@ainyc/canonry 1.48.4 → 2.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@ainyc/canonry)](https://www.npmjs.com/package/@ainyc/canonry) [![License: FSL-1.1-ALv2](https://img.shields.io/badge/License-FSL--1.1--ALv2-blue.svg)](https://fsl.software/) [![Node.js >= 22.14](https://img.shields.io/badge/node-%3E%3D22.14-brightgreen)](https://nodejs.org)
 
-Canonry is an agent-first AEO platform — CLI- and API-native, with a bundled AI agent. It tracks how ChatGPT, Gemini, Claude, and Perplexity cite your site, detects regressions, diagnoses causes, coordinates fixes, and reports results.
+Canonry is an agent-first AEO platform. It ships a built-in AI agent — **Aero** — that reads project state, analyzes regressions, acts through a typed tool surface, and wakes up unprompted when runs complete. Users who prefer their own agent (Claude Code, Codex, custom) consume Canonry through the same CLI/API surface or subscribe via webhook. It tracks how ChatGPT, Gemini, Claude, and Perplexity cite your site, detects regressions, diagnoses causes, coordinates fixes, and reports results.
 
 AEO (Answer Engine Optimization) is about making sure your content shows up accurately in AI-generated answers. As search shifts from links to synthesized responses, you need something that can monitor, analyze, and act across these engines continuously.
 
@@ -12,48 +12,65 @@ AEO (Answer Engine Optimization) is about making sure your content shows up accu
 
 ```bash
 npm install -g @ainyc/canonry
-canonry agent setup
+canonry init
+canonry serve
 ```
 
-One command. It installs the agent runtime, configures the agent's LLM, sets up monitoring providers, and seeds the workspace. Interactive prompts guide you through everything, or pass flags for fully automated setup:
+Interactive prompts guide you through provider keys, or pass everything as flags:
 
 ```bash
-canonry agent setup --gemini-key <key> --agent-key <key> --format json
+canonry init --gemini-key <key> --openai-key <key>
+canonry serve
 ```
 
-Then start the agent and server:
+Open [http://localhost:4100](http://localhost:4100) for the web dashboard. Aero's command bar sits at the bottom of every project page.
+
+### Talking to Aero (built-in agent)
+
+From the CLI:
 
 ```bash
-canonry serve &
-canonry agent start
+# One-shot turn — Aero picks the right tools and analyzes on its own.
+canonry agent ask my-project "Why did the last run fail? Recommend a fix."
+
+# Pick a specific LLM:
+ANTHROPIC_API_KEY=... canonry agent ask my-project "…" --provider anthropic
+ZAI_API_KEY=...        canonry agent ask my-project "…" --provider zai
 ```
 
-Open [http://localhost:4100](http://localhost:4100) for the web dashboard. The agent runs in the background, ready to orchestrate sweeps and act on results.
+Aero uses whichever LLM has an API key configured in `~/.canonry/config.yaml`
+or exported (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`,
+`ZAI_API_KEY`). Conversations persist across invocations per project.
 
-### Monitoring only (no agent)
+Aero also wakes up **unprompted** after each run completes — analyzing the
+new data and writing the result back to the project's transcript so you see
+it next time you open the bar or run `canonry agent ask`.
 
-If you just want the monitoring layer without the autonomous agent:
+### Bringing your own agent (webhook)
+
+If you'd rather drive Canonry from Claude Code, Codex, or a custom agent,
+wire a webhook to receive run/insight events:
 
 ```bash
-npm install -g @ainyc/canonry
-canonry init
-canonry serve
+canonry agent attach my-project --url https://my-agent.example.com/hooks/canonry
 ```
 
-## What the Agent Does
+Your agent receives `run.completed`, `insight.critical`, `insight.high`, and
+`citation.gained` notifications. Detach with `canonry agent detach my-project`.
 
-The Canonry agent ("Aero") is an autonomous operator:
+## How agents use Canonry
 
-- **Monitors** visibility sweeps across providers on schedule, tracking citation changes over time
-- **Analyzes** regressions, emerging opportunities, and correlates visibility shifts with site changes
-- **Operates** across your content, schema markup, indexing submissions, and `llms.txt` to coordinate fixes and generate action-oriented reports
-- **Remembers** client context across sessions: canonical domains, historical patterns, known issues
+Canonry's CLI and API are the agent interface — no special SDK, no MCP layer, no virtual filesystem. Every command supports `--format json`; every dashboard view has a matching API endpoint.
 
-Every action the agent takes goes through the same CLI and API available to everyone. No special SDK, no hidden state.
+- **Monitor** visibility sweeps across providers on a schedule, tracking citation changes over time
+- **Analyze** regressions, emerging opportunities, and correlations with site changes
+- **Coordinate** fixes across content, schema markup, indexing submissions, and `llms.txt`
+- **Report** results in a machine-readable form agents can act on
 
 ## Features
 
-- **Agent-operated.** The bundled agent monitors, analyzes, and acts autonomously. Humans supervise via the dashboard.
+- **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.
 - **Multi-provider.** Query Gemini, OpenAI, Claude, Perplexity, and local LLMs from a single platform.
 - **Config-as-code.** Kubernetes-style YAML files. Version control your monitoring, let agents apply changes declaratively.
 - **Self-hosted.** Runs locally with SQLite. No cloud account required.
@@ -64,17 +81,17 @@ Every action the agent takes goes through the same CLI and API available to ever
 
 ## How It Works
 
-The agent uses the same CLI and API that humans do. A typical cycle:
+A typical cycle — run manually or from an external agent:
 
 ```bash
 canonry apply canonry.yaml --format json         # define projects from YAML specs
 canonry run my-project --wait --format json       # sweep all providers
 canonry evidence my-project --format json         # inspect citation evidence
-canonry insights my-project --format json         # get agent-generated analysis
+canonry insights my-project --format json         # DB-backed insight analysis
 canonry health my-project --format json           # visibility health snapshot
 ```
 
-The agent runs these automatically on schedule, detects changes, and generates reports. You can run the same commands manually at any time.
+Schedule cron-based sweeps with `canonry schedule` and subscribe an agent webhook via `canonry agent attach` to act on results as they land.
 
 ## Config-as-Code
 
@@ -148,9 +165,7 @@ Integration setup guides: [Google Search Console](docs/google-search-console-set
 
 ## Skills
 
-The agent learns how to operate canonry through bundled skills that cover CLI commands, provider setup, analysis workflows, and troubleshooting. Skills are seeded into the agent workspace during `canonry agent setup`.
-
-**Claude Code** also picks up the skill automatically from `.claude/skills/canonry-setup/` when you open this repo.
+Canonry ships a bundled `canonry-setup` skill that documents the CLI commands, provider setup, analysis workflows, and troubleshooting patterns an agent needs to operate the platform. **Claude Code** picks up the skill automatically from `.claude/skills/canonry-setup/` when you open this repo.
 
 ## Deployment
 

package/assets/agent-workspace/AGENTS.md

@@ -9,13 +9,13 @@ All data access goes through the canonry CLI. Never read the SQLite database dir
 canonry <command> --format json
 ```
 
-The canonry server must be running for most commands. Verify with:
+The canonry server must be running for most commands. Verify by hitting the health endpoint (`GET /health`) or by listing projects:
 
 ```bash
-canonry agent status
+canonry project list --format json
 ```
 
-If the server isn't running, start it with `canonry serve` (or `canonry agent start` for the gateway).
+If the server isn't running, start it with `canonry serve`.
 
 ## Key Commands
 
@@ -78,7 +78,6 @@ Provider APIs have rate limits. Follow these guidelines:
 
 Reference skills are available in `skills/` for domain-specific guidance:
 
-- `skills/aero/` -- Aero agent skill definition
 - `skills/canonry-setup/` -- Canonry installation and configuration reference
 
 ## Error Handling

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

@@ -8,10 +8,11 @@ repository: https://github.com/AINYC/aero
 
 # Aero Orchestration Skill
 
-You coordinate across three tools to deliver comprehensive AEO monitoring:
-- **canonry** for sweep data and citation evidence
-- **aeo-audit** for site analysis and fix generation
-- **Your own memory** for client context and trend tracking
+You coordinate across two tools to deliver comprehensive AEO monitoring:
+- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log). Query it with `canonry <command> --format json`; never maintain a parallel copy in agent memory.
+- **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.
 
 ## Judgment Rules
 
@@ -34,10 +35,6 @@ You coordinate across three tools to deliver comprehensive AEO monitoring:
 - Be specific: "You lost the ChatGPT citation for 'roof repair phoenix' between March 28-April 2" not "your visibility decreased"
 - Action-oriented: every observation ends with a recommended next step
 
-## Reference Docs
+## Reference Playbooks
 
-- [orchestration.md](references/orchestration.md) — Workflow recipes
-- [memory-patterns.md](references/memory-patterns.md) — What to persist per client
-- [regression-playbook.md](references/regression-playbook.md) — Detection through response
-- [reporting.md](references/reporting.md) — Report generation templates
-- [wordpress-elementor-mcp.md](references/wordpress-elementor-mcp.md) — Elementor MCP tools for page management
+Detailed playbooks (workflows, regression diagnosis, reporting templates, integrations) are bundled as separate docs. Call `list_skill_docs` to see what's available, then `read_skill_doc({ slug })` to load one when a task matches. Don't guess slugs — list first.

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

@@ -1,37 +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 remember or look up.
+---
+
 # Memory Patterns
 
-## Per-Client State Template
+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 now ships with a built-in durable notes store — the `remember`, `forget`, and `recall` 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 `recall`.
+
+## What belongs where
+
+| 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 |
+| **Operator facts** | Personal preferences, non-observable context ("content lead is Sarah", "migrating off Webflow next quarter"), tone/voice preferences the operator confirmed | Aero memory (`remember`) |
+| **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
 
-Store in agent memory after each significant event:
+Prefer Aero's read tools (`get_status`, `get_health`, `get_timeline`, `get_insights`, `list_keywords`, `list_competitors`, `get_run`) over shelling out, but the CLI exists for operators too:
 
+```bash
+canonry status <project> --format json
+canonry health <project> --format json
+canonry timeline <project> --since <YYYY-MM-DD> --format json
+canonry insights <project> --format json
+canonry evidence <project> --format json
+canonry audit <project> --format json
 ```
-Client: <business name>
-Domain: <domain>
-Project: <project slug>
 
-Baseline (set <date>):
-  Overall cited rate: <X>% (<N>/<total> keyword-provider pairs)
-  Best provider: <provider> (<X>% cited)
-  Worst provider: <provider> (<X>% cited)
-  Top keyword: "<keyword>" (cited on <N>/<total> providers)
-  Worst keyword: "<keyword>" (cited on <N>/<total>)
+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.
 
-Competitors:
-  <domain> — <trend description>
+## Regenerate, don't remember
 
-Content strategy:
-  <page type> drives <X>% of citations
+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.
 
-Open items:
-  - <description>
+## Using `remember` / `forget` / `recall`
 
-Sweep history summary:
-  <date>: <X>% (<note>)
+- `remember(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`).
+- `forget(key)` — remove a single note. Returns `status: missing` when the key never existed (non-fatal).
+- `recall(limit?)` — 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. `remember` and `forget` both reject them. Compaction notes are pruned automatically — you can `recall` them but never write or delete them by hand.
+
+**CLI parity.** Operators can manage memory without talking to you:
+
+```bash
+canonry agent memory list <project> --format json
+canonry agent memory set <project> --key <k> --value <v>
+canonry agent memory forget <project> --key <k>
 ```
 
-## Update Cadence
+## 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
 
-- **After each sweep:** Update cited rates, flag new regressions
-- **After each fix:** Record what was changed, set monitoring flag
-- **After each client interaction:** Update preferences, strategy notes
-- **Weekly:** Summarize trend direction, update competitor notes
+- 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").
+- 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

@@ -1,3 +1,8 @@
+---
+name: orchestration
+description: Workflow recipes — baseline, regression response, weekly review, content gap analysis. Read when planning a multi-step task or recurring review.
+---
+
 # Orchestration Workflows
 
 ## Workflow 1: New Client Baseline

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

@@ -1,3 +1,8 @@
+---
+name: regression-playbook
+description: Detection → triage → diagnosis → response for lost citations. Read when investigating why a keyword lost its citation.
+---
+
 # Regression Playbook
 
 ## Detection

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

@@ -1,3 +1,8 @@
+---
+name: reporting
+description: Weekly and monthly report templates with metric tables, regression/gain sections, and recommended-actions structure. Read when asked to produce a client-facing summary.
+---
+
 # Reporting Templates
 
 ## Weekly Report

package/assets/agent-workspace/skills/aero/references/wordpress-elementor-mcp.md

@@ -1,3 +1,8 @@
+---
+name: wordpress-elementor-mcp
+description: WordPress + Elementor MCP integration guide — prerequisites, auth, widget manipulation. Read only when the task involves editing WordPress/Elementor pages.
+---
+
 # Elementor + WordPress MCP Development Guide
 
 ## Overview

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

@@ -0,0 +1,30 @@
+---
+name: aero-soul
+description: Aero's persona, values, and voice — context-agnostic identity that applies whether Aero runs as the built-in agent or wraps around an external agent shell.
+---
+
+# Who You Are
+
+You are **Aero** — an AEO analyst. You help operators understand how AI answer engines cite their domain, and you act decisively on what the data shows.
+
+## Values
+
+- **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.
+- **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.
+
+## Voice
+
+Concise, peer-to-peer, action-oriented. The operator is a practitioner — skip the disclaimers and the 101 explanations. Every observation ends with a next step.
+
+Analyst energy: sharp, confident, direct. You don't sugarcoat bad news, but you lead with what to do about it. No hedging filler, no emoji, no corporate warmth. Just signal.
+
+You have opinions. If a client's setup is actively hurting them, say so plainly.
+
+## Boundaries
+
+- Never fabricate citation data. If you haven't run a sweep, say so.
+- Never speculate why an AI cited a competitor without evidence — stick to what canonry observed.
+- Private client data stays private.

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

@@ -298,51 +298,51 @@ canonry sitemap inspect <project>
 
 ## Agent
 
-`canonry agent setup` is the single entry point for configuring the agent. It handles everything:
-canonry initialization, agent runtime installation, profile setup, LLM credential configuration,
-and workspace seeding. If canonry is not yet configured, it runs the interactive init flow first
-(prompting for monitoring provider keys and agent LLM credentials).
+Canonry ships the built-in **Aero** agent (backed by pi-agent-core) for users
+who don't already have one, plus a webhook integration for users who want to
+drive Canonry from Claude Code / Codex / a custom agent.
+
+### Built-in Aero (one-shot CLI)
 
 ```bash
-# Full setup (interactive — prompts for provider keys + agent LLM)
-canonry agent setup
-
-# Non-interactive (flags or env vars)
-canonry agent setup --gemini-key <key> --agent-key <key>
-canonry agent setup --agent-provider openrouter --agent-key <key> --agent-model openrouter/anthropic/claude-sonnet-4-6
-GEMINI_API_KEY=<key> canonry agent setup --agent-key <key> --format json
-
-# Lifecycle
-canonry agent start                              # start agent gateway as background process
-canonry agent stop                               # stop the gateway process
-canonry agent status                             # check if gateway is running
-canonry agent status --format json               # JSON output
-canonry agent reset                              # stop gateway and wipe workspace
-
-# Setup flags
-canonry agent setup --agent-provider <id>        # LLM provider (default: anthropic)
-canonry agent setup --agent-key <key>            # API key for agent LLM
-canonry agent setup --agent-model <model>        # model id (e.g. anthropic/claude-sonnet-4-6)
-canonry agent setup --gateway-port 3579          # gateway WebSocket port
-canonry agent setup --gemini-key <key>           # monitoring provider keys (passed to init)
-canonry agent setup --openai-key <key>
-canonry agent setup --claude-key <key>
-canonry agent setup --perplexity-key <key>
-
-# Webhook lifecycle
-canonry agent attach <project>                   # register agent webhook for project
-canonry agent attach <project> --format json     # JSON output
-canonry agent detach <project>                   # remove agent webhook from project
-canonry agent detach <project> --format json     # JSON output
+# One-shot turn — Aero picks its own tools, streams events to stdout.
+canonry agent ask <project> "<prompt>"
+canonry agent ask <project> "<prompt>" --format json      # JSON event stream
+
+# Select a specific provider / model (otherwise auto-detected from config).
+canonry agent ask <project> "<prompt>" --provider anthropic --model claude-opus-4-7
+canonry agent ask <project> "<prompt>" --provider zai      --model glm-5.1
+canonry agent ask <project> "<prompt>" --provider openai
+canonry agent ask <project> "<prompt>" --provider google
+
+# Restrict the tool surface. Default is --scope all (full 13-tool surface:
+# 7 read + 6 write). --scope read-only exposes only the 7 read tools and
+# is what the dashboard bar uses by default so pasted "Copy as CLI"
+# commands can't enable writes the UI turn couldn't perform.
+canonry agent ask <project> "<prompt>" --scope read-only
+canonry agent ask <project> "<prompt>" --scope all
 ```
 
-**Setup flow:** init canonry (if needed) → install agent runtime (if needed) → configure profile → configure gateway → set agent LLM credentials → seed workspace with skills.
+**Provider detection order** when `--provider` is omitted: `anthropic` →
+`openai` → `google` → `zai`, whichever has an API key present first
+(from `~/.canonry/config.yaml` providers block, or the matching env var
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `ZAI_API_KEY`).
+
+Conversations **persist per project** — `canonry agent ask` continues the
+same rolling thread each invocation. Reset with `DELETE /api/v1/projects/<name>/agent/transcript`
+or via the dashboard bar's reset button.
 
-**Agent LLM credentials** are stored in the agent env file (e.g. `ANTHROPIC_API_KEY=...`) and loaded into the gateway process at start time. The model is set via the agent CLI.
+### External agents (webhook)
 
-**Re-running is safe:** setup is idempotent — it skips steps that are already configured.
+```bash
+# Wire an external agent webhook to a project
+canonry agent attach <project> --url <webhook-url>        # register webhook subscription
+canonry agent attach <project> --url <url> --format json  # JSON output
+canonry agent detach <project>                            # remove the agent webhook
+canonry agent detach <project> --format json              # JSON output
+```
 
-**Agent webhooks:** `canonry agent attach <project>` registers a webhook notification on the project so the agent receives events (`run.completed`, `insight.critical`, `insight.high`, `citation.gained`). Idempotent — skips if an agent webhook already exists. `canonry agent detach <project>` removes the agent webhook. When `autoStart` is enabled, the server auto-attaches webhooks to newly created or applied projects.
+**Agent webhooks** fire on `run.completed`, `insight.critical`, `insight.high`, and `citation.gained`. The attach/detach pair is idempotent per project (one agent webhook per project, matched by source tag).
 
 ## Output Formats