@ainyc/canonry 4.30.0 → 4.32.0

package/README.md

@@ -8,9 +8,9 @@
 - Watch AI engines crawl and refer traffic via [server-log ingestion](skills/canonry/references/server-side-traffic.md) — Cloud Run logs and the WordPress Traffic Logger plugin today
 - Diagnose against real traffic with built-in [GSC](docs/google-search-console-setup.md), [GA4](docs/google-analytics-setup.md), and [Bing Webmaster](docs/bing-webmaster-setup.md)
 - Execute fixes via [WordPress](docs/wordpress-setup.md), JSON-LD schema, and indexing submissions
-- Manage many clients declaratively — config-as-code YAML + `canonry apply`
+- Manage many clients declaratively — config-as-code YAML + `cnry apply`
 - Schedule recurring visibility checks AND traffic syncs, with webhook alerts on regressions
-- Generate client-ready HTML reports — `canonry report <project>`
+- Generate client-ready HTML reports — `cnry report <project>`
 - Drive from your own agent via the [67-tool MCP adapter](docs/mcp.md) or webhooks
 - Or use **Aero** — Canonry's built-in agent that wakes up after every run
 
@@ -22,28 +22,30 @@ Every dashboard view has a matching CLI command and API endpoint. The CLI is the
 
 ```bash
 npm install -g @ainyc/canonry
-canonry init
-canonry serve
+cnry init
+cnry serve
 ```
 
+The CLI installs as `cnry` (short form) and `canonry` — the two are interchangeable.
+
 Open [http://localhost:4100/setup](http://localhost:4100/setup). A guided wizard walks you through provider keys, project setup, queries, and your first visibility check.
 
 Prefer the terminal?
 
 ```bash
-canonry project create my-site --domain example.com
-canonry query add my-site "your first query" "second query"
-canonry run my-site --wait
-canonry evidence my-site
-canonry insights my-site
+cnry project create my-site --domain example.com
+cnry query add my-site "your first query" "second query"
+cnry run my-site --wait
+cnry evidence my-site
+cnry insights my-site
 ```
 
 ## If you get stuck
 
 | Problem | Fix |
 |---------|-----|
-| No provider key configured | Grab a free [Gemini key](https://aistudio.google.com/apikey), set `GEMINI_API_KEY`, restart `canonry serve`. |
-| No results after a run | Visibility checks are async — check the Runs tab or use `canonry run <project> --wait`. |
+| No provider key configured | Grab a free [Gemini key](https://aistudio.google.com/apikey), set `GEMINI_API_KEY`, restart `cnry serve`. |
+| No results after a run | Visibility checks are async — check the Runs tab or use `cnry run <project> --wait`. |
 | Not sure what queries to test | The setup wizard auto-generates them by analyzing your site. |
 | `npm install` fails on `node-gyp` | Install build tools for `better-sqlite3` ([guide](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md)). |
 
@@ -57,7 +59,7 @@ canonry insights my-site
 | Perplexity | [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) | `PERPLEXITY_API_KEY` |
 | Local LLMs | Any OpenAI-compatible endpoint | `LOCAL_LLM_URL` |
 
-Configure during `canonry init`, in the dashboard `/settings`, or as env vars.
+Configure during `cnry init`, in the dashboard `/settings`, or as env vars.
 
 ## Documentation
 
@@ -69,7 +71,7 @@ Configure during `canonry init`, in the dashboard `/settings`, or as env vars.
 | **Integrations** | [GSC](docs/google-search-console-setup.md) · [GA4](docs/google-analytics-setup.md) · [Bing](docs/bing-webmaster-setup.md) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloud Run + WordPress logs)](skills/canonry/references/server-side-traffic.md) |
 | **Deployment** — Docker, Railway, Render, systemd, Tailscale | [docs/deployment.md](docs/deployment.md) |
 | **API** — 118+ endpoints | `GET /api/v1/openapi.json` (no auth) |
-| **Skills bundle** for Claude Code / Codex | `canonry skills install` ([details](skills/canonry/SKILL.md)) |
+| **Skills bundle** for Claude Code / Codex | `cnry skills install` ([details](skills/canonry/SKILL.md)) |
 | **Roadmap & ADRs** | [docs/roadmap.md](docs/roadmap.md) · [docs/adr/](docs/adr/) |
 | **All docs** | [docs/README.md](docs/README.md) |
 

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

@@ -9,12 +9,12 @@ repository: https://github.com/AINYC/aero
 # Aero Orchestration Skill
 
 You coordinate across two tools to deliver comprehensive AEO monitoring:
-- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log, **GA4 traffic + AI/social referrals**). Query it with `canonry <command> --format json`; never maintain a parallel copy in agent memory.
+- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log, **GA4 traffic + AI/social referrals**). Query it with `cnry <command> --format json` (the CLI is also installed as `canonry` — the two are interchangeable); never maintain a parallel copy in agent memory.
 - **aeo-audit** — on-demand site analysis and fix generation.
 
 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.
 
-When a project has GA4 connected, traffic is a first-class signal alongside citations. Use `canonry ga traffic` / `canonry ga attribution --trend` for the current snapshot, `canonry ga ai-referral-history` and `canonry ga social-referral-history` for daily series. Reads query a local DB synced by `canonry ga sync` — confirm `canonry ga status` shows a recent `lastSyncedAt` before quoting numbers; if stale, re-sync first. Full command reference and return shapes live in the co-installed `canonry/references/canonry-cli.md` (look for the "Google Analytics 4" section).
+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. Full command reference and return shapes live in the co-installed `canonry/references/canonry-cli.md` (look for the "Google Analytics 4" section).
 
 ## Judgment Rules
 

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

@@ -11,7 +11,15 @@ Discovery turns a free-text ICP description into a deduped basket of representat
 - **wasted-surface** — a tracked competitor is cited but the project is not
 - **aspirational** — neither the project nor a tracked competitor is cited (greenfield)
 
-Plus a competitor map: every non-canonical domain that shows up in probe citations, ranked by hit count, so the operator can spot recurring competitors that aren't yet on the watchlist.
+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.
+
+After probing, one Gemini call classifies every recurring cited domain into a `competitorType`:
+
+- **direct-competitor** — a business competing for the same customers (another hotel, another tool in the category). The only type promoted by default.
+- **ota-aggregator** — OTAs, marketplaces, directories, review aggregators (expedia.com, booking.com, g2.com). Suppressed from competitor tracking.
+- **editorial-media** — news, blogs, "best of" round-ups (timeout.com, a personal blog). A *channel* to earn placement in, not a competitor — suppressed by default.
+- **other** — government sites, social platforms, off-topic domains. Suppressed.
+- **unknown** — classification failed, or a session that pre-dates classification. Excluded from the default promote.
 
 ## When discovery is the right move
 
@@ -24,7 +32,7 @@ Plus a competitor map: every non-canonical domain that shows up in probe citatio
 The operator runs:
 
 ```bash
-canonry discover run <project> --icp "..." --wait
+cnry discover run <project> --icp "..." --wait
 ```
 
 Or the MCP equivalent: `canonry_discover_run_start` with `{ project, request: { icpDescription, dedupThreshold?, maxProbes? } }`. The endpoint returns `{ runId, sessionId, status: "running" }` immediately and finishes the work in the background. Poll `canonry_discover_session_get` until `status` is `completed` or `failed`.
@@ -39,13 +47,13 @@ Per session: ~$1 at the default probe budget (100 queries × 1 Gemini grounded c
 
 `canonry_discover_session_get` returns:
 
-- Session-level: `seedCountRaw` vs `seedCount` (proves embedding dedup did real work), bucket counts, `competitorMap` (top recurring non-tracked domains).
+- Session-level: `seedCountRaw` vs `seedCount` (proves embedding dedup did real work), bucket counts, `competitorMap` (top recurring non-tracked domains, each with `hits` and `competitorType`).
 - Per-probe: query, bucket, citation state, the cited domains list.
 
 Things to call out without being asked:
 
 - **High wasted-surface ratio** (≥ 40% of probes, or > cited count at ≥ 20%) → the project is missing from its own competitive space. The auto-written `discovery.basket-divergence` insight flags this as `high` severity.
-- **Recurring new competitor domains** in `competitorMap` that aren't already in the project's tracked competitor list → `canonry discover promote` adopts domains with at least 2 hits automatically alongside the queries; or add them à la carte with `canonry competitor add <project> <domain>`.
+- **Recurring `direct-competitor` domains** in `competitorMap` that aren't already in the project's tracked competitor list → `cnry discover promote` adopts `direct-competitor` domains with at least 2 hits automatically alongside the queries; or add them à la carte with `cnry competitor add <project> <domain>`. Domains classified `ota-aggregator` / `editorial-media` / `other` are surfaced but **not** promoted by default — flag a recurring `editorial-media` site as a placement opportunity, not a competitor.
 - **Aspirational greenfield** queries with no tracked competitor and no canonical cite → low-friction content opportunities.
 
 ## Promoting a session into the tracked basket
@@ -53,7 +61,7 @@ Things to call out without being asked:
 Once a session is `completed`, preview first unless the operator has already approved the write:
 
 ```bash
-canonry discover promote preview <project> <session-id>
+cnry discover promote preview <project> <session-id>
 ```
 
 Or the MCP equivalent: `canonry_discover_promote_preview` with `{ project, sessionId }`.
@@ -63,15 +71,16 @@ The preview returns every bucket so you can explain the tradeoff:
 - `cited` — already grounded to the project, safe to track.
 - `aspirational` — greenfield ICP-fit opportunities, safe to track as a growth basket.
 - `wasted-surface` — competitor-cited but project-missing. Treat as content-planning evidence first; do not add it to the weekly tracked basket unless the operator explicitly wants those off-ICP competitor gaps tracked.
-- `suggestedCompetitors` — recurring domains not already tracked. The promote path only auto-adopts domains with at least 2 hits.
+- `suggestedCompetitors` — recurring domains (≥ 2 hits) not already tracked, of **every** classified type, each tagged with `competitorType`. The default promote adopts only the `direct-competitor` ones; the others are shown so you can recommend a `--competitor-types` widening.
 
 Promote with one of these paths:
 
 ```bash
-canonry discover promote <project> <session-id>                          # cited + aspirational buckets + recurring competitor domains
-canonry discover promote <project> <session-id> --bucket aspirational    # scope to a bucket subset (repeatable / comma-separated)
-canonry discover promote <project> <session-id> --bucket wasted-surface  # explicitly track off-ICP competitor gaps
-canonry discover promote <project> <session-id> --no-competitors         # queries only, skip the competitor merge
+cnry discover promote <project> <session-id>                                          # cited + aspirational buckets + direct-competitor domains
+cnry discover promote <project> <session-id> --bucket aspirational                    # scope to a bucket subset (repeatable / comma-separated)
+cnry discover promote <project> <session-id> --bucket wasted-surface                  # explicitly track off-ICP competitor gaps
+cnry discover promote <project> <session-id> --competitor-types direct-competitor,editorial-media   # widen the competitor merge to other classified types
+cnry discover promote <project> <session-id> --no-competitors                         # queries only, skip the competitor merge
 ```
 
 Or the MCP equivalent:
@@ -80,14 +89,14 @@ Or the MCP equivalent:
 { "project": "<project>", "sessionId": "<session-id>" }
 ```
 
-That default request promotes `cited` + `aspirational` queries and recurring competitors. For scoped writes, pass `request`:
+That default request promotes `cited` + `aspirational` queries and `direct-competitor` domains. For scoped writes, pass `request`:
 
 ```json
-{ "project": "<project>", "sessionId": "<session-id>", "request": { "buckets": ["aspirational"], "includeCompetitors": false } }
+{ "project": "<project>", "sessionId": "<session-id>", "request": { "buckets": ["aspirational"], "competitorTypes": ["direct-competitor", "editorial-media"], "includeCompetitors": false } }
 ```
 
 - **Default is cited + aspirational.** `wasted-surface` queries are off-ICP competitor gaps; promote them only when the operator explicitly wants those tracked in the weekly basket.
-- **Competitor promotion requires recurrence.** Default competitor merge ignores one-off domains and adopts only domains with at least 2 hits.
+- **Competitor promotion requires recurrence + a promotable type.** The default competitor merge ignores one-off domains (< 2 hits) and adopts only domains classified `direct-competitor`. Pass `competitorTypes` (CLI: `--competitor-types`) to also adopt `editorial-media` channels, or `competitorTypes: ["unknown"]` to recover a legacy session promoted before classification existed.
 - **Add-only and idempotent.** Queries and competitor domains already tracked are returned under `skipped`, never inserted twice. Re-running a promote is safe.
 - **Completed sessions only.** Promoting a `queued`/`seeding`/`probing`/`failed` session is rejected — the buckets aren't final.
 - Promoted rows carry `provenance="discovery:<sessionId>"`, so a tracked query can always be traced back to the session that surfaced it.
@@ -106,8 +115,8 @@ Respond with:
 
 1. A one-line headline naming the dominant bucket.
 2. The top 2-3 wasted-surface queries (call `canonry_discover_session_get` to fetch them — don't guess).
-3. The top 1-2 recurring new competitor domains worth tracking, ignoring one-hit domains unless the operator asks for the full long tail.
-4. A single recommended next step. Examples: "preview and promote cited + aspirational findings (`canonry discover promote preview`, then `canonry discover promote`)", "the wasted-surface set warrants a content plan around X before tracking", "the aspirational set is greenfield — pick the 3 with highest commercial intent and write content".
+3. The top 1-2 recurring `direct-competitor` domains worth tracking, ignoring one-hit domains unless the operator asks for the full long tail. If a recurring `editorial-media` domain stands out, mention it separately as a placement opportunity — not a competitor.
+4. A single recommended next step. Examples: "preview and promote cited + aspirational findings (`cnry discover promote preview`, then `cnry discover promote`)", "the wasted-surface set warrants a content plan around X before tracking", "the aspirational set is greenfield — pick the 3 with highest commercial intent and write content".
 
 Do not recommend "promote everything" as the default. The safe path is: inspect session detail, preview promotion candidates, then promote the default cited + aspirational set. Escalate `wasted-surface` to tracking only when the operator deliberately chooses that tradeoff.
 
@@ -120,7 +129,7 @@ Keep it tight. The operator wakes to a short, decision-ready summary, not a full
 
 ## Failure modes
 
-- **Gemini not configured** → orchestrator throws early; `runs.status='failed'` with `Gemini provider is not configured.` Surface as "configure Gemini before running discovery" — link to `canonry init` or `~/.canonry/config.yaml`.
+- **Gemini not configured** → orchestrator throws early; `runs.status='failed'` with `Gemini provider is not configured.` Surface as "configure Gemini before running discovery" — link to `cnry init` or `~/.canonry/config.yaml`.
 - **Vertex-only Gemini** → embeddings step throws (Vertex embeddings deferred). Same surface, "use a Gemini API key for now."
 - **ICP missing** → route returns 400 with `VALIDATION_ERROR`. Ask the operator for the ICP description in plain language.
 - **Seed collapse (hyperlocal/niche businesses)** → 40 raw seeds collapse to 1-2 canonical queries after embedding+clustering, even at low dedup thresholds. This happens when Gemini generates seed queries that all live in the same semantic pocket (e.g. all variants of "boutique hotel Venice Beach"). The embedding model sees them as near-identical, so clustering produces one representative.
@@ -130,7 +139,7 @@ Keep it tight. The operator wakes to a short, decision-ready summary, not a full
   **Remediation:** break the ICP into 3-5 distinct purchase-intent angles and run one session per angle via `--icp-angle`:
 
   ```bash
-  canonry discover run <project> \
+  cnry discover run <project> \
     --icp-angle "romantic anniversary stay in Venice Beach" \
     --icp-angle "best rooftop bars and dining hotels LA" \
     --icp-angle "walkable Venice Beach hotels near Abbot Kinney" \

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

@@ -22,12 +22,12 @@ Aero ships with a built-in durable notes store — the `canonry_memory_set`, `ca
 Prefer Aero's read tools (`canonry_project_overview`, `canonry_health_latest`, `canonry_timeline_get`, `canonry_insights_list`, `canonry_queries_list`, `canonry_competitors_list`, `canonry_run_get`) over shelling out, but the CLI exists for operators too:
 
 ```bash
-canonry status <project> --format json
-canonry health <project> --format json
-canonry timeline <project> --since <YYYY-MM-DD> --format json
-canonry insights <project> --format json
-canonry evidence <project> --format json
-canonry audit <project> --format json
+cnry status <project> --format json
+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
 ```
 
 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.
@@ -47,9 +47,9 @@ Derived interpretations (trend summaries, correlations between events) are cheap
 **CLI parity.** Operators can manage memory without talking to you:
 
 ```bash
-canonry agent memory list <project> --format json
-canonry agent memory set <project> --key <k> --value <v>
-canonry agent memory forget <project> --key <k>
+cnry agent memory list <project> --format json
+cnry agent memory set <project> --key <k> --value <v>
+cnry agent memory forget <project> --key <k>
 ```
 
 ## Good remember candidates

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

@@ -10,7 +10,7 @@ description: Workflow recipes — baseline, regression response, weekly review,
 Trigger: First sweep completes for a new project
 
 Steps:
-1. `canonry evidence <project> --format json` → get initial citation data
+1. `cnry evidence <project> --format json` → get initial citation data
 2. Compute baseline: cited rate, provider breakdown, top/bottom queries
 3. `npx @ainyc/aeo-audit "<domain>" --format json` → site readiness score
 4. Identify top 3 gaps (uncited queries with fixable site issues)
@@ -22,9 +22,9 @@ Steps:
 Trigger: Comparison shows decline or webhook fires regression.detected
 
 Steps:
-1. `canonry evidence <project> --format json` → current state
-2. `canonry history <project>` → trend for affected query
-3. Check indexing: `canonry google coverage <project>` → is the page still indexed?
+1. `cnry evidence <project> --format json` → current state
+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?
 5. Audit the page: `npx @ainyc/aeo-audit "<page-url>" --format json`
 6. Diagnose cause: indexing issue / content issue / competitive displacement
@@ -37,7 +37,7 @@ Steps:
 Trigger: Scheduled (weekly, or on-demand)
 
 Steps:
-1. `canonry evidence <project> --format json` → current metrics
+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
@@ -49,7 +49,7 @@ Steps:
 Trigger: User asks "why aren't we cited for X?" or multiple uncited queries detected
 
 Steps:
-1. `canonry evidence <project>` → confirm uncited
+1. `cnry evidence <project>` → confirm uncited
 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

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

@@ -10,9 +10,9 @@ description: Weekly and monthly report templates with metric tables, regression/
 When a client asks for a "current state" or "AEO report" without a specific custom narrative, prefer the bundled report instead of hand-rolling sections:
 
 ```bash
-canonry report <project>                          # writes canonry-report-<project>-YYYY-MM-DD.html in cwd
-canonry report <project> --output dist/aeo.html   # custom path
-canonry report <project> --format json            # raw payload, useful for narrating in chat
+cnry report <project>                          # writes canonry-report-<project>-YYYY-MM-DD.html in cwd
+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.

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

@@ -36,6 +36,8 @@ Agent-first open-source AEO (Answer Engine Optimization) operating platform. Tra
 
 **Website:** [ainyc.ai](https://ainyc.ai) | **Docs:** [github.com/AINYC/canonry](https://github.com/AINYC/canonry)
 
+**CLI:** invoke as `cnry` (short form) or `canonry` — both ship with the npm package and are interchangeable. Examples in this skill use `cnry`.
+
 ## When to Use
 
 - Tracking query citations across AI providers
@@ -56,11 +58,11 @@ Agent-first open-source AEO (Answer Engine Optimization) operating platform. Tra
 
 A canonry engagement follows the same loop regardless of project size:
 
-1. **Diagnose** — Run a baseline sweep (`canonry run <project> --wait`) and a technical audit (`npx @ainyc/aeo-audit@latest <url> --format json`). See `references/aeo-analysis.md` for interpretation.
+1. **Diagnose** — Run a baseline sweep (`cnry run <project> --wait`) and a technical audit (`npx @ainyc/aeo-audit@latest <url> --format json`). See `references/aeo-analysis.md` for interpretation.
 2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.
 3. **Execute** — Apply fixes via the canonry CLI or platform integrations. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.
 4. **Monitor** — Re-run sweeps weekly. Correlate visibility shifts with deployments and competitor moves.
-5. **Report** — Lead with data, not interpretation: "Lost `<query>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `canonry report <project>` to generate a self-contained HTML bundle (executive summary, citation scorecard, competitor landscape, GSC + GA4 performance, insights). Same payload is available via `--format json` and the `canonry_report` MCP tool.
+5. **Report** — Lead with data, not interpretation: "Lost `<query>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `cnry report <project>` to generate a self-contained HTML bundle (executive summary, citation scorecard, competitor landscape, GSC + GA4 performance, insights). Same payload is available via `--format json` and the `canonry_report` MCP tool.
 
 ## Common Starting Points
 
@@ -70,7 +72,7 @@ A canonry engagement follows the same loop regardless of project size:
 
 ## Google Analytics 4
 
-GA4 is a first-class signal alongside citation tracking. Connect once with `canonry ga connect <project> --property-id <id> --key-file <path>`; `canonry ga sync` then pulls daily landing-page traffic, AI-referral sessions across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), and social referrals split into Organic vs Paid via GA4's `channelGroup` — and persists everything into four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`). All read commands query that local store, so they are fast and quotaless once a sync has run. AI referrals are tracked across three GA4 attribution dimensions (session source / first-user source / manual UTM) and joined to landing pages, so you can see which page each AI provider sent traffic to. Use `canonry ga traffic` for the current snapshot, `canonry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `canonry ga ai-referral-history` / `canonry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.
+GA4 is a first-class signal alongside citation tracking. Connect once with `cnry ga connect <project> --property-id <id> --key-file <path>`; `cnry ga sync` then pulls daily landing-page traffic, AI-referral sessions across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), and social referrals split into Organic vs Paid via GA4's `channelGroup` — and persists everything into four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`). All read commands query that local store, so they are fast and quotaless once a sync has run. AI referrals are tracked across three GA4 attribution dimensions (session source / first-user source / manual UTM) and joined to landing pages, so you can see which page each AI provider sent traffic to. Use `cnry ga traffic` for the current snapshot, `cnry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `cnry ga ai-referral-history` / `cnry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.
 
 ## Boundaries & Safety
 

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

@@ -57,7 +57,7 @@ Shows which source categories AI models cite for your queries. Helps identify:
 ### Step 1: Check indexing first
 Not cited ≠ bad content. Often the page isn't indexed yet.
 ```bash
-canonry google coverage <project>
+cnry google coverage <project>
 ```
 If key pages are "unknown to Google," submit them before drawing conclusions.
 
@@ -70,28 +70,28 @@ For competitive queries, if others are cited and the client isn't:
 - Do they have stronger schema/structured data?
 - Are they more established in the index?
 
-Run `canonry evidence <project> --format json` and check `competitorOverlap` in snapshots.
+Run `cnry evidence <project> --format json` and check `competitorOverlap` in snapshots.
 
 ### 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.
 
 ### Step 5: Check analytics trends
 ```bash
-canonry analytics <project> --feature gaps --window 30d
+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:
 ```bash
-canonry ga status <project>                          # confirm lastSyncedAt is recent; re-sync if stale
-canonry ga ai-referral-history <project> --format json
+cnry ga status <project>                          # confirm lastSyncedAt is recent; re-sync if stale
+cnry ga ai-referral-history <project> --format json
                                                       # daily {date, source, medium, attribution, sessions, users}
-canonry ga attribution <project> --trend             # 7d/30d direction per channel + biggest mover
+cnry ga attribution <project> --trend             # 7d/30d direction per channel + biggest mover
 ```
 Read the result against the citation loss window:
 - **AI sessions flat or up** → the citation loss may be sweep-side noise (provider variance, query refresh). Track for one more cycle before alarming the client.
-- **AI sessions dropped on the same date** → real outage; escalate. Cross-reference `aiReferrals[]` from `canonry ga traffic` to identify which provider lost traffic.
+- **AI sessions dropped on the same date** → real outage; escalate. Cross-reference `aiReferrals[]` from `cnry ga traffic` to identify which provider lost traffic.
 - **Organic dropped but AI held** → the citation loss is masking a separate indexing issue. Re-run Step 1.
 
 GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI channel that isn't reflected in citation count usually means a provider expanded an existing citation's exposure (more queries triggering it) — a quiet win worth flagging in the next report.
@@ -106,14 +106,14 @@ GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI c
 - Did a competitor page launch?
 - Did the page get deindexed or go down?
 - Did the model update?
-- Check `canonry google deindexed <project>` for index losses
+- 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.
 
 ## What to Recommend
 
 ### Low overall citation (< 50%)
-1. Audit indexing — `canonry google coverage <project>`
+1. Audit indexing — `cnry google coverage <project>`
 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)