@seoagent-official/seoagent 1.65.0 → 1.66.0

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.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": {
     "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

@@ -141,6 +141,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.

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).
 
@@ -737,9 +740,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: