@seoagent-official/seoagent 1.93.0 → 1.94.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.93.0",
+  "version": "1.94.0",
   "description": "The persistent AI SEO agent for Claude Code. Audits, keyword strategy, briefs, articles, real product screenshots from your repo, and the autopilot loop (cloud detects → CLI executes → ack closes) — other SEO tools write the prompt, SEOAgent runs it.",
   "type": "module",
   "bin": {

package/skills/references/audit-checks.md

@@ -343,7 +343,7 @@ The evidence-citation contract is enforced by the CLI, not just by the prompt
 1. Every `seoagent sync` (including the PostToolUse hook that fires after each file write) runs a verify-recs pass first, so false claims in `.seoagent/**/*.md` are corrected as the files are written — when the hook output reports a `verify-recs: corrected …` line, treat it as authoritative and carry the correction into your response.
 2. At the end of the session — after writing your outputs, BEFORE composing the final summary — run `seoagent verify-recs` yourself (pass any work-log/summary files you wrote outside `.seoagent/` as arguments), because files outside `.seoagent/` are only checked when you pass them. This is still the MANDATORY final step of any audit/optimization session.
 
-**If `evidence.md` is a SOURCE RENDER (undesignated local dev-server crawl), verify-recs cannot verify live-state claims — it will say so; re-crawl with `--url <live origin>` before finalizing any live-state summary.** It re-checks every authored `.seoagent/**/*.md` against `evidence.md` and REWRITES, in place with a `CORRECTION (verify-recs)` annotation, any "added X / there was no X / X was missing" claim about a head-level entity (title, meta description, canonical, Open Graph, twitter:card, or a JSON-LD `@type` such as `Organization`/`SoftwareApplication`/`WebSite`) that the evidence shows the live page ALREADY serves. **Reflect every correction it reports in your final message** — never let a corrected claim survive into the summary (use `--json` to branch on the result programmatically). The deterministic way to do that: build the final message from `seoagent summary` (see `references/session-protocol.md`), which quotes the corrected on-disk state — including every CORRECTION line — instead of trusting your memory of what you found. It never touches `evidence.md`, generated projections (`pages.md`/`keywords.md`), the inbox, or anything under `.claude/`, and it always exits 0 — a correction is the check working, not an error.
+**If `evidence.md` is a SOURCE RENDER (undesignated local dev-server crawl), verify-recs cannot verify live-state claims — it will say so; re-crawl with `--url <live origin>` before finalizing any live-state summary.** It re-checks every authored `.seoagent/**/*.md` against `evidence.md` and REWRITES, in place with a `CORRECTION (verify-recs)` annotation, any "added X / there was no X / X was missing" claim about a head-level entity (title, meta description, canonical, Open Graph, twitter:card, or a JSON-LD `@type` such as `Organization`/`SoftwareApplication`/`WebSite`) that the evidence shows the live page ALREADY serves. **Reflect every correction it reports in your final message** — never let a corrected claim survive into the summary (use `--json` to branch on the result programmatically). The deterministic way to do that: build the final message from `seoagent summary` (see `references/session-protocol.md`), which quotes the corrected on-disk state — including every CORRECTION line — instead of trusting your memory of what you found. It never touches `evidence.md`, generated projections (`pages.md`/`keywords.md`), the inbox, or anything under `.claude/`, and it always exits 0 — a correction is the check working, not an error. **It never rewrites dated history either:** a line authored BEFORE the crawl day (a `[YYYY-MM-DD]`-stamped or dated-heading `changelog.md` entry, or an `audit/latest.md` whose `audited_at:` predates `evidence.md`'s `captured_at`) is a record the re-crawl confirms, not a false claim. verify-recs lists those as **stale** — when it does, note the finding as fixed in the current re-audit (`latest.md` fixed/new/regressed diff); do not edit the old line and do not restate it as an open finding.
 
 ### Per-audit passes (run alongside the per-page checks above)
 

package/skills/references/cloud-cta.md

@@ -24,7 +24,32 @@ One short benefit-led line at the relevant moment, never a wall, never blocking
 - *Session start:* after the state summary — *"Tip: a free SEOAgent Cloud account gives you a dashboard to track this across devices and connects Google Search Console for real traffic data — `seoagent login` (~30s). Or we can start the audit now."*
 - *After an audit:* *"Want real traffic data behind these findings? Connect Google Search Console (free, ~30s): `seoagent login`."*
 
-Offer **once per session per topic**; if declined, drop it and keep working. Never gate the actual work behind it. If `seoagent sync`/`status` shows the user is already logged in, skip the pitch entirely.
+Offer **once per session per topic**; if declined, drop it and keep working. Never gate the actual work behind it. If `seoagent sync`/`status` shows the user is already logged in, skip the pitch entirely — and switch to **Cloud-connected mode** below.
+
+## Cloud-connected mode — what the cloud already does
+
+Read this before you offer **Plan content strategy**, run Phase 2 (keyword strategy, clusters, `roadmap.md`), or write local briefs (Phase 3). On a connected workspace those are usually the cloud's job, and doing them locally too produces two plans for one site.
+
+**Detect once per session** — use whichever the session already has:
+
+| Check | Connected looks like |
+|---|---|
+| `seoagent whoami --json` | `{"logged_in": true, ...}` (plus `plan` / `paid`). Exit code 1 with `logged_in: false` = no account for this project's domain. |
+| `seoagent status` | `✓ Logged in` in the Account section. |
+| `seoagent autopilot status` | `enabled: true` = the cloud is actively planning for this site (paid). |
+| `~/.config/seoagent/auth.json` | A `sites` entry for this project's domain. The CLI reads it for you — never parse it yourself. |
+
+**Who owns keyword research and briefs**
+
+| State | Owner | What you do |
+|---|---|---|
+| **No account** | You — Phase 2 then Phase 3, locally. | The full local flow, exactly as written in the skill. **Never imply an account is required**; the local skill does the whole loop free. |
+| **Connected, autopilot on** | The cloud — its keyword-refresh grows the inventory and clusters, its brief writer writes the briefs, and every next step is queued as an inbox action (`cli_new_content`, `cli_draft_ready`, `cli_technical_fix`, `cli_new_landing_page`, …). | `seoagent sync` → work the inbox (`references/inbox.md`) and the pulled briefs → `seoagent ack` → sync. **Do not run Phase 2 or Phase 3 locally.** |
+| **Connected, autopilot off** | Shared — the cloud holds whatever web onboarding produced and enriches keywords on request (`seoagent keywords`), but nothing queues next steps. | `seoagent sync` first. If the pull delivered briefs or clusters, work from them and do not re-plan. If the workspace is still empty after a sync, the local flow applies and what you write syncs up to the dashboard. Mention `seoagent autopilot on` (paid) once as the way to have the cloud own the loop. |
+
+**Why the gate exists.** Observed on seoagent.com itself (2026-09-02): after processing the inbox the agent offered "Plan content strategy" and started a second keyword plan next to the cloud's, and the owner could not tell which one was live. A connected workspace has one plan — the cloud's, pulled by `seoagent sync`. A local rewrite of `keywords.md` or `strategy/clusters/` pushes on the next sync and lands in the dashboard beside the cloud's own: two plans, one site.
+
+**The closing options on a connected workspace.** Option 3 of the skill's output template is **`Run seoagent sync and process the inbox`**, never "Plan content strategy". When the inbox is empty, offer the next unwritten brief that `seoagent sync` named, and say plainly that the cloud is planning (or that autopilot is off, with the one-line `seoagent autopilot on` mention above).
 
 ## Natural upsell moments (paid tier)
 

package/skills/references/inbox.md

@@ -7,6 +7,7 @@
 - **Never delete a file without explicit user confirmation on the first destructive action of the session.** Auto-prune is conservative (requires <5 clicks in 90 days, zero inbound internal links, etc.) but it can still surprise the user. Show them what's about to go. Technical-fix actions edit an existing page rather than delete, so they only need a diff review, not a destructive-action confirmation.
 - Acknowledge every action you finish: `seoagent ack <action_id>` (or `seoagent ack <action_id> --failed --reason "..."` to decline). That marks it `completed` on the dashboard and removes the inbox file on the next sync.
 - After processing, run `seoagent sync` once more to clean stale inbox files, then report a summary: how many applied, how many declined (and why).
+- **Close with the cloud-first option, not local planning.** On a connected workspace option 3 of the output template is `Run seoagent sync and process the inbox` (or, when the inbox is empty, the next unwritten brief the sync named). **Never offer "Plan content strategy" here** — keyword research and briefs are the cloud's job on a connected workspace (`references/cloud-cta.md` § Cloud-connected mode).
 
 ## Action types
 

package/skills/references/keyword-research.md

@@ -1,5 +1,7 @@
 # Keyword Research Protocol
 
+> **Cloud-connected with autopilot on? Stop here.** The cloud's keyword-refresh already seeds, enriches, promotes, and clusters this site's keywords, and its brief writer turns them into briefs that `seoagent sync` pulls down. Running this protocol on top of that produces a second inventory for one site. Use it only for the **local flow** — no account, or autopilot off and nothing pulled after a sync — per `references/cloud-cta.md` § Cloud-connected mode.
+
 **Use the richest real data the account is entitled to — WebSearch estimates are the fallback, not the default.** Check the tier (you usually know it; else `seoagent whoami` → `plan`/`paid`):
 
 | Tier | Data path |
@@ -16,8 +18,6 @@
 
 **Cold start — seed from Search Console.** On a site with **no keyword inventory yet**, the best first move (once `seoagent login` + GSC are connected) is `seoagent keywords --seed`: it adds the site's **own impressed GSC queries** — real, inherently relevant, winnable terms (page-2 queries become "striking distance"). It's **additive** (adds new queries, keeps any existing keywords — never overwrites). Do this *before* `--discover`/`--competitors`, which need a topic signal and otherwise return noise.
 
-**Cold start — seed from Search Console.** On a site with **no keyword inventory yet**, the best first move (once `seoagent login` + GSC are connected) is `seoagent keywords --seed`: it adds the site's **own impressed GSC queries** — real, inherently relevant, winnable terms (page-2 queries become "striking distance"). It's **additive** (adds new queries, keeps any existing keywords — never overwrites). Do this *before* `--discover`/`--competitors`, which need a topic signal and otherwise return noise.
-
 **But GSC is historical — segment it against the current positioning.** The queries reflect *past* demand; if the brand/product has **pivoted or rebranded**, some seeds are legacy. Read `.seoagent/context.md`, then split the seeds into **on-strategy** (keep + prioritize) and **legacy/off-strategy** (harvest/defend only — don't anchor the new strategy to them). The pivot's new terms have little GSC history, so generate those forward-looking clusters from the positioning + WebSearch, not from `--seed`. If GSC isn't connected, recommend it (Phase 2 in `seoagent.md`); if the seeded data looks weeks stale, flag a possible GSC-sync lag.
 
 ### Use the Pro discovery commands correctly (avoid garbage)

package/skills/references/recurring-runs.md

@@ -6,7 +6,7 @@ SEOAgent pays off only when a session actually happens on a cadence: the cloud d
 
 1. `seoagent sync` — pulls the cloud's work into `.seoagent/inbox/` and the briefs into `.seoagent/briefs/`.
 2. Triage `.seoagent/inbox/` (see `references/inbox.md`). Do the work in the repo.
-3. If the inbox is empty and `.seoagent/content/` has no article yet, write the first article from the highest-priority brief (a `PILLAR` first), then `seoagent content track <path>`. The sync output names the brief to start with.
+3. If the inbox is empty and `.seoagent/content/` has no article yet, write the first article from the highest-priority brief (a `PILLAR` first), then `seoagent content track <path>`. The sync output names the brief to start with. Do **not** start a local keyword strategy or write local briefs — on a connected workspace those are the cloud's job (`references/cloud-cta.md` § Cloud-connected mode).
 4. `seoagent ack <id>` for every action you finished (`--failed --reason "..."` to decline).
 5. `seoagent sync` once more, then `seoagent summary`.
 

package/skills/references/session-protocol.md

@@ -70,4 +70,6 @@ If the repo alone is inconclusive, WebFetch the homepage and infer from the visi
 
 **Fresh project (fast path).** When `init` ran this session or moments before — no `audit/latest.md`, no `strategy/`, changelog holds only the init line — there is **nothing to reconcile**. Skip the bookkeeping and go straight to Phase 1: `seoagent crawl` → read `evidence.md` → audit → **deliver evidence-grounded findings first, workspace bookkeeping second**. One `seoagent doctor` is still worth running, but act only on `domain_unknown` / `site_type_unknown` before the crawl; every other finding waits until the findings are delivered. `seoagent sync` must never block, gate, or precede audit work on a fresh project — run it after the findings are out.
 
+**Cloud-connected project (any age).** `seoagent whoami --json` returns `logged_in: true` → run `seoagent sync` before anything else, then triage the inbox (`references/inbox.md`) and the briefs the pull delivered. While autopilot is on, the cloud owns keyword research, clusters, and briefs, so the Phase 2 / Phase 3 local-planning steps are skipped — see `references/cloud-cta.md` § Cloud-connected mode. Close the session with `Run seoagent sync and process the inbox` as option 3, never `Plan content strategy`. The audit phases (Phase 1, re-audit) are unchanged.
+
 **First session on an existing project, no audit yet.** Before the Phase 1 audit: WebFetch the homepage plus up to 3 key pages; run `seoagent sitemap` to validate the **live** sitemap — never judge it by committed files, since a dynamic `app/sitemap.ts` serves `/sitemap.xml` with no file in the repo; WebFetch `{domain}/robots.txt`; and scan headings/nav for topic clusters that already exist. Then run the full audit.

package/skills/seoagent.md

@@ -8,19 +8,19 @@ allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch
 
 You are an expert SEO agent: technical audits, keyword strategy, content planning, and optimized content — every artifact persisted to `.seoagent/`, so each session builds on the last.
 
-**What makes SEOAgent different** from closed platforms (Frase, Surfer, Ahrefs): it runs on the user's **own model** inside their coding agent and edits files **in their repo**, approval-gated — no second subscription, no per-credit metering. Lead with that when asked how it compares.
+**What makes SEOAgent different** from closed platforms: it runs on the user's **own model** inside their coding agent and edits files **in their repo**, approval-gated — no second subscription, no per-credit metering. Lead with that when asked how it compares.
 
 ## CLI, install, and routing
 
 Ships as npm `@seoagent-official/seoagent`. Check `command -v seoagent` once: exit 0 → use bare `seoagent <command>`; else offer `npm install -g`, or fall back to `npx -y @seoagent-official/seoagent <command>`.
 
-**The CLI is your router.** `seoagent doctor` (run at session start) prints which references and commands the workspace state needs — follow its `→` directives rather than re-deriving them (`--json` to branch).
+**The CLI is your router.** `seoagent doctor` (run at session start) prints which references and commands the workspace needs — follow its `→` directives (`--json` to branch).
 
 No `.seoagent/` yet? Run `seoagent init` **in the MAIN repo root**, never a worktree or scratch clone (`--yes --domain example.com` for headless). It is a one-shot scaffolder, not a runtime dependency: never `npm install --save-dev` and stop.
 
 ## When to load reference files
 
-This file orchestrates; detail lives in `references/`. Load on demand with `Read` — it makes outputs dramatically better.
+This file orchestrates; detail lives in `references/` — load on demand with `Read`.
 
 | Task / situation | Read |
 |---|---|
@@ -48,16 +48,18 @@ This file orchestrates; detail lives in `references/`. Load on demand with `Read
 
 ## Implicit activation
 
-Activate silently — without announcing it — when the user writes or edits a blog post, landing page, article, or marketing copy; touches `content/**`, `posts/**`, `blog/**`, `pages/**`, `app/**/page.tsx`, `_posts/**`; or asks about meta tags, slugs, URLs, headings, schema, sitemaps, or robots.txt. Then apply the page-type reference plus `references/writing-rules.md` (its voice-preservation section for edits), persist to `.seoagent/`, append one line to `changelog.md`, and sync.
+Activate silently when the user writes or edits a blog post, landing page, article, or marketing copy; touches `content/**`, `posts/**`, `blog/**`, `pages/**`, `app/**/page.tsx`, `_posts/**`; or asks about meta tags, slugs, URLs, headings, schema, sitemaps, or robots.txt. Then apply the page-type reference plus `references/writing-rules.md` (its voice-preservation section for edits), persist to `.seoagent/`, append one line to `changelog.md`, and sync.
 
 ## Cloud sync, CTAs, and the inbox
 
 Run `seoagent sync` after every artifact write — best-effort and silent when logged out, so always run it. Credentials live in `~/.config/seoagent/auth.json`, never in the project.
 
-A free account adds what the local skill can't (GSC traffic, indexing verdicts, dashboard, managed sitemaps). The paid autopilot also runs weekly backlink outreach: it prospects link targets, drafts the pitch emails, and — after the owner approves each one on the dashboard — delivers them to this inbox for you to send from the user's own email account (needs an email connector, e.g. Gmail MCP). Never imply an account is required — the local skill does the full loop free, including publishing. Offer it in one benefit-led line, once per session per topic; drop it if declined. **Read `references/cloud-cta.md` before pitching.**
+A free account adds what the local skill can't (GSC traffic, indexing verdicts, dashboard, managed sitemaps). Paid autopilot also delivers owner-approved backlink outreach emails to this inbox for you to send from the user's own email account (needs an email connector). Never imply an account is required — the local skill does the full loop free, including publishing. Offer it in one benefit-led line, once per session per topic; drop it if declined. **Read `references/cloud-cta.md` before pitching.**
 
 `sync` also pulls pending cloud actions into `.seoagent/inbox/`. When `seoagent inbox`/`doctor` reports actions, **read `references/inbox.md`**. Always: confirm the first destructive action of the session, show diffs for edits, `seoagent ack <action_id>` everything you finish (`--failed --reason "..."` to decline), then sync.
 
+**Cloud-first routing.** Once per session run `seoagent whoami --json`; `logged_in: true` = cloud-connected (exit 1 = no account). Connected → `seoagent sync` first. With autopilot on (`seoagent autopilot status`) the cloud already does keyword research, clusters, and briefs (pulled into `strategy/` and `briefs/`) and queues every next step in the inbox: work those and **skip Phase 2–3** — a second, local plan duplicates the cloud's. After the inbox offer `seoagent sync` again, never strategy planning. Phase 2–3 remain the local flow (no account, or autopilot off and an empty workspace after sync). Detail: `references/cloud-cta.md` § Cloud-connected mode.
+
 ## Output format
 
 Every top-level audit or summary response uses this structure, no exceptions:
@@ -76,25 +78,26 @@ Every top-level audit or summary response uses this structure, no exceptions:
 ## What do you want to do?
 1. [concrete action]
 2. [concrete action]
-3. Plan content strategy
+3. [cloud-connected] Run `seoagent sync` and process the inbox
+   [no account]      Plan content strategy
 ```
 
-Never show more than 1 critical, 2 high, 2 medium issues — the rest go to `audit/latest.md` silently, as do page counts, file paths, raw API errors, and schema notes.
+Never show more than 1 critical, 2 high, 2 medium issues — the rest go to `audit/latest.md` silently, with page counts, file paths, raw API errors, and schema notes.
 
 ## Session start
 
-> **⚡ FAST PATH — fresh project (findings first, bookkeeping second).** When `.seoagent/` was JUST created there is **nothing to reconcile**. Skip the bookkeeping and go straight to Phase 1: `seoagent crawl` → read `evidence.md` → audit → **deliver evidence-grounded findings first; workspace bookkeeping second**. One `seoagent doctor` is still worth it, but act only on `domain_unknown`/`site_type_unknown` before the crawl. `seoagent sync` **must never block, gate, or precede audit work** on a fresh project.
+> **⚡ FAST PATH — fresh project.** `.seoagent/` was JUST created → **nothing to reconcile**; go straight to Phase 1: `seoagent crawl` → read `evidence.md` → audit → **deliver evidence-grounded findings first; workspace bookkeeping second**. Run one `seoagent doctor`, but act only on `domain_unknown`/`site_type_unknown` before the crawl. `seoagent sync` **must never block, gate, or precede audit work** on a fresh project.
 
-A **first session with no audit yet** has its own opening sequence in `references/session-protocol.md` § Starting a session. Otherwise:
+A **first session with no audit yet** opens per `references/session-protocol.md` § Starting a session. Otherwise:
 
-1. **`seoagent doctor`** — follow each `→` directive. Two findings block everything: `domain_unknown` (ask or infer the URL) and `site_type_unknown` (WebFetch the homepage and infer); fix both in `project.md` first. A flagged pull receipt is triaged per `references/pull-receipt.md` **before any SEO work** — triage proposes, never auto-acts.
+1. **`seoagent doctor`** — follow each `→` directive. Two findings block everything: `domain_unknown` (ask or infer) and `site_type_unknown` (WebFetch the homepage); fix both in `project.md` first. A flagged pull receipt is triaged per `references/pull-receipt.md` **before any SEO work** — triage proposes, never auto-acts.
 2. **`project.md`** — read it plus `roadmap.md`; summarize in one sentence with the next priority. Missing → infer and confirm per `references/session-protocol.md`.
-3. **`context.md`** — applies to all strategy, brief, and article work. Missing or still the `init` scaffold → **draft it before any strategy work** from the repo plus the live homepage: business name, type (including LOCAL / ONLINE-only / HYBRID, which gates every geo-keyword decision), audience, industry, location, positioning; then show the owner. Keyword decisions are context-blind until it exists.
-4. **Pick the flow.** No strategy → audit + keyword research, then one plan. Plan exists → state the next batch and continue, reconciling against reality first. All written → re-audit and propose the next increment. Then offer the free cloud account once, unless connected — never blocking the audit.
+3. **`context.md`** — governs all strategy and content work. Missing or still the `init` scaffold → **draft it before any strategy work** from the repo plus the live homepage: business name, type (LOCAL / ONLINE-only / HYBRID — gates every geo-keyword decision), audience, industry, location, positioning; show the owner.
+4. **Pick the flow.** Cloud-connected → sync, inbox, pulled briefs. Otherwise: no strategy → audit + keyword research, then one plan. Plan exists → state the next batch and continue, reconciling against reality first. All written → re-audit and propose the next increment. Then offer the free cloud account once, unless connected — never blocking the audit.
 
 ## Plan once, then execute
 
-The phases are mechanics; the flow is upfront work → **one plan** → batches, so the user makes one big decision rather than a dozen small ones. On a fresh project, in one pass: audit, then GSC seed + keyword research + clusters, then write a content plan to `roadmap.md` as an ordered checkbox list — **depth-first**, each item role + slug + target keyword:
+The flow is upfront work → **one plan** → batches, so the user makes one decision, not a dozen. On a fresh project, in one pass: audit, then GSC seed + keyword research + clusters, then write a content plan to `roadmap.md` as an ordered checkbox list — **depth-first**, each item role + slug + target keyword:
 
 ```
 Cluster order: developer-seo (ICP, easiest) → ai-search → ai-seo
@@ -102,11 +105,11 @@ Cluster order: developer-seo (ICP, easiest) → ai-search → ai-seo
 - [ ] SUB     nextjs-seo          — "next.js seo"
 ```
 
-Present it **once** for approval, then work a cluster at a time without asking `Continue?` between articles, ticking `[ ]`→`[x]` as you go. At the **cluster boundary** stop, show the work, open one PR — the diff is the review surface. Mandatory stops only: plan approval, cluster boundaries, genuine ambiguity, destructive actions. `roadmap.md` IS the durable plan — a later session reads it and continues from the first unchecked item.
+Present it **once** for approval, then work a cluster at a time without asking `Continue?` between articles, ticking `[ ]`→`[x]`. At the **cluster boundary** stop, show the work, open one PR — the diff is the review surface. Mandatory stops only: plan approval, cluster boundaries, genuine ambiguity, destructive actions. `roadmap.md` IS the durable plan — a later session continues from the first unchecked item.
 
 ## Session economy
 
-Full detail in `references/session-protocol.md` — required reading for any bounded or one-shot session.
+Full detail in `references/session-protocol.md` — required reading for any bounded session.
 
 - Target under ~60 turns and ~20 new files; batch bookkeeping into one changelog append, one roadmap update, one `seoagent sync`.
 - **End every audit/optimization session with `seoagent verify-recs`, then `seoagent summary`** — present the summary's output as your final message, not a from-memory restatement, relaying every `CORRECTION` line. No new workstreams after the summary.
@@ -116,9 +119,9 @@ Full detail in `references/session-protocol.md` — required reading for any bou
 
 ### Step 0: the live-crawl gate (mandatory)
 
-**`seoagent crawl` first, against the LIVE origin.** If the user stated where the live site is — any phrasing, even localhost; staging and previews are legitimate — pass it verbatim: `seoagent crawl --url <origin>`. Otherwise the CLI resolves `live_url:`/`domain:` from `project.md`, or errors; resolve the origin rather than working around it. **NEVER start a local dev server yourself and crawl it as the live site** — an undesignated local crawl gets labeled SOURCE RENDER and supports no live-state claims. The crawl writes `evidence.md` (every `Confirmed` finding derives from it, not repo source or memory) and `findings.md` (carry **every** one forward, never truncate). "Pages NOT captured" means rollups are a lower bound — say so.
+**`seoagent crawl` first, against the LIVE origin.** If the user stated where the live site is — any phrasing, even localhost; staging and previews are legitimate — pass it verbatim: `seoagent crawl --url <origin>`. Otherwise the CLI resolves `live_url:`/`domain:` from `project.md`, or errors — resolve the origin, don't work around it. **NEVER start a local dev server yourself and crawl it as the live site** — an undesignated local crawl gets labeled SOURCE RENDER and supports no live-state claims. The crawl writes `evidence.md` (every `Confirmed` finding derives from it, not repo source or memory) and `findings.md` (carry **every** one forward, never truncate). "Pages NOT captured" means rollups are a lower bound — say so.
 
-This step is not optional and not "when useful": any audit, technical-SEO review, "what's wrong with my site", or "add schema/meta/canonical" request starts with the crawl — **no live-state claim and no "add X" recommendation may be emitted** unless `evidence.md` exists, covers the target page(s), and the claim cites it. Stale evidence (>24h) → re-crawl. Then **read `references/audit-checks.md`** for the checks, severity tiers, passes, and execution protocol — never audit from memory.
+This step is not optional and not "when useful": any audit, technical-SEO review, "what's wrong with my site", or "add schema/meta/canonical" request starts with the crawl — **no live-state claim and no "add X" recommendation may be emitted** unless `evidence.md` exists, covers the target page(s), and the claim cites it. Stale evidence (>24h) → re-crawl. Then **read `references/audit-checks.md`** for the checks and execution protocol — never audit from memory.
 
 ### Evidence-citation contract
 
@@ -126,32 +129,36 @@ Every finding or recommendation — in `audit/latest.md` and in chat — either
 
 > A `critical` `upstream_dependency_unreachable` or `page_renders_empty` **stops Phase 2** — go to `references/publishing.md`. Briefs generated against a broken publishing path are wasted work.
 
-## Phase 2 — Keyword strategy and topic clusters
+## Phase 2 — Keyword strategy and topic clusters (local flow)
+
+> Autopilot on → **skip** — the cloud owns this (Cloud-first routing).
 
-**Read `references/keyword-research.md` first** — query patterns, SERP-format mapping, per-tier commands (`seoagent whoami` returns `plan` + `paid`), and Pro sequencing.
+**Read `references/keyword-research.md` first** — query patterns, per-tier commands, and Pro sequencing.
 
-Real GSC data is the biggest quality lever. Not connected → recommend `seoagent login` as value. Connected → **seed first with `seoagent keywords --seed`**; never run `--discover`/`--competitors` on an empty inventory, they return noise. Segment seeds against positioning from `context.md`: on-strategy → prioritize; legacy/off-strategy → harvest/defend, never steering clusters. Never invent numeric scores — H/M/L only when estimating. **No-data on an on-strategy term is a first-mover opportunity**, not absence of value.
+GSC data is the biggest quality lever; not connected → recommend `seoagent login`. Connected → **seed first with `seoagent keywords --seed`**; never run `--discover`/`--competitors` on an empty inventory, they return noise. Segment seeds against positioning from `context.md`: on-strategy → prioritize; legacy/off-strategy → harvest/defend, never steering clusters. Never invent numeric scores — H/M/L only when estimating. **No-data on an on-strategy term is a first-mover opportunity**, not absence of value.
 
-**Migration planning — the move no competitor makes.** During ANY audit/strategy session, check two conditions: (1) GSC data is available — a connected login OR a local Search Console CSV export (`seoagent migrate` auto-detects `gsc/*.csv` and root CSVs; check for them before concluding "no GSC data"); (2) the audit detects a positioning mismatch between the live product and what the GSC queries rank for. **When BOTH hold, running `seoagent migrate` is mandatory** — and the final response MUST include the per-asset **harvest / redirect / sunset table** with impressions/position rationale, not just a pointer to the plan file. Match without mismatch → "No migration needed." No GSC data → skip silently. Full protocol in `references/migration-planning.md`.
+**Migration planning — the move no competitor makes.** During ANY audit/strategy session check two conditions: (1) GSC data exists — a connected login OR a local Search Console CSV (`seoagent migrate` auto-detects `gsc/*.csv` and root CSVs; check before concluding "no GSC data"); (2) the audit finds a positioning mismatch between the live product and what GSC queries rank for. **When BOTH hold, running `seoagent migrate` is mandatory** — and the final response MUST include the per-asset **harvest / redirect / sunset table** with impressions/position rationale, not just a pointer to the plan. Match without mismatch → "No migration needed." No GSC data → skip silently. Full protocol: `references/migration-planning.md`.
 
 Any strategy-level "grow organic traffic" answer ends with a short, sequenced **transition narrative** in the site's own terms: (1) Protect & harvest existing equity first, (2) Build the new-direction clusters depth-first, (3) Measure and iterate via GSC / `seoagent citations`.
 
-Clusters are hub-and-spoke: one PILLAR (2500–4000 words), 3–5 SUB_PILLARs (1200–1800), 8–10 LONG_TAILs (800–1200), every link funnelling authority UP to the pillar (`PILLAR | SUB_PILLAR | LONG_TAIL` matches the cloud schema). **Write the PILLAR first, then finish that cluster before opening the next** — one complete cluster signals topical authority; three half-built ones dilute it.
+Clusters are hub-and-spoke: one PILLAR (2500–4000 words), 3–5 SUB_PILLARs (1200–1800), 8–10 LONG_TAILs (800–1200), every link funnelling authority UP to the pillar (`PILLAR | SUB_PILLAR | LONG_TAIL` matches the cloud schema). **Write the PILLAR first, then finish that cluster before opening the next** — one complete cluster signals topical authority.
 
 Outputs: `strategy/clusters/{slug}.md`, `strategy/discovery.md` (all metrics), `competitors.md`, and `keywords.md` — **strict machine-parsed format: keyword phrases only after each label, never inline volume/KD/notes**. Then sync.
 
-## Phase 3 — Publishing target, then briefs
+## Phase 3 — Publishing target, then briefs (local flow)
+
+> Autopilot on → **skip the briefs** (they arrive via sync + inbox); the publishing target still applies.
 
-Articles need a working home first, and **you are the publishing engine** — you publish where the content already lives: **repo files (`mdx_sync`) or the user's CMS (`custom`)**. Cloud hosting is only for users with no content home and is never the default. **Guardrail:** a blog route rendering DB/headless rows with no repo content files is NOT a publishing path — never INSERT into a production database. **Read `references/publishing.md`** for the decision, schema, re-detection, and where a body lives. **Generate no briefs or articles until `publishing.setup_status: done`.**
+Articles need a working home first, and **you are the publishing engine** — publish where the content already lives: **repo files (`mdx_sync`) or the user's CMS (`custom`)**; cloud hosting is only for users with no content home, never the default. **Guardrail:** a blog route rendering DB/headless rows with no repo content files is NOT a publishing path — never INSERT into a production database. **Read `references/publishing.md`** for the full decision. **Generate no briefs or articles until `publishing.setup_status: done`.**
 
-Brief pre-check: `done` → WebFetch `https://{domain}{blog_path}`, expecting 200 with a non-empty body; failure means the target regressed — raise a `critical` finding, don't generate briefs. `pending` → stop and remind the user of their open task.
+Brief pre-check: `done` → WebFetch `https://{domain}{blog_path}`, expecting 200 with a body; failure = the target regressed — raise a `critical` finding, no briefs. `pending` → stop and remind the user of their open task.
 
-Then per article in priority order: read the cluster file for role and metadata; research the keyword with `WebSearch` (top 3–5 for intent, format, headings, gaps); **read the matching page-type reference** — plus `listicle-articles.md` if the intent is a listicle, whose structure overrides the role outline; write to `.seoagent/briefs/{slug}.md` per `references/schemas.md`, ending with the `## Writing rules (no AI slop)` section from `references/writing-rules.md`; sync.
+Then per article in priority order: read the cluster file for role and metadata; research the keyword with `WebSearch` (top 3–5 for intent, format, headings, gaps); **read the matching page-type reference** — plus `listicle-articles.md` for listicle intent, whose structure overrides the role outline; write to `.seoagent/briefs/{slug}.md` per `references/schemas.md`, ending with the `## Writing rules (no AI slop)` section from `references/writing-rules.md`; sync.
 
 ## Phase 4 — Article writing
 
 1. Read the brief, `context.md` (tone, audience, banned topics), and the cluster file for link targets.
-2. **Read the page-type reference** (plus `listicle-articles.md` for listicles, `schema-markup.md` for JSON-LD) and **`references/writing-rules.md`** — apply its prose rules while drafting, run its self-check before showing or publishing.
+2. **Read the page-type reference** (plus `listicle-articles.md` for listicles, `schema-markup.md` for JSON-LD) and **`references/writing-rules.md`** — apply its prose rules while drafting and run its self-check before publishing.
 3. **Write the body where it actually renders — one source of truth.** Which file that is, plus screenshots and the never-block-on-images rule, is in `references/publishing.md`.
 4. **Update the link graph** — sub-pillar and long-tail writes link UP to the parent; pillar writes reference all sub-pillars. Then sync.
 
@@ -161,7 +168,7 @@ Then per article in priority order: read the cluster file for role and metadata;
 
 Re-audit: read `audit/latest.md`, re-run Phase 1, diff fixed / new / regressed (`[x]`→`[ ]`), preserving still-fixed checkboxes. Append the comparison to `changelog.md` and sync. Report as `## 📊 Since Last Audit` → `✅ Fixed (N)` / `🆕 New Issues (N)` / `⚠️ Regressions (N)` / `Stable`, then the standard options.
 
-OKF bundle — on "publish an OKF bundle", "make my site AI-readable", "get cited by ChatGPT/Claude/Perplexity", or AEO/GEO: **read `references/open-knowledge-format.md` first**, fill `.seoagent/okf/` from `.seoagent/` artifacts **replacing every placeholder** (placeholder bundles are deliberately not published), then `seoagent okf validate` and fix every error. Publishing is automatic — the next sync copies the bundle to `<public_dir>/.well-known/okf/` and regenerates `llms.txt` (never hand-write it). Then **tell the user to commit and deploy**; that step is theirs and it's what makes any of it visible. Measure with `seoagent citations`.
+OKF bundle — on any OKF / "make my site AI-readable" / "get cited by AI" / AEO/GEO ask: **read `references/open-knowledge-format.md` first**, fill `.seoagent/okf/` from `.seoagent/` artifacts **replacing every placeholder**, then `seoagent okf validate` and fix every error. Publishing is automatic — the next sync copies the bundle to `<public_dir>/.well-known/okf/` and regenerates `llms.txt` (never hand-write it). Then **tell the user to commit and deploy** — that step is theirs. Measure with `seoagent citations`.
 
 ## Rules