@ainyc/canonry 4.27.2 → 4.29.0

package/README.md

@@ -5,7 +5,7 @@
 **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-setup/references/server-side-traffic.md) — Cloud Run today, more sources coming
+- Watch AI engines crawl and refer traffic via [server-log ingestion](skills/canonry-setup/references/server-side-traffic.md) — Cloud Run logs and the WordPress Traffic Logger plugin today
 - Diagnose against real traffic with built-in [GSC](docs/google-search-console-setup.md), [GA4](docs/google-analytics-setup.md), and [Bing Webmaster](docs/bing-webmaster-setup.md)
 - Execute fixes via [WordPress](docs/wordpress-setup.md), JSON-LD schema, and indexing submissions
 - Manage many clients declaratively — config-as-code YAML + `canonry apply`
@@ -66,7 +66,7 @@ Configure during `canonry init`, in the dashboard `/settings`, or as env vars.
 | **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) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloud Run logs)](skills/canonry-setup/references/server-side-traffic.md) |
+| **Integrations** | [GSC](docs/google-search-console-setup.md) · [GA4](docs/google-analytics-setup.md) · [Bing](docs/bing-webmaster-setup.md) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloud Run + WordPress logs)](skills/canonry-setup/references/server-side-traffic.md) |
 | **Deployment** — Docker, Railway, Render, systemd, Tailscale | [docs/deployment.md](docs/deployment.md) |
 | **API** — 118+ endpoints | `GET /api/v1/openapi.json` (no auth) |
 | **Skills bundle** for Claude Code / Codex | `canonry skills install` ([details](skills/canonry-setup/SKILL.md)) |

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

@@ -45,6 +45,7 @@ Detailed playbooks live alongside this file. Read them on demand when the task m
 |---|---|
 | `references/orchestration.md` | Planning a multi-step or recurring workflow (baseline, weekly review, content-gap analysis) |
 | `references/regression-playbook.md` | A query lost its citation and you need to triage and respond |
+| `references/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 |

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

@@ -45,9 +45,53 @@ Per session: ~$1 at the default probe budget (100 queries × 1 Gemini grounded c
 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.
-- **New competitor domains** in `competitorMap` that aren't already in the project's tracked competitor list → suggest adding via `canonry competitor add <project> <domain>`. PR 2's `canonry discover promote` will automate this.
+- **Recurring new competitor domains** in `competitorMap` that aren't already in the project's tracked competitor list → `canonry discover promote` adopts domains with at least 2 hits automatically alongside the queries; or add them à la carte with `canonry competitor add <project> <domain>`.
 - **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
+canonry 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 not already tracked. The promote path only auto-adopts domains with at least 2 hits.
+
+Promote with one of these paths:
+
+```bash
+canonry discover promote <project> <session-id>                          # cited + aspirational buckets + recurring competitor domains
+canonry discover promote <project> <session-id> --bucket aspirational    # scope to a bucket subset (repeatable / comma-separated)
+canonry discover promote <project> <session-id> --bucket wasted-surface  # explicitly track off-ICP competitor gaps
+canonry discover promote <project> <session-id> --no-competitors         # queries only, skip the competitor merge
+```
+
+Or the MCP equivalent:
+
+```json
+{ "project": "<project>", "sessionId": "<session-id>" }
+```
+
+That default request promotes `cited` + `aspirational` queries and recurring competitors. For scoped writes, pass `request`:
+
+```json
+{ "project": "<project>", "sessionId": "<session-id>", "request": { "buckets": ["aspirational"], "includeCompetitors": false } }
+```
+
+- **Default is cited + aspirational.** `wasted-surface` queries are off-ICP competitor gaps; promote them only when the operator explicitly wants those tracked in the weekly basket.
+- **Competitor promotion requires recurrence.** Default competitor merge ignores one-off domains and adopts only domains with at least 2 hits.
+- **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:
@@ -62,14 +106,15 @@ 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 new competitor domains worth tracking.
-4. A single recommended next step. Examples: "add competitor.com to the tracked list", "the wasted-surface set warrants a content plan around X", "the aspirational set is greenfield — pick the 3 with highest commercial intent and write content".
+3. The top 1-2 recurring new competitor domains worth tracking, ignoring one-hit domains unless the operator asks for the full long tail.
+4. A single recommended next step. Examples: "preview and promote cited + aspirational findings (`canonry discover promote preview`, then `canonry discover promote`)", "the wasted-surface set warrants a content plan around X before tracking", "the aspirational set is greenfield — pick the 3 with highest commercial intent and write content".
+
+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 promotion.** PR 2 ships `canonry discover promote` which adopts queries into the project's tracked basket with `provenance='discovery:<sessionId>'`. Until then, the operator merges manually via `canonry query add` / `canonry competitor add`.
 - **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.
 
@@ -78,6 +123,22 @@ Keep it tight. The operator wakes to a short, decision-ready summary, not a full
 - **Gemini not configured** → orchestrator throws early; `runs.status='failed'` with `Gemini provider is not configured.` Surface as "configure Gemini before running discovery" — link to `canonry init` or `~/.canonry/config.yaml`.
 - **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
+  canonry 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
 

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

@@ -88,7 +88,7 @@ GA4 is a first-class signal alongside citation tracking. Connect once with `cano
 | `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 today; WordPress / others later) for AI Visibility — Server-Side. Connect, sync, manage sources, troubleshoot. |
+| `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. |
 
 ---
 

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

@@ -230,13 +230,16 @@ canonry google request-indexing <project> --all-unindexed # push all unknown pag
 canonry discover run <project> --icp "..." --wait --format json    # full pipeline: seed → embed → cluster → probe → bucket
 canonry discover run <project> --icp "..." --dedup-threshold 0.85  # tune cosine threshold (default 0.85)
 canonry discover run <project> --icp "..." --max-probes 100         # per-session probe budget (default 100, hard cap 500)
+canonry discover run <project> --icp-angle "angle 1" --icp-angle "angle 2" --wait  # multi-angle: one session per ICP angle, useful for hyperlocal/niche businesses
 
 canonry discover list <project>                                     # newest-first session list
 canonry discover show <project> <session-id>                        # per-query probe rows + buckets
-canonry discover promote preview <project> <session-id>             # preview the basket PR 2 will write (read-only)
+canonry discover promote preview <project> <session-id>             # preview bucketed candidates + recurring suggested competitors (read-only)
+canonry discover promote <project> <session-id>                     # adopt cited + aspirational queries + recurring competitors
+canonry discover promote <project> <session-id> --bucket aspirational --no-competitors   # scope to a bucket subset / skip competitor merge
 ```
 
-Discovery requires Gemini configured (API key today; Vertex-mode embeddings are deferred). The pipeline writes a `discovery_sessions` row, a `runs` row (kind `aeo-discover-probe`), and one `discovery.basket-divergence` insight when the session completes. Aero wakes unprompted with the bucket-count payload so the operator can act without polling.
+Discovery requires Gemini configured (API key today; Vertex-mode embeddings are deferred). The pipeline writes a `discovery_sessions` row, a `runs` row (kind `aeo-discover-probe`), and one `discovery.basket-divergence` insight when the session completes. Aero wakes unprompted with the bucket-count payload so the operator can act without polling. `discover promote` defaults to cited + aspirational queries and recurring competitor domains; include `--bucket wasted-surface` explicitly for off-ICP competitor gaps. Promotion is add-only and idempotent — queries/domains already tracked are reported as skipped, never inserted twice — and only works on `completed` sessions; promoted rows carry `provenance="discovery:<sessionId>"`.
 
 ## Bing Webmaster Tools