@seoagent-official/seoagent 1.87.0 → 1.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.87.0",
+  "version": "1.88.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/inbox.md

@@ -20,6 +20,10 @@
 | `cli_ai_files_update` | The AI-readable file layer (OKF bundle + `llms.txt`) is missing, unmanaged, or stale | Safe |
 | `cli_new_landing_page` | High-value keyword (`easy_win`/`competitor_gap`) with no page covering it — write a landing page | Safe (new content) |
 | `cli_draft_ready` | The cloud already wrote a complete article and synced it to `.seoagent/content/<slug>.md` — review and place it | Safe (new content) |
+| `cli_send_outreach_email` | A human-approved link-building email to send **from the user's own email account** | **Outward-facing — confirm first send of the session** |
+| `cli_draft_context` | Business context is missing while suggested keywords wait on the relevance judge — draft `.seoagent/context.md` | Safe (repo-local file) |
+| `cli_run_audit` | The full technical audit is stale (>28 days) or has never run — re-run Skill Phase 1 and sync | Safe (read-only crawl + report) |
+| `cli_outreach_drafts_ready` | Outreach email drafts await the owner's review on the dashboard — tell the user, then ack | Safe (informational) |
 
 ## Per-type procedure
 
@@ -88,3 +92,33 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 - **Review the draft** (frontmatter carries title, meta description, status), then place it where this project's content renders: repo-native (mdx_sync) → copy/adapt into the repo's content directory and `seoagent content track` it; CMS → create the entry and track it; cloud-hosted → flip frontmatter `status` to `published` and sync. The inbox file body walks through each strategy.
 - Edit freely before publishing — the `.seoagent` copy is the user's now. Show the user the draft before publishing.
 - Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "not publishing; ..."`).
+
+### `cli_send_outreach_email-<id>.md`
+
+- `Read` it. The frontmatter has `action_id`, `to_email`, `to_name`, and `prospect_url`; the body carries the exact subject + email text the user **already reviewed and approved in the SEOAgent dashboard**. Your job is delivery only.
+- **Send it from the user's own email account** using whatever email tooling this session has (Gmail connector/MCP, AgentMail, a mail CLI, …). SEOAgent never sends email itself.
+- **Confirm once per session** before the first outbound email (show recipient + subject); then send subsequent approved emails without re-prompting. Send **verbatim** — no added signature, links, or attachments; the one allowed edit is fixing an obviously wrong greeting name.
+- No `to_email`? Check the prospect page for the author's address or a contact form — a form submission with the body text counts as sent.
+- Acknowledge after sending: `seoagent ack <action_id>` — the dashboard marks the draft **sent** and the prospect **contacted**. Declining (`--failed --reason "not sending; ..."`) dismisses the draft. A transient tooling failure should NOT be acked — leave it pending and it returns next sync.
+- **No email tooling available at all?** Leave the action pending and tell the user what tooling would enable sending (or that they can send manually from the dashboard's drafts queue).
+
+### `cli_draft_context-<id>.md`
+
+- `Read` it. The frontmatter has `action_id`, `artifact_path` (normally `.seoagent/context.md`), and `unjudged_keywords` — how many suggested keywords are stuck because the cloud's relevance judge has no business context for this site.
+- **Draft the context file.** Open `artifact_path`; an untouched `seoagent init` scaffold carries an `AGENT:` comment with the full drafting instructions — follow those. Fill `business.type`, `business.audience`, and `business.description` from what you know of the repo (README, landing page copy), and set `business.location` ONLY if the business serves a physical area. State the reach explicitly — LOCAL, ONLINE-only, or HYBRID — the keyword gates key off it. **If you can't tell from the repo, ask the user; never guess.**
+- Push it with `seoagent sync` — the next keyword-refresh run picks it up and judges the backlog.
+- Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "declined; ..."` if the user doesn't want context captured — SEOAgent won't ask again).
+
+### `cli_run_audit-<id>.md`
+
+- `Read` it. The frontmatter has `action_id`, `reason` (`never_audited`|`stale`), `last_audit_at`, and `age_days`.
+- **Run the Skill's audit protocol (Phase 1)**: fresh evidence first (`seoagent crawl`, plus `seoagent indexing` when GSC is connected — evidence older than 24h doesn't count), then the per-page checks from `references/audit-checks.md`, then write `.seoagent/audit/latest.md`. If `reason` is `stale`, this is a **re-audit**: diff against the previous `latest.md` and mark what's fixed / new / regressed (skill § re-audit protocol).
+- Push with `seoagent sync` — the server marks the previous report's still-open findings `superseded`, so the dashboard shows only the current audit.
+- Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "declined; ..."` — autopilot won't ask again until next month).
+
+### `cli_outreach_drafts_ready-<id>.md`
+
+- `Read` it. The frontmatter has `action_id`, `awaiting_drafts`, and `site_url`.
+- **Informational — nothing to change in this repo.** The backlinks autopilot drafted link-building emails, but only the owner can approve outreach, and the approval queue lives in the SEOAgent dashboard (the site's **Outreach** tab, drafts filter). Tell the user how many drafts await and where; each shows the prospect page, pitch angle, and the exact email text (edit / approve / dismiss).
+- Approved drafts return to this inbox as `cli_send_outreach_email` actions for delivery.
+- Acknowledge after surfacing it: `seoagent ack <action_id>`. Decline (`--failed --reason "not now; ..."`) if the user isn't interested — the reminder returns only when the awaiting count changes on a later weekly run.

package/skills/references/migration-planning.md

@@ -54,3 +54,12 @@ Harvest actions (refresh/repurpose) flow through the normal rewrite protocol (`r
 ## Relationship to keyword strategy
 
 Migration planning is the **backward-looking** counterpart to Phase 2's forward-looking clusters. Run `keywords --seed` to see the historical demand, split on/off strategy (Phase 2 step 3), then use `seoagent migrate` to give the **off-strategy-but-valuable** bucket a concrete per-URL disposition. The new direction's forward clusters still come from `context.md` + WebSearch (they have little GSC history yet).
+
+## Do you actually have GSC data? Check before concluding "no"
+
+"No GSC data" is the wrong conclusion far too often. Two sources count, and the second is easy to miss:
+
+1. **A connected login** — `seoagent whoami` shows the account and GSC connection.
+2. **A local Search Console CSV export.** `seoagent migrate` auto-detects `gsc/*.csv` and CSVs in the repo root. A user who exported from Search Console and dropped the file in the repo has GSC data even with no login at all.
+
+Check both before deciding the migration path does not apply. Only when neither exists do you skip migration silently.

package/skills/references/publishing.md

@@ -88,3 +88,20 @@ Then:
 5. Append to `changelog.md`: `[date] Publishing re-detected: {old} → {new}`. Run `seoagent sync`.
 
 If you spot the drift incidentally (mid-audit, mid-edit), surface it as a one-line heads-up + offer rather than blocking — re-detect only when the user agrees, or when you're about to act on the stale target (Phase 3+).
+
+## Where the article body lives — one source of truth
+
+The publishing strategy decides where an article's **body** is written. Never write it twice.
+
+- **`mdx_sync` / `custom`** — the body lives in the **repo file or CMS entry**, NOT in `.seoagent/`. Match the site's existing frontmatter and content model exactly (read an existing article first). Tracking is automatic once `publishing.content_dir` is set: the next sync registers the file. Only when no content dir is declared *and* nothing is tracked yet, run once:
+  `seoagent content track --slug {slug} --url https://{domain}{blog_path}/{slug} --file {path}`
+  (it self-records `content_dir`). **Never hand-write a duplicate full-body `.seoagent/content/{slug}.md`** — two copies of one article drift, and the sync then reports both.
+- **`managed_proxy` / `subdomain`** (cloud-hosted) — the body **does** live in `.seoagent/content/{slug}.md` with full SEO frontmatter (schema in `references/schemas.md`), published by `seoagent sync`.
+
+Either way: ship repo articles the way the repo ships — PR or branch, never straight to the default branch without asking.
+
+## Images — never block publishing on them
+
+Always write `images:` frontmatter with `alt` + `prompt` (or `src` for a captured screenshot). If `project.md` has `image_provider`, offer `seoagent generate-image --prompt "..." --out .seoagent/content/images/{slug}-hero.png`. If it's absent, run `seoagent env-check` first — it detects keys added after `init` and records the provider. Still nothing → offer the one-line key ask, then **write prompts only and continue publishing**. Images are never a blocker.
+
+For SaaS sites (`site_type: saas`, or a repo rendering real product UI), capture real product screenshots per `references/screenshots.md` for hero/feature/how-to spots **before** falling back to generated images.

package/skills/references/session-protocol.md

@@ -65,3 +65,9 @@ When `.seoagent/project.md` doesn't exist, or `domain`/`site_type` is `unknown`:
 If the repo alone is inconclusive, WebFetch the homepage and infer from the visible content — pricing pages and trial CTAs → `saas`, product listings/cart → `product`, blog-heavy with no auth → `content`. `Edit` `project.md` to update `site_type` **before any audit or strategy work** — every later phase makes worse decisions when this is `unknown`.
 
 **Confirm inferences**: state domain and site type with evidence (which env key, `package.json` field, or dependency pattern). Ask the user to confirm or correct before writing `project.md`.
+
+## Starting a session: fast path and first session
+
+**Fresh project (fast path).** When `init` ran this session or moments before — no `audit/latest.md`, no `strategy/`, changelog holds only the init line — there is **nothing to reconcile**. Skip the bookkeeping and go straight to Phase 1: `seoagent crawl` → read `evidence.md` → audit → **deliver evidence-grounded findings first, workspace bookkeeping second**. One `seoagent doctor` is still worth running, but act only on `domain_unknown` / `site_type_unknown` before the crawl; every other finding waits until the findings are delivered. `seoagent sync` must never block, gate, or precede audit work on a fresh project — run it after the findings are out.
+
+**First session on an existing project, no audit yet.** Before the Phase 1 audit: WebFetch the homepage plus up to 3 key pages; run `seoagent sitemap` to validate the **live** sitemap — never judge it by committed files, since a dynamic `app/sitemap.ts` serves `/sitemap.xml` with no file in the repo; WebFetch `{domain}/robots.txt`; and scan headings/nav for topic clusters that already exist. Then run the full audit.