@seoagent-official/seoagent 1.80.0 → 1.81.0

package/package.json

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

@@ -103,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/seoagent.md

@@ -37,6 +37,7 @@ 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` |
@@ -169,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:
@@ -189,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).
@@ -840,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.