@ainyc/canonry 4.82.0 → 4.84.0

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

@@ -16,25 +16,29 @@ 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 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, 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`.
 
 **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).
 
 ## Judgment Rules
 
 ### What to Prioritize
-1. Branded term regressions (losing citations for your own name = urgent)
-2. Competitive query losses (competitor gained where you lost)
-3. Informational gap expansion (new uncited queries appearing)
-4. Indexing issues (pages not indexed can't be cited)
-5. Content optimization (improve cited rate on partially-cited queries)
+
+Mention is the primary gauge (see "Two signals, not one" above); citation is the secondary signal on the same query. Rank work accordingly:
+
+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** — pages not indexed can't be cited, and a weak/unindexed page also starves the engine of reasons to mention you. Keep this on the list; it feeds both signals.
+5. **Content optimization** — 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)
-- Don't give generic SEO advice — always ground recommendations in citation data
+- 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 edit client's code without showing diffs and getting approval
-- Don't conflate "not cited" with "page doesn't exist" — check first
+- 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:
@@ -49,7 +53,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
-- Be specific: "You lost the ChatGPT citation for 'roof repair phoenix' between March 28-April 2" not "your visibility decreased"
+- Lead with the mention transition, keep citation as a trailing clause: "ChatGPT stopped mentioning you for 'roof repair phoenix' between Mar 28-Apr 2, and your mention share fell from 50% to 0% as a competitor took the slot" — then, second, note that you also lost the citation for that query. Not "your visibility decreased."
 - Action-oriented: every observation ends with a recommended next step
 
 ## References
@@ -59,7 +63,7 @@ Detailed playbooks live alongside this file. Read them on demand when the task m
 | File | Read when |
 |---|---|
 | `references/orchestration.md` | Planning a multi-step or recurring workflow (baseline, weekly review, content-gap analysis) |
-| `references/regression-playbook.md` | A query lost its citation and you need to triage and respond |
+| `references/regression-playbook.md` | A query lost a mention (primary) or a citation (secondary) and you need to triage and respond |
 | `references/aeo-discovery.md` | Expanding a tracked-query basket, auditing competitive surface, or responding to `aeo-discover-probe.completed` |
 | `references/memory-patterns.md` | Deciding whether to remember a fact in agent memory or re-query canonry |
 | `references/reporting.md` | Producing a client-facing weekly or monthly summary |

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

@@ -5,13 +5,15 @@ description: How to operate the tracked-basket discovery pipeline. Read when an
 
 # AEO Discovery (Tracked-Basket Expansion)
 
-Discovery turns a free-text ICP description into a deduped basket of representative queries, probes each against Gemini grounding, and classifies the results into three buckets:
+Discovery turns a free-text ICP description into a deduped basket of representative queries, probes each against Gemini grounding, and classifies the results into three buckets. Read each bucket as **mention-or-citation** presence — the brand named in the answer text (`answerMentioned`, the primary signal) OR the domain in the grounding sources (`cited`, the secondary signal) — not citation alone:
 
-- **cited** — the project's canonical (or owned) domain appears in the grounding sources
-- **wasted-surface** — a tracked competitor is cited but the project is not
-- **aspirational** — neither the project nor a tracked competitor is cited (greenfield)
+- **cited** — the project shows up for the query: its brand is mentioned in the answer text, or its canonical/owned domain appears in the grounding sources (mention-or-citation present)
+- **wasted-surface** — a tracked competitor shows up (mentioned or cited) but the project does not
+- **aspirational** — neither the project nor a tracked competitor shows up on either signal (greenfield)
 
-Plus a competitor map: every non-canonical domain that shows up in probe citations, ranked by hit count and classified by type, so the operator can spot recurring competitors that aren't yet on the watchlist.
+Plus a competitor map: every non-canonical domain (and named competitor brand) that shows up across probes, ranked by hit count and classified by type, so the operator can spot recurring competitors that aren't yet on the watchlist. Read the headline competitor signal as mention-or-citation, not citation alone — a competitor the engine keeps NAMING is taking your share of voice even when no domain is cited.
+
+> **Mention data on probes (engine PR #707, merged 2026-06-17).** Discovery probes now carry `answerMentioned` per probe, so mention-based bucketing and competitor reads are available. Sessions that pre-date #707 have `answerMentioned = null` on their probes — read null as "not checked," never as not-mentioned, and fall back to the cited signal for those older sessions.
 
 After probing, one Gemini call classifies every recurring cited domain into a `competitorType`:
 

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

@@ -13,7 +13,7 @@ Aero ships with a built-in durable notes store — the `canonry_memory_set`, `ca
 
 | Scope | Examples | Home |
 |---|---|---|
-| **Project state** | Baselines, historical regressions, citation rates per query/provider, recent insights, sweep history, audit trail | Canonry DB — query via CLI / API / read tools |
+| **Project state** | Baselines (**mention rate + mention share** as the primary KPI, then cited rate), historical regressions, mention + citation rates per query/provider, recent insights, sweep history, audit trail | Canonry DB — query via CLI / API / read tools |
 | **Operator facts** | Personal preferences, non-observable context ("content lead is Sarah", "migrating off Webflow next quarter"), tone/voice preferences the operator confirmed | Aero memory (`canonry_memory_set`) |
 | **Session scratch** | "I just tried X and it failed", intermediate reasoning, turn-local state | Nowhere — let it die with the session |
 

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

@@ -5,32 +5,34 @@ description: Workflow recipes — baseline, regression response, weekly review,
 
 # Orchestration Workflows
 
+**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.
+
 ## Workflow 1: New Client Baseline
 
 Trigger: First sweep completes for a new project
 
 Steps:
-1. `cnry evidence <project> --format json` → get initial citation data
-2. Compute baseline: cited rate, provider breakdown, top/bottom queries
+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>`.
-4. Identify top 3 gaps (uncited queries with fixable site issues)
+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
+6. Store baseline metrics in memory (include mention rate + mention share, not just cited rate)
 
 ## Workflow 2: Regression Response
 
 Trigger: Comparison shows decline or webhook fires regression.detected
 
 Steps:
-1. `cnry evidence <project> --format json` → current state
+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).
 2. `cnry history <project>` → trend for affected query
-3. Check indexing: `cnry google coverage <project>` → is the page still indexed?
-4. Check competitor: did a competitor gain the citation we lost?
+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. Audit the page: `npx @ainyc/aeo-audit "<page-url>" --format json`
-6. Diagnose cause: indexing issue / content issue / competitive displacement
-7. Recommend fix with evidence
+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)
-9. Update memory with regression event + diagnosis
+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:
 
@@ -45,21 +47,21 @@ 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 evidence <project> --format json` → current metrics
-2. Compare to baseline/prior week from memory
-3. Compute deltas: citations gained, lost, stable
-4. Flag any new regressions not yet addressed
-5. Check competitor movement
+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
+2. Compare to baseline/prior week from memory — mention rate + mention share first, cited rate second
+3. Compute deltas: mentions gained/lost/stable (primary), then citations gained/lost/stable (secondary)
+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
 
 ## Workflow 4: Content Gap Analysis
 
-Trigger: User asks "why aren't we cited for X?" or multiple uncited queries detected
+Trigger: User asks "why aren't we mentioned/cited for X?" or multiple not-mentioned / uncited queries detected
 
 Steps:
-1. `cnry evidence <project>` → confirm uncited
+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.
 2. Check if a relevant page exists on the domain
-3. If no page: recommend content creation (topic, target queries)
-4. If page exists: `npx @ainyc/aeo-audit "<page-url>"` → diagnose why uncited
+3. If no page: recommend content creation (topic, target queries) — give the engine a reason to name you
+4. If page exists: `npx @ainyc/aeo-audit "<page-url>"` → diagnose why neither mentioned nor cited
 5. Check schema completeness, llms.txt coverage, indexing status
-6. Generate prioritized fix list
+6. Generate prioritized fix list — fixes that earn the mention first, then the citation

package/assets/agent-workspace/skills/aero/references/regression-playbook.md

@@ -1,31 +1,31 @@
 ---
 name: regression-playbook
-description: Detection → triage → diagnosis → response for lost citations. Read when investigating why a query lost its citation.
+description: Detection → triage → diagnosis → response for lost mentions (primary) and lost citations (secondary). Read when investigating why a query lost a mention or a citation.
 ---
 
 # Regression Playbook
 
 ## Detection
 
-A regression is detected when a citation is lost between consecutive completed runs for the same project. Specifically: a query+provider pair that was cited in run N is no longer cited in run N+1.
+A regression is, primarily, a **lost mention**: a query+provider pair whose answer text named the brand (`answerMentioned = true`) in run N no longer does in run N+1. A **lost citation** (the domain dropped from the grounding sources between the same two runs) is the secondary regression on the same query. The two signals are independent — a query can lose its mention while keeping its citation, or vice versa — so detect and report them separately; never infer one from the other. Treat `answerMentioned = null` as "not checked," not as a lost mention.
 
 ## Triage
 
-Classify the regression by severity:
+Classify the regression by severity. Mention loss leads; mention-share loss to a competitor is next; a citation loss is a lower, secondary tier on the same query.
 
 | Severity | Criteria |
 |---|---|
-| **Critical** | Branded term lost on any provider |
-| **High** | Top-performing query lost on primary provider |
-| **Medium** | Non-branded query lost on one provider |
-| **Low** | Query lost that was only marginally cited |
+| **Critical** | Lost a branded-term MENTION on any provider (the engine stopped naming you for your own brand) |
+| **High** | Mention-share loss — a competitor took mention share on a top query where yours fell; or a top-performing query lost its mention on the primary provider |
+| **Medium** | Non-branded query lost its mention on one provider; or a top query lost its CITATION (secondary signal) while the mention held |
+| **Low** | Query lost a mention or citation it only held marginally |
 
 ## Diagnosis
 
 For each regression, check causes in order:
 
-1. **Competitor displacement** — Did a competitor domain appear in the citation for this query+provider? Check current run snapshots. For the whole picture, `cnry sources <project> --rank` (MCP: `canonry_analytics_sources`) ranks every cited domain and tags each with a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), and `--by-provider` shows which engine grounds on whom — so you can tell a rival you must out-rank from an aggregator/editorial surface you should pitch for placement.
-2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status.
+1. **Competitor displacement** — Check mention share BEFORE cited-domain displacement. First: did a competitor brand take the mention share you lost? Compare `scores.mentionShare` (`cnry overview`) run-over-run and read `cnry analytics <project> --feature gaps` (`mentionGap[]` = competitor mentioned where you're not) to see who is being named instead of you. Only then check the citation side: did a competitor domain appear in the grounding sources for this query+provider? Check current run snapshots. For the whole cited picture, `cnry sources <project> --rank` (MCP: `canonry_analytics_sources`) ranks every cited domain and tags each with a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), and `--by-provider` shows which engine grounds on whom — so you can tell a rival you must out-rank from an aggregator/editorial surface you should pitch for placement.
+2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status. An unindexed or thin page starves the engine of reasons to mention you as well as to cite you.
 3. **Content change** — Did the page content change significantly? Compare content hashes if available.
 4. **Provider behavior change** — Did the provider change its response pattern for this query type?
 5. **Unknown** — No clear cause identified. Flag for manual investigation.

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

@@ -15,10 +15,11 @@ cnry report <project> --output dist/aeo.html   # custom path
 cnry report <project> --format json            # raw payload, useful for narrating in chat
 ```
 
-The HTML is self-contained (inline CSS + SVG charts, no network dependencies) and covers: executive summary, per-query × per-provider citation matrix, competitor landscape, AI citation sources, GSC + GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps. Same payload is available via `GET /api/v1/projects/<name>/report` and the `canonry_report` MCP tool — use `--format json` when you want to summarize specific numbers in a thread instead of attaching the file.
+The HTML is self-contained (inline CSS + SVG charts, no network dependencies) and leads visually with mention coverage (the primary gauge), then covers: executive summary, per-query × per-provider matrix (mention + citation), competitor landscape, AI citation sources, GSC + GA4 performance, social and AI referrals, indexing health, trend, prioritized insights, and recommended next steps. Same payload is available via `GET /api/v1/projects/<name>/report` and the `canonry_report` MCP tool — use `--format json` when you want to summarize specific numbers in a thread instead of attaching the file.
 
 Behaviors worth knowing before narrating numbers from the report:
-- `executiveSummary.citationRate` is **per-query** — `citedQueryCount / totalQueryCount`, where a query counts as cited if any provider in the run cited it. The denominator is total tracked queries (not (query × provider) pairs), so the rate stays comparable when provider count varies between runs. Use `citedQueryCount` / `totalQueryCount` directly when narrating ratios.
+- **Mention is the primary metric; citation is secondary.** Narrate the mention figures first. `executiveSummary.mentionRate` is **per-query** — `mentionedQueryCount / totalQueryCount`, where a query counts as mentioned if any provider's answer text named the brand in the run. The report leads visually with mention coverage, but the machine field backing that headline is not confirmed in the CLI docs — [confirm field name against `cnry report --format json` / `ProjectReportDto`] before quoting it as the headline; `executiveSummary.mentionRate` / `mentionedQueryCount` are the confirmed per-query mention fields.
+- `executiveSummary.citationRate` is the **secondary**, per-query citation signal — `citedQueryCount / totalQueryCount`, where a query counts as cited if any provider in the run cited it. The denominator is total tracked queries (not (query × provider) pairs), so the rate stays comparable when provider count varies between runs. Use `citedQueryCount` / `totalQueryCount` directly when narrating ratios. Mention and citation are independent — never compute one from the other.
 - The same per-query definition powers every `citationsTrend[].citationRate` so trend deltas reflect real movement, not provider-mix variance.
 - `citationsTrend` excludes partial runs. A project with only one completed run shows `trend: "unknown"` — never claim a comparison that isn't there.
 - Project ownership and competitor tagging use subdomain-aware matching: `blog.example.com` counts as the project when `example.com` is the canonical domain or in `ownedDomains`; `blog.rival.com` is tagged `isCompetitor: true` when `rival.com` is tracked.
@@ -32,9 +33,11 @@ The hand-rolled templates below are still the right call when the user wants a f
 # Weekly AEO Report: <project> (<date range>)
 
 ## Summary
-- Cited rate: <X>% (Δ<+/-Y>% from last week)
-- Regressions: <N> new, <N> resolved
-- Gains: <N> new citations
+- Mention rate: <X>% (Δ<+/-Y>% from last week)        ← primary KPI
+- Mention share: <X>% (Δ<+/-Y>% from last week)       ← AI share-of-voice vs competitors
+- Cited rate: <X>% (Δ<+/-Y>% from last week)          ← secondary signal
+- Regressions: <N> new, <N> resolved (lead with lost mentions; note lost citations second)
+- Gains: <N> new mentions / <N> new citations
 - Providers monitored: <N>
 
 ## Key Changes
@@ -72,14 +75,16 @@ The hand-rolled templates below are still the right call when the user wants a f
 ## Metrics
 | Metric | Start of Month | End of Month | Change |
 |--------|---------------|--------------|--------|
-| Overall cited rate | <X>% | <Y>% | <Δ>% |
+| Mention rate (primary) | <X>% | <Y>% | <Δ>% |
+| Mention share (primary) | <X>% | <Y>% | <Δ>% |
+| Cited rate (secondary) | <X>% | <Y>% | <Δ>% |
 | Queries monitored | <N> | <N> | <Δ> |
 | Active regressions | <N> | <N> | <Δ> |
 
 ## Provider Breakdown
-| Provider | Cited Rate | Trend |
-|----------|-----------|-------|
-| <provider> | <X>% | ↑/↓/→ |
+| Provider | Mention Rate | Mention Trend | Cited Rate | Cited Trend |
+|----------|--------------|---------------|-----------|-------------|
+| <provider> | <X>% | ↑/↓/→ | <X>% | ↑/↓/→ |
 
 ## Fixes Deployed
 | Date | Fix | Status | Impact |

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

@@ -5,12 +5,12 @@ description: Aero's persona, values, and voice — context-agnostic identity tha
 
 # Who You Are
 
-You are **Aero** — an AEO analyst. You help operators understand how AI answer engines cite their domain, and you act decisively on what the data shows.
+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.
 
 ## Values
 
-- **Evidence over opinion.** Numbers before interpretation. "You lost the ChatGPT citation for 'roof repair phoenix' between March 28 and April 2" beats "your visibility decreased."
-- **Proactive, not passive.** Regressions don't wait to be asked about. Surface them when you spot them. Flag emerging competitors the moment they appear in citations you own.
+- **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.
 - **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.
@@ -25,6 +25,6 @@ You have opinions. If a client's setup is actively hurting them, say so plainly.
 
 ## Boundaries
 
-- Never fabricate citation data. If you haven't run a sweep, say so.
-- Never speculate why an AI cited a competitor without evidence — stick to what canonry observed.
+- Never fabricate mention or citation data. If you haven't run a sweep, say so. Never coerce `answerMentioned` null → false — null means "not checked," not "not mentioned."
+- Never speculate why an AI mentioned or cited a competitor without evidence — stick to what canonry observed.
 - Private client data stays private.

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

@@ -131,7 +131,7 @@ Aero also wakes unprompted after every `run.completed` so insights and regressio
 
 - **Never touch live WordPress without explicit approval**
 - **Back up `~/.canonry/config.yaml` before any config edit**
-- **Never fabricate citation data** — if a sweep hasn't run, say so
+- **Never fabricate mention or citation data** — if a sweep hasn't run, say so; never coerce `answerMentioned` null → false (null = "not checked")
 - **Client data stays private** — canonry repo is public; no real domains in issues
 - **Respect API rate limits** — batch operations, avoid tight loops
 

package/assets/agent-workspace/skills/canonry/references/aeo-analysis.md

@@ -1,51 +1,87 @@
 # AEO Analysis: Interpreting Canonry Results
 
+Canonry tracks two independent signals per (query × provider): **mention** (the brand is named in the AI answer text, `answerMentioned`) and **citation** (the domain appears in the grounding sources, `cited`/`citedDomains`). **Mention is the primary read; citation is secondary.** Never compute one from the other, and never coerce `answerMentioned` null → false — null means "not checked," not "not mentioned."
+
+## What Mention Means
+
+A "mentioned" query means the client's brand was NAMED in the AI provider's answer text when that query was asked — the model said the brand out loud in its prose. This is the primary gauge of AI visibility: it is what the user actually reads. It does NOT mean:
+- The AI recommended them positively (it may name them neutrally or unfavorably)
+- The brand was the headline answer
+- It will persist on the next sweep
+
+A "not-mentioned" query means the answer text never named the client. `answerMentioned = null` is distinct: the mention was not checked for that snapshot — treat it as missing, not negative.
+
+**Mention share** is the competitive read: of all brand names appearing across the answer set (the project plus tracked competitors), the fraction that were the project = AI share-of-voice. A competitor taking mention share on a query you used to own is the highest-signal regression.
+
+### First diagnostic read (mention-first)
+
+```bash
+cnry get <project> scores.mentionCoverage.value     # mention rate (primary)
+cnry get <project> scores.mentionShare.value        # mention share / AI share-of-voice (primary)
+cnry analytics <project> --feature gaps             # mentionGap[] / notMentioned[] (who's named instead of you)
+```
+
+Read citation as the secondary lens only after the mention read:
+
+```bash
+cnry get <project> scores.citationCoverage.value    # cited rate (secondary)
+```
+
 ## What Citation Means
 
-A "cited" query means the client's domain appeared in an AI provider's response when that query was asked. It does NOT mean:
+A "cited" query means the client's domain appeared in an AI provider's grounding sources when that query was asked — the structured source list, not the prose. It is the **secondary** signal. It does NOT mean:
 - The AI recommended them positively
 - The citation is prominent
 - It will persist on the next sweep
+- That the brand was also mentioned in the answer text (citation and mention are independent — a model can cite the domain without naming the brand, and vice versa)
 
-A "not-cited" query means the AI answered without mentioning the client at all.
+A "not-cited" query means the AI answered without grounding on the client's domain.
 
 ## 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.
+
 ```
-✓ cited  AEO Agency NYC             ← branded/direct match
-✓ cited  best plumber brooklyn
-✗ not-cited  how to fix a leaky faucet  ← informational gap: no page for this topic
-✗ not-cited  emergency plumber near me  ← competitive gap: others cited instead
+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
 ```
 
+The summary line reports each signal independently: `Mentioned: X / Y` (primary) and `Cited: X / Y` (secondary) — a query can be one, both, or neither.
+
 ### Query Categories
 
 **Branded/direct queries** (e.g., "[business name] [city]"):
-- If cited: good — entity is established for core queries
-- If not cited: urgent — something broken at a fundamental level (indexing, schema, llms.txt)
+- If mentioned: good — the engine names you for your own core queries (and check the citation as the secondary confirmation)
+- If not mentioned: urgent — the engine won't even say your name; something broken at a fundamental level (indexing, schema, llms.txt). Losing the citation for your own name is the secondary signal on the same query.
 
 **Competitive queries** (e.g., "best [service] [city]"):
-- If not cited: check who IS cited — competitor analysis needed
+- If not mentioned: check who IS mentioned (mention share) — competitor analysis needed. Then check who is cited as the secondary lens.
 - Harder wins; require established authority and trust signals
 
 **Informational/how-to queries** (e.g., "how to [do X]"):
-- If not cited: almost always a content gap — no page targeting this topic, or it's not indexed
-- High-leverage — informational content positions a site as authoritative to AI models
+- If not mentioned (and not cited): almost always a content gap — no page targeting this topic, or it's not indexed
+- High-leverage — informational content positions a site as authoritative to AI models, earning the mention first and the citation second
 
 ## Using Analytics
 
-### Citation Rate Trends (`--feature metrics`)
-Shows citation rate over time across providers. Use to identify:
-- Improving or declining visibility trends
+### Mention + Citation Rate Trends (`--feature metrics`)
+`BrandMetricsDto` returns both `mentionTrend` (primary) and `trend` (the citation trend, secondary) over time across providers. Read mention first. Use to identify:
+- Improving or declining mention trends (does the engine name you more or less often?), then citation trends
 - Provider-specific performance differences
 - Impact of content/indexing changes over time
 
-**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 uncited) queries from creating a false drop in the citation 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.
+**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`)
-Categorizes queries as cited, gap (competitor cited but you're not), or uncited (nobody cited). Priorities:
-- **Gap queries** are highest priority — competitors are winning these
-- **Uncited queries** may need content or may be too broad
+`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:
+- **`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
 
 ### Source Breakdown (`--feature sources`)
 Shows which source categories AI models cite for your queries. Helps identify:
@@ -59,10 +95,15 @@ Every content target carries a deterministic `winnabilityClass`: **ownable** (wo
 - `canonry content brief <project> <targetRef>` — synthesize a structured brief (angle, why-winnable, schema hookup) for an **ownable** target. Ceded targets are rejected — don't chase them.
 Recommend briefs only for ownable targets; for ceded head terms, advise earning placement on the aggregator/editorial surface instead of writing a competing page.
 
-## Diagnosing Citation Gaps
+## Diagnosing Mention + Citation Gaps
+
+### Step 0: Read the mention signal first
+Before anything else, separate the two signals. `cnry analytics <project> --feature gaps` tells you whether the query is in `notMentioned[]` (the engine never names you), `mentionGap[]` (a competitor is named instead), or only in the cited `gap[]`/`uncited[]` (a citation gap while the mention may hold). The fix priority follows the mention: earn the name first, the source citation second. `answerMentioned = null` means the snapshot wasn't checked — re-run, don't read it as not-mentioned.
+
+> **Known gap:** `cnry health` is citation-only today (no mention dimension). For the mention-first read, use `cnry overview` / `cnry get <project> scores.mentionCoverage.value` / `cnry get <project> scores.mentionShare.value` until health is extended.
 
-### Step 1: Check indexing first
-Not cited ≠ bad content. Often the page isn't indexed yet.
+### Step 1: Check indexing
+Not mentioned / not cited ≠ bad content. Often the page isn't indexed yet, which starves both signals.
 ```bash
 cnry google coverage <project>
 ```
@@ -72,7 +113,7 @@ If key pages are "unknown to Google," submit them before drawing conclusions.
 Is there a page on the site targeting that query? If not, that's the gap — not a canonry or provider issue.
 
 ### Step 3: Check competitors
-For competitive queries, if others are cited and the client isn't:
+For competitive queries, if others are mentioned/cited and the client isn't (check mention share first, cited domains second):
 - Do competitors have more specific, dedicated pages?
 - Do they have stronger schema/structured data?
 - Are they more established in the index?
@@ -89,7 +130,7 @@ cnry analytics <project> --feature gaps --window 30d
 Look for patterns: are gaps growing or shrinking? Are new competitors appearing?
 
 ### Step 6: Check GA4 traffic for impact
-A lost citation isn't always a lost user. Before declaring a regression real, confirm whether AI-referral traffic actually fell on the same window:
+A lost mention (or lost citation) isn't always a lost user. Before declaring a regression real, confirm whether AI-referral traffic actually fell on the same window:
 ```bash
 cnry ga status <project>                          # confirm lastSyncedAt is recent; re-sync if stale
 cnry ga ai-referral-history <project> --format json
@@ -105,40 +146,47 @@ GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI c
 
 ## Trend Interpretation
 
-**Stable cited** — monitor for regressions, no action needed.
+Read transitions on the mention signal first (primary), then the citation signal (secondary). They move independently — a query can gain the mention while losing the citation.
 
-**New citation** (was not-cited, now cited) — win. Correlate with what changed: new content, indexing, schema update.
+**Stable mentioned** — the engine keeps naming you; monitor for regressions, no action needed. (Track the cited state as the secondary confirmation.)
 
-**Regression** (was cited, now not-cited) — investigate immediately:
+**New mention** (was not-mentioned, now mentioned) — primary win. Correlate with what changed: new content, indexing, schema update. A **new citation** (domain newly in sources) is a secondary win on the same query.
+
+**Regression** — investigate immediately, leading with a **lost mention** (was mentioned, now not). A lost citation while the mention holds is the secondary, lower-tier regression. Either way:
+- Did a competitor take the mention share (`mentionGap[]`)?
 - Did a competitor page launch?
 - Did the page get deindexed or go down?
 - Did the model update?
 - Check `cnry google deindexed <project>` for index losses
 
-**Fluctuation** (cited in some runs, not others) — normal for competitive queries. Track trend over 5+ runs before drawing conclusions. AI answers are non-deterministic.
+**Fluctuation** (mentioned/cited in some runs, not others) — normal for competitive queries. Track the trend over 5+ runs before drawing conclusions. AI answers are non-deterministic.
 
 ## What to Recommend
 
-### Low overall citation (< 50%)
-1. Audit indexing — `cnry google coverage <project>`
+### Low overall mention rate (< 50%)
+Mention rate is the primary KPI — fix this before cited rate.
+1. Audit indexing — `cnry google coverage <project>` (an unindexed page can't be named or cited)
 2. Submit unindexed pages to Google Indexing API
 3. Submit sitemap to Bing WMT + send IndexNow batch
-4. Check core pages for schema (LocalBusiness / Organization / FAQPage)
-5. Map uncited queries to pages — which have no corresponding page?
+4. Check core pages for schema (LocalBusiness / Organization / FAQPage) so the brand name is unambiguous
+5. Map `notMentioned[]` / `mentionGap[]` queries to pages — which have no corresponding page, and who is named instead?
+
+A low cited rate while the mention rate holds is the secondary problem: the engine names you but grounds on other sources — pursue the citation (schema, llms.txt, indexing) after the mention is secured.
 
-### Branded terms not cited
-Red flag. Check:
+### Branded terms not mentioned
+Red flag — the engine won't even say your name. Check (the lost citation for your own name is the secondary signal here):
 - Is the homepage indexed?
 - Does `llms.txt` exist and list the business clearly?
 - Does schema include the exact brand name in `name` field?
+- Is a brand alias missing? (`spec.brandAliases` widens the `answerMentioned` detector for variants like "Acme Cloud" vs "AcmeCloud".)
 
-### Informational terms not cited
+### Informational terms not mentioned
 Content strategy play:
-- Does a page targeting this topic exist? If not, create it.
+- Does a page targeting this topic exist? If not, create it — give the engine a reason to name you.
 - Is it indexed? If not, submit it.
 - Is it structured for AI extraction? (FAQ schema, clear H2s, definition-style answers)
 
-### Provider variance (cited on one, not others)
+### Provider variance (mentioned/cited on one, not others)
 Expected — each provider has independent knowledge. Focus on the ones that matter most for the client's audience. Don't over-optimize for one provider at the expense of others.
 
 ## The AEO Timeline Reality

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

@@ -103,24 +103,35 @@ Use `--probe` whenever you're testing on your own initiative — verifying a fix
 
 `snapshot` does not create a project or write to the DB. It generates category queries, runs providers, and produces a report for prospecting.
 
-## Citation Data
+## Mention + Citation Data
+
+Two independent signals per (query × provider): **mention** (`answerMentioned` — brand named in the answer text; the **primary** read) and **citation** (`cited`/`citedDomains` — domain in the grounding sources; **secondary**). Read mention first. Never compute one from the other; never coerce `answerMentioned` null → false (null = "not checked").
 
 ```bash
-cnry evidence <project>                        # per-query cited/not-cited + mentioned/not-mentioned
+cnry evidence <project>                        # per-query [C/c][M/m] cell + Mentioned: X / Y / Cited: X / Y
 cnry evidence <project> --format json          # JSON output
 cnry history <project>                         # audit trail
 cnry export <project> --include-results        # export as YAML
-cnry backfill answer-visibility                # recompute citationState from stored answers
-cnry backfill answer-visibility --dry-run      # preview which snapshots would change
-cnry backfill answer-mentions                  # recompute answerMentioned from stored answers (honors brandAliases)
+cnry backfill answer-mentions                  # recompute answerMentioned (primary) from stored answers (honors brandAliases)
 cnry backfill answer-mentions --dry-run
+cnry backfill answer-visibility                # recompute citationState (secondary) from stored answers
+cnry backfill answer-visibility --dry-run      # preview which snapshots would change
 cnry backfill insights <project>               # recompute insights for completed runs
 cnry backfill insights <project> --since 2026-04-01 --dry-run
 ```
 
-Output uses a two-glyph cell per (query × provider): `[C/c][M/m]` — uppercase = present, lowercase = absent, `–` = no snapshot. Always print the legend before the table; never collapse the two signals into one cell.
+Output uses 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.
 
-Summary: `Cited: X / Y` and `Mentioned: X / Y` are reported independently — a query can be one, both, or neither.
+```
+Legend: [C/c][M/m]  C=cited c=not-cited  M=mentioned m=not-mentioned  –=no snapshot
+
+[C][M]  acme corp ny       ← mentioned AND cited
+[c][M]  best crm for smb    ← mentioned, not cited (mention win, citation gap)
+[C][m]  crm pricing         ← cited, not mentioned (citation without share of voice)
+[c][m]  free crm tools      ← neither
+```
+
+Summary: `Mentioned: X / Y` (primary) and `Cited: X / Y` (secondary) are reported independently — a query can be one, both, or neither.
 
 ## Reports
 
@@ -144,8 +155,8 @@ Behavior to know when narrating numbers from the report:
 
 ```bash
 cnry analytics <project>                       # default analytics view
-cnry analytics <project> --feature metrics     # citation rate trends
-cnry analytics <project> --feature gaps        # brand gap analysis (cited/gap/uncited)
+cnry analytics <project> --feature metrics     # mention + citation rate trends (BrandMetricsDto: mentionTrend primary, trend secondary)
+cnry analytics <project> --feature gaps        # brand gap analysis — mention buckets (mentionedQueries[]/mentionGap[]/notMentioned[]) primary, cited buckets (cited[]/gap[]/uncited[]) secondary
 cnry analytics <project> --feature sources     # source breakdown by category
 cnry analytics <project> --window 7d           # time window: 7d, 30d, 90d, all
 ```
@@ -190,7 +201,7 @@ cnry insights <project>                        # list active insights (regressio
 cnry insights <project> --dismissed            # include dismissed insights
 cnry insights <project> --format json          # JSON output
 cnry insights dismiss <project> <id>           # dismiss an insight
-cnry health <project>                          # latest citation health snapshot
+cnry health <project>                          # latest citation health snapshot (citation-only — see known gap below)
 cnry health <project> --history                # health trend over time
 cnry health <project> --history --limit 10     # limit history entries
 cnry health <project> --format json            # JSON output
@@ -198,6 +209,8 @@ cnry backfill insights <project>              # backfill insights for all comple
 cnry backfill insights <project> --from-run <id> --to-run <id>  # backfill a range
 ```
 
+> **Known gap (mention-first read):** `cnry health` is **citation-only** today — it has no mention dimension. For the primary mention-first read, use `cnry overview` and `cnry get <project> scores.mentionCoverage.value` / `cnry get <project> scores.mentionShare.value` until health is extended.
+
 ## Queries & Competitors
 
 ```bash
@@ -237,6 +250,8 @@ Available events: `citation.lost`, `citation.gained`, `run.completed`, `run.fail
 
 `insight.critical` and `insight.high` fire when the intelligence engine generates critical- or high-severity insights after a sweep completes.
 
+> **No mention events yet.** Notification events cover the citation signal only — there are **no** `mention.lost` / `mention.gained` events today. For mention-first monitoring, read `scores.mentionCoverage` / `scores.mentionShare` via `cnry overview` (or the `insight.*` events, which can be driven by mention-side insights); do not wire automation to mention events that aren't emitted.
+
 ## Provider Settings & Quotas
 
 ```bash