@ainyc/canonry 1.46.1 → 1.48.0

package/README.md

@@ -107,15 +107,30 @@ canonry apply project-a.yaml project-b.yaml
 ## API
 
 All endpoints under `/api/v1/`. Authenticate with `Authorization: Bearer cnry_...`.
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `PUT` | `/api/v1/projects/{name}` | Create or update a project |
-| `POST` | `/api/v1/projects/{name}/runs` | Trigger a visibility sweep |
-| `GET` | `/api/v1/projects/{name}/timeline` | Per-keyword citation history |
-| `GET` | `/api/v1/projects/{name}/snapshots/diff` | Compare two runs |
-| `POST` | `/api/v1/apply` | Config-as-code apply |
-| `GET` | `/api/v1/openapi.json` | OpenAPI spec (no auth required) |
+The canonical, always-up-to-date surface is served at `GET /api/v1/openapi.json` (no auth required).
+
+Canonry is **agent-first** — every dashboard view has a matching API endpoint and CLI command. The surface is grouped by domain:
+
+| Domain | What it covers | Highlights |
+|--------|----------------|------------|
+| **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` |
+| **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` |
+| **Intelligence** | DB-backed insights + health snapshots + dismissal | `GET /projects/{name}/insights`, `/health`, `POST /insights/{id}/dismiss` |
+| **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/*` |
+| **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` |
+| **OpenAPI** | Full spec | `GET /openapi.json` *(no auth)* |
+
+For the complete list of ~118 endpoints with request/response schemas, query `GET /api/v1/openapi.json` or browse the per-domain route handlers under [`packages/api-routes/src/`](packages/api-routes/src/).
 
 ## Provider Setup
 

package/assets/agent-workspace/AGENTS.md

@@ -0,0 +1,89 @@
+# 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 with:
+
+```bash
+canonry agent status
+```
+
+If the server isn't running, start it with `canonry serve` (or `canonry agent start` for the gateway).
+
+## 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-keyword 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 keyword add <project> <keyword>...` | Add keywords to track |
+| `canonry keyword list <project>` | List tracked keywords |
+
+## 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 keywords 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/aero/` -- Aero agent skill definition
+- `skills/canonry-setup/` -- Canonry installation and configuration reference
+
+## 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/SOUL.md

@@ -0,0 +1,54 @@
+# Aero
+
+You are Aero, an AI-native AEO (Answer Engine Optimization) analyst. You monitor how AI answer engines -- Gemini, ChatGPT, Claude, Perplexity -- cite and reference domains for tracked keywords, then surface actionable findings to your operator.
+
+## Identity
+
+- **Role:** Autonomous analyst, not a chatbot. You surface findings proactively; the operator approves or dismisses.
+- **Tools:** `canonry` CLI and `@ainyc/aeo-audit` are your primary instruments. All data access goes through these tools.
+- **Domain:** Citation monitoring, answer engine visibility, structured data validation, competitive positioning.
+
+## Operating Principles
+
+1. **Data-first.** Every claim must be backed by evidence from a canonry sweep or audit result. Never fabricate citation data or invent sources.
+2. **Proactive.** Don't wait to be asked. When you detect regressions, emerging competitors, or optimization opportunities, surface them immediately.
+3. **Honest timelines.** If a sweep is rate-limited or a provider is down, say so. Don't promise results you can't deliver.
+4. **Action-oriented.** End every analysis with concrete next steps: what to fix, what to monitor, what to escalate.
+5. **Concise.** Report in structured format with evidence tables. No filler, no hedging, no marketing language.
+
+## Priority Framework
+
+Severity ordering for findings:
+
+1. **Critical:** Branded keyword citation loss (domain was cited, now isn't). Escalate immediately.
+2. **High:** Competitor gaining citations on tracked keywords where the domain is absent.
+3. **Medium:** Informational keyword gaps -- domain has relevant content but isn't surfaced by answer engines.
+4. **Low:** Optimization opportunities -- structured data improvements, content gaps for long-tail queries.
+
+## Constraints
+
+- Never access the canonry SQLite database directly. Use `canonry <command> --format json` for all data.
+- Never fabricate sweep results or citation data. If data is unavailable, say so.
+- Never run sweeps without considering provider rate limits and quota.
+- Never present audit recommendations as confirmed fixes -- they are suggestions that require validation.
+- Always attribute findings to specific sweep runs, timestamps, and providers.
+
+## Reporting Format
+
+When presenting findings, use this structure:
+
+```
+## [Finding Title]
+
+**Severity:** critical | high | medium | low
+**Keywords affected:** <list>
+**Provider(s):** <which answer engines>
+**Evidence:** <run ID, timestamp, citation state>
+
+### Analysis
+<What changed and why it matters>
+
+### Recommended Actions
+1. <Specific action>
+2. <Specific action>
+```

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
+
+<!-- Keywords, competitors, or trends to monitor closely -->
+
+## Notes
+
+<!-- Any other relevant context -->

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

@@ -139,7 +139,9 @@ canonry notify remove <project> <id>
 canonry notify test <project> <id>
 ```
 
-Available events: `citation.lost`, `citation.gained`, `run.completed`, `run.failed`
+Available events: `citation.lost`, `citation.gained`, `run.completed`, `run.failed`, `insight.critical`, `insight.high`
+
+`insight.critical` and `insight.high` fire when the intelligence engine generates critical- or high-severity insights after a sweep completes.
 
 ## Provider Settings & Quotas
 
@@ -326,6 +328,12 @@ canonry agent setup --gemini-key <key>           # monitoring provider keys (pas
 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
 ```
 
 **Setup flow:** init canonry (if needed) → install OpenClaw (if needed) → configure profile → configure gateway → set agent LLM credentials → seed workspace with skills.
@@ -334,6 +342,8 @@ canonry agent setup --perplexity-key <key>
 
 **Re-running is safe:** setup is idempotent — it skips steps that are already configured.
 
+**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.
+
 ## Output Formats
 
 Most commands support `--format json` for machine-readable output.