@ainyc/canonry 3.6.4 → 4.1.3

package/README.md

@@ -66,15 +66,15 @@ adapter. The fastest path is the `canonry mcp install` helper:
 
 ```bash
 canonry mcp install --client claude-desktop      # or: cursor
-canonry mcp install --client claude-desktop --read-only  # 33 read tools only
+canonry mcp install --client claude-desktop --read-only  # 45 read API tools only
 canonry mcp config  --client codex               # print snippet for unsupported clients
 ```
 
 `install` merges a `canonry` entry into the client's config, backs up the
 original, and is idempotent. Restart the client after install to pick it up.
 
-The adapter exposes 48 tools — projects, runs, snapshots, insights, health,
-keyword and competitor management, schedules, GSC and GA reads, and the
+The adapter exposes 67 API tools — projects, runs, snapshots, insights, health,
+query and competitor management, schedules, GSC and GA reads, and the
 config-as-code apply path. Auth and configuration are inherited from
 `~/.canonry/config.yaml`. See [`docs/mcp.md`](docs/mcp.md) for the full
 surface and safety rules.
@@ -91,7 +91,7 @@ Canonry's CLI and API are the agent interface. The optional `canonry-mcp` adapte
 ## Features
 
 - **Built-in AI agent (Aero).** Reads state, analyzes regressions, fires write tools (`run_sweep`, `dismiss_insight`, `update_schedule`, etc.), wakes up unprompted after runs. Backed by [`pi-agent-core`](https://github.com/badlogic/pi-mono) — 15+ LLM providers, streaming first.
-- **Agent-first.** Every CLI command supports `--format json`; every UI view has a matching API endpoint. An optional `canonry-mcp` stdio adapter exposes 48 tools to MCP clients like Claude Desktop and Codex.
+- **Agent-first.** Every CLI command supports `--format json`; every UI view has a matching API endpoint. An optional `canonry-mcp` stdio adapter exposes 67 API tools to MCP clients like Claude Desktop and Codex.
 - **Multi-provider.** Query Gemini, OpenAI, Claude, Perplexity, and local LLMs from a single platform.
 - **Content opportunity engine.** Per-query recommendations typed by action (`create` / `expand` / `refresh` / `add-schema`) with auditable score breakdowns, drivers, and demand-source labels. Combines GSC ranking signals with competitor citation evidence so zero-traffic gaps still surface. Available via `canonry content targets / gaps / sources`, the matching API endpoints, and Aero's tool surface.
 - **Config-as-code.** Kubernetes-style YAML files. Version control your monitoring, let agents apply changes declaratively.
@@ -128,7 +128,7 @@ spec:
   canonicalDomain: example.com
   country: US
   language: en
-  keywords:
+  queries:
     - best dental implants near me
     - emergency dentist open now
   competitors:
@@ -156,17 +156,17 @@ Canonry is **agent-first** — every dashboard view has a matching API endpoint
 |--------|----------------|------------|
 | **Projects** | Create, read, update, delete projects; locations; export | `PUT /projects/{name}`, `GET /projects`, `GET /projects/{name}/export` |
 | **Apply** | Config-as-code — declarative multi-project upsert | `POST /apply` |
-| **Keywords / Competitors** | Per-project keyword and competitor management | `POST/DELETE /projects/{name}/keywords`, `/competitors` |
+| **Queries / Competitors** | Per-project query and competitor management | `POST/DELETE /projects/{name}/queries`, `/competitors` |
 | **Runs** | Trigger, list, cancel, and inspect visibility sweeps | `POST /projects/{name}/runs`, `GET /runs`, `POST /runs/{id}/cancel` |
 | **Schedules** | Cron-based recurring sweeps | `GET/PUT /projects/{name}/schedule` |
-| **History / Snapshots** | Timeline + run diffs + per-keyword citation state | `GET /projects/{name}/timeline`, `/snapshots/diff`, `/history` |
+| **History / Snapshots** | Timeline + run diffs + per-query citation state | `GET /projects/{name}/timeline`, `/snapshots/diff`, `/history` |
 | **Intelligence** | DB-backed insights + health snapshots + dismissal | `GET /projects/{name}/insights`, `/health`, `POST /insights/{id}/dismiss` |
 | **Content** | Action-typed content opportunities, gaps, and grounding-source map | `GET /projects/{name}/content/targets`, `/gaps`, `/sources` |
 | **Notifications** | Webhook subscriptions per project (agent or user-defined) | `GET/POST/DELETE /projects/{name}/notifications`, `POST /.../test` |
 | **Analytics** | Aggregated dashboard analytics | `GET /projects/{name}/analytics` |
 | **Google (GSC + OAuth)** | Search Console integration, OAuth flow, property selection, URL inspection | `/google/*`, `/projects/{name}/google/*` |
 | **Google Analytics (GA4)** | Traffic, social referrals, attribution, AI referrals | `/projects/{name}/ga/*` |
-| **Bing Webmaster** | Coverage, URL inspection, keyword stats | `/projects/{name}/bing/*` |
+| **Bing Webmaster** | Coverage, URL inspection, keyword stats (Bing's term) | `/projects/{name}/bing/*` |
 | **WordPress** | Content publishing + site management integration | `/projects/{name}/wordpress/*` |
 | **CDP (ChatGPT browser provider)** | Chrome DevTools Protocol health and session status | `/cdp/*` |
 | **Settings / Auth / Telemetry** | Server config, API key management, opt-in telemetry | `/settings`, `/telemetry` |
@@ -194,10 +194,10 @@ Canonry ships a bundled `canonry-setup` skill that turns Aero (or any Claude-pow
 
 The skill covers the end-to-end answer-engine optimization loop:
 
-- **AEO monitoring.** Running citation sweeps across Gemini, ChatGPT, Claude, and Perplexity via `canonry run` / `canonry evidence` / `canonry status`, including how to interpret per-phrase citation state and regressions.
+- **AEO monitoring.** Running citation sweeps across Gemini, ChatGPT, Claude, and Perplexity via `canonry run` / `canonry evidence` / `canonry status`, including how to interpret per-query citation state and regressions.
 - **Technical SEO audits.** Driving the companion [`@ainyc/aeo-audit`](https://www.npmjs.com/package/@ainyc/aeo-audit) CLI for 14-factor scoring — structured data (JSON-LD), content depth, AI-readable files (`llms.txt`, `llms-full.txt`), E-E-A-T signals, FAQ blocks, definition blocks, H1/alt/meta hygiene.
 - **Indexing diagnosis.** Google Search Console and Bing Webmaster Tools coverage, URL inspection, and one-shot submissions via `canonry google request-indexing` / `canonry bing request-indexing`.
-- **Schema & content execution.** Patterns for injecting LocalBusiness/FAQPage JSON-LD, writing `llms.txt` with service-area detail, trimming keyphrase lists to high-intent queries, and handling WordPress/Elementor specifics (REST API, Application Passwords, Elementor Custom Code).
+- **Schema & content execution.** Patterns for injecting LocalBusiness/FAQPage JSON-LD, writing `llms.txt` with service-area detail, trimming query lists to high-intent queries, and handling WordPress/Elementor specifics (REST API, Application Passwords, Elementor Custom Code).
 - **Diagnose → prioritize → execute → monitor → report workflow.** Opinionated defaults for new sites (0 citations), regressions on established sites, and county-level targeting — with guardrails like "never fabricate citation data" and "back up `~/.canonry/config.yaml` before editing".
 
 See [`skills/canonry-setup/SKILL.md`](skills/canonry-setup/SKILL.md) plus the reference files under [`skills/canonry-setup/references/`](skills/canonry-setup/references/) (`canonry-cli.md`, `aeo-analysis.md`, `indexing.md`, `wordpress-integration.md`) for the full playbook. Aero loads the same material natively, so anything an external agent can do through the skill, Aero can do from the CLI or dashboard command bar.

package/assets/agent-workspace/AGENTS.md

@@ -29,7 +29,7 @@ If the server isn't running, start it with `canonry serve`.
 | `canonry evidence <project>` | Raw citation evidence from sweeps |
 | `canonry insights <project>` | AI-generated insights and findings |
 | `canonry health <project>` | Health snapshot with visibility scores |
-| `canonry timeline <project>` | Per-keyword citation history over time |
+| `canonry timeline <project>` | Per-query citation history over time |
 | `canonry export <project>` | Full project data export |
 
 ### Auditing
@@ -45,8 +45,8 @@ npx @ainyc/aeo-audit <url> --format json
 |---------|---------|
 | `canonry project list` | List all projects |
 | `canonry project create <name> --domain <domain>` | Create a new project |
-| `canonry keyword add <project> <keyword>...` | Add keywords to track |
-| `canonry keyword list <project>` | List tracked keywords |
+| `canonry query add <project> <query>...` | Add queries to track |
+| `canonry query list <project>` | List tracked queries |
 
 ## Workflow Patterns
 
@@ -59,7 +59,7 @@ npx @ainyc/aeo-audit <url> --format json
 
 ### Investigation workflow
 
-1. Identify affected keywords from insights
+1. Identify affected queries from insights
 2. Pull evidence: `canonry evidence <project> --format json`
 3. Check timeline for trends: `canonry timeline <project> --format json`
 4. If structural issues suspected, run audit: `npx @ainyc/aeo-audit <url> --format json`

package/assets/agent-workspace/USER.md

@@ -16,7 +16,7 @@ This file stores client-specific context accumulated over time. Update it as you
 
 ## Watchlist
 
-<!-- Keywords, competitors, or trends to monitor closely -->
+<!-- Queries, competitors, or trends to monitor closely -->
 
 ## Notes
 

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

@@ -20,10 +20,10 @@ When a project has GA4 connected, traffic is a first-class signal alongside cita
 
 ### What to Prioritize
 1. Branded term regressions (losing citations for your own name = urgent)
-2. Competitive keyword losses (competitor gained where you lost)
-3. Informational gap expansion (new uncited keywords appearing)
+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 keywords)
+5. Content optimization (improve cited rate on partially-cited queries)
 
 ### What NOT to Do
 - Don't promise fixes will appear in the next sweep (AEO changes take weeks/months)
@@ -44,7 +44,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 keyword lost its citation and you need to triage and respond |
+| `references/regression-playbook.md` | A query lost its citation and you need to triage and respond |
 | `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 |
 | `references/wordpress-elementor-mcp.md` | Editing WordPress pages with the Elementor MCP integration |

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

@@ -13,13 +13,13 @@ 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 keyword/provider, recent insights, sweep history, audit trail | Canonry DB — query via CLI / API / read tools |
+| **Project state** | Baselines, historical regressions, 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 |
 
 ## How to read project state from canonry
 
-Prefer Aero's read tools (`canonry_project_overview`, `canonry_health_latest`, `canonry_timeline_get`, `canonry_insights_list`, `canonry_keywords_list`, `canonry_competitors_list`, `canonry_run_get`) over shelling out, but the CLI exists for operators too:
+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
@@ -61,6 +61,6 @@ canonry agent memory forget <project> --key <k>
 ## Bad remember candidates
 
 - Anything canonry already tracks (runs, insights, citation rates, schedules). Query it.
-- Turn-local state that's useful for one follow-up and then noise ("user just asked about keyword Y").
+- Turn-local state that's useful for one follow-up and then noise ("user just asked about query Y").
 - Raw evidence or long transcripts — persist a conclusion, not a dump.
 - Unvalidated guesses. Memory isn't a place to think aloud; it's a place to record things you're willing to act on next session.

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

@@ -11,9 +11,9 @@ Trigger: First sweep completes for a new project
 
 Steps:
 1. `canonry evidence <project> --format json` → get initial citation data
-2. Compute baseline: cited rate, provider breakdown, top/bottom keywords
+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 keywords with fixable site issues)
+4. Identify top 3 gaps (uncited queries with fixable site issues)
 5. Generate onboarding report with baseline + action plan
 6. Store baseline metrics in memory
 
@@ -23,7 +23,7 @@ Trigger: Comparison shows decline or webhook fires regression.detected
 
 Steps:
 1. `canonry evidence <project> --format json` → current state
-2. `canonry history <project> --keyword "<keyword>"` → trend for affected keyword
+2. `canonry history <project>` → trend for affected query
 3. Check indexing: `canonry 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`
@@ -46,12 +46,12 @@ Steps:
 
 ## Workflow 4: Content Gap Analysis
 
-Trigger: User asks "why aren't we cited for X?" or multiple uncited keywords detected
+Trigger: User asks "why aren't we cited for X?" or multiple uncited queries detected
 
 Steps:
-1. `canonry evidence <project> --keyword "<keyword>"` → confirm uncited
+1. `canonry evidence <project>` → confirm uncited
 2. Check if a relevant page exists on the domain
-3. If no page: recommend content creation (topic, target keywords)
+3. If no page: recommend content creation (topic, target queries)
 4. If page exists: `npx @ainyc/aeo-audit "<page-url>"` → diagnose why uncited
 5. Check schema completeness, llms.txt coverage, indexing status
 6. Generate prioritized fix list

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

@@ -1,13 +1,13 @@
 ---
 name: regression-playbook
-description: Detection → triage → diagnosis → response for lost citations. Read when investigating why a keyword lost its citation.
+description: Detection → triage → diagnosis → response for lost citations. Read when investigating why a query lost its citation.
 ---
 
 # Regression Playbook
 
 ## Detection
 
-A regression is detected when a citation is lost between consecutive completed runs for the same project. Specifically: a keyword+provider pair that was cited in run N is no longer cited in run N+1.
+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.
 
 ## Triage
 
@@ -16,15 +16,15 @@ Classify the regression by severity:
 | Severity | Criteria |
 |---|---|
 | **Critical** | Branded term lost on any provider |
-| **High** | Top-performing keyword lost on primary provider |
-| **Medium** | Non-branded keyword lost on one provider |
-| **Low** | Keyword lost that was only marginally cited |
+| **High** | Top-performing query lost on primary provider |
+| **Medium** | Non-branded query lost on one provider |
+| **Low** | Query lost that was only marginally cited |
 
 ## Diagnosis
 
 For each regression, check causes in order:
 
-1. **Competitor displacement** — Did a competitor domain appear in the citation for this keyword+provider? Check current run snapshots.
+1. **Competitor displacement** — Did a competitor domain appear in the citation for this query+provider? Check current run snapshots.
 2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status.
 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?
@@ -32,7 +32,7 @@ For each regression, check causes in order:
 
 ## Response
 
-1. Alert the client with specific data (keyword, provider, dates, evidence)
+1. Alert the client with specific data (query, provider, dates, evidence)
 2. Recommend diagnostic steps based on suspected cause
 3. If actionable: generate fix (schema update, content suggestion, indexing resubmission)
 4. Set monitoring flag to track if the regression resolves

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

@@ -15,7 +15,7 @@ canonry report <project> --output dist/aeo.html   # custom path
 canonry 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-keyword × 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 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.
 
 Behaviors worth knowing before narrating numbers from the report:
 - `executiveSummary.citationRate` is always sourced from the latest visibility run (completed **or** partial), so it tracks the scorecard table even when the latest sweep had a flaky provider.
@@ -42,14 +42,14 @@ The hand-rolled templates below are still the right call when the user wants a f
 - <third>
 
 ## Regressions
-| Keyword | Provider | Status | Suspected Cause |
-|---------|----------|--------|-----------------|
-| <keyword> | <provider> | New/Investigating/Resolved | <cause> |
+| Query | Provider | Status | Suspected Cause |
+|-------|----------|--------|-----------------|
+| <query> | <provider> | New/Investigating/Resolved | <cause> |
 
 ## Gains
-| Keyword | Provider | Position | Page |
-|---------|----------|----------|------|
-| <keyword> | <provider> | <N> | <url> |
+| Query | Provider | Position | Page |
+|-------|----------|----------|------|
+| <query> | <provider> | <N> | <url> |
 
 ## Competitor Watch
 - <competitor>: <trend>
@@ -72,7 +72,7 @@ The hand-rolled templates below are still the right call when the user wants a f
 | Metric | Start of Month | End of Month | Change |
 |--------|---------------|--------------|--------|
 | Overall cited rate | <X>% | <Y>% | <Δ>% |
-| Keywords monitored | <N> | <N> | <Δ> |
+| Queries monitored | <N> | <N> | <Δ> |
 | Active regressions | <N> | <N> | <Δ> |
 
 ## Provider Breakdown

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

@@ -12,7 +12,7 @@ You are **Aero** — an AEO analyst. You help operators understand how AI answer
 - **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.
 - **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. Keywords define what gets tracked. Confirm intent before mutating state the operator will notice.
+- **Cautious with writes.** Sweeps cost quota. Schedules shape downstream notifications. Queries define what gets tracked. Confirm intent before mutating state the operator will notice.
 - **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.
 
 ## Voice

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

@@ -38,7 +38,7 @@ Agent-first open-source AEO (Answer Engine Optimization) operating platform. Tra
 
 ## When to Use
 
-- Tracking keyphrase citations across AI providers
+- Tracking query citations across AI providers
 - Running technical SEO audits (14‑factor scoring)
 - Implementing structured data (JSON‑LD)
 - Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools
@@ -57,16 +57,16 @@ 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.
-2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → keyphrase strategy. Branded-term losses are urgent.
+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 `<keyword>` 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 `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.
 
 ## Common Starting Points
 
-- **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent keyphrases. See `references/indexing.md`.
+- **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`.
-- **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county keyphrases until base visibility exists.
+- **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
 

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

@@ -2,12 +2,12 @@
 
 ## What Citation Means
 
-A "cited" keyword 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 response when that query was asked. It does NOT mean:
 - The AI recommended them positively
 - The citation is prominent
 - It will persist on the next sweep
 
-A "not-cited" keyword means the AI answered without mentioning the client at all.
+A "not-cited" query means the AI answered without mentioning the client at all.
 
 ## Reading Evidence Output
 
@@ -18,17 +18,17 @@ A "not-cited" keyword means the AI answered without mentioning the client at all
 ✗ not-cited  emergency plumber near me  ← competitive gap: others cited instead
 ```
 
-### Keyword Categories
+### Query Categories
 
-**Branded/direct keywords** (e.g., "[business name] [city]"):
+**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)
 
-**Competitive keywords** (e.g., "best [service] [city]"):
+**Competitive queries** (e.g., "best [service] [city]"):
 - If not cited: check who IS cited — competitor analysis needed
 - Harder wins; require established authority and trust signals
 
-**Informational/how-to keywords** (e.g., "how to [do X]"):
+**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
 
@@ -40,15 +40,15 @@ Shows citation rate over time across providers. Use to identify:
 - Provider-specific performance differences
 - Impact of content/indexing changes over time
 
-**Key phrase normalization:** When new key phrases are added to a project mid-history, canonry automatically normalizes each time bucket to only include key phrases that existed before that bucket started. This prevents newly-added (typically uncited) key phrases from creating a false drop in the citation rate trend. The chart displays dashed vertical annotation lines at points where key phrases were added (e.g. "+3 kp"), and each bucket's tooltip shows the key phrase count ("kp") 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 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.
 
 ### Gap Analysis (`--feature gaps`)
-Categorizes keywords as cited, gap (competitor cited but you're not), or uncited (nobody cited). Priorities:
-- **Gap keywords** are highest priority — competitors are winning these
-- **Uncited keywords** may need content or may be too broad
+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
 
 ### Source Breakdown (`--feature sources`)
-Shows which source categories AI models cite for your keywords. Helps identify:
+Shows which source categories AI models cite for your queries. Helps identify:
 - Whether competitors dominate specific categories
 - Content format opportunities (FAQ, how-to, comparison pages)
 
@@ -62,10 +62,10 @@ canonry google coverage <project>
 If key pages are "unknown to Google," submit them before drawing conclusions.
 
 ### Step 2: Check if content exists
-Is there a page on the site targeting that keyword? If not, that's the gap — not a canonry or provider issue.
+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 keywords, if others are cited and the client isn't:
+For competitive queries, if others are cited and the client isn't:
 - Do competitors have more specific, dedicated pages?
 - Do they have stronger schema/structured data?
 - Are they more established in the index?
@@ -108,7 +108,7 @@ GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI c
 - Did the model update?
 - Check `canonry google deindexed <project>` for index losses
 
-**Fluctuation** (cited in some runs, not others) — normal for competitive keywords. Track trend over 5+ runs before drawing conclusions. AI answers are non-deterministic.
+**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
 
@@ -117,7 +117,7 @@ GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI c
 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 keywords to pages — which have no corresponding page?
+5. Map uncited queries to pages — which have no corresponding page?
 
 ### Branded terms not cited
 Red flag. Check:

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

@@ -71,7 +71,7 @@ Run statuses: `queued` → `running` → `completed` / `failed` / `partial`
 ## Citation Data
 
 ```bash
-canonry evidence <project>                        # per-keyword cited/not-cited
+canonry evidence <project>                        # per-query cited/not-cited
 canonry evidence <project> --format json          # JSON output
 canonry history <project>                         # audit trail
 canonry export <project> --include-results        # export as YAML
@@ -80,7 +80,7 @@ canonry backfill answer-visibility --project <name> --format json
 ```
 
 Output shows:
-- `✓ cited` — domain appeared in AI response for that keyword
+- `✓ cited` — domain appeared in AI response for that query
 - `✗ not-cited` — domain did not appear
 - Summary: `Cited: X / Y`
 
@@ -127,14 +127,14 @@ canonry backfill insights <project>              # backfill insights for all com
 canonry backfill insights <project> --from-run <id> --to-run <id>  # backfill a range
 ```
 
-## Keywords & Competitors
+## Queries & Competitors
 
 ```bash
-canonry keyword add <project> "phrase one" "phrase two"
-canonry keyword remove <project> "phrase"
-canonry keyword list <project>
-canonry keyword import <project> keywords.txt
-canonry keyword generate <project> --provider gemini --count 10 --save
+canonry query add <project> "phrase one" "phrase two"
+canonry query remove <project> "phrase"
+canonry query list <project>
+canonry query import <project> queries.txt
+canonry query generate <project> --provider gemini --count 10 --save
 
 canonry competitor add <project> competitor1.com competitor2.com
 canonry competitor list <project>