Open-source SEO, GEO, and marketing skills for AI agents.
add OpenClaw adaptive SEO loop MVP
Tongde5b119ae660
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Changeddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.mdindex 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└── VERSIONdiff --git a/docs/openclaw-adaptive-layer.md b/docs/openclaw-adaptive-layer.mdnew file mode 100644index 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.mdnew file mode 100644index 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+```++++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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.webpnew file mode 100644index 00000000..28cc4b78Binary files /dev/null and b/openclaw/artifacts/visuals/continuous-seo-improvement-loop.webp differdiff --git a/openclaw/bin/bootstrap_site.py b/openclaw/bin/bootstrap_site.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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 recorddiff --git a/openclaw/bin/score_feedback.py b/openclaw/bin/score_feedback.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.shnew file mode 100755index 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.examplenew file mode 100644index 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>&1diff --git a/openclaw/shared/adapter-rules.md b/openclaw/shared/adapter-rules.mdnew file mode 100644index 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.mdnew file mode 100644index 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 deploydiff --git a/openclaw/shared/policy.md b/openclaw/shared/policy.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.pynew file mode 100644index 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 contentsdiff --git a/test/openclaw/test_openclaw_mvp.py b/test/openclaw/test_openclaw_mvp.pynew file mode 100644index 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'))