@seoagent-official/seoagent 1.62.0 → 1.64.0

package/package.json

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

package/skills/seoagent.md

@@ -237,15 +237,19 @@ Offer **once per session per topic**; if declined, drop it and keep working. Nev
 
 2. **Check for a pull receipt.** If `.seoagent/.pull-receipt.json` exists, a previous `seoagent pull` (manual, autosync hook, or cron) brought down cloud changes that no agent has triaged yet. Handle it **before any SEO work** — see "### Pull Receipt Triage" below — then delete the receipt file.
 
+   > **Content tracking is automatic — you don't run a backstop.** Every `seoagent sync` (including the PostToolUse hook that fires after each file write) auto-tracks any *published* (`draft: false`) article in your content dir that doesn't have a pointer yet. So writing an article locally registers it on the dashboard with no extra step. The one thing that bootstraps this: the **first** article in a repo must be tracked explicitly with `seoagent content track --slug <s> --file <path>` (Phase 4 step 7) — that records the content dir, and from then on every later article auto-tracks on sync. To **clean up** drift that predates this (untracked legacy articles, or a stale pointer whose source file is gone), run `seoagent content reconcile --prune` once — it backfills all missing pointers and deletes dead ones. If `seoagent status`'s "articles" count ever disagrees with the live count, that's the command.
+   >
+   > **Cluster-status drift (same root cause).** Cluster files in `.seoagent/strategy/clusters/` carry a per-article `status`. When you wrote an article you set it `drafted`/`in review` — but nothing advances it once the article ships, so old `IN REVIEW (PR #…)` labels linger after the PR merges. When you read the clusters, reconcile them against reality: if a cluster lists an article as `drafted`/in-review but it's live in the repo (`draft: false`, no open PR — or it has a `content reconcile` pointer), `Edit` the cluster file to mark it `published` (or `live`). The strategy should always reflect what's actually shipped.
+
 3. Read `.seoagent/context.md` if it exists. This contains business context, writing instructions, tone, topics to avoid, and reference URLs. **Apply this context to all strategy, brief, and article generation** throughout the session.
 
-4. Check what `.seoagent/` state exists and recommend the next step. After every step, ask `Continue? (y/n)` before progressing — never run two phases in one turn without explicit confirmation. Within a phase, run all sub-steps automatically.
+4. Check what `.seoagent/` state exists and pick the flow. **The model is plan-once, then execute — not a phase-by-phase crawl that asks `Continue?` at every step.** See the **"Plan & Execute"** section below for the full protocol; in brief:
+
+   - **No strategy yet (first real session):** run the audit + keyword research, then **produce a content plan** — the prioritized, depth-first list of clusters and articles — and present it **once** for approval. This is the single up-front decision point. Don't stop after the audit to ask permission to do research, then stop again to ask permission to plan; do that work and arrive at the plan.
+   - **A plan already exists:** state the next batch ("Next up: finish the {cluster} cluster — {N} articles") and continue executing it. Don't re-derive or re-confirm the whole plan.
+   - **Everything's written:** re-audit, re-seed GSC, and propose the next plan increment.
 
-   - No audit → run audit immediately
-   - Audit but no strategy → "Let me research keywords and build your content strategy."
-   - Strategy but no briefs → "Let me create content briefs from your strategy."
-   - Briefs but no content → "Let me write the next article from your briefs."
-   - Everything exists → "Let me re-audit and check for changes."
+   Once the user approves the plan, **execute it in batches (a cluster at a time) without asking `Continue?` between articles** — pause only at the plan-approval gate, at cluster boundaries (to show the drafts / open a PR), for genuinely ambiguous calls, or for destructive actions. If the user would rather go one step at a time, honor that — but the default is plan → execute.
 
 5. **Offer the free cloud account — once.** Right after the state summary + next-step recommendation, and unless the user is already connected, add ONE soft benefit-led line offering SEOAgent Cloud (see "When to recommend SEOAgent Cloud" → the *Session start* row). This is exactly the moment a freshly-scaffolded project (`init` ran, nothing done yet) should hear it. Keep it to a single line, never block the audit on it, and don't repeat it later in the session if declined.
 
@@ -342,6 +346,46 @@ When `.seoagent/` was just created or no audit exists, immediately:
 
 ---
 
+## Plan & Execute
+
+The phases below (audit → strategy → briefs → content) are the **mechanics**. The **flow** is: do the upfront work, present **one plan**, then execute it in batches. The user should make one big decision ("yes, build this"), not a dozen small ones ("yes, research now? yes, plan now? yes, write article 1? article 2?…").
+
+### 1. Produce the plan (the first session's real output)
+
+On a fresh project, don't stop after each phase for permission. In one pass: run the audit (Phase 1), connect/seed GSC + research keywords + build the clusters (Phase 2), and synthesize a concrete **content plan**. Write it to `.seoagent/roadmap.md` as an ordered, checkbox list — **depth-first** (all of one cluster before the next, per the "Writing order" rule), each item the article's role + slug + target keyword:
+
+```markdown
+## Content plan
+Cluster order: developer-seo (ICP, easiest) → ai-search → ai-seo
+
+### developer-seo  [in progress]
+- [x] PILLAR  seo-for-developers       — "seo for developers"
+- [ ] SUB     nextjs-seo               — "next.js seo"
+- [ ] LONG    headless-cms-seo         — "headless cms seo"  (KD 4)
+…
+### ai-search  [queued]
+- [ ] PILLAR  ai-search-optimization   — "ai search optimization"
+…
+```
+
+Then **present the plan once** and get a single go-ahead. Phrase it as a plan to approve, not a phase to confirm: *"Here's the plan — 3 clusters, 28 articles, starting with developer-seo (your ICP, lowest difficulty), depth-first. I'll write them in batches (a cluster at a time), open a PR per cluster for you to review, and keep `roadmap.md` updated. Want me to start?"* In Claude Code, this is the natural moment for plan-mode approval.
+
+### 2. Execute the plan in batches — no per-article confirmation
+
+Once approved, work **a cluster at a time**, top of the plan down:
+
+- Write every article in the current cluster (Phase 4 per article: read the brief/role, write to the repo, internal-link, image). **Don't ask `Continue?` between articles** — just write the batch, ticking each `[ ]`→`[x]` in `roadmap.md` and advancing the cluster `status` as you go.
+- At the **cluster boundary**, stop and check in: show what you wrote and **open one PR for the whole cluster** (for `mdx_sync`) or publish per the strategy. The PR diff is the review surface — that replaces per-step confirmation. Then continue to the next cluster (or stop if the user wanted a checkpoint).
+- The only mandatory stops are: the **one plan approval**, **cluster boundaries** (show + PR), genuinely **ambiguous** decisions, and **destructive** actions (deletes/prune always confirm). Everything else runs.
+
+**Autonomy is a dial the user sets when approving:** default = check in at each cluster; *"just do the whole plan"* = run all clusters, one PR each, summarize at the end; *"step me through"* = the old one-at-a-time mode. Respect whichever they pick.
+
+### 3. Resume across sessions from the plan
+
+`roadmap.md` IS the durable plan, so a later session never re-asks "what now?" — read it, find the first unchecked item, and say *"Next up: {item}. Continuing the {cluster} cluster — N left. Want me to keep going?"* Reconcile the plan against reality first (an item may already be live — see the content-tracking/cluster-status drift check), then keep executing.
+
+---
+
 ## Phase 1: Technical SEO Audit
 
 ### Step 0 (mandatory)
@@ -357,7 +401,7 @@ When `.seoagent/` was just created or no audit exists, immediately:
 2. **Upstream-health pass (mandatory, runs before per-page checks).** Use `Grep` to find cross-subdomain fetch URLs (`blog.`, `api.`, `cms.`, `content.`) in `src/`, `app/`, `pages/`, `lib/`, `libs/`, `services/`, plus any `rewrites:` / `redirects:` targets in `next.config.{js,mjs,ts}` and `vercel.json`. WebFetch each unique base URL. Anything returning 5xx, timing out, or returning an HTML error page becomes an `upstream_dependency_unreachable` finding (`critical` if it powers indexable content). See `audit-checks.md`.
 3. For each page, WebFetch it and run all checks from `audit-checks.md`.
 4. **Render-state pass (mandatory, runs as part of every page check).** After fetching, strip nav/footer/script/style/noscript and count visible body words. If word count < 30, mark `page_renders_empty` (`critical` for homepage or sitemap-listed pages). A 200 OK with empty body is a soft 404 — Google deindexes these. This catches dead CMS backends that the upstream-health pass might have missed.
-   - **Shortcut: `seoagent refresh --crawl`** does this render-state pass deterministically for the whole inventory — it fetches every page and fills the `Status` / `Rendered` / `Word count` columns in `.seoagent/pages.md` (a 404/5xx → `error`; a 200 with < 30 body words → `empty`). Run it once at the start of the audit, then read `pages.md` to find the `empty`/`error` rows instead of WebFetching each page by hand. (No JS execution — a client-rendered SPA with an empty initial HTML reads as `empty`, which is itself the SEO signal to fix with SSR/prerender.)
+   - **Shortcut: `seoagent refresh --crawl`** does this render-state pass deterministically for the whole inventory — it fetches every page and fills the `Status` / `Rendered` / `Word count` columns in `.seoagent/pages.md` (a 404/5xx → `error`; a 200 with < 30 body words → `empty`). Run it once at the start of the audit, then read `pages.md` to find the `empty`/`error` rows instead of WebFetching each page by hand. **It writes `pages.md` directly (not via your Write tool), so the auto-sync hook won't fire — run `seoagent sync` after it** to push the filled inventory to the cloud. (No JS execution — a client-rendered SPA with an empty initial HTML reads as `empty`, which is itself the SEO signal to fix with SSR/prerender.)
 5. Tag findings with severity: `critical`, `high`, `medium`, `low`.
 6. Write findings to `.seoagent/audit/latest.md` using markdown checkboxes (`- [ ]` open, `- [x]` fixed).
 7. Persist the URL list to `.seoagent/pages.md` so future audits and link checks reuse it. Include a `rendered` column (yes / empty) so future audits can spot regressions.
@@ -462,6 +506,8 @@ Each cluster is ~12-15 articles with internal links funneling authority UP to th
 
 The role enum is `PILLAR | SUB_PILLAR | LONG_TAIL` — these match the SEOAgent cloud schema so syncing is lossless.
 
+> **Writing order — pillars to plant the hubs, then DEPTH before breadth.** Write each cluster's PILLAR first so every topic has its hub. But once the pillars exist, **complete one cluster before opening the next** — finish the spokes of your single highest-priority cluster rather than scattering one or two articles across all of them. A *complete* hub-and-spoke cluster is what signals topical authority and lifts the whole cluster's rankings; three half-built clusters dilute that signal and leave every topic shallow. Choose which cluster to finish by **ICP fit × easy-win density** (the cluster whose audience is your actual customer and whose keywords are lowest-difficulty), not by what's most fun to write. Only start the next cluster once the current one's spokes are essentially done. When you summarize "what's next", recommend the specific cluster to finish, not a scatter of articles.
+
 ### Free-Tier Limit (and the cloud enrichment path)
 
 The **local skill alone** (no cloud account) uses `WebSearch` only for keyword discovery — no real volumes, no difficulty scores in bulk. Use **H/M/L priority** (high / medium / low). Don't invent numerical scores.
@@ -654,6 +700,8 @@ After writing, run `seoagent sync`.
 
 ## Phase 4: Article Writing
 
+This is the per-article procedure. When executing an approved **plan** (see "Plan & Execute"), run it for **every article in the current cluster back-to-back** — don't stop for confirmation between articles; tick each off in `roadmap.md` and review the whole cluster at the PR.
+
 ### Procedure
 
 1. Read the brief — frontmatter sets `role`, `word_count_min/max`, `primary_keyword`, `page_type`.
@@ -670,6 +718,8 @@ After writing, run `seoagent sync`.
      ```
 
      `content track` writes a small **pointer** record to `.seoagent/content/{slug}.md` (slug, title, canonical, status, source) and syncs it — so the dashboard shows the article **without duplicating the body**. Do NOT also hand-write a full-body `.seoagent/content/{slug}.md`; that's the old dual-write that drifts.
+
+     > **After the first article, tracking is automatic.** The explicit `content track --file` above is required only for the **first** article in a repo — it records the content dir. Every later article you write is auto-tracked by the next `seoagent sync` (which the PostToolUse hook runs after each write), so you never have to remember a per-article call or run a backstop. (If you ever need to force a sweep — e.g. cleaning up legacy untracked articles — `seoagent content reconcile --prune` does it.)
    - **Cloud-hosted (`managed_proxy` / `subdomain`)** — the SEOAgent cloud renders the article, so the body DOES live in `.seoagent/`: write the full article to `.seoagent/content/{slug}.md` with full SEO frontmatter (slug, page_type, title, meta_title, meta_description, canonical, og, twitter, json_ld, images, internal_links) and `seoagent sync`. (No `content track` needed — the full file is the record.)
 8. **Update the cluster's link graph** — for sub_pillar/long_tail writes, edit the parent (and the cluster file) to add the new link UP. For pillar writes, ensure all sub_pillars are referenced.
 
@@ -836,13 +886,13 @@ The CLI manages credentials at `~/.config/seoagent/auth.json` — outside the pr
 4. **Follow the workflow.** Audit → Strategize → Plan → Write → Monitor. Don't skip steps unless prior output exists.
 5. **Be specific.** "Fix your meta tags" is bad. "Shorten homepage title from 72 to 55 characters" is good.
 6. **H/M/L priorities only** — no fictional formulas. Real keyword data is a Cloud upgrade.
-7. **Always end with choices.** Every response ends with numbered next steps (2-3 max).
+7. **End with the plan's next step, not a menu.** When executing an approved plan, close with progress + what's next in the plan ("3 of 8 in this cluster done; writing the next now"), not a 2–3-option menu every turn. Offer explicit choices only at real decision points (the plan-approval gate, a cluster boundary, an ambiguous call).
 8. **Update the roadmap and changelog** after every action.
 9. **Sync after every artifact write.** Run `seoagent sync` (no-op when not logged in — always run it).
 10. **WebFetch before reporting missing.** Never say a URL is missing without fetching it live first.
 11. **Use the output template** for all top-level reports.
 12. **Read context before generating.** Before any strategy, brief, or article, read `.seoagent/context.md`.
-13. **Confirm between phases** with `Continue? (y/n)` — auto-progress within a phase, never across.
+13. **Plan once, then execute** (see "Plan & Execute"). Get one approval on the content plan, then run it in batches (a cluster at a time) — don't ask `Continue?` between articles or phases. Pause only for: the plan approval, cluster boundaries (show drafts + open a PR), ambiguous decisions, and destructive actions. Go fully autonomous or step-by-step if the user asks.
 14. **Hub-and-spoke linking is mandatory** — sub_pillars link UP to pillar; long_tails link UP to parent sub_pillar; pillars link DOWN to all sub_pillars.
 15. **Edit existing files; Write only new ones.** `project.md`, `context.md`, `roadmap.md`, `changelog.md`, and any artifact created by `init` already exist — use the `Edit` tool to modify them. Reserve `Write` for files that don't exist yet. Trying to `Write` an existing file fails with "File must be read first" and wastes a tool call.
 16. **Use the CMS metadata.** If `project.md` has `cms: strapi | wordpress | sanity | contentful | ghost | webflow | shopify | payload | directus | mdx-local`, the user has a CMS. When writing articles in Phase 4, mention how the article's frontmatter maps to that CMS's content model (e.g. Strapi: title → Title field, body → Content rich-text). When the cluster is content-focused, suggest publishing the article to the detected CMS as the next step. The free tier writes to `.seoagent/content/` only — Cloud handles the publish itself.