@canonry/canonry 4.158.0 → 4.160.0

package/README.md

@@ -2,10 +2,10 @@
 
 [![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)
 
-Your entire AEO + web analytics stack, agent-first. **Open source. Self-hosted. Local.**
+Your entire AEO/GEO/AI Visibility, technical SEO + web analytics stack. **Agent-first. Self-hosted. Local.**
 
 - **Local-only:** Canonry runs on your machine and stores its data in SQLite.
-- Track citations across Gemini, ChatGPT, Claude, Perplexity, and local LLMs
+- Track web search citations and mentions across Gemini, ChatGPT, Claude, Perplexity, and local LLMs
 - Capture server-side traffic from Cloudflare, Cloud Run, Vercel, and WordPress — [setup guide](skills/canonry/references/server-side-traffic.md)
 - 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
@@ -94,7 +94,7 @@ Configure during `cnry init`, in the dashboard `/settings`, or as env vars.
 | **Aero — built-in agent** | [skills/aero/SKILL.md](skills/aero/SKILL.md) |
 | **Agent Plugin — portable core + Codex / Claude adapters** | [docs/plugins.md](docs/plugins.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 (Cloudflare direct push, Cloud Run, Vercel, WordPress)](skills/canonry/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) · [Google Business Profile](skills/canonry/references/google-business-profile.md) · [WordPress](docs/wordpress-setup.md) · [Server-side traffic (Cloudflare direct push or Queue pull, Cloud Run, Vercel, WordPress)](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) |
 | **Standalone skills bundle** for Claude Code / Codex | `cnry skills install` ([details](skills/canonry/SKILL.md)) |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,102 @@
+# Third-party notices
+
+Canonry includes the following font software in its bundled dashboard assets.
+
+## Geist and Geist Mono
+
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+Geist-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+GeistMono-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,102 @@
+# Third-party notices
+
+Canonry includes the following font software in its bundled dashboard assets.
+
+## Geist and Geist Mono
+
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+Geist-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+GeistMono-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

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

@@ -16,7 +16,22 @@ Persist only *user-scoped* context (operator preferences, communication style) i
 
 **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, ask for explicit approval before re-syncing. 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`.
+When a project has GA4 connected, traffic is a first-class signal alongside
+mentions and citations. Use `cnry ga traffic` and `cnry ga attribution --trend`
+for the current snapshot. Use the GA referral-history commands for daily series.
+Before you quote GA4 data, make sure that `cnry ga status` has a recent
+`lastSyncedAt`. If it is stale, get approval before you run `cnry ga sync`.
+
+For Cloud Run, WordPress, Vercel, or Cloudflare, use `cnry traffic status` and
+`cnry traffic events` for crawler and AI-referral evidence. Read the Cloudflare
+`deliveryMode` before you recommend an action. Direct push does not use
+`traffic sync`. Queue pull freshness requires an enabled `traffic-sync`
+schedule. Run the `traffic.source.*` doctor checks. Inspect
+`traffic.source.queue-backlog` before you quote current Queue data. If more than
+1,000 messages remain, report that one default tick cannot drain the backlog.
+Get approval before you run a manual sync or change the schedule. The full
+command reference is 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).
 

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

@@ -1,6 +1,6 @@
 ---
 name: canonry
-description: "Set up and operate Canonry AEO projects: inspect mention and citation coverage, diagnose regressions, run technical audits, and act through the Canonry CLI or MCP tools. Examples: inspect project acme coverage (run + report), diagnose query drift via attribution (report.html + visibility-attribution), submit GSC sitemaps (gsc-sitemap-submission batched)."
+description: "Set up and operate Canonry AEO projects. Inspect mention and citation coverage, diagnose regressions, and run technical audits. Connect Cloudflare direct-push or queue-pull traffic. Act through the Canonry CLI or MCP tools. Examples: inspect project acme coverage (run + report), diagnose query drift via attribution (report.html + visibility-attribution), or submit GSC sitemaps (gsc-sitemap-submission batched)."
 compatibility: Requires Node.js 22.14+ and globally installed @canonry/canonry; canonry-mcp must be on PATH.
 metadata:
   agent: >-
@@ -131,10 +131,22 @@ GA4 is a first-class signal alongside citation tracking. Connect once with `cnry
 
 When the project ships behind a server you control, connect Cloud Run, WordPress,
 or Vercel. `cnry traffic sync` pulls and classifies their logs into hourly
-buckets. For a Cloudflare site, `cnry traffic connect cloudflare <project> ...`
-deploys a direct-push Worker from the credential-owning host. Cloudflare direct
-push does not use `traffic sync`. Use `cnry traffic events / sources / status`
-for every adapter. See `references/server-side-traffic.md` for setup.
+buckets. For Cloudflare, choose `direct-push` or `queue-pull` on the local,
+credential-owning host. Direct push requires a public Canonry HTTPS receiver.
+It does not use `traffic sync`. Queue pull sends events to a Cloudflare Queue,
+then Canonry drains it through `traffic sync` and the `traffic-sync` schedule.
+
+If the connect response reports `activationRequired`, attach the Worker route
+first. Then run `cnry traffic activate <project> --source <id>`. Activation
+pauses all sibling sources. It also moves the one `traffic-sync` schedule to
+Queue pull. A first source becomes active automatically.
+
+Each default Queue tick drains at most 1,000 messages. Use `cnry traffic status`
+and the `traffic.source.queue-backlog` doctor check to read the backlog. If more
+than 1,000 messages remain, get approval before a manual sync or a shorter
+schedule interval. Use `cnry traffic events`, `cnry traffic sources`, and
+`cnry traffic status` for every adapter. See
+`references/server-side-traffic.md` for setup and smoke tests.
 
 **Vercel gotcha:** a freshly connected Vercel source captures only going-forward traffic — `lastSyncedAt` is seeded to NOW to avoid the 30-day default window exceeding Vercel's ~14-day request-logs retention (which would otherwise throw on every first sync). Use `cnry traffic backfill <project> --source <id> --days N` for historical recovery. If an idle Vercel/Cloud Run source has been failing long enough that `lastSyncedAt` aged past retention, unstick it with `cnry traffic reset <project> --source <id> --advance-to-now`.
 

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

@@ -258,6 +258,7 @@ Site-wide technical audit (structured data, AI-readable content, AI-crawler acce
 cnry technical-aeo run <project> --wait                 # full crawl + audit; defaults to 1,000 pages / 100,000 edges; waits for terminal state
 cnry technical-aeo run <project> --sitemap-url <url> --max-pages 5000 --max-edges 250000 --max-depth 12   # optional crawl seeds and custom budgets; hard caps are 50,000 pages / 1,000,000 edges
 cnry technical-aeo run <project> --check-dead-links --wait   # opt in to dead-link checks; they are off by default
+cnry technical-aeo progress <project> --run-id <id> [--format json] # exact durable phase and pages found / checked / failed counters; never a synthesized percentage
 cnry technical-aeo crawl <project> [--run-id <id>] [--format json]   # crawl metadata, budgets, completeness, and termination
 cnry site-health overview <project> [--run-id <id>] [--format json] # operator-facing alias for crawl metadata
 cnry site-health page-audit <project> (--node-key <key>|--url <url>) [--run-id <id>] [--format json] # exact audit score, factor findings, recommendations, and crawl provenance for one graph page
@@ -563,6 +564,72 @@ cnry wordpress onboard <project> --url <url> --user <user>  # full onboarding wo
 
 **Onboard** runs: connect → audit → set-meta → schema deploy → Google submit → Bing submit. Use `--skip-schema` or `--skip-submit` to skip steps. `--profile <file>` provides business data and page-to-schema mapping for schema deployment.
 
+## Server-Side Traffic
+
+Cloudflare supports direct push and Queue pull. Run Cloudflare connect only from
+the local host that owns the Canonry configuration and Wrangler profile. This
+operation is not available through MCP because it uses local credentials.
+
+```bash
+# Direct push to a stable public Canonry HTTPS receiver:
+cnry traffic connect cloudflare <project> \
+  --delivery-mode direct-push \
+  --zone-id <zone-id> --account-id <account-id> \
+  --deploy --confirm-route --confirm-fail-open
+
+# Create the Queue and enable its HTTP pull consumer first:
+wrangler queues create canonry-traffic-<project>
+# Workers Paid only: use this command to change the four-day default.
+wrangler queues update canonry-traffic-<project> \
+  --message-retention-period-secs <seconds>
+wrangler queues info canonry-traffic-<project>
+wrangler queues consumer http add canonry-traffic-<project>
+
+# Queue pull keeps the API token in the local Canonry credential store:
+cnry traffic connect cloudflare <project> \
+  --delivery-mode queue-pull \
+  --zone-id <zone-id> --account-id <account-id> \
+  --queue-id <queue-id> --queue-name canonry-traffic-<project> \
+  --api-token-file <mode-0600-token-file> \
+  --retention-seconds <actual-queue-retention-seconds> \
+  --deploy --confirm-route --confirm-fail-open
+```
+
+Workers Free retention is fixed at `86400` seconds. Workers Paid defaults to
+`345600` seconds. If you change paid retention with `wrangler queues update`,
+pass the same value to Canonry. The Canonry flag does not change the Queue.
+
+Both commands deploy an unattached Worker. Attach the exact site route in the
+Cloudflare Dashboard. Then set its request-limit failure mode to **Fail open**.
+Do not put the Queue API token on the command line or in an agent transcript.
+
+```bash
+# If connect reports activationRequired, activate after the route is live:
+cnry traffic activate <project> --source <source-id>
+cnry traffic sync <project> --source <source-id>      # pull adapters, including Cloudflare Queue pull
+cnry traffic sources <project> --format json
+cnry traffic status <project> --format json
+cnry traffic events <project> --source <source-id> --format json
+
+cnry doctor --project <project> --check 'traffic.source.*' --format json
+cnry schedule show <project> --kind traffic-sync --format json
+cnry schedule set <project> --kind traffic-sync \
+  --source <source-id> --cron "*/10 * * * *"
+```
+
+A first source becomes active automatically. A staged source stays paused until
+the explicit activation command. Activation pauses sibling sources and moves the
+one `traffic-sync` schedule for the project. Direct push rejects `traffic sync` and
+does not use this schedule.
+
+Queue pull drains at most 1,000 messages in one default sync. The doctor warns
+when the remaining backlog is more than 1,000 messages. If the operator approves
+a manual drain, run a manual sync. If the backlog recurs, get approval to shorten
+the schedule interval.
+
+Read the [server-side traffic guide](server-side-traffic.md) for token safety,
+route checks, activation order, smoke tests, rollback, and troubleshooting.
+
 ## Google Analytics 4
 
 GA4 integration uses service account authentication (no OAuth). The service account must have Viewer access on the GA4 property. `ga sync` writes to four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`); every subsequent read command queries the local store rather than re-fetching from GA4, so reads are fast and quotaless. AI-referral rows are tracked across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), three GA4 attribution dimensions (`session` / `first_user` / `manual_utm`), and joined to landing pages. Social referrals are split Organic vs Paid via GA4's `sessionDefaultChannelGroup`. All commands support `--format json`.