@canonry/canonry 4.177.0 → 4.177.2

package/README.md

@@ -18,7 +18,7 @@ Think PostHog, for AI search visibility. Canonry tracks what ChatGPT, Claude, Ge
 |---|---|
 | **Measure** | Track mentions and citations across Gemini, ChatGPT, Claude, Perplexity, and local models. Join them with GSC, GA4, Bing, server side traffic, Business Profile, and backlink data. |
 | **Diagnose** | Crawl the site, score Page Health, inspect evidence, compare competitors, and explain regressions. |
-| **Act** | Give your agent the context to make surgical on-site technical SEO changes and coordinate content, indexing, analytics, and paid media. |
+| **Act** | Give your agent the context + skills to make surgical on-site technical SEO changes and coordinate content, indexing, analytics, and paid media. |
 | **Operate** | Create automation workflows, schedule checks, sync data, send webhooks, and generate client-ready reports. |
 
 ### Built-in integrations and workflows

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

@@ -160,6 +160,13 @@ 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.
 
+**WordPress safety:** incremental pulls are fixed `[since, until)` windows; a
+new or idle source begins at the plugin's 365-day maximum retention horizon.
+Canonry rejects an endpoint that returns events outside that window. Keep
+existing WordPress rollups intact: generic replace-mode backfill is unavailable
+until a retention-aware repair can prove coverage and declare any unrecoverable
+span.
+
 **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`.
 
 ## Local AEO (Google Business Profile)

package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md

@@ -72,21 +72,17 @@ sync flow does NOT echo the private key back in any response.
 ## Connecting a WordPress source
 
 The WordPress adapter pulls events from the **Canonry Traffic Logger**
-WordPress plugin, which captures every non-admin GET page-load **that
-reaches PHP** and exposes a paginated REST endpoint protected by an
-Application Password.
-
-> **Cache blind spot.** The plugin is a PHP hook, so it only sees
-> requests that execute WordPress. A full-page cache (LiteSpeed, WP
-> Rocket, W3 Total Cache, WP Super Cache) or CDN serves cached pages
-> before PHP runs, so cache-served page views, including live AI
-> user-fetches (Claude-User, ChatGPT-User), are NOT logged. Bot crawls
-> of uncached endpoints (sitemap, feeds, assets, cache misses) still
-> come through, which can make capture look healthy while real page
-> views go uncounted. Exclude AI user-agents from the cache (and any
-> CDN), or capture from access/edge logs instead. The
-> `traffic.source.cache-blindspot` doctor check warns whenever a
-> WordPress source is connected.
+WordPress plugin, which is PHP-only: it captures non-admin GET page-loads
+**that reach PHP** and exposes a paginated REST endpoint protected by an
+Application Password. It has no browser-side capture path.
+
+> **Cache blind spot.** Cache-served requests never execute PHP, so they
+> produce no plugin event. A full-page cache (LiteSpeed, WP Rocket, W3 Total
+> Cache, WP Super Cache) or any CDN can therefore make the source look active
+> while real page views, AI crawlers, and live AI user-fetches such as
+> `Claude-User` and `ChatGPT-User` go uncounted. To use this source for
+> AI-agent traffic, bypass **every** cache layer for the selected AI user
+> agents, or capture from access/edge logs instead.
 
 **Which user-agents to exclude from the cache** (one per line in
 LiteSpeed's "Do Not Cache User Agents", WP Rocket's
@@ -94,23 +90,61 @@ LiteSpeed's "Do Not Cache User Agents", WP Rocket's
 Agents"):
 
 ```
-Claude-User
-ClaudeBot
-ChatGPT-User
-OAI-SearchBot
 GPTBot
+OAI-SearchBot
+OAI-AdsBot
+ChatGPT-User
+openai-mcp
+ClaudeBot
+Claude-
+anthropic-ai
 PerplexityBot
 Perplexity-User
+ShapBot
+Shap-User
+Google-Agent
+Google-GeminiNotebook
+Google-NotebookLM
+Google-CloudVertexBot
+Bytespider
+Applebot
+meta-externalagent
+CCBot
+cohere-ai
+Diffbot
+MistralAI-User
+MistralAI-Index
+MistralAI-Training
+MistralBot
+DeepSeekBot
+xAI-Bot
+Grok-Bot
+GrokBot
+YouBot
+DuckAssistBot
+Amazonbot
+Amzn-SearchBot
+Amzn-User
 ```
 
-These are the answer-engine fetchers in both live-user-fetch (`*-User`)
-and crawler forms. Do NOT add `Googlebot` or `Bingbot`: caching helps
-search crawlers (page speed is a ranking signal, and cached pages let
-them crawl more per visit, which matters most on crawl-budget-starved
-sites), and their crawl stats are already authoritative in GSC and Bing
-Webmaster Tools. Rule of thumb: bypass cache only for agents you cannot
-measure elsewhere and that gain nothing from being cached. Answer-engine
-fetchers fit both; search crawlers fit neither.
+This list mirrors Canonry's current classifier: answer-engine user-fetch,
+crawl, search, and training agents for which WordPress has no cache-independent
+measurement surface. `ClaudeBot` covers Anthropic's unhyphenated core crawler;
+`Claude-` is a separate family rule so newly named `Claude-*Bot` variants
+inherit the bypass. Do NOT add traditional search agents
+`Googlebot`, `bingbot`, `DuckDuckBot`, `YandexBot`, or `Baiduspider`: caching
+helps them crawl efficiently, and the important Google/Bing crawl evidence is
+available through their webmaster tools.
+
+> **1.1.0 -> 1.1.1 measurement boundary.** Plugin 1.1.0 briefly added a
+> JavaScript beacon to recover browser/referral page views served from cache.
+> Plugin 1.1.1 removes it and returns to PHP-only capture. This intentionally
+> means cache-served browser referrals can again be absent even when GA4
+> reports sessions; neither version made cache-served crawler requests visible
+> to PHP. Annotate the upgrade time, do not interpret a trend spanning it as
+> like-for-like traffic, and purge HTML from both the WordPress cache and every
+> outer CDN. A temporary `/wp-json/canonry/v1/pv` compatibility route returns
+> `204` for scripts stranded in old cached HTML, but never records an event.
 
 ```bash
 # 1. Install the plugin. Download the latest release zip from the
@@ -151,6 +185,38 @@ The plugin auto-prunes events older than the retention window (default
 90 days) once per day via WP-Cron. Operators who want a different
 window change it in `Settings → Canonry Traffic Logger`.
 
+### WordPress incremental-window safety
+
+Each incremental WordPress sync uses one fixed half-open `[since, until)`
+window. A fresh source, or an idle source without an explicit
+`--since-minutes`, starts with a 365-day horizon, matching the plugin's
+maximum configurable retention. A site configured for less retention simply
+returns its available tail. If the window needs more than one capped drain,
+Canonry persists both its lower and upper bounds with the continuation cursor
+and retries that exact interval until the plugin reports it is terminal. It
+then advances the normal watermark. Every returned event is validated against
+the requested interval; an older or custom extension that ignores `since` or
+`until` fails closed before any rollup is written. Update that extension to a
+bounded-window-capable Canonry traffic logger before syncing again.
+
+Do not run generic replace-mode backfill for a WordPress source. The plugin
+prunes retained events and cannot prove that it covers every bucket a replace
+transaction would delete, even when no continuation is pending. Canonry
+rejects that generic path universally. Keep existing rollups intact, use a
+retention-aware repair, and explicitly declare any unrecoverable portion before
+reporting a historical trend.
+
+After upgrading from the former unbounded WordPress sync, a source with an old
+continuation cursor is intentionally rejected rather than guessed at. Keep its
+schedule paused, record the ambiguous historical span, then use the explicit
+reset below to start fresh. Reset stops future replay; it does not repair past
+rollups. Generic WordPress replace-mode backfill remains unavailable until a
+retention-aware repair can establish coverage.
+
+Reconnecting with a different WordPress `baseUrl` archives the old source and
+creates a fresh one. Its existing rollups and any unrecovered marker remain
+with the old lineage rather than mixing with the new endpoint's traffic.
+
 ## Connecting a Vercel source
 
 The Vercel adapter pulls per-request logs from the Vercel API for a
@@ -869,15 +935,14 @@ cnry traffic reset <project> --source <id> --advance-to-now
 
 `--advance-to-now` is required — there is no implicit reset.
 
-`reset` accepts any **non-archived** source type. The `lastSyncedAt`
-advance is meaningful for time-windowed sources (Vercel, Cloud Run)
-where it determines the next sync window. Cursor-based sources
-(WordPress) keep their `last_cursor` intact, so the `lastSyncedAt`
-advance is informational — the next WordPress drain still resumes
-from the cursor. The primary use case is the retention-trap recovery
-above; clearing `lastError` for a transient WordPress failure also
-works. Archived sources are rejected — re-connect them with
-`cnry traffic connect ...` instead.
+`reset` accepts any **non-archived** source type. A WordPress reset clears
+its `last_cursor` and pending-window marker as well as advancing
+`lastSyncedAt`, so the next bounded drain begins at the reset watermark
+instead of combining it with an old cursor. The primary use case is the
+retention-trap recovery above; clearing `lastError` for a transient WordPress
+failure also works. Reset deliberately abandons any ambiguous pending history;
+it is not a historical repair. Archived sources are rejected — re-connect them
+with `cnry traffic connect ...` instead.
 
 Time-window and cursor adapters use the `last_event_ids` overlap ring. Queue
 pull uses durable event receipts sized to Queue retention. Both paths make a
@@ -947,7 +1012,7 @@ The doctor checks are adapter-agnostic. When they fail or warn:
 | `traffic.source.queue-backlog` | `traffic.queue-backlog.within-drain-budget` | 1–1,000 Queue messages remain. If no new messages arrive, the next scheduled sync can drain them. Run a manual sync to accelerate. |
 | `traffic.source.queue-backlog` | `traffic.queue-backlog.remaining` | More than 1,000 Queue messages remain. Run a manual sync. If the backlog persists, shorten the traffic-sync schedule. |
 | `traffic.source.credentials` | `traffic.credentials.resolve-failed` | Reconnect from the host that owns the source credentials. Queue pull requires a non-empty Account Queues Edit token paired by source ID. |
-| `traffic.source.cache-blindspot` | `traffic.cache-blindspot.wordpress-plugin` | A WordPress source is connected, so the plugin cannot see cache-served page views. Exclude AI user-agents from the page cache and any CDN, or switch to a log/edge source. Warns only, not a failure. |
+| `traffic.source.cache-blindspot` | `traffic.cache-blindspot.wordpress-plugin` | Cache-served requests never execute PHP and produce no event, so a source can look active while real page views go uncounted. Exclude selected AI user agents from every page-cache and CDN layer, or switch to a log/edge source. Warns only, not a failure. |
 | `traffic.source.worker-version` | `traffic.worker-version.waiting-for-first-event` | Send a smoke-test request through the Worker. For Queue delivery, run a sync to ingest it. Then run the doctor again. |
 | `traffic.source.worker-version` | `traffic.worker-version.stale` | Regenerate and redeploy the Worker from the credential-owning host with the source's existing delivery mode, then verify the route or Queue binding. |
 
@@ -1012,21 +1077,18 @@ domains, or PII are surfaced.
 
 ## Limits & caveats
 
-- **The WordPress plugin is blind to cache-served traffic.** The
-  `wordpress` adapter logs only requests that reach PHP. A full-page
-  cache or CDN serves cached pages from the edge, so cache-served page
-  views, including live AI user-fetches (Claude-User, ChatGPT-User),
-  never reach the plugin and go uncounted, even though bot crawls of
-  uncached endpoints (sitemap, assets) still appear. On a cached
-  WordPress site, treat the plugin's page-view counts as a floor, not a
-  total. Either exclude AI user-agents from the cache + CDN, or capture
-  cache-independent via a `cloud-run` / `vercel` / edge-log source. The
-  `traffic.source.cache-blindspot` doctor check surfaces this. Adapter
-  coverage differs: `vercel` ingests edge request-logs so cache hits are
-  captured (it records the `cache` HIT/MISS label), and `cloud-run` logs
-  every request that reaches the service, missing only what a CDN placed
-  in front of Cloud Run serves from its own edge cache. Only the
-  hook-based `wordpress` adapter has the always-present blind spot.
+- **The WordPress plugin is PHP-only.** The `wordpress` adapter records only
+  requests that reach PHP. Cache-served page requests, including AI crawlers
+  and live AI user-fetches, go uncounted even while crawls of uncached
+  sitemaps, assets, or cache misses appear. On a cached WordPress site, treat
+  this source as a floor unless the selected AI user agents bypass every
+  page-cache and CDN layer. The static doctor warning surfaces this limitation
+  without requesting the origin. Otherwise, use a cache-independent
+  `cloud-run`, `vercel`, or edge-log source. Adapter coverage
+  differs: `vercel` ingests edge request logs so cache hits are captured (it
+  records the `cache` HIT/MISS label), and `cloud-run` logs every request that
+  reaches the service, missing only what a CDN ahead of Cloud Run serves at its
+  own edge.
 - **Path-level citation cross-reference is not implemented yet.** The
   citation store is domain-grain (`query_snapshots.cited_domains`). A
   future iteration that lands URL-grain citation evidence will extend
@@ -1047,17 +1109,21 @@ domains, or PII are surfaced.
   `traffic_sources.source_type` and a `TrafficSourceValidator`
   registration.
 
-### Page caches and the beacon lane
-
-A page cache (LiteSpeed, WP Rocket, Super Cache, any `advanced-cache.php`
-drop-in) serves visitors before WordPress PHP boots, so the plugin's request
-hook never sees those page views: on a cached site the PHP lane records only
-redirects, errors, and crawlers on uncached URLs, and landed AI referrals read
-as zero while GA4 shows sessions. Plugin 1.1.0 adds a beacon lane — a
-first-party inline ping to the plugin's own REST route (never page-cached) —
-that records real browser views, cached or not. It auto-enables when a page
-cache is detected (`Settings → Canonry Traffic Logger` can force on/off).
-Bots and non-200s stay in the PHP lane; browser 200s belong to the beacon, so
-uncached views are not double-counted. On sites running plugin ≤ 1.0.x behind
-a cache, treat GA4 as the landed-visit signal and the server source as the
-bot/crawler signal only.
+### Page caches and PHP-only coverage
+
+A page cache (LiteSpeed, WP Rocket, Super Cache, or any
+`advanced-cache.php` drop-in) can serve a request before WordPress boots. The
+plugin therefore has one capture lane only: PHP. It cannot recover a
+cache-served crawler, user fetch, referral, or browser page view after the
+fact.
+
+For the AI agents measured by this source, configure cache bypasses at every
+layer that can answer the public request: the WordPress cache, a host/CDN cache,
+and any edge cache. A LiteSpeed exclusion alone is insufficient when an outer
+CDN can return a cached response first.
+
+Cache exclusions for the selected AI agents can recover crawler and user-fetch
+coverage, but they do not recover ordinary browser referrals served from cache.
+Use GA4 for landed browser visits or edge/access logs for cache-independent
+request coverage. The `traffic.source.cache-blindspot` doctor check is a static
+warning; it does not request or impersonate traffic against the public origin.

package/dist/{chunk-F4ZZKGAC.js → chunk-6XUWDSLN.js}

@@ -91,7 +91,7 @@ import {
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
   trafficSeriesGranularitySchema
-} from "./chunk-UXXXKDW4.js";
+} from "./chunk-PQT3ECM3.js";
 
 // src/config.ts
 import fs from "fs";
@@ -9487,17 +9487,17 @@ var trafficConnectVercelInputSchema = z3.object({
 var trafficSyncInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_connect_cloud_run or canonry_traffic_sources_list."),
-  sinceMinutes: z3.number().int().positive().max(7 * 24 * 60).optional().describe("Lookback window in minutes. Defaults to the source's configured window (60 min) when omitted; clamped forward to lastSyncedAt to avoid double-counting.")
+  sinceMinutes: z3.number().int().positive().max(365 * 24 * 60).optional().describe("Optional lookback in minutes. Defaults are adapter-specific and clamp forward to lastSyncedAt; a new or idle WordPress source uses 365d to cover the plugin\u2019s maximum configurable retention.")
 });
 var trafficBackfillInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_sources_list."),
-  days: z3.number().int().positive().max(30).optional().describe("Lookback window in days. Default 30, capped server-side at the upstream log retention ceiling (Cloud Logging _Default = 30d).")
+  days: z3.number().int().positive().max(90).optional().describe("Lookback window in days. Default 30, capped by the adapter at 90d. Generic WordPress replace backfill is unavailable because retained coverage is unproven.")
 });
 var trafficResetInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_sources_list."),
-  advanceToNow: z3.literal(true).describe("Must be `true`. Explicit gate against accidental resets. Advances lastSyncedAt to NOW and clears the source's error state.")
+  advanceToNow: z3.literal(true).describe("Must be `true`. Explicit gate against accidental resets. Advances lastSyncedAt to NOW and clears the source's error state; WordPress also clears its continuation state and records an unrecovered span that needs retention-aware repair.")
 });
 var trafficEventsInputSchema = z3.object({
   project: projectNameSchema,
@@ -10650,7 +10650,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_traffic_connect_wordpress",
     title: "Connect WordPress traffic-logger source",
-    description: "Connect a WordPress site (running the canonry traffic-logger plugin) as a server-side traffic source. Probes the plugin endpoint with the supplied Application Password before persisting \u2014 a bad credential or unreachable host surfaces as a 502 error. Reconnecting updates the existing active WordPress source in place. The Application Password is stored in ~/.canonry/config.yaml (not the DB) and never echoed back.",
+    description: "Connect a WordPress site (running the canonry traffic-logger plugin) as a server-side traffic source. Probes the plugin endpoint with the supplied Application Password before persisting; a bad credential or unreachable host surfaces as a 502 error. Reconnecting the same endpoint updates the active source in place. Changing baseUrl archives the old lineage and creates a fresh source so rollups cannot mix across endpoints. The Application Password is stored in ~/.canonry/config.yaml (not the DB) and never echoed back.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficConnectWordpressInputSchema,
@@ -10671,8 +10671,8 @@ var canonryMcpTools = [
   }),
   defineTool({
     name: "canonry_traffic_sync",
-    title: "Sync Cloud Run traffic source",
-    description: "Pull the most recent Cloud Logging entries for a Cloud Run traffic source, classify them as crawler / AI-referral / unknown, and upsert hourly rollups + raw samples. Returns totals, bucket counts, and the run id. The window auto-clamps forward to lastSyncedAt to avoid double-counting on back-to-back calls.",
+    title: "Sync traffic source",
+    description: "Pull a Cloud Run, WordPress, Vercel, or Cloudflare Queue traffic source, classify crawler / AI-referral / unknown traffic, and upsert hourly rollups plus raw samples. Time-window pulls clamp forward to lastSyncedAt. WordPress uses a fixed bounded window, defaults a new or idle source to 365d, validates the returned events remain inside that window, and serializes syncs with a source lease.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficSyncInputSchema,
@@ -10682,8 +10682,8 @@ var canonryMcpTools = [
   }),
   defineTool({
     name: "canonry_traffic_backfill",
-    title: "Backfill Cloud Run traffic source",
-    description: 'Async one-shot reclassification of historical Cloud Run logs. Pulls the last `days` of request logs (capped at the 30d Cloud Logging retention ceiling), classifies them with current rules, and replaces the hourly rollup buckets + sample slice in the window. Returns immediately with `{ runId, status: "running" }`; poll canonry_run_get for completion. lastSyncedAt only advances forward \u2014 a backfill never undoes incremental sync progress that ran ahead of it.',
+    title: "Backfill traffic source",
+    description: 'Async one-shot reclassification for Cloud Run or Vercel traffic. It replaces the selected window\u2019s rollups with a fresh bounded pull and current classifier output. WordPress generic replace backfill is unavailable because the endpoint cannot prove retained coverage; use a retention-aware repair that explicitly declares any unrecoverable span. Returns `{ runId, status: "running" }`; poll canonry_run_get for completion.',
     access: "write",
     tier: "traffic",
     inputSchema: trafficBackfillInputSchema,
@@ -10694,7 +10694,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_traffic_reset",
     title: "Advance traffic source lastSyncedAt to NOW",
-    description: "Operator recovery for a stuck traffic source. Advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. Accepts any non-archived source: the `lastSyncedAt` advance determines the next sync window for time-windowed sources (Vercel, Cloud Run); cursor-based sources (WordPress) keep their `last_cursor` so the advance is informational. Common trigger: an idle Vercel/Cloud Run source whose `lastSyncedAt` aged past the upstream retention boundary and every sync now throws a retention error. Historical events in the gap are unrecoverable from the sync path; run canonry_traffic_backfill separately if any of them are needed. Archived sources are rejected \u2014 re-connect via the appropriate canonry_traffic_connect_* tool instead.",
+    description: "Operator recovery for a stuck traffic source. Advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. A WordPress reset also clears its continuation state and records an unrecovered span so its next bounded drain cannot combine an old cursor with a new window. That stops replay but is not historical repair. Generic WordPress replace-mode backfill is unavailable because retained coverage is unproven; use a retention-aware repair that explicitly declares any unrecoverable span. Archived sources are rejected; reconnect them with the appropriate canonry_traffic_connect_* tool.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficResetInputSchema,