@seoagent-official/seoagent 1.133.1 → 1.134.0

package/package.json

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

@@ -201,7 +201,7 @@ Recommendation: "Add ~{target - current} words of substantive content. Target 80
 ### `keyword_not_in_first_100_words`
 Check: primary keyword (from brief if available, inferred from title otherwise) appears in body before word 100.
 Severity: `medium`
-Recommendation: "Move the primary keyword `{keyword}` into the first paragraph for AI-extractability."
+Recommendation: "Move the primary keyword `{keyword}` into the first paragraph for AI-extractability (on a designed page: into the existing hero copy)."
 
 ### `images_without_alt`
 Check: `evidence.md` — each page section's **images** line (`N total, M missing alt` + the first offending srcs) and the rollup's *Images missing alt* total. The crawl extracts `<img>` tags with no `alt` attribute from the server HTML (`alt=""` on decorative images counts as present). Do NOT conclude alt coverage from WebFetch or repo source — report the counts + srcs the evidence lists, per page.
@@ -211,7 +211,7 @@ Recommendation: "Add descriptive alt text to {N} images on {page} (starting with
 ### `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."
+Recommendation: "Add a real product screenshot to the hero + feature sections, in their existing image slots — read `references/screenshots.md` to capture them from the product's own code in this repo. Never add a new section to hold one. 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.
@@ -260,7 +260,7 @@ Recommendation: "Robots.txt blocks AI crawlers ({list}). If you want to be cited
 ### `no_extractable_answer_block`
 Check: page has primary keyword in title/H1 but no paragraph in the first 200 words that directly answers the keyword's intent.
 Severity: `medium`
-Recommendation: "Lead with a definition or direct answer in the first paragraph (40-80 words) so AI search engines can extract it."
+Recommendation: "Lead with a definition or direct answer in the first paragraph (40-80 words) so AI search engines can extract it. On a designed page (the homepage, a landing, product or pricing page), put the answer in the existing hero sub-heading or the first section's copy; never insert a new paragraph or block between sections."
 
 ### `llms_txt_missing`
 Check: `WebFetch https://{domain}/llms.txt`. It fails the check if it 404s, or returns something that isn't markdown starting with an `#` H1 (a soft-404 / SPA shell).

package/skills/references/inbox.md

@@ -74,6 +74,7 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
   - `rank_expansion` → the page already wins, or is in striking distance, for the queries in the body. Deepen **that** page against **those** queries; never spawn a new one.
   - `low_ctr` → **read the body, not just the reason.** Past roughly position 20 nobody sees the snippet, so the body says "Lift ranking" and a title rewrite is wasted work: fill the gaps a searcher on the page's real queries expects, and add the vocabulary those queries use if the page answers them in different words. Only when the body says "Improve CTR" (shallow position) is rewriting the title + meta description the fix — and write it against the **"Queries this page already ranks for"** section, which both depths now carry, not a keyword guessed from the slug. When one of those queries is the site's own brand name the page is competing with its own homepage, so check the new snippet does not restate what another of this site's results already says.
   - `stale_thin` → expand and update.
+- **The reasons above are article advice.** When the page is a designed page (the homepage, or a landing, product, feature, pricing or `/for/` page built from its own sections and components), the file's step 2 says so and replaces them: work inside the sections the page already has, never add a new section, band or block, and if the change needs a slot the page does not have, decline with `--failed --reason "Suggestion: <the copy> (goes <where>)"` instead of building it. See `references/landing-pages.md` § Editing an existing designed page.
 - Follow the rewrite protocol (`references/rewrite-protocol.md`). Reversible edit — follow the file's go-ahead step: **Standing approval** → apply, commit, ack; otherwise show the user the diff (confirm once per session, then proceed; interactive sessions can review the revised draft via `references/draft-review.md`).
 - Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "kept as-is; ..."`).
 

package/skills/references/landing-pages.md

@@ -2,6 +2,10 @@
 
 Use when writing or improving a sales / conversion / feature / pricing / homepage. Different from blog content — landing pages are conversion-focused, not authority-focused.
 
+**Editing a page that already exists? Read § Editing an existing designed page first.** The section order and word count below are for a NEW page; never add sections to an existing page to match them.
+
+**Every page uses the site's own design.** Before writing a new page or editing one, read the closest existing page of the same kind and what gives it its look: its components, the theme or Tailwind config, the global CSS, the fonts. Build with those, so the result looks like the rest of the site. Never introduce a font, color or style the site does not already use.
+
 ## When to Use
 
 - The user asks for a homepage, feature page, pricing page, product page, or campaign landing page
@@ -159,8 +163,18 @@ images:
       prompt: "..."
 ```
 
+## Editing an existing designed page
+
+The homepage and every product, feature, pricing and `/for/*` page are designed: each section is a component with its own layout. An SEO edit to one fits that design, or it goes to the owner as a suggestion.
+
+- **Fit an existing slot.** Rewrite the H1, a sub-heading or the hero and intro copy; tighten or extend copy inside an existing section; add questions to an existing FAQ (often a data array); add entries to an existing list or table; put links in existing copy. Use the page's own components, classes and styles.
+- **Never add a standalone section, band or block**: no "What is X?" band between the hero and the next section, no new FAQ block, no answer paragraph dropped between sections, no "Related pages" strip. The article rules (definition block, answer-first opening, FAQ section) are for articles; on a designed page the same intent goes into the hero sub-heading or the copy of a section that is already there.
+- **No slot fits? Suggest, don't build.** Give the owner the proposed copy and where it would go ("replace the sub-heading under the hero with: …"). For an inbox action or an unattended run, decline the action with a reason that starts `Suggestion:`; the hosted runner lists it under "Suggestions for you" in its pull request. In an interactive session, show it to the user and build it only if they ask.
+- **Don't change the layout to make room.** Reordering sections, new components and new visual styles are design work for the owner.
+- **Section Ordering** and **Word Count Target** above describe a new page. An existing page with fewer sections is not missing any, and short copy on a designed page is often intentional.
+
 ## Persistence
 
 Even though landing pages aren't in `strategy/clusters/`, persist the content to `.seoagent/content/{slug}.md` with `page_type: landing`. Add an entry to `changelog.md`. Run `seoagent sync`.
 
-If the user is editing an existing landing page rather than creating a new one, follow `references/rewrite-protocol.md` instead.
+If the user is editing an existing landing page rather than creating a new one, follow `references/rewrite-protocol.md` and § Editing an existing designed page above.

package/skills/references/rewrite-protocol.md

@@ -60,7 +60,7 @@ Run a structured diagnosis. Use this exact template — output it to the user be
 
 ## Plan (Y/N)
 1. Update {N} stats with 2026 figures
-2. Add new H2: "{section title}" linking to {sub_pillar}
+2. Add new H2: "{section title}" linking to {sub_pillar}   # articles only, never on a landing page
 3. Tighten {section} — currently {old word count}, target {new word count}
 4. Refresh hero image alt text + add OG card
 ```
@@ -127,11 +127,12 @@ Run `seoagent sync`.
 ### Rewriting a Landing Page
 
 Same protocol but:
+- **Fit the design, or suggest.** Follow `references/landing-pages.md` § Editing an existing designed page: every edit goes inside a section the page already has, and the plan adds no new H2, section, band or block. Anything that needs a new section goes in the diagnosis under `### Suggestions for the owner` (the proposed copy and where it would go) and is not built. The article patterns (definition block, answer-first opening, FAQ section) do not apply.
 - Track conversion impact — note in changelog if there's a CRO concern
 - 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.
+- **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 put it in that section's existing image slot — this is how an *existing* SaaS landing page gets the screenshots it's missing. No section has a slot for it? Suggest it; don't add a section to hold it.
 
 ### Rewriting Without an Existing Brief
 

package/skills/references/writing-rules.md

@@ -55,7 +55,7 @@ When revising a page that already exists — Phase 4b rewrites, `cli_content_upd
 - **Make the minimum effective edit.** Fix slop patterns, errors, and unclear passages. Leave strong human sentences alone. A rough draft with a real voice should still sound like the same person after editing.
 - **Keep the user's meaning.** Don't invent claims, examples, stats, or opinions. If something is unclear, ask.
 - **Keep useful edge.** Strong opinions, blunt language, humor, and honest admissions stay if they belong to the writer. Don't replace them with safer wording.
-- **Keep structure unless it hurts the piece.** If you reorganize, say why in the change summary.
+- **Keep structure unless it hurts the piece.** If you reorganize, say why in the change summary. A designed page (the homepage, a landing, product or pricing page) keeps its sections exactly: no new section or block, per `references/landing-pages.md` § Editing an existing designed page.
 - Empty qualifiers like "I think", "maybe", "to be honest" stay when they express real uncertainty or the writer's spoken rhythm.
 
 ## Self-check before showing a draft

package/skills/seoagent.md

@@ -6,7 +6,7 @@ allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch
 
 # SEOAgent — Persistent AI SEO Agent
 
-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.
+You are an expert SEO agent: technical audits, keyword strategy, content planning, and optimized content — every artifact persisted to `.seoagent/`.
 
 **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.
 
@@ -29,7 +29,7 @@ Detail lives in `references/` — load on demand with `Read`.
 | Running a full audit | `references/audit-checks.md` |
 | Keyword research | `references/keyword-research.md` |
 | Migration after a pivot/rebrand | `references/migration-planning.md` |
-| Landing page | `references/landing-pages.md` |
+| Landing page, or editing a designed page (homepage, landing, pricing) | `references/landing-pages.md` |
 | Pillar / sub-pillar / long-tail article | `references/pillar-articles.md` · `references/sub-pillar-articles.md` · `references/long-tail-articles.md` |
 | Listicle ("Top N" / "Best X") | `references/listicle-articles.md` |
 | Product screenshots (SaaS) | `references/screenshots.md` |