@seoagent-official/seoagent 1.50.0 → 1.51.1

package/README.md

@@ -37,20 +37,40 @@
 ---
 
 > **This package is a one-shot scaffolder, not a runtime dependency.** Run `init` once to scaffold `.seoagent/` + the Claude Code skill in your repo. Nothing to keep in `package.json` afterwards. No `postinstall` script — installs are silent and play nicely with npm 11+.
+>
+> **Upgrading is hands-off.** When a newer CLI is published, the next time you open Claude Code, the session-start hook surfaces a notice and Claude can offer to run `seoagent update-cli` — which updates the binary **and** refreshes every project on your machine to it in one go. Prefer to do nothing? Each project also self-updates on its own the next time you open it (the `SessionStart` hook runs `seoagent sync` before the skill loads). Refreshes only rewrite the skill files; your `.seoagent/` knowledge is never touched. (No more `rm -rf .seoagent && seoagent init`.) Run `seoagent refresh --all` anytime to sweep every project yourself.
 
-## Install
+## Install — pick one
+
+You can run SEOAgent two ways. Pick whichever fits how you work; both end up scaffolding the same `.seoagent/` workspace and installing the same Claude Code skill.
+
+### Option A — Global install (recommended for daily use)
+
+```bash
+npm install -g @seoagent-official/seoagent
+seoagent init
+```
+
+**Why this way:** `seoagent` is on your PATH so every command is `seoagent <cmd>` — short to type, instant to run (no npm fetch per call). Claude Code can also call `seoagent <cmd>` directly via its Bash tool, so the skill runs at full speed with no per-call latency.
+
+### Option B — One-shot via `npx` (no global install)
 
 ```bash
 npx -y @seoagent-official/seoagent init
 ```
 
-The scaffolder will:
+**Why this way:** nothing global on your machine, every invocation pulls the latest published version. Great for CI / one-off use / trying SEOAgent before committing. Trade-off: every command pays a ~2s npm fetch on cold cache, and Claude Code's Bash calls do the same.
+
+---
+
+Either way, `init` will:
+
 - Scan your repo for `package.json` `homepage` field + common `.env` files (`NEXT_PUBLIC_SITE_URL`, `SITE_URL`, etc.) to infer your domain
 - Create `.seoagent/` with `project.md`, `context.md`, and folders for audits, briefs, content
 - Install the skill at `.claude/skills/seoagent/SKILL.md` so Claude Code picks it up
 - Add a `PostToolUse` hook to `.claude/settings.json` so edits to `.seoagent/` auto-sync to the cloud (when you're logged in)
 
-The scaffolded sync hook uses `npx -y @seoagent-official/seoagent sync --silent` so the package is fetched on demand from then on — no `package.json` entry needed.
+The scaffolded sync hook uses `npx -y @seoagent-official/seoagent sync --silent` either way — it's infrastructure that survives your environment changing (so it works even if you later uninstall the global package).
 
 Then open Claude Code in this repo and say *"audit my site."* The skill takes it from there.
 
@@ -61,15 +81,16 @@ Then open Claude Code in this repo and say *"audit my site."* The skill takes it
 
 ### Headless / non-interactive
 
+Global install:
+
 ```bash
-npx -y @seoagent-official/seoagent init --yes --domain example.com
+seoagent init --yes --domain example.com
 ```
 
-### Optional: install globally for a bare `seoagent` command
+Via npx:
 
 ```bash
-npm install -g @seoagent-official/seoagent
-seoagent init   # in your project repo
+npx -y @seoagent-official/seoagent init --yes --domain example.com
 ```
 
 ## Why SEOAgent?
@@ -105,9 +126,11 @@ SEOAgent runs as a CLI on top of the [Claude Agent SDK](https://github.com/anthr
 
 **SEO-Optimized Articles** — Articles written from briefs with full SEO frontmatter: meta_title, meta_description, canonical, OpenGraph, Twitter cards, JSON-LD (Article + FAQPage + HowTo as appropriate), image plans. Saved to `.seoagent/content/`.
 
-**Image Generation (Bring Your Own Key)** — Detect `OPENAI_API_KEY`, `FAL_KEY`, or `REPLICATE_API_TOKEN` from your env. Generate hero + inline images with `npx @seoagent-official/seoagent generate-image`. You pay the LLM provider directly.
+**Image Generation (Bring Your Own Key)** — Detect `OPENAI_API_KEY`, `FAL_KEY`, or `REPLICATE_API_TOKEN` from your env. Generate hero + inline images with `seoagent generate-image`. You pay the LLM provider directly.
+
+**Open Knowledge Format bundle (AEO/GEO)** — Generate a Google [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle for your site — a curated, agent-readable knowledge layer so ChatGPT, Claude, Perplexity, and Google's AI understand and cite your business accurately. Claude maps your `.seoagent/` knowledge into OKF markdown; `seoagent okf scaffold` and `seoagent okf validate` handle the structure. Saved to `.seoagent/okf/`.
 
-**Open Knowledge Format bundle (AEO/GEO)** — Generate a Google [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle for your site — a curated, agent-readable knowledge layer so ChatGPT, Claude, Perplexity, and Google's AI understand and cite your business accurately. Claude maps your `.seoagent/` knowledge into OKF markdown; `npx @seoagent-official/seoagent okf scaffold` and `okf validate` handle the structure. Saved to `.seoagent/okf/`.
+**AI Citation Scorecard (the measurement half of AEO)** — Publishing an OKF bundle makes you *citable*; `seoagent citations` tells you whether it's *working*. It runs a set of buyer-intent questions through the Claude Agent SDK **with live web search** and reports which ones surface your business — a web-grounded proxy for how ChatGPT, Perplexity, and Google's AI Overviews answer. Saved to `.seoagent/citations/scorecard.md`. (Honest by design: it measures Claude + web search, not a per-engine guarantee — re-run over time to watch the trend.)
 
 **Compounding Roadmap** — Prioritized action plan that updates after every action. Saved to `.seoagent/roadmap.md`. Persistent changelog at `.seoagent/changelog.md`.
 
@@ -133,6 +156,8 @@ SEOAgent runs as a CLI on top of the [Claude Agent SDK](https://github.com/anthr
     concepts/                 # type: Concept|Topic — definitive explanations
     faqs/                     # type: FAQ — answer-engine Q&A
     articles/                 # type: Article — published pages (resource = live URL)
+  citations/                  # AI citation scorecards (measure the OKF/AEO loop)
+    scorecard.md              # Which buyer-intent queries surface you, web-grounded
   pages.md                    # Sitemap inventory (URL list)
   competitors.md              # Competitor profiles + gaps
   keywords.md                 # Master keyword inventory (assigned + backlog)
@@ -203,15 +228,15 @@ Three things to notice:
 2. **Priority badges** (`p:high · ⇧ +12% CTR · ⏱ 2 min`) tell you *which* actions to run first. The picker pre-selects high-priority entries by default — one Enter ships the highest-leverage work.
 3. **Declines self-ack.** When the agent decides an action is off-strategy, ambiguous, or a false positive, it emits `__DECLINED__: <reason>` and `seoagent ack --failed --reason "…"` fires automatically. You never type the reason by hand.
 
-## CLI Commands (all 19)
+## CLI Commands (all 22)
 
-Grouped by what they're for. Run via `npx -y @seoagent-official/seoagent <cmd>` or, after `npm install -g @seoagent-official/seoagent`, just `seoagent <cmd>`.
+Grouped by what they're for. Run as bare `seoagent <cmd>` after the one-time `npm install -g @seoagent-official/seoagent`. (Or `npx -y @seoagent-official/seoagent <cmd>` for a one-shot CI invocation.)
 
 **Setup + lifecycle**
 
 | Command | What it does |
 |---|---|
-| `init` | Scaffold `.seoagent/` + install the SKILL bundle + write the sync hook. Run once per repo. Auto-detects domain + site type; supports `--yes --domain <d> --site-type <t>` for CI. |
+| `init` | Scaffold `.seoagent/` + install the SKILL bundle + write the sync hook. Run once per repo. Auto-detects domain + site type; supports `--yes --domain <d> --site-type <t>` for CI. **Re-running later refreshes the skill in place** (non-destructive — never touches `.seoagent/`), handy to force the skill up to your current CLI version. |
 | `login` | Connect this CLI to seoagent.com (browser OAuth flow). Free dashboard access; required for `sync` / `process` / `ack` / paid features. |
 | `logout` | Clear stored credentials. |
 | `uninstall` | Remove `.seoagent/`, the skill, and the sync hook. `--global` also wipes the login session and cache. |
@@ -244,17 +269,25 @@ Grouped by what they're for. Run via `npx -y @seoagent-official/seoagent <cmd>`
 | `keywords` | Enrich your existing keyword inventory with real search volume + difficulty. `--discover` finds new targets; `--competitors` shows the gap (paid). |
 | `internal-links` | Generate internal-linking recommendations from your existing pages + topic clusters. |
 | `okf [scaffold\|validate]` | Generate an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle for AI agents (AEO/GEO) → `.seoagent/okf/`. `scaffold` starts it; `validate` checks `type` fields, ISO-8601 timestamps + cross-links. The skill fills the content. |
+| `citations` | Measure whether answer engines cite you (AEO/GEO). Runs buyer-intent queries through the Claude Agent SDK **with live web search** → `.seoagent/citations/scorecard.md`. `--queries <1-12>` (default 6), `--model <name>`, `--json`. Uses your `claude login` session or `ANTHROPIC_API_KEY`, same as `process`. |
 | `generate-image` | Generate hero / inline images via the detected provider (BYO API key). |
 
-**Account**
+**Account + maintenance**
 
 | Command | What it does |
 |---|---|
 | `upgrade` | Open the seoagent.com pricing page. |
+| `update-cli` | Update the CLI to the latest npm version, **then refresh every project on this machine** to it (spawns `refresh --all`). `--no-projects` skips the sweep; `--dry-run` previews. |
+| `refresh` | Force the installed skill up to your CLI version (non-destructive). `--all` sweeps every SEOAgent project on the machine — handy right after an upgrade so you don't have to open each one. |
 
 ## Auto-Sync Hook
 
-`init` writes a `PostToolUse` hook to `.claude/settings.json` so every Write/Edit to `.seoagent/` triggers `npx @seoagent-official/seoagent sync --silent` automatically. No-op when not logged in. The hook is race-safe: a cooperative lock keeps a manual `seoagent sync` from clobbering an in-flight hook run (and vice versa).
+`init` writes two hooks to `.claude/settings.json`, both running `npx -y @seoagent-official/seoagent sync --silent`:
+
+- a **`SessionStart`** hook — runs at the start of every Claude Code session, **before** Claude reads the skill, so the skill is always current (this is what makes a CLI upgrade take effect on your *next* session);
+- a **`PostToolUse`** (`Write|Edit`) hook — keeps `.seoagent/` synced as the agent edits during a session.
+
+The hooks deliberately use the `npx -y` form (not bare `seoagent`) so they survive `npm uninstall -g` and stay current with whatever's published. No-op when not logged in. Race-safe: a cooperative lock keeps a manual `seoagent sync` from clobbering an in-flight hook run. Both run the same `sync`, which **auto-refreshes the installed skill** when the CLI is newer than the project's `skill_version` — rewriting only the skill bundle, never `.seoagent/`.
 
 ## SEOAgent Cloud
 
@@ -268,7 +301,7 @@ The free skill handles audits, strategy, briefs, articles, and persistent state
 - **Team collaboration** — Invite members, share strategy, coordinate publishing
 - **Cloud dashboard** — See everything Claude Code did at seoagent.com (also free with any account)
 
-Run `npx @seoagent-official/seoagent login` for the free dashboard, or `npx @seoagent-official/seoagent upgrade` for paid features.
+Run `seoagent login` (or `npx -y @seoagent-official/seoagent login`) for the free dashboard, or `seoagent upgrade` for paid features.
 
 ## Pattern Note