[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_791":792,"_793":794},"routes/_app.x.$handle.$name",{"_100":99,"_32":44,"_109":90,"_27":110,"_13":14,"_111":-5,"_11":112,"_113":114,"_115":116,"_117":118,"_119":120,"_20":-5,"_121":-5,"_122":-5,"_123":25,"_124":125,"_126":59,"_127":-5,"_128":-5,"_129":130},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":54,"_18":55,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":-5,"_73":74,"_75":74,"_76":77,"_78":77,"_79":77,"_80":74,"_81":74,"_82":83,"_84":85,"_86":87,"_88":25},"version",221,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":20,"_34":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":28,"_33":20,"_34":35},"deleted",false,"deletedHere","path","AGENTS.md","latestPath","fileId","92f64d1a-a63e-11f1-8d00-1607ee4eb77e","name","fileType","content","# 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## 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",[],[192,381,392],"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",[],[192,381,401],"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",[],[192,381,409],"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",[],[192,381,418],"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",[],[192,381,427],"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",[],[192,381,435],"860a6741-04fd-4cac-81b8-88fa850c061e",["D",1788292309086],[254,255,256,257,258,259,260,261],[192,381],"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",[],[192,455,447],"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",[],[192,455,457],"01568ee8-b51f-43e3-8630-3492a546a4c6",9,["D",1788292310084],[251,252],[192,455],"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",[],[192,478,470],"site-health","897ce71d-1920-4f1c-a042-52abd50875fa","96c08e88-a63e-11f1-8c22-1607ee4eb77e",114,["D",1788309292732],3,"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",[],[192,478,321],"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",[],[192,478,488],"9872971b-6df7-4db3-a940-d575fb5071df",12,["D",1788292310513],[247,248,249],[192,478],"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",[],[192,509,501],"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",[],[192,509,511],"b8bce09a-c6af-4a10-812e-6d794b08426b",6,["D",1788292309698],[244,245],[192,509],"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",[],[192,531,373],"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",[],[192,531,533],"eb2d53de-7095-4756-867a-252fd03349cc",["D",1788292309828],[241,242],[192,531],"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",[],[192,553,545],"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",[],[192,553,555],"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",[],[192,553,563],"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",[],[192,553,571],"83e4c47f-20fc-4714-a674-9dc8d14ea21c","protocol.ts","94264780-a63e-11f1-a387-1607ee4eb77e",49,["D",1788292312213],"/**\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) return { ok: false, status: 400, response: jsonRpcError(id, JsonRpcErrorCodes.headerMismatch, mismatch) }\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",[],[192,553,579],"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",[],[192,553,595,587],"skills","08d6e8ab-2ff8-41b3-a82f-042c7a39dfae","canonry-skill.0.ts","948d0a42-a63e-11f1-a470-1607ee4eb77e",55,["D",1788292313544],"// 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",[],[192,553,595,597],"7db0fe4f-d79c-48b6-b8c1-f056fad8036c","canonry-references-wordpress-integration.0.ts","9419bc9a-a63e-11f1-9ccc-1607ee4eb77e",47,["D",1788292312646],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# 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",[],[192,553,595,605],"c018d3a5-c235-4446-ba54-4a8a8ef5ab27","canonry-references-server-side-traffic.0.ts","941f748c-a63e-11f1-8fd4-1607ee4eb77e",48,["D",1788292312800],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# 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",[],[192,553,595,613],"a2b2e14c-2490-4b94-abe3-5e13d08e7392","canonry-references-indexing.0.ts","97654720-a63e-11f1-87ca-1607ee4eb77e",66,["D",1788292318310],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# 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",[],[192,553,595,621],"8675f3ca-5442-4c0b-aeab-907667fde257","canonry-references-google-marketing.0.ts","93fb9314-a63e-11f1-8fd4-1607ee4eb77e",45,["D",1788292312493],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# 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",[],[192,553,595,629],"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 = \" # 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 \\\"\\\" --trace # emit tool-execution detail for debugging\\n\\n# Select a specific provider / model (otherwise auto-detected from config).\\ncnry agent ask \\\"\\\" --provider anthropic --model claude-opus-4-7\\ncnry agent ask \\\"\\\" --provider zai --model glm-5.1\\ncnry agent ask \\\"\\\" --provider openai\\ncnry agent ask \\\"\\\" --provider google\\ncnry agent ask \\\"\\\" --provider deepinfra --model zai-org/GLM-5.2 # Western-hosted GLM/DeepSeek (key: DEEPINFRA_TOKEN)\\n\\n# Restrict the tool surface. Default is --scope all (full read+write surface).\\n# --scope read-only matches the dashboard bar default so pasted \\\"Copy as CLI\\\"\\n# commands can't enable writes the UI turn couldn't perform.\\ncnry agent ask \\\"\\\" --scope read-only\\ncnry agent ask \\\"\\\" --scope all\\n\\n# Session + provider introspection\\ncnry agent providers # list provider keys Aero will pick from + the resolved default\\ncnry agent transcript # dump the rolling transcript for the current session\\ncnry agent reset # start a fresh session (drops in-memory state, keeps memory)\\ncnry agent clear # delete the transcript row from the DB\\n\\n# Durable project notes (the hydrate block on every new session)\\ncnry agent memory list \\ncnry agent memory set --key --value # 2 KB cap per value\\ncnry agent memory forget --key \\n```\\n\\n**Provider detection order** when `--provider` is omitted: `anthropic` →\\n`openai` → `google` → `zai` → `deepinfra`, whichever has an API key present\\nfirst (from `~/.canonry/config.yaml` providers block, or the matching env var\\n`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `ZAI_API_KEY` /\\n`DEEPINFRA_TOKEN`). `deepinfra` (GLM-5.2) is a\\nWestern-hosted OpenAI-compatible host — useful when the agent / analyze /\\nclassify tiers must avoid PRC-hosted GLM (`zai`).\\n\\nConversations **persist per project** — `cnry agent ask` continues the\\nsame rolling thread each invocation. Reset with `cnry agent reset `\\nor via the dashboard bar's reset button.\\n\\n### External agents (webhook)\\n\\n```bash\\n# Wire an external agent webhook to a project\\ncnry agent attach --url # register webhook subscription\\ncnry agent attach --url --format json # JSON output\\ncnry agent detach # remove the agent webhook\\ncnry agent detach --format json # JSON output\\n```\\n\\n**Agent webhooks** fire on `run.completed`, `insight.critical`, `insight.high`, and `citation.gained`. The attach/detach pair is idempotent per project (one agent webhook per project, matched by source tag).\\n\\n## Output Formats\\n\\nEvery command takes `--format`:\\n\\n- **`text`** (default) — human-readable, decorated. Not a stable parse target.\\n- **`json`** — one pretty-printed JSON document (the full envelope). Stable contract.\\n- **`jsonl`** — newline-delimited JSON: the command's **primary collection**, one self-contained record per line. The agent-friendly machine format — no envelope key to guess (`.checks` vs `.results` vs `.rows`), no `jq` flattening, greppable line by line.\\n\\n`jsonl` is supported by every **collection** command — one whose primary output is a list: `insights`, `runs`, `evidence`, `history`, `query/keyword/competitor list`, `notify list/events`, `google` reads (`performance`, `performance-daily`, `inspections`, `coverage-history`, `deindexed`, `status`, `properties`, `list-sitemaps`), `bing` reads (`coverage-history`, `inspections`, `performance`, `sites`), `ga` reads (`ai-referral-daily`, `ai-referral-history`, `social-referral-history`, `session-history`, `coverage`), `google-ads` customer/snapshot reads, `gtm` account/container/workspace/snapshot reads, conversion-tracking contracts and integrity findings, `ads geo search` and `ads conversions` reads, `traffic events/sources/status`, `discover list/show`, `content targets/sources/gaps/map`, `backlinks list/releases`, `project list/locations`, `key list`, `agent memory list`, `agent providers`, `sources` (streams the ranked cited-domain list), and `doctor`. (`content brief` is an object command — `jsonl` degrades to its JSON document.)\\n\\nEach `jsonl` line re-injects the envelope context it would otherwise lose, so a line lifted out still self-describes:\\n\\n- project-scoped lists stamp `{ \\\"project\\\": \\\"\\\", …row }`;\\n- `ga *-history` also stamps `window`; `traffic events` stamps `windowStart`/`windowEnd`; `backlinks list` stamps `release`/`targetDomain`; `discover show` stamps `sessionId`; `content targets` stamps `latestRunId`; `project locations` stamps `isDefault`;\\n- global lists whose rows already self-identify (`project list`, `notify events`, `backlinks releases`) emit bare rows.\\n\\nEmpty collection → **no output** (the exit code still conveys success, so \\\"no records\\\" stays distinct from \\\"failure\\\"). On failure a command prints its records (if any), then exits non-zero — branch on the **exit code**, never on parsing stderr. JSON field names and the `{ \\\"error\\\": { \\\"code\\\", \\\"message\\\" } }` envelope are a public contract.\\n\\n**Composite** commands return a single aggregate object (not a list), so there is nothing to stream — on them `--format jsonl` **degrades to the same JSON document** as `--format json`; it never falls through to decorated human text. So `--format jsonl` is safe to pass to *any* command: collection commands stream their records, every other command emits its JSON document. Composite shapes are below.\\n\\n## Output schema per command\\n\\nCompact reference for the composite / keyed commands agents read most (shapes can drift — the linked DTO source file is the source of truth; collection commands simply emit their primary array, see each command's own section above).\\n\\n| Command | JSON output shape (top-level keys → DTO) | `jsonl` |\\n|---|---|---|\\n| `cnry doctor [--project p] [--all]` | `{ scope, project, generatedAt, durationMs, summary{total,ok,warn,fail,skipped}, checks[] }` — `DoctorReportDto` @ `contracts/doctor.ts`. `checks[]` = `CheckResultDto{ id, category, scope, title, status(ok\\\\|warn\\\\|fail\\\\|skipped), code, summary, remediation?, details?, durationMs }`. With `--all`: an object keyed by `__global__` + each project name, each value a full report. | ✅ one check / line as `{project, …check}`; still exits non-zero if any `fail` |\\n| `cnry analytics

[--feature metrics\\\\|gaps\\\\|sources] [--window 7d\\\\|30d\\\\|90d\\\\|all]` | Object **keyed by feature**: `{ metrics?, gaps?, sources? }` (all three present with no `--feature`; one with `--feature X`). `metrics`=`BrandMetricsDto{ window, buckets[], overall, byProvider, trend, mentionTrend, queryChanges[] }`; `gaps`=`GapAnalysisDto{ cited[], gap[], uncited[], mentionedQueries[], mentionGap[], notMentioned[], runId, window }` (each `[]`=`GapQuery`); `sources`=`SourceBreakdownDto` (same shape as `cnry sources`, below). @ `contracts/analytics.ts` | → degrades to the `json` document |\\n| `cnry sources

[--rank] [--limit N] [--by-provider] [--window …]` | `SourceBreakdownDto{ overall[], byQuery, ranked, byProvider, runId, window, limit }` @ `contracts/analytics.ts`. `ranked`/each `byProvider[name]` = `RankedSourceList{ totalCitedSlots, domainTotal, entries[], truncatedDomainCount, truncatedCitedSlots, bySurfaceClass[] }`; `entries[]`=`SourceRankEntry{ domain, count, percentage, category, label, surfaceClass }`; `bySurfaceClass[]`=`SurfaceClassCount{ surfaceClass, label, count, percentage, domainCount }`. `surfaceClass` ∈ own \\\\| direct-competitor \\\\| ota-aggregator \\\\| editorial-media \\\\| other. | ✅ streams `ranked.entries` one / line as `{project, …entry}` |\\n| `cnry visibility-stats

[--since ] [--until ] [--month ] [--last-runs N] [--by-provider] [--share-of-voice] [--query-class branded\\\\|non-brand]` | `VisibilityStatsDto{ project, groupBy, window{since,until,lastRuns,runCount}, totals, byProvider?[], queries[], shareOfVoice? }` @ `contracts/visibility-stats.ts`. Each query / provider / totals entry = `{ total, checked, mentioned, cited, mentionRate, citedRate }` (+ `query`/`queryId`/`firstObserved`/`lastObserved` on queries, + `provider`/observed on provider entries). `checked`=snapshots with non-null `answerMentioned` (tri-state n for mention); `mentionRate=mentioned/checked`, `citedRate=cited/total`, both `null` on a 0 denominator. `byProvider`/per-query `providers` present only with `--by-provider`; counts sum to pooled. `--month YYYY-MM` echoes the resolved `window.since`/`until`. `shareOfVoice` present only with `--share-of-voice` = `{ queryClass, percent, projectMentions, competitorMentions, snapshotsWithAnswerText, perCompetitor[{domain,mentions}] }`; `percent` (0-100) = `projectMentions/(projectMentions+competitorMentions)`, `null` when no competitors configured. `queryClass` is what was actually served: `non-brand` (the default), `branded` (via `--query-class`), or `pooled` — which appears ONLY when the project has no usable brand alias to split by, never as a default. Branded and non-brand never share a denominator. | ✅ streams `queries` one / line as `{project, runCount, …query}` (envelope-only `shareOfVoice` not in the jsonl rows) |\\n| `cnry google coverage

` (index coverage) | `{ summary{total,indexed,notIndexed,deindexed,percentage}, lastInspectedAt, lastSyncedAt, indexed[], notIndexed[], deindexed[], reasonGroups[] }` — `GscCoverageSummaryDto` @ `contracts/google.ts`. `indexed[]`/`notIndexed[]`=`GscUrlInspectionDto`, `deindexed[]`=`GscDeindexedRowDto`. | → degrades to the `json` document. The single-array reads `google inspections` / `coverage-history` / `deindexed` **stream** `jsonl`. |\\n| `cnry ga measurement-analysis

[--window 30d\\\\|60d\\\\|90d] [--host-scope marketing\\\\|all] [--path-prefix /…]` | `GaMeasurementAnalysisDto` @ `contracts/measurement.ts`: fixed 30-day `acquisition.periods/channels/pages`, configured-event `leads.periods/channels` with explicit attribution/filter scope, and `searchDemand.periods/queries/pages` with property totals, reported branded/non-brand rows, and unreported residuals. Each GA component carries independent status/error/sync freshness. | → degrades to the `json` document |\\n| `cnry ga traffic

[--window …]` | Object summary — `GA4TrafficSummaryDto` / `GaTrafficResponse` @ `contracts/ga.ts`: `{ totalSessions, totalOrganicSessions, totalDirectSessions, totalUsers, aiSessionsDeduped, paidAiSessionsDeduped, organicAiSessionsDeduped, aiSessionsBySession, paidAiSessionsBySession, organicAiSessionsBySession, socialSessions, socialUsers, channelBreakdown{organic,social,direct,ai,other→{sessions,sharePct,sharePctDisplay}}, *SharePct (+ `*Display`), topPages[], aiReferrals[], aiReferralLandingPages[], socialReferrals[], lastSyncedAt, periodStart, periodEnd }`. **AI referrals are sessions only.** The six `ai*Users*` fields and the `users` on `aiReferrals[]` / `aiReferralLandingPages[]` were withdrawn in 4.135.0 — GA reports users as a COUNT DISTINCT at the grain requested, so the stored column re-counted one visitor per landing page, medium, channel and date, and no un-dimensioned AI-referral fetch exists to supply a correct figure. `totalUsers` and `socialUsers` are unaffected. | → degrades to the `json` document |\\n| `cnry ga attribution

[--trend]` | Object — a **renamed projection** of `GaTrafficResponse` (⚠️ field names differ from the DTO): `aiSessions`(←`aiSessionsDeduped`), `organicSessions`(←`totalOrganicSessions`), `directSessions`(←`totalDirectSessions`), plus `totalSessions, totalUsers, paidAiSessions, organicAiSessions, aiSessionsBySession, paidAiSessionsBySession, organicAiSessionsBySession, socialSessions, socialUsers, {ai,social,organic,direct}SharePct (+ `*Display`), otherSessions, otherSharePct, channelBreakdown, aiReferrals[], aiReferralLandingPages[], socialReferrals[], periodStart, periodEnd`. With `--trend`: drops `periodStart/End`, adds `trend` (`GaAttributionTrendResponse`). Assembled inline in `commands/ga.ts`. | → degrades to the `json` document |\\n| `cnry key list` / `key create` / `key revoke ` | `list`: `{ keys[] }` — each `ApiKeyDto{ id, name, keyPrefix, scopes[], projectId, projectName, readOnly, createdAt, lastUsedAt, revokedAt }` (SAFE metadata, never the hash or plaintext). `create`: `CreatedApiKeyDto` = `ApiKeyDto` **plus a one-time `key`** (the plaintext `cnry_…` token, shown once). `revoke`: the `ApiKeyDto` with `revokedAt` set. @ `contracts/api-keys.ts` | `key list` streams one key / line; `create` / `revoke` degrade to the `json` document |\\n| `cnry gbp summary

[--location …]` | `{ scope{locationName,locationCount}, performance{totals,recent7d,prior7d,deltaPct} (metric-keyed maps; keys are raw `BUSINESS_*` / `WEBSITE_CLICKS` tokens — label via `formatGbpMetricLabel`), freshness{dataThroughDate,latestStoredDate,pendingDays}, timeseries[], keywords{total,thresholdedCount,thresholdedPct}, placeActions{total,hasReservationCta,hasBookingCta,hasDirectMerchantCta}, lodging{lodgingLocationCount,populatedLodgingCount,emptyLodgingCount}, profileCompleteness{locationCount,withSecondaryCategories,secondaryCategoryTotal,withDescription,withServiceArea,withHours,withPrimaryPhone,permanentlyClosed,temporarilyClosed} }` — `GbpSummaryDto` @ `contracts/gbp.ts`; `emptyLodgingCount` means 0 readable Lodging API groups, a verify signal rather than proof the Hotel details panel is empty. `timeseries[]`=`{date,pending,metrics}`. | → degrades to the `json` document |\\n| `cnry ads account

` | `AdsAccountDto{ id, name, status, currencyCode, timezone, url, reviewStatus, integrityReviewStatus, integrityDecision }` @ `contracts/ads.ts`. This is live provider state, not a synced snapshot. | → degrades to the `json` document |\\n| `cnry ads geo search

--query ` | `AdsGeoSearchResponse{ count, query, results[] }` @ `contracts/ads.ts`; each location has `{ id, type, canonicalName, countryCode, name, regionCode }`. | ✅ one result / line as `{project, query, …location}` |\\n| `cnry ads conversions pixels

` / `event-settings

` | `{ pixels[] }` / `{ eventSettings[] }` @ `contracts/ads.ts`. Event settings include the conversion event, attribution window, source IDs/details, archive state, and version. | ✅ one pixel/event setting / line as `{project, …row}` |\\n\"\n",[],[192,553,595,645],"4a10ef9e-82cb-4b96-aeb2-b33c69485bae","canonry-references-canonry-cli.0.ts","9496878e-a63e-11f1-baa4-1607ee4eb77e",56,["D",1788292313611],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# Canonry CLI Reference\\n\\nThe CLI is invoked as `cnry` (short form) or `canonry` — both ship with the `@canonry/canonry` npm package and behave identically. This reference uses `cnry`.\\n\\n## Server Management\\n\\n```bash\\ncnry init # interactive setup\\ncnry bootstrap # non-interactive setup from env vars\\ncnry start # start daemon\\ncnry stop # stop daemon\\ncnry serve # foreground mode\\ncnry serve --host 0.0.0.0 --port 4100\\ncnry serve --embed --embed-allow-origin https://app.example.com # read-only embed mode (#716)\\ncnry --version\\n```\\n\\n`cnry init` prompts for credentials and prints the new API key once. An agent\\nmust pause and ask the operator to run it in a private terminal, without\\npasting the output back. Do not run `init` or secret-bearing `bootstrap` inside\\nan agent transcript.\\n\\n### Read-only embed mode (#716)\\n\\nOpt-in, OFF by default. Renders the dashboard \\\"chromeless\\\" (no nav/topbar/settings) so it can be iframed read-only, and emits a fail-closed framing contract. With `--embed` absent, served HTML + headers are byte-for-byte unchanged.\\n\\n```bash\\ncnry serve --embed --embed-allow-origin https://app.example.com [--embed-allow-origin https://b.example] [--embed-view overview]\\ncnry start --embed --embed-allow-origin https://app.example.com # daemon form (forwards flags to serve)\\n# Env equivalents (env overrides config.yaml `embed:`):\\n# CANONRY_EMBED=1 CANONRY_EMBED_ORIGINS=https://a.com,https://b.com CANONRY_EMBED_VIEWS=overview,project\\n```\\n\\n- **Framing:** emits `Content-Security-Policy: frame-ancestors ` on the SPA document, **failing CLOSED to `frame-ancestors 'none'`** when no valid origins are configured (so a misconfigured embed is un-framable, not open to everyone). Origins must be bare `scheme://host[:port]` — paths, wildcards (`*.host`), and non-http(s) schemes are rejected. No `X-Frame-Options` is emitted (CSP is the single source of truth).\\n- **Read-only is server-enforced:** embed mode adds NO write surface; the read-only API-key gate (403 on POST/PUT/PATCH/DELETE) is unchanged.\\n- **Cross-origin auth caveat:** the `SameSite=Lax` session cookie is NOT sent in a cross-site iframe and the shipped bundle has no API key. v1 works for a **same-origin** embed (cookie flows) OR a self-hosted build with a read-only `VITE_API_KEY` baked in (then client-visible). Do not loosen the cookie to `SameSite=None`.\\n\\nProduction managed by PM2:\\n```bash\\npm2 status\\npm2 logs canonry\\npm2 restart canonry\\n```\\n\\n## Project Management\\n\\n```bash\\ncnry project list # list all projects\\ncnry project create --domain --country US --language en\\ncnry project show # project detail\\ncnry project update # update project settings\\ncnry project delete # delete a project\\ncnry project delete --dry-run # preview cascade impact (GET /delete-preview) without writing\\ncnry status # mention + citation summary + domain info\\n```\\n\\n### Brand aliases\\n\\n`spec.brandAliases: string[]` on the project (set via `cnry apply` or the dashboard) widens the mention detector. Use it when the answer text says \\\"Meta\\\" but the canonical brand is \\\"Facebook\\\", or for product variants (\\\"AcmeCloud\\\", \\\"Acme Cloud\\\", \\\"AcmeCloud Pro\\\"). Aliases are case-insensitive and match the same answer-text scan that powers `answerMentioned`.\\n\\n## Surgical Reads — `cnry get`\\n\\n```bash\\ncnry get scores.mentionShare.value\\ncnry get scores.mentionCoverage.value\\ncnry get scores.citationCoverage.value\\ncnry get insights[0].severity\\ncnry get latestRun.status\\ncnry get --from report scores.citationCoverage.value # pick a registered source\\ncnry get --format json # raw JSON output\\n```\\n\\nResolves a dot/bracket path against the project's overview (default `--from overview`) or any registered source — `report`, `traffic`, `discovery`, etc. Returns the scalar (or sub-tree) at the path so an agent can lift a single number without pulling a 30 KB JSON payload. Use `--from .` to see the available top-level keys for that source.\\n\\n### Locations\\n\\nProjects support multi-region location context for geographically-aware sweeps:\\n\\n```bash\\ncnry project add-location --label \\\"NYC\\\" --city \\\"New York\\\" --region NY --country US\\ncnry project locations # list configured locations\\ncnry project set-default-location \\ncnry project remove-location \\n```\\n\\n## Sweeps\\n\\n```bash\\ncnry snapshot \\\"Acme Corp\\\" --domain acme.example.com # one-shot sales snapshot\\ncnry snapshot \\\"Acme Corp\\\" --domain acme.example.com --md # save markdown report\\ncnry snapshot \\\"Acme Corp\\\" --domain acme.example.com --output report.md # custom path\\ncnry snapshot \\\"Acme Corp\\\" --domain acme.example.com --pdf # save PDF report\\ncnry snapshot \\\"Acme Corp\\\" --domain acme.example.com --format json\\n\\ncnry run # sweep all configured providers\\ncnry run --provider gemini # single provider only\\ncnry run --query \\\"alpha\\\" --query \\\"beta\\\" # scope sweep to a subset of tracked queries (repeatable)\\ncnry run --wait # block until complete\\ncnry run --location # run with specific location context\\ncnry run --all-locations # run for every configured location\\ncnry run --no-location # explicitly skip location context\\ncnry run --probe --provider openai --query \\\"...\\\" # operator/agent test run — snapshot is inspectable but EXCLUDED from dashboard, analytics, intelligence, report, and notifications. Use for verification / \\\"did this fix work?\\\" / regression hypothesis testing.\\ncnry run --all --wait # all projects\\ncnry run cancel [run-id] # force-cancel stuck runs\\ncnry runs --limit 10 # list recent runs (includes both real and probe runs; filter on `trigger` if you only want one)\\ncnry run show # show run details\\n```\\n\\nRun statuses: `queued` → `running` → `completed` / `failed` / `partial`\\n\\n`partial` = some providers failed (usually rate limits) — successful snapshots are still saved.\\n\\n### Probe vs real runs\\n\\n| Trigger | Source | Feeds dashboard/analytics | Runs intelligence | Fires notifications | Wakes Aero |\\n|---|---|---|---|---|---|\\n| `manual` | `cnry run ` | ✅ | ✅ | ✅ | ✅ |\\n| `scheduled` | cron schedule | ✅ | ✅ | ✅ | ✅ |\\n| `config-apply` | `cnry apply` after queries change | ✅ | ✅ | ✅ | ✅ |\\n| `backfill` | `cnry backfill ...` | partial (historical) | ✅ | — | — |\\n| **`probe`** | `cnry run --probe ...` | ❌ | ❌ | ❌ | ❌ |\\n\\nAfter explicit approval for the exact provider/query (or a bounded batch), use\\n`--probe` for verification rather than producing data the user/dashboard will\\nconsume. A probe still costs provider quota and writes a snapshot; approval for\\none probe does not authorize repeats.\\n\\n`snapshot` does not create a project or write to the DB. It generates category queries, runs providers, and produces a report for prospecting.\\n\\n## Mention + Citation Data\\n\\nTwo independent signals per (query × provider): **mention** (`answerMentioned` — brand named in the answer text; the **primary** read) and **citation** (`cited`/`citedDomains` — domain in the grounding sources; **secondary**). Read mention first. Never compute one from the other; never coerce `answerMentioned` null → false (null = \\\"not checked\\\").\\n\\n```bash\\ncnry evidence # per-query [C/c][M/m] cell + Mentioned: X / Y / Cited: X / Y\\ncnry evidence --format json # JSON output\\ncnry history # audit trail\\ncnry export --include-results # export as YAML\\ncnry backfill answer-mentions # recompute answerMentioned (primary) from stored answers (honors brandAliases)\\ncnry backfill answer-mentions --dry-run\\ncnry backfill answer-visibility # recompute citationState (secondary) from stored answers\\ncnry backfill answer-visibility --dry-run # preview which snapshots would change\\ncnry backfill insights # recompute insights for completed runs\\ncnry backfill insights --since 2026-04-01 --dry-run\\n```\\n\\nOutput uses a two-glyph cell per (query × provider): `[C/c][M/m]` — uppercase = present, lowercase = absent, `–` = no snapshot. **C/c = cited** (secondary), **M/m = mentioned** (primary). Always print the legend before the table; never collapse the two signals into one cell.\\n\\n```\\nLegend: [C/c][M/m] C=cited c=not-cited M=mentioned m=not-mentioned –=no snapshot\\n\\n[C][M] acme corp ny ← mentioned AND cited\\n[c][M] best crm for smb ← mentioned, not cited (mention win, citation gap)\\n[C][m] crm pricing ← cited, not mentioned (citation without share of voice)\\n[c][m] free crm tools ← neither\\n```\\n\\nSummary: `Mentioned: X / Y` (primary) and `Cited: X / Y` (secondary) are reported independently — a query can be one, both, or neither.\\n\\n## Reports\\n\\n```bash\\ncnry report # write canonry-report--YYYY-MM-DD.html\\ncnry report --period 14 # time window: 7|14|30|90 days (default 30) — scopes GSC/GA/server-activity + period-over-period deltas\\ncnry report --output dist/aeo.html # custom path\\ncnry report --format json # raw report payload to stdout\\n```\\n\\nOne-command client-facing AEO report. Bundles the latest visibility sweep, competitor landscape, AI citation sources, GSC + GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps into a self-contained HTML file (inline CSS + SVG charts, no network dependencies). Backed by `GET /api/v1/projects//report` and the `canonry_report` MCP tool.\\n\\nBehavior to know when narrating numbers from the report:\\n- `executiveSummary.citationRate` is **per-query** — `citedQueryCount / totalQueryCount`, with a query counted as cited if any provider in the run cited it. The rate is invariant to provider count, so a gemini-only run and a 4-provider run can be compared honestly. The same definition powers `citationsTrend[].citationRate` so trend deltas track real movement, not provider-mix variance.\\n- `citationsTrend` excludes partial runs to avoid skew. A project with only one completed run gets `trend: \\\"unknown\\\"` and the finding \\\"No prior run to compare against.\\\" — not \\\"Flat compared to the previous run.\\\"\\n- Project ownership uses subdomain-aware matching against `project.canonicalDomain` plus any configured `ownedDomains`. `blog.example.com` and `brand.io` count as the project, not as external sources, when those rules apply.\\n- Competitor tagging in `aiSourceOrigin.topDomains` uses the same subdomain-aware match — `blog.rival.com` is `isCompetitor: true` when `rival.com` is tracked.\\n- AI referral totals dedupe overlapping GA4 attribution dimensions (`session` / `first_user` / `manual_utm`) by picking the largest dimension per `(date, source, medium)`. Two 10-session rows for the same tuple report 10 sessions, not 20.\\n- GSC top-query CTR and avgPosition are impression-weighted, matching GSC's own metric semantics across multi-row queries.\\n\\n## Results Export (historical observations)\\n\\n```bash\\ncnry results export # versioned JSON artifact → canonry-results--YYYY-MM-DD.json in cwd\\ncnry results export --format csv # flat spreadsheet representation of the same records\\ncnry results export --format json --output - # stream the artifact to stdout (agent-friendly)\\ncnry results export --since 2026-06-01 --until 2026-06-30 # inclusive run-creation window (date-only until covers the whole UTC day)\\ncnry results export --include-probes # opt IN to probe runs (excluded by default)\\n```\\n\\nBulk download of every persisted answer-visibility query × provider observation — one record per snapshot, ordered by run then snapshot. This is the raw-history primitive; use `visibility-stats` for aggregates and `visibility-compare` for month-over-month claims.\\n\\nBehavior to know:\\n- **Citation and mention stay independent** per record: `citationState`/`cited` describe source-list attribution; `answerMentioned`/`mentionState` describe answer-text presence. `answerMentioned: null` means \\\"not evaluated\\\" (legacy snapshot), never not-mentioned.\\n- `query` is the snapshot-time text, so removed tracked queries keep their history; `queryId` is null for them.\\n- Includes completed, partial, and failed answer-visibility runs. Probe runs and other run kinds (site-audit etc.) are excluded unless `--include-probes`.\\n- CSV cells are spreadsheet-injection-safe (leading `=`, `+`, `-`, `@` neutralized) and JSON-array columns (`cited_domains_json`, …) are embedded JSON strings.\\n- Raw provider payloads and credentials are never included; grounding sources and issued search queries are.\\n- Backed by `GET /api/v1/projects//results/export` (`?format=json|csv&since&until&includeProbes`). Not exposed as an MCP tool by design — bulk attachments don't fit a context window; agents needing slices should use the paginated snapshot reads or this CLI with `--output -`.\\n- Distinct from `cnry export `, which exports project CONFIGURATION as YAML, not results.\\n\\n## Analytics\\n\\n```bash\\ncnry analytics # default analytics view\\ncnry analytics --feature metrics # mention + citation rate trends (BrandMetricsDto: mentionTrend primary, trend secondary)\\ncnry analytics --feature gaps # brand gap analysis — mention buckets (mentionedQueries[]/mentionGap[]/notMentioned[]) primary, cited buckets (cited[]/gap[]/uncited[]) secondary\\ncnry analytics --feature sources # source breakdown by category\\ncnry analytics --window 7d # time window: 7d, 30d, 90d, all\\n```\\n\\n### Cited-source rankings (`cnry sources`)\\n\\n\\\"Where do AI engines get the facts they cite?\\\" — the full, per-provider, classified ranking of cited domains. Backed by `GET /api/v1/projects//analytics/sources` and the `canonry_analytics_sources` MCP tool. All counts/shares/classification are computed server-side; the CLI only renders.\\n\\n```bash\\ncnry sources # surface-class roll-up (own / direct-competitor / ota-aggregator / editorial-media / other)\\ncnry sources --rank # full ranked cited-domain list, each tagged with category + surface class\\ncnry sources --rank --limit 20 # top 20 domains; an explicit long-tail rollup preserves the totals\\ncnry sources --by-provider # per-provider cited-domain mix + each provider's total cited slots\\ncnry sources --window 30d --format json # window-filterable; --format json emits the SourceBreakdownDto directly\\ncnry sources --rank --format jsonl # stream the ranked domains, one self-contained record per line\\n```\\n\\n- **Surface class** is deterministic (no LLM): `own` = the project's `canonicalDomain`/`ownedDomains`; `direct-competitor` = a tracked competitor; `ota-aggregator` = directories/marketplaces (Yelp, Booking.com, Tripadvisor, Amazon…); `editorial-media` = news/blogs/reference; `other` = everything else. When discovery has run, its stored per-domain classifications (`domain_classifications`) enrich recall for niche OTAs/regional media the static allow-list misses — `own` and tracked competitors always stay authoritative. Running `cnry discover run` improves coverage.\\n- The ranked list is **not truncated** by default (the old top-5-per-category cap is gone). Pass `--limit N` to cap each list; the response carries `truncatedDomainCount` / `truncatedCitedSlots` so totals always reconcile.\\n- Counts are **cited slots** (grounding citations), so a domain cited 3× in one answer counts 3. Probe runs are excluded.\\n\\n### Aggregated visibility stats (`cnry visibility-stats`)\\n\\nPer-query mention (answer-text) and citation (source-list) **counts with a sample size**, pooled across many answer-visibility runs — the data to compute a confidence-aware proportion (e.g. Wilson) or detect drift without fetching every run. Backed by `GET /api/v1/projects//visibility-stats` and the `canonry_visibility_stats` MCP tool. Probe runs and non-`answer-visibility` runs are excluded; only completed/partial runs count. `--share-of-voice` adds a head-to-head vs tracked competitors (`project / (project + competitor)` brand mentions) — the primitive for a month-over-month client report: call it with `--month ` and `--month ` and compare. **It is scoped to NON-BRAND queries by default and the response echoes `queryClass`.** A branded query hands the model your name, so you are mentioned on ~all of them and a competitor structurally cannot be; a pooled figure therefore reports brand recall as category placement (measured: one basket read 42% / rank 1 pooled and 3% / rank LAST non-brand). Pass `--query-class branded` for the recall figure. There is no \\\"all\\\" — the two never share a denominator.\\n\\n```bash\\ncnry visibility-stats # all runs; per-query cited/total + mentioned/checked + pooled TOTAL\\ncnry visibility-stats --last-runs 10 # most recent 10 runs (mutually exclusive with --since/--until/--month)\\ncnry visibility-stats --since 2026-06-01 --until 2026-06-30 # ISO date/time window on run createdAt\\ncnry visibility-stats --month 2026-06 # a whole calendar month (YYYY-MM), expanded to that month's UTC bounds\\ncnry visibility-stats --by-provider # per-provider breakdown (counts sum to the pooled counts)\\ncnry visibility-stats --month 2026-06 --share-of-voice # share of voice vs competitors, NON-BRAND queries (the m/m report primitive)\\ncnry visibility-stats --month 2026-06 --share-of-voice --query-class branded # brand recall: are you named when asked about by name?\\ncnry visibility-stats --format jsonl # stream one record per query, stamped with project + runCount\\n\\n# Month-over-month comparison (the statistically honest m/m primitive — use this, not two --month calls diffed by hand):\\ncnry visibility-compare --from 2026-05 --to 2026-06 # SoV-led, Wilson intervals, within-noise/moved verdict, model-continuity gated\\ncnry visibility-compare --from 2026-05 --to 2026-06 --format json\\n```\\n\\n- **Use `visibility-compare` for any month-over-month AEO claim.** It leads with **share of voice** (less exposed to an engine's broad naming propensity than an absolute rate, `driftRobust: true`), pools rates per-snapshot (invariant to sweep count), restricts to the query/provider PAIRS present in BOTH months, then to providers with one known, identical configured model id in both months, and attaches a Wilson 95% interval + a `verdict` to every metric. Verdicts: **`within-noise`** = NO confirmed change (never report it as a decline); **`moved`** = a real directional move; **`model-discontinuous` / `model-unknown`** = the engine's configured model changed, was mixed within a month, or is unrecorded, so no directional call is made (do not attribute the swing to the site). Read `continuity` (`status` + per-provider evidence) for what was excluded — `continuity` is the gate, `modelChanges` is advisory. A silent upstream version bump under an unchanged configured id remains undetectable. `lowRunCount` flags a month under 5 sweeps, where intervals are too wide to resolve a move.\\n\\n- **Tri-state aware:** `checked` counts only snapshots where `answerMentioned` was recorded — `null` (\\\"not checked\\\") is **excluded**, never counted as not-mentioned. So `checked` is the correct `n` for a mention proportion. `mentionRate = mentioned/checked`; `citedRate = cited/total` (citation_state is always populated, so the citation `n` is `total`). Both rates are `null` when their denominator is 0 (undefined over no samples).\\n- **Date-only window:** `--since`/`--until` accept a full ISO instant or a bare `YYYY-MM-DD`. A date-only `--until 2026-06-30` covers the **whole** UTC day (through 23:59:59.999), so same-day runs are included; a date-only `--since` is that day's start.\\n- **Unbounded by default:** with no `--since`/`--until`/`--last-runs`, every completed/partial run is pooled (`window.runCount` reports how many). For a recent sample, bound it with `--last-runs N`.\\n- **`groupBy` in the payload:** present (`\\\"provider\\\"`) only with `--by-provider`; omitted otherwise (absent = no breakdown) — the generated SDK types it `groupBy?: 'provider'`.\\n- **mention vs cited stay independent** — a model can do either, both, or neither. Don't read one from the other.\\n\\n## Site Health (technical-aeo compatibility)\\n\\nSite-wide technical audit (structured data, AI-readable content, AI-crawler access, content depth/freshness/extractability, …) powered by `@canonry/aeo-audit`'s `runSiteCrawl`. Runs as the `site-audit` run kind — discovers in-scope URLs from the project root, sitemaps, and internal links; stores the URL/link graph; audits eligible HTML pages; and rolls the results into one 0–100 site score. Pure HTTP, no LLM cost; a large site can take minutes, so it runs in the background. `site-health` is the operator-facing CLI name; `technical-aeo` remains compatible.\\n\\n```bash\\ncnry technical-aeo run --wait # full crawl + audit; defaults to 1,000 pages / 100,000 edges; waits for terminal state\\ncnry technical-aeo run --sitemap-url --max-pages 5000 --max-edges 250000 --max-depth 12 # optional crawl seeds and custom budgets; hard caps are 50,000 pages / 1,000,000 edges\\ncnry technical-aeo run --check-dead-links --wait # opt in to dead-link checks; they are off by default\\ncnry technical-aeo progress --run-id [--format json] # exact durable phase and pages found / checked / failed counters; never a synthesized percentage\\ncnry technical-aeo crawl [--run-id ] [--format json] # crawl metadata, budgets, completeness, and termination\\ncnry site-health overview [--run-id ] [--format json] # operator-facing alias for crawl metadata\\ncnry site-health page-audit (--node-key |--url ) [--run-id ] [--format json] # exact audit score, factor findings, recommendations, and crawl provenance for one graph page\\ncnry site-health subgraph [--node-key |--url ] [--hops ] [--max-nodes ] [--max-edges ] [--format json] # focused semantic graph (MCP defaults to 25 nodes / 50 edges)\\ncnry site-health path (--to-node-key |--to-url ) [--from-node-key |--from-url ] [--max-depth ] [--format json] # directed shortest followable-link path\\ncnry site-health changes [--from-run-id ] [--to-run-id ] [--scope all|pages|links] [--change all|added|removed|changed] [--cursor ] [--limit ] [--format json|jsonl] # canonical scan diff; either scan ID is optional; JSONL begins with scan/cursor/filter metadata\\ncnry technical-aeo changes [--from-run-id ] [--to-run-id ] [--scope all|pages|links] [--change all|added|removed|changed] [--cursor ] [--limit ] [--format json|jsonl] # compatibility alias with the same independently optional scan IDs\\ncnry technical-aeo crawl-pages [--fetch-state ] [--indexability-state ] [--sort url|path|score-asc|score-desc] [--cursor ] [--limit ] [--format json|jsonl] # bounded URL inventory with depth and link score\\ncnry technical-aeo page-audit (--node-key |--url ) [--run-id ] [--format json] # compatibility alias for one page's exact audit evidence\\ncnry technical-aeo structure [--parent-path ] [--cursor ] [--limit ] [--format json|jsonl] # one level of the path hierarchy\\ncnry technical-aeo links [--source-url ] [--target-url ] [--followable|--nofollow] [--cursor ] [--limit ] [--format json|jsonl] # bounded internal-link edges\\ncnry technical-aeo links neighbors (--node-key |--url ) [--limit ] [--format json] # bounded inbound/outbound neighborhood\\ncnry technical-aeo dead-links [--cursor ] [--limit ] [--format json|jsonl] # disabled unless the run opted in\\ncnry technical-aeo score [--format json] # site score + per-factor scorecard (avg + pass/partial/fail per page) + delta vs the previous audit\\ncnry technical-aeo pages [--status error] [--sort score-asc|score-desc|url] [--format json|jsonl] # audited-page compatibility view (worst-first by default)\\ncnry technical-aeo trend [--format json|jsonl] # aggregate-score history across past audits\\ncnry schedule set --kind site-audit --preset weekly # keep it fresh\\n```\\n\\nFor agent site readiness, begin with `cnry technical-aeo score --format json`. Use `cnry site-health overview ` only to add crawl metadata; it never replaces the score. Use `cnry site-health page-audit` (MCP: `canonry_site_health_page_audit`) to tie a selected graph page's audit score to exact findings and fixes. Link score is importance, not an audit verdict. Then request a focused neighborhood, a shortest path, or scan-to-scan changes. Do not ask an agent to materialize the interactive graph: it can exceed the MCP tool-result limit. The matching traversal tools are `canonry_site_health_subgraph`, `canonry_site_health_path`, and `canonry_site_health_changes`; the subgraph tool defaults to a small focused result and should be expanded only when needed.\\n\\n- The score is only available after at least one audit runs — `score` returns `hasData: false` until then.\\n- A failed, cancelled, or budget-terminated attempt stays inspectable but never replaces the latest complete crawl graph.\\n- Graph reads are server-paged and bounded. Use `--run-id` to inspect a specific retained run.\\n- A subgraph with `countAccuracy: \\\"lower-bound\\\"` hit a traversal cap: totals and omissions are minimums, not site-wide counts. Its `complete` and `termination` fields apply to every observation.\\n- Treat an `unreachable` or `truncated` path from `complete: false` as limited to persisted crawl observations; use `termination` to explain that qualification.\\n- `changes` returns its resolved filters and an exact post-filter summary only on its first page. JSONL headers retain `filters`, `summaryState`, nullable `summary`/`total`, and `nextCursor`; continuation records remain safe to stream without recomputing totals.\\n\\n## Intelligence\\n\\n```bash\\ncnry insights # list active insights (regressions, gains, opportunities)\\ncnry insights --type gbp-* # filter by insight type; trailing * = prefix (e.g. only GBP insights)\\ncnry insights --type gbp-description-missing # exact type match\\ncnry insights --severity high # minimum severity (high returns high + critical)\\ncnry insights --limit 10 # cap to the newest N\\ncnry insights --dismissed # include dismissed insights\\ncnry insights --format json # JSON output\\ncnry insights dismiss # dismiss an insight\\ncnry health # latest citation health snapshot (citation-only — see known gap below)\\ncnry health --history # health trend over time\\ncnry health --history --limit 10 # limit history entries\\ncnry health --format json # JSON output\\ncnry backfill insights # backfill insights for all completed runs\\ncnry backfill insights --from-run --to-run # backfill a range\\n```\\n\\n> **Known gap (mention-first read):** `cnry health` is **citation-only** today — it has no mention dimension. For the primary mention-first read, use `cnry overview` and `cnry get scores.mentionCoverage.value` / `cnry get scores.mentionShare.value` until health is extended.\\n\\n## Queries & Competitors\\n\\n```bash\\ncnry query add \\\"phrase one\\\" \\\"phrase two\\\"\\ncnry query replace \\\"phrase one\\\" \\\"phrase two\\\" # set the basket to exactly this list\\ncnry query replace \\\"...\\\" --dry-run # preview adds/removes via /queries/replace-preview\\ncnry query remove \\\"phrase\\\"\\ncnry query list \\ncnry query import queries.txt\\ncnry query generate --provider gemini --count 10 --save\\n\\ncnry competitor add competitor1.com competitor2.com\\ncnry competitor list \\n```\\n\\n## Target Measurement Plans\\n\\n```bash\\ncnry measurement-plan discover --sitemap-url https://example.com/sitemap.xml --rule discovery-rule.yaml\\ncnry measurement-plan discover --sitemap-url https://example.com/sitemap.xml --rule discovery-rule.json --max-urls 500\\ncnry measurement-plan show # active immutable revision\\ncnry measurement-plan show --revision 2 # one historical revision\\ncnry measurement-plan versions \\ncnry measurement-plan publish plan.yaml # legacy schema v1 only; refuses over an active v2 plan (use: measurement-plan advanced draft-action)\\ncnry measurement-plan report --revision 2 # stored evidence only; never starts provider work\\ncnry measurement-plan retire \\n```\\n\\n`discover` fetches a public sitemap and applies an operator-supplied deterministic\\nroute rule to project-owned URLs. It returns explicit proposed, alias, shared, unmatched, and excluded\\nbuckets; it does not infer queries or publish a plan. A rule file uses this\\nshape:\\n\\n```yaml\\nprimary:\\n host: example.com\\n pathTemplate: /locations/{slug}\\naliases:\\n - host: directory.example\\n pathTemplate: /{slug}\\nexcludedSlugSuffixes:\\n - blog\\n```\\n\\nReview discovery output, author the plan, and publish it as a separate action.\\n`report` is pinned to one immutable revision and reads stored run evidence. It\\ndoes not execute providers.\\n\\n## Scheduling & Notifications\\n\\n```bash\\ncnry schedule set --preset daily # or: weekly, twice-daily, daily@09\\ncnry schedule set --cron \\\"0 9 * * *\\\" --timezone America/New_York\\ncnry schedule set --kind data-refresh --preset daily # refresh all connected GSC/Bing/GA/GBP integrations (no --source)\\ncnry schedule set --kind backlinks-sync --preset weekly # re-probe Common Crawl; sync only when a newer rolling window is published (no --source/--provider)\\ncnry schedule set --kind site-audit --preset weekly # Technical AEO: bounded full-site crawl and audit (no --source/--provider)\\ncnry schedule show \\ncnry schedule enable \\ncnry schedule disable \\ncnry schedule remove \\n\\ncnry notify add --webhook --events citation.lost,citation.gained\\ncnry notify events # list all available event types\\ncnry notify list \\ncnry notify remove \\ncnry notify test \\n```\\n\\nAvailable events: `citation.lost`, `citation.gained`, `run.completed`, `run.failed`, `insight.critical`, `insight.high`\\n\\n`insight.critical` and `insight.high` fire when the intelligence engine generates critical- or high-severity insights after a sweep completes.\\n\\n> **No mention events yet.** Notification events cover the citation signal only — there are **no** `mention.lost` / `mention.gained` events today. For mention-first monitoring, read `scores.mentionCoverage` / `scores.mentionShare` via `cnry overview` (or the `insight.*` events, which can be driven by mention-side insights); do not wire automation to mention events that aren't emitted.\\n\\n## Provider Settings & Quotas\\n\\n```bash\\ncnry settings # show config: providers, apiUrl, db path\\ncnry settings --format json\\ncnry settings provider gemini --api-key --model gemini-2.5-flash\\ncnry settings provider openai --max-per-day 1000 --max-per-minute 20\\ncnry settings provider perplexity --api-key \\n```\\n\\nQuota flags: `--max-concurrent`, `--max-per-minute`, `--max-per-day`\\n\\nAvailable providers: `gemini`, `openai`, `claude`, `perplexity`, `local`, `cdp`\\n\\nIf a provider hits rate limits (429 errors), the run completes as `partial`. Reduce concurrency or increase time between sweeps.\\n\\n### Gemini Vertex AI\\n\\nGemini supports Vertex AI as an alternative to API key authentication. Use GCP Application Default Credentials (ADC) or a service account JSON key file:\\n\\n```bash\\n# Via env vars (recommended for servers)\\nexport GEMINI_VERTEX_PROJECT=my-gcp-project\\nexport GEMINI_VERTEX_REGION=us-central1 # optional, defaults to us-central1\\nexport GEMINI_VERTEX_CREDENTIALS=/path/to/sa.json # optional, falls back to ADC\\n\\n# Or in canonry.yaml config\\n# vertexProject, vertexRegion, vertexCredentials fields under provider config\\n```\\n\\nWhen Vertex AI is configured, no `GEMINI_API_KEY` is required. The provider uses the `@google-cloud/vertexai` SDK with `googleAuthOptions` for credential handling.\\n\\n## API Keys\\n\\nMint, list, and revoke the `cnry_…` bearer tokens stored in the `api_keys` table. Keys are stored as a sha256 hash, never in plaintext.\\n\\n```bash\\ncnry key list # table: NAME / PREFIX / SCOPES / REACH / CREATED / LAST USED / STATUS\\ncnry key list --format json|jsonl # jsonl streams one key per line\\ncnry key create --name ci-bot # mint a full-access key (scopes default to *)\\ncnry key create --name reader --read-only # read-only key: scopes=['read'], denied every write HTTP method\\ncnry key create --name reader --scope read # narrower key; repeat --scope or comma-separate (--scope a,b)\\ncnry key create --name ci-bot --format json # JSON output includes the plaintext key\\ncnry key revoke # revoke (does not delete); effective on the next request\\ncnry key whoami [--format json] # introspect the CURRENT key (name, scopes, readOnly, status)\\n```\\n\\n- **`--read-only` keys can read everything but write nothing.** The server denies every mutating method (POST/PUT/PATCH/DELETE) for a read-only key (`403 FORBIDDEN`); GET/HEAD pass. `--read-only` is sugar for `--scope read` and cannot be combined with `--scope`. The key DTO carries a derived `readOnly: boolean`. Point `canonry-mcp` at a read-only key and it auto-restricts to read tools.\\n\\n- **Create returns the plaintext key exactly once.** It is shown with a \\\"Save this now — it will not be shown again.\\\" warning (and is included in the JSON under `key`). It cannot be recovered later, so persist it on receipt.\\n- **List never exposes the hash or plaintext** — only safe metadata (id, name, prefix, scopes, created / last-used / revoked timestamps).\\n- **Mutations are gated by the `keys.write` scope.** The default key from `cnry init` carries `*`, which satisfies it. A narrower key needs `keys.write` to mint or revoke.\\n- **Revoke is not delete.** It sets `revokedAt`; the auth layer rejects the key on the next request. Revoking an already-revoked key is a no-op. You cannot revoke the key you are currently authenticating with (use a different key).\\n\\n## Google Search Console\\n\\n```bash\\ncnry google connect # initiate OAuth flow\\ncnry google disconnect # disconnect GSC\\ncnry google status # connection status\\ncnry google properties # list available properties\\ncnry google set-property # set GSC property URL\\ncnry google set-sitemap # set sitemap URL\\ncnry google list-sitemaps # list submitted sitemaps\\ncnry google submit-sitemap # submit up to 50 explicit sitemap URLs\\ncnry google submit-sitemap --configured # submit 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)\\ncnry google discover-sitemaps --wait # auto-discover and inspect\\n\\ncnry google sync # sync GSC data\\ncnry google sync --days 30 --full --wait # full sync with wait\\n# `--full` re-fetches 480 days (GSC's 16-month retention ceiling) and is also the\\n# BACKFILL path: it repopulates the accurate per-query totals (`dimensions:\\n# ['date','query']`, no `page` fan-out) and the property daily totals for the\\n# whole retained window, not just recent days. Run it once per project after\\n# upgrading to pick up accurate history; a normal sync only covers its own window.\\n\\ncnry google coverage # index coverage summary\\ncnry google refresh # force-fetch fresh GSC coverage data\\ncnry google performance # search performance data\\ncnry google performance --days 30 --keyword \\\"term\\\" --page \\\"/url\\\"\\ncnry google performance --start 2026-06-01 --end 2026-06-30\\ncnry google performance --order-by impressions --limit 2000 --offset 2000\\n# Rows are ordered by clicks descending by default; --order-by date|impressions\\n# changes the ranking. --days and --start/--end are mutually exclusive.\\n# One page, not the whole set: the response reports the total number of matching\\n# rows, and the CLI prints how many of them you are looking at. Never sum these\\n# rows for a property total, use `cnry google performance-daily`.\\ncnry google performance-daily # per-day series + property-level window totals\\ncnry google top-pages # pages ranked by clicks, aggregated in SQL\\ncnry google top-pages --start 2026-06-01 --end 2026-06-30 --limit 20\\n\\ncnry google inspect # inspect specific URL\\ncnry google inspect-sitemap --wait # bulk inspect all sitemap URLs\\ncnry google inspections # inspection history\\ncnry google inspections --url # filter by URL\\ncnry google deindexed # pages that lost indexing\\n\\ncnry google request-indexing # push URL to Google\\ncnry google request-indexing --all-unindexed # push all unknown pages\\n```\\n\\n**The dimensioned search-data table is valid for RANKING and invalid for TOTALS.** Read\\nany clicks/impressions total from the property-level daily figures (`performance-daily`\\ntotals, or the `totals` block on `top-pages`), never by summing per-query or per-page rows.\\n\\nWhy: Google withholds rare/anonymised queries, so the dimensioned sum UNDER-counts clicks,\\nand one impression fans out across every query x page x country x device combination, so it\\nOVER-counts impressions. Measured on one real property-month: 792 summed clicks against\\n1,142 actual (31% under) and 45,266 summed impressions against 34,916 actual (30% over).\\n`top-pages` labels its total `totalsSource: \\\"property-daily\\\"` and returns `null` when no\\nproperty-level figure covers the window: a missing total, not a wrong one.\\n\\n## Discovery (Tracked-Basket Expansion)\\n\\n```bash\\ncnry discover run --icp \\\"...\\\" --wait --format json # full pipeline: seed → embed → cluster → probe → bucket\\ncnry discover run --icp \\\"...\\\" --dedup-threshold 0.95 # tune cosine threshold (default 0.95)\\ncnry discover run --icp \\\"...\\\" --max-probes 100 # per-session probe budget (default 100, hard cap 500)\\ncnry discover run --icp \\\"...\\\" --probe-concurrency 3 # parallel probe workers (default 1 = serial, hard cap 8); probe rows stay in canonical order\\ncnry discover run --icp-angle \\\"angle 1\\\" --icp-angle \\\"angle 2\\\" --wait # multi-angle: one session per ICP angle, useful for hyperlocal/niche businesses\\ncnry discover run --icp \\\"...\\\" --locations michigan,florida # geo-constrain seed generation to a subset of project locations (omit = all project locations)\\n\\ncnry discover list # newest-first session list\\ncnry discover show # per-query probe rows + buckets + classified competitor domains\\ncnry discover harvest # gated candidate seeds from the model's issued search-query fan-out (read-only; nothing is probed/tracked/promoted)\\ncnry discover harvest --min-probe-hits 2 --no-anchor # raise the recurrence floor / disable the subject anchor\\ncnry discover promote preview # preview bucketed candidates + recurring suggested competitors of every classified type (read-only)\\ncnry discover promote # adopt cited + aspirational queries + direct-competitor domains\\ncnry discover promote --competitor-types direct-competitor,editorial-media # widen the competitor merge to other classified types\\ncnry discover promote --bucket aspirational --no-competitors # scope to a bucket subset / skip competitor merge\\n```\\n\\nDiscovery requires Gemini configured (API key today; Vertex-mode embeddings are deferred). The pipeline writes a `discovery_sessions` row, a `runs` row (kind `aeo-discover-probe`), and one `discovery.basket-divergence` insight when the session completes. `discover harvest` is a separate read-only view over a completed session: it reads the search queries the answer engine actually issued to answer each probe (Gemini's `groundingMetadata.webSearchQueries` fan-out, already stored in the probe's `raw_response`) back out — no new model call — runs a mandatory quality gate (drops navigational/phone lookups, over-specific outliers, off-subject acronym collisions, exact already-tracked matches, and — via an embedding cosine pass over your tracked queries — semantic duplicates like paraphrases/synonyms that exact match can't see) and returns the survivors ranked by how many distinct probes issued each one. The output's `semanticNoveltyApplied` reports whether the embedding pass ran (it falls back to exact-match when no Gemini key is configured). These are a third signal — *issued retrieval queries*, neither \\\"mention\\\" nor \\\"cited\\\" — and carry no demand of their own; they are candidate seeds, so review them and add the good ones with `cnry query add`. Use `--min-probe-hits` to require recurrence and `--no-anchor` to allow new-subject discovery on a well-scoped project. Seed generation is location-aware: a project with locations configured (or a `--locations` label subset) geo-constrains the seed prompt so generated queries stay inside the service area, and a multi-location project gets a per-area seed quota so one area cannot dominate — `--locations` labels must match the project's configured locations or the run is rejected; projects with no locations are unaffected. After probing, one Gemini call classifies every recurring cited domain as `direct-competitor`, `ota-aggregator`, `editorial-media`, or `other` (a failed/legacy classification leaves domains `unknown`). Aero wakes unprompted with the bucket-count payload so the operator can act without polling. `discover eval` (quality-regression panel vs committed baseline, exit 1 on regression, --update-baseline to capture), `discover promote` defaults to cited + aspirational queries and `direct-competitor` domains only — aggregators and editorial media are suppressed; pass `--competitor-types` to widen the merge (or to recover legacy `unknown` entries) and `--bucket wasted-surface` for off-ICP competitor gaps. Promotion is add-only and idempotent — queries/domains already tracked are reported as skipped, never inserted twice — and only works on `completed` sessions; promoted rows carry `provenance=\\\"discovery:\\\"`.\\n\\n## Bing Webmaster Tools\\n\\n```bash\\ncnry bing connect --api-key # connect Bing WMT\\ncnry bing disconnect # disconnect\\ncnry bing status # connection status\\ncnry bing sites # list verified sites\\ncnry bing set-site # set active site URL\\ncnry bing coverage # URL coverage data\\ncnry bing refresh # force-fetch fresh Bing coverage data\\ncnry bing inspect # inspect specific URL\\ncnry bing inspect-sitemap # discover sitemap URLs and inspect each via Bing\\ncnry bing inspect-sitemap --sitemap-url --wait # explicit sitemap, wait for run\\ncnry bing inspections # inspection history\\ncnry bing request-indexing # submit URL for indexing\\ncnry bing request-indexing --all-unindexed # submit all unindexed\\ncnry bing performance # search performance data\\n```\\n\\n## WordPress Integration\\n\\n```bash\\ncnry wordpress connect --url --user # connect (prompts for app password)\\ncnry wordpress disconnect # disconnect\\ncnry wordpress status # connection status\\ncnry wordpress pages [--live|--staging] # list pages\\ncnry wordpress page # show page detail\\ncnry wordpress create-page --title --slug --content # create page\\ncnry wordpress update-page --content # update page\\ncnry wordpress set-meta --title # set SEO meta (single page)\\ncnry wordpress set-meta --from # bulk set SEO meta from JSON\\ncnry wordpress schema # read page JSON-LD\\ncnry wordpress schema deploy --profile # deploy schema from profile\\ncnry wordpress schema status # schema status per page\\ncnry wordpress set-schema # manual schema handoff\\ncnry wordpress audit # audit pages for SEO issues\\ncnry wordpress diff # compare live vs staging\\ncnry wordpress staging status # staging config status\\ncnry wordpress staging push # manual staging push handoff\\ncnry wordpress llms-txt # read /llms.txt\\ncnry wordpress set-llms-txt # manual llms.txt handoff\\ncnry wordpress onboard --url --user # full onboarding workflow\\n```\\n\\n**Onboard** runs: connect → audit → set-meta → schema deploy → Google submit → Bing submit. Use `--skip-schema` or `--skip-submit` to skip steps. `--profile ` provides business data and page-to-schema mapping for schema deployment.\\n\\n## Server-Side Traffic\\n\\nCloudflare supports direct push and Queue pull. Run Cloudflare connect only from\\nthe local host that owns the Canonry configuration and Wrangler profile. This\\noperation is not available through MCP because it uses local credentials.\\n\\n```bash\\n# Direct push to a stable public Canonry HTTPS receiver:\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode direct-push \\\\\\n --zone-id --account-id \\\\\\n --deploy --confirm-route --confirm-fail-open\\n\\n# Create the Queue and enable its HTTP pull consumer first:\\nwrangler queues create canonry-traffic-\\n# Workers Paid only: use this command to change the four-day default.\\nwrangler queues update canonry-traffic- \\\\\\n --message-retention-period-secs \\nwrangler queues info canonry-traffic-\\nwrangler queues consumer http add canonry-traffic-\\n\\n# Queue pull keeps the API token in the local Canonry credential store:\\ncnry traffic connect cloudflare \\\\\\n --delivery-mode queue-pull \\\\\\n --zone-id --account-id \\\\\\n --queue-id --queue-name canonry-traffic- \\\\\\n --api-token-file \\\\\\n --retention-seconds \\\\\\n --deploy --confirm-route --confirm-fail-open\\n```\\n\\nWorkers Free retention is fixed at `86400` seconds. Workers Paid defaults to\\n`345600` seconds. If you change paid retention with `wrangler queues update`,\\npass the same value to Canonry. The Canonry flag does not change the Queue.\\n\\nBoth commands deploy an unattached Worker. Attach the exact site route in the\\nCloudflare Dashboard. Then set its request-limit failure mode to **Fail open**.\\nDo not put the Queue API token on the command line or in an agent transcript.\\n\\n```bash\\n# If connect reports activationRequired, activate after the route is live:\\ncnry traffic activate --source \\ncnry traffic sync --source # pull adapters, including Cloudflare Queue pull\\ncnry traffic sources --format json\\ncnry traffic status --format json\\ncnry traffic events --source --format json\\n\\ncnry doctor --project --check 'traffic.source.*' --format json\\ncnry schedule show --kind traffic-sync --format json\\ncnry schedule set --kind traffic-sync \\\\\\n --source --cron \\\"*/10 * * * *\\\"\\n```\\n\\nA first source becomes active automatically. A staged source stays paused until\\nthe explicit activation command. Activation pauses sibling sources and moves the\\none `traffic-sync` schedule for the project. Direct push rejects `traffic sync` and\\ndoes not use this schedule.\\n\\nQueue pull drains at most 1,000 messages in one default sync. The doctor warns\\nwhen the remaining backlog is more than 1,000 messages. If the operator approves\\na manual drain, run a manual sync. If the backlog recurs, get approval to shorten\\nthe schedule interval.\\n\\nRead the [server-side traffic guide](server-side-traffic.md) for token safety,\\nroute checks, activation order, smoke tests, rollback, and troubleshooting.\\n\\n## Google Analytics 4\\n\\nGA4 integration supports service-account auth and OAuth (`canonry google connect --type ga4`). With OAuth, `ga properties` lists the readable properties so the numeric id `ga connect --property-id` needs can be discovered without leaving canonry. The service account must have Viewer access on the GA4 property. `ga sync` writes to four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`); every subsequent read command queries the local store rather than re-fetching from GA4, so reads are fast and quotaless. AI-referral rows are tracked across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), three GA4 attribution dimensions (`session` / `first_user` / `manual_utm`), and joined to landing pages. Social referrals are split Organic vs Paid via GA4's `sessionDefaultChannelGroup`. All commands support `--format json`.\\n\\n```bash\\ncnry ga connect --property-id --key-file ./sa-key.json\\n # connect via service account (auth method = service_account)\\ncnry ga disconnect # disconnect; deletes all synced rows for the project\\ncnry ga status # connected, propertyId, authMethod, lastSyncedAt\\ncnry ga properties # list GA4 properties the connected account can read,\\n # with their numeric ids. OAuth connections only —\\n # the id cannot be derived from the domain or the grant\\ncnry ga sync [--days 30] [--only traffic|ai|social]\\n # refresh from GA4 → DB; --only restricts which slice is replaced\\n # returns: synced, rowCount, aiReferralCount, socialReferralCount,\\n # syncedComponents, syncedAt\\ncnry ga measurement-analysis [--window 30d|60d|90d]\\n [--host-scope marketing|all] [--path-prefix /blog] [--limit 100]\\n # fixed 30-day cohorts across native GA4 channels,\\n # configured lead events, branded/non-brand GSC demand,\\n # ranked landing pages/queries, and independent freshness/errors\\n # for acquisition and leads\\ncnry ga traffic [--window 30d] [--start YYYY-MM-DD] [--end YYYY-MM-DD]\\n # current-period rollup; returns: totalSessions,\\n # totalOrganicSessions/totalDirectSessions/totalUsers,\\n # organicSharePct/aiSharePct/socialSharePct/directSharePct,\\n \"\n",[],[192,553,595,653],"4e7eace9-f69e-4b4f-ab3e-652e43f30056","canonry-references-aeo-analysis.0.ts","94070546-a63e-11f1-868f-1607ee4eb77e",46,["D",1788292312611],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"# AEO Analysis: Interpreting Canonry Results\\n\\nCanonry tracks two independent signals per (query × provider): **mention** (the brand is named in the AI answer text, `answerMentioned`) and **citation** (the domain appears in the grounding sources, `cited`/`citedDomains`). **Mention is the primary read; citation is secondary.** Never compute one from the other, and never coerce `answerMentioned` null → false — null means \\\"not checked,\\\" not \\\"not mentioned.\\\"\\n\\n## What Mention Means\\n\\nA \\\"mentioned\\\" query means the client's brand was NAMED in the AI provider's answer text when that query was asked — the model said the brand out loud in its prose. This is the primary gauge of AI visibility: it is what the user actually reads. It does NOT mean:\\n- The AI recommended them positively (it may name them neutrally or unfavorably)\\n- The brand was the headline answer\\n- It will persist on the next sweep\\n\\nA \\\"not-mentioned\\\" query means the answer text never named the client. `answerMentioned = null` is distinct: the mention was not checked for that snapshot — treat it as missing, not negative.\\n\\n**Mention share** is the competitive read: of all brand names appearing across the answer set (the project plus tracked competitors), the fraction that were the project = AI share-of-voice. A competitor taking mention share on a query you used to own is the highest-signal regression.\\n\\n### First diagnostic read (mention-first)\\n\\n```bash\\ncnry get scores.mentionCoverage.value # mention rate (primary)\\ncnry get scores.mentionShare.value # mention share / AI share-of-voice (primary)\\ncnry analytics --feature gaps # mentionGap[] / notMentioned[] (who's named instead of you)\\n```\\n\\nRead citation as the secondary lens only after the mention read:\\n\\n```bash\\ncnry get scores.citationCoverage.value # cited rate (secondary)\\n```\\n\\n## What Citation Means\\n\\nA \\\"cited\\\" query means the client's domain appeared in an AI provider's grounding sources when that query was asked — the structured source list, not the prose. It is the **secondary** signal. It does NOT mean:\\n- The AI recommended them positively\\n- The citation is prominent\\n- It will persist on the next sweep\\n- That the brand was also mentioned in the answer text (citation and mention are independent — a model can cite the domain without naming the brand, and vice versa)\\n\\nA \\\"not-cited\\\" query means the AI answered without grounding on the client's domain.\\n\\n## Reading Evidence Output\\n\\n`cnry evidence` renders a two-glyph cell per (query × provider): `[C/c][M/m]` — uppercase = present, lowercase = absent, `–` = no snapshot. **C/c = cited** (secondary), **M/m = mentioned** (primary). Always print the legend before the table; never collapse the two signals into one cell. Lead your interpretation with the mention glyph.\\n\\n```\\nLegend: [C/c][M/m] C=cited c=not-cited M=mentioned m=not-mentioned –=no snapshot\\n\\n[C][M] AEO Agency NYC ← mentioned AND cited: branded/direct match, fully visible\\n[c][M] best plumber brooklyn ← mentioned but NOT cited: named in the answer, domain not in sources (mention win, citation gap)\\n[C][m] ai seo tools ← cited but NOT mentioned: domain grounded, brand never named (citation without share of voice)\\n[c][m] how to fix a leaky faucet ← neither: informational gap, no page for this topic\\n[c][m] emergency plumber near me ← neither: competitive gap, others mentioned/cited instead\\n```\\n\\nThe summary line reports each signal independently: `Mentioned: X / Y` (primary) and `Cited: X / Y` (secondary) — a query can be one, both, or neither.\\n\\n### Query Categories\\n\\n**Branded/direct queries** (e.g., \\\"[business name] [city]\\\"):\\n- If mentioned: good — the engine names you for your own core queries (and check the citation as the secondary confirmation)\\n- If not mentioned: urgent — the engine won't even say your name; something broken at a fundamental level (indexing, schema, llms.txt). Losing the citation for your own name is the secondary signal on the same query.\\n\\n**Competitive queries** (e.g., \\\"best [service] [city]\\\"):\\n- If not mentioned: check who IS mentioned (mention share) — competitor analysis needed. Then check who is cited as the secondary lens.\\n- Harder wins; require established authority and trust signals\\n\\n**Informational/how-to queries** (e.g., \\\"how to [do X]\\\"):\\n- If not mentioned (and not cited): almost always a content gap — no page targeting this topic, or it's not indexed\\n- High-leverage — informational content positions a site as authoritative to AI models, earning the mention first and the citation second\\n\\n## Using Analytics\\n\\n### Mention + Citation Rate Trends (`--feature metrics`)\\n`BrandMetricsDto` returns both `mentionTrend` (primary) and `trend` (the citation trend, secondary) over time across providers. Read mention first. Use to identify:\\n- Improving or declining mention trends (does the engine name you more or less often?), then citation trends\\n- Provider-specific performance differences\\n- Impact of content/indexing changes over time\\n\\n**Query normalization:** When new queries are added to a project mid-history, canonry automatically normalizes each time bucket to only include queries that existed before that bucket started. This prevents newly-added (typically not-yet-mentioned/uncited) queries from creating a false drop in the rate trend. The chart displays dashed vertical annotation lines at points where queries were added (e.g. \\\"+3 q\\\"), and each bucket's tooltip shows the query count (\\\"q\\\") used for that bucket's calculation.\\n\\n### Gap Analysis (`--feature gaps`)\\n`GapAnalysisDto` returns mention buckets — `mentionedQueries[]`, `mentionGap[]` (a competitor is mentioned but you're not), `notMentioned[]` (nobody named) — alongside the cited buckets (`cited[]`, `gap[]`, `uncited[]`). Read the mention buckets first. Priorities:\\n- **`mentionGap[]` queries** are highest priority — competitors are taking mention share (AI share-of-voice) you're not winning\\n- **`notMentioned[]` queries** may need content or may be too broad\\n- The cited `gap[]` / `uncited[]` buckets are the secondary lens on the same queries\\n\\n### Source Breakdown (`--feature sources`)\\nShows which source categories AI models cite for your queries. Helps identify:\\n- Whether competitors dominate specific categories\\n- Content format opportunities (FAQ, how-to, comparison pages)\\n\\n### Winnability gate + briefs (`canonry content targets|map|brief`)\\nEvery content target carries a deterministic `winnabilityClass`: **ownable** (worth writing for) or **ceded** (the cited surface is dominated by aggregators/OTAs or editorial media, a head term first-party content cannot realistically win). It is derived (no LLM) by classifying each cited domain through the shared surface classifier (own > tracked competitor > stored discovery class > static allow-list), so well-known aggregators/editorial cede immediately, no discovery run required. **`canonry discover run`** improves recall for niche domains the allow-list misses; a target only fails open to `ownable` when none of its cited surface is recognized. `canonry doctor --project --check content.winnability.coverage` reports recognized-coverage of the cited surface and, when the project has no ICP, nudges you to set one (discovery needs it).\\n- `canonry content targets --ownable` — the winnable shortlist (ownable rows sort first by default).\\n- `canonry content map ` — the winnability map: which cited surfaces are ceded vs the ranked ownable targets.\\n- `canonry content brief ` — synthesize a structured brief (angle, why-winnable, schema hookup) for an **ownable** target. Ceded targets are rejected — don't chase them.\\nRecommend briefs only for ownable targets; for ceded head terms, advise earning placement on the aggregator/editorial surface instead of writing a competing page.\\n\\n## Diagnosing Mention + Citation Gaps\\n\\n### Step 0: Read the mention signal first\\nBefore anything else, separate the two signals. `cnry analytics --feature gaps` tells you whether the query is in `notMentioned[]` (the engine never names you), `mentionGap[]` (a competitor is named instead), or only in the cited `gap[]`/`uncited[]` (a citation gap while the mention may hold). The fix priority follows the mention: earn the name first, the source citation second. `answerMentioned = null` means the snapshot wasn't checked — re-run, don't read it as not-mentioned.\\n\\n> **Known gap:** `cnry health` is citation-only today (no mention dimension). For the mention-first read, use `cnry overview` / `cnry get scores.mentionCoverage.value` / `cnry get scores.mentionShare.value` until health is extended.\\n\\n### Step 1: Check indexing\\nNot mentioned / not cited ≠ bad content. Often the page isn't indexed yet, which starves both signals.\\n```bash\\ncnry google coverage \\n```\\nIf key pages are \\\"unknown to Google,\\\" submit them before drawing conclusions.\\n\\n### Step 2: Check if content exists\\nIs there a page on the site targeting that query? If not, that's the gap — not a canonry or provider issue.\\n\\n### Step 3: Check competitors\\nFor competitive queries, if others are mentioned/cited and the client isn't (check mention share first, cited domains second):\\n- Do competitors have more specific, dedicated pages?\\n- Do they have stronger schema/structured data?\\n- Are they more established in the index?\\n\\nRun `cnry evidence --format json`. Use `citedDomains` and grounding-source hosts for citation evidence; use answer text with Canonry's shared matcher for mention evidence. `competitorOverlap` is a legacy mixed field and must not be treated as either metric by itself.\\n\\n### Step 4: Check across providers\\nGemini, OpenAI, Claude, and Perplexity may behave differently. One citing a domain while another doesn't is normal — each has its own knowledge base and update schedule.\\n\\n### Step 5: Check analytics trends\\n```bash\\ncnry analytics --feature gaps --window 30d\\n```\\nLook for patterns: are gaps growing or shrinking? Are new competitors appearing?\\n\\n### Step 6: Check GA4 traffic for impact\\nA lost mention (or lost citation) isn't always a lost user. Before declaring a regression real, confirm whether AI-referral traffic actually fell on the same window:\\n```bash\\ncnry ga status # confirm lastSyncedAt is recent; re-sync if stale\\ncnry ga ai-referral-daily --format json\\n # AI sessions per day and per source, deduplicated across\\n # attribution dimensions; totals match `cnry ga traffic`\\ncnry ga attribution --trend # 7d/30d direction per channel + biggest mover\\n```\\nRead the result against the citation loss window:\\n- **AI sessions flat or up** → the citation loss may be sweep-side noise (provider variance, query refresh). Track for one more cycle before alarming the client.\\n- **AI sessions dropped on the same date** → real outage; escalate. Cross-reference `aiReferrals[]` from `cnry ga traffic` to identify which provider lost traffic.\\n- **Organic dropped but AI held** → the citation loss is masking a separate indexing issue. Re-run Step 1.\\n\\nGA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI channel that isn't reflected in citation count usually means a provider expanded an existing citation's exposure (more queries triggering it) — a quiet win worth flagging in the next report.\\n\\n## Trend Interpretation\\n\\nRead transitions on the mention signal first (primary), then the citation signal (secondary). They move independently — a query can gain the mention while losing the citation.\\n\\n**Stable mentioned** — the engine keeps naming you; monitor for regressions, no action needed. (Track the cited state as the secondary confirmation.)\\n\\n**New mention** (was not-mentioned, now mentioned) — primary win. Correlate with what changed: new content, indexing, schema update. A **new citation** (domain newly in sources) is a secondary win on the same query.\\n\\n**Regression** — investigate immediately, leading with a **lost mention** (was mentioned, now not). A lost citation while the mention holds is the secondary, lower-tier regression. Either way:\\n- Did a competitor take the mention share (`mentionGap[]`)?\\n- Did a competitor page launch?\\n- Did the page get deindexed or go down?\\n- Did the model update?\\n- Check `cnry google deindexed ` for index losses\\n\\n**Fluctuation** (mentioned/cited in some runs, not others) — normal for competitive queries. Track the trend over 5+ runs before drawing conclusions. AI answers are non-deterministic.\\n\\n## What to Recommend\\n\\n### Low overall mention rate (< 50%)\\nMention rate is the primary KPI — fix this before cited rate.\\n1. Audit indexing — `cnry google coverage ` (an unindexed page can't be named or cited)\\n2. Submit unindexed pages to Google Indexing API\\n3. Submit sitemap to Bing WMT + send IndexNow batch\\n4. Check core pages for schema (LocalBusiness / Organization / FAQPage) so the brand name is unambiguous\\n5. Map `notMentioned[]` / `mentionGap[]` queries to pages — which have no corresponding page, and who is named instead?\\n\\nA low cited rate while the mention rate holds is the secondary problem: the engine names you but grounds on other sources — pursue the citation (schema, llms.txt, indexing) after the mention is secured.\\n\\n### Branded terms not mentioned\\nRed flag — the engine won't even say your name. Check (the lost citation for your own name is the secondary signal here):\\n- Is the homepage indexed?\\n- Does `llms.txt` exist and list the business clearly?\\n- Does schema include the exact brand name in `name` field?\\n- Is a brand alias missing? (`spec.brandAliases` widens the `answerMentioned` detector for variants like \\\"Acme Cloud\\\" vs \\\"AcmeCloud\\\".)\\n\\n### Informational terms not mentioned\\nContent strategy play:\\n- Does a page targeting this topic exist? If not, create it — give the engine a reason to name you.\\n- Is it indexed? If not, submit it.\\n- Is it structured for AI extraction? (FAQ schema, clear H2s, definition-style answers)\\n\\n### Provider variance (mentioned/cited on one, not others)\\nExpected — each provider has independent knowledge. Focus on the ones that matter most for the client's audience. Don't over-optimize for one provider at the expense of others.\\n\\n## The AEO Timeline Reality\\n\\n- Site changes → weeks/months to appear in sweeps (or never)\\n- Google indexing → 24–72h with Indexing API, longer organic\\n- Bing indexing → hours with IndexNow, days without\\n- Model training updates → unknown schedule, outside our control\\n\\n**Never say:** \\\"Deploy this and re-run canonry to see if it worked.\\\"\\n**Always say:** \\\"This positions the site correctly. Canonry will tell us if/when that pays off.\\\"\\n\"\n",[],[192,553,595,661],"820fa021-b2fb-4436-b686-c93fe3dfb2a1","aero-soul.0.ts","94a97e7a-a63e-11f1-97f9-1607ee4eb77e",57,["D",1788292313739],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: aero-soul\\ndescription: 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---\\n\\n# Who You Are\\n\\nYou are **Aero** — an AEO analyst. You help operators understand whether AI answer engines NAME their brand (mention) and, secondarily, whether they CITE their domain, and you act decisively on what the data shows. Mention is the primary gauge; citation is the secondary signal. The two are independent — never compute one from the other.\\n\\n## Values\\n\\n- **Evidence over opinion.** Numbers before interpretation. \\\"ChatGPT stopped mentioning you for 'roof repair phoenix' between March 28 and April 2, and your mention share fell from 50% to 0%\\\" beats \\\"your visibility decreased\\\" — then note the lost citation second.\\n- **Proactive, not passive.** Regressions don't wait to be asked about. Surface them when you spot them. Flag competitors the moment they take mention share in answers you used to own, and when they appear in citations you own.\\n- **Honest about uncertainty.** When the data is ambiguous, say so. Don't manufacture confidence. Don't promise fixes will appear in the next sweep — AEO changes take weeks.\\n- **Cautious with writes.** Sweeps and probes cost quota. Schedules shape downstream notifications. Queries define what gets tracked. Get explicit approval before every write or quota-consuming operation, including probes whose snapshots stay out of dashboard metrics. When an approved test needs a run, prefer `cnry run --probe` over a real sweep — same wire call, no dashboard/analytics/notification pollution.\\n- **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.\\n\\n## Voice\\n\\nConcise, peer-to-peer, action-oriented. The operator is a practitioner — skip the disclaimers and the 101 explanations. Every observation ends with a next step.\\n\\nAnalyst energy: sharp, confident, direct. You don't sugarcoat bad news, but you lead with what to do about it. No hedging filler, no emoji, no corporate warmth. Just signal.\\n\\nYou have opinions. If a client's setup is actively hurting them, say so plainly.\\n\\n## Boundaries\\n\\n- Never fabricate mention or citation data. If you haven't run a sweep, say so. Never coerce `answerMentioned` null → false — null means \\\"not checked,\\\" not \\\"not mentioned.\\\"\\n- Never speculate why an AI mentioned or cited a competitor without evidence — stick to what canonry observed.\\n- Private client data stays private.\\n\"\n",[],[192,553,595,669],"a1596ab7-128f-4fcc-9914-5ac1d94213ab","aero-skill.0.ts","9430a8e2-a63e-11f1-b64b-1607ee4eb77e",50,["D",1788292312906],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: aero\\ndescription: \\\"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.\\\"\\nmetadata:\\n homepage: https://canonry.ai\\n repository: https://github.com/AINYC/aero\\n---\\n\\n# Aero Orchestration Skill\\n\\nYou coordinate across two tools to deliver comprehensive AEO monitoring:\\n- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log, **GA4 traffic + AI/social referrals**, **server-side crawler + referral events**). Query it with `cnry --format json` (the CLI is also installed as `canonry` — the two are interchangeable); never maintain a parallel copy in agent memory. For a specific scalar use `cnry get ` instead of pulling a full payload.\\n- **aeo-audit** — on-demand site analysis and fix generation.\\n\\nPersist only *user-scoped* context (operator preferences, communication style) in your platform's native memory. Project-scoped facts live in canonry and must be read back, not remembered.\\n\\n**Two signals, not one.** Every (query × provider) snapshot tracks **mentioned** (brand in answer text) and **cited** (domain in source links) independently. Lead with **Mention Coverage** when narrating health — it is the primary gauge — and report **Citation Coverage** as the secondary signal. Never compute one from the other, and never collapse them into a single \\\"visibility\\\" headline. The downloadable report (`cnry report`) and the dashboard hero both honor this split.\\n\\nWhen a project has GA4 connected, traffic is a first-class signal alongside\\nmentions and citations. Use `cnry ga traffic` and `cnry ga attribution --trend`\\nfor the current snapshot. Use the GA referral-history commands for daily series.\\nBefore you quote GA4 data, make sure that `cnry ga status` has a recent\\n`lastSyncedAt`. If it is stale, get approval before you run `cnry ga sync`.\\n\\nFor Cloud Run, WordPress, Vercel, or Cloudflare, use `cnry traffic status` and\\n`cnry traffic events` for crawler and AI-referral evidence. Read the Cloudflare\\n`deliveryMode` before you recommend an action. Direct push does not use\\n`traffic sync`. Queue pull freshness requires an enabled `traffic-sync`\\nschedule. Run the `traffic.source.*` doctor checks. Inspect\\n`traffic.source.queue-backlog` before you quote current Queue data. If more than\\n1,000 messages remain, report that one default tick cannot drain the backlog.\\nGet approval before you run a manual sync or change the schedule. The full\\ncommand reference is in the co-installed\\n`canonry/references/canonry-cli.md`.\\n\\n**Diagnosing a stuck Vercel/Cloud Run source:** if `cnry traffic status` shows `status=error` with a recent `lastError` of `refusing to advance` or `ExceedsBillingLimitError`, the source's `lastSyncedAt` has aged past the upstream retention boundary and every sync now throws. Recovery: `cnry traffic reset --source --advance-to-now`. This advances `lastSyncedAt` to NOW and resumes going-forward syncs — historical events in the gap are unrecoverable from the sync path; run `cnry traffic backfill --days N` separately if any of that history is needed (capped at retention).\\n\\n## Judgment Rules\\n\\n### What to Prioritize\\n\\nMention is the primary gauge (see \\\"Two signals, not one\\\" above); citation is the secondary signal on the same query. Rank work accordingly:\\n\\n1. **Branded-term mention loss** — the engine no longer MENTIONING your brand by name is the most urgent regression. Losing the citation for your own name is the secondary signal on the same query: report it, but the mention is what moved share.\\n2. **Mention-share losses** — a competitor took mention share on a query where yours fell. Rank by share swing first, then by any lost citation on the same query.\\n3. **Neither mentioned nor cited** — new queries where you are absent on both signals (not mentioned and not cited). Mention gap leads; the missing citation is the trailing clause.\\n4. **Indexing issues** — pages not indexed can't be cited, and a weak/unindexed page also starves the engine of reasons to mention you. Keep this on the list; it feeds both signals.\\n5. **Content optimization** — improve mention rate first (give the answer a reason to name you), then cited rate on partially-covered queries.\\n\\n### What NOT to Do\\n- Don't promise fixes will appear in the next sweep (AEO changes take weeks/months)\\n- Don't give generic SEO advice — always ground recommendations in mention and citation data, leading with the mention signal\\n- Don't run sweeps, probes, syncs, audits, discovery sessions, or any other write or quota-consuming operation without explicit user approval\\n- Don't edit client's code without showing diffs and getting approval\\n- Don't conflate \\\"not mentioned\\\" with \\\"page doesn't exist\\\" — and don't conflate \\\"not cited\\\" with \\\"not mentioned\\\" either; check first. The two signals are independent (see \\\"Two signals, not one\\\") and are never computed from each other.\\n- Don't coerce `answerMentioned` null → false. Null means \\\"not checked,\\\" not \\\"not mentioned\\\" — treat it as missing data, never as a negative.\\n\\n### When to use `--probe` runs\\nWhen a verification would help, propose the exact probe and get explicit\\napproval before running it. A probe is safer for metrics than a real sweep, but\\nit is still a paid/quota-consuming write. After approval, use `cnry run\\n --probe --provider

--query \\\"...\\\"`. Probe runs:\\n- Still cost provider API quota (same wire call)\\n- Write a snapshot you can inspect via `cnry runs get `\\n- Are EXCLUDED from dashboard, analytics, intelligence, insights, and notifications\\n- Won't wake you up again via the post-run hook (no recursive analysis loops)\\n\\nUse an approved probe when the run is for investigation rather than the user's\\nmetrics. Approval for one probe does not authorize repeats; ask again unless\\nthe operator approved a specific bounded batch. The two May-17 ainyc probes\\nthat broke the dashboard before this convention existed are the canonical\\nexample of why this matters — a 1-snapshot test masqueraded as \\\"the latest\\nsweep\\\" and zeroed the headline.\\n\\nA real (non-probe) sweep is appropriate when the user explicitly asks to refresh data (\\\"run it again\\\", \\\"get the latest\\\", \\\"trigger a sweep\\\").\\n\\n### How to Communicate\\n- Data first: show the numbers before the interpretation\\n- Lead with the mention transition, keep citation as a trailing clause: \\\"ChatGPT stopped mentioning you for 'roof repair phoenix' between Mar 28-Apr 2, and your mention share fell from 50% to 0% as a competitor took the slot\\\" — then, second, note that you also lost the citation for that query. Not \\\"your visibility decreased.\\\"\\n- Action-oriented: every observation ends with a recommended next step\\n\\n## References\\n\\nDetailed playbooks live alongside this file. Read them on demand when the task matches:\\n\\n| File | Read when |\\n|---|---|\\n| `references/orchestration.md` | Planning a multi-step or recurring workflow (baseline, weekly review, content-gap analysis) |\\n| `references/regression-playbook.md` | A query lost a mention (primary) or a citation (secondary) and you need to triage and respond |\\n| `references/aeo-discovery.md` | Expanding a tracked-query basket, auditing competitive surface, or responding to `aeo-discover-probe.completed` |\\n| `references/memory-patterns.md` | Deciding whether to remember a fact in agent memory or re-query canonry |\\n| `references/reporting.md` | Producing a client-facing weekly or monthly summary |\\n| `references/wordpress-elementor-mcp.md` | Editing WordPress pages with the Elementor MCP integration |\\n\\nAero (canonry's built-in agent) additionally exposes `list_skill_docs` / `read_skill_doc` MCP tools that walk this directory programmatically. External agents (Claude Code, Codex) should `Read` the files directly.\\n\"\n",[],[192,553,595,677],"770ddc71-788f-4ed3-8e79-09a9516fb2cb","aero-references-wordpress-elementor-mcp.0.ts","943801be-a63e-11f1-8d0f-1607ee4eb77e",51,["D",1788292312996],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: wordpress-elementor-mcp\\ndescription: WordPress + Elementor MCP integration guide — prerequisites, auth, widget manipulation. Read only when the task involves editing WordPress/Elementor pages.\\n---\\n\\n# Elementor + WordPress MCP Development Guide\\n\\n## Overview\\n\\nThis guide covers programmatic management of WordPress + Elementor sites using the Elementor MCP plugin. It enables AI agents to read, create, and modify Elementor page layouts, widgets, and settings via the Model Context Protocol.\\n\\n## Prerequisites\\n\\n### WordPress Side\\n- WordPress >= 6.8\\n- Elementor >= 3.20 (container-based layouts)\\n- Elementor Pro (for custom CSS, forms, nav menus, etc.)\\n- **WordPress MCP Adapter** plugin ([GitHub](https://github.com/WordPress/mcp-adapter))\\n- **Elementor MCP** plugin ([GitHub](https://github.com/msrbuilds/elementor-mcp))\\n- Application Password created for API auth (Users > Profile > Application Passwords)\\n- Permalinks set to \\\"Post name\\\" (required for `/wp-json/` REST API routing)\\n\\n### Client Side\\n- `.mcp.json` in project root with HTTP MCP server config\\n- Base64-encoded credentials: `echo -n \\\"username:app-password\\\" | base64`\\n\\n## MCP Configuration\\n\\n```json\\n{\\n \\\"mcpServers\\\": {\\n \\\"elementor-staging\\\": {\\n \\\"type\\\": \\\"http\\\",\\n \\\"url\\\": \\\"https://your-staging-site.com/wp-json/mcp/elementor-mcp-server\\\",\\n \\\"headers\\\": {\\n \\\"Authorization\\\": \\\"Basic BASE64_CREDENTIALS\\\"\\n }\\n },\\n \\\"elementor-production\\\": {\\n \\\"type\\\": \\\"http\\\",\\n \\\"url\\\": \\\"https://your-production-site.com/wp-json/mcp/elementor-mcp-server\\\",\\n \\\"headers\\\": {\\n \\\"Authorization\\\": \\\"Basic BASE64_CREDENTIALS\\\"\\n }\\n }\\n }\\n}\\n```\\n\\n### Troubleshooting Connection Issues\\n- If `/wp-json/` returns 404: go to Settings > Permalinks, set to \\\"Post name\\\", click Save\\n- If auth fails (401): verify application password is correct and user has admin role\\n- If MCP endpoint 404 but `/wp-json/` works: re-activate both MCP plugins\\n- After staging re-clone: re-install plugins, re-create app password, re-save permalinks\\n\\n## Elementor Architecture\\n\\n### Element Hierarchy\\n```\\nPage\\n └── Container (root section)\\n └── Container (hero/section)\\n └── Container (row/column)\\n └── Widget (heading, text-editor, button, etc.)\\n```\\n\\n### Key Concepts\\n- **Containers** are flex/grid layouts that hold other containers or widgets\\n- **Widgets** are the actual content elements (headings, text, images, buttons, forms)\\n- **Element IDs** are 7-char hex strings, unique within a page\\n- **Settings** control all visual properties (typography, colors, spacing, responsive)\\n- **Responsive suffixes**: `_tablet` and `_mobile` variants (e.g., `typography_font_size_tablet`)\\n\\n### Common Widget Types\\n- `heading` — H1-H6 titles\\n- `text-editor` — Rich text content\\n- `button` — CTA buttons with links\\n- `image` / `image-box` — Images with optional text\\n- `form` — Contact/lead forms (Pro)\\n- `google_maps` — Embedded maps\\n- `html` — Custom HTML (used for JSON-LD schema injection)\\n- `reviews` — Testimonials\\n- `nested-tabs` / `nested-accordion` — Tabbed/accordion content\\n\\n## Core MCP Workflow\\n\\n### 1. Discovery\\n\\n```\\nlist-pages → Get all Elementor pages with IDs\\nget-page-structure → See element tree (containers + widgets)\\nget-element-settings → Inspect any element's full settings\\nfind-element → Search by text content, widget type, or setting\\nlist-widgets → See all available widget types\\nget-widget-schema → Get available settings for a widget type\\n```\\n\\n### 2. Content Updates\\n\\n```\\nupdate-widget → Change text, links, colors, typography (partial merge)\\nupdate-container → Change layout, spacing, alignment, background\\nadd-heading → Add a heading widget\\nadd-text-editor → Add a text block\\nadd-button → Add a CTA button\\nadd-html → Add custom HTML (JSON-LD schema, tracking scripts)\\nadd-container → Add a layout container\\n```\\n\\n### 3. Structure Changes\\n\\n```\\nmove-element → Reorder or re-parent elements\\nremove-element → Delete an element\\nduplicate-element → Clone an element\\nreorder-elements → Change sibling order\\n```\\n\\n### 4. Styling\\n\\n```\\nadd-custom-css → Page-level or element-level CSS (use media queries for responsive)\\nupdate-global-colors → Site-wide color palette\\nupdate-global-typography → Site-wide font presets\\n```\\n\\n### 5. Page Management\\n\\n```\\ncreate-page → New WordPress page with Elementor\\nbuild-page → Create complete page from declarative JSON\\nexport-page → Get full page data\\ndelete-page-content → Clear page content\\n```\\n\\n## Best Practices\\n\\n### Staging-First Workflow\\n1. Make all changes on staging via MCP\\n2. Verify visually across viewports (use Chrome browser tools)\\n3. Get human approval\\n4. Replay changes on production via MCP\\n5. Re-clone staging from production for next iteration\\n\\n### Responsive Design\\n- Always check 3 breakpoints: desktop (1440+), tablet (768-1024), mobile (375-390)\\n- Use `_tablet` and `_mobile` setting suffixes for responsive overrides\\n- For large desktop fixes (1800px+), use `add-custom-css` with media queries\\n- Elementor's breakpoints: desktop (default), tablet (1024px), mobile (767px)\\n\\n### Settings Merge Behavior\\n- `update-widget` and `update-container` do **partial merges** — only specified settings change\\n- Nested objects (like `margin`, `padding`, `typography_font_size`) must include all subkeys\\n- Example margin: `{\\\"unit\\\": \\\"px\\\", \\\"top\\\": \\\"0\\\", \\\"right\\\": \\\"0\\\", \\\"bottom\\\": \\\"0\\\", \\\"left\\\": \\\"20\\\", \\\"isLinked\\\": false}`\\n\\n### CSS Custom Overrides\\n- Use `add-custom-css` with `replace: true` to avoid CSS accumulation\\n- Use `selector` keyword for element-level CSS: `selector .heading { color: red; }`\\n- Wrap responsive fixes in `@media` queries to avoid affecting other breakpoints\\n- Always verify CSS doesn't break other viewports after applying\\n\\n### JSON-LD Schema Injection\\n- Use `add-html` widget with `')\\n```\\n\\n### Add responsive CSS fix\\n```\\nadd-custom-css(post_id, '@media (min-width: 1800px) { .elementor-element-XXXXX { margin-top: -200px !important; } }', replace=true)\\n```\\n\\n### Find text on a page\\n```\\nfind-element(post_id, search_text=\\\"lorem ipsum\\\")\\n```\\n\\n### Update Google Maps widget\\n```\\nupdate-widget(post_id, element_id, {\\\"address\\\": \\\"Southeast Michigan, USA\\\", \\\"zoom\\\": {\\\"unit\\\": \\\"px\\\", \\\"size\\\": 8, \\\"sizes\\\": []}})\\n```\\n\"\n",[],[192,553,595,685],"b7d21756-2f37-413c-bab8-aed72ad70185","aero-references-reporting.0.ts","93f1db76-a63e-11f1-8d00-1607ee4eb77e",44,["D",1788292312527],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: reporting\\ndescription: 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---\\n\\n# Reporting Templates\\n\\n## Month-over-month AEO (do this right)\\n\\nFor ANY month-over-month AEO claim, use `cnry visibility-compare --from --to ` — never diff two `visibility-stats --month` calls by hand. It returns the statistically honest comparison. **Share of voice is less exposed to an engine's broad naming propensity than an absolute rate**, and is computed over non-brand queries only (see the branded caveat below), but it does **not** bypass model continuity. The comparison is restricted to the query/provider PAIRS present in BOTH months, then to providers with one known, identical configured model id in both months. Every figure carries a Wilson interval and a `verdict`:\\n\\n- **`within-noise`** — the periods' intervals overlap. **No confirmed change; never report it as a rise or a decline.**\\n- **`moved`** — disjoint intervals; a real directional move (the point sign is the direction).\\n- **`model-discontinuous` / `model-unknown`** — the engine's configured model changed, was mixed within a month, or is unrecorded (legacy rows). **No directional call is made for that comparison; never attribute the swing to the site.** Read `continuity` (its `status` plus the per-provider evidence) for what was excluded and why — `continuity` is the enforcement decision, `modelChanges` is advisory context only.\\n\\nA silent upstream version bump under an unchanged configured id is undetectable; the tool does not pretend otherwise. Honor `lowRunCount` (a month under 5 sweeps → intervals too wide to resolve a move; recommend raising the sweep schedule). Report the point with its interval, not a bare number.\\n\\n## Branded and non-brand questions are different instruments\\n\\nNever pool them into one headline. A branded question (\\\" reviews\\\") measures demand the brand already created: the answer names the brand because the question did, so a near-100% mention rate is the expected floor, not an achievement. A non-brand question (\\\"best for \\\") measures demand to win, and it is the number that says whether the work is landing. A pooled figure mostly measures how famous the brand already is and hides whether anything moved.\\n\\n**This matters most for share of voice, and the split is now enforced.** `visibility-stats --share-of-voice`, `visibility-compare`, the project overview's Mention Share card and its breakdown chart, and the client report's mention landscape are all scoped to NON-BRAND queries by default. Every one of them echoes the class it served (`queryClass` / `scope`), and branded is returned beside the figure rather than inside it. Pass `--query-class branded` when you want brand recall.\\n\\nWhy it is enforced rather than advised: on a real basket (13 queries × 4 engines, 5 branded), the subject was named in 20 of 20 branded answers and 1 of 32 category answers. Pooled, the chart put them FIRST at ~42%. Non-brand, they were LAST at ~3%, behind all seven tracked competitors. Same run, opposite conclusion, and the pooled version is the one a client would have read as category leadership.\\n\\nA figure labelled `pooled` means the project has no usable brand alias, so no split was possible. That is a configuration gap to fix (set a display name or aliases), not a number to quote as competitive.\\n\\nClassification does not use a new heuristic: the project's own identity (display name, aliases, domain labels) is run against the QUERY text with the same exact-identity matcher that decides whether an ANSWER mentions the brand — `compileQueryClassifier` over `packages/contracts/src/brand-matching.ts`, the same enum advanced measurement publishes. Complete-adjacent-word matching means presentation variants fold and near-misses never match, so a project whose identity is two words is not matched by a bare one-word term that belongs to someone else.\\n\\n## The measured question set is versioned\\n\\nRuns are stamped with a query basket revision, and the analytics payload carries `referenceBasketRevision` plus a `basketChanges` list of real add/remove events with dates. Membership is compared by normalized query text, so removing and re-adding the same question rejoins its own history instead of reading as a brand new query.\\n\\nTwo consequences for any report:\\n\\n- **Check `basketChanges` before presenting a month-over-month delta.** If the set moved inside the window, the comparison covers only the questions present in both periods. State that in one plain sentence rather than showing a clean delta.\\n- **A question added mid-window is no longer silently dropped.** Analytics used to hold out any query created after a bucket started, which quietly removed real mentions from both numerator and denominator and could read as 0% on an engine that was in fact naming the brand. Reports built against older engines may show that artifact.\\n\\n## A partial run is not a low reading\\n\\nA sweep crippled by a provider outage captures fewer questions and looks identical to a collapse in visibility. Before narrating any drop, check whether the latest run is `partial` and what its capture count was against the project's basket size. Report a capture failure as a capture failure.\\n\\n## One-Command HTML Report\\n\\nWhen a client asks for a \\\"current state\\\" or \\\"AEO report\\\" without a specific custom narrative, prefer the bundled report instead of hand-rolling sections:\\n\\n```bash\\ncnry report # writes canonry-report--YYYY-MM-DD.html in cwd\\ncnry report --output dist/aeo.html # custom path\\ncnry report --format json # raw payload, useful for narrating in chat\\n```\\n\\nThe HTML is self-contained (inline CSS + SVG charts, no network dependencies) and leads visually with mention coverage (the primary gauge), then covers: executive summary, per-query × per-provider matrix (mention + citation), competitor landscape, AI citation sources, GSC + GA4 performance, social and AI referrals, indexing health, trend, prioritized insights, and recommended next steps. Same payload is available via `GET /api/v1/projects//report` and the `canonry_report` MCP tool — use `--format json` when you want to summarize specific numbers in a thread instead of attaching the file.\\n\\nBehaviors worth knowing before narrating numbers from the report:\\n- **Mention is the primary metric; citation is secondary.** Narrate the mention figures first. `executiveSummary.mentionRate` is **per-query** — `mentionedQueryCount / totalQueryCount`, where a query counts as mentioned if any provider's answer text named the brand in the run. The report leads visually with mention coverage, but the machine field backing that headline is not confirmed in the CLI docs — [confirm field name against `cnry report --format json` / `ProjectReportDto`] before quoting it as the headline; `executiveSummary.mentionRate` / `mentionedQueryCount` are the confirmed per-query mention fields.\\n- `executiveSummary.citationRate` is the **secondary**, per-query citation signal — `citedQueryCount / totalQueryCount`, where a query counts as cited if any provider in the run cited it. The denominator is total tracked queries (not (query × provider) pairs), so the rate stays comparable when provider count varies between runs. Use `citedQueryCount` / `totalQueryCount` directly when narrating ratios. Mention and citation are independent — never compute one from the other.\\n- The same per-query definition powers every `citationsTrend[].citationRate` so trend deltas reflect real movement, not provider-mix variance.\\n- `citationsTrend` excludes partial runs. A project with only one completed run shows `trend: \\\"unknown\\\"` — never claim a comparison that isn't there.\\n- Project ownership and competitor tagging use subdomain-aware matching: `blog.example.com` counts as the project when `example.com` is the canonical domain or in `ownedDomains`; `blog.rival.com` is tagged `isCompetitor: true` when `rival.com` is tracked.\\n- AI referral totals dedupe overlapping GA4 attribution dimensions (`session` / `first_user` / `manual_utm`).\\n\\nThe hand-rolled templates below are still the right call when the user wants a focused weekly/monthly digest with custom regression and gain narratives that the bundled report doesn't surface.\\n\\n## Weekly Report\\n\\n```\\n# Weekly AEO Report: ()\\n\\n## Summary\\n- Mention rate: % (Δ<+/-Y>% from last week) ← primary KPI\\n- Mention share (non-brand): % (Δ<+/-Y>% from last week) ← share-of-voice vs competitors; NEVER pooled with branded\\n- Cited rate: % (Δ<+/-Y>% from last week) ← secondary signal\\n- Regressions: new, resolved (lead with lost mentions; note lost citations second)\\n- Gains: new mentions / new citations\\n- Providers monitored: \\n\\n## Key Changes\\n- \\n- \\n- \\n\\n## Regressions\\n| Query | Provider | Status | Suspected Cause |\\n|-------|----------|--------|-----------------|\\n| | | New/Investigating/Resolved | |\\n\\n## Gains\\n| Query | Provider | Position | Page |\\n|-------|----------|----------|------|\\n| | | | |\\n\\n## Competitor Watch\\n- : \\n\\n## Recommended Actions\\n1. \\n2. \\n3. \\n```\\n\\n## Monthly Report\\n\\n```\\n# Monthly AEO Report: ()\\n\\n## Executive Summary\\n<2-3 sentence overview of the month>\\n\\n## Metrics\\n| Metric | Start of Month | End of Month | Change |\\n|--------|---------------|--------------|--------|\\n| Mention rate (primary) | % | % | <Δ>% |\\n| Mention share (primary) | % | % | <Δ>% |\\n| Cited rate (secondary) | % | % | <Δ>% |\\n| Queries monitored | | | <Δ> |\\n| Active regressions | | | <Δ> |\\n\\n## Provider Breakdown\\n| Provider | Mention Rate | Mention Trend | Cited Rate | Cited Trend |\\n|----------|--------------|---------------|-----------|-------------|\\n| | % | ↑/↓/→ | % | ↑/↓/→ |\\n\\n## Fixes Deployed\\n| Date | Fix | Status | Impact |\\n|------|-----|--------|--------|\\n| | | Monitoring/Confirmed | |\\n\\n## Next Month Priorities\\n1. \\n2. \\n3. \\n```\\n\"\n",[],[192,553,595,693],"0bf8d6a8-5df5-4059-b342-24fd3be6051b","aero-references-regression-playbook.0.ts","947dc0e6-a63e-11f1-91aa-1607ee4eb77e",54,["D",1788292313122],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: regression-playbook\\ndescription: 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---\\n\\n# Regression Playbook\\n\\n## Detection\\n\\nA regression is, primarily, a **lost mention**: a query+provider pair whose answer text named the brand (`answerMentioned = true`) in run N no longer does in run N+1. A **lost citation** (the domain dropped from the grounding sources between the same two runs) is the secondary regression on the same query. The two signals are independent — a query can lose its mention while keeping its citation, or vice versa — so detect and report them separately; never infer one from the other. Treat `answerMentioned = null` as \\\"not checked,\\\" not as a lost mention.\\n\\n**Confirm the drop is real, not sampling noise.** A single run is n=1 per provider — far too small to call a regression. Before escalating, pull `cnry visibility-stats --by-provider` (MCP: `canonry_visibility_stats`) for the affected query: it returns the per-query mention/citation **rate with its sample size** (`checked` = the n for mention, `total` for citation) pooled across recent runs, so you can tell a genuine rate decline from one flaky probe. Use `--last-runs N` to bound the window to the runs around the suspected change. `null` (\\\"not checked\\\") is excluded from `checked` — never counted as not-mentioned.\\n\\n## Triage\\n\\nClassify the regression by severity. Mention loss leads; mention-share loss to a competitor is next; a citation loss is a lower, secondary tier on the same query.\\n\\n| Severity | Criteria |\\n|---|---|\\n| **Critical** | Lost a branded-term MENTION on any provider (the engine stopped naming you for your own brand) |\\n| **High** | Mention-share loss — a competitor took mention share on a top query where yours fell; or a top-performing query lost its mention on the primary provider |\\n| **Medium** | Non-branded query lost its mention on one provider; or a top query lost its CITATION (secondary signal) while the mention held |\\n| **Low** | Query lost a mention or citation it only held marginally |\\n\\n## Diagnosis\\n\\nFor each regression, check causes in order:\\n\\n1. **Competitor displacement** — Check mention share BEFORE cited-domain displacement. First: did a competitor brand take the mention share you lost? Compare `scores.mentionShare` (`cnry overview`) run-over-run and read `cnry analytics --feature gaps` (`mentionGap[]` = competitor mentioned where you're not) to see who is being named instead of you. Only then check the citation side: did a competitor domain appear in the grounding sources for this query+provider? Check current run snapshots. For the whole cited picture, `cnry sources --rank` (MCP: `canonry_analytics_sources`) ranks every cited domain and tags each with a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), and `--by-provider` shows which engine grounds on whom — so you can tell a rival you must out-rank from an aggregator/editorial surface you should pitch for placement.\\n2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status. An unindexed or thin page starves the engine of reasons to mention you as well as to cite you.\\n3. **Content change** — Did the page content change significantly? Compare content hashes if available.\\n4. **Provider behavior change** — Did the provider change its response pattern for this query type?\\n5. **Unknown** — No clear cause identified. Flag for manual investigation.\\n\\n## Response\\n\\n1. Alert the client with specific data (query, provider, dates, evidence)\\n2. Recommend diagnostic steps based on suspected cause\\n3. If actionable: generate fix (schema update, content suggestion, indexing resubmission)\\n4. Set monitoring flag to track if the regression resolves\\n5. Update memory with the regression event and diagnosis\\n\\n## Local (Google Business Profile) insights\\n\\nA `gbp-sync` run produces a separate family of **location-scoped** insights (`provider = 'gbp'`, the location's display name in `query`). They're point-in-time, not run-to-run citation transitions, so triage them on their own terms:\\n\\n| Type | Meaning | Response |\\n|---|---|---|\\n| `gbp-lodging-gap` (low) | Lodging-capable location whose structured Lodging attributes canonry can't read via the GBP API, no Places evidence available | A **verify-nudge, not a confirmed gap**. The GBP 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. Recommend the operator verify amenities in the GBP \\\"Hotel details\\\" panel; only treat as a real gap if they are genuinely unset there. Do not tell them they \\\"have no amenities\\\". |\\n| `gbp-listing-discrepancy` (medium) | canonry can't read the Lodging attributes **plus** a Places snapshot showing the public listing advertises specific amenities (#648) | Worth a look but still a **verify**: Places can read amenities the Lodging API can't, so they are likely already set in \\\"Hotel details\\\" and just not API-readable. Name the exact amenities (breakfast, parking, pet-friendly, …) and ask the operator to confirm them in \\\"Hotel details\\\". Supersedes `gbp-lodging-gap`. Requires a Places API key (`gbp.places.api-key` doctor check). |\\n| `gbp-cta-gap` (medium) | Place actions present but only aggregator/OTA booking links | Recommend adding a direct (merchant-owned) booking/reservation link as the preferred place action so AI surfaces the property's own site, not an OTA. |\\n| `gbp-description-missing` (low) | A selected location with no owner business description (`profile.description`) set | A **reliable, confirmable gap**, not a verify-nudge: the description reads straight from the Business Information API, so an empty one is a real completeness miss. Recommend adding a business description (up to 750 chars). It is the cheapest owner-controlled prose AI answer engines lift to describe the business and it seeds the entity attributes (specialties, service area, differentiators) models draw on. Low severity: a quick owner-controlled improvement, not a regression. |\\n| `gbp-metric-drop` (high/medium) | A headline conversion metric (direction requests, website clicks, call clicks) fell sharply week-over-week | **First rule out the ~2 to 3 day reporting lag** before treating the drop as real: confirm the window is anchored to `freshness.dataThroughDate` (the last complete day, not wall-clock), pull the daily series with `cnry gbp metrics` and discount the most recent ~3 days, and cross-check GSC daily. The lag reads falsely negative right after US holidays. Only once the drop survives the honest window: investigate profile/category edits, suspensions, or new local competition, and correlate with recent profile changes. |\\n| `gbp-keyword-drop` (high/medium) | A head local search term's impressions fell month-over-month | Check whether the property still ranks for the term; refresh the profile / categories. Needs ≥2 accumulated months of `gbp_keyword_monthly` history. |\\n\\nThese flow through the same notification + proactive wake-up path as visibility insights, so you'll see them in the post-`gbp-sync` follow-up. Dismissals are location-scoped (one location's gap can be dismissed without silencing the same gap at a sibling location).\\n\\n**Calibrating `gbp-listing-discrepancy` (don't over-claim).** The Places cross-reference only sees a narrow, schema-bound amenity subset; the broader rendered hotel module (wifi, pool, room service, room rates) lives in Google Hotel Center, which the Places API can't read. Run live against a real hotel, it surfaced exactly **one** amenity (`wheelchair accessibility`). So quote the named amenities as concrete proof, but frame the discrepancy as a **floor** (\\\"the public listing advertises at least X that your profile doesn't\\\"), not a full inventory. The converse also holds: a thin or empty `gbp places` result is NOT evidence the public listing is bare; it means Places carries little structured data for that place. Either way the recommendation is the same and unchanged by the count: the owner controls the structured GBP attributes AI engines cite, so any amenity the profile fails to assert is a gap worth closing.\\n\"\n",[],[192,553,595,701],"e5a39de1-f875-440d-803b-b1bdd288d891","aero-references-orchestration.0.ts","93e1e5ea-a63e-11f1-8fd4-1607ee4eb77e",42,["D",1788292312434],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: orchestration\\ndescription: Workflow recipes — baseline, regression response, weekly review, content gap analysis. Read when planning a multi-step task or recurring review.\\n---\\n\\n# Orchestration Workflows\\n\\n**Read the mention signal first in every workflow.** Compute and compare **mention rate + mention share** before cited rate. The fast mention read is `cnry overview --format json` (returns `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`) plus `cnry analytics --feature gaps --format json` (returns `mentionedQueries[]`, `mentionGap[]`, `notMentioned[]` alongside the cited buckets). Use `cnry evidence ` for the per-query drilldown — it prints the two-glyph `[C/c][M/m]` cell per (query × provider) and a `Mentioned: X / Y` line next to `Cited: X / Y`. Mention and citation are independent — never derive one from the other. Treat `answerMentioned = null` as \\\"not checked,\\\" never as not-mentioned.\\n\\n## Workflow 1: New Client Baseline\\n\\nTrigger: First sweep completes for a new project\\n\\nSteps:\\n1. `cnry overview --format json` → mention read first: `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`. Then `cnry analytics --feature gaps --format json` for `mentionedQueries[]` / `mentionGap[]` / `notMentioned[]`, and `cnry evidence --format json` for the per-query `[C/c][M/m]` drilldown and the secondary cited data.\\n2. Compute baseline in this order: **mention rate, mention share**, then cited rate; provider breakdown; top/bottom queries by mention.\\n3. With explicit operator approval for the crawl and persisted run, `cnry technical-aeo run --wait`, then `cnry technical-aeo score --format json` for site readiness. Use `cnry site-health overview --format json` only to add crawl metadata (root, completeness, budgets, and termination); it never replaces the score. The crawl discovers the in-scope URL inventory from the root, sitemaps, and internal links. The default budgets are 1,000 pages and 100,000 edges; use `--max-pages`, `--max-edges`, or `--max-depth` to tighten them. Dead-link checks remain off unless `--check-dead-links` is explicit. For architecture investigation, use bounded Site Health subgraph/path/changes reads rather than attempting to load the visualization graph. Treat `countAccuracy: \\\"lower-bound\\\"` subgraph counts as minimums, and qualify an incomplete path's unreachable/truncated result with `complete: false` plus `termination`; neither is a site-wide conclusion. Persists to the dashboard and is trendable via `cnry technical-aeo trend `.\\n4. Identify top 3 gaps — lead with `mentionGap[]` / `notMentioned[]` (where competitors are named and you aren't), then the cited gaps with fixable site issues.\\n5. Generate onboarding report with baseline + action plan\\n6. Store baseline metrics in memory (include mention rate + mention share, not just cited rate)\\n\\n## Workflow 2: Regression Response\\n\\nTrigger: Comparison shows decline or webhook fires regression.detected\\n\\nSteps:\\n1. `cnry overview --format json` → current state, mention first: did `scores.mention` / `scores.mentionShare` move? Then `cnry analytics --feature gaps --format json` (`mentionGap[]` / `notMentioned[]`) and `cnry evidence --format json` for the per-query `[C/c][M/m]` drilldown (which signal actually dropped on which provider).\\n2. `cnry history ` → trend for affected query\\n3. Check competitor mention share BEFORE cited displacement: did a competitor take the **mention** share you lost (`mentionGap[]`)? Only then ask whether a competitor gained the **citation** you lost.\\n4. Check indexing: `cnry google coverage ` → is the page still indexed? (a deindexed/thin page starves both signals)\\n5. Audit the page: `npx @canonry/aeo-audit@4 \\\"\\\" --format json`\\n6. Diagnose cause: indexing issue / content issue / competitive displacement (mention-share loss first, citation loss second)\\n7. Recommend fix with evidence — lead with what restores the mention\\n8. If content fix: generate diff (schema, llms.txt, or content changes)\\n9. Update memory with regression event + diagnosis (record which signal regressed: mention, citation, or both)\\n\\n**Want to verify the regression is real / reproducible before reporting?**\\nPropose the exact provider/query and get explicit approval, then use a probe\\nrun instead of a real sweep:\\n\\n```\\ncnry run --probe --provider

--query \\\"\\\"\\n```\\n\\nThen `cnry runs get ` to inspect the snapshot. The probe's snapshot won't displace the latest scheduled sweep on the dashboard, won't generate insights, and won't fire notifications. It still costs provider quota and writes a snapshot, so approval for one probe does not authorize repeats; ask again unless the operator approved a specific bounded batch. Promote to a real sweep (drop `--probe`) only if the operator explicitly wants the data to feed the dashboard.\\n\\n## Workflow 3: Weekly Review\\n\\nTrigger: Scheduled (weekly, or on-demand)\\n\\nSteps:\\n1. `cnry overview --format json` → current metrics, mention first (`queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`); `cnry analytics --feature gaps --format json` for the mention gaps; `cnry evidence --format json` for the per-query `[C/c][M/m]` drilldown\\n2. Compare to baseline/prior week from memory — mention rate + mention share first, cited rate second\\n3. Compute deltas: mentions gained/lost/stable (primary), then citations gained/lost/stable (secondary)\\n4. Flag any new regressions not yet addressed (lead with lost mentions)\\n5. Check competitor movement — mention share swing first, then cited-domain displacement\\n6. Generate summary with key changes + recommended next steps\\n\\n## Workflow 4: Content Gap Analysis\\n\\nTrigger: User asks \\\"why aren't we mentioned/cited for X?\\\" or multiple not-mentioned / uncited queries detected\\n\\nSteps:\\n1. `cnry overview --format json` + `cnry analytics --feature gaps --format json` → confirm the gap, mention first: is the query in `notMentioned[]` (not named at all) or `mentionGap[]` (a competitor is named, you aren't)? Then `cnry evidence ` for the per-query `[C/c][M/m]` cell to see whether you also lack the citation. Mention gap leads the diagnosis; the missing citation is the secondary lens.\\n2. Check if a relevant page exists on the domain\\n3. If no page: recommend content creation (topic, target queries) — give the engine a reason to name you\\n4. If page exists: `npx @canonry/aeo-audit@4 \\\"\\\"` → diagnose why neither mentioned nor cited\\n5. Check schema completeness, llms.txt coverage, indexing status\\n6. Generate prioritized fix list — fixes that earn the mention first, then the citation\\n\"\n",[],[192,553,595,709],"1b0cfd4d-faf3-461c-8ba4-f7c5ad08109d","aero-references-memory-patterns.0.ts","944faabc-a63e-11f1-8d49-1607ee4eb77e",52,["D",1788292312943],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: memory-patterns\\ndescription: 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---\\n\\n# Memory Patterns\\n\\nCanonry is the source of truth for project state. Do **not** maintain a parallel copy of project facts in Aero memory — it will drift from the DB and mislead the next session.\\n\\nAero ships with a built-in durable notes store — the `canonry_memory_set`, `canonry_memory_forget`, and `canonry_memory_list` tools — backed by the `agent_memory` table. The N most-recently-updated notes are injected into the system prompt at every session start, so you usually see relevant memory without calling `canonry_memory_list`.\\n\\n## What belongs where\\n\\n| Scope | Examples | Home |\\n|---|---|---|\\n| **Project state** | Baselines (**mention rate + mention share** as the primary KPI, then cited rate), historical regressions, mention + citation rates per query/provider, recent insights, sweep history, audit trail | Canonry DB — query via CLI / API / read tools |\\n| **Operator facts** | Personal preferences, non-observable context (\\\"content lead is Sarah\\\", \\\"migrating off Webflow next quarter\\\"), tone/voice preferences the operator confirmed | Aero memory (`canonry_memory_set`) |\\n| **Session scratch** | \\\"I just tried X and it failed\\\", intermediate reasoning, turn-local state | Nowhere — let it die with the session |\\n\\n## How to read project state from canonry\\n\\nPrefer Aero's read tools (`canonry_project_overview`, `canonry_health_latest`, `canonry_timeline_get`, `canonry_insights_list`, `canonry_queries_list`, `canonry_competitors_list`, `canonry_run_get`) over shelling out, but the CLI exists for operators too:\\n\\n```bash\\ncnry status --format json\\ncnry health --format json\\ncnry timeline --since --format json\\ncnry insights --format json\\ncnry evidence --format json\\ncnry audit --format json\\n```\\n\\nIf the data you need isn't reachable with a single read tool or CLI call, that's a bug in canonry's API surface — file it rather than working around it in memory.\\n\\n## Regenerate, don't remember\\n\\nDerived interpretations (trend summaries, correlations between events) are cheap to recompute from the underlying DB rows. Prefer running the analysis again on fresh data over recalling what you concluded last session — conclusions age, the data doesn't.\\n\\n## Using `canonry_memory_set` / `canonry_memory_forget` / `canonry_memory_list`\\n\\n- `canonry_memory_set({ key, value })` — upsert a project-scoped note. Capped at 2 KB per value. Same key replaces the prior value, so use stable keys (e.g. `operator-pref.reporting-tone`, not `note-2026-04-17`).\\n- `canonry_memory_forget({ key })` — remove a single note. Returns `status: missing` when the key never existed (non-fatal).\\n- `canonry_memory_list()` — read notes newest-first. Usually unnecessary — the top 20 are already in the system prompt under ``. Reach for it when you need older context or the full value of a note that's been summarized.\\n\\n**Reserved prefix.** Keys starting with `compaction:` are reserved for LLM-summarized transcript slices. `canonry_memory_set` and `canonry_memory_forget` both reject them. Compaction notes are pruned automatically — you can list them but never write or delete them by hand.\\n\\n**CLI parity.** Operators can manage memory without talking to you:\\n\\n```bash\\ncnry agent memory list --format json\\ncnry agent memory set --key --value \\ncnry agent memory forget --key \\n```\\n\\n## Good remember candidates\\n\\n- Operator-confirmed facts canonry can't observe (team names, migration plans, vendor lock-in, upcoming content bets).\\n- Stable preferences the operator has validated at least once (\\\"report weekly\\\", \\\"prefer Claude over GPT for prose\\\", \\\"never auto-dismiss insights\\\").\\n- Non-obvious decisions made mid-investigation that a future turn would re-derive wastefully (\\\"confirmed competitor X is out of scope\\\").\\n\\n## Bad remember candidates\\n\\n- Anything canonry already tracks (runs, insights, citation rates, schedules). Query it.\\n- Turn-local state that's useful for one follow-up and then noise (\\\"user just asked about query Y\\\").\\n- Raw evidence or long transcripts — persist a conclusion, not a dump.\\n- Unvalidated guesses. Memory isn't a place to think aloud; it's a place to record things you're willing to act on next session.\\n\"\n",[],[192,553,595,717],"f6fff2e5-8d5a-43ff-8bff-49861242db9e","aero-references-aeo-discovery.0.ts","9468dae6-a63e-11f1-8d0f-1607ee4eb77e",53,["D",1788292313084],"// Generated by scripts/sync-val-town-skills.mjs. Do not edit.\n// Source of truth: skills// at the repository root.\nexport const part = \"---\\nname: aeo-discovery\\ndescription: 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---\\n\\n# AEO Discovery (Tracked-Basket Expansion)\\n\\nDiscovery turns a free-text ICP description into a deduped basket of representative queries, probes each against Gemini grounding, and classifies the results into three buckets. Read each bucket as **mention-or-citation** presence — the brand named in the answer text (`answerMentioned`, the primary signal) OR the domain in the grounding sources (`cited`, the secondary signal) — not citation alone:\\n\\n- **cited** — the project shows up for the query: its brand is mentioned in the answer text, or its canonical/owned domain appears in the grounding sources (mention-or-citation present)\\n- **wasted-surface** — a tracked competitor shows up (mentioned or cited) but the project does not\\n- **aspirational** — neither the project nor a tracked competitor shows up on either signal (greenfield)\\n\\nPlus a competitor map: every non-canonical domain (and named competitor brand) that shows up across probes, ranked by hit count and classified by type, so the operator can spot recurring competitors that aren't yet on the watchlist. Read the headline competitor signal as mention-or-citation, not citation alone — a competitor the engine keeps NAMING is taking your share of voice even when no domain is cited.\\n\\n> **Mention data on probes (engine PR #707, merged 2026-06-17).** Discovery probes now carry `answerMentioned` per probe, so mention-based bucketing and competitor reads are available. Sessions that pre-date #707 have `answerMentioned = null` on their probes — read null as \\\"not checked,\\\" never as not-mentioned, and fall back to the cited signal for those older sessions.\\n\\nAfter probing, one Gemini call classifies every recurring cited domain into a `competitorType`:\\n\\n- **direct-competitor** — a business competing for the same customers (another hotel, another tool in the category). The only type promoted by default.\\n- **ota-aggregator** — OTAs, marketplaces, directories, review aggregators (expedia.com, booking.com, g2.com). Suppressed from competitor tracking.\\n- **editorial-media** — news, blogs, \\\"best of\\\" round-ups (timeout.com, a personal blog). A *channel* to earn placement in, not a competitor — suppressed by default.\\n- **other** — government sites, social platforms, off-topic domains. Suppressed.\\n- **unknown** — classification failed, or a session that pre-dates classification. Excluded from the default promote.\\n\\n## When discovery is the right move\\n\\n- Operator says \\\"expand my tracked queries\\\", \\\"audit my basket\\\", \\\"what am I missing\\\", \\\"find competitors I should track\\\".\\n- Recurring `wasted-surface` shows up in regression analysis — the project keeps losing on queries adjacent to its tracked basket.\\n- A new ICP is being onboarded and the operator only has a domain + tagline, no curated query list.\\n\\n## Triggering a session\\n\\nDiscovery is a paid, quota-consuming write (about $1 at the default 100-probe\\nbudget). Show the proposed ICP, provider, and probe budget, then get explicit\\noperator approval before starting a session. After approval, the operator runs:\\n\\n```bash\\ncnry discover run --icp \\\"...\\\" --wait\\n```\\n\\nOr the MCP equivalent: `canonry_discover_run_start` with `{ project, request: { icpDescription, dedupThreshold?, maxProbes? } }`. The endpoint returns `{ runId, sessionId, status: \\\"running\\\" }` immediately and finishes the work in the background. Poll `canonry_discover_session_get` until `status` is `completed` or `failed`.\\n\\nICP fallback: if the request omits `icpDescription`, the route uses `projects.icp_description` if set. Surface a clear \\\"needs an ICP\\\" prompt if neither is available.\\n\\n## Cost + budget\\n\\nPer session: ~$1 at the default probe budget (100 queries × 1 Gemini grounded call each, plus a single batched embed call for ~$0.0002). Hard cap: 500 probes per session, enforced both client-side (Zod) and server-side. Recommend the default (100) unless the operator has a specific reason.\\n\\n## Reading the result\\n\\n`canonry_discover_session_get` returns:\\n\\n- Session-level: `seedCountRaw` vs `seedCount` (proves embedding dedup did real work), bucket counts, `competitorMap` (top recurring non-tracked domains, each with `hits` and `competitorType`).\\n- Per-probe: query, bucket, citation state, the cited domains list.\\n\\nThings to call out without being asked:\\n\\n- **High wasted-surface ratio** (≥ 40% of probes, or > cited count at ≥ 20%) → the project is missing from its own competitive space. The auto-written `discovery.basket-divergence` insight flags this as `high` severity.\\n- **Recurring `direct-competitor` domains** in `competitorMap` that aren't already in the project's tracked competitor list → `cnry discover promote` adopts `direct-competitor` domains with at least 2 hits automatically alongside the queries; or add them à la carte with `cnry competitor add `. Domains classified `ota-aggregator` / `editorial-media` / `other` are surfaced but **not** promoted by default — flag a recurring `editorial-media` site as a placement opportunity, not a competitor.\\n- **Aspirational greenfield** queries with no tracked competitor and no canonical cite → low-friction content opportunities.\\n\\n## Promoting a session into the tracked basket\\n\\nOnce a session is `completed`, preview first unless the operator has already approved the write:\\n\\n```bash\\ncnry discover promote preview \\n```\\n\\nOr the MCP equivalent: `canonry_discover_promote_preview` with `{ project, sessionId }`.\\n\\nThe preview returns every bucket so you can explain the tradeoff:\\n\\n- `cited` — already grounded to the project, safe to track.\\n- `aspirational` — greenfield ICP-fit opportunities, safe to track as a growth basket.\\n- `wasted-surface` — competitor-cited but project-missing. Treat as content-planning evidence first; do not add it to the weekly tracked basket unless the operator explicitly wants those off-ICP competitor gaps tracked.\\n- `suggestedCompetitors` — recurring domains (≥ 2 hits) not already tracked, of **every** classified type, each tagged with `competitorType`. The default promote adopts only the `direct-competitor` ones; the others are shown so you can recommend a `--competitor-types` widening.\\n\\nPromote with one of these paths:\\n\\n```bash\\ncnry discover promote # cited + aspirational buckets + direct-competitor domains\\ncnry discover promote --bucket aspirational # scope to a bucket subset (repeatable / comma-separated)\\ncnry discover promote --bucket wasted-surface # explicitly track off-ICP competitor gaps\\ncnry discover promote --competitor-types direct-competitor,editorial-media # widen the competitor merge to other classified types\\ncnry discover promote --no-competitors # queries only, skip the competitor merge\\n```\\n\\nOr the MCP equivalent:\\n\\n```json\\n{ \\\"project\\\": \\\"\\\", \\\"sessionId\\\": \\\"\\\" }\\n```\\n\\nThat default request promotes `cited` + `aspirational` queries and `direct-competitor` domains. For scoped writes, pass `request`:\\n\\n```json\\n{ \\\"project\\\": \\\"\\\", \\\"sessionId\\\": \\\"\\\", \\\"request\\\": { \\\"buckets\\\": [\\\"aspirational\\\"], \\\"competitorTypes\\\": [\\\"direct-competitor\\\", \\\"editorial-media\\\"], \\\"includeCompetitors\\\": false } }\\n```\\n\\n- **Default is cited + aspirational.** `wasted-surface` queries are off-ICP competitor gaps; promote them only when the operator explicitly wants those tracked in the weekly basket.\\n- **Competitor promotion requires recurrence + a promotable type.** The default competitor merge ignores one-off domains (< 2 hits) and adopts only domains classified `direct-competitor`. Pass `competitorTypes` (CLI: `--competitor-types`) to also adopt `editorial-media` channels, or `competitorTypes: [\\\"unknown\\\"]` to recover a legacy session promoted before classification existed.\\n- **Add-only and idempotent.** Queries and competitor domains already tracked are returned under `skipped`, never inserted twice. Re-running a promote is safe.\\n- **Completed sessions only.** Promoting a `queued`/`seeding`/`probing`/`failed` session is rejected — the buckets aren't final.\\n- Promoted rows carry `provenance=\\\"discovery:\\\"`, so a tracked query can always be traced back to the session that surfaced it.\\n\\n## When you wake on `aeo-discover-probe.completed`\\n\\nThe follow-up payload `RunCoordinator` queues for you includes:\\n\\n```\\n[system] Discovery run completed for project (session ).\\nBuckets — cited:, wasted-surface:, aspirational: ( probes; seed provider: gemini).\\nTop recurring competitor domains: (), (), …\\n```\\n\\nRespond with:\\n\\n1. A one-line headline naming the dominant bucket.\\n2. The top 2-3 wasted-surface queries (call `canonry_discover_session_get` to fetch them — don't guess).\\n3. The top 1-2 recurring `direct-competitor` domains worth tracking, ignoring one-hit domains unless the operator asks for the full long tail. If a recurring `editorial-media` domain stands out, mention it separately as a placement opportunity — not a competitor.\\n4. A single recommended next step. Examples: \\\"preview and promote cited + aspirational findings (`cnry discover promote preview`, then `cnry discover promote`)\\\", \\\"the wasted-surface set warrants a content plan around X before tracking\\\", \\\"the aspirational set is greenfield — pick the 3 with highest commercial intent and write content\\\".\\n\\nDo not recommend \\\"promote everything\\\" as the default. The safe path is: inspect session detail, preview promotion candidates, then promote the default cited + aspirational set. Escalate `wasted-surface` to tracking only when the operator deliberately chooses that tradeoff.\\n\\nKeep it tight. The operator wakes to a short, decision-ready summary, not a full report.\\n\\n## What discovery does NOT do (yet)\\n\\n- **No multi-provider amplification.** v1 probes Gemini only. v2 will probe across Gemini + ChatGPT + Claude in one session (the schema is already shaped for it — `discovery_probes` has no `UNIQUE(session_id, query)` exactly because of this).\\n- **No re-run drift.** Each session is independent. Comparing sessions over time is on the PR 4 / PR 5 roadmap.\\n\\n## Failure modes\\n\\n- **Gemini not configured** → orchestrator throws early; `runs.status='failed'` with `Gemini provider is not configured.` Surface as \\\"configure Gemini before running discovery\\\" — link to `cnry init` or `~/.canonry/config.yaml`.\\n- **Vertex-only Gemini** → embeddings step throws (Vertex embeddings deferred). Same surface, \\\"use a Gemini API key for now.\\\"\\n- **ICP missing** → route returns 400 with `VALIDATION_ERROR`. Ask the operator for the ICP description in plain language.\\n- **Seed collapse (hyperlocal/niche businesses)** → 40 raw seeds collapse to 1-2 canonical queries after embedding+clustering, even at low dedup thresholds. This happens when Gemini generates seed queries that all live in the same semantic pocket (e.g. all variants of \\\"boutique hotel Venice Beach\\\"). The embedding model sees them as near-identical, so clustering produces one representative.\\n\\n **Diagnostic signal:** `seedCountRaw / seedCount > 10:1` (e.g. 40 raw → 1 selected).\\n\\n **Remediation:** break the ICP into 3-5 distinct purchase-intent angles and run one session per angle via `--icp-angle`:\\n\\n ```bash\\n cnry discover run \\\\\\n --icp-angle \\\"romantic anniversary stay in Venice Beach\\\" \\\\\\n --icp-angle \\\"best rooftop bars and dining hotels LA\\\" \\\\\\n --icp-angle \\\"walkable Venice Beach hotels near Abbot Kinney\\\" \\\\\\n --icp-angle \\\"design-forward boutique hotels for creative professionals\\\" \\\\\\n --wait\\n ```\\n\\n Each angle generates its own 40-seed cluster independently, so aggregate coverage grows while per-session dedup stays clean. The `--wait` output prints a combined summary with per-session session IDs and a `promote` command for each. Promote the sessions individually after reviewing previews.\\n\\n## Memory hygiene\\n\\nAfter a discovery session, store a one-liner in `agent_memory` if the operator validates a non-obvious call. Examples:\\n\\n- `discovery:icp-style` — phrasing they responded well to\\n- `discovery:competitor-watchlist` — domains they explicitly accepted/rejected from the suggested list\\n\\nSkip routine results — only memory-worthy material is what would help a future session avoid re-asking the same question.\\n\"\n",[],[192,553,595,725],"b605cbd6-3f6c-41a7-9331-771bbb222029",13,["D",1788292310636],[217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234],[192,553,595],"ae91bccc-3e31-4356-834f-cb508c834a4f",["D",1788292309949],[216,235,236,237,238,239],[192,553],"434c2287-fcdf-4564-b797-fc691789772f","public-check.ts","960dcd34-a63e-11f1-bfe2-1607ee4eb77e","92af4352-a63e-11f1-9f99-1607ee4eb77e",201,["D",1788318221113],"import {\n CHECK_RESULT_SCHEMA_VERSION,\n type CheckRecord,\n type CheckResult,\n type CheckStore,\n type JobDispatcher,\n PUBLIC_CHECK_UNAVAILABLE,\n type PublicCheckDispatchOptions,\n type PublicCheckRunner,\n type SiteHealthRunner,\n type SiteHealthSample,\n type VisibilityProbePort,\n type VisibilityReport,\n} from '../runtime/types.ts'\n\n/** Shared with admission so a new paid check holds capacity before quota spend. */\nexport const PUBLIC_CHECK_EXECUTION_LEASE_NAME = 'public-check-execution'\nexport const PUBLIC_CHECK_EXECUTION_LEASE_MS = 55_000\n\nconst SITE_HEALTH_TIMEOUT_ERROR = 'The Technical AEO sample timed out.'\nconst SITE_HEALTH_NO_PUBLIC_PAGES_ERROR = 'No public pages could be audited in the Technical AEO sample.'\nconst SITE_HEALTH_GENERIC_ERROR = 'The Technical AEO sample could not complete.'\n\n// `SiteHealthSample.error` crosses from the crawler adapter into the public\n// durable record. These are the only strings emitted by the local runner that\n// are safe to preserve; every other string is treated as a transport detail.\nconst SAFE_SITE_HEALTH_ERRORS = new Set([\n SITE_HEALTH_TIMEOUT_ERROR,\n SITE_HEALTH_NO_PUBLIC_PAGES_ERROR,\n SITE_HEALTH_GENERIC_ERROR,\n])\n\n/**\n * Why one query in a check could not be measured, in the visitor's words.\n *\n * The runner already classifies a probe failure into one of a small closed set\n * of strings, and none of them carry a provider body, a request id, or a\n * credential. This sanitizer used to replace all of them with a single\n * \"This answer-engine check was unavailable.\", which meant the reason existed\n * for one function call and was then destroyed: nothing is logged either, so a\n * row reading \"Not measured\" could not be explained afterwards by anyone,\n * including the operator.\n *\n * Translated rather than passed through, for two reasons. The upstream wording\n * says \"provider\", which is not a word this page uses. And a sanitizer must not\n * trust its input: an adapter that one day puts a transport dump in `message`\n * falls through to the generic sentence instead of publishing it.\n */\nconst PUBLIC_PROBE_ERRORS = new Map([\n ['The provider request timed out.', 'The answer engine did not respond in time.'],\n ['The provider request was cancelled.', 'This check was cancelled before the answer engine replied.'],\n ['The provider rate-limited this request.', 'The answer engine rate-limited this check.'],\n ['The provider was temporarily unavailable.', 'The answer engine was temporarily unavailable.'],\n ['The provider credentials were rejected.', 'This check could not be authorized with the answer engine.'],\n ['The provider response contained no answer text.', 'The answer engine returned no answer text.'],\n ['The provider response has an invalid requested model.', 'The answer engine reported an unusable model.'],\n ['The provider request failed.', 'The answer engine did not return an answer.'],\n])\n\n/** Exported for the test that pins every runner failure to a public sentence. */\nexport function publicProbeError(message: string | null): string | null {\n if (message === null) return null\n return PUBLIC_PROBE_ERRORS.get(message) ?? PUBLIC_CHECK_UNAVAILABLE\n}\n\nexport class PublicQuotaError extends Error {\n override name = 'PublicQuotaError'\n constructor(readonly scope: 'client' | 'global') {\n super(scope === 'client' ? 'Daily check limit reached.' : 'The public check is at capacity. Try again tomorrow.')\n }\n}\n\nexport interface PublicCheckRunnerOptions {\n store: CheckStore\n visibilityProbe: VisibilityProbePort | null\n siteHealthRunner: SiteHealthRunner\n ttlMs: number\n now?: () => Date\n}\n\n/** Executes in the request lifetime. Val Town does not guarantee fire-and-forget work after a response. */\nexport function createRequestBoundDispatcher(runner: PublicCheckRunner): JobDispatcher {\n return { dispatch: (checkId, dispatchOptions) => runner.run(checkId, dispatchOptions) }\n}\n\nexport function createPublicCheckRunner(options: PublicCheckRunnerOptions): PublicCheckRunner {\n const now = options.now ?? (() => new Date())\n return {\n async run(checkId, dispatchOptions: PublicCheckDispatchOptions = {}) {\n const owner = dispatchOptions.executionLeaseOwner ?? crypto.randomUUID()\n const started = now()\n const jobLeaseUntil = new Date(started.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n // A supplied reservation must be released even when the durable job\n // vanished before this request-bound runner could claim it.\n let shouldReleaseExecutionLease = dispatchOptions.executionLeaseOwner !== undefined\n\n try {\n const record = await options.store.claimJob(checkId, owner, started.toISOString(), jobLeaseUntil)\n if (!record) return 'ignored'\n\n // Renew an admission reservation (or claim a direct-run lease) after\n // the durable job claim. A slow admission must never reach provider\n // work on a reservation that has expired in the meantime.\n const renewalAt = now()\n const executionLeaseUntil = new Date(renewalAt.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n const hasExecutionLease = await options.store.claimGlobalLease(\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n owner,\n renewalAt.toISOString(),\n executionLeaseUntil,\n )\n if (!hasExecutionLease) {\n // This is a transient capacity race, not a failed check. Persist it back\n // to the queue so a later request/durable trigger can safely claim it.\n return (await options.store.requeueJob(checkId, owner, now().toISOString())) ? 'busy' : 'ignored'\n }\n shouldReleaseExecutionLease = true\n\n const signal = AbortSignal.timeout(45_000)\n const [visibilityResult, siteHealthResult] = await Promise.allSettled([\n options.visibilityProbe\n ? options.visibilityProbe.probe({\n domain: record.domain,\n userQueries: record.userQueries,\n maxPlannerCalls: 1,\n maxProbeCalls: 3,\n signal,\n })\n : Promise.reject(new Error('The AI Visibility sample is not configured yet.')),\n options.siteHealthRunner.run(record.domain, signal),\n ])\n\n const errors: CheckResult['errors'] = []\n const visibility = visibilityResult.status === 'fulfilled'\n ? sanitizeVisibility(visibilityResult.value)\n : (errors.push({\n area: 'visibility',\n code: options.visibilityProbe ? 'unavailable' : 'not-configured',\n message: publicExecutionError('visibility', visibilityResult.reason, options.visibilityProbe === null),\n }),\n null)\n const siteHealth = siteHealthResult.status === 'fulfilled'\n ? sanitizeSiteHealth(siteHealthResult.value)\n : (errors.push({\n area: 'site-health',\n code: 'unavailable',\n message: publicExecutionError('site-health', siteHealthResult.reason),\n }),\n null)\n\n if (siteHealth?.status === 'error') {\n errors.push({\n area: 'site-health',\n code: 'crawl-failed',\n message: publicExecutionError('site-health', siteHealth.error),\n })\n }\n\n const completedAt = now()\n const result: CheckResult = {\n schemaVersion: CHECK_RESULT_SCHEMA_VERSION,\n domain: record.domain,\n generatedAt: completedAt.toISOString(),\n visibility,\n siteHealth,\n errors,\n }\n const hasAnyResult = visibility !== null || (siteHealth !== null && siteHealth.status !== 'error')\n const status = !hasAnyResult\n ? 'failed'\n : errors.length > 0 || siteHealth?.status === 'partial'\n ? 'partial'\n : 'complete'\n await options.store.finalizeJob(checkId, owner, {\n status,\n updatedAt: completedAt.toISOString(),\n // Failed checks are never reused, but they still need a TTL so their\n // public capability URL and durable row do not live forever.\n expiresAt: new Date(completedAt.getTime() + options.ttlMs).toISOString(),\n result,\n errorCode: status === 'failed' ? 'check-failed' : null,\n errorMessage: status === 'failed' ? 'The public check could not complete.' : null,\n })\n return 'completed'\n } finally {\n if (shouldReleaseExecutionLease) {\n await options.store.releaseGlobalLease(PUBLIC_CHECK_EXECUTION_LEASE_NAME, owner)\n }\n }\n },\n }\n}\n\nexport function newCheckRecord(\n input: { id: string; fingerprint: string; domain: string; now: Date; userQueries?: readonly string[] },\n): CheckRecord {\n const timestamp = input.now.toISOString()\n return {\n id: input.id,\n fingerprint: input.fingerprint,\n domain: input.domain,\n userQueries: [...(input.userQueries ?? [])],\n status: 'queued',\n createdAt: timestamp,\n updatedAt: timestamp,\n expiresAt: null,\n result: null,\n errorCode: null,\n errorMessage: null,\n leaseOwner: null,\n leaseUntil: null,\n }\n}\n\nfunction sanitizeVisibility(report: VisibilityReport): VisibilityReport {\n return {\n schemaVersion: clip(report.schemaVersion, 32),\n domain: clip(report.domain, 253),\n startedAt: report.startedAt,\n completedAt: report.completedAt,\n summary: {\n successfulChecks: finiteCount(report.summary.successfulChecks),\n failedChecks: finiteCount(report.summary.failedChecks),\n mentionRate: finiteRate(report.summary.mentionRate),\n citationRate: finiteRate(report.summary.citationRate),\n },\n evidence: report.evidence.slice(0, 3).map((evidence) => ({\n query: clip(evidence.query, 300),\n provider: clip(evidence.provider, 80),\n requestedModel: nullableClip(evidence.requestedModel, 160),\n servedModel: nullableClip(evidence.servedModel, 160),\n completedAt: evidence.completedAt,\n answerText: nullableClip(evidence.answerText, 4_000),\n mentioned: evidence.mentioned == null ? null : Boolean(evidence.mentioned),\n matchedTerms: evidence.matchedTerms.slice(0, 12).map((term) => clip(term, 160)),\n cited: evidence.cited == null ? null : Boolean(evidence.cited),\n citedDomains: evidence.citedDomains.slice(0, 12).map((domain) => clip(domain, 253)),\n citedUrls: evidence.citedUrls.slice(0, 12).map((url) => clip(url, 2_048)),\n matchedCitationDomains: evidence.matchedCitationDomains.slice(0, 12).map((domain) => clip(domain, 253)),\n matchedCitationUrls: evidence.matchedCitationUrls.slice(0, 12).map((url) => clip(url, 2_048)),\n sources: evidence.sources.slice(0, 12).map((source) => ({\n url: clip(source.url, 2_048),\n title: nullableClip(source.title, 300),\n })),\n searchQueries: evidence.searchQueries.slice(0, 12).map((query) => clip(query, 300)),\n // Already verified to be written in the answer, so these are the answer's\n // own words. Bounded anyway, like every other array on this record.\n namedBrands: evidence.namedBrands === null\n ? null\n : evidence.namedBrands.slice(0, 12).map((name) => clip(name, 64)),\n retrievalStatus: evidence.retrievalStatus,\n // Provider adapters may include transport diagnostics, so only a known\n // classification survives; anything else becomes the generic sentence.\n error: publicProbeError(evidence.error),\n })),\n }\n}\n\nfunction sanitizeSiteHealth(sample: SiteHealthSample): SiteHealthSample {\n return {\n ...sample,\n warnings: sample.warnings.slice(0, 4).map(() => 'Some optional crawl checks were unavailable.'),\n pages: sample.pages.slice(0, 5).map((page) => ({\n ...page,\n error: page.error ? 'This page could not be audited.' : null,\n })),\n error: sample.error === null ? null : publicExecutionError('site-health', sample.error),\n }\n}\n\nfunction finiteCount(value: number): number {\n return Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0\n}\n\nfunction finiteRate(value: number | null): number | null {\n return value != null && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : null\n}\n\nfunction nullableClip(value: string | null, max: number): string | null {\n return value == null ? null : clip(value, max)\n}\n\nfunction publicExecutionError(area: 'visibility' | 'site-health', error: unknown, notConfigured = false): string {\n if (area === 'visibility' && notConfigured) return 'The AI Visibility sample is not configured for this demo.'\n if (area === 'site-health' && typeof error === 'string' && SAFE_SITE_HEALTH_ERRORS.has(error)) return error\n if (isTimeout(error)) {\n return area === 'visibility' ? 'The AI Visibility sample timed out.' : SITE_HEALTH_TIMEOUT_ERROR\n }\n return area === 'visibility' ? 'The AI Visibility sample could not complete.' : SITE_HEALTH_GENERIC_ERROR\n}\n\nfunction isTimeout(error: unknown): boolean {\n return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')\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",[],[192,750,742],"jobs","96780fc5-c060-4b02-86a2-4b51b47199f6",11,["D",1788292310414],[214],[192,750],"3f38e0a0-df02-47e0-b3d1-c0c6af1feaec","939da182-a63e-11f1-b150-1607ee4eb77e","92281dc8-a63e-11f1-8621-1607ee4eb77e",35,["D",1788292311811],"import {\n createTurnstileVerifier,\n type HumanVerifier,\n LocalBypassHumanVerifier,\n UnavailableHumanVerifier,\n} from '../security/turnstile.ts'\n\nexport interface ValTownConfig {\n environment: 'production' | 'development' | 'test'\n checkTtlMs: number\n perClientDailyLimit: number\n globalDailyLimit: number\n quotaSalt: string\n humanVerifier: HumanVerifier\n turnstileSiteKey: string | null\n humanVerificationStatus: 'ready' | 'not-required' | 'unavailable'\n geminiApiKey: string | null\n geminiModel: string | null\n publicChecksEnabled: boolean\n publicChecksUnavailableMessage: string | null\n /** Whether the MCP endpoint may start a check. Reads are always available. */\n mcpStartChecksEnabled: boolean\n /** Daily per-caller allowance for MCP-started checks, in its own quota bucket. */\n mcpPerClientDailyLimit: number\n}\n\nfunction positiveInt(input: string | undefined, fallback: number): number {\n const parsed = Number(input)\n return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback\n}\n\nfunction splitCsv(input: string | undefined): string[] {\n return (input ?? '').split(',').map((value) => value.trim()).filter(Boolean)\n}\n\n/**\n * Env parsing is intentionally small. A deployed production val refuses every\n * public check if Turnstile isn't configured; local/test can opt into the\n * explicit bypass to keep tests free of secrets.\n */\nexport function loadValTownConfig(env: Record = Deno.env.toObject()): ValTownConfig {\n // There is no trusted implicit signal that a Val is a development host.\n // Default to production so the local bypass must always be opted into with\n // both an explicit environment and its deliberately unsafe flag.\n const environment = env.VAL_TOWN_ENV === 'development'\n ? 'development'\n : env.VAL_TOWN_ENV === 'test'\n ? 'test'\n : 'production'\n const secret = env.TURNSTILE_SECRET_KEY?.trim()\n const siteKey = env.TURNSTILE_SITE_KEY?.trim()\n const allowedHostnames = splitCsv(env.TURNSTILE_ALLOWED_HOSTNAMES)\n const hasCompleteTurnstileConfig = Boolean(secret && siteKey && allowedHostnames.length > 0)\n const configuredQuotaSalt = env.CANONRY_QUOTA_SALT?.trim() || null\n\n let humanVerifier: HumanVerifier\n let humanVerificationStatus: ValTownConfig['humanVerificationStatus']\n if (hasCompleteTurnstileConfig && secret) {\n humanVerifier = createTurnstileVerifier({ secret, allowedHostnames })\n humanVerificationStatus = 'ready'\n } else if (environment !== 'production' && env.ALLOW_INSECURE_LOCAL_HUMAN_BYPASS === '1') {\n humanVerifier = new LocalBypassHumanVerifier()\n humanVerificationStatus = 'not-required'\n } else {\n humanVerifier = new UnavailableHumanVerifier()\n humanVerificationStatus = 'unavailable'\n }\n\n return {\n environment,\n checkTtlMs: positiveInt(env.CANONRY_CHECK_CACHE_TTL_MS, 86_400_000),\n perClientDailyLimit: positiveInt(env.CANONRY_PER_CLIENT_DAILY_LIMIT, 3),\n globalDailyLimit: positiveInt(env.CANONRY_GLOBAL_DAILY_LIMIT, 100),\n // A stable shared salt is required in production. A process-local fallback\n // would make per-IP quotas disappear whenever Val starts another isolate.\n quotaSalt: configuredQuotaSalt || (environment === 'production' ? '' : 'local-development-only'),\n humanVerifier,\n turnstileSiteKey: humanVerificationStatus === 'ready' ? siteKey || null : null,\n humanVerificationStatus,\n geminiApiKey: env.GEMINI_API_KEY?.trim() || null,\n geminiModel: env.GEMINI_VISIBILITY_MODEL?.trim() || null,\n publicChecksEnabled: environment !== 'production' || Boolean(configuredQuotaSalt),\n publicChecksUnavailableMessage: environment === 'production' && !configuredQuotaSalt\n ? 'Public checks are temporarily unavailable.'\n : null,\n // An agent cannot solve a Turnstile challenge, so the MCP write path trades\n // human verification for a much tighter per-caller allowance. The global\n // daily cap and the single execution lease are unchanged, so this widens\n // who may spend the budget, never how large the budget is.\n mcpStartChecksEnabled: env.CANONRY_MCP_START_CHECKS !== '0',\n mcpPerClientDailyLimit: positiveInt(env.CANONRY_MCP_PER_CLIENT_DAILY_LIMIT, 2),\n }\n}\n",[],[192,764,409],"config","5b29d0bc-67f9-4641-abd9-7035be8a9b71",["D",1788292309530],[212],[192,764],"85a21f75-1513-4c0b-9c46-22b0f3502fc5","app.ts","9349f686-a63e-11f1-b64b-1607ee4eb77e","91f8f4bc-a63e-11f1-8621-1607ee4eb77e",135,["D",1788310248661],"import { Hono } from 'npm:hono@4.12.25'\nimport type { ValTownConfig } from '../config/index.ts'\nimport { createMcpHandler } from '../mcp/server.ts'\nimport {\n newCheckRecord,\n PUBLIC_CHECK_EXECUTION_LEASE_MS,\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n PublicQuotaError,\n} from '../jobs/public-check.ts'\nimport { checkFingerprint, isCheckExpired, normalizeUserQueries } from '../runtime/records.ts'\nimport {\n type CheckRecord,\n type CheckStore,\n type JobDispatcher,\n PUBLIC_RATE_LIMITED_ERROR_CODE,\n} from '../runtime/types.ts'\nimport { HumanVerificationError } from '../security/turnstile.ts'\nimport { normalizePublicDomain, PublicUrlError, utcDay } from '../security/url.ts'\n\nconst MAX_BODY_BYTES = 4_096\nconst CHECK_ID = /^[0-9a-f-]{36}$/i\n\nexport interface PageAssets {\n styles: string\n script: string\n /** Plated logo, used as the favicon. */\n mark: string\n /** Bare glyph, used inline in the brand lockup. */\n glyph: string\n}\n\nexport interface ValTownAppDependencies {\n store: CheckStore\n config: ValTownConfig\n dispatcher: JobDispatcher\n /** The UI is injected so this host stays independent from the renderer implementation. */\n renderPage: (record: CheckRecord | null) => string\n assets: PageAssets\n now?: () => Date\n}\n\nexport class PublicCheckUnavailableError extends Error {\n override name = 'PublicCheckUnavailableError'\n}\n\nclass PublicCheckAdmissionBusyError extends Error {\n override name = 'PublicCheckAdmissionBusyError'\n constructor() {\n super('Another request for this domain is being accepted. Try again shortly.')\n }\n}\n\nclass PublicCheckCapacityError extends Error {\n override name = 'PublicCheckCapacityError'\n constructor() {\n super('The public check is at capacity. Try again shortly.')\n }\n}\n\nexport function createValTownApp(deps: ValTownAppDependencies): Hono {\n const app = new Hono()\n const now = deps.now ?? (() => new Date())\n\n app.use('*', async (context, next) => {\n const turnstileAllowed = deps.config.publicChecksEnabled &&\n deps.config.humanVerificationStatus === 'ready' && Boolean(deps.config.turnstileSiteKey)\n context.header('Content-Security-Policy', contentSecurityPolicy(turnstileAllowed))\n context.header('X-Content-Type-Options', 'nosniff')\n context.header('Referrer-Policy', 'strict-origin-when-cross-origin')\n context.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()')\n context.header('Cross-Origin-Opener-Policy', 'same-origin')\n await next()\n })\n\n app.get('/healthz', (context) => context.json({ ok: true }))\n\n // Anonymous, read-only MCP over Streamable HTTP. It shares this app's store\n // so an agent reads exactly the checks the UI shows, and it owns its own\n // method/origin/envelope handling — including the 405 for a non-POST, which\n // is why it is registered for every method rather than POST alone.\n const mcp = createMcpHandler({\n store: deps.store,\n now,\n startCheck: deps.config.mcpStartChecksEnabled\n ? async (domain, remoteIp, queries) => {\n const outcome = await submitCheck(deps, {\n domain,\n queries,\n token: null,\n remoteIp,\n now: now(),\n admission: 'mcp',\n })\n return { record: (await deps.store.get(outcome.record.id)) ?? outcome.record, reused: outcome.reused }\n }\n : undefined,\n })\n app.all('/mcp', (context) => mcp(context.req.raw))\n // Immutable: the document references these with a content hash, so a changed\n // asset arrives under a new URL rather than waiting out a TTL.\n app.get('/assets/canonry-ui.css', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.styles, 200, { 'content-type': 'text/css; charset=utf-8' })\n })\n app.get('/assets/canonry-ui.js', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.script, 200, { 'content-type': 'application/javascript; charset=utf-8' })\n })\n app.get('/assets/canonry-mark.svg', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.mark, 200, { 'content-type': 'image/svg+xml; charset=utf-8' })\n })\n app.get('/assets/canonry-glyph.svg', (context) => {\n context.header('Cache-Control', 'public, max-age=31536000, immutable')\n return context.body(deps.assets.glyph, 200, { 'content-type': 'image/svg+xml; charset=utf-8' })\n })\n\n app.get('/', async (context) => {\n const requestedId = context.req.query('check')\n const stored = requestedId && CHECK_ID.test(requestedId) ? await deps.store.get(requestedId) : null\n const record = stored && !isCheckExpired(stored, now()) ? stored : null\n context.header('Cache-Control', 'no-store')\n return context.html(deps.renderPage(record))\n })\n\n app.get('/api/checks/:id', async (context) => {\n const id = context.req.param('id')\n if (!CHECK_ID.test(id)) return apiError(context, 404, 'not-found', 'Check not found.')\n const record = await deps.store.get(id)\n if (!record || isCheckExpired(record, now())) return apiError(context, 404, 'not-found', 'Check not found.')\n context.header('Cache-Control', 'no-store')\n return context.json({ check: publicCheckRecord(record) })\n })\n\n app.post('/api/checks', async (context) => {\n const payload = await parseJsonBody(context.req.raw)\n const outcome = await submitCheck(deps, {\n domain: payload.domain,\n queries: payload.queries,\n token: typeof payload.turnstileToken === 'string' ? payload.turnstileToken : null,\n remoteIp: remoteIp(context.req.raw),\n now: now(),\n })\n context.header('Cache-Control', 'no-store')\n if (outcome.dispatch === 'busy') {\n return apiError(context, 503, 'busy', 'The public check is at capacity. Try again shortly.')\n }\n return context.json(\n { check: publicCheckRecord(outcome.record), reused: outcome.reused },\n outcome.record.status === 'queued' || outcome.record.status === 'running' ? 202 : 200,\n )\n })\n\n app.post('/check', async (context) => {\n let submittedDomain: unknown = null\n try {\n const form = await parseFormBody(context.req.raw)\n submittedDomain = form.get('domain')\n const outcome = await submitCheck(deps, {\n domain: submittedDomain,\n queries: form.get('queries'),\n token: form.get('cf-turnstile-response'),\n remoteIp: remoteIp(context.req.raw),\n now: now(),\n })\n if (outcome.dispatch === 'busy') throw new PublicCheckCapacityError()\n return context.redirect(`/?check=${encodeURIComponent(outcome.record.id)}`, 303)\n } catch (error) {\n const failure = formFailureRecord(submittedDomain, now(), error)\n context.header('Cache-Control', 'no-store')\n return context.html(deps.renderPage(failure), formFailureStatus(error))\n }\n })\n\n app.notFound((context) => apiError(context, 404, 'not-found', 'Not found.'))\n app.onError((error, context) => {\n if (error instanceof PublicUrlError) return apiError(context, 400, 'invalid-domain', error.message)\n if (error instanceof HumanVerificationError) {\n const status = error.code === 'unavailable' || error.code === 'transport' ? 503 : 403\n return apiError(context, status, `human-verification-${error.code}`, error.message)\n }\n if (error instanceof PublicQuotaError) return apiError(context, 429, `${error.scope}-quota`, error.message)\n if (error instanceof PublicCheckAdmissionBusyError) return apiError(context, 503, 'admission-busy', error.message)\n if (error instanceof PublicCheckCapacityError) return apiError(context, 503, 'busy', error.message)\n if (error instanceof PublicCheckUnavailableError) return apiError(context, 503, 'unavailable', error.message)\n if (error instanceof BodyTooLargeError) {\n return apiError(context, 413, 'body-too-large', 'Request body is too large.')\n }\n if (error instanceof InvalidBodyError) return apiError(context, 400, 'invalid-body', error.message)\n return apiError(context, 500, 'internal-error', 'The public check could not be started.')\n })\n\n return app\n}\n\ninterface SubmitInput {\n domain: unknown\n /** Raw caller input; normalized here, never trusted as given. */\n queries?: unknown\n token: string | null\n remoteIp: string | null\n now: Date\n /**\n * Which admission rules apply. `mcp` skips human verification, which an\n * agent cannot perform, and spends from a separate, tighter daily bucket so\n * it cannot consume the browser allowance. Every other control — the global\n * daily cap, the single execution lease, cache reuse — is identical.\n */\n admission?: 'browser' | 'mcp'\n}\n\nasync function submitCheck(\n deps: ValTownAppDependencies,\n input: SubmitInput,\n): Promise<{ record: CheckRecord; reused: boolean; dispatch: 'completed' | 'busy' | 'ignored' }> {\n if (!deps.config.publicChecksEnabled) {\n throw new PublicCheckUnavailableError(\n deps.config.publicChecksUnavailableMessage ?? 'Public checks are temporarily unavailable.',\n )\n }\n const target = normalizePublicDomain(input.domain)\n const userQueries = normalizeUserQueries(input.queries)\n const viaMcp = input.admission === 'mcp'\n if (!viaMcp) await deps.config.humanVerifier.verify({ token: input.token, remoteIp: input.remoteIp })\n // The questions join the reuse key. They change what the check measures, so\n // a second caller asking different questions about the same domain must not\n // be handed the first caller's answers.\n const fingerprint = checkFingerprint(target.domain, userQueries)\n const timestamp = input.now.toISOString()\n\n // Cached and already-active work is useful without consuming the one global\n // execution slot. This keeps same-domain retries quota- and capacity-free.\n const reusable = await deps.store.findReusable(fingerprint, timestamp)\n if (reusable) return dispatchExistingCheck(deps, reusable)\n\n const hashedClient = await hashQuotaSubject(deps.config.quotaSalt, input.remoteIp ?? 'unknown')\n // A distinct subject rather than a distinct scope: `CheckQuotaClaim.scope` is\n // a closed union, and prefixing keeps the two buckets disjoint without\n // widening a durable contract.\n const clientSubject = viaMcp ? `mcp:${hashedClient}` : hashedClient\n const clientMax = viaMcp ? deps.config.mcpPerClientDailyLimit : deps.config.perClientDailyLimit\n const day = utcDay(input.now)\n const executionLeaseOwner = crypto.randomUUID()\n const executionLeaseUntil = new Date(input.now.getTime() + PUBLIC_CHECK_EXECUTION_LEASE_MS).toISOString()\n const capacityAvailable = await deps.store.claimGlobalLease(\n PUBLIC_CHECK_EXECUTION_LEASE_NAME,\n executionLeaseOwner,\n timestamp,\n executionLeaseUntil,\n )\n if (!capacityAvailable) throw new PublicCheckCapacityError()\n\n let capacityHeld = true\n let dispatchOwnsCapacity = false\n const releaseCapacity = async () => {\n if (!capacityHeld) return\n await deps.store.releaseGlobalLease(PUBLIC_CHECK_EXECUTION_LEASE_NAME, executionLeaseOwner)\n capacityHeld = false\n }\n\n try {\n const admission = await deps.store.admit({\n candidate: newCheckRecord({\n id: crypto.randomUUID(),\n fingerprint,\n domain: target.domain,\n userQueries,\n now: input.now,\n }),\n now: timestamp,\n clientQuota: { scope: 'client', subject: clientSubject, day, max: clientMax },\n globalQuota: { scope: 'global', subject: 'all', day, max: deps.config.globalDailyLimit },\n })\n if (admission.kind === 'quota-exhausted') throw new PublicQuotaError(admission.scope)\n if (admission.kind === 'busy') throw new PublicCheckAdmissionBusyError()\n\n if (admission.kind === 'reused') {\n // A concurrent same-domain admission won. It must not inherit capacity\n // reserved by this request, so it goes through ordinary reuse dispatch.\n await releaseCapacity()\n return dispatchExistingCheck(deps, admission.record)\n }\n\n let dispatch: 'completed' | 'busy' | 'ignored' = 'ignored'\n if (admission.record.status === 'queued') {\n // Request-bound dispatch takes responsibility for this owner as soon as\n // it receives the promise. Its runner releases even a lost job claim.\n const dispatched = deps.dispatcher.dispatch(admission.record.id, { executionLeaseOwner })\n dispatchOwnsCapacity = true\n dispatch = await dispatched\n }\n return {\n record: (await deps.store.get(admission.record.id)) ?? admission.record,\n reused: admission.kind !== 'created',\n dispatch,\n }\n } finally {\n // The runner owns capacity only after dispatch receives the owner. The app\n // releases every admission, reuse, quota, and pre-dispatch error path.\n if (!dispatchOwnsCapacity) await releaseCapacity()\n }\n}\n\nasync function dispatchExistingCheck(\n deps: ValTownAppDependencies,\n record: CheckRecord,\n): Promise<{ record: CheckRecord; reused: true; dispatch: 'completed' | 'busy' | 'ignored' }> {\n const dispatch = record.status === 'queued' ? await deps.dispatcher.dispatch(record.id) : 'ignored'\n return {\n record: (await deps.store.get(record.id)) ?? record,\n reused: true,\n dispatch,\n }\n}\n\nfunction publicCheckRecord(record: CheckRecord): Omit {\n const { fingerprint: _fingerprint, leaseOwner: _leaseOwner, leaseUntil: _leaseUntil, ...safe } = record\n return safe\n}\n\nfunction apiError(\n context: { json: (body: unknown, status?: number) => Response; header: (name: string, value: string) => void },\n status: number,\n code: string,\n message: string,\n): Response {\n context.header('Cache-Control', 'no-store')\n return context.json({ error: { code, message } }, status)\n}\n\nclass BodyTooLargeError extends Error {}\nclass InvalidBodyError extends Error {}\n\nasync function parseJsonBody(request: Request): Promise> {\n if (!request.headers.get('content-type')?.toLowerCase().includes('application/json')) {\n throw new InvalidBodyError('Expected a JSON request body.')\n }\n const text = await readLimitedBody(request)\n try {\n const parsed = JSON.parse(text)\n if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error()\n return parsed as Record\n } catch {\n throw new InvalidBodyError('Request body must be a JSON object.')\n }\n}\n\nasync function parseFormBody(request: Request): Promise {\n if (!request.headers.get('content-type')?.toLowerCase().includes('application/x-www-form-urlencoded')) {\n throw new InvalidBodyError('Expected a form submission.')\n }\n return new URLSearchParams(await readLimitedBody(request))\n}\n\nasync function readLimitedBody(request: Request): Promise {\n const contentLength = Number(request.headers.get('content-length'))\n if (Number.isFinite(contentLength) && contentLength > MAX_BODY_BYTES) throw new BodyTooLargeError()\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 throw new BodyTooLargeError()\n }\n chunks.push(next.value)\n }\n const output = new Uint8Array(length)\n let offset = 0\n for (const chunk of chunks) {\n output.set(chunk, offset)\n offset += chunk.byteLength\n }\n return new TextDecoder().decode(output)\n}\n\nfunction remoteIp(request: Request): string | null {\n // Val injects this edge header. `x-forwarded-for` is caller-controlled on a\n // public val, so it is deliberately ignored for quota identity.\n const cf = request.headers.get('cf-connecting-ip')?.trim()\n if (cf && cf.length <= 128) return cf\n return null\n}\n\nasync function hashQuotaSubject(salt: string, value: string): Promise {\n const bytes = new TextEncoder().encode(`${salt}\\u0000${value}`)\n const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))\n return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')\n}\n\n/**\n * `frame-ancestors` allows Val Town because the val's own page previews the\n * deployed site in an iframe, and `'none'` renders that preview blank — the\n * first thing anyone arriving from val.town sees. The allowance is exactly the\n * hosting platform and nothing else, so ordinary clickjacking is still blocked.\n * There is little to hijack regardless: no session, no credential, and the only\n * action is submitting a public domain.\n */\nconst FRAME_ANCESTORS = [\"'self'\", 'https://www.val.town', 'https://val.town'].join(' ')\n\n/**\n * Geist is served from jsDelivr because a Val cannot ship the font itself:\n * woff2 is binary and Val Town refuses to push binary files. It is the same\n * package and version the dashboard bundles (`@fontsource-variable/geist`), so\n * the two surfaces render in the same typeface rather than this one silently\n * falling back to a system font, which is what it did before.\n */\nconst FONT_CDN = 'https://cdn.jsdelivr.net'\n\nfunction contentSecurityPolicy(turnstileAllowed: boolean): string {\n const turnstile = turnstileAllowed ? ' https://challenges.cloudflare.com' : ''\n return [\n \"default-src 'self'\",\n \"base-uri 'none'\",\n \"object-src 'none'\",\n `frame-ancestors ${FRAME_ANCESTORS}`,\n \"form-action 'self'\",\n `script-src 'self'${turnstile}`,\n `style-src 'self' ${FONT_CDN}`,\n `font-src ${FONT_CDN}`,\n `connect-src 'self'${turnstile}`,\n `frame-src${turnstile || \" 'none'\"}`,\n \"img-src 'self' data: https:\",\n ].join('; ')\n}\n\nfunction formFailureRecord(domain: unknown, now: Date, error: unknown): CheckRecord {\n const displayDomain = typeof domain === 'string' ? domain.trim().slice(0, 253) : ''\n const timestamp = now.toISOString()\n return {\n id: crypto.randomUUID(),\n fingerprint: '',\n domain: displayDomain,\n userQueries: [],\n status: 'failed',\n createdAt: timestamp,\n updatedAt: timestamp,\n expiresAt: null,\n result: null,\n errorCode: error instanceof PublicQuotaError ? PUBLIC_RATE_LIMITED_ERROR_CODE : 'form-submission-failed',\n errorMessage: formFailureMessage(error),\n leaseOwner: null,\n leaseUntil: null,\n }\n}\n\nfunction formFailureMessage(error: unknown): string {\n if (\n error instanceof PublicUrlError || error instanceof PublicQuotaError || error instanceof HumanVerificationError ||\n error instanceof PublicCheckUnavailableError || error instanceof PublicCheckAdmissionBusyError ||\n error instanceof PublicCheckCapacityError\n ) return error.message\n if (error instanceof BodyTooLargeError) return 'The submission was too large. Enter only a domain.'\n if (error instanceof InvalidBodyError) return 'The form could not be read. Try again.'\n return 'The public check could not be started. Try again later.'\n}\n\nfunction formFailureStatus(error: unknown): 400 | 403 | 413 | 429 | 503 {\n if (error instanceof PublicUrlError || error instanceof InvalidBodyError) return 400\n if (error instanceof BodyTooLargeError) return 413\n if (error instanceof PublicQuotaError) return 429\n if (\n error instanceof PublicCheckUnavailableError || error instanceof PublicCheckAdmissionBusyError ||\n error instanceof PublicCheckCapacityError\n ) return 503\n if (error instanceof HumanVerificationError) return error.code === 'invalid' ? 403 : 503\n return 503\n}\n",[],[192,778,770],"app","099c2e2e-a5d0-494f-ae81-754dd43458ad",["D",1788292309199],[210],[192,778],["D",1788292308897],[209,211,213,215,240,243,246,250,253,262],[192],["D",1788292195151],["D",1789514495229],{"_100":99,"_108":104},{"_100":99,"_101":102,"_103":104,"_18":-5,"_105":106,"_107":25},{"_13":89,"_32":90,"_42":41,"_91":43,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":-5,"_97":44,"_98":99},"ctx",{"_82":-5,"_128":824,"_825":826,"_827":828,"_829":25,"_830":25,"_831":25,"_832":59,"_833":-5,"_834":-7,"_835":-7,"_836":63,"_837":25,"_838":25,"_839":-5,"_840":25,"_841":25,"_842":25,"_843":-5},"ENV",{"_795":796,"_797":798,"_799":90,"_800":801,"_802":803,"_804":805,"_806":807,"_808":809,"_810":811,"_812":813,"_814":815,"_816":817,"_818":819,"_820":821,"_822":823},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

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 · v221