@canonry/canonry 4.156.0 → 4.158.0

package/README.md

@@ -6,7 +6,7 @@ Your entire AEO + web analytics stack, agent-first. **Open source. Self-hosted.
 
 - **Local-only:** Canonry runs on your machine and stores its data in SQLite.
 - Track citations across Gemini, ChatGPT, Claude, Perplexity, and local LLMs
-- Watch AI engines crawl and refer traffic via [server-log ingestion](skills/canonry/references/server-side-traffic.md) — Cloud Run, Vercel, and the WordPress Traffic Logger plugin today
+- 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
 - Manage [ChatGPT ads](docs/mcp.md#tool-surface) with OpenAI Ads Manager — connect an ad account, inspect conversion setup and performance, prepare paused campaigns, and launch only with an explicit human approval
@@ -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 (Cloud Run + Vercel + WordPress logs)](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, 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/assets/agent-workspace/skills/canonry/SKILL.md

@@ -66,7 +66,7 @@ tool or `403` by switching credentials.
 - Running technical SEO audits (14‑factor scoring)
 - Implementing structured data (JSON‑LD)
 - Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools
-- Wiring server-side traffic (Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal
+- Wiring server-side traffic (Cloudflare, Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal
 - Optimizing `llms.txt`, sitemaps, robots.txt for AI crawlers
 - Submitting URLs to Google Indexing API and Bing IndexNow
 - Analyzing competitor citation patterns
@@ -129,7 +129,12 @@ GA4 is a first-class signal alongside citation tracking. Connect once with `cnry
 
 ## Server-Side Traffic
 
-When the project ships behind a server you control, wire crawler + AI-referral evidence directly from the edge: `cnry traffic connect cloud-run | wordpress | vercel <project> ...` writes credentials to `~/.canonry/config.yaml`, `cnry traffic sync` pulls and classifies logs into hourly buckets, and `cnry traffic events / sources / status` expose the rollups. See `references/server-side-traffic.md` for adapter-specific setup.
+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.
 
 **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`.
 
@@ -168,7 +173,7 @@ Aero also wakes unprompted after every `run.completed` so insights and regressio
 | `references/aeo-analysis.md` | Interpreting sweep output, diagnosing regressions, planning content fixes |
 | `references/indexing.md` | Submitting URLs, checking GSC/Bing coverage, fixing indexing gaps |
 | `references/wordpress-integration.md` | Connecting to WordPress, editing pages, pushing staging → live |
-| `references/server-side-traffic.md` | Wiring server-log evidence (Cloud Run, WordPress, Vercel adapters) for AI Visibility — Server-Side. Connect, sync, manage sources, troubleshoot. |
+| `references/server-side-traffic.md` | Wiring server-side evidence from Cloudflare, Cloud Run, WordPress, and Vercel. Connect, inspect, sync pull sources, and troubleshoot. |
 | `references/google-business-profile.md` | Connecting Google Business Profile for local AEO: access-form approval, GCP API enablement, the v4-reviews access gate, hotel lodging/place-action signals, data shapes, troubleshooting. |
 
 ---

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

@@ -1,8 +1,8 @@
 # Server-side traffic (AI Visibility — Server-Side)
 
-Server-side traffic ingestion captures **what AI engines actually do in
-your server logs** — bots crawling pages, AI products sending
-click-through arrivals — in addition to the citation data that measures
+Server-side traffic ingestion captures **what AI engines actually do at
+your site** — bots crawling pages, AI products fetching pages for users,
+and AI products sending click-through arrivals. Citation data measures
 **what models say** about you. The two surfaces are independent.
 
 ## When to use it
@@ -10,6 +10,7 @@ click-through arrivals — in addition to the citation data that measures
 Reach for server-side traffic when an analyst or operator asks:
 
 - *"Is GPTBot / ClaudeBot / PerplexityBot actually fetching my pages?"*
+- *"Did an AI product fetch this page for a user?"*
 - *"Which paths are AI engines paying attention to?"*
 - *"Are users clicking through from chatgpt.com / claude.ai / etc.?"*
 - *"My citation rate is fine but there's no traffic — why?"*
@@ -21,24 +22,28 @@ blockers, or analytics gaps.
 
 ## Architecture
 
-Two tables, populated from server-log adapters:
+Four tables store the shared output from every adapter:
 
 | Table | What's in it |
 |---|---|
 | `crawler_events_hourly` | One row per `(project, source, hour, bot, verification, path, status)` — bot crawls rolled up by hour |
+| `ai_user_fetch_events_hourly` | One row per `(project, source, hour, bot, verification, path, status)` — user-initiated AI fetches rolled up by hour |
 | `ai_referral_events_hourly` | One row per `(project, source, hour, product, source_domain, evidence_type, landing_path, status)` — click-through arrivals rolled up by hour |
-| `raw_event_samples` | Bounded forensic samples (≤100 per sync) for spot-checking |
+| `raw_event_samples` | Bounded forensic samples for spot checks. Cloudflare uses a per-source, per-hour cap |
 
 Each `traffic_sources` row is one server-log integration for a project.
 Adapters today:
 
-| Adapter | Source | Best for |
-|---|---|---|
-| `cloud-run` | GCP Cloud Run request logs via Logging API | Any service running on Cloud Run |
-| `wordpress` | The Canonry Traffic Logger WP plugin's REST endpoint | WordPress sites where you control wp-admin |
-| `vercel` | Vercel project logs via the Vercel API | Sites deployed on Vercel (Next.js, SvelteKit, etc.) |
+| Adapter | Transport | Source | Best for |
+|---|---|---|---|
+| [`cloud-run`](#connecting-a-cloud-run-source) | Pull | GCP Cloud Run request logs via Logging API | Any service running on Cloud Run |
+| [`wordpress`](#connecting-a-wordpress-source) | Pull | Canonry Traffic Logger REST endpoint | WordPress sites where you control wp-admin |
+| [`vercel`](#connecting-a-vercel-source) | Pull | Vercel project logs via the Vercel API | Sites deployed on Vercel |
+| [`cloudflare`](#connecting-a-cloudflare-source-direct-push) | Direct push | A zone Worker selects and sends edge events | Sites whose public traffic passes through Cloudflare |
 
 Future adapters slot in by implementing the same contract.
+Cloud Run, WordPress, and Vercel pull logs during `traffic sync`.
+Cloudflare sends selected events from its Worker and does not use `traffic sync`.
 
 ## Connecting a Cloud Run source
 
@@ -190,6 +195,425 @@ Run `cnry traffic backfill <project> --source <id> --days N` (capped at
 history. It's an explicit operator action; the connect flow never pulls
 it implicitly.
 
+## Connecting a Cloudflare source (direct push)
+
+Cloudflare direct push runs a small ES-module Worker on the site's exact
+zone route. It applies a broad AI filter and sends selected edge events
+to Canonry in `ctx.waitUntil()`. The origin response remains independent
+from filtering, scheduling, and delivery errors. The event shape is also
+the contract for the later Queue pull transport.
+
+The shipped adapter does not pull Cloudflare analytics or request logs.
+Queue pull has a reserved transport mode, but it is not available yet.
+
+```mermaid
+flowchart LR
+  request["Site request"] --> worker["Canonry Cloudflare Worker"]
+  worker --> origin["Existing origin or Pages site"]
+  origin --> response["Unchanged site response"]
+  worker -. "signed selected event via ctx.waitUntil" .-> ingest["Canonry public HTTPS ingest"]
+  ingest --> classify["Shared traffic classifier"]
+  classify --> rollups["Hourly crawler, user-fetch, and referral rollups"]
+```
+
+### Setup flow
+
+1. Create or select a Canonry project with one exact canonical hostname.
+2. Give the Canonry server a stable public HTTPS URL outside the site route.
+3. Authenticate Wrangler with the Cloudflare account that owns the zone.
+4. Inspect existing Worker routes for the exact canonical hostname.
+5. Run the local Cloudflare connect command with `--deploy`.
+6. Attach the printed route in Cloudflare and set it to **Fail open**.
+7. Send the smoke requests and run the Canonry doctor.
+
+### Current support boundary
+
+Direct push currently supports a local `canonry serve` instance. The CLI
+and server must read the same `~/.canonry/config.yaml` credential store.
+You can expose that local server through a stable HTTPS tunnel.
+
+The Cloud Run `apps/api` service has no Cloudflare credential store.
+Therefore, `apps/api` cannot retain the per-source bearer and HMAC values
+that deployment requires.
+
+CAUTION: Use one authoritative server-traffic source for the canonical
+site. Overlapping adapters capture the same requests and double-count
+project totals. This is a current limitation. Queue support must define
+source coverage before it permits a transport change.
+
+### Expose the Canonry receiver
+
+Complete the local dashboard setup and set its password before you expose
+Canonry. A tunnel makes the loopback server reachable from the public Internet.
+
+Use a named Cloudflare Tunnel or another stable reverse proxy:
+
+```text
+https://canonry-ops.example.net
+  -> stable tunnel or reverse proxy
+  -> http://127.0.0.1:4100
+```
+
+Then complete these steps:
+
+1. Back up `~/.canonry/config.yaml`.
+2. Set `publicUrl` to the external Canonry URL.
+3. If Canonry uses a base path, include that path in `publicUrl`.
+4. Restart `canonry serve`.
+5. Send an unsigned request to the ingest path from the public Internet.
+6. Make sure that the response status is `401`.
+
+```yaml
+publicUrl: https://canonry-ops.example.net
+```
+
+```bash
+CANONRY_PUBLIC_URL=https://canonry-ops.example.net
+
+curl -sS -o /dev/null -w '%{http_code}\n' \
+  -X POST -H 'content-type: application/json' --data '{}' \
+  "${CANONRY_PUBLIC_URL%/}/api/v1/projects/<project>/traffic/cloudflare/ingest"
+```
+
+The `401` response proves that the request reached Canonry's transport
+authentication. A `403` can mean that Cloudflare Access or a WAF rule blocked
+the request first. Exempt only the exact ingest path from interactive
+challenges. Keep the rest of Canonry behind its normal access controls.
+
+Do not use a random TryCloudflare URL for production. The Worker stores the
+ingest URL at deployment time. If a temporary URL changes, rerun connect and
+redeploy the Worker.
+
+The public URL is the Canonry receiver, not the tracked site. Use a different
+hostname from the generated Worker route. Do not add credentials, a query, or
+a fragment to this URL.
+
+### Prerequisites and route preflight
+
+1. Install a current Wrangler release.
+2. Run `wrangler login`.
+   If Wrangler lists multiple accounts, pass the exact `--account-id`.
+3. Run `wrangler whoami` to get the account ID.
+4. Get the zone ID from the Cloudflare zone Overview page.
+5. Make sure that the zone belongs to the selected account.
+6. Make sure that Cloudflare proxies the canonical hostname in DNS.
+7. Inspect every Worker route that overlaps the canonical hostname. Cloudflare
+   uses the most-specific matching route. Record any excluded path coverage.
+8. Make sure that `<canonical-host>/*` is unclaimed. If a more-specific route
+   must remain, integrate Canonry there or accept that those paths are absent.
+9. If another Worker owns the catch-all route, stop. Integrate Canonry into that
+   Worker instead of attaching a second Worker.
+10. Review the account request volume. A route invokes the Worker for every
+   matching request. The filter does not reduce Worker invocations.
+
+```bash
+npm install -g wrangler@latest
+wrangler login
+wrangler whoami
+```
+
+Canonry does not pass a `--profile` option to Wrangler. Wrangler uses the auth
+profile that is active for the current directory, or its default profile. If
+you use named profiles, activate one before you run Canonry:
+
+```bash
+wrangler auth list
+wrangler auth activate <profile> .
+wrangler whoami --json
+```
+
+The project must already exist. Use a bare public hostname such as
+`www.example.com` for its canonical domain. `--zone-id` is mandatory with
+`--deploy`. You can omit `--account-id` when the active profile has one account.
+
+The generated route covers only the project's exact canonical hostname. It
+does not also cover `www` or the apex. Test and redirect the other hostname
+separately.
+
+A Worker Route can run in front of a Cloudflare Pages custom domain. If the
+origin is another Worker, use a Custom Domain or integrate Canonry into that
+Worker. A same-zone Worker Route cannot be the target of `fetch()`.
+
+Workers Free includes 100,000 requests per account each day. The quota
+resets at midnight UTC. A fail-closed route returns Cloudflare error 1027
+after the account exhausts this quota. A fail-open route bypasses the
+Worker and keeps the origin available. See [Cloudflare Workers limits](https://developers.cloudflare.com/workers/platform/limits/).
+
+Free-plan classification uses user-agent, referer, and UTM evidence. Granular
+`request.cf.botManagement` scores require the Enterprise Bot Management add-on.
+
+### Generate or deploy
+
+```bash
+# Generate secret-free worker.js and wrangler.toml in
+# ./canonry-cloudflare-<project-slug>:
+cnry traffic connect cloudflare <project> \
+  --zone-id <cloudflare-zone-id> \
+  --account-id <cloudflare-account-id>
+
+# Deploy only the Worker after the route preflight.
+# Both safety acknowledgements are mandatory:
+cnry traffic connect cloudflare <project> \
+  --zone-id <cloudflare-zone-id> \
+  --account-id <cloudflare-account-id> \
+  --deploy --confirm-route --confirm-fail-open
+
+# Optional artifact directory / source label:
+cnry traffic connect cloudflare <project> \
+  --display-name "Cloudflare · production" \
+  --output-dir ./infra/canonry-cloudflare
+```
+
+`--confirm-route` acknowledges that you inspected the exact route.
+`--confirm-fail-open` acknowledges that you will configure the required route
+toggle. Canonry does not persist these flags. Neither flag changes Cloudflare.
+
+The command prints the source ID, artifact directory, and manual route steps.
+Keep the source ID for the acceptance test and later diagnosis.
+
+With `--deploy`, Canonry checks Wrangler before it connects the source. The
+preflight uses `--dry-run --secrets-file ... --strict` to parse and bundle
+representative generated artifacts. An incompatible Wrangler stops this step
+before Canonry changes state. The generated `[secrets].required` table is an
+[official Wrangler safety check](https://developers.cloudflare.com/changelog/post/2026-03-24-secrets-config-property/);
+it does not contain secret values.
+
+The generated TOML never declares `[[routes]]`. Thus, Wrangler deploys the
+Worker without placing it on production traffic. After deployment, open
+Cloudflare Dashboard and complete these steps:
+
+1. Open **Workers & Pages → Overview** and select the generated Worker.
+2. Open **Settings → Domains & Routes → Add → Route**.
+3. Select the zone and enter the exact `<canonical-host>/*` route.
+4. Set **Request limit failure mode** to **Fail open**.
+5. Add the route.
+
+Wrangler cannot configure the failure-mode toggle.
+
+The generated source and TOML contain no credential values. Non-secret
+configuration values are Worker vars. The `--account-id` option makes
+connect write `account_id` at the top level.
+
+The bearer and HMAC values stay in the local Canonry credential store.
+They become `CANONRY_BEARER_TOKEN` and `CANONRY_HMAC_SECRET` Worker
+secrets. With `--deploy`, the CLI uses a mode-0600 temporary secrets file.
+Then it invokes Wrangler with `--secrets-file ... --strict` and removes
+the file.
+
+Rerun the same connect command to update an old generated Worker. Canonry
+atomically replaces recognizable Canonry-generated files. It refuses
+operator-owned files and symlinks. Therefore, doctor remediation does not
+require manual file deletion.
+
+Wrangler preflight failures occur before Canonry creates a source. Artifact or
+deployment failures can occur after source creation. Rerun the same command
+with the same output directory. Canonry reuses the source and its credentials.
+
+Cloudflare connect is absent from MCP because deployment reads local
+secrets. An agent can guide the CLI command. It must not request, print,
+or send either secret through chat.
+
+### Direct-push behavior and smoke test
+
+The Worker forwards a request candidate when at least one condition is true:
+
+- Its user-agent matches a known AI crawler or user-fetch agent.
+- Its user-agent contains the broad `bot`, `crawler`, or `spider` keyword.
+- Its referer or `utm_source` matches a known AI product.
+- Bot Management marks it as verified or gives it a score below 30.
+
+The shared Canonry classifier makes the strict classification after delivery.
+Thus, the broad edge filter can send a candidate that produces no rollup.
+
+Direct push observes only requests that reach this Worker. A terminating
+Access, WAF, bot-protection, or AI Crawl Control action can stop a request first.
+For a crawler smoke test, use a narrow exception for only the smoke path when
+the site's security policy permits it. Do not disable site-wide protection.
+
+Direct push has bounded retries for network failures and HTTP 408, 425,
+429, and 5xx responses (250 ms, then 1 s). Delivery is asynchronous and
+never changes the site's response. If Canonry remains unavailable after
+the retry budget, the selected event is lost. Direct push has no durable
+edge buffer. This limit is the primary reason to add Queue pull next.
+
+The receiver accepts at most 256 KiB per request. Its default budgets are
+6,000 requests per minute for each source and each caller IP. A bearer token
+and HMAC protect the route. The HMAC timestamp window is five minutes. A
+transactional receipt protects each event ID for ten minutes. Receipt claims,
+hourly rollups, samples, and source progress commit in one transaction.
+
+Direct push sends one selected event per batch. It does not batch or sample at
+the edge. Canonry stores at most 100 raw samples per source per UTC hour, while
+it continues to add all classified events to hourly rollups.
+
+The Worker transports the raw client IP, full query string, and full referer
+URL for classification. Canonry does not persist these raw values. Raw samples
+store `ipHash: null`, a normalized path without its query, and only the referer
+host. A later privacy change can send only the query parameters that the
+classifier requires.
+
+Raw samples retain the user-agent and normalized path. Do not put personal
+data in URL paths. Canonry replaces numeric, UUID, and long hexadecimal path
+segments with `:id`, but it retains other path segments.
+
+### User acceptance test
+
+1. Choose a stable, harmless origin path and create a unique smoke-run name.
+2. Before route attachment, capture the origin response and source rollups.
+3. Attach the exact route with **Fail open**.
+4. Capture the origin response again. Compare its body and critical headers.
+5. Send four classified requests and one negative control.
+6. Poll the source rollups, inspect the unique paths, and run the doctor.
+
+Replace the example hostname, `<project>`, and `<source-id>` before you run
+these commands:
+
+```bash
+CANONRY_SMOKE_SITE=https://www.example.com
+CANONRY_SMOKE_RUN=run-$(date -u +%Y%m%dT%H%M%SZ)
+CANONRY_SMOKE_PREFIX=/canonry-cloudflare-smoke/$CANONRY_SMOKE_RUN
+CANONRY_SMOKE_DIR=$(mktemp -d)
+
+# Run these commands before route attachment.
+curl -sS -D "$CANONRY_SMOKE_DIR/origin-before.headers" \
+  -o "$CANONRY_SMOKE_DIR/origin-before.body" \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/origin"
+cnry traffic events <project> --source <source-id> \
+  --kind all --since-minutes 120 --limit 5000 --format json \
+  > "$CANONRY_SMOKE_DIR/events-before.json"
+
+# Stop here. Attach the exact route with Fail open, then continue.
+curl -sS -D "$CANONRY_SMOKE_DIR/origin-after.headers" \
+  -o "$CANONRY_SMOKE_DIR/origin-after.body" \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/origin"
+grep -Ei '^(HTTP/|content-type:|cache-control:|location:)' \
+  "$CANONRY_SMOKE_DIR/origin-before.headers" \
+  "$CANONRY_SMOKE_DIR/origin-after.headers"
+cmp "$CANONRY_SMOKE_DIR/origin-before.body" \
+  "$CANONRY_SMOKE_DIR/origin-after.body"
+
+# AI crawler
+curl -sS -o /dev/null -w '%{http_code}\n' -A 'GPTBot/1.2' \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/crawler"
+
+# AI user fetch
+curl -sS -o /dev/null -w '%{http_code}\n' -A 'ChatGPT-User/1.0' \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/user-fetch"
+
+# AI referral by referer
+curl -sS -o /dev/null -w '%{http_code}\n' -A 'Mozilla/5.0 CanonrySmoke' \
+  -e 'https://chatgpt.com/' \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/referral"
+
+# AI referral by UTM
+curl -sS -o /dev/null -w '%{http_code}\n' -A 'Mozilla/5.0 CanonrySmoke' \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/utm?utm_source=chatgpt"
+
+# Negative control: this request must not add a classified traffic rollup
+curl -sS -o /dev/null -w '%{http_code}\n' -A 'Mozilla/5.0 CanonrySmoke' \
+  "$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/control"
+
+# Poll until the deterministic UTM event arrives, for at most 20 seconds.
+for CANONRY_SMOKE_ATTEMPT in 1 2 3 4 5 6 7 8 9 10; do
+  cnry traffic events <project> --source <source-id> \
+    --kind all --since-minutes 120 --limit 5000 --format json \
+    > "$CANONRY_SMOKE_DIR/events-after.json"
+  grep -Fq "$CANONRY_SMOKE_PREFIX/utm" \
+    "$CANONRY_SMOKE_DIR/events-after.json" && break
+  sleep 2
+done
+
+cat "$CANONRY_SMOKE_DIR/events-before.json"
+cat "$CANONRY_SMOKE_DIR/events-after.json"
+
+if grep -Fq "$CANONRY_SMOKE_PREFIX/control" \
+  "$CANONRY_SMOKE_DIR/events-after.json"; then
+  echo 'Unexpected classified control rollup'
+else
+  echo 'Negative control passed'
+fi
+
+cnry doctor --project <project> --check 'traffic.source.*' --format json
+```
+
+The smoke paths can return `404`. The body and critical headers must match the
+no-Worker baseline. When all four selected requests reach the Worker, the
+unique paths must show one crawler, one AI user fetch, and two AI referrals.
+The control path must not appear in a classified rollup. On Bot Management
+plans, a low bot score can still cause its transport.
+
+The crawler request uses a spoofed user agent. It tests forwarding and
+classification only. Canonry reports it as `claimed_unverified` unless the
+client IP belongs to the bot's published IP ranges. If only the crawler path is
+absent, inspect AI Crawl Control, Access, WAF, and other terminating rules. The
+UTM request is the deterministic direct-push transport check.
+
+The events command returns hourly rollups, not raw request records. The doctor
+must report current Worker version and recent traffic.
+
+### Staging release test
+
+1. Cause a receiver failure. Make sure that the origin stays healthy.
+2. Return HTTP `429` from staging and send a bounded bot burst.
+3. Make sure that delivery stops after one request and two retries.
+4. Compare p50 and p95 TTFB before and after route attachment.
+5. Inspect Worker logs. Make sure that logs contain no secret values.
+6. Rehearse rollback and make sure that the origin stays healthy.
+
+A direct-push source does not use `cnry traffic sync` or a traffic-sync
+schedule.
+
+### Rollback and teardown
+
+For a dedicated Canonry-generated Worker:
+
+1. Detach the exact site route from the Worker.
+2. Request an ordinary site page. Make sure that the origin status,
+   headers, and body remain healthy.
+3. Run `wrangler delete --config <artifact-directory>/wrangler.toml`.
+4. Stop the tunnel if no other integration uses it.
+5. Run the doctor. Expect source-health warnings until Canonry supports
+   Cloudflare disconnect.
+
+If Canonry code shares an existing Worker, remove only the Canonry code and
+bindings. Redeploy the prior Worker version. Do not delete the shared Worker.
+
+The current CLI and API have no Cloudflare disconnect operation. The source
+row and local credential store remain after teardown. A follow-up must add
+source archival and local credential cleanup.
+
+### Cloudflare troubleshooting
+
+| Symptom | Action |
+|---|---|
+| Wrangler preflight fails | Install the latest Wrangler. Run `wrangler whoami`. Then rerun connect. |
+| Worker deploys to the wrong account | Make the correct Wrangler profile active. Pass the matching `--account-id`. |
+| Route cannot attach | Make sure that the zone is active, DNS is proxied, and the exact route is unclaimed. Inspect every overlapping route. |
+| Receiver probe returns `403` | Remove the Access or WAF challenge from the exact ingest path. |
+| Worker log shows ingest `401` | Rerun connect from the credential-owning host. Make sure that system clocks differ by less than five minutes. |
+| No events arrive | Make sure that the route matches the exact host and `publicUrl` is reachable. Inspect AI Crawl Control, Access, WAF, and route precedence. Then send the UTM smoke request. |
+| Some paths are absent | Inspect more-specific routes and terminating security rules. Integrate Canonry into those routes or document the excluded coverage. |
+| Ingest returns `429` | Wait for the rate window. The Worker retries twice, then drops the event. |
+| Site returns Cloudflare error `1027` | Set the route to **Fail open**, or detach it. The account exhausted its daily Worker requests. |
+| Doctor reports stale or empty direct-push data | Do not run `traffic sync`. Inspect the route, receiver, and Worker logs. Then repeat the smoke request. |
+
+### Queue pull seam (not shipped yet)
+
+Queue pull is the first follow-up for hosted or platform deployments with
+loopback-only tenant engines. Customer Workers cannot reach those engines.
+The future pull adapter will let Canonry read events without a public
+tenant-ingest endpoint.
+
+Before broad direct-push rollout, consider an edge sampling or batching control
+for high-volume generic bot traffic.
+
+`deliveryMode: direct-push` is explicit in the source config. The reserved
+`queue-pull` mode will keep the Worker filter, `CloudflareEdgeEventBatch`,
+canonical JSON encoding, normalizer, classifier, and rollups unchanged.
+Only delivery changes to a Queue binding, and Canonry gains a polling
+adapter. A source must use one mode at a time so the same edge event cannot
+arrive through both transports and double-count.
+
 ## Syncing data
 
 ```bash
@@ -282,8 +706,8 @@ schema change, the stored rollups are untouched.
 | Project dashboard `/projects/:name/activity` | Live source table + 24h totals + GA4 referrals (combined view) |
 | Top-level `/traffic` route | Cross-project source admin (connect, sync, archive) |
 | `cnry report <project>` (HTML + SPA) | "AI Visibility — Server-Side" section, ranked above Indexing Health |
-| `cnry doctor --project <name>` | `traffic.source.connected`, `recent-data`, `credentials`, `scopes`, `cache-blindspot` checks |
-| MCP toolkit `traffic` | Tools: `canonry_traffic_status`, `_sources_list`, `_source_get`, `_events`, `_connect_cloud_run`, `_sync` |
+| `cnry doctor --project <name>` | Source health checks, including Cloudflare `traffic.source.worker-version` deployment drift |
+| MCP toolkit `traffic` | Read/status tools plus pull-source setup/sync tools. Cloudflare connect is local-CLI-only so Worker secrets cannot enter an MCP transcript. |
 
 ## Doctor signals
 
@@ -293,14 +717,23 @@ The doctor checks are adapter-agnostic. When they fail or warn:
 |---|---|---|
 | `traffic.source.connected` | `traffic.source.none` | No source — `cnry traffic connect cloud-run …` |
 | `traffic.source.connected` | `traffic.source.all-errored` | Re-connect the source. The check's `details.lastError` shows the underlying reason. |
-| `traffic.source.recent-data` | `traffic.recent-data.stale` | Last sync was >7d ago. Run `cnry traffic sync …` or schedule a recurring sync. |
-| `traffic.source.recent-data` | `traffic.recent-data.empty` | Source connected but no data in 30d. Verify config and credentials with `cnry traffic sources <project>`. |
-| `traffic.source.credentials` | `traffic.credentials.resolve-failed` | Service-account key in `~/.canonry/config.yaml` is invalid or expired. Re-connect. |
+| `traffic.source.recent-data` | `traffic.recent-data.stale` | For pull sources, run `cnry traffic sync …`. For Cloudflare direct push, inspect the route and receiver. |
+| `traffic.source.recent-data` | `traffic.recent-data.empty` | Inspect source configuration. For Cloudflare direct push, send the UTM smoke request and inspect Worker logs. |
+| `traffic.source.credentials` | `traffic.credentials.resolve-failed` | Reconnect from the host that owns the source credentials. |
 | `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.worker-version` | `traffic.worker-version.waiting-for-first-event` | Send a smoke-test request through the Worker. Then run the doctor again. |
+| `traffic.source.worker-version` | `traffic.worker-version.stale` | Redeploy the generated Worker from the credential-owning host. Use `--deploy --confirm-route --confirm-fail-open`. Attach the route manually. |
+
+Cloudflare doctor behavior is capability-driven: only
+`deliveryMode=direct-push` (and legacy Cloudflare rows with no mode) skips
+pull-watermark lag. The same mode enables `traffic.source.worker-version`.
+That check compares `configJson.workerVersion` with `lastWorkerVersion`.
+The reserved Queue pull mode uses pull checks and skips the version check.
 
 ## Scheduling
 
-`cnry schedule` supports `--kind traffic-sync`. Recurring syncs are
+`cnry schedule` supports `--kind traffic-sync` for pull sources. Cloudflare
+direct push is event-driven and must not receive a traffic-sync schedule. Recurring syncs are
 safe because of the `last_event_ids` cross-sync dedupe ring buffer
 described above. Recommended cadence:
 
@@ -358,15 +791,15 @@ domains, or PII are surfaced.
   treat the report's crawled-paths table as "engine attention" — the
   signal is the bot fetched it, not whether it was cited.
 - **Verified vs unverified.** The headline numbers count only
-  rDNS-verified hits. Unverified bots claim a known UA but couldn't be
-  cross-confirmed via reverse-DNS — they may be the real bot or an
-  imitator. Don't promote unverified counts in client-facing copy.
+  published-IP-range-verified hits. Unverified bots claim a known UA but
+  do not match the operator's published IP ranges. The bot can be real or an
+  imitator. Do not promote unverified counts in client-facing copy.
   **Vercel sources are a special case:** the Vercel pull API returns
   no client IP, so every Vercel crawler hit is unverified by
   construction (UA-only). A Vercel source reading 100% unverified is
   expected, not a misconfiguration.
-- **Three adapters shipped (Cloud Run + WordPress + Vercel); more
-  planned.** The doctor checks and the report renderer are
+- **Four adapters ship: Cloud Run, WordPress, Vercel, and Cloudflare
+  direct push. More adapters are planned.** The doctor checks and report renderer are
   adapter-agnostic — adding a new adapter is just a new entry in
   `traffic_sources.source_type` and a `TrafficSourceValidator`
   registration.

package/assets/assets/{AuditHistoryPanel-gmJMVlXX.js → AuditHistoryPanel-McQfjoU9.js}

@@ -1 +1 @@
-import{r as a,u as h,j as e}from"./vendor-tanstack-pFxw0eGP.js";import{cs as L,ct as P,bN as E,k as u,B as x,d as v,T as k}from"./index-DP-fT2uI.js";const o=100;function M(s){if(s==="all")return;const n=Number.parseInt(s,10);return new Date(Date.now()-n*24*60*60*1e3).toISOString()}function O(s){const n=s.userAgent?.toLowerCase()??"";return n.includes("canonry-mcp")?"MCP":n.includes("canonry-cli")?"CLI":n.includes("mozilla/")?"Dashboard":s.actor==="scheduler"?"Scheduler":s.actor==="agent"?"Agent":s.actor==="mcp"?"MCP":s.actor==="cli"?"CLI":s.actor}function B(s){return/delete|remove|revoke|disconnect|failed/.test(s)?"negative":/create|add|connect|completed/.test(s)?"positive":/update|replace|sync|apply/.test(s)?"caution":"neutral"}function D(s){return[s.action,s.actor,s.entityType,s.entityId,s.actorSession,s.userAgent,s.diff==null?"":JSON.stringify(s.diff)].filter(Boolean).join(" ").toLowerCase()}function H({projectName:s}){const[n,l]=a.useState(0),[c,y]=a.useState("90d"),[m,N]=a.useState(""),[p,w]=a.useState(""),S=a.useMemo(()=>M(c),[c]),g={limit:o,offset:n*o,since:S,actor:m||void 0},C=h({...L({client:u,path:{name:s??""},query:g}),enabled:!!s}),A=h({...P({client:u,query:g}),enabled:!s}),f=h({...E({client:u}),enabled:!s}),i=s?C:A,r=i.data??[],I=a.useMemo(()=>new Map((f.data??[]).map(t=>[t.id,t.displayName||t.name])),[f.data]),d=p.trim().toLowerCase(),j=a.useMemo(()=>d?r.filter(t=>D(t).includes(d)):r,[r,d]),b=t=>{l(0),t()};return i.isLoading?e.jsx("p",{className:"supporting-copy mt-6",role:"status",children:"Loading change history…"}):e.jsxs("section",{className:"mt-6","aria-labelledby":"change-history-heading",children:[e.jsxs("div",{className:"section-head section-head-inline",children:[e.jsxs("div",{children:[e.jsx("p",{className:"eyebrow eyebrow-soft",children:"Audit trail"}),e.jsx("h2",{id:"change-history-heading",children:"Change history"}),e.jsx("p",{className:"supporting-copy mt-1 max-w-2xl",children:"Configuration and operator actions. Execution outcomes remain in Runs."})]}),e.jsx(x,{type:"button",variant:"outline",size:"sm",onClick:()=>{i.refetch()},disabled:i.isFetching,children:i.isFetching?"Refreshing…":"Refresh"})]}),e.jsxs("div",{className:"mt-4 grid gap-2 sm:grid-cols-3",children:[e.jsx("input",{type:"search","aria-label":"Search change history",value:p,onChange:t=>w(t.target.value),placeholder:"Search actions, entities, or details",className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong placeholder-mono-600 focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600"}),e.jsxs("select",{"aria-label":"Filter change history by actor",value:m,onChange:t=>b(()=>N(t.target.value)),className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600",children:[e.jsx("option",{value:"",children:"All actors"}),e.jsx("option",{value:"api",children:"API and dashboard"}),e.jsx("option",{value:"cli",children:"CLI"}),e.jsx("option",{value:"scheduler",children:"Scheduler"}),e.jsx("option",{value:"agent",children:"Agent"}),e.jsx("option",{value:"mcp",children:"MCP"})]}),e.jsxs("select",{"aria-label":"Filter change history by date range",value:c,onChange:t=>b(()=>y(t.target.value)),className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600",children:[e.jsx("option",{value:"30d",children:"Last 30 days"}),e.jsx("option",{value:"90d",children:"Last 90 days"}),e.jsx("option",{value:"365d",children:"Last year"}),e.jsx("option",{value:"all",children:"All retained history"})]})]}),i.isError?e.jsxs(v,{className:"surface-card empty-card mt-4",children:[e.jsx("h3",{children:"Change history unavailable"}),e.jsx("p",{children:i.error instanceof Error?i.error.message:"Could not load the audit trail."})]}):j.length===0?e.jsxs(v,{className:"surface-card empty-card mt-4",children:[e.jsx("h3",{children:"No changes match these filters"}),e.jsx("p",{children:"Widen the date range or clear the actor and search filters."})]}):e.jsx("div",{className:"evidence-table-wrap mt-4",children:e.jsxs("table",{className:"evidence-table",children:[e.jsx("thead",{children:e.jsxs("tr",{children:[e.jsx("th",{children:"When"}),s?null:e.jsx("th",{children:"Scope"}),e.jsx("th",{children:"Action"}),e.jsx("th",{children:"Entity"}),e.jsx("th",{children:"Origin"}),e.jsx("th",{children:"Details"})]})}),e.jsx("tbody",{children:j.map(t=>e.jsxs("tr",{children:[e.jsx("td",{className:"whitespace-nowrap tabular-nums text-muted",children:new Date(t.createdAt).toLocaleString()}),s?null:e.jsx("td",{className:"text-secondary",children:t.projectId?I.get(t.projectId)??`Deleted project · ${t.projectId}`:"Instance settings"}),e.jsx("td",{children:e.jsx(k,{tone:B(t.action),children:t.action})}),e.jsxs("td",{children:[e.jsx("span",{className:"text-strong",children:t.entityType}),t.entityId?e.jsx("span",{className:"mt-0.5 block max-w-48 truncate font-mono text-[11px] text-faint",title:t.entityId,children:t.entityId}):null]}),e.jsxs("td",{children:[e.jsx("span",{className:"text-secondary",children:O(t)}),t.actorSession?e.jsxs("span",{className:"mt-0.5 block max-w-40 truncate font-mono text-[11px] text-faint",title:t.actorSession,children:["Session ",t.actorSession]}):null]}),e.jsx("td",{children:t.diff==null?e.jsx("span",{className:"text-faint",children:"No field diff"}):e.jsxs("details",{children:[e.jsx("summary",{className:"min-h-11 cursor-pointer py-3 text-sm text-secondary hover:text-strong",children:"View diff"}),e.jsx("pre",{className:"max-h-72 max-w-xl overflow-auto whitespace-pre-wrap break-words rounded-md bg-bg-elevated p-3 text-xs text-secondary",children:JSON.stringify(t.diff,null,2)})]})})]},t.id))})]})}),!i.isError&&(n>0||r.length===o)?e.jsxs("div",{className:"mt-4 flex items-center justify-between gap-3",children:[e.jsx(x,{type:"button",variant:"outline",size:"sm",disabled:n===0,onClick:()=>l(t=>Math.max(0,t-1)),children:"Previous"}),e.jsxs("span",{className:"text-xs tabular-nums text-muted",children:["Page ",n+1]}),e.jsx(x,{type:"button",variant:"outline",size:"sm",disabled:r.length<o,onClick:()=>l(t=>t+1),children:"Next"})]}):null]})}export{H as A};
+import{r as a,u as h,j as e}from"./vendor-tanstack-pFxw0eGP.js";import{cv as L,cw as P,bQ as E,k as u,B as x,d as v,T as k}from"./index-DUfg50Pl.js";const o=100;function M(s){if(s==="all")return;const n=Number.parseInt(s,10);return new Date(Date.now()-n*24*60*60*1e3).toISOString()}function O(s){const n=s.userAgent?.toLowerCase()??"";return n.includes("canonry-mcp")?"MCP":n.includes("canonry-cli")?"CLI":n.includes("mozilla/")?"Dashboard":s.actor==="scheduler"?"Scheduler":s.actor==="agent"?"Agent":s.actor==="mcp"?"MCP":s.actor==="cli"?"CLI":s.actor}function B(s){return/delete|remove|revoke|disconnect|failed/.test(s)?"negative":/create|add|connect|completed/.test(s)?"positive":/update|replace|sync|apply/.test(s)?"caution":"neutral"}function D(s){return[s.action,s.actor,s.entityType,s.entityId,s.actorSession,s.userAgent,s.diff==null?"":JSON.stringify(s.diff)].filter(Boolean).join(" ").toLowerCase()}function F({projectName:s}){const[n,l]=a.useState(0),[c,y]=a.useState("90d"),[m,N]=a.useState(""),[p,w]=a.useState(""),S=a.useMemo(()=>M(c),[c]),g={limit:o,offset:n*o,since:S,actor:m||void 0},C=h({...L({client:u,path:{name:s??""},query:g}),enabled:!!s}),A=h({...P({client:u,query:g}),enabled:!s}),f=h({...E({client:u}),enabled:!s}),i=s?C:A,r=i.data??[],I=a.useMemo(()=>new Map((f.data??[]).map(t=>[t.id,t.displayName||t.name])),[f.data]),d=p.trim().toLowerCase(),j=a.useMemo(()=>d?r.filter(t=>D(t).includes(d)):r,[r,d]),b=t=>{l(0),t()};return i.isLoading?e.jsx("p",{className:"supporting-copy mt-6",role:"status",children:"Loading change history…"}):e.jsxs("section",{className:"mt-6","aria-labelledby":"change-history-heading",children:[e.jsxs("div",{className:"section-head section-head-inline",children:[e.jsxs("div",{children:[e.jsx("p",{className:"eyebrow eyebrow-soft",children:"Audit trail"}),e.jsx("h2",{id:"change-history-heading",children:"Change history"}),e.jsx("p",{className:"supporting-copy mt-1 max-w-2xl",children:"Configuration and operator actions. Execution outcomes remain in Runs."})]}),e.jsx(x,{type:"button",variant:"outline",size:"sm",onClick:()=>{i.refetch()},disabled:i.isFetching,children:i.isFetching?"Refreshing…":"Refresh"})]}),e.jsxs("div",{className:"mt-4 grid gap-2 sm:grid-cols-3",children:[e.jsx("input",{type:"search","aria-label":"Search change history",value:p,onChange:t=>w(t.target.value),placeholder:"Search actions, entities, or details",className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong placeholder-mono-600 focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600"}),e.jsxs("select",{"aria-label":"Filter change history by actor",value:m,onChange:t=>b(()=>N(t.target.value)),className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600",children:[e.jsx("option",{value:"",children:"All actors"}),e.jsx("option",{value:"api",children:"API and dashboard"}),e.jsx("option",{value:"cli",children:"CLI"}),e.jsx("option",{value:"scheduler",children:"Scheduler"}),e.jsx("option",{value:"agent",children:"Agent"}),e.jsx("option",{value:"mcp",children:"MCP"})]}),e.jsxs("select",{"aria-label":"Filter change history by date range",value:c,onChange:t=>b(()=>y(t.target.value)),className:"min-h-11 rounded-md border border-base bg-bg px-3 text-sm text-strong focus:outline-none focus-visible:ring-1 focus-visible:ring-mono-600",children:[e.jsx("option",{value:"30d",children:"Last 30 days"}),e.jsx("option",{value:"90d",children:"Last 90 days"}),e.jsx("option",{value:"365d",children:"Last year"}),e.jsx("option",{value:"all",children:"All retained history"})]})]}),i.isError?e.jsxs(v,{className:"surface-card empty-card mt-4",children:[e.jsx("h3",{children:"Change history unavailable"}),e.jsx("p",{children:i.error instanceof Error?i.error.message:"Could not load the audit trail."})]}):j.length===0?e.jsxs(v,{className:"surface-card empty-card mt-4",children:[e.jsx("h3",{children:"No changes match these filters"}),e.jsx("p",{children:"Widen the date range or clear the actor and search filters."})]}):e.jsx("div",{className:"evidence-table-wrap mt-4",children:e.jsxs("table",{className:"evidence-table",children:[e.jsx("thead",{children:e.jsxs("tr",{children:[e.jsx("th",{children:"When"}),s?null:e.jsx("th",{children:"Scope"}),e.jsx("th",{children:"Action"}),e.jsx("th",{children:"Entity"}),e.jsx("th",{children:"Origin"}),e.jsx("th",{children:"Details"})]})}),e.jsx("tbody",{children:j.map(t=>e.jsxs("tr",{children:[e.jsx("td",{className:"whitespace-nowrap tabular-nums text-muted",children:new Date(t.createdAt).toLocaleString()}),s?null:e.jsx("td",{className:"text-secondary",children:t.projectId?I.get(t.projectId)??`Deleted project · ${t.projectId}`:"Instance settings"}),e.jsx("td",{children:e.jsx(k,{tone:B(t.action),children:t.action})}),e.jsxs("td",{children:[e.jsx("span",{className:"text-strong",children:t.entityType}),t.entityId?e.jsx("span",{className:"mt-0.5 block max-w-48 truncate font-mono text-[11px] text-faint",title:t.entityId,children:t.entityId}):null]}),e.jsxs("td",{children:[e.jsx("span",{className:"text-secondary",children:O(t)}),t.actorSession?e.jsxs("span",{className:"mt-0.5 block max-w-40 truncate font-mono text-[11px] text-faint",title:t.actorSession,children:["Session ",t.actorSession]}):null]}),e.jsx("td",{children:t.diff==null?e.jsx("span",{className:"text-faint",children:"No field diff"}):e.jsxs("details",{children:[e.jsx("summary",{className:"min-h-11 cursor-pointer py-3 text-sm text-secondary hover:text-strong",children:"View diff"}),e.jsx("pre",{className:"max-h-72 max-w-xl overflow-auto whitespace-pre-wrap break-words rounded-md bg-bg-elevated p-3 text-xs text-secondary",children:JSON.stringify(t.diff,null,2)})]})})]},t.id))})]})}),!i.isError&&(n>0||r.length===o)?e.jsxs("div",{className:"mt-4 flex items-center justify-between gap-3",children:[e.jsx(x,{type:"button",variant:"outline",size:"sm",disabled:n===0,onClick:()=>l(t=>Math.max(0,t-1)),children:"Previous"}),e.jsxs("span",{className:"text-xs tabular-nums text-muted",children:["Page ",n+1]}),e.jsx(x,{type:"button",variant:"outline",size:"sm",disabled:r.length<o,onClick:()=>l(t=>t+1),children:"Next"})]}):null]})}export{F as A};