@seoagent-official/seoagent 1.117.6 → 1.119.0

package/package.json

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

@@ -28,6 +28,7 @@
 | `cli_run_audit` | The full technical audit is stale (≥7 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) |
 | `cli_submit_listing` | The owner approved a directory listing submission (or correction) on the dashboard — fill the directory's form **in a browser** with the facts given | **Outward-facing — owner-approved; stop at any account, CAPTCHA or payment** |
+| `cli_competitor_new_pages` | A competitor's sitemap listed new pages this week — review each and plan a better page only where one is possible; the plan goes to the cloud planner with the ack | Safe (planning only — no files; never copy) |
 
 ## Per-type procedure
 
@@ -150,3 +151,14 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 - **Stop and decline** if the form asks for an account, a sign-in, a CAPTCHA, a payment, or any agreement beyond submitting the listing, or if a required field has no fact: `seoagent ack <action_id> --failed --reason "<what blocked you>"`. The reason becomes the owner's to-do on the dashboard.
 - Submitted: `seoagent ack <action_id> --url "<listing URL, if shown>"` → the listing goes to `submitted`; the next NAP audit marks it live once it appears.
 - The directory says the owner must verify (code, postcard, call, email): `seoagent ack <action_id> --verify "<what the owner must do>" --verify-type code|postcard|call|email` → the listing goes to `pending_owner_verification` and the dashboard shows the to-do. SEOAgent never receives the code.
+
+### `cli_competitor_new_pages-<id>.md`
+
+- `Read` it. The frontmatter has `action_id`, `competitor_domain`, `detected_week` and `new_page_count`; the body lists up to 20 of the new URLs (newest `lastmod` first) and says how many more there are.
+- **Planning, not writing.** Nothing is written or published from this action — the output is the plan and the skip reasons, sent with the ack.
+- **For each page:** open it (WebFetch or a browser tool) and name the **search it targets**. Check whether this site already covers that search — `pages.md`, the project's published content, `.seoagent/briefs/`. Covered → skip (a page of ours that answers it worse is an update, not a new page: say so in the skip reason).
+- **Plan only where this site can make a better page than theirs** — and name what ours will have that theirs does not (first-hand data, a working example from this product, a fuller or more current answer, a tool, an honest comparison). Can't name it, off-topic, or not content (careers, press, changelog) → skip with a one-line reason.
+- **The plan goes in the ack, not in `roadmap.md`.** Each `--plan` becomes a planned keyword in the cloud planner (judged a target, labelled a competitor gap); the planner writes its brief — with what ours adds — and queues the page when its turn comes, and it arrives in `briefs/` and the inbox like any other. Do not write the article in this session, and do not add a local roadmap item: a second plan duplicates the cloud's.
+- **Never copy their content** — text, headings, structure, examples or images. Their page shows a search is worth answering; the answer is ours.
+- A big batch (`new_page_count` far above the 20 listed) is usually one template — a programmatic set or a new section: open a sample and judge the set as one plan.
+- Close it out: `seoagent ack <action_id> --plan "<target search> | <their url> | <what ours adds>" --skip "<their url> | <reason>"`, one `--plan` per planned page and one `--skip` per skipped one. An entry the CLI cannot parse refuses the ack before anything is sent. Could not review them (fetch blocked, no web access) → `seoagent ack <action_id> --failed --reason "could not review: ..."`.

package/skills/references/recurring-runs.md

@@ -5,10 +5,11 @@ SEOAgent pays off only when a session actually happens on a cadence: the cloud d
 ## The session loop (every run, no exceptions)
 
 1. `seoagent sync` — pulls the cloud's work into `.seoagent/inbox/` and the briefs into `.seoagent/briefs/`.
-2. Triage `.seoagent/inbox/` (see `references/inbox.md`). Do the work in the repo.
-3. If the inbox is empty and `.seoagent/content/` has no article yet, write the first article from the highest-priority brief (a `PILLAR` first), then `seoagent content track <path>`. The sync output names the brief to start with. Do **not** start a local keyword strategy or write local briefs — on a connected workspace those are the cloud's job (`references/cloud-cta.md` § Cloud-connected mode).
-4. `seoagent ack <id>` for every action you finished (`--failed --reason "..."` to decline).
-5. `seoagent sync` once more, then `seoagent summary`.
+2. `seoagent facts` — if it lists facts whose source changed since the last check, correct them and every page that states the old value, then `seoagent facts --mark` (`references/session-protocol.md` § Fact check against commits).
+3. Triage `.seoagent/inbox/` (see `references/inbox.md`). Do the work in the repo.
+4. If the inbox is empty and `.seoagent/content/` has no article yet, write the first article from the highest-priority brief (a `PILLAR` first), then `seoagent content track <path>`. The sync output names the brief to start with. Do **not** start a local keyword strategy or write local briefs — on a connected workspace those are the cloud's job (`references/cloud-cta.md` § Cloud-connected mode).
+5. `seoagent ack <id>` for every action you finished (`--failed --reason "..."` to decline).
+6. `seoagent sync` once more, then `seoagent summary`.
 
 Never skip step 1 because a login failed. An unbound CLI cannot sync. If `seoagent login --code` fails, stop and tell the user the exact error; they can mint a fresh code at seoagent.com/grok. **Never guess, invent, or retype a setup code from memory** — a code is `sa_` + 24 random hex characters that only the server issues, it works exactly once, and a made-up one fails with `not recognized` every time.
 

package/skills/references/schemas.md

@@ -24,7 +24,9 @@ llms_owner: route                # optional: only value is `route`. Set it when
 
 ## `.seoagent/context.md`
 
-Business context, audience, tone, banned topics, reference URLs. Read on every session.
+Business context, facts, audience, tone, banned topics, reference URLs. Read on every session.
+
+`# Facts` holds one product fact per line (price, plan, limit, feature, integration), each ending in `— source: <repo file or URL>`: `- Pro plan is $49/month — source: app/pricing/page.tsx`. `seoagent facts` diffs those sources against the commits since the last `seoagent facts --mark` (see `references/session-protocol.md` § Fact check against commits).
 
 ## `.seoagent/roadmap.md`
 

package/skills/references/session-protocol.md

@@ -43,6 +43,28 @@ Cluster files in `.seoagent/strategy/clusters/` carry a per-article `status`. Wh
 
 Confirm the recorded CMS still has a supporting signal in the repo (its dep in `package.json` or its env var). If that signal is gone — the user moved off it — don't silently trust the stale value: flag it and run **"Re-detecting the publishing target"** in `references/publishing.md`. Skip this check when no `publishing.cms` is set.
 
+## Fact check against commits
+
+A page that states a price, a plan limit or a feature is only as current as the code it was read from. `.seoagent/context.md` keeps those facts under `# Facts`, one per line, each naming where it was read:
+
+```
+# Facts
+
+- Pro plan is $49/month, billed monthly — source: app/pricing/page.tsx
+- Free plan includes 3 projects — source: lib/plans.ts
+- Exports to QuickBooks and Xero — source: https://example.com/integrations
+```
+
+**Writing facts.** Read each one from the code or the live page that defines it, never from memory or marketing copy, and name that file or URL. A fact you cannot point to a source for stays out. Prefer the repo file over a URL: commits to it are what the check can see.
+
+**Checking them** (doctor flags `facts_stale`; run it every scheduled session either way):
+
+1. `seoagent facts` — lists each fact whose source file changed since the last check, with the commits that touched it.
+2. For each listed fact, re-read the source. If the value changed, update the fact line, then search the content and page files for the OLD value (the number, the plan name, the limit) and correct every page that still states it, in this session.
+3. `seoagent facts --mark` — records HEAD as checked. Run it only after step 2 is done; a mark before the pages are fixed hides the stale ones from every later session.
+
+`unchecked` (no baseline yet) means verify every repo-sourced fact once, then mark. URL-sourced facts are invisible to git: re-fetch them at each re-audit. A fact whose source no longer exists (renamed or deleted file) gets a new source or is removed. The product is right and the page is wrong: never change the product's code to match a page.
+
 ## Inferring domain and site type
 
 When `.seoagent/project.md` doesn't exist, or `domain`/`site_type` is `unknown`: