@ainyc/canonry 4.27.2 → 4.28.0

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.
 

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

@@ -233,10 +233,12 @@ canonry discover run <project> --icp "..." --max-probes 100         # per-sessio
 
 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