Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

add OpenClaw adaptive SEO loop MVP

Tongde5b119ae660
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 55550b63..5fd5a4ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+
+## [Unreleased]
+
+### Added
+- **OpenClaw adaptive layer (working MVP).** Added a new `openclaw/` repo surface that wraps the existing Toprank SEO skills for OpenClaw without duplicating them. The MVP includes multi-site portfolio docs, per-site work-folder conventions, wrapper skills (`toprank-site-onboard`, `toprank-portfolio-review`, `toprank-weekly-review`, `toprank-improve-page`, `toprank-investigate-drop`), JSON artifact schemas, helper scripts to bootstrap a portfolio and per-site workspace, onboarding persistence, weekly-review run persistence, portfolio review ranking, page-improvement persistence, drop-investigation persistence, follow-up discovery, a simple scheduler runner that processes due `feedback_check` items and surfaces manual-attention work, automatic baseline snapshot inheritance for feedback queue items, a first-pass feedback scorer that classifies follow-ups as `win`, `neutral`, `loss`, or `inconclusive` from before/after metric snapshots, learned-prior updates in `learned-patterns.json`, and a helper to hydrate observed metrics from real Google Search Console data.
+
+---
+
## [0.15.2] — 2026-04-29
### Changed
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b77e6286..c46aa378 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,6 +22,17 @@ Each skill lives in its own folder under a category directory (e.g., `seo/`, `go
* `VERSION`
6. **Update Changelog**: Add a brief description of your new skill to `CHANGELOG.md`.
+
+### 1A. OpenClaw adaptive layer
+
+The repo also ships an OpenClaw-specific surface under `openclaw/`.
+
+- Keep the existing `seo/` and `google-ads/` skills canonical.
+- Add runtime-specific wrappers under `openclaw/skills/` instead of duplicating skill logic.
+- Put schemas under `openclaw/artifacts/schemas/` and shared docs under `openclaw/shared/`.
+- **Do not register OpenClaw wrapper skills in `.claude-plugin/plugin.json`** — they are not part of the Claude plugin surface.
+- Runtime state belongs under `~/.toprank/openclaw`, not in git.
+
### 2. Improving Existing Skills
* Refine prompts in `SKILL.md` for better accuracy.
diff --git a/README.md b/README.md
index f727d017..79717abc 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,23 @@ Add the marketplace and enable the plugin in `~/.claude/settings.json`:
</details>
+
+---
+
+## OpenClaw (alpha)
+
+This repo now includes an **OpenClaw adaptive layer** under [`openclaw/`](openclaw/). It keeps the existing Toprank SEO skills intact, then adds:
+
+- multi-site portfolio state,
+- a per-site work folder for each website,
+- OpenClaw wrapper skills,
+- structured JSON artifacts for reviews, plans, and feedback.
+
+Start here:
+
+- [`openclaw/README.md`](openclaw/README.md)
+- [`docs/openclaw-adaptive-layer.md`](docs/openclaw-adaptive-layer.md)
+
---
## Skills
@@ -212,6 +229,7 @@ toprank/
│ ├── geo-optimizer/ <- GEO for AI search engines
│ └── setup-cms/ <- CMS connector
├── gemini/ <- cross-model review via Gemini CLI
+├── openclaw/ <- OpenClaw adaptive layer (multi-site wrappers, artifacts, installers)
├── toprank-upgrade-skill/ <- self-updater
├── test/ <- unit + LLM-judge eval tests
└── VERSION
diff --git a/docs/openclaw-adaptive-layer.md b/docs/openclaw-adaptive-layer.md
new file mode 100644
index 00000000..b4aabe76
--- /dev/null
+++ b/docs/openclaw-adaptive-layer.md
@@ -0,0 +1,192 @@
+# OpenClaw Adaptive Layer (MVP)
+
+Toprank's OpenClaw surface is a thin adaptive layer that sits on top of the existing open-source SEO skills. It does **not** replace `seo/` or `google-ads/`. It adds multi-site state, scheduled review loops, artifact writing, and policy gates so an operator can manage a portfolio of websites from one OpenClaw workspace.
+
+## Product definition
+
+**Goal:** maximize qualified organic growth across a portfolio of websites, subject to explicit safety and approval rules.
+
+**Core idea:** the existing Toprank skills are capability modules; the OpenClaw layer is the operator.
+
+## Operating model
+
+The layer runs two loops:
+
+1. **Portfolio loop** — look across all registered sites, rank urgency and opportunity, decide where attention should go next.
+2. **Site loop** — observe a single site, diagnose the highest-leverage issue, propose or draft the next action, verify it, and schedule a later feedback check.
+
+## MVP scope
+
+The MVP deliberately stays narrow.
+
+### Supported actions
+- title/meta rewrite proposals
+- schema proposals
+- internal-link recommendations
+- page improvement proposals
+- traffic-drop investigation plans
+- weekly review prioritization
+
+### Not in MVP
+- automatic publishing to CMS
+- autonomous mass rewrites
+- automatic redirect sweeps
+- cross-site learned priors driving writes without approval
+
+## Multi-site workspace layout
+
+Runtime state lives **outside the repo** under `~/.toprank/openclaw` by default.
+
+```text
+~/.toprank/openclaw/
+├── portfolio.json
+├── schedule.json
+└── sites/
+ ├── pawsvip.com/
+ │ ├── site-profile.json
+ │ ├── goals.json
+ │ ├── latest-state.json
+ │ ├── learned-patterns.json
+ │ ├── queue/
+ │ ├── proposals/
+ │ ├── runs/
+ │ └── feedback/
+ └── bestpettravel.com/
+ └── ...
+```
+
+The repo contains the shared layer under `openclaw/`:
+
+```text
+openclaw/
+├── README.md
+├── artifacts/
+│ ├── examples/
+│ └── schemas/
+├── bin/
+├── install/
+├── shared/
+└── skills/
+```
+
+## JSON file catalog
+
+### Portfolio-level
+
+- `portfolio.json` — the registry of all sites, their business weight, cadence, and status.
+- `schedule.json` — upcoming recurring checks and feedback follow-ups.
+
+### Per-site core files
+
+- `site-profile.json` — domain, canonical URL, brand terms, CMS, primary business context.
+- `goals.json` — one or more active SEO goals for the site.
+- `latest-state.json` — the last summarized state snapshot used for quick loading.
+- `learned-patterns.json` — site-local observations about what interventions have worked or failed.
+
+### Per-site work folders
+
+- `queue/` — pending work items the layer should revisit.
+- `proposals/` — generated proposals and patch candidates waiting for review or approval.
+- `runs/` — immutable run artifacts grouped by timestamp.
+- `feedback/` — post-action outcome reviews.
+
+### Per-run files
+
+Each run directory under `sites/<site_id>/runs/<timestamp>/` can contain:
+
+- `trigger.json`
+- `state-snapshot.json`
+- `audit.json`
+- `action-plan.json`
+- `proposal.json`
+- `patch-set.json`
+- `verification.json`
+- `feedback.json`
+- `learning-log.json`
+
+The MVP requires at least:
+- `audit.json`
+- `action-plan.json`
+- `verification.json`
+
+## Policy model
+
+### Auto-safe
+- run audits
+- write local artifacts
+- update queue items
+- generate proposals and drafts
+
+### Approval-required
+- edit website repo files
+- write to a CMS
+- open a PR
+- publish content or metadata
+
+### Blocked from auto
+- delete content in production
+- deploy bulk redirect changes
+- perform irreversible public changes without approval
+
+## Wrapper skills
+
+The MVP ships five OpenClaw-facing wrapper skills:
+
+- `toprank-site-onboard`
+- `toprank-portfolio-review`
+- `toprank-weekly-review`
+- `toprank-improve-page`
+- `toprank-investigate-drop`
+
+These wrappers keep the existing `seo/` skills as the source of truth. The wrapper adds:
+
+- site selection
+- multi-site state loading
+- artifact writing
+- policy gating
+- follow-up scheduling
+
+## Recommended cadence
+
+- **daily** — lightweight portfolio health scan
+- **weekly** — portfolio review + top site deep review
+- **14/28 day** — feedback checks on prior actions
+
+## Success criteria for MVP
+
+The MVP is working if an OpenClaw operator can:
+
+1. register multiple websites,
+2. keep a separate work folder for each site,
+3. run a portfolio review to decide where to focus,
+4. run a site review that produces structured artifacts,
+5. draft one safe next action,
+6. schedule and record a follow-up result.
+
+## Working implementation status
+
+The current MVP includes these concrete helper flows:
+
+- `openclaw/bin/onboard_site.py` — creates or updates the site work folder, portfolio entry, and initial goal.
+- `openclaw/bin/weekly_review.py` — runs or reads Search Console analysis, builds the weekly review payload automatically, persists the run, and seeds baseline metrics for follow-up scoring.
+- `openclaw/bin/persist_run.py` — takes a structured review payload and writes a timestamped run with `audit.json`, `action-plan.json`, `verification.json`, and optional queue items.
+- `openclaw/bin/portfolio_review.py` — ranks active sites using business weight, open issues, and active goals, then writes a portfolio review snapshot.
+- `openclaw/bin/improve_page.py` — persists a page-improvement proposal, optional patch-set, and feedback follow-up.
+- `openclaw/bin/investigate_drop.py` — persists a traffic-drop investigation, ranked recovery actions, and optional page-improvement follow-up.
+- `openclaw/bin/followups_due.py` — lists scheduled follow-up items that are due, making the schedule actionable.
+- `openclaw/bin/run_scheduler.py` — processes due schedule entries, auto-materializes feedback-check runs, and surfaces manual-attention items.
+- `openclaw/bin/record_followup_metrics.py` and `openclaw/bin/score_feedback.py` — let the operator attach observed metrics to a follow-up and score it as a win / neutral / loss / inconclusive.
+- `openclaw/bin/hydrate_followup_gsc.py` — can populate observed metrics from real Google Search Console data when a site has a GSC property or canonical URL configured.
+
+This means the adaptive layer can already persist real onboarding, automated weekly-review state, page-improvement proposals, drop investigations, due follow-up discovery, simple autonomous schedule processing, first-pass feedback scoring, and site-local learned priors even before the higher-level wrappers become fully autonomous.
+
+## Priority adaptation
+
+The weekly review runner now reads `learned-patterns.json` before ranking actions.
+
+That means the same site can evolve different preferences over time:
+- if `meta_tags` repeatedly improves `non_brand_clicks_28d`, weekly review boosts it,
+- if `page_improvement` repeatedly loses on the same metric, weekly review discounts it,
+- if no prior exists, the runner falls back to raw severity and opportunity heuristics.
+
+This is the first real behavior change driven by past outcomes.
diff --git a/openclaw/README.md b/openclaw/README.md
new file mode 100644
index 00000000..0b286445
--- /dev/null
+++ b/openclaw/README.md
@@ -0,0 +1,203 @@
+# OpenClaw surface for Toprank
+
+Toprank + OpenClaw is now a **closed-loop SEO operator**.
+
+It does not just run one-off audits. It can now:
+- pull real SEO signals from Google Search Console,
+- diagnose opportunities,
+- prioritize the next action using learned history,
+- persist proposals and safe operational steps,
+- schedule follow-up checks,
+- score whether changes worked,
+- update learned priors,
+- and keep going.
+
+This directory adds that multi-site adaptive layer for OpenClaw **without replacing the existing Toprank skills**.
+
+## The new power
+
+**SEO becomes a continuous system instead of a manual project.**
+
+```text
+signals -> diagnosis -> action -> follow-up measurement -> scoring -> learned priors -> better next action
+```
+
+![Continuous SEO Improvement Loop](artifacts/visuals/continuous-seo-improvement-loop.webp)
+
+In practice, this means OpenClaw can continuously work a portfolio of sites by reading live data, generating the next best move, revisiting outcomes later, and getting smarter from the result.
+
+## What it is
+
+- `skills/` — OpenClaw wrapper skills
+- `shared/` — adapter rules, artifact contract, policy, and trigger docs
+- `artifacts/schemas/` — JSON schemas for runtime artifacts
+- `bin/` — small helper scripts for multi-site workspace bootstrapping
+- `install/` — installers/bootstrap helpers
+
+## What it is not
+
+- not a second copy of the SEO skill library
+- not a replacement for the Claude plugin surface
+- not a production auto-publisher
+
+## Runtime state
+
+The adaptive layer writes runtime state outside the repo by default:
+
+```
+~/.toprank/openclaw
+```
+
+Override with:
+
+```
+export TOPRANK_OPENCLAW_HOME=/custom/path
+```
+
+## Install
+
+The wrappers are designed to be **symlinked** into `~/.openclaw/skills/` so they can still resolve the canonical `seo/` skills in this repo.
+
+```bash
+./openclaw/install/install.sh
+```
+
+That script:
+
+1. creates `~/.toprank/openclaw/` if needed,
+2. bootstraps `portfolio.json` and `schedule.json`,
+3. symlinks all `openclaw/skills/*` into `~/.openclaw/skills/`.
+
+## Bootstrap a site work folder
+
+```bash
+./openclaw/install/bootstrap-site.sh https://example.com
+```
+
+That creates:
+
+```text
+~/.toprank/openclaw/sites/example.com/
+├── site-profile.json
+├── goals.json
+├── latest-state.json
+├── learned-patterns.json
+├── queue/
+├── proposals/
+├── runs/
+└── feedback/
+```
+
+## Why this matters
+
+Before this layer, Toprank had strong point skills.
+
+Now it has memory and recurrence:
+- **real signal ingestion** via GSC analysis,
+- **persistent state** per website,
+- **scheduled follow-ups** instead of forgotten recommendations,
+- **feedback scoring** instead of vague “seems better”,
+- **learned priors** so future prioritization adapts.
+
+That is the step from “SEO assistant” to “SEO operating loop”.
+
+## Working helper scripts
+
+- `python3 openclaw/bin/onboard_site.py <url> ...` — updates `portfolio.json`, `site-profile.json`, and `goals.json`
+- `python3 openclaw/bin/persist_run.py <site> --payload-file payload.json` — writes review artifacts into a timestamped run folder and refreshes `latest-state.json`
+- `python3 openclaw/bin/portfolio_review.py` — ranks active sites and writes a portfolio review snapshot
+- `python3 openclaw/bin/weekly_review.py <site>` — generates a real weekly review payload from GSC analysis, persists artifacts, and creates a scored follow-up baseline
+- `python3 openclaw/bin/improve_page.py <site> --url <url> ...` — persists a page-improvement proposal and follow-up task
+- `python3 openclaw/bin/investigate_drop.py <site> --summary "..." ...` — persists a drop investigation and recovery plan
+- `python3 openclaw/bin/followups_due.py` — shows which scheduled follow-up items are due now
+- `python3 openclaw/bin/run_scheduler.py` — processes due schedule items, materializes follow-up review artifacts, and surfaces manual-attention work
+- `python3 openclaw/bin/record_followup_metrics.py <site> <item_id> ...` — records observed metrics on a queued follow-up
+- `python3 openclaw/bin/hydrate_followup_gsc.py <site> <item_id> ...` — pulls real GSC metrics into a queued follow-up using the existing `seo-analysis` scripts (uses `site-profile.json` `gsc_property` when present, otherwise falls back to `canonical_url`)
+- `python3 openclaw/bin/score_feedback.py --item-file <queue-item.json>` — scores a follow-up as win / neutral / loss / inconclusive
+
+Use these example payloads and flows as templates:
+
+- `openclaw/artifacts/examples/weekly-review-payload.json`
+- `openclaw/artifacts/examples/gsc-analysis-sample.json`
+- `openclaw/artifacts/examples/improve-page-payload.json`
+- `openclaw/artifacts/examples/investigate-drop-payload.json`
+- `openclaw/artifacts/examples/scored-feedback-item.json`
+
+## Wrapper skills
+
+- `toprank-site-onboard` — register a site and initialize its work folder
+- `toprank-portfolio-review` — rank all active sites by urgency/opportunity
+- `toprank-weekly-review` — review one site and propose the next best action
+- `toprank-improve-page` — improve one URL on a site
+- `toprank-investigate-drop` — traffic-drop recovery workflow
+
+## Autonomous loop building blocks
+
+The closed loop is now made of three concrete runtime pieces:
+
+1. **Weekly review from real data**
+ - `weekly_review.py` runs or reads GSC analysis
+ - generates `audit.json`, `action-plan.json`, `verification.json`
+ - seeds `baseline_metrics` for later scoring
+
+2. **Scheduled follow-up evaluation**
+ - `run_scheduler.py` revisits due `feedback_check` items
+ - `hydrate_followup_gsc.py` can pull fresh observed metrics
+ - `score_feedback.py` classifies `win` / `neutral` / `loss` / `inconclusive`
+
+3. **Learning from outcomes**
+ - `learned-patterns.json` stores site-level priors
+ - weekly review uses those priors to bias future action ranking
+
+## Automated weekly review
+
+The OpenClaw layer now has a real weekly review runner:
+
+```bash
+python3 openclaw/bin/weekly_review.py example.com
+```
+
+Useful flags:
+- `--gsc-property sc-domain:example.com`
+- `--analysis-file openclaw/artifacts/examples/gsc-analysis-sample.json`
+
+This runner:
+- runs or reads GSC analysis,
+- builds `audit.json`, `action-plan.json`, and `verification.json`,
+- inherits baseline metrics into the follow-up queue item,
+- uses `learned-patterns.json` to bias action ranking,
+- turns raw signals into a concrete next action plus a measurable follow-up.
+
+## Scheduler runner
+
+The MVP now includes a simple runner for automation:
+
+```bash
+python3 openclaw/bin/run_scheduler.py
+# or
+./openclaw/install/run-scheduler.sh
+```
+
+What it does today:
+- processes due `feedback_check` items automatically,
+- scores them as `win`, `neutral`, `loss`, or `inconclusive` when metric snapshots exist,
+- writes follow-up run artifacts,
+- marks processed schedule items,
+- updates `learned-patterns.json` with outcome priors,
+- surfaces unsupported due items as `ready_for_attention`.
+
+Install it on macOS with launchd:
+
+```bash
+./openclaw/install/install-launchd.sh --write-only
+# inspect the plist, then load it for real:
+./openclaw/install/install-launchd.sh
+```
+
+Or use the cron example at `openclaw/install/toprank-openclaw.cron.example`.
+
+This is now the core of a real autonomous operator loop.
+
+## Design principle
+
+The OpenClaw surface is an **adapter layer**. The existing Toprank skill folders remain canonical. The OpenClaw wrappers add persistent state, portfolio awareness, artifact writing, and policy gates.
diff --git a/openclaw/artifacts/examples/action-plan.json b/openclaw/artifacts/examples/action-plan.json
new file mode 100644
index 00000000..37f61a11
--- /dev/null
+++ b/openclaw/artifacts/examples/action-plan.json
@@ -0,0 +1,17 @@
+{
+ "site_id": "example.com",
+ "generated_at": "2026-04-29T22:00:00Z",
+ "goal_id": "goal_example_001",
+ "actions": [
+ {
+ "action_id": "action_001",
+ "title": "Rewrite the homepage title and meta description to match high-impression queries.",
+ "type": "meta_tags",
+ "priority_score": 0.87,
+ "expected_impact": "Improve CTR on a high-impression page.",
+ "requires_approval": true,
+ "reversibility": "high",
+ "owner": "operator"
+ }
+ ]
+}
diff --git a/openclaw/artifacts/examples/goal.json b/openclaw/artifacts/examples/goal.json
new file mode 100644
index 00000000..1c29e2f5
--- /dev/null
+++ b/openclaw/artifacts/examples/goal.json
@@ -0,0 +1,8 @@
+{
+ "goal_id": "goal_example_001",
+ "site_id": "example.com",
+ "type": "grow_non_brand_clicks",
+ "primary_metric": "non_brand_clicks_28d",
+ "target_delta": 0.2,
+ "status": "active"
+}
diff --git a/openclaw/artifacts/examples/gsc-analysis-sample.json b/openclaw/artifacts/examples/gsc-analysis-sample.json
new file mode 100644
index 00000000..3809108a
--- /dev/null
+++ b/openclaw/artifacts/examples/gsc-analysis-sample.json
@@ -0,0 +1,69 @@
+{
+ "site": "sc-domain:example.com",
+ "period": {
+ "start": "2026-04-01",
+ "end": "2026-04-28",
+ "days": 28
+ },
+ "summary": {
+ "clicks": 150,
+ "impressions": 5200,
+ "ctr": 2.88,
+ "position": 10.7
+ },
+ "ctr_gaps_by_page": [
+ {
+ "page": "https://example.com/services/dog-daycare",
+ "clicks": 20,
+ "impressions": 1200,
+ "ctr": 1.67,
+ "position": 7.4
+ }
+ ],
+ "ctr_opportunities": [
+ {
+ "query": "dog daycare seattle",
+ "clicks": 12,
+ "impressions": 900,
+ "ctr": 1.33,
+ "position": 6.9
+ }
+ ],
+ "cannibalization": [
+ {
+ "query": "dog daycare pricing",
+ "winner_page": "https://example.com/services/dog-daycare",
+ "loser_pages": [
+ "https://example.com/pricing"
+ ]
+ }
+ ],
+ "comparison": {
+ "declining_pages": [
+ {
+ "page": "https://example.com/services/dog-boarding",
+ "change_pct": -35.0,
+ "clicks_now": 18,
+ "clicks_prev": 28
+ }
+ ],
+ "declining_queries": [
+ {
+ "query": "overnight dog boarding",
+ "change_pct": -28.0,
+ "clicks_now": 9,
+ "clicks_prev": 13
+ }
+ ]
+ },
+ "branded_split": {
+ "branded": {
+ "clicks": 40,
+ "impressions": 1000
+ },
+ "non_branded": {
+ "clicks": 110,
+ "impressions": 4200
+ }
+ }
+}
diff --git a/openclaw/artifacts/examples/improve-page-payload.json b/openclaw/artifacts/examples/improve-page-payload.json
new file mode 100644
index 00000000..8afac00f
--- /dev/null
+++ b/openclaw/artifacts/examples/improve-page-payload.json
@@ -0,0 +1,53 @@
+{
+ "generated_at": "2026-04-29T22:00:00Z",
+ "trigger": {
+ "type": "improve_page",
+ "target": "https://example.com/services/dog-daycare",
+ "notes": "Improve a service page with weak CTR and missing schema."
+ },
+ "audit": {
+ "summary": "The service page has good impressions but weak CTR and limited structured context.",
+ "issues": [
+ {
+ "title": "Title and meta description do not match top service-intent queries.",
+ "severity": "warning",
+ "confidence": 0.79,
+ "evidence": [
+ "Page receives impressions but CTR is below site baseline.",
+ "Current title misses the city + service modifier."
+ ],
+ "recommended_action_type": "meta_tags"
+ }
+ ]
+ },
+ "action_plan": {
+ "actions": [
+ {
+ "action_id": "action_001",
+ "title": "Draft new title/meta and local-service schema for the page.",
+ "type": "page_improvement",
+ "priority_score": 0.84,
+ "expected_impact": "Improve CTR and clarify page relevance.",
+ "requires_approval": true,
+ "reversibility": "high",
+ "owner": "operator"
+ }
+ ]
+ },
+ "proposal": {
+ "proposal_type": "page_improvement",
+ "target": "https://example.com/services/dog-daycare",
+ "summary": "Generate 3 title/meta candidates and add schema markup recommendations.",
+ "requires_approval": true
+ },
+ "verification": {
+ "checks": [
+ {
+ "name": "proposal persisted",
+ "status": "pass",
+ "notes": "Proposal artifact stored."
+ }
+ ],
+ "follow_up_due": "2026-05-13T22:00:00Z"
+ }
+}
diff --git a/openclaw/artifacts/examples/investigate-drop-payload.json b/openclaw/artifacts/examples/investigate-drop-payload.json
new file mode 100644
index 00000000..3ec1f39c
--- /dev/null
+++ b/openclaw/artifacts/examples/investigate-drop-payload.json
@@ -0,0 +1,55 @@
+{
+ "generated_at": "2026-04-29T22:00:00Z",
+ "trigger": {
+ "type": "traffic_drop_detected",
+ "notes": "Organic clicks fell 28% week over week on the primary service cluster."
+ },
+ "audit": {
+ "summary": "Traffic drop investigation identified one likely technical issue and one likely intent/CTR issue.",
+ "issues": [
+ {
+ "title": "A high-value service page may have fallen out of the index.",
+ "severity": "critical",
+ "confidence": 0.82,
+ "evidence": [
+ "Primary service page lost impressions sharply.",
+ "Recent crawl reported inconsistent indexation."
+ ],
+ "recommended_action_type": "drop_recovery"
+ },
+ {
+ "title": "Homepage CTR declined after a recent copy change.",
+ "severity": "warning",
+ "confidence": 0.68,
+ "evidence": [
+ "CTR down on high-impression brand-adjacent queries."
+ ],
+ "recommended_action_type": "drop_recovery"
+ }
+ ]
+ },
+ "action_plan": {
+ "actions": [
+ {
+ "action_id": "action_001",
+ "title": "Investigate indexation and request recrawl if needed.",
+ "type": "drop_recovery",
+ "priority_score": 0.92,
+ "expected_impact": "Recover lost visibility from a likely indexation issue.",
+ "requires_approval": true,
+ "reversibility": "high",
+ "owner": "operator"
+ }
+ ]
+ },
+ "verification": {
+ "checks": [
+ {
+ "name": "drop investigation persisted",
+ "status": "pass",
+ "notes": "Recovery plan stored."
+ }
+ ],
+ "follow_up_due": "2026-05-06T22:00:00Z"
+ }
+}
diff --git a/openclaw/artifacts/examples/portfolio.json b/openclaw/artifacts/examples/portfolio.json
new file mode 100644
index 00000000..674d24ea
--- /dev/null
+++ b/openclaw/artifacts/examples/portfolio.json
@@ -0,0 +1,13 @@
+{
+ "schema_version": "1",
+ "portfolio_id": "default",
+ "sites": [
+ {
+ "site_id": "example.com",
+ "display_name": "Example",
+ "business_weight": 1.0,
+ "cadence": "weekly",
+ "status": "active"
+ }
+ ]
+}
diff --git a/openclaw/artifacts/examples/scored-feedback-item.json b/openclaw/artifacts/examples/scored-feedback-item.json
new file mode 100644
index 00000000..4e583ade
--- /dev/null
+++ b/openclaw/artifacts/examples/scored-feedback-item.json
@@ -0,0 +1,26 @@
+{
+ "item_id": "followup_example_homepage_ctr_14d",
+ "site_id": "example.com",
+ "type": "feedback_check",
+ "status": "pending",
+ "due_at": "2026-05-13T22:00:00Z",
+ "notes": "Review homepage CTR after approved metadata changes.",
+ "primary_metric": "organic_clicks_28d",
+ "primary_direction": "higher_better",
+ "success_threshold_pct": 0.1,
+ "baseline_metrics": {
+ "organic_clicks_28d": 100,
+ "conversions_28d": 10
+ },
+ "observed_metrics": {
+ "organic_clicks_28d": 121,
+ "conversions_28d": 11
+ },
+ "guardrail_metrics": [
+ {
+ "metric": "conversions_28d",
+ "direction": "higher_better",
+ "max_worsen_pct": 0.05
+ }
+ ]
+}
diff --git a/openclaw/artifacts/examples/site-profile.json b/openclaw/artifacts/examples/site-profile.json
new file mode 100644
index 00000000..1082f60a
--- /dev/null
+++ b/openclaw/artifacts/examples/site-profile.json
@@ -0,0 +1,12 @@
+{
+ "schema_version": "1",
+ "site_id": "example.com",
+ "canonical_url": "https://example.com",
+ "display_name": "Example",
+ "brand_terms": [
+ "Example"
+ ],
+ "cms": "nextjs",
+ "business_context": "Demo site profile for the OpenClaw adaptive layer.",
+ "status": "active"
+}
diff --git a/openclaw/artifacts/examples/weekly-review-payload.json b/openclaw/artifacts/examples/weekly-review-payload.json
new file mode 100644
index 00000000..8aafe5d9
--- /dev/null
+++ b/openclaw/artifacts/examples/weekly-review-payload.json
@@ -0,0 +1,79 @@
+{
+ "generated_at": "2026-04-29T22:00:00Z",
+ "trigger": {
+ "type": "weekly_review",
+ "notes": "Scheduled weekly review for example.com."
+ },
+ "state_snapshot": {
+ "summary": "Homepage CTR is lagging and one service page has indexation risk.",
+ "open_issues": [
+ {
+ "title": "Homepage CTR lag",
+ "severity": "warning",
+ "confidence": 0.78
+ },
+ {
+ "title": "Service page not consistently indexed",
+ "severity": "warning",
+ "confidence": 0.66
+ }
+ ],
+ "recent_actions": [],
+ "metrics": {
+ "organic_clicks_28d": 100,
+ "organic_impressions_28d": 4000,
+ "organic_ctr_28d": 2.5,
+ "avg_position_28d": 11.2,
+ "non_brand_clicks_28d": 72,
+ "branded_clicks_28d": 28
+ }
+ },
+ "audit": {
+ "summary": "Two high-leverage SEO issues were identified during the weekly review.",
+ "issues": [
+ {
+ "title": "Homepage title does not align with top impression queries.",
+ "severity": "warning",
+ "confidence": 0.81,
+ "evidence": [
+ "High impressions with below-baseline CTR.",
+ "Current title misses the primary service term."
+ ],
+ "recommended_action_type": "meta_tags"
+ }
+ ]
+ },
+ "action_plan": {
+ "actions": [
+ {
+ "action_id": "action_001",
+ "title": "Draft three homepage title/meta variants for approval.",
+ "type": "meta_tags",
+ "priority_score": 0.87,
+ "expected_impact": "Improve CTR on the site's highest-impression page.",
+ "requires_approval": true,
+ "reversibility": "high",
+ "owner": "operator"
+ }
+ ]
+ },
+ "verification": {
+ "checks": [
+ {
+ "name": "artifact completeness",
+ "status": "pass",
+ "notes": "Audit, action plan, and verification artifacts were written."
+ }
+ ],
+ "follow_up_due": "2026-05-13T22:00:00Z"
+ },
+ "queue_items": [
+ {
+ "item_id": "followup_example_homepage_ctr_14d",
+ "type": "feedback_check",
+ "status": "pending",
+ "due_at": "2026-05-13T22:00:00Z",
+ "notes": "Re-check homepage CTR after any approved metadata update."
+ }
+ ]
+}
diff --git a/openclaw/artifacts/schemas/action-plan.schema.json b/openclaw/artifacts/schemas/action-plan.schema.json
new file mode 100644
index 00000000..12d3e936
--- /dev/null
+++ b/openclaw/artifacts/schemas/action-plan.schema.json
@@ -0,0 +1,73 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Action Plan",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "goal_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "actions": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "action_id": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ },
+ "priority_score": {
+ "type": "number"
+ },
+ "expected_impact": {
+ "type": "string"
+ },
+ "requires_approval": {
+ "type": "boolean"
+ },
+ "reversibility": {
+ "type": "string",
+ "enum": [
+ "high",
+ "medium",
+ "low"
+ ]
+ },
+ "owner": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "action_id",
+ "title",
+ "type",
+ "priority_score",
+ "requires_approval"
+ ],
+ "additionalProperties": true
+ }
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "actions"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/audit.schema.json b/openclaw/artifacts/schemas/audit.schema.json
new file mode 100644
index 00000000..f632f9d5
--- /dev/null
+++ b/openclaw/artifacts/schemas/audit.schema.json
@@ -0,0 +1,63 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Audit",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "issues": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "title": {
+ "type": "string"
+ },
+ "severity": {
+ "type": "string",
+ "enum": [
+ "critical",
+ "warning",
+ "info"
+ ]
+ },
+ "confidence": {
+ "type": "number"
+ },
+ "evidence": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "recommended_action_type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "title",
+ "severity",
+ "evidence"
+ ],
+ "additionalProperties": true
+ }
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "summary",
+ "issues"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/feedback.schema.json b/openclaw/artifacts/schemas/feedback.schema.json
new file mode 100644
index 00000000..6293ded5
--- /dev/null
+++ b/openclaw/artifacts/schemas/feedback.schema.json
@@ -0,0 +1,40 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Feedback",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "action_id": {
+ "type": "string"
+ },
+ "window_days": {
+ "type": "integer"
+ },
+ "outcome": {
+ "type": "string",
+ "enum": [
+ "win",
+ "neutral",
+ "loss",
+ "inconclusive"
+ ]
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "action_id",
+ "window_days",
+ "outcome",
+ "summary"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/goal.schema.json b/openclaw/artifacts/schemas/goal.schema.json
new file mode 100644
index 00000000..c7c9c52d
--- /dev/null
+++ b/openclaw/artifacts/schemas/goal.schema.json
@@ -0,0 +1,41 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Goal",
+ "type": "object",
+ "properties": {
+ "goal_id": {
+ "type": "string"
+ },
+ "site_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ },
+ "primary_metric": {
+ "type": "string"
+ },
+ "target_delta": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "active",
+ "paused",
+ "archived"
+ ]
+ }
+ },
+ "required": [
+ "goal_id",
+ "site_id",
+ "type",
+ "primary_metric",
+ "status"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/learning-log.schema.json b/openclaw/artifacts/schemas/learning-log.schema.json
new file mode 100644
index 00000000..002370c1
--- /dev/null
+++ b/openclaw/artifacts/schemas/learning-log.schema.json
@@ -0,0 +1,42 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Learning Log",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "observations": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "pattern": {
+ "type": "string"
+ },
+ "confidence": {
+ "type": "number"
+ },
+ "notes": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "pattern",
+ "confidence",
+ "notes"
+ ],
+ "additionalProperties": true
+ }
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "observations"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/patch-set.schema.json b/openclaw/artifacts/schemas/patch-set.schema.json
new file mode 100644
index 00000000..4ee8e3f2
--- /dev/null
+++ b/openclaw/artifacts/schemas/patch-set.schema.json
@@ -0,0 +1,42 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Patch Set",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "patches": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string"
+ },
+ "change_type": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "change_type",
+ "summary"
+ ],
+ "additionalProperties": true
+ }
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "patches"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/portfolio.schema.json b/openclaw/artifacts/schemas/portfolio.schema.json
new file mode 100644
index 00000000..e90cee94
--- /dev/null
+++ b/openclaw/artifacts/schemas/portfolio.schema.json
@@ -0,0 +1,60 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Portfolio",
+ "type": "object",
+ "properties": {
+ "schema_version": {
+ "type": "string"
+ },
+ "portfolio_id": {
+ "type": "string"
+ },
+ "sites": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "display_name": {
+ "type": "string"
+ },
+ "business_weight": {
+ "type": "number"
+ },
+ "cadence": {
+ "type": "string",
+ "enum": [
+ "daily",
+ "weekly",
+ "monthly",
+ "on_demand"
+ ]
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "active",
+ "paused",
+ "archived"
+ ]
+ }
+ },
+ "required": [
+ "site_id",
+ "business_weight",
+ "cadence",
+ "status"
+ ],
+ "additionalProperties": true
+ }
+ }
+ },
+ "required": [
+ "schema_version",
+ "portfolio_id",
+ "sites"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/proposal.schema.json b/openclaw/artifacts/schemas/proposal.schema.json
new file mode 100644
index 00000000..9ac89b1c
--- /dev/null
+++ b/openclaw/artifacts/schemas/proposal.schema.json
@@ -0,0 +1,34 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Proposal",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "proposal_type": {
+ "type": "string"
+ },
+ "target": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "requires_approval": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "proposal_type",
+ "target",
+ "summary",
+ "requires_approval"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/queue-item.schema.json b/openclaw/artifacts/schemas/queue-item.schema.json
new file mode 100644
index 00000000..05b5f1de
--- /dev/null
+++ b/openclaw/artifacts/schemas/queue-item.schema.json
@@ -0,0 +1,44 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Queue Item",
+ "type": "object",
+ "properties": {
+ "item_id": {
+ "type": "string"
+ },
+ "site_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "in_progress",
+ "blocked",
+ "done"
+ ]
+ },
+ "due_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "notes": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "item_id",
+ "site_id",
+ "type",
+ "status"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/site-profile.schema.json b/openclaw/artifacts/schemas/site-profile.schema.json
new file mode 100644
index 00000000..07a5bd41
--- /dev/null
+++ b/openclaw/artifacts/schemas/site-profile.schema.json
@@ -0,0 +1,53 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Site Profile",
+ "type": "object",
+ "properties": {
+ "schema_version": {
+ "type": "string"
+ },
+ "site_id": {
+ "type": "string"
+ },
+ "canonical_url": {
+ "type": "string"
+ },
+ "display_name": {
+ "type": "string"
+ },
+ "brand_terms": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "cms": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "business_context": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "active",
+ "paused",
+ "archived"
+ ]
+ }
+ },
+ "required": [
+ "schema_version",
+ "site_id",
+ "canonical_url",
+ "brand_terms",
+ "status"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/state-snapshot.schema.json b/openclaw/artifacts/schemas/state-snapshot.schema.json
new file mode 100644
index 00000000..301623e2
--- /dev/null
+++ b/openclaw/artifacts/schemas/state-snapshot.schema.json
@@ -0,0 +1,37 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw State Snapshot",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "trigger": {
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "open_issues": {
+ "type": "array",
+ "items": {
+ "type": "object"
+ }
+ },
+ "recent_actions": {
+ "type": "array",
+ "items": {
+ "type": "object"
+ }
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "summary"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/schemas/verification.schema.json b/openclaw/artifacts/schemas/verification.schema.json
new file mode 100644
index 00000000..951711cc
--- /dev/null
+++ b/openclaw/artifacts/schemas/verification.schema.json
@@ -0,0 +1,56 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "Toprank OpenClaw Verification",
+ "type": "object",
+ "properties": {
+ "site_id": {
+ "type": "string"
+ },
+ "generated_at": {
+ "type": "string"
+ },
+ "checks": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "pass",
+ "warning",
+ "fail",
+ "not_run"
+ ]
+ },
+ "notes": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "name",
+ "status"
+ ],
+ "additionalProperties": true
+ }
+ },
+ "follow_up_due": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "site_id",
+ "generated_at",
+ "checks"
+ ],
+ "additionalProperties": true
+}
diff --git a/openclaw/artifacts/visuals/continuous-seo-improvement-loop.webp b/openclaw/artifacts/visuals/continuous-seo-improvement-loop.webp
new file mode 100644
index 00000000..28cc4b78
Binary files /dev/null and b/openclaw/artifacts/visuals/continuous-seo-improvement-loop.webp differ
diff --git a/openclaw/bin/bootstrap_site.py b/openclaw/bin/bootstrap_site.py
new file mode 100755
index 00000000..349237c4
--- /dev/null
+++ b/openclaw/bin/bootstrap_site.py
@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Initialize a per-site work folder inside the Toprank OpenClaw runtime workspace."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from runtime import bootstrap_workspace, ensure_site_dirs, load_json, save_json, workspace_root
+from site_id import normalize_site_id
+
+
+def bootstrap_site(site_input: str, root: Path | None = None) -> Path:
+ site_id = normalize_site_id(site_input)
+ root = bootstrap_workspace(root or workspace_root())
+ site_root = ensure_site_dirs(site_id, root)
+
+ profile = site_root / "site-profile.json"
+ goals = site_root / "goals.json"
+ latest = site_root / "latest-state.json"
+ learned = site_root / "learned-patterns.json"
+
+ if not profile.exists():
+ save_json(
+ profile,
+ {
+ "schema_version": "1",
+ "site_id": site_id,
+ "canonical_url": site_input if "://" in site_input else f"https://{site_id}",
+ "display_name": site_id,
+ "brand_terms": [],
+ "cms": None,
+ "business_context": None,
+ "status": "active",
+ },
+ )
+
+ if not goals.exists():
+ save_json(goals, {"active": [], "archived": []})
+
+ if not latest.exists():
+ save_json(
+ latest,
+ {
+ "site_id": site_id,
+ "summary": "bootstrap complete",
+ "open_issues": [],
+ "recent_actions": [],
+ },
+ )
+
+ if not learned.exists():
+ save_json(learned, {"site_id": site_id, "observations": []})
+
+ return site_root
+
+
+def main(argv: list[str]) -> int:
+ if len(argv) != 2:
+ print("usage: bootstrap_site.py <url-or-domain>", file=sys.stderr)
+ return 1
+ print(bootstrap_site(argv[1]))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/bootstrap_workspace.py b/openclaw/bin/bootstrap_workspace.py
new file mode 100755
index 00000000..7d4e0237
--- /dev/null
+++ b/openclaw/bin/bootstrap_workspace.py
@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Create the Toprank OpenClaw runtime workspace if it does not exist."""
+
+from __future__ import annotations
+
+from runtime import bootstrap_workspace
+
+
+if __name__ == "__main__":
+ print(bootstrap_workspace())
diff --git a/openclaw/bin/followups_due.py b/openclaw/bin/followups_due.py
new file mode 100755
index 00000000..071c4a63
--- /dev/null
+++ b/openclaw/bin/followups_due.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""List due or upcoming follow-up items from the Toprank OpenClaw schedule."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from runtime import bootstrap_workspace, load_json, now_iso, workspace_root
+
+
+def parse_iso(value: str | None) -> datetime:
+ if not value:
+ return datetime.max.replace(tzinfo=timezone.utc)
+ normalized = value.replace("Z", "+00:00")
+ return datetime.fromisoformat(normalized)
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--site")
+ parser.add_argument("--include-future", action="store_true")
+ parser.add_argument("--as-of", default=now_iso())
+ args = parser.parse_args(argv[1:])
+
+ root = bootstrap_workspace(workspace_root())
+ schedule = load_json(root / "schedule.json", {"upcoming": []})
+ cutoff = parse_iso(args.as_of)
+
+ items = []
+ for item in schedule.get("upcoming", []):
+ if args.site and item.get("site_id") != args.site:
+ continue
+ due_at = parse_iso(item.get("due_at"))
+ if args.include_future or due_at <= cutoff:
+ items.append(item)
+
+ items.sort(key=lambda item: item.get("due_at") or "")
+ result = {
+ "generated_at": now_iso(),
+ "as_of": args.as_of,
+ "site_filter": args.site,
+ "count": len(items),
+ "items": items,
+ }
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/hydrate_followup_gsc.py b/openclaw/bin/hydrate_followup_gsc.py
new file mode 100755
index 00000000..6d7bb22e
--- /dev/null
+++ b/openclaw/bin/hydrate_followup_gsc.py
@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Fetch real GSC metrics for a follow-up item and attach them as observed metrics."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from runtime import bootstrap_workspace, load_json, workspace_root
+
+ANALYZE_GSC = Path(__file__).resolve().parents[2] / "seo" / "seo-analysis" / "scripts" / "analyze_gsc.py"
+
+
+def infer_days(primary_metric: str | None, fallback: int = 28) -> int:
+ if not primary_metric:
+ return fallback
+ for part in primary_metric.split("_"):
+ if part.endswith("d") and part[:-1].isdigit():
+ return int(part[:-1])
+ return fallback
+
+
+def metric_suffix(days: int) -> str:
+ return f"_{days}d"
+
+
+def extract_metrics(data: dict, days: int) -> dict[str, float]:
+ suffix = metric_suffix(days)
+ summary = data.get("summary", {})
+ metrics: dict[str, float] = {}
+ if summary:
+ metrics[f"organic_clicks{suffix}"] = float(summary.get("clicks", 0))
+ metrics[f"organic_impressions{suffix}"] = float(summary.get("impressions", 0))
+ metrics[f"organic_ctr{suffix}"] = float(summary.get("ctr", 0))
+ metrics[f"avg_position{suffix}"] = float(summary.get("position", 0))
+ branded_split = data.get("branded_split") or {}
+ branded = branded_split.get("branded") or {}
+ non_branded = branded_split.get("non_branded") or {}
+ if branded or non_branded:
+ metrics[f"branded_clicks{suffix}"] = float(branded.get("clicks", 0))
+ metrics[f"non_brand_clicks{suffix}"] = float(non_branded.get("clicks", 0))
+ metrics[f"branded_impressions{suffix}"] = float(branded.get("impressions", 0))
+ metrics[f"non_brand_impressions{suffix}"] = float(non_branded.get("impressions", 0))
+ return metrics
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site_id")
+ parser.add_argument("item_id")
+ parser.add_argument("--gsc-property")
+ parser.add_argument("--brand-terms")
+ parser.add_argument("--days", type=int)
+ parser.add_argument("--analysis-file")
+ args = parser.parse_args(argv[1:])
+
+ root = bootstrap_workspace(workspace_root())
+ site_root = root / "sites" / args.site_id
+ queue_path = site_root / "queue" / f"{args.item_id}.json"
+ if not queue_path.exists():
+ raise SystemExit(f"queue item not found: {queue_path}")
+ queue_item = load_json(queue_path, {})
+ profile = load_json(site_root / "site-profile.json", {})
+
+ primary_metric = queue_item.get("primary_metric")
+ days = args.days or infer_days(primary_metric, 28)
+ gsc_property = args.gsc_property or profile.get("gsc_property") or profile.get("canonical_url")
+ if not gsc_property:
+ raise SystemExit("No GSC property or canonical_url available for this site.")
+
+ brand_terms = args.brand_terms or ",".join(profile.get("brand_terms", []))
+
+ if args.analysis_file:
+ data = json.loads(Path(args.analysis_file).read_text())
+ else:
+ with tempfile.NamedTemporaryFile(prefix="toprank_gsc_", suffix=".json", delete=False) as tmp:
+ output_path = Path(tmp.name)
+
+ cmd = [sys.executable, str(ANALYZE_GSC), "--site", gsc_property, "--days", str(days), "--output", str(output_path)]
+ if brand_terms:
+ cmd.extend(["--brand-terms", brand_terms])
+ subprocess.run(cmd, check=True)
+
+ data = json.loads(output_path.read_text())
+ observed_metrics = extract_metrics(data, days)
+ queue_item.setdefault("observed_metrics", {})
+ queue_item["observed_metrics"].update(observed_metrics)
+ queue_path.write_text(json.dumps(queue_item, indent=2, ensure_ascii=False) + "\n")
+
+ schedule_path = root / "schedule.json"
+ schedule = load_json(schedule_path, {"schema_version": "1", "upcoming": []})
+ for item in schedule.get("upcoming", []):
+ if item.get("item_id") == args.item_id and item.get("site_id") == args.site_id:
+ item.setdefault("observed_metrics", {})
+ item["observed_metrics"].update(observed_metrics)
+ break
+ schedule_path.write_text(json.dumps(schedule, indent=2, ensure_ascii=False) + "\n")
+
+ print(json.dumps({
+ "queue_path": str(queue_path),
+ "gsc_property": gsc_property,
+ "days": days,
+ "observed_metrics": observed_metrics,
+ }, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/improve_page.py b/openclaw/bin/improve_page.py
new file mode 100755
index 00000000..a2f0882e
--- /dev/null
+++ b/openclaw/bin/improve_page.py
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Create and persist a page-improvement proposal for a site."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from persist_run import persist_payload
+from runtime import now_iso, workspace_root
+from site_id import normalize_site_id
+
+
+def future_iso(days: int) -> str:
+ return (datetime.now(timezone.utc) + timedelta(days=days)).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site")
+ parser.add_argument("--url", required=True)
+ parser.add_argument("--issue-summary", required=True)
+ parser.add_argument("--proposal-summary", required=True)
+ parser.add_argument("--action-type", default="page_improvement")
+ parser.add_argument("--expected-impact", default="Improve organic performance for the target page.")
+ parser.add_argument("--requires-approval", dest="requires_approval", action="store_true", default=True)
+ parser.add_argument("--auto-safe", dest="requires_approval", action="store_false")
+ parser.add_argument("--follow-up-days", type=int, default=14)
+ parser.add_argument("--primary-metric", default="organic_clicks_28d")
+ parser.add_argument("--success-threshold-pct", type=float, default=0.1)
+ parser.add_argument("--baseline-metric", action="append", default=[])
+ parser.add_argument("--guardrail-metric", action="append", default=[], help="metric:direction:max_worsen_pct")
+ parser.add_argument("--patch-path", action="append", default=[])
+ parser.add_argument("--patch-summary", action="append", default=[])
+ args = parser.parse_args(argv[1:])
+
+ site_id = normalize_site_id(args.site)
+ generated_at = now_iso()
+ follow_up_due = future_iso(args.follow_up_days)
+
+ baseline_metrics = {}
+ for raw in args.baseline_metric:
+ if "=" not in raw:
+ raise SystemExit(f"baseline metric must look like name=value, got: {raw}")
+ name, value = raw.split("=", 1)
+ baseline_metrics[name.strip()] = float(value)
+
+ guardrail_metrics = []
+ for raw in args.guardrail_metric:
+ metric, direction, max_worsen = raw.split(":", 2)
+ guardrail_metrics.append({"metric": metric, "direction": direction, "max_worsen_pct": float(max_worsen)})
+
+ proposal = {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "proposal_type": args.action_type,
+ "target": args.url,
+ "summary": args.proposal_summary,
+ "requires_approval": args.requires_approval,
+ }
+
+ payload: dict = {
+ "generated_at": generated_at,
+ "trigger": {
+ "type": "improve_page",
+ "target": args.url,
+ "notes": f"Improve page workflow for {args.url}.",
+ },
+ "state_snapshot": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "summary": f"Page improvement requested for {args.url}.",
+ "open_issues": [
+ {
+ "title": args.issue_summary,
+ "severity": "warning",
+ "confidence": 0.75,
+ }
+ ],
+ "recent_actions": [],
+ },
+ "audit": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "summary": f"Focused page review for {args.url}.",
+ "issues": [
+ {
+ "title": args.issue_summary,
+ "severity": "warning",
+ "confidence": 0.75,
+ "evidence": [f"Target URL: {args.url}"],
+ "recommended_action_type": args.action_type,
+ }
+ ],
+ },
+ "action_plan": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "actions": [
+ {
+ "action_id": f"improve_page_{site_id}_{generated_at.replace(':', '-')}",
+ "title": args.proposal_summary,
+ "type": args.action_type,
+ "priority_score": 0.82,
+ "expected_impact": args.expected_impact,
+ "requires_approval": args.requires_approval,
+ "reversibility": "high",
+ "owner": "operator",
+ }
+ ],
+ },
+ "proposal": proposal,
+ "verification": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "checks": [
+ {
+ "name": "proposal persisted",
+ "status": "pass",
+ "notes": f"Stored proposal artifact for {args.url}.",
+ },
+ {
+ "name": "approval gate",
+ "status": "warning" if args.requires_approval else "pass",
+ "notes": "External or production writes still require approval." if args.requires_approval else "No external write requested yet.",
+ },
+ ],
+ "follow_up_due": follow_up_due,
+ },
+ "queue_items": [
+ {
+ "item_id": f"followup_{site_id}_{generated_at.replace(':', '-')}",
+ "type": "feedback_check",
+ "status": "pending",
+ "due_at": follow_up_due,
+ "notes": f"Review impact of page improvement for {args.url}.",
+ "action_type": args.action_type,
+ "primary_metric": args.primary_metric,
+ "primary_direction": "higher_better",
+ "success_threshold_pct": args.success_threshold_pct,
+ "baseline_metrics": baseline_metrics,
+ "guardrail_metrics": guardrail_metrics,
+ }
+ ],
+ }
+
+ if args.patch_path:
+ patches = []
+ for index, path in enumerate(args.patch_path):
+ summary = args.patch_summary[index] if index < len(args.patch_summary) else f"Patch proposal for {path}"
+ patches.append({"path": path, "change_type": args.action_type, "summary": summary})
+ payload["patch_set"] = {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "patches": patches,
+ }
+
+ result = persist_payload(args.site, payload, root=workspace_root())
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/investigate_drop.py b/openclaw/bin/investigate_drop.py
new file mode 100755
index 00000000..635e772c
--- /dev/null
+++ b/openclaw/bin/investigate_drop.py
@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Create and persist a traffic-drop investigation for a site."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from persist_run import persist_payload
+from runtime import now_iso, workspace_root
+from site_id import normalize_site_id
+
+
+def future_iso(days: int) -> str:
+ return (datetime.now(timezone.utc) + timedelta(days=days)).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site")
+ parser.add_argument("--summary", required=True)
+ parser.add_argument("--likely-cause", action="append", default=[])
+ parser.add_argument("--target-url")
+ parser.add_argument("--follow-up-days", type=int, default=7)
+ parser.add_argument("--primary-metric", default="organic_clicks_7d")
+ parser.add_argument("--success-threshold-pct", type=float, default=0.1)
+ parser.add_argument("--baseline-metric", action="append", default=[])
+ parser.add_argument("--guardrail-metric", action="append", default=[], help="metric:direction:max_worsen_pct")
+ args = parser.parse_args(argv[1:])
+
+ site_id = normalize_site_id(args.site)
+ generated_at = now_iso()
+ follow_up_due = future_iso(args.follow_up_days)
+ causes = args.likely_cause or ["Investigate ranking, indexation, and CTR changes."]
+
+ baseline_metrics = {}
+ for raw in args.baseline_metric:
+ if "=" not in raw:
+ raise SystemExit(f"baseline metric must look like name=value, got: {raw}")
+ name, value = raw.split("=", 1)
+ baseline_metrics[name.strip()] = float(value)
+
+ guardrail_metrics = []
+ for raw in args.guardrail_metric:
+ metric, direction, max_worsen = raw.split(":", 2)
+ guardrail_metrics.append({"metric": metric, "direction": direction, "max_worsen_pct": float(max_worsen)})
+
+ issues = []
+ actions = []
+ for index, cause in enumerate(causes, start=1):
+ issues.append(
+ {
+ "title": cause,
+ "severity": "warning" if index > 1 else "critical",
+ "confidence": max(0.45, 0.8 - ((index - 1) * 0.1)),
+ "evidence": [args.summary],
+ "recommended_action_type": "drop_recovery",
+ }
+ )
+ actions.append(
+ {
+ "action_id": f"drop_recovery_{index:02d}",
+ "title": f"Investigate and mitigate: {cause}",
+ "type": "drop_recovery",
+ "priority_score": round(0.92 - ((index - 1) * 0.08), 2),
+ "expected_impact": "Recover lost visibility or conversions from the reported drop.",
+ "requires_approval": index == 1,
+ "reversibility": "high",
+ "owner": "operator",
+ }
+ )
+
+ queue_items = [
+ {
+ "item_id": f"drop_followup_{site_id}_{generated_at.replace(':', '-')}",
+ "type": "feedback_check",
+ "status": "pending",
+ "due_at": follow_up_due,
+ "notes": "Reassess the traffic drop after mitigation work or more data.",
+ "action_type": "drop_recovery",
+ "primary_metric": args.primary_metric,
+ "primary_direction": "higher_better",
+ "success_threshold_pct": args.success_threshold_pct,
+ "baseline_metrics": baseline_metrics,
+ "guardrail_metrics": guardrail_metrics,
+ }
+ ]
+
+ if args.target_url:
+ queue_items.append(
+ {
+ "item_id": f"improve_page_{site_id}_{generated_at.replace(':', '-')}",
+ "type": "improve_page",
+ "status": "pending",
+ "notes": f"Run a focused page improvement workflow for {args.target_url}.",
+ "target": args.target_url,
+ }
+ )
+
+ payload = {
+ "generated_at": generated_at,
+ "trigger": {
+ "type": "traffic_drop_detected",
+ "notes": args.summary,
+ "target": args.target_url,
+ },
+ "state_snapshot": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "summary": args.summary,
+ "open_issues": [
+ {
+ "title": issue["title"],
+ "severity": issue["severity"],
+ "confidence": issue["confidence"],
+ }
+ for issue in issues
+ ],
+ "recent_actions": [],
+ },
+ "audit": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "summary": args.summary,
+ "issues": issues,
+ },
+ "action_plan": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "actions": actions,
+ },
+ "verification": {
+ "site_id": site_id,
+ "generated_at": generated_at,
+ "checks": [
+ {
+ "name": "drop investigation persisted",
+ "status": "pass",
+ "notes": "Stored ranked recovery actions for the reported drop.",
+ },
+ {
+ "name": "follow-up scheduled",
+ "status": "pass",
+ "notes": f"Feedback check scheduled for {follow_up_due}.",
+ },
+ ],
+ "follow_up_due": follow_up_due,
+ },
+ "queue_items": queue_items,
+ }
+
+ result = persist_payload(args.site, payload, root=workspace_root())
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/onboard_site.py b/openclaw/bin/onboard_site.py
new file mode 100755
index 00000000..b7f154fc
--- /dev/null
+++ b/openclaw/bin/onboard_site.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Register or update a site in the Toprank OpenClaw portfolio."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from bootstrap_site import bootstrap_site
+from runtime import load_json, now_iso, save_json, upsert_portfolio_site, workspace_root
+from site_id import normalize_site_id
+
+
+def parse_brand_terms(raw: str | None) -> list[str]:
+ if not raw:
+ return []
+ return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+def next_goal_id(active: list[dict], site_id: str) -> str:
+ return f"goal_{site_id.replace('.', '_')}_{len(active) + 1:03d}"
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site")
+ parser.add_argument("--display-name")
+ parser.add_argument("--brand-terms", help="Comma-separated brand terms")
+ parser.add_argument("--cms")
+ parser.add_argument("--business-context")
+ parser.add_argument("--business-weight", type=float, default=1.0)
+ parser.add_argument("--cadence", default="weekly", choices=["daily", "weekly", "monthly", "on_demand"])
+ parser.add_argument("--goal-type", default="grow_non_brand_clicks")
+ parser.add_argument("--primary-metric", default="non_brand_clicks_28d")
+ parser.add_argument("--target-delta", type=float)
+ parser.add_argument("--skip-goal", action="store_true")
+ args = parser.parse_args(argv[1:])
+
+ root = workspace_root()
+ site_id = normalize_site_id(args.site)
+ site_path = bootstrap_site(args.site, root)
+
+ profile_path = site_path / "site-profile.json"
+ goals_path = site_path / "goals.json"
+ latest_path = site_path / "latest-state.json"
+
+ profile = load_json(profile_path, {})
+ profile.update(
+ {
+ "schema_version": "1",
+ "site_id": site_id,
+ "canonical_url": args.site if "://" in args.site else f"https://{site_id}",
+ "display_name": args.display_name or profile.get("display_name") or site_id,
+ "brand_terms": parse_brand_terms(args.brand_terms) or profile.get("brand_terms") or [],
+ "cms": args.cms if args.cms is not None else profile.get("cms"),
+ "business_context": args.business_context if args.business_context is not None else profile.get("business_context"),
+ "status": profile.get("status", "active"),
+ }
+ )
+ save_json(profile_path, profile)
+
+ portfolio_site = upsert_portfolio_site(
+ site_id,
+ display_name=profile["display_name"],
+ business_weight=args.business_weight,
+ cadence=args.cadence,
+ status=profile["status"],
+ root=root,
+ )
+
+ goals = load_json(goals_path, {"active": [], "archived": []})
+ created_goal = None
+ if not args.skip_goal:
+ active = goals.setdefault("active", [])
+ existing = next(
+ (
+ goal
+ for goal in active
+ if goal.get("type") == args.goal_type and goal.get("primary_metric") == args.primary_metric and goal.get("status") == "active"
+ ),
+ None,
+ )
+ if existing is None:
+ created_goal = {
+ "goal_id": next_goal_id(active, site_id),
+ "site_id": site_id,
+ "type": args.goal_type,
+ "primary_metric": args.primary_metric,
+ "target_delta": args.target_delta,
+ "status": "active",
+ "created_at": now_iso(),
+ }
+ active.append(created_goal)
+ save_json(goals_path, goals)
+ else:
+ created_goal = existing
+
+ latest = load_json(latest_path, {"site_id": site_id})
+ latest.update(
+ {
+ "site_id": site_id,
+ "generated_at": now_iso(),
+ "summary": f"Onboarded {profile['display_name']} into the OpenClaw portfolio.",
+ "open_issues": latest.get("open_issues", []),
+ "recent_actions": [
+ {
+ "type": "site_onboard",
+ "at": now_iso(),
+ "notes": f"Initialized work folder for {site_id}.",
+ }
+ ],
+ }
+ )
+ save_json(latest_path, latest)
+
+ result = {
+ "site_id": site_id,
+ "site_path": str(site_path),
+ "portfolio_site": portfolio_site,
+ "goal": created_goal,
+ }
+ print(__import__("json").dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/persist_run.py b/openclaw/bin/persist_run.py
new file mode 100755
index 00000000..00470628
--- /dev/null
+++ b/openclaw/bin/persist_run.py
@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Persist OpenClaw run artifacts for a site review or follow-up."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from bootstrap_site import bootstrap_site
+from runtime import ensure_site_dirs, load_json, now_iso, save_json, timestamp_slug, upsert_schedule_items, workspace_root
+from site_id import normalize_site_id
+
+ARTIFACT_KEYS = {
+ "trigger": "trigger.json",
+ "state_snapshot": "state-snapshot.json",
+ "audit": "audit.json",
+ "action_plan": "action-plan.json",
+ "proposal": "proposal.json",
+ "patch_set": "patch-set.json",
+ "verification": "verification.json",
+ "feedback": "feedback.json",
+ "learning_log": "learning-log.json",
+}
+
+
+REQUIRED_KEYS = ["audit", "action_plan", "verification"]
+
+
+def metric_direction(metric_name: str | None) -> str:
+ if not metric_name:
+ return "higher_better"
+ return "lower_better" if "position" in metric_name.lower() else "higher_better"
+
+
+def extract_metric_snapshot(payload: dict) -> dict:
+ for source_key in ["state_snapshot", "audit", "proposal", "feedback"]:
+ source = payload.get(source_key)
+ if isinstance(source, dict) and isinstance(source.get("metrics"), dict):
+ return dict(source["metrics"])
+ return {}
+
+
+def enrich_queue_items(payload: dict) -> None:
+ queue_items = payload.get("queue_items")
+ if not isinstance(queue_items, list):
+ return
+ metric_snapshot = extract_metric_snapshot(payload)
+ first_action = None
+ actions = payload.get("action_plan", {}).get("actions", []) if isinstance(payload.get("action_plan"), dict) else []
+ if actions:
+ first_action = actions[0]
+ proposal = payload.get("proposal") if isinstance(payload.get("proposal"), dict) else {}
+ trigger = payload.get("trigger") if isinstance(payload.get("trigger"), dict) else {}
+
+ for item in queue_items:
+ if not isinstance(item, dict):
+ continue
+ if item.get("type") != "feedback_check":
+ continue
+ if first_action and not item.get("action_type"):
+ item["action_type"] = first_action.get("type")
+ if proposal.get("target") and not item.get("target"):
+ item["target"] = proposal.get("target")
+ elif trigger.get("target") and not item.get("target"):
+ item["target"] = trigger.get("target")
+ if metric_snapshot and not item.get("baseline_metrics"):
+ item["baseline_metrics"] = dict(metric_snapshot)
+ if not item.get("primary_metric") and metric_snapshot:
+ preferred = [
+ key
+ for key in [
+ "non_brand_clicks_28d",
+ "organic_clicks_28d",
+ "organic_clicks_7d",
+ "organic_impressions_28d",
+ "organic_ctr_28d",
+ "avg_position_28d",
+ ]
+ if key in metric_snapshot
+ ]
+ item["primary_metric"] = preferred[0] if preferred else next(iter(metric_snapshot.keys()), None)
+ if item.get("primary_metric") and not item.get("primary_direction"):
+ item["primary_direction"] = metric_direction(item.get("primary_metric"))
+ if "success_threshold_pct" not in item:
+ item["success_threshold_pct"] = 0.1
+ if "guardrail_metrics" not in item:
+ item["guardrail_metrics"] = []
+
+
+def with_defaults(payload: dict, site_id: str) -> dict:
+ generated_at = payload.get("generated_at") or now_iso()
+ payload["generated_at"] = generated_at
+ for key in REQUIRED_KEYS:
+ if key not in payload:
+ raise ValueError(f"payload missing required key: {key}")
+ enrich_queue_items(payload)
+ for key in ["state_snapshot", "audit", "action_plan", "proposal", "patch_set", "verification", "feedback", "learning_log"]:
+ if key in payload and isinstance(payload[key], dict):
+ payload[key].setdefault("site_id", site_id)
+ payload[key].setdefault("generated_at", generated_at)
+ if "trigger" not in payload:
+ payload["trigger"] = {"site_id": site_id, "generated_at": generated_at, "type": "manual_request"}
+ else:
+ payload["trigger"].setdefault("site_id", site_id)
+ payload["trigger"].setdefault("generated_at", generated_at)
+ return payload
+
+
+def persist_queue_items(site_path: Path, queue_items: list[dict], site_id: str) -> tuple[list[str], list[dict]]:
+ queue_dir = site_path / "queue"
+ queue_dir.mkdir(parents=True, exist_ok=True)
+ written = []
+ normalized = []
+ for index, item in enumerate(queue_items, start=1):
+ item_id = item.get("item_id") or f"queue_{timestamp_slug()}_{index:02d}"
+ item.setdefault("site_id", site_id)
+ item.setdefault("status", "pending")
+ item.setdefault("created_at", now_iso())
+ item["item_id"] = item_id
+ path = queue_dir / f"{item_id}.json"
+ save_json(path, item)
+ written.append(str(path))
+ normalized.append(item)
+ return written, normalized
+
+
+def derive_latest_state(payload: dict, site_id: str) -> dict:
+ if isinstance(payload.get("state_snapshot"), dict):
+ latest = dict(payload["state_snapshot"])
+ latest.setdefault("site_id", site_id)
+ latest.setdefault("generated_at", payload["generated_at"])
+ return latest
+
+ audit = payload["audit"]
+ actions = payload["action_plan"].get("actions", [])
+ summary = audit.get("summary") or "Weekly review complete."
+ open_issues = []
+ for issue in audit.get("issues", [])[:5]:
+ open_issues.append(
+ {
+ "title": issue.get("title"),
+ "severity": issue.get("severity", "warning"),
+ "confidence": issue.get("confidence"),
+ }
+ )
+ recent_actions = []
+ for action in actions[:3]:
+ recent_actions.append(
+ {
+ "type": action.get("type"),
+ "title": action.get("title"),
+ "requires_approval": action.get("requires_approval", True),
+ }
+ )
+ return {
+ "site_id": site_id,
+ "generated_at": payload["generated_at"],
+ "summary": summary,
+ "open_issues": open_issues,
+ "recent_actions": recent_actions,
+ }
+
+
+def next_run_dir(site_path: Path) -> Path:
+ base = timestamp_slug()
+ candidate = site_path / "runs" / base
+ if not candidate.exists():
+ return candidate
+ counter = 2
+ while True:
+ candidate = site_path / "runs" / f"{base}-{counter:02d}"
+ if not candidate.exists():
+ return candidate
+ counter += 1
+
+
+def persist_payload(site_input: str, payload: dict, *, root: Path | None = None) -> dict:
+ root = root or workspace_root()
+ site_id = normalize_site_id(site_input)
+ site_path = ensure_site_dirs(site_id, root)
+ if not (site_path / "site-profile.json").exists():
+ bootstrap_site(site_input, root)
+
+ payload = with_defaults(payload, site_id)
+
+ run_dir = next_run_dir(site_path)
+ run_dir.mkdir(parents=True, exist_ok=False)
+
+ written = []
+ for key, filename in ARTIFACT_KEYS.items():
+ data = payload.get(key)
+ if data is None:
+ continue
+ path = run_dir / filename
+ save_json(path, data)
+ written.append(str(path))
+
+ latest_state = derive_latest_state(payload, site_id)
+ save_json(site_path / "latest-state.json", latest_state)
+
+ queue_paths = []
+ schedule_items_written = []
+ if isinstance(payload.get("queue_items"), list):
+ queue_paths, normalized_queue = persist_queue_items(site_path, payload["queue_items"], site_id)
+ schedule_candidates = [item for item in normalized_queue if item.get("due_at")]
+ if schedule_candidates:
+ schedule_items_written = upsert_schedule_items(schedule_candidates, root)
+
+ return {
+ "site_id": site_id,
+ "run_dir": str(run_dir),
+ "artifacts_written": written,
+ "queue_items_written": queue_paths,
+ "schedule_items_written": schedule_items_written,
+ }
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site")
+ parser.add_argument("--payload-file", required=True)
+ args = parser.parse_args(argv[1:])
+
+ payload = json.loads(Path(args.payload_file).read_text())
+ result = persist_payload(args.site, payload)
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/portfolio_review.py b/openclaw/bin/portfolio_review.py
new file mode 100755
index 00000000..381726c8
--- /dev/null
+++ b/openclaw/bin/portfolio_review.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Rank active sites in the Toprank OpenClaw portfolio by urgency and upside."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from runtime import bootstrap_workspace, load_json, now_iso, save_json, timestamp_slug, workspace_root
+
+SEVERITY_WEIGHTS = {
+ "critical": 3.0,
+ "warning": 1.5,
+ "info": 0.5,
+}
+
+
+def site_priority(record: dict, latest_state: dict, goals: dict) -> tuple[float, dict]:
+ open_issues = latest_state.get("open_issues", [])
+ urgency = sum(SEVERITY_WEIGHTS.get(issue.get("severity", "warning"), 1.0) for issue in open_issues) or 0.5
+ active_goals = len(goals.get("active", [])) or 1
+ business_weight = float(record.get("business_weight", 1.0))
+ opportunity = 1.0 + (0.25 * min(active_goals, 4))
+ score = round(business_weight * urgency * opportunity, 3)
+ summary = latest_state.get("summary") or "No recent state summary."
+ return score, {
+ "site_id": record["site_id"],
+ "display_name": record.get("display_name") or record["site_id"],
+ "score": score,
+ "business_weight": business_weight,
+ "open_issue_count": len(open_issues),
+ "active_goal_count": len(goals.get("active", [])),
+ "summary": summary,
+ "top_issue": open_issues[0]["title"] if open_issues else None,
+ }
+
+
+def main(argv: list[str]) -> int:
+ root = bootstrap_workspace(workspace_root())
+ portfolio = load_json(root / "portfolio.json", {"sites": []})
+ active_sites = [site for site in portfolio.get("sites", []) if site.get("status", "active") == "active"]
+
+ rankings = []
+ for record in active_sites:
+ site_root = root / "sites" / record["site_id"]
+ latest_state = load_json(site_root / "latest-state.json", {"summary": "No state yet.", "open_issues": []})
+ goals = load_json(site_root / "goals.json", {"active": [], "archived": []})
+ score, site_summary = site_priority(record, latest_state, goals)
+ rankings.append(site_summary)
+
+ rankings.sort(key=lambda item: item["score"], reverse=True)
+ result = {
+ "generated_at": now_iso(),
+ "site_count": len(rankings),
+ "rankings": rankings,
+ "recommended_focus_site": rankings[0]["site_id"] if rankings else None,
+ }
+
+ output_dir = root / "portfolio-reviews"
+ output_dir.mkdir(parents=True, exist_ok=True)
+ save_json(output_dir / f"{timestamp_slug()}.json", result)
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/record_followup_metrics.py b/openclaw/bin/record_followup_metrics.py
new file mode 100755
index 00000000..5f438541
--- /dev/null
+++ b/openclaw/bin/record_followup_metrics.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Attach observed metric values to a queued follow-up item and matching schedule entry."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from runtime import bootstrap_workspace, load_json, save_json, workspace_root
+
+
+def parse_metric_pairs(values: list[str]) -> dict[str, float]:
+ metrics: dict[str, float] = {}
+ for raw in values:
+ if "=" not in raw:
+ raise ValueError(f"metric must look like name=value, got: {raw}")
+ name, value = raw.split("=", 1)
+ metrics[name.strip()] = float(value)
+ return metrics
+
+
+def update_item(payload: dict, args: argparse.Namespace) -> dict:
+ if args.primary_metric:
+ payload["primary_metric"] = args.primary_metric
+ if args.primary_direction:
+ payload["primary_direction"] = args.primary_direction
+ if args.success_threshold_pct is not None:
+ payload["success_threshold_pct"] = args.success_threshold_pct
+ if args.baseline_metric:
+ payload["baseline_metrics"] = {**payload.get("baseline_metrics", {}), **parse_metric_pairs(args.baseline_metric)}
+ if args.observed_metric:
+ payload["observed_metrics"] = {**payload.get("observed_metrics", {}), **parse_metric_pairs(args.observed_metric)}
+ if args.guardrail_metric:
+ guardrails = payload.get("guardrail_metrics", [])
+ for raw in args.guardrail_metric:
+ metric, direction, max_worsen = raw.split(":", 2)
+ guardrails.append({"metric": metric, "direction": direction, "max_worsen_pct": float(max_worsen)})
+ payload["guardrail_metrics"] = guardrails
+ if args.notes:
+ payload["notes"] = args.notes
+ return payload
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site_id")
+ parser.add_argument("item_id")
+ parser.add_argument("--primary-metric")
+ parser.add_argument("--primary-direction", choices=["higher_better", "lower_better"])
+ parser.add_argument("--success-threshold-pct", type=float)
+ parser.add_argument("--baseline-metric", action="append", default=[])
+ parser.add_argument("--observed-metric", action="append", default=[])
+ parser.add_argument("--guardrail-metric", action="append", default=[], help="metric:direction:max_worsen_pct")
+ parser.add_argument("--notes")
+ args = parser.parse_args(argv[1:])
+
+ root = bootstrap_workspace(workspace_root())
+ queue_path = root / "sites" / args.site_id / "queue" / f"{args.item_id}.json"
+ if not queue_path.exists():
+ raise SystemExit(f"queue item not found: {queue_path}")
+
+ queue_payload = load_json(queue_path, {})
+ queue_payload = update_item(queue_payload, args)
+ save_json(queue_path, queue_payload)
+
+ schedule_path = root / "schedule.json"
+ schedule = load_json(schedule_path, {"schema_version": "1", "upcoming": []})
+ for item in schedule.get("upcoming", []):
+ if item.get("item_id") == args.item_id and item.get("site_id") == args.site_id:
+ item.update(queue_payload)
+ break
+ save_json(schedule_path, schedule)
+
+ print(json.dumps({"queue_path": str(queue_path), "updated_item": queue_payload}, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/run_scheduler.py b/openclaw/bin/run_scheduler.py
new file mode 100755
index 00000000..76fb04c6
--- /dev/null
+++ b/openclaw/bin/run_scheduler.py
@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Process due items from the Toprank OpenClaw schedule."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from persist_run import persist_payload
+from runtime import bootstrap_workspace, load_json, now_iso, save_json, update_learned_patterns, workspace_root
+from score_feedback import score_item
+
+
+def parse_iso(value: str | None) -> datetime:
+ if not value:
+ return datetime.max.replace(tzinfo=timezone.utc)
+ return datetime.fromisoformat(value.replace('Z', '+00:00'))
+
+
+def update_queue_file(root: Path, item: dict, **updates) -> str | None:
+ item_id = item.get("item_id")
+ site_id = item.get("site_id")
+ if not item_id or not site_id:
+ return None
+ queue_path = root / "sites" / site_id / "queue" / f"{item_id}.json"
+ if not queue_path.exists():
+ return None
+ payload = load_json(queue_path, {})
+ payload.update(updates)
+ save_json(queue_path, payload)
+ return str(queue_path)
+
+
+def build_feedback_payload(item: dict, root: Path) -> dict:
+ site_id = item["site_id"]
+ latest = load_json(root / "sites" / site_id / "latest-state.json", {"summary": "No recent state summary.", "open_issues": []})
+ summary = item.get("notes") or latest.get("summary") or "Scheduled follow-up review."
+ action_id = item.get("item_id", "feedback_check")
+ score = score_item(item)
+ outcome = score.get("outcome", "inconclusive")
+ reason = score.get("reason", "no scoring reason available")
+ score_summary = f"Feedback outcome: {outcome}. Reason: {reason}."
+ if score.get("primary_metric"):
+ score_summary += f" Primary metric `{score['primary_metric']}` changed {score.get('primary_change', 0):+.1%}."
+ return {
+ "trigger": {
+ "type": "scheduled_followup",
+ "notes": summary,
+ "source_item_id": action_id,
+ },
+ "state_snapshot": {
+ "site_id": site_id,
+ "summary": f"Follow-up checkpoint due for {site_id}. {score_summary}",
+ "open_issues": latest.get("open_issues", []),
+ "recent_actions": latest.get("recent_actions", []),
+ },
+ "audit": {
+ "site_id": site_id,
+ "summary": f"Scheduled feedback review for {site_id}. {score_summary}",
+ "issues": [
+ {
+ "title": "A scheduled follow-up reached its review window.",
+ "severity": "info" if outcome in {"win", "neutral", "inconclusive"} else "warning",
+ "confidence": score.get("confidence", 0.6),
+ "evidence": [summary, score_summary],
+ "recommended_action_type": "feedback_review",
+ }
+ ],
+ },
+ "action_plan": {
+ "site_id": site_id,
+ "actions": [
+ {
+ "action_id": f"feedback_review_{action_id}",
+ "title": "Review post-change performance and decide whether to continue, revise, or stop the intervention.",
+ "type": "feedback_review",
+ "priority_score": 0.7,
+ "expected_impact": "Turns a pending follow-up into a concrete review task.",
+ "requires_approval": False,
+ "reversibility": "high",
+ "owner": "operator",
+ }
+ ],
+ },
+ "feedback": {
+ "site_id": site_id,
+ "action_id": action_id,
+ "window_days": 14,
+ "outcome": outcome,
+ "summary": score_summary,
+ "score": score,
+ },
+ "learning_log": {
+ "site_id": site_id,
+ "observations": [
+ {
+ "pattern": f"followup_{outcome}",
+ "confidence": score.get("confidence", 0.55),
+ "notes": score_summary,
+ }
+ ],
+ },
+ "verification": {
+ "site_id": site_id,
+ "checks": [
+ {
+ "name": "follow-up materialized",
+ "status": "pass",
+ "notes": "A scheduled follow-up run artifact was created.",
+ },
+ {
+ "name": "outcome available",
+ "status": "pass" if outcome != "inconclusive" else "warning",
+ "notes": score_summary if outcome != "inconclusive" else "Metric data is still incomplete, so the follow-up remains inconclusive.",
+ },
+ ],
+ "follow_up_due": None,
+ },
+ }
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--site")
+ parser.add_argument("--as-of", default=now_iso())
+ parser.add_argument("--dry-run", action="store_true")
+ args = parser.parse_args(argv[1:])
+
+ root = bootstrap_workspace(workspace_root())
+ schedule_path = root / "schedule.json"
+ schedule = load_json(schedule_path, {"schema_version": "1", "upcoming": []})
+ upcoming = schedule.setdefault("upcoming", [])
+ as_of_dt = parse_iso(args.as_of)
+
+ processed = []
+ manual_attention = []
+
+ for item in upcoming:
+ if item.get("status", "pending") not in {"pending", "ready_for_attention"}:
+ continue
+ if args.site and item.get("site_id") != args.site:
+ continue
+ if parse_iso(item.get("due_at")) > as_of_dt:
+ continue
+
+ if item.get("type") == "feedback_check":
+ if args.dry_run:
+ processed.append({"item_id": item.get("item_id"), "site_id": item.get("site_id"), "dry_run": True})
+ continue
+ payload = build_feedback_payload(item, root)
+ result = persist_payload(item["site_id"], payload, root=root)
+ feedback_outcome = payload.get("feedback", {}).get("outcome", "inconclusive")
+ item["status"] = "processed"
+ item["processed_at"] = now_iso()
+ item["result_run_dir"] = result["run_dir"]
+ update_queue_file(root, item, status="done", processed_at=item["processed_at"], result_run_dir=result["run_dir"])
+
+ feedback_path = root / "sites" / item["site_id"] / "feedback" / f"{item['item_id']}.json"
+ feedback_payload = {
+ "site_id": item["site_id"],
+ "item_id": item["item_id"],
+ "processed_at": item["processed_at"],
+ "result_run_dir": result["run_dir"],
+ "status": feedback_outcome,
+ "notes": payload.get("feedback", {}).get("summary") or item.get("notes"),
+ "score": payload.get("feedback", {}).get("score"),
+ }
+ save_json(feedback_path, feedback_payload)
+ update_learned_patterns(
+ item["site_id"],
+ action_type=item.get("action_type"),
+ primary_metric=payload.get("feedback", {}).get("score", {}).get("primary_metric"),
+ outcome=feedback_outcome,
+ primary_change=payload.get("feedback", {}).get("score", {}).get("primary_change"),
+ confidence=payload.get("feedback", {}).get("score", {}).get("confidence"),
+ notes=payload.get("feedback", {}).get("summary") or item.get("notes"),
+ root=root,
+ )
+ processed.append({"item_id": item.get("item_id"), "site_id": item.get("site_id"), "result_run_dir": result["run_dir"], "outcome": feedback_outcome})
+ else:
+ item["status"] = "ready_for_attention"
+ item["surfaced_at"] = now_iso()
+ update_queue_file(root, item, status="ready_for_attention", surfaced_at=item["surfaced_at"])
+ manual_attention.append({"item_id": item.get("item_id"), "site_id": item.get("site_id"), "type": item.get("type")})
+
+ if not args.dry_run:
+ save_json(schedule_path, schedule)
+
+ result = {
+ "generated_at": now_iso(),
+ "as_of": args.as_of,
+ "processed": processed,
+ "manual_attention": manual_attention,
+ "dry_run": args.dry_run,
+ }
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/runtime.py b/openclaw/bin/runtime.py
new file mode 100755
index 00000000..1bd9b33c
--- /dev/null
+++ b/openclaw/bin/runtime.py
@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Shared helpers for the Toprank OpenClaw runtime workspace."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def workspace_root() -> Path:
+ configured = os.environ.get("TOPRANK_OPENCLAW_HOME")
+ return Path(configured or (Path.home() / ".toprank" / "openclaw")).expanduser()
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def timestamp_slug() -> str:
+ return now_iso().replace(":", "-")
+
+
+def load_json(path: Path, default: Any) -> Any:
+ if not path.exists():
+ return default
+ return json.loads(path.read_text())
+
+
+def save_json(path: Path, payload: Any) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+
+
+def bootstrap_workspace(root: Path | None = None) -> Path:
+ root = (root or workspace_root()).expanduser()
+ (root / "sites").mkdir(parents=True, exist_ok=True)
+
+ portfolio = root / "portfolio.json"
+ schedule = root / "schedule.json"
+
+ if not portfolio.exists():
+ save_json(portfolio, {"schema_version": "1", "portfolio_id": "default", "sites": []})
+ if not schedule.exists():
+ save_json(schedule, {"schema_version": "1", "upcoming": []})
+ return root
+
+
+def site_root(site_id: str, root: Path | None = None) -> Path:
+ root = bootstrap_workspace(root)
+ return root / "sites" / site_id
+
+
+def ensure_site_dirs(site_id: str, root: Path | None = None) -> Path:
+ site = site_root(site_id, root)
+ for subdir in ["queue", "proposals", "runs", "feedback"]:
+ (site / subdir).mkdir(parents=True, exist_ok=True)
+ return site
+
+
+def update_learned_patterns(
+ site_id: str,
+ *,
+ action_type: str | None,
+ primary_metric: str | None,
+ outcome: str,
+ primary_change: float | None,
+ confidence: float | None,
+ notes: str | None = None,
+ root: Path | None = None,
+) -> dict[str, Any]:
+ site = ensure_site_dirs(site_id, root)
+ path = site / "learned-patterns.json"
+ payload = load_json(path, {"site_id": site_id, "observations": [], "priors": {}})
+ payload.setdefault("site_id", site_id)
+ payload.setdefault("observations", [])
+ priors = payload.setdefault("priors", {})
+
+ key = f"{action_type or 'unknown'}::{primary_metric or 'unknown'}"
+ prior = priors.setdefault(
+ key,
+ {
+ "action_type": action_type or "unknown",
+ "primary_metric": primary_metric or "unknown",
+ "sample_size": 0,
+ "wins": 0,
+ "neutral": 0,
+ "losses": 0,
+ "inconclusive": 0,
+ "avg_primary_change": 0.0,
+ "confidence": 0.0,
+ "last_outcome": None,
+ "last_updated_at": None,
+ },
+ )
+
+ prior["sample_size"] += 1
+ if outcome == "win":
+ prior["wins"] += 1
+ elif outcome == "loss":
+ prior["losses"] += 1
+ elif outcome == "neutral":
+ prior["neutral"] += 1
+ else:
+ prior["inconclusive"] += 1
+
+ if primary_change is not None:
+ previous_count = prior["sample_size"] - 1
+ previous_avg = float(prior.get("avg_primary_change", 0.0))
+ prior["avg_primary_change"] = round(((previous_avg * previous_count) + float(primary_change)) / max(prior["sample_size"], 1), 4)
+ if confidence is not None:
+ previous_count = prior["sample_size"] - 1
+ previous_conf = float(prior.get("confidence", 0.0))
+ prior["confidence"] = round(((previous_conf * previous_count) + float(confidence)) / max(prior["sample_size"], 1), 4)
+
+ prior["last_outcome"] = outcome
+ prior["last_updated_at"] = now_iso()
+
+ payload["observations"].append(
+ {
+ "generated_at": now_iso(),
+ "action_type": action_type or "unknown",
+ "primary_metric": primary_metric or "unknown",
+ "outcome": outcome,
+ "primary_change": primary_change,
+ "confidence": confidence,
+ "notes": notes,
+ }
+ )
+ save_json(path, payload)
+ return payload
+
+
+def upsert_schedule_items(items: list[dict[str, Any]], root: Path | None = None) -> list[dict[str, Any]]:
+ root = bootstrap_workspace(root)
+ schedule_path = root / "schedule.json"
+ schedule = load_json(schedule_path, {"schema_version": "1", "upcoming": []})
+ upcoming = schedule.setdefault("upcoming", [])
+ written: list[dict[str, Any]] = []
+
+ for item in items:
+ item_id = item.get("item_id")
+ if not item_id:
+ continue
+ existing = next((entry for entry in upcoming if entry.get("item_id") == item_id), None)
+ if existing is None:
+ upcoming.append(item)
+ written.append(item)
+ else:
+ existing.update(item)
+ written.append(existing)
+
+ save_json(schedule_path, schedule)
+ return written
+
+
+def upsert_portfolio_site(
+ site_id: str,
+ *,
+ display_name: str | None = None,
+ business_weight: float = 1.0,
+ cadence: str = "weekly",
+ status: str = "active",
+ root: Path | None = None,
+) -> dict[str, Any]:
+ root = bootstrap_workspace(root)
+ portfolio_path = root / "portfolio.json"
+ portfolio = load_json(portfolio_path, {"schema_version": "1", "portfolio_id": "default", "sites": []})
+ sites = portfolio.setdefault("sites", [])
+
+ existing = next((item for item in sites if item.get("site_id") == site_id), None)
+ record = {
+ "site_id": site_id,
+ "display_name": display_name or site_id,
+ "business_weight": business_weight,
+ "cadence": cadence,
+ "status": status,
+ }
+
+ if existing is None:
+ sites.append(record)
+ else:
+ existing.update(record)
+ record = existing
+
+ save_json(portfolio_path, portfolio)
+ return record
diff --git a/openclaw/bin/score_feedback.py b/openclaw/bin/score_feedback.py
new file mode 100755
index 00000000..259d8835
--- /dev/null
+++ b/openclaw/bin/score_feedback.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Score a follow-up outcome from before/after metrics."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+DIRECTION_HIGHER = "higher_better"
+DIRECTION_LOWER = "lower_better"
+VALID_DIRECTIONS = {DIRECTION_HIGHER, DIRECTION_LOWER}
+
+
+def normalized_change(before: float, after: float, direction: str) -> float:
+ if before == 0:
+ if after == 0:
+ return 0.0
+ raw = 1.0
+ else:
+ raw = (after - before) / abs(before)
+ if direction == DIRECTION_LOWER:
+ return -raw
+ return raw
+
+
+def score_item(item: dict[str, Any]) -> dict[str, Any]:
+ baseline = item.get("baseline_metrics") or {}
+ observed = item.get("observed_metrics") or {}
+ primary_metric = item.get("primary_metric")
+ primary_direction = item.get("primary_direction", DIRECTION_HIGHER)
+ threshold = float(item.get("success_threshold_pct", 0.1))
+ guardrails = item.get("guardrail_metrics") or []
+
+ if primary_direction not in VALID_DIRECTIONS:
+ raise ValueError(f"invalid primary_direction: {primary_direction}")
+ if not primary_metric:
+ return {"outcome": "inconclusive", "reason": "missing primary_metric"}
+ if primary_metric not in baseline or primary_metric not in observed:
+ return {"outcome": "inconclusive", "reason": f"missing metric data for {primary_metric}"}
+
+ before = float(baseline[primary_metric])
+ after = float(observed[primary_metric])
+ primary_change = normalized_change(before, after, primary_direction)
+
+ metric_deltas: dict[str, dict[str, float | str]] = {}
+ for metric in set(baseline) & set(observed):
+ direction = DIRECTION_HIGHER
+ if metric == primary_metric:
+ direction = primary_direction
+ for guardrail in guardrails:
+ if guardrail.get("metric") == metric:
+ direction = guardrail.get("direction", direction)
+ break
+ metric_deltas[metric] = {
+ "before": float(baseline[metric]),
+ "after": float(observed[metric]),
+ "normalized_change": round(normalized_change(float(baseline[metric]), float(observed[metric]), direction), 4),
+ "direction": direction,
+ }
+
+ guardrail_failures = []
+ for guardrail in guardrails:
+ metric = guardrail.get("metric")
+ if metric not in baseline or metric not in observed:
+ continue
+ direction = guardrail.get("direction", DIRECTION_HIGHER)
+ max_worsen_pct = float(guardrail.get("max_worsen_pct", 0.05))
+ delta = normalized_change(float(baseline[metric]), float(observed[metric]), direction)
+ if delta < -max_worsen_pct:
+ guardrail_failures.append(
+ {
+ "metric": metric,
+ "normalized_change": round(delta, 4),
+ "max_worsen_pct": max_worsen_pct,
+ }
+ )
+
+ if guardrail_failures:
+ outcome = "loss"
+ reason = "guardrail failure"
+ elif primary_change >= threshold:
+ outcome = "win"
+ reason = "primary metric improved"
+ elif primary_change <= -threshold:
+ outcome = "loss"
+ reason = "primary metric worsened"
+ else:
+ outcome = "neutral"
+ reason = "change stayed within the neutral band"
+
+ confidence = min(0.95, round(0.55 + min(abs(primary_change), 1.0) * 0.35 + min(len(guardrails), 2) * 0.03, 2))
+
+ return {
+ "outcome": outcome,
+ "reason": reason,
+ "primary_metric": primary_metric,
+ "primary_direction": primary_direction,
+ "primary_change": round(primary_change, 4),
+ "success_threshold_pct": threshold,
+ "guardrail_failures": guardrail_failures,
+ "metric_deltas": metric_deltas,
+ "confidence": confidence,
+ }
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--item-file", required=True)
+ args = parser.parse_args(argv[1:])
+ item = json.loads(Path(args.item_file).read_text())
+ print(json.dumps(score_item(item), indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/site_id.py b/openclaw/bin/site_id.py
new file mode 100755
index 00000000..86dd99a9
--- /dev/null
+++ b/openclaw/bin/site_id.py
@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Normalize a URL or hostname into a stable site_id."""
+
+from __future__ import annotations
+
+import sys
+from urllib.parse import urlparse
+
+
+def normalize_site_id(value: str) -> str:
+ raw = (value or '').strip().lower()
+ if not raw:
+ raise ValueError('site input is required')
+ parsed = urlparse(raw if '://' in raw else f'https://{raw}')
+ host = (parsed.hostname or parsed.path or '').strip().lower()
+ if host.startswith('www.'):
+ host = host[4:]
+ if not host:
+ raise ValueError(f'could not derive site id from: {value!r}')
+ return host
+
+
+def main(argv: list[str]) -> int:
+ if len(argv) != 2:
+ print('usage: site_id.py <url-or-domain>', file=sys.stderr)
+ return 1
+ try:
+ print(normalize_site_id(argv[1]))
+ except ValueError as exc:
+ print(str(exc), file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == '__main__':
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/bin/weekly_review.py b/openclaw/bin/weekly_review.py
new file mode 100755
index 00000000..257e55a2
--- /dev/null
+++ b/openclaw/bin/weekly_review.py
@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""Run an automated weekly review for a site using GSC analysis output."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+ sys.path.insert(0, str(CURRENT_DIR))
+
+from persist_run import persist_payload
+from runtime import load_json, workspace_root
+from site_id import normalize_site_id
+
+ANALYZE_GSC = Path(__file__).resolve().parents[2] / "seo" / "seo-analysis" / "scripts" / "analyze_gsc.py"
+DEFAULT_PRIMARY_METRIC = "non_brand_clicks_28d"
+
+
+def future_iso(days: int) -> str:
+ return (datetime.now(timezone.utc) + timedelta(days=days)).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def metric_snapshot_from_analysis(data: dict[str, Any]) -> dict[str, float]:
+ period_days = int((data.get("period") or {}).get("days") or 28)
+ suffix = f"_{period_days}d"
+ summary = data.get("summary") or {}
+ branded_split = data.get("branded_split") or {}
+ branded = branded_split.get("branded") or {}
+ non_branded = branded_split.get("non_branded") or {}
+ snapshot: dict[str, float] = {
+ f"organic_clicks{suffix}": float(summary.get("clicks", 0)),
+ f"organic_impressions{suffix}": float(summary.get("impressions", 0)),
+ f"organic_ctr{suffix}": float(summary.get("ctr", 0)),
+ f"avg_position{suffix}": float(summary.get("position", 0)),
+ }
+ if branded_split:
+ snapshot[f"non_brand_clicks{suffix}"] = float(non_branded.get("clicks", 0))
+ snapshot[f"branded_clicks{suffix}"] = float(branded.get("clicks", 0))
+ snapshot[f"non_brand_impressions{suffix}"] = float(non_branded.get("impressions", 0))
+ snapshot[f"branded_impressions{suffix}"] = float(branded.get("impressions", 0))
+ return snapshot
+
+
+def learned_multiplier(learned: dict[str, Any], action_type: str, primary_metric: str) -> float:
+ priors = (learned or {}).get("priors") or {}
+ prior = priors.get(f"{action_type}::{primary_metric}")
+ if not prior:
+ return 1.0
+ sample_size = max(int(prior.get("sample_size", 0)), 1)
+ wins = int(prior.get("wins", 0))
+ losses = int(prior.get("losses", 0))
+ neutral = int(prior.get("neutral", 0))
+ avg_change = float(prior.get("avg_primary_change", 0.0))
+ confidence = float(prior.get("confidence", 0.0))
+ win_rate = wins / sample_size
+ loss_rate = losses / sample_size
+ neutral_rate = neutral / sample_size
+ raw = 1.0 + (win_rate * 0.25) - (loss_rate * 0.2) + (avg_change * 0.5) + (confidence * 0.1) + (neutral_rate * 0.02)
+ return max(0.7, min(1.5, round(raw, 3)))
+
+
+def make_issue(title: str, severity: str, confidence: float, evidence: list[str], action_type: str, target: str | None = None, base_priority: float = 0.5) -> dict[str, Any]:
+ issue = {
+ "title": title,
+ "severity": severity,
+ "confidence": round(confidence, 2),
+ "evidence": evidence,
+ "recommended_action_type": action_type,
+ "base_priority": round(base_priority, 3),
+ }
+ if target:
+ issue["target"] = target
+ return issue
+
+
+def derive_candidate_issues(data: dict[str, Any]) -> list[dict[str, Any]]:
+ issues: list[dict[str, Any]] = []
+ comparison = data.get("comparison") or {}
+ ctr_gaps = data.get("ctr_gaps_by_page") or []
+ cannibalization = data.get("cannibalization") or []
+ ctr_opps = data.get("ctr_opportunities") or []
+ declining_pages = comparison.get("declining_pages") or []
+ declining_queries = comparison.get("declining_queries") or []
+
+ if declining_pages:
+ page = declining_pages[0]
+ issues.append(
+ make_issue(
+ f"Traffic dropped on {page.get('page')}",
+ "critical",
+ 0.84,
+ [
+ f"Clicks changed {page.get('change_pct')}% vs prior period.",
+ f"Current clicks: {page.get('clicks_now')} | previous clicks: {page.get('clicks_prev')}",
+ ],
+ "page_improvement",
+ target=page.get("page"),
+ base_priority=0.95,
+ )
+ )
+
+ if ctr_gaps:
+ gap = ctr_gaps[0]
+ issues.append(
+ make_issue(
+ f"High-impression page with low CTR: {gap.get('page')}",
+ "warning",
+ 0.78,
+ [
+ f"{gap.get('impressions')} impressions with CTR {gap.get('ctr')}%.",
+ f"Average position {gap.get('position')} suggests snippet improvements may help.",
+ ],
+ "meta_tags",
+ target=gap.get("page"),
+ base_priority=0.8,
+ )
+ )
+
+ if cannibalization:
+ cannibal = cannibalization[0]
+ issues.append(
+ make_issue(
+ f"Cannibalization on query '{cannibal.get('query')}'",
+ "warning",
+ 0.73,
+ [
+ f"Winner page: {cannibal.get('winner_page')}",
+ f"Competing pages: {', '.join(cannibal.get('loser_pages', []))}",
+ ],
+ "internal_links",
+ target=cannibal.get("winner_page"),
+ base_priority=0.72,
+ )
+ )
+
+ if ctr_opps:
+ opp = ctr_opps[0]
+ issues.append(
+ make_issue(
+ f"Query-level CTR opportunity: {opp.get('query')}",
+ "info",
+ 0.68,
+ [
+ f"{opp.get('impressions')} impressions with CTR {opp.get('ctr')}%.",
+ f"Average position {opp.get('position')}.",
+ ],
+ "meta_tags",
+ base_priority=0.64,
+ )
+ )
+
+ if declining_queries:
+ query = declining_queries[0]
+ issues.append(
+ make_issue(
+ f"Query demand fell for '{query.get('query')}'",
+ "warning",
+ 0.66,
+ [
+ f"Clicks changed {query.get('change_pct')}% vs prior period.",
+ f"Current clicks: {query.get('clicks_now')} | previous clicks: {query.get('clicks_prev')}",
+ ],
+ "content_refresh",
+ base_priority=0.62,
+ )
+ )
+
+ return issues
+
+
+def apply_prioritization(candidates: list[dict[str, Any]], learned: dict[str, Any], primary_metric: str) -> list[dict[str, Any]]:
+ severity_weight = {"critical": 1.0, "warning": 0.75, "info": 0.45}
+ ranked = []
+ for item in candidates:
+ multiplier = learned_multiplier(learned, item["recommended_action_type"], primary_metric)
+ score = item.get("base_priority", 0.5) * severity_weight.get(item.get("severity", "warning"), 0.6) * multiplier * (0.6 + item.get("confidence", 0.5))
+ enriched = dict(item)
+ enriched["priority_score"] = round(score, 3)
+ enriched["learned_multiplier"] = multiplier
+ ranked.append(enriched)
+ ranked.sort(key=lambda issue: issue["priority_score"], reverse=True)
+ return ranked
+
+
+def build_payload(site_id: str, analysis: dict[str, Any], learned: dict[str, Any], goal: dict[str, Any] | None) -> dict[str, Any]:
+ metrics = metric_snapshot_from_analysis(analysis)
+ primary_metric = None
+ if goal and goal.get("primary_metric"):
+ primary_metric = goal["primary_metric"]
+ if not primary_metric:
+ primary_metric = DEFAULT_PRIMARY_METRIC if DEFAULT_PRIMARY_METRIC in metrics else next(iter(metrics.keys()), DEFAULT_PRIMARY_METRIC)
+
+ candidates = derive_candidate_issues(analysis)
+ ranked = apply_prioritization(candidates, learned, primary_metric)
+ top_issues = ranked[:3] if ranked else [
+ make_issue(
+ "No major issue surfaced from the automated weekly review.",
+ "info",
+ 0.5,
+ ["Use the canonical seo-analysis skill for deeper manual diagnosis if needed."],
+ "manual_review",
+ base_priority=0.3,
+ )
+ ]
+
+ summary = analysis.get("summary") or {}
+ non_brand_clicks = metrics.get(primary_metric)
+ action_entries = []
+ queue_items = []
+ for idx, issue in enumerate(top_issues, start=1):
+ action_id = f"weekly_action_{idx:02d}"
+ action_type = issue["recommended_action_type"]
+ action_entries.append(
+ {
+ "action_id": action_id,
+ "title": issue["title"],
+ "type": action_type,
+ "priority_score": issue["priority_score"],
+ "expected_impact": f"Address {action_type.replace('_', ' ')} opportunity surfaced in the weekly review.",
+ "requires_approval": action_type not in {"manual_review"},
+ "reversibility": "high",
+ "owner": "operator",
+ "target": issue.get("target"),
+ "learned_multiplier": issue.get("learned_multiplier", 1.0),
+ }
+ )
+ if idx == 1 and action_type != "manual_review":
+ queue_items.append(
+ {
+ "item_id": f"followup_{site_id}_{action_type}_{analysis['period']['days']}d",
+ "type": "feedback_check",
+ "status": "pending",
+ "due_at": future_iso(14),
+ "notes": f"Review the impact of the weekly action: {issue['title']}",
+ "action_type": action_type,
+ "target": issue.get("target"),
+ "primary_metric": primary_metric,
+ "primary_direction": "higher_better" if "position" not in primary_metric else "lower_better",
+ "success_threshold_pct": 0.1,
+ "baseline_metrics": metrics,
+ "guardrail_metrics": [],
+ }
+ )
+
+ return {
+ "trigger": {
+ "type": "weekly_review",
+ "notes": f"Automated weekly review for {site_id}.",
+ },
+ "state_snapshot": {
+ "site_id": site_id,
+ "summary": f"{summary.get('clicks', 0)} clicks, {summary.get('impressions', 0)} impressions, CTR {summary.get('ctr', 0)}%, position {summary.get('position', 0)}.",
+ "open_issues": [
+ {
+ "title": issue["title"],
+ "severity": issue["severity"],
+ "confidence": issue["confidence"],
+ }
+ for issue in top_issues
+ ],
+ "recent_actions": [],
+ "metrics": metrics,
+ },
+ "audit": {
+ "site_id": site_id,
+ "summary": f"Automated weekly review surfaced {len(top_issues)} prioritized issue(s).",
+ "issues": top_issues,
+ "metrics": metrics,
+ },
+ "action_plan": {
+ "site_id": site_id,
+ "goal_id": goal.get("goal_id") if goal else None,
+ "actions": action_entries,
+ },
+ "verification": {
+ "site_id": site_id,
+ "checks": [
+ {"name": "gsc analysis available", "status": "pass", "notes": "Weekly review generated from Search Console data."},
+ {"name": "action plan generated", "status": "pass", "notes": f"Primary metric for follow-up scoring: {primary_metric}."},
+ ],
+ "follow_up_due": None,
+ },
+ "queue_items": queue_items,
+ }
+
+
+def run_analysis(site_property: str, days: int, brand_terms: str | None) -> dict[str, Any]:
+ with tempfile.NamedTemporaryFile(prefix="toprank_weekly_review_", suffix=".json", delete=False) as tmp:
+ output_path = Path(tmp.name)
+ cmd = [sys.executable, str(ANALYZE_GSC), "--site", site_property, "--days", str(days), "--output", str(output_path)]
+ if brand_terms:
+ cmd.extend(["--brand-terms", brand_terms])
+ subprocess.run(cmd, check=True)
+ return json.loads(output_path.read_text())
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("site")
+ parser.add_argument("--analysis-file")
+ parser.add_argument("--gsc-property")
+ parser.add_argument("--brand-terms")
+ parser.add_argument("--days", type=int, default=28)
+ args = parser.parse_args(argv[1:])
+
+ root = workspace_root()
+ site_id = normalize_site_id(args.site)
+ site_root = root / "sites" / site_id
+ profile = load_json(site_root / "site-profile.json", {})
+ goals = load_json(site_root / "goals.json", {"active": [], "archived": []})
+ learned = load_json(site_root / "learned-patterns.json", {"site_id": site_id, "observations": [], "priors": {}})
+ active_goal = goals.get("active", [None])[0] if goals.get("active") else None
+
+ if args.analysis_file:
+ analysis = json.loads(Path(args.analysis_file).read_text())
+ else:
+ site_property = args.gsc_property or profile.get("gsc_property") or profile.get("canonical_url")
+ if not site_property:
+ raise SystemExit("No GSC property or canonical_url found for this site. Provide --gsc-property or update site-profile.json.")
+ brand_terms = args.brand_terms if args.brand_terms is not None else ",".join(profile.get("brand_terms", []))
+ analysis = run_analysis(site_property, args.days, brand_terms)
+
+ payload = build_payload(site_id, analysis, learned, active_goal)
+ result = persist_payload(args.site, payload, root=root)
+ result["primary_metric"] = payload["queue_items"][0]["primary_metric"] if payload.get("queue_items") else None
+ print(json.dumps(result, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main(sys.argv))
diff --git a/openclaw/install/bootstrap-site.sh b/openclaw/install/bootstrap-site.sh
new file mode 100755
index 00000000..24014566
--- /dev/null
+++ b/openclaw/install/bootstrap-site.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+if [ "$#" -ne 1 ]; then
+ echo "usage: $0 <url-or-domain>" >&2
+ exit 1
+fi
+python3 "$REPO_ROOT/openclaw/bin/bootstrap_site.py" "$1"
diff --git a/openclaw/install/install-launchd.sh b/openclaw/install/install-launchd.sh
new file mode 100755
index 00000000..752cb264
--- /dev/null
+++ b/openclaw/install/install-launchd.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+PYTHON_BIN="$(command -v python3)"
+LABEL="com.noworkstudio.toprank.openclaw.scheduler"
+INTERVAL=3600
+OUTPUT_DIR="${HOME}/Library/LaunchAgents"
+WRITE_ONLY=0
+RUNTIME_HOME="${TOPRANK_OPENCLAW_HOME:-$HOME/.toprank/openclaw}"
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --label)
+ LABEL="$2"
+ shift 2
+ ;;
+ --interval)
+ INTERVAL="$2"
+ shift 2
+ ;;
+ --output-dir)
+ OUTPUT_DIR="$2"
+ shift 2
+ ;;
+ --runtime-home)
+ RUNTIME_HOME="$2"
+ shift 2
+ ;;
+ --write-only)
+ WRITE_ONLY=1
+ shift
+ ;;
+ *)
+ echo "Unknown argument: $1" >&2
+ exit 1
+ ;;
+ esac
+done
+
+mkdir -p "$OUTPUT_DIR"
+PLIST_PATH="$OUTPUT_DIR/${LABEL}.plist"
+STDOUT_LOG="${RUNTIME_HOME}/logs/scheduler.stdout.log"
+STDERR_LOG="${RUNTIME_HOME}/logs/scheduler.stderr.log"
+mkdir -p "$(dirname "$STDOUT_LOG")"
+
+cat > "$PLIST_PATH" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+ <dict>
+ <key>Label</key>
+ <string>${LABEL}</string>
+ <key>ProgramArguments</key>
+ <array>
+ <string>${PYTHON_BIN}</string>
+ <string>${REPO_ROOT}/openclaw/bin/run_scheduler.py</string>
+ </array>
+ <key>EnvironmentVariables</key>
+ <dict>
+ <key>TOPRANK_OPENCLAW_HOME</key>
+ <string>${RUNTIME_HOME}</string>
+ </dict>
+ <key>StartInterval</key>
+ <integer>${INTERVAL}</integer>
+ <key>RunAtLoad</key>
+ <true/>
+ <key>StandardOutPath</key>
+ <string>${STDOUT_LOG}</string>
+ <key>StandardErrorPath</key>
+ <string>${STDERR_LOG}</string>
+ </dict>
+</plist>
+PLIST
+
+plutil -lint "$PLIST_PATH" >/dev/null
+
+echo "Wrote $PLIST_PATH"
+
+if [[ "$WRITE_ONLY" == "1" ]]; then
+ echo "Skipped launchctl load (--write-only)."
+ exit 0
+fi
+
+launchctl bootout "gui/${UID}" "$PLIST_PATH" >/dev/null 2>&1 || true
+launchctl bootstrap "gui/${UID}" "$PLIST_PATH"
+launchctl enable "gui/${UID}/${LABEL}" >/dev/null 2>&1 || true
+
+echo "Loaded ${LABEL}"
diff --git a/openclaw/install/install.sh b/openclaw/install/install.sh
new file mode 100755
index 00000000..525d9422
--- /dev/null
+++ b/openclaw/install/install.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+SKILL_TARGET_DIR="${OPENCLAW_SKILLS_DIR:-$HOME/.openclaw/skills}"
+
+mkdir -p "$SKILL_TARGET_DIR"
+python3 "$REPO_ROOT/openclaw/bin/bootstrap_workspace.py" >/dev/null
+
+for skill_dir in "$REPO_ROOT"/openclaw/skills/*; do
+ name="$(basename "$skill_dir")"
+ ln -sfn "$skill_dir" "$SKILL_TARGET_DIR/$name"
+ echo "linked $name -> $skill_dir"
+done
+
+echo
+echo "OpenClaw skills installed."
+echo "Runtime home: ${TOPRANK_OPENCLAW_HOME:-$HOME/.toprank/openclaw}"
+echo "Skills dir: $SKILL_TARGET_DIR"
diff --git a/openclaw/install/run-scheduler.sh b/openclaw/install/run-scheduler.sh
new file mode 100755
index 00000000..f05b6b11
--- /dev/null
+++ b/openclaw/install/run-scheduler.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+python3 "$REPO_ROOT/openclaw/bin/run_scheduler.py" "$@"
diff --git a/openclaw/install/toprank-openclaw.cron.example b/openclaw/install/toprank-openclaw.cron.example
new file mode 100644
index 00000000..79445197
--- /dev/null
+++ b/openclaw/install/toprank-openclaw.cron.example
@@ -0,0 +1,4 @@
+# Run the Toprank OpenClaw scheduler every hour.
+# Edit TOPRANK_OPENCLAW_HOME if you keep runtime state elsewhere.
+
+0 * * * * TOPRANK_OPENCLAW_HOME="$HOME/.toprank/openclaw" /usr/bin/env python3 /ABSOLUTE/PATH/TO/toprank/openclaw/bin/run_scheduler.py >> "$HOME/.toprank/openclaw/logs/cron.log" 2>&1
diff --git a/openclaw/shared/adapter-rules.md b/openclaw/shared/adapter-rules.md
new file mode 100644
index 00000000..fa631092
--- /dev/null
+++ b/openclaw/shared/adapter-rules.md
@@ -0,0 +1,79 @@
+# Adapter Rules
+
+These rules apply to every `openclaw/skills/*` wrapper.
+
+## 1. Preserve the canonical skills
+
+The existing Toprank skills under `seo/` and `google-ads/` remain the source of truth for domain expertise. Do not fork or silently rewrite them inside the OpenClaw surface.
+
+## 2. Treat OpenClaw as the operator layer
+
+The wrapper is responsible for:
+
+- selecting the right site,
+- loading persistent state,
+- deciding whether to run at the portfolio or site level,
+- writing structured artifacts,
+- applying policy gates,
+- scheduling follow-up work.
+
+## 3. Runtime home
+
+Use:
+
+```bash
+TOPRANK_OPENCLAW_HOME="${TOPRANK_OPENCLAW_HOME:-$HOME/.toprank/openclaw}"
+```
+
+Never write live operator state into this git repo.
+
+## 4. Site selection
+
+Every wrapper must resolve a `site_id` before acting. Use the helper:
+
+```bash
+python3 {baseDir}/../../bin/site_id.py https://example.com
+```
+
+If the user did not specify a site and multiple sites are active, either:
+
+- run `toprank-portfolio-review`, or
+- ask the user which site they mean.
+
+## 5. Required artifacts
+
+Every non-trivial run should write at least:
+
+- `audit.json`
+- `action-plan.json`
+- `verification.json`
+
+under:
+
+```text
+$TOPRANK_OPENCLAW_HOME/sites/<site_id>/runs/<timestamp>/
+```
+
+## 6. Approval boundaries
+
+Wrappers may automatically:
+
+- read site state,
+- run analysis,
+- update queue items,
+- generate proposals and drafts.
+
+Wrappers must ask first before:
+
+- editing website repo files,
+- writing to a CMS,
+- opening a PR,
+- publishing or deploying changes.
+
+## 7. Multi-site first
+
+Assume the operator owns multiple websites. State must stay isolated by site. Never mix artifacts from two sites in the same run folder.
+
+## 8. Feedback discipline
+
+If a wrapper proposes or drafts an action, it should also write a queue or schedule entry for a future outcome check when the action is time-based.
diff --git a/openclaw/shared/artifact-contract.md b/openclaw/shared/artifact-contract.md
new file mode 100644
index 00000000..7a6a0e58
--- /dev/null
+++ b/openclaw/shared/artifact-contract.md
@@ -0,0 +1,64 @@
+# Artifact Contract
+
+The OpenClaw adaptive layer is artifact-first. Runs should leave behind structured JSON that another agent turn can resume from.
+
+## Portfolio files
+
+- `portfolio.json` — registry of sites, business weights, cadence, and status
+- `schedule.json` — future recurring checks and follow-up tasks
+
+## Per-site files
+
+- `site-profile.json` — stable description of the website
+- `goals.json` — active and archived SEO goals
+- `latest-state.json` — compact snapshot used for fast re-entry
+- `learned-patterns.json` — site-local lessons with confidence
+
+## Per-run files
+
+Each run lives under:
+
+```text
+sites/<site_id>/runs/<timestamp>/
+```
+
+Recommended files:
+
+- `trigger.json`
+- `state-snapshot.json`
+- `audit.json`
+- `action-plan.json`
+- `proposal.json`
+- `patch-set.json`
+- `verification.json`
+- `feedback.json`
+- `learning-log.json`
+
+## Minimal required shape
+
+### audit.json
+Must answer:
+- what problem was found?
+- what evidence supports it?
+- how severe is it?
+
+### action-plan.json
+Must answer:
+- what should happen next?
+- what is the expected impact?
+- does it require approval?
+
+### verification.json
+Must answer:
+- what was checked?
+- what is safe/unsafe?
+- what follow-up is required?
+
+## Queue items
+
+Queue files under `sites/<site_id>/queue/` represent deferred work. Typical items:
+
+- weekly review
+- feedback check in 14 days
+- page improvement pending approval
+- revisit indexing issue after deploy
diff --git a/openclaw/shared/policy.md b/openclaw/shared/policy.md
new file mode 100644
index 00000000..6875ac30
--- /dev/null
+++ b/openclaw/shared/policy.md
@@ -0,0 +1,33 @@
+# Policy
+
+## Default operating mode
+
+Use **operator mode** by default:
+
+- generate drafts and proposals automatically,
+- ask before any external or production write.
+
+## Safety classes
+
+### Auto-safe
+- local audits
+- artifact writes
+- queue updates
+- proposal generation
+- internal prioritization
+
+### Approval-required
+- repo file edits for the target website
+- CMS writes
+- PR creation
+- content publication
+- production metadata changes
+
+### Blocked from auto
+- destructive mass changes
+- irreversible public actions
+- bulk redirects without review
+
+## Business weighting
+
+Use the `business_weight` in `portfolio.json` when ranking sites. Important sites should receive more attention, but active regressions may still preempt lower-value growth work.
diff --git a/openclaw/shared/triggers.md b/openclaw/shared/triggers.md
new file mode 100644
index 00000000..3368803e
--- /dev/null
+++ b/openclaw/shared/triggers.md
@@ -0,0 +1,21 @@
+# Triggers
+
+The adaptive layer can wake up from three kinds of triggers.
+
+## Scheduled
+- `daily_health_check`
+- `weekly_review`
+- `monthly_strategy_refresh`
+
+## Event-driven
+- `traffic_drop_detected`
+- `indexing_regression`
+- `post_deploy_check`
+- `important_page_changed`
+
+## Manual
+- `manual_request`
+- `improve_this_page`
+- `investigate_drop`
+
+For the MVP, scheduled and manual triggers are enough. Event-driven triggers can be represented as queue items or future integrations.
diff --git a/openclaw/skills/toprank-improve-page/SKILL.md b/openclaw/skills/toprank-improve-page/SKILL.md
new file mode 100644
index 00000000..5a598c22
--- /dev/null
+++ b/openclaw/skills/toprank-improve-page/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: toprank-improve-page
+description: Improve one URL inside a registered site by producing a focused diagnosis, proposal, and verification artifact.
+metadata: { "openclaw": { "emoji": "🧱", "homepage": "https://github.com/nowork-studio/toprank", "requires": { "bins": ["python3"] } } }
+---
+
+# Toprank Improve Page
+
+1. Read `{baseDir}/../../shared/adapter-rules.md`.
+2. Read `{baseDir}/../../shared/artifact-contract.md`.
+3. Read `{baseDir}/../../shared/policy.md`.
+4. Load the site work folder, then focus on the target URL and choose the canonical page-level skills that best fit the issue.
+5. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-page/SKILL.md`.
+6. Convert the page diagnosis into a structured proposal using `python3 {baseDir}/../../bin/improve_page.py <site> --url <url> --issue-summary "..." --proposal-summary "..."`.
+7. If you also have file-level edits to suggest, include `--patch-path` and `--patch-summary` so a `patch-set.json` artifact is written.
+8. Verify that the run wrote `proposal.json` and `verification.json`, plus `patch-set.json` when relevant.
+9. If the next action requires editing a site repo, CMS, publishing content, or opening a PR, stop and ask for approval before doing it.
+
+## Wrapper job
+
+Use this when the operator wants a single page improved.
+
+Typical combinations:
+- `seo-page` for diagnosis,
+- `meta-tags-optimizer` for title/meta candidates,
+- `schema-markup-generator` for structured data proposals,
+- `content-writer` for a content brief or rewrite draft.
+
+Write at least `proposal.json` and `verification.json`. If you generate patches or file-level changes, also write `patch-set.json`.
diff --git a/openclaw/skills/toprank-investigate-drop/SKILL.md b/openclaw/skills/toprank-investigate-drop/SKILL.md
new file mode 100644
index 00000000..d1f5f0e6
--- /dev/null
+++ b/openclaw/skills/toprank-investigate-drop/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: toprank-investigate-drop
+description: Investigate an organic traffic drop for one registered site and produce a ranked recovery plan with artifacts.
+metadata: { "openclaw": { "emoji": "🚨", "homepage": "https://github.com/nowork-studio/toprank", "requires": { "bins": ["python3"] } } }
+---
+
+# Toprank Investigate Drop
+
+1. Read `{baseDir}/../../shared/adapter-rules.md`.
+2. Read `{baseDir}/../../shared/artifact-contract.md`.
+3. Read `{baseDir}/../../shared/policy.md`.
+4. Resolve the target site, load prior audits and latest state, then compare the current problem against the site's recent history before choosing the next recovery action.
+5. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md`.
+6. Convert the investigation into a structured recovery run using `python3 {baseDir}/../../bin/investigate_drop.py <site> --summary "..." --likely-cause "..."`.
+7. If the drop points to a specific URL, include `--target-url <url>` so the adaptive layer queues a follow-up page-improvement task.
+8. Verify that the run wrote `audit.json`, `action-plan.json`, and `verification.json`, plus any follow-up queue items.
+9. If the next action requires editing a site repo, CMS, publishing content, or opening a PR, stop and ask for approval before doing it.
+
+## Wrapper job
+
+Use this when the operator reports a traffic loss or ranking decline.
+
+Your job:
+- identify likely causes,
+- separate technical issues from content/intent issues,
+- rank the fastest and safest recovery actions,
+- write `audit.json`, `action-plan.json`, and `verification.json`.
+
+If the drop investigation suggests a page-level fix, queue a follow-up `toprank-improve-page` task.
diff --git a/openclaw/skills/toprank-portfolio-review/SKILL.md b/openclaw/skills/toprank-portfolio-review/SKILL.md
new file mode 100644
index 00000000..024def9c
--- /dev/null
+++ b/openclaw/skills/toprank-portfolio-review/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: toprank-portfolio-review
+description: Review all registered websites in the Toprank OpenClaw portfolio and rank which site deserves attention next.
+metadata: { "openclaw": { "emoji": "📊", "homepage": "https://github.com/nowork-studio/toprank", "requires": { "bins": ["python3"] } } }
+---
+
+# Toprank Portfolio Review
+
+1. Read `{baseDir}/../../shared/adapter-rules.md`.
+2. Read `{baseDir}/../../shared/artifact-contract.md`.
+3. Read `{baseDir}/../../shared/policy.md`.
+4. Load `portfolio.json` and each active site's `latest-state.json` from the OpenClaw runtime home.
+5. Run `python3 {baseDir}/../../bin/portfolio_review.py` to get the current ranked site list and write a portfolio review artifact.
+6. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md` only for the top-ranked site(s) if you need deeper analysis.
+7. If the top site needs deeper work, either launch `toprank-weekly-review` for that site or ask the operator which site to dive into.
+
+## Wrapper job
+
+Use this when the operator owns multiple websites and needs portfolio-level prioritization.
+
+Your job:
+- scan all active sites,
+- rank them by urgency and upside,
+- name the one or two sites that deserve attention now,
+- create queue items or follow-up tasks for deeper site reviews.
+
+Use business weight, visible regressions, and opportunity size when ranking the sites.
diff --git a/openclaw/skills/toprank-site-onboard/SKILL.md b/openclaw/skills/toprank-site-onboard/SKILL.md
new file mode 100644
index 00000000..9c0560ca
--- /dev/null
+++ b/openclaw/skills/toprank-site-onboard/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: toprank-site-onboard
+description: Register a website in Toprank's OpenClaw adaptive layer and initialize its per-site work folder.
+metadata: { "openclaw": { "emoji": "🧭", "homepage": "https://github.com/nowork-studio/toprank", "requires": { "bins": ["python3"] } } }
+---
+
+# Toprank Site Onboard
+
+1. Read `{baseDir}/../../shared/adapter-rules.md`.
+2. Read `{baseDir}/../../shared/artifact-contract.md`.
+3. Read `{baseDir}/../../shared/policy.md`.
+4. Gather the site URL, display name, brand terms, business weight, cadence, and one initial SEO goal.
+5. Run:
+ - `python3 {baseDir}/../../bin/bootstrap_workspace.py`
+ - `python3 {baseDir}/../../bin/onboard_site.py <url> --display-name "..." --brand-terms "A,B" --business-weight 1.0 --cadence weekly --goal-type grow_non_brand_clicks --primary-metric non_brand_clicks_28d`
+6. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md` only if you need deeper site understanding during onboarding.
+7. Confirm that `site-profile.json`, `goals.json`, and `portfolio.json` were updated.
+
+## Wrapper job
+
+Use this when the operator is adding a new website.
+
+Your job:
+- create or update the portfolio registry,
+- initialize the site work folder,
+- capture brand terms, business weight, cadence, and one initial SEO goal,
+- write `site-profile.json` and `goals.json`.
+
+If the user already has multiple sites, keep this site's state isolated under its own folder.
diff --git a/openclaw/skills/toprank-weekly-review/SKILL.md b/openclaw/skills/toprank-weekly-review/SKILL.md
new file mode 100644
index 00000000..60ea2e9a
--- /dev/null
+++ b/openclaw/skills/toprank-weekly-review/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: toprank-weekly-review
+description: Run a weekly SEO review for one registered website, write audit artifacts, and choose the next best safe action.
+metadata: { "openclaw": { "emoji": "📈", "homepage": "https://github.com/nowork-studio/toprank", "requires": { "bins": ["python3"] } } }
+---
+
+# Toprank Weekly Review
+
+1. Read `{baseDir}/../../shared/adapter-rules.md`.
+2. Read `{baseDir}/../../shared/artifact-contract.md`.
+3. Read `{baseDir}/../../shared/policy.md`.
+4. Resolve the target `site_id`; if no site was specified and multiple sites are active, run portfolio review first or ask the user which site to review.
+5. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md`.
+6. Prefer the automated runner:
+ - `python3 {baseDir}/../../bin/weekly_review.py <site_id-or-url>`
+ - add `--gsc-property` if the site profile does not already contain one
+ - add `--analysis-file` when testing against a saved GSC analysis JSON fixture
+7. The runner will generate and persist the review artifacts automatically.
+8. Verify that the run wrote `audit.json`, `action-plan.json`, and `verification.json`, refreshed `latest-state.json`, and created a follow-up queue item.
+9. If the next action requires editing a site repo, CMS, publishing content, or opening a PR, stop and ask for approval before doing it.
+
+## Wrapper job
+
+Use this as the default weekly loop for a single site.
+
+Your job:
+- load the site profile, goals, and latest state,
+- run a fresh review using the canonical SEO analysis skill,
+- identify the top three issues,
+- prioritize exactly one next best action,
+- write `audit.json`, `action-plan.json`, and `verification.json`.
+
+When possible, also create a queue item for a 14-day or 28-day follow-up check.
diff --git a/openclaw/workspace-template/README.md b/openclaw/workspace-template/README.md
new file mode 100644
index 00000000..783dd818
--- /dev/null
+++ b/openclaw/workspace-template/README.md
@@ -0,0 +1,5 @@
+# Workspace Template
+
+This directory documents the runtime layout created under `~/.toprank/openclaw`.
+
+The files here are templates and examples only. Do not store live operator data in the git repo.
diff --git a/openclaw/workspace-template/portfolio.json b/openclaw/workspace-template/portfolio.json
new file mode 100644
index 00000000..6938c73d
--- /dev/null
+++ b/openclaw/workspace-template/portfolio.json
@@ -0,0 +1,5 @@
+{
+ "schema_version": "1",
+ "portfolio_id": "default",
+ "sites": []
+}
diff --git a/openclaw/workspace-template/schedule.json b/openclaw/workspace-template/schedule.json
new file mode 100644
index 00000000..34003973
--- /dev/null
+++ b/openclaw/workspace-template/schedule.json
@@ -0,0 +1,4 @@
+{
+ "schema_version": "1",
+ "upcoming": []
+}
diff --git a/test/openclaw/test_launchd_install.py b/test/openclaw/test_launchd_install.py
new file mode 100644
index 00000000..4d7f53f2
--- /dev/null
+++ b/test/openclaw/test_launchd_install.py
@@ -0,0 +1,24 @@
+import os
+import subprocess
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_install_launchd_script_writes_valid_plist(tmp_path):
+ output_dir = tmp_path / 'LaunchAgents'
+ runtime_home = tmp_path / 'runtime'
+ script = REPO_ROOT / 'openclaw' / 'install' / 'install-launchd.sh'
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(runtime_home)
+ subprocess.run(
+ [str(script), '--write-only', '--output-dir', str(output_dir), '--interval', '1800'],
+ check=True,
+ env=env,
+ )
+ plists = list(output_dir.glob('*.plist'))
+ assert len(plists) == 1
+ contents = plists[0].read_text()
+ assert 'run_scheduler.py' in contents
+ assert '1800' in contents
diff --git a/test/openclaw/test_openclaw_mvp.py b/test/openclaw/test_openclaw_mvp.py
new file mode 100644
index 00000000..7fdec928
--- /dev/null
+++ b/test/openclaw/test_openclaw_mvp.py
@@ -0,0 +1,478 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_all_schema_files_are_valid_json():
+ schema_dir = REPO_ROOT / 'openclaw' / 'artifacts' / 'schemas'
+ for path in schema_dir.glob('*.json'):
+ data = json.loads(path.read_text())
+ assert data['type'] == 'object'
+ assert '$schema' in data
+
+
+def test_example_action_plan_has_expected_shape():
+ path = REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'action-plan.json'
+ data = json.loads(path.read_text())
+ assert data['site_id'] == 'example.com'
+ assert data['actions']
+ assert data['actions'][0]['requires_approval'] is True
+
+
+def test_bootstrap_workspace_and_site(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_workspace.py')], check=True, env=env)
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'https://Example.com'], check=True, env=env)
+ site_root = tmp_path / 'runtime' / 'sites' / 'example.com'
+ assert (tmp_path / 'runtime' / 'portfolio.json').exists()
+ assert (site_root / 'site-profile.json').exists()
+ assert (site_root / 'queue').is_dir()
+ profile = json.loads((site_root / 'site-profile.json').read_text())
+ assert profile['site_id'] == 'example.com'
+
+
+def test_onboard_site_updates_portfolio_and_goal(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'onboard_site.py'),
+ 'https://example.com',
+ '--display-name',
+ 'Example Site',
+ '--brand-terms',
+ 'Example,Example Site',
+ '--business-weight',
+ '0.8',
+ '--cadence',
+ 'weekly',
+ '--goal-type',
+ 'grow_non_brand_clicks',
+ '--primary-metric',
+ 'non_brand_clicks_28d',
+ ],
+ check=True,
+ env=env,
+ )
+ portfolio = json.loads((tmp_path / 'runtime' / 'portfolio.json').read_text())
+ assert portfolio['sites'][0]['site_id'] == 'example.com'
+ assert portfolio['sites'][0]['business_weight'] == 0.8
+ site_root = tmp_path / 'runtime' / 'sites' / 'example.com'
+ profile = json.loads((site_root / 'site-profile.json').read_text())
+ assert profile['display_name'] == 'Example Site'
+ assert profile['brand_terms'] == ['Example', 'Example Site']
+ goals = json.loads((site_root / 'goals.json').read_text())
+ assert goals['active']
+ assert goals['active'][0]['primary_metric'] == 'non_brand_clicks_28d'
+
+
+def test_persist_run_writes_artifacts_and_queue(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ payload_path = tmp_path / 'payload.json'
+ payload_path.write_text((REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'weekly-review-payload.json').read_text())
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'persist_run.py'),
+ 'example.com',
+ '--payload-file',
+ str(payload_path),
+ ],
+ check=True,
+ env=env,
+ )
+ runs_dir = tmp_path / 'runtime' / 'sites' / 'example.com' / 'runs'
+ run_dirs = [path for path in runs_dir.iterdir() if path.is_dir()]
+ assert len(run_dirs) == 1
+ run_dir = run_dirs[0]
+ assert (run_dir / 'audit.json').exists()
+ assert (run_dir / 'action-plan.json').exists()
+ assert (run_dir / 'verification.json').exists()
+ latest = json.loads((tmp_path / 'runtime' / 'sites' / 'example.com' / 'latest-state.json').read_text())
+ assert 'Homepage CTR' in latest['summary']
+ queue_dir = tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue'
+ queue_files = list(queue_dir.glob('*.json'))
+ assert len(queue_files) == 1
+ queue_item = json.loads(queue_files[0].read_text())
+ assert queue_item['type'] == 'feedback_check'
+ assert queue_item['baseline_metrics']['organic_clicks_28d'] == 100
+ assert queue_item['primary_metric'] == 'non_brand_clicks_28d'
+ assert queue_item['action_type'] == 'meta_tags'
+ schedule = json.loads((tmp_path / 'runtime' / 'schedule.json').read_text())
+ assert schedule['upcoming']
+ assert schedule['upcoming'][0]['item_id'] == queue_item['item_id']
+
+
+def test_improve_page_persists_proposal_and_patch_set(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'improve_page.py'),
+ 'example.com',
+ '--url',
+ 'https://example.com/services/dog-daycare',
+ '--issue-summary',
+ 'Service page CTR is low and schema is missing.',
+ '--proposal-summary',
+ 'Draft new title/meta candidates and add LocalBusiness schema.',
+ '--patch-path',
+ 'pages/services/dog-daycare.tsx',
+ '--patch-summary',
+ 'Add schema and update metadata fields.',
+ ],
+ check=True,
+ env=env,
+ )
+ run_dirs = list((tmp_path / 'runtime' / 'sites' / 'example.com' / 'runs').iterdir())
+ assert len(run_dirs) == 1
+ run_dir = run_dirs[0]
+ assert (run_dir / 'proposal.json').exists()
+ assert (run_dir / 'patch-set.json').exists()
+ proposal = json.loads((run_dir / 'proposal.json').read_text())
+ assert proposal['target'] == 'https://example.com/services/dog-daycare'
+ patch_set = json.loads((run_dir / 'patch-set.json').read_text())
+ assert patch_set['patches'][0]['path'] == 'pages/services/dog-daycare.tsx'
+
+
+def test_investigate_drop_creates_recovery_plan_and_followups(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'investigate_drop.py'),
+ 'example.com',
+ '--summary',
+ 'Organic clicks fell sharply on the primary service cluster.',
+ '--likely-cause',
+ 'A service page may have fallen out of the index.',
+ '--likely-cause',
+ 'Homepage CTR declined after a copy update.',
+ '--target-url',
+ 'https://example.com/services/dog-daycare',
+ ],
+ check=True,
+ env=env,
+ )
+ run_dirs = list((tmp_path / 'runtime' / 'sites' / 'example.com' / 'runs').iterdir())
+ assert len(run_dirs) == 1
+ run_dir = run_dirs[0]
+ audit = json.loads((run_dir / 'audit.json').read_text())
+ assert len(audit['issues']) == 2
+ queue_files = list((tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue').glob('*.json'))
+ queue_types = {json.loads(path.read_text())['type'] for path in queue_files}
+ assert 'feedback_check' in queue_types
+ assert 'improve_page' in queue_types
+
+
+def test_followups_due_lists_due_items(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ payload_path = tmp_path / 'payload.json'
+ payload = json.loads((REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'weekly-review-payload.json').read_text())
+ payload['queue_items'][0]['due_at'] = '2026-04-01T00:00:00Z'
+ payload_path.write_text(json.dumps(payload, indent=2) + '\n')
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'persist_run.py'),
+ 'example.com',
+ '--payload-file',
+ str(payload_path),
+ ],
+ check=True,
+ env=env,
+ )
+ result = subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'followups_due.py'),
+ '--as-of',
+ '2026-04-15T00:00:00Z',
+ ],
+ check=True,
+ env=env,
+ capture_output=True,
+ text=True,
+ )
+ data = json.loads(result.stdout)
+ assert data['count'] == 1
+ assert data['items'][0]['type'] == 'feedback_check'
+
+
+def test_hydrate_followup_gsc_updates_observed_metrics(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ payload_path = tmp_path / 'payload.json'
+ payload = json.loads((REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'weekly-review-payload.json').read_text())
+ payload_path.write_text(json.dumps(payload, indent=2) + '\n')
+ subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'persist_run.py'), 'example.com', '--payload-file', str(payload_path)],
+ check=True,
+ env=env,
+ )
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'hydrate_followup_gsc.py'),
+ 'example.com',
+ 'followup_example_homepage_ctr_14d',
+ '--analysis-file',
+ str(REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'gsc-analysis-sample.json'),
+ ],
+ check=True,
+ env=env,
+ )
+ queue_path = tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue' / 'followup_example_homepage_ctr_14d.json'
+ queue_item = json.loads(queue_path.read_text())
+ assert queue_item['observed_metrics']['non_brand_clicks_28d'] == 110.0
+ assert queue_item['observed_metrics']['organic_clicks_28d'] == 150.0
+
+
+def test_record_followup_metrics_and_score_script(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ payload_path = tmp_path / 'payload.json'
+ payload = json.loads((REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'weekly-review-payload.json').read_text())
+ payload['queue_items'][0]['due_at'] = '2026-04-01T00:00:00Z'
+ payload['queue_items'][0]['baseline_metrics'] = {'organic_clicks_28d': 100, 'conversions_28d': 10}
+ payload['queue_items'][0]['primary_metric'] = 'organic_clicks_28d'
+ payload['queue_items'][0]['success_threshold_pct'] = 0.1
+ payload['queue_items'][0]['guardrail_metrics'] = [{'metric': 'conversions_28d', 'direction': 'higher_better', 'max_worsen_pct': 0.05}]
+ payload_path.write_text(json.dumps(payload, indent=2) + '\n')
+ subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'persist_run.py'), 'example.com', '--payload-file', str(payload_path)],
+ check=True,
+ env=env,
+ )
+ item_id = payload['queue_items'][0]['item_id']
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'record_followup_metrics.py'),
+ 'example.com',
+ item_id,
+ '--observed-metric',
+ 'organic_clicks_28d=125',
+ '--observed-metric',
+ 'conversions_28d=11',
+ ],
+ check=True,
+ env=env,
+ )
+ queue_path = tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue' / f'{item_id}.json'
+ score_result = subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'score_feedback.py'), '--item-file', str(queue_path)],
+ check=True,
+ env=env,
+ capture_output=True,
+ text=True,
+ )
+ score = json.loads(score_result.stdout)
+ assert score['outcome'] == 'win'
+ assert score['primary_metric'] == 'organic_clicks_28d'
+
+
+def test_run_scheduler_processes_due_feedback_checks(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ payload_path = tmp_path / 'payload.json'
+ payload = json.loads((REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'weekly-review-payload.json').read_text())
+ payload['queue_items'][0]['due_at'] = '2026-04-01T00:00:00Z'
+ payload['queue_items'][0]['baseline_metrics'] = {'organic_clicks_28d': 100}
+ payload['queue_items'][0]['observed_metrics'] = {'organic_clicks_28d': 120}
+ payload['queue_items'][0]['primary_metric'] = 'organic_clicks_28d'
+ payload['queue_items'][0]['success_threshold_pct'] = 0.1
+ payload_path.write_text(json.dumps(payload, indent=2) + '\n')
+ subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'persist_run.py'), 'example.com', '--payload-file', str(payload_path)],
+ check=True,
+ env=env,
+ )
+ result = subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'run_scheduler.py'), '--as-of', '2026-04-15T00:00:00Z'],
+ check=True,
+ env=env,
+ capture_output=True,
+ text=True,
+ )
+ data = json.loads(result.stdout)
+ assert len(data['processed']) == 1
+ schedule = json.loads((tmp_path / 'runtime' / 'schedule.json').read_text())
+ assert schedule['upcoming'][0]['status'] == 'processed'
+ feedback_dir = tmp_path / 'runtime' / 'sites' / 'example.com' / 'feedback'
+ feedback_files = list(feedback_dir.glob('*.json'))
+ assert len(feedback_files) == 1
+ feedback = json.loads(feedback_files[0].read_text())
+ assert feedback['status'] == 'win'
+ learned = json.loads((tmp_path / 'runtime' / 'sites' / 'example.com' / 'learned-patterns.json').read_text())
+ assert learned['priors']['meta_tags::organic_clicks_28d']['wins'] == 1
+
+
+def test_run_scheduler_surfaces_manual_attention_items(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run([sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'bootstrap_site.py'), 'example.com'], check=True, env=env)
+ schedule_path = tmp_path / 'runtime' / 'schedule.json'
+ schedule = {'schema_version': '1', 'upcoming': [{'item_id': 'manual_001', 'site_id': 'example.com', 'type': 'improve_page', 'status': 'pending', 'due_at': '2026-04-01T00:00:00Z'}]}
+ schedule_path.write_text(json.dumps(schedule, indent=2) + '\n')
+ queue_path = tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue' / 'manual_001.json'
+ queue_path.write_text(json.dumps(schedule['upcoming'][0], indent=2) + '\n')
+ result = subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'run_scheduler.py'), '--as-of', '2026-04-15T00:00:00Z'],
+ check=True,
+ env=env,
+ capture_output=True,
+ text=True,
+ )
+ data = json.loads(result.stdout)
+ assert len(data['manual_attention']) == 1
+ updated_schedule = json.loads(schedule_path.read_text())
+ assert updated_schedule['upcoming'][0]['status'] == 'ready_for_attention'
+
+
+def test_weekly_review_uses_learned_priors_and_seeds_followup(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'onboard_site.py'),
+ 'https://example.com',
+ '--display-name',
+ 'Example',
+ '--goal-type',
+ 'grow_non_brand_clicks',
+ '--primary-metric',
+ 'non_brand_clicks_28d',
+ ],
+ check=True,
+ env=env,
+ )
+ learned_path = tmp_path / 'runtime' / 'sites' / 'example.com' / 'learned-patterns.json'
+ learned_path.write_text(json.dumps({
+ 'site_id': 'example.com',
+ 'observations': [],
+ 'priors': {
+ 'meta_tags::non_brand_clicks_28d': {
+ 'action_type': 'meta_tags',
+ 'primary_metric': 'non_brand_clicks_28d',
+ 'sample_size': 3,
+ 'wins': 2,
+ 'neutral': 1,
+ 'losses': 0,
+ 'inconclusive': 0,
+ 'avg_primary_change': 0.18,
+ 'confidence': 0.72,
+ 'last_outcome': 'win',
+ 'last_updated_at': '2026-04-01T00:00:00Z'
+ },
+ 'page_improvement::non_brand_clicks_28d': {
+ 'action_type': 'page_improvement',
+ 'primary_metric': 'non_brand_clicks_28d',
+ 'sample_size': 2,
+ 'wins': 0,
+ 'neutral': 0,
+ 'losses': 2,
+ 'inconclusive': 0,
+ 'avg_primary_change': -0.15,
+ 'confidence': 0.8,
+ 'last_outcome': 'loss',
+ 'last_updated_at': '2026-04-01T00:00:00Z'
+ }
+ }
+ }, indent=2) + '\n')
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'weekly_review.py'),
+ 'example.com',
+ '--analysis-file',
+ str(REPO_ROOT / 'openclaw' / 'artifacts' / 'examples' / 'gsc-analysis-sample.json'),
+ ],
+ check=True,
+ env=env,
+ )
+ run_dirs = sorted((tmp_path / 'runtime' / 'sites' / 'example.com' / 'runs').iterdir())
+ run_dir = run_dirs[-1]
+ action_plan = json.loads((run_dir / 'action-plan.json').read_text())
+ assert action_plan['actions'][0]['type'] == 'meta_tags'
+ queue_files = list((tmp_path / 'runtime' / 'sites' / 'example.com' / 'queue').glob('*.json'))
+ assert len(queue_files) == 1
+ queue_item = json.loads(queue_files[0].read_text())
+ assert queue_item['baseline_metrics']['non_brand_clicks_28d'] == 110.0
+ assert queue_item['primary_metric'] == 'non_brand_clicks_28d'
+ assert queue_item['action_type'] == 'meta_tags'
+
+
+def test_portfolio_review_ranks_sites(tmp_path):
+ env = os.environ.copy()
+ env['TOPRANK_OPENCLAW_HOME'] = str(tmp_path / 'runtime')
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'onboard_site.py'),
+ 'https://alpha.example',
+ '--display-name',
+ 'Alpha',
+ '--business-weight',
+ '1.0',
+ ],
+ check=True,
+ env=env,
+ )
+ subprocess.run(
+ [
+ sys.executable,
+ str(REPO_ROOT / 'openclaw' / 'bin' / 'onboard_site.py'),
+ 'https://beta.example',
+ '--display-name',
+ 'Beta',
+ '--business-weight',
+ '0.5',
+ ],
+ check=True,
+ env=env,
+ )
+ latest_alpha = tmp_path / 'runtime' / 'sites' / 'alpha.example' / 'latest-state.json'
+ latest_beta = tmp_path / 'runtime' / 'sites' / 'beta.example' / 'latest-state.json'
+ latest_alpha.write_text(json.dumps({
+ 'site_id': 'alpha.example',
+ 'summary': 'Alpha has a critical indexing regression.',
+ 'open_issues': [{'title': 'Critical indexing regression', 'severity': 'critical'}],
+ 'recent_actions': []
+ }, indent=2) + '\n')
+ latest_beta.write_text(json.dumps({
+ 'site_id': 'beta.example',
+ 'summary': 'Beta is stable.',
+ 'open_issues': [],
+ 'recent_actions': []
+ }, indent=2) + '\n')
+ result = subprocess.run(
+ [sys.executable, str(REPO_ROOT / 'openclaw' / 'bin' / 'portfolio_review.py')],
+ check=True,
+ env=env,
+ capture_output=True,
+ text=True,
+ )
+ data = json.loads(result.stdout)
+ assert data['recommended_focus_site'] == 'alpha.example'
+ review_dir = tmp_path / 'runtime' / 'portfolio-reviews'
+ assert any(review_dir.glob('*.json'))