@canonry/canonry 4.104.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Arber X
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,117 @@
+# Canonry <img src="https://raw.githubusercontent.com/Canonry/canonry/main/apps/web/public/favicon-32.png" alt="Canonry canary icon" width="24" />
+
+[![npm version](https://img.shields.io/npm/v/@canonry/canonry)](https://www.npmjs.com/package/@canonry/canonry) [![Node.js >= 22.14](https://img.shields.io/badge/node-%3E%3D22.14-brightgreen)](https://nodejs.org)
+
+**Agent-first AEO operating platform. Open source. Self-hosted.**
+
+- Track citations across Gemini, ChatGPT, Claude, Perplexity, and local LLMs
+- Watch AI engines crawl and refer traffic via [server-log ingestion](skills/canonry/references/server-side-traffic.md) — Cloud Run, Vercel, 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)
+- Track local AEO via [Google Business Profile](skills/canonry/references/google-business-profile.md) — search-term impressions, performance metrics, and hotel lodging + booking-CTA gaps
+- Discover who links to you with [Common Crawl backlinks](skills/canonry/references/canonry-cli.md#backlinks-common-crawl) — follows Common Crawl's rolling monthly hyperlink graph, auto-syncing each new window on a schedule, queried locally with DuckDB
+- Execute fixes via [WordPress](docs/wordpress-setup.md), JSON-LD schema, and indexing submissions
+- Manage many clients declaratively — config-as-code YAML + `cnry apply`
+- Schedule recurring visibility checks, traffic syncs, and Business Profile syncs, with webhook alerts on regressions
+- 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
+
+Every dashboard view has a matching CLI command and API endpoint. The CLI is the surface; the UI consumes the same API your agent does.
+
+![Canonry Dashboard](https://raw.githubusercontent.com/Canonry/canonry/main/docs/images/dashboard.png)
+
+## Run your first AI visibility check in 5 minutes
+
+```bash
+npm install -g @canonry/canonry
+cnry init
+cnry serve
+```
+
+The CLI installs as `cnry` (short form) and `canonry` — the two are interchangeable.
+The legacy package name `@ainyc/canonry` is still published at the same versions for compatibility, but new installs should use `@canonry/canonry`.
+
+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.
+
+If you serve Canonry on `0.0.0.0` or a LAN address, complete first-run dashboard password setup from loopback first, or authenticate with a `cnry_...` bearer key. The unauthenticated setup path is loopback-only by design.
+
+Prefer the terminal?
+
+```bash
+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
+```
+
+## Or set it up with your AI coding agent
+
+Drop this into Claude Code, Codex, or any shell-capable agent. It installs canonry, runs your first sweep, audits your site for AEO readiness, and stops for your sign-off before taking any action on your behalf:
+
+```text
+Set up canonry for me. Canonry is an open-source platform that tracks how AI answer engines (Gemini, ChatGPT, Claude, Perplexity) cite my site.
+
+1. Ask me for: my domain, 3–5 queries I want to track, and which provider I want to start with (gemini / openai / claude / perplexity). Wait for my answers before proceeding.
+2. Run `npm install -g @canonry/canonry`.
+3. Run `cnry init` in this directory. This scaffolds config and installs the canonry skills into `.claude/skills/canonry/`, `.claude/skills/aero/`, `.codex/skills/canonry/`, and `.codex/skills/aero/`. If the skills aren't there afterwards, run `cnry skills install`.
+4. Read the operator playbook at `.claude/skills/canonry/SKILL.md` and follow it end-to-end: create the project with my domain and queries, wire up the provider key I chose, and trigger the first sweep.
+5. Open my browser to the dashboard so I can see the run results.
+6. Switch to the analyst playbook at `.claude/skills/aero/SKILL.md` and run a baseline AEO audit on my behalf. Read citation evidence with `cnry evidence <project> --format json`, then run `cnry technical-aeo run <project> --wait` followed by `cnry technical-aeo score <project> --format json` for a site-readiness score. This crawls every page in my sitemap (not just the homepage), scores the whole site 0–100, and saves the result so it appears in the dashboard and can be re-audited on a schedule.
+7. Summarize what you found: my mention and citation rates per provider, the top 3 queries I'm not yet cited on, and the highest-impact site issues from the audit. Ask me for permission before taking any further action, such as drafting content, submitting URLs for indexing, editing files, or anything else that changes my site.
+```
+
+One-click copy at [canonry.ai](https://canonry.ai).
+
+## If you get stuck
+
+| Problem | Fix |
+|---------|-----|
+| No provider key configured | Open `/setup`, or grab a free [Gemini key](https://aistudio.google.com/apikey), set `GEMINI_API_KEY`, and restart `cnry serve`. |
+| Why did my first audit fail? | Run `cnry doctor`, then reopen `/setup`; it checks provider keys and setup blockers before the first sweep. |
+| 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 | Setup wizard auto-generates them; expand the basket later with `cnry discover run <project> --icp "..."` — see the [discovery methodology](skills/aero/references/aeo-discovery.md). |
+| `npm install` fails on `node-gyp` | Install build tools for `better-sqlite3` ([guide](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md)). |
+
+## Provider keys
+
+| Provider | Key source | Env var |
+|----------|-----------|---------|
+| Gemini | [aistudio.google.com](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` |
+| OpenAI | [platform.openai.com](https://platform.openai.com/api-keys) | `OPENAI_API_KEY` |
+| Claude | [console.anthropic.com](https://console.anthropic.com/settings/keys) | `ANTHROPIC_API_KEY` |
+| 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 `cnry init`, in the dashboard `/settings`, or as env vars.
+
+## Documentation
+
+| | |
+|---|---|
+| **Architecture & data model** | [docs/architecture.md](docs/architecture.md) · [docs/data-model.md](docs/data-model.md) |
+| **Aero — built-in agent** | [skills/aero/SKILL.md](skills/aero/SKILL.md) |
+| **MCP — Claude Desktop / Cursor / Codex** | [docs/mcp.md](docs/mcp.md) |
+| **Integrations** | [GSC](docs/google-search-console-setup.md) · [GA4](docs/google-analytics-setup.md) · [Bing](docs/bing-webmaster-setup.md) · [Google Business Profile](skills/canonry/references/google-business-profile.md) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloud Run + Vercel + 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 | `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) |
+
+## Requirements
+
+Node.js ≥ 22.14.0. At least one provider API key.
+
+## Contributing
+
+```bash
+git clone https://github.com/Canonry/canonry.git && cd canonry
+pnpm install && pnpm run typecheck && pnpm run test && pnpm run lint
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[FSL-1.1-ALv2](./LICENSE). Free to use, modify, and self-host. Each version converts to Apache 2.0 after two years.

package/assets/agent-workspace/AGENTS.md

@@ -0,0 +1,88 @@
+# Aero Agent -- Operational Guidelines
+
+## Data Access
+
+All data access goes through the canonry CLI. Never read the SQLite database directly.
+
+```bash
+# Always use --format json for structured output
+canonry <command> --format json
+```
+
+The canonry server must be running for most commands. Verify by hitting the health endpoint (`GET /health`) or by listing projects:
+
+```bash
+canonry project list --format json
+```
+
+If the server isn't running, start it with `canonry serve`.
+
+## Key Commands
+
+### Monitoring
+
+| Command | Purpose |
+|---------|---------|
+| `canonry run <project>` | Trigger a visibility sweep across all configured providers |
+| `canonry run <project> --provider gemini` | Single-provider sweep |
+| `canonry status <project>` | Current project status and latest run summary |
+| `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-query citation history over time |
+| `canonry export <project>` | Full project data export |
+
+### Auditing
+
+```bash
+# Run a technical AEO audit on a URL
+npx @ainyc/aeo-audit <url> --format json
+```
+
+### Project Management
+
+| Command | Purpose |
+|---------|---------|
+| `canonry project list` | List all projects |
+| `canonry project create <name> --domain <domain>` | Create a new project |
+| `canonry query add <project> <query>...` | Add queries to track |
+| `canonry query list <project>` | List tracked queries |
+
+## Workflow Patterns
+
+### Daily monitoring sweep
+
+1. Check project status: `canonry status <project> --format json`
+2. Run sweep if stale: `canonry run <project>`
+3. Review insights: `canonry insights <project> --format json`
+4. Escalate critical/high severity findings to the operator
+
+### Investigation workflow
+
+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`
+5. Compile findings with evidence and recommended actions
+
+## Quota Awareness
+
+Provider APIs have rate limits. Follow these guidelines:
+
+- Don't run full sweeps more than necessary. Check `canonry status` first to see when the last run completed.
+- Use `--provider <name>` for targeted single-provider checks when investigating a specific engine.
+- If a run returns `partial` status, some providers failed -- check the run details before retrying.
+- Space out consecutive sweeps. Back-to-back runs waste quota without new data.
+
+## Skills
+
+Reference skills are available in `skills/` for domain-specific guidance:
+
+- `skills/canonry/` -- Canonry operator playbook
+
+## Error Handling
+
+- Exit code `0` = success, `1` = user error, `2` = system error.
+- On exit code `2` (system error), check server status and retry once before escalating.
+- On exit code `1` (user error), review the error message -- don't retry the same command.
+- Parse stderr for structured error JSON: `{ "error": { "code": "...", "message": "..." } }`.

package/assets/agent-workspace/USER.md

@@ -0,0 +1,23 @@
+# Client Context
+
+This file stores client-specific context accumulated over time. Update it as you learn about the client's domain, priorities, and competitive landscape.
+
+## Client Info
+
+<!-- Domain, industry, target audience, key products/services -->
+
+## Projects
+
+<!-- Active canonry projects and their purpose -->
+
+## Key Findings
+
+<!-- Important discoveries from sweeps and audits, with dates -->
+
+## Watchlist
+
+<!-- Queries, competitors, or trends to monitor closely -->
+
+## Notes
+
+<!-- Any other relevant context -->

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

@@ -0,0 +1,72 @@
+---
+name: aero
+slug: aero
+description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis with persistent memory and proactive regression response.
+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**, **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.
+
+**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 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
+
+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 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 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:
+- Still cost provider API quota (same wire call)
+- Write a snapshot you can inspect via `cnry runs get <id>`
+- Are EXCLUDED from dashboard, analytics, intelligence, insights, and notifications
+- Won't wake you up again via the post-run hook (no recursive analysis loops)
+
+Use probes whenever the run is for **your** investigation, not for the user's metrics. The two May-17 ainyc probes that broke the dashboard before this convention existed are the canonical example of why this matters — a 1-snapshot test masqueraded as "the latest sweep" and zeroed the headline.
+
+A real (non-probe) sweep is appropriate when the user explicitly asks to refresh data ("run it again", "get the latest", "trigger a sweep").
+
+### How to Communicate
+- Data first: show the numbers before the interpretation
+- 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
+
+Detailed playbooks live alongside this file. Read them on demand when the task matches:
+
+| 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 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 |
+| `references/wordpress-elementor-mcp.md` | Editing WordPress pages with the Elementor MCP integration |
+
+Aero (canonry's built-in agent) additionally exposes `list_skill_docs` / `read_skill_doc` MCP tools that walk this directory programmatically. External agents (Claude Code, Codex) should `Read` the files directly.

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

@@ -0,0 +1,161 @@
+---
+name: aeo-discovery
+description: How to operate the tracked-basket discovery pipeline. Read when an operator asks to expand a project's basket, audit its competitive surface, or you wake unprompted on `aeo-discover-probe.completed`.
+---
+
+# 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. 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 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 (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`:
+
+- **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
+
+- Operator says "expand my tracked queries", "audit my basket", "what am I missing", "find competitors I should track".
+- Recurring `wasted-surface` shows up in regression analysis — the project keeps losing on queries adjacent to its tracked basket.
+- A new ICP is being onboarded and the operator only has a domain + tagline, no curated query list.
+
+## Triggering a session
+
+The operator runs:
+
+```bash
+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`.
+
+ICP fallback: if the request omits `icpDescription`, the route uses `projects.icp_description` if set. Surface a clear "needs an ICP" prompt if neither is available.
+
+## Cost + budget
+
+Per session: ~$1 at the default probe budget (100 queries × 1 Gemini grounded call each, plus a single batched embed call for ~$0.0002). Hard cap: 500 probes per session, enforced both client-side (Zod) and server-side. Recommend the default (100) unless the operator has a specific reason.
+
+## Reading the result
+
+`canonry_discover_session_get` returns:
+
+- 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 `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
+
+Once a session is `completed`, preview first unless the operator has already approved the write:
+
+```bash
+cnry discover promote preview <project> <session-id>
+```
+
+Or the MCP equivalent: `canonry_discover_promote_preview` with `{ project, sessionId }`.
+
+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 (≥ 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
+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:
+
+```json
+{ "project": "<project>", "sessionId": "<session-id>" }
+```
+
+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"], "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 + 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.
+
+## When you wake on `aeo-discover-probe.completed`
+
+The follow-up payload `RunCoordinator` queues for you includes:
+
+```
+[system] Discovery run <runId> completed for project <name> (session <sessionId>).
+Buckets — cited:<n>, wasted-surface:<n>, aspirational:<n> (<probeCount> probes; seed provider: gemini).
+Top recurring competitor domains: <domain1>(<hits>), <domain2>(<hits>), …
+```
+
+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 `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.
+
+Keep it tight. The operator wakes to a short, decision-ready summary, not a full report.
+
+## What discovery does NOT do (yet)
+
+- **No multi-provider amplification.** v1 probes Gemini only. v2 will probe across Gemini + ChatGPT + Claude in one session (the schema is already shaped for it — `discovery_probes` has no `UNIQUE(session_id, query)` exactly because of this).
+- **No re-run drift.** Each session is independent. Comparing sessions over time is on the PR 4 / PR 5 roadmap.
+
+## 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 `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.
+
+  **Diagnostic signal:** `seedCountRaw / seedCount > 10:1` (e.g. 40 raw → 1 selected).
+
+  **Remediation:** break the ICP into 3-5 distinct purchase-intent angles and run one session per angle via `--icp-angle`:
+
+  ```bash
+  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" \
+    --icp-angle "design-forward boutique hotels for creative professionals" \
+    --wait
+  ```
+
+  Each angle generates its own 40-seed cluster independently, so aggregate coverage grows while per-session dedup stays clean. The `--wait` output prints a combined summary with per-session session IDs and a `promote` command for each. Promote the sessions individually after reviewing previews.
+
+## Memory hygiene
+
+After a discovery session, store a one-liner in `agent_memory` if the operator validates a non-obvious call. Examples:
+
+- `discovery:icp-style` — phrasing they responded well to
+- `discovery:competitor-watchlist` — domains they explicitly accepted/rejected from the suggested list
+
+Skip routine results — only memory-worthy material is what would help a future session avoid re-asking the same question.

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

@@ -0,0 +1,66 @@
+---
+name: memory-patterns
+description: When to remember vs. re-query — project state lives in canonry, only durable user-scoped facts go in Aero memory. Read when unsure whether to call canonry_memory_set or look up.
+---
+
+# Memory Patterns
+
+Canonry is the source of truth for project state. Do **not** maintain a parallel copy of project facts in Aero memory — it will drift from the DB and mislead the next session.
+
+Aero ships with a built-in durable notes store — the `canonry_memory_set`, `canonry_memory_forget`, and `canonry_memory_list` tools — backed by the `agent_memory` table. The N most-recently-updated notes are injected into the system prompt at every session start, so you usually see relevant memory without calling `canonry_memory_list`.
+
+## What belongs where
+
+| Scope | Examples | Home |
+|---|---|---|
+| **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 |
+
+## 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_queries_list`, `canonry_competitors_list`, `canonry_run_get`) over shelling out, but the CLI exists for operators too:
+
+```bash
+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.
+
+## Regenerate, don't remember
+
+Derived interpretations (trend summaries, correlations between events) are cheap to recompute from the underlying DB rows. Prefer running the analysis again on fresh data over recalling what you concluded last session — conclusions age, the data doesn't.
+
+## Using `canonry_memory_set` / `canonry_memory_forget` / `canonry_memory_list`
+
+- `canonry_memory_set({ key, value })` — upsert a project-scoped note. Capped at 2 KB per value. Same key replaces the prior value, so use stable keys (e.g. `operator-pref.reporting-tone`, not `note-2026-04-17`).
+- `canonry_memory_forget({ key })` — remove a single note. Returns `status: missing` when the key never existed (non-fatal).
+- `canonry_memory_list()` — read notes newest-first. Usually unnecessary — the top 20 are already in the system prompt under `<memory>`. Reach for it when you need older context or the full value of a note that's been summarized.
+
+**Reserved prefix.** Keys starting with `compaction:` are reserved for LLM-summarized transcript slices. `canonry_memory_set` and `canonry_memory_forget` both reject them. Compaction notes are pruned automatically — you can list them but never write or delete them by hand.
+
+**CLI parity.** Operators can manage memory without talking to you:
+
+```bash
+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
+
+- Operator-confirmed facts canonry can't observe (team names, migration plans, vendor lock-in, upcoming content bets).
+- Stable preferences the operator has validated at least once ("report weekly", "prefer Claude over GPT for prose", "never auto-dismiss insights").
+- Non-obvious decisions made mid-investigation that a future turn would re-derive wastefully ("confirmed competitor X is out of scope").
+
+## 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 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.