@ainyc/canonry 4.46.0 → 4.46.1

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

@@ -2,19 +2,21 @@
 name: aero
 slug: aero
 description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis with persistent memory and proactive regression response.
-homepage: https://ainyc.ai
+homepage: https://canonry.ai
 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 `cnry <command> --format json` (the CLI is also installed as `canonry` — the two are interchangeable); 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**, **server-side crawler + referral events**). 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. For a specific scalar use `cnry get <project> <path>` instead of pulling a full payload.
 - **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 `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).
+**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`.
 
 ## Judgment Rules
 

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

@@ -32,48 +32,91 @@ metadata:
 
 # Canonry
 
-Agent-first open-source AEO (Answer Engine Optimization) operating platform. Track how AI answer engines cite your domain across Gemini, ChatGPT, Claude, and Perplexity, then act on the signal through the content engine and integrations.
+Agent-first open-source AEO (Answer Engine Optimization) operating platform. Track how AI answer engines **mention** your brand in answers and **cite** your domain in sources across Gemini, ChatGPT, Claude, and Perplexity, then act on the signal through the content engine and integrations.
 
-**Website:** [ainyc.ai](https://ainyc.ai) | **Docs:** [github.com/AINYC/canonry](https://github.com/AINYC/canonry)
+**Website:** [canonry.ai](https://canonry.ai) | **Org:** [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
+- Tracking brand **mentions** in AI answer text and **citations** in source links across providers
+- Expanding the tracked-query basket from an ICP description (`cnry discover run`)
 - Running technical SEO audits (14‑factor scoring)
 - Implementing structured data (JSON‑LD)
 - Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools
+- Wiring server-side traffic (Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal
 - Optimizing `llms.txt`, sitemaps, robots.txt for AI crawlers
 - Submitting URLs to Google Indexing API and Bing IndexNow
 - Analyzing competitor citation patterns
 
 ## Core Philosophy
 
-- **Measure outcomes** — AI models are black boxes; track citations, don't assume causality
+- **Measure outcomes** — AI models are black boxes; track mentions + citations, don't assume causality
 - **Signal over noise** — Focus on high‑intent queries; avoid granular targeting until base visibility exists
 - **CLI‑native** — API‑driven changes over manual CMS clicks; faster, repeatable, auditable
 
+## What Canonry Measures (Vocabulary)
+
+Two parallel signals are tracked per (query × provider) snapshot. They are independent — a model can do either, both, or neither — never conflate them.
+
+| Term | Means | Headline metric |
+|---|---|---|
+| **mentioned** | The project's brand or domain appears in the LLM's **answer text** (the prose the model returns). | **Mention Coverage** — share of (query × provider) snapshots where the brand was mentioned. **Mention Share** is the project's share among the cited+mentioned set vs competitors. |
+| **cited** | The project's domain appears in the LLM's **source links** (the grounding citations returned alongside the answer). | **Citation Coverage** — share of snapshots where the domain was in the source list. |
+
+Configure `spec.brandAliases` on the project (or pass via `cnry apply`) so the mention detector catches "Meta" alongside "Facebook", etc. The downloadable report (`cnry report`) and the dashboard both lead with Mention Coverage; Citation Coverage rides as the secondary gauge.
+
 ## How to Operate
 
 A canonry engagement follows the same loop regardless of project size:
 
-1. **Diagnose** — Run a baseline sweep (`cnry run <project> --wait`) and a technical audit (`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`). Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.
 2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.
-3. **Execute** — Apply fixes via the canonry CLI or platform integrations. 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 `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.
+3. **Execute** — Apply fixes via the canonry CLI or platform integrations. Use `--dry-run` on supported mutations (`cnry project delete`, `cnry query replace`, `cnry backfill ...`) to preview before committing. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.
+4. **Monitor** — Re-run sweeps weekly (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.
+5. **Report** — Lead with data, not interpretation: "Lost the mention for `<query>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `cnry report <project>` to generate a self-contained HTML bundle (mention + citation hero, competitor landscape, GSC + GA4 performance, insights, suggested next queries). Same payload is available via `--format json` and the `canonry_report` MCP tool.
+
+## Surgical Reads
+
+When you need a specific value rather than a full payload, use the dot-path getter:
+
+```bash
+cnry get <project> scores.mentionShare.value
+cnry get <project> scores.mentionCoverage.value
+cnry get <project> insights[0].severity
+cnry get <project> --from report scores.citationCoverage.value
+```
+
+`cnry get` resolves a path into the project's overview (default) or any registered source (`report`, `traffic`, `discovery`, etc.). Returns scalar values without forcing the agent to grep through a 30 KB JSON dump.
 
 ## Common Starting Points
 
 - **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent queries. See `references/indexing.md`.
 - **Established site, regression** → diff canonry runs to find the loss window; verify schema is intact; resubmit affected URLs. See `references/aeo-analysis.md`.
+- **Empty / generic query basket** → describe the ICP and let discovery expand: `cnry discover run <project> --icp "..." --wait`, then `cnry discover promote <session-id>` to adopt the cited + aspirational queries. Multi-location projects can geo-constrain with `--locations <label,...>`.
 - **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county queries until base visibility exists.
 
 ## Google Analytics 4
 
 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.
 
+## Server-Side Traffic
+
+When the project ships behind a server you control, wire crawler + AI-referral evidence directly from the edge: `cnry traffic connect cloud-run | wordpress | vercel <project> ...` writes credentials to `~/.canonry/config.yaml`, `cnry traffic sync` pulls and classifies logs into hourly buckets, and `cnry traffic events / sources / status` expose the rollups. See `references/server-side-traffic.md` for adapter-specific setup.
+
+## Built-in Analyst (Aero)
+
+Canonry ships a built-in agent — Aero — for users who don't already have one. Drive it from the CLI:
+
+```bash
+cnry agent ask <project> "what changed since the last sweep?"
+cnry agent ask <project> "..." --provider claude --scope read-only
+cnry agent memory list <project>          # durable project notes
+```
+
+Aero also wakes unprompted after every `run.completed` so insights and regressions get analyzed without a user click. Users who already run their own agent (Claude Code, Codex, custom) wire webhooks instead: `cnry agent attach <project> --url <webhook-url>` subscribes to `run.completed`, `insight.critical`, `insight.high`, `citation.gained`.
+
 ## Boundaries & Safety
 
 - **Never touch live WordPress without explicit approval**
@@ -86,13 +129,13 @@ GA4 is a first-class signal alongside citation tracking. Connect once with `cnry
 
 | File | Read when |
 |---|---|
-| `references/canonry-cli.md` | Looking up specific canonry commands or flags |
+| `references/canonry-cli.md` | Looking up specific canonry commands, flags, or JSON return shapes |
 | `references/aeo-analysis.md` | Interpreting sweep output, diagnosing regressions, planning content fixes |
 | `references/indexing.md` | Submitting URLs, checking GSC/Bing coverage, fixing indexing gaps |
 | `references/wordpress-integration.md` | Connecting to WordPress, editing pages, pushing staging → live |
-| `references/server-side-traffic.md` | Wiring server-log evidence (Cloud Run + WordPress adapters; more planned) for AI Visibility — Server-Side. Connect, sync, manage sources, troubleshoot. |
+| `references/server-side-traffic.md` | Wiring server-log evidence (Cloud Run, WordPress, Vercel adapters) for AI Visibility — Server-Side. Connect, sync, manage sources, troubleshoot. |
 
 ---
 
-**Tools:** canonry v3+, @ainyc/aeo-audit v1.3+  
-**Website:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)
+**Tools:** canonry v4+, @ainyc/aeo-audit v1.3+  
+**Website:** [canonry.ai](https://canonry.ai) | **Org:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)

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

@@ -29,9 +29,28 @@ cnry project create <name> --domain <url> --country US --language en
 cnry project show <name>                       # project detail
 cnry project update <name>                     # update project settings
 cnry project delete <name>                     # delete a project
-cnry status <project>                          # citation summary + domain info
+cnry project delete <name> --dry-run           # preview cascade impact (GET /delete-preview) without writing
+cnry status <project>                          # mention + citation summary + domain info
 ```
 
+### Brand aliases
+
+`spec.brandAliases: string[]` on the project (set via `cnry apply` or the dashboard) widens the mention detector. Use it when the answer text says "Meta" but the canonical brand is "Facebook", or for product variants ("AcmeCloud", "Acme Cloud", "AcmeCloud Pro"). Aliases are case-insensitive and match the same answer-text scan that powers `answerMentioned`.
+
+## Surgical Reads — `cnry get`
+
+```bash
+cnry get <project> scores.mentionShare.value
+cnry get <project> scores.mentionCoverage.value
+cnry get <project> scores.citationCoverage.value
+cnry get <project> insights[0].severity
+cnry get <project> latestRun.status
+cnry get <project> --from report scores.citationCoverage.value   # pick a registered source
+cnry get <project> <path> --format json                          # raw JSON output
+```
+
+Resolves a dot/bracket path against the project's overview (default `--from overview`) or any registered source — `report`, `traffic`, `discovery`, etc. Returns the scalar (or sub-tree) at the path so an agent can lift a single number without pulling a 30 KB JSON payload. Use `--from <source> .` to see the available top-level keys for that source.
+
 ### Locations
 
 Projects support multi-region location context for geographically-aware sweeps:
@@ -74,18 +93,21 @@ Run statuses: `queued` → `running` → `completed` / `failed` / `partial`
 ## Citation Data
 
 ```bash
-cnry evidence <project>                        # per-query cited/not-cited
+cnry evidence <project>                        # per-query cited/not-cited + mentioned/not-mentioned
 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 answer visibility from stored answers
-cnry backfill answer-visibility --project <name> --format json
+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 --dry-run
+cnry backfill insights <project>               # recompute insights for completed runs
+cnry backfill insights <project> --since 2026-04-01 --dry-run
 ```
 
-Output shows:
-- `✓ cited` — domain appeared in AI response for that query
-- `✗ not-cited` — domain did not appear
-- Summary: `Cited: X / Y`
+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.
+
+Summary: `Cited: X / Y` and `Mentioned: X / Y` are reported independently — a query can be one, both, or neither.
 
 ## Reports
 
@@ -134,6 +156,8 @@ cnry backfill insights <project> --from-run <id> --to-run <id>  # backfill a ran
 
 ```bash
 cnry query add <project> "phrase one" "phrase two"
+cnry query replace <project> "phrase one" "phrase two"   # set the basket to exactly this list
+cnry query replace <project> "..." --dry-run             # preview adds/removes via /queries/replace-preview
 cnry query remove <project> "phrase"
 cnry query list <project>
 cnry query import <project> queries.txt
@@ -388,6 +412,8 @@ drive Canonry from Claude Code / Codex / a custom agent.
 # One-shot turn — Aero picks its own tools, streams events to stdout.
 cnry agent ask <project> "<prompt>"
 cnry agent ask <project> "<prompt>" --format json      # JSON event stream
+cnry agent ask --all "<prompt>"                        # fan out the same prompt across every project
+cnry agent ask <project> "<prompt>" --trace            # emit tool-execution detail for debugging
 
 # Select a specific provider / model (otherwise auto-detected from config).
 cnry agent ask <project> "<prompt>" --provider anthropic --model claude-opus-4-7
@@ -395,12 +421,22 @@ cnry agent ask <project> "<prompt>" --provider zai      --model glm-5.1
 cnry agent ask <project> "<prompt>" --provider openai
 cnry agent ask <project> "<prompt>" --provider google
 
-# Restrict the tool surface. Default is --scope all (full 13-tool surface:
-# 7 read + 6 write). --scope read-only exposes only the 7 read tools and
-# is what the dashboard bar uses by default so pasted "Copy as CLI"
+# Restrict the tool surface. Default is --scope all (full read+write surface).
+# --scope read-only matches the dashboard bar default so pasted "Copy as CLI"
 # commands can't enable writes the UI turn couldn't perform.
 cnry agent ask <project> "<prompt>" --scope read-only
 cnry agent ask <project> "<prompt>" --scope all
+
+# Session + provider introspection
+cnry agent providers <project>                # list provider keys Aero will pick from + the resolved default
+cnry agent transcript <project>               # dump the rolling transcript for the current session
+cnry agent reset <project>                    # start a fresh session (drops in-memory state, keeps memory)
+cnry agent clear <project>                    # delete the transcript row from the DB
+
+# Durable project notes (the <memory> hydrate block on every new session)
+cnry agent memory list <project>
+cnry agent memory set <project> --key <k> --value <v>     # 2 KB cap per value
+cnry agent memory forget <project> --key <k>
 ```
 
 **Provider detection order** when `--provider` is omitted: `anthropic` →
@@ -409,7 +445,7 @@ cnry agent ask <project> "<prompt>" --scope all
 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `ZAI_API_KEY`).
 
 Conversations **persist per project** — `cnry agent ask` continues the
-same rolling thread each invocation. Reset with `DELETE /api/v1/projects/<name>/agent/transcript`
+same rolling thread each invocation. Reset with `cnry agent reset <project>`
 or via the dashboard bar's reset button.
 
 ### External agents (webhook)

package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md

@@ -36,6 +36,7 @@ Adapters today:
 |---|---|---|
 | `cloud-run` | GCP Cloud Run request logs via Logging API | Any service running on Cloud Run |
 | `wordpress` | The Canonry Traffic Logger WP plugin's REST endpoint | WordPress sites where you control wp-admin |
+| `vercel` | Vercel project logs via the Vercel API | Sites deployed on Vercel (Next.js, SvelteKit, etc.) |
 
 Future adapters slot in by implementing the same contract.
 
@@ -104,6 +105,37 @@ The plugin auto-prunes events older than the retention window (default
 90 days) once per day via WP-Cron. Operators who want a different
 window change it in `Settings → Canonry Traffic Logger`.
 
+## Connecting a Vercel source
+
+The Vercel adapter pulls per-request logs from the Vercel API for a
+specific project + environment. Logs are filtered by canonical domain
+before classification so a multi-tenant Vercel project only surfaces
+hits for the tracked site.
+
+```bash
+# 1. In the Vercel dashboard, create a token with read access to the
+#    target team (Settings → Tokens → Create). Note the team ID
+#    (Settings → General → Team ID) and the Vercel project ID
+#    (Project → Settings → General → Project ID).
+
+# 2. Connect from cnry CLI:
+cnry traffic connect vercel <project> \
+  --project-id prj_xxxxxxxx \
+  --team-id   team_xxxxxxxx \
+  --token     <vercel-token>            # or: --token-file <path>
+
+# 3. (Optional) scope to a specific environment (default: production):
+cnry traffic connect vercel <project> \
+  --project-id prj_xxx --team-id team_xxx --token ... \
+  --environment preview
+```
+
+Credentials live in `~/.canonry/config.yaml` under `vercelTraffic:`,
+mirroring the cloud-run / wordpress blocks. The adapter classifies bot
+crawls + AI-referral arrivals into the same `crawler_events_hourly` /
+`ai_referral_events_hourly` tables — downstream commands
+(`cnry traffic events / sources / status`) are source-agnostic.
+
 ## Syncing data
 
 ```bash