@seoagent-official/seoagent 1.75.0 → 1.76.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.75.0",
+  "version": "1.76.1",
   "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

@@ -8,8 +8,12 @@ Loaded by Phase 1 (Technical SEO Audit) when running a full audit. The main `SKI
 
 **Origin binding — the crawl must hit the LIVE site the user designated, and evidence.md records which origin it hit.** If the user/session provided a live URL, pass it verbatim: `seoagent crawl --url <origin>` (authoritative even when loopback — staging/preview is legitimate); otherwise the CLI uses `live_url:`/`domain:` from `project.md`, and errors if neither exists — never guess, and **never start a local dev server and crawl it as the live site**. Check the **"Crawled origin:"** line at the top of `evidence.md` before deriving findings: if the file is labeled **SOURCE RENDER (local dev server) — NOT the public live site** (`source_render: true`), it describes an undesignated local render — NO live-state finding (`Confirmed` present OR absent) may be derived from it, and `seoagent verify-recs` will refuse to verify against it. Re-crawl with `--url <live origin>` first.
 
+**An incomplete capture makes every finding a LOWER BOUND.** If `evidence.md` contains a **"Pages NOT captured"** section (`capture_complete: false` in its frontmatter), the crawl discovered pages it could not fetch — after per-page retries and a sequential re-fetch. The rollup and per-page findings then describe only the captured subset: report the code-generated "N discovered pages could not be crawled — evidence is incomplete" finding verbatim, state the incompleteness (and each failure reason) in the audit and final summary, and never treat an uncaptured page as passing any check — no claim about it (present OR absent) is Confirmed.
+
 **The evidence covers the whole crawl, not just the homepage — audit accordingly.** The crawl discovers subpages from the live sitemap + homepage nav links (default 15 pages) and writes a per-page section for **EVERY page in `evidence.md`**, plus a **`## Site-wide rollup`** section that aggregates the per-page gaps: *Pages missing canonical*, *Pages missing meta description*, *Pages with multiple H1s*, *Pages with no structured data*, and *Images missing alt* (total + per-page counts with the offending srcs). Run the per-page checks below against **every crawled page** — a subpage's missing canonical or a blog post's missing meta description is exactly what the rollup lists — and report those findings from the rollup + per-page sections, never from homepage-only inspection or guesswork.
 
+**The crawl also writes `.seoagent/audit/findings.md` — the complete, code-generated findings baseline. Your audit builds on it.** It derives one human-readable finding per confirmed rollup issue (affected URLs, why it matters, suggested fix, `Confirmed` label, `Evidence:` citation), including client-rendered shells, sitemap coverage gaps, robots.txt facts, and broken crawled URLs. Treat it as the completeness floor: `audit/latest.md` adds GSC cross-referencing, prioritization, and strategy ON TOP of findings.md — it must carry **every** finding forward (**never re-derive from scratch, never truncate**), and the final message lists every finding title (`seoagent summary` does this mechanically via its "Technical findings (from live crawl)" section). Session economy applies to bookkeeping, never to findings completeness. Items findings.md lists under **"Already present on the live site"** must never become "add X" recommendations — when the repo source lacks something the live page serves, the **repo source is stale — the live page already serves it; reconcile the source**.
+
 Three rules govern every finding:
 
 1. **Confidence label (mandatory on every finding).** Tag each finding `Confirmed` (verified against the live evidence in `evidence.md` / a fetch you just did), `Likely` (strong inference, not directly verified), or `Hypothesis` (unverified). **Never emit an unverified specific — a price, a line number, a competitor name/roster, a dynamic on-page metric — as a bare fact.** A "2,184 families" style counter that is NOT in the server-fetched HTML is at most `Likely`/`Hypothesis`, never `Confirmed`.

package/skills/seoagent.md

@@ -403,6 +403,8 @@ Every session has a budget — headless/one-shot runs have a hard turn cap, inte
 4. **Reserve the final turns for the wrap-up.** When the work above is done, end the session with exactly two steps: `seoagent verify-recs` (pass any work-log files written outside `.seoagent/` — the sync hook already covers `.seoagent/` itself) and then **`seoagent summary`**, whose output is what you present as the final message (see "Ending a Session" below). **No new workstreams after the summary** — do not open a new work stream (another audit pass, another content draft) you cannot finish inside the budget. An unfinished extra stream plus a missing summary is worth less than a complete summary.
 5. **Prefer editing an existing file over creating a new one** when appending related content. Fewer files means fewer writes, fewer sync round-trips, and a workspace the next session can actually read.
 
+**Session economy applies to bookkeeping, never to findings completeness.** The rules above trim churn — file-write sprawl, re-polish loops, per-item status ticks — they never license dropping findings. Reporting **every confirmed finding** from `.seoagent/audit/findings.md` (every title in the final message at minimum; full detail by reference to the file) is **non-negotiable**: a terse report that omits confirmed findings is a failed session, not an economical one. `seoagent summary` makes this mechanical — its "Technical findings (from live crawl)" section lists every finding title, and that list is never truncated.
+
 These are general bounded-session economics, not a benchmark mode — in an interactive session the same rules simply make you faster and the workspace cleaner.
 
 ## Ending a Session — the final message comes from `seoagent summary`
@@ -410,6 +412,7 @@ These are general bounded-session economics, not a benchmark mode — in an inte
 **The final message of any audit/optimization session must be built by running `seoagent summary` and presenting its output — not from memory.** Files are mechanically corrected by verify-recs, but a chat message isn't a file: restating findings from memory is exactly how a corrected claim ("added Organization JSON-LD — none existed") sneaks back into the summary after the file said otherwise. `seoagent summary` composes the deliverable from the corrected on-disk state:
 
 - the top findings quoted verbatim from `.seoagent/audit/latest.md` (with their confidence labels and `Evidence:` citations),
+- a **"Technical findings (from live crawl)"** section listing EVERY finding title from the code-generated `.seoagent/audit/findings.md` (full detail stays in the file) — relay all of them; this list is the completeness floor and is never trimmed for brevity,
 - every `CORRECTION (verify-recs)` line — relay the corrected framing, never the original claim,
 - the migration plan's harvest/redirect/sunset table when `.seoagent/strategy/migration-plan.md` exists,
 - the top open roadmap items,
@@ -429,6 +432,10 @@ Run it as the session's last command (`seoagent summary`, or `--json` to branch
    - **NEVER start a local dev server yourself and crawl it as the live site.** A dev server renders the repo's current state, which can differ from production in either direction — evidence captured from it would make every "Confirmed absent/present" claim false about the real site. If you crawl an origin the CLI wasn't told is live, `evidence.md` is labeled **SOURCE RENDER (local dev server) — NOT the public live site**, and no live-state claim may be derived from it.
 
    The crawl fetches the homepage + top pages, the real robots.txt, and the live sitemap, and writes `.seoagent/audit/evidence.md` — the verified evidence base (exact title/meta, ALL H1s, canonical + server/client-render flag, every JSON-LD `@type`, OG/Twitter tags, the ACTUAL robots.txt contents, sitemap URL + blog-post counts, client-rendered-shell detection), with the **crawled origin recorded at the top** — check it matches the site you're auditing. **`Read` that file — every `Confirmed` finding must be derived from it, not from repo source or memory.** (Use `seoagent crawl --json` if you want the structured bundle.)
+
+   The crawl also generates **`.seoagent/audit/findings.md`** — a code-built technical findings report: one finding per confirmed issue in the evidence (affected URLs, why it matters, suggested fix, `Confirmed` label, `Evidence:` citation), covering the full surface — missing canonicals, missing meta descriptions, multiple H1s, images without alt (with srcs), pages with no structured data, client-rendered shells, sitemap coverage gaps, robots.txt facts, and broken crawled URLs. **Your audit (`audit/latest.md`) builds on `findings.md`** — carry every finding in it forward (add GSC cross-referencing, prioritization, and strategy on top; re-grade severity with context where justified) and **never re-derive the technical findings from scratch, never truncate the list**. A finding present in `findings.md` but absent from your audit and final summary means the audit is incomplete. Items its "Already present on the live site" section lists must never become "add X" recommendations — when the repo source lacks something the live page serves, the repo source is stale; reconcile the source.
+
+   **Incomplete capture = incomplete evidence (check this FIRST).** If `evidence.md` has a **"Pages NOT captured"** section (frontmatter `capture_complete: false`), the crawl discovered pages it could not fetch — every finding and rollup in the evidence is then a **LOWER BOUND, not a complete picture**. Treat it that way explicitly: relay the code-generated "could not be crawled — evidence is incomplete" finding, state in your audit and final summary that N discovered pages were not captured (with their failure reasons), and never treat an uncaptured page as passing any check — no claim about those pages, present OR absent, is Confirmed. If the failures look transient (timeouts/network errors), re-run `seoagent crawl` once before finalizing.
 2. **Read `.claude/skills/seoagent/references/audit-checks.md`.** It contains the full check list, the **Verify-before-assert** rules (confidence labels, never-recommend-what-exists, live-vs-source reconciliation), severity tiers, and recommendation text per check. Do not run the audit from memory — the reference is the source of truth and gives consistent results across sessions.
 
 3. **Step 0 is not optional and not "when useful" — it is the gate for ALL live-state work.** Any audit, technical-SEO review, "what's wrong with my site", or "add schema/meta/canonical" request starts with `seoagent crawl` — even a quick one, even when the repo source looks obvious. The crawl now covers the homepage **plus subpages discovered from the live sitemap + homepage nav links** (default 15 pages, fetched concurrently), so it's fast and it sees the blog posts and subpages where the real gaps hide. **No live-state claim and no "add X" recommendation may be emitted unless `.seoagent/audit/evidence.md` exists, covers the target page(s), and the claim cites it.** If `evidence.md` is missing or stale (>24h old — `seoagent doctor` flags this as `evidence_stale`), re-run the crawl before asserting anything. Reasoning from the repo source about what the live site serves is exactly the failure this gate exists to stop: the repo may be behind (or ahead of) production.
@@ -1008,7 +1015,7 @@ The CLI manages credentials at `~/.config/seoagent/auth.json` — outside the pr
 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.
 17. **Use the blog_path metadata.** If `project.md` has `blog_path: /blog` (or similar), articles' canonical URLs use that prefix: `https://{domain}{blog_path}/{slug}`.
-18. **Respect the session budget** (see "Session Economy — bounded sessions"). Target under ~60 turns and under ~20 new files per session; consolidate writes, batch bookkeeping into one final update and batch multi-file code edits, scope single-session asks to audit + plan + top fixes, and reserve the final turns for `seoagent verify-recs` + `seoagent summary` (see "Ending a Session") — no new workstreams after the summary, and never start one you can't finish.
+18. **Respect the session budget** (see "Session Economy — bounded sessions"). Target under ~60 turns and under ~20 new files per session; consolidate writes, batch bookkeeping into one final update and batch multi-file code edits, scope single-session asks to audit + plan + top fixes, and reserve the final turns for `seoagent verify-recs` + `seoagent summary` (see "Ending a Session") — no new workstreams after the summary, and never start one you can't finish. The budget trims bookkeeping, never findings: every confirmed finding in `.seoagent/audit/findings.md` is reported (title at minimum), no matter how tight the session.
 
 ---