@canonry/canonry 7.98.0 → 7.100.0

package/README.md

@@ -13,7 +13,7 @@
 
 <p align="center">
   <strong>The agent-first AEO operating platform.</strong><br/>
-  Track mentions and citations across ChatGPT, Claude, Gemini, Meta Muse, and more. Join them with Search Console, GA4, ads, AI crawler traffic, site audits, and SEO data. Then let your agent create content, publish fixes, manage ChatGPT ads, get pages indexed, and measure what changed.<br/>
+  Track mentions and citations across ChatGPT, Claude, Gemini, Meta Muse, and more. Join them with Search Console, GA4, ads, AI crawler traffic, Agent Readiness site audits, and SEO data. Then let your agent create content, publish fixes, manage ChatGPT ads, get pages indexed, and measure what changed.<br/>
   <sub>Open source · Self-hosted · Bring your own keys</sub>
 </p>
 
@@ -48,11 +48,13 @@ See what AI agents actually do on your site, from your server logs: which pages
 
 <a href="skills/canonry/references/server-side-traffic.md"><picture><source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/traffic-mobile.png" /><img src="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/traffic.png" alt="Server traffic for the last 24 hours: 105 AI crawler visits, 35 AI user fetches, and 46 AI referral sessions, with an hourly chart, with sample data" width="100%" /></picture></a>
 
-### Site Health
+<a id="site-health"></a>
 
-Crawl your site, score each page for AI readiness, and map the internal links between pages. Each finding lists the pages it affects. [Docs →](skills/canonry/references/canonry-cli.md#site-health-technical-aeo-compatibility)
+### Agent Readiness
 
-<a href="skills/canonry/references/canonry-cli.md#site-health-technical-aeo-compatibility"><picture><source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/site-health-mobile.png" /><img src="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/site-health.png" alt="Site map of 205 crawled pages and the links between them, beside a list of site sections, with sample data" width="100%" /></picture></a>
+A site audit for AI agents. Crawl your site and score how well agents and answer engines can reach, read, and cite each page: AI crawler access, `llms.txt`, structured data, extractable content, and more. Each finding lists the pages it affects, and a map shows the internal links between pages. [Docs →](skills/canonry/references/canonry-cli.md#agent-readiness) · [Audit engine →](https://github.com/Canonry/agent-readiness)
+
+<a href="skills/canonry/references/canonry-cli.md#agent-readiness"><picture><source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/site-health-mobile.png" /><img src="https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/readme/site-health.png" alt="Site map of 205 crawled pages and the links between them, beside a list of site sections, with sample data" width="100%" /></picture></a>
 
 <a id="seo-data"></a>
 
@@ -86,7 +88,7 @@ Let your agent run ChatGPT Ads: sync campaigns and daily results, create and edi
 
 **An example job for your connected agent:**
 
-> Find where competitors get cited and we don't. Use search data and the site audit to prepare a pull request or WordPress draft for review. After it ships, rerun checks and report what changed.
+> Find where competitors get cited and we don't. Use search data and the Agent Readiness audit scan to prepare a pull request or WordPress draft for review. After it ships, rerun checks and report what changed.
 
 ## How it works
 
@@ -171,11 +173,11 @@ Use the official Canonry docs:
 Pick one path and stay on it. Use connected Canonry tools (plugin or MCP) only if you have them and I have not pointed you at a specific install. A connected tool runs in its own process and never sees `CANONRY_CONFIG_DIR`, `CANONRY_PORT`, or anything else you export in a shell, so it always acts on my default install. If I named a config directory, a port, or a sandbox, that is the shell path: use `cnry` and tell me which path you chose. Never mix the two in one run, and never create a duplicate project. The `cnry` and `canonry` commands are interchangeable.
 
 1. Ask for my public domain, country, and language. Do not create or scan anything yet. Country and language are only applied when a project is created, so if you reuse an existing project, report its country and language instead of changing them.
-2. Shell path only: confirm `cnry` is on PATH, then run `cnry --version`. If Canonry is missing, propose `npm install -g @canonry/canonry` and wait for approval. Then run `cnry doctor --format json`, which is the command that says whether config, database, and server are in place. `cnry --version` does not read config and succeeds on a completely unconfigured install, so it cannot answer this. If config is missing, run `cnry bootstrap` yourself: it is not interactive, takes about a second, and is safe to rerun. Do not hand it to me and wait. The interactive command is `cnry init`, which is optional provider and OAuth setup that Page Health does not need. Bootstrap prints an API key, so do not repeat its output back to me, and never ask me to paste passwords, API keys, OAuth credentials, or command output.
+2. Shell path only: confirm `cnry` is on PATH, then run `cnry --version`. If Canonry is missing, propose `npm install -g @canonry/canonry` and wait for approval. Then run `cnry doctor --format json`, which is the command that says whether config, database, and server are in place. `cnry --version` does not read config and succeeds on a completely unconfigured install, so it cannot answer this. If config is missing, run `cnry bootstrap` yourself: it is not interactive, takes about a second, and is safe to rerun. Do not hand it to me and wait. The interactive command is `cnry init`, which is optional provider and OAuth setup that Agent Readiness does not need. Bootstrap prints an API key, so do not repeat its output back to me, and never ask me to paste passwords, API keys, OAuth credentials, or command output.
 3. Confirm the API is reachable. `cnry doctor --format json` reports it, and any project read exits non-zero with `CONNECTION_ERROR` when it is not. If it is unreachable, propose `cnry start` and wait for approval. Use `cnry start`, which is the background daemon, and not `cnry serve`, which runs in the foreground and will block you until I stop it, even though some error messages suggest it. Stop anything you started with `cnry stop`.
-4. List projects with the connected project tool or `cnry project list --format json`, and reuse one whose domain matches. Confirm the proposed name is not already assigned to a different domain. To find out whether a project has already been scanned, run `cnry technical-aeo score <project> --format json` with no `--run-id`, which reports the latest run. Read the `hasData` field, not the score: this command exits 0 and reports `aggregateScore: 0` for a project that has never been scanned, so reading the score alone would have you tell me my site scored zero. If `hasData` is true and `runStatus` is `completed` or `partial`, read that scan instead of starting a new one. If no project matches, show the exact create operation and wait for approval.
-5. Propose a bounded Site Health scan: `--max-pages 100` for a first look, plus whether dead-link checking is on (it is off unless you pass `--check-dead-links`). Show the connected operation or the exact `cnry technical-aeo run <project> --max-pages 100 --wait --format json` command with the project name filled in, and wait for separate approval before scanning. `--wait` polls for up to 15 minutes and returns only the run id and status. If the status it returns is still `queued` or `running`, the scan has not finished: do not rerun it or report results, poll `cnry technical-aeo progress <project> --run-id <run-id> --format json` until it is terminal. If `--wait` outruns your own tool timeout first, recover the run id with `cnry technical-aeo score <project> --format json` and poll the same way.
-6. When the run is `completed` or `partial`, read `cnry technical-aeo crawl <project> --run-id <run-id> --format json` first. It is the only one of these commands that carries `termination` and `complete`; the score and pages commands do not. Then read `cnry technical-aeo score <project> --run-id <run-id> --format json` and `cnry technical-aeo pages <project> --run-id <run-id> --sort score-asc --limit 10 --format jsonl`. Tell me the termination reason in plain words and whether the scan covered the whole site or stopped at a page, link, depth, or time limit. A `partial` run scored the pages it reached and not my site, so never present it as a full-site result. If it stopped early, the fix depends on the reason, so say which: a page or depth limit needs a larger budget, a time limit needs a smaller scan (a lower `--max-pages` or `--max-depth`). If the run failed or was cancelled, inspect the run error and stop.
+4. List projects with the connected project tool or `cnry project list --format json`, and reuse one whose domain matches. Confirm the proposed name is not already assigned to a different domain. To find out whether a project has already been scanned, run `cnry agent-readiness score <project> --format json` with no `--run-id`, which reports the latest run. Read the `hasData` field, not the score: this command exits 0 and reports `aggregateScore: 0` for a project that has never been scanned, so reading the score alone would have you tell me my site scored zero. If `hasData` is true and `runStatus` is `completed` or `partial`, read that scan instead of starting a new one. If no project matches, show the exact create operation and wait for approval.
+5. Propose a bounded Agent Readiness audit scan: `--max-pages 100` for a first look, plus whether dead-link checking is on (it is off unless you pass `--check-dead-links`). Show the connected operation or the exact `cnry agent-readiness run <project> --max-pages 100 --wait --format json` command with the project name filled in, and wait for separate approval before scanning. `--wait` polls for up to 15 minutes and returns only the run id and status. If the status it returns is still `queued` or `running`, the scan has not finished: do not rerun it or report results, poll `cnry agent-readiness progress <project> --run-id <run-id> --format json` until it is terminal. If `--wait` outruns your own tool timeout first, recover the run id with `cnry runs <project> --kind site-audit --limit 1 --format json`, which returns the newest scan whatever its status, and poll the same way.
+6. When the run is `completed` or `partial`, read `cnry agent-readiness overview <project> --run-id <run-id> --format json` first. It is the only one of these commands that carries `termination` and `complete`; the score and page-scores commands do not. Then read `cnry agent-readiness score <project> --run-id <run-id> --format json` and `cnry agent-readiness page-scores <project> --run-id <run-id> --sort score-asc --limit 10 --format jsonl`. Tell me the termination reason in plain words and whether the scan covered the whole site or stopped at a page, link, depth, or time limit. A `partial` run scored the pages it reached and not my site, so never present it as a full-site result. If it stopped early, the fix depends on the reason, so say which: a page or depth limit needs a larger budget, a time limit needs a smaller scan (a lower `--max-pages` or `--max-depth`). If the run failed or was cancelled, inspect the run error and stop.
 7. Summarize only completed evidence, then propose AI Visibility setup. Ask before you add queries, connect providers, start a provider-backed or quota-consuming run, edit files, or publish.
 ```
 
@@ -205,7 +207,7 @@ cnry bootstrap
 cnry serve
 ```
 
-Then open [http://127.0.0.1:4100/setup](http://127.0.0.1:4100/setup) and follow the setup to scan your site. The crawl saves a Page Health baseline. AI Visibility is optional and has a separate setup.
+Then open [http://127.0.0.1:4100/setup](http://127.0.0.1:4100/setup) and follow the setup to scan your site. The crawl saves an Agent Readiness baseline. AI Visibility is optional and has a separate setup.
 
 <details>
 <summary>Scan and read results from the terminal</summary>
@@ -214,17 +216,17 @@ Keep `cnry serve` active. In a second terminal, create a project and start a bou
 
 ```bash
 cnry project create my-site --domain example.com --country US --language en
-cnry technical-aeo run my-site --max-pages 100 --wait --format json
+cnry agent-readiness run my-site --max-pages 100 --wait --format json
 ```
 
 Read the run ID and status from the output. If the status is `completed` or `partial`, read evidence from that run:
 
 ```bash
-cnry technical-aeo score my-site --run-id <run-id> --format json
-cnry technical-aeo pages my-site --run-id <run-id> --sort score-asc --limit 10 --format jsonl
+cnry agent-readiness score my-site --run-id <run-id> --format json
+cnry agent-readiness page-scores my-site --run-id <run-id> --sort score-asc --limit 10 --format jsonl
 ```
 
-`--wait` polls for up to 15 minutes. If the scan remains active, use `cnry technical-aeo progress <project> --run-id <id> --format json`.
+`--wait` polls for up to 15 minutes. If the scan remains active, use `cnry agent-readiness progress <project> --run-id <id> --format json`.
 If the scan fails or is cancelled, read the error with `cnry run show <run-id> --format json`.
 
 </details>
@@ -294,8 +296,8 @@ For a configured portfolio destination, select one `--market <key>` or `--proper
 
 | Problem | Next step |
 |---|---|
-| Site scan is still active | Read exact counters with `cnry technical-aeo progress <project> --run-id <id> --format json`. |
-| Site scan failed | Read the error with `cnry run show <run-id> --format json`. Read the last phase and counters with the progress command. |
+| Agent Readiness audit scan is still active | Read exact counters with `cnry agent-readiness progress <project> --run-id <id> --format json`. |
+| Agent Readiness audit scan failed | Read the error with `cnry run show <run-id> --format json`. Read the last phase and counters with the progress command. |
 | No visibility results | Inspect existing work with `cnry runs <project> --format json`, then `cnry run show <run-id> --format json`. This does not start another paid run. |
 | `npm install` fails on `node-gyp` | Install build tools for `better-sqlite3` ([guide](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md)). |
 

package/assets/agent-workspace/AGENTS.md

@@ -26,16 +26,22 @@ If the server isn't running, start it with `canonry serve`.
 | `canonry run <project>` | Trigger a visibility sweep across all configured providers |
 | `canonry run <project> --provider gemini` | Single-provider sweep |
 | `canonry status <project>` | Current project status and latest run summary |
-| `canonry evidence <project>` | Raw citation evidence from sweeps |
+| `canonry evidence <project>` | Per-query citation evidence; its JSON carries each query's history across sweeps |
 | `canonry insights <project>` | AI-generated insights and findings |
 | `canonry health <project>` | Health snapshot with visibility scores |
-| `canonry timeline <project>` | Per-query citation history over time |
 | `canonry export <project>` | Full project data export |
 
-### Auditing
+### Agent Readiness
 
 ```bash
-# Run an agent readiness audit on a URL
+# Scan the project's site: a bounded first look, waiting for the result
+canonry agent-readiness run <project> --max-pages 100 --wait --format json
+# Read the latest scan: the summary first, then the score, issues and one page's evidence
+canonry agent-readiness overview <project> --format json
+canonry agent-readiness score <project> --format json
+canonry agent-readiness issues <project> --format json
+canonry agent-readiness page-audit <project> --url <url> --format json
+# Check one page without a project, with the standalone audit
 npx @canonry/agent-readiness@8 <url> --format json
 ```
 
@@ -61,8 +67,8 @@ npx @canonry/agent-readiness@8 <url> --format json
 
 1. Identify affected queries from insights
 2. Pull evidence: `canonry evidence <project> --format json`
-3. Check timeline for trends: `canonry timeline <project> --format json`
-4. If structural issues suspected, run audit: `npx @canonry/agent-readiness@8 <url> --format json`
+3. Check each query's history across sweeps: the `runs` in that evidence
+4. If structural issues are suspected, read the latest Agent Readiness audit scan: `canonry agent-readiness overview <project> --format json`
 5. Compile findings with evidence and recommended actions
 
 ## Quota Awareness
@@ -79,6 +85,7 @@ Provider APIs have rate limits. Follow these guidelines:
 Reference skills are available in `skills/` for domain-specific guidance:
 
 - `skills/canonry/` -- Canonry operator playbook
+- `skills/aero/` -- Aero analyst playbook
 
 ## Error Handling
 

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

@@ -1,6 +1,6 @@
 ---
 name: aero
-description: "Diagnose AEO regressions and interpret Canonry AI visibility, SEO data, Advanced multi-property portfolios, and Site Health evidence. Use when prioritizing keyword or organic ranking opportunities, explaining mention or citation changes, comparing Properties or markets, diagnosing page findings, preparing reports, or analyzing a completed `cnry` sweep or site audit. Preserves measurement scope, missing-data states, and comparison limits. Use the canonry skill for setup and operations."
+description: "Diagnose AEO regressions and interpret Canonry AI visibility, SEO data, Advanced multi-property portfolios, and Agent Readiness evidence. Use when prioritizing keyword or organic ranking opportunities, explaining mention or citation changes, comparing Properties or markets, diagnosing page findings, preparing reports, or analyzing a completed `cnry` sweep or Agent Readiness audit scan. Preserves measurement scope, missing-data states, and comparison limits. Use the canonry skill for setup and operations."
 metadata:
   homepage: https://canonry.ai
   repository: https://github.com/AINYC/aero
@@ -8,7 +8,7 @@ metadata:
 
 # Aero Orchestration Skill
 
-Use Canonry's stored evidence to explain AI visibility, SEO opportunities, and site readiness. In
+Use Canonry's stored evidence to explain AI visibility, SEO opportunities, and Agent Readiness. In
 built-in Aero, use `aero_list_toolkits` and `aero_load_toolkit` to load relevant
 tools, then call the available `canonry_*` tools directly. Project-scoped
 tools use the session's project; they do not accept a different project from
@@ -17,8 +17,8 @@ json`. CLI examples in the references are for hosts with a shell; built-in
 Aero should use the corresponding exposed tool, not invent shell access.
 
 Canonry is the source of truth for runs, measurement plans, Property evidence,
-Site Health audits, integrations, and history. Read stored page audits before
-proposing fresh `agent-readiness` work. New crawls and provider work require approval
+Agent Readiness audit scans, integrations, and history. Read stored page audits before
+proposing a new Agent Readiness audit scan. New crawls and provider work require approval
 covering that work; an existing explicit authorization remains valid.
 
 ## Choose the evidence scope
@@ -30,12 +30,27 @@ covering that work; an existing explicit authorization remains valid.
   Priorities are recommendations, not computed scores or traffic forecasts.
   Aero cannot edit SEO profiles or start paid SEO refreshes.
 - **Establish the portfolio type before answering; never infer it.**
-  `canonry_project_overview` returns no plan, Target, or Property data, so its
-  silence is not evidence of a Simple project. When the system prompt carries
-  a "Project shape:" line, it already states the type and plan revision; do
-  not call `canonry_measurement_plan_get` to confirm it. Without that line,
-  call `canonry_measurement_plan_get` before stating that a project has no
-  Properties, no Advanced plan, or cannot break out per-Property performance.
+  `canonry_project_overview` states it in `mentionCoverage.selection.mode`
+  and `whatChanged.mode`: `advanced` when the project has a published
+  Advanced plan, `simple` otherwise. It carries no plan revision, structure
+  or Target data; its only Property data is the Properties and markets behind
+  each lost query in `whatChanged`. An older server returns neither field,
+  and that silence is not evidence of a Simple project. When the system
+  prompt carries a "Project shape:" line, it already states the type and plan
+  revision; do not call `canonry_measurement_plan_get` to confirm it. Without
+  that line, call `canonry_measurement_plan_get` before stating that a
+  project has no Properties, no Advanced plan, or cannot break out
+  per-Property performance.
+- **What changed in the latest check (both types):** quote the overview's
+  `whatChanged`, the counts the dashboard's What changed card shows, rather
+  than recounting answers. `lostMentions` and `lostCitations` each count the
+  queries that lost that signal (`queryCount`; `queries` lists at most 25,
+  with `truncated: true` when there are more) and stay separate. Read
+  `comparison` first. When its `state` is `unavailable`, nothing was
+  compared, so a 0 is unknown, not stable: say why from its `reason`.
+  `not-measured` there means the project has no completed check yet; it says
+  nothing about any answer's citation. `no-previous-check` means the latest
+  check is the first.
   The plan is structure only, with no metrics, and can be very large: never
   analyze, list, or rank Properties from it. For "which Property is
   best/worst", use `canonry_measurement_portfolio_summary`, then
@@ -59,8 +74,11 @@ covering that work; an existing explicit authorization remains valid.
     `queryClass` and `runId: latest`. Report its selected answer count and
     population. These conditioned reads provide counts, not competitive share
     of voice. Per-Property named-instead lists sample weak Properties.
-  - What changed: `canonry_measurement_changes` once per class, with its
-    `distribution` and `withinNoise`.
+  - What changed: the overview's `whatChanged` for the latest check, as the
+    dashboard card shows it (each lost query with its Properties and
+    markets). For movement per Property, `canonry_measurement_changes` once
+    per class, with its `distribution` and `withinNoise`; the noise rule
+    below applies before calling a Property's movement a loss.
   - Which metros have the biggest gaps: the compact portfolio summary's
     `weakestMarkets`, ranked from actual full metro aggregates with its own
     `population` and `queryClass`. Quote each row's mention and citation rates
@@ -80,13 +98,13 @@ covering that work; an existing explicit authorization remains valid.
   Rows tied at the weakest rate are listed by name, not rank: give
   `tiedAtWeakest.count` and call the rows examples. Compact reads omit
   `.byMetro`; request raw detail only when those tie counts are needed.
-- **Site Health:** read `references/site-health.md` before diagnosing scores,
-  crawl coverage, internal links, or page findings. Technical readiness is a
-  separate signal from measured mentions and citations. Use the latest audit
-  run selected by the tool. `runSelection` explains same-date ambiguity and
+- **Agent Readiness:** read `references/site-health.md` before diagnosing scores,
+  crawl coverage, internal links, or page findings. Agent Readiness is a
+  separate signal from measured mentions and citations. Use the latest scan
+  selected by the tool. `runSelection` explains same-date ambiguity and
   prefers complete scans, then the largest page sample, on the latest date.
-  For a dated question, pass `date: YYYY-MM-DD` to the crawl or crawl-pages
-  read. An empty read for an assumed year does not prove a historical scan is
+  For a dated question, pass `date: YYYY-MM-DD` to
+  `canonry_agent_readiness_overview` or `canonry_agent_readiness_pages`. An empty read for an assumed year does not prove a historical scan is
   missing. When the user omitted the year, use
   `availableScanDates.matchingMonthDayDates` from the dated no-data result to
   resolve it, then request the exact returned `YYYY-MM-DD`. If several years
@@ -144,14 +162,14 @@ covering that work; an existing explicit authorization remains valid.
   reasons; do not average Property percentages or sum overlapping markets.
 - When a native turn supplies current-view context, use `aero_inspect_view`
   first for view-relative claims. It resolves the selected Property, market,
-  class, dates, run, or Site Health page against stored evidence. Context is
+  class, dates, run, or Agent Readiness page against stored evidence. Context is
   a selection, not permission. Explicit user scope takes precedence; without
   context, resolve names/URLs or ask which Property/page before scoped claims.
 - Link the returned evidence beside findings. State measurement time separately
   from retrieval time, each class's numerator/denominator, missing-data reasons,
   and comparison limits. Keep observations separate from hypotheses and propose
   a concrete check for each hypothesis. Never turn an unavailable comparison
-  into a trend or infer a cause from a technical score alone.
+  into a trend or infer a cause from an Agent Readiness score alone.
 - Read `references/agent-operations.md` for shared vocabulary, evidence,
   comparison, and authority rules. Its MCP onboarding instructions apply to
   external hosts; built-in Aero loads its authorized toolkits and has skill-doc
@@ -159,7 +177,7 @@ covering that work; an existing explicit authorization remains valid.
 
 Persist only *user-scoped* context (operator preferences, communication style) in your platform's native memory. Project-scoped facts live in canonry and must be read back, not remembered.
 
-**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 AI visibility and report **Citation Coverage** as the secondary signal. Never compute one from the other, and never collapse them into a single "visibility" headline. For Site Health questions, lead with the requested audit or crawl evidence.
+**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 AI visibility and report **Citation Coverage** as the secondary signal. Never compute one from the other, and never collapse them into a single "visibility" headline. For Agent Readiness questions, lead with the requested audit or crawl evidence.
 
 When a project has GA4 connected, traffic is a first-class signal alongside
 mentions and citations. Use `cnry ga traffic` and `cnry ga attribution --trend`
@@ -200,16 +218,17 @@ Mention is the primary gauge (see "Two signals, not one" above); citation is the
 1. **Branded-term mention loss** — the engine no longer MENTIONING your brand by name is the most urgent regression. Losing the citation for your own name is the secondary signal on the same query: report it, but the mention is what moved share.
 2. **Mention-share losses** — a competitor took mention share on a query where yours fell. Rank by share swing first, then by any lost citation on the same query.
 3. **Neither mentioned nor cited** — new queries where you are absent on both signals (not mentioned and not cited). Mention gap leads; the missing citation is the trailing clause.
-4. **Indexing issues**, only when indexing or Site Health evidence read in this turn shows them. Pages not indexed can't be cited, and a weak/unindexed page also starves the engine of reasons to mention you; it feeds both signals.
+4. **Indexing issues**, only when indexing or Agent Readiness evidence read in this turn shows them. Pages not indexed can't be cited, and a weak/unindexed page also starves the engine of reasons to mention you; it feeds both signals.
 5. **Content optimization**, only when page or answer evidence read in this turn points to it. Improve mention rate first (give the answer a reason to name you), then cited rate on partially-covered queries.
 
 ### What NOT to Do
 - Don't promise fixes will appear in the next sweep (AEO changes take weeks/months)
-- Ground AI visibility recommendations in mention and citation evidence. Ground Site Health recommendations in persisted audit and crawl findings.
-- Don't run sweeps, probes, syncs, audits, discovery sessions, or any other write or quota-consuming operation without explicit user approval
+- Ground AI visibility recommendations in mention and citation evidence. Ground Agent Readiness recommendations in persisted audit and crawl findings.
+- Don't run sweeps, probes, syncs, Agent Readiness audit scans, 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.
+- Don't read `citationState: not-measured` as not cited. The engine returns no sources (a local model), so its citations were never observed; cited rates already leave it out. Never call it a citation gap or a lost citation. Other reads carry the same state in their own shape: `citationUnavailableReason: citation-not-measured` (visibility report), `{state: unavailable, reason: citation_not_measured}` (Advanced metrics), `citationMeasured: false` (research, snapshot), the `citationNotMeasured*` counts (overview, analytics), the gaps bucket `citationNotMeasured[]`, and `excludedNotMeasured` (compare). `references/agent-operations.md` lists them.
 
 ### When to use `--probe` runs
 When a verification would help, propose the exact probe and get explicit
@@ -232,7 +251,7 @@ A real (non-probe) sweep is appropriate when the user explicitly asks to refresh
 
 ### How to Communicate
 - Data first: show the numbers before the interpretation
-- For AI visibility, lead with the mention transition, then the citation change. For Site Health, lead with the requested score or finding and its affected pages and crawl limits.
+- For AI visibility, lead with the mention transition, then the citation change. For Agent Readiness, lead with the requested score or finding and its affected pages and crawl limits.
 - Action-oriented: every observation ends with a recommended next step
 - Rest each recommended priority on a measured fact: the Property or metro
   and the answer counts behind it. A cause is a hypothesis: label it, and
@@ -259,7 +278,7 @@ Detailed playbooks live alongside this file. Read them on demand when the task m
 |---|---|
 | `references/seo-analysis.md` | Prioritizing keyword or organic ranking opportunities from saved SEO data |
 | `references/portfolio-analysis.md` | Interpreting Simple or Advanced portfolios, ranking Properties or markets, or comparing measurement runs |
-| `references/site-health.md` | Diagnosing site/page scores, crawl completeness, internal links, or changes between scans |
+| `references/site-health.md` | Diagnosing Agent Readiness site/page scores, crawl completeness, internal links, or changes between scans |
 | `references/agent-operations.md` | Checking shared scope, evidence, comparison, or permission rules; generated from the canonical operations guide |
 | `references/orchestration.md` | Planning a multi-step or recurring workflow (baseline, weekly review, content-gap analysis) |
 | `references/regression-playbook.md` | A query lost a mention (primary) or a citation (secondary) and you need to triage and respond |

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

@@ -8,11 +8,16 @@ description: Shared Canonry vocabulary, evidence scope, comparison rules, and au
 > **Built-in Aero:** your available `canonry_*` tools are already loaded, and
 > you read this guide through `read_skill_doc` (slug `agent-operations`). Your
 > catalog does not include `canonry_help` or `canonry_load_toolkit`; the
-> connection and navigation steps below are for external MCP hosts. Your
-> project-scoped tools use the current session's project. Dashboard selections
-> are not passed to chat: resolve the requested Property, market, filters, or
-> page before making a scoped claim. The `portfolio-analysis` and `site-health`
-> skill docs cover those investigations for Simple and Advanced portfolios.
+> connection and navigation steps below are for external MCP hosts. It also
+> leaves out the provider connection actions the guide names
+> (`canonry_provider_test`, `canonry_provider_settings_update` and
+> `canonry_providers_reload`): they spend on or change the operator's
+> install-wide provider accounts, so the operator runs them from the dashboard
+> or CLI. Your project-scoped tools use the current session's project.
+> Dashboard selections are not passed to chat: resolve the requested Property,
+> market, filters, or page before making a scoped claim. The
+> `portfolio-analysis` and `site-health` skill docs cover those investigations
+> for Simple and Advanced portfolios.
 
 # Canonry Operations Guide v1
 
@@ -61,6 +66,22 @@ guide plus links to host-native references. It does not replace runtime help.
   compute one signal from the other.
 - `answerMentioned: null` means not checked, not false. Missing runs and empty
   populations mean no measurement, not zero visibility.
+- `citationState: not-measured` (with `cited: null`) means the engine returns no
+  sources, such as a local model without web access, so whether it cites the
+  domain was never observed. It is never a miss: cited rates leave it out and
+  count it as `citationNotMeasured`, and a cited rate with nothing measured is
+  null, not 0. Mention is still measured on those answers. Other reads show the
+  same state in their own shape:
+  - visibility report: an answer's `citationUnavailableReason:
+    citation-not-measured`, or a rate's `reason: citation-not-measured`;
+  - Advanced metrics: `{state: unavailable, reason: citation_not_measured}`;
+  - research and snapshot answers: `citationMeasured: false` (research also
+    sends `citationState: null`);
+  - overview: `citationNotMeasuredQueries`, `citationNotMeasuredPairs` and
+    `citationNotMeasuredCount`;
+  - analytics: the gaps bucket `citationNotMeasured[]` and sources'
+    `citationNotMeasuredAnswers`;
+  - visibility compare: `excludedNotMeasured`.
 - Preserve project, time window, provider, requested/served model, location,
   sample size, and query class when comparing evidence. Use server-returned
   metrics; do not invent a score from incompatible populations.
@@ -75,11 +96,21 @@ guide plus links to host-native references. It does not replace runtime help.
 **Status:** read the stored overview and freshness first. Say when evidence is
 missing instead of silently creating it.
 
-**Setup:** Page Health needs no answer-engine provider; AI Visibility does.
-After a Page Health result on an install with no provider (a `NO_PROVIDER`
+**Setup:** Agent Readiness needs no answer-engine provider; AI Visibility does.
+After an Agent Readiness result on an install with no provider (a `NO_PROVIDER`
 notice, or doctor's `providers.none-configured`), propose AI Visibility setup
 as the next step. The operator adds the provider key in the dashboard or in
-their own terminal; never ask for it in chat.
+their own terminal; never ask for it in chat. A saved key is not a verified one:
+with approval, `canonry settings provider test <name>` or `canonry_provider_test`
+checks the saved connection with the provider now (usually one tiny prompt on
+the operator's account) and reports `connected`, `failed` with the provider's
+reason, or `not-verified`. It needs install administrator authority and
+`settings.write`; while a connection's test is still running, another test of it
+returns `OPERATION_IN_PROGRESS`, so wait for that result. The latest result is
+kept as the connection's `lastTest` (`canonry settings provider-info <name>` or
+`canonry_provider_settings_get`) until its key, endpoint, model, Vertex project,
+region or credentials, or CDP endpoint changes, or the connection is
+disconnected; read it before testing again.
 Rerunning `canonry bootstrap` after a provider change reloads saved provider
 settings on a matching running local server and reports whether they became
 active. If the server is offline, start it to apply the saved settings. For an
@@ -93,8 +124,8 @@ Ports and database settings still need a restart.
 changed separately from why it might have changed. A hypothesis is not a
 measured cause. Propose bounded verification if stored evidence is insufficient.
 
-**Site Health:** read `canonry_site_health_issues` for stored technical findings,
-affected-page counts and example URLs, then `canonry_site_health_issue_pages`
+**Agent Readiness:** read `canonry_agent_readiness_issues` for stored findings,
+affected-page counts and example URLs, then `canonry_agent_readiness_issue_pages`
 for a selected issue's remaining pages. Pin subsequent reads to the returned
 run. Inspect coverage and omissions: a passing score can still have findings,
 an older scan may lack cross-page evidence, and a partial scan cannot establish
@@ -154,8 +185,12 @@ authority without exposing its token. Missing `operator` means unapproved.
 machine. Telemetry reports configured preference, effective state, and any
 environment override; inspecting status never creates an anonymous identifier.
 After approval, `canonry_telemetry_update` changes that preference and
-`canonry_provider_settings_update` changes an already-configured provider's
-model/quota. Both require `settings.write`; neither accepts credentials.
+`canonry_provider_settings_update` changes or resets an already-configured
+provider's model and quota, restores its built-in endpoint, or removes an
+optional Local key. Both require `settings.write`; neither accepts credentials.
+A reset, restoring the endpoint and removing the Local key included, also
+requires install administrator authority. Pass the `revision` from
+`canonry_provider_settings_get` as `expectedRevision` to reject a stale edit.
 Server telemetry reads and updates additionally require operator authority.
 Ordinary audit-history reads omit internal telemetry events and their state.
 

package/assets/agent-workspace/skills/aero/references/memory-patterns.md

@@ -27,7 +27,7 @@ cnry health <project> --format json
 cnry timeline <project> --since <YYYY-MM-DD> --format json
 cnry insights <project> --format json
 cnry evidence <project> --format json
-cnry audit <project> --format json
+cnry agent-readiness score <project> --format json
 ```
 
 If the data you need isn't reachable with a single read tool or CLI call, that's a bug in canonry's API surface — file it rather than working around it in memory.

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

@@ -7,20 +7,20 @@ description: Workflow recipes — baseline, regression response, weekly review,
 
 Use these recipes with the current measurement scope. For Advanced
 portfolios, read `portfolio-analysis.md` and use the Property/market tools
-instead of substituting project-level metrics. For crawl or audit work, read
+instead of substituting project-level metrics. For Agent Readiness work, read
 `site-health.md`. Built-in Aero uses the corresponding exposed `canonry_*`
 tools; CLI examples below assume an external host with a shell.
 
-**Read the mention signal first in every workflow.** Compute and compare **mention rate + mention share** before cited rate. The fast mention read is `cnry overview <project> --format json` (returns `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`) plus `cnry analytics <project> --feature gaps --format json` (returns `mentionedQueries[]`, `mentionGap[]`, `notMentioned[]` alongside the cited buckets). Use `cnry evidence <project>` for the per-query drilldown — it prints the two-glyph `[C/c][M/m]` cell per (query × provider) and a `Mentioned: X / Y` line next to `Cited: X / Y`. Mention and citation are independent — never derive one from the other. Treat `answerMentioned = null` as "not checked," never as not-mentioned.
+**Read the mention signal first in every workflow.** Compute and compare **mention rate + mention share** before cited rate. The fast mention read is `cnry overview <project> --format json` (returns `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`) plus `cnry analytics <project> --feature gaps --format json` (returns `mentionedQueries[]`, `mentionGap[]`, `notMentioned[]` alongside the cited buckets, plus `citationNotMeasured[]` for queries whose engines return no sources). Use `cnry citations visibility <project>` for the per-query drilldown — it prints a two-glyph `[C/c/·][M/m]` cell per (query × engine), where `·` means the engine returns no sources, so the citation was not measured (never a miss). `cnry evidence <project>` lists each query's latest citation (`✓ cited`, `✗ not-cited`, `· not measured`) and `Cited: X / Y` over the queries whose answers carried sources. Mention and citation are independent — never derive one from the other. Treat `answerMentioned = null` as "not checked," never as not-mentioned.
 
 ## Workflow 1: New Client Baseline
 
 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.
+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 citations visibility <project> --format json` for the per-query × engine drilldown (each engine's `mentioned` and `citationState`, where `not-measured` is never a miss) 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. With explicit operator approval for the crawl and persisted run, `cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json` for site readiness. Use `cnry site-health overview <project> --format json` only to add crawl metadata (root, completeness, budgets, and termination); it never replaces the score. The crawl discovers the in-scope URL inventory from the root, sitemaps, and internal links. Without `--max-pages` the scan uses the project's saved page budget (`cnry project update <project> --site-audit-max-pages <n|full>`), else the full site (up to 50,000 pages); the edge budget is unset by default and the crawl engine derives it from the page count, so `--max-edges` sets a ceiling rather than lifting one. Use `--max-pages`, `--max-edges`, or `--max-depth` to tighten them. `--wait` stops polling after 15 minutes while a larger scan keeps running; follow it with `cnry technical-aeo progress <project> --run-id <id>`. Dead-link checks remain off unless `--check-dead-links` is explicit. For architecture investigation, use bounded Site Health subgraph/path/changes reads rather than attempting to load the visualization graph. Treat `countAccuracy: "lower-bound"` subgraph counts as minimums, and qualify an incomplete path's unreachable/truncated result with `complete: false` plus `termination`; neither is a site-wide conclusion. 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 agent-readiness run <project> --wait`, then `cnry agent-readiness score <project> --format json` for the Agent Readiness score. Use `cnry agent-readiness overview <project> --format json` only to add crawl metadata (root, completeness, budgets, and termination); it never replaces the score. The crawl discovers the in-scope URL inventory from the root, sitemaps, and internal links. Without `--max-pages` the scan uses the project's saved page budget (`cnry project update <project> --site-audit-max-pages <n|full>`), else the full site (up to 50,000 pages); the edge budget is unset by default and the crawl engine derives it from the page count, so `--max-edges` sets a ceiling rather than lifting one. Use `--max-pages`, `--max-edges`, or `--max-depth` to tighten them. `--wait` stops polling after 15 minutes while a larger scan keeps running; follow it with `cnry agent-readiness progress <project> --run-id <id>`. Dead-link checks remain off unless `--check-dead-links` is explicit. For architecture investigation, use bounded Agent Readiness subgraph/path/changes reads rather than attempting to load the visualization graph. Treat `countAccuracy: "lower-bound"` subgraph counts as minimums, and qualify an incomplete path's unreachable/truncated result with `complete: false` plus `termination`; neither is a site-wide conclusion. Persists to the dashboard and is trendable via `cnry agent-readiness 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. Read baselines back from stored runs; remember only operator-confirmed context that Canonry cannot observe.
@@ -30,11 +30,11 @@ Steps:
 Trigger: Comparison shows decline or webhook fires regression.detected
 
 Steps:
-1. `cnry overview <project> --format json` → current state, mention first: did `scores.mention` / `scores.mentionShare` move? Then `cnry analytics <project> --feature gaps --format json` (`mentionGap[]` / `notMentioned[]`) and `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown (which signal actually dropped on which provider).
+1. `cnry overview <project> --format json` → current state, mention first: did `scores.mention` / `scores.mentionShare` move? Its `whatChanged` already lists what the latest check lost: `lostMentions` first, then `lostCitations`, each query once with the engines and locations (and for Advanced the Properties and markets) that lost it. These are the dashboard's What changed counts, so start from them instead of recounting. Check `comparison` first: when it is `unavailable`, nothing was compared and a 0 is unknown. When `truncated` is true, `queries` lists only the first 25 of `queryCount`. Then `cnry analytics <project> --feature gaps --format json` (`mentionGap[]` / `notMentioned[]`) and `cnry citations visibility <project> --format json` for the per-query × engine drilldown (which signal actually dropped on which provider; a `not-measured` citation never dropped).
 2. `cnry history <project>` → trend for affected query
 3. Check competitor mention share BEFORE cited displacement: did a competitor take the **mention** share you lost (`mentionGap[]`)? Only then ask whether a competitor gained the **citation** you lost.
 4. Check indexing: `cnry google coverage <project>` → is the page still indexed? (a deindexed/thin page starves both signals)
-5. Read the page's persisted audit with `canonry_site_health_page_audit`. Propose a bounded new audit only if the stored evidence cannot answer the question.
+5. Read the page's persisted audit with `canonry_agent_readiness_page_audit`. Propose a bounded new audit only if the stored evidence cannot answer the question.
 6. Diagnose cause: indexing issue / content issue / competitive displacement (mention-share loss first, citation loss second)
 7. Recommend fix with evidence — lead with what restores the mention
 8. If content fix: generate diff (schema, llms.txt, or content changes)
@@ -55,9 +55,9 @@ Then `cnry runs get <id>` to inspect the snapshot. The probe's snapshot won't di
 Trigger: Scheduled (weekly, or on-demand)
 
 Steps:
-1. `cnry overview <project> --format json` → current metrics, mention first (`queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`); `cnry analytics <project> --feature gaps --format json` for the mention gaps; `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown
+1. `cnry overview <project> --format json` → current metrics, mention first (`queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`); `cnry analytics <project> --feature gaps --format json` for the mention gaps; `cnry citations visibility <project> --format json` for the per-query × engine drilldown (`not-measured` citations stay out of gained/lost)
 2. Compare compatible stored periods/runs using the reporting or portfolio playbook — mention rate + mention share first, cited rate second
-3. Compute deltas: mentions gained/lost/stable (primary), then citations gained/lost/stable (secondary)
+3. Compute deltas: mentions gained/lost/stable (primary), then citations gained/lost/stable (secondary). The latest check's losses are the overview's `whatChanged.lostMentions` and `lostCitations` (check `comparison` and `truncated`); compare stored runs only for gains and for sweeps before it.
 4. Flag any new regressions not yet addressed (lead with lost mentions)
 5. Check competitor movement — mention share swing first, then cited-domain displacement
 6. Generate summary with key changes + recommended next steps
@@ -67,7 +67,7 @@ Steps:
 Trigger: User asks "why aren't we mentioned/cited for X?" or multiple not-mentioned / uncited queries detected
 
 Steps:
-1. `cnry overview <project> --format json` + `cnry analytics <project> --feature gaps --format json` → confirm the gap, mention first: is the query in `notMentioned[]` (not named at all) or `mentionGap[]` (a competitor is named, you aren't)? Then `cnry evidence <project>` for the per-query `[C/c][M/m]` cell to see whether you also lack the citation. Mention gap leads the diagnosis; the missing citation is the secondary lens.
+1. `cnry overview <project> --format json` + `cnry analytics <project> --feature gaps --format json` → confirm the gap, mention first: is the query in `notMentioned[]` (not named at all) or `mentionGap[]` (a competitor is named, you aren't)? Then `cnry citations visibility <project>` for the per-query `[C/c/·][M/m]` cell to see whether you also lack the citation (`·` means the engine returns no sources: not measured, not a gap). Mention gap leads the diagnosis; the missing citation is the secondary lens.
 2. Check if a relevant page exists on the domain
 3. If no page: recommend content creation (topic, target queries) — give the engine a reason to name you
 4. If page exists, inspect its persisted page audit and answer evidence. Treat a technical finding as a possible contributor, not proof of why an answer engine omitted the brand.

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

@@ -13,7 +13,7 @@ For a calendar-month comparison of a Property, group or market, call
 use `canonry_measurement_changes` for compatible stored-run comparisons of
 changed Properties. Do not substitute a project-wide month comparison for
 Property-scoped data.
-For Site Health reports, read `site-health.md` and keep crawl and audit
+For Agent Readiness reports, read `site-health.md` and keep crawl and audit
 provenance separate from answer-visibility periods.
 
 For project-wide month-over-month AEO claims, use `canonry_visibility_compare`
@@ -56,6 +56,10 @@ Two consequences for any report:
 
 A sweep crippled by a provider outage captures fewer questions and looks identical to a collapse in visibility. Before narrating any drop, check whether the latest run is `partial` and what its capture count was against the project's basket size. Report a capture failure as a capture failure.
 
+## A cited rate can be not measured
+
+An engine that returns no sources (a local model) has no cited rate: the API sends `null`, and `visibility-compare` counts those answers as `excludedNotMeasured`. Where a template below asks for a cited rate as `<X>%`, write "not measured" for that engine, never `0%`, and leave it out of cited deltas. Its mention rate is still measured and reported.
+
 ## Build summaries from stored evidence
 
 For keyword and organic ranking recommendations, read `seo-analysis.md`.
@@ -94,8 +98,8 @@ and requires explicit approval; preparing a summary does not authorize it.
 ## Summary
 - Mention rate: <X>% (Δ<+/-Y>% from last week)        ← primary KPI
 - Mention share (non-brand): <X>% (Δ<+/-Y>% from last week)   ← share-of-voice vs competitors; NEVER pooled with branded
-- Cited rate: <X>% (Δ<+/-Y>% from last week)          ← secondary signal
-- Regressions: <N> new, <N> resolved (lead with lost mentions; note lost citations second)
+- Cited rate: <X>% (Δ<+/-Y>% from last week)          ← secondary signal; "not measured" when null, never 0%
+- Regressions: <N> new, <N> resolved (lead with lost mentions; note lost citations second)   ← latest check: the overview's whatChanged.lostMentions / lostCitations queryCount; comparison unavailable = not compared, never 0
 - Gains: <N> new mentions / <N> new citations
 - Providers monitored: <N>
 
@@ -143,7 +147,7 @@ and requires explicit approval; preparing a summary does not authorize it.
 ## Provider Breakdown
 | Provider | Mention Rate | Mention Trend | Cited Rate | Cited Trend |
 |----------|--------------|---------------|-----------|-------------|
-| <provider> | <X>% | ↑/↓/→ | <X>% | ↑/↓/→ |
+| <provider> | <X>% | ↑/↓/→ | <X>% or not measured | ↑/↓/→ |
 
 ## Fixes Deployed
 | Date | Fix | Status | Impact |

package/assets/agent-workspace/skills/aero/references/seo-analysis.md

@@ -121,8 +121,8 @@ Use this order of judgment:
 | Competitor with stronger domain estimates | Investigate the difference within comparable scope | Per-target evidence. Totals do not establish keyword gaps. |
 | Missing, stale, partial, or incompatible evidence | Validate the evidence first | The exact missing dataset, profile, or comparable refresh |
 
-Inspect stored page or Site Health evidence before prescribing title, content, indexability, or internal-link changes.
-Read `site-health` through `read_skill_doc` for its interpretation rules.
+Inspect stored page or Agent Readiness evidence before prescribing title, content, indexability, or internal-link changes.
+Read the Agent Readiness skill doc (slug `site-health`) through `read_skill_doc` for its interpretation rules.
 A rank alone cannot identify a technical or content cause.
 If supporting evidence is absent, recommend a specific inspection instead of asserting a defect.