@canonry/canonry 4.127.0 → 4.129.0

package/README.md

@@ -8,12 +8,13 @@
 - Watch AI engines crawl and refer traffic via [server-log ingestion](skills/canonry/references/server-side-traffic.md) — Cloud Run, Vercel, and the WordPress Traffic Logger plugin today
 - Diagnose against real traffic with built-in [GSC](docs/google-search-console-setup.md), [GA4](docs/google-analytics-setup.md), and [Bing Webmaster](docs/bing-webmaster-setup.md)
 - Track local AEO via [Google Business Profile](skills/canonry/references/google-business-profile.md) — search-term impressions, performance metrics, and hotel lodging + booking-CTA gaps
+- Manage [ChatGPT ads](docs/mcp.md#tool-surface) with OpenAI Ads Manager — connect an ad account, inspect conversion setup and performance, prepare paused campaigns, and launch only with an explicit human approval
 - Discover who links to you with [Common Crawl backlinks](skills/canonry/references/canonry-cli.md#backlinks-common-crawl) — follows Common Crawl's rolling monthly hyperlink graph, auto-syncing each new window on a schedule, queried locally with DuckDB
 - Execute fixes via [WordPress](docs/wordpress-setup.md), JSON-LD schema, and indexing submissions
 - Manage many clients declaratively — config-as-code YAML + `cnry apply`
 - Schedule recurring visibility checks, traffic syncs, and Business Profile syncs, with webhook alerts on regressions
 - Generate client-ready HTML reports — `cnry report <project>`
-- Drive from your own agent via the [67-tool MCP adapter](docs/mcp.md) or webhooks
+- Drive from your own agent via the [MCP adapter](docs/mcp.md), a [native Codex or Claude Code plugin](docs/plugins.md), or webhooks
 - Or use **Aero** — Canonry's built-in agent that wakes up after every run
 
 Every dashboard view has a matching CLI command and API endpoint. The CLI is the surface; the UI consumes the same API your agent does.
@@ -54,20 +55,82 @@ cnry project update my-site --provider gemini --provider-model gemini=gemini-2.5
 cnry project update my-site --clear-provider-model gemini
 ```
 
-## Or set it up with your AI coding agent
+## Manage ChatGPT ads with human control
 
-Drop this into Claude Code, Codex, or any shell-capable agent. It installs canonry, runs your first sweep, audits your site for AEO readiness, and stops for your sign-off before taking any action on your behalf:
+Connect an OpenAI Ads Manager account to bring its account state, integrity review,
+conversion pixels and event settings, campaign structure, and paid-performance
+rollups into the same project as your organic AEO evidence.
+
+```bash
+cnry ads connect my-site --api-key <ads-manager-sdk-key>
+cnry ads sync my-site
+cnry ads account my-site
+cnry ads summary my-site
+```
+
+Canonry and your agent can inspect the live account, look up geo targets, prepare
+campaigns, ad groups, and ChatGPT chat-card ads in a paused state, and keep durable
+operation receipts for reconciliation. Activation is deliberately separate: a human
+approves one exact campaign tree, then a scoped executor may launch only that approved
+tree. This keeps spend-bearing changes reviewable and recoverable instead of granting
+an agent unrestricted access to your ad account. See the [MCP tool surface](docs/mcp.md#tool-surface)
+for the complete agent workflow and safety model.
+
+## Use the native Codex or Claude Code plugin
+
+The native plugin gives your agent Canonry's operator playbooks and starts the existing `canonry-mcp` adapter. Canonry itself remains the execution and data plane.
+
+Install the runtime. If this is the first initialization, skip the legacy per-project skill and MCP copies:
+
+```bash
+npm install -g @canonry/canonry
+# First initialization only
+cnry init --skip-skills --skip-mcp
+```
+
+Run `cnry init` in a private terminal: it prompts for credentials and prints the
+new full-access API key once. Never paste that output into an agent chat or
+shared log.
+
+Then install the plugin for your client:
+
+```bash
+# Codex
+codex plugin marketplace add Canonry/canonry
+codex plugin add canonry@canonry
+
+# Claude Code
+claude plugin marketplace add Canonry/canonry
+claude plugin install canonry@canonry
+```
+
+Ensure Canonry's local daemon is running, then verify that its advisory doctor
+check sees the enabled plugin:
+
+```bash
+# Only when Canonry is not already running
+cnry start
+cnry doctor --check 'agent.skills.*' --format json
+```
+
+The plugin contains no credentials and declares no hooks or automatic provider calls. It does not expand Canonry's server-enforced key scope, but fresh `cnry init` creates a full-instance `*` key and a write-capable key makes write tools available to the client by default; a read-only key restricts the catalog to reads. Treat the default as teammate-level access to every project and shared setting on that single-tenant instance, and get explicit approval before every mutation or quota-consuming sweep. Existing `cnry skills install` and standalone MCP configuration remain supported; use one integration path per client to avoid duplicate skills or MCP servers. See the [plugin setup and security guide](docs/plugins.md).
+
+## Or use any shell-capable coding agent
+
+Without the native plugin, drop this into any shell-capable agent. It keeps
+credential setup private and asks before each persisted or quota-consuming
+operation:
 
 ```text
 Set up canonry for me. Canonry is an open-source platform that tracks how AI answer engines (Gemini, ChatGPT, Claude, Perplexity) cite my site.
 
 1. Ask me for: my domain, 3–5 queries I want to track, and which provider I want to start with (gemini / openai / claude / perplexity). Wait for my answers before proceeding.
-2. Run `npm install -g @canonry/canonry`.
-3. Run `cnry init` in this directory. This scaffolds config and installs the canonry skills into `.claude/skills/canonry/`, `.claude/skills/aero/`, `.codex/skills/canonry/`, and `.codex/skills/aero/`. If the skills aren't there afterwards, run `cnry skills install`.
-4. Read the operator playbook at `.claude/skills/canonry/SKILL.md` and follow it end-to-end: create the project with my domain and queries, wire up the provider key I chose, and trigger the first sweep.
-5. Open my browser to the dashboard so I can see the run results.
-6. Switch to the analyst playbook at `.claude/skills/aero/SKILL.md` and run a baseline AEO audit on my behalf. Read citation evidence with `cnry evidence <project> --format json`, then run `cnry technical-aeo run <project> --wait` followed by `cnry technical-aeo score <project> --format json` for a site-readiness score. This crawls every page in my sitemap (not just the homepage), scores the whole site 0–100, and saves the result so it appears in the dashboard and can be re-audited on a schedule.
-7. Summarize what you found: my mention and citation rates per provider, the top 3 queries I'm not yet cited on, and the highest-impact site issues from the audit. Ask me for permission before taking any further action, such as drafting content, submitting URLs for indexing, editing files, or anything else that changes my site.
+2. Ask for approval, then run `npm install -g @canonry/canonry`.
+3. Do not run `cnry init` yourself or ask me for credentials. Tell me to run `cnry init` in my own private terminal because it prompts for provider secrets and prints the new full-access API key once. Wait for me to confirm completion; never ask me to paste its output. This scaffolds config and installs the Canonry skills.
+4. Read `.claude/skills/canonry/SKILL.md`, run the read-only doctor checks, and show me the exact project/domain/query changes you propose. Ask for explicit approval before creating the project or changing queries.
+5. After project setup, show the provider and query count for the first sweep and ask for explicit approval for that quota-consuming run. Only then trigger it.
+6. Read `.claude/skills/aero/SKILL.md` and summarize the existing mention and citation evidence. Propose the technical audit, including its page limit, and ask for separate approval before running `cnry technical-aeo run <project> --wait`; after approval, read the result with `cnry technical-aeo score <project> --format json`.
+7. Open the dashboard only if I ask, then summarize what you found: mention and citation rates per provider, the top 3 gaps, and the highest-impact site issues. Ask again before drafting content, submitting URLs, editing files, publishing, or performing any other mutation or quota-consuming operation.
 ```
 
 One-click copy at [canonry.ai](https://canonry.ai).
@@ -100,11 +163,13 @@ Configure during `cnry init`, in the dashboard `/settings`, or as env vars.
 |---|---|
 | **Architecture & data model** | [docs/architecture.md](docs/architecture.md) · [docs/data-model.md](docs/data-model.md) |
 | **Aero — built-in agent** | [skills/aero/SKILL.md](skills/aero/SKILL.md) |
+| **Native plugins — Codex / Claude Code** | [docs/plugins.md](docs/plugins.md) |
 | **MCP — Claude Desktop / Cursor / Codex** | [docs/mcp.md](docs/mcp.md) |
 | **Integrations** | [GSC](docs/google-search-console-setup.md) · [GA4](docs/google-analytics-setup.md) · [Bing](docs/bing-webmaster-setup.md) · [Google Business Profile](skills/canonry/references/google-business-profile.md) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloud Run + Vercel + WordPress logs)](skills/canonry/references/server-side-traffic.md) |
 | **Deployment** — Docker, Railway, Render, systemd, Tailscale | [docs/deployment.md](docs/deployment.md) |
 | **API** — 118+ endpoints | `GET /api/v1/openapi.json` (no auth) |
-| **Skills bundle** for Claude Code / Codex | `cnry skills install` ([details](skills/canonry/SKILL.md)) |
+| **Standalone skills bundle** for Claude Code / Codex | `cnry skills install` ([details](skills/canonry/SKILL.md)) |
+| **Roadmap & ADRs** | [docs/roadmap.md](docs/roadmap.md) · [docs/adr/](docs/adr/) |
 | **All docs** | [docs/README.md](docs/README.md) |
 
 ## Requirements

package/assets/agent-workspace/skills/aero/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: aero
-slug: aero
 description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis with persistent memory and proactive regression response.
-homepage: https://canonry.ai
-repository: https://github.com/AINYC/aero
+metadata:
+  homepage: https://canonry.ai
+  repository: https://github.com/AINYC/aero
 ---
 
 # Aero Orchestration Skill
@@ -16,7 +16,7 @@ Persist only *user-scoped* context (operator preferences, communication style) i
 
 **Two signals, not one.** Every (query × provider) snapshot tracks **mentioned** (brand in answer text) and **cited** (domain in source links) independently. Lead with **Mention Coverage** when narrating health — it is the primary gauge — and report **Citation Coverage** as the secondary signal. Never compute one from the other, and never collapse them into a single "visibility" headline. The downloadable report (`cnry report`) and the dashboard hero both honor this split.
 
-When a project has GA4 connected, traffic is a first-class signal alongside mentions and citations. Use `cnry ga traffic` / `cnry ga attribution --trend` for the current snapshot, `cnry ga ai-referral-history` and `cnry ga social-referral-history` for daily series. Reads query a local DB synced by `cnry ga sync` — confirm `cnry ga status` shows a recent `lastSyncedAt` before quoting numbers; if stale, re-sync first. When the project has a server-side traffic source attached (Cloud Run / WordPress / Vercel), `cnry traffic status` and `cnry traffic events` surface crawler + AI-referral evidence the GA4 layer can miss. Full command reference and return shapes live in the co-installed `canonry/references/canonry-cli.md`.
+When a project has GA4 connected, traffic is a first-class signal alongside mentions and citations. Use `cnry ga traffic` / `cnry ga attribution --trend` for the current snapshot, `cnry ga ai-referral-history` and `cnry ga social-referral-history` for daily series. Reads query a local DB synced by `cnry ga sync` — confirm `cnry ga status` shows a recent `lastSyncedAt` before quoting numbers; if stale, ask for explicit approval before re-syncing. When the project has a server-side traffic source attached (Cloud Run / WordPress / Vercel), `cnry traffic status` and `cnry traffic events` surface crawler + AI-referral evidence the GA4 layer can miss. Full command reference and return shapes live in the co-installed `canonry/references/canonry-cli.md`.
 
 **Diagnosing a stuck Vercel/Cloud Run source:** if `cnry traffic status` shows `status=error` with a recent `lastError` of `refusing to advance` or `ExceedsBillingLimitError`, the source's `lastSyncedAt` has aged past the upstream retention boundary and every sync now throws. Recovery: `cnry traffic reset <project> --source <id> --advance-to-now`. This advances `lastSyncedAt` to NOW and resumes going-forward syncs — historical events in the gap are unrecoverable from the sync path; run `cnry traffic backfill --days N` separately if any of that history is needed (capped at retention).
 
@@ -35,19 +35,27 @@ Mention is the primary gauge (see "Two signals, not one" above); citation is the
 ### What NOT to Do
 - Don't promise fixes will appear in the next sweep (AEO changes take weeks/months)
 - Don't give generic SEO advice — always ground recommendations in mention and citation data, leading with the mention signal
-- Don't run sweeps without user confirmation (they consume API quota)
+- Don't run sweeps, probes, syncs, audits, discovery sessions, or any other write or quota-consuming operation without explicit user approval
 - Don't edit client's code without showing diffs and getting approval
 - Don't conflate "not mentioned" with "page doesn't exist" — and don't conflate "not cited" with "not mentioned" either; check first. The two signals are independent (see "Two signals, not one") and are never computed from each other.
 - Don't coerce `answerMentioned` null → false. Null means "not checked," not "not mentioned" — treat it as missing data, never as a negative.
 
 ### When to use `--probe` runs
-When you need to **verify** something on your own initiative — "did the OpenAI provider migration land cleanly?", "is the regression still reproducible after the WP fix?", "does this query actually surface us when I think it should?" — use `cnry run <project> --probe --provider <p> --query "..."`. Probe runs:
+When a verification would help, propose the exact probe and get explicit
+approval before running it. A probe is safer for metrics than a real sweep, but
+it is still a paid/quota-consuming write. After approval, use `cnry run
+<project> --probe --provider <p> --query "..."`. Probe runs:
 - Still cost provider API quota (same wire call)
 - Write a snapshot you can inspect via `cnry runs get <id>`
 - Are EXCLUDED from dashboard, analytics, intelligence, insights, and notifications
 - Won't wake you up again via the post-run hook (no recursive analysis loops)
 
-Use probes whenever the run is for **your** investigation, not for the user's metrics. The two May-17 ainyc probes that broke the dashboard before this convention existed are the canonical example of why this matters — a 1-snapshot test masqueraded as "the latest sweep" and zeroed the headline.
+Use an approved probe when the run is for investigation rather than the user's
+metrics. Approval for one probe does not authorize repeats; ask again unless
+the operator approved a specific bounded batch. The two May-17 ainyc probes
+that broke the dashboard before this convention existed are the canonical
+example of why this matters — a 1-snapshot test masqueraded as "the latest
+sweep" and zeroed the headline.
 
 A real (non-probe) sweep is appropriate when the user explicitly asks to refresh data ("run it again", "get the latest", "trigger a sweep").
 

package/assets/agent-workspace/skills/aero/references/aeo-discovery.md

@@ -31,7 +31,9 @@ After probing, one Gemini call classifies every recurring cited domain into a `c
 
 ## Triggering a session
 
-The operator runs:
+Discovery is a paid, quota-consuming write (about $1 at the default 100-probe
+budget). Show the proposed ICP, provider, and probe budget, then get explicit
+operator approval before starting a session. After approval, the operator runs:
 
 ```bash
 cnry discover run <project> --icp "..." --wait

package/assets/agent-workspace/skills/aero/references/orchestration.md

@@ -14,7 +14,7 @@ Trigger: First sweep completes for a new project
 Steps:
 1. `cnry overview <project> --format json` → mention read first: `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`. Then `cnry analytics <project> --feature gaps --format json` for `mentionedQueries[]` / `mentionGap[]` / `notMentioned[]`, and `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown and the secondary cited data.
 2. Compute baseline in this order: **mention rate, mention share**, then cited rate; provider breakdown; top/bottom queries by mention.
-3. `cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json` → site readiness score across every page in the sitemap (auto-discovered; add `--limit <n>` to `run` to cap, default 500). Persists to the dashboard and is trendable via `cnry technical-aeo trend <project>`.
+3. With explicit operator approval for the crawl and persisted run, `cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json` → site readiness score across every page in the sitemap (auto-discovered; add `--limit <n>` to `run` to cap, default 500). Persists to the dashboard and is trendable via `cnry technical-aeo trend <project>`.
 4. Identify top 3 gaps — lead with `mentionGap[]` / `notMentioned[]` (where competitors are named and you aren't), then the cited gaps with fixable site issues.
 5. Generate onboarding report with baseline + action plan
 6. Store baseline metrics in memory (include mention rate + mention share, not just cited rate)
@@ -34,13 +34,15 @@ Steps:
 8. If content fix: generate diff (schema, llms.txt, or content changes)
 9. Update memory with regression event + diagnosis (record which signal regressed: mention, citation, or both)
 
-**Want to verify the regression is real / reproducible before reporting?** Use a probe run instead of a real sweep:
+**Want to verify the regression is real / reproducible before reporting?**
+Propose the exact provider/query and get explicit approval, then use a probe
+run instead of a real sweep:
 
 ```
 cnry run <project> --probe --provider <p> --query "<regressed-query>"
 ```
 
-Then `cnry runs get <id>` to inspect the snapshot. The probe's snapshot won't displace the latest scheduled sweep on the dashboard, won't generate insights, and won't fire notifications — so you can re-test as many times as needed without polluting metrics. Promote to a real sweep (drop `--probe`) only if the operator explicitly wants the data to feed the dashboard.
+Then `cnry runs get <id>` to inspect the snapshot. The probe's snapshot won't displace the latest scheduled sweep on the dashboard, won't generate insights, and won't fire notifications. It still costs provider quota and writes a snapshot, so approval for one probe does not authorize repeats; ask again unless the operator approved a specific bounded batch. Promote to a real sweep (drop `--probe`) only if the operator explicitly wants the data to feed the dashboard.
 
 ## Workflow 3: Weekly Review
 

package/assets/agent-workspace/skills/aero/soul.md

@@ -12,7 +12,7 @@ You are **Aero** — an AEO analyst. You help operators understand whether AI an
 - **Evidence over opinion.** Numbers before interpretation. "ChatGPT stopped mentioning you for 'roof repair phoenix' between March 28 and April 2, and your mention share fell from 50% to 0%" beats "your visibility decreased" — then note the lost citation second.
 - **Proactive, not passive.** Regressions don't wait to be asked about. Surface them when you spot them. Flag competitors the moment they take mention share in answers you used to own, and when they appear in citations you own.
 - **Honest about uncertainty.** When the data is ambiguous, say so. Don't manufacture confidence. Don't promise fixes will appear in the next sweep — AEO changes take weeks.
-- **Cautious with writes.** Sweeps cost quota. Schedules shape downstream notifications. Queries define what gets tracked. Confirm intent before mutating state the operator will notice. When *you* need to test something (verify a fix, reproduce a regression), use `cnry run --probe` — same wire call, no dashboard/analytics/notification pollution.
+- **Cautious with writes.** Sweeps and probes cost quota. Schedules shape downstream notifications. Queries define what gets tracked. Get explicit approval before every write or quota-consuming operation, including probes whose snapshots stay out of dashboard metrics. When an approved test needs a run, prefer `cnry run --probe` over a real sweep — same wire call, no dashboard/analytics/notification pollution.
 - **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.
 
 ## Voice

package/assets/agent-workspace/skills/canonry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canonry
-description: "Agent-first AEO operating platform."
+description: "Set up and operate Canonry AEO projects: inspect mention and citation coverage, diagnose regressions, run technical audits, and act through the Canonry CLI or MCP tools."
 metadata:
   {
     "agent":
@@ -16,14 +16,6 @@ metadata:
               "bins": ["canonry"],
               "label": "Install canonry globally",
               "command": "npm install -g @canonry/canonry"
-            },
-            {
-              "id": "npx",
-              "kind": "npx",
-              "package": "@canonry/canonry",
-              "bins": ["canonry"],
-              "label": "Run canonry via npx",
-              "command": "npx @canonry/canonry@latest init"
             }
           ],
       },
@@ -38,6 +30,50 @@ Agent-first open-source AEO (Answer Engine Optimization) operating platform. Tra
 
 **CLI:** invoke as `cnry` (short form) or `canonry` — both ship with the npm package and are interchangeable. Examples in this skill use `cnry`.
 
+## Runtime Preflight
+
+Before using the native Codex or Claude Code plugin, verify the separately
+installed Canonry runtime. It requires Node.js 22.14 or newer, and the native
+plugin specifically needs the global package so `canonry-mcp` remains on
+`PATH`; a one-off `npx` invocation is not sufficient:
+
+```bash
+node --version
+command -v cnry
+cnry --version
+```
+
+Then prepare the runtime in this order:
+
+1. With approval, install the global runtime if `command -v cnry` failed.
+2. Check only whether `$CANONRY_CONFIG_DIR/config.yaml` (when that variable is
+   set) or `~/.canonry/config.yaml` exists; do not print the file. If it does
+   not exist, pause and ask the operator to run `cnry init --skip-skills --skip-mcp`
+   in their own private terminal, then confirm completion without
+   pasting the output. Never execute `init` inside the agent session: it prompts
+   for provider credentials and prints the new full-access API key once. The
+   plugin already supplies the skills and MCP registration.
+3. After a fresh initialization, get approval and run `cnry start --format
+   json`; `start` waits for the health endpoint before returning. On an
+   existing installation, try the doctor command first and start only when the
+   transport is unavailable. Never stop or restart a healthy daemon just to
+   install the plugin.
+4. Run `cnry doctor --format json` after the daemon is ready. A successful JSON
+   response proves the health-check path works; individual checks may still
+   report actionable `warn` or `fail` statuses. Plugin installation state is
+   read live, so installing the plugin alone does not require a daemon restart.
+
+Never ask the operator to paste credentials into the chat, print the raw API
+key, or inspect `~/.canonry/config.yaml` for secrets. The plugin does not expand
+the configured key's server-enforced scope, but it gives the client tools that
+can exercise that scope. Fresh `cnry init` creates a full-instance `*` key, so
+the default plugin has teammate-level access to every project and shared
+instance settings. A write-capable key exposes write tools by default; a
+read-only key restricts the catalog to reads, while a project-scoped key keeps
+its project route boundary but is not tenant isolation: a write-capable scoped
+key can still mutate shared instance settings. Do not work around a missing
+tool or `403` by switching credentials.
+
 ## When to Use
 
 - Tracking brand **mentions** in AI answer text and **citations** in source links across providers
@@ -74,13 +110,13 @@ Configure `spec.brandAliases` on the project (or pass via `cnry apply`) so the m
 
 A canonry engagement follows the same loop regardless of project size:
 
-1. **Diagnose** — Run a baseline sweep (`cnry run <project> --wait`) and a technical audit (`cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json`). The audit crawls every page in the project's sitemap (auto-discovered from `/sitemap.xml`, the sitemap index, or `robots.txt`) so readiness reflects the whole site, not just one page, and persists the score to the dashboard. Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.
+1. **Diagnose** — After explicit approval for the quota-consuming persisted runs, run a baseline sweep (`cnry run <project> --wait`) and a technical audit (`cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json`). The audit crawls every page in the project's sitemap (auto-discovered from `/sitemap.xml`, the sitemap index, or `robots.txt`) so readiness reflects the whole site, not just one page, and persists the score to the dashboard. Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.
 2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.
 3. **Execute** — Apply fixes via the canonry CLI or platform integrations. Use `--dry-run` on supported mutations (`cnry project delete`, `cnry query replace`, `cnry backfill ...`) to preview before committing. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.
-4. **Monitor** — Re-run sweeps weekly (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.
+4. **Monitor** — Re-run sweeps weekly only through an operator-approved schedule or after fresh explicit approval (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.
 5. **Report** — Lead with data, not interpretation: "Lost the mention for `<query>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `cnry report <project>` to generate a self-contained HTML bundle (mention + citation hero, competitor landscape, GSC + GA4 performance, insights, suggested next queries). Same payload is available via `--format json` and the `canonry_report` MCP tool.
 
-**Verifying without polluting metrics**: when you need to test something on your own initiative — "did the latest provider deploy work?", "is this regression reproducible?", "would this query actually surface us?" — use `cnry run <project> --probe --provider <p> --query "..."`. Probe runs write a snapshot you can inspect via `cnry runs get <id>` but are excluded from the dashboard, analytics, intelligence, report, and notifications. Use probes for *your* investigation; use real sweeps when the operator wants the data to feed metrics.
+**Verifying without polluting metrics**: when a test would help — "did the latest provider deploy work?", "is this regression reproducible?", "would this query actually surface us?" — propose the exact provider/query and get explicit approval before using `cnry run <project> --probe --provider <p> --query "..."`. Probe runs still cost quota and write a snapshot, but are excluded from the dashboard, analytics, intelligence, report, and notifications. Approval for one probe does not authorize repeats unless the operator approved a bounded batch; use real sweeps only when the operator wants the data to feed metrics.
 
 ## Surgical Reads
 
@@ -132,6 +168,7 @@ Aero also wakes unprompted after every `run.completed` so insights and regressio
 
 ## Boundaries & Safety
 
+- **Get explicit approval before every mutation or quota-consuming sweep** — reads and `--dry-run` previews are safe defaults
 - **Never touch live WordPress without explicit approval**
 - **Back up `~/.canonry/config.yaml` before any config edit**
 - **Never fabricate mention or citation data** — if a sweep hasn't run, say so; never coerce `answerMentioned` null → false (null = "not checked")
@@ -151,5 +188,5 @@ Aero also wakes unprompted after every `run.completed` so insights and regressio
 
 ---
 
-**Tools:** canonry v4+, @ainyc/aeo-audit v1.3+  
+**Tools:** canonry v4+, @ainyc/aeo-audit v1.3+
 **Website:** [canonry.ai](https://canonry.ai) | **Org:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)

package/assets/agent-workspace/skills/canonry/references/canonry-cli.md

@@ -15,6 +15,11 @@ cnry serve --embed --embed-allow-origin https://app.example.com   # read-only em
 cnry --version
 ```
 
+`cnry init` prompts for credentials and prints the new API key once. An agent
+must pause and ask the operator to run it in a private terminal, without
+pasting the output back. Do not run `init` or secret-bearing `bootstrap` inside
+an agent transcript.
+
 ### Read-only embed mode (#716)
 
 Opt-in, OFF by default. Renders the dashboard "chromeless" (no nav/topbar/settings) so it can be iframed read-only, and emits a fail-closed framing contract. With `--embed` absent, served HTML + headers are byte-for-byte unchanged.
@@ -115,7 +120,10 @@ Run statuses: `queued` → `running` → `completed` / `failed` / `partial`
 | `backfill` | `cnry backfill ...` | partial (historical) | ✅ | — | — |
 | **`probe`** | `cnry run --probe ...` | ❌ | ❌ | ❌ | ❌ |
 
-Use `--probe` whenever you're testing on your own initiative — verifying a fix landed, reproducing a regression, sanity-checking a query — rather than producing data the user/dashboard will consume.
+After explicit approval for the exact provider/query (or a bounded batch), use
+`--probe` for verification rather than producing data the user/dashboard will
+consume. A probe still costs provider quota and writes a snapshot; approval for
+one probe does not authorize repeats.
 
 `snapshot` does not create a project or write to the DB. It generates category queries, runs providers, and produces a report for prospecting.
 

package/assets/agent-workspace/skills/canonry/references/indexing.md

@@ -63,7 +63,9 @@ cnry google request-indexing <project> --all-unindexed
 - OAuth connection set up in canonry (`cnry settings` shows Google connection)
 - Officially intended for JobPosting/BroadcastEvent schema; in practice Google processes all URLs
 
-**After submitting:** Check coverage again after 48h. Once indexed, run a sweep — pages must be indexed before citation is possible.
+**After submitting:** Check coverage again after 48h. Once indexed, ask for
+explicit approval before running a quota-consuming sweep — pages must be
+indexed before citation is possible.
 
 ---
 
@@ -160,4 +162,4 @@ Expected response: `202 Accepted`
 4. Submit sitemap to Bing WMT (manual, one-time per site)
 5. Send IndexNow batch for key URLs
 6. Re-check coverage after 48h
-7. Run a sweep after pages confirmed indexed
+7. After explicit approval, run a sweep once pages are confirmed indexed

package/dist/{chunk-HQRUFTLN.js → chunk-EF67Y6CI.js}

@@ -18795,7 +18795,7 @@ var routeCatalog = [
     method: "post",
     path: "/api/v1/projects/{name}/ads/activation-grants/{grantId}/revoke",
     summary: "Revoke or cancel an OpenAI Ads activation grant",
-    description: "Human-only kill switch. Before execution, the grant becomes revoked. After execution starts, or while an activation outcome is unknown, revocationRequestedAt is recorded atomically. Subsequent activation steps are blocked, and the recovery worker rolls back confirmed active entities. Unknown outcomes remain explicitly unknown while the watchdog repeatedly issues exact-tree safety pauses. A provider request already authorized or in flight may still settle before containment. Verified rollback leaves the single-use grant consumed and the operation failed.",
+    description: "Human-only kill switch. Before execution, the grant becomes revoked. After execution starts, or while an activation outcome is unknown, revocationRequestedAt is recorded atomically. Subsequent activation steps are blocked, and the recovery worker rolls back confirmed active entities. Unknown outcomes remain explicitly unknown unless revocation was requested, the provider settlement window elapsed, and the watchdog can enumerate the complete provider tree and verify every entity paused. A provider request already authorized or in flight may still settle before containment. Verified rollback leaves the single-use grant consumed and the operation failed.",
     tags: ["ads"],
     parameters: [
       nameParameter,
@@ -23338,6 +23338,13 @@ function stableStringify3(value) {
 }
 
 // ../api-routes/src/google.ts
+function isOnProjectDomain(url, projectDomain) {
+  try {
+    return new URL(url).hostname.toLowerCase().replace(/^www\./, "") === projectDomain;
+  } catch {
+    return false;
+  }
+}
 function scopesForConnectionType(type) {
   switch (type) {
     case "gsc":
@@ -24142,14 +24149,21 @@ async function googleRoutes(app, opts) {
           latestByUrl.set(row.url, row);
         }
       }
+      const gatherDomain = normalizeProjectDomain(project.canonicalDomain);
       const unindexedUrls = [];
+      let skippedOtherHost = 0;
       for (const [url, row] of latestByUrl) {
-        if (row.indexingState !== "INDEXING_ALLOWED") {
-          unindexedUrls.push(url);
+        if (row.indexingState === "INDEXING_ALLOWED") continue;
+        if (!isOnProjectDomain(url, gatherDomain)) {
+          skippedOtherHost += 1;
+          continue;
         }
+        unindexedUrls.push(url);
       }
       if (unindexedUrls.length === 0) {
-        throw validationError('No unindexed URLs found. Run "canonry google inspect-sitemap" first.');
+        throw validationError(
+          skippedOtherHost > 0 ? `No unindexed URLs found on "${project.canonicalDomain}" (skipped ${skippedOtherHost} on other hosts). Run "canonry google inspect-sitemap" first.` : 'No unindexed URLs found. Run "canonry google inspect-sitemap" first.'
+        );
       }
       urlsToNotify = unindexedUrls;
     }
@@ -24160,14 +24174,7 @@ async function googleRoutes(app, opts) {
       throw validationError(`Cannot request indexing for more than ${INDEXING_API_DAILY_LIMIT} URLs per request (got ${urlsToNotify.length})`);
     }
     const projectDomain = normalizeProjectDomain(project.canonicalDomain);
-    const invalidUrls = urlsToNotify.filter((url) => {
-      try {
-        const hostname = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
-        return hostname !== projectDomain;
-      } catch {
-        return true;
-      }
-    });
+    const invalidUrls = urlsToNotify.filter((url) => !isOnProjectDomain(url, projectDomain));
     if (invalidUrls.length > 0) {
       throw validationError(
         `URLs must belong to project domain "${project.canonicalDomain}". Invalid: ${invalidUrls.slice(0, 5).join(", ")}`
@@ -25989,6 +25996,7 @@ async function executeApprovedAdsActivation(dependencies, request) {
 // ../api-routes/src/ads-activation-routes.ts
 var MAX_ACTIVATION_GRANT_LIFETIME_MS = 24 * 60 * 60 * 1e3;
 var ACTIVATION_LEASE_MS = 5 * 6e4;
+var ACTIVATION_REVOCATION_SETTLEMENT_MS = ACTIVATION_LEASE_MS;
 var ACTIVATION_STEP_INSERT_BATCH_SIZE = 40;
 function parseBody(schema, value) {
   const parsed = schema.safeParse(value);
@@ -26554,6 +26562,56 @@ function selectWatchdogOperations(app, nowIso, batchSize, allowLiveRevocationLea
 function selectRecoveryWatchdogOperations(app, nowIso, batchSize) {
   return selectWatchdogOperations(app, nowIso, batchSize, false);
 }
+function finalizeContainedRevokedUnknownActivation(app, operation, grant) {
+  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  const revocationRequestedAt = grant.revocationRequestedAt === null ? Number.NaN : Date.parse(grant.revocationRequestedAt);
+  if (!Number.isFinite(revocationRequestedAt) || Date.parse(nowIso) - revocationRequestedAt < ACTIVATION_REVOCATION_SETTLEMENT_MS) {
+    return false;
+  }
+  return app.db.transaction((tx) => {
+    const operationUpdate = tx.update(adsOperations).set({
+      state: AdsOperationStates.failed,
+      errorCode: AdsActivationErrorCodes.grantRevoked,
+      errorMessage: "Ads activation was cancelled and the provider tree was verified paused",
+      leaseOwner: null,
+      leaseExpiresAt: null,
+      lastReconciledAt: nowIso,
+      updatedAt: nowIso
+    }).where(and19(
+      eq25(adsOperations.id, operation.id),
+      eq25(adsOperations.state, AdsOperationStates.unknown)
+    )).run();
+    if (operationUpdate.changes !== 1) return false;
+    const grantUpdate = tx.update(adsActivationGrants).set({
+      state: AdsActivationGrantStates.consumed,
+      consumedAt: nowIso,
+      updatedAt: nowIso
+    }).where(and19(
+      eq25(adsActivationGrants.id, grant.id),
+      eq25(adsActivationGrants.operationId, operation.id),
+      eq25(adsActivationGrants.state, AdsActivationGrantStates.unknown),
+      isNotNull(adsActivationGrants.revocationRequestedAt)
+    )).run();
+    if (grantUpdate.changes !== 1) {
+      throw internalError("Revoked unknown ads activation could not be finalized");
+    }
+    writeAuditLog(tx, {
+      projectId: operation.projectId,
+      actor: "system",
+      action: "ads.campaign_tree_activate.failed",
+      entityType: AdsActivationEntityTypes.campaign,
+      entityId: operation.entityId,
+      diff: {
+        operationId: operation.id,
+        operationKey: operation.operationKey,
+        grantId: grant.id,
+        reason: "revoked_and_verified_paused"
+      },
+      userAgent: "canonry-activation-watchdog"
+    });
+    return true;
+  }, { behavior: "immediate" });
+}
 function validateWatchdogContainmentBinding(app, opts, operation, grant) {
   const terminal = terminalActivationResponse(app, opts, grant, operation.operationKey);
   if (terminal) {
@@ -26703,6 +26761,13 @@ async function sweepStaleAdsActivationsOnce(app, opts) {
         runtime.provider,
         grant.manifest
       );
+      if (safety.fullyVerified && grant.revocationRequestedAt !== null && finalizeContainedRevokedUnknownActivation(app, operation, grant)) {
+        app.log.warn(
+          { operationId: operation.id },
+          "Revoked unknown ads activation was finalized after verified pause"
+        );
+        return;
+      }
       app.db.update(adsOperations).set({
         reconcileAttempts: operation.reconcileAttempts + 1,
         lastReconciledAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -38362,12 +38427,47 @@ import crypto29 from "crypto";
 import fs6 from "fs";
 import path7 from "path";
 var REQUIRED_SKILLS = ["canonry", "aero"];
+function pluginStateFor(ctx) {
+  try {
+    return ctx.getAgentPluginState?.();
+  } catch {
+    return void 0;
+  }
+}
+function unverifiedPluginClients(state) {
+  if (!state) return [];
+  return state.configuredClients.filter((client) => !state.verifiedClients.includes(client));
+}
+function displayPluginClients(clients) {
+  return clients.map((client) => client === "claude-code" ? "Claude Code" : "Codex").join(" + ");
+}
 var skillsInstalledCheck = {
   id: "agent.skills.installed",
   category: CheckCategories.agent,
   scope: CheckScopes.global,
-  title: "Agent skills installed (~/.claude/skills/)",
-  run: () => {
+  title: "Agent skills available",
+  run: (ctx) => {
+    const agentPlugin = pluginStateFor(ctx);
+    const unverifiedClients = unverifiedPluginClients(agentPlugin);
+    if (unverifiedClients.length > 0) {
+      return {
+        status: CheckStatuses.warn,
+        code: "agent.skills.plugin-unverified",
+        summary: `The Canonry plugin is enabled for ${displayPluginClients(unverifiedClients)}, but its cached manifest and skill assets could not be verified.`,
+        remediation: "Reinstall `canonry@canonry` with the affected client plugin manager, or disable the stale plugin entry.",
+        details: { delivery: "plugin", ...agentPlugin, unverifiedClients }
+      };
+    }
+    if (agentPlugin && agentPlugin.configuredClients.length > 0) {
+      const clients = displayPluginClients(agentPlugin.verifiedClients);
+      return {
+        status: CheckStatuses.ok,
+        code: "agent.skills.plugin-installed",
+        summary: `Canonry skills are available through the verified native ${clients} plugin${agentPlugin.verifiedClients.length === 1 ? "" : "s"}.`,
+        remediation: null,
+        details: { delivery: "plugin", ...agentPlugin }
+      };
+    }
     const home = process.env.HOME;
     if (!home) {
       return {
@@ -38388,7 +38488,8 @@ var skillsInstalledCheck = {
     const details = {
       checkedPath: skillsBase,
       installed,
-      missing
+      missing,
+      ...agentPlugin ? { agentPlugin } : {}
     };
     if (missing.length === 0) {
       return {
@@ -38421,9 +38522,51 @@ var skillsCurrentCheck = {
   id: "agent.skills.current",
   category: CheckCategories.agent,
   scope: CheckScopes.global,
-  title: "Agent skills up to date (~/.claude/skills/)",
+  title: "Agent skills up to date",
   run: (ctx) => {
+    const agentPlugin = pluginStateFor(ctx);
     const bundled = ctx.bundledSkills;
+    const unverifiedClients = unverifiedPluginClients(agentPlugin);
+    if (unverifiedClients.length > 0) {
+      return {
+        status: CheckStatuses.warn,
+        code: "agent.skills.plugin-unverified",
+        summary: `The Canonry plugin cache could not be verified for ${displayPluginClients(unverifiedClients)}; freshness cannot be assessed.`,
+        remediation: "Reinstall `canonry@canonry` with the affected client plugin manager, or disable the stale plugin entry.",
+        details: { delivery: "plugin", ...agentPlugin, unverifiedClients }
+      };
+    }
+    if (agentPlugin && agentPlugin.configuredClients.length > 0) {
+      const clients = displayPluginClients(agentPlugin.verifiedClients);
+      if (!bundled || bundled.length === 0) {
+        return {
+          status: CheckStatuses.skipped,
+          code: "agent.skills.bundle-unavailable",
+          summary: `Canonry skills are supplied by the verified native ${clients} plugin${agentPlugin.verifiedClients.length === 1 ? "" : "s"}, but the running bundle version is unavailable for comparison.`,
+          remediation: null,
+          details: { delivery: "plugin", ...agentPlugin }
+        };
+      }
+      const bundledVersion2 = bundled[0].version;
+      const mismatchedClients = agentPlugin.verifiedClients.filter((client) => agentPlugin.verifiedClientVersions?.[client] !== bundledVersion2);
+      if (mismatchedClients.length > 0) {
+        const versions = mismatchedClients.map((client) => `${client === "claude-code" ? "Claude Code" : "Codex"} v${agentPlugin.verifiedClientVersions?.[client] ?? "unknown"}`).join(", ");
+        return {
+          status: CheckStatuses.warn,
+          code: "agent.skills.plugin-version-mismatch",
+          summary: `${versions} ${mismatchedClients.length === 1 ? "does" : "do"} not match the running Canonry v${bundledVersion2}; plugin skills may be stale or incompatible.`,
+          remediation: "Update the Canonry runtime and `canonry@canonry` plugin to the same version with the affected client plugin manager.",
+          details: { delivery: "plugin", bundledVersion: bundledVersion2, ...agentPlugin, mismatchedClients }
+        };
+      }
+      return {
+        status: CheckStatuses.ok,
+        code: "agent.skills.plugin-current",
+        summary: `Canonry skills are supplied by the verified native ${clients} plugin${agentPlugin.verifiedClients.length === 1 ? "" : "s"} at the running version (v${bundledVersion2}).`,
+        remediation: null,
+        details: { delivery: "plugin", bundledVersion: bundledVersion2, ...agentPlugin }
+      };
+    }
     if (!bundled || bundled.length === 0) {
       return {
         status: CheckStatuses.skipped,
@@ -40427,7 +40570,8 @@ async function doctorRoutes(app, opts) {
       getAgentProviderSummary: opts.getAgentProviderSummary,
       trafficSourceValidators: opts.trafficSourceValidators,
       runtimeStatePaths: opts.runtimeStatePaths,
-      bundledSkills: opts.bundledSkills
+      bundledSkills: opts.bundledSkills,
+      getAgentPluginState: opts.getAgentPluginState
     };
     return runChecks(ctx, ALL_CHECKS, { checkIds });
   });
@@ -40454,7 +40598,8 @@ async function doctorRoutes(app, opts) {
       getAgentProviderSummary: opts.getAgentProviderSummary,
       trafficSourceValidators: opts.trafficSourceValidators,
       runtimeStatePaths: opts.runtimeStatePaths,
-      bundledSkills: opts.bundledSkills
+      bundledSkills: opts.bundledSkills,
+      getAgentPluginState: opts.getAgentPluginState
     };
     return runChecks(ctx, ALL_CHECKS, { checkIds });
   });
@@ -41496,7 +41641,8 @@ async function apiRoutes(app, opts) {
       getAgentProviderSummary: opts.getAgentProviderSummary,
       trafficSourceValidators: buildTrafficSourceValidators(opts),
       runtimeStatePaths: opts.runtimeStatePaths,
-      bundledSkills: opts.bundledSkills
+      bundledSkills: opts.bundledSkills,
+      getAgentPluginState: opts.getAgentPluginState
     });
     if (opts.registerAuthenticatedRoutes) {
       await opts.registerAuthenticatedRoutes(api);

package/dist/{chunk-A4YBV4Y4.js → chunk-ZHWWSU7H.js}

@@ -116,7 +116,7 @@ import {
   siteAuditPages,
   siteAuditSnapshots,
   usageCounters
-} from "./chunk-HQRUFTLN.js";
+} from "./chunk-EF67Y6CI.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -6967,7 +6967,7 @@ function readStoredGroundingSources(rawResponse) {
   return result;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-2WKS3EWJ.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-NTIKN7YG.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -7776,7 +7776,7 @@ function emitInstallSummary(summary, format) {
 Target: ${summary.targetDir}`);
   console.log(summary.message);
 }
-function getMissingUserSkillsNudge(home) {
+function getMissingUserSkillsNudge(home, agentPlugin) {
   if (!home) return null;
   const skillsBase = path5.join(home, ".claude", "skills");
   const installed = [];
@@ -7786,6 +7786,25 @@ function getMissingUserSkillsNudge(home) {
     if (existsSafe(skillFile)) installed.push(name);
     else missing.push(name);
   }
+  if (agentPlugin && agentPlugin.configuredClients.length > 0) {
+    const unverifiedClients = agentPlugin.configuredClients.filter((client) => !agentPlugin.verifiedClients.includes(client));
+    const mismatchedClients = agentPlugin.verifiedClients.filter((client) => agentPlugin.verifiedClientVersions?.[client] !== PACKAGE_VERSION);
+    if (unverifiedClients.length === 0 && mismatchedClients.length === 0) return null;
+    const displayClients = (clients) => clients.map((client) => client === "claude-code" ? "Claude Code" : "Codex").join(" + ");
+    const problems = [];
+    if (unverifiedClients.length > 0) {
+      problems.push(`The Canonry plugin is enabled for ${displayClients(unverifiedClients)}, but its cached manifest and skill assets could not be verified.`);
+    }
+    if (mismatchedClients.length > 0) {
+      const versions = mismatchedClients.map((client) => `${client === "claude-code" ? "Claude Code" : "Codex"} v${agentPlugin.verifiedClientVersions?.[client] ?? "unknown"}`).join(", ");
+      problems.push(`${versions} ${mismatchedClients.length === 1 ? "does" : "do"} not match the running Canonry v${PACKAGE_VERSION}.`);
+    }
+    return {
+      message: `Tip: ${problems.join(" ")} Update or reinstall \`canonry@canonry\` with the affected client plugin manager.`,
+      missing,
+      installed
+    };
+  }
   if (missing.length === 0) return null;
   const fix = missing.length === BUNDLED_SKILL_NAMES.length ? "canonry skills install --user" : `canonry skills install ${missing.join(" ")} --user`;
   return {
@@ -12574,6 +12593,7 @@ async function createServer(opts) {
         return void 0;
       }
     })(),
+    getAgentPluginState: opts.getAgentPluginState,
     // Local canonry serve runs on the operator's machine, where pointing a
     // webhook at localhost (Discord test container, Pipedream-mock dev server,
     // etc.) is a legitimate workflow. Default to allowing it for the local

package/dist/cli.js

@@ -29,7 +29,7 @@ import {
   setTelemetrySource,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-A4YBV4Y4.js";
+} from "./chunk-ZHWWSU7H.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -54,7 +54,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-HQRUFTLN.js";
+} from "./chunk-EF67Y6CI.js";
 import {
   AdsOperationKinds,
   AdsOperationStates,
@@ -141,9 +141,9 @@ import { parseArgs } from "util";
 function commandId(spec) {
   return spec.path.join(".");
 }
-function matchesPath(args, path11) {
-  if (args.length < path11.length) return false;
-  return path11.every((segment, index) => args[index] === segment);
+function matchesPath(args, path12) {
+  if (args.length < path12.length) return false;
+  return path12.every((segment, index) => args[index] === segment);
 }
 function withGlobalOptions(options) {
   const base = options ? { ...options } : {};
@@ -3506,9 +3506,9 @@ async function gaConnect(project, opts) {
     propertyId: opts.propertyId
   };
   if (opts.keyFile) {
-    const fs15 = await import("fs");
+    const fs16 = await import("fs");
     try {
-      const content = fs15.readFileSync(opts.keyFile, "utf-8");
+      const content = fs16.readFileSync(opts.keyFile, "utf-8");
       JSON.parse(content);
       body.keyJson = content;
     } catch (e) {
@@ -4766,9 +4766,9 @@ async function getCommand(opts) {
     console.log(JSON.stringify(leaf, null, 2));
   }
 }
-function walkPath(value, path11) {
-  if (!path11 || path11 === ".") return value;
-  const segments = path11.split(".").flatMap((part) => {
+function walkPath(value, path12) {
+  if (!path12 || path12 === ".") return value;
+  const segments = path12.split(".").flatMap((part) => {
     const tokens = [];
     let i = 0;
     const bracketStart = part.indexOf("[");
@@ -4816,13 +4816,13 @@ var GET_CLI_COMMANDS = [
     },
     run: async (input) => {
       const project = requireProject(input, "get", USAGE2);
-      const path11 = requirePositional(input, 1, {
+      const path12 = requirePositional(input, 1, {
         command: "get",
         usage: USAGE2,
         message: 'path is required (e.g. "scores.mentionShare.value")'
       });
       const from = getString(input.values, "from");
-      await getCommand({ project, path: path11, from, format: input.format });
+      await getCommand({ project, path: path12, from, format: input.format });
     }
   }
 ];
@@ -4861,9 +4861,9 @@ async function trafficConnectWordpress(project, opts) {
   }
   let applicationPassword = opts.appPassword?.trim() ?? "";
   if (!applicationPassword && opts.appPasswordFile) {
-    const fs15 = await import("fs");
+    const fs16 = await import("fs");
     try {
-      applicationPassword = fs15.readFileSync(opts.appPasswordFile, "utf-8").trim();
+      applicationPassword = fs16.readFileSync(opts.appPasswordFile, "utf-8").trim();
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       throw new CliError({
@@ -4919,10 +4919,10 @@ async function trafficConnectCloudRun(project, opts) {
       details: { project }
     });
   }
-  const fs15 = await import("fs");
+  const fs16 = await import("fs");
   let keyJson;
   try {
-    keyJson = fs15.readFileSync(opts.serviceAccountKey, "utf-8");
+    keyJson = fs16.readFileSync(opts.serviceAccountKey, "utf-8");
     JSON.parse(keyJson);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
@@ -4982,9 +4982,9 @@ async function trafficConnectVercel(project, opts) {
   }
   let token = opts.token?.trim() ?? "";
   if (!token && opts.tokenFile) {
-    const fs15 = await import("fs");
+    const fs16 = await import("fs");
     try {
-      token = fs15.readFileSync(opts.tokenFile, "utf-8").trim();
+      token = fs16.readFileSync(opts.tokenFile, "utf-8").trim();
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       throw new CliError({
@@ -12026,6 +12026,177 @@ function encodeSetupState(state) {
   return flags.length > 0 ? flags.sort().join("|") : "none";
 }
 
+// src/agent-plugin.ts
+import fs14 from "fs";
+import path11 from "path";
+var CANONRY_PLUGIN_ID = "canonry@canonry";
+var REQUIRED_SKILLS = ["canonry", "aero"];
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9a-z.-]+))?(?:\+[0-9a-z.-]+)?$/i.exec(version);
+  if (!match) return null;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match.at(4)?.split(".")
+  };
+}
+function compareSemver(left, right) {
+  const leftVersion = parseSemver(left);
+  const rightVersion = parseSemver(right);
+  for (let index = 0; index < leftVersion.core.length; index += 1) {
+    if (leftVersion.core[index] !== rightVersion.core[index]) {
+      return leftVersion.core[index] > rightVersion.core[index] ? 1 : -1;
+    }
+  }
+  if (!leftVersion.prerelease && !rightVersion.prerelease) return 0;
+  if (!leftVersion.prerelease) return 1;
+  if (!rightVersion.prerelease) return -1;
+  const length = Math.max(leftVersion.prerelease.length, rightVersion.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftIdentifier = leftVersion.prerelease.at(index);
+    const rightIdentifier = rightVersion.prerelease.at(index);
+    if (leftIdentifier === void 0) return -1;
+    if (rightIdentifier === void 0) return 1;
+    if (leftIdentifier === rightIdentifier) continue;
+    const leftNumeric = /^\d+$/.test(leftIdentifier);
+    const rightNumeric = /^\d+$/.test(rightIdentifier);
+    if (leftNumeric && rightNumeric) return Number(leftIdentifier) > Number(rightIdentifier) ? 1 : -1;
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftIdentifier > rightIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+function isCanonryPluginId(value) {
+  return value.trim() === CANONRY_PLUGIN_ID;
+}
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs14.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readClaudePluginConfigured(filePath) {
+  const parsed = readJson(filePath);
+  if (!parsed || typeof parsed !== "object") return false;
+  const enabledPlugins = parsed.enabledPlugins;
+  if (!enabledPlugins || typeof enabledPlugins !== "object") return false;
+  for (const [id, enabled] of Object.entries(enabledPlugins)) {
+    if (isCanonryPluginId(id)) return enabled === true;
+  }
+  return false;
+}
+function readCodexPluginConfigured(filePath) {
+  try {
+    let currentPlugin = null;
+    let inPluginsTable = false;
+    for (const line of fs14.readFileSync(filePath, "utf8").split(/\r?\n/)) {
+      const section = /^\s*\[plugins\.(?:"([^"]+)"|'([^']+)'|(\S+))\]\s*(?:#.*)?$/.exec(line);
+      if (section) {
+        const captures = section.slice(1, 4);
+        currentPlugin = captures.find((value) => value != null && value.length > 0) ?? null;
+        inPluginsTable = false;
+        continue;
+      }
+      if (/^\s*\[plugins\]\s*(?:#.*)?$/.test(line)) {
+        currentPlugin = null;
+        inPluginsTable = true;
+        continue;
+      }
+      if (/^\s*\[/.test(line)) {
+        currentPlugin = null;
+        inPluginsTable = false;
+        continue;
+      }
+      if (currentPlugin && isCanonryPluginId(currentPlugin)) {
+        const enabled = /^\s*enabled\s*=\s*(true|false)\s*(?:#.*)?$/.exec(line);
+        if (enabled) return enabled[1] === "true";
+      } else if (inPluginsTable) {
+        const inline = /^\s*(?:"([^"]+)"|'([^']+)'|([^=\s]+))\s*=\s*\{[^}]*\benabled\s*=\s*(true|false)\b[^}]*\}\s*(?:#.*)?$/.exec(line);
+        const id = inline?.[1] ?? inline?.[2] ?? inline?.[3];
+        if (inline && id && isCanonryPluginId(id)) return inline[4] === "true";
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function verifiedPluginVersion(root, client) {
+  const manifestDir = client === "claude-code" ? ".claude-plugin" : ".codex-plugin";
+  const manifest = readJson(path11.join(root, manifestDir, "plugin.json"));
+  if (!manifest || typeof manifest !== "object") return null;
+  const plugin = manifest;
+  if (plugin.name !== "canonry" || typeof plugin.version !== "string" || !parseSemver(plugin.version) || plugin.skills !== "./skills/" || plugin.mcpServers !== "./.mcp.json") {
+    return null;
+  }
+  const mcp = readJson(path11.join(root, ".mcp.json"));
+  if (!mcp || typeof mcp !== "object") return null;
+  const canonryServer = mcp.mcpServers?.canonry;
+  if (canonryServer?.command !== "canonry-mcp") return null;
+  return REQUIRED_SKILLS.every((name) => fs14.existsSync(path11.join(root, "skills", name, "SKILL.md"))) ? plugin.version : null;
+}
+function readClaudeUserInstallPaths(claudeConfigDir) {
+  const parsed = readJson(path11.join(claudeConfigDir, "plugins", "installed_plugins.json"));
+  if (!parsed || typeof parsed !== "object") return [];
+  const plugins = parsed.plugins;
+  if (!plugins || typeof plugins !== "object") return [];
+  const installs = plugins[CANONRY_PLUGIN_ID];
+  if (!Array.isArray(installs)) return [];
+  return installs.flatMap((install) => {
+    if (!install || typeof install !== "object") return [];
+    const record = install;
+    return record.scope === "user" && typeof record.installPath === "string" ? [record.installPath] : [];
+  });
+}
+function listDirectories(dir) {
+  try {
+    return fs14.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path11.join(dir, entry.name));
+  } catch {
+    return [];
+  }
+}
+function newestVersion(versions) {
+  return versions.sort(compareSemver).at(-1) ?? null;
+}
+function verifiedClaudeVersion(claudeConfigDir) {
+  return newestVersion(readClaudeUserInstallPaths(claudeConfigDir).map((installPath) => verifiedPluginVersion(installPath, "claude-code")).filter((version) => version !== null));
+}
+function verifiedCodexVersion(codexHome) {
+  const pluginCache = path11.join(codexHome, "plugins", "cache", "canonry", "canonry");
+  const versionedRoots = listDirectories(pluginCache).map((installPath) => ({ installPath, version: path11.basename(installPath) })).filter((candidate) => parseSemver(candidate.version) !== null).sort((left, right) => compareSemver(left.version, right.version));
+  const active = versionedRoots.at(-1);
+  if (!active) return verifiedPluginVersion(pluginCache, "codex");
+  const manifestVersion = verifiedPluginVersion(active.installPath, "codex");
+  return manifestVersion === active.version ? manifestVersion : null;
+}
+function detectCanonryAgentPlugin(opts = {}) {
+  const home = opts.home?.trim() || null;
+  const claudeConfigDir = opts.claudeConfigDir?.trim() || (home ? path11.join(home, ".claude") : null);
+  const codexHome = opts.codexHome?.trim() || (home ? path11.join(home, ".codex") : null);
+  const configuredClients = [];
+  const verifiedClients = [];
+  const verifiedClientVersions = {};
+  const claudeConfigured = claudeConfigDir ? readClaudePluginConfigured(path11.join(claudeConfigDir, "settings.json")) : false;
+  if (claudeConfigured) {
+    configuredClients.push("claude-code");
+    const version = claudeConfigDir ? verifiedClaudeVersion(claudeConfigDir) : null;
+    if (version) {
+      verifiedClients.push("claude-code");
+      verifiedClientVersions["claude-code"] = version;
+    }
+  }
+  const codexConfigured = codexHome ? readCodexPluginConfigured(path11.join(codexHome, "config.toml")) : false;
+  if (codexConfigured) {
+    configuredClients.push("codex");
+    const version = codexHome ? verifiedCodexVersion(codexHome) : null;
+    if (version) {
+      verifiedClients.push("codex");
+      verifiedClientVersions.codex = version;
+    }
+  }
+  return { configuredClients, verifiedClients, verifiedClientVersions };
+}
+
 // src/commands/serve.ts
 function resolveServePort(envPort, configPort) {
   const trimmed = envPort?.trim();
@@ -12063,7 +12234,12 @@ async function serveCommand(format = "text") {
     process.stderr.write(`warning: ai-referral-paths backfill skipped: ${msg}
 `);
   }
-  const app = await createServer({ config, db, host });
+  const getAgentPluginState = () => detectCanonryAgentPlugin({
+    home: process.env.HOME,
+    claudeConfigDir: process.env.CLAUDE_CONFIG_DIR,
+    codexHome: process.env.CODEX_HOME
+  });
+  const app = await createServer({ config, db, host, getAgentPluginState });
   let shuttingDown = false;
   const shutdown = (signal) => {
     if (shuttingDown) return;
@@ -12099,7 +12275,7 @@ Canonry server running at ${url}`);
         console.log("First-run dashboard password setup is unauthenticated only on loopback; complete setup from this machine first or use a bearer cnry_... key.");
       }
       console.log("Press Ctrl+C to stop.\n");
-      const nudge = getMissingUserSkillsNudge(process.env.HOME);
+      const nudge = getMissingUserSkillsNudge(process.env.HOME, getAgentPluginState());
       if (nudge) process.stderr.write(`${nudge.message}
 `);
     }
@@ -12855,7 +13031,7 @@ var VISIBILITY_STATS_CLI_COMMANDS = [
 ];
 
 // src/cli-commands/wordpress.ts
-import fs14 from "fs";
+import fs15 from "fs";
 
 // src/commands/wordpress.ts
 function getClient26() {
@@ -13094,12 +13270,12 @@ async function wordpressSetMeta(project, body) {
   printPageDetail(result);
 }
 async function wordpressBulkSetMeta(project, opts) {
-  const fs15 = await import("fs/promises");
-  const path11 = await import("path");
-  const filePath = path11.resolve(opts.from);
+  const fs16 = await import("fs/promises");
+  const path12 = await import("path");
+  const filePath = path12.resolve(opts.from);
   let raw;
   try {
-    raw = await fs15.readFile(filePath, "utf8");
+    raw = await fs16.readFile(filePath, "utf8");
   } catch {
     throw new CliError({
       code: "FILE_READ_ERROR",
@@ -13196,13 +13372,13 @@ async function wordpressSetSchema(project, body) {
   printManualAssist(`Schema update for "${body.slug}"`, result);
 }
 async function wordpressSchemaDeploy(project, opts) {
-  const fs15 = await import("fs/promises");
-  const path11 = await import("path");
+  const fs16 = await import("fs/promises");
+  const path12 = await import("path");
   const yaml = await loadYamlModule();
-  const filePath = path11.resolve(opts.profile);
+  const filePath = path12.resolve(opts.profile);
   let raw;
   try {
-    raw = await fs15.readFile(filePath, "utf8");
+    raw = await fs16.readFile(filePath, "utf8");
   } catch {
     throw new CliError({
       code: "FILE_READ_ERROR",
@@ -13307,13 +13483,13 @@ async function wordpressOnboard(project, opts) {
   }
   let profileData;
   if (opts.profile) {
-    const fs15 = await import("fs/promises");
-    const path11 = await import("path");
+    const fs16 = await import("fs/promises");
+    const path12 = await import("path");
     const yaml = await loadYamlModule();
-    const filePath = path11.resolve(opts.profile);
+    const filePath = path12.resolve(opts.profile);
     let raw;
     try {
-      raw = await fs15.readFile(filePath, "utf8");
+      raw = await fs16.readFile(filePath, "utf8");
     } catch {
       throw new CliError({
         code: "FILE_READ_ERROR",
@@ -13462,7 +13638,7 @@ function resolveContent(input, command, usage, options) {
   }
   if (contentFile) {
     try {
-      return fs14.readFileSync(contentFile, "utf-8");
+      return fs15.readFileSync(contentFile, "utf-8");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw usageError(`Error: could not read --content-file "${contentFile}": ${message}`, {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { FastifyInstance } from 'fastify';
 import { DatabaseClient } from '@ainyc/canonry-db';
-import { ProviderQuotaPolicy, EmbedConfigEntry } from '@ainyc/canonry-contracts';
+import { ProviderQuotaPolicy, EmbedConfigEntry, AgentPluginState } from '@ainyc/canonry-contracts';
 
 type GoogleConnectionType = 'gsc' | 'ga4' | 'gbp';
 interface ProviderConfigEntry {
@@ -264,6 +264,8 @@ declare function createServer(opts: {
      * assert the injected config + framing header on the served document.
      */
     assetsDir?: string;
+    /** Live user-global native Canonry plugin state for agent-skills doctor checks. */
+    getAgentPluginState?: () => AgentPluginState;
 }): Promise<FastifyInstance>;
 
 export { type CanonryConfig, createServer, loadConfig };

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   createServer
-} from "./chunk-A4YBV4Y4.js";
+} from "./chunk-ZHWWSU7H.js";
 import {
   loadConfig
 } from "./chunk-IHRW6WWV.js";
-import "./chunk-HQRUFTLN.js";
+import "./chunk-EF67Y6CI.js";
 import "./chunk-BLSHHRRU.js";
 export {
   createServer,

package/dist/{intelligence-service-2WKS3EWJ.js → intelligence-service-NTIKN7YG.js}

@@ -1,6 +1,6 @@
 import {
   IntelligenceService
-} from "./chunk-HQRUFTLN.js";
+} from "./chunk-EF67Y6CI.js";
 import "./chunk-BLSHHRRU.js";
 export {
   IntelligenceService

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonry/canonry",
-  "version": "4.127.0",
+  "version": "4.129.0",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -66,26 +66,26 @@
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "@ainyc/canonry-api-client": "0.0.0",
-    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
-    "@ainyc/canonry-contracts": "0.0.0",
+    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-db": "0.0.0",
+    "@ainyc/canonry-contracts": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
     "@ainyc/canonry-integration-openai-ads": "0.0.0",
     "@ainyc/canonry-integration-cloud-run": "0.0.0",
     "@ainyc/canonry-integration-commoncrawl": "0.0.0",
     "@ainyc/canonry-integration-google": "0.0.0",
     "@ainyc/canonry-integration-google-places": "0.0.0",
-    "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-integration-traffic": "0.0.0",
+    "@ainyc/canonry-integration-google-business-profile": "0.0.0",
     "@ainyc/canonry-integration-wordpress": "0.0.0",
+    "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-provider-cdp": "0.0.0",
     "@ainyc/canonry-provider-claude": "0.0.0",
-    "@ainyc/canonry-integration-google-business-profile": "0.0.0",
+    "@ainyc/canonry-provider-gemini": "0.0.0",
     "@ainyc/canonry-provider-local": "0.0.0",
     "@ainyc/canonry-provider-openai": "0.0.0",
-    "@ainyc/canonry-provider-perplexity": "0.0.0",
-    "@ainyc/canonry-provider-gemini": "0.0.0"
+    "@ainyc/canonry-provider-perplexity": "0.0.0"
   },
   "scripts": {
     "build": "tsx scripts/copy-agent-assets.ts && tsup && tsx build-web.ts",