@canonry/canonry 7.98.0 → 7.100.0

package/assets/agent-workspace/skills/aero/references/site-health.md

@@ -1,27 +1,28 @@
 ---
 name: site-health
-description: Diagnose Site Health scores, page findings, crawl coverage, internal links, and scan changes while preserving run provenance and incomplete-data limits.
+description: Diagnose Agent Readiness scores, page findings, crawl coverage, internal links, and scan changes while preserving run provenance and incomplete-data limits.
 ---
 
-# Site Health diagnosis
+# Agent Readiness diagnosis
 
-Site Health is the product label for the `technical-aeo` audit and crawl
-surface. It measures technical readiness. Mention coverage and citation
-coverage come from answer-engine measurements; neither is derived from an
-audit score, link score, or graph position.
+Agent Readiness is the product name for the site scan, page scores, and link
+map (CLI `agent-readiness`, MCP `canonry_agent_readiness_*`). It measures how
+ready a site's pages are for AI agents and answer engines. Mention coverage and
+citation coverage come from answer-engine measurements; neither is derived from
+an audit score, link score, or graph position.
 
 ## Start with stored evidence
 
-Read `canonry_site_health_overview` for the selected or latest crawl's root,
+Read `canonry_agent_readiness_overview` for the selected or latest crawl's root,
 run identity, completeness, counts, budgets, versions, termination, and
-dead-link check state. Pair it with `canonry_technical_aeo_score` for the
+dead-link check state. Pair it with `canonry_agent_readiness_score` for the
 aggregate score, factor distributions, issues, and prioritized fixes. Pin
 the score and subsequent reads to the returned run when available. Overview
 is crawl metadata, not the scorecard. Older scorecard-only audits can lack
 a graph; report the available scores and missing crawl evidence separately.
 
-Use `canonry_technical_aeo_pages` for low-scoring or failed pages and
-`canonry_site_health_page_audit` for one page's exact factor scores, finding
+Use `canonry_agent_readiness_page_scores` for low-scoring or failed pages and
+`canonry_agent_readiness_page_audit` for one page's exact factor scores, finding
 codes/messages, recommendations, and critical defects. Prefer a returned
 `nodeKey`; use the exact URL when no node key is available. The chat does not
 receive the selected graph node, so resolve the requested page or ask for it.
@@ -30,17 +31,17 @@ receive the selected graph node, so resolve the requested page or ask for it.
 
 | Question | Read |
 |---|---|
-| Which technical issues need investigation, including on passing pages? | `canonry_site_health_issues` for grouped findings, counts, example URLs and coverage |
-| Which pages have a selected issue? | `canonry_site_health_issue_pages`; pin the list's run and follow the affected-page cursor |
-| Which URLs were discovered and audited? | `canonry_technical_aeo_crawl_pages`; filter audit/fetch/indexability state and follow its cursor |
-| How is the site organized? | `canonry_technical_aeo_structure` for one path level |
-| What links to/from this page? | `canonry_technical_aeo_link_neighbors`; inbound and outbound truncation are independent |
-| What is around this page? | `canonry_site_health_subgraph`; refocus or expand only as needed |
-| Can the root reach this page? | `canonry_site_health_path` for a directed followable path |
-| Which editorial or template links exist? | `canonry_technical_aeo_internal_links` with supported filters |
-| What changed between scans? | `canonry_site_health_changes` for compatible complete snapshots |
-| Were broken links checked? | `canonry_technical_aeo_dead_links` |
-| How have scores moved? | `canonry_technical_aeo_trend`, then inspect the relevant runs and coverage |
+| Which issues need investigation, including on passing pages? | `canonry_agent_readiness_issues` for grouped findings, counts, example URLs and coverage |
+| Which pages have a selected issue? | `canonry_agent_readiness_issue_pages`; pin the list's run and follow the affected-page cursor |
+| Which URLs were discovered and audited? | `canonry_agent_readiness_pages`; filter audit/fetch/indexability state and follow its cursor |
+| How is the site organized? | `canonry_agent_readiness_structure` for one path level |
+| What links to/from this page? | `canonry_agent_readiness_link_neighbors`; inbound and outbound truncation are independent |
+| What is around this page? | `canonry_agent_readiness_subgraph`; refocus or expand only as needed |
+| Can the root reach this page? | `canonry_agent_readiness_path` for a directed followable path |
+| Which editorial or template links exist? | `canonry_agent_readiness_links` with supported filters |
+| What changed between scans? | `canonry_agent_readiness_changes` for compatible complete snapshots |
+| Were broken links checked? | `canonry_agent_readiness_dead_links` |
+| How have scores moved? | `canonry_agent_readiness_trend`, then inspect the relevant runs and coverage |
 
 Use semantic reads rather than requesting the full interactive graph or
 inferring importance from visualization coordinates. Defaults for subgraphs
@@ -102,14 +103,24 @@ multiple Properties; avoid counting the same finding as independent proof
 for each one.
 
 Rank persisted critical defects and fixes using severity and affected-page
-evidence, with business or link importance where available. State the run,
+evidence, with business or link importance where available.
+
+On an Advanced project, the critical defect `names-another-entity` marks a
+page that belongs to one Property whose FAQ, title or H1 names another of the
+plan's Properties, usually text copied between Property pages. The page audit
+read carries up to 25 `evidence` entries: the place (`faq-question`,
+`faq-answer`, `title`, `h1`), the FAQ question, the named Property's key and
+name, and a short snippet. Quote those rather than the issue title, and name
+the Property the page belongs to. The check uses the plan revision in the
+scan's `effectiveOptions.entityPlanRevision`; a null revision means the scan
+did not check names, not that no page names another Property. State the run,
 scope, finding, affected page(s), and supported next step. A technical issue
 can be a hypothesis for an AI-visibility gap, but the crawl alone cannot prove
 why an answer engine omitted a Property. Join the corresponding answer
 evidence before making that connection.
 
 Read existing data first. If absent or stale, propose an explicitly bounded
-`canonry_technical_aeo_run` when a new audit is needed. Existing authorization
+`canonry_agent_readiness_run` when a new scan is needed. Existing authorization
 for that run remains valid; a diagnostic question alone does not authorize
 a crawl. Dead-link checks remain off unless requested. After an approved
 run, follow its returned ID with `canonry_run_get`, then inspect that run's

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

@@ -8,8 +8,8 @@ description: Aero's persona, values, and voice — context-agnostic identity tha
 You are **Aero** — an AEO analyst. You help operators understand whether AI answer engines NAME their brand (mention) and, secondarily, whether they CITE their domain, and you act decisively on what the data shows. Mention is the primary gauge; citation is the secondary signal. The two are independent — never compute one from the other.
 
 For multi-property portfolios, keep each Property's identity and measurement
-scope intact. For Site Health, explain the stored audit findings and crawl
-limits first. A technical score does not measure AI visibility, and a crawl
+scope intact. For Agent Readiness, explain the stored audit findings and crawl
+limits first. An Agent Readiness score does not measure AI visibility, and a crawl
 finding alone does not prove why an answer engine omitted a brand.
 
 ## Values

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

@@ -52,6 +52,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.
@@ -66,11 +82,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
@@ -84,8 +110,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
@@ -145,8 +171,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/canonry/references/aeo-analysis.md

@@ -37,21 +37,24 @@ A "cited" query means the client's domain appeared in an AI provider's grounding
 
 A "not-cited" query means the AI answered without grounding on the client's domain.
 
+A "not-measured" citation means the engine returns no sources at all (a local model with no web access), so whether it would cite the client was never observed. It is never a miss and is left out of every cited rate; report it as not measured, and read that answer's mention as usual.
+
 ## Reading Evidence Output
 
-`cnry evidence` renders a two-glyph cell per (query × provider): `[C/c][M/m]` — uppercase = present, lowercase = absent, `–` = no snapshot. **C/c = cited** (secondary), **M/m = mentioned** (primary). Always print the legend before the table; never collapse the two signals into one cell. Lead your interpretation with the mention glyph.
+`cnry citations visibility <project>` renders a two-glyph cell per (query × engine): citation first, mention second. Uppercase = present, lowercase = absent, `·` = citation not measured (the engine returns no sources), `–` = no snapshot. **C/c = cited** (secondary), **M/m = mentioned** (primary). The legend prints above the table; keep it when you quote the table, and never collapse the two signals into one cell. Lead your interpretation with the mention glyph.
 
 ```
-Legend: [C/c][M/m]  C=cited c=not-cited  M=mentioned m=not-mentioned  –=no snapshot
-
-[C][M]  AEO Agency NYC             ← mentioned AND cited: branded/direct match, fully visible
-[c][M]  best plumber brooklyn      ← mentioned but NOT cited: named in the answer, domain not in sources (mention win, citation gap)
-[C][m]  ai seo tools               ← cited but NOT mentioned: domain grounded, brand never named (citation without share of voice)
-[c][m]  how to fix a leaky faucet  ← neither: informational gap, no page for this topic
-[c][m]  emergency plumber near me  ← neither: competitive gap, others mentioned/cited instead
+(cell = [citation][mention];  C=cited c=not ·=not measured, M=mentioned m=not, –=no data)
+Query                      gemini  local  openai  Cite  Ment
+AEO Agency NYC             CM      ·M     CM      2/2   3/3   ← mentioned AND cited: branded/direct match, fully visible
+best plumber brooklyn      cM      ·M     cM      0/2   3/3   ← mentioned but NOT cited: named in the answer, domain not in sources (mention win, citation gap)
+ai seo tools               Cm      ·m     cm      1/2   0/3   ← cited but NOT mentioned: domain grounded, brand never named (citation without share of voice)
+how to fix a leaky faucet  cm      ·m     cm      0/2   0/3   ← neither: informational gap, no page for this topic
 ```
 
-The summary line reports each signal independently: `Mentioned: X / Y` (primary) and `Cited: X / Y` (secondary) — a query can be one, both, or neither.
+`Cite` counts the engines that cited the query out of those whose sources were checked (`·` when none were); `Ment` counts the engines that mentioned it. Above the table, `Cited in sources: X/Y engines` and `Mentioned in answers: X/Y engines` report each signal independently — a query can be one, both, or neither.
+
+`cnry evidence <project>` is the per-query citation history instead: one line per query with its latest citation (`✓ cited`, `✗ not-cited` or `· not measured (no sources)`, plus a transition such as `(lost)`), then `Cited: X / Y` over the queries whose latest answers carried sources and `Not measured: N`. It prints no mention line; read mention from its `--format json` (each run's `mentionState` and `mentionTransition`) or from `cnry citations visibility`.
 
 ### Query Categories
 
@@ -78,7 +81,7 @@ The summary line reports each signal independently: `Mentioned: X / Y` (primary)
 **Query normalization:** When new queries are added to a project mid-history, canonry automatically normalizes each time bucket to only include queries that existed before that bucket started. This prevents newly-added (typically not-yet-mentioned/uncited) queries from creating a false drop in the rate trend. The chart displays dashed vertical annotation lines at points where queries were added (e.g. "+3 q"), and each bucket's tooltip shows the query count ("q") used for that bucket's calculation.
 
 ### Gap Analysis (`--feature gaps`)
-`GapAnalysisDto` returns mention buckets — `mentionedQueries[]`, `mentionGap[]` (a competitor is mentioned but you're not), `notMentioned[]` (nobody named) — alongside the cited buckets (`cited[]`, `gap[]`, `uncited[]`). Read the mention buckets first. Priorities:
+`GapAnalysisDto` returns mention buckets — `mentionedQueries[]`, `mentionGap[]` (a competitor is mentioned but you're not), `notMentioned[]` (nobody named) — alongside the cited buckets (`cited[]`, `gap[]`, `uncited[]`, and `citationNotMeasured[]` for queries whose engines return no sources, which are in none of the other three). Read the mention buckets first. Priorities:
 - **`mentionGap[]` queries** are highest priority — competitors are taking mention share (AI share-of-voice) you're not winning
 - **`notMentioned[]` queries** may need content or may be too broad
 - The cited `gap[]` / `uncited[]` buckets are the secondary lens on the same queries
@@ -135,7 +138,7 @@ For competitive queries, if others are mentioned/cited and the client isn't (che
 - Do they have stronger schema/structured data?
 - Are they more established in the index?
 
-Run `cnry evidence <project> --format json`. Use `citedDomains` and grounding-source hosts for citation evidence; use answer text with Canonry's shared matcher for mention evidence. `competitorOverlap` is a legacy mixed field and must not be treated as either metric by itself.
+Take a `runId` from `cnry evidence <project> --format json` (it lists each query's runs and their citation states) and run `cnry run show <run-id> --format json`. Its snapshots carry the evidence: use `citedDomains` and `citedUrls` for citation evidence, and the answer text with Canonry's shared matcher for mention evidence. `competitorOverlap` is a legacy mixed field and must not be treated as either metric by itself.
 
 ### Step 4: Check across providers
 Gemini, OpenAI, Claude, and Perplexity may behave differently. One citing a domain while another doesn't is normal — each has its own knowledge base and update schedule.