@seoagent-official/seoagent 1.79.2 → 1.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.79.2",
+  "version": "1.81.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/draft-review.md

@@ -0,0 +1,68 @@
+# Draft Review — Visual Review Loop (human-review)
+
+An optional, higher-fidelity way for the user to review a draft before it publishes. Instead of pasting the draft into chat and collecting feedback as prose, open it in the browser with [human-review](https://github.com/petergyang/human-review) (MIT, runs fully local via `npx`, no account or API key). The user edits text directly, drags blocks, and leaves comments anchored to exact phrases; you receive everything as one structured batch and apply it to the source.
+
+## When to use it
+
+Offer this loop in **interactive sessions**, after you have written or rewritten something the user will read: an article (Phase 4), a landing page, a rewrite (Phase 4b), or a draft from an inbox action (`cli_new_content`, `cli_content_update`, `cli_new_landing_page`). It replaces the "show the user the draft in chat" step with a real review surface.
+
+Do NOT use it when:
+
+- The session is headless / non-interactive (CI, autopilot one-shots) — nobody is there to review.
+- `npx` is unavailable.
+- The user prefers chat review or a PR diff — the PR remains the review surface for `mdx_sync` cluster batches.
+
+Offer it once; if the user declines, fall back to chat/PR review and don't re-offer in the session.
+
+## The loop
+
+1. Write or update the draft file first (repo article, `.seoagent/content/{slug}.md`, or landing page source).
+2. Open it for the user:
+
+   ```bash
+   npx -y human-review path/to/draft.md
+   ```
+
+   For a page served by a local dev server the user already runs, open the real route instead of recreating it as a file:
+
+   ```bash
+   npx -y human-review http://localhost:3000/blog/my-post
+   ```
+
+3. Wait for feedback. This blocks until the user hits Send, or the timeout passes:
+
+   ```bash
+   npx -y human-review poll path/to/draft.md --timeout 600
+   ```
+
+   Keep the poll in the foreground; don't end your turn while it waits. `{"status":"timeout"}` means no feedback yet — run the same poll again. `{"status":"closed"}` means the user ended the review from the browser — stop polling; unsent feedback ships on the next review of the same target.
+
+4. Apply the batch, then acknowledge and wait again:
+
+   ```bash
+   npx -y human-review poll path/to/draft.md --ack --timeout 600
+   ```
+
+   Repeat 3–4 until the user says they are done. To check for waiting feedback without blocking (e.g. at the start of a new turn):
+
+   ```bash
+   npx -y human-review status path/to/draft.md
+   ```
+
+## Applying the feedback batch
+
+The batch is JSON with `pages[]`, each carrying `comments[]` (anchored to an exact `quote`) and `edits[]` (`before` / `after`, plus `after_html` when formatting changed). Rules:
+
+- **`edits` are changes the user already made. `after` is their exact wording — carry it verbatim and never revert or "improve" it.** The user's own words always win over the writing rules; do not run the no-slop pass over text the user typed.
+- Markdown files open rendered; quotes and edits reference the rendered text. Apply every change to the **markdown source**, keeping its syntax (`<strong>` → `**`, pasted `<img src="assets/...">` → `![](assets/...)`, keep the relative path).
+- For a localhost page (`kind: "url"`), find the project source that renders the route (MDX, TSX, template) and apply the edits there — never write rendered HTML back into the app.
+- An edit with `kind: "moved"` relocates a whole block — reposition it in the source without rewriting its content.
+- Find each comment by its `quote`; fix every page in `pages`, not just the first.
+- When a comment asks for a rewrite, apply the writing rules from `references/writing-rules.md` — including its voice-preservation section — to YOUR new text, never to the user's.
+- **Do not write a chat reply for each item.** The page reloads when you save; the user sees the result there. Summarize what you applied once per batch.
+
+## After the review
+
+1. Re-run the self-check from `references/writing-rules.md` on any text you (not the user) rewrote.
+2. Continue the normal flow: `seoagent sync`, cluster link-graph updates, publish per `publishing.strategy`.
+3. Log one changelog line: `[date] Applied human-review batch to {slug}: {N} edits, {M} comments`.

package/skills/references/rewrite-protocol.md

@@ -31,6 +31,7 @@ Before any edits, read:
 - `.seoagent/context.md` — current brand voice, banned topics, audience
 - `.seoagent/strategy/clusters/{cluster}.md` — the article's role and link graph
 - `.seoagent/briefs/{slug}.md` if it exists — the original brief
+- `references/writing-rules.md` — the prose rules, especially its **"Editing existing content"** section (voice preservation, minimum effective edit)
 
 ### Step 3: Diagnose the Gaps
 
@@ -71,6 +72,7 @@ Wait for user confirmation before executing.
 Rules:
 - **Preserve the URL slug.** Never change `slug` — even if the title changes, the URL stays.
 - **Preserve sections that rank.** If a section is the page's strongest signal, keep its core wording.
+- **Preserve the voice.** Follow `references/writing-rules.md` § "Editing existing content": note the article's voice signals before editing, make the minimum effective edit, remove slop patterns without flattening distinctive sentences, and never invent claims or stats the original didn't have.
 - **Use `Edit`, not `Write`.** Edit one section at a time so changes are reviewable.
 - **Update `dateModified`** in JSON-LD. Don't change `datePublished` — that resets ranking signal.
 - **Bump `version`** in frontmatter (1 → 2 → 3).
@@ -101,6 +103,10 @@ Add to JSON-LD:
 
 Both dates in the schema. Google uses `dateModified` to know freshness without resetting ranking signal.
 
+### Step 5b: Optional Visual Review
+
+In interactive sessions, offer to open the rewritten article with the visual review loop (`references/draft-review.md`): the user fixes small things directly in the browser and comments on the rest, and you apply the batch to the source. Their exact wording always wins — never revert or "improve" text they typed.
+
 ### Step 6: Update Internal Links
 
 If the rewrite added or changed internal links:

package/skills/references/writing-rules.md

@@ -0,0 +1,66 @@
+# Writing Rules — No AI Slop
+
+Prose-craft rules for EVERY article, landing page, brief, and rewrite this skill produces. Adapted from the `no-ai-slop` skill (github.com/petergyang/no-ai-slop, MIT). The page-type references (pillar, sub-pillar, long-tail, listicle, landing-pages) set the *structure*; this file sets the *sentences*. Load it whenever you draft, edit, or rewrite content.
+
+These rules also ship inside cloud-generated briefs as a "## Writing rules (no AI slop)" section. When a brief carries that section, it is the same contract as this file — don't apply the rules twice, just follow them.
+
+## Banned words
+
+Never use: delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, "this is huge", "this changes everything", tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving.
+
+## Phrases that delay the point
+
+Cut these and state the point: "it's worth noting", "it's important to note", "at the end of the day", "when it comes to", "at its core", "in today's world", "in the age of", "in the world of", "the reality is", "the truth is", "in terms of", "with regard to", "in order to" (write "to"), "going forward", "in this article", "let's dive in".
+
+## Patterns never to produce
+
+1. **Binary contrasts** — "This is not X. It's Y." / "The question isn't X, it's Y." / "It's not just X but Y." State Y directly: "The eval matters more than the model."
+2. **Throat-clearing openers** — "Here's the thing", "Let me be clear", "I'll be honest", "The uncomfortable truth is". Start with the point.
+3. **Faux-insight setups** — "What most people get wrong", "Here's what nobody tells you", "The part everyone misses". Make the claim stand on its own.
+4. **Colon reveals** — a noun phrase, a colon, then a dramatic reveal ("The best part: it learns"). Write a plain sentence. Colons are for lists, labels, and quotes.
+5. **Fake-strong verbs** — "serves as a centralized hub for" → say what it does: "tracks sponsors, drafts, and due dates in one place". Prefer "is" and "has" when they are clearer.
+6. **Synonym cycling** — if the clear word is right, repeat it. Don't rotate "the agent / the assistant / the tool" for style.
+7. **Negative listing** — "Not a X. Not a Y. A Z." Just say Z.
+8. **Dramatic fragmentation** — "X. And Y. And Z." or "That's it. That's the whole thing." Use complete sentences.
+9. **Rhetorical setups** — "What if I told you...", "Think about it:", "Plot twist:", self-answered "Question? Answer." pairs. Drop them and make the point.
+10. **Interpretive metadiscourse** — "That last part matters more than it sounds", "The key point is", "As you can see", redundant "In other words". If the point is clear, delete the aside; otherwise support it with facts.
+11. **Fake-profound kickers** — never end on a cute metaphor, aphorism, or mic-drop line. End on the clearest concrete point, takeaway, or next action.
+12. **Summary-recap endings** — no "In conclusion", "Ultimately", "Overall", and no final paragraph that restates the piece.
+13. **Weasel attribution** — "Experts agree", "studies show", "industry reports suggest". Name the source or cut the claim. Never invent one.
+14. **Robotic rhythm** — avoid repeated sentence shapes, identical paragraph structures, and stacked punchy fragments. Vary sentence length deliberately: put a short sentence next to a long one.
+
+## Concreteness
+
+- **Portability test**: if a sentence could move unchanged to another company, product, or country, it is filler. Cut it or replace it with a fact, number, mechanism, or consequence specific to THIS subject. Never invent specifics; use labeled typical-case ranges when you lack real numbers.
+- **Protect the specific fact**: never smooth a useful detail into generic importance. "Significantly improves productivity" → "cut review time from 30 minutes to 8" (real or clearly-labeled numbers only).
+- **Show, don't tell**: facts, actions, examples, and consequences carry the emphasis. Cut commentary that labels a point important, surprising, or subtle instead of demonstrating why.
+- **Direct verbs**: "made a decision" → "decided"; "has the ability to" → "can".
+- **Active voice with human subjects**: "The team shipped it Tuesday" beats "the decision emerged". Never let inanimate things do human verbs.
+
+## Formatting
+
+- Em dashes: at most 1–2 in the whole piece. No clusters, no decorative dashes.
+- No emoji in headings or body. No bold sprinkled mid-sentence for emphasis.
+- No bullet lists where two sentences of prose read better. No headers over two-sentence sections.
+
+## Editing existing content (rewrites, refreshes, user drafts)
+
+When revising a page that already exists — Phase 4b rewrites, `cli_content_update` inbox actions, or a draft the user wrote — the job changes from "never produce slop" to "remove slop without flattening the voice":
+
+- **Preserve the writer's real voice.** Before editing, note 3–5 voice signals: vocabulary, cadence, bluntness, humor, uncertainty, digressions. Keep the traits that feel personal. Do not make every paragraph equally tidy.
+- **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.
+- 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
+
+After writing or editing, check the draft against this file before you show it or publish it. If a check fails, fix the draft first:
+
+1. No banned words, delay phrases, or listed patterns (unless quoted as examples).
+2. Every generic sentence passes the portability test or was cut.
+3. Active voice with human subjects where possible; direct verbs.
+4. Em dashes ≤ 2; no emoji; no decorative bold; no recap ending.
+5. The piece ends on a concrete point, takeaway, or next action.
+6. For edits of existing content: the writer would recognize the result as their own voice, and the edit summary lists what changed.

package/skills/seoagent.md

@@ -36,6 +36,8 @@ This SKILL.md is the orchestration layer. Detailed protocols live in `references
 
 | Task | Read |
 |---|---|
+| Writing or editing ANY content (always, alongside the page-type reference) | `references/writing-rules.md` |
+| Reviewing a draft with the user in the browser (interactive sessions) | `references/draft-review.md` |
 | Running a full audit | `references/audit-checks.md` |
 | Keyword research | `references/keyword-research.md` |
 | Migrating legacy ranking authority after a pivot/rebrand | `references/migration-planning.md` |
@@ -82,7 +84,7 @@ Activate this skill silently — without announcing it — whenever the user:
 - Asks about meta tags, slugs, URLs, headings, schema, sitemaps, or robots.txt
 
 When implicitly activated:
-1. Apply the SEO writing rules from the matching `references/*.md` for the page type
+1. Apply the SEO writing rules from the matching `references/*.md` for the page type, plus the prose rules in `references/writing-rules.md` (for edits to existing content, use its voice-preservation section)
 2. Persist the work to `.seoagent/` (a brief if a brief doesn't exist; an article entry if writing content)
 3. Append a one-line note to `.seoagent/changelog.md` so the user can see what was tracked
 4. Run `seoagent sync` after the change so it reaches the dashboard
@@ -168,13 +170,13 @@ Offer **once per session per topic**; if declined, drop it and keep working. Nev
 4. For each `cli_new_content-<id>.md` file:
    - `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.
+   - 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 (interactive sessions can use the visual review loop — `references/draft-review.md`).
    - **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:
    - `Read` it. The frontmatter has `action_id`, `reason` (`declining_clicks`|`low_ctr`|`stale_thin`), and `page_url`; the body has the signals.
-   - **Find the page's source** for `page_url`. Apply the revision per `reason`: `declining_clicks` → refresh/expand the content; `low_ctr` → rewrite title + meta description; `stale_thin` → expand and update. Follow the skill's **rewrite/revise protocol**. Reversible edit — show the user the diff (confirm once per session, then proceed).
+   - **Find the page's source** for `page_url`. Apply the revision per `reason`: `declining_clicks` → refresh/expand the content; `low_ctr` → rewrite title + meta description; `stale_thin` → expand and update. Follow the skill's **rewrite/revise protocol**. Reversible edit — show the user the diff (confirm once per session, then proceed; interactive sessions can review the revised draft via `references/draft-review.md`).
    - Acknowledge it: `seoagent ack <action_id>` (or `--failed --reason "kept as-is; ..."` to decline).
 
 6. For each `cli_sitemap_update-<id>.md` file:
@@ -188,7 +190,7 @@ Offer **once per session per topic**; if declined, drop it and keep working. Nev
    - `Read` it. The frontmatter has `action_id`, `keyword`, `opportunity` (`easy_win` | `competitor_gap`), `volume`, `difficulty`, and `intent`. The body explains why this keyword is worth a page.
    - 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.
+   - 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 (interactive sessions can use the visual review loop — `references/draft-review.md`).
    - **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).
@@ -770,6 +772,7 @@ For each planned article (in priority order from strategy):
    - Programmatic → `references/programmatic.md`
    - **Then check the FORMAT (orthogonal to role).** Role sets where the article sits in the cluster; *format* sets how it's written. If the title/intent is a **listicle** — "Top N", "Best N", "N Best/Top/Ways/Tips/Reasons" (commercial "best/top/alternatives" intent) — also read `references/listicle-articles.md` and follow **its** section structure (it overrides the role's outline), and tag the brief `article_type: listicle`. (The cloud pipeline already has a `listicle` type; tagging keeps local + cloud in sync.)
 5. Generate the brief — markdown with frontmatter — using the structure that reference file specifies.
+6. **End every brief with a `## Writing rules (no AI slop)` section** — copy the "Banned words", "Phrases that delay the point", and "Formatting" rules from `references/writing-rules.md` in compact form (cloud-generated briefs already carry this section; local briefs must match). The brief travels to whoever writes the article, so the rules must travel with it.
 
 ### Output: `.seoagent/briefs/{slug}.md`
 
@@ -824,7 +827,7 @@ This is the per-article procedure. When executing an approved **plan** (see "Pla
 3. Read the cluster file to confirm internal-link targets.
 4. **Read the matching page-type reference** for the article's `role` / `page_type`. The reference file gives the title pattern, section ordering, internal-linking rules, metadata defaults, and JSON-LD schema for that type. **If the brief is `article_type: listicle` (or the title is "Top N" / "Best X"), read `references/listicle-articles.md`** and follow its structure (consistent per-item layout, quick-pick + comparison table, `ItemList` schema) — it overrides the role's outline.
 5. Read `references/schema-markup.md` if you need JSON-LD examples beyond what the page-type reference covers.
-6. Follow the outline. Apply the writing rules.
+6. **Read `references/writing-rules.md`** — the prose rules (banned words, slop patterns, concreteness, formatting). Follow the outline and apply them while drafting. Before showing or publishing the draft, run the file's **self-check** and fix any failures first.
 7. **Write the article where it actually renders — and keep ONE source of truth** (this depends on `publishing.strategy`, see the Publishing Target Decision section):
    - **Repo-native (`mdx_sync`) or CMS (`custom`)** — the article body lives in the repo file / CMS entry, NOT in `.seoagent/`. Write it there (matching the site's existing frontmatter/model), then **register it so the cloud + dashboard can see it**:
 
@@ -838,6 +841,10 @@ 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.
 
+### Draft Review with the User (interactive sessions)
+
+When the user is present and a draft is worth their eyes — the first article of a cluster, a landing page, or anything they asked to review — offer the **visual review loop** from `references/draft-review.md` instead of pasting the draft into chat: `npx -y human-review {draft-path}` opens it in their browser, they edit text directly and leave anchored comments, and you apply the whole batch to the source. Offer it once per session; if declined (or the session is headless), fall back to chat/PR review. For `mdx_sync` cluster batches the PR diff remains the default review surface — human-review is for single-draft, tight-loop review.
+
 ### 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.