[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_792":793,"_794":795},"routes/_app.x.$handle.$name",{"_102":101,"_33":47,"_111":92,"_28":112,"_13":14,"_113":-5,"_11":114,"_115":116,"_117":118,"_119":120,"_121":122,"_20":-5,"_123":-5,"_124":-5,"_125":27,"_126":127,"_128":25,"_129":-5,"_130":-5,"_131":132},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_45":46,"_33":47,"_40":48,"_49":-5,"_50":27,"_51":52,"_53":52,"_54":55,"_56":57,"_18":58,"_59":60,"_61":25,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":76,"_77":76,"_78":79,"_80":79,"_81":79,"_82":76,"_83":76,"_84":85,"_86":87,"_88":89,"_90":27},"version",238,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":27,"_28":29,"_30":29},"file",{"_31":32,"_33":34,"_35":36,"_37":39,"_40":41,"_42":14,"_43":44,"_24":27},"previous",{"_31":32,"_33":34,"_35":36,"_37":38},"deleted",true,"deletedHere",false,"path","src/mcp/skills/canonry-skill.0.ts","latestPath","fileId","948d0a42-a63e-11f1-a470-1607ee4eb77e","name","canonry-skill.0.ts","fileType","script","content","// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: canonry\\ndescription: \\\"Operate Canonry (the `cnry` / `canonry` CLI) for AEO. Load this BEFORE any canonry operator task: creating or configuring a project, connecting GSC, GA4, Bing, Google Business Profile or a Cloudflare traffic source, running or scheduling a sweep, reading mention and citation coverage, running a technical audit, submitting sitemaps, or diagnosing why a number moved. Covers anything touching cnry, canonry doctor, ~/.canonry, @canonry/canonry, the canonry_* MCP tools, mention share, or direct-push / queue-pull traffic. Load it before acting, not after something fails.\\\"\\ncompatibility: Requires Node.js 22.14+ and globally installed @canonry/canonry; canonry-mcp must be on PATH.\\nmetadata:\\n agent: >-\\n {\\\"emoji\\\":\\\"📡\\\",\\\"requires\\\":{\\\"bins\\\":[\\\"canonry\\\"]},\\\"install\\\":[{\\\"id\\\":\\\"npm\\\",\\\"kind\\\":\\\"npm\\\",\\\"package\\\":\\\"@canonry/canonry\\\",\\\"bins\\\":[\\\"canonry\\\"],\\\"label\\\":\\\"Install canonry globally\\\",\\\"command\\\":\\\"npm install -g @canonry/canonry\\\"}]}\\n---\\n\\n# Canonry\\n\\nAgent-first open-source AEO (Answer Engine Optimization) operating platform. Track how AI answer engines **mention** your brand in answers and **cite** your domain in sources across Gemini, ChatGPT, Claude, and Perplexity, then act on the signal through the content engine and integrations.\\n\\n**Website:** [canonry.ai](https://canonry.ai) | **Docs:** [github.com/Canonry/canonry](https://github.com/Canonry/canonry)\\n\\n**CLI:** invoke as `cnry` (short form) or `canonry` — both ship with the npm package and are interchangeable. Examples in this skill use `cnry`.\\n\\n## Runtime Preflight\\n\\nBefore using the native Codex or Claude Code plugin, verify the separately\\ninstalled Canonry runtime. It requires Node.js 22.14 or newer, and the native\\nplugin specifically needs the global package so `canonry-mcp` remains on\\n`PATH`; a one-off `npx` invocation is not sufficient:\\n\\n```bash\\nnode --version\\ncommand -v cnry\\ncnry --version\\n```\\n\\nThen prepare the runtime in this order:\\n\\n1. With approval, install the global runtime if `command -v cnry` failed.\\n2. Check only whether `$CANONRY_CONFIG_DIR/config.yaml` (when that variable is\\n set) or `~/.canonry/config.yaml` exists; do not print the file. If it does\\n not exist, pause and ask the operator to run `cnry init --skip-skills --skip-mcp`\\n in their own private terminal, then confirm completion without\\n pasting the output. Never execute `init` inside the agent session: it prompts\\n for provider credentials and prints the new full-access API key once. The\\n plugin already supplies the skills and MCP registration.\\n3. After a fresh initialization, get approval and run `cnry start --format\\n json`; `start` waits for the health endpoint before returning. On an\\n existing installation, try the doctor command first and start only when the\\n transport is unavailable. Never stop or restart a healthy daemon just to\\n install the plugin.\\n4. Run `cnry doctor --format json` after the daemon is ready. A successful JSON\\n response proves the health-check path works; individual checks may still\\n report actionable `warn` or `fail` statuses. Plugin installation state is\\n read live, so installing the plugin alone does not require a daemon restart.\\n\\nNever ask the operator to paste credentials into the chat, print the raw API\\nkey, or inspect `~/.canonry/config.yaml` for secrets. The plugin does not expand\\nthe configured key's server-enforced scope, but it gives the client tools that\\ncan exercise that scope. Fresh `cnry init` creates a full-instance `*` key, so\\nthe default plugin has teammate-level access to every project and shared\\ninstance settings. A write-capable key exposes write tools by default; a\\nread-only key restricts the catalog to reads, while a project-scoped key keeps\\nits project route boundary but is not tenant isolation: a write-capable scoped\\nkey can still mutate shared instance settings. Do not work around a missing\\ntool or `403` by switching credentials.\\n\\n## When to Use\\n\\n- Tracking brand **mentions** in AI answer text and **citations** in source links across providers\\n- Expanding the tracked-query basket from an ICP description (`cnry discover run`)\\n- Running technical SEO audits (14‑factor scoring)\\n- Implementing structured data (JSON‑LD)\\n- Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools\\n- Wiring server-side traffic (Cloudflare, Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal\\n- Inspecting Google Ads conversion goals and GTM live configuration as read-only conversion evidence\\n- Optimizing `llms.txt`, sitemaps, robots.txt for AI crawlers\\n- Submitting URLs to Google Indexing API and Bing IndexNow\\n- Analyzing competitor citation patterns\\n- Operating guarded ChatGPT ads lifecycle changes and reconciling unresolved mutation receipts\\n\\n## Core Philosophy\\n\\n- **Measure outcomes** — AI models are black boxes; track mentions + citations, don't assume causality\\n- **Signal over noise** — Focus on high‑intent queries; avoid granular targeting until base visibility exists\\n- **CLI‑native** — API‑driven changes over manual CMS clicks; faster, repeatable, auditable\\n- **Recover before retrying ads writes** — Page through `pending`, `unknown`, and `reconciling` receipts. Resume `campaign_tree_activate` through its bodyless exact-executor recovery operation; reconcile other supported receipts by verifying the checkpointed provider ID on the receipt-bound account. Never resend a mutation under a different key; an uncheckpointed create remains unresolved. A fresh pending generic receipt waits for its minimum-idle window, inconclusive reads back off, and a quarantined receipt requires human remediation.\\n- **Separate approval from ads execution** — A human with `ads.approve` creates a short-lived grant for the exact paused campaign tree and a different executor key. The operator may activate only that tree with `ads.activate`; it cannot mint or widen its own approval.\\n\\n## What Canonry Measures (Vocabulary)\\n\\nTwo parallel signals are tracked per (query × provider) snapshot. They are independent — a model can do either, both, or neither — never conflate them.\\n\\n| Term | Means | Headline metric |\\n|---|---|---|\\n| **mentioned** | The project's brand or domain appears in the LLM's **answer text** (the prose the model returns). | **Mention Coverage** — share of (query × provider) snapshots where the brand was mentioned. **Mention Share** is the project's share among the cited+mentioned set vs competitors. |\\n| **cited** | The project's domain appears in the LLM's **source links** (the grounding citations returned alongside the answer). | **Citation Coverage** — share of snapshots where the domain was in the source list. |\\n\\nConfigure `spec.brandAliases` on the project (or pass via `cnry apply`) so the mention detector catches \\\"Meta\\\" alongside \\\"Facebook\\\", etc. The downloadable report (`cnry report`) and the dashboard both lead with Mention Coverage; Citation Coverage rides as the secondary gauge.\\n\\n## How to Operate\\n\\nA canonry engagement follows the same loop regardless of project size:\\n\\n1. **Diagnose** — After explicit approval for the quota-consuming persisted runs, run a baseline sweep (`cnry run --wait`) and a technical audit (`cnry technical-aeo run --wait`, then `cnry technical-aeo score --format json`). Use `cnry site-health overview --format json` only to add crawl metadata; it never replaces the score. The audit discovers the in-scope site from the root, sitemaps, and internal links, persists the crawl graph and score, and keeps dead-link checks off unless explicitly requested. Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.\\n2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.\\n3. **Execute** — Apply fixes via the canonry CLI or platform integrations. Use `--dry-run` on supported mutations (`cnry project delete`, `cnry query replace`, `cnry backfill ...`) to preview before committing. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.\\n4. **Monitor** — Re-run sweeps weekly only through an operator-approved schedule or after fresh explicit approval (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.\\n5. **Report** — Lead with data, not interpretation: \\\"Lost the mention for `` on Gemini between and — two competitors moved in. Here's what to fix.\\\" For a one-command client-facing summary, run `cnry report ` to generate a self-contained HTML bundle (mention + citation hero, competitor landscape, GSC + GA4 performance, insights, suggested next queries). Same payload is available via `--format json` and the `canonry_report` MCP tool.\\n\\n**Verifying without polluting metrics**: when a test would help — \\\"did the latest provider deploy work?\\\", \\\"is this regression reproducible?\\\", \\\"would this query actually surface us?\\\" — propose the exact provider/query and get explicit approval before using `cnry run --probe --provider

--query \\\"...\\\"`. Probe runs still cost quota and write a snapshot, but are excluded from the dashboard, analytics, intelligence, report, and notifications. Approval for one probe does not authorize repeats unless the operator approved a bounded batch; use real sweeps only when the operator wants the data to feed metrics.\\n\\n## Surgical Reads\\n\\nWhen you need a specific value rather than a full payload, use the dot-path getter:\\n\\n```bash\\ncnry get scores.mentionShare.value\\ncnry get scores.mentionCoverage.value\\ncnry get insights[0].severity\\ncnry get --from report scores.citationCoverage.value\\n```\\n\\n`cnry get` resolves a path into the project's overview (default) or any registered source (`report`, `traffic`, `discovery`, etc.). Returns scalar values without forcing the agent to grep through a 30 KB JSON dump.\\n\\n## Common Starting Points\\n\\n- **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent queries. See `references/indexing.md`.\\n- **Established site, regression** → diff canonry runs to find the loss window; verify schema is intact; resubmit affected URLs. See `references/aeo-analysis.md`.\\n- **Empty / generic query basket** → describe the ICP and let discovery expand: `cnry discover run --icp \\\"...\\\" --wait`, then `cnry discover promote ` to adopt the cited + aspirational queries. Multi-location projects can geo-constrain with `--locations `.\\n- **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county queries until base visibility exists.\\n\\n## Google Analytics 4\\n\\nGA4 is a first-class signal alongside citation tracking. Connect once with `cnry ga connect --property-id --key-file `; `cnry ga sync` then pulls daily landing-page traffic, AI-referral sessions across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), and social referrals split into Organic vs Paid via GA4's `channelGroup` — and persists everything into four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`). All read commands query that local store, so they are fast and quotaless once a sync has run. AI referrals are tracked across three GA4 attribution dimensions (session source / first-user source / manual UTM) and joined to landing pages, so you can see which page each AI provider sent traffic to. Use `cnry ga traffic` for the current snapshot, `cnry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `cnry ga ai-referral-history` / `cnry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.\\n\\n## Google Ads and GTM\\n\\nGoogle Ads and GTM are separate, project-scoped sources for one conversion\\ncontract. Provider snapshots are static configuration evidence. They do not\\nprove browser events, tag firing, or recorded conversions. Stored snapshots are\\nthe safe default. A bounded live read needs `google-marketing.read-live`. Version\\n1 does not mutate Google Ads or edit, version, or publish GTM. Read\\n`references/google-marketing.md` before assessing or refreshing this evidence.\\nThe operator must complete OAuth, resource selection, and contract creation.\\nNever request OAuth credentials or a Google Ads developer token.\\n\\n## Server-Side Traffic\\n\\nWhen the project ships behind a server you control, connect Cloud Run, WordPress,\\nor Vercel. `cnry traffic sync` pulls and classifies their logs into hourly\\nbuckets. For Cloudflare, choose `direct-push` or `queue-pull` on the local,\\ncredential-owning host. Direct push requires a public Canonry HTTPS receiver.\\nIt does not use `traffic sync`. Queue pull sends events to a Cloudflare Queue,\\nthen Canonry drains it through `traffic sync` and the `traffic-sync` schedule.\\n\\nIf the connect response reports `activationRequired`, attach the Worker route\\nfirst. Then run `cnry traffic activate --source `. Activation\\npauses all sibling sources. It also moves the one `traffic-sync` schedule to\\nQueue pull. A first source becomes active automatically.\\n\\nEach default Queue tick drains at most 1,000 messages. Use `cnry traffic status`\\nand the `traffic.source.queue-backlog` doctor check to read the backlog. If more\\nthan 1,000 messages remain, get approval before a manual sync or a shorter\\nschedule interval. Use `cnry traffic events`, `cnry traffic sources`, and\\n`cnry traffic status` for every adapter. See\\n`references/server-side-traffic.md` for setup and smoke tests.\\n\\n**WordPress safety:** incremental pulls are fixed `[since, until)` windows; a\\nnew or idle source begins at the plugin's 365-day maximum retention horizon.\\nCanonry rejects an endpoint that returns events outside that window. Keep\\nexisting WordPress rollups intact: generic replace-mode backfill is unavailable\\nuntil a retention-aware repair can prove coverage and declare any unrecoverable\\nspan.\\n\\n**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 --source --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 --source --advance-to-now`.\\n\\n## Local AEO (Google Business Profile)\\n\\nFor businesses with a physical location or service area, Google Business Profile is the local-AEO signal source — reviews, search-keyword impressions, daily performance metrics, and (for hotels) structured amenities + booking CTAs all feed how AI engines answer local-intent queries. Connect with `cnry gbp connect `, discover locations with `cnry gbp locations discover `, and pick which sync with `cnry gbp locations select/deselect`.\\n\\n**Hard prerequisites and gotchas — read `references/google-business-profile.md` before attempting setup:** GBP requires a Google access-form approval (0 QPM until granted), the only OAuth scope is the write-capable `business.manage`, **reviews live on a separately-gated legacy v4 API that the Basic approval does NOT grant** (and can't be self-enabled), and the **Q&A API was retired (2025-11-03)**. Keyword data is heavily privacy-redacted (often 100% for small businesses); an empty place-action profile is a real AEO finding to surface, but an empty lodging result is a verify-not-a-gap (the Lodging API can return 0 readable groups even when the owner-facing \\\"Hotel details\\\" panel has amenities set). The reference doc has the full setup walkthrough, the real-world data shapes, and the troubleshooting matrix.\\n\\n## Built-in Analyst (Aero)\\n\\nCanonry ships a built-in agent — Aero — for users who don't already have one. Drive it from the CLI:\\n\\n```bash\\ncnry agent ask \\\"what changed since the last sweep?\\\"\\ncnry agent ask \\\"...\\\" --provider claude --scope read-only\\ncnry agent memory list # durable project notes\\n```\\n\\nAero also wakes unprompted after every `run.completed` so insights and regressions get analyzed without a user click. Users who already run their own agent (Claude Code, Codex, custom) wire webhooks instead: `cnry agent attach --url ` subscribes to `run.completed`, `insight.critical`, `insight.high`, `citation.gained`.\\n\\n## Boundaries & Safety\\n\\n- **Get explicit approval before every mutation or quota-consuming sweep.** Also get approval before each live provider read. Stored reads and `--dry-run` previews are safe defaults.\\n- **Never touch live WordPress without explicit approval**\\n- **Back up `~/.canonry/config.yaml` before any config edit**\\n- **Never fabricate mention or citation data** — if a sweep hasn't run, say so; never coerce `answerMentioned` null → false (null = \\\"not checked\\\")\\n- **Client data stays private** — canonry repo is public; no real domains in issues\\n- **Respect API rate limits** — batch operations, avoid tight loops\\n- **Keep Google marketing read-only in v1** — stored evidence is the default.\\n `google-marketing.read-live` permits bounded provider reads only. It grants no\\n Google Ads mutation or GTM edit or publish authority.\\n\\n## References\\n\\n| File | Read when |\\n|---|---|\\n| `references/canonry-cli.md` | Looking up specific canonry commands, flags, or JSON return shapes |\\n| `references/aeo-analysis.md` | Interpreting sweep output, diagnosing regressions, planning content fixes |\\n| `references/indexing.md` | Submitting URLs, checking GSC/Bing coverage, fixing indexing gaps |\\n| `references/wordpress-integration.md` | Connecting to WordPress, editing pages, pushing staging → live |\\n| `references/server-side-traffic.md` | Wiring server-side evidence from Cloudflare, Cloud Run, WordPress, and Vercel. Connect, inspect, sync pull sources, and troubleshoot. |\\n| `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. |\\n| `references/google-marketing.md` | Inspecting first-class Google Ads and GTM evidence. Covers the conversion-integrity chain, static and runtime truth, live-read scope, v1 read-only boundary, and future write approvals. |\\n\\n---\\n\\n**Tools:** canonry v4+, @canonry/aeo-audit@4\\n**Website:** [canonry.ai](https://canonry.ai) | **Org:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)\\n\"\n","// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part =\n '---\\nname: canonry\\ndescription: \"Operate Canonry (the `cnry` / `canonry` CLI) for AEO. Load this BEFORE any canonry operator task: creating or configuring a project, connecting GSC, GA4, Bing, Google Business Profile or a Cloudflare traffic source, running or scheduling a sweep, reading mention and citation coverage, running a technical audit, submitting sitemaps, or diagnosing why a number moved. Covers anything touching cnry, canonry doctor, ~/.canonry, @canonry/canonry, the canonry_* MCP tools, mention share, or direct-push / queue-pull traffic. Load it before acting, not after something fails.\"\\ncompatibility: Requires Node.js 22.14+ and globally installed @canonry/canonry; canonry-mcp must be on PATH.\\nmetadata:\\n agent: >-\\n {\"emoji\":\"📡\",\"requires\":{\"bins\":[\"canonry\"]},\"install\":[{\"id\":\"npm\",\"kind\":\"npm\",\"package\":\"@canonry/canonry\",\"bins\":[\"canonry\"],\"label\":\"Install canonry globally\",\"command\":\"npm install -g @canonry/canonry\"}]}\\n---\\n\\n# Canonry\\n\\nAgent-first open-source AEO (Answer Engine Optimization) operating platform. Track how AI answer engines **mention** your brand in answers and **cite** your domain in sources across Gemini, ChatGPT, Claude, and Perplexity, then act on the signal through the content engine and integrations.\\n\\n**Website:** [canonry.ai](https://canonry.ai) | **Docs:** [github.com/Canonry/canonry](https://github.com/Canonry/canonry)\\n\\n**CLI:** invoke as `cnry` (short form) or `canonry` — both ship with the npm package and are interchangeable. Examples in this skill use `cnry`.\\n\\n## Runtime Preflight\\n\\nBefore using the native Codex or Claude Code plugin, verify the separately\\ninstalled Canonry runtime. It requires Node.js 22.14 or newer, and the native\\nplugin specifically needs the global package so `canonry-mcp` remains on\\n`PATH`; a one-off `npx` invocation is not sufficient:\\n\\n```bash\\nnode --version\\ncommand -v cnry\\ncnry --version\\n```\\n\\nThen prepare the runtime in this order:\\n\\n1. With approval, install the global runtime if `command -v cnry` failed.\\n2. Check only whether `$CANONRY_CONFIG_DIR/config.yaml` (when that variable is\\n set) or `~/.canonry/config.yaml` exists; do not print the file. If it does\\n not exist, pause and ask the operator to run `cnry init --skip-skills --skip-mcp`\\n in their own private terminal, then confirm completion without\\n pasting the output. Never execute `init` inside the agent session: it prompts\\n for provider credentials and prints the new full-access API key once. The\\n plugin already supplies the skills and MCP registration.\\n3. After a fresh initialization, get approval and run `cnry start --format\\n json`; `start` waits for the health endpoint before returning. On an\\n existing installation, try the doctor command first and start only when the\\n transport is unavailable. Never stop or restart a healthy daemon just to\\n install the plugin.\\n4. Run `cnry doctor --format json` after the daemon is ready. A successful JSON\\n response proves the health-check path works; individual checks may still\\n report actionable `warn` or `fail` statuses. Plugin installation state is\\n read live, so installing the plugin alone does not require a daemon restart.\\n\\nNever ask the operator to paste credentials into the chat, print the raw API\\nkey, or inspect `~/.canonry/config.yaml` for secrets. The plugin does not expand\\nthe configured key\\'s server-enforced scope, but it gives the client tools that\\ncan exercise that scope. Fresh `cnry init` creates a full-instance `*` key, so\\nthe default plugin has teammate-level access to every project and shared\\ninstance settings. A write-capable key exposes write tools by default; a\\nread-only key restricts the catalog to reads, while a project-scoped key keeps\\nits project route boundary but is not tenant isolation: a write-capable scoped\\nkey can still mutate shared instance settings. Do not work around a missing\\ntool or `403` by switching credentials.\\n\\n## When to Use\\n\\n- Tracking brand **mentions** in AI answer text and **citations** in source links across providers\\n- Expanding the tracked-query basket from an ICP description (`cnry discover run`)\\n- Running technical SEO audits (14‑factor scoring)\\n- Implementing structured data (JSON‑LD)\\n- Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools\\n- Wiring server-side traffic (Cloudflare, Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal\\n- Inspecting Google Ads conversion goals and GTM live configuration as read-only conversion evidence\\n- Optimizing `llms.txt`, sitemaps, robots.txt for AI crawlers\\n- Submitting URLs to Google Indexing API and Bing IndexNow\\n- Analyzing competitor citation patterns\\n- Operating guarded ChatGPT ads lifecycle changes and reconciling unresolved mutation receipts\\n\\n## Core Philosophy\\n\\n- **Measure outcomes** — AI models are black boxes; track mentions + citations, don\\'t assume causality\\n- **Signal over noise** — Focus on high‑intent queries; avoid granular targeting until base visibility exists\\n- **CLI‑native** — API‑driven changes over manual CMS clicks; faster, repeatable, auditable\\n- **Recover before retrying ads writes** — Page through `pending`, `unknown`, and `reconciling` receipts. Resume `campaign_tree_activate` through its bodyless exact-executor recovery operation; reconcile other supported receipts by verifying the checkpointed provider ID on the receipt-bound account. Never resend a mutation under a different key; an uncheckpointed create remains unresolved. A fresh pending generic receipt waits for its minimum-idle window, inconclusive reads back off, and a quarantined receipt requires human remediation.\\n- **Separate approval from ads execution** — A human with `ads.approve` creates a short-lived grant for the exact paused campaign tree and a different executor key. The operator may activate only that tree with `ads.activate`; it cannot mint or widen its own approval.\\n\\n## What Canonry Measures (Vocabulary)\\n\\nTwo parallel signals are tracked per (query × provider) snapshot. They are independent — a model can do either, both, or neither — never conflate them.\\n\\n| Term | Means | Headline metric |\\n|---|---|---|\\n| **mentioned** | The project\\'s brand or domain appears in the LLM\\'s **answer text** (the prose the model returns). | **Mention Coverage** — share of (query × provider) snapshots where the brand was mentioned. **Mention Share** is the project\\'s share among the cited+mentioned set vs competitors. |\\n| **cited** | The project\\'s domain appears in the LLM\\'s **source links** (the grounding citations returned alongside the answer). | **Citation Coverage** — share of snapshots where the domain was in the source list. |\\n\\nConfigure `spec.brandAliases` on the project (or pass via `cnry apply`) so the mention detector catches \"Meta\" alongside \"Facebook\", etc. The downloadable report (`cnry report`) and the dashboard both lead with Mention Coverage; Citation Coverage rides as the secondary gauge.\\n\\n## How to Operate\\n\\nA canonry engagement follows the same loop regardless of project size:\\n\\n1. **Diagnose** — After explicit approval for the quota-consuming persisted runs, run a baseline sweep (`cnry run --wait`) and a technical audit (`cnry technical-aeo run --wait`, then `cnry technical-aeo score --format json`). Use `cnry site-health overview --format json` only to add crawl metadata; it never replaces the score. The audit discovers the in-scope site from the root, sitemaps, and internal links, persists the crawl graph and score, and keeps dead-link checks off unless explicitly requested. Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.\\n2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.\\n3. **Execute** — Apply fixes via the canonry CLI or platform integrations. Use `--dry-run` on supported mutations (`cnry project delete`, `cnry query replace`, `cnry backfill ...`) to preview before committing. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.\\n4. **Monitor** — Re-run sweeps weekly only through an operator-approved schedule or after fresh explicit approval (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.\\n5. **Report** — Lead with data, not interpretation: \"Lost the mention for `` on Gemini between and — two competitors moved in. Here\\'s what to fix.\" For a one-command client-facing summary, run `cnry report ` to generate a self-contained HTML bundle (mention + citation hero, competitor landscape, GSC + GA4 performance, insights, suggested next queries). Same payload is available via `--format json` and the `canonry_report` MCP tool.\\n\\n**Verifying without polluting metrics**: when a test would help — \"did the latest provider deploy work?\", \"is this regression reproducible?\", \"would this query actually surface us?\" — propose the exact provider/query and get explicit approval before using `cnry run --probe --provider

--query \"...\"`. Probe runs still cost quota and write a snapshot, but are excluded from the dashboard, analytics, intelligence, report, and notifications. Approval for one probe does not authorize repeats unless the operator approved a bounded batch; use real sweeps only when the operator wants the data to feed metrics.\\n\\n## Surgical Reads\\n\\nWhen you need a specific value rather than a full payload, use the dot-path getter:\\n\\n```bash\\ncnry get scores.mentionShare.value\\ncnry get scores.mentionCoverage.value\\ncnry get insights[0].severity\\ncnry get --from report scores.citationCoverage.value\\n```\\n\\n`cnry get` resolves a path into the project\\'s overview (default) or any registered source (`report`, `traffic`, `discovery`, etc.). Returns scalar values without forcing the agent to grep through a 30 KB JSON dump.\\n\\n## Common Starting Points\\n\\n- **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent queries. See `references/indexing.md`.\\n- **Established site, regression** → diff canonry runs to find the loss window; verify schema is intact; resubmit affected URLs. See `references/aeo-analysis.md`.\\n- **Empty / generic query basket** → describe the ICP and let discovery expand: `cnry discover run --icp \"...\" --wait`, then `cnry discover promote ` to adopt the cited + aspirational queries. Multi-location projects can geo-constrain with `--locations `.\\n- **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county queries until base visibility exists.\\n\\n## Google Analytics 4\\n\\nGA4 is a first-class signal alongside citation tracking. Connect once with `cnry ga connect --property-id --key-file `; `cnry ga sync` then pulls daily landing-page traffic, AI-referral sessions across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), and social referrals split into Organic vs Paid via GA4\\'s `channelGroup` — and persists everything into four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`). All read commands query that local store, so they are fast and quotaless once a sync has run. AI referrals are tracked across three GA4 attribution dimensions (session source / first-user source / manual UTM) and joined to landing pages, so you can see which page each AI provider sent traffic to. Use `cnry ga traffic` for the current snapshot, `cnry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `cnry ga ai-referral-history` / `cnry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.\\n\\n## Google Ads and GTM\\n\\nGoogle Ads and GTM are separate, project-scoped sources for one conversion\\ncontract. Provider snapshots are static configuration evidence. They do not\\nprove browser events, tag firing, or recorded conversions. Stored snapshots are\\nthe safe default. A bounded live read needs `google-marketing.read-live`. Version\\n1 does not mutate Google Ads or edit, version, or publish GTM. Read\\n`references/google-marketing.md` before assessing or refreshing this evidence.\\nThe operator must complete OAuth, resource selection, and contract creation.\\nNever request OAuth credentials or a Google Ads developer token.\\n\\n## Server-Side Traffic\\n\\nWhen the project ships behind a server you control, connect Cloud Run, WordPress,\\nor Vercel. `cnry traffic sync` pulls and classifies their logs into hourly\\nbuckets. For Cloudflare, choose `direct-push` or `queue-pull` on the local,\\ncredential-owning host. Direct push requires a public Canonry HTTPS receiver.\\nIt does not use `traffic sync`. Queue pull sends events to a Cloudflare Queue,\\nthen Canonry drains it through `traffic sync` and the `traffic-sync` schedule.\\n\\nIf the connect response reports `activationRequired`, attach the Worker route\\nfirst. Then run `cnry traffic activate --source `. Activation\\npauses all sibling sources. It also moves the one `traffic-sync` schedule to\\nQueue pull. A first source becomes active automatically.\\n\\nEach default Queue tick drains at most 1,000 messages. Use `cnry traffic status`\\nand the `traffic.source.queue-backlog` doctor check to read the backlog. If more\\nthan 1,000 messages remain, get approval before a manual sync or a shorter\\nschedule interval. Use `cnry traffic events`, `cnry traffic sources`, and\\n`cnry traffic status` for every adapter. See\\n`references/server-side-traffic.md` for setup and smoke tests.\\n\\n**WordPress safety:** incremental pulls are fixed `[since, until)` windows; a\\nnew or idle source begins at the plugin\\'s 365-day maximum retention horizon.\\nCanonry rejects an endpoint that returns events outside that window. Keep\\nexisting WordPress rollups intact: generic replace-mode backfill is unavailable\\nuntil a retention-aware repair can prove coverage and declare any unrecoverable\\nspan.\\n\\n**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 --source --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 --source --advance-to-now`.\\n\\n## Local AEO (Google Business Profile)\\n\\nFor businesses with a physical location or service area, Google Business Profile is the local-AEO signal source — reviews, search-keyword impressions, daily performance metrics, and (for hotels) structured amenities + booking CTAs all feed how AI engines answer local-intent queries. Connect with `cnry gbp connect `, discover locations with `cnry gbp locations discover `, and pick which sync with `cnry gbp locations select/deselect`.\\n\\n**Hard prerequisites and gotchas — read `references/google-business-profile.md` before attempting setup:** GBP requires a Google access-form approval (0 QPM until granted), the only OAuth scope is the write-capable `business.manage`, **reviews live on a separately-gated legacy v4 API that the Basic approval does NOT grant** (and can\\'t be self-enabled), and the **Q&A API was retired (2025-11-03)**. Keyword data is heavily privacy-redacted (often 100% for small businesses); an empty place-action profile is a real AEO finding to surface, but an empty lodging result is a verify-not-a-gap (the Lodging API can return 0 readable groups even when the owner-facing \"Hotel details\" panel has amenities set). The reference doc has the full setup walkthrough, the real-world data shapes, and the troubleshooting matrix.\\n\\n## Built-in Analyst (Aero)\\n\\nCanonry ships a built-in agent — Aero — for users who don\\'t already have one. Drive it from the CLI:\\n\\n```bash\\ncnry agent ask \"what changed since the last sweep?\"\\ncnry agent ask \"...\" --provider claude --scope read-only\\ncnry agent memory list # durable project notes\\n```\\n\\nAero also wakes unprompted after every `run.completed` so insights and regressions get analyzed without a user click. Users who already run their own agent (Claude Code, Codex, custom) wire webhooks instead: `cnry agent attach --url ` subscribes to `run.completed`, `insight.critical`, `insight.high`, `citation.gained`.\\n\\n## Boundaries & Safety\\n\\n- **Get explicit approval before every mutation or quota-consuming sweep.** Also get approval before each live provider read. Stored reads and `--dry-run` previews are safe defaults.\\n- **Never touch live WordPress without explicit approval**\\n- **Back up `~/.canonry/config.yaml` before any config edit**\\n- **Never fabricate mention or citation data** — if a sweep hasn\\'t run, say so; never coerce `answerMentioned` null → false (null = \"not checked\")\\n- **Client data stays private** — canonry repo is public; no real domains in issues\\n- **Respect API rate limits** — batch operations, avoid tight loops\\n- **Keep Google marketing read-only in v1** — stored evidence is the default.\\n `google-marketing.read-live` permits bounded provider reads only. It grants no\\n Google Ads mutation or GTM edit or publish authority.\\n\\n## References\\n\\n| File | Read when |\\n|---|---|\\n| `references/canonry-cli.md` | Looking up specific canonry commands, flags, or JSON return shapes |\\n| `references/aeo-analysis.md` | Interpreting sweep output, diagnosing regressions, planning content fixes |\\n| `references/indexing.md` | Submitting URLs, checking GSC/Bing coverage, fixing indexing gaps |\\n| `references/wordpress-integration.md` | Connecting to WordPress, editing pages, pushing staging → live |\\n| `references/server-side-traffic.md` | Wiring server-side evidence from Cloudflare, Cloud Run, WordPress, and Vercel. Connect, inspect, sync pull sources, and troubleshoot. |\\n| `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. |\\n| `references/google-marketing.md` | Inspecting first-class Google Ads and GTM evidence. Covers the conversion-integrity chain, static and runtime truth, live-read scope, v1 read-only boundary, and future write approvals. |\\n\\n---\\n\\n**Tools:** canonry v4+, @canonry/aeo-audit@4\\n**Website:** [canonry.ai](https://canonry.ai) | **Org:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)\\n'\n","createdAt",["D",1788372561192],"branchVersion","branchId","a4524491-dcb3-470a-a361-437a88df6a63","id","b1194860-7c77-41d7-b0b7-f3529a80e15b","AI-Visibility-Check",["D",1788292195151],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Does AI mention your brand and cite your site? Free check.","imageUrl","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/f4d36c97-6af9-485c-0fa5-13e825466c01/square512?exp=1789567199&sig=384af81203f705af155e58c5f81ae8936be1a2a7073f35bdb03d5b63169e25d2","891d245e-ec71-404d-a5ca-223733ee2844","pinnedFileId","92ee44ee-a63e-11f1-8fd4-1607ee4eb77e","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","01a0460b-6625-75ce-9e7f-9a6b062b0798","tursoName","b11948607c7741d7b0b7f3529a80e15b","tursoHostname","b11948607c7741d7b0b7f3529a80e15b-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789514495229],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_102":101,"_110":106},"org",{"_102":101,"_103":104,"_105":106,"_18":-5,"_107":108,"_109":27},"branch",{"_13":91,"_33":92,"_45":44,"_93":46,"_94":-5,"_95":-5,"_96":-5,"_97":-5,"_98":-5,"_99":47,"_100":101},"isOwned",333,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","canonry","handle","displayName","Canonry","avatar","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/5ae39d80-0d23-48e5-89d8-6bd2a7096401/square512?exp=1789567199&sig=a5ebc03fa3701ebdc18a3095160be5dbf1e5c6f020560ab8d689b484c3dfeba5","tier","free","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_45":46,"_33":47,"_40":787,"_49":-5,"_50":27,"_51":52,"_53":52,"_54":55,"_56":57,"_18":58,"_59":60,"_61":25,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":788,"_74":-5,"_75":76,"_77":76,"_78":79,"_80":79,"_81":79,"_82":76,"_83":76,"_84":789,"_86":790,"_88":791,"_90":27},"tree",[214,277,278,279,280,281,282,283],"files",[214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283],"counts",{"_203":65,"_204":157,"_205":65,"_206":207,"_208":209},"contents",[133,134,135,136,137,138,139,140],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_45":197,"_33":198,"_31":199,"_143":-5,"_43":44,"_42":157,"_145":25,"_40":200,"_13":65,"_35":201,"_37":-5,"_24":27,"_150":-5,"_28":202},{"_45":190,"_33":191,"_31":192,"_143":-5,"_43":44,"_42":193,"_145":27,"_40":194,"_13":65,"_35":20,"_37":195,"_24":27,"_150":-5,"_28":196},{"_45":182,"_33":183,"_31":184,"_143":-5,"_43":44,"_42":185,"_145":27,"_40":186,"_13":187,"_35":20,"_37":188,"_24":27,"_150":-5,"_28":189},{"_45":175,"_33":176,"_31":177,"_143":-5,"_43":44,"_42":178,"_145":25,"_40":179,"_13":65,"_35":20,"_37":180,"_24":27,"_150":-5,"_28":181},{"_45":167,"_33":168,"_31":169,"_143":-5,"_43":44,"_42":170,"_145":25,"_40":171,"_13":172,"_35":20,"_37":173,"_24":27,"_150":-5,"_28":174},{"_45":160,"_33":161,"_31":162,"_143":-5,"_43":44,"_42":163,"_145":27,"_40":164,"_13":157,"_35":20,"_37":165,"_24":27,"_150":-5,"_28":166},{"_45":152,"_33":153,"_31":154,"_143":-5,"_43":44,"_42":155,"_145":27,"_40":156,"_13":157,"_35":20,"_37":158,"_24":27,"_150":-5,"_28":159},{"_45":141,"_33":142,"_31":60,"_143":-5,"_43":44,"_42":144,"_145":27,"_40":146,"_13":147,"_35":148,"_37":149,"_24":27,"_150":-5,"_28":151},"f3803363-df7a-4276-be7a-1f9d96e87453","main.http.tsx","parentId",131,"latest",["D",1788310248412],5,"http","import { sqlite } from 'https://esm.town/v/std/sqlite/main.ts'\nimport { createValTownApp } from './src/app/app.ts'\nimport { loadValTownConfig } from './src/config/index.ts'\nimport { createPublicCheckRunner, createRequestBoundDispatcher } from './src/jobs/public-check.ts'\nimport { createSiteHealthRunner } from './src/site-health/runner.ts'\nimport { ValSqliteCheckStore } from './src/storage/val-sqlite.ts'\nimport {\n canonryDemoClientScript,\n canonryDemoStyles,\n canonryGlyph,\n canonryMark,\n createPublicCheckForm,\n emptyLandingViewModel,\n renderCanonryDemo,\n toCanonryDemoViewModel,\n} from './src/ui/index.ts'\nimport { createGeminiValVisibilityProbe } from './src/visibility/gemini-probe.ts'\n\nconst config = loadValTownConfig()\nconst store = new ValSqliteCheckStore(sqlite)\nawait store.initialize()\n\nconst visibilityProbe = config.geminiApiKey\n ? createGeminiValVisibilityProbe({ apiKey: config.geminiApiKey, model: config.geminiModel ?? undefined })\n : null\nconst runner = createPublicCheckRunner({\n store,\n visibilityProbe,\n siteHealthRunner: createSiteHealthRunner(),\n ttlMs: config.checkTtlMs,\n})\n\nconst form = createPublicCheckForm(config)\n\nconst app = createValTownApp({\n store,\n config,\n dispatcher: createRequestBoundDispatcher(runner),\n renderPage: (record) =>\n record\n ? renderCanonryDemo(toCanonryDemoViewModel(record, { form, title: 'AI Visibility Check' }))\n : renderCanonryDemo(emptyLandingViewModel(form)),\n assets: { styles: canonryDemoStyles, script: canonryDemoClientScript, mark: canonryMark, glyph: canonryGlyph },\n})\n\nexport default app.fetch\n","label",[142],"ce93a88c-c0e2-4875-91f6-704275c78f37","deno.lock","96393c08-a63e-11f1-9d10-1607ee4eb77e",69,["D",1788292423313],1,"{\n \"version\": \"5\",\n \"specifiers\": {\n \"npm:@canonry/aeo-audit@7.1.0\": \"7.1.0\",\n \"npm:@google/genai@1.46.0\": \"1.46.0\",\n \"npm:@libsql/client@0.17.2\": \"0.17.2\",\n \"npm:hono@4.12.25\": \"4.12.25\"\n },\n \"npm\": {\n \"@canonry/aeo-audit@7.1.0\": {\n \"integrity\": \"sha512-XwWEfzVqrzBkaCCAe4ficJW52LUhpxzsNF3uB3v3u2RsUHD3nRhv03jSgyTpj7hILTUNJTt8Xqn5HNMgDqX19w==\",\n \"dependencies\": [\n \"cheerio\",\n \"ipaddr.js\",\n \"undici\"\n ],\n \"bin\": true\n },\n \"@google/genai@1.46.0\": {\n \"integrity\": \"sha512-ewPMN5JkKfgU5/kdco9ZhXBHDPhVqZpMQqIFQhwsHLf8kyZfx1cNpw1pHo1eV6PGEW7EhIBFi3aYZraFndAXqg==\",\n \"dependencies\": [\n \"google-auth-library\",\n \"p-retry\",\n \"protobufjs\",\n \"ws\"\n ]\n },\n \"@libsql/client@0.17.2\": {\n \"integrity\": \"sha512-0aw0S3iQMHvOxfRt5j1atoCCPMT3gjsB2PS8/uxSM1DcDn39xqz6RlgSMxtP8I3JsxIXAFuw7S41baLEw0Zi+Q==\",\n \"dependencies\": [\n \"@libsql/core\",\n \"@libsql/hrana-client\",\n \"js-base64\",\n \"libsql\",\n \"promise-limit\"\n ]\n },\n \"@libsql/core@0.17.4\": {\n \"integrity\": \"sha512-LqF9gIvnJ38nmAH1y/ChizHqDO/MO1wLgA96XrraulEEbqXxLjleSH92YWTolbuJKgPUmGu4aJk9W3UnAcxLOQ==\",\n \"dependencies\": [\n \"js-base64\"\n ]\n },\n \"@libsql/darwin-arm64@0.5.29\": {\n \"integrity\": \"sha512-K+2RIB1OGFPYQbfay48GakLhqf3ArcbHqPFu7EZiaUcRgFcdw8RoltsMyvbj5ix2fY0HV3Q3Ioa/ByvQdaSM0A==\",\n \"os\": [\"darwin\"],\n \"cpu\": [\"arm64\"]\n },\n \"@libsql/darwin-x64@0.5.29\": {\n \"integrity\": \"sha512-OtT+KFHsKFy1R5FVadr8FJ2Bb1mghtXTyJkxv0trocq7NuHntSki1eUbxpO5ezJesDvBlqFjnWaYYY516QNLhQ==\",\n \"os\": [\"darwin\"],\n \"cpu\": [\"x64\"]\n },\n \"@libsql/hrana-client@0.9.0\": {\n \"integrity\": \"sha512-pxQ1986AuWfPX4oXzBvLwBnfgKDE5OMhAdR/5cZmRaB4Ygz5MecQybvwZupnRz341r2CtFmbk/BhSu7k2Lm+Jw==\",\n \"dependencies\": [\n \"@libsql/isomorphic-ws\",\n \"cross-fetch\",\n \"js-base64\",\n \"node-fetch@3.3.2\"\n ]\n },\n \"@libsql/isomorphic-ws@0.1.5\": {\n \"integrity\": \"sha512-DtLWIH29onUYR00i0GlQ3UdcTRC6EP4u9w/h9LxpUZJWRMARk6dQwZ6Jkd+QdwVpuAOrdxt18v0K2uIYR3fwFg==\",\n \"dependencies\": [\n \"@types/ws\",\n \"ws\"\n ]\n },\n \"@libsql/linux-arm-gnueabihf@0.5.29\": {\n \"integrity\": \"sha512-CD4n4zj7SJTHso4nf5cuMoWoMSS7asn5hHygsDuhRl8jjjCTT3yE+xdUvI4J7zsyb53VO5ISh4cwwOtf6k2UhQ==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"arm\"]\n },\n \"@libsql/linux-arm-musleabihf@0.5.29\": {\n \"integrity\": \"sha512-2Z9qBVpEJV7OeflzIR3+l5yAd4uTOLxklScYTwpZnkm2vDSGlC1PRlueLaufc4EFITkLKXK2MWBpexuNJfMVcg==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"arm\"]\n },\n \"@libsql/linux-arm64-gnu@0.5.29\": {\n \"integrity\": \"sha512-gURBqaiXIGGwFNEaUj8Ldk7Hps4STtG+31aEidCk5evMMdtsdfL3HPCpvys+ZF/tkOs2MWlRWoSq7SOuCE9k3w==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"arm64\"]\n },\n \"@libsql/linux-arm64-musl@0.5.29\": {\n \"integrity\": \"sha512-fwgYZ0H8mUkyVqXZHF3mT/92iIh1N94Owi/f66cPVNsk9BdGKq5gVpoKO+7UxaNzuEH1roJp2QEwsCZMvBLpqg==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"arm64\"]\n },\n \"@libsql/linux-x64-gnu@0.5.29\": {\n \"integrity\": \"sha512-y14V0vY0nmMC6G0pHeJcEarcnGU2H6cm21ZceRkacWHvQAEhAG0latQkCtoS2njFOXiYIg+JYPfAoWKbi82rkg==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"x64\"]\n },\n \"@libsql/linux-x64-musl@0.5.29\": {\n \"integrity\": \"sha512-gquqwA/39tH4pFl+J9n3SOMSymjX+6kZ3kWgY3b94nXFTwac9bnFNMffIomgvlFaC4ArVqMnOZD3nuJ3H3VO1w==\",\n \"os\": [\"linux\"],\n \"cpu\": [\"x64\"]\n },\n \"@libsql/win32-x64-msvc@0.5.29\": {\n \"integrity\": \"sha512-4/0CvEdhi6+KjMxMaVbFM2n2Z44escBRoEYpR+gZg64DdetzGnYm8mcNLcoySaDJZNaBd6wz5DNdgRmcI4hXcg==\",\n \"os\": [\"win32\"],\n \"cpu\": [\"x64\"]\n },\n \"@neon-rs/load@0.0.4\": {\n \"integrity\": \"sha512-kTPhdZyTQxB+2wpiRcFWrDcejc4JI6tkPuS7UZCG4l6Zvc5kU/gGQ/ozvHTh1XR5tS+UlfAfGuPajjzQjCiHCw==\"\n },\n \"@protobufjs/aspromise@1.1.2\": {\n \"integrity\": \"sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==\"\n },\n \"@protobufjs/base64@1.1.2\": {\n \"integrity\": \"sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==\"\n },\n \"@protobufjs/codegen@2.0.5\": {\n \"integrity\": \"sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==\"\n },\n \"@protobufjs/eventemitter@1.1.1\": {\n \"integrity\": \"sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==\"\n },\n \"@protobufjs/fetch@1.1.1\": {\n \"integrity\": \"sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==\",\n \"dependencies\": [\n \"@protobufjs/aspromise\"\n ]\n },\n \"@protobufjs/float@1.0.2\": {\n \"integrity\": \"sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==\"\n },\n \"@protobufjs/path@1.1.2\": {\n \"integrity\": \"sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==\"\n },\n \"@protobufjs/pool@1.1.0\": {\n \"integrity\": \"sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==\"\n },\n \"@protobufjs/utf8@1.1.2\": {\n \"integrity\": \"sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==\"\n },\n \"@types/node@26.4.0\": {\n \"integrity\": \"sha512-faiGnoIrLH/V8cibOMEAZ8pMw6oXqSukl29ra4mN8GdaB2ZewzeaLj+INpV5N+Z1eKWzY+IzaIZH2EIR6YZRNQ==\",\n \"dependencies\": [\n \"undici-types\"\n ]\n },\n \"@types/retry@0.12.0\": {\n \"integrity\": \"sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==\"\n },\n \"@types/ws@8.18.1\": {\n \"integrity\": \"sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==\",\n \"dependencies\": [\n \"@types/node\"\n ]\n },\n \"agent-base@7.1.4\": {\n \"integrity\": \"sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==\"\n },\n \"base64-js@1.5.1\": {\n \"integrity\": \"sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==\"\n },\n \"bignumber.js@9.3.1\": {\n \"integrity\": \"sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==\"\n },\n \"boolbase@1.0.0\": {\n \"integrity\": \"sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==\"\n },\n \"buffer-equal-constant-time@1.0.1\": {\n \"integrity\": \"sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==\"\n },\n \"cheerio-select@2.1.0\": {\n \"integrity\": \"sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g==\",\n \"dependencies\": [\n \"boolbase\",\n \"css-select\",\n \"css-what\",\n \"domelementtype\",\n \"domhandler\",\n \"domutils\"\n ]\n },\n \"cheerio@1.2.0\": {\n \"integrity\": \"sha512-WDrybc/gKFpTYQutKIK6UvfcuxijIZfMfXaYm8NMsPQxSYvf+13fXUJ4rztGGbJcBQ/GF55gvrZ0Bc0bj/mqvg==\",\n \"dependencies\": [\n \"cheerio-select\",\n \"dom-serializer\",\n \"domhandler\",\n \"domutils\",\n \"encoding-sniffer\",\n \"htmlparser2\",\n \"parse5\",\n \"parse5-htmlparser2-tree-adapter\",\n \"parse5-parser-stream\",\n \"undici\",\n \"whatwg-mimetype\"\n ]\n },\n \"cross-fetch@4.1.0\": {\n \"integrity\": \"sha512-uKm5PU+MHTootlWEY+mZ4vvXoCn4fLQxT9dSc1sXVMSFkINTJVN8cAQROpwcKm8bJ/c7rgZVIBWzH5T78sNZZw==\",\n \"dependencies\": [\n \"node-fetch@2.7.0\"\n ]\n },\n \"css-select@5.2.2\": {\n \"integrity\": \"sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==\",\n \"dependencies\": [\n \"boolbase\",\n \"css-what\",\n \"domhandler\",\n \"domutils\",\n \"nth-check\"\n ]\n },\n \"css-what@6.2.2\": {\n \"integrity\": \"sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==\"\n },\n \"data-uri-to-buffer@4.0.1\": {\n \"integrity\": \"sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==\"\n },\n \"debug@4.4.3\": {\n \"integrity\": \"sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==\",\n \"dependencies\": [\n \"ms\"\n ]\n },\n \"detect-libc@2.0.2\": {\n \"integrity\": \"sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==\"\n },\n \"dom-serializer@2.0.0\": {\n \"integrity\": \"sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==\",\n \"dependencies\": [\n \"domelementtype\",\n \"domhandler\",\n \"entities@4.5.0\"\n ]\n },\n \"domelementtype@2.3.0\": {\n \"integrity\": \"sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==\"\n },\n \"domhandler@5.0.3\": {\n \"integrity\": \"sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==\",\n \"dependencies\": [\n \"domelementtype\"\n ]\n },\n \"domutils@3.2.2\": {\n \"integrity\": \"sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==\",\n \"dependencies\": [\n \"dom-serializer\",\n \"domelementtype\",\n \"domhandler\"\n ]\n },\n \"ecdsa-sig-formatter@1.0.11\": {\n \"integrity\": \"sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==\",\n \"dependencies\": [\n \"safe-buffer\"\n ]\n },\n \"encoding-sniffer@0.2.1\": {\n \"integrity\": \"sha512-5gvq20T6vfpekVtqrYQsSCFZ1wEg5+wW0/QaZMWkFr6BqD3NfKs0rLCx4rrVlSWJeZb5NBJgVLswK/w2MWU+Gw==\",\n \"dependencies\": [\n \"iconv-lite\",\n \"whatwg-encoding\"\n ]\n },\n \"entities@4.5.0\": {\n \"integrity\": \"sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==\"\n },\n \"entities@6.0.1\": {\n \"integrity\": \"sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==\"\n },\n \"entities@7.0.1\": {\n \"integrity\": \"sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==\"\n },\n \"extend@3.0.2\": {\n \"integrity\": \"sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==\"\n },\n \"fetch-blob@3.2.0\": {\n \"integrity\": \"sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==\",\n \"dependencies\": [\n \"node-domexception\",\n \"web-streams-polyfill\"\n ]\n },\n \"formdata-polyfill@4.0.10\": {\n \"integrity\": \"sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==\",\n \"dependencies\": [\n \"fetch-blob\"\n ]\n },\n \"gaxios@7.3.1\": {\n \"integrity\": \"sha512-kB3rzJV7d9juLZh8/56QTXCwQfxyhdOMdyYk1HdQKFtF8TJTDTZQJtixWIwXdE9Jji91mC41DUNpjleo4L4eAQ==\",\n \"dependencies\": [\n \"extend\",\n \"https-proxy-agent\",\n \"node-fetch@3.3.2\"\n ]\n },\n \"gcp-metadata@8.1.2\": {\n \"integrity\": \"sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==\",\n \"dependencies\": [\n \"gaxios\",\n \"google-logging-utils\",\n \"json-bigint\"\n ]\n },\n \"google-auth-library@10.9.1\": {\n \"integrity\": \"sha512-i1ydyHrqcIxXkWh/uBmVkzCvIuq5yiK2ATndIe5XxKholrG/MTYP9xGYka4sQhrbIAgGjL2B6NOE7rFaiF3fXw==\",\n \"dependencies\": [\n \"base64-js\",\n \"ecdsa-sig-formatter\",\n \"gaxios\",\n \"gcp-metadata\",\n \"google-logging-utils\",\n \"jws\"\n ]\n },\n \"google-logging-utils@1.1.3\": {\n \"integrity\": \"sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==\"\n },\n \"hono@4.12.25\": {\n \"integrity\": \"sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ==\"\n },\n \"htmlparser2@10.1.0\": {\n \"integrity\": \"sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==\",\n \"dependencies\": [\n \"domelementtype\",\n \"domhandler\",\n \"domutils\",\n \"entities@7.0.1\"\n ]\n },\n \"https-proxy-agent@7.0.6\": {\n \"integrity\": \"sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==\",\n \"dependencies\": [\n \"agent-base\",\n \"debug\"\n ]\n },\n \"iconv-lite@0.6.3\": {\n \"integrity\": \"sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==\",\n \"dependencies\": [\n \"safer-buffer\"\n ]\n },\n \"ipaddr.js@2.5.0\": {\n \"integrity\": \"sha512-aq+t5NAc+cS6rZQQVWC2x98CPqGtKKTMDd4Gaodv0wShnItdKg/51djkGJ1hqH+Oy0ivDftCbSLCQob8zso01w==\"\n },\n \"js-base64@3.9.3\": {\n \"integrity\": \"sha512-uwYQp+VJ38FVvtim6qNbit6e9uT6dwWQ4Y1+H9TxhW5hcHjpHwoxlR0nMpqUmIFOmu4VqMxwdJA88gIVuZJQ/g==\"\n },\n \"json-bigint@1.0.0\": {\n \"integrity\": \"sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==\",\n \"dependencies\": [\n \"bignumber.js\"\n ]\n },\n \"jwa@2.0.1\": {\n \"integrity\": \"sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==\",\n \"dependencies\": [\n \"buffer-equal-constant-time\",\n \"ecdsa-sig-formatter\",\n \"safe-buffer\"\n ]\n },\n \"jws@4.0.1\": {\n \"integrity\": \"sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==\",\n \"dependencies\": [\n \"jwa\",\n \"safe-buffer\"\n ]\n },\n \"libsql@0.5.29\": {\n \"integrity\": \"sha512-8lMP8iMgiBzzoNbAPQ59qdVcj6UaE/Vnm+fiwX4doX4Narook0a4GPKWBEv+CR8a1OwbfkgL18uBfBjWdF0Fzg==\",\n \"dependencies\": [\n \"@neon-rs/load\",\n \"detect-libc\"\n ],\n \"optionalDependencies\": [\n \"@libsql/darwin-arm64\",\n \"@libsql/darwin-x64\",\n \"@libsql/linux-arm-gnueabihf\",\n \"@libsql/linux-arm-musleabihf\",\n \"@libsql/linux-arm64-gnu\",\n \"@libsql/linux-arm64-musl\",\n \"@libsql/linux-x64-gnu\",\n \"@libsql/linux-x64-musl\",\n \"@libsql/win32-x64-msvc\"\n ],\n \"os\": [\"darwin\", \"linux\", \"win32\"],\n \"cpu\": [\"x64\", \"arm64\", \"wasm32\", \"arm\"]\n },\n \"long@5.3.2\": {\n \"integrity\": \"sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==\"\n },\n \"ms@2.1.3\": {\n \"integrity\": \"sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==\"\n },\n \"node-domexception@1.0.0\": {\n \"integrity\": \"sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==\",\n \"deprecated\": true\n },\n \"node-fetch@2.7.0\": {\n \"integrity\": \"sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==\",\n \"dependencies\": [\n \"whatwg-url\"\n ]\n },\n \"node-fetch@3.3.2\": {\n \"integrity\": \"sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==\",\n \"dependencies\": [\n \"data-uri-to-buffer\",\n \"fetch-blob\",\n \"formdata-polyfill\"\n ]\n },\n \"nth-check@2.1.1\": {\n \"integrity\": \"sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==\",\n \"dependencies\": [\n \"boolbase\"\n ]\n },\n \"p-retry@4.6.2\": {\n \"integrity\": \"sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==\",\n \"dependencies\": [\n \"@types/retry\",\n \"retry\"\n ]\n },\n \"parse5-htmlparser2-tree-adapter@7.1.0\": {\n \"integrity\": \"sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g==\",\n \"dependencies\": [\n \"domhandler\",\n \"parse5\"\n ]\n },\n \"parse5-parser-stream@7.1.2\": {\n \"integrity\": \"sha512-JyeQc9iwFLn5TbvvqACIF/VXG6abODeB3Fwmv/TGdLk2LfbWkaySGY72at4+Ty7EkPZj854u4CrICqNk2qIbow==\",\n \"dependencies\": [\n \"parse5\"\n ]\n },\n \"parse5@7.3.0\": {\n \"integrity\": \"sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==\",\n \"dependencies\": [\n \"entities@6.0.1\"\n ]\n },\n \"promise-limit@2.7.0\": {\n \"integrity\": \"sha512-7nJ6v5lnJsXwGprnGXga4wx6d1POjvi5Qmf1ivTRxTjH4Z/9Czja/UCMLVmB9N93GeWOU93XaFaEt6jbuoagNw==\"\n },\n \"protobufjs@7.6.6\": {\n \"integrity\": \"sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==\",\n \"dependencies\": [\n \"@protobufjs/aspromise\",\n \"@protobufjs/base64\",\n \"@protobufjs/codegen\",\n \"@protobufjs/eventemitter\",\n \"@protobufjs/fetch\",\n \"@protobufjs/float\",\n \"@protobufjs/path\",\n \"@protobufjs/pool\",\n \"@protobufjs/utf8\",\n \"@types/node\",\n \"long\"\n ],\n \"scripts\": true\n },\n \"retry@0.13.1\": {\n \"integrity\": \"sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==\"\n },\n \"safe-buffer@5.2.1\": {\n \"integrity\": \"sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==\"\n },\n \"safer-buffer@2.1.2\": {\n \"integrity\": \"sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==\"\n },\n \"tr46@0.0.3\": {\n \"integrity\": \"sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==\"\n },\n \"undici-types@8.3.0\": {\n \"integrity\": \"sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==\"\n },\n \"undici@7.29.0\": {\n \"integrity\": \"sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==\"\n },\n \"web-streams-polyfill@3.3.3\": {\n \"integrity\": \"sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==\"\n },\n \"webidl-conversions@3.0.1\": {\n \"integrity\": \"sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==\"\n },\n \"whatwg-encoding@3.1.1\": {\n \"integrity\": \"sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==\",\n \"dependencies\": [\n \"iconv-lite\"\n ],\n \"deprecated\": true\n },\n \"whatwg-mimetype@4.0.0\": {\n \"integrity\": \"sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==\"\n },\n \"whatwg-url@5.0.0\": {\n \"integrity\": \"sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==\",\n \"dependencies\": [\n \"tr46\",\n \"webidl-conversions\"\n ]\n },\n \"ws@8.21.3\": {\n \"integrity\": \"sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==\"\n }\n },\n \"redirects\": {\n \"https://esm.town/v/std/API_URL\": \"https://esm.town/v/std/API_URL?v=5\",\n \"https://esm.town/v/std/sqlite/main.ts\": \"https://esm.town/v/std/sqlite@31-main/main.ts\"\n },\n \"remote\": {\n \"https://esm.town/v/std/API_URL?v=5\": \"46109f905a50e32281d3ffbe7b9c8209a778290c5274d83d131fba2d26c4974d\",\n \"https://esm.town/v/std/sqlite@31-main/main.ts\": \"1e2a0fdf57aa0b4fcf840c04d048e81f415d0ed93205522b6579b2971a8cfd64\"\n }\n}\n",[153],"1474d51a-5085-4e3d-a6ff-fddbd85aa630","deno.json","935238aa-a63e-11f1-9f99-1607ee4eb77e",68,["D",1788292423281],"{\n \"compilerOptions\": {\n \"strict\": true,\n \"noUncheckedIndexedAccess\": true\n },\n \"tasks\": {\n \"check\": \"deno check --allow-import --frozen main.http.tsx\",\n \"test\": \"deno test --allow-env --allow-net --allow-import --frozen test\",\n \"lint\": \"deno lint --allow-import main.http.tsx src test\",\n \"dev\": \"deno run --allow-net --allow-env --allow-import test/dev-server.ts\"\n },\n \"fmt\": {\n \"lineWidth\": 120,\n \"singleQuote\": true,\n \"semiColons\": false\n },\n \"lint\": {\n \"rules\": {\n \"exclude\": [\n \"no-import-prefix\"\n ]\n }\n }\n}\n",[161],"cb16d29c-f734-4227-a27a-e40b02a633a3","README.md","92e8b0ce-a63e-11f1-91a7-1607ee4eb77e",111,["D",1788308781777],4,"# AI Visibility Check\n\nEnter a domain. See whether an AI answer engine mentions your brand and cites your site.\n\nFree. No signup. About 45 seconds.\n\n## Signals\n\nTwo signals, measured separately.\n\n| Signal | Meaning |\n|---|---|\n| Mentioned | Your brand appears in the text the engine wrote. |\n| Cited | Your domain appears in the sources behind the answer. |\n\nThey are independent. A site can be cited without being named, or named without being cited.\n\n## Results\n\n- Three questions generated for your site\n- The full answer text\n- Mentioned and cited per question, with the sources used\n- A technical audit of a sample of pages\n- A map of how those pages link to each other\n\nA failed check is reported as failed, not scored as zero.\n\n## MCP\n\nThis is also an MCP server. No API key.\n\n```json\n{ \"mcpServers\": { \"ai-visibility-check\": { \"url\": \"https:///mcp\" } } }\n```\n\nTools: `start_check`, `get_check`, `get_ai_visibility`, `get_site_health`, `list_skills`, `read_skill`, `self_host`.\n\nThe Canonry and Aero analyst playbooks are served as MCP resources.\n\n## Limits\n\n- One engine (Gemini)\n- Three generated questions\n- Five pages of audit\n- One snapshot. No history, no tracking, no alerts\n\n## Canonry\n\nCanonry is the open source platform this samples. It runs on your own machine.\n\n```sh\nnpm install -g @canonry/canonry\ncanonry init\n```\n\nFour answer engines. Unlimited questions on a schedule. Whole-site audits. History, competitor share, and joins to\nSearch Console, GA4, and Bing.\n\n[github.com/Canonry/canonry](https://github.com/Canonry/canonry) · [canonry.ai](https://canonry.ai)\n",[168],"655360bd-bc32-4a60-b9ab-c9156f924695","CLAUDE.md","930d2c42-a63e-11f1-8d00-1607ee4eb77e",18,["D",1788292310988],"@AGENTS.md\n",[176],"afec59fa-bd15-43ae-a1f8-9bb973d55c24","AGENTS.md","92f64d1a-a63e-11f1-8d00-1607ee4eb77e",225,["D",1788372408495],26,"# AI Visibility Check (Val Town)\n\nThis directory is the exact source mirrored to the public `canonry/AI-Visibility-Check` val. Git is authoritative; do not make\nproduction-only edits in Val Town because `vt push` removes remote-only files.\n\n## Naming\n\nThe Val is **AI Visibility Check**, not Canonry. It runs 3 generated queries against one engine and audits 5 pages,\nwhere Canonry tracks four engines on a schedule with no such limits. Calling this \"Canonry\" would tell a visitor, or\nan agent reading `serverInfo`, that they had the platform when they have a sample of it. So the product name, the val\nname, and the MCP `serverInfo.name` all say AI Visibility Check.\n\nAttribution runs the other way, and deliberately: every surface points back at the open-source project. The header\nbyline, the footer (with the install command), the MCP `initialize` instructions, the `self_host` tool, and the\nbundled skills all name Canonry and link to it. Keep that; a sample that does not lead anywhere is just a toy.\n\n## Boundaries\n\n- Keep the host Deno-native and web-standard. Do not import the Node Canonry server, Fastify, `better-sqlite3`, or the\n Vite dashboard.\n- Import reusable engines through exact pins. Technical AEO uses `@canonry/aeo-audit`; AI Visibility is implemented\n locally under `src/visibility/` so this Val owns its Gemini planner, adapter, and evidence runner.\n- The browser never receives provider, Turnstile-secret, deployment, or signing credentials.\n- Anonymous work is bounded by human verification, atomic quotas, cache reuse, output clipping, and hard provider/crawl\n deadlines.\n- `allowPrivateHost` names the ONE host being crawled, per attempt, and must never be widened. Val Town grants no DNS\n (`Deno.resolveDns` has no net access to the resolver, `node:dns.resolve4` returns UNKNOWN), so the engine's\n resolve-then-check SSRF guard fails closed on every hostname and the crawl audits zero pages for every domain. The\n option is a hostname rather than a boolean precisely so the guard cannot be switched off: a matching host skips the\n DNS preflight and IP pinning, and every other host, including a redirect to cloud metadata, is still resolved and\n still blocked. Two layers below it, `normalizePublicDomain` has already rejected private hosts at the input\n boundary, and Val Town's sandbox refuses fetches to 169.254.169.254, 127.0.0.1, 10/8 and 192.168/16 outright.\n- Keep Technical AEO labeled as a bounded page sample, not a whole-site score.\n- Mention and citation are independent signals. Summary denominators contain successful checks only; failures stay\n visible.\n- The visibility core (`contracts`, `runtime`, `brand`, `runner`) must not read environment, storage, or HTTP state.\n Only the Gemini adapter makes provider calls; the host owns credentials, quotas, and scheduling.\n- **Never render data the Val did not measure.** The landing page ships an empty state, not a fixture. It previously\n drew a four-engine trend with invented model identifiers, labelled only by a badge in the page header, well above\n the numbers it qualified — anyone who scrolled read fabrication as measurement, and it advertised three engines this\n Val does not run. A fresh check is a single Gemini snapshot; there is no history to draw and none may be invented.\n- Never present the Val as the full platform. Bounds stay stated on the surface that shows the number.\n- `src/mcp/skills/` is generated. Edit `skills//` at the repository root, then run\n `node scripts/sync-val-town-skills.mjs` and commit the result. Never hand-edit a generated module.\n\n## MCP endpoint\n\n`POST /mcp` serves Model Context Protocol over Streamable HTTP so an agent can read this Val's checks directly. It is\nadditive: every browser route is unchanged, and the endpoint shares the same `CheckStore`, so an agent sees exactly the\nchecks the UI shows.\n\n- **Reads never spend.** `get_check`, `get_ai_visibility`, and `get_site_health` resolve through `store.get` and\n `store.findReusable` only. They must never reach `admit` or `dispatch`; a test asserts an uncached domain lookup\n leaves the store untouched.\n- **`start_check` is the only tool that spends,** and it runs the host's full admission path. It skips Turnstile,\n which an agent cannot solve, and spends from its own `mcp:` quota subject with its own daily limit. It must keep\n sharing the global daily cap and the single execution lease: the global cap is what bounds the bill, so MCP may\n widen who spends the budget but never how large it is. Disable with `CANONRY_MCP_START_CHECKS=0`.\n- **It blocks.** Execution is request-bound (`AbortSignal.timeout(45_000)`); there is no background queue, so\n returning a check ID early would kill the work with the request.\n- **Anonymous, on purpose.** Everything reachable here is already public: `/api/checks/:id` serves any check without a\n credential, and the skills ship in a public npm package. A token would gate nothing and would make the endpoint\n useless as something an agent is simply pointed at.\n- **Two protocol eras.** Revision `2026-07-28` removed sessions and the GET stream; every shipping client still opens\n with `initialize`. Both work. Keep the strict mirrored-header checks keyed off the version the caller declared, or\n legacy clients break.\n- Responses are always `application/json`. Nothing here streams, so do not add an SSE encoder.\n- `self_host` is the conversion path and costs nothing. Keep it in the read set and keep its comparison honest.\n- Mention and citation stay independent in tool output, and a failed check stays `null` rather than becoming `false`.\n\n## Share of voice\n\n`src/visibility/share.ts` ranks every domain the engine attributed as a source across the answers.\n\n- **It is CITATION share, and the label must say so.** Mention share needs the rivals' brand names so they can be\n matched in the answer text. A public check has no competitor list, and the probe contract in\n `src/visibility/contracts.ts` forbids the shortcut: brand names are exact approved aliases and a prose alias is\n never derived from a domain. Inferring \"stripe.com is in the sources, so the word Stripe here is a rival mention\"\n is precisely the guess that contract rules out. Do not add it.\n- **A domain counts once per answer, never once per link.** Ten links to one documentation site is one site holding\n one answer; counting links would let a single well-linked page outrank a domain cited across every answer.\n- **A failed answer is unmeasured and cannot enter the denominator.** A successful answer that attributed no source is\n counted separately and stated, because an answer with no sources is not an answer where rivals won.\n- **The checked site keeps its row even at 0%,** and absorbs its own subdomains. A measured zero is the finding; a\n missing row reads as an error. The first version re-inserted the target only when it ranked BELOW the display cut,\n which silently dropped it whenever it was never cited at all: a domain absent from the ranking has no rank. Assert\n the ROW exists, not just that `targetShare` is zero, or the test passes while the UI omits it.\n- **Two bases, one ranker, never blended.** `Mentioned` is brands named in the answer prose; `Cited` is domains the\n engine attributed as sources. They are independent signals with separate tables, captions, column headers, and\n denominators, and `rank()` is shared so ordering, the display cut, and the tail cannot drift between them. The switch\n is two radios and a general-sibling CSS selector, never script: the page CSP blocks inline script, and a control that\n only works once an external file has loaded is broken on first paint. Radios also carry real keyboard semantics.\n- **Mention share exists only because of `mention-extract.ts`.** A mention is a name written in text, and nothing before\n the probes run knows the rivals' names. Deriving one from a cited domain is the exact inference `contracts.ts`\n forbids, so instead the model PROPOSES and exact matching DISPOSES: one extra bounded call lists the names each\n answer writes, and every proposal is re-verified with `namesWrittenIn`, the same adjacent-complete-words rule the\n target's own verdict uses. An invented, expanded, or translated name is not in the prose, so it is dropped. The\n target's row is counted from its OWN `mentioned` verdict, never from the extraction, because its aliases are approved\n and the extraction's are proposals.\n- **The extraction constrains its own output.** It uses no tool, so unlike the planner it can set `responseMimeType` +\n `responseSchema`; the planner has to hand-parse a fence because Gemini 2.5 refuses structured output alongside\n `googleSearch`. `thinkingBudget: 0` is set for the same reason the first live run returned nothing: thinking is on by\n default on 2.5 and bills from the same output allowance, so a reasoning model can spend the whole budget before\n writing a character and return empty text. Copying names out of a text needs no reasoning.\n- **`namedBrands: null` is unmeasured, not empty.** An answer the extraction never covered leaves the mention basis out\n of the denominator entirely. Counting it as naming nobody would deflate every share by an outage instead of\n reporting one.\n- **The Val budget is now five provider calls** (1 planner, 3 probes, 1 extraction), pinned by\n `visibility-gemini.test.ts`. That number is meant to be noticed when a feature adds a call.\n- **It is a donut, and the hole is the point.** The target's own share is written into the ring's centre and stated\n nowhere else. A share chart where the reader hunts for their own row has buried its own headline, and the section\n header used to print the same number a second time. Arc lengths come from the COUNTS, never from the rounded display\n percent: eight rows each rounded to 5% leave a ring visibly short of closing. Geometry rides on SVG attributes\n (`stroke-dasharray`, `stroke-dashoffset`), never inline style, because the page CSP blocks the latter. One neutral\n ramp drives both the arc stroke and the legend swatch through a `--share-color` custom property, so a colour is\n written once.\n- **The tail is a stated fact, not a row.** Folding it into `entries` printed \"12 more sites, 12 of 2 answers\", where\n the answers column counted appearances spread over twelve domains against the answer count. It is its own field, it\n keeps its bar segment, and the head plus the tail still total 1.\n- Segment geometry is SVG attributes, never inline style: the page CSP blocks inline styles. The checked site is the\n only coloured segment; rivals sit on a neutral ramp, because hues would imply a taxonomy that does not exist.\n\n## The engine pin lives in source, so the bump sweeps source\n\nVal Town ignores an import map, so every import is fully qualified inline:\n`npm:@canonry/aeo-audit@7.1.0`, repeated in each file that imports the engine. That is N places to drift instead of\none `deno.json` key.\n\n`scripts/bump-aeo-audit.mjs` therefore SWEEPS `apps/val-town/src` and `main.http.tsx` rather than editing a manifest\nkey, and `aeo-audit-dependency-contract.test.ts` asserts the set of inline specifiers collapses to exactly one version\nthat equals Canonry's pin. Both were written against the import map the val briefly had; the bump would have thrown on\nevery engine release and the val would have sat on an old engine while Canonry moved.\n\nA new file importing the engine is picked up with no change to either, which is the point of scanning rather than\nlisting.\n\n## A failed start must not look like a bounce\n\n`.form-busy` carries two different things: \"Starting check…\" and the reason a check failed. They used to be the same\n13px `--secondary` line, sitting directly under `#queries-help`, which is also 13px `--secondary`, and `.check-facts`\nat 12px muted. So when `restore()` hid the waiting view and un-hid the hero, the page appeared to bounce back to the\nform with nothing said, while the reason sat on screen as the fourth of four near-identical grey lines.\n\nA failure now gets `is-error`, which reuses the `.verification-unavailable` treatment already in the stylesheet\n(`--caution`, circled `!`). The glyph is generated content, not markup, because the message is set with `textContent`.\n`markBusy()` clears the class, so a previous failure cannot outlive the next submit.\n\nThe stub `classList` in `render.test.ts` had only `toggle` and `contains`. Adding `add`/`remove` was needed, and the\nexisting behavioural test caught the missing method immediately, which is the argument for driving the real script in\nthe harness rather than asserting on its source. The failure half still needs a `FormData` stub to drive, so it is\npinned at the source; the clear-on-submit half is behavioural.\n\n## A basis with no data is offered and explained\n\nThe section renders BOTH radios always. A basis with nothing to show gets a pane saying so and a dimmed label, and the\ndefault selection lands on a basis that has data so the page never opens onto an empty pane.\n\nIt used to render only the bases it had, which meant a check with no mention data lost the control entirely. A reader\ncannot tell a missing control from a broken page, and asked twice why the toggle was gone. This is not only about\nrecords written before the extraction shipped: the extraction call can fail on a live check, leaving `namedBrands:\nnull` on a fresh one.\n\n## Adding a measured signal bumps the reuse key\n\n`checkFingerprint` is `visibility-v3:` because checks now measure the brands each answer names. The key is the cache\nand the one-active-check index, so a v2 record kept satisfying requests for the same domain and served a result\nsilently missing half the report until it hit its own 24h TTL. The repo's own identity-vs-tuning rule covers this: a\nparameter, or a signal, that changes what the operation PRODUCES must join the reuse key.\n\nBumping retires those records for REUSE only. `?check=` still resolves, so a shared link keeps working and shows\nthe explained-empty mention pane.\n\n## A numeric column is aligned once, on the column\n\n`is-numeric` goes on the header AND on every cell in that column, and one rule keys off it. Alignment used to live on\nthe cell classes only (`.share-pct`, `.share-count`, `.inbound-cell`), so every header inherited the table's `left` and\nsat half a table away from its own numbers: \"ANSWERS\" on the left edge, \"1 of 2\" on the right. Two places that had to\nbe kept in step by hand, and were not.\n\n`render.test.ts` walks every rendered table, reads which header indices carry the class, and asserts each body cell at\nthat index agrees. Note the lookahead in its header regex: `]*>` also matches ``, which silently shifts\nevery column index by one and makes the guard report a failure in the wrong column.\n\n## The link graph is numbers, not a diagram\n\nThe crawl's internal-link graph is real and still stored, still in the `get_site_health` MCP payload, and still capped\nby `site-map.ts`. It is no longer DRAWN, and the reason is worth keeping.\n\nA 5-page crawl cannot support a graph. On real data every crawled page came back at `depth 0` and every discovered\ntarget at `depth null`, and inbound links took three distinct values across 24 nodes. The diagram claimed three visual\nchannels (column = click depth, height = inbound rank, size = inbound count) and two of them had no variation to show,\nso node position was effectively alphabetical. A picture whose caption asserts axes the data cannot fill reads as\ninvented, and a reader who says \"is this fake?\" is reading it correctly.\n\nAn earlier version was worse: it spaced nodes evenly around concentric rings, so the angle came from an array index.\nAdjacency is the first thing an eye reads in a graph, and there it meant nothing at all.\n\nWhat survived: inbound links are now a column on the sampled-pages table, joined from the same graph by URL, and the\nbounded-crawl counts (\"N of M pages and N of M internal links\") are a line under it. Both are pinned by tests, because\nthe risk when deleting a visual is silently deleting the facts it carried.\n\n## UI\n\nMatch the Canonry dashboard's restrained evidence-first hierarchy: compact header, underline tabs,\ncharts/tables/details, visible focus, and native disclosure controls. Do not port the full React SPA or add a card grid.\n\n#- **Factors are ranked by score, best first, at read time.** The audit engine emits its rollup alphabetically, which\n reads as a list of names rather than a result. Order is a reading decision over stored data, not part of the record,\n so `orderFactors` is applied where the data is read: the UI view model and the `get_site_health` payload call the\n same comparator, so a check written before the change ranks correctly too and the two surfaces never disagree about\n which factor is doing best. An unmeasured factor sorts LAST, never as a zero: \"not applicable to the sampled page\n types\" is the absence of a measurement, and ranking it below the worst real score claims it is worse than the worst\n thing found. Ties break by name, since several factors scoring 100 is the common case. Assert factors by id, never by\n index; a positional assertion in `render.test.ts` broke the moment the order became meaningful.\n\n## Site Health follows the dashboard's page audit\n\nOne collapsed `

` per factor, mirroring `apps/web/src/components/project/PageAuditEvidence.tsx`. The summary\ncarries the name, the page count, and the score, which is everything a reader needs to decide whether to open it. The\nevidence and the fix live together inside, because a problem and its remedy are one thought.\n\nIt used to be two columns, Factors beside Top fixes, built by flattening every recommendation away from the factor it\ncame from and printing the factor's name as the fix's own subtitle. The two columns restated each other, and a\nrecommendation repeated across five sampled pages appeared five times, so one templated problem read as five.\nRecommendations and findings are now deduped onto their factor.\n\nCritical defects sit outside the score, so they render above the list and are never collapsed.\n\n### The waiting state\n\nA check takes about 45 seconds and execution is request-bound, so a native form POST leaves the browser blocked on a\nnavigation for the whole time with nothing on screen but a disabled button. Script intercepts the submit, posts to\n`/api/checks`, and shows `renderLoadingView()` until the id comes back. The work still happens inside that one\nrequest; it is just no longer the thing the browser is painting.\n\n- **It claims only what is knowable while waiting.** The domain and the visitor's own questions are already theirs;\n elapsed time is counted, not guessed. The bar is indeterminate on purpose: the server reports no phase, and a bar\n that filled would be inventing progress.\n- **The two tracks are concurrent because they are.** The runner is `Promise.allSettled` over the probe and the crawl,\n so showing them as parallel is a fact, not a layout choice. Do not turn them into a sequence of phases.\n- **The no-script path must keep working.** The form still carries `method=\"post\" action=\"/check\"`, the enhancement\n falls back when the waiting view is absent, and a test asserts both.\n- **Reset Turnstile on failure.** A token is redeemed exactly once, and this page now survives a failed submit, so a\n retry without `turnstile.reset()` sends a spent token.\n- Motion is `transform` and `opacity` only, and stops entirely under `prefers-reduced-motion`.\n\n### Say it once\n\nThe page carried the same idea up to three times. It opened with a `DOMAIN REPORT` kicker over a derived display name\nover a subtitle naming the two tabs directly beneath it over the domain the name came from; then an `AI VISIBILITY`\nkicker repeating the active tab; then a sentence defining mention against cited, which the evidence section defined\nagain in its own words a screen later. All of it is named in `DESIGN.md` (\"Do not repeat a page choice through cards,\ntabs, and headings\") and in `PRODUCT.md`'s anti-references (\"Multiple headings that restate the same page\").\n\nSo: no section kickers. Six tiny uppercase labels over six headings is scaffolding, not voice, and the headings\nalready name their sections. The page title is the domain itself, because that is the subject and a derived name is\none more thing to read. Mention against cited is stated once, in the metric labels where the numbers are\n(`Mentioned in the answer`, `Cited as a source`), not in prose above them and again below.\n\nTone belongs in a whole frame and a glyph, never a coloured rail down one edge. A `border-left` heavier than 1px used\nas an accent is the side-stripe pattern; notices use a full tone-tinted border instead.\n\n### What is shared with `apps/web`, and what cannot be\n\nThe two surfaces must LOOK like one product, but they cannot SHARE code. `apps/web` is React 19 + Vite + Tailwind 4\nwith TanStack Query, and its components are bound to the generated SDK (`useQuery(getApiV1…Options({client:\nheyClient}))`). This Val is a Deno request handler that returns HTML strings, with no bundler and a `script-src 'self'`\npolicy. Importing a component would drag in the router, the query layer, and a Tailwind build.\n\nSo the design system is shared by VALUE, and the values must be copied exactly:\n\n- **Fonts.** Same package and version the dashboard bundles, `@fontsource-variable/geist@5.3.0` and `-mono`, loaded\n from jsDelivr because a Val cannot ship woff2 (binary files are rejected). Naming Geist in a font stack without\n loading it — which is what this page did originally — silently renders the whole surface in a system font.\n- **Typographic detail.** `font-feature-settings: \"cv11\", \"ss01\", \"ss03\"`, `-0.015em` heading tracking (`-0.02em` on\n h1), `\"ss02\", \"cv11\"` on monospace, and antialiasing. Without these the same typeface still reads as a different one.\n- **Colour.** Token values are copied from `apps/web/src/styles.css`, alpha included (`rgb(24 24 27 / 0.3)`), not\n eyeballed to a nearby hex. A test pins them.\n\nThe site map is the one place where sharing was considered and rejected. The dashboard solves its layout with\nForceAtlas2 + noverlap in a `node:worker_threads` worker and renders it with Sigma/WebGL, for graphs of 20k–50k nodes.\nVal Town has no worker threads, the page must render without JavaScript, and this graph is at most 24 nodes — a regime\nwhere a force simulation is both overkill and non-deterministic. The deterministic depth-ring layout is the right\ntool at this size, not a shortcut.\n\n## Architecture\n\n```mermaid\nflowchart LR\n B[Browser] --> H[Val Town Deno host]\n H --> V[Val-local visibility core]\n H --> A[@canonry/aeo-audit]\n V --> G[Gemini: 1 plan + 3 queries]\n A --> C[5-page site sample]\n G --> S[Sanitized check result]\n C --> S\n S --> Q[Val-scoped SQLite]\n Q --> B\n Q --> M[MCP endpoint /mcp]\n K[canonry + aero skills] --> M\n M --> N[Any MCP client]\n```\n\nThe Deno host owns HTTP routes, Turnstile, quotas, cache records, job leases, and HTML. Technical AEO comes from the\npinned audit engine. This Val owns the visibility contracts, bounded evidence runner, Gemini planner, and Gemini\nadapter. The visibility core does not read environment, storage, or HTTP state.\n\n```text\napps/val-town/\n├── main.http.tsx Val HTTP entry\n├── deno.json Deno tasks and lint policy\n├── deno.lock Deno dependency lock\n├── .vt/state.json Val and branch identity\n├── src/\n│ ├── app/ HTTP routes and response policy\n│ ├── config/ Environment configuration\n│ ├── jobs/ Request-bound check runner\n│ ├── mcp/ MCP transport, tools, and generated skill resources\n│ ├── security/ URL and Turnstile checks\n│ ├── site-health/ Technical AEO adapter\n│ ├── storage/ SQLite and memory ports\n│ ├── ui/ HTML, CSS, and browser script\n│ └── visibility/ Local contracts, evidence runner, Gemini planner and adapter\n└── test/ Deno backend and UI tests, plus the local dev server\n```\n\n## Dependencies\n\nEvery dependency is fully qualified at the import site (`npm:hono@4.12.25`, `https://esm.town/v/std/sqlite/main.ts`).\nVal Town resolves the module graph from esm.town and does NOT apply a pushed `deno.json` import map, so a bare\nspecifier deploys and then throws `not a dependency and not in import map` at the first request. `deno.json` therefore\nexcludes the `no-import-prefix` lint rule, which exists to enforce the opposite convention.\n\n## Fixed public limits\n\n- A visitor may supply up to three questions; the planner generates only the remainder, and is not called at all when\n all three are supplied. Supplied questions are IDENTITY, not tuning: they join `checkFingerprint`, so two callers\n asking different questions about one domain never share a cached result.\n- One grounded Gemini planning call creates the questions the visitor did not supply.\n- Three Gemini checks run with a concurrency limit of two.\n- The site sample checks at most five pages and 2,500 edges.\n- The full request stops after 45 seconds.\n- Turnstile, daily quotas, one active job, and a 24-hour cache bound public use.\n- The link map displays at most 24 nodes and 60 edges, and says so when it truncates.\n\nThe host scopes `allowPrivateHost` to the one host being crawled, per the boundary above. Failed provider\nchecks stay `Not measured` and do not reduce reported rates.\n\n## Local development\n\n```sh\ndeno task dev # http://localhost:8787 — stub runners, no network\nGEMINI_API_KEY=… deno task dev # real Gemini planner, probes, and crawl\n```\n\nIn-memory storage and no Turnstile, so the UI and `/mcp` both work without credentials. `npx\n@modelcontextprotocol/inspector` against `http://localhost:8787/mcp` drives the endpoint as a real client would.\n\n## Verification\n\nRun `deno task check`, `deno task lint`, and `deno task test` from this directory, and\n`node scripts/sync-val-town-skills.mjs --check` from the repository root. A deployment additionally requires a\n`vt push --dry-run` and a live health smoke test.\n\n## Production configuration\n\nSet in Val Town: `VAL_TOWN_ENV=production`, `GEMINI_API_KEY`, `CANONRY_QUOTA_SALT`, `TURNSTILE_SECRET_KEY`,\n`TURNSTILE_SITE_KEY`, `TURNSTILE_ALLOWED_HOSTNAMES`. Optional: `CANONRY_MCP_START_CHECKS=0` removes the MCP write\ntool; `CANONRY_MCP_PER_CLIENT_DAILY_LIMIT` sets its daily per-caller allowance (default 2).\n\nPublic checks are disabled when the production quota salt or Turnstile configuration is absent, so an unconfigured\ndeployment serves reads and skills but refuses to spend.\n\n## Release order\n\n1. Regenerate `deno.lock`, and the skill mirror with `node scripts/sync-val-town-skills.mjs`.\n2. Run the verification commands above.\n3. Run `vt push --dry-run` and review the file plan.\n4. Run `vt push` only after approval.\n5. Request `/healthz` and confirm `{\"ok\":true}`.\n\n`vt push` makes the Val match this directory. It deletes remote-only files, so do not edit production in the Val Town\neditor.\n\n## A failed check says why\n\n`mentioned: null` / `cited: null` is a check that did not happen, and the row reads \"Not measured\". The runner already\nclassifies why into a closed set of safe strings (timed out, rate-limited, temporarily unavailable, credentials\nrejected, no answer text, unusable model, cancelled, generic), and `gemini-probe.ts` carries the message through.\n\nThe public sanitizer used to overwrite all of it with one \"This answer-engine check was unavailable.\". Nothing is\nlogged either, so the reason existed for one function call and was then destroyed: a row nobody, operator included,\ncould explain afterwards. `publicProbeError` now translates each known message into visitor wording (\"answer engine\",\nnot \"provider\") and falls back to the generic sentence for anything it does not recognize, so a sanitizer still never\ntrusts its input.\n\n`probe-error-copy.test.ts` drives the REAL runner into each failure, then asserts none of them lands on the generic\nfallback. That is the guard: a new failure mode added upstream without a translation fails the suite instead of\nsilently erasing its own reason. The banner leads with the reason only when every failed check shares one; with two\ndifferent reasons it would have to pick one and be wrong about the rest, so it defers to the per-row evidence.\n\n## Say it once, and say it where it belongs\n\nThe block under the landing form was three paragraphs of identical muted grey carrying five facts, two of them twice:\nthe question count sat in the hint and again in the page footer, and the single engine sat in its own sentence and\nagain in the footer. Repetition with no contrast is what made it read as a wall.\n\nIt is now two lines with two steps of hierarchy:\n\n- The **hint** (13px, `--secondary`) is an instruction and belongs to the questions field. `DESIGN.md` reserves\n `--muted` for nonessential metadata and forbids putting instructions in it, which is what the old block did with all\n three lines.\n- The **facts row** (12px, `--muted`, dot-separated) is scope metadata, so muted is correct there. It reuses the\n `.sample-facts` separator vocabulary, including the narrow-width collapse to a stack, since a wrapped item that\n begins with a separator reads as broken.\n\nThe footer sentence is gone from the LANDING, where the facts row above it already says everything, and kept on the\nRESULT page, where there is no form and a report read on its own must still state what it is a sample of. Both are\npinned by tests. The redundancy test counts on the visible block only: the tooltip's copy is deliberately written\ntwice, once as the trigger's accessible name and once as the body, which is one statement for two audiences.\n\n## The heading's tooltip is CSS only\n\nThe landing explains itself through a note on the heading rather than a subtitle. It opens on `:hover` and, critically,\n`:focus-within` — the page CSP allows no inline script, and the trigger must work before the enhancement script loads\nor without it at all. That is why the trigger is a real `${\n escapeHtml(copy)\n }`\n}\n\nfunction renderCheckForm(model: CanonryDemoViewModel, variant: 'hero' | 'compact' = 'compact'): string {\n if (!model.form) return ''\n const value = model.status === 'demo' || model.status === 'empty' ? '' : model.domain\n const verificationStatus = model.form.verificationStatus ?? (model.form.turnstileSiteKey ? 'ready' : 'not-required')\n const hasTurnstile = Boolean(model.form.turnstileSiteKey && verificationStatus === 'ready')\n const disabled = verificationStatus === 'unavailable'\n // interaction-only: the challenge still runs on load, so a token is ready at\n // submit, but the widget is drawn only if the visitor has to do something.\n // The default (`always`) meant the result page carried a green \"Success!\"\n // panel next to the check-another-domain form, announcing the outcome of a\n // challenge for a submission that had not happened, beside a report that had.\n const verification = hasTurnstile\n ? `

`\n : verificationStatus === 'unavailable'\n ? `

!${\n escapeHtml(\n model.form.verificationUnavailableMessage ?? 'Human verification is unavailable. Public checks are disabled.',\n )\n }

`\n : ''\n const verificationSlot = verification\n ? `

${verification}

`\n : ''\n const hero = variant === 'hero'\n return `\n

\n \n

\n \n \n

\n ${\n hero\n ? `

\n Questions you want to show up for optional\n \n

Add up to ${MAX_USER_QUERIES}. We generate the rest. ${QUERY_HINT_SUFFIX}

`\n : ''\n }\n ${\n hero\n // Scope facts, one line, said once. They used to be a sentence here and\n // a second sentence in the footer, which repeated the engine and the\n // question count the hint above already states.\n ? `

Gemini only5-page technical SEO auditMore engines in open source Canonry

`\n : ''\n }\n \n ${verificationSlot}\n

`\n}\n\nfunction renderMain(model: CanonryDemoViewModel): string {\n const glyphHref = assetUrl(DEFAULT_GLYPH_SRC, canonryGlyph)\n const globalNotice =\n (model.status === 'demo' || model.status === 'ready' ? model.notice : model.notice ?? statusCopy(model.status)) ??\n undefined\n const loading = model.status === 'loading'\n const visibility = model.visibility\n // Nothing has been checked yet, so a report header, tabs, and two empty\n // panels are scaffolding around an absence. Lead with the one action instead.\n if (model.status === 'empty') {\n return `\n

\n \n

Does AI mention your brand?${renderInfoTip(LANDING_EXPLAINER)}

\n ${renderCheckForm(model, 'hero')}\n

\n ${renderLoadingView()}\n

\n \n

`\n }\n return `\n

\n \n

${escapeHtml(model.domain)}

\n ${model.locale ? `

${escapeHtml(model.locale)}

` : ''}\n

\n ${model.status === 'demo' ? 'Sample data' : ''}\n

\n ${renderNotice(globalNotice)}\n

\n \n \n

\n ${\n visibility\n ? `${renderVisibilityChart(visibility)}${renderShareSection(visibility)}${renderEvidence(visibility)}`\n : '

No visibility result

Start a check to inspect answer-engine evidence.

'\n }\n

\n \n \n \n

`\n}\n\n/** Returns a complete document so the runtime can use it as an HTTP response body. */\nexport function renderCanonryDemo(model: CanonryDemoViewModel): string {\n const title = `${model.displayName} | AI Visibility Check`\n return `\n\n \n \n \n \n ${escapeHtml(title)}\n \n \n \n \n \n \n ${\n model.form?.turnstileSiteKey && (model.form.verificationStatus ?? 'ready') === 'ready'\n ? ''\n : ''\n }\n \n ${renderMain(model)}\n`\n}\n\n/** Useful for a host that owns the outer document or wants an embedded fragment. */\nexport function renderCanonryDemoBody(model: CanonryDemoViewModel): string {\n return renderMain(model)\n}\n",[],[198,387,398],"555b38fe-64c9-4c6f-9734-139ff6dabb8a","mark.ts","5b89fa92-a667-11f1-a7f4-1607ee4eb77e",195,["D",1788318220417],"/**\n * The Canonry company marks, derived from `plugins/canonry/assets/logo-dark.svg`.\n *\n * Two forms, because a logo and a glyph do different jobs.\n *\n * `canonryMark` keeps the plate and is the favicon, where a mark needs its own\n * field. `canonryGlyph` is the same paths with the plate removed and the\n * viewBox cropped to the artwork: inside the plate the bird fills 58% of the\n * width, so at byline size it rendered as a speck, and the plate's warm #1C1413\n * fought this page's cool zinc surface. Cropping is a reframe, not a redraw;\n * the paths are untouched.\n *\n * The cream is the brand's own #FFFAED, and against zinc it is the one warm\n * thing on the page. That is the point: it is the only element here that is\n * Canonry rather than this tool.\n *\n * This is the company silhouette, not the red canary. The canary is the\n * dashboard app's mark; the two are deliberately different.\n */\nexport const canonryMark =\n ''\n\nexport const canonryGlyph =\n ''\n",[],[198,387,407],"e4144b58-ceb7-4b1c-9e71-c6a6eccbf2f7","index.ts","93608ea0-a63e-11f1-9b04-1607ee4eb77e",185,["D",1788315636199],8,"export { createPublicCheckForm } from './check-form.ts'\nexport { canonryDemoClientScript, QUERY_HINT_SUFFIX } from './client.ts'\nexport { emptyLandingViewModel, toCanonryDemoViewModel } from './from-check-record.ts'\nexport type { CheckRecordViewOptions } from './from-check-record.ts'\nexport { assetUrl, renderCanonryDemo, renderCanonryDemoBody } from './render.ts'\nexport { canonryGlyph, canonryMark } from './mark.ts'\nexport { canonryDemoStyles } from './styles.ts'\nexport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n DemoUiStatus,\n EvidenceSource,\n EvidenceState,\n ProviderDescriptor,\n QueryEvidenceViewModel,\n ShareEntryViewModel,\n ShareTailViewModel,\n ShareViewModel,\n SiteHealthDefectViewModel,\n SiteHealthFactorState,\n SiteHealthFactorViewModel,\n SiteHealthPageViewModel,\n SiteHealthProvenanceViewModel,\n SiteHealthViewModel,\n SiteMapEdgeViewModel,\n SiteMapNodeViewModel,\n SiteMapViewModel,\n UiAction,\n UiNotice,\n VisibilityMetric,\n VisibilitySummaryMetric,\n VisibilityViewModel,\n} from './types.ts'\n",[],[198,387,415],"9e01233f-a575-4b35-9295-e916b7f66f05","from-check-record.ts","9329ca82-a63e-11f1-9b04-1607ee4eb77e",203,["D",1788318219989],10,"import { orderFactors } from '../site-health/factor-order.ts'\nimport { computeMentionShare, computeShareOfVoice, type ShareOfVoice } from '../visibility/share.ts'\nimport type {\n CheckRecord,\n CheckResult,\n SiteHealthPageSample,\n SiteHealthSample,\n VisibilityEvidence,\n VisibilityReport,\n} from '../runtime/types.ts'\nimport { PUBLIC_CHECK_UNAVAILABLE, PUBLIC_RATE_LIMITED_ERROR_CODE } from '../runtime/types.ts'\nimport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n QueryEvidenceViewModel,\n SiteHealthDefectViewModel,\n SiteHealthFactorViewModel,\n SiteHealthPageViewModel,\n VisibilityViewModel,\n} from './types.ts'\n\nexport interface CheckRecordViewOptions {\n form?: CheckFormViewModel\n displayName?: string\n locale?: string\n title?: string\n}\n\nconst LOCAL_READY_FORM: CheckFormViewModel = {\n action: '/check',\n method: 'post',\n verificationFieldName: 'cf-turnstile-response',\n verificationStatus: 'not-required',\n submitLabel: 'Check a domain',\n}\n\n/**\n * Converts a sanitized, durable public-check record into the narrow UI model.\n * It deliberately never turns an absent provider report into a 0% score.\n */\nexport function toCanonryDemoViewModel(\n record: CheckRecord | null,\n options: CheckRecordViewOptions = {},\n): CanonryDemoViewModel {\n const domain = record?.domain ?? ''\n const result = record?.result ?? null\n const status = record ? mapStatus(record) : 'empty'\n const resultDomain = result?.domain || domain\n const displayName = options.displayName ?? nameFromDomain(resultDomain || 'Canonry')\n const visibility = result?.visibility ? mapVisibility(result.visibility) : undefined\n const siteHealth = result?.siteHealth ? mapSiteHealth(result.siteHealth, result.generatedAt) : undefined\n\n return {\n status,\n title: options.title,\n displayName,\n domain: resultDomain,\n locale: options.locale,\n form: { ...LOCAL_READY_FORM, ...options.form },\n visibility,\n siteHealth,\n notice: buildNotice(record, result),\n }\n}\n\nfunction mapStatus(record: CheckRecord): CanonryDemoViewModel['status'] {\n if (record.errorCode === PUBLIC_RATE_LIMITED_ERROR_CODE) return 'rate-limited'\n switch (record.status) {\n case 'queued':\n case 'running':\n return 'loading'\n case 'partial':\n return 'partial'\n case 'failed':\n return 'error'\n case 'complete':\n return 'ready'\n }\n}\n\n/**\n * Percentages are rounded for display only. The shares they come from sum to\n * exactly 1; rounding each independently can land the printed column on 99 or\n * 101, so the bar is drawn from the unrounded share and only the labels round.\n */\nfunction mapShare(report: VisibilityReport): VisibilityViewModel['share'] {\n return toShareView(computeShareOfVoice(report.evidence, report.domain), report.domain)\n}\n\n/**\n * The mention table is keyed by NAME, so the target's row is labelled with the\n * brand the answers actually wrote when they named it, falling back to the\n * domain when no answer named it at all. Labelling that row with the domain\n * would put a domain in a table of names.\n */\nfunction mapMentionShare(report: VisibilityReport): VisibilityViewModel['mentionShare'] {\n const label = targetBrandLabel(report)\n return toShareView(computeMentionShare(report.evidence, label), label)\n}\n\nfunction targetBrandLabel(report: VisibilityReport): string {\n for (const row of report.evidence) {\n // matchedTerms holds the approved aliases this answer actually wrote. The\n // domain can appear there too, and a domain is not the brand's name.\n const name = row.matchedTerms.find((term) => !term.includes('.'))\n if (name) return name\n }\n return report.domain\n}\n\nfunction toShareView(share: ShareOfVoice | null, targetLabel: string): VisibilityViewModel['share'] {\n if (!share) return undefined\n return {\n basis: share.basis,\n measuredAnswers: share.measuredAnswers,\n totalAppearances: share.totalAppearances,\n unattributedAnswers: share.unattributedAnswers,\n targetDomain: targetLabel,\n targetPercent: Math.round((share.targetShare ?? 0) * 100),\n tail: share.tail ? { domains: share.tail.domains, percent: Math.round(share.tail.share * 100) } : null,\n entries: share.entries.map((entry) => ({\n domain: entry.domain,\n answers: entry.answers,\n percent: Math.round(entry.share * 100),\n isTarget: entry.isTarget,\n })),\n }\n}\n\nfunction mapVisibility(report: VisibilityReport): VisibilityViewModel {\n const providers = uniqueProviders(report.evidence)\n const denominator = report.summary.successfulChecks\n const mentioned = report.evidence.filter((row) => row.mentioned).length\n const cited = report.evidence.filter((row) => row.cited).length\n const failed = report.summary.failedChecks\n return {\n historyKind: 'snapshot',\n share: mapShare(report),\n mentionShare: mapMentionShare(report),\n requestedAt: report.startedAt,\n checkedAt: report.completedAt,\n providers,\n summaries: {\n mentioned: {\n rate: percent(report.summary.mentionRate),\n numerator: mentioned,\n denominator,\n },\n cited: {\n rate: percent(report.summary.citationRate),\n numerator: cited,\n denominator,\n },\n },\n completedChecks: denominator,\n requestedChecks: denominator + failed,\n failedChecks: failed,\n evidence: report.evidence.map(mapEvidence),\n notice: failed > 0\n ? {\n tone: 'caution',\n title: `${failed} ${failed === 1 ? 'check' : 'checks'} unavailable`,\n // The reason leads, because that is what a row reading \"Not measured\"\n // makes someone ask. It is only stated when the failures agree on one;\n // with several reasons the banner would have to pick one and be wrong\n // about the rest, so it defers to the per-row evidence instead.\n detail: `${failureReason(report.evidence) ?? ''}Mention and citation rates use completed checks only.`,\n }\n : undefined,\n }\n}\n\n/** The one reason every failed check shares, or null when they disagree. */\nfunction failureReason(evidence: readonly VisibilityEvidence[]): string | null {\n const reasons = new Set(\n evidence.filter((row) => row.mentioned === null && row.cited === null)\n .map((row) => row.error)\n // The generic sentence is the absence of a reason, and every check stored\n // before the sanitizer kept one carries it. Leading with it produces\n // \"1 check unavailable. This answer-engine check was unavailable.\"\n .filter((error): error is string => Boolean(error) && error !== PUBLIC_CHECK_UNAVAILABLE),\n )\n if (reasons.size !== 1) return null\n const [reason] = [...reasons]\n return reason ? `${reason} ` : null\n}\n\nfunction uniqueProviders(evidence: readonly VisibilityEvidence[]): VisibilityViewModel['providers'] {\n const seen = new Map()\n for (const row of evidence) {\n if (seen.has(row.provider)) continue\n seen.set(row.provider, {\n id: row.provider,\n label: providerLabel(row.provider),\n model: row.requestedModel ?? undefined,\n })\n }\n return [...seen.values()]\n}\n\nfunction mapEvidence(row: VisibilityEvidence): QueryEvidenceViewModel {\n // The portable probe distinguishes all provider sources from the sources\n // whose URL actually matches the target. Accept the old runtime shape while\n // it rolls forward, but never mark every cited source as a target citation.\n const matchedCitationUrls = new Set(readMatchedCitationUrls(row))\n return {\n id: `${row.provider}:${row.query}:${row.completedAt}`,\n query: row.query,\n provider: row.provider,\n providerLabel: providerLabel(row.provider),\n requestedModel: row.requestedModel,\n servedModel: row.servedModel,\n completedAt: row.completedAt,\n mentioned: row.mentioned,\n cited: row.cited,\n matchedTerms: row.matchedTerms,\n answerText: row.answerText,\n sources: row.sources.map((source) => ({\n url: source.url,\n title: source.title,\n isTargetDomain: matchedCitationUrls.has(source.url),\n })),\n searchQueries: row.searchQueries,\n retrievalStatus: mapRetrievalStatus(row.retrievalStatus),\n error: row.error,\n }\n}\n\nfunction readMatchedCitationUrls(row: VisibilityEvidence): readonly string[] {\n return (row as VisibilityEvidence & { matchedCitationUrls?: readonly string[] }).matchedCitationUrls ?? []\n}\n\nfunction percent(value: number | null): number | null {\n if (value == null || !Number.isFinite(value)) return null\n return Math.max(0, Math.min(100, value * 100))\n}\n\nfunction mapRetrievalStatus(status: VisibilityEvidence['retrievalStatus']): QueryEvidenceViewModel['retrievalStatus'] {\n if (status === 'error') return 'failed'\n if (status === 'grounded') return 'success'\n if (status === 'not-grounded') return 'not-measured'\n return 'pending'\n}\n\nfunction mapSiteHealth(sample: SiteHealthSample, checkedAt: string): NonNullable {\n const complete = sample.pages.filter((page) => page.status === 'success').length\n const failed = sample.pages.filter((page) => page.status === 'error').length\n const attempted = Math.min(5, Math.max(sample.pages.length, sample.pagesObserved))\n return {\n sampleLabel: sample.label,\n score: sample.score,\n discoveredPages: sample.pagesDiscovered,\n attemptedPages: attempted,\n completedPages: complete,\n failedPages: failed,\n checkedAt,\n // Best score first. Alphabetical order reads as a list of names; ranked\n // order reads as a result, with the work to do gathered at the bottom.\n factors: orderFactors(\n sample.factors.map((factor) => {\n const state = factorState(sample, factor.id, factor.count)\n const evidence = factorEvidence(sample, factor.id)\n return {\n id: factor.id,\n label: factor.name,\n state,\n score: state === 'measured' ? factor.averageScore : null,\n findings: evidence.findings,\n recommendations: evidence.recommendations,\n detail: state === 'measured'\n ? `Measured across ${factor.count} sampled ${factor.count === 1 ? 'page' : 'pages'}.`\n : state === 'not-applicable'\n ? 'Not applicable to the sampled page types.'\n : 'Not measured in this sample.',\n }\n }),\n (factor) => ({ score: factor.score, label: factor.label }),\n ),\n criticalDefects: criticalDefects(sample),\n worstPages: sample.pages.map(mapSiteHealthPage),\n // Passed through as measured. A crawl with no usable graph stays absent\n // rather than becoming an empty diagram that implies a site with no links.\n siteMap: sample.siteMap && sample.siteMap.nodes.length > 0\n ? {\n nodes: sample.siteMap.nodes,\n edges: sample.siteMap.edges,\n totalPages: sample.siteMap.totalPages,\n totalEdges: sample.siteMap.totalEdges,\n truncated: sample.siteMap.truncated,\n }\n : undefined,\n terminationReason: sample.terminationReason,\n provenance: {\n schemaVersion: sample.schemaVersion,\n rootUrl: sample.rootUrl,\n finalRootUrl: sample.finalRootUrl,\n attemptedHosts: sample.attemptedHosts,\n engineVersion: readOptionalString(sample, 'engineVersion') ?? readOptionalString(sample, 'crawlEngineVersion'),\n },\n notice: sample.status === 'error' || sample.error\n ? {\n tone: 'caution',\n title: 'Site sample unavailable',\n detail: sample.error ?? 'The Technical AEO sample could not complete.',\n }\n : sample.status === 'partial'\n ? {\n tone: 'caution',\n title: 'Partial site sample',\n detail: 'Only completed pages contribute to the shown evidence.',\n }\n : sample.warnings.length\n ? { tone: 'caution', title: 'Sample warning', detail: sample.warnings[0]! }\n : undefined,\n }\n}\n\nfunction factorState(sample: SiteHealthSample, factorId: string, count: number): SiteHealthFactorViewModel['state'] {\n if (count > 0) return 'measured'\n const sampled = sample.pages.flatMap((page) => page.factors.filter((factor) => factor.id === factorId))\n if (sampled.length > 0 && sampled.every((factor) => factor.applicable === false)) return 'not-applicable'\n return 'unavailable'\n}\n\nfunction readOptionalString(value: object, key: string): string | null {\n const candidate = (value as Record)[key]\n return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : null\n}\n\nfunction mapSiteHealthPage(page: SiteHealthPageSample): SiteHealthPageViewModel {\n const findings = [\n ...page.criticalDefects.map((defect) => defect.detail),\n ...page.factors.flatMap((factor) => factor.findings.map((finding) => finding.message)),\n ...(page.error ? [page.error] : []),\n ].filter(Boolean).slice(0, 6)\n return {\n url: page.url,\n score: page.score,\n status: page.status === 'error' ? 'unavailable' : (page.score ?? 0) >= 80 ? 'good' : 'needs-attention',\n findings,\n indexable: indexability(page.indexability),\n }\n}\n\n/**\n * Findings and fixes belong to the factor they came from.\n *\n * They used to be flattened into one \"Top fixes\" column beside a \"Factors\"\n * column, which separated a problem from its cause and printed the factor name\n * as the fix's own subtitle: the two columns restated each other. Aggregating\n * per factor, the way the dashboard's page audit does, means one row carries\n * the name, the score, the evidence, and what to do about it.\n *\n * Deduped across sampled pages because five pages of one template produce five\n * copies of the same sentence, and a list of five identical fixes reads as five\n * problems.\n */\nfunction factorEvidence(sample: SiteHealthSample, factorId: string): {\n findings: string[]\n recommendations: string[]\n} {\n const findings = new Set()\n const recommendations = new Set()\n for (const page of sample.pages) {\n for (const factor of page.factors) {\n if (factor.id !== factorId) continue\n for (const finding of factor.findings) if (finding.message) findings.add(finding.message)\n for (const recommendation of factor.recommendations) if (recommendation) recommendations.add(recommendation)\n }\n }\n return { findings: [...findings], recommendations: [...recommendations] }\n}\n\n/**\n * Defects sit outside the score, so they stay visible rather than collapsing\n * behind a disclosure with everything else.\n */\nfunction criticalDefects(sample: SiteHealthSample): SiteHealthDefectViewModel[] {\n const byKey = new Map()\n for (const page of sample.pages) {\n for (const defect of page.criticalDefects) {\n const key = `${defect.id}:${defect.detail}`\n const existing = byKey.get(key)\n if (existing) existing.pages += 1\n else {\n byKey.set(key, {\n id: defect.id,\n severity: defect.severity,\n detail: defect.detail,\n recommendation: defect.recommendation,\n pages: 1,\n })\n }\n }\n }\n return [...byKey.values()]\n}\n\nfunction indexability(value: string | null): boolean | null {\n if (!value) return null\n if (value === 'eligible' || value === 'indexable') return true\n if (value === 'hidden' || value === 'failed' || value === 'not-indexable') return false\n return null\n}\n\nfunction providerLabel(provider: string): string {\n const known: Record = {\n gemini: 'Gemini',\n openai: 'OpenAI',\n claude: 'Claude',\n perplexity: 'Perplexity',\n }\n return known[provider] ?? (provider ? `${provider.slice(0, 1).toUpperCase()}${provider.slice(1)}` : 'Unknown engine')\n}\n\nfunction buildNotice(record: CheckRecord | null, result: CheckResult | null): CanonryDemoViewModel['notice'] {\n if (!record) return undefined\n if (record.errorCode === PUBLIC_RATE_LIMITED_ERROR_CODE) {\n return {\n tone: 'caution',\n title: 'Check limit reached',\n detail: record.errorMessage ?? 'This public sample has reached its current limit. Try again later.',\n }\n }\n if (record.status === 'failed') {\n return {\n tone: 'negative',\n title: 'This check could not finish',\n detail: record.errorMessage ?? 'Try another public domain later.',\n }\n }\n if (result?.errors.length) {\n const first = result.errors[0]!\n return {\n tone: 'caution',\n title: first.area === 'visibility' ? 'Visibility was unavailable' : 'Site sample was unavailable',\n detail: first.message,\n }\n }\n return undefined\n}\n\nfunction nameFromDomain(domain: string): string {\n const host = domain.replace(/^www\\./i, '').split('.')[0] ?? domain\n return host\n .replace(/[-_]+/g, ' ')\n .replace(/\\b\\w/g, (letter) => letter.toUpperCase())\n}\n\n/**\n * The landing view, shown before anything has been checked.\n *\n * It carries no `visibility` and no `siteHealth` because nothing has been\n * measured yet. Earlier this page rendered a fixture — four answer engines,\n * a four-week trend, invented model identifiers — labelled only by a badge in\n * the header, well above the numbers it qualified. Anyone scrolling read\n * fabricated data as measurement, and it advertised three engines this tool\n * does not run. An empty state is the honest thing to show when the answer is\n * \"nothing yet\".\n */\nexport function emptyLandingViewModel(form: CheckFormViewModel): CanonryDemoViewModel {\n return {\n status: 'empty',\n title: 'AI Visibility Check',\n displayName: 'Check a domain',\n domain: '',\n form,\n }\n}\n",[],[198,387,424],"ebebf191-63d3-4bd5-a0da-c99bdac6307f","client.ts","933a30f2-a63e-11f1-aa2a-1607ee4eb77e",220,["D",1788362833780],"/**\n * The one place the timing is written. The script below rewrites the query\n * hint's text on every keystroke, so a suffix left only in the server markup\n * would survive until the visitor types and then silently disappear.\n */\nexport const QUERY_HINT_SUFFIX = 'Takes about 45 seconds.'\n\n/** Client-side enhancement only. The page remains usable with native forms and details. */\nexport const canonryDemoClientScript = `\n(() => {\n const tabs = Array.from(document.querySelectorAll('[data-report-tab]'));\n const panels = Array.from(document.querySelectorAll('[data-report-panel]'));\n const setTab = (name, focus) => {\n tabs.forEach((tab) => {\n const active = tab.dataset.reportTab === name;\n tab.setAttribute('aria-selected', String(active));\n tab.tabIndex = active ? 0 : -1;\n if (active && focus) tab.focus();\n });\n panels.forEach((panel) => { panel.hidden = panel.dataset.reportPanel !== name; });\n };\n tabs.forEach((tab, index) => {\n tab.addEventListener('click', () => setTab(tab.dataset.reportTab, false));\n tab.addEventListener('keydown', (event) => {\n if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;\n event.preventDefault();\n const target = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : tabs.length - 1)) % tabs.length;\n const next = tabs[target];\n if (next) setTab(next.dataset.reportTab, true);\n });\n });\n const queries = document.querySelector('[data-query-hint]');\n const queryInput = document.getElementById('queries-input');\n if (queries && queryInput) {\n const max = Number(queries.dataset.max || 3);\n const update = () => {\n const used = queryInput.value.split('\\\\n').map((line) => line.trim()).filter((line) => line.length >= 3).length;\n const kept = Math.min(used, max);\n const rest = max - kept;\n const counts = kept === 0\n ? 'Add up to ' + max + '. We generate the rest.'\n : rest === 0\n ? 'Using your ' + kept + '. We generate none.'\n : 'Using your ' + kept + '. We generate the other ' + rest + '.';\n // Interpolated at module load so the server markup and every rewrite of\n // this line read one constant.\n queries.textContent = counts + ' ' + ${JSON.stringify(QUERY_HINT_SUFFIX)};\n };\n queryInput.addEventListener('input', update);\n update();\n }\n\n const form = document.querySelector('[data-domain-check-form]');\n if (form) {\n const submit = form.querySelector('[data-domain-submit]');\n const busy = form.querySelector('[data-form-busy]');\n const checking = document.querySelector('[data-checking]');\n\n const markBusy = () => {\n form.setAttribute('aria-busy', 'true');\n if (submit instanceof HTMLButtonElement) {\n submit.disabled = true;\n submit.setAttribute('aria-disabled', 'true');\n submit.textContent = 'Starting…';\n }\n if (busy) {\n busy.hidden = false;\n busy.classList.remove('is-error');\n busy.textContent = 'Starting check…';\n }\n };\n\n // Without the waiting view there is nothing to enhance: fall back to the\n // native POST, which still works, just with a blocked browser.\n if (!checking) {\n form.addEventListener('submit', markBusy);\n } else {\n const elapsedEl = checking.querySelector('[data-checking-elapsed]');\n const domainEl = checking.querySelector('[data-checking-domain]');\n const queriesEl = checking.querySelector('[data-checking-queries]');\n const hero = document.querySelector('[data-hero]');\n\n const restore = (message) => {\n checking.hidden = true;\n if (hero) hero.hidden = false;\n form.removeAttribute('aria-busy');\n if (submit instanceof HTMLButtonElement) {\n submit.disabled = false;\n submit.removeAttribute('aria-disabled');\n submit.textContent = submit.dataset.label || 'Check a domain';\n }\n if (busy) {\n busy.hidden = false;\n // A failure and \"Starting check…\" used to be the same 13px grey line,\n // sitting under two more 13px grey lines. Hiding the waiting view and\n // restoring the hero then read as the page bouncing back to the form\n // with no explanation, when the explanation was right there.\n busy.classList.add('is-error');\n busy.textContent = message;\n }\n // A Turnstile token is redeemed exactly once. The page is still here\n // after a failure, so the spent token has to be replaced before the\n // visitor can try again.\n if (window.turnstile && typeof window.turnstile.reset === 'function') {\n try { window.turnstile.reset(); } catch (_) { /* widget absent */ }\n }\n };\n\n form.addEventListener('submit', (event) => {\n const data = new FormData(form);\n const domain = String(data.get('domain') || '').trim();\n if (!domain) return;\n event.preventDefault();\n markBusy();\n\n if (domainEl) domainEl.textContent = domain;\n const typed = String(data.get('queries') || '')\n .split('\\\\n').map((line) => line.trim()).filter((line) => line.length >= 3).slice(0, 3);\n if (queriesEl) {\n queriesEl.textContent = '';\n for (const question of typed) {\n const item = document.createElement('li');\n item.textContent = question;\n queriesEl.appendChild(item);\n }\n queriesEl.hidden = typed.length === 0;\n }\n if (hero) hero.hidden = true;\n checking.hidden = false;\n\n const started = Date.now();\n const tick = setInterval(() => {\n if (elapsedEl) elapsedEl.textContent = Math.round((Date.now() - started) / 1000) + 's';\n }, 1000);\n\n fetch(form.dataset.jsonAction || '/api/checks', {\n method: 'POST',\n headers: { 'content-type': 'application/json', accept: 'application/json' },\n body: JSON.stringify({\n domain: domain,\n queries: typed,\n turnstileToken: data.get('cf-turnstile-response') || null,\n }),\n })\n .then((response) => response.json().then((body) => ({ ok: response.ok, body: body })))\n .then((result) => {\n clearInterval(tick);\n const id = result.body && result.body.check && result.body.check.id;\n if (result.ok && id) {\n location.href = '/?check=' + encodeURIComponent(id);\n return;\n }\n const error = result.body && result.body.error;\n restore((error && error.message) || 'The check could not be started. Try again.');\n })\n .catch(() => {\n clearInterval(tick);\n restore('The check could not be reached. Try again.');\n });\n });\n }\n }\n})();\n`\n",[],[198,387,433],"bdd01eca-55df-4b2d-8bff-52e3ec3f77da","check-form.ts","9316a416-a63e-11f1-8fd4-1607ee4eb77e",19,["D",1788292311023],"import type { ValTownConfig } from '../config/index.ts'\nimport type { CheckFormViewModel } from './types.ts'\n\ntype PublicCheckFormConfig = Pick<\n ValTownConfig,\n | 'publicChecksEnabled'\n | 'publicChecksUnavailableMessage'\n | 'humanVerificationStatus'\n | 'turnstileSiteKey'\n>\n\n/** Builds the public form from the complete admission capability, not CAPTCHA alone. */\nexport function createPublicCheckForm(config: PublicCheckFormConfig): CheckFormViewModel {\n const unavailable = !config.publicChecksEnabled\n return {\n action: '/check',\n method: 'post',\n verificationFieldName: 'cf-turnstile-response',\n turnstileSiteKey: unavailable ? null : config.turnstileSiteKey,\n turnstileAction: 'audit',\n verificationStatus: unavailable ? 'unavailable' : config.humanVerificationStatus,\n verificationUnavailableMessage: unavailable\n ? config.publicChecksUnavailableMessage ?? 'Public checks are temporarily unavailable.'\n : 'Human verification is not configured. Public checks are disabled.',\n submitLabel: 'Check a domain',\n }\n}\n",[],[198,387,441],"860a6741-04fd-4cac-81b8-88fa850c061e",["D",1788292309086],[260,261,262,263,264,265,266,267],[198,387],"b6cd75f1-b77a-4bf1-bd7b-7837b74f1cd9","val-sqlite.ts","96cede34-a63e-11f1-b854-1607ee4eb77e","927bf83a-a63e-11f1-8d00-1607ee4eb77e",126,["D",1788309825717],"import type {\n CheckAdmission,\n CheckAdmissionInput,\n CheckRecord,\n CheckResult,\n CheckStatus,\n CheckStore,\n} from '../runtime/types.ts'\n\ntype SqlArg = string | number | null\n\nexport interface ValSqliteStatement {\n sql: string\n args?: SqlArg[] | Record\n}\n\nexport interface ValSqliteResult {\n rows: unknown[]\n}\n\n/** Minimal structural type of Val Town's initialized @libsql/client instance. */\nexport interface ValSqliteClient {\n execute(statement: string | ValSqliteStatement): Promise\n /**\n * Val Town documents `batch` as the multi-statement primitive. `write` mode\n * applies every statement as one SQLite transaction.\n */\n batch(statements: ValSqliteStatement[], mode: 'write'): Promise\n}\n\nconst ADMISSION_PENDING = '__canonry_admission_pending__'\nconst ADMISSION_CLIENT_CLAIMED = '__canonry_admission_client_claimed__'\nconst ADMISSION_GRANTED = '__canonry_admission_granted__'\n\nconst ADDITIVE_COLUMNS = [\n 'ALTER TABLE canonry_checks ADD COLUMN user_queries TEXT',\n]\n\nconst SCHEMA = [\n `CREATE TABLE IF NOT EXISTS canonry_checks (\n id TEXT PRIMARY KEY,\n fingerprint TEXT NOT NULL,\n domain TEXT NOT NULL,\n status TEXT NOT NULL,\n created_at TEXT NOT NULL,\n updated_at TEXT NOT NULL,\n expires_at TEXT,\n result_json TEXT,\n error_code TEXT,\n error_message TEXT,\n lease_owner TEXT,\n lease_until TEXT,\n user_queries TEXT\n )`,\n 'CREATE INDEX IF NOT EXISTS canonry_checks_reuse ON canonry_checks (fingerprint, created_at DESC)',\n 'CREATE INDEX IF NOT EXISTS canonry_checks_lease ON canonry_checks (status, lease_until)',\n // A second active record would be paid duplicate work even if a caller\n // bypassed the admission batch. Terminal/cached history stays unconstrained.\n \"CREATE UNIQUE INDEX IF NOT EXISTS canonry_checks_one_active ON canonry_checks (fingerprint) WHERE status IN ('queued', 'running')\",\n `CREATE TABLE IF NOT EXISTS canonry_quota (\n scope TEXT NOT NULL,\n subject TEXT NOT NULL,\n day TEXT NOT NULL,\n count INTEGER NOT NULL,\n PRIMARY KEY (scope, subject, day)\n )`,\n `CREATE TABLE IF NOT EXISTS canonry_leases (\n name TEXT PRIMARY KEY,\n holder TEXT NOT NULL,\n expires_at TEXT NOT NULL\n )`,\n]\n\n/** Val-scoped SQLite adapter. SQL remains behind the store port for local/test parity. */\nexport class ValSqliteCheckStore implements CheckStore {\n constructor(private readonly sqlite: ValSqliteClient) {}\n\n async initialize(): Promise {\n for (const statement of SCHEMA) await this.sqlite.execute(statement)\n // A table created before `user_queries` existed will not gain it from\n // CREATE TABLE IF NOT EXISTS. ALTER is the only way to reach it, and it\n // throws once the column is present, which is the steady state.\n for (const statement of ADDITIVE_COLUMNS) {\n try {\n await this.sqlite.execute(statement)\n } catch {\n // Already applied.\n }\n }\n }\n\n /** Atomically reuse, reclaim, spend quota, and create in Val's documented write batch. */\n async admit(input: CheckAdmissionInput): Promise {\n const results = await this.sqlite.batch(this.admissionBatch(input), 'write')\n const reclaimed = results[0]?.rows[0] ? rowToCheck(results[0].rows[0]) : null\n const candidateCreated = results[1]?.rows.length === 1\n const clientQuotaClaimed = results[2]?.rows.length === 1\n const globalQuotaClaimed = results[4]?.rows.length === 1\n const reusable = results[10]?.rows[0] ? rowToCheck(results[10].rows[0]) : null\n\n if (reclaimed && reusable) return { kind: 'reclaimed', record: reusable }\n if (!candidateCreated && reusable) return { kind: 'reused', record: reusable }\n if (candidateCreated && !clientQuotaClaimed) return { kind: 'quota-exhausted', scope: 'client' }\n if (candidateCreated && !globalQuotaClaimed) return { kind: 'quota-exhausted', scope: 'global' }\n if (candidateCreated && reusable) return { kind: 'created', record: reusable }\n\n throw new Error('Atomic admission completed without a reusable or created check.')\n }\n\n findReusable(fingerprint: string, now: string): Promise {\n return this.findReusableWith(fingerprint, now)\n }\n\n async create(record: CheckRecord): Promise {\n await this.createWith(record)\n }\n\n async get(id: string): Promise {\n const result = await this.sqlite.execute({ sql: 'SELECT * FROM canonry_checks WHERE id = ? LIMIT 1', args: [id] })\n return result.rows[0] ? rowToCheck(result.rows[0]) : null\n }\n\n async update(\n id: string,\n patch: Partial>,\n ): Promise {\n const fields: string[] = []\n const args: SqlArg[] = []\n if (patch.status !== undefined) {\n fields.push('status = ?')\n args.push(patch.status)\n }\n if (patch.updatedAt !== undefined) {\n fields.push('updated_at = ?')\n args.push(patch.updatedAt)\n }\n if (patch.expiresAt !== undefined) {\n fields.push('expires_at = ?')\n args.push(patch.expiresAt)\n }\n if (patch.result !== undefined) {\n fields.push('result_json = ?')\n args.push(patch.result ? JSON.stringify(patch.result) : null)\n }\n if (patch.errorCode !== undefined) {\n fields.push('error_code = ?')\n args.push(patch.errorCode)\n }\n if (patch.errorMessage !== undefined) {\n fields.push('error_message = ?')\n args.push(patch.errorMessage)\n }\n if (fields.length === 0) return this.get(id)\n args.push(id)\n await this.sqlite.execute({ sql: `UPDATE canonry_checks SET ${fields.join(', ')} WHERE id = ?`, args })\n return this.get(id)\n }\n\n async claimJob(id: string, owner: string, now: string, leaseUntil: string): Promise {\n const result = await this.sqlite.execute({\n sql: `UPDATE canonry_checks\n SET status = 'running', updated_at = ?, lease_owner = ?, lease_until = ?\n WHERE id = ? AND (status = 'queued' OR (status = 'running' AND (lease_until IS NULL OR lease_until <= ?)))\n RETURNING *`,\n args: [now, owner, leaseUntil, id, now],\n })\n return result.rows[0] ? rowToCheck(result.rows[0]) : null\n }\n\n async finalizeJob(\n id: string,\n owner: string,\n patch: Partial>,\n ): Promise {\n const fields: string[] = ['lease_owner = NULL', 'lease_until = NULL']\n const args: SqlArg[] = []\n if (patch.status !== undefined) {\n fields.push('status = ?')\n args.push(patch.status)\n }\n if (patch.updatedAt !== undefined) {\n fields.push('updated_at = ?')\n args.push(patch.updatedAt)\n }\n if (patch.expiresAt !== undefined) {\n fields.push('expires_at = ?')\n args.push(patch.expiresAt)\n }\n if (patch.result !== undefined) {\n fields.push('result_json = ?')\n args.push(patch.result ? JSON.stringify(patch.result) : null)\n }\n if (patch.errorCode !== undefined) {\n fields.push('error_code = ?')\n args.push(patch.errorCode)\n }\n if (patch.errorMessage !== undefined) {\n fields.push('error_message = ?')\n args.push(patch.errorMessage)\n }\n args.push(id, owner)\n const result = await this.sqlite.execute({\n sql: `UPDATE canonry_checks SET ${fields.join(', ')} WHERE id = ? AND lease_owner = ? RETURNING *`,\n args,\n })\n return result.rows[0] ? rowToCheck(result.rows[0]) : null\n }\n\n async requeueJob(id: string, owner: string, now: string): Promise {\n const result = await this.sqlite.execute({\n sql: `UPDATE canonry_checks\n SET status = 'queued', updated_at = ?, lease_owner = NULL, lease_until = NULL\n WHERE id = ? AND lease_owner = ?\n RETURNING *`,\n args: [now, id, owner],\n })\n return result.rows[0] ? rowToCheck(result.rows[0]) : null\n }\n\n async claimGlobalLease(name: string, holder: string, now: string, leaseUntil: string): Promise {\n const result = await this.sqlite.execute({\n sql: `INSERT INTO canonry_leases (name, holder, expires_at) VALUES (?, ?, ?)\n ON CONFLICT(name) DO UPDATE SET holder = excluded.holder, expires_at = excluded.expires_at\n WHERE canonry_leases.holder = excluded.holder OR canonry_leases.expires_at <= ?\n RETURNING name`,\n args: [name, holder, leaseUntil, now],\n })\n return result.rows.length > 0\n }\n\n async releaseGlobalLease(name: string, holder: string): Promise {\n await this.sqlite.execute({ sql: 'DELETE FROM canonry_leases WHERE name = ? AND holder = ?', args: [name, holder] })\n }\n\n claimQuota(scope: string, subject: string, day: string, max: number): Promise {\n return this.claimQuotaWith(scope, subject, day, max)\n }\n\n private admissionBatch(input: CheckAdmissionInput): ValSqliteStatement[] {\n const candidate = input.candidate\n const activeCheckWhere = `(status = 'queued'\n OR (status = 'running' AND lease_until IS NOT NULL AND lease_until > ?)\n OR (status IN ('complete', 'partial') AND expires_at > ?))`\n\n return [\n // Reclaim only when an active or cached check would not already be\n // reused. This is the same precedence as findReusable() before the\n // transaction was introduced.\n {\n sql: `UPDATE canonry_checks\n SET status = 'queued', updated_at = ?, lease_owner = NULL, lease_until = NULL\n WHERE id = (\n SELECT id FROM canonry_checks\n WHERE fingerprint = ?\n AND status = 'running'\n AND (lease_until IS NULL OR lease_until <= ?)\n ORDER BY created_at DESC LIMIT 1\n )\n AND NOT EXISTS (\n SELECT 1 FROM canonry_checks\n WHERE fingerprint = ? AND ${activeCheckWhere}\n )\n RETURNING *`,\n args: [input.now, candidate.fingerprint, input.now, candidate.fingerprint, input.now, input.now],\n },\n // A pending row is a durable admission slot. The partial unique index\n // above prevents a second active record even if this batch is ever\n // called through a different Val isolate.\n {\n sql: `INSERT INTO canonry_checks\n (id, fingerprint, domain, status, created_at, updated_at, expires_at, result_json, error_code, error_message, lease_owner, lease_until, user_queries)\n SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?\n WHERE NOT EXISTS (\n SELECT 1 FROM canonry_checks\n WHERE fingerprint = ? AND ${activeCheckWhere}\n )\n RETURNING id`,\n args: [\n candidate.id,\n candidate.fingerprint,\n candidate.domain,\n candidate.status,\n candidate.createdAt,\n candidate.updatedAt,\n candidate.expiresAt,\n candidate.result ? JSON.stringify(candidate.result) : null,\n ADMISSION_PENDING,\n candidate.errorMessage,\n candidate.leaseOwner,\n candidate.leaseUntil,\n JSON.stringify(candidate.userQueries ?? []),\n candidate.fingerprint,\n input.now,\n input.now,\n ],\n },\n {\n sql: `INSERT INTO canonry_quota (scope, subject, day, count)\n SELECT ?, ?, ?, 1\n WHERE EXISTS (\n SELECT 1 FROM canonry_checks WHERE id = ? AND error_code = ?\n )\n ON CONFLICT(scope, subject, day) DO UPDATE SET count = count + 1\n WHERE canonry_quota.count < ?\n RETURNING count`,\n args: [\n input.clientQuota.scope,\n input.clientQuota.subject,\n input.clientQuota.day,\n candidate.id,\n ADMISSION_PENDING,\n input.clientQuota.max,\n ],\n },\n // SQLite changes() refers to the immediately preceding batch statement.\n // It lets the next durable state transition distinguish a quota cap from\n // an admitted claim without exposing an intermediate row outside this\n // atomic write batch.\n {\n sql: `UPDATE canonry_checks\n SET error_code = ?\n WHERE id = ? AND error_code = ? AND changes() = 1`,\n args: [ADMISSION_CLIENT_CLAIMED, candidate.id, ADMISSION_PENDING],\n },\n {\n sql: `INSERT INTO canonry_quota (scope, subject, day, count)\n SELECT ?, ?, ?, 1\n WHERE EXISTS (\n SELECT 1 FROM canonry_checks WHERE id = ? AND error_code = ?\n )\n ON CONFLICT(scope, subject, day) DO UPDATE SET count = count + 1\n WHERE canonry_quota.count < ?\n RETURNING count`,\n args: [\n input.globalQuota.scope,\n input.globalQuota.subject,\n input.globalQuota.day,\n candidate.id,\n ADMISSION_CLIENT_CLAIMED,\n input.globalQuota.max,\n ],\n },\n {\n sql: `UPDATE canonry_checks\n SET error_code = ?\n WHERE id = ? AND error_code = ? AND changes() = 1`,\n args: [ADMISSION_GRANTED, candidate.id, ADMISSION_CLIENT_CLAIMED],\n },\n // A global-cap rejection gives the client quota slot back before the\n // batch commits. A client-cap rejection never reaches this state.\n {\n sql: `UPDATE canonry_quota\n SET count = count - 1\n WHERE scope = ? AND subject = ? AND day = ? AND count > 0\n AND EXISTS (\n SELECT 1 FROM canonry_checks WHERE id = ? AND error_code = ?\n )`,\n args: [\n input.clientQuota.scope,\n input.clientQuota.subject,\n input.clientQuota.day,\n candidate.id,\n ADMISSION_CLIENT_CLAIMED,\n ],\n },\n {\n sql: 'DELETE FROM canonry_quota WHERE scope = ? AND subject = ? AND day = ? AND count <= 0',\n args: [input.clientQuota.scope, input.clientQuota.subject, input.clientQuota.day],\n },\n {\n sql: `DELETE FROM canonry_checks\n WHERE id = ? AND error_code IN (?, ?)\n RETURNING id`,\n args: [candidate.id, ADMISSION_PENDING, ADMISSION_CLIENT_CLAIMED],\n },\n {\n sql: 'UPDATE canonry_checks SET error_code = NULL WHERE id = ? AND error_code = ?',\n args: [candidate.id, ADMISSION_GRANTED],\n },\n {\n sql: `SELECT * FROM canonry_checks\n WHERE fingerprint = ? AND ${activeCheckWhere}\n ORDER BY created_at DESC LIMIT 1`,\n args: [candidate.fingerprint, input.now, input.now],\n },\n ]\n }\n\n private async findReusableWith(fingerprint: string, now: string): Promise {\n const result = await this.sqlite.execute({\n sql: `SELECT * FROM canonry_checks\n WHERE fingerprint = ?\n AND (\n status = 'queued'\n OR (status = 'running' AND lease_until IS NOT NULL AND lease_until > ?)\n OR (status IN ('complete', 'partial') AND expires_at > ?)\n )\n ORDER BY created_at DESC LIMIT 1`,\n args: [fingerprint, now, now],\n })\n const row = result.rows[0]\n return row ? rowToCheck(row) : null\n }\n\n private async createWith(record: CheckRecord): Promise {\n await this.sqlite.execute({\n sql: `INSERT INTO canonry_checks\n (id, fingerprint, domain, status, created_at, updated_at, expires_at, result_json, error_code, error_message, lease_owner, lease_until, user_queries)\n VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n args: [\n record.id,\n record.fingerprint,\n record.domain,\n record.status,\n record.createdAt,\n record.updatedAt,\n record.expiresAt,\n record.result ? JSON.stringify(record.result) : null,\n record.errorCode,\n record.errorMessage,\n record.leaseOwner,\n record.leaseUntil,\n JSON.stringify(record.userQueries ?? []),\n ],\n })\n }\n private async claimQuotaWith(scope: string, subject: string, day: string, max: number): Promise {\n // The WHERE condition is evaluated within this one UPSERT, so concurrent\n // requests cannot both spend the final remaining slot.\n const result = await this.sqlite.execute({\n sql: `INSERT INTO canonry_quota (scope, subject, day, count)\n VALUES (?, ?, ?, 1)\n ON CONFLICT(scope, subject, day) DO UPDATE SET count = count + 1\n WHERE canonry_quota.count < ?\n RETURNING count`,\n args: [scope, subject, day, max],\n })\n return result.rows.length > 0\n }\n}\n\nfunction rowToCheck(row: unknown): CheckRecord {\n const value = row as Record\n const resultJson = readString(value, 'result_json')\n return {\n id: readString(value, 'id') ?? '',\n fingerprint: readString(value, 'fingerprint') ?? '',\n domain: readString(value, 'domain') ?? '',\n status: (readString(value, 'status') ?? 'failed') as CheckStatus,\n createdAt: readString(value, 'created_at') ?? '',\n updatedAt: readString(value, 'updated_at') ?? '',\n expiresAt: readString(value, 'expires_at'),\n result: resultJson ? JSON.parse(resultJson) as CheckResult : null,\n errorCode: readString(value, 'error_code'),\n errorMessage: readString(value, 'error_message'),\n leaseOwner: readString(value, 'lease_owner'),\n leaseUntil: readString(value, 'lease_until'),\n userQueries: readQueries(value),\n }\n}\n\n/** Rows written before the column existed read as an empty list, not a crash. */\nfunction readQueries(value: Record): string[] {\n const raw = value.user_queries\n if (typeof raw !== 'string' || raw === '') return []\n try {\n const parsed = JSON.parse(raw)\n return Array.isArray(parsed) ? parsed.filter((entry): entry is string => typeof entry === 'string') : []\n } catch {\n return []\n }\n}\n\nfunction readString(value: Record, key: string): string | null {\n const current = value[key]\n return typeof current === 'string' ? current : current == null ? null : String(current)\n}\n",[],[198,461,453],"storage","557649bd-7156-4137-9af2-6a32e284decc","memory.ts","95930b94-a63e-11f1-93d2-1607ee4eb77e",60,["D",1788292315183],"import type { CheckAdmission, CheckAdmissionInput, CheckRecord, CheckStore } from '../runtime/types.ts'\n\nconst ADMISSION_LEASE_PREFIX = 'public-check-admission:'\nconst ADMISSION_LEASE_MS = 10_000\nconst ADMISSION_RETRIES = 8\nconst ADMISSION_RETRY_DELAY_MS = 8\n\n/** Deterministic store for local development and tests. Production uses Val SQLite. */\nexport class MemoryCheckStore implements CheckStore {\n readonly checks = new Map()\n readonly quota = new Map()\n\n initialize(): Promise {\n return Promise.resolve()\n }\n\n async admit(input: CheckAdmissionInput): Promise {\n const leaseName = `${ADMISSION_LEASE_PREFIX}${input.candidate.fingerprint}`\n const leaseUntil = new Date(new Date(input.now).getTime() + ADMISSION_LEASE_MS).toISOString()\n\n for (let attempt = 0; attempt < ADMISSION_RETRIES; attempt++) {\n const holder = crypto.randomUUID()\n if (!await this.claimGlobalLease(leaseName, holder, input.now, leaseUntil)) {\n if (attempt + 1 < ADMISSION_RETRIES) await delay(ADMISSION_RETRY_DELAY_MS)\n continue\n }\n\n try {\n const reusable = await this.findReusable(input.candidate.fingerprint, input.now)\n if (reusable) return { kind: 'reused', record: reusable }\n\n const stale = this.findStaleRunning(input.candidate.fingerprint, input.now)\n if (stale) {\n const current = this.checks.get(stale.id)\n if (current?.status === 'running' && (!current.leaseUntil || current.leaseUntil <= input.now)) {\n const reclaimed: CheckRecord = {\n ...current,\n status: 'queued',\n updatedAt: input.now,\n leaseOwner: null,\n leaseUntil: null,\n }\n this.checks.set(reclaimed.id, reclaimed)\n return { kind: 'reclaimed', record: clone(reclaimed) }\n }\n const retried = await this.findReusable(input.candidate.fingerprint, input.now)\n if (retried) return { kind: 'reused', record: retried }\n }\n\n if (\n !await this.claimQuota(\n input.clientQuota.scope,\n input.clientQuota.subject,\n input.clientQuota.day,\n input.clientQuota.max,\n )\n ) {\n return { kind: 'quota-exhausted', scope: 'client' }\n }\n if (\n !await this.claimQuota(\n input.globalQuota.scope,\n input.globalQuota.subject,\n input.globalQuota.day,\n input.globalQuota.max,\n )\n ) {\n this.releaseQuota(input.clientQuota.scope, input.clientQuota.subject, input.clientQuota.day)\n return { kind: 'quota-exhausted', scope: 'global' }\n }\n\n try {\n await this.create(input.candidate)\n return { kind: 'created', record: clone(input.candidate) }\n } catch (error) {\n this.releaseQuota(input.clientQuota.scope, input.clientQuota.subject, input.clientQuota.day)\n this.releaseQuota(input.globalQuota.scope, input.globalQuota.subject, input.globalQuota.day)\n throw error\n }\n } finally {\n await this.releaseGlobalLease(leaseName, holder)\n }\n }\n\n return { kind: 'busy' }\n }\n\n findReusable(fingerprint: string, now: string): Promise {\n const candidates = [...this.checks.values()]\n .filter((check) => check.fingerprint === fingerprint)\n .sort((a, b) => b.createdAt.localeCompare(a.createdAt))\n for (const check of candidates) {\n if (check.status === 'queued') return Promise.resolve(clone(check))\n if (check.status === 'running' && check.leaseUntil && check.leaseUntil > now) return Promise.resolve(clone(check))\n if ((check.status === 'complete' || check.status === 'partial') && check.expiresAt && check.expiresAt > now) {\n return Promise.resolve(clone(check))\n }\n }\n return Promise.resolve(null)\n }\n\n create(record: CheckRecord): Promise {\n this.checks.set(record.id, clone(record))\n return Promise.resolve()\n }\n\n get(id: string): Promise {\n const record = this.checks.get(id)\n return Promise.resolve(record ? clone(record) : null)\n }\n\n update(\n id: string,\n patch: Partial>,\n ): Promise {\n const current = this.checks.get(id)\n if (!current) return Promise.resolve(null)\n const next = { ...current, ...clone(patch) }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n claimJob(id: string, owner: string, now: string, leaseUntil: string): Promise {\n const current = this.checks.get(id)\n if (!current) return Promise.resolve(null)\n const canClaim = current.status === 'queued' ||\n (current.status === 'running' && (!current.leaseUntil || current.leaseUntil <= now))\n if (!canClaim) return Promise.resolve(null)\n const next: CheckRecord = { ...current, status: 'running', updatedAt: now, leaseOwner: owner, leaseUntil }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n finalizeJob(\n id: string,\n owner: string,\n patch: Partial>,\n ): Promise {\n const current = this.checks.get(id)\n if (!current || current.leaseOwner !== owner) return Promise.resolve(null)\n const next: CheckRecord = { ...current, ...clone(patch), leaseOwner: null, leaseUntil: null }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n requeueJob(id: string, owner: string, now: string): Promise {\n const current = this.checks.get(id)\n if (!current || current.leaseOwner !== owner) return Promise.resolve(null)\n const next: CheckRecord = { ...current, status: 'queued', updatedAt: now, leaseOwner: null, leaseUntil: null }\n this.checks.set(id, next)\n return Promise.resolve(clone(next))\n }\n\n claimGlobalLease(name: string, holder: string, now: string, leaseUntil: string): Promise {\n const current = this.globalLeases.get(name)\n if (current && current.holder !== holder && current.leaseUntil > now) return Promise.resolve(false)\n this.globalLeases.set(name, { holder, leaseUntil })\n return Promise.resolve(true)\n }\n\n releaseGlobalLease(name: string, holder: string): Promise {\n if (this.globalLeases.get(name)?.holder === holder) this.globalLeases.delete(name)\n return Promise.resolve()\n }\n\n claimQuota(scope: string, subject: string, day: string, max: number): Promise {\n const key = `${scope}:${subject}:${day}`\n const value = this.quota.get(key) ?? 0\n if (value >= max) return Promise.resolve(false)\n this.quota.set(key, value + 1)\n return Promise.resolve(true)\n }\n\n private findStaleRunning(fingerprint: string, now: string): CheckRecord | null {\n const candidate = [...this.checks.values()]\n .filter((check) =>\n check.fingerprint === fingerprint && check.status === 'running' &&\n (!check.leaseUntil || check.leaseUntil <= now)\n )\n .sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]\n return candidate ? clone(candidate) : null\n }\n\n private releaseQuota(scope: string, subject: string, day: string): void {\n const key = `${scope}:${subject}:${day}`\n const value = this.quota.get(key) ?? 0\n if (value <= 1) this.quota.delete(key)\n else this.quota.set(key, value - 1)\n }\n\n private readonly globalLeases = new Map()\n}\n\nfunction delay(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\nfunction clone(value: T): T {\n return structuredClone(value)\n}\n",[],[198,461,463],"01568ee8-b51f-43e3-8630-3492a546a4c6",9,["D",1788292310084],[257,258],[198,461],"9a19121e-e04a-4b00-8567-0ab15ac06a19","site-map.ts","bf52f586-a641-11f1-bb98-1607ee4eb77e","92bd6c2a-a63e-11f1-9f99-1607ee4eb77e",90,["D",1788293673799],"/**\n * Build a bounded internal-link graph from a crawl the audit already ran.\n *\n * The crawler observes up to 2,500 edges while auditing five pages, and until\n * now every one of them was discarded. They are the most interesting thing in\n * the report for a reader: an audit score says a page is weak, the link graph\n * says whether anything points at it.\n *\n * Two node kinds, kept visibly distinct. A CRAWLED node was fetched and\n * audited, so it carries a score and an indexability verdict. A DISCOVERED node\n * is a link target the crawler saw but never opened; it has a URL and nothing\n * else. Rendering them alike would imply a measurement that never happened.\n *\n * Selection is deterministic — no clock, no randomness — so the same crawl\n * always produces the same picture, and a cached result never disagrees with\n * the run that produced it.\n */\nimport type { CrawlEdgeObservation, CrawlPageObservation } from 'npm:@canonry/aeo-audit@7.1.0'\nimport type { SiteMapEdge, SiteMapNode, SiteMapSample } from '../runtime/types.ts'\n\n/**\n * Display caps, not crawl caps. Past roughly this many nodes a static graph\n * stops being readable and becomes decoration.\n */\nexport const SITE_MAP_MAX_NODES = 24\nexport const SITE_MAP_MAX_EDGES = 60\n\n/** Path for display, or the host for the site root. Query and hash are dropped. */\nfunction nodeLabel(url: string): string {\n try {\n const parsed = new URL(url)\n const path = parsed.pathname.replace(/\\/+$/, '')\n return path === '' ? parsed.hostname.replace(/^www\\./i, '') : path\n } catch {\n return url\n }\n}\n\nfunction indexableOf(page: CrawlPageObservation): boolean | null {\n const state = page.indexability?.state\n if (state === 'indexable') return true\n if (state === 'noindex' || state === 'blocked') return false\n return null\n}\n\n/**\n * A crawled page is keyed by the URL it settled on, because that is the URL its\n * inbound links resolve to. Keying by the requested URL would leave a redirected\n * page looking unlinked.\n */\nfunction pageKey(page: CrawlPageObservation): string {\n return page.finalUrl ?? page.requestedUrl\n}\n\nexport function buildSiteMap(\n pages: readonly CrawlPageObservation[],\n edges: readonly CrawlEdgeObservation[],\n): SiteMapSample | null {\n const internal = edges.filter((edge) => edge.classification === 'internal' && edge.from !== edge.to)\n if (pages.length === 0 && internal.length === 0) return null\n\n const inbound = new Map()\n const outbound = new Map()\n for (const edge of internal) {\n outbound.set(edge.from, (outbound.get(edge.from) ?? 0) + 1)\n inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1)\n }\n\n const crawled = new Map()\n for (const page of pages) crawled.set(pageKey(page), page)\n\n const candidates = new Set([...crawled.keys()])\n for (const edge of internal) {\n candidates.add(edge.from)\n candidates.add(edge.to)\n }\n\n const toNode = (url: string): SiteMapNode => {\n const page = crawled.get(url)\n return {\n key: url,\n url,\n label: nodeLabel(url),\n depth: page?.depth ?? null,\n crawled: page !== undefined,\n score: page?.audit?.overallScore ?? null,\n indexable: page ? indexableOf(page) : null,\n inboundLinks: inbound.get(url) ?? 0,\n outboundLinks: outbound.get(url) ?? 0,\n }\n }\n\n // Crawled pages are never dropped — they are what was actually measured.\n // Remaining slots go to the most-linked discovered targets, since a page\n // twelve others point at says more about the site than an orphan does.\n const all = [...candidates].map(toNode)\n const keptCrawled = all.filter((node) => node.crawled).sort(byDepthThenUrl)\n const discovered = all.filter((node) => !node.crawled).sort(byInboundThenUrl)\n const nodes = [...keptCrawled, ...discovered].slice(0, SITE_MAP_MAX_NODES)\n const nodeKeys = new Set(nodes.map((node) => node.key))\n\n const mapped: SiteMapEdge[] = internal\n .filter((edge) => nodeKeys.has(edge.from) && nodeKeys.has(edge.to))\n .map((edge) => ({ from: edge.from, to: edge.to, followable: edge.followableOccurrences > 0 }))\n const dedupedEdges = dedupe(mapped).sort(byEndpoints).slice(0, SITE_MAP_MAX_EDGES)\n\n return {\n nodes,\n edges: dedupedEdges,\n totalPages: candidates.size,\n totalEdges: dedupe(internal.map((edge) => ({ from: edge.from, to: edge.to, followable: true }))).length,\n truncated: candidates.size > nodes.length || internal.length > dedupedEdges.length,\n }\n}\n\nfunction byDepthThenUrl(a: SiteMapNode, b: SiteMapNode): number {\n return (a.depth ?? 99) - (b.depth ?? 99) || a.url.localeCompare(b.url)\n}\n\nfunction byInboundThenUrl(a: SiteMapNode, b: SiteMapNode): number {\n return b.inboundLinks - a.inboundLinks || a.url.localeCompare(b.url)\n}\n\nfunction byEndpoints(a: SiteMapEdge, b: SiteMapEdge): number {\n return a.from.localeCompare(b.from) || a.to.localeCompare(b.to)\n}\n\n/** One edge per (from, to); the crawler already aggregates occurrences. */\nfunction dedupe(edges: readonly SiteMapEdge[]): SiteMapEdge[] {\n const seen = new Map()\n for (const edge of edges) {\n // Written as an escape, not a literal: a raw NUL byte makes the file\n // binary and Val Town refuses to push it. NUL is still the right\n // separator here, because it cannot occur in a URL.\n const key = `${edge.from}\\u0000${edge.to}`\n const existing = seen.get(key)\n if (existing) existing.followable ||= edge.followable\n else seen.set(key, { ...edge })\n }\n return [...seen.values()]\n}\n",[],[198,484,476],"site-health","897ce71d-1920-4f1c-a042-52abd50875fa","96c08e88-a63e-11f1-8c22-1607ee4eb77e",114,["D",1788309292732],"import { runSiteCrawl } from 'npm:@canonry/aeo-audit@7.1.0'\nimport type { CrawlPageObservation, SiteCrawlOptions, SiteCrawlReport } from 'npm:@canonry/aeo-audit@7.1.0'\nimport { wwwAlternate } from '../security/url.ts'\nimport { buildSiteMap } from './site-map.ts'\nimport type { FactorSample, SiteHealthPageSample, SiteHealthRunner, SiteHealthSample } from '../runtime/types.ts'\n\nexport const VAL_TOWN_SITE_HEALTH_LIMITS = Object.freeze({\n mode: 'full' as const,\n maxPages: 5,\n maxEdges: 2_500,\n maxFetches: 32,\n maxDurationMs: 20_000,\n maxBytes: 12 * 1024 * 1024,\n maxPageBytes: 2 * 1024 * 1024,\n maxDepth: 2,\n maxLinksPerPage: 250,\n maxQueryVariants: 2,\n maxSitemapFanout: 8,\n maxSitemapUrls: 250,\n concurrency: 2,\n requestDelayMs: 100,\n respectRobots: true,\n checkDeadLinks: false,\n includeGeo: false,\n includeAgentSkills: false,\n includeLighthouse: false,\n}) satisfies SiteCrawlOptions\n\ntype Crawl = (rootUrl: string, options: SiteCrawlOptions) => Promise\n\nexport function createSiteHealthRunner(crawl: Crawl = runSiteCrawl): SiteHealthRunner {\n return {\n async run(domain, parentSignal) {\n const hosts = [domain, wwwAlternate(domain)].filter((value): value is string => Boolean(value))\n const attemptedHosts: string[] = []\n const signal = AbortSignal.any([parentSignal, AbortSignal.timeout(30_000)])\n let primaryError: unknown = null\n\n for (let index = 0; index < hosts.length; index++) {\n const host = hosts[index]!\n attemptedHosts.push(host)\n try {\n // `allowPrivateHost` names the ONE host being crawled, which is what\n // makes Technical AEO possible on Val Town at all.\n //\n // The engine's SSRF guard resolves every hostname with DNS and rejects\n // private addresses before opening a socket. Val Town grants no DNS:\n // `Deno.resolveDns` lacks net access to the resolver and\n // `node:dns.resolve4` returns UNKNOWN, so the guard failed closed on\n // every host and the crawl audited zero pages for every domain.\n //\n // This is not a way to switch the guard off; the option is a hostname,\n // not a boolean, precisely so it cannot be. A matching host skips the\n // DNS preflight and IP pinning (fetch-page.ts), and every OTHER host —\n // a redirect to cloud metadata, an internal service reached from a\n // sitemap — is still resolved and still blocked.\n //\n // `host` is safe to name because `normalizePublicDomain` has already\n // rejected localhost, .local, every private IPv4 range and all IPv6\n // literals before this runs. If it nonetheless rebinds to a private\n // address, Val Town's own sandbox refuses the fetch: 169.254.169.254,\n // 127.0.0.1, 10/8 and 192.168/16 all fail with \"Requires net access\"\n // before a socket opens.\n const report = await crawl(`https://${host}/`, {\n ...VAL_TOWN_SITE_HEALTH_LIMITS,\n allowPrivateHost: host,\n signal,\n })\n if (index === 0 && hosts[1] && shouldTryWwwAlternate(report, hosts[1])) continue\n return toSample(domain, report, attemptedHosts)\n } catch (error) {\n primaryError ??= error\n }\n }\n\n return failedSample(domain, attemptedHosts, safeError(primaryError))\n },\n }\n}\n\nfunction shouldTryWwwAlternate(report: SiteCrawlReport, alternateHost: string): boolean {\n if (report.summary.pagesFetched === 0 && report.summary.pagesObserved === 0) return true\n if (report.summary.terminationReason !== 'root-host-redirect' || !report.summary.finalRootUrl) return false\n try {\n return new URL(report.summary.finalRootUrl).hostname.toLowerCase().replace(/\\.$/, '') === alternateHost\n } catch {\n return false\n }\n}\n\nfunction toSample(domain: string, report: SiteCrawlReport, attemptedHosts: string[]): SiteHealthSample {\n const summary = report.summary\n const pages = report.mode === 'full' ? report.pages.map(toPage).sort(sortWorstFirst).slice(0, 5) : []\n // Built from the full observation set, not the worst-first five above: the\n // graph's value is the links between pages, and slicing first would sever them.\n const siteMap = report.mode === 'full' ? buildSiteMap(report.pages, report.edges) : null\n // v7 always reports this count. Treat a missing legacy/mock field as unknown\n // rather than inventing an error; an explicit zero is never a valid sample.\n const hasAuditedPages = summary.auditRollup.auditedPages !== 0\n const status = !hasAuditedPages ? 'error' : summary.complete ? 'complete' : 'partial'\n return {\n schemaVersion: summary.crawlSchemaVersion,\n label: '5-page Technical AEO sample',\n domain,\n rootUrl: summary.rootUrl,\n finalRootUrl: summary.finalRootUrl,\n status,\n score: hasAuditedPages ? summary.auditRollup.aggregateScore : null,\n pagesDiscovered: summary.pagesDiscovered,\n pagesFetched: summary.pagesFetched,\n pagesObserved: summary.pagesObserved,\n elapsedMs: summary.elapsedMs,\n terminationReason: summary.terminationReason,\n // Warnings may carry transport diagnostics from the crawler. Keep the\n // public record descriptive without persisting those raw messages.\n warnings: summary.warnings.slice(0, 4).map(() => 'Some optional crawl checks were unavailable.'),\n factors: hasAuditedPages\n ? summary.auditRollup.factors.slice(0, 16).map((factor) => ({\n id: factor.id,\n name: clip(factor.name, 100),\n averageScore: round(factor.averageScore),\n count: factor.count,\n }))\n : [],\n pages,\n siteMap,\n attemptedHosts,\n error: hasAuditedPages ? null : 'No public pages could be audited in the Technical AEO sample.',\n }\n}\n\nfunction toPage(page: CrawlPageObservation): SiteHealthPageSample {\n const audit = page.audit\n return {\n url: clip(page.finalUrl ?? page.requestedUrl, 2_048),\n status: audit ? 'success' : 'error',\n score: audit ? round(audit.overallScore) : null,\n depth: page.depth,\n indexability: page.indexability?.state ?? null,\n factors: audit\n ? audit.factors.slice(0, 16).map((factor) => ({\n id: factor.id,\n name: clip(factor.name, 100),\n score: round(factor.score),\n applicable: factor.applicable ?? null,\n findings: factor.findings.slice(0, 3).map((finding) => ({\n code: clip(finding.code, 160),\n message: clip(finding.message, 500),\n })),\n recommendations: factor.recommendations.slice(0, 3).map((recommendation) => clip(recommendation, 500)),\n } satisfies FactorSample))\n : [],\n criticalDefects: audit\n ? audit.criticalDefects.slice(0, 8).map((defect) => ({\n id: defect.id,\n severity: defect.severity,\n detail: clip(defect.detail, 500),\n recommendation: clip(defect.recommendation, 500),\n }))\n : [],\n error: audit ? null : 'This page could not be audited.',\n }\n}\n\nfunction sortWorstFirst(left: SiteHealthPageSample, right: SiteHealthPageSample): number {\n if (left.score == null && right.score != null) return -1\n if (left.score != null && right.score == null) return 1\n return (left.score ?? 0) - (right.score ?? 0) || left.url.localeCompare(right.url)\n}\n\nfunction failedSample(domain: string, attemptedHosts: string[], error: string): SiteHealthSample {\n return {\n schemaVersion: '1.0',\n label: '5-page Technical AEO sample',\n domain,\n rootUrl: `https://${domain}/`,\n finalRootUrl: null,\n status: 'error',\n score: null,\n pagesDiscovered: 0,\n pagesFetched: 0,\n pagesObserved: 0,\n elapsedMs: 0,\n terminationReason: null,\n warnings: [],\n factors: [],\n pages: [],\n siteMap: null,\n attemptedHosts,\n error,\n }\n}\n\nfunction safeError(error: unknown): string {\n if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {\n return 'The Technical AEO sample timed out.'\n }\n return 'The Technical AEO sample could not complete.'\n}\n\nfunction clip(value: string, max: number): string {\n return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`\n}\n\nfunction round(value: number): number {\n return Math.round(value * 10) / 10\n}\n",[],[198,484,326],"37c32e25-97f8-4d9c-a502-d62cf5a68610","factor-order.ts","0d94f77c-a66e-11f1-8c55-1607ee4eb77e",167,["D",1788312702941],"/**\n * Display order for the audit factors: best score first, worst last.\n *\n * The audit engine returns its rollup alphabetically, which reads as a list of\n * names rather than a result. Sorting by score turns the same rows into a\n * ranking, so the strongest signals sit at the top and the work to do collects\n * at the bottom where it is easy to scan.\n *\n * Ordering is a reading decision over stored data, not part of the record, so it\n * is applied at read time. That keeps checks written before this change in the\n * new order too, and it is why both surfaces call the same comparator: the UI\n * and the MCP payload describe the same audit and must not disagree about which\n * factor is doing best.\n */\n\n/** What the order is decided on. `score` is null when nothing was measured. */\nexport interface FactorRank {\n score: number | null\n label: string\n}\n\n/**\n * An unmeasured factor sorts last, never as a zero. \"Not applicable to the\n * sampled page types\" is the absence of a measurement; ranking it below the\n * worst real score would claim it is worse than the worst thing found.\n */\nexport function compareFactorRank(a: FactorRank, b: FactorRank): number {\n const aScore = typeof a.score === 'number' && Number.isFinite(a.score) ? a.score : null\n const bScore = typeof b.score === 'number' && Number.isFinite(b.score) ? b.score : null\n if (aScore === null || bScore === null) {\n if (aScore !== bScore) return aScore === null ? 1 : -1\n } else if (aScore !== bScore) {\n return bScore - aScore\n }\n // Ties break by name so the same audit always draws the same list. Several\n // factors scoring 100 is the common case, not an edge case.\n return a.label.localeCompare(b.label)\n}\n\n/** Sort a copy, so a stored array is never reordered in place. */\nexport function orderFactors(items: readonly T[], rank: (item: T) => FactorRank): T[] {\n return [...items].sort((a, b) => compareFactorRank(rank(a), rank(b)))\n}\n",[],[198,484,493],"9872971b-6df7-4db3-a940-d575fb5071df",12,["D",1788292310513],[253,254,255],[198,484],"ec409f06-74cc-48dc-8496-7ea08a6c02f3","url.ts","938ff438-a63e-11f1-9193-1607ee4eb77e","92429036-a63e-11f1-9a7d-1607ee4eb77e",34,["D",1788292311893],"const MAX_DOMAIN_INPUT_LENGTH = 253\n\nexport class PublicUrlError extends Error {\n override name = 'PublicUrlError'\n}\n\nexport interface NormalizedPublicDomain {\n domain: string\n rootUrl: string\n}\n\nfunction isBlockedIpv4(host: string): boolean {\n const parts = host.split('.').map(Number)\n if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false\n const a = parts[0]!\n const b = parts[1]!\n const c = parts[2]!\n return a === 0 ||\n a === 10 ||\n a === 127 ||\n (a === 100 && b >= 64 && b <= 127) ||\n (a === 169 && b === 254) ||\n (a === 172 && b >= 16 && b <= 31) ||\n (a === 192 && b === 0 && c === 0) ||\n (a === 192 && b === 168) ||\n (a === 198 && (b === 18 || b === 19)) ||\n a >= 224\n}\n\n/** `URL.hostname` retains brackets around an IPv6 literal. */\nfunction normalizedIpv6Literal(host: string): string | null {\n const value = host.toLowerCase()\n const unbracketed = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value\n // A parsed URL hostname contains a colon only for an IPv6 literal. Do not\n // run IPv6 prefix checks against DNS names such as fda.gov or fc2.com.\n return unbracketed.includes(':') ? unbracketed : null\n}\n\nfunction isBlockedIpv6(value: string): boolean {\n return value === '::1' ||\n value === '::' ||\n value.startsWith('fe80:') ||\n value.startsWith('fc') ||\n value.startsWith('fd')\n}\n\n/**\n * Normalizes a user domain to a HTTPS root. This is a first-line guard; the\n * crawler still performs DNS and per-hop SSRF validation before every fetch.\n */\nexport function normalizePublicDomain(input: unknown): NormalizedPublicDomain {\n if (typeof input !== 'string') throw new PublicUrlError('Enter a domain.')\n const trimmed = input.trim()\n if (!trimmed || trimmed.length > MAX_DOMAIN_INPUT_LENGTH) throw new PublicUrlError('Enter a valid public domain.')\n\n const candidate = /^[a-z][a-z0-9+.-]*:\\/\\//i.test(trimmed) ? trimmed : `https://${trimmed}`\n let url: URL\n try {\n url = new URL(candidate)\n } catch {\n throw new PublicUrlError('Enter a valid public domain.')\n }\n\n if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n throw new PublicUrlError('Only HTTP(S) domains can be checked.')\n }\n if (url.username || url.password) throw new PublicUrlError('Credentials are not allowed in a domain.')\n if (url.port && url.port !== '80' && url.port !== '443') {\n throw new PublicUrlError('Only standard web ports can be checked.')\n }\n if (url.pathname !== '/' || url.search || url.hash) throw new PublicUrlError('Enter a domain, not a page URL.')\n\n const hostname = url.hostname.toLowerCase().replace(/\\.$/, '')\n if (!hostname || hostname === 'localhost' || hostname.endsWith('.localhost') || hostname.endsWith('.local')) {\n throw new PublicUrlError('Private and local hosts cannot be checked.')\n }\n if (isBlockedIpv4(hostname)) {\n throw new PublicUrlError('Private and local hosts cannot be checked.')\n }\n\n const ipv6 = normalizedIpv6Literal(hostname)\n if (ipv6) {\n if (isBlockedIpv6(ipv6)) throw new PublicUrlError('Private and local hosts cannot be checked.')\n throw new PublicUrlError('IPv6 literal domains are not supported.')\n }\n\n // URL already performs IDNA conversion. IPv6 literals were rejected above;\n // require a DNS-looking name or a public IPv4 literal.\n const isIpv4 = /^\\d{1,3}(?:\\.\\d{1,3}){3}$/.test(hostname)\n if (!isIpv4 && (!hostname.includes('.') || hostname.length > MAX_DOMAIN_INPUT_LENGTH)) {\n throw new PublicUrlError('Enter a public domain with a valid hostname.')\n }\n\n return { domain: hostname, rootUrl: `https://${hostname}/` }\n}\n\n/** The sole alternate hostname the public host may attempt after a failed root crawl. */\nexport function wwwAlternate(domain: string): string | null {\n if (/^\\d{1,3}(?:\\.\\d{1,3}){3}$/.test(domain) || domain.includes(':')) return null\n return domain.startsWith('www.') ? domain.slice(4) : `www.${domain}`\n}\n\nexport function utcDay(now: Date = new Date()): string {\n return now.toISOString().slice(0, 10)\n}\n",[],[198,514,506],"security","a0bcfaff-8b0b-4a2e-90df-4d7ad01ae08d","turnstile.ts","93acddaa-a63e-11f1-a387-1607ee4eb77e",37,["D",1788292311919],"export class HumanVerificationError extends Error {\n override name = 'HumanVerificationError'\n constructor(message: string, readonly code: 'unavailable' | 'invalid' | 'transport' = 'invalid') {\n super(message)\n }\n}\n\nexport interface HumanVerificationInput {\n token: string | null\n remoteIp: string | null\n}\n\nexport interface HumanVerifier {\n verify(input: HumanVerificationInput): Promise\n}\n\nexport interface TurnstileVerifierOptions {\n secret: string\n allowedHostnames: readonly string[]\n fetchImpl?: typeof fetch\n}\n\n/** One public form, one server-enforced action. Do not make this client/env configurable. */\nexport const TURNSTILE_AUDIT_ACTION = 'audit'\n\ninterface TurnstileResponse {\n success?: boolean\n action?: string\n hostname?: string\n ['error-codes']?: string[]\n}\n\n/** Server-side only Turnstile verification. Tokens never become stored check data. */\nexport function createTurnstileVerifier(options: TurnstileVerifierOptions): HumanVerifier {\n const allowedHostnames = new Set(options.allowedHostnames.map((hostname) => hostname.toLowerCase()))\n const fetchImpl = options.fetchImpl ?? fetch\n\n return {\n async verify({ token, remoteIp }) {\n if (!token || token.length > 2048) throw new HumanVerificationError('Complete the human verification challenge.')\n const form = new URLSearchParams({\n secret: options.secret,\n response: token,\n idempotency_key: crypto.randomUUID(),\n })\n if (remoteIp) form.set('remoteip', remoteIp)\n\n let response: Response\n try {\n response = await fetchImpl('https://challenges.cloudflare.com/turnstile/v0/siteverify', {\n method: 'POST',\n headers: { 'content-type': 'application/x-www-form-urlencoded' },\n body: form,\n signal: AbortSignal.timeout(10_000),\n })\n } catch {\n throw new HumanVerificationError('Human verification is temporarily unavailable.', 'transport')\n }\n if (!response.ok) throw new HumanVerificationError('Human verification is temporarily unavailable.', 'transport')\n\n let payload: TurnstileResponse\n try {\n payload = await response.json() as TurnstileResponse\n } catch {\n throw new HumanVerificationError('Human verification is temporarily unavailable.', 'transport')\n }\n if (!payload.success) throw new HumanVerificationError('Complete the human verification challenge.')\n if (payload.action !== TURNSTILE_AUDIT_ACTION) {\n throw new HumanVerificationError('Human verification did not match this check.')\n }\n if (allowedHostnames.size > 0 && (!payload.hostname || !allowedHostnames.has(payload.hostname.toLowerCase()))) {\n throw new HumanVerificationError('Human verification did not match this site.')\n }\n },\n }\n}\n\n/** Production deliberately fails closed until a real Turnstile secret is configured. */\nexport class UnavailableHumanVerifier implements HumanVerifier {\n verify(): Promise {\n return Promise.reject(new HumanVerificationError('Human verification is not configured.', 'unavailable'))\n }\n}\n\n/** Development/test-only seam. It is never selected by a production configuration. */\nexport class LocalBypassHumanVerifier implements HumanVerifier {\n verify(): Promise {\n return Promise.resolve()\n }\n}\n",[],[198,514,516],"b8bce09a-c6af-4a10-812e-6d794b08426b",6,["D",1788292309698],[250,251],[198,514],"4b7c2164-3e1c-41d8-86af-c928c2dad0a3","93a5c9fc-a63e-11f1-8fd4-1607ee4eb77e","9256932e-a63e-11f1-9a7d-1607ee4eb77e",200,["D",1788318220929],"/**\n * Runtime-neutral contracts for the public Canonry sample. The Val host owns\n * request handling and persistence; package adapters own provider and crawler\n * implementation details.\n */\n\nexport const CHECK_RESULT_SCHEMA_VERSION = '1.0' as const\n/** Controlled presentation code for native public-form quota failures. */\nexport const PUBLIC_RATE_LIMITED_ERROR_CODE = 'public-rate-limited' as const\n/**\n * What a failed check says when its reason could not be classified. Shared\n * because the UI must recognise it as the ABSENCE of a reason: leading a banner\n * with it restates the banner's own title and tells the reader nothing.\n */\nexport const PUBLIC_CHECK_UNAVAILABLE = 'This answer-engine check was unavailable.' as const\n\nexport type CheckStatus = 'queued' | 'running' | 'complete' | 'partial' | 'failed'\n\nexport interface VisibilitySource {\n url: string\n title: string | null\n}\n\n/** A normalized, display-safe answer observation. Never place a raw provider response here. */\nexport interface VisibilityEvidence {\n query: string\n provider: string\n requestedModel: string | null\n servedModel: string | null\n completedAt: string\n answerText: string | null\n /** Null means the provider check failed; it is never silently converted to false. */\n mentioned: boolean | null\n matchedTerms: string[]\n /** Null means the provider check failed; it is never silently converted to false. */\n cited: boolean | null\n citedDomains: string[]\n citedUrls: string[]\n matchedCitationDomains: string[]\n matchedCitationUrls: string[]\n sources: VisibilitySource[]\n searchQueries: string[]\n /**\n * Brands this answer NAMES in its prose, every one verified to be written\n * there. Null means the extraction did not run or failed, which is not the\n * same as an answer that named nobody, and keeps mention share unmeasured\n * rather than reporting a field of zeroes.\n */\n namedBrands: string[] | null\n retrievalStatus: 'grounded' | 'not-grounded' | 'unknown' | 'error'\n error: string | null\n}\n\nexport interface VisibilitySummary {\n successfulChecks: number\n failedChecks: number\n mentionRate: number | null\n citationRate: number | null\n}\n\nexport interface VisibilityReport {\n schemaVersion: string\n domain: string\n startedAt: string\n completedAt: string\n summary: VisibilitySummary\n evidence: VisibilityEvidence[]\n}\n\nexport interface VisibilityProbeInput {\n domain: string\n /**\n * Caller-supplied questions, used verbatim. The planner generates only\n * `maxProbeCalls - userQueries.length`, and is not called at all when the\n * caller supplied the full set.\n */\n userQueries?: readonly string[]\n /** The package may use this one capped call to derive a profile/query basket. */\n maxPlannerCalls: 1\n /** The package may issue at most this many grounded answer-engine probes. */\n maxProbeCalls: 3\n signal: AbortSignal\n}\n\n/**\n * Boundary between public-check orchestration and the Val-local visibility\n * implementation. The public result never includes raw provider responses.\n */\nexport interface VisibilityProbePort {\n probe(input: VisibilityProbeInput): Promise\n}\n\nexport interface FactorSample {\n id: string\n name: string\n score: number\n applicable: boolean | null\n findings: Array<{ code: string; message: string }>\n recommendations: string[]\n}\n\nexport interface SiteHealthPageSample {\n url: string\n status: 'success' | 'error'\n score: number | null\n depth: number | null\n indexability: string | null\n factors: FactorSample[]\n criticalDefects: Array<{\n id: string\n severity: string\n detail: string\n recommendation: string\n }>\n error: string | null\n}\n\n/**\n * One page in the crawled link graph. A node is either a page the crawler\n * actually fetched and audited (`crawled`), or a link target it saw but never\n * opened — the distinction matters, because only a crawled node can carry a\n * score, and drawing the two alike would imply measurement that never happened.\n */\nexport interface SiteMapNode {\n key: string\n url: string\n /** Path for display, or the host for the site root. */\n label: string\n depth: number | null\n crawled: boolean\n score: number | null\n indexable: boolean | null\n inboundLinks: number\n outboundLinks: number\n}\n\n/** A followable-or-not internal link between two mapped nodes. */\nexport interface SiteMapEdge {\n from: string\n to: string\n followable: boolean\n}\n\n/**\n * A bounded internal-link graph built from the same crawl as the page audit.\n *\n * `totalPages` / `totalEdges` are the pre-cap totals, so a reader can always\n * tell a displayed sample from the whole site.\n */\nexport interface SiteMapSample {\n nodes: SiteMapNode[]\n edges: SiteMapEdge[]\n totalPages: number\n totalEdges: number\n truncated: boolean\n}\n\nexport interface SiteHealthSample {\n schemaVersion: string\n label: '5-page Technical AEO sample'\n domain: string\n rootUrl: string\n finalRootUrl: string | null\n status: 'complete' | 'partial' | 'error'\n score: number | null\n pagesDiscovered: number\n pagesFetched: number\n pagesObserved: number\n elapsedMs: number\n terminationReason: string | null\n warnings: string[]\n factors: Array<{ id: string; name: string; averageScore: number; count: number }>\n pages: SiteHealthPageSample[]\n /** Null when the crawl produced no usable graph, never an empty stand-in. */\n siteMap: SiteMapSample | null\n attemptedHosts: string[]\n error: string | null\n}\n\nexport interface CheckResult {\n schemaVersion: typeof CHECK_RESULT_SCHEMA_VERSION\n domain: string\n generatedAt: string\n visibility: VisibilityReport | null\n siteHealth: SiteHealthSample | null\n errors: Array<{ area: 'visibility' | 'site-health'; code: string; message: string }>\n}\n\nexport interface CheckRecord {\n id: string\n fingerprint: string\n domain: string\n /** Questions the visitor supplied. The generator fills the remainder. */\n userQueries: string[]\n status: CheckStatus\n createdAt: string\n updatedAt: string\n expiresAt: string | null\n result: CheckResult | null\n errorCode: string | null\n errorMessage: string | null\n /** A durable execution claim. It prevents two Val isolates from running one check. */\n leaseOwner: string | null\n leaseUntil: string | null\n}\n\nexport interface CheckQuotaClaim {\n scope: 'client' | 'global'\n subject: string\n day: string\n max: number\n}\n\n/**\n * A durable admission result. The store owns this whole decision so concurrent\n * Val isolates cannot independently spend quota and start the same domain.\n */\nexport type CheckAdmission =\n | { kind: 'created'; record: CheckRecord }\n | { kind: 'reused'; record: CheckRecord }\n | { kind: 'reclaimed'; record: CheckRecord }\n | { kind: 'quota-exhausted'; scope: 'client' | 'global' }\n | { kind: 'busy' }\n\nexport interface CheckAdmissionInput {\n candidate: CheckRecord\n now: string\n clientQuota: CheckQuotaClaim\n globalQuota: CheckQuotaClaim\n}\n\nexport interface CheckStore {\n initialize(): Promise\n /**\n * Atomically reuse an active/fresh check, reclaim a crashed lease, or spend\n * quota and create one new record. Production executes this as one durable\n * SQLite admission batch; callers must not compose these steps.\n */\n admit(input: CheckAdmissionInput): Promise\n /** Legacy/read seam used by tests and status helpers; it never returns an expired running lease. */\n findReusable(fingerprint: string, now: string): Promise\n create(record: CheckRecord): Promise\n get(id: string): Promise\n update(\n id: string,\n patch: Partial>,\n ): Promise\n /** Atomically transition a queued/stale check to running and attach a per-check lease. */\n claimJob(id: string, owner: string, now: string, leaseUntil: string): Promise\n /** Publish a terminal result only if this isolate still owns the per-check lease. */\n finalizeJob(\n id: string,\n owner: string,\n patch: Partial>,\n ): Promise\n /** Return an unstarted claimed job to the durable queue when global capacity is occupied. */\n requeueJob(id: string, owner: string, now: string): Promise\n /** One active paid/public check at a time, with expiry so a crashed isolate recovers. */\n claimGlobalLease(name: string, holder: string, now: string, leaseUntil: string): Promise\n releaseGlobalLease(name: string, holder: string): Promise\n /** Atomically spend one unit only while the current UTC-day total is below max. */\n claimQuota(scope: string, subject: string, day: string, max: number): Promise\n}\n\nexport interface SiteHealthRunner {\n run(domain: string, signal: AbortSignal): Promise\n}\n\n/**\n * Internal-only handoff for a request that already reserved the one global\n * execution slot before durable admission. It is never derived from client\n * input or exposed by the public API.\n */\nexport interface PublicCheckDispatchOptions {\n executionLeaseOwner?: string\n}\n\nexport interface PublicCheckRunner {\n run(checkId: string, options?: PublicCheckDispatchOptions): Promise<'completed' | 'busy' | 'ignored'>\n}\n\nexport interface JobDispatcher {\n dispatch(checkId: string, options?: PublicCheckDispatchOptions): Promise<'completed' | 'busy' | 'ignored'>\n}\n",[],[198,536,379],"runtime","30900eea-d6de-4fb1-b86e-dbb1a2dddd6a","records.ts","93b29a9c-a63e-11f1-965f-1607ee4eb77e",217,["D",1788320555384],"/**\n * Shared record identity and lifetime rules.\n *\n * Both the HTTP app and the MCP endpoint resolve checks and decide whether one\n * is still readable. Two copies of either rule would drift silently: a\n * mismatched fingerprint makes the MCP endpoint miss cached work the UI can\n * see, and a mismatched expiry lets one surface serve a result the other has\n * already retired.\n */\nimport type { CheckRecord } from './types.ts'\n\n/** Caller-supplied questions, normalized for identity and for the prompt. */\nexport const MAX_USER_QUERIES = 3\nconst MIN_QUERY_CHARS = 3\nconst MAX_QUERY_CHARS = 200\n\n/**\n * Reuse identity for a domain check. It is versioned because it keys the cache\n * and the one-active-check index: changing what a check measures without\n * changing this prefix would let an old result answer a new question.\n *\n * v3 adds the brands each answer names, which is what mention share is built\n * from. A v2 record cannot satisfy a v3 request: it carries `namedBrands: null`\n * on every row, so the visitor would get a result silently missing half the\n * report and no way to tell why. Bumping the prefix retires those records at\n * the moment the signal set changed rather than at their own TTL.\n *\n * The caller's own questions are part of that identity. They change what the\n * check MEASURES, so two requests for one domain with different questions must\n * never share a result: without them in the key, the second caller silently\n * receives answers to the first caller's questions. Order is preserved rather\n * than sorted, so the key is exactly what was asked.\n */\nexport function checkFingerprint(domain: string, userQueries: readonly string[] = []): string {\n const base = `visibility-v3:${domain}`\n if (userQueries.length === 0) return base\n return `${base}|${userQueries.join('\\u0001')}`\n}\n\n/**\n * Trim, drop blanks, bound length, and cap the count. Returns the questions in\n * the order given; the generator fills whatever remains.\n */\nexport function normalizeUserQueries(input: unknown): string[] {\n const raw = typeof input === 'string' ? input.split('\\n') : Array.isArray(input) ? input : []\n const out: string[] = []\n for (const value of raw) {\n if (typeof value !== 'string') continue\n const trimmed = value.trim().replace(/\\s+/g, ' ')\n if (trimmed.length < MIN_QUERY_CHARS) continue\n out.push(trimmed.slice(0, MAX_QUERY_CHARS))\n if (out.length === MAX_USER_QUERIES) break\n }\n return out\n}\n\n/** A record with no `expiresAt` never expires; anything at or past it is gone. */\nexport function isCheckExpired(record: CheckRecord, at: Date): boolean {\n if (!record.expiresAt) return false\n const expiresAt = Date.parse(record.expiresAt)\n return Number.isFinite(expiresAt) && expiresAt <= at.getTime()\n}\n",[],[198,536,538],"eb2d53de-7095-4756-867a-252fd03349cc",["D",1788292309828],[247,248],[198,536],"a206d538-29a1-4c55-b790-d902b8bd2c9b","tools.ts","93d9894a-a63e-11f1-8fd4-1607ee4eb77e","9269bbca-a63e-11f1-8d00-1607ee4eb77e",206,["D",1788318395885],"/**\n * The MCP tool surface: reads over checks this val has already run, plus the\n * bundled skills for clients that do not implement MCP resources.\n *\n * Every tool but `start_check` is a read, and `start_check` runs the host's\n * full admission path — same global daily cap, same single execution lease,\n * same cache reuse — differing only in that it skips Turnstile, which an agent\n * cannot solve, and spends from its own tighter per-caller bucket. The global\n * cap is what bounds the bill; Turnstile bounds fairness, so this widens who\n * may spend the budget without widening the budget.\n *\n * Results are JSON in a text block rather than `structuredContent`, because\n * every client across both protocol eras renders text content, while typed\n * output is newer and unevenly implemented.\n */\nimport { checkFingerprint, isCheckExpired } from '../runtime/records.ts'\nimport { orderFactors } from '../site-health/factor-order.ts'\nimport { computeMentionShare, computeShareOfVoice, type ShareOfVoice } from '../visibility/share.ts'\nimport type { CheckRecord, CheckStore, VisibilityEvidence } from '../runtime/types.ts'\nimport { normalizePublicDomain, PublicUrlError } from '../security/url.ts'\nimport { listSkillResources, readSkillResource, skillIndex } from './resources.ts'\n\nconst CHECK_ID = /^[0-9a-f-]{36}$/i\n\nexport interface McpToolDefinition {\n name: string\n title: string\n description: string\n inputSchema: Record\n}\n\nexport interface McpToolResult {\n content: Array<{ type: 'text'; text: string }>\n isError?: boolean\n}\n\n/** Runs the host's full admission path; absent when the host disables MCP starts. */\nexport type StartCheckFn = (\n domain: string,\n remoteIp: string | null,\n queries: readonly string[],\n) => Promise<{ record: CheckRecord; reused: boolean }>\n\nexport interface McpToolContext {\n store: CheckStore\n now: () => Date\n startCheck?: StartCheckFn\n /** Edge-provided caller identity, used only as the quota subject. */\n remoteIp?: string | null\n}\n\nfunction ok(payload: unknown): McpToolResult {\n return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] }\n}\n\nfunction fail(message: string, hint?: string): McpToolResult {\n return {\n content: [{ type: 'text', text: JSON.stringify(hint ? { error: message, hint } : { error: message }, null, 2) }],\n isError: true,\n }\n}\n\nconst TARGET_SCHEMA = {\n type: 'object',\n properties: {\n checkId: { type: 'string', description: 'A check ID returned by a previous tool call or shown in the web UI.' },\n domain: {\n type: 'string',\n description:\n 'A domain such as \"example.com\". Resolves the most recent cached check; it never starts one. Use start_check ' +\n 'to run a fresh check.',\n },\n },\n additionalProperties: false,\n} as const\n\n/**\n * Resolve either addressing mode to a readable record.\n *\n * A domain lookup only ever finds work the val already did — it never starts\n * a check — so a miss is reported as a miss rather than quietly queuing paid\n * work the caller did not ask for.\n */\nasync function resolveCheck(\n context: McpToolContext,\n args: Record,\n): Promise<{ record: CheckRecord } | { error: McpToolResult }> {\n const checkId = typeof args.checkId === 'string' ? args.checkId.trim() : ''\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n\n if (!checkId && !domain) return { error: fail('Provide either \"checkId\" or \"domain\".') }\n\n const now = context.now()\n\n if (checkId) {\n if (!CHECK_ID.test(checkId)) return { error: fail(`\"${checkId}\" is not a valid check ID.`) }\n const record = await context.store.get(checkId)\n if (!record || isCheckExpired(record, now)) {\n return {\n error: fail(`No check found for ID \"${checkId}\".`, 'Public checks expire; run a new one from the web UI.'),\n }\n }\n return { record }\n }\n\n let normalized: string\n try {\n normalized = normalizePublicDomain(domain).domain\n } catch (error) {\n return { error: fail(error instanceof PublicUrlError ? error.message : 'Enter a valid public domain.') }\n }\n\n const record = await context.store.findReusable(checkFingerprint(normalized), now.toISOString())\n if (!record) {\n return {\n error: fail(\n `No cached check for \"${normalized}\".`,\n 'Run one with start_check, or from the web UI, then read it here.',\n ),\n }\n }\n return { record }\n}\n\n/** Shared envelope so every tool reports status and freshness the same way. */\nfunction recordEnvelope(record: CheckRecord) {\n return {\n checkId: record.id,\n domain: record.domain,\n status: record.status,\n createdAt: record.createdAt,\n updatedAt: record.updatedAt,\n expiresAt: record.expiresAt,\n error: record.errorCode ? { code: record.errorCode, message: record.errorMessage } : null,\n }\n}\n\n/**\n * Mention and citation are independent signals and are always reported as a\n * pair. A rate is null when nothing succeeded, never 0 — a provider failure is\n * an absent measurement, not a miss, and collapsing the two would report a site\n * as invisible when the check simply did not complete.\n */\nfunction visibilitySummary(record: CheckRecord) {\n const visibility = record.result?.visibility\n if (!visibility) return { measured: false as const }\n return {\n measured: true as const,\n scope: 'non-brand',\n scopeNote: 'Queries are generated non-brand queries, so the project cannot be handed its own answer.',\n successfulChecks: visibility.summary.successfulChecks,\n failedChecks: visibility.summary.failedChecks,\n mentionRate: visibility.summary.mentionRate,\n citationRate: visibility.summary.citationRate,\n rateNote: 'Rates are over successful checks only. A null rate means nothing succeeded, not a rate of zero.',\n startedAt: visibility.startedAt,\n completedAt: visibility.completedAt,\n }\n}\n\nfunction siteHealthSummary(record: CheckRecord) {\n const siteHealth = record.result?.siteHealth\n if (!siteHealth) return { measured: false as const }\n return {\n measured: true as const,\n label: siteHealth.label,\n status: siteHealth.status,\n score: siteHealth.score,\n pagesDiscovered: siteHealth.pagesDiscovered,\n pagesFetched: siteHealth.pagesFetched,\n pagesObserved: siteHealth.pagesObserved,\n terminationReason: siteHealth.terminationReason,\n warnings: siteHealth.warnings,\n error: siteHealth.error,\n }\n}\n\n/** One share table on the wire, or null when that signal was not measurable. */\nfunction shareTable(share: ShareOfVoice | null, note: string) {\n if (!share) return null\n return {\n basis: share.basis,\n note,\n measuredAnswers: share.measuredAnswers,\n unattributedAnswers: share.unattributedAnswers,\n totalAppearances: share.totalAppearances,\n targetShare: share.targetShare,\n entries: share.entries,\n }\n}\n\n/**\n * The mention table is keyed by name, so the target's row needs the brand the\n * answers wrote, not its domain. Falls back to the domain when no answer named\n * it, which is the case where the row exists to report a zero.\n */\nfunction targetBrandLabel(evidence: readonly VisibilityEvidence[], domain: string): string {\n for (const row of evidence) {\n const name = row.matchedTerms.find((term) => !term.includes('.'))\n if (name) return name\n }\n return domain\n}\n\nfunction evidenceRow(evidence: VisibilityEvidence) {\n return {\n query: evidence.query,\n provider: evidence.provider,\n servedModel: evidence.servedModel,\n completedAt: evidence.completedAt,\n // Both signals, always. `null` on either means that check failed.\n mentioned: evidence.mentioned,\n matchedTerms: evidence.matchedTerms,\n cited: evidence.cited,\n matchedCitationDomains: evidence.matchedCitationDomains,\n matchedCitationUrls: evidence.matchedCitationUrls,\n citedDomains: evidence.citedDomains,\n sources: evidence.sources,\n searchQueries: evidence.searchQueries,\n // Brands this answer named, each verified to be written in it. Null means\n // the extraction did not run, not that the answer named nobody.\n namedBrands: evidence.namedBrands,\n retrievalStatus: evidence.retrievalStatus,\n answerText: evidence.answerText,\n error: evidence.error,\n }\n}\n\n/**\n * The conversion path. An agent that has just shown a user their coverage is\n * exactly where \"how do I get this properly\" gets asked, and without this it\n * would have to guess at an install command.\n */\nconst SELF_HOST_TOOL: McpToolDefinition = {\n name: 'self_host',\n title: 'How to self-host Canonry',\n description:\n 'How to run the full Canonry platform instead of this bounded sample: install command, repository, docs, and ' +\n 'what self-hosting adds over this endpoint. Call it when the user asks for more engines, scheduled tracking, ' +\n 'more queries, their own data, or how any of this actually works.',\n inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n}\n\nconst START_CHECK_TOOL: McpToolDefinition = {\n name: 'start_check',\n title: 'Run a new Canonry check',\n description:\n 'Run a fresh check for a domain: three grounded Gemini queries plus a bounded Technical AEO page sample. ' +\n 'Blocks until the check finishes, up to about 45 seconds, and returns the same shape as get_check. A domain ' +\n 'checked in the last 24 hours with the same questions returns the cached result immediately and costs nothing. ' +\n 'Daily limits apply.',\n inputSchema: {\n type: 'object',\n properties: {\n domain: { type: 'string', description: 'A domain such as \"example.com\".' },\n queries: {\n type: 'array',\n items: { type: 'string' },\n maxItems: 3,\n description:\n 'Optional. Up to 3 questions to put to the answer engine, used verbatim. Any remaining slots are filled ' +\n 'with questions generated for the site, so supplying none generates all three.',\n },\n },\n required: ['domain'],\n additionalProperties: false,\n },\n}\n\nconst READ_TOOLS: readonly McpToolDefinition[] = [\n SELF_HOST_TOOL,\n {\n name: 'get_check',\n title: 'Get a Canonry check',\n description:\n 'Status and headline numbers for one domain check: AI visibility (mention and citation rates over non-brand ' +\n 'queries) and the bounded Technical AEO site sample. Address it by checkId or by domain. Reads existing work ' +\n 'only — it never starts a new check.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'get_ai_visibility',\n title: 'Get AI visibility evidence',\n description:\n 'Per query and answer engine evidence for one check. Every row carries \"mentioned\" (the brand appears in the ' +\n 'answer text) and \"cited\" (the domain appears in the sources behind the answer) as independent signals, plus ' +\n 'the answer text, the cited domains and URLs, and the search queries the engine issued. A null signal means ' +\n 'that check failed and was not measured. Also returns two share tables, which are never mixed: citationShare ' +\n '(which domains the engine cited, and what share each holds) and mentionShare (which brands the answer prose ' +\n 'named). Every name in mentionShare was verified to be written in the answer it is counted against.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'get_site_health',\n title: 'Get Technical AEO site sample',\n description:\n 'The bounded Technical AEO sample for one check: overall score, per-factor averages, and per-page scores with ' +\n 'findings, critical defects, and recommendations, plus siteMap — the internal link graph observed by the same ' +\n 'crawl, as nodes and edges. A node is either crawled (it has a score and an indexability verdict) or merely ' +\n 'linked to (it has neither). This is a small page sample, not a whole-site audit.',\n inputSchema: TARGET_SCHEMA,\n },\n {\n name: 'list_skills',\n title: 'List Canonry skill documents',\n description:\n 'Index of the bundled canonry (operator) and aero (analyst) skill documents available from this endpoint. ' +\n 'Entry points come first; read one with read_skill. Clients that support MCP resources can read the same ' +\n 'documents from resources/list.',\n inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n },\n {\n name: 'read_skill',\n title: 'Read a Canonry skill document',\n description: 'Read one skill document as markdown. Accepts a canonry-skill:// URI or a path such as ' +\n '\"aero/references/regression-playbook.md\". Start with an entry point from list_skills, then open the ' +\n 'reference the task calls for.',\n inputSchema: {\n type: 'object',\n properties: {\n uri: { type: 'string', description: 'A canonry-skill:// URI, or \"/\", or a bare reference path.' },\n },\n required: ['uri'],\n additionalProperties: false,\n },\n },\n]\n\n/** The advertised catalog. `start_check` appears only when the host can honour it. */\nexport function mcpTools(context: McpToolContext): readonly McpToolDefinition[] {\n return context.startCheck ? [...READ_TOOLS, START_CHECK_TOOL] : READ_TOOLS\n}\n\nexport async function callMcpTool(\n context: McpToolContext,\n name: string,\n args: Record,\n): Promise {\n switch (name) {\n case 'get_check': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n return ok({\n ...recordEnvelope(resolved.record),\n aiVisibility: visibilitySummary(resolved.record),\n siteHealth: siteHealthSummary(resolved.record),\n partialErrors: resolved.record.result?.errors ?? [],\n })\n }\n\n case 'get_ai_visibility': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n const visibility = resolved.record.result?.visibility\n if (!visibility) {\n return ok({\n ...recordEnvelope(resolved.record),\n measured: false,\n reason: resolved.record.status === 'queued' || resolved.record.status === 'running'\n ? 'The check is still running.'\n : 'This check has no AI visibility result.',\n })\n }\n const citationShare = computeShareOfVoice(visibility.evidence, visibility.domain)\n const mentionShare = computeMentionShare(\n visibility.evidence,\n targetBrandLabel(visibility.evidence, visibility.domain),\n )\n return ok({\n ...recordEnvelope(resolved.record),\n summary: visibilitySummary(resolved.record),\n // Two independent signals, two tables. Never one blended number: a site\n // can be cited without being named and named without being cited.\n citationShare: shareTable(\n citationShare,\n 'Share of the sources the engine used, by how many answers each domain appeared in.',\n ),\n mentionShare: shareTable(\n mentionShare,\n 'Share of the brands the answer prose named, by how many answers named each. Every name was verified to be ' +\n 'written in the answer it is counted against; null means the extraction did not run.',\n ),\n // Retained under its historical name so an existing caller does not\n // break. It has always been the citation table.\n shareOfVoice: shareTable(\n citationShare,\n 'Deprecated alias of citationShare. Use citationShare or mentionShare.',\n ),\n evidence: visibility.evidence.map(evidenceRow),\n })\n }\n\n case 'get_site_health': {\n const resolved = await resolveCheck(context, args)\n if ('error' in resolved) return resolved.error\n const siteHealth = resolved.record.result?.siteHealth\n if (!siteHealth) {\n return ok({\n ...recordEnvelope(resolved.record),\n measured: false,\n reason: resolved.record.status === 'queued' || resolved.record.status === 'running'\n ? 'The check is still running.'\n : 'This check has no Technical AEO result.',\n })\n }\n return ok({\n ...recordEnvelope(resolved.record),\n summary: siteHealthSummary(resolved.record),\n rootUrl: siteHealth.rootUrl,\n finalRootUrl: siteHealth.finalRootUrl,\n // Ranked best to worst, the same order the page shows. A factor with\n // no sampled page is unmeasured, so it ranks last rather than as a 0.\n factors: orderFactors(\n siteHealth.factors,\n (factor) => ({ score: factor.count > 0 ? factor.averageScore : null, label: factor.name }),\n ),\n pages: siteHealth.pages,\n // The internal-link graph from the same crawl. An agent asking \"what\n // links to this weak page\" needs the edges, not just the scores.\n siteMap: siteHealth.siteMap,\n })\n }\n\n case 'start_check': {\n if (!context.startCheck) return fail('Starting a check is not enabled on this endpoint.')\n const domain = typeof args.domain === 'string' ? args.domain.trim() : ''\n if (!domain) return fail('Provide a \"domain\".')\n try {\n const queries = Array.isArray(args.queries) ? args.queries : []\n const { record, reused } = await context.startCheck(domain, context.remoteIp ?? null, queries)\n return ok({\n ...recordEnvelope(record),\n reused,\n aiVisibility: visibilitySummary(record),\n siteHealth: siteHealthSummary(record),\n partialErrors: record.result?.errors ?? [],\n })\n } catch (error) {\n // The host throws typed admission failures (quota, capacity, invalid\n // domain). Their messages are already caller-safe and actionable.\n return fail(error instanceof Error ? error.message : 'The check could not be started.')\n }\n }\n\n case 'self_host':\n return ok({\n summary:\n 'This endpoint is a bounded sample. Canonry is the full platform it samples: open source, self-hosted, ' +\n 'agent-first, with your own data in local SQLite.',\n install: 'npm install -g @canonry/canonry',\n quickstart: [\n 'npm install -g @canonry/canonry',\n 'canonry init',\n 'canonry project create my-site --domain example.com --country US --language en',\n 'canonry query add my-site \"best example widgets\"',\n 'canonry run my-site',\n 'canonry visibility-stats my-site',\n ],\n repository: 'https://github.com/Canonry/canonry',\n website: 'https://canonry.ai',\n package: 'https://www.npmjs.com/package/@canonry/canonry',\n license: 'FSL-1.1-ALv2',\n whatSelfHostingAdds: [\n 'All four answer engines — Gemini, ChatGPT, Claude, Perplexity — not Gemini alone.',\n 'Unlimited tracked queries and scheduled sweeps, instead of 3 generated queries on demand.',\n 'Whole-site technical audits, instead of a 5-page sample.',\n 'History, trends, competitor mention share, and regression insights over time.',\n 'Google Search Console, GA4, Bing, Business Profile, and server-side traffic joined to the same view.',\n 'Your own MCP server (canonry-mcp, 188 tools) and the built-in Aero analyst agent.',\n 'Your data stays in your own SQLite database.',\n ],\n skills: 'The canonry and aero skill documents served by this endpoint are the same playbooks a local install ' +\n 'ships. Read canonry-skill://canonry/SKILL.md to operate the CLI.',\n })\n\n case 'list_skills':\n return ok({ skills: skillIndex(), resources: listSkillResources().length })\n\n case 'read_skill': {\n const uri = typeof args.uri === 'string' ? args.uri.trim() : ''\n if (!uri) return fail('Provide a skill document \"uri\".')\n const contents = readSkillResource(uri)\n if (!contents) {\n return fail(`No skill document matches \"${uri}\".`, 'Call list_skills for the available URIs.')\n }\n return { content: [{ type: 'text', text: contents.text }] }\n }\n\n default:\n return null\n }\n}\n",[],[198,558,550],"mcp","0f16cbfc-2035-48da-893f-092c47b72357","skill-types.ts","93c6ea42-a63e-11f1-9a7d-1607ee4eb77e",40,["D",1788292312217],"/**\n * One bundled skill document, served as an MCP resource.\n *\n * The shape mirrors how the skills are meant to be read: `entryPoint` marks\n * `SKILL.md`, which a connecting agent should load first, and everything else\n * is a reference it opens only when the task calls for it. That is the same\n * lazy-load contract the skills already have in a local install, so an agent\n * reaching them over MCP does not need a second set of rules.\n */\nexport interface SkillDocument {\n /** Stable `canonry-skill:///` identity. */\n uri: string\n skill: string\n /** Path relative to the skill root, for example `references/reporting.md`. */\n path: string\n title: string\n /**\n * For an entry point this is the skill's frontmatter `description` — its\n * entire trigger surface. For a reference it names the owning skill.\n */\n description: string\n entryPoint: boolean\n characters: number\n content: string\n}\n",[],[198,558,560],"c4a2bb17-8623-438d-b37d-71bc2f559281","server.ts","97ad3ed6-a63e-11f1-adb4-1607ee4eb77e",108,["D",1788304015946],"/**\n * MCP method dispatch and the HTTP handler for the `/mcp` endpoint.\n *\n * The endpoint is anonymous, which is a deliberate consequence of what it\n * exposes: checks on this val are already public — the web UI serves any of\n * them from `/api/checks/:id` without a credential — and the skills ship in a\n * public npm package. A token would gate nothing already unreachable, while\n * making the endpoint useless as something an agent is simply pointed at.\n *\n * `start_check` is the one tool that spends. It is admitted by per-caller\n * quota rather than by a credential, under the same global daily cap as the\n * browser, so an anonymous caller can consume its share of the day's budget\n * but never enlarge it.\n */\nimport { listSkillResources, readSkillResource } from './resources.ts'\nimport {\n isAllowedOrigin,\n JsonRpcErrorCodes,\n type JsonRpcResponse,\n jsonRpcError,\n jsonRpcResult,\n type ParsedMcpRequest,\n parseMcpRequest,\n SUPPORTED_PROTOCOL_VERSIONS,\n} from './protocol.ts'\nimport { callMcpTool, type McpToolContext, mcpTools, type StartCheckFn } from './tools.ts'\n\n/** Version of this MCP surface, not of the Canonry package the val samples. */\nexport const MCP_SERVER_VERSION = '1.0.0'\n\nconst MAX_BODY_BYTES = 262_144\n\n// Named for what this endpoint is, not for the platform it samples. Calling it\n// `canonry` would tell an agent it had the whole product, when it has three\n// queries and five pages.\nconst SERVER_INFO = {\n name: 'ai-visibility-check',\n title: 'AI Visibility Check (by Canonry)',\n version: MCP_SERVER_VERSION,\n} as const\n\nconst INSTRUCTIONS = [\n 'AI Visibility Check is a free, bounded sample of Canonry. It measures whether an AI answer engine mentions a',\n 'brand and cites its domain. One check is 3 generated non-brand queries against Gemini plus a 5-page technical',\n 'audit: enough to see the signal, not enough to monitor a site. Canonry itself is open source, self-hosted,',\n 'tracks Gemini, ChatGPT, Claude and Perplexity on a schedule, and has no such limits. Call self_host for that.',\n '',\n 'Two signals are tracked separately and must never be merged: \"mentioned\" means the brand appears in the answer',\n 'text, \"cited\" means the domain appears in the sources behind the answer. A model can do either, both, or neither.',\n 'A null signal means that check failed and was not measured — it is not a miss.',\n '',\n 'Start with list_skills and read the aero entry point for how to interpret and report on coverage; read the canonry',\n 'entry point for how to operate the CLI. Then use get_check for headline numbers, get_ai_visibility for per-query',\n 'evidence, and get_site_health for the Technical AEO page sample.',\n '',\n 'get_check, get_ai_visibility, and get_site_health read existing checks and never spend. start_check runs a fresh',\n 'one, blocks for up to about 45 seconds, and is subject to daily limits; a domain checked in the last 24 hours',\n 'returns from cache at no cost. Prefer reading before starting.',\n].join('\\n')\n\nexport interface McpHandlerOptions {\n store: McpToolContext['store']\n now?: () => Date\n /** Omit to keep the endpoint strictly read-only. */\n startCheck?: StartCheckFn\n}\n\nfunction jsonResponse(body: JsonRpcResponse, status = 200): Response {\n return new Response(JSON.stringify(body), {\n status,\n headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },\n })\n}\n\nasync function readLimitedBody(request: Request): Promise {\n const declared = Number(request.headers.get('content-length'))\n if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) return null\n if (!request.body) return ''\n const reader = request.body.getReader()\n const chunks: Uint8Array[] = []\n let length = 0\n while (true) {\n const next = await reader.read()\n if (next.done) break\n length += next.value.byteLength\n if (length > MAX_BODY_BYTES) {\n await reader.cancel()\n return null\n }\n chunks.push(next.value)\n }\n const merged = new Uint8Array(length)\n let offset = 0\n for (const chunk of chunks) {\n merged.set(chunk, offset)\n offset += chunk.byteLength\n }\n return new TextDecoder().decode(merged)\n}\n\n/**\n * Val injects `cf-connecting-ip`. `x-forwarded-for` is caller-controlled on a\n * public val and is deliberately ignored, so a caller cannot mint a fresh\n * quota identity per request.\n */\nfunction edgeIp(request: Request): string | null {\n const value = request.headers.get('cf-connecting-ip')?.trim()\n return value && value.length <= 128 ? value : null\n}\n\n/** Dispatch one parsed message. Returns null for a notification, which gets 202. */\nasync function dispatch(\n context: McpToolContext,\n request: ParsedMcpRequest,\n): Promise<{ response: JsonRpcResponse; status: number } | null> {\n const { message, protocolVersion } = request\n const id = message.id ?? null\n const params = message.params ?? {}\n\n switch (message.method) {\n case 'initialize': {\n // Echo a version the caller asked for when it is one we speak, so a\n // legacy client stays in its own era instead of being pushed forward\n // into rules it does not implement. A client that declared its version\n // only in the `MCP-Protocol-Version` header and omitted it from params\n // still gets its own era back, because `protocolVersion` carries what\n // the envelope declared; falling through to the newest version would\n // answer a 2025 client with 2026 rules it has no code for.\n const requested = typeof params.protocolVersion === 'string' ? params.protocolVersion : null\n const negotiated = requested && (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)\n ? requested\n : protocolVersion\n return {\n status: 200,\n response: jsonRpcResult(id, {\n protocolVersion: negotiated,\n capabilities: { tools: { listChanged: false }, resources: { listChanged: false, subscribe: false } },\n serverInfo: SERVER_INFO,\n instructions: INSTRUCTIONS,\n }),\n }\n }\n\n // Accepted so a legacy handshake completes. There is no session to advance.\n case 'notifications/initialized':\n case 'notifications/cancelled':\n return null\n\n case 'ping':\n return { status: 200, response: jsonRpcResult(id, {}) }\n\n case 'tools/list':\n return { status: 200, response: jsonRpcResult(id, { tools: mcpTools(context) }) }\n\n case 'tools/call': {\n const name = typeof params.name === 'string' ? params.name : ''\n const args = params.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments)\n ? params.arguments as Record\n : {}\n if (!name) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, 'tools/call requires a \"name\".'),\n }\n }\n const result = await callMcpTool(context, name, args)\n if (!result) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, `Unknown tool \"${name}\".`),\n }\n }\n return { status: 200, response: jsonRpcResult(id, result) }\n }\n\n case 'resources/list':\n return { status: 200, response: jsonRpcResult(id, { resources: listSkillResources() }) }\n\n // Answered rather than refused: several clients probe both during startup,\n // and a method-not-found there reads as a broken server.\n case 'resources/templates/list':\n return { status: 200, response: jsonRpcResult(id, { resourceTemplates: [] }) }\n\n case 'prompts/list':\n return { status: 200, response: jsonRpcResult(id, { prompts: [] }) }\n\n case 'resources/read': {\n const uri = typeof params.uri === 'string' ? params.uri : ''\n const contents = uri ? readSkillResource(uri) : null\n if (!contents) {\n return {\n status: 200,\n response: jsonRpcError(id, JsonRpcErrorCodes.invalidParams, `Resource not found: \"${uri}\".`),\n }\n }\n return { status: 200, response: jsonRpcResult(id, { contents: [contents] }) }\n }\n\n default:\n // Streamable HTTP pairs an unknown method with 404, which is how a client\n // tells a modern server apart from a legacy endpoint that lacks this route.\n return {\n status: 404,\n response: jsonRpcError(id, JsonRpcErrorCodes.methodNotFound, `Unknown method \"${message.method}\".`),\n }\n }\n}\n\n/** Handle one POST to the MCP endpoint. */\nexport function createMcpHandler(options: McpHandlerOptions): (request: Request) => Promise {\n const base: McpToolContext = {\n store: options.store,\n now: options.now ?? (() => new Date()),\n startCheck: options.startCheck,\n }\n\n return async (request: Request): Promise => {\n if (request.method !== 'POST') {\n // The modern revision removed the GET stream and DELETE teardown.\n return jsonResponse(\n jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'The MCP endpoint accepts POST only.'),\n 405,\n )\n }\n\n if (!isAllowedOrigin(request.headers, request.url)) {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Origin not allowed.'), 403)\n }\n\n const raw = await readLimitedBody(request)\n if (raw === null) {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request body is too large.'), 413)\n }\n\n let body: unknown\n try {\n body = JSON.parse(raw)\n } catch {\n return jsonResponse(jsonRpcError(null, JsonRpcErrorCodes.parseError, 'Request body is not valid JSON.'), 400)\n }\n\n const parsed = parseMcpRequest(request.headers, body)\n if (!parsed.ok) return jsonResponse(parsed.response, parsed.status)\n\n let outcome: Awaited>\n try {\n outcome = await dispatch({ ...base, remoteIp: edgeIp(request) }, parsed.request)\n } catch {\n // Never surface an internal message; a store failure can carry\n // deployment detail that does not belong on a public endpoint.\n return jsonResponse(\n jsonRpcError(parsed.request.message.id ?? null, JsonRpcErrorCodes.internalError, 'Internal error.'),\n 200,\n )\n }\n\n if (!outcome) {\n if (!parsed.request.isNotification) {\n // A request that dispatched as a notification would otherwise hang the\n // caller waiting for a response that is never coming.\n return jsonResponse(\n jsonRpcError(\n parsed.request.message.id ?? null,\n JsonRpcErrorCodes.invalidRequest,\n `\"${parsed.request.message.method}\" is a notification and must be sent without an \"id\".`,\n ),\n 400,\n )\n }\n return new Response(null, { status: 202, headers: { 'cache-control': 'no-store' } })\n }\n\n return jsonResponse(outcome.response, outcome.status)\n }\n}\n",[],[198,558,568],"ccfbc8ea-f94f-4497-a994-e882d008b341","resources.ts","93b7d796-a63e-11f1-9193-1607ee4eb77e",39,["D",1788292312132],"/**\n * The bundled `canonry` and `aero` skills, served as MCP resources.\n *\n * This is the half of the endpoint that makes the other half worth connecting\n * to. Coverage numbers on their own need interpretation — which signal moved,\n * whether the denominator is comparable, what to do next — and that\n * interpretation is exactly what the two skills already write down. An agent\n * that reads them alongside the data behaves like an analyst instead of a JSON\n * pretty-printer.\n *\n * `resources/list` returns entry points and references together, with\n * `SKILL.md` first, so a client can load the entry point and open a reference\n * only when the task calls for it. That is the same contract a local install\n * has, so nothing new has to be explained to the agent.\n */\nimport type { SkillDocument } from './skill-types.ts'\nimport { SKILL_DOCUMENTS } from './skills/catalog.ts'\n\nexport const SKILL_RESOURCE_MIME_TYPE = 'text/markdown'\n\nexport interface McpResourceDescriptor {\n uri: string\n name: string\n title: string\n description: string\n mimeType: string\n}\n\nexport interface McpResourceContents {\n uri: string\n mimeType: string\n text: string\n}\n\n/** Entry points first, then references, each group alphabetical by URI. */\nconst ORDERED_DOCUMENTS: readonly SkillDocument[] = [...SKILL_DOCUMENTS].sort((a, b) => {\n if (a.entryPoint !== b.entryPoint) return a.entryPoint ? -1 : 1\n return a.uri.localeCompare(b.uri)\n})\n\nconst BY_URI = new Map(ORDERED_DOCUMENTS.map((document) => [document.uri, document]))\n\n/**\n * Also index by `/` and by bare path so a caller that reconstructs\n * a reference from prose in `SKILL.md` — which links them as\n * `references/reporting.md` — reaches the document instead of a not-found.\n */\nconst BY_ALIAS = new Map()\nfor (const document of ORDERED_DOCUMENTS) {\n BY_ALIAS.set(`${document.skill}/${document.path}`, document)\n const bare = document.path\n // A bare path is ambiguous only if two skills share it; first one wins and\n // the qualified form above always remains exact.\n if (!BY_ALIAS.has(bare)) BY_ALIAS.set(bare, document)\n}\n\nexport function listSkillResources(): McpResourceDescriptor[] {\n return ORDERED_DOCUMENTS.map((document) => ({\n uri: document.uri,\n name: `${document.skill}/${document.path}`,\n title: document.title,\n description: document.entryPoint\n ? `Entry point for the ${document.skill} skill. ${document.description}`\n : document.description,\n mimeType: SKILL_RESOURCE_MIME_TYPE,\n }))\n}\n\nexport function findSkillDocument(uri: string): SkillDocument | null {\n const trimmed = uri.trim()\n return BY_URI.get(trimmed) ?? BY_ALIAS.get(trimmed.replace(/^canonry-skill:\\/\\//, '')) ?? null\n}\n\nexport function readSkillResource(uri: string): McpResourceContents | null {\n const document = findSkillDocument(uri)\n if (!document) return null\n return { uri: document.uri, mimeType: SKILL_RESOURCE_MIME_TYPE, text: document.content }\n}\n\n/** Compact index used by the `read_skill` tool, for clients without resource support. */\nexport function skillIndex(): Array<{ uri: string; skill: string; path: string; title: string; entryPoint: boolean }> {\n return ORDERED_DOCUMENTS.map((document) => ({\n uri: document.uri,\n skill: document.skill,\n path: document.path,\n title: document.title,\n entryPoint: document.entryPoint,\n }))\n}\n",[],[198,558,576],"67c1d767-f5f3-4ebd-bca5-d25acdc403f7","protocol.ts","94264780-a63e-11f1-a387-1607ee4eb77e",229,["D",1788372559904],"/**\n * JSON-RPC framing and Streamable HTTP envelope rules for the MCP endpoint.\n *\n * Two protocol eras have to work at once. Revision `2026-07-28` removed\n * protocol-level sessions and the GET stream, and moved per-request metadata\n * into the body, so a modern client can POST `tools/call` with no handshake at\n * all. Every client shipping today still opens with `initialize` and expects a\n * negotiated version back. Refusing either one would make the endpoint useless\n * to half its callers, so this module speaks both and keys the strict checks\n * off the version the caller actually declared.\n *\n * Responses are always `application/json`. Both eras permit it for a request\n * that has nothing to stream, and every tool here returns a single value, so\n * an SSE encoder would be machinery with no purpose.\n */\n\n/** Newest first. The head is what an unversioned or unknown request negotiates to. */\nexport const SUPPORTED_PROTOCOL_VERSIONS = [\n '2026-07-28',\n '2025-11-25',\n '2025-06-18',\n '2025-03-26',\n] as const\n\nexport type ProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number]\n\nexport const LATEST_PROTOCOL_VERSION: ProtocolVersion = SUPPORTED_PROTOCOL_VERSIONS[0]\n\n/**\n * The first revision that mirrors body fields into headers and requires them to\n * agree. Older callers never send `Mcp-Method`, so validating them against it\n * would reject every compliant legacy client.\n */\nconst HEADER_VALIDATION_FROM: ProtocolVersion = '2026-07-28'\n\nexport const JSON_RPC_VERSION = '2.0'\n\nexport const JsonRpcErrorCodes = {\n parseError: -32700,\n invalidRequest: -32600,\n methodNotFound: -32601,\n invalidParams: -32602,\n internalError: -32603,\n /** Streamable HTTP: headers disagree with the body, or a required one is missing. */\n headerMismatch: -32020,\n} as const\n\nexport type JsonRpcId = string | number | null\n\nexport interface JsonRpcRequest {\n jsonrpc: typeof JSON_RPC_VERSION\n id?: JsonRpcId\n method: string\n params?: Record\n}\n\nexport interface JsonRpcError {\n code: number\n message: string\n data?: unknown\n}\n\nexport interface JsonRpcSuccessResponse {\n jsonrpc: typeof JSON_RPC_VERSION\n id: JsonRpcId\n result: unknown\n}\n\nexport interface JsonRpcErrorResponse {\n jsonrpc: typeof JSON_RPC_VERSION\n id: JsonRpcId\n error: JsonRpcError\n}\n\nexport type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse\n\nexport function jsonRpcResult(id: JsonRpcId, result: unknown): JsonRpcSuccessResponse {\n return { jsonrpc: JSON_RPC_VERSION, id, result }\n}\n\nexport function jsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcErrorResponse {\n return { jsonrpc: JSON_RPC_VERSION, id, error: data === undefined ? { code, message } : { code, message, data } }\n}\n\nexport function isSupportedProtocolVersion(value: string): value is ProtocolVersion {\n return (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(value)\n}\n\nfunction requiresHeaderValidation(version: ProtocolVersion): boolean {\n // Dated versions compare correctly as strings; they are all `YYYY-MM-DD`.\n return version >= HEADER_VALIDATION_FROM\n}\n\n/** A parsed, envelope-valid POST body plus the metadata the transport carries. */\nexport interface ParsedMcpRequest {\n message: JsonRpcRequest\n /** Absent `id` means a notification, which is answered with 202 and no body. */\n isNotification: boolean\n protocolVersion: ProtocolVersion\n}\n\nexport type McpRequestParseResult =\n | { ok: true; request: ParsedMcpRequest }\n | { ok: false; status: number; response: JsonRpcErrorResponse }\n\nfunction readMetaProtocolVersion(params: Record | undefined): string | null {\n const meta = params?._meta\n if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return null\n const value = (meta as Record)['io.modelcontextprotocol/protocolVersion']\n return typeof value === 'string' ? value : null\n}\n\n/**\n * Undo the `=?base64?…?=` sentinel a client uses for a header value that cannot\n * be written as plain ASCII. Comparing the raw sentinel against the body would\n * report a mismatch on every non-ASCII tool name.\n */\nfunction decodeHeaderValue(value: string): string {\n if (!value.startsWith('=?base64?') || !value.endsWith('?=')) return value\n try {\n const encoded = value.slice('=?base64?'.length, -'?='.length)\n return new TextDecoder().decode(Uint8Array.from(atob(encoded), (char) => char.charCodeAt(0)))\n } catch {\n return value\n }\n}\n\n/**\n * Validate the HTTP envelope and JSON-RPC shape of one POST.\n *\n * Returns the negotiated protocol version alongside the message so the\n * dispatcher never has to re-derive it. A failure carries both the HTTP status\n * and the JSON-RPC body, because Streamable HTTP pairs specific statuses with\n * specific error codes and a caller distinguishes eras by reading them.\n */\nexport function parseMcpRequest(headers: Headers, body: unknown): McpRequestParseResult {\n if (!body || typeof body !== 'object' || Array.isArray(body)) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request body must be a JSON-RPC object.'),\n }\n }\n\n const message = body as Record\n if (message.jsonrpc !== JSON_RPC_VERSION) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Expected \"jsonrpc\": \"2.0\".'),\n }\n }\n if (typeof message.method !== 'string' || message.method.length === 0) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Request is missing a \"method\".'),\n }\n }\n if ('result' in message || 'error' in message) {\n // Clients never send responses on this transport in any era.\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(null, JsonRpcErrorCodes.invalidRequest, 'Clients must not send JSON-RPC responses.'),\n }\n }\n\n const rawId = message.id\n const isNotification = rawId === undefined\n const id: JsonRpcId = typeof rawId === 'string' || typeof rawId === 'number' ? rawId : null\n const params = message.params && typeof message.params === 'object' && !Array.isArray(message.params)\n ? message.params as Record\n : undefined\n\n const headerVersion = headers.get('mcp-protocol-version')?.trim() || null\n const bodyVersion = readMetaProtocolVersion(params)\n\n // A version present in both places must agree before either is trusted; a\n // proxy routing on the header and a server reading the body would otherwise\n // act on different values.\n if (headerVersion && bodyVersion && headerVersion !== bodyVersion) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(\n id,\n JsonRpcErrorCodes.headerMismatch,\n `MCP-Protocol-Version header \"${headerVersion}\" does not match the body value \"${bodyVersion}\".`,\n ),\n }\n }\n\n const declared = headerVersion ?? bodyVersion\n\n // An `initialize` with no declared version is a legacy client opening a\n // handshake; it negotiates inside the method. Anything else defaults to the\n // newest version, which is also the one whose rules are strictest.\n let protocolVersion: ProtocolVersion = LATEST_PROTOCOL_VERSION\n if (declared !== null) {\n if (!isSupportedProtocolVersion(declared)) {\n return {\n ok: false,\n status: 400,\n response: jsonRpcError(\n id,\n JsonRpcErrorCodes.invalidRequest,\n `Unsupported protocol version \"${declared}\".`,\n { supported: [...SUPPORTED_PROTOCOL_VERSIONS] },\n ),\n }\n }\n protocolVersion = declared\n }\n\n if (declared !== null && requiresHeaderValidation(protocolVersion)) {\n const mismatch = validateMirroredHeaders(headers, message.method, params)\n if (mismatch) {\n return { ok: false, status: 400, response: jsonRpcError(id, JsonRpcErrorCodes.headerMismatch, mismatch) }\n }\n }\n\n return {\n ok: true,\n request: {\n message: { jsonrpc: JSON_RPC_VERSION, id, method: message.method, params },\n isNotification,\n protocolVersion,\n },\n }\n}\n\n/** `Mcp-Method` and, where the method carries a name, `Mcp-Name` must mirror the body. */\nfunction validateMirroredHeaders(\n headers: Headers,\n method: string,\n params: Record | undefined,\n): string | null {\n const headerMethod = headers.get('mcp-method')?.trim()\n if (!headerMethod) return 'Mcp-Method header is required.'\n if (headerMethod !== method) {\n return `Mcp-Method header \"${headerMethod}\" does not match the body method \"${method}\".`\n }\n\n const namedMethods: Record = {\n 'tools/call': 'name',\n 'resources/read': 'uri',\n 'prompts/get': 'name',\n }\n const nameField = namedMethods[method]\n if (!nameField) return null\n\n const bodyValue = params?.[nameField]\n if (typeof bodyValue !== 'string') return null\n\n const headerName = headers.get('mcp-name')\n if (headerName === null) return 'Mcp-Name header is required for this method.'\n const decoded = decodeHeaderValue(headerName.trim())\n if (decoded !== bodyValue) {\n return `Mcp-Name header \"${decoded}\" does not match the body value \"${bodyValue}\".`\n }\n return null\n}\n\n/**\n * Reject a cross-origin browser caller.\n *\n * A non-browser MCP client sends no `Origin` at all, so this is only ever\n * exercised by a page in a browser. Allowing same-origin and absent covers\n * every real client while closing the DNS-rebinding hole the transport spec\n * calls out.\n */\nexport function isAllowedOrigin(headers: Headers, requestUrl: string): boolean {\n const origin = headers.get('origin')\n if (!origin) return true\n try {\n return new URL(origin).origin === new URL(requestUrl).origin\n } catch {\n return false\n }\n}\n",[],[198,558,584],"505f0491-d221-40e9-a017-b2abe4b96e41","catalog.ts","94b112b6-a63e-11f1-add5-1607ee4eb77e","92d014b0-a63e-11f1-8fd4-1607ee4eb77e",58,["D",1788292313768],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\n\nimport type { SkillDocument } from '../skill-types.ts'\n\nimport { part as aeroSkillPart0 } from './aero-skill.0.ts'\nimport { part as aeroReferencesAeoDiscoveryPart0 } from './aero-references-aeo-discovery.0.ts'\nimport { part as aeroReferencesMemoryPatternsPart0 } from './aero-references-memory-patterns.0.ts'\nimport { part as aeroReferencesOrchestrationPart0 } from './aero-references-orchestration.0.ts'\nimport { part as aeroReferencesRegressionPlaybookPart0 } from './aero-references-regression-playbook.0.ts'\nimport { part as aeroReferencesReportingPart0 } from './aero-references-reporting.0.ts'\nimport { part as aeroReferencesWordpressElementorMcpPart0 } from './aero-references-wordpress-elementor-mcp.0.ts'\nimport { part as aeroSoulPart0 } from './aero-soul.0.ts'\nimport { part as canonrySkillPart0 } from './canonry-skill.0.ts'\nimport { part as canonryReferencesAeoAnalysisPart0 } from './canonry-references-aeo-analysis.0.ts'\nimport { part as canonryReferencesCanonryCliPart0 } from './canonry-references-canonry-cli.0.ts'\nimport { part as canonryReferencesCanonryCliPart1 } from './canonry-references-canonry-cli.1.ts'\nimport { part as canonryReferencesGoogleBusinessProfilePart0 } from './canonry-references-google-business-profile.0.ts'\nimport { part as canonryReferencesGoogleMarketingPart0 } from './canonry-references-google-marketing.0.ts'\nimport { part as canonryReferencesIndexingPart0 } from './canonry-references-indexing.0.ts'\nimport { part as canonryReferencesServerSideTrafficPart0 } from './canonry-references-server-side-traffic.0.ts'\nimport { part as canonryReferencesWordpressIntegrationPart0 } from './canonry-references-wordpress-integration.0.ts'\n\nexport const SKILL_DOCUMENTS: readonly SkillDocument[] = [\n {\n uri: \"canonry-skill://aero/SKILL.md\",\n skill: \"aero\",\n path: \"SKILL.md\",\n title: \"aero skill\",\n description: \"Diagnose AEO regressions and report on them: why mention or citation coverage moved, which queries and answer engines changed, and what to do about it. Use when a coverage number moved and needs explaining, when preparing a client report or month-over-month comparison, or when a `cnry` sweep completed and needs analysis. Coordinates canonry sweeps with aeo-audit site analysis and keeps durable project memory. Use the canonry skill for setup and operations instead.\",\n entryPoint: true,\n characters: 8122,\n content: aeroSkillPart0,\n },\n {\n uri: \"canonry-skill://aero/references/aeo-discovery.md\",\n skill: \"aero\",\n path: \"references/aeo-discovery.md\",\n title: \"AEO Discovery (Tracked-Basket Expansion)\",\n description: \"How to operate the tracked-basket discovery pipeline. Read when an operator asks to expand a project's basket, audit its competitive surface, or you wake unprompted on `aeo-discover-probe.completed`.\",\n entryPoint: false,\n characters: 12617,\n content: aeroReferencesAeoDiscoveryPart0,\n },\n {\n uri: \"canonry-skill://aero/references/memory-patterns.md\",\n skill: \"aero\",\n path: \"references/memory-patterns.md\",\n title: \"Memory Patterns\",\n description: \"When to remember vs. re-query — project state lives in canonry, only durable user-scoped facts go in Aero memory. Read when unsure whether to call canonry_memory_set or look up.\",\n entryPoint: false,\n characters: 4458,\n content: aeroReferencesMemoryPatternsPart0,\n },\n {\n uri: \"canonry-skill://aero/references/orchestration.md\",\n skill: \"aero\",\n path: \"references/orchestration.md\",\n title: \"Orchestration Workflows\",\n description: \"Workflow recipes — baseline, regression response, weekly review, content gap analysis. Read when planning a multi-step task or recurring review.\",\n entryPoint: false,\n characters: 6788,\n content: aeroReferencesOrchestrationPart0,\n },\n {\n uri: \"canonry-skill://aero/references/regression-playbook.md\",\n skill: \"aero\",\n path: \"references/regression-playbook.md\",\n title: \"Regression Playbook\",\n description: \"Detection → triage → diagnosis → response for lost mentions (primary) and lost citations (secondary). Read when investigating why a query lost a mention or a citation.\",\n entryPoint: false,\n characters: 8306,\n content: aeroReferencesRegressionPlaybookPart0,\n },\n {\n uri: \"canonry-skill://aero/references/reporting.md\",\n skill: \"aero\",\n path: \"references/reporting.md\",\n title: \"Reporting Templates\",\n description: \"Weekly and monthly report templates with metric tables, regression/gain sections, and recommended-actions structure. Read when asked to produce a client-facing summary.\",\n entryPoint: false,\n characters: 10349,\n content: aeroReferencesReportingPart0,\n },\n {\n uri: \"canonry-skill://aero/references/wordpress-elementor-mcp.md\",\n skill: \"aero\",\n path: \"references/wordpress-elementor-mcp.md\",\n title: \"Elementor + WordPress MCP Development Guide\",\n description: \"WordPress + Elementor MCP integration guide — prerequisites, auth, widget manipulation. Read only when the task involves editing WordPress/Elementor pages.\",\n entryPoint: false,\n characters: 8449,\n content: aeroReferencesWordpressElementorMcpPart0,\n },\n {\n uri: \"canonry-skill://aero/soul.md\",\n skill: \"aero\",\n path: \"soul.md\",\n title: \"Who You Are\",\n description: \"Aero's persona, values, and voice — context-agnostic identity that applies whether Aero runs as the built-in agent or wraps around an external agent shell.\",\n entryPoint: false,\n characters: 2540,\n content: aeroSoulPart0,\n },\n {\n uri: \"canonry-skill://canonry/SKILL.md\",\n skill: \"canonry\",\n path: \"SKILL.md\",\n title: \"canonry skill\",\n description: \"Operate Canonry (the `cnry` / `canonry` CLI) for AEO. Load this BEFORE any canonry operator task: creating or configuring a project, connecting GSC, GA4, Bing, Google Business Profile or a Cloudflare traffic source, running or scheduling a sweep, reading mention and citation coverage, running a technical audit, submitting sitemaps, or diagnosing why a number moved. Covers anything touching cnry, canonry doctor, ~/.canonry, @canonry/canonry, the canonry_* MCP tools, mention share, or direct-push / queue-pull traffic. Load it before acting, not after something fails.\",\n entryPoint: true,\n characters: 18860,\n content: canonrySkillPart0,\n },\n {\n uri: \"canonry-skill://canonry/references/aeo-analysis.md\",\n skill: \"canonry\",\n path: \"references/aeo-analysis.md\",\n title: \"AEO Analysis: Interpreting Canonry Results\",\n description: \"canonry skill reference: references/aeo-analysis.md\",\n entryPoint: false,\n characters: 14833,\n content: canonryReferencesAeoAnalysisPart0,\n },\n {\n uri: \"canonry-skill://canonry/references/canonry-cli.md\",\n skill: \"canonry\",\n path: \"references/canonry-cli.md\",\n title: \"Canonry CLI Reference\",\n description: \"canonry skill reference: references/canonry-cli.md\",\n entryPoint: false,\n characters: 101004,\n content: [canonryReferencesCanonryCliPart0, canonryReferencesCanonryCliPart1].join(''),\n },\n {\n uri: \"canonry-skill://canonry/references/google-business-profile.md\",\n skill: \"canonry\",\n path: \"references/google-business-profile.md\",\n title: \"Google Business Profile Integration\",\n description: \"canonry skill reference: references/google-business-profile.md\",\n entryPoint: false,\n characters: 32627,\n content: canonryReferencesGoogleBusinessProfilePart0,\n },\n {\n uri: \"canonry-skill://canonry/references/google-marketing.md\",\n skill: \"canonry\",\n path: \"references/google-marketing.md\",\n title: \"Google Ads and Google Tag Manager\",\n description: \"canonry skill reference: references/google-marketing.md\",\n entryPoint: false,\n characters: 6311,\n content: canonryReferencesGoogleMarketingPart0,\n },\n {\n uri: \"canonry-skill://canonry/references/indexing.md\",\n skill: \"canonry\",\n path: \"references/indexing.md\",\n title: \"Indexing Workflows for AEO\",\n description: \"canonry skill reference: references/indexing.md\",\n entryPoint: false,\n characters: 6438,\n content: canonryReferencesIndexingPart0,\n },\n {\n uri: \"canonry-skill://canonry/references/server-side-traffic.md\",\n skill: \"canonry\",\n path: \"references/server-side-traffic.md\",\n title: \"Server-side traffic (AI Visibility — Server-Side)\",\n description: \"canonry skill reference: references/server-side-traffic.md\",\n entryPoint: false,\n characters: 53542,\n content: canonryReferencesServerSideTrafficPart0,\n },\n {\n uri: \"canonry-skill://canonry/references/wordpress-integration.md\",\n skill: \"canonry\",\n path: \"references/wordpress-integration.md\",\n title: \"WordPress Integration\",\n description: \"canonry skill reference: references/wordpress-integration.md\",\n entryPoint: false,\n characters: 2258,\n content: canonryReferencesWordpressIntegrationPart0,\n },\n]\n",[],[198,558,600,592],"skills","3b407e93-33be-49d2-b948-3ff483d0f07f",["D",1788372561192],[],[198,558,600,34],"84ec8cc7-f919-4962-98b8-eac81a8c101d","canonry-references-wordpress-integration.0.ts","9419bc9a-a63e-11f1-9ccc-1607ee4eb77e",230,["D",1788372560128],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part =\n '# WordPress Integration\\n\\nCanonry integrates with WordPress through the core REST API plus Application Passwords.\\n\\n## What Canonry Automates\\n\\n- Read and write page content, titles, slugs, and status\\n- Audit pages for `noindex`, missing SEO title, missing meta description, missing schema, and thin content\\n- Compare live vs staging for a page with `cnry wordpress diff`\\n- Update SEO meta when the site exposes writable REST meta fields\\n\\n## What Stays Manual\\n\\nCanonry generates payloads and instructions for these workflows, but it does not apply them remotely:\\n\\n- `cnry wordpress set-schema`\\n- `cnry wordpress set-llms-txt`\\n- `cnry wordpress staging push`\\n\\nExpect those commands to return:\\n\\n- `manualRequired: true`\\n- generated content\\n- target/admin URL when available\\n- next-step instructions\\n\\n## Environment Model\\n\\nEach project-scoped WordPress connection stores:\\n\\n- live `url`\\n- optional `stagingUrl`\\n- `defaultEnv`\\n- `username`\\n- `appPassword`\\n\\nEnv-sensitive commands accept `--live` or `--staging`. If neither is provided, canonry uses `defaultEnv`.\\n\\n## Typical Workflow\\n\\n```bash\\ncnry wordpress connect mysite --url https://example.com --user admin --staging-url https://staging.example.com --default-env staging\\ncnry wordpress pages mysite --staging\\ncnry wordpress page mysite pricing --staging\\ncnry wordpress set-meta mysite pricing --title \"SEO title\" --description \"Meta description\" --staging\\ncnry wordpress audit mysite --staging\\ncnry wordpress diff mysite pricing\\ncnry wordpress staging push mysite\\n```\\n\\n## Important Constraints\\n\\n- WordPress auth is stored locally in `~/.canonry/config.yaml`\\n- Canonry does not use wp-admin automation or undocumented plugin APIs\\n- If SEO meta is not writable through REST, canonry returns an actionable error instead of guessing\\n- Duplicate slug matches are returned as explicit ambiguity errors with candidate page IDs/titles\\n- Authentication is verified on connect by calling `/wp/v2/users/me` — if that fails, canonry returns an actionable error message\\n\\n## Related: Elementor MCP\\n\\nFor programmatic management of Elementor page layouts, widgets, and styling via MCP tools, see the aero skill reference: [`skills/aero/references/wordpress-elementor-mcp.md`](../../aero/references/wordpress-elementor-mcp.md).\\n'\n",[],[198,558,600,606],"1d0315d1-aedd-483b-8283-8c329d2b93f4","canonry-references-server-side-traffic.0.ts","941f748c-a63e-11f1-8fd4-1607ee4eb77e",232,["D",1788372560225],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part =\n '# Server-side traffic (AI Visibility — Server-Side)\\n\\nServer-side traffic ingestion captures **what AI engines actually do at\\nyour site** — bots crawling pages, AI products fetching pages for users,\\nand AI products sending click-through arrivals. Citation data measures\\n**what models say** about you. The two surfaces are independent.\\n\\n## When to use it\\n\\nReach for server-side traffic when an analyst or operator asks:\\n\\n- *\"Is GPTBot / ClaudeBot / PerplexityBot actually fetching my pages?\"*\\n- *\"Did an AI product fetch this page for a user?\"*\\n- *\"Which paths are AI engines paying attention to?\"*\\n- *\"Are users clicking through from chatgpt.com / claude.ai / etc.?\"*\\n- *\"My citation rate is fine but there\\'s no traffic — why?\"*\\n\\nGA4 referrals (chatgpt.com → your site) catch click-throughs after they\\nland. Server logs catch the upstream bot activity AND referrals at the\\nedge — including arrivals GA4 missed because of cookie consent, ad\\nblockers, or analytics gaps.\\n\\n## Architecture\\n\\nFour tables store the shared output from every adapter:\\n\\n| Table | What\\'s in it |\\n|---|---|\\n| `crawler_events_hourly` | One row per `(project, source, hour, bot, verification, path, status)` — bot crawls rolled up by hour |\\n| `ai_user_fetch_events_hourly` | One row per `(project, source, hour, bot, verification, path, status)` — user-initiated AI fetches rolled up by hour |\\n| `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 |\\n| `raw_event_samples` | Bounded forensic samples for spot checks. Source writes plus a startup/daily global sweep enforce 30-day retention; Cloudflare also uses a per-source, per-hour cap |\\n\\nEach `traffic_sources` row is one server-log integration for a project.\\nAdapters today:\\n\\n| Adapter | Transport | Source | Best for |\\n|---|---|---|---|\\n| [`cloud-run`](#connecting-a-cloud-run-source) | Pull | GCP Cloud Run request logs via Logging API | Any service running on Cloud Run |\\n| [`wordpress`](#connecting-a-wordpress-source) | Pull | Canonry Traffic Logger REST endpoint | WordPress sites where you control wp-admin |\\n| [`vercel`](#connecting-a-vercel-source) | Pull | Vercel project logs via the Vercel API | Sites deployed on Vercel |\\n| [`cloudflare`](#connecting-a-cloudflare-source) | Direct push or Queue pull | A zone Worker selects edge events; Canonry either receives them directly or pulls them from Cloudflare Queues | Sites whose public traffic passes through Cloudflare |\\n\\nFuture adapters slot in by implementing the same contract.\\nCloud Run, WordPress, Vercel, and Cloudflare Queue sources pull during\\n`traffic sync`. Cloudflare direct push sends selected events from its Worker\\nand does not use `traffic sync`.\\n\\n## Connecting a Cloud Run source\\n\\n```bash\\n# 1. Create a service account in the Cloud project that hosts the Cloud Run\\n# service. Grant it `roles/logging.viewer`. Download the JSON key.\\n\\n# 2. Connect from cnry CLI:\\ncnry traffic connect cloud-run \\\\\\n --gcp-project \\\\\\n --service-account-key \\n\\n# 3. (Optional) narrow to a specific service or location:\\ncnry traffic connect cloud-run \\\\\\n --gcp-project \\\\\\n --service-account-key \\\\\\n --service my-service-name \\\\\\n --location us-east1\\n```\\n\\nCredentials are stored in `~/.canonry/config.yaml` (not the DB). The\\ncanonical key lives only on the host that runs `cnry serve`. The\\nsync flow does NOT echo the private key back in any response.\\n\\n## Connecting a WordPress source\\n\\nThe WordPress adapter pulls events from the **Canonry Traffic Logger**\\nWordPress plugin, which is PHP-only: it captures non-admin GET page-loads\\n**that reach PHP** and exposes a paginated REST endpoint protected by an\\nApplication Password. It has no browser-side capture path.\\n\\n> **Cache blind spot.** Cache-served requests never execute PHP, so they\\n> produce no plugin event. A full-page cache (LiteSpeed, WP Rocket, W3 Total\\n> Cache, WP Super Cache) or any CDN can therefore make the source look active\\n> while real page views, AI crawlers, and live AI user-fetches such as\\n> `Claude-User` and `ChatGPT-User` go uncounted. To use this source for\\n> AI-agent traffic, bypass **every** cache layer for the selected AI user\\n> agents, or capture from access/edge logs instead.\\n\\n**Which user-agents to exclude from the cache** (one per line in\\nLiteSpeed\\'s \"Do Not Cache User Agents\", WP Rocket\\'s\\n`rocket_cache_reject_ua`, or W3TC / WP Super Cache \"Rejected User\\nAgents\"):\\n\\n```\\nGPTBot\\nOAI-SearchBot\\nOAI-AdsBot\\nChatGPT-User\\nopenai-mcp\\nClaudeBot\\nClaude-\\nanthropic-ai\\nPerplexityBot\\nPerplexity-User\\nShapBot\\nShap-User\\nGoogle-Agent\\nGoogle-GeminiNotebook\\nGoogle-NotebookLM\\nGoogle-CloudVertexBot\\nBytespider\\nApplebot\\nmeta-externalagent\\nCCBot\\ncohere-ai\\nDiffbot\\nMistralAI-User\\nMistralAI-Index\\nMistralAI-Training\\nMistralBot\\nDeepSeekBot\\nxAI-Bot\\nGrok-Bot\\nGrokBot\\nYouBot\\nDuckAssistBot\\nAmazonbot\\nAmzn-SearchBot\\nAmzn-User\\n```\\n\\nThis list mirrors Canonry\\'s current classifier: answer-engine user-fetch,\\ncrawl, search, and training agents for which WordPress has no cache-independent\\nmeasurement surface. `ClaudeBot` covers Anthropic\\'s unhyphenated core crawler;\\n`Claude-` is a separate family rule so newly named `Claude-*Bot` variants\\ninherit the bypass. Do NOT add traditional search agents\\n`Googlebot`, `bingbot`, `DuckDuckBot`, `YandexBot`, or `Baiduspider`: caching\\nhelps them crawl efficiently, and the important Google/Bing crawl evidence is\\navailable through their webmaster tools.\\n\\n> **1.1.0 -> 1.1.1 measurement boundary.** Plugin 1.1.0 briefly added a\\n> JavaScript beacon to recover browser/referral page views served from cache.\\n> Plugin 1.1.1 removes it and returns to PHP-only capture. This intentionally\\n> means cache-served browser referrals can again be absent even when GA4\\n> reports sessions; neither version made cache-served crawler requests visible\\n> to PHP. Annotate the upgrade time, do not interpret a trend spanning it as\\n> like-for-like traffic, and purge HTML from both the WordPress cache and every\\n> outer CDN. A temporary `/wp-json/canonry/v1/pv` compatibility route returns\\n> `204` for scripts stranded in old cached HTML, but never records an event.\\n\\n```bash\\n# 1. Install the plugin. Download the latest release zip from the\\n# canonry-traffic-logger plugin\\'s GitHub release (the repo CI workflow\\n# publishes a zip on every plugin-file change), then in wp-admin:\\n# Plugins → Add New → Upload Plugin → upload + activate.\\n\\n# 2. In wp-admin, create an Application Password for the operator user:\\n# Users → Profile → Application Passwords. Copy the generated password.\\n\\n# 3. (Optional) Adjust settings at Settings → Canonry Traffic Logger:\\n# - Retention window: clamps to 7-365 days, default 90.\\n# - \"Behind a proxy or CDN\": enable this when the site sits behind\\n# Cloudflare or another reverse proxy, so the real visitor IP\\n# (needed to verify AI-bot hits) is read from forwarded headers\\n# rather than the proxy\\'s edge address.\\n# The page also shows the current event count and oldest event.\\n\\n# 4. Connect from cnry CLI:\\ncnry traffic connect wordpress \\\\\\n --url https://example.com \\\\\\n --username admin \\\\\\n --app-password \"xxxx xxxx xxxx xxxx xxxx xxxx\"\\n```\\n\\nWhat the events table looks like (mirrors the TS\\n`WordpressTrafficEventPayload`):\\n\\n| Column | Meaning |\\n|---|---|\\n| `observed_at` | ISO 8601 UTC timestamp with millisecond precision |\\n| `method`, `host`, `path`, `query_string` | Split `REQUEST_URI` parts |\\n| `status` | HTTP response status code |\\n| `user_agent`, `referer` | Headers as captured at request time |\\n| `remote_ip` | Client IP address (IPv4 or IPv6), or empty when none was captured |\\n\\nThe plugin auto-prunes events older than the retention window (default\\n90 days) once per day via WP-Cron. Operators who want a different\\nwindow change it in `Settings → Canonry Traffic Logger`.\\n\\n### WordPress incremental-window safety\\n\\nEach incremental WordPress sync uses one fixed half-open `[since, until)`\\nwindow. A fresh source, or an idle source without an explicit\\n`--since-minutes`, starts with a 365-day horizon, matching the plugin\\'s\\nmaximum configurable retention. A site configured for less retention simply\\nreturns its available tail. If the window needs more than one capped drain,\\nCanonry persists both its lower and upper bounds with the continuation cursor\\nand retries that exact interval until the plugin reports it is terminal. It\\nthen advances the normal watermark. Every returned event is validated against\\nthe requested interval; an older or custom extension that ignores `since` or\\n`until` fails closed before any rollup is written. Update that extension to a\\nbounded-window-capable Canonry traffic logger before syncing again.\\n\\nDo not run generic replace-mode backfill for a WordPress source. The plugin\\nprunes retained events and cannot prove that it covers every bucket a replace\\ntransaction would delete, even when no continuation is pending. Canonry\\nrejects that generic path universally. Keep existing rollups intact, use a\\nretention-aware repair, and explicitly declare any unrecoverable portion before\\nreporting a historical trend.\\n\\nAfter upgrading from the former unbounded WordPress sync, a source with an old\\ncontinuation cursor is intentionally rejected rather than guessed at. Keep its\\nschedule paused, record the ambiguous historical span, then use the explicit\\nreset below to start fresh. Reset stops future replay; it does not repair past\\nrollups. Generic WordPress replace-mode backfill remains unavailable until a\\nretention-aware repair can establish coverage.\\n\\nReconnecting with a different WordPress `baseUrl` archives the old source and\\ncreates a fresh one. Its existing rollups and any unrecovered marker remain\\nwith the old lineage rather than mixing with the new endpoint\\'s traffic.\\n\\n## Connecting a Vercel source\\n\\nThe Vercel adapter pulls per-request logs from the Vercel API for a\\nspecific project + environment. Logs are filtered by canonical domain\\nbefore classification so a multi-tenant Vercel project only surfaces\\nhits for the tracked site.\\n\\n```bash\\n# 1. In the Vercel dashboard, create a token with read access to the\\n# target team (Settings → Tokens → Create). Note the team ID\\n# (Settings → General → Team ID) and the Vercel project ID\\n# (Project → Settings → General → Project ID).\\n\\n# 2. Connect from cnry CLI:\\ncnry traffic connect vercel \\\\\\n --project-id prj_xxxxxxxx \\\\\\n --team-id team_xxxxxxxx \\\\\\n --token # or: --token-file \\n\\n# 3. (Optional) scope to a specific environment (default: production):\\ncnry traffic connect vercel \\\\\\n --project-id prj_xxx --team-id team_xxx --token ... \\\\\\n --environment preview\\n```\\n\\nCredentials live in `~/.canonry/config.yaml` under `vercelTraffic:`,\\nmirroring the cloud-run / wordpress blocks. The adapter classifies bot\\ncrawls + AI-referral arrivals into the same `crawler_events_hourly` /\\n`ai_referral_events_hourly` tables — downstream commands\\n(`cnry traffic events / sources / status`) are source-agnostic.\\n\\n### Vercel first-sync window (gotcha)\\n\\nA new Vercel source captures **only going-forward traffic** by default.\\n`cnry traffic connect vercel` seeds `lastSyncedAt = NOW` so the first\\nscheduled sync uses a tight window inside Vercel\\'s ~14-day\\n`request-logs` retention. Without this, the first sync would fall back\\nto a 30-day window, exceed retention, and throw — leaving the source\\npermanently stuck.\\n\\nRun `cnry traffic backfill --source --days N` (capped at\\n~14 to stay inside retention) if you need any of the pre-connect\\nhistory. It\\'s an explicit operator action; the connect flow never pulls\\nit implicitly.\\n\\n## Connecting a Cloudflare source\\n\\nBoth Cloudflare modes run the same small ES-module Worker on the site\\'s exact\\nzone route. It applies a broad AI filter and delivers selected edge events in\\n`ctx.waitUntil()`. The origin response remains independent from filtering,\\nscheduling, and delivery errors. Both modes use the same\\n`CloudflareEdgeEventBatch`, normalizer, classifier, receipts, and rollups.\\n\\n- `direct-push` sends a signed batch to a public Canonry HTTPS receiver.\\n- `queue-pull` sends the batch to a Cloudflare Queue. The single-team Canonry\\n server pulls and acknowledges it through the Cloudflare Queues HTTP API.\\n\\nThe adapter does not pull Cloudflare analytics or request logs.\\n\\n```mermaid\\nflowchart LR\\n request[\"Site request\"] --> worker[\"Canonry Cloudflare Worker\"]\\n worker --> origin[\"Existing origin or Pages site\"]\\n origin --> response[\"Unchanged site response\"]\\n worker -. \"direct-push\" .-> ingest[\"Canonry public HTTPS ingest\"]\\n worker -. \"queue-pull\" .-> queue[\"Cloudflare Queue\"]\\n queue --> pull[\"Canonry scheduled pull\"]\\n ingest --> classify[\"Shared receipt and traffic pipeline\"]\\n pull --> classify\\n classify --> rollups[\"Hourly crawler, user-fetch, and referral rollups\"]\\n```\\n\\n### Setup flow\\n\\n1. Create or select a Canonry project with one exact canonical hostname.\\n2. Choose delivery: direct push needs a stable public Canonry HTTPS URL outside\\n the site route; Queue pull needs a pre-created Queue and HTTP pull consumer.\\n3. Authenticate Wrangler with the Cloudflare account that owns the zone.\\n4. Inspect existing Worker routes for the exact canonical hostname.\\n5. **Size the request volume** (see below) and decide whether an\\n asset-exclusion route is needed.\\n6. Run the local Cloudflare connect command with `--deploy`.\\n7. Attach the printed route in Cloudflare and set it to **Fail open** — it\\n defaults to OFF.\\n8. Attach the asset-exclusion route if step 5 called for one.\\n9. Activate the source and set a `traffic-sync` schedule. Connect syncs once\\n and does not schedule; use `*/15 * * * *`, not daily, so a failed sync can\\n still recover inside the queue\\'s retention window.\\n10. Send the smoke requests and run the Canonry doctor.\\n\\nA full operator walkthrough with copy-paste commands lives in\\n`docs/cloudflare-traffic-setup.md`.\\n\\n### Current support boundary\\n\\nBoth modes currently target one local, single-team `canonry serve` instance.\\nThe Queue consumer is not a multi-tenant Cloudflare control plane. The CLI and\\nserver must read the same `~/.canonry/config.yaml` credential store. Direct\\npush requires a stable public HTTPS receiver; Queue pull does not.\\n\\nThe Cloud Run `apps/api` service has no Cloudflare credential store.\\nTherefore, `apps/api` cannot retain direct-push bearer/HMAC values or the\\nQueue API token.\\n\\nCAUTION: Use one authoritative server-traffic source for the canonical site.\\nConnecting any adapter while a sibling source is active creates or keeps a\\npaused staged source. `canonry traffic activate` validates the target\\'s local\\ncredential, atomically pauses every sibling, and moves or removes the one\\ntraffic-sync schedule. Overlapping adapters outside this cutover can still\\ndouble-count project totals.\\n\\n### Expose the Canonry receiver (direct push only)\\n\\nComplete the local dashboard setup and set its password before you expose\\nCanonry. A tunnel makes the loopback server reachable from the public Internet.\\n\\nUse a named Cloudflare Tunnel or another stable reverse proxy:\\n\\n```text\\nhttps://canonry-ops.example.net\\n -> stable tunnel or reverse proxy\\n -> http://127.0.0.1:4100\\n```\\n\\nThen complete these steps:\\n\\n1. Back up `~/.canonry/config.yaml`.\\n2. Set `publicUrl` to the external Canonry URL.\\n3. If Canonry uses a base path, include that path in `publicUrl`.\\n4. Restart `canonry serve`.\\n5. Send an unsigned request to the ingest path from the public Internet.\\n6. Make sure that the response status is `401`.\\n\\n```yaml\\npublicUrl: https://canonry-ops.example.net\\n```\\n\\n```bash\\nCANONRY_PUBLIC_URL=https://canonry-ops.example.net\\n\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' \\\\\\n -X POST -H \\'content-type: application/json\\' --data \\'{}\\' \\\\\\n \"${CANONRY_PUBLIC_URL%/}/api/v1/projects//traffic/cloudflare/ingest\"\\n```\\n\\nThe `401` response proves that the request reached Canonry\\'s transport\\nauthentication. A `403` can mean that Cloudflare Access or a WAF rule blocked\\nthe request first. Exempt only the exact ingest path from interactive\\nchallenges. Keep the rest of Canonry behind its normal access controls.\\n\\nDo not use a random TryCloudflare URL for production. The Worker stores the\\ningest URL at deployment time. If a temporary URL changes, rerun connect and\\nredeploy the Worker.\\n\\nThe public URL is the Canonry receiver, not the tracked site. Use a different\\nhostname from the generated Worker route. Do not add credentials, a query, or\\na fragment to this URL.\\n\\n### Prerequisites and route preflight\\n\\n1. Install a current Wrangler release.\\n2. Run `wrangler login`.\\n If Wrangler lists multiple accounts, pass the exact `--account-id`.\\n3. Run `wrangler whoami` to get the account ID.\\n4. Get the zone ID from the Cloudflare zone Overview page.\\n5. Make sure that the zone belongs to the selected account.\\n6. Make sure that Cloudflare proxies the canonical hostname in DNS.\\n7. Inspect every Worker route that overlaps the canonical hostname. Cloudflare\\n uses the most-specific matching route. Record any excluded path coverage.\\n8. Make sure that `/*` is unclaimed. If a more-specific route\\n must remain, integrate Canonry there or accept that those paths are absent.\\n9. If another Worker owns the catch-all route, stop. Integrate Canonry into that\\n Worker instead of attaching a second Worker.\\n10. Review the account request volume. A route invokes the Worker for every\\n matching request. The filter does not reduce Worker invocations.\\n\\n### Sizing the route before you attach it\\n\\n\"Review the account request volume\" is not a judgement call. Compute it:\\n\\n```\\nsessions/day x pageviews/session x SAME-ORIGIN requests/pageview\\n```\\n\\nOnly same-origin requests count. Assets on a third-party CDN never reach the\\nzone and never invoke the Worker. Count them on one real page:\\n\\n```bash\\ncurl -s https:/// \\\\\\n | grep -oE \\'(src|href)=\"/[^\"]+\\\\.(js|css|woff2?|png|jpg|svg)\"\\' | wc -l\\n```\\n\\nA JavaScript app will exceed the Workers Free allowance (100,000 requests/day,\\naccount-wide) by a wide margin, because the HTML is one request and the bundle\\nis dozens. Measured on a Nuxt storefront: 7,238 sessions/day and 27 same-origin\\n`/_nuxt/*` assets per page projected 200k-400k/day, and the deployed Worker\\nlogged 958 invocations in 4 minutes (~345k/day). Images were on\\n`cdn.shopify.com` and cost nothing.\\n\\nAttach an asset-exclusion route unless the site is server-rendered with few\\nsame-origin assets, or the account is on Workers Paid.\\n\\n### Excluding static assets from the route\\n\\nA route with NO script disables Workers on that path, and Cloudflare applies\\nthe most specific match. This removes the bundle without losing any crawler\\nevidence, because crawlers request pages, not JS chunks.\\n\\n```bash\\n# assets -> no worker. Omitting \"script\" is what disables it.\\ncurl -s -X POST -H \"Authorization: Bearer $CF_TOKEN\" -H \"Content-Type: application/json\" \\\\\\n --data \\'{\"pattern\":\"/_nuxt/*\"}\\' \\\\\\n \"https://api.cloudflare.com/client/v4/zones/$ZONE/workers/routes\"\\n```\\n\\nPrefixes by framework: `/_nuxt/*` Nuxt, `/_next/*` Next.js, plus `/assets/*`,\\n`/static/*`, `/build/*`.\\n\\n**The Worker\\'s own \"Domains and Routes\" tab cannot do this.** That screen only\\nattaches routes TO that Worker, so adding the asset path there routes assets\\nINTO the Worker and doubles the load. Asset exclusion is zone-level: the zone\\'s\\nWorkers Routes page, or the API above.\\n\\n### Fail open defaults to OFF\\n\\n`request_limit_fail_open` is per route and defaults to `false`. Left off, a\\nWorker error or an exhausted request allowance returns 5xx for every request on\\nthat route, which on a catch-all is the whole site. Setting it is not optional\\nand it is not the default, so verify rather than assume:\\n\\n```bash\\ncurl -s -H \"Authorization: Bearer $CF_TOKEN\" \\\\\\n \"https://api.cloudflare.com/client/v4/zones/$ZONE/workers/routes\" \\\\\\n | jq \\'.result[] | {pattern, script, request_limit_fail_open}\\'\\n```\\n\\nBoth route operations need `Zone | Workers Routes | Edit` on the token.\\n\\n```bash\\nnpm install -g wrangler@latest\\nwrangler login\\nwrangler whoami\\n```\\n\\nCanonry does not pass a `--profile` option to Wrangler. Wrangler uses the auth\\nprofile that is active for the current directory, or its default profile. If\\nyou use named profiles, activate one before you run Canonry:\\n\\n```bash\\nwrangler auth list\\nwrangler auth activate .\\nwrangler whoami --json\\n```\\n\\nThe project must already exist. Use a bare public hostname such as\\n`www.example.com` for its canonical domain. `--zone-id` is mandatory with\\n`--deploy`. You can omit `--account-id` when the active profile has one account.\\n\\nThe generated route covers only the project\\'s exact canonical hostname. It\\ndoes not also cover `www` or the apex. Test and redirect the other hostname\\nseparately.\\n\\nA Worker Route can run in front of a Cloudflare Pages custom domain. If the\\norigin is another Worker, use a Custom Domain or integrate Canonry into that\\nWorker. A same-zone Worker Route cannot be the target of `fetch()`.\\n\\nWorkers Free includes 100,000 requests per account each day. The quota\\nresets at midnight UTC. A fail-closed route returns Cloudflare error 1027\\nafter the account exhausts this quota. A fail-open route bypasses the\\nWorker and keeps the origin available. See [Cloudflare Workers limits](https://developers.cloudflare.com/workers/platform/limits/).\\n\\nFree-plan classification uses user-agent, referer, and UTM evidence. Granular\\n`request.cf.botManagement` scores require the Enterprise Bot Management add-on.\\n\\n### Generate or deploy direct push\\n\\n```bash\\n# Generate secret-free worker.js and wrangler.toml in\\n# ./canonry-cloudflare-:\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode direct-push \\\\\\n --zone-id \\\\\\n --account-id \\n\\n# Deploy only the Worker after the route preflight.\\n# Both safety acknowledgements are mandatory:\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode direct-push \\\\\\n --zone-id \\\\\\n --account-id \\\\\\n --deploy --confirm-route --confirm-fail-open\\n\\n# Optional artifact directory / source label:\\ncnry traffic connect cloudflare \\\\\\n --display-name \"Cloudflare · production\" \\\\\\n --output-dir ./infra/canonry-cloudflare\\n```\\n\\n`--confirm-route` acknowledges that you inspected the exact route.\\n`--confirm-fail-open` acknowledges that you will configure the required route\\ntoggle. Canonry does not persist these flags. Neither flag changes Cloudflare.\\n\\nThe command prints the source ID, artifact directory, and manual route steps.\\nKeep the source ID for the acceptance test and later diagnosis.\\n\\nWith `--deploy`, Canonry checks Wrangler before it connects the source. The\\npreflight uses `--dry-run --secrets-file ... --strict` to parse and bundle\\nrepresentative generated artifacts. An incompatible Wrangler stops this step\\nbefore Canonry changes state. The generated `[secrets].required` table is an\\n[official Wrangler safety check](https://developers.cloudflare.com/changelog/post/2026-03-24-secrets-config-property/);\\nit does not contain secret values.\\n\\nThe generated TOML never declares `[[routes]]`. Thus, Wrangler deploys the\\nWorker without placing it on production traffic. After deployment, open\\nCloudflare Dashboard and complete these steps:\\n\\n1. Open **Workers & Pages → Overview** and select the generated Worker.\\n2. Open **Settings → Domains & Routes → Add → Route**.\\n3. Select the zone and enter the exact `/*` route.\\n4. Set **Request limit failure mode** to **Fail open**.\\n5. Add the route.\\n\\nWrangler cannot configure the failure-mode toggle.\\n\\nThe generated source and TOML contain no credential values. Non-secret\\nconfiguration values are Worker vars. The `--account-id` option makes\\nconnect write `account_id` at the top level.\\n\\nThe bearer and HMAC values stay in the local Canonry credential store.\\nThey become `CANONRY_BEARER_TOKEN` and `CANONRY_HMAC_SECRET` Worker\\nsecrets. With `--deploy`, the CLI uses a mode-0600 temporary secrets file.\\nThen it invokes Wrangler with `--secrets-file ... --strict` and removes\\nthe file.\\n\\nRerun the same connect command to update an old generated Worker. Canonry\\natomically replaces recognizable Canonry-generated files. It refuses\\noperator-owned files and symlinks. Therefore, doctor remediation does not\\nrequire manual file deletion.\\n\\nWrangler preflight failures occur before Canonry creates a source. Artifact or\\ndeployment failures can occur after source creation. Rerun the same command\\nwith the same output directory. Canonry reuses the source and its credentials.\\n\\nCloudflare connect is absent from MCP because deployment reads local\\nsecrets. An agent can guide the CLI command. It must not request, print,\\nor send either secret through chat.\\n\\n### Generate or deploy Queue pull\\n\\nQueue pull reuses the same edge filter without requiring a public Canonry\\nreceiver. Create the Queue first. Then use `wrangler queues info` to get its ID.\\nCreate a Cloudflare API token with **Account Queues Edit** for the owning\\naccount. Put only the token in a mode-0600 file. Keep that file off shell argv.\\n\\n```bash\\nwrangler queues create canonry-traffic-\\n\\n# Workers Paid only: use this command to change the four-day default.\\nwrangler queues update canonry-traffic- \\\\\\n --message-retention-period-secs \\n\\nwrangler queues info canonry-traffic-\\nwrangler queues consumer http add canonry-traffic-\\n\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode queue-pull \\\\\\n --zone-id \\\\\\n --account-id \\\\\\n --queue-id \\\\\\n --queue-name canonry-traffic- \\\\\\n --api-token-file \\\\\\n --retention-seconds \\n\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode queue-pull \\\\\\n --zone-id \\\\\\n --account-id \\\\\\n --queue-id \\\\\\n --queue-name canonry-traffic- \\\\\\n --api-token-file \\\\\\n --retention-seconds \\\\\\n --deploy --confirm-route --confirm-fail-open\\n```\\n\\nRead the Queue ID from the `wrangler queues info` output. Pass that exact value\\nto `--queue-id`.\\n\\nThe `queues update` command sets Cloudflare retention on Workers Paid. The\\nCanonry `--retention-seconds` option only records the actual value. It does not\\nchange the Queue. Use `86400` for Workers Free, where retention is fixed at one\\nday. Workers Paid defaults to `345600` (four days). Paid accounts accept values\\nfrom 60 seconds through 14 days. If you change the paid Queue, use the same\\nvalue in both commands. See Cloudflare\\'s [Queue limits](https://developers.cloudflare.com/queues/platform/limits/).\\n\\nThe HTTP-consumer command is required. The producer binding does not enable\\nHTTP pull. Cloudflare does not support an HTTP pull consumer in\\n`wrangler.toml`. Remove any existing Worker consumer before you enable HTTP\\npull. One Queue cannot use both consumer types at the same time. See\\nCloudflare\\'s [pull-consumer setup](https://developers.cloudflare.com/queues/configuration/pull-consumers/).\\n\\nThe token stays only in Canonry\\'s local credential store. It is not written to\\nthe source row, Worker, TOML, command output, MCP, or Worker bindings. Wrangler\\nauthentication remains the operator\\'s active Wrangler profile. Canonry does\\nnot reuse the Queue pull token for deployment.\\n\\nThe generated TOML contains one `[[queues.producers]]` binding named\\n`CANONRY_TRAFFIC_QUEUE` and no direct-push ingest URL or Worker secrets. After\\nthe Worker is deployed and the route is ready, activate a staged source:\\n\\n```bash\\ncnry traffic activate --source \\ncnry traffic sync --source \\n```\\n\\nA new project with no other active traffic source activates immediately. A\\nmode change stays paused until the explicit activation command. Activation\\npauses the prior source and points the project\\'s one `traffic-sync` schedule at\\nQueue pull; activating direct push removes that Queue schedule.\\n\\nFor Queue-to-direct rollback, drain Queue pull until its backlog is empty,\\nswitch the Cloudflare route, then activate direct push immediately. The route\\nchange and Canonry activation are separate operator actions, so keep the\\ncutover window short.\\n\\n### Queue-pull acceptance test\\n\\nUse this test after the Queue-pull source is active and the Worker route is\\nattached. The UTM request provides a deterministic classification signal.\\nIf connect reports `activationRequired`, activate the source before this test:\\n\\n```bash\\ncnry traffic activate --source \\n```\\n\\n```bash\\nCANONRY_QUEUE_SMOKE_PATH=\"/canonry-cloudflare-queue-smoke/$(date -u +%Y%m%dT%H%M%SZ)\"\\n\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' \\\\\\n \"https://www.example.com${CANONRY_QUEUE_SMOKE_PATH}?utm_source=chatgpt\"\\n\\nsleep 2\\ncnry traffic sync --source \\ncnry traffic events --source \\\\\\n --kind all --since-minutes 120 --limit 5000 --format json\\ncnry traffic status --format json\\ncnry doctor --project --check \\'traffic.source.*\\' --format json\\n```\\n\\nThe manual sync must complete. The events output must contain the unique smoke\\npath as an AI referral. The status output shows `queueBacklogCount` and\\n`queueBacklogObservedAt`. The doctor must not report a credential failure. If\\nthe path is absent, wait two seconds and repeat the sync up to ten times.\\n\\n### Direct-push behavior and smoke test\\n\\nThe Worker forwards a request candidate when at least one condition is true:\\n\\n- Its user-agent matches a known AI crawler or user-fetch agent.\\n- Its user-agent contains the broad `bot`, `crawler`, or `spider` keyword.\\n- Its referer or `utm_source` matches a known AI product.\\n- Bot Management marks it as verified or gives it a score below 30.\\n\\nThe shared Canonry classifier makes the strict classification after delivery.\\nThus, the broad edge filter can send a candidate that produces no rollup.\\n\\nDirect push observes only requests that reach this Worker. A terminating\\nAccess, WAF, bot-protection, or AI Crawl Control action can stop a request first.\\nFor a crawler smoke test, use a narrow exception for only the smoke path when\\nthe site\\'s security policy permits it. Do not disable site-wide protection.\\n\\nDirect push has bounded retries for network failures and HTTP 408, 425,\\n429, and 5xx responses (250 ms, then 1 s). Delivery is asynchronous and\\nnever changes the site\\'s response. If Canonry remains unavailable after\\nthe retry budget, the selected event is lost. Direct push has no durable\\nedge buffer. Use Queue pull when delivery needs a durable edge buffer.\\n\\nThe receiver accepts at most 256 KiB per request. Its default budgets are\\n6,000 requests per minute for each source and each caller IP. A bearer token\\nand HMAC protect the route. The HMAC timestamp window is five minutes. A\\ntransactional receipt protects each event ID for ten minutes. Receipt claims,\\nhourly rollups, samples, and source progress commit in one transaction.\\n\\nDirect push sends one selected event per batch. It does not batch or sample at\\nthe edge. Canonry stores at most 100 raw samples per source per UTC hour, while\\nit continues to add all classified events to hourly rollups.\\n\\nThe Worker transports the raw client IP, full query string, and full referer\\nURL for classification. Canonry does not persist these raw values. Raw samples\\nstore `ipHash: null`, a normalized path without its query, and only the referer\\nhost. A later privacy change can send only the query parameters that the\\nclassifier requires.\\n\\nRaw samples retain the user-agent and normalized path. Do not put personal\\ndata in URL paths. Canonry replaces numeric, UUID, and long hexadecimal path\\nsegments with `:id`, but it retains other path segments.\\n\\n### Direct-push acceptance test\\n\\n1. Choose a stable, harmless origin path and create a unique smoke-run name.\\n2. Before route attachment, capture the origin response and source rollups.\\n3. Attach the exact route with **Fail open**.\\n4. Capture the origin response again. Compare its body and critical headers.\\n5. Send four classified requests and one negative control.\\n6. Poll the source rollups, inspect the unique paths, and run the doctor.\\n\\nReplace the example hostname, ``, and `` before you run\\nthese commands:\\n\\n```bash\\nCANONRY_SMOKE_SITE=https://www.example.com\\nCANONRY_SMOKE_RUN=run-$(date -u +%Y%m%dT%H%M%SZ)\\nCANONRY_SMOKE_PREFIX=/canonry-cloudflare-smoke/$CANONRY_SMOKE_RUN\\nCANONRY_SMOKE_DIR=$(mktemp -d)\\n\\n# Run these commands before route attachment.\\ncurl -sS -D \"$CANONRY_SMOKE_DIR/origin-before.headers\" \\\\\\n -o \"$CANONRY_SMOKE_DIR/origin-before.body\" \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/origin\"\\ncnry traffic events --source \\\\\\n --kind all --since-minutes 120 --limit 5000 --format json \\\\\\n > \"$CANONRY_SMOKE_DIR/events-before.json\"\\n\\n# Stop here. Attach the exact route with Fail open, then continue.\\ncurl -sS -D \"$CANONRY_SMOKE_DIR/origin-after.headers\" \\\\\\n -o \"$CANONRY_SMOKE_DIR/origin-after.body\" \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/origin\"\\ngrep -Ei \\'^(HTTP/|content-type:|cache-control:|location:)\\' \\\\\\n \"$CANONRY_SMOKE_DIR/origin-before.headers\" \\\\\\n \"$CANONRY_SMOKE_DIR/origin-after.headers\"\\ncmp \"$CANONRY_SMOKE_DIR/origin-before.body\" \\\\\\n \"$CANONRY_SMOKE_DIR/origin-after.body\"\\n\\n# AI crawler\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' -A \\'GPTBot/1.2\\' \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/crawler\"\\n\\n# AI user fetch\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' -A \\'ChatGPT-User/1.0\\' \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/user-fetch\"\\n\\n# AI referral by referer\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' -A \\'Mozilla/5.0 CanonrySmoke\\' \\\\\\n -e \\'https://chatgpt.com/\\' \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/referral\"\\n\\n# AI referral by UTM\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' -A \\'Mozilla/5.0 CanonrySmoke\\' \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/utm?utm_source=chatgpt\"\\n\\n# Negative control: this request must not add a classified traffic rollup\\ncurl -sS -o /dev/null -w \\'%{http_code}\\\\n\\' -A \\'Mozilla/5.0 CanonrySmoke\\' \\\\\\n \"$CANONRY_SMOKE_SITE$CANONRY_SMOKE_PREFIX/control\"\\n\\n# Poll until the deterministic UTM event arrives, for at most 20 seconds.\\nfor CANONRY_SMOKE_ATTEMPT in 1 2 3 4 5 6 7 8 9 10; do\\n cnry traffic events --source \\\\\\n --kind all --since-minutes 120 --limit 5000 --format json \\\\\\n > \"$CANONRY_SMOKE_DIR/events-after.json\"\\n grep -Fq \"$CANONRY_SMOKE_PREFIX/utm\" \\\\\\n \"$CANONRY_SMOKE_DIR/events-after.json\" && break\\n sleep 2\\ndone\\n\\ncat \"$CANONRY_SMOKE_DIR/events-before.json\"\\ncat \"$CANONRY_SMOKE_DIR/events-after.json\"\\n\\nif grep -Fq \"$CANONRY_SMOKE_PREFIX/control\" \\\\\\n \"$CANONRY_SMOKE_DIR/events-after.json\"; then\\n echo \\'Unexpected classified control rollup\\'\\nelse\\n echo \\'Negative control passed\\'\\nfi\\n\\ncnry doctor --project --check \\'traffic.source.*\\' --format json\\n```\\n\\nThe smoke paths can return `404`. The body and critical headers must match the\\nno-Worker baseline. When all four selected requests reach the Worker, the\\nunique paths must show one crawler, one AI user fetch, and two AI referrals.\\nThe control path must not appear in a classified rollup. On Bot Management\\nplans, a low bot score can still cause its transport.\\n\\nThe crawler request uses a spoofed user agent. It tests forwarding and\\nclassification only. Canonry reports it as `claimed_unverified` unless the\\nclient IP belongs to the bot\\'s published IP ranges. If only the crawler path is\\nabsent, inspect AI Crawl Control, Access, WAF, and other terminating rules. The\\nUTM request is the deterministic direct-push transport check.\\n\\nThe events command returns hourly rollups, not raw request records. The doctor\\nmust report current Worker version and recent traffic.\\n\\n### Staging release test\\n\\n1. Cause a receiver failure. Make sure that the origin stays healthy.\\n2. Return HTTP `429` from staging and send a bounded bot burst.\\n3. Make sure that delivery stops after one request and two retries.\\n4. Compare p50 and p95 TTFB before and after route attachment.\\n5. Inspect Worker logs. Make sure that logs contain no secret values.\\n6. Rehearse rollback and make sure that the origin stays healthy.\\n\\nA direct-push source does not use `cnry traffic sync` or a traffic-sync\\nschedule.\\n\\n### Rollback and teardown\\n\\nFor a dedicated Canonry-generated Worker:\\n\\n1. Detach the exact site route from the Worker.\\n2. Request an ordinary site page. Make sure that the origin status,\\n headers, and body remain healthy.\\n3. If this source uses Queue pull, run manual syncs until its backlog is zero.\\n4. If a replacement source exists, activate it after the Queue is empty.\\n5. If no replacement source exists, run\\n `cnry schedule remove --kind traffic-sync`.\\n6. If this source uses Queue pull, run\\n `wrangler queues consumer http remove `.\\n7. Run `wrangler delete --config /wrangler.toml`.\\n8. If this source uses direct push, stop its unused tunnel.\\n9. Run the doctor. Expect source-health warnings until Canonry supports\\n Cloudflare disconnect.\\n\\nCAUTION: If no other producer uses the Queue, delete it only after the drain:\\n\\n```bash\\nwrangler queues delete \\n```\\n\\nIf the API token is dedicated to Canonry, revoke it after you remove the HTTP\\nconsumer.\\n\\nIf Canonry code shares an existing Worker, remove only the Canonry code and\\nbindings. Redeploy the prior Worker version. Do not delete the shared Worker.\\n\\nThe current CLI and API have no Cloudflare disconnect operation. The source\\nrow and local credential store remain after teardown. A follow-up must add\\nsource archival and local credential cleanup.\\n\\n### Cloudflare troubleshooting\\n\\n| Symptom | Action |\\n|---|---|\\n| Wrangler preflight fails | Install the latest Wrangler. Run `wrangler whoami`. Then rerun connect. |\\n| Worker deploys to the wrong account | Make the correct Wrangler profile active. Pass the matching `--account-id`. |\\n| Route cannot attach | Make sure that the zone is active, DNS is proxied, and the exact route is unclaimed. Inspect every overlapping route. |\\n| Direct-push receiver returns `403` | Remove the Access or WAF challenge from the exact ingest path. |\\n| Direct-push Worker log shows ingest `401` | Rerun connect from the credential-owning host. Make sure that system clocks differ by less than five minutes. |\\n| No direct-push events arrive | Make sure that the route matches the exact host. Make sure that `publicUrl` is reachable. Inspect AI Crawl Control, Access, WAF, and route precedence. Then send the UTM smoke request. |\\n| No Queue-pull events arrive | Run `wrangler queues info ` and `wrangler queues consumer http list `. Make sure that the producer binding uses that Queue. Make sure that the account ID, Queue ID, and token scope match. Then run the Queue acceptance test. |\\n| Queue pull returns `403` | Create a token with **Account Queues Edit** for the Queue account. Reconnect with the token file. |\\n| Queue backlog remains above 1,000 | Run a manual sync. If the backlog grows again, shorten the 30-minute schedule interval. |\\n| Some paths are absent | Inspect more-specific routes and terminating security rules. Integrate Canonry into those routes or document the excluded coverage. |\\n| Direct-push ingest returns `429` | Wait for the rate window. The Worker retries twice, then drops the event. |\\n| Site returns Cloudflare error `1027` | Set the route to **Fail open**, or detach it. The account exhausted its daily Worker requests. |\\n| 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. |\\n\\n### Queue pull delivery guarantees\\n\\nQueue delivery is at least once. Canonry claims a durable source-scoped sync\\nlease, short-polls bounded batches, validates the transport-neutral event\\nschema and canonical host, and commits event receipts plus rollups in one DB\\ntransaction. It acknowledges the Cloudflare lease only after that commit.\\n\\nIf acknowledgement fails after commit, Cloudflare can redeliver the batch.\\nThe durable receipt makes the redelivery a no-op before Canonry acknowledges it\\nagain. Unsupported V8 messages and malformed message bodies are acknowledged\\nas poison after their safe lease metadata is read; raw bodies and the API token\\nnever enter errors or logs. A process crash leaves unacknowledged messages for\\nCloudflare to redeliver after the visibility timeout.\\n\\nThe source lease rejects concurrent scheduler and operator drains. A stale\\nlease can be recovered after its expiry, and only its owner can release it.\\nReceipts remain for Cloudflare\\'s current 14-day platform maximum plus a replay\\nmargin. This stays safe even when the locally recorded retention is stale or\\nlower than the Queue\\'s actual setting.\\n\\nEach default Queue sync drains at most 10 batches of 100 messages: **1,000\\nmessages per tick**. Doctor reports a residual of 1–1,000 messages as within\\nthat budget. If no new messages arrive, the next scheduled sync can clear it.\\nDoctor warns when more than 1,000 messages remain because one default tick\\ncannot drain the residual. Run a manual sync to accelerate the drain. If the\\nbacklog remains above 1,000, shorten the `traffic-sync` schedule interval.\\n\\n## Syncing data\\n\\n```bash\\n# Manual sync — pulls [lastSyncedAt, now]. For a freshly connected\\n# source the window is short (since connect-time NOW). For a\\n# regular-cadence schedule the window stays ~30 min wide.\\ncnry traffic sync --source \\n\\n# Override the lookback window (minutes) — note: clamped forward to\\n# lastSyncedAt, so this can only NARROW the window, never widen it\\n# past data already pulled.\\ncnry traffic sync --source --since-minutes 4320 # 3 days\\n```\\n\\nCloudflare Queue pull is cursorless and ignores `--since-minutes`; each call\\ndrains a bounded set of leased Queue messages. Repeat the command when you need\\nto accelerate a backlog, or let the auto-created 30-minute schedule continue\\ndraining. Direct push still rejects `traffic sync` because it has no pull\\ntransport.\\n\\n### Unsticking a stuck source\\n\\nIf a Vercel (or Cloud Run) source has been failing for so long that\\n`lastSyncedAt` aged past the upstream retention boundary, every sync\\nwill throw a retention error and `lastSyncedAt` will never advance —\\nthe source is permanently stuck. Recovery:\\n\\n```bash\\n# Advances lastSyncedAt to NOW, clears the error state. Skipped\\n# history is unrecoverable from the sync path; run backfill separately\\n# if any of it needs to be captured.\\ncnry traffic reset --source --advance-to-now\\n```\\n\\n`--advance-to-now` is required — there is no implicit reset.\\n\\n`reset` accepts any **non-archived** source type. A WordPress reset clears\\nits `last_cursor` and pending-window marker as well as advancing\\n`lastSyncedAt`, so the next bounded drain begins at the reset watermark\\ninstead of combining it with an old cursor. The primary use case is the\\nretention-trap recovery above; clearing `lastError` for a transient WordPress\\nfailure also works. Reset deliberately abandons any ambiguous pending history;\\nit is not a historical repair. Archived sources are rejected — re-connect them\\nwith `cnry traffic connect ...` instead.\\n\\nTime-window and cursor adapters use the `last_event_ids` overlap ring. Queue\\npull uses durable event receipts sized to Queue retention. Both paths make a\\nrepeated pull safe to schedule or trigger from CI.\\n\\n## Inspecting source state\\n\\n```bash\\n# All sources with last-24h totals + latest sync run (single-call):\\ncnry traffic status --format json\\n\\n# Just the source list:\\ncnry traffic sources --format json\\n\\n# Windowed events (defaults to last 24h):\\ncnry traffic events --kind crawler --limit 200 --format json\\ncnry traffic events --kind ai-referral --since 2026-04-01 --until 2026-04-30\\n```\\n\\nThe `traffic status` composite returns the same per-source detail\\n(24h crawler hits, AI-referral arrivals, raw-event-sample count, latest\\nsync-run summary) whether you reach it via the CLI, the API, or the\\nMCP `canonry_traffic_status` tool.\\n\\n**Crawler hits are segmented by path class (#719).** On real sites the raw\\n`crawlerHits` total is dominated by infrastructure polling — a bot re-fetching\\n`sitemap_index.xml`, `robots.txt`, and static assets — which overstates how\\nmuch of your *content* is being crawled. `traffic status` and `traffic events`\\ntherefore return, alongside the unchanged `crawlerHits` total:\\n\\n- `crawlerContentHits` — crawls of actual content/document pages (the signal you\\n usually want: \"are bots reading my pages?\").\\n- `crawlerInfraHits` — sitemap + robots + asset fetches.\\n- `crawlerSegments` — the full `{ content, sitemap, robots, asset, other }`\\n breakdown; the five buckets sum to `crawlerHits`, and\\n `content + infra + other == crawlerHits`. `other` captures non-page downloads\\n and feeds (PDF, CSV, RSS) plus WordPress polling endpoints that are not page\\n reads (`/feed`, `//feed`, `/wp-json/...`, `xmlrpc.php`, `wp-cron.php`), so\\n they stay out of `crawlerContentHits`.\\n\\nEach crawler row from `traffic events` also carries a `pathClass`\\n(`content | sitemap | robots | asset | other`). The dashboard leads with the\\ncontent figure and shows infrastructure polling as a secondary number. The\\nclassification is read-time only (the pure `classifyTrafficPath` helper) — no\\nschema change, the stored rollups are untouched.\\n\\n## Where the data shows up\\n\\n| Surface | What\\'s rendered |\\n|---|---|\\n| Project dashboard `/projects/:name/activity` | Live source table + 24h totals + GA4 referrals (combined view) |\\n| Top-level `/traffic` route | Cross-project source admin (connect, sync, archive) |\\n| `cnry report ` (HTML + SPA) | \"AI Visibility — Server-Side\" section, ranked above Indexing Health |\\n| `cnry doctor --project ` | Source health checks, including last-observed Worker drift for direct and Queue sources plus Queue local credential/sync state |\\n| 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. |\\n\\n## Doctor signals\\n\\nThe doctor checks are adapter-agnostic. When they fail or warn:\\n\\n| Check | Code | What to do |\\n|---|---|---|\\n| `traffic.source.connected` | `traffic.source.none` | No source — `cnry traffic connect cloud-run …` |\\n| `traffic.source.connected` | `traffic.source.all-errored` | Re-connect the source. The check\\'s `details.lastError` shows the underlying reason. |\\n| `traffic.source.recent-data` | `traffic.recent-data.stale` | For pull sources, run `cnry traffic sync …`. For Cloudflare direct push, inspect the route and receiver. |\\n| `traffic.source.recent-data` | `traffic.recent-data.empty` | Inspect source configuration. For Cloudflare direct push, send the UTM smoke request and inspect Worker logs. |\\n| `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. |\\n| `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. |\\n| `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. |\\n| `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. |\\n| `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. |\\n| `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. |\\n\\nCloudflare doctor behavior is capability-driven: only\\n`deliveryMode=direct-push` (and legacy Cloudflare rows with no mode) skips\\npull-watermark lag. Both direct and Queue modes enable\\n`traffic.source.worker-version`. That check compares the shared current\\ngenerated version with `lastWorkerVersion`, the version on the most recently\\ningested batch. It is last-observed evidence, not proof that every deployment\\nor queued message runs that version. Queue pull also keeps its pull-lag checks.\\n\\n## Scheduling\\n\\n`cnry schedule` supports `--kind traffic-sync` for pull sources. Activation of\\nQueue, Cloud Run, WordPress, or Vercel creates or repoints this schedule at a\\n30-minute cadence.\\nCloudflare direct push is event-driven and must not receive a traffic-sync\\nschedule. Recurring syncs are safe because of the adapter\\'s overlap ring or\\ndurable Queue receipts.\\n\\nKeep the auto-created 30-minute schedule for Queue pull. The Worker sends one\\nselected event in each Queue message. At its 1,000-message limit, this cadence\\ndrains about 0.56 selected events per second. If the Queue backlog remains\\nabove 1,000, run a manual sync. Then shorten the interval:\\n\\n```bash\\ncnry schedule set --kind traffic-sync \\\\\\n --source --cron \"*/10 * * * *\"\\n```\\n\\nUse these cadences only for Cloud Run, WordPress, and Vercel:\\n\\n| Cadence | Use case |\\n|---|---|\\n| `0 */6 * * *` (every 6h) | Production agencies tracking active client sites |\\n| `0 0 * * *` (daily) | Lower-traffic sites or local dev |\\n| Manual only | First few weeks while validating data |\\n\\n## Telemetry\\n\\nEvery successful or failed sync emits a `traffic.synced` event to the\\ncanonry telemetry pipeline:\\n\\n```jsonc\\n{\\n \"event\": \"traffic.synced\",\\n \"errorCode\": \"PROVIDER_AUTH\", // present only when status=\\'failed\\'\\n \"properties\": {\\n \"status\": \"completed\" | \"failed\",\\n \"sourceType\": \"cloud-run\", // adapter type\\n \"sourceId\": \"\", // opaque\\n \"pulledEvents\": 234,\\n \"crawlerHits\": 200,\\n \"aiReferralHits\": 12,\\n \"durationMs\": 4150\\n }\\n}\\n```\\n\\nCounts are aggregate. The sourceId is an opaque UUID. No raw paths,\\ndomains, or PII are surfaced.\\n\\n## Limits & caveats\\n\\n- **The WordPress plugin is PHP-only.** The `wordpress` adapter records only\\n requests that reach PHP. Cache-served page requests, including AI crawlers\\n and live AI user-fetches, go uncounted even while crawls of uncached\\n sitemaps, assets, or cache misses appear. On a cached WordPress site, treat\\n this source as a floor unless the selected AI user agents bypass every\\n page-cache and CDN layer. The static doctor warning surfaces this limitation\\n without requesting the origin. Otherwise, use a cache-independent\\n `cloud-run`, `vercel`, or edge-log source. Adapter coverage\\n differs: `vercel` ingests edge request logs so cache hits are captured (it\\n records the `cache` HIT/MISS label), and `cloud-run` logs every request that\\n reaches the service, missing only what a CDN ahead of Cloud Run serves at its\\n own edge.\\n- **Path-level citation cross-reference is not implemented yet.** The\\n citation store is domain-grain (`query_snapshots.cited_domains`). A\\n future iteration that lands URL-grain citation evidence will extend\\n the `topCrawledPaths` entry with a `citationState` flag. Until then,\\n treat the report\\'s crawled-paths table as \"engine attention\" — the\\n signal is the bot fetched it, not whether it was cited.\\n- **Verified vs unverified.** The headline numbers count only\\n published-IP-range-verified hits. Unverified bots claim a known UA but\\n do not match the operator\\'s published IP ranges. The bot can be real or an\\n imitator. Do not promote unverified counts in client-facing copy.\\n **Vercel sources are a special case:** the Vercel pull API returns\\n no client IP, so every Vercel crawler hit is unverified by\\n construction (UA-only). A Vercel source reading 100% unverified is\\n expected, not a misconfiguration.\\n- **Four adapters ship: Cloud Run, WordPress, Vercel, and Cloudflare with\\n direct-push and queue-pull delivery. More adapters are planned.** The doctor checks and report renderer are\\n adapter-agnostic — adding a new adapter is just a new entry in\\n `traffic_sources.source_type` and a `TrafficSourceValidator`\\n registration.\\n\\n### Page caches and PHP-only coverage\\n\\nA page cache (LiteSpeed, WP Rocket, Super Cache, or any\\n`advanced-cache.php` drop-in) can serve a request before WordPress boots. The\\nplugin therefore has one capture lane only: PHP. It cannot recover a\\ncache-served crawler, user fetch, referral, or browser page view after the\\nfact.\\n\\nFor the AI agents measured by this source, configure cache bypasses at every\\nlayer that can answer the public request: the WordPress cache, a host/CDN cache,\\nand any edge cache. A LiteSpeed exclusion alone is insufficient when an outer\\nCDN can return a cached response first.\\n\\nCache exclusions for the selected AI agents can recover crawler and user-fetch\\ncoverage, but they do not recover ordinary browser referrals served from cache.\\nUse GA4 for landed browser visits or edge/access logs for cache-independent\\nrequest coverage. The `traffic.source.cache-blindspot` doctor check is a static\\nwarning; it does not request or impersonate traffic against the public origin.\\n'\n",[],[198,558,600,614],"2a69f577-ab61-49d0-bf5d-08924a89d962","canonry-references-indexing.0.ts","97654720-a63e-11f1-87ca-1607ee4eb77e",235,["D",1788372560670],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part =\n '# Indexing Workflows for AEO\\n\\nGetting pages indexed fast is high-leverage AEO work. Unindexed pages are invisible to AI citation regardless of content quality.\\n\\n## Priority Order\\n\\n1. **Sitemap submission** — general-site discovery signal; submit on setup and resubmit after material sitemap changes\\n2. **Bing WMT + IndexNow** — crawl notification path for Bing-backed surfaces\\n3. **Google Indexing API** — only for eligible JobPosting and livestream BroadcastEvent pages\\n\\n---\\n\\n## Google Search Console\\n\\n### Check coverage\\n```bash\\ncnry google coverage \\n```\\n\\nStatuses to act on:\\n- `URL is unknown to Google` → highest priority, submit immediately\\n- `Discovered - currently not indexed` → Google found it but hasn\\'t crawled — submit to accelerate\\n- `indexed` → no action needed\\n\\n### Sync GSC data\\n```bash\\ncnry google sync # incremental sync\\ncnry google sync --full --wait # full re-sync\\n```\\n\\n### Check search performance\\n```bash\\ncnry google performance # top rows by clicks\\ncnry google performance --days 90 --keyword \"term\"\\ncnry google performance --start 2026-06-01 --end 2026-06-30 --order-by date\\n```\\n\\n### Discover and inspect sitemaps\\n```bash\\ncnry google discover-sitemaps --wait # auto-discover sitemaps and queue inspection\\ncnry google list-sitemaps # list submitted sitemaps\\ncnry google inspect-sitemap --wait # bulk inspect all sitemap URLs\\n```\\n\\n### Submit or resubmit sitemaps\\n```bash\\ncnry google submit-sitemap https://example.com/sitemap.xml\\ncnry google submit-sitemap --configured # Canonry\\'s saved default\\ncnry google submit-sitemap --all # prefer sitemap indexes (fallback: top-level files)\\ncnry google submit-sitemap --all-files # include top-level files and index children (batched by 50)\\n```\\n\\nAn accepted submission asks Google to refetch the sitemap; it does not guarantee\\nthat any URL will be indexed. Existing read-only GSC connections must reconnect\\nonce to grant the full `webmasters` scope required for sitemap submission.\\n\\n### Inspect individual URLs\\n```bash\\ncnry google inspect # inspect specific URL\\ncnry google inspections # inspection history\\ncnry google inspections --url # filter by URL\\ncnry google deindexed # pages that lost indexing\\n```\\n\\n### Submit URLs to Google Indexing API\\n```bash\\n# Single URL\\ncnry google request-indexing \\n\\n# All unindexed at once\\ncnry google request-indexing --all-unindexed\\n```\\n\\n**Requirements:**\\n- \"Web Search Indexing API\" enabled in the GCP project\\n- OAuth connection set up in canonry (`cnry settings` shows Google connection)\\n- The URL has eligible `JobPosting` or livestream `BroadcastEvent` structured data\\n\\n**After submitting:** Check coverage again after 48h. Once indexed, ask for\\nexplicit approval before running a quota-consuming sweep — pages must be\\nindexed before citation is possible.\\n\\n---\\n\\n## Bing Webmaster Tools\\n\\n### One-time setup\\n```bash\\ncnry bing connect --api-key \\ncnry bing set-site https://example.com/\\n```\\n\\nGet API key from: https://www.bing.com/webmasters/ → Settings → API Access\\n\\n### Check connection and coverage\\n```bash\\ncnry bing status \\ncnry bing coverage \\ncnry bing performance \\n```\\n\\n### Inspect URLs\\n```bash\\ncnry bing inspect \\ncnry bing inspections \\n```\\n\\n### Inspect every URL in your sitemap\\n```bash\\ncnry bing inspect-sitemap # default https:///sitemap.xml\\ncnry bing inspect-sitemap --sitemap-url # explicit sitemap or sitemap index\\ncnry bing inspect-sitemap --wait # block until the run finishes\\n```\\nBing has no native sitemap inspection API — this command fetches the sitemap, diffs against the tracked URL set, then calls `GetUrlInfo` for each discovered URL so coverage reflects the full sitemap rather than only previously inspected pages.\\n\\n### Submit URLs for indexing\\n```bash\\ncnry bing request-indexing \\ncnry bing request-indexing --all-unindexed\\n```\\n\\n### Submit sitemap (manual, one-time)\\nBing WMT → Sitemaps → submit `https://example.com/sitemap.xml`\\n\\n### IndexNow (instant crawl signal)\\nIndexNow is a direct ping to Bing: \"these URLs changed, crawl them now.\" Without it, Bing discovers pages on its own schedule (days to weeks). With it, typically hours.\\n\\n**Host the key file at the root:**\\n```\\nhttps://example.com/.txt\\n```\\nFile content: just the key string, nothing else.\\n\\n**Submit URLs:**\\n```bash\\ncurl -X POST \"https://www.bing.com/indexnow\" \\\\\\n -H \"Content-Type: application/json; charset=utf-8\" \\\\\\n -d \\'{\\n \"host\": \"example.com\",\\n \"key\": \"\",\\n \"keyLocation\": \"https://example.com/.txt\",\\n \"urlList\": [\\n \"https://example.com/\",\\n \"https://example.com/page-1\"\\n ]\\n }\\'\\n```\\n\\nExpected response: `202 Accepted`\\n\\n**Note:** IndexNow only covers Bing (and Yandex). It does NOT affect ChatGPT, Claude, or Gemini.\\n\\n---\\n\\n## When to Use What\\n\\n| Goal | Tool |\\n|---|---|\\n| Notify Google about an eligible job or livestream page | Google Indexing API |\\n| Get pages into Copilot / Bing AI | IndexNow + Bing WMT |\\n| Audit what Google currently knows | `cnry google coverage ` |\\n| Audit what Bing currently knows | `cnry bing coverage ` |\\n| Fast crawl of new/updated pages on Bing | IndexNow batch submit |\\n| Ask Google to refetch changed sitemaps | `cnry google submit-sitemap --all` |\\n| Ongoing Google crawl health | `cnry google sync` + `cnry google performance` |\\n| Ongoing Bing crawl health | Bing WMT sitemap + `cnry bing performance` |\\n| Find deindexed pages | `cnry google deindexed ` |\\n\\n---\\n\\n## General Workflow for New Client Pages\\n\\n1. `cnry google submit-sitemap --configured` — submit the saved sitemap\\n2. `cnry google coverage ` — identify unindexed pages\\n3. For eligible job or livestream pages only: `cnry google request-indexing --all-unindexed`\\n4. `cnry bing request-indexing --all-unindexed` — push to Bing\\n5. Submit sitemap to Bing WMT (manual, one-time per site)\\n6. Send IndexNow batch for key URLs\\n7. Re-check coverage after 48h\\n8. After explicit approval, run a sweep once pages are confirmed indexed\\n'\n",[],[198,558,600,622],"ef7ee2c5-f782-4bea-84a4-3c618e5ce068","canonry-references-google-marketing.0.ts","93fb9314-a63e-11f1-8fd4-1607ee4eb77e",228,["D",1788372559936],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part =\n '# Google Ads and Google Tag Manager\\n\\nUse this reference to inspect Google Ads and Google Tag Manager (GTM) as one\\nconversion-tracking system.\\n\\n## Scope\\n\\nCanonry treats `google-ads` and `gtm` as separate, project-scoped providers.\\n`ads` remains the OpenAI/ChatGPT Ads namespace. Version 1 reads provider data\\nand assesses evidence. It does not mutate a Google provider.\\n\\n## Shared integrity chain\\n\\n```text\\ndeclared conversion contract\\n |\\n +--> Google Ads action -> effective campaign goals -> bounded metrics\\n |\\n +--> GTM live tag -> triggers + variables\\n \\\\ /\\n \\\\ /\\n static assessment\\n\\nwebsite event -> GTM firing -> Google Ads conversion receipt\\n |\\n runtime observation\\n```\\n\\nThe contract names the application event, Google Ads conversion action, campaign\\ngoals, GTM tag, triggers, variables, and required runtime evidence.\\nAn action marked primary is not necessarily an effective, biddable campaign goal.\\n\\n| Evidence | It establishes | It does not establish |\\n| --- | --- | --- |\\n| Contract plus Ads and GTM snapshots | Whether static configuration agrees with the declared conversion | A browser event occurred, a tag fired, or Google Ads recorded a conversion |\\n| Runtime observation | Required event, GTM, and Ads evidence was observed | A mismatched static configuration is correct |\\n\\nAn observed runtime signal never repairs an unproven static graph. Opaque custom\\nHTML and templates stay `unknown` or `needs-review`.\\n\\n## Integrity status\\n\\n- `configured`: A contract exists, but the static graph is unproved or inconsistent.\\n- `statically-consistent`: Static checks pass and runtime verification is not required.\\n- `runtime-unverified`: Static checks pass, but required runtime evidence is absent.\\n- `observed`: Static checks pass and trusted runtime evidence is present.\\n\\nInspect findings with the status. `configured` is not a pass state.\\n\\nThe default Canonry runtime does not store runtime observations in version 1.\\nA runtime-required contract therefore stops at `runtime-unverified`.\\n\\n## Operator setup\\n\\nThe operator completes setup in the dashboard:\\n\\n1. Configure the Web application OAuth client in **Settings → Google OAuth**.\\n2. Register the exact Google Ads and Tag Manager redirect URI.\\n3. Open **Project → Conversions**.\\n4. Connect Google Ads and enter the developer token.\\n5. Select the Ads manager and customer context.\\n6. Connect Tag Manager.\\n7. Select the account and container.\\n8. If stored draft evidence is required, select a draft workspace.\\n9. Sync both providers.\\n10. Declare the conversion contract.\\n\\nUse the\\n[Google Marketing setup guide](https://github.com/Canonry/canonry/blob/main/docs/google-marketing.md)\\nfor Google Cloud requirements, a contract example, Doctor commands, and\\ntroubleshooting.\\n\\nThe operator must not give an agent OAuth credentials or a developer token.\\nOAuth starts and finishes in the same signed-in dashboard browser.\\n\\n## Agent procedure\\n\\n1. Call `canonry_load_toolkit` with `{ \"name\": \"google-ads\" }`.\\n2. Wait for the call to return.\\n3. Load `gtm`, `conversion-tracking`, and `monitoring` in the same way.\\n4. Read provider status and stored snapshots.\\n5. Read the declared contracts.\\n6. Assess each contract with `canonry_conversion_tracking_integrity`.\\n7. Report static failures separately from unknown runtime evidence.\\n\\nUse stored evidence first. Before a live provider discovery or sync, get\\nexplicit approval.\\n\\nLive discovery needs a full-instance key with\\n`google-marketing.read-live`. Sync also needs\\n`google-marketing.write` and can use a project-scoped key. A sync queues a run.\\nPoll `canonry_run_get` with the returned run ID until its status is `completed`,\\n`failed`, or `cancelled`. Assess new evidence only after `completed`. If the run\\nfails or is cancelled, report that result instead.\\n\\nMCP does not expose OAuth, resource selection, disconnect, or contract writes.\\nThose actions remain in the operator dashboard and CLI.\\n\\nIf organic performance is in scope, call `canonry_organic_evidence` from the\\nloaded `monitoring` toolkit. Use integrity as a measurement-confidence gate.\\nDo not attribute one organic question or citation to one paid conversion.\\n\\n## Read authority\\n\\nStored snapshot reads are local, redacted evidence. They do not call a provider.\\n`google-marketing.read-live` is the explicit Canonry capability for a bounded,\\nquota-consuming Google Ads or GTM provider read. It does not grant\\n`google-marketing.write` authority, but it also does not narrow Google\\'s OAuth\\ntoken: Google Ads has one broad `adwords` scope. Use a Google Ads user with the\\nRead-only account role and a developer token approved for Reporting permissible\\nuse. GTM uses its read-only OAuth scope.\\n\\nLive queries use bounded account, date, row, page, and retry inputs. GTM uses\\nGETs; Google Ads also uses the non-mutating SearchStream POST endpoint. Agents do not\\nexpose OAuth tokens, OAuth client secrets, or the Google Ads developer token.\\nOAuth, resource selection, and disconnect remain explicit operator actions.\\nOAuth must start and be confirmed in the same signed-in dashboard browser; CLI\\nand MCP never print or transfer authorization URLs.\\n\\nThe OAuth web client must register the exact callback\\n`/api/v1/google-marketing/callback` (default local install:\\n`http://localhost:4100/api/v1/google-marketing/callback`). Pending authorization\\nis process-local, expires after 15 minutes, and must be restarted after a server\\nrestart, browser change, or expiry.\\n\\n## Version 1 safety boundary\\n\\nVersion 1 has no Google Ads create, update, or delete path. It has no GTM create,\\nedit, version, or publish path. A live read never changes either boundary.\\n\\nA selected draft workspace produces a sanitized draft snapshot. The integrity\\nassessment uses the live graph and does not assess the draft graph.\\n\\nThe manual browser procedure is external evidence. It does not change the\\nCanonry status in version 1.\\n\\n## Future write boundary\\n\\nAny future provider write must be proposal-bound. Google Ads needs a reviewable\\nplan and explicit approval. GTM workspace edit approval and GTM publish approval\\nare separate events. Approval to edit a draft never authorizes publishing it.\\n'\n",[],[198,558,600,630],"ceed4eda-5188-4cd3-9d3d-b42272bd8ba0","canonry-references-google-business-profile.0.ts","93ebebf8-a63e-11f1-91a7-1607ee4eb77e",43,["D",1788292312311],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# Google Business Profile Integration\\n\\nCanonry integrates with the Google Business Profile (GBP) API to surface local AEO signals: search-keyword impressions, daily performance metrics, hotel lodging attributes, and booking/reservation CTAs (plus reviews on the projects where Google has granted v4 access — see the gating section). This data feeds the local-AEO dashboard and the Aero analyst.\\n\\n> **Q&A is not available.** Google **retired** the My Business Q&A API (`mybusinessqanda.googleapis.com`) on 2025-11-03, and began winding down the public Q&A section on profiles shortly after. There is no programmatic way to read or write profile Q&A. Don't plan around it.\\n\\n## What Canonry Automates\\n\\n- Discover GBP accounts and locations the connected user manages, with explicit per-location selection\\n- Sync search-keyword impressions aggregated over a date window (default ~12 months; stored with `periodStart`/`periodEnd`)\\n- Sync daily performance metrics — impressions, website clicks, call clicks, direction requests (all 11 `DailyMetric`s)\\n- For hotels: sync lodging attributes (amenities, accessibility, pets, etc.) and place action links (booking CTAs)\\n- Roll the above into a composite summary scorecard (`canonry gbp summary`)\\n- Sync reviews per location — **only where Google has granted v4 access** (gated; unavailable on most projects — see below)\\n\\n## What Stays Manual\\n\\n- Replying to reviews (Phase 4 — write surface)\\n- Posting local posts / offers (Phase 4)\\n- Updating lodging attributes (Phase 4)\\n- Pub/Sub notifications setup (Phase 4)\\n\\nFor now, canonry is read-only on GBP. The Aero agent can draft suggested replies, but applying them is manual.\\n\\n## Hard Prerequisite: API Access Approval\\n\\n**Before anything works**, your Google Cloud project must be approved through Google's Business Profile API Basic Access form. Until approved, every API call returns HTTP 403 / 0 QPM — regardless of OAuth scope or which APIs you've enabled.\\n\\n### Eligibility requirements\\n\\nFrom [Google's prerequisites doc](https://developers.google.com/my-business/content/prereqs#request-access):\\n\\n- **Active Verified Profile** — \\\"Manage a Google Business Profile that is verified and active for 60+ days.\\\"\\n- **Website Requirement** — \\\"Have a website representing the business listed on the GBP.\\\"\\n- **Profile Completeness** — Google recommends the profile be \\\"fully complete and kept up-to-date with the current business information.\\\"\\n\\nBrand-new profiles (under 60 days) and profiles with no associated website are not eligible.\\n\\n### Submitting the access request\\n\\n1. Go to the GBP API contact form: \\n2. Select **\\\"Application for Basic API Access\\\"** from the dropdown.\\n3. Provide:\\n - Your **Google Cloud Console project number** (Cloud Console → Project Info dashboard, *not* the project ID)\\n - Email address listed as an **owner or manager** on the target GBP profile\\n\\n### Approval timeline\\n\\n- Google sends a follow-up email after review (timing varies; common reports are days to a few weeks).\\n- Approval is signaled by a **quota change** in Google Cloud Console:\\n - **Not approved**: quota is **0 QPM** (Queries Per Minute) — every API call returns 403.\\n - **Approved**: quota is **300 QPM** — all enabled APIs become callable.\\n\\nCheck quota at Cloud Console → APIs & Services → quotas, filtered by one of the GBP APIs.\\n\\n## GCP Setup\\n\\n### Enable the right APIs\\n\\nIn Cloud Console → APIs & Services → Library, enable:\\n\\n| API | Purpose |\\n|---|---|\\n| My Business Account Management API | List accounts |\\n| My Business Business Information API | List locations + place action links |\\n| Business Profile Performance API | Daily metrics + monthly search keywords |\\n| My Business Verifications API | (optional) Voice-of-Merchant state |\\n| **My Business Lodging API** | **Hotel attributes — required if working with lodging properties** |\\n| **My Business Place Actions API** | **Booking / reservation CTAs — required if hotels or restaurants use them** |\\n\\n**Do NOT enable \\\"My Business Q&A API\\\"** — Google **retired** it on 2025-11-03. It's listed in some older setup docs but no longer functions.\\n\\n### The legacy \\\"Google My Business API\\\" (v4 — reviews)\\n\\nThe **reviews** endpoint lives on the legacy `mybusiness.googleapis.com` (v4), a separate API from the v1 family above. It is the single biggest stumbling block, and **production testing (May 2026) proved the Basic API Access approval does NOT grant it.**\\n\\nWhat we confirmed, with a project approved and running the v1 family at 300 QPM, authenticated as the exact approved account with the `business.manage` scope:\\n\\n- The v4 reviews call still returns `403 SERVICE_DISABLED`.\\n- The API is **not searchable in the API Library** — the library page returns \\\"Failed to load.\\\"\\n- `gcloud services enable mybusiness.googleapis.com` returns `PERMISSION_DENIED` reason `110002` (`AUTH_PERMISSION_DENIED`) **even as the approved account** — this is the signature of a producer-restricted (Google-allowlisted) service that the project owner cannot toggle.\\n- Per Google's [Basic setup](https://developers.google.com/my-business/content/basic-setup) doc: *\\\"The Google My Business API is only visible in the Google API Console to users who submit and receive approval for their Google Account through the access request form.\\\"*\\n\\n**Conclusion:** the v4 GMB API is gated independently of the v1 approval and Google controls the switch. The only routes are (1) the **shortcut \\\"enable\\\" link from the access-approval email**, opened as the approved account in the browser, or (2) replying to the access-request thread asking Google to enable `mybusiness.googleapis.com` for your project number. Self-service (library, gcloud) does not work. Build reviews behind this gate and ship the rest without it.\\n\\n**Account-credential gotcha:** API calls use your **Application Default Credentials** (`gcloud auth application-default login` → `print-access-token`), while `gcloud services enable` uses the separate **gcloud CLI account** (`gcloud config get-value account`). These can be different identities. Verify the token's real account with `curl \\\"https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=$TOKEN\\\"` before concluding anything about access — a \\\"wrong account\\\" symptom is often just the two credential stores disagreeing.\\n\\n### Create OAuth client credentials\\n\\n1. Cloud Console → APIs & Services → **OAuth consent screen** → set up consent (External works). Add your own email under \\\"Test users\\\" while the app is in test mode.\\n2. Cloud Console → APIs & Services → **Credentials** → **+ Create Credentials** → **OAuth client ID**.\\n3. Application type: **Web application**.\\n4. Authorized redirect URIs: `http://localhost:53682/callback` (or whatever port canonry's connect flow uses — match it exactly).\\n5. Save the **Client ID** and **Client secret**.\\n\\n### Store credentials for canonry\\n\\nEither set env vars before running CLI commands:\\n\\n```bash\\nexport GOOGLE_CLIENT_ID=\\\"…\\\"\\nexport GOOGLE_CLIENT_SECRET=\\\"…\\\"\\n```\\n\\nOr persist them in `~/.canonry/config.yaml`:\\n\\n```yaml\\ngoogle:\\n clientId: \\\"your-client-id\\\"\\n clientSecret: \\\"your-client-secret\\\"\\n```\\n\\nOAuth tokens (per-user, obtained at connect time) are stored in the same file under `google.connections`. They are never written to the canonry database.\\n\\n## Connect a Project\\n\\nOnce GCP setup is done and the access form is approved:\\n\\n```bash\\ncanonry gbp connect \\ncanonry gbp accounts # list accessible accounts (pick one)\\ncanonry gbp locations discover --account accounts/123 # discover that account's locations\\ncanonry gbp locations # verify discovered locations\\ncanonry gbp sync --wait # run a first sync\\ncanonry gbp summary # check derived metrics\\n```\\n\\nThe OAuth scope requested is `https://www.googleapis.com/auth/business.manage`. **There is no read-only variant** — Google does not publish one. The consent screen will say \\\"manage your business profile\\\" even though canonry's read-only surface cannot write anything until Phase 4.\\n\\n### Account selection is per project\\n\\nA single OAuth user often manages **multiple GBP accounts** (a personal account, a location group, agency-managed businesses). Each canonry project tracks **one** account's locations — so to track two businesses, use two projects.\\n\\n- **List accounts:** `canonry gbp accounts ` (API `GET /gbp/accounts`, MCP `canonry_gbp_accounts`) shows every account the connection can see, with its `accounts/{n}` resource name.\\n- **Pick one at discover time:** `canonry gbp locations discover --account accounts/{n}`. Omitting `--account` reuses the account the project already tracks; on the very first discover with no `--account`, canonry falls back to the **first** account the user can see — so if you manage more than one account, always pass `--account` the first time to avoid silently tracking the wrong business.\\n- **Switching accounts is destructive:** re-pointing a project at a *different* account would drop the old account's locations and all its synced data, so it's rejected unless you pass `--switch-account` (API `switchAccount: true`). You can also `canonry gbp disconnect ` (which now clears the project's entire GBP footprint) and start fresh.\\n\\n## The Summary Scorecard (`canonry gbp summary`)\\n\\n`canonry gbp summary [--location locations/XXX]` (API: `GET /gbp/summary`, MCP: `canonry_gbp_summary`) is the single composite read that rolls every synced GBP surface into one scorecard. All math lives in the API (`buildGbpSummary`) — the CLI and dashboard only render it, so `--format json` matches the API response field-for-field. Fields:\\n\\n- **`scope`** — `{ locationName, locationCount }`. `locationName` is null when summarizing across all selected locations.\\n- **`performance`** — daily-metric roll-up:\\n - `totals` — sum per `DailyMetric` over everything synced.\\n - `recent7d` / `prior7d` — per-metric sums for the last 7 days vs the 7 days before, anchored to the **last complete (non-zero) day** (`freshness.dataThroughDate`), not wall-clock and not the max stored date. GBP data lags ~2–3 days and the trailing days can arrive as not-yet-reported zeros; anchoring to the last complete day keeps those lag zeros out of the recent window so a reporting-lag artifact is never shown as a real decline (#658). Both maps are backfilled with the union of metrics as explicit `0`s.\\n - `deltaPct` — percent change recent-vs-prior per metric, **over complete days only**; **`null` when the prior window is `0`** (no divide-by-zero, and \\\"appeared from nothing\\\" is not a percentage).\\n- **`freshness`** — `{ dataThroughDate, latestStoredDate, pendingDays }` (#658). `dataThroughDate` is the last day with reported activity; `latestStoredDate` is the max stored date (≥ dataThroughDate when the lag tail was stored as zeros); `pendingDays` is how many trailing days are still pending vs today. Renderers show \\\"data through <date> · Nd pending\\\" and never treat the tail as a drop.\\n- **`timeseries`** — `[{ date, pending, metrics }]` over the most recent ~30 days, for the trend charts. Each day carries every in-window metric (0 where absent that day) and a `pending` flag marking the reporting-lag tail.\\n- **`keywords`** — `{ total, thresholdedCount, thresholdedPct }`. `thresholdedPct` (0–100) is the share of keywords whose exact count Google redacted — your headline data-fidelity number (expect ~89% for a busy hotel, 100% for an SMB).\\n- **`placeActions`** — `{ total, hasReservationCta, hasBookingCta, hasDirectMerchantCta }`. `hasDirectMerchantCta` is false when the only booking links are OTA/aggregator (Expedia/Booking) — a recommendation to add a direct CTA.\\n- **`lodging`** — `{ lodgingLocationCount, populatedLodgingCount, emptyLodgingCount }`. `emptyLodgingCount` counts lodging-capable locations whose Lodging API response contains zero readable structured groups. That is common even for complete hotels (the owner-set \\\"Hotel details\\\" amenity panel can be populated while this API response is still only `{name}`), so it is a verify signal, not a confirmed gap.\\n\\n## Scheduling\\n\\n`gbp-sync` is a schedulable run kind (alongside `answer-visibility` and `traffic-sync`). It needs no source — it syncs the project's selected locations:\\n\\n```bash\\ncanonry schedule set --kind gbp-sync --preset daily\\ncanonry schedule show --kind gbp-sync\\n```\\n\\nOne schedule row per `(project, kind)`, so a GBP sync schedule coexists with a visibility-sweep schedule. The scheduler creates the `gbp-sync` run and runs the same worker the manual `canonry gbp sync` uses; on completion the run flows through the post-run pipeline (insights + Aero wake-up).\\n\\n## Health Checks (`canonry doctor`)\\n\\n```bash\\ncanonry doctor --project --check 'gbp.*'\\n```\\n\\n- `gbp.auth.connection` — OAuth creds present + refresh token works.\\n- `gbp.auth.scopes` — granted scope includes `business.manage`.\\n- `gbp.account.access` — the tracked account is still listable. A `gbp.account.quota-pending` **warn** means the API access form is still pending Google approval (0 QPM) — auth is fine, the API just isn't enabled yet.\\n- `gbp.places.api-key` — Places API readiness for the listing cross-reference (#648). **Warns** when GBP is connected but no Places key is set, or when no selected location carries a Maps place id (re-run `gbp locations discover`). Skipped when Places is disabled (`places.tier: off`) or GBP isn't connected.\\n- `gbp.data.recent-sync` — a selected location synced in the last 7d (warn) / 30d (fail); warns when never synced.\\n\\n## Insights (after a `gbp-sync` run)\\n\\nA completed `gbp-sync` run generates location-scoped insights (`provider = 'gbp'`), surfaced in `canonry insights`, the dashboard, notifications (`insight.critical`/`insight.high`), and Aero's proactive wake-up:\\n\\n- `gbp-lodging-gap` (low) — a lodging-capable location whose structured Lodging attributes canonry can't read via the GBP Lodging API, **and no Places evidence available** (Places disabled, no key, or no snapshot yet). This is a **verify-nudge, not a confirmed gap**: the Lodging API returns empty even for complete hotels because the owner-set \\\"Hotel details\\\" amenity panel writes to a separate surface the API doesn't expose. Treat `populatedGroupCount === 0` as \\\"can't confirm via the API\\\", not \\\"owner set no amenities\\\", and recommend verifying the \\\"Hotel details\\\" panel.\\n- `gbp-listing-discrepancy` (medium) — the version of the above with Places evidence (#648 Phase B): canonry can't read the Lodging attributes, *plus* a Places snapshot showing the public listing advertises specific amenities (e.g. breakfast, parking, pet-friendly). Because Places can read amenities the Lodging API can't, those amenities are likely already set in \\\"Hotel details\\\" and simply not API-readable, so this is still a **verify** (confirm in \\\"Hotel details\\\"), not a confirmed gap. Names the exact amenities. **Supersedes `gbp-lodging-gap`** when Places data exists. Requires a Places API key + a synced lodging location with a place id.\\n- `gbp-cta-gap` (medium) — place actions present but no direct-merchant booking CTA (only aggregators).\\n- `gbp-description-missing` (low) — a selected location with no owner business description (`profile.description`). Unlike the lodging nudge this is a **reliable, confirmable gap** (the description reads straight from the Business Information API): recommend adding a description (up to 750 chars), the cheapest owner-controlled prose AI engines lift to describe the business.\\n- `gbp-metric-drop` (high/medium) — a headline conversion metric (direction requests, website clicks, call clicks) fell sharply week-over-week within the synced window.\\n- `gbp-keyword-drop` (high/medium) — a head search term's impressions fell month-over-month.\\n\\nThe month-over-month keyword signal is powered by the **accumulating** `gbp_keyword_monthly` table: each sync fetches the last few complete months (one call per month, since the API aggregates a range into a single figure) and preserves older in-retention months, so a real monthly series builds up over time. The current-snapshot reads (`gbp keywords`, `gbp summary`) are unchanged — they still use the trailing-window `gbp_keyword_impressions` table.\\n\\n## Owner-Set Attributes (`gbp attributes`)\\n\\nEvery `gbp sync` also captures the location's **owner-set attributes** via the Business Information API (`getAttributes`) and stores them snapshot-on-change in `gbp_attributes_snapshots`. Unlike the Lodging API (hotels only) this works for **any** business category: amenity / service / accessibility / identity / social-URL tags such as `has_onsite_services`, `offers_online_estimates`, `is_owned_by_women`, wheelchair accessibility, `url_instagram`, `url_facebook`. The API returns **only the attributes the owner has set**, so `attributeCount` is a reliable, owner-readable completeness signal (not a verify-nudge like the lodging gap).\\n\\nRead them with `canonry gbp attributes [--location ] [--format json]` (API `GET /gbp/attributes`, MCP `canonry_gbp_attributes`). The CLI prints each location's set attributes (`key: value`); `--format json` returns the full normalized records (`{name, valueType, values, unsetValues, uris}`).\\n\\n## The Dashboard (`GbpSection`)\\n\\nThe project page shows a self-gating \\\"Google Business Profile\\\" section (only when a GBP connection exists): a **graph-first** performance block — a daily conversion-trend chart (the hero) plus a reach (impressions) area, with the reporting-lag tail greyed as \\\"pending\\\", a \\\"data through <date>\\\" label, and all-zero series collapsed to a \\\"Not active\\\" footnote (#658) — alongside the owner-vs-public gap insight (`gbp-listing-discrepancy`), the public-listing (Places) amenity block, a search-terms table, and a locations table with a track/untrack toggle and a Sync button. Every number is computed server-side by `buildGbpSummary`; the component only renders (Recharts via `ChartPrimitives`). The raw owner-configured Place Action CTAs and the lodging-completeness count are **deliberately not shown in the dashboard**: they are owner-set with no public counterpart to cross-reference, so an \\\"Absent\\\" / \\\"empty\\\" tile would read as a fact about the live listing when it is only an unverifiable owner signal (#648, PR #660). Operators still read them via `cnry gbp place-actions` / `cnry gbp lodging`, and the `/gbp/summary` API still carries both fields.\\n\\n## Hotel-Specific Setup\\n\\nFor hotel groups, two extra signal sources are critical:\\n\\n### Lodging attributes (`canonry gbp lodging`)\\n\\nHotel amenities are a high-signal local-AEO surface: answer engines often answer queries like \\\"does X hotel have a pool?\\\" or \\\"is Y pet-friendly?\\\" from structured hotel facts instead of website copy alone. Canonry therefore treats the Lodging API as a separate hotel-only source from generic Business Information `getAttributes`.\\n\\nCanonry snapshots the raw Lodging API resource on every `gbp sync` and reports how many top-level groups are readable. It does **not** infer missing amenities from a zero-group response, and it does **not** treat generic `getAttributes` tags as a substitute for Hotel details. A zero-group Lodging API response remains a verify-the-Hotel-details-panel signal.\\n\\nA non-lodging location returns HTTP 400 `FAILED_PRECONDITION` (\\\"This operation is not supported for this location. Please check the value of `Location.location_state.can_operate_lodging_data`\\\") — not a 404. Fix the primary category in the Business Profile UI to a lodging category first. A lodging-category location can return HTTP 200 with only `{ \\\"name\\\": \\\"...\\\" }`. That is the common case observed on a complete hotel, even when the owner-facing \\\"Hotel details\\\" panel has amenities filled in. So an empty result is a \\\"can't read via the API\\\" verify, not proof the hotel has no amenities.\\n\\n### Place action links (`canonry gbp place-actions`)\\n\\nBooking and reservation CTAs surfaced in AI answers come from `placeActionLinks`, not from the website URL. Canonry tracks:\\n\\n- `placeActionType` (`RESERVATION`, `BOOK`, `ORDER_FOOD`, …)\\n- `providerType` (`MERCHANT` for direct, `AGGREGATOR` for OTA links like Expedia/Booking)\\n- `isPreferred` flag\\n- `uri`\\n\\nA property with only aggregator booking links and no direct merchant CTA is a recommendation to surface.\\n\\n## Places enrichment — the rendered-listing cross-reference (#648)\\n\\nFor lodging locations, canonry pulls the **Places API (New) Place Details** — the amenities Google's *public* listing advertises (breakfast, parking, pet policy, accessibility, editorial summary) — and cross-references them against the owner-configured GBP profile. When the Lodging API returns nothing but the public listing advertises amenities, the `gbp-listing-discrepancy` insight names those amenities so the operator can verify they are set in the \\\"Hotel details\\\" panel (the listing may already be drawing them from there even though this Lodging API response returned no readable groups).\\n\\n**Setup** — the Places API uses a plain **API key**, not OAuth (unrelated to `google.clientId`). A billing account (card) is required on the GCP project even within the free tier.\\n\\n```yaml\\n# ~/.canonry/config.yaml — top-level `places` block (an API key, not OAuth, so\\n# it is separate from the `google` block — same as `ga4`, `bing`, `wordpress`).\\nplaces:\\n apiKey: \\\"AIza...\\\" # or env GOOGLE_PLACES_API_KEY\\n tier: atmosphere # atmosphere (default) | pro | off\\n refreshIntervalDays: 7 # cost lever — re-fetch a location at most weekly\\n```\\n\\nThe next `gbp sync` then snapshots Place Details for selected lodging locations that carry a Maps place id (re-run `gbp locations discover` if `gbp.places.api-key` warns there are none). Read it back with `canonry gbp places ` (the `amenities` list is computed server-side).\\n\\n**Cost** — Place Details is billed at the highest field-mask tier requested. The amenity booleans powering the cross-reference are the **Enterprise + Atmosphere** SKU: **1,000 free calls/month, then $25/1,000**. Because canonry fetches Places only for lodging locations and only past the refresh interval (default weekly), a typical operator book (a handful to ~200 hotels on a weekly refresh) stays inside the free tier — **$0/month**. Drop `tier` to `pro` (5,000 free, accessibility-only — thinner cross-reference) or `off` to disable. `accessibilityOptions` is Pro tier; the IDs-only refresh is free.\\n\\n## Provenance: the three data planes (how to present GBP)\\n\\nEvery GBP number belongs to one of three planes. **Tag each figure by plane before you show or say it.** The two classic mistakes are presenting plane 1 as if it were plane 2, and presenting a plane-3 lag artifact as a real change.\\n\\n| Plane | Source | How to present it |\\n|---|---|---|\\n| **1. Owner-configured / owner-readable** (CTAs, profile fields, generic attributes, readable lodging groups) | Business Info / Place Actions / Lodging APIs | \\\"Owner profile completeness\\\", never a fact about the live listing. An empty field is the operator's blind spot, not proof the public listing is empty. Surface as a finding **only when cross-referenced** against plane 2. |\\n| **2. Public rendered** (what searchers and AI see) | Places API (New): a thin, schema-bound subset | Label it a **partial** public view. Thin or empty Places data is NOT evidence the listing is sparse, because the full rendered listing also synthesizes Hotel Center pricing, OTA links, and Local Guide contributions that no API returns. |\\n| **3. Performance** (impressions, clicks, directions, calls) | Performance API, ~2 to 3 day reporting lag | NOT an owner-content signal: the owner-configured caveat does not apply. The honesty lever here is the lag. Anchor windows to the last complete day, show `freshness`, and never call the unreported tail a decline (worse right after US holidays). |\\n\\n**The only thing to present as a \\\"finding\\\"** is the plane-1-vs-plane-2 delta: the `gbp-listing-discrepancy` insight. Quote its named amenities as a floor (\\\"the public listing advertises at least X that your profile doesn't\\\"), never a complete inventory.\\n\\n## Important Constraints\\n\\n- **GBP API returns owner-configured data only** — the API exposes only what the profile owner has set. Google's *rendered* hotel listing synthesizes additional amenities, room pricing, and booking links from Google Hotel Center, OTA feeds (Booking/Expedia/Hotels.com), and Places/user-contributed data — none of which the GBP API returns. So an empty Lodging API result does **not** mean the public listing is empty, and it does **not** prove the owner set no amenities: the owner-facing \\\"Hotel details\\\" amenity panel writes to a separate surface the Lodging API does not return, so it is commonly empty even for complete hotels. Treat it as a \\\"verify the Hotel details panel\\\", not a confirmed gap. **Canonry pulls the rendered-listing side from the Places API and cross-references it against the GBP profile** (issue #648, shipped) — see \\\"Places enrichment\\\" below.\\n- **No read-only OAuth scope** — `business.manage` is the only published scope. The consent screen will warn about write access even though canonry's v1 is read-only.\\n- **300 QPM shared quota** — across all GBP sub-APIs on one Google Cloud project. Canonry's sync worker caps per-location concurrency at 4 (~28 in-flight calls at peak) to stay well under the cap.\\n- **10 edits/min per profile** — hard cap on writes (relevant for Phase 4). Cannot be raised.\\n- **Privacy-redacted keyword impressions** — for each keyword aggregated over the requested window, Google returns either an exact `value` or only a `threshold` floor (` --location locations/XXX` to retry a subset.\\n\\n## Real-World Data Shapes & Signal Patterns\\n\\nValidated against three live businesses of different types (a computer-support shop, a roofing contractor, and a Venice Beach hotel). Bake these into any parsing or analysis code.\\n\\n### Response-shape quirks (the parser MUST handle these)\\n\\n- **Values are string-encoded integers.** Keyword counts come as `{ \\\"insightsValue\\\": { \\\"value\\\": \\\"10939\\\" } }` or `{ \\\"insightsValue\\\": { \\\"threshold\\\": \\\"15\\\" } }` — note the nesting under `insightsValue` and that `\\\"10939\\\"` is a string. `Number()` it.\\n- **Daily-metric zero days omit the value entirely.** A datedValue with no traffic is `{ \\\"date\\\": {\\\"year\\\":2026,\\\"month\\\":5,\\\"day\\\":1} }` — there is no `\\\"value\\\": \\\"0\\\"`. Treat a missing `value` as 0; don't skip the row.\\n- **Dates are split objects** (`{year, month, day}`), not ISO strings. Reassemble.\\n\\n### Signal patterns (what the data actually looks like)\\n\\n- **`BUSINESS_DIRECTION_REQUESTS` is the most reliably-populated conversion signal** across every business type — even a tiny roofing contractor logged 66/30d while its website-clicks (2) and call-clicks (1) were near-zero. For local/service businesses it's the headline AEO-conversion proxy, not website clicks.\\n- **Most of the 11 daily metrics are all-zero** for non-retail businesses (`BUSINESS_CONVERSATIONS`, `BUSINESS_BOOKINGS`, `BUSINESS_FOOD_*` were 0 for all three). Syncing all 11 is fine (zeros are cheap) but the dashboard should hide all-zero series.\\n- **Impressions skew to Maps for physical-destination businesses.** The hotel pulled 7,402 desktop-maps impressions vs 2,257 desktop-search in 30 days — people find it on Maps.\\n- **Keyword thresholding scales with volume.** A busy hotel was ~89% thresholded (its head terms like `hotels`→10,939 had exact values); both small businesses were **100% thresholded** (every keyword redacted). For the typical SMB location, expect zero exact keyword values — design the UI to lead with the `/ at the repository root.\nexport const part =\n ' # topPages[], aiReferrals[], aiReferralLandingPages[],\\n # aiSessionsDeduped, aiSessionsBySession, socialReferrals[]\\n # (sessions only — the AI-referral user counts were withdrawn\\n # in 4.135.0; GA counts users distinct per grain)\\ncnry ga attribution [--trend] # unified channel breakdown (organic / ai / social / direct\\n # sessions + raw and display share %s); --trend adds 7d/30d\\n # direction per channel + biggest mover\\ncnry ga ai-referral-daily [--window 30d] [--start YYYY-MM-DD] [--end YYYY-MM-DD]\\n # AI sessions per day and per source: days[] with\\n # {date, sessions, paidSessions, organicSessions,\\n # bySource[]} + window totals. Landing pages summed inside\\n # ONE attribution dimension, never across dimensions, so\\n # totalSessions equals aiSessionsDeduped from `ga traffic`.\\n # Use this for any AI session COUNT. Sessions only: GA\\n # counts users DISTINCT per grain, so an AI-referral user\\n # count cannot be summed from these rows or fetched.\\ncnry ga ai-referral-history [--window 30d] [--start YYYY-MM-DD] [--end YYYY-MM-DD]\\n # RAW DETAIL, one row per (day × source × dimension ×\\n # landing page): {date, source, medium, attribution,\\n # landingPage, sessions, users}. Rows are fragments of a\\n # day, commonly worth 1 session each. Never collapse them\\n # into a total; read ai-referral-daily instead.\\ncnry ga social-referral-history [--window 30d] [--start YYYY-MM-DD] [--end YYYY-MM-DD]\\n # daily array of {date, source, medium, channel,\\n # sessions, users}; channel ∈ {Organic Social, Paid Social}\\ncnry ga social-referral-summary [--trend]\\n # one-line social rollup: socialSessions, socialUsers,\\n # socialSharePct, topSources[]; --trend adds 7d/30d direction\\ncnry ga session-history [--window 30d] [--start YYYY-MM-DD] [--end YYYY-MM-DD]\\n # daily totals: {date, sessions, organicSessions, users}\\ncnry ga coverage # per-page overlay: {landingPage, sessions,\\n # organicSessions, users}\\n```\\n\\n`--window` is rolling from now, so it can never name a calendar month. Pass `--start` / `--end` (inclusive, `YYYY-MM-DD`) for a calendar range; explicit dates win over `--window`. An unrecognised `--window` value is now REJECTED with a validation error rather than silently returning the full history under the label the caller asked for.\\n\\nEvery read command queries persisted DB rows, so a stale `lastSyncedAt` means the response is stale — always check `ga status` before drawing conclusions, and re-`ga sync` if the data is older than the analysis window. Use `--only ai` or `--only social` to refresh just one slice when iterating.\\n\\n## Google Business Profile (Local AEO)\\n\\nGBP integration tracks how AI engines see a business\\'s local presence — search-keyword impressions, daily performance metrics, hotel lodging attributes, and booking CTAs. It reuses the **Google OAuth client** (same `google.clientId`/`clientSecret` as GSC; the connection is stored under the `gbp` connection type). **Hard prerequisite:** the Google Cloud project must be approved through Google\\'s Business Profile API Basic Access form, or every call returns HTTP 403 at 0 QPM. See `references/google-business-profile.md` for the full GCP-setup + access-request playbook, the reviews/Q&A gating, and real-world data-shape quirks.\\n\\nLike GA4, `gbp sync` writes to local DB tables and every read command queries the local store — reads are fast and quotaless; a stale sync means stale reads. All commands support `--format json`.\\n\\n```bash\\ncnry gbp connect [--public-url ] # OAuth connect (reuses the Google client)\\ncnry gbp disconnect # remove the GBP connection + ALL synced GBP data\\ncnry gbp accounts # list GBP accounts this connection can access\\n # (account selection is per project — pick one below)\\ncnry gbp locations discover [--account accounts/{n}] [--switch-account] [--no-select-new]\\n # discover a chosen account\\'s locations; --account targets a\\n # specific account (omit = the account the project already tracks,\\n # else the first visible one); --switch-account opts into the\\n # destructive re-point to a different account; selects all new by default\\ncnry gbp locations [--selected-only] # list discovered locations + selection state\\ncnry gbp locations select --location locations/{n}\\ncnry gbp locations deselect --location locations/{n}\\n # only SELECTED locations are synced\\ncnry gbp sync [--location locations/{n}] [--days N] [--months N] [--wait]\\n # fires the gbp-sync run: daily metrics + keyword impressions\\n # + place-action links + lodging snapshot per selected location;\\n # --wait polls to a terminal run status\\ncnry gbp metrics [--location locations/{n}] [--metric ]\\n # stored daily metrics + totals-by-metric\\ncnry gbp keywords [--location locations/{n}]\\n # stored search-keyword impressions over the synced\\n # periodStart..periodEnd window; renders exact counts and\\n # [--location locations/{n}]\\n # booking / reservation / order CTAs per location, with\\n # placeActionType, providerType (MERCHANT vs AGGREGATOR), isPreferred, uri\\ncnry gbp lodging [--location locations/{n}]\\n # latest hotel-attribute snapshot per location (snapshot-on-change):\\n # populatedGroupCount + syncedAt; populatedGroupCount=0 means the Lodging\\n # API returns no structured attributes (common even for complete hotels;\\n # verify the \"Hotel details\" panel), a verify signal, not a confirmed gap\\ncnry gbp places [--location locations/{n}]\\n # latest Places-API rendered-listing snapshot per location: the\\n # server-derived `amenities` the public listing advertises (#648 cross-reference).\\n # Needs a Places API key (places.apiKey / GOOGLE_PLACES_API_KEY)\\ncnry gbp summary [--location locations/{n}]\\n # composite scorecard: performance totals + recent-vs-prior 7d\\n # deltas (deltaPct null when prior=0), keyword coverage,\\n # place-action CTA presence flags, Lodging API readable-group counts,\\n # owner-content profile completeness (secondary categories /\\n # description / service area / hours / phone + closed-status counts)\\n```\\n\\n`gbp sync` produces a run with the standard statuses (`completed` / `partial` / `failed`); `partial` means some selected locations synced and others errored (the per-location errors are on the run). Non-lodging locations are skipped cleanly (Google answers the lodging call with HTTP 400, not 404). Reviews are **not** synced — the v4 Reviews API is producer-restricted by Google and unavailable on most projects; the Q&A API was retired (2025-11-03).\\n\\n## Google Ads + Google Tag Manager conversion integrity\\n\\n`google-ads` and `gtm` are separate first-class namespaces. **`ads` remains\\nOpenAI / ChatGPT Ads**; do not use it for Google Ads. Canonry v1 only reads\\nprovider state: it never changes a Google Ads campaign/conversion action/goal,\\nand it never edits or publishes GTM.\\n\\n```bash\\n# OAuth is an explicit same-browser operator flow. Start and confirm it from\\n# the project\\'s Conversion Integrity dashboard; the CLI does not print OAuth URLs.\\n\\ncnry google-ads status # local connection + selection/freshness only\\ncnry google-ads customers --format jsonl\\ncnry google-ads select --customer [--login-customer ]\\ncnry google-ads sync # bounded read-only queries (GET + SearchStream POST) + redacted snapshots\\ncnry google-ads snapshots --format jsonl\\ncnry google-ads snapshot

\\ncnry google-ads disconnect # removes private credential; retains redacted evidence\\n\\ncnry gtm status # local connection + selection/freshness only\\ncnry gtm accounts --format jsonl\\ncnry gtm containers --account --format jsonl\\ncnry gtm workspaces --account --container --format jsonl\\ncnry gtm select --account --container [--workspace ]\\ncnry gtm sync # bounded provider GETs + redacted live/draft snapshots\\ncnry gtm snapshots --format jsonl\\ncnry gtm snapshot

\\ncnry gtm disconnect # removes private credential; retains redacted evidence\\n\\n# One contract joins business meaning to the selected Google Ads action and GTM graph.\\ncnry conversion-tracking contracts --format jsonl\\ncnry conversion-tracking contracts get

\\ncnry conversion-tracking contracts create --input contract.json\\ncnry conversion-tracking contracts update

--input contract.json\\ncnry conversion-tracking contracts delete

\\ncnry conversion-tracking contracts integrity

--format jsonl\\n```\\n\\nUse this purchase contract as `contract.json`:\\n\\n```json\\n{\\n \"name\": \"Purchase completed\",\\n \"eventName\": \"purchase\",\\n \"googleAds\": {\\n \"customerId\": \"1234567890\",\\n \"conversionActionId\": \"987654321\",\\n \"conversionId\": \"AW-1234567890\",\\n \"conversionLabel\": \"purchase_label\",\\n \"campaignIds\": [],\\n \"requireBiddableGoal\": true,\\n \"requirePrimaryAction\": true\\n },\\n \"gtm\": {\\n \"accountId\": \"123456\",\\n \"containerId\": \"654321\",\\n \"tagId\": \"42\",\\n \"triggerIds\": [\"17\"],\\n \"variableIds\": [\"21\", \"22\", \"23\"]\\n },\\n \"runtime\": {\\n \"verificationRequired\": true,\\n \"requireTransactionId\": true,\\n \"requireValue\": true,\\n \"requireCurrency\": true,\\n \"productionHosts\": [\"example.com\"]\\n }\\n}\\n```\\n\\nReplace every example ID with a canonical ID from the current snapshots. Use\\nthe Ads customer ID without dashes, the conversion-action `id`, and each GTM\\nresource `id`. Do not use GTM resource paths or the public `GTM-...` container\\nID.\\n\\nEmpty campaign, trigger, or variable arrays disable their corresponding\\nassertions. Canonry checks `requireBiddableGoal` only for listed campaigns. If\\nyou do not know the exact GTM-facing values, omit `conversionId` and\\n`conversionLabel`. Do not supply server-owned IDs or timestamps.\\n\\nUse the\\n[Google Marketing setup guide](https://github.com/Canonry/canonry/blob/main/docs/google-marketing.md)\\nfor the operator workflow.\\n\\nStored snapshot and contract reads are local, redacted, and quota-free. Customer,\\naccount, container, and workspace discovery plus sync are live Google reads; the\\ncaller needs `google-marketing.read-live` in addition to normal write authority\\nfor a sync. `google-ads sync` captures conversion actions and the **effective\\nper-campaign goal graph**; `gtm sync` captures sanitized live and selected-draft\\nconfiguration graphs. They do not prove a browser event fired or that Google Ads\\nrecorded a conversion.\\n\\nThe integrity result is intentionally monotonic:\\n\\n- `configured` means a contract exists but its static graph is unproven or inconsistent.\\n- `statically-consistent` means the stored Ads and GTM evidence agrees.\\n- `runtime-unverified` means the static graph agrees but runtime proof is missing.\\n- `observed` means static and trusted runtime evidence are both present.\\n\\nThe default Canonry runtime does not store runtime evidence in version 1. A\\nruntime-required contract therefore stops at `runtime-unverified`.\\n\\nA selected GTM draft workspace produces stored draft evidence. Integrity uses\\nthe live container graph and does not assess the draft graph.\\n\\nTreat unrecognized GTM custom HTML/templates as `unknown` / needs-review, never\\nas a pass. An Ads action\\'s `primaryForGoal` flag is not proof that a campaign\\neffectively bids toward it; inspect the effective campaign goal evidence.\\n\\n`--format jsonl` streams one record per line for Google Ads customers and\\nsnapshots, GTM accounts/containers/workspaces and snapshots, and\\nconversion-tracking contracts. Each line is stamped with `project`; live\\ndiscovery rows also include `fetchedAt`. Integrity JSONL streams deterministic\\nfindings, each stamped with `project`, `contractId`, `integrityStatus`, and\\n`evaluatedAt`. Status, sync, one-snapshot, one-contract, connect/select, and\\ndisconnect commands emit their normal JSON document when passed `--format\\njsonl`.\\n\\n## OpenAI ads (ChatGPT ads)\\n\\nPaid-surface data for the project\\'s connected OpenAI ad account. Ads render only in the ChatGPT consumer UI (never in API answers), so the Advertiser API is the only window into the paid layer. Money is integer micros in all stored/JSON data; insights `ctr`/`cpcMicros` are derived server-side and `null` on zero denominators. Paid metrics are \"paid\"/\"sponsored\" — never conflate with organic `cited`/`mentioned`.\\n\\n```\\ncnry ads connect --api-key # mint the key in OpenAI Ads Manager; validated upstream, stored in ~/.canonry/config.yaml\\ncnry ads status \\ncnry ads account # live account identity, currency/timezone, status, and integrity review\\ncnry ads geo search --query \"New York\" --limit 20 --format jsonl\\ncnry ads conversions pixels --format jsonl\\ncnry ads conversions event-settings --format jsonl\\ncnry ads image upload --input image.json\\ncnry ads campaign create --input campaign.json\\ncnry ads campaign update

--input update.json\\ncnry ads campaign pause

--input pause.json\\ncnry ads ad-group create --input group.json\\ncnry ads ad-group update

--input update.json\\ncnry ads ad-group pause

--input pause.json\\ncnry ads ad create --input ad.json\\ncnry ads ad update

--input update.json\\ncnry ads ad pause

--input pause.json\\ncnry ads operation

# inspect one durable mutation receipt\\ncnry ads operations unresolved --limit 100 --format json\\n # list pending/unknown/reconciling receipts before new writes\\ncnry ads operations unresolved --cursor --limit 100 --format json\\n # advance past permanent rows with the opaque keyset cursor\\ncnry ads operation reconcile --operation-key \\n # verify nonactivation provider state; never retries the mutation\\ncnry ads operation resume-activation --operation-key \\n # exact-executor recovery for an existing activation receipt; no body\\ncnry ads activation-grant create --input grant.json\\n # human approval for one exact tree + executor key + expiry\\ncnry ads activation-grant revoke

\\n # revoke only while the grant is unused\\ncnry ads campaign activate-tree

--input activate.json\\n # executor consumes the exact approved grant\\ncnry ads sync # ads-sync run: entity snapshots + daily rollups\\ncnry ads campaigns --format jsonl # lifecycle timestamps, location IDs, context hints, creative file IDs\\ncnry ads insights --level campaign --from 2026-06-01 --format jsonl\\ncnry ads summary # campaign-level totals only (no double counting)\\ncnry ads delivery-diagnostics # stored snapshot provenance, configuration facts, historical campaign activity\\ncnry ads live-delivery --campaign # LIVE provider read + stored-snapshot delta (read-only, bounded, 1/min per project)\\ncnry ads disconnect \\ncnry schedule set --kind ads-sync --preset daily\\n```\\n\\n`ads sync` runs report `completed` / `partial` (some campaigns failed; per-campaign errors on the run) / `failed`. Doctor checks: `ads.auth.connection`, `ads.data.recent-sync` (both skipped when not connected).\\n\\nThe stored rollups include the ad account\\'s CURRENT local day while it is still\\nrunning, so the newest date is a partial figure that grows on every sync. Do not\\ncompare it against a finished day, and do not fold it into a period total\\nwithout saying so. Every read that can reach it says which date it is:\\n`ads insights` flags the row (`inProgress: true`), and `ads summary` /\\n`ads delivery-diagnostics` carry `window.inProgressDate` (null when the window\\nholds only closed days). \"Current\" means current in the ACCOUNT\\'s timezone, not\\nyours.\\n\\nOne number on that row is not just partial, it is missing: conversions. OpenAI\\nwill not report a conversion count for a day that is still open, so the current\\nday always shows 0 conversions no matter what actually happened. The real\\nfigure lands on the first sync after the day closes. Impressions, clicks, and\\nspend are live on that row as usual.\\n\\n`ads account`, `ads geo search`, and both `ads conversions` commands read the\\nlive OpenAI Advertiser API rather than the local synced snapshot. Use `account`\\nto verify the connected advertiser and review state, `geo search` to resolve\\ncampaign `locationIds` from provider-issued IDs, and the conversion reads to\\nverify the available pixel/CAPI sources, event goal, and attribution window\\nbefore launch. Geo search defaults to 20 results and accepts 1-100. Its JSONL\\nrows carry `{ project, query, ...location }`; conversion rows carry\\n`{ project, ...pixel }` or `{ project, ...eventSetting }`.\\n\\n`ads delivery-diagnostics` reads stored snapshot provenance, stored\\nconfiguration, and historical campaign activity only. It is never a live OpenAI\\nserving or eligibility verdict. Agents must branch on `snapshot.status` /\\n`issue` and `assessment.state`; partial or unavailable structure must not be\\ntreated as current provider state.\\n\\n`ads live-delivery` is the opposite lane: it calls the provider RIGHT NOW and\\nreturns the provider\\'s current status and metrics per campaign / ad group / ad,\\nunaggregated and in the provider\\'s own units, next to the stored snapshot values\\nand an explicit per-entity delta. Reach for it when the stored snapshot is\\ncontradicted by the advertiser UI, not for routine checks: it is read-only but\\nit spends a third-party call budget, so one project may issue at most one live\\nread per minute (`429` with `retryAfterMs` otherwise). The attempt is counted as\\nsoon as the provider is called, so a `502` still costs the interval: on an\\nupstream failure wait out `retryAfterMs` instead of retrying straight away. Read\\n`bounds.truncated` before concluding anything about entities you did not see,\\nand treat `presence: \"stored-only\"` as \"absent upstream\" ONLY on an untruncated,\\nerror-free read. In `metricDeltas`, every date except the account\\'s current\\nlocal day compares whole days on both sides, so a difference there is real; the\\ncurrent local day is still accruing live while the stored side stopped at the\\nlast sync, so a difference on it is snapshot staleness. `--lookback-days` (1-30,\\ndefault 7) sizes the metrics window; `--campaign` scopes the walk.\\n\\nLifecycle inputs are JSON files, or `--input -` for stdin. Every request carries\\na unique `operationKey`. Identical replays return the stored receipt without a\\nsecond upstream request. Before issuing new lifecycle writes, run `ads\\noperations unresolved`; if a receipt is `pending`, `unknown`, or `reconciling`,\\ndo not retry with a different key. Branch on `kind`: use `ads operation\\nresume-activation` for `campaign_tree_activate`, and generic `ads operation\\nreconcile` for other supported receipts. Generic reconciliation only reads and\\nverifies provider state. It never re-sends the mutation or accepts a\\ncaller-selected provider entity. Canonry resolves a generic receipt only when\\nthe provider ID was durably checkpointed and its live state matches the stored\\nsafe fields on the receipt-bound account. An uncheckpointed create remains\\nunresolved because mutable-field equality cannot prove which request created an\\nentity. A pending generic receipt must be idle for five minutes before either a\\nhuman or the sweeper may claim it, so recovery cannot race a request that is\\nstill returning from the provider. Automatic inconclusive inspections back off\\nfrom a five-minute base; explicit operator requests may inspect sooner, but\\nevery generic path stops after five attempts. The receipt then remains visible\\nas `unknown` with `ADS_RECONCILIATION_QUARANTINED` and requires manual provider\\nremediation. JSON list responses return `nextCursor`; pass it back unchanged\\nwith the same project and state filter to continue.\\nCreates are always paused. Updates require the entity to\\nalready be paused and `expectedUpdatedAt` to equal the latest\\n`upstreamUpdatedAt` from `ads campaigns` after a sync. Canonry exposes pause as\\nthe kill switch and deliberately omits archive and direct entity activation.\\nA human can instead approve one exact campaign tree for a different executor\\nkey. The short-lived grant pins every campaign/ad-group/ad ID and\\n`expectedUpdatedAt`; execution rechecks the account and ad review gates, then\\nactivates ads first, ad groups second, and the campaign last. Each step is\\ndurably checkpointed. A failure rolls back the campaign before its children,\\nand an ambiguous outcome fails closed for manual remediation.\\n\\nFor a conversion-optimized campaign, set `biddingType` to `clicks` and pass at\\nleast one exact `conversionEventSettingIds` value returned by `ads conversions\\nevent-settings`. Each child ad group must set `billingEventType` to `click`.\\nCanonry rejects missing or duplicate conversion IDs and rejects any ad-group\\nbilling mode that does not match its live parent campaign before writing to the\\nprovider. Omit these fields to preserve the legacy impressions/impression mode.\\n\\nCampaign updates may omit `locationIds` to preserve current geo targeting or\\npass a non-empty list to replace it. The guarded operator cannot pass `null` or\\nan empty list to clear targeting. OpenAI documents that clearing targeting can\\nmake the campaign eligible for all available locations, so an intentional\\nall-location change remains a human action in Ads Manager. See\\n[Campaign Targeting](https://developers.openai.com/ads/campaign-targeting) and\\nthe [campaign update contract](https://developers.openai.com/ads/api-reference/campaigns#update-a-campaign).\\n\\n### Guarded operator release gates\\n\\nDefault external automation to a project-scoped API key with exactly `read`,\\n`ads.write`, and `ads.activate`; never hand an external operator an unscoped\\nkey:\\n\\n```bash\\ncanonry key create --name ads-operator --project \\\\\\n --scope read --scope ads.write --scope ads.activate\\ncanonry key create --name ads-approver --project \\\\\\n --scope read --scope ads.approve\\n```\\n\\nKeep the plaintext keys separate. The human approval request must authenticate\\nwith the `ads-approver` key and name the operator key\\'s ID as\\n`executorApiKeyId`; Canonry refuses a grant whose approver and executor IDs are\\nthe same. Approval create/revoke exist in REST and CLI only. MCP and Aero expose\\n`activate-tree` plus bodyless recovery of its existing receipt, so the ads\\noperator cannot mint, replace, or widen its own grant.\\n\\nThe grant request is strict JSON. Its entity arrays must be uniquely sorted by\\nprovider ID so the manifest has one canonical hash:\\n\\n```json\\n{\\n \"manifest\": {\\n \"campaign\": {\\n \"id\": \"cmpn_...\",\\n \"expectedUpdatedAt\": 1780868842,\\n \"adGroups\": [{\\n \"id\": \"adgrp_...\",\\n \"expectedUpdatedAt\": 1780864410,\\n \"ads\": [{ \"id\": \"ad_...\", \"expectedUpdatedAt\": 1781139491 }]\\n }]\\n }\\n },\\n \"executorApiKeyId\": \"key_...\",\\n \"expiresAt\": \"2026-07-18T18:00:00.000Z\"\\n}\\n```\\n\\nThe approval response returns `grant.id` and `grant.manifestHash`. Pass those\\nunchanged to the operator:\\n\\n```json\\n{\\n \"operationKey\": \"launch:campaign:2026-07-18:1\",\\n \"grantId\": \"grant_...\",\\n \"manifestHash\": \"64-lowercase-hex-characters\"\\n}\\n```\\n\\nBefore enabling spend on an advertiser account, run a paused, disposable\\nlive-provider smoke test and capture sanitized raw responses for campaign get,\\ncreate, and pause. For every response, verify and record the exact case and type\\nof `status`, plus the type and exact returned value of `updated_at`. The\\ncaptured responses must agree with the typed client and fixtures without\\ncoercion. After explicit budget approval, repeat the check through one minimal\\ngrant-bound activate-tree execution and immediate campaign pause; verify every\\nactivation response reports exact `active` plus an integer `updated_at`.\\n\\nThe receipt lifecycle is safe across concurrent writers: an atomic claim picks\\none upstream sender and losers replay the canonical receipt. A leased generic\\nreconciler settles supported stale `pending` / `unknown` rows by verifying\\nprovider state. Exact credential/account verification is cached for five\\nminutes, keyed by a one-way credential fingerprint plus the project and stored\\naccount identity; credential rotation or account rebinding misses the cache\\nimmediately. Activation receipts keep their grant and ordered step ledger\\nauthoritative: only the exact bound executor may call the bodyless resume route,\\nwhich cannot substitute a manifest, grant, account, or campaign. When another\\nworker owns reconciliation or activation recovery, callers wait and read the\\ncanonical receipt instead of starting a second pass.\\n\\n## Backlinks (Common Crawl)\\n\\nCanonry actively ingests backlinks from **Common Crawl**, a free public hyperlink graph that refreshes about monthly. The workspace-level release sync downloads each release once and reuses it across projects; per-project extraction requires DuckDB (install once with `cnry backlinks install`).\\n\\nDatabases created by older Canonry versions can retain historical `source=bing-webmaster` rows. Read filters remain compatible with those inert rows, but Canonry no longer fetches or refreshes them.\\n\\nCommon Crawl publishes the hyperlink graph as **rolling, monthly-stepped, overlapping 3-month windows** named by the window\\'s first month\\'s year: `cc-main-YYYY---` (e.g. `cc-main-2026-mar-apr-may`). Omit `--release` to auto-discover the newest published window.\\n\\n```bash\\ncnry backlinks install # install bundled DuckDB binary\\ncnry backlinks doctor # show install + plugin status\\ncnry backlinks status # latest workspace Common Crawl release sync\\ncnry backlinks releases # list cached releases on disk\\ncnry backlinks releases latest # probe Common Crawl for the newest published rolling window\\ncnry backlinks sync # Common Crawl: auto-discover + download + query the newest release (workspace-wide)\\ncnry backlinks sync --release cc-main-2026-mar-apr-may --wait # pin a window, block until ready/failed\\ncnry backlinks sources # active readiness + retained source data\\ncnry backlinks sources --exclude-crawlers # counts drop crawler/proxy hosts (matches the dashboard)\\ncnry backlinks list # top Common Crawl linking domains\\ncnry backlinks list --limit 100 --release \\ncnry backlinks extract --release --wait # Common Crawl: re-extract against a ready release\\ncnry backlinks cache prune --release # delete cached release files from disk\\n```\\n\\nAll commands support `--format json`; collection commands (`list`, `sources`, `releases`) also support `--format jsonl`. A Common Crawl release sync has statuses `queued` → `downloading` → `querying` → `ready` / `failed`. Per-project extracts use the standard run statuses (`queued` → `running` → `completed` / `failed`). Projects with `autoExtractBacklinks` enabled get an extract enqueued automatically when a release sync transitions to `ready`.\\n\\n**`jsonl` output schema:** `backlinks list` streams `rows` (each `{ project, release, targetDomain, linkingDomain, numHosts, source }`); `backlinks sources` streams the per-source availability list (`{ project, targetDomain, source, connected, hasData, latestRelease, totalLinkingDomains, lastSyncedAt }`); `backlinks releases` streams cached-release rows bare.\\n\\nTo keep backlinks fresh automatically, schedule a `backlinks-sync` kind (`cnry schedule set --kind backlinks-sync --preset weekly`): each tick re-probes Common Crawl and runs the workspace release sync **only when a newer rolling window is published** (it skips when the newest `ready` sync already covers the latest release, so it never re-downloads a near-identical window).\\n\\n## CDP / Browser Provider\\n\\nThe CDP (Chrome DevTools Protocol) provider enables browser-based queries against AI chat interfaces (e.g., ChatGPT). This gives more accurate results than API-based providers for some use cases.\\n\\n```bash\\ncnry cdp connect --host localhost --port 9222 # connect to Chrome CDP\\ncnry cdp status # show connection status\\ncnry cdp targets # list available targets (ChatGPT, etc.)\\ncnry cdp screenshot --targets chatgpt # screenshot a query result\\n```\\n\\n**Requires:** Chrome running with `--remote-debugging-port=9222`\\n\\n## Telemetry\\n\\n```bash\\ncnry telemetry status # show telemetry status\\ncnry telemetry enable # enable anonymous telemetry\\ncnry telemetry disable # disable telemetry\\n```\\n\\n## Config as Code\\n\\n```bash\\ncnry apply project.yaml # apply declarative config\\ncnry apply file1.yaml file2.yaml # multiple files\\ncnry export --include-results > project.yaml\\ncnry sitemap inspect \\n```\\n\\n## Agent\\n\\nCanonry ships the built-in **Aero** agent (backed by pi-agent-core) for users\\nwho don\\'t already have one, plus a webhook integration for users who want to\\ndrive Canonry from Claude Code / Codex / a custom agent.\\n\\n### Built-in Aero (one-shot CLI)\\n\\n```bash\\n# One-shot turn — Aero picks its own tools, streams events to stdout.\\ncnry agent ask \"\"\\ncnry agent ask \"\" --format json # JSON event stream\\ncnry agent ask --all \"\" # fan out the same prompt across every project\\ncnry agent ask

Who else shows up

Answer-engine snapshot

Query evidence

Evidence

Recommended fix

Technical AEO sample

${escapeHtml(siteHealth.sampleLabel)}

Problems outside the score

Factors

Worst sampled pages

Does AI mention your brand?${renderInfoTip(LANDING_EXPLAINER)}

${escapeHtml(model.domain)}

Diff · v238