@seoagent-official/seoagent 1.65.0 → 1.66.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.65.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.",
+  "version": "1.66.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": {
     "seoagent": "index.js"
@@ -48,7 +48,9 @@
     "keyword-research",
     "internal-links",
     "schema-markup",
-    "autopilot"
+    "autopilot",
+    "product-screenshots",
+    "saas-seo"
   ],
   "license": "MIT",
   "homepage": "https://seoagent.com",

package/skills/references/audit-checks.md

@@ -2,6 +2,20 @@
 
 Loaded by Phase 1 (Technical SEO Audit) when running a full audit. The main `SKILL.md` summarizes the categories; this reference holds the complete check list with the exact pattern to match and the recommendation text.
 
+## Verify-before-assert (read first — non-negotiable)
+
+**Every factual claim about a page's live state must be grounded in an actual fetch of the live URL — never in repo source, memory, or a prior.** Before running these checks, run `seoagent crawl` (Phase 1 Step 0). It writes `.seoagent/audit/evidence.md` — the live-crawl evidence base (exact title, meta, ALL H1s, canonical + server/client-render flag, every JSON-LD `@type`, OG/Twitter tags, the ACTUAL robots.txt contents, the sitemap URL + blog-post counts, client-rendered-shell detection). Read that file and derive Confirmed findings from it.
+
+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`.
+
+2. **Never recommend adding something that already exists.** If `evidence.md` shows the page already serves `Organization` JSON-LD, a canonical tag, OG tags, etc., do NOT recommend adding them — that's the stale-source hallucination this guardrail exists to stop. Only recommend adding what the live evidence shows is genuinely absent.
+
+3. **Live-vs-source reconciliation.** When repo/source state and the live-rendered page can disagree, grade the finding against the LIVE site. A repo-only issue (e.g. a `noindex` in a source file that isn't in the served HTML, a robots rule in a committed file that the live `/robots.txt` doesn't serve) must be labeled **"repo-only, unconfirmed on live"** and reported separately — never as production reality.
+
+**Do not assert repo-internal specifics (file paths, line numbers) as fact in a live-state finding.** They are fixing *hints*, not verified live facts — mark them `Likely` and phrase as "likely in `app/layout.tsx`", never "on line 42".
+
 ## Crawlability & Indexation
 
 ### `robots_txt_exists`
@@ -10,9 +24,9 @@ Severity if fail: `high`
 Recommendation: "Create a robots.txt file at {domain}/robots.txt. At minimum: `User-agent: *\nAllow: /\nSitemap: {domain}/sitemap.xml`."
 
 ### `robots_txt_blocks_important_paths`
-Check: parse robots.txt for `Disallow:` directives. Match against the URL list in `pages.md`.
+Check: use the ACTUAL robots.txt contents from `evidence.md` (the crawl fetched and parsed the live file). Match its real `Disallow:` rules against the URL list in `pages.md`.
 Severity: `critical` if blocks > 5 known important pages; `high` if blocks any important page.
-Recommendation: List the blocking rules and which pages they affect.
+Recommendation: List **only the blocking rules that actually appear in the fetched robots.txt** and which pages they affect. **Never invent a rule** (e.g. do NOT claim `Disallow: /private/` unless it is verbatim in the fetched file) — quoting a rule that isn't there is the exact hallucination this audit must avoid. If robots.txt wasn't fetched, this check is `Hypothesis` — say "couldn't verify robots.txt" rather than asserting any rule.
 
 ### `sitemap_exists`
 Check: WebFetch `{domain}/sitemap.xml`. Pass = 200 OK and parseable XML.
@@ -67,6 +81,11 @@ Recommendation: "{dependency_url} returned {status}. The pages it powers ({list}
 
 > **Why this check matters:** the most common SEO disaster on a live site is a CMS that's been quietly down for weeks — every page returns 200, the audit looks clean, but Google has been deindexing the blog the whole time. This check catches it on the first audit.
 
+### `client_rendered_shell`
+Check: `evidence.md` flags the page as a client-rendered shell — the server HTML is near-empty and/or shows a "Loading…" placeholder with no in-body links. The classic case is a blog index that ships a `Loading…` shell with no post `<a>` links in the server HTML: crawlers (and this fetch) see zero posts.
+Severity: `critical` if it's a content-listing / blog-index / indexable page; `high` otherwise.
+Recommendation: "This page renders client-side — the server HTML has no content/links, so crawlers can't see it (Confirmed from the crawl). Server-render or pre-render it (SSR/SSG/ISR) so the {posts/listings} are in the initial HTML. Any on-page data on this page (counts, listings) is Likely/Hypothesis until it's server-rendered."
+
 ## On-Page SEO
 
 ### `title_missing`
@@ -105,9 +124,9 @@ Severity: `high`
 Recommendation: "Add exactly one `<h1>` containing the primary keyword."
 
 ### `h1_multiple`
-Check: more than one `<h1>` in body.
+Check: `evidence.md` lists more than one `<h1>` for the page (it captures ALL H1s in document order, so conflicting H1s are detected).
 Severity: `medium`
-Recommendation: "Reduce to one `<h1>`. Demote others to `<h2>` or `<h3>`."
+Recommendation: "Page has {N} `<h1>`s ({list}). Reduce to one; demote the others to `<h2>`/`<h3>`."
 
 ### `heading_hierarchy_skipped`
 Check: H1 → H3 with no H2 between, or H2 → H4 with no H3.
@@ -141,6 +160,11 @@ Check: `<img>` tags without `alt=""` attribute (decorative images should have em
 Severity: `medium` if > 3 images; `low` otherwise.
 Recommendation: "Add descriptive alt text to {N} images. SEOAgent can write these — `seoagent.js` does it automatically on production."
 
+### `missing_product_screenshots`
+Applies only when `project.md` has `site_type: saas` (or the repo renders a real product UI). Check: a landing / feature / how-to page that describes the product but has **no real product screenshot** in its hero or feature sections (illustration-only, stock photo, or no image where a UI shot belongs).
+Severity: `low` (a conversion + trust gap, not an indexation issue).
+Recommendation: "Add a real product screenshot to the hero + feature sections — read `references/screenshots.md` to capture them from the product's own code in this repo. Real UI shots out-convert AI illustrations on a SaaS page."
+
 ### `internal_links_count`
 Check: number of `<a>` tags pointing to same-domain URLs in body.
 Severity: `medium` if 0 (orphan); `low` if < 3.
@@ -197,18 +221,20 @@ Recommendation: "Add an FAQ section with 5-7 H3 questions. Powers FAQ schema and
 
 ## Schema Markup
 
+> **Schema checks MUST use `evidence.md`, not WebFetch.** WebFetch strips `<script>` tags — it CANNOT see JSON-LD, so "no schema found" from WebFetch is a false negative that leads directly to recommending schema the page already serves. The `seoagent crawl` evidence base parses raw HTML and lists every JSON-LD `@type` present per page. Read that. **Only flag a schema type as missing when `evidence.md` shows it is genuinely absent — never recommend adding a `@type` that already appears in the evidence.**
+
 ### `no_json_ld_on_article`
-Check: page is a blog article (URL pattern `/blog/*`) but page HTML has no `<script type="application/ld+json">` Article schema.
+Check: page is a blog article (URL pattern `/blog/*`) AND `evidence.md` shows **no `Article` (or `BlogPosting`/`NewsArticle`) `@type`** for it.
 Severity: `medium`
-Recommendation: "Add `Article` JSON-LD with headline, author, datePublished, dateModified, image, publisher.logo. See `references/schema-markup.md`."
+Recommendation (only if genuinely absent): "Add `Article` JSON-LD with headline, author, datePublished, dateModified, image, publisher.logo. See `references/schema-markup.md`."
 
 ### `no_organization_schema_on_homepage`
-Check: homepage has no `Organization` schema.
+Check: `evidence.md` shows the homepage has **no `Organization` `@type`** (and no `SoftwareApplication`/`WebSite` that would already cover the brand entity). If the evidence lists `Organization`/`SoftwareApplication`, this check PASSES — do not recommend adding it.
 Severity: `medium`
-Recommendation: "Add `Organization` JSON-LD on homepage with name, url, logo, sameAs links to social profiles."
+Recommendation (only if genuinely absent): "Add `Organization` JSON-LD on homepage with name, url, logo, sameAs links to social profiles."
 
 ### `note_schema_detection_limitation`
-WebFetch strips `<script>` tags including JSON-LD. After auditing, always tell the user: "Test your pages at https://search.google.com/test/rich-results for accurate schema validation — WebFetch can't see your JSON-LD blocks directly."
+Schema is verified from `evidence.md` (raw-HTML JSON-LD parse), not WebFetch. If the crawl couldn't run, treat any "no schema" conclusion as `Hypothesis` and tell the user: "Test your pages at https://search.google.com/test/rich-results — I couldn't verify JSON-LD via WebFetch (it strips `<script>` blocks). Run `seoagent crawl` for a verified read."
 
 ## Site Architecture
 

package/skills/references/landing-pages.md

@@ -145,6 +145,8 @@ Landing pages need:
 - 2-4 feature/inline images — actual screenshots, not stock photography
 - 1 OG image — branded, includes product name and value prop, 1200×630
 
+**For a SaaS / product site, the hero + feature images should be real product screenshots — read `references/screenshots.md`** for how to capture them from the product's own code in this repo (no Playwright/paid API) and where to place them. Real UI shots out-convert AI illustrations on a SaaS landing page; only fall back to a generated image when a screenshot isn't possible.
+
 In article frontmatter:
 ```yaml
 images:

package/skills/references/rewrite-protocol.md

@@ -125,6 +125,7 @@ Same protocol but:
 - Don't ship the rewrite during a campaign in flight — coordinate with the user
 - Update OG card and Twitter card alt text (often forgotten)
 - Update JSON-LD `Product` / `Offer` if pricing or feature claims changed
+- **Screenshot-gap pass (SaaS sites):** during the diagnosis (Step 3), scan the page for hero/feature sections that describe the product but show no real screenshot (illustration-only, stock, or empty). For each gap, capture a real product screenshot from this repo's UI per `references/screenshots.md` and fold it into the rewrite — this is how an *existing* SaaS landing page gets the screenshots it's missing.
 
 ### Rewriting Without an Existing Brief
 

package/skills/references/screenshots.md

@@ -0,0 +1,83 @@
+# Product Screenshot Protocol
+
+Use when the site is a **SaaS / product app** and a page or article would be stronger with a **real screenshot of the product's UI**. A genuine product screenshot is the single highest-converting visual on a SaaS landing page or how-to article — it beats AI illustrations and stock photography every time.
+
+**You capture these yourself, from the product's own code in this repo.** No Playwright/Puppeteer dependency, no paid screenshot API — use the screenshot capability already available in your environment (a connected browser/preview tool, or the project's own dev server). If you have no way to capture, fall back gracefully (see **Fallback**) — never block a page on a screenshot.
+
+## When this applies (SaaS gate)
+
+Only pursue product screenshots when **both** are true:
+
+1. **The site is a SaaS / product app**, not a content/local/services site. Confirm from the repo, which is the ground truth:
+   - `project.md` has `site_type: saas`, **or**
+   - the repo renders a real UI (an app shell, dashboard, feature components under `app/`, `src/components/`, etc.) — a product you could screenshot.
+   - A plumber's blog, a media site, or a pure-marketing repo with no product UI → **skip this protocol**.
+2. **A specific spot would be stronger with a UI shot and doesn't have one** (see Gap Evaluation).
+
+If the cloud queued an action whose body has a **"Screenshots to capture"** section, the SaaS gate is already a yes — go straight to Gap Evaluation + Capture.
+
+## Where product screenshots add value
+
+| Page / section | Shot to capture |
+|---|---|
+| Landing **hero** | The product's primary screen (dashboard, main view) — the "this is the thing" shot |
+| Landing **feature deep-dives** | The specific UI for each feature being described (one shot per feature section) |
+| **How-to / tutorial** article steps | The screen the step is describing — capture the actual state for that step |
+| **Comparison** pages | The product's UI for the capability being compared |
+
+Don't over-shoot: 1 hero + 2–4 feature shots is the sweet spot for a landing page. A how-to gets one shot per major step that has a UI.
+
+## Gap Evaluation (new pages AND existing ones)
+
+Scan the page for **missing visuals** — places where the reader is asked to imagine UI that you could just show:
+
+- A feature `<section>` / feature block describing the product with **no image**.
+- A how-to step ("Click **Connect**", "Open the dashboard") with **no screenshot** of that screen.
+- A landing **hero** with no product shot (or a stock/illustration placeholder where a real screen belongs).
+- Prose like "see the X view", "your dashboard shows…", "the editor lets you…" with nothing to look at.
+
+Each gap that passes the SaaS gate is a screenshot to capture. When auditing/refreshing an **existing** landing page, this same scan is how you find screenshots to add — fold the gaps into the rewrite (see `references/rewrite-protocol.md`).
+
+## Capture
+
+1. **Find the route/component** in this repo that renders the UI you want — the page route (e.g. `app/dashboard/page.tsx`, a feature page) or a self-contained component you can render in isolation.
+2. **Render it.** Detect the project's dev command from `package.json` `scripts` (`dev`, then `start`) and start it (or reuse a server that's already running). Note the local URL (e.g. `http://localhost:3000/<route>`).
+3. **Capture a PNG** of the rendered route using the screenshot capability available in your environment. Frame/crop to the relevant UI — show the feature, not the whole browser chrome. Use a clean state (seeded/demo data, no personal info, no error toasts).
+   - **Do NOT** add Playwright/Puppeteer to the project, and **do NOT** call a paid screenshot API just for this. Use what's already available.
+4. **Save it** to the repo's public asset directory — detect the convention (`public/screenshots/`, `static/screenshots/`, `assets/`) and create `screenshots/` there if absent. Name it `{page-slug}-{section}.png` (e.g. `pricing-hero.png`, `seo-audit-feature.png`).
+5. **Reference it** in the page/article with descriptive, keyword-aware alt text and responsive markup that matches how the site embeds images (Next.js `<Image>`, MDX `![alt](path)`, an existing image component — match the site's pattern). Alt text describes the screen + the keyword, e.g. `alt="SEOAgent dashboard showing a completed technical SEO audit with severity badges"`.
+
+## Frontmatter
+
+When the page uses `images:` frontmatter (landing pages, content), record the screenshot as a captured asset, not an AI prompt:
+
+```yaml
+images:
+  hero:
+    alt: "SEOAgent dashboard showing a completed audit with green/red severity badges"
+    src: /screenshots/dashboard-hero.png      # captured product screenshot (preferred for SaaS)
+  inline:
+    - alt: "The keyword research view with volume and difficulty columns"
+      src: /screenshots/keywords-feature.png
+      placement: "after H2 'Keyword research'"
+```
+
+`src` = a real captured screenshot. Fall back to `prompt:` (AI image) only when a screenshot isn't possible.
+
+## Fallback (never block the page)
+
+If the product can't be rendered/captured (no dev server, no screenshot tool available, the route needs auth you don't have, or there's no real UI yet):
+
+- Leave a marker where the shot belongs so the gap is visible and actionable later:
+  ```html
+  <!-- SCREENSHOT-TODO: capture the {feature} screen at {route} and place here -->
+  ```
+- Also write an AI image `prompt:` into the frontmatter (existing flow in `references/landing-pages.md` → Images) so publishing still succeeds with *some* visual.
+- Mention to the user in one line what you couldn't capture and why, so they can run the dev server / point you at the right screen.
+
+## Conventions
+
+- One folder for captures (`public/screenshots/` or the repo's equivalent) — don't scatter PNGs.
+- Real, current UI only — never fabricate a screenshot or reuse a competitor's.
+- No PII / no real customer data in the frame — use demo/seed state.
+- Re-capture when the UI changes materially (a feature redesign stales old shots) — the Gap Evaluation on a refresh catches this.

package/skills/seoagent.md

@@ -1,6 +1,6 @@
 ---
 name: seoagent
-description: "Persistent AI SEO agent. ALWAYS use when the user mentions: SEO, ranking, rank, keywords, meta tags, search traffic, organic traffic, content strategy, audit, Google, Bing, Search Console, GSC, schema markup, JSON-LD, sitemap, robots.txt, internal linking, AI search, AEO, GEO, OKF, Open Knowledge Format, AI knowledge bundle, llms.txt, alt text, page speed, Core Web Vitals, slug, URL structure, canonical, breadcrumbs, hub and spoke, pillar content, topic cluster, programmatic SEO, landing page SEO, blog SEO, listicle, best-of / top-N roundup, why am I not ranking. Also use SILENTLY when the user asks to write, edit, or improve a blog post, landing page, marketing copy, or any file under content/, posts/, blog/, pages/ — these are SEO-adjacent and should persist to .seoagent/ even without an explicit invocation. Replaces separate seo-audit, content-strategy, programmatic-seo, ai-seo, site-architecture, and schema-markup skills with one unified, persistent workflow."
+description: "Persistent AI SEO agent. ALWAYS use when the user mentions: SEO, ranking, rank, keywords, meta tags, search traffic, organic traffic, content strategy, audit, Google, Bing, Search Console, GSC, schema markup, JSON-LD, sitemap, robots.txt, internal linking, AI search, AEO, GEO, OKF, Open Knowledge Format, AI knowledge bundle, llms.txt, alt text, page speed, Core Web Vitals, slug, URL structure, canonical, breadcrumbs, hub and spoke, pillar content, topic cluster, programmatic SEO, landing page SEO, blog SEO, listicle, best-of / top-N roundup, product screenshots, SaaS screenshots, why am I not ranking. Also use SILENTLY when the user asks to write, edit, or improve a blog post, landing page, marketing copy, or any file under content/, posts/, blog/, pages/ — these are SEO-adjacent and should persist to .seoagent/ even without an explicit invocation. Replaces separate seo-audit, content-strategy, programmatic-seo, ai-seo, site-architecture, and schema-markup skills with one unified, persistent workflow."
 allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch
 ---
 
@@ -43,6 +43,7 @@ This SKILL.md is the orchestration layer. Detailed protocols live in `references
 | Writing a sub-pillar article | `references/sub-pillar-articles.md` |
 | Writing a long-tail article | `references/long-tail-articles.md` |
 | Writing a listicle ("Top N" / "Best X") | `references/listicle-articles.md` |
+| Adding **product screenshots** to a SaaS page/article (or a "Screenshots to capture" inbox action) | `references/screenshots.md` |
 | Programmatic SEO at scale | `references/programmatic.md` |
 | Adding schema markup / JSON-LD | `references/schema-markup.md` |
 | Refreshing or rewriting an existing page | `references/rewrite-protocol.md` |
@@ -166,6 +167,7 @@ Offer **once per session per topic**; if declined, drop it and keep working. Nev
    - `Read` it. The frontmatter has `action_id`, `brief_slug`, `primary_keyword`, `cluster`, and `priority`. The body points at the synced brief.
    - **Read the full brief** under `.seoagent/` (briefs file or `strategy/` entry matching `brief_slug`) for the outline, word-count target, and internal-link plan.
    - Write the article following the skill's **content-production protocol** (Phase 4 below), then publish it where this project's content lives (repo `content/` or the connected CMS — you are the publishing engine). Show the user the draft before publishing.
+   - **If the action body has a "Screenshots to capture" section** (autopilot flagged this as a SaaS product), follow `references/screenshots.md` — capture real product screenshots from this repo's UI for the relevant sections instead of shipping illustration-only.
    - Acknowledge it: `seoagent ack <action_id>` (or `--failed --reason "skipped; off-strategy"` to decline).
 
 5. For each `cli_content_update-<id>.md` file:
@@ -185,6 +187,7 @@ Offer **once per session per topic**; if declined, drop it and keep working. Nev
    - Cross-reference `.seoagent/keywords.md` for related keywords — they tell you which cluster this page belongs to and which secondary keywords to weave in.
    - Pick an article type from `intent` (commercial/transactional → product or comparison page; informational → guide or pillar). Pick a clean URL slug from `keyword`.
    - Write the article following the skill's **content-production protocol** (Phase 4 — match the article type's quality rules, add internal links from related cluster pages, etc.). Show the user the draft before publishing.
+   - **If the action body has a "Screenshots to capture" section** (SaaS product), follow `references/screenshots.md` — a landing page for a SaaS product should lead with a real product screenshot in the hero + feature sections, captured from this repo's UI.
    - Publish where this project's content lives (repo `content/` or the connected CMS). Safe (new content) — but still confirm the user wants this specific page before committing.
    - Acknowledge it: `seoagent ack <action_id>` (or `--failed --reason "already covered by /existing-page"` to decline).
 
@@ -389,9 +392,12 @@ Once approved, work **a cluster at a time**, top of the plan down:
 
 ## Phase 1: Technical SEO Audit
 
-### Step 0 (mandatory)
+### Step 0 (mandatory — capture the live-crawl evidence base, then read the checks)
 
-**Read `.claude/skills/seoagent/references/audit-checks.md` before any WebFetch.** It contains the full check list with 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.
+1. **Run `seoagent crawl` first.** It 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). **`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.)
+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.
+
+**Verify-before-assert is the load-bearing rule of the whole audit.** Never state a live-page fact you didn't fetch: don't invent a robots.txt rule, don't recommend adding schema/canonical/OG tags the evidence shows already exist, don't report a dynamic on-page number (a "2,184 families" counter) as `Confirmed` unless it's in the server-fetched HTML. Tag every finding `Confirmed` / `Likely` / `Hypothesis`. If `seoagent crawl` couldn't run (offline, no domain), fall back to per-page WebFetch — but remember WebFetch strips `<script>`, so schema conclusions from it are `Hypothesis`, never `Confirmed`.
 
 ### Procedure
 
@@ -451,7 +457,7 @@ When the user says "I fixed X":
 2. Append to `changelog.md`: `[date] Fixed: {finding}`.
 3. Run `seoagent sync`.
 
-> **Rule**: Before reporting any URL is missing or broken, always WebFetch the live URL first. Never assume a 404 from inference alone.
+> **Rule (verify-before-assert)**: Before reporting ANY live-state fact — a URL is missing/broken, robots.txt blocks a path, a page lacks schema, a title/H1/canonical value — it must be grounded in an actual fetch (`seoagent crawl`'s `evidence.md`, or a WebFetch you just ran). Never assume a 404, a robots rule, or a missing schema from inference/repo source alone. Every finding carries a confidence tag (`Confirmed`/`Likely`/`Hypothesis`); unverified specifics (prices, line numbers, competitor names, dynamic counters) are never emitted as bare fact.
 
 ---
 
@@ -737,9 +743,13 @@ This is the per-article procedure. When executing an approved **plan** (see "Pla
    - **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.
 
+### Product Screenshots (SaaS — do this before AI images)
+
+**If `project.md` has `site_type: saas` (or the repo renders a real product UI), prefer real product screenshots over AI illustrations** — they're the highest-converting visual on a SaaS landing page or how-to article. Before falling back to a generated image, **read `references/screenshots.md`** and follow it: scan the page for spots where a UI shot would add value and is missing (hero, feature sections, how-to steps), then capture those screens **from the product's own code in this repo** (using your environment's screenshot capability + the project's dev server — no Playwright/Puppeteer dependency, no paid API), save them under `public/screenshots/`, and reference them with descriptive alt text. If you can't capture (no dev server / no screenshot tool / no real UI), the protocol's fallback leaves a `<!-- SCREENSHOT-TODO -->` marker + an AI image prompt so publishing still works. Non-SaaS sites skip this and go straight to image generation below.
+
 ### Image Generation (Free Tier)
 
-Always write `images:` frontmatter with `alt` and `prompt`. Then resolve a provider — **don't silently ship imageless articles:**
+Always write `images:` frontmatter with `alt` and `prompt` (or `src` for a captured screenshot — see Product Screenshots above). Then resolve a provider — **don't silently ship imageless articles:**
 
 1. **If `project.md` has `image_provider` set to `openai|fal|replicate`**, offer to generate the hero image:
 
@@ -904,7 +914,7 @@ The CLI manages credentials at `~/.config/seoagent/auth.json` — outside the pr
 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.
+10. **Verify before you assert.** Every claim about a page's live state (robots.txt rules, schema/JSON-LD, meta tags, titles, headings, canonical, sitemap contents, whether a URL exists) must be grounded in an actual live fetch — `seoagent crawl`'s `.seoagent/audit/evidence.md` or a WebFetch you just ran — never repo source, memory, or a prior. **Never recommend adding something the live page already has.** Tag every finding `Confirmed` / `Likely` / `Hypothesis`; never emit an unverified specific (price, line number, competitor, dynamic on-page metric) as a bare fact. Repo-only issues that aren't confirmed on the live site are labeled and reported separately, not as production reality.
 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. **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.