[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_711":712,"_713":714},"routes/_app.x.$handle.$name",{"_100":99,"_31":44,"_109":90,"_26":110,"_13":14,"_111":-5,"_11":112,"_113":114,"_115":116,"_117":118,"_119":120,"_20":-5,"_121":-5,"_122":-5,"_123":24,"_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,"_31":44,"_37":45,"_46":-5,"_47":24,"_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":24},"version",62,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":34,"_35":36,"_37":38,"_39":14,"_40":41,"_23":24},"previous","deleted",false,"deletedHere","path","src/jobs/public-check.ts","latestPath","fileId","960dcd34-a63e-11f1-bfe2-1607ee4eb77e","name","public-check.ts","fileType","script","content","import {\n CHECK_RESULT_SCHEMA_VERSION,\n type CheckRecord,\n type CheckResult,\n type CheckStore,\n type JobDispatcher,\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\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({ domain: record.domain, maxPlannerCalls: 1, maxProbeCalls: 3, signal })\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(input: { id: string; fingerprint: string; domain: string; now: Date }): CheckRecord {\n const timestamp = input.now.toISOString()\n return {\n id: input.id,\n fingerprint: input.fingerprint,\n domain: input.domain,\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 retrievalStatus: evidence.retrievalStatus,\n // Provider adapters may include transport diagnostics; this public record\n // retains only a controlled availability state.\n error: evidence.error ? 'This answer-engine check was unavailable.' : null,\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","createdAt",["D",1788292315934],"branchVersion","branchId","a4524491-dcb3-470a-a361-437a88df6a63","id","b1194860-7c77-41d7-b0b7-f3529a80e15b","AI-Visibility-Check",["D",1788292195151],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Does AI mention your brand and cite your site? Free check.","imageUrl","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/f4d36c97-6af9-485c-0fa5-13e825466c01/square512?exp=1789549199&sig=92ee6749b247ee91708b5e416b8711f6feca8aafcccd8176db8c563f01c4ab51","891d245e-ec71-404d-a5ca-223733ee2844","pinnedFileId","92ee44ee-a63e-11f1-8fd4-1607ee4eb77e","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","01a0460b-6625-75ce-9e7f-9a6b062b0798","tursoName","b11948607c7741d7b0b7f3529a80e15b","tursoHostname","b11948607c7741d7b0b7f3529a80e15b-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789514495229],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_100":99,"_108":104},"org",{"_100":99,"_101":102,"_103":104,"_18":-5,"_105":106,"_107":24},"branch",{"_13":89,"_31":90,"_42":41,"_91":43,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":-5,"_97":44,"_98":99},"isOwned",333,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","canonry","handle","displayName","Canonry","avatar","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/5ae39d80-0d23-48e5-89d8-6bd2a7096401/square512?exp=1789549199&sig=8fff3646e917fd1a59abe9de8276029babb42246cd40658a590eb6cf82b240b4","tier","free","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_42":43,"_31":44,"_37":706,"_46":-5,"_47":24,"_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":707,"_72":-5,"_73":74,"_75":74,"_76":77,"_78":77,"_79":77,"_80":74,"_81":74,"_82":708,"_84":709,"_86":710,"_88":24},"tree",[201,257,258,259,260,261,262],"files",[201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262],"counts",{"_190":63,"_191":186,"_192":63,"_193":194,"_195":196},"contents",[131,132,133,134,135,136,137],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_42":183,"_31":184,"_29":185,"_140":-5,"_40":41,"_39":186,"_142":59,"_37":187,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_26":189},{"_42":176,"_31":177,"_29":178,"_140":-5,"_40":41,"_39":179,"_142":24,"_37":180,"_13":63,"_33":20,"_35":181,"_23":24,"_146":-5,"_26":182},{"_42":169,"_31":170,"_29":171,"_140":-5,"_40":41,"_39":172,"_142":24,"_37":173,"_13":63,"_33":20,"_35":174,"_23":24,"_146":-5,"_26":175},{"_42":162,"_31":163,"_29":164,"_140":-5,"_40":41,"_39":165,"_142":59,"_37":166,"_13":63,"_33":20,"_35":167,"_23":24,"_146":-5,"_26":168},{"_42":155,"_31":156,"_29":157,"_140":-5,"_40":41,"_39":158,"_142":24,"_37":159,"_13":63,"_33":20,"_35":160,"_23":24,"_146":-5,"_26":161},{"_42":148,"_31":149,"_29":150,"_140":-5,"_40":41,"_39":151,"_142":24,"_37":152,"_13":63,"_33":20,"_35":153,"_23":24,"_146":-5,"_26":154},{"_42":138,"_31":139,"_29":57,"_140":-5,"_40":41,"_39":141,"_142":24,"_37":143,"_13":63,"_33":144,"_35":145,"_23":24,"_146":-5,"_26":147},"5188999e-ad25-4c5c-8de9-2938d6984856","main.http.tsx","parentId",15,"latest",["D",1788292310790],"http","import { sqlite } from '@valtown/sqlite'\nimport { createValTownApp } from './src/app/app.ts'\nimport { loadValTownConfig } from './src/config/index.ts'\nimport { createPublicCheckRunner, createRequestBoundDispatcher } from './src/jobs/public-check.ts'\nimport { createSiteHealthRunner } from './src/site-health/runner.ts'\nimport { ValSqliteCheckStore } from './src/storage/val-sqlite.ts'\nimport {\n canonryDemoClientScript,\n canonryDemoStyles,\n createPublicCheckForm,\n demoCanonryViewModel,\n renderCanonryDemo,\n toCanonryDemoViewModel,\n} from './src/ui/index.ts'\nimport { createGeminiValVisibilityProbe } from './src/visibility/gemini-probe.ts'\n\nconst config = loadValTownConfig()\nconst store = new ValSqliteCheckStore(sqlite)\nawait store.initialize()\n\nconst visibilityProbe = config.geminiApiKey\n ? createGeminiValVisibilityProbe({ apiKey: config.geminiApiKey, model: config.geminiModel ?? undefined })\n : null\nconst runner = createPublicCheckRunner({\n store,\n visibilityProbe,\n siteHealthRunner: createSiteHealthRunner(),\n ttlMs: config.checkTtlMs,\n})\n\nconst form = createPublicCheckForm(config)\n\nconst app = createValTownApp({\n store,\n config,\n dispatcher: createRequestBoundDispatcher(runner),\n renderPage: (record) =>\n record\n ? renderCanonryDemo(toCanonryDemoViewModel(record, { form, title: 'Canonry sample' }))\n : renderCanonryDemo({ ...demoCanonryViewModel, form }),\n assets: { styles: canonryDemoStyles, script: canonryDemoClientScript },\n})\n\nexport default app.fetch\n","label",[139],"fbb68b0c-0ce2-4e8d-9ee4-3fb5259c1a6d","deno.json","935238aa-a63e-11f1-9f99-1607ee4eb77e",26,["D",1788292310786],"{\n \"compilerOptions\": {\n \"strict\": true,\n \"noUncheckedIndexedAccess\": true\n },\n \"imports\": {\n \"hono\": \"npm:hono@4.12.25\",\n \"@canonry/aeo-audit\": \"npm:@canonry/aeo-audit@7.1.0\",\n \"@google/genai\": \"npm:@google/genai@1.46.0\",\n \"@valtown/sqlite\": \"https://esm.town/v/std/sqlite/main.ts\"\n },\n \"tasks\": {\n \"check\": \"deno check --allow-import --frozen main.http.tsx\",\n \"test\": \"deno test --allow-env --allow-net --allow-import --frozen test\",\n \"lint\": \"deno lint --allow-import main.http.tsx src test\",\n \"dev\": \"deno run --allow-net --allow-env --allow-import test/dev-server.ts\"\n },\n \"fmt\": {\n \"lineWidth\": 120,\n \"singleQuote\": true,\n \"semiColons\": false\n }\n}\n",[149],"d96e6cf8-bc82-4972-bc5b-b415d772d5e5","README.md","92e8b0ce-a63e-11f1-91a7-1607ee4eb77e",14,["D",1788292310785],"# AEO Check — a Canonry sample on Val Town\n\nThis directory contains **AEO Check** (`canonry/aeo-check`), a free, bounded public sample of Canonry. Git is the\nsource for every file in the Val.\n\nIt is deliberately not called Canonry: one check is 3 generated non-brand queries against Gemini plus a 5-page audit,\nwhile Canonry tracks Gemini, ChatGPT, Claude, and Perplexity on a schedule with no such limits. Every surface — header\nbyline, footer, MCP `initialize` instructions, the `self_host` tool, and the bundled skills — points back at the\nopen-source project at [github.com/Canonry/canonry](https://github.com/Canonry/canonry).\n\nThe sample uses one Canonry interface for two reports:\n\n- **AI Visibility** shows a sample trend, fresh Gemini results, and source evidence for each query.\n- **Site Health** shows a bounded Technical AEO score, factors, fixes, and page evidence.\n\nThe same data is also served to agents over MCP at `POST /mcp`, together with the bundled `canonry` and `aero` skills.\n\nThe four-engine trend contains labeled sample data. A fresh domain check contains one real Gemini snapshot and no\ninvented history.\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 adapter.\nThe visibility core does not read environment, storage, or HTTP state.\n\n## Directory map\n\n```text\napps/val-town/\n├── main.http.tsx Val HTTP entry\n├── deno.json Production imports and Deno tasks\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/ Canonry HTML, CSS, and browser script\n│ └── visibility/ Local contracts, evidence runner, Gemini planner and adapter\n└── test/ Deno backend and UI tests\n```\n\n## Connect an agent\n\n`POST /mcp` speaks the Model Context Protocol over Streamable HTTP. Point any MCP client at the Val's `/mcp` URL; no\ncredential is required, because everything it serves is already public.\n\n```json\n{ \"mcpServers\": { \"aeo-check\": { \"url\": \"https:///mcp\" } } }\n```\n\nIt exposes six read tools — `get_check`, `get_ai_visibility`, `get_site_health`, `list_skills`, `read_skill`,\n`self_host` — plus `start_check`, and serves all 16 `canonry` and `aero` skill documents as MCP resources, entry points first. An agent\nreads the entry point for how to interpret coverage, then opens the reference the task calls for, exactly as it would\nin a local install.\n\nReads address a check by `checkId` or by `domain` and never spend: a domain resolves to the most recent cached check,\nor reports a miss. `start_check` runs a fresh one and blocks until it finishes, up to about 45 seconds, because\nexecution is request-bound and there is no background queue.\n\n`start_check` skips Turnstile, which an agent cannot solve, and spends from its own daily bucket\n(`CANONRY_MCP_PER_CLIENT_DAILY_LIMIT`, default 2) keyed on the caller's edge IP. It shares the same global daily cap\nand the same single execution lease as the browser, so MCP widens who may spend the budget, never how large it is. A\ndomain checked within the cache TTL returns immediately at no cost. Set `CANONRY_MCP_START_CHECKS=0` to remove the\ntool entirely.\n\nBoth protocol revisions work: the sessionless `2026-07-28` transport and the older `initialize` handshake that current\nclients still use.\n\n`src/mcp/skills/` is generated from `skills/` at the repository root — Val Town caps a file at 80,000 characters and\n`canonry-cli.md` is over it, so the mirror chunks each document. Run `node scripts/sync-val-town-skills.mjs` after\nediting a skill and commit the result; `--check` fails on drift.\n\n## Fixed public limits\n\n- One grounded Gemini planning call creates three non-brand queries.\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\nThe host never sets `allowPrivateHost`. Failed provider checks stay `Not measured` and do not reduce the reported rates.\n\n## Run it locally\n\n```sh\ncd apps/val-town\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. Smoke-test the endpoint with:\n\n```sh\ncurl -s localhost:8787/mcp -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\nOr drive it from a real client: `npx @modelcontextprotocol/inspector`, then connect to\n`http://localhost:8787/mcp` over Streamable HTTP.\n\n## Local checks\n\n```sh\nnode scripts/sync-val-town-skills.mjs --check # from the repository root\n\ncd apps/val-town\nnpx --yes deno@2.7.5 check --allow-import --frozen --config deno.json main.http.tsx\nnpx --yes deno@2.7.5 lint --config deno.json main.http.tsx src test\nnpx --yes deno@2.7.5 test --allow-env --allow-net --allow-import --frozen --config deno.json test\n```\n\n## Production configuration\n\nSet these environment variables in Val Town:\n\n- `VAL_TOWN_ENV=production`\n- `GEMINI_API_KEY`\n- `CANONRY_QUOTA_SALT`\n- `TURNSTILE_SECRET_KEY`\n- `TURNSTILE_SITE_KEY`\n- `TURNSTILE_ALLOWED_HOSTNAMES`\n\nOptional: `CANONRY_MCP_START_CHECKS=0` disables MCP-started checks; `CANONRY_MCP_PER_CLIENT_DAILY_LIMIT` sets their\ndaily per-caller allowance (default 2).\n\nThe host disables public checks when the production quota salt or Turnstile configuration is absent.\n\n## Release order\n\n1. Regenerate `deno.lock` with `deno.json`, and the skill mirror with `node scripts/sync-val-town-skills.mjs`.\n2. Run the local checks.\n3. Run `vt push --dry-run` from this directory.\n4. Review the file plan.\n5. Run `vt push` only after approval.\n6. Request `/healthz` and make sure that it returns `{\"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",[156],"655360bd-bc32-4a60-b9ab-c9156f924695","CLAUDE.md","930d2c42-a63e-11f1-8d00-1607ee4eb77e",18,["D",1788292310988],"@AGENTS.md\n",[163],"45bc70da-b408-45c0-826b-7bd5c2e0dc27","AGENTS.md","92f64d1a-a63e-11f1-8d00-1607ee4eb77e",16,["D",1788292310802],"# AEO Check (Val Town)\n\nThis directory is the exact source mirrored to the public `canonry/aeo-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 **AEO Check**, not Canonry. It runs 3 generated queries against one engine and audits 5 pages; Canonry\ntracks four engines on a schedule with no such limits. Calling this \"Canonry\" would tell a visitor — or an agent\nreading `serverInfo` — that they had the platform when they have a sample of it, so the product name, the val name,\nand the MCP `serverInfo.name` all say `aeo-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- Never set `allowPrivateHost`. 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- Demo history must be explicitly labeled sample data. A fresh check is a snapshot until real history exists.\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## 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## 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",[170],"32515d7c-b260-427a-af1a-f218e7d2f15a",".vtignore","92ff2520-a63e-11f1-91a7-1607ee4eb77e",17,["D",1788292310911],".env\n.env.*\ncoverage/\ntest/\n",[177],"70fabb5a-32a8-428a-9a8c-08292618dd57","src","91c8aac8-a63e-11f1-b64b-1607ee4eb77e",1,["D",1788292308897],"directory",[184],"pulls","branches","forks","envVars",{"_197":199,"_200":63},"connections",{"_197":63,"_198":63},"count","unfilledCount",7,"emptyCount",{"_42":183,"_31":184,"_29":185,"_140":-5,"_40":41,"_39":186,"_142":59,"_37":703,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":704,"_26":705},{"_42":698,"_31":697,"_29":691,"_140":185,"_40":41,"_39":699,"_142":59,"_37":700,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":701,"_26":702},{"_42":688,"_31":689,"_29":690,"_140":691,"_40":41,"_39":692,"_142":24,"_37":693,"_13":63,"_33":34,"_35":694,"_23":24,"_146":-5,"_264":695,"_26":696},{"_42":683,"_31":682,"_29":676,"_140":185,"_40":41,"_39":684,"_142":24,"_37":685,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":686,"_26":687},{"_42":674,"_31":364,"_29":675,"_140":676,"_40":41,"_39":677,"_142":24,"_37":678,"_13":63,"_33":34,"_35":679,"_23":24,"_146":-5,"_264":680,"_26":681},{"_42":669,"_31":668,"_29":662,"_140":185,"_40":41,"_39":670,"_142":24,"_37":671,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":672,"_26":673},{"_42":659,"_31":660,"_29":661,"_140":662,"_40":41,"_39":663,"_142":24,"_37":664,"_13":63,"_33":34,"_35":665,"_23":24,"_146":-5,"_264":666,"_26":667},{"_42":654,"_31":653,"_29":649,"_140":185,"_40":41,"_39":655,"_142":59,"_37":656,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":657,"_26":658},{"_42":648,"_31":32,"_29":30,"_140":649,"_40":41,"_39":14,"_142":24,"_37":650,"_13":63,"_33":34,"_35":36,"_23":24,"_146":-5,"_264":651,"_26":652},{"_42":643,"_31":475,"_29":469,"_140":185,"_40":41,"_39":644,"_142":59,"_37":645,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":646,"_26":647},{"_42":638,"_31":509,"_29":503,"_140":469,"_40":41,"_39":639,"_142":24,"_37":640,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":641,"_26":642},{"_42":630,"_31":631,"_29":632,"_140":503,"_40":41,"_39":633,"_142":24,"_37":634,"_13":63,"_33":34,"_35":635,"_23":24,"_146":-5,"_264":636,"_26":637},{"_42":622,"_31":623,"_29":624,"_140":503,"_40":41,"_39":625,"_142":24,"_37":626,"_13":63,"_33":34,"_35":627,"_23":24,"_146":-5,"_264":628,"_26":629},{"_42":614,"_31":615,"_29":616,"_140":503,"_40":41,"_39":617,"_142":24,"_37":618,"_13":63,"_33":34,"_35":619,"_23":24,"_146":-5,"_264":620,"_26":621},{"_42":606,"_31":607,"_29":608,"_140":503,"_40":41,"_39":609,"_142":24,"_37":610,"_13":63,"_33":34,"_35":611,"_23":24,"_146":-5,"_264":612,"_26":613},{"_42":598,"_31":599,"_29":600,"_140":503,"_40":41,"_39":601,"_142":24,"_37":602,"_13":63,"_33":34,"_35":603,"_23":24,"_146":-5,"_264":604,"_26":605},{"_42":590,"_31":591,"_29":592,"_140":503,"_40":41,"_39":593,"_142":24,"_37":594,"_13":63,"_33":34,"_35":595,"_23":24,"_146":-5,"_264":596,"_26":597},{"_42":582,"_31":583,"_29":584,"_140":503,"_40":41,"_39":585,"_142":24,"_37":586,"_13":63,"_33":34,"_35":587,"_23":24,"_146":-5,"_264":588,"_26":589},{"_42":574,"_31":575,"_29":576,"_140":503,"_40":41,"_39":577,"_142":24,"_37":578,"_13":63,"_33":34,"_35":579,"_23":24,"_146":-5,"_264":580,"_26":581},{"_42":566,"_31":567,"_29":568,"_140":503,"_40":41,"_39":569,"_142":24,"_37":570,"_13":63,"_33":34,"_35":571,"_23":24,"_146":-5,"_264":572,"_26":573},{"_42":558,"_31":559,"_29":560,"_140":503,"_40":41,"_39":561,"_142":24,"_37":562,"_13":63,"_33":34,"_35":563,"_23":24,"_146":-5,"_264":564,"_26":565},{"_42":550,"_31":551,"_29":552,"_140":503,"_40":41,"_39":553,"_142":24,"_37":554,"_13":63,"_33":34,"_35":555,"_23":24,"_146":-5,"_264":556,"_26":557},{"_42":542,"_31":543,"_29":544,"_140":503,"_40":41,"_39":545,"_142":24,"_37":546,"_13":63,"_33":34,"_35":547,"_23":24,"_146":-5,"_264":548,"_26":549},{"_42":534,"_31":535,"_29":536,"_140":503,"_40":41,"_39":537,"_142":24,"_37":538,"_13":63,"_33":34,"_35":539,"_23":24,"_146":-5,"_264":540,"_26":541},{"_42":526,"_31":527,"_29":528,"_140":503,"_40":41,"_39":529,"_142":24,"_37":530,"_13":63,"_33":34,"_35":531,"_23":24,"_146":-5,"_264":532,"_26":533},{"_42":518,"_31":519,"_29":520,"_140":503,"_40":41,"_39":521,"_142":24,"_37":522,"_13":63,"_33":34,"_35":523,"_23":24,"_146":-5,"_264":524,"_26":525},{"_42":510,"_31":511,"_29":512,"_140":503,"_40":41,"_39":513,"_142":24,"_37":514,"_13":63,"_33":34,"_35":515,"_23":24,"_146":-5,"_264":516,"_26":517},{"_42":500,"_31":501,"_29":502,"_140":503,"_40":41,"_39":504,"_142":24,"_37":505,"_13":63,"_33":34,"_35":506,"_23":24,"_146":-5,"_264":507,"_26":508},{"_42":492,"_31":493,"_29":494,"_140":469,"_40":41,"_39":495,"_142":24,"_37":496,"_13":63,"_33":34,"_35":497,"_23":24,"_146":-5,"_264":498,"_26":499},{"_42":484,"_31":485,"_29":486,"_140":469,"_40":41,"_39":487,"_142":24,"_37":488,"_13":63,"_33":34,"_35":489,"_23":24,"_146":-5,"_264":490,"_26":491},{"_42":476,"_31":477,"_29":478,"_140":469,"_40":41,"_39":479,"_142":24,"_37":480,"_13":63,"_33":34,"_35":481,"_23":24,"_146":-5,"_264":482,"_26":483},{"_42":466,"_31":467,"_29":468,"_140":469,"_40":41,"_39":470,"_142":24,"_37":471,"_13":63,"_33":34,"_35":472,"_23":24,"_146":-5,"_264":473,"_26":474},{"_42":462,"_31":453,"_29":447,"_140":185,"_40":41,"_39":199,"_142":59,"_37":463,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":464,"_26":465},{"_42":454,"_31":455,"_29":456,"_140":447,"_40":41,"_39":457,"_142":24,"_37":458,"_13":63,"_33":34,"_35":459,"_23":24,"_146":-5,"_264":460,"_26":461},{"_42":445,"_31":338,"_29":446,"_140":447,"_40":41,"_39":448,"_142":24,"_37":449,"_13":63,"_33":34,"_35":450,"_23":24,"_146":-5,"_264":451,"_26":452},{"_42":440,"_31":431,"_29":425,"_140":185,"_40":41,"_39":441,"_142":24,"_37":442,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":443,"_26":444},{"_42":432,"_31":433,"_29":434,"_140":425,"_40":41,"_39":435,"_142":24,"_37":436,"_13":63,"_33":34,"_35":437,"_23":24,"_146":-5,"_264":438,"_26":439},{"_42":422,"_31":423,"_29":424,"_140":425,"_40":41,"_39":426,"_142":24,"_37":427,"_13":63,"_33":34,"_35":428,"_23":24,"_146":-5,"_264":429,"_26":430},{"_42":415,"_31":416,"_29":417,"_140":185,"_40":41,"_39":418,"_142":59,"_37":419,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":420,"_26":421},{"_42":410,"_31":409,"_29":403,"_140":185,"_40":41,"_39":411,"_142":24,"_37":412,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":413,"_26":414},{"_42":400,"_31":401,"_29":402,"_140":403,"_40":41,"_39":404,"_142":24,"_37":405,"_13":63,"_33":34,"_35":406,"_23":24,"_146":-5,"_264":407,"_26":408},{"_42":395,"_31":346,"_29":340,"_140":185,"_40":41,"_39":396,"_142":59,"_37":397,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":398,"_26":399},{"_42":387,"_31":388,"_29":389,"_140":340,"_40":41,"_39":390,"_142":24,"_37":391,"_13":63,"_33":34,"_35":392,"_23":24,"_146":-5,"_264":393,"_26":394},{"_42":379,"_31":380,"_29":381,"_140":340,"_40":41,"_39":382,"_142":24,"_37":383,"_13":63,"_33":34,"_35":384,"_23":24,"_146":-5,"_264":385,"_26":386},{"_42":371,"_31":372,"_29":373,"_140":340,"_40":41,"_39":374,"_142":24,"_37":375,"_13":63,"_33":34,"_35":376,"_23":24,"_146":-5,"_264":377,"_26":378},{"_42":363,"_31":364,"_29":365,"_140":340,"_40":41,"_39":366,"_142":24,"_37":367,"_13":63,"_33":34,"_35":368,"_23":24,"_146":-5,"_264":369,"_26":370},{"_42":355,"_31":356,"_29":357,"_140":340,"_40":41,"_39":358,"_142":24,"_37":359,"_13":63,"_33":34,"_35":360,"_23":24,"_146":-5,"_264":361,"_26":362},{"_42":347,"_31":348,"_29":349,"_140":340,"_40":41,"_39":350,"_142":24,"_37":351,"_13":63,"_33":34,"_35":352,"_23":24,"_146":-5,"_264":353,"_26":354},{"_42":337,"_31":338,"_29":339,"_140":340,"_40":41,"_39":341,"_142":24,"_37":342,"_13":63,"_33":34,"_35":343,"_23":24,"_146":-5,"_264":344,"_26":345},{"_42":332,"_31":291,"_29":285,"_140":185,"_40":41,"_39":333,"_142":24,"_37":334,"_13":63,"_33":188,"_35":-5,"_23":24,"_146":-5,"_264":335,"_26":336},{"_42":324,"_31":325,"_29":326,"_140":285,"_40":41,"_39":327,"_142":24,"_37":328,"_13":63,"_33":34,"_35":329,"_23":24,"_146":-5,"_264":330,"_26":331},{"_42":316,"_31":317,"_29":318,"_140":285,"_40":41,"_39":319,"_142":24,"_37":320,"_13":63,"_33":34,"_35":321,"_23":24,"_146":-5,"_264":322,"_26":323},{"_42":308,"_31":309,"_29":310,"_140":285,"_40":41,"_39":311,"_142":24,"_37":312,"_13":63,"_33":34,"_35":313,"_23":24,"_146":-5,"_264":314,"_26":315},{"_42":300,"_31":301,"_29":302,"_140":285,"_40":41,"_39":303,"_142":24,"_37":304,"_13":63,"_33":34,"_35":305,"_23":24,"_146":-5,"_264":306,"_26":307},{"_42":292,"_31":293,"_29":294,"_140":285,"_40":41,"_39":295,"_142":24,"_37":296,"_13":63,"_33":34,"_35":297,"_23":24,"_146":-5,"_264":298,"_26":299},{"_42":282,"_31":283,"_29":284,"_140":285,"_40":41,"_39":286,"_142":24,"_37":287,"_13":63,"_33":34,"_35":288,"_23":24,"_146":-5,"_264":289,"_26":290},{"_42":176,"_31":177,"_29":178,"_140":-5,"_40":41,"_39":179,"_142":24,"_37":279,"_13":63,"_33":20,"_35":181,"_23":24,"_146":-5,"_264":280,"_26":281},{"_42":169,"_31":170,"_29":171,"_140":-5,"_40":41,"_39":172,"_142":24,"_37":276,"_13":63,"_33":20,"_35":174,"_23":24,"_146":-5,"_264":277,"_26":278},{"_42":162,"_31":163,"_29":164,"_140":-5,"_40":41,"_39":165,"_142":59,"_37":273,"_13":63,"_33":20,"_35":167,"_23":24,"_146":-5,"_264":274,"_26":275},{"_42":155,"_31":156,"_29":157,"_140":-5,"_40":41,"_39":158,"_142":24,"_37":270,"_13":63,"_33":20,"_35":160,"_23":24,"_146":-5,"_264":271,"_26":272},{"_42":148,"_31":149,"_29":150,"_140":-5,"_40":41,"_39":151,"_142":24,"_37":267,"_13":63,"_33":20,"_35":153,"_23":24,"_146":-5,"_264":268,"_26":269},{"_42":138,"_31":139,"_29":57,"_140":-5,"_40":41,"_39":141,"_142":24,"_37":263,"_13":63,"_33":144,"_35":145,"_23":24,"_146":-5,"_264":265,"_26":266},["D",1788292310790],"children",[],[139],["D",1788292310786],[],[149],["D",1788292310785],[],[156],["D",1788292310988],[],[163],["D",1788292310802],[],[170],["D",1788292310911],[],[177],"c839bdb8-988e-4523-919e-ece5a8822925","runtime.ts","9370d1ac-a63e-11f1-b150-1607ee4eb77e","92153f82-a63e-11f1-8621-1607ee4eb77e",30,["D",1788292311627],"import type { VisibilityProbeLimits } from './contracts.ts'\n\nconst HARD_LIMITS = {\n timeoutMs: { min: 1_000, max: 30_000 },\n maxConcurrency: { min: 1, max: 4 },\n maxQueries: { min: 1, max: 20 },\n maxProviders: { min: 1, max: 8 },\n maxAnswerChars: { min: 256, max: 20_000 },\n maxSources: { min: 1, max: 50 },\n maxSourceUrlChars: { min: 128, max: 4_096 },\n maxSourceTitleChars: { min: 32, max: 1_024 },\n maxSearchQueries: { min: 0, max: 25 },\n maxSearchQueryChars: { min: 32, max: 512 },\n} as const\n\nexport const MAX_QUERY_CHARS = 512\n/** Stable query IDs are returned verbatim, so reject oversize caller input. */\nexport const MAX_QUERY_ID_CHARS = 160\n/** Provider names are public report identities, not arbitrary display text. */\nexport const MAX_PROVIDER_ID_CHARS = 80\n/** Requested/served model identifiers are public report identities. */\nexport const MAX_MODEL_ID_CHARS = 256\nexport const MAX_BRAND_NAME_CHARS = 128\nexport const MAX_BRAND_NAMES = 20\nexport const MAX_DOMAIN_CHARS = 253\nexport const MAX_PROVIDER_ERROR_CHARS = 180\nexport const MAX_EXTRACTED_SOURCES = 100\n\nexport function resolveLimits(\n defaults: VisibilityProbeLimits,\n partial: Partial | undefined,\n): VisibilityProbeLimits {\n const candidate = { ...defaults, ...partial }\n return {\n timeoutMs: boundedInteger(candidate.timeoutMs, HARD_LIMITS.timeoutMs),\n maxConcurrency: boundedInteger(candidate.maxConcurrency, HARD_LIMITS.maxConcurrency),\n maxQueries: boundedInteger(candidate.maxQueries, HARD_LIMITS.maxQueries),\n maxProviders: boundedInteger(candidate.maxProviders, HARD_LIMITS.maxProviders),\n maxAnswerChars: boundedInteger(candidate.maxAnswerChars, HARD_LIMITS.maxAnswerChars),\n maxSources: boundedInteger(candidate.maxSources, HARD_LIMITS.maxSources),\n maxSourceUrlChars: boundedInteger(candidate.maxSourceUrlChars, HARD_LIMITS.maxSourceUrlChars),\n maxSourceTitleChars: boundedInteger(candidate.maxSourceTitleChars, HARD_LIMITS.maxSourceTitleChars),\n maxSearchQueries: boundedInteger(candidate.maxSearchQueries, HARD_LIMITS.maxSearchQueries),\n maxSearchQueryChars: boundedInteger(candidate.maxSearchQueryChars, HARD_LIMITS.maxSearchQueryChars),\n }\n}\n\nfunction boundedInteger(value: number, bounds: { min: number; max: number }): number {\n if (!Number.isFinite(value)) return bounds.min\n return Math.max(bounds.min, Math.min(bounds.max, Math.floor(value)))\n}\n\nexport function clipText(value: string, maxChars: number): { value: string; truncated: boolean } {\n if (value.length <= maxChars) return { value, truncated: false }\n return { value: value.slice(0, maxChars), truncated: true }\n}\n\nexport function cleanText(value: unknown): string {\n return typeof value === 'string' ? value.trim() : ''\n}\n\nexport function uniqueStable(values: readonly string[]): string[] {\n const seen = new Set()\n const unique: string[] = []\n for (const value of values) {\n if (seen.has(value)) continue\n seen.add(value)\n unique.push(value)\n }\n return unique\n}\n\nexport interface DeadlineSignal {\n signal: AbortSignal\n didTimeout(): boolean\n dispose(): void\n}\n\n/** Web-standard timeout composition that works in Node and Deno without globals. */\nexport function createDeadlineSignal(parent: AbortSignal | undefined, timeoutMs: number): DeadlineSignal {\n const controller = new AbortController()\n let timedOut = false\n const timeoutReason = new DOMException('Visibility provider request timed out.', 'TimeoutError')\n const abortFromParent = () => controller.abort(parent?.reason)\n if (parent?.aborted) abortFromParent()\n else parent?.addEventListener('abort', abortFromParent, { once: true })\n const timer = setTimeout(() => {\n timedOut = true\n controller.abort(timeoutReason)\n }, timeoutMs)\n return {\n signal: controller.signal,\n didTimeout: () => timedOut,\n dispose: () => {\n clearTimeout(timer)\n parent?.removeEventListener('abort', abortFromParent)\n },\n }\n}\n\nexport function isAbortError(error: unknown): boolean {\n if (error instanceof DOMException) return error.name === 'AbortError' || error.name === 'TimeoutError'\n if (!(error instanceof Error)) return false\n return error.name === 'AbortError' || error.name === 'TimeoutError' || /\\babort(?:ed|ing)?\\b/i.test(error.message)\n}\n\n/** Do not echo provider response bodies, URLs, or accidental credentials into report storage. */\nexport function safeProviderErrorMessage(error: unknown): string {\n const generic = 'The provider request failed.'\n if (!(error instanceof Error)) return generic\n const message = error.message.replace(/[\\r\\n\\t]+/g, ' ').trim()\n if (!message) return generic\n // Provider SDK messages commonly embed request IDs and error bodies. Keep a\n // small classified surface instead of a transport dump.\n if (/\\b429\\b/.test(message)) return 'The provider rate-limited this request.'\n if (/\\b(?:500|501|502|503|504)\\b/.test(message)) return 'The provider was temporarily unavailable.'\n if (/invalid api key|api[_ -]?key|unauthori[sz]ed|forbidden/i.test(message)) {\n return 'The provider credentials were rejected.'\n }\n if (/timeout|timed out/i.test(message)) return 'The provider request timed out.'\n return clipText(generic, MAX_PROVIDER_ERROR_CHARS).value\n}\n\nexport function nowIso(now: (() => Date) | undefined): string {\n return (now?.() ?? new Date()).toISOString()\n}\n\nexport function throwIfAborted(signal: AbortSignal): void {\n if (!signal.aborted) return\n throw signal.reason instanceof Error ? signal.reason : new DOMException('Aborted', 'AbortError')\n}\n\nexport function sleep(delayMs: number, signal: AbortSignal): Promise {\n return new Promise((resolve, reject) => {\n throwIfAborted(signal)\n const timer = setTimeout(done, delayMs)\n const onAbort = () => {\n clearTimeout(timer)\n signal.removeEventListener('abort', onAbort)\n reject(signal.reason instanceof Error ? signal.reason : new DOMException('Aborted', 'AbortError'))\n }\n function done(): void {\n signal.removeEventListener('abort', onAbort)\n resolve()\n }\n signal.addEventListener('abort', onAbort, { once: true })\n })\n}\n",[],[184,291,283],"visibility","abbdcbe9-fc5e-403a-94fd-785d60bfad8a","runner.ts","938767d2-a63e-11f1-a6d3-1607ee4eb77e",33,["D",1788292311828],"import {\n DEFAULT_VISIBILITY_PROBE_LIMITS,\n type RunVisibilityProbeInput,\n VISIBILITY_PROBE_SCHEMA_VERSION,\n type VisibilityProbeCheck,\n type VisibilityProbeFailure,\n type VisibilityProbeQuery,\n type VisibilityProbeReport,\n type VisibilityProbeReportStatus,\n type VisibilityProbeSourceEvidence,\n type VisibilityProbeSummary,\n type VisibilityProbeTarget,\n type VisibilityProviderAdapter,\n type VisibilityProviderResponse,\n} from './contracts.ts'\nimport {\n type CitationEvidence,\n detectCitation,\n detectMention,\n type NormalizedTarget,\n normalizeTarget,\n} from './brand.ts'\nimport {\n cleanText,\n clipText,\n createDeadlineSignal,\n isAbortError,\n MAX_EXTRACTED_SOURCES,\n MAX_MODEL_ID_CHARS,\n MAX_PROVIDER_ID_CHARS,\n MAX_QUERY_CHARS,\n MAX_QUERY_ID_CHARS,\n nowIso,\n resolveLimits,\n safeProviderErrorMessage,\n throwIfAborted,\n uniqueStable,\n} from './runtime.ts'\n\ninterface PreparedQuery extends VisibilityProbeQuery {\n id: string\n text: string\n}\n\ninterface PreparedAdapter {\n adapter: VisibilityProviderAdapter\n name: string\n requestedModel: string | null\n}\n\ninterface CheckSlot {\n query: PreparedQuery\n adapter: PreparedAdapter\n}\n\n/**\n * Execute a bounded query × provider matrix and return only normalized evidence.\n * A failed check is intentionally represented with null metrics, never coerced\n * into `not-mentioned` / `not-cited`.\n */\nexport async function runVisibilityProbe(input: RunVisibilityProbeInput): Promise {\n const limits = resolveLimits(DEFAULT_VISIBILITY_PROBE_LIMITS, input.limits)\n const target = normalizeTarget(input.target)\n const queries = prepareQueries(input.queries, limits.maxQueries)\n const adapters = prepareAdapters(input.adapters, limits.maxProviders)\n const startedAt = nowIso(input.now)\n const slots = createSlots(queries, adapters)\n const checks = new Array(slots.length)\n let cursor = 0\n\n const worker = async (): Promise => {\n while (cursor < slots.length) {\n const index = cursor\n cursor += 1\n checks[index] = await executeSlot(slots[index]!, target, limits, input.signal, input.now)\n }\n }\n await Promise.all(Array.from({ length: Math.min(limits.maxConcurrency, slots.length) }, worker))\n\n const summary = summarize(checks)\n return {\n schemaVersion: VISIBILITY_PROBE_SCHEMA_VERSION,\n target: { canonicalDomain: target.canonicalDomain, brandNames: target.brandNames },\n startedAt,\n completedAt: nowIso(input.now),\n status: reportStatus(summary),\n checks,\n summary,\n }\n}\n\nfunction prepareQueries(input: readonly VisibilityProbeQuery[], maxQueries: number): PreparedQuery[] {\n if (input.length === 0) throw new Error('at least one query is required')\n if (input.length > maxQueries) throw new Error(`at most ${maxQueries} queries are allowed`)\n const ids = new Set()\n return input.map((candidate, index) => {\n const text = cleanText(candidate.text)\n if (!text) throw new Error(`query ${index + 1} must not be empty`)\n if (text.length > MAX_QUERY_CHARS) {\n throw new Error(`query ${index + 1} must be at most ${MAX_QUERY_CHARS} characters`)\n }\n const id = cleanText(candidate.id) || `query-${index + 1}`\n if (id.length > MAX_QUERY_ID_CHARS) {\n throw new Error(`query ${index + 1} ID must be at most ${MAX_QUERY_ID_CHARS} characters`)\n }\n if (ids.has(id)) throw new Error('query IDs must be unique')\n ids.add(id)\n return { id, text }\n })\n}\n\nfunction prepareAdapters(input: readonly VisibilityProviderAdapter[], maxProviders: number): PreparedAdapter[] {\n if (input.length === 0) throw new Error('at least one provider adapter is required')\n if (input.length > maxProviders) throw new Error(`at most ${maxProviders} provider adapters are allowed`)\n const names = new Set()\n return input.map((adapter) => {\n const name = cleanText(adapter.name)\n if (!name || typeof adapter.execute !== 'function') {\n throw new Error('each provider adapter must have a name and execute function')\n }\n if (name.length > MAX_PROVIDER_ID_CHARS) {\n throw new Error(`provider adapter names must be at most ${MAX_PROVIDER_ID_CHARS} characters`)\n }\n if (names.has(name)) throw new Error('provider adapter names must be unique')\n const requestedModel = boundedIdentifier(adapter.requestedModel, MAX_MODEL_ID_CHARS)\n if (adapter.requestedModel !== undefined && !requestedModel) {\n throw new Error(`provider adapter requestedModel must be at most ${MAX_MODEL_ID_CHARS} non-whitespace characters`)\n }\n names.add(name)\n return { adapter, name, requestedModel }\n })\n}\n\nfunction createSlots(queries: readonly PreparedQuery[], adapters: readonly PreparedAdapter[]): CheckSlot[] {\n const slots: CheckSlot[] = []\n for (const query of queries) {\n for (const adapter of adapters) slots.push({ query, adapter })\n }\n return slots\n}\n\nasync function executeSlot(\n slot: CheckSlot,\n target: NormalizedTarget,\n limits: ReturnType,\n parentSignal: AbortSignal | undefined,\n now: (() => Date) | undefined,\n): Promise {\n const deadline = createDeadlineSignal(parentSignal, limits.timeoutMs)\n try {\n throwIfAborted(deadline.signal)\n const response = await slot.adapter.adapter.execute({\n query: slot.query,\n target: { canonicalDomain: target.canonicalDomain, brandNames: target.brandNames },\n signal: deadline.signal,\n limits,\n })\n throwIfAborted(deadline.signal)\n return successfulCheck(slot, response, target, limits, now)\n } catch (error) {\n return failedCheck(slot, classifyFailure(error, deadline.didTimeout()), now)\n } finally {\n deadline.dispose()\n }\n}\n\nfunction successfulCheck(\n slot: CheckSlot,\n response: VisibilityProviderResponse,\n target: NormalizedTarget,\n limits: ReturnType,\n now: (() => Date) | undefined,\n): VisibilityProbeCheck {\n const answer = cleanText(response.answerText)\n if (!answer) {\n return failedCheck(\n slot,\n { code: 'invalid-response', message: 'The provider response contained no answer text.' },\n now,\n )\n }\n const requestedModel = boundedIdentifier(response.requestedModel, MAX_MODEL_ID_CHARS)\n if (!requestedModel) {\n return failedCheck(slot, {\n code: 'invalid-response',\n message: 'The provider response has an invalid requested model.',\n }, now)\n }\n // Match only the evidence that will be returned. This keeps the verdict\n // auditable and caps work even for a malformed custom adapter.\n const clippedAnswer = clipText(answer, limits.maxAnswerChars)\n const mention = detectMention(clippedAnswer.value, target)\n const citation = detectCitation((response.sources ?? []).slice(0, MAX_EXTRACTED_SOURCES), target)\n const clippedSources = clipSources(citation, limits)\n const normalizedSearchQueries = normalizeSearchQueries(response.searchQueries, limits)\n return {\n queryId: slot.query.id,\n query: slot.query.text,\n provider: slot.adapter.name,\n requestedModel,\n servedModel: boundedIdentifier(response.servedModel, MAX_MODEL_ID_CHARS),\n completedAt: nowIso(now),\n status: 'success',\n answerText: clippedAnswer.value,\n answerTruncated: clippedAnswer.truncated,\n mentioned: mention.mentioned,\n matchedTerms: mention.matchedTerms,\n cited: citation.cited,\n citedDomains: uniqueStable(\n clippedSources.map((source) => source.domain).filter((domain): domain is string => Boolean(domain)),\n ),\n citedUrls: clippedSources.map((source) => source.url),\n // Derive every outward-facing URL/domain array from the clipped source\n // set. `citation` may inspect up to the extraction hard cap to preserve\n // the verdict, but it must never leak an unbounded provider URL.\n matchedCitationDomains: uniqueStable(\n clippedSources.filter((source) => source.targetDomainMatch)\n .map((source) => source.domain)\n .filter((domain): domain is string => Boolean(domain)),\n ),\n matchedCitationUrls: clippedSources.filter((source) => source.targetDomainMatch).map((source) => source.url),\n sources: clippedSources,\n sourceCount: citation.sources.length,\n sourcesTruncated: citation.sources.length > clippedSources.length,\n searchQueries: normalizedSearchQueries.values,\n searchQueriesTruncated: normalizedSearchQueries.truncated,\n retrievalStatus: response.retrievalStatus ?? 'unknown',\n error: null,\n }\n}\n\nfunction clipSources(\n citation: CitationEvidence,\n limits: ReturnType,\n): VisibilityProbeSourceEvidence[] {\n // If output clipping occurs, keep target matches first so `cited: true`\n // always has visible source evidence. Relative provider order is preserved\n // within the matching and non-matching groups.\n const ordered = [\n ...citation.sources.filter((source) => source.targetDomainMatch),\n ...citation.sources.filter((source) => !source.targetDomainMatch),\n ]\n return ordered.slice(0, limits.maxSources).map((source) => ({\n url: clipText(source.url, limits.maxSourceUrlChars).value,\n title: source.title ? clipText(source.title, limits.maxSourceTitleChars).value : null,\n domain: source.domain,\n targetDomainMatch: source.targetDomainMatch,\n }))\n}\n\nfunction normalizeSearchQueries(\n values: readonly string[] | undefined,\n limits: ReturnType,\n): { values: string[]; truncated: boolean } {\n const source = (values ?? []).slice(0, MAX_EXTRACTED_SOURCES)\n const cleaned = uniqueStable(source.map(cleanText).filter(Boolean))\n return {\n values: cleaned.slice(0, limits.maxSearchQueries).map((value) => clipText(value, limits.maxSearchQueryChars).value),\n truncated: values !== undefined && (values.length > source.length || cleaned.length > limits.maxSearchQueries),\n }\n}\n\nfunction failedCheck(\n slot: CheckSlot,\n error: VisibilityProbeFailure,\n now: (() => Date) | undefined,\n): VisibilityProbeCheck {\n return {\n queryId: slot.query.id,\n query: slot.query.text,\n provider: slot.adapter.name,\n requestedModel: slot.adapter.requestedModel,\n servedModel: null,\n completedAt: nowIso(now),\n status: 'failed',\n answerText: null,\n answerTruncated: false,\n mentioned: null,\n matchedTerms: [],\n cited: null,\n citedDomains: [],\n citedUrls: [],\n matchedCitationDomains: [],\n matchedCitationUrls: [],\n sources: [],\n sourceCount: 0,\n sourcesTruncated: false,\n searchQueries: [],\n searchQueriesTruncated: false,\n retrievalStatus: 'unknown',\n error,\n }\n}\n\nfunction boundedIdentifier(value: unknown, maxChars: number): string | null {\n const normalized = cleanText(value)\n return normalized && normalized.length <= maxChars ? normalized : null\n}\n\nfunction classifyFailure(error: unknown, timedOut: boolean): VisibilityProbeFailure {\n if (timedOut) return { code: 'timeout', message: 'The provider request timed out.' }\n if (isAbortError(error)) return { code: 'aborted', message: 'The provider request was cancelled.' }\n return { code: 'provider-error', message: safeProviderErrorMessage(error) }\n}\n\nfunction summarize(checks: readonly VisibilityProbeCheck[]): VisibilityProbeSummary {\n const successfulChecks = checks.filter((check) => check.status === 'success')\n const mentionedChecks = successfulChecks.filter((check) => check.mentioned === true).length\n const citedChecks = successfulChecks.filter((check) => check.cited === true).length\n const denominator = successfulChecks.length\n return {\n totalChecks: checks.length,\n successfulChecks: denominator,\n failedChecks: checks.length - denominator,\n mentionedChecks,\n citedChecks,\n mentionRate: denominator > 0 ? mentionedChecks / denominator : null,\n citationRate: denominator > 0 ? citedChecks / denominator : null,\n }\n}\n\nfunction reportStatus(summary: VisibilityProbeSummary): VisibilityProbeReportStatus {\n if (summary.successfulChecks === 0) return 'failed'\n return summary.failedChecks > 0 ? 'partial' : 'completed'\n}\n\n/** Public helper for callers that want to validate normalized target input before a run. */\nexport function normalizeVisibilityProbeTarget(target: VisibilityProbeTarget): VisibilityProbeTarget {\n const normalized = normalizeTarget(target)\n return { canonicalDomain: normalized.canonicalDomain, brandNames: normalized.brandNames }\n}\n",[],[184,291,293],"910191b8-ae0d-426c-98fa-4fd7b945f7b1","gemini.ts","9378da96-a63e-11f1-9b04-1607ee4eb77e",31,["D",1788292311720],"import { type GenerateContentParameters, type GenerateContentResponse, GoogleGenAI } from '@google/genai'\n\nimport type {\n VisibilityProbeTarget,\n VisibilityProviderAdapter,\n VisibilityProviderRequest,\n VisibilityProviderResponse,\n VisibilityQueryPlan,\n VisibilityQueryPlanner,\n VisibilityQueryPlanningInput,\n VisibilitySource,\n} from './contracts.ts'\nimport { detectMention, hostOf, normalizeTarget } from './brand.ts'\nimport {\n cleanText,\n clipText,\n createDeadlineSignal,\n isAbortError,\n MAX_EXTRACTED_SOURCES,\n MAX_MODEL_ID_CHARS,\n nowIso,\n sleep,\n throwIfAborted,\n uniqueStable,\n} from './runtime.ts'\n\nexport const DEFAULT_GEMINI_VISIBILITY_MODEL = 'gemini-2.5-flash'\nconst VERTEX_AI_SEARCH_PROXY_DOMAIN = 'vertexaisearch.cloud.google.com'\nconst MAX_PLANNER_CONTEXT_CHARS = 12_000\nconst MAX_PLANNER_OUTPUT_TOKENS = 700\n\nexport interface GeminiVisibilityAdapterOptions {\n apiKey: string\n model?: string\n /** 0–2 retries for 429/5xx/network failures. Defaults to one retry. */\n maxRetries?: number\n retryBaseDelayMs?: number\n /** Bounded model output. Defaults to 1,200 and is capped at 2,048. */\n maxOutputTokens?: number\n /** Test/advanced-runtime seam; normal hosts should omit this and use the SDK client. */\n client?: GeminiContentClient\n}\n\nexport interface GeminiContentClient {\n models: {\n generateContent(params: GenerateContentParameters): Promise\n }\n}\n\n/**\n * A Gemini adapter that asks Gemini to use native Google Search grounding.\n * It emits only normalized answer/source evidence and never retains a raw SDK\n * response. The caller owns key storage, budgets, and request admission.\n */\nexport function createGeminiVisibilityAdapter(options: GeminiVisibilityAdapterOptions): VisibilityProviderAdapter {\n const config = normalizeGeminiOptions(options)\n const client = options.client ?? createGeminiClient(config)\n return {\n name: 'gemini',\n requestedModel: config.model,\n async execute(request: VisibilityProviderRequest): Promise {\n const response = await withBoundedRetry(\n () =>\n client.models.generateContent({\n model: config.model,\n contents: request.query.text,\n config: {\n tools: [{ googleSearch: {} }],\n candidateCount: 1,\n temperature: 0,\n maxOutputTokens: config.maxOutputTokens,\n abortSignal: request.signal,\n },\n }),\n request.signal,\n config,\n )\n return normalizeGeminiVisibilityResponse(response, config.model)\n },\n }\n}\n\n/**\n * One bounded planning call for public-domain onboarding. It plans aliases and\n * non-brand buyer queries from caller-provided homepage text; it never fetches\n * the domain itself and does not run a visibility probe.\n */\nexport function createGeminiVisibilityQueryPlanner(options: GeminiVisibilityAdapterOptions): VisibilityQueryPlanner {\n const config = normalizeGeminiOptions(options)\n const client = options.client ?? createGeminiClient(config)\n return {\n name: 'gemini',\n requestedModel: config.model,\n async plan(input: VisibilityQueryPlanningInput): Promise {\n const target = normalizeTarget({ canonicalDomain: input.canonicalDomain, brandNames: input.brandNames ?? [] })\n const context = cleanText(input.homepageContext)\n const maxQueries = boundedPlannerQueryCount(input.maxQueries)\n const deadline = createDeadlineSignal(input.signal, 15_000)\n try {\n throwIfAborted(deadline.signal)\n const response = await withBoundedRetry(\n () =>\n client.models.generateContent({\n model: config.model,\n contents: buildPlannerPrompt({\n canonicalDomain: target.canonicalDomain,\n homepageContext: context ? clipText(context, MAX_PLANNER_CONTEXT_CHARS).value : null,\n maxQueries,\n }),\n config: {\n temperature: 0,\n candidateCount: 1,\n maxOutputTokens: MAX_PLANNER_OUTPUT_TOKENS,\n // Gemini 2.5 does not support structured output plus a built-in\n // tool. We rely on the strict JSON/fence parser below instead.\n tools: [{ googleSearch: {} }],\n abortSignal: deadline.signal,\n },\n }),\n deadline.signal,\n // Planning is one logical and one provider call in the public\n // funnel. Hosts may re-admit a new plan explicitly if desired.\n { ...config, maxRetries: 0 },\n )\n return parseGeminiQueryPlan({\n responseText: extractAnswerText(response),\n target: { canonicalDomain: target.canonicalDomain, brandNames: target.brandNames },\n maxQueries,\n requestedModel: config.model,\n servedModel: extractServedModel(response),\n generatedAt: nowIso(input.now),\n })\n } finally {\n deadline.dispose()\n }\n },\n }\n}\n\ninterface NormalizedGeminiOptions {\n apiKey: string\n model: string\n maxRetries: number\n retryBaseDelayMs: number\n maxOutputTokens: number\n}\n\nfunction normalizeGeminiOptions(options: GeminiVisibilityAdapterOptions): NormalizedGeminiOptions {\n const apiKey = cleanText(options.apiKey)\n if (!apiKey) throw new Error('Gemini API key is required')\n const model = cleanText(options.model) || DEFAULT_GEMINI_VISIBILITY_MODEL\n if (model.length > MAX_MODEL_ID_CHARS) {\n throw new Error(`Gemini model must be at most ${MAX_MODEL_ID_CHARS} characters`)\n }\n return {\n apiKey,\n model,\n maxRetries: clampInteger(options.maxRetries ?? 1, 0, 2),\n retryBaseDelayMs: clampInteger(options.retryBaseDelayMs ?? 400, 100, 2_000),\n maxOutputTokens: clampInteger(options.maxOutputTokens ?? 1_200, 128, 2_048),\n }\n}\n\nexport function createGeminiClient(options: Pick): GoogleGenAI {\n return new GoogleGenAI({ apiKey: options.apiKey })\n}\n\nasync function withBoundedRetry(\n operation: () => Promise,\n signal: AbortSignal,\n config: Pick,\n): Promise {\n let attempt = 0\n for (;;) {\n throwIfAborted(signal)\n try {\n return await operation()\n } catch (error) {\n if (attempt >= config.maxRetries || !isRetryable(error) || isAbortError(error) || signal.aborted) throw error\n const delay = Math.min(config.retryBaseDelayMs * (2 ** attempt), 4_000)\n attempt += 1\n await sleep(delay, signal)\n }\n }\n}\n\nfunction isRetryable(error: unknown): boolean {\n if (error instanceof TypeError) return true\n if (!error || typeof error !== 'object') return false\n const record = error as Record\n const candidate = record.status ?? record.statusCode ?? record.code\n const status = typeof candidate === 'number' ? candidate : Number(candidate)\n if (Number.isInteger(status)) return status === 429 || status >= 500\n const message = error instanceof Error ? error.message : ''\n return /\\b(?:429|500|501|502|503|504)\\b|fetch failed|network/i.test(message)\n}\n\n/** Exported for provider fixture tests; it is deliberately raw-payload free. */\nexport function normalizeGeminiVisibilityResponse(\n response: GenerateContentResponse,\n requestedModel: string,\n): VisibilityProviderResponse {\n const model = boundedModelId(requestedModel)\n if (!model) throw new Error(`Gemini model must be at most ${MAX_MODEL_ID_CHARS} non-whitespace characters`)\n return {\n requestedModel: model,\n servedModel: extractServedModel(response),\n answerText: extractAnswerText(response),\n sources: extractGroundedSources(response),\n searchQueries: extractSearchQueries(response),\n // Google Search grounding is requested, but the API does not reliably\n // attest whether a search actually ran for each answer.\n retrievalStatus: 'unknown',\n }\n}\n\nfunction asRecord(value: unknown): Record | null {\n return value && typeof value === 'object' ? value as Record : null\n}\n\nfunction asRecords(value: unknown): Record[] {\n return Array.isArray(value)\n ? value.flatMap((item) => {\n const record = asRecord(item)\n return record ? [record] : []\n })\n : []\n}\n\nexport function extractAnswerText(response: GenerateContentResponse): string {\n const record = asRecord(response)\n const candidate = asRecords(record?.candidates).at(0)\n const content = asRecord(candidate?.content)\n const parts = asRecords(content?.parts)\n return parts.flatMap((part) => typeof part.text === 'string' ? [part.text] : []).join('')\n}\n\nfunction extractServedModel(response: GenerateContentResponse): string | null {\n return boundedModelId(asRecord(response)?.modelVersion)\n}\n\nexport function extractGroundedSources(response: GenerateContentResponse): VisibilitySource[] {\n const record = asRecord(response)\n const candidate = asRecords(record?.candidates).at(0)\n const metadata = asRecord(candidate?.groundingMetadata)\n const chunks = asRecords(metadata?.groundingChunks)\n const indices = new Set()\n for (const support of asRecords(metadata?.groundingSupports)) {\n const values = support.groundingChunkIndices\n if (!Array.isArray(values)) continue\n for (const value of values) {\n if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value < chunks.length) {\n indices.add(value)\n }\n }\n }\n const selected = indices.size > 0 ? [...indices].map((index) => chunks[index]!).filter(Boolean) : chunks\n const sources: VisibilitySource[] = []\n const seen = new Set()\n for (const chunk of selected) {\n if (sources.length >= MAX_EXTRACTED_SOURCES) break\n const web = asRecord(chunk.web)\n const source = typeof web?.uri === 'string'\n ? normalizeGeminiSource(web.uri, typeof web.title === 'string' ? web.title : null)\n : null\n if (!source || seen.has(source.url)) continue\n seen.add(source.url)\n sources.push(source)\n }\n return sources\n}\n\nfunction normalizeGeminiSource(uri: string, title: string | null): VisibilitySource | null {\n try {\n const parsed = new URL(uri)\n if (hostOf(parsed.hostname) !== VERTEX_AI_SEARCH_PROXY_DOMAIN) {\n return { url: parsed.toString(), title }\n }\n const prefix = '/grounding-api-redirect/'\n if (parsed.pathname.startsWith(prefix)) {\n try {\n const redirect = decodeURIComponent(parsed.pathname.slice(prefix.length))\n const redirected = new URL(redirect)\n if (redirected.protocol === 'https:' || redirected.protocol === 'http:') {\n return { url: redirected.toString(), title }\n }\n } catch {\n // Opaque redirect; retain its URL below without treating its host as a citation.\n }\n }\n // Vertex can return an opaque redirect. Preserve the evidence URL but\n // never attribute the proxy hostname as a source. A title is only usable\n // when it is itself exactly a hostname/domain, never ordinary prose.\n return { url: parsed.toString(), title, domain: titleDomain(title) }\n } catch {\n return null\n }\n}\n\nfunction titleDomain(title: string | null): string | null {\n const candidate = cleanText(title)\n if (!candidate || !/^[a-z0-9.-]+$/i.test(candidate)) return null\n const domain = hostOf(candidate)\n return domain && domain.includes('.') ? domain : null\n}\n\nexport function extractSearchQueries(response: GenerateContentResponse): string[] {\n const record = asRecord(response)\n const candidate = asRecords(record?.candidates).at(0)\n const metadata = asRecord(candidate?.groundingMetadata)\n const values = metadata?.webSearchQueries\n return Array.isArray(values) ? uniqueStable(values.flatMap((value) => typeof value === 'string' ? [value] : [])) : []\n}\n\nfunction boundedPlannerQueryCount(value: number | undefined): number {\n return clampInteger(value ?? 3, 1, 3)\n}\n\nfunction clampInteger(value: number, min: number, max: number): number {\n if (!Number.isFinite(value)) return min\n return Math.max(min, Math.min(max, Math.floor(value)))\n}\n\nexport interface GeminiQueryPlanParseInput {\n responseText: string\n target: VisibilityProbeTarget\n maxQueries: number\n requestedModel: string\n servedModel: string | null\n generatedAt: string\n}\n\n/**\n * Deterministic parser/validator for the planner's one-call JSON response.\n * It accepts only exact JSON and removes branded, duplicate, empty, and\n * overlong queries before returning a plan.\n */\nexport function parseGeminiQueryPlan(input: GeminiQueryPlanParseInput): VisibilityQueryPlan {\n const requestedModel = boundedModelId(input.requestedModel)\n if (!requestedModel) throw new Error(`Gemini model must be at most ${MAX_MODEL_ID_CHARS} non-whitespace characters`)\n let parsed: unknown\n try {\n parsed = JSON.parse(stripCodeFence(input.responseText))\n } catch {\n throw new Error('The query planner returned invalid JSON.')\n }\n const record = asRecord(parsed)\n const rawNames = Array.isArray(record?.brandNames) ? record.brandNames.slice(0, 20) : []\n const rawQueries = Array.isArray(record?.queries) ? record.queries.slice(0, 20) : []\n const plannerNames = rawNames.flatMap((value) => typeof value === 'string' ? [cleanText(value)] : [])\n .filter((name) => name.length > 0 && name.length <= 128)\n const target = normalizeTarget({\n canonicalDomain: input.target.canonicalDomain,\n brandNames: uniqueStable([...input.target.brandNames, ...plannerNames]),\n })\n const seenQueries = new Set()\n const queries = rawQueries.flatMap((value) => typeof value === 'string' ? [cleanText(value)] : [])\n .filter((query) => query.length > 0 && query.length <= 512)\n .filter((query) => {\n const key = query.toLocaleLowerCase('en').replace(/\\s+/g, ' ')\n if (seenQueries.has(key)) return false\n seenQueries.add(key)\n return !detectMention(query, target).mentioned\n })\n .slice(0, input.maxQueries)\n .map((text, index) => ({ id: `planned-query-${index + 1}`, text }))\n if (queries.length !== input.maxQueries) {\n throw new Error(`The query planner did not return ${input.maxQueries} non-brand buyer queries.`)\n }\n return {\n target: { canonicalDomain: target.canonicalDomain, brandNames: target.brandNames },\n queries,\n planner: 'gemini',\n requestedModel,\n servedModel: boundedModelId(input.servedModel),\n generatedAt: input.generatedAt,\n }\n}\n\nfunction boundedModelId(value: unknown): string | null {\n const model = cleanText(value)\n return model && model.length <= MAX_MODEL_ID_CHARS ? model : null\n}\n\nfunction stripCodeFence(value: string): string {\n const trimmed = value.trim()\n if (!trimmed.startsWith('```') || !trimmed.endsWith('```')) return trimmed\n const firstNewline = trimmed.indexOf('\\n')\n if (firstNewline === -1) return trimmed\n const language = trimmed.slice(3, firstNewline).trim().toLowerCase()\n if (language && language !== 'json') return trimmed\n return trimmed.slice(firstNewline + 1, -3).trim()\n}\n\nexport function buildPlannerPrompt(input: {\n canonicalDomain: string\n homepageContext: string | null\n maxQueries: number\n}): string {\n return [\n 'You create a small AI-visibility probe plan from a company website.',\n 'Return JSON only, with this exact shape: {\"brandNames\":[\"...\"],\"queries\":[\"...\"]}.',\n `Return 1-5 exact company/brand aliases and exactly ${input.maxQueries} non-brand buyer-intent queries.`,\n 'Queries must be natural questions or searches a prospective buyer could use before knowing the company.',\n 'Do not include the company name, domain, URLs, competitors, explanations, markdown, or extra keys.',\n `Domain: ${input.canonicalDomain}`,\n input.homepageContext\n ? 'Homepage extract:'\n : 'No homepage extract was provided. Use Google Search grounding to verify the domain context.',\n ...(input.homepageContext ? [input.homepageContext] : []),\n ].join('\\n')\n}\n",[],[184,291,301],"396ac57b-3fb8-40c9-8e0f-13271ea85e04","gemini-probe.ts","9381a0ae-a63e-11f1-8fd4-1607ee4eb77e",32,["D",1788292311602],"import {\n createGeminiVisibilityAdapter,\n createGeminiVisibilityQueryPlanner,\n type GeminiContentClient,\n} from './gemini.ts'\nimport type { VisibilityProbeCheck, VisibilityProbeReport } from './contracts.ts'\nimport { runVisibilityProbe } from './runner.ts'\nimport type {\n VisibilityEvidence,\n VisibilityProbeInput,\n VisibilityProbePort,\n VisibilityReport,\n} from '../runtime/types.ts'\n\nexport interface GeminiValVisibilityProbeOptions {\n apiKey: string\n model?: string\n /** Test seam; production uses the SDK client created by the local adapter. */\n client?: GeminiContentClient\n}\n\nexport const VAL_TOWN_GEMINI_VISIBILITY_LIMITS = {\n maxPlannerCalls: 1,\n maxProbeCalls: 3,\n plannerTimeoutMs: 10_000,\n probeTimeoutMs: 10_000,\n probeConcurrency: 2,\n} as const\n\n/**\n * Val-specific composition of the local planner, provider adapter, and\n * evidence runner. The public host can make exactly one planning call and at\n * most three probe calls per check.\n */\nexport function createGeminiValVisibilityProbe(options: GeminiValVisibilityProbeOptions): VisibilityProbePort {\n const planner = createGeminiVisibilityQueryPlanner({\n apiKey: options.apiKey,\n model: options.model,\n maxRetries: 0,\n maxOutputTokens: 700,\n client: options.client,\n })\n const adapter = createGeminiVisibilityAdapter({\n apiKey: options.apiKey,\n model: options.model,\n maxRetries: 0,\n maxOutputTokens: 1_000,\n client: options.client,\n })\n\n return {\n async probe(input: VisibilityProbeInput): Promise {\n const plannerSignal = AbortSignal.any([\n input.signal,\n AbortSignal.timeout(VAL_TOWN_GEMINI_VISIBILITY_LIMITS.plannerTimeoutMs),\n ])\n const plan = await planner.plan({\n canonicalDomain: input.domain,\n brandNames: [],\n maxQueries: VAL_TOWN_GEMINI_VISIBILITY_LIMITS.maxProbeCalls,\n signal: plannerSignal,\n })\n const report = await runVisibilityProbe({\n target: plan.target,\n queries: plan.queries,\n adapters: [adapter],\n signal: input.signal,\n limits: {\n maxQueries: VAL_TOWN_GEMINI_VISIBILITY_LIMITS.maxProbeCalls,\n maxProviders: 1,\n maxConcurrency: VAL_TOWN_GEMINI_VISIBILITY_LIMITS.probeConcurrency,\n timeoutMs: VAL_TOWN_GEMINI_VISIBILITY_LIMITS.probeTimeoutMs,\n maxAnswerChars: 4_000,\n maxSources: 12,\n maxSearchQueries: 12,\n },\n })\n return toHostReport(input.domain, report)\n },\n }\n}\n\nfunction toHostReport(domain: string, report: VisibilityProbeReport): VisibilityReport {\n return {\n schemaVersion: String(report.schemaVersion),\n domain,\n startedAt: report.startedAt,\n completedAt: report.completedAt,\n summary: {\n successfulChecks: report.summary.successfulChecks,\n failedChecks: report.summary.failedChecks,\n mentionRate: report.summary.mentionRate,\n citationRate: report.summary.citationRate,\n },\n evidence: report.checks.map(toEvidence),\n }\n}\n\nfunction toEvidence(check: VisibilityProbeCheck): VisibilityEvidence {\n return {\n query: check.query,\n provider: check.provider,\n requestedModel: check.requestedModel,\n servedModel: check.servedModel,\n completedAt: check.completedAt,\n answerText: check.answerText,\n mentioned: check.mentioned,\n matchedTerms: check.matchedTerms,\n cited: check.cited,\n citedDomains: check.citedDomains,\n citedUrls: check.citedUrls,\n matchedCitationDomains: check.matchedCitationDomains,\n matchedCitationUrls: check.matchedCitationUrls,\n sources: check.sources.map((source) => ({ url: source.url, title: source.title })),\n searchQueries: check.searchQueries,\n retrievalStatus: check.status === 'failed'\n ? 'error'\n : check.retrievalStatus === 'used'\n ? 'grounded'\n : check.retrievalStatus === 'not-used'\n ? 'not-grounded'\n : 'unknown',\n error: check.error?.message ?? null,\n }\n}\n",[],[184,291,309],"0ddab71a-7a15-42ed-82e7-e1ec8b4c27e8","contracts.ts","93687142-a63e-11f1-9f99-1607ee4eb77e",29,["D",1788292311586],"/** A versioned, persistence-free report contract. */\nexport const VISIBILITY_PROBE_SCHEMA_VERSION = 1 as const\n\n/**\n * User-approved identity for one site. `brandNames` are exact aliases, not\n * fuzzy search terms. A domain counts as an answer mention only when it is\n * written explicitly; the probe never silently derives a prose alias from it.\n */\nexport interface VisibilityProbeTarget {\n canonicalDomain: string\n brandNames: readonly string[]\n}\n\nexport interface VisibilityProbeQuery {\n /** Stable caller identity. A deterministic position-based ID is used when omitted. */\n id?: string\n text: string\n}\n\nexport type VisibilityRetrievalStatus = 'used' | 'not-used' | 'unknown'\n\n/** A provider-normalized source. Never pass raw provider response objects here. */\nexport interface VisibilitySource {\n url: string\n title?: string | null\n /**\n * Optional provider-normalized source domain. `null` explicitly says an\n * opaque provider redirect could not be attributed to a website, so callers\n * must not fall back to the redirect host.\n */\n domain?: string | null\n}\n\n/**\n * What a provider adapter returns after it has interpreted its own response.\n * The runner applies the target-specific mention/citation detection and output\n * caps, so adapters have no Canonry persistence or UI knowledge.\n */\nexport interface VisibilityProviderResponse {\n requestedModel: string\n /** Only use a provider-disclosed identity; never fall back to requestedModel. */\n servedModel?: string | null\n answerText: string\n sources?: readonly VisibilitySource[]\n searchQueries?: readonly string[]\n retrievalStatus?: VisibilityRetrievalStatus\n}\n\nexport interface VisibilityProviderRequest {\n query: VisibilityProbeQuery\n target: VisibilityProbeTarget\n signal: AbortSignal\n limits: VisibilityProbeLimits\n}\n\n/** Provider-neutral execution seam. Adapters own credentials passed at construction. */\nexport interface VisibilityProviderAdapter {\n /** Stable machine identifier, for example `gemini`. */\n readonly name: string\n /** Configuration identity, useful when a request fails before the provider responds. */\n readonly requestedModel?: string\n execute(request: VisibilityProviderRequest): Promise\n}\n\n/**\n * All values are bounded by hard local limits. The public Val Town sample sets\n * tighter product limits (three Gemini queries).\n */\nexport interface VisibilityProbeLimits {\n /** Per query-provider request deadline. */\n timeoutMs: number\n maxConcurrency: number\n maxQueries: number\n maxProviders: number\n maxAnswerChars: number\n maxSources: number\n maxSourceUrlChars: number\n maxSourceTitleChars: number\n maxSearchQueries: number\n maxSearchQueryChars: number\n}\n\nexport const DEFAULT_VISIBILITY_PROBE_LIMITS: VisibilityProbeLimits = {\n timeoutMs: 16_000,\n maxConcurrency: 1,\n maxQueries: 10,\n maxProviders: 4,\n maxAnswerChars: 12_000,\n maxSources: 20,\n maxSourceUrlChars: 2_048,\n maxSourceTitleChars: 512,\n maxSearchQueries: 10,\n maxSearchQueryChars: 300,\n}\n\nexport interface RunVisibilityProbeInput {\n target: VisibilityProbeTarget\n queries: readonly VisibilityProbeQuery[]\n adapters: readonly VisibilityProviderAdapter[]\n limits?: Partial\n /** Cancels outstanding work. A cancellation becomes a failed check, never a false negative. */\n signal?: AbortSignal\n /** Deterministic test seam; no wall-clock state is retained. */\n now?: () => Date\n}\n\nexport type VisibilityProbeCheckStatus = 'success' | 'failed'\nexport type VisibilityProbeReportStatus = 'completed' | 'partial' | 'failed'\n\nexport type VisibilityProbeFailureCode = 'aborted' | 'timeout' | 'provider-error' | 'invalid-response'\n\n/** Safe, clipped error information. Provider bodies and credentials never leave an adapter. */\nexport interface VisibilityProbeFailure {\n code: VisibilityProbeFailureCode\n message: string\n}\n\n/** A source selected for display after output caps are applied. */\nexport interface VisibilityProbeSourceEvidence {\n url: string\n title: string | null\n domain: string | null\n /** This source points to the target domain or one of its subdomains. */\n targetDomainMatch: boolean\n}\n\n/** One query × provider observation. `null` means the check failed, not false. */\nexport interface VisibilityProbeCheck {\n queryId: string\n query: string\n provider: string\n requestedModel: string | null\n servedModel: string | null\n completedAt: string\n status: VisibilityProbeCheckStatus\n answerText: string | null\n answerTruncated: boolean\n mentioned: boolean | null\n matchedTerms: string[]\n cited: boolean | null\n /** All domain identities emitted by the provider's source list, subject to output caps. */\n citedDomains: string[]\n /** All source URLs emitted by the provider's source list, subject to output caps. */\n citedUrls: string[]\n matchedCitationDomains: string[]\n matchedCitationUrls: string[]\n sources: VisibilityProbeSourceEvidence[]\n sourceCount: number\n sourcesTruncated: boolean\n searchQueries: string[]\n searchQueriesTruncated: boolean\n retrievalStatus: VisibilityRetrievalStatus\n error: VisibilityProbeFailure | null\n}\n\n/** Rates use successful query-provider checks only. They are null when none succeeded. */\nexport interface VisibilityProbeSummary {\n totalChecks: number\n successfulChecks: number\n failedChecks: number\n mentionedChecks: number\n citedChecks: number\n mentionRate: number | null\n citationRate: number | null\n}\n\nexport interface VisibilityProbeReport {\n schemaVersion: typeof VISIBILITY_PROBE_SCHEMA_VERSION\n target: VisibilityProbeTarget\n startedAt: string\n completedAt: string\n status: VisibilityProbeReportStatus\n checks: VisibilityProbeCheck[]\n summary: VisibilityProbeSummary\n}\n\n/**\n * Separate optional planning seam. The host supplies any homepage text it has\n * already fetched; the planner never fetches a website to plan a probe.\n */\nexport interface VisibilityQueryPlanningInput {\n canonicalDomain: string\n /** Optional host-fetched homepage extract. An empty value uses grounded domain research only. */\n homepageContext?: string\n brandNames?: readonly string[]\n maxQueries?: number\n signal?: AbortSignal\n /** Deterministic test seam; no wall-clock state is retained. */\n now?: () => Date\n}\n\nexport interface VisibilityQueryPlan {\n target: VisibilityProbeTarget\n queries: VisibilityProbeQuery[]\n planner: string\n requestedModel: string\n servedModel: string | null\n generatedAt: string\n}\n\nexport interface VisibilityQueryPlanner {\n readonly name: string\n readonly requestedModel: string\n plan(input: VisibilityQueryPlanningInput): Promise\n}\n",[],[184,291,317],"40410abf-b9cd-4f61-b495-e6b8b0487782","brand.ts","935818ec-a63e-11f1-b64b-1607ee4eb77e",27,["D",1788292311530],"import type { VisibilityProbeTarget, VisibilitySource } from './contracts.ts'\nimport { cleanText, MAX_BRAND_NAME_CHARS, MAX_BRAND_NAMES, MAX_DOMAIN_CHARS, uniqueStable } from './runtime.ts'\n\n/**\n * Exact brand identity matching, kept Val-local so the probe core has no\n * dependency on Canonry's private workspace contracts at runtime. The behavior\n * deliberately mirrors Canonry's approved-alias model: adjacent\n * complete words only, never substring or edit-distance guesses.\n */\nconst WORD_SEGMENTER = new Intl.Segmenter('en', { granularity: 'word' })\nconst NON_WORD = /[^\\p{L}\\p{N}]+/gu\nconst WORD_RUNS = /[\\p{L}\\p{N}]+/gu\nconst ACCENT_BEARING_SCRIPT = /[\\p{Script=Latin}\\p{Script=Greek}\\p{Script=Cyrillic}]/u\nconst NON_ASCII = /\\P{ASCII}/u\nconst WRITTEN_URL_OR_DOMAIN =\n /(?:https?:\\/\\/|www\\.)[^\\s<>(){}]+|\\b(?:[\\p{L}\\p{N}](?:[\\p{L}\\p{N}-]{0,61}[\\p{L}\\p{N}])?\\.)+[a-z]{2,63}(?:[/?#][^\\s<>(){}]*)?/giu\n\nexport interface NormalizedTarget {\n canonicalDomain: string\n /** Explicit caller-approved names, safe to return on the public report. */\n brandNames: string[]\n /** Exact-match aliases. These are caller-approved names only. */\n aliases: string[]\n}\n\nexport interface MentionEvidence {\n mentioned: boolean\n matchedTerms: string[]\n}\n\nexport interface CitationEvidence {\n cited: boolean\n citedDomains: string[]\n citedUrls: string[]\n matchedCitationDomains: string[]\n matchedCitationUrls: string[]\n sources: NormalizedSource[]\n}\n\nexport interface NormalizedSource {\n url: string\n title: string | null\n domain: string | null\n targetDomainMatch: boolean\n}\n\nfunction foldAccents(value: string): string {\n if (!NON_ASCII.test(value)) return value\n let folded = ''\n for (const character of value) {\n if (character.charCodeAt(0) < 0x80) {\n folded += character\n continue\n }\n const decomposed = character.normalize('NFD')\n const base = decomposed[0]!\n folded += decomposed.length > 1 && ACCENT_BEARING_SCRIPT.test(base) ? base : character\n }\n return folded\n}\n\nfunction normalizedWords(value: string): string[] {\n const normalized = foldAccents(value.normalize('NFKC')).toLocaleLowerCase('en')\n const words: string[] = []\n for (const segment of WORD_SEGMENTER.segment(normalized)) {\n if (!segment.isWordLike) continue\n for (const word of segment.segment.match(WORD_RUNS) ?? []) words.push(word)\n }\n return words\n}\n\nfunction brandKey(value: string): string {\n return normalizedWords(value).join('')\n}\n\nfunction matchedAliasKeys(text: string, aliases: readonly string[]): Set {\n const keys = new Set(aliases.map(brandKey).filter(Boolean))\n if (keys.size === 0) return new Set()\n const normalized = foldAccents(text.normalize('NFKC')).toLocaleLowerCase('en')\n const compact = normalized.replace(NON_WORD, '')\n const reachable = new Set([...keys].filter((key) => compact.includes(key)))\n if (reachable.size === 0) return new Set()\n\n const longest = Math.max(...[...reachable].map((key) => key.length))\n const found = new Set()\n const words = normalizedWords(text)\n for (let start = 0; start < words.length; start++) {\n let candidate = ''\n for (let end = start; end < words.length; end++) {\n candidate += words[end]\n if (reachable.has(candidate)) found.add(candidate)\n if (candidate.length >= longest) break\n }\n if (found.size === reachable.size) break\n }\n return found\n}\n\n/** Normalize only a hostname / http(s) URL; output never retains credentials. */\nexport function hostOf(value: string | null | undefined): string | null {\n const candidate = cleanText(value)\n // A source URL can legitimately be longer than its hostname. Bound the\n // parser input, then validate the resulting hostname independently.\n if (!candidate || candidate.length > 8_192) return null\n const withScheme = /^https?:\\/\\//i.test(candidate) ? candidate : `https://${candidate}`\n try {\n const hostname = new URL(withScheme).hostname.replace(/^www\\./i, '').replace(/\\.$/, '').toLowerCase()\n return hostname && hostname.length <= MAX_DOMAIN_CHARS ? hostname : null\n } catch {\n return null\n }\n}\n\nexport function hostMatchesDomain(candidate: string | null | undefined, domain: string): boolean {\n const candidateHost = hostOf(candidate)\n return candidateHost === domain || Boolean(candidateHost?.endsWith(`.${domain}`))\n}\n\nexport function normalizeTarget(target: VisibilityProbeTarget): NormalizedTarget {\n const canonicalDomain = hostOf(target.canonicalDomain)\n if (!canonicalDomain || !canonicalDomain.includes('.')) {\n throw new Error('target.canonicalDomain must be a valid public hostname')\n }\n if (!Array.isArray(target.brandNames)) throw new Error('target.brandNames must be an array')\n if (target.brandNames.length > MAX_BRAND_NAMES) {\n throw new Error(`target.brandNames may contain at most ${MAX_BRAND_NAMES} entries`)\n }\n\n const explicitNames = target.brandNames.map(cleanText).filter(Boolean)\n if (explicitNames.some((name) => name.length > MAX_BRAND_NAME_CHARS)) {\n throw new Error(`target.brandNames entries must be at most ${MAX_BRAND_NAME_CHARS} characters`)\n }\n const brandNames = uniqueStable(explicitNames)\n return { canonicalDomain, brandNames, aliases: brandNames }\n}\n\nfunction normalizeSourceUrl(value: string): string | null {\n const raw = cleanText(value)\n if (!raw) return null\n try {\n const parsed = new URL(raw)\n if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null\n parsed.username = ''\n parsed.password = ''\n return parsed.toString()\n } catch {\n return null\n }\n}\n\n/** Find explicit written URLs/domains in answer prose, not fuzzy word fragments. */\nfunction writtenHosts(text: string): string[] {\n const hosts: string[] = []\n for (const match of text.matchAll(WRITTEN_URL_OR_DOMAIN)) {\n const candidate = match[0]!.replace(/[.,;:!?]+$/, '')\n const host = hostOf(candidate)\n if (host) hosts.push(host)\n }\n return uniqueStable(hosts)\n}\n\nexport function detectMention(answerText: string, target: NormalizedTarget): MentionEvidence {\n const matchedTerms: string[] = []\n if (writtenHosts(answerText).some((host) => hostMatchesDomain(host, target.canonicalDomain))) {\n matchedTerms.push(target.canonicalDomain)\n }\n\n const matchedKeys = matchedAliasKeys(answerText, target.aliases)\n for (const alias of target.aliases) {\n if (matchedKeys.has(brandKey(alias))) matchedTerms.push(alias)\n }\n const unique = uniqueStable(matchedTerms)\n return {\n mentioned: unique.length > 0,\n matchedTerms: unique,\n }\n}\n\n/**\n * Derive citation evidence strictly from the source list. This intentionally\n * does not inspect answer prose: a mention without a source is not a citation.\n */\nexport function detectCitation(\n inputSources: readonly VisibilitySource[] | undefined,\n target: NormalizedTarget,\n): CitationEvidence {\n const sourceMap = new Map()\n for (const source of inputSources ?? []) {\n const url = normalizeSourceUrl(source.url)\n if (!url || sourceMap.has(url)) continue\n // An adapter may explicitly set `domain: null` for an opaque provider\n // redirect. Do not turn that infrastructure hostname into a citation.\n const domain = source.domain === undefined ? hostOf(url) : hostOf(source.domain)\n sourceMap.set(url, {\n url,\n title: cleanText(source.title) || null,\n domain,\n targetDomainMatch: domain ? hostMatchesDomain(domain, target.canonicalDomain) : false,\n })\n }\n const sources = [...sourceMap.values()]\n const citedDomains = uniqueStable(sources.flatMap((source) => source.domain ? [source.domain] : []))\n const citedUrls = sources.map((source) => source.url)\n const matchedSources = sources.filter((source) => source.targetDomainMatch)\n return {\n cited: matchedSources.length > 0,\n citedDomains,\n citedUrls,\n matchedCitationDomains: uniqueStable(matchedSources.flatMap((source) => source.domain ? [source.domain] : [])),\n matchedCitationUrls: matchedSources.map((source) => source.url),\n sources,\n }\n}\n",[],[184,291,325],"7093d43c-bb87-4fe5-82ad-1c7711051c31",4,["D",1788292309391],[251,252,253,254,255,256],[184,291],"b9daa5e5-0737-4b14-b647-904b6d187cb0","types.ts","931ff2a0-a63e-11f1-b64b-1607ee4eb77e","91e63a7a-a63e-11f1-9a7d-1607ee4eb77e",20,["D",1788292311121],"/**\n * The public Val Town page consumes this intentionally small, serializable\n * view model. The runtime maps normalized Canonry results into it; this layer\n * never reads secrets, provider payloads, or storage directly.\n */\n\nexport type DemoUiStatus =\n | 'demo'\n | 'ready'\n | 'loading'\n | 'partial'\n | 'error'\n | 'rate-limited'\n | 'empty'\n\nexport type VisibilityMetric = 'mentioned' | 'cited'\nexport type EvidenceState = 'success' | 'pending' | 'failed' | 'not-measured'\n\nexport interface UiAction {\n label: string\n href?: string\n /** Submit action when the action is represented by the public check form. */\n formAction?: string\n}\n\nexport interface UiNotice {\n title: string\n detail: string\n tone: 'neutral' | 'positive' | 'caution' | 'negative'\n action?: UiAction\n}\n\nexport interface ProviderDescriptor {\n id: string\n label: string\n /** Requested model, never inferred from a response. */\n model?: string\n color?: string\n}\n\nexport interface VisibilityTrendPoint {\n /** Human-readable bucket label, for example \"May 06\". */\n label: string\n observedAt?: string\n values: Record>>\n}\n\nexport interface VisibilitySummaryMetric {\n /** 0..100 only when denominator is known. */\n rate: number | null\n numerator: number\n denominator: number\n deltaPoints?: number | null\n}\n\nexport interface EvidenceSource {\n url: string\n title?: string | null\n /** Whether the source URL belongs to the checked domain. */\n isTargetDomain?: boolean\n}\n\nexport interface QueryEvidenceViewModel {\n id: string\n query: string\n provider: string\n providerLabel?: string\n requestedModel?: string | null\n servedModel?: string | null\n completedAt?: string | null\n /** A null signal means unavailable, never false. */\n mentioned: boolean | null\n /** A null signal means unavailable, never false. */\n cited: boolean | null\n matchedTerms?: readonly string[]\n answerText?: string | null\n sources?: readonly EvidenceSource[]\n searchQueries?: readonly string[]\n retrievalStatus?: EvidenceState\n error?: string | null\n}\n\nexport interface VisibilityViewModel {\n /** Demo history is explicitly synthetic. Fresh live work is a snapshot. */\n historyKind: 'demo-history' | 'snapshot'\n checkedAt?: string | null\n requestedAt?: string | null\n providers: readonly ProviderDescriptor[]\n summaries: Record\n trend?: readonly VisibilityTrendPoint[]\n evidence: readonly QueryEvidenceViewModel[]\n /** Successful checks only are the denominator for the summary rates. */\n completedChecks: number\n requestedChecks: number\n failedChecks?: number\n notice?: UiNotice\n}\n\nexport type SiteHealthFactorState = 'measured' | 'not-applicable' | 'unavailable'\n\nexport interface SiteHealthFactorViewModel {\n id: string\n label: string\n state: SiteHealthFactorState\n score: number | null\n detail: string\n}\n\nexport type PageHealthStatus = 'good' | 'needs-attention' | 'unavailable'\n\nexport interface SiteHealthPageViewModel {\n url: string\n score: number | null\n status: PageHealthStatus\n findings: readonly string[]\n indexable?: boolean | null\n}\n\nexport interface SiteHealthFixViewModel {\n id: string\n title: string\n detail: string\n affectedPages?: number | null\n}\n\nexport interface SiteHealthProvenanceViewModel {\n /** Crawl-result schema retained so the bounded sample remains traceable. */\n schemaVersion?: string | null\n /** Requested and resolved crawl roots distinguish a redirect from a source URL. */\n rootUrl?: string | null\n finalRootUrl?: string | null\n /** Hosts the bounded runner actually attempted, in order. */\n attemptedHosts?: readonly string[]\n /** Optional engine identity when the host makes it available. */\n engineVersion?: string | null\n}\n\nexport interface SiteHealthViewModel {\n /** Must remain an honest bounded-sample label in the public demo. */\n sampleLabel: string\n score: number | null\n /** URLs found by the bounded crawl, not a total site-page count. */\n discoveredPages: number\n attemptedPages: number\n completedPages: number\n failedPages: number\n checkedAt?: string | null\n factors: readonly SiteHealthFactorViewModel[]\n topFixes: readonly SiteHealthFixViewModel[]\n worstPages: readonly SiteHealthPageViewModel[]\n /** Durable reason a bounded crawl ended before completion, never synthesized. */\n terminationReason?: string | null\n provenance?: SiteHealthProvenanceViewModel\n notice?: UiNotice\n}\n\nexport interface CheckFormViewModel {\n action: string\n method?: 'get' | 'post'\n /** Field read by the server-side verifier. Never render a secret in this model. */\n verificationFieldName?: string\n /** A public Cloudflare Turnstile site key. Omit it for local/test bypasses. */\n turnstileSiteKey?: string | null\n /** `audit` is intentionally fixed so the server can reject action mismatches. */\n turnstileAction?: 'audit'\n /** Production without a configured verifier is truthfully disabled. */\n verificationStatus?: 'ready' | 'not-required' | 'unavailable'\n verificationUnavailableMessage?: string\n submitLabel?: string\n}\n\nexport interface CanonryDemoViewModel {\n status: DemoUiStatus\n title?: string\n displayName: string\n domain: string\n locale?: string\n form?: CheckFormViewModel\n visibility?: VisibilityViewModel\n siteHealth?: SiteHealthViewModel\n notice?: UiNotice\n}\n",[],[184,346,338],"ui","3634ab7f-7575-4b55-bad7-eb76244ebd09","styles.ts","933382e8-a63e-11f1-91a7-1607ee4eb77e",22,["D",1788292311113],"/** Self-contained styles served from `/assets/canonry-ui.css` by the Val host. */\nexport const canonryDemoStyles = String.raw`\n:root {\n color-scheme: dark;\n --bg: #09090b;\n --surface: #111113;\n --surface-soft: #18181b;\n --surface-hover: #202024;\n --border: #29292e;\n --border-strong: #414147;\n --text: #f4f4f5;\n --text-strong: #e4e4e7;\n --secondary: #a1a1aa;\n --muted: #87878f;\n --faint: #62626b;\n --positive: #34d399;\n --caution: #fbbf24;\n --negative: #fb7185;\n --link: #93c5fd;\n --focus: #f4f4f5;\n --sans: Geist, Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n --mono: \"Geist Mono\", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n}\n* { box-sizing: border-box; }\nhtml { background: var(--bg); }\nbody { margin: 0; background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; line-height: 1.5; }\nbutton, input { font: inherit; }\na { color: var(--link); }\na:focus-visible, button:focus-visible, input:focus-visible, summary:focus-visible { outline: 2px solid var(--focus); outline-offset: 3px; }\n.canonry-demo { width: min(100%, 1440px); margin: 0 auto; min-height: 100vh; padding: 0 32px 28px; }\n.app-header { min-height: 74px; display: flex; align-items: center; justify-content: space-between; gap: 22px; border-bottom: 1px solid var(--border); }\n.brand-lockup { display: flex; align-items: baseline; gap: 10px; white-space: nowrap; }\n.wordmark { color: var(--text); font-size: 18px; font-weight: 700; letter-spacing: -.04em; text-decoration: none; }\n.brand-lockup > span { color: var(--muted); font-size: 12px; }\n.domain-form { display: grid; grid-template-columns: auto minmax(360px, 1fr); gap: 6px 10px; align-items: center; max-width: 620px; }\n.domain-form > label { color: var(--secondary); font-size: 13px; white-space: nowrap; }\n.domain-form-row { display: flex; min-width: 0; }\n.domain-form input { min-width: 0; width: 100%; height: 38px; border: 1px solid var(--border-strong); border-radius: 6px 0 0 6px; background: var(--surface); color: var(--text); padding: 0 11px; }\n.domain-form input::placeholder { color: var(--muted); }\n.domain-form button { min-height: 38px; border: 1px solid var(--text); border-radius: 0 6px 6px 0; background: var(--text); color: var(--bg); padding: 0 13px; font-weight: 650; cursor: pointer; white-space: nowrap; }\n.domain-form button:hover { background: #d4d4d8; border-color: #d4d4d8; }\n.domain-form button:active { transform: translateY(1px); }\n.domain-form button:disabled, .domain-form input:disabled { cursor: not-allowed; opacity: .55; }\n.domain-form button:disabled:hover { background: var(--text); border-color: var(--text); }\n.domain-form > p { grid-column: 2; margin: 0; color: var(--muted); font-size: 13px; }\n.verification-slot { grid-column: 2; min-height: 0; }\n.turnstile-wrap { margin-top: 3px; min-height: 65px; }\n.verification-unavailable { display: flex; gap: 7px; align-items: center; margin: 3px 0 0; color: var(--caution); font-size: 13px; }\n.verification-unavailable span { display: grid; width: 17px; height: 17px; place-items: center; border: 1px solid currentColor; border-radius: 50%; font-family: var(--mono); font-size: 11px; }\n.report-header { display: flex; justify-content: space-between; gap: 20px; padding: 38px 0 32px; border-bottom: 1px solid var(--border); }\n.eyebrow { margin: 0 0 7px; color: var(--muted); font-size: 11px; font-weight: 650; letter-spacing: .13em; text-transform: uppercase; }\nh1, h2, h3, p { margin-top: 0; }\nh1 { margin-bottom: 8px; color: var(--text); font-size: clamp(24px, 3vw, 34px); letter-spacing: -.035em; line-height: 1.15; }\nh1 span { display: block; color: var(--secondary); font-size: .55em; font-weight: 500; letter-spacing: -.015em; margin-top: 4px; }\nh2 { margin: 0; color: var(--text-strong); font-size: 21px; font-weight: 600; letter-spacing: -.025em; }\nh3 { color: var(--text-strong); font-size: 15px; font-weight: 600; margin: 0 0 12px; }\n.report-domain { margin: 0; color: var(--secondary); font-family: var(--mono); font-size: 13px; }\n.sample-badge { height: fit-content; border: 1px solid var(--border-strong); border-radius: 999px; color: var(--secondary); font-size: 12px; padding: 4px 9px; white-space: nowrap; }\n.notice { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; gap: 10px; align-items: start; margin: 18px 0 0; border: 1px solid var(--border); border-left-width: 3px; padding: 11px 13px; background: var(--surface); }\n.notice-neutral { border-left-color: var(--secondary); }\n.notice-positive { border-left-color: var(--positive); }\n.notice-caution { border-left-color: var(--caution); }\n.notice-negative { border-left-color: var(--negative); }\n.notice-glyph { display: grid; width: 18px; height: 18px; place-items: center; border: 1px solid currentColor; border-radius: 50%; color: var(--secondary); font-family: var(--mono); font-size: 11px; line-height: 1; }\n.notice-caution .notice-glyph { color: var(--caution); }\n.notice-negative .notice-glyph { color: var(--negative); }\n.notice-title { margin: 0; color: var(--text-strong); font-weight: 600; }\n.notice-detail { margin: 1px 0 0; color: var(--secondary); font-size: 13px; }\n.notice-link { align-self: center; font-size: 13px; white-space: nowrap; }\n.report-tabs { display: flex; gap: 28px; height: 62px; align-items: end; border-bottom: 1px solid var(--border); }\n.report-tabs button { position: relative; min-height: 45px; border: 0; padding: 0 0 14px; background: transparent; color: var(--secondary); cursor: pointer; font-size: 15px; font-weight: 550; }\n.report-tabs button:hover { color: var(--text); }\n.report-tabs button[aria-selected=\"true\"] { color: var(--text); }\n.report-tabs button[aria-selected=\"true\"]::after { position: absolute; right: 0; bottom: -1px; left: 0; height: 2px; background: var(--text); content: \"\"; }\n[data-report-panel] { padding-top: 34px; }\n.analysis-section { padding: 0 0 36px; border-bottom: 1px solid var(--border); }\n.analysis-section + .analysis-section { padding-top: 32px; }\n.section-heading { display: flex; align-items: start; justify-content: space-between; gap: 18px; margin-bottom: 22px; }\n.section-heading .eyebrow { margin-bottom: 5px; }\n.trend-heading { align-items: end; }\n.signal-summary { display: flex; align-items: baseline; justify-content: flex-end; flex-wrap: wrap; gap: 8px; text-align: right; }\n.signal-summary .metric-label { color: var(--secondary); font-size: 13px; }\n.signal-summary strong { color: var(--text); font-family: var(--mono); font-size: 30px; letter-spacing: -.06em; line-height: 1; }\n.metric-delta { font-family: var(--mono); font-size: 13px; font-weight: 600; }\n.metric-delta.up { color: var(--positive); }\n.metric-delta.down { color: var(--negative); }\n.chart-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-bottom: 15px; }\n.segmented-control { display: inline-flex; border: 1px solid var(--border-strong); border-radius: 6px; overflow: hidden; }\n.metric-toggle { min-height: 34px; border: 0; border-right: 1px solid var(--border-strong); padding: 0 12px; background: transparent; color: var(--secondary); cursor: pointer; font-weight: 550; }\n.metric-toggle:last-child { border-right: 0; }\n.metric-toggle:hover { background: var(--surface-hover); color: var(--text); }\n.metric-toggle.is-active { background: #42424a; color: var(--text); }\n.chart-denominator { margin: 0; color: var(--muted); font-family: var(--mono); font-size: 13px; }\n.chart-legend { display: flex; flex-wrap: wrap; gap: 9px 20px; margin: 0 0 14px; padding: 0; list-style: none; }\n.chart-legend li { display: inline-flex; align-items: center; gap: 7px; color: var(--secondary); font-size: 13px; }\n.chart-legend strong { color: var(--text-strong); font-family: var(--mono); font-size: 12px; }\n.chart-legend code { color: var(--muted); font-family: var(--mono); font-size: 11px; }\n.legend-line { width: 23px; height: 3px; border-radius: 999px; background: var(--series-color, var(--secondary)); }\n.series-0 { --series-color: #fb923c; }\n.series-1 { --series-color: #60a5fa; }\n.series-2 { --series-color: #34d399; }\n.series-3 { --series-color: #22d3ee; }\n.series-4 { --series-color: #a78bfa; }\n.trend-chart { min-height: 275px; border-top: 1px solid var(--border); border-bottom: 1px solid var(--border); padding: 14px 0 4px; }\n.trend-svg { display: block; width: 100%; height: 275px; overflow: visible; }\n.chart-grid { stroke: #29292e; stroke-width: 1; }\n.chart-axis { fill: #94949d; font-family: var(--mono); font-size: 11px; }\n.chart-line { fill: none; stroke: var(--series-color, var(--secondary)); stroke-width: 3; stroke-linecap: round; stroke-linejoin: round; vector-effect: non-scaling-stroke; }\n.chart-dot { fill: var(--series-color, var(--secondary)); }\n.chart-caption { margin: 12px 0 0; color: var(--secondary); font-size: 13px; }\n.data-disclosure { margin-top: 14px; color: var(--secondary); }\n.data-disclosure > summary, .evidence-detail > summary, .page-detail > summary { width: fit-content; color: var(--link); cursor: pointer; font-size: 13px; }\n.data-disclosure > summary:hover, .evidence-detail > summary:hover, .page-detail > summary:hover { color: #dbeafe; }\n.table-wrap { overflow-x: auto; max-width: 100%; }\n.compact-table, .evidence-table { width: 100%; border-collapse: collapse; min-width: 680px; text-align: left; }\n.compact-table { margin-top: 12px; }\nth { color: var(--secondary); font-size: 11px; font-weight: 650; letter-spacing: .075em; text-transform: uppercase; }\nth, td { border-bottom: 1px solid var(--border); padding: 11px 12px; vertical-align: top; }\ntbody th { color: var(--text-strong); font-size: 13px; font-weight: 550; letter-spacing: normal; text-transform: none; }\ntd { color: var(--secondary); font-size: 13px; }\n.section-intro { max-width: 68ch; margin: -10px 0 18px; color: var(--secondary); font-size: 13px; }\n.query-text { display: inline-block; max-width: 37ch; }\n.signal { display: inline-flex; align-items: center; gap: 5px; white-space: nowrap; font-size: 13px; font-weight: 550; }\n.signal-positive { color: var(--positive); }\n.signal-neutral { color: var(--secondary); }\n.signal-caution { color: var(--caution); }\n.signal-unavailable { color: var(--muted); }\n.evidence-detail > summary, .page-detail > summary { white-space: nowrap; }\n.evidence-content { max-width: 720px; padding: 12px 0 4px; }\n.evidence-meta { display: flex; flex-wrap: wrap; gap: 6px 16px; color: var(--muted); font-size: 12px; }\ncode { color: var(--text-strong); font-family: var(--mono); font-size: .92em; }\n.detail-label { display: block; margin: 12px 0 4px; color: var(--muted); font-size: 11px; font-weight: 650; letter-spacing: .09em; text-transform: uppercase; }\n.evidence-answer blockquote { max-width: 72ch; margin: 0; border-left: 2px solid var(--border-strong); padding-left: 11px; color: var(--text-strong); }\n.detail-empty { color: var(--muted); font-size: 13px; }\n.detail-error { color: var(--negative); }\n.source-list { display: grid; gap: 7px; margin: 0; padding: 0; list-style: none; }\n.source-title { display: block; overflow: hidden; max-width: 70ch; color: var(--link); text-overflow: ellipsis; white-space: nowrap; }\n.source-host { display: block; color: var(--muted); font-family: var(--mono); font-size: 11px; }\n.empty-state, .snapshot-state { display: flex; gap: 12px; align-items: flex-start; border: 1px dashed var(--border-strong); padding: 19px; color: var(--secondary); }\n.empty-state p, .snapshot-state p { margin: 0; }\n.empty-title, .snapshot-title { color: var(--text-strong); font-weight: 600; }\n.snapshot-icon { color: var(--muted); font-family: var(--mono); font-size: 22px; line-height: 1; }\n.snapshot-metrics { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px; margin: 18px 0 0; }\n.snapshot-metrics > div { border-top: 1px solid var(--border); padding-top: 11px; }\n.snapshot-metrics dt { color: var(--secondary); font-size: 13px; }\n.snapshot-metrics dd { margin: 3px 0 0; color: var(--text); font-family: var(--mono); font-size: 25px; font-weight: 650; letter-spacing: -.05em; }\n.snapshot-metrics span { color: var(--muted); font-size: 13px; }\n.checked-at { margin: 0; color: var(--muted); font-family: var(--mono); font-size: 12px; }\n.site-score { display: flex; align-items: baseline; gap: 9px; white-space: nowrap; }\n.site-score span { color: var(--secondary); font-size: 13px; }\n.site-score strong { color: var(--text); font-family: var(--mono); font-size: 24px; letter-spacing: -.05em; }\n.sample-facts { display: flex; flex-wrap: wrap; gap: 6px 16px; margin: -6px 0 24px; color: var(--secondary); font-size: 13px; }\n.sample-facts span + span::before { display: inline-block; margin-right: 16px; color: var(--faint); content: \"·\"; }\n.sample-facts strong { color: var(--text-strong); font-family: var(--mono); }\n.site-grid { display: grid; grid-template-columns: minmax(0, 1.2fr) minmax(300px, .8fr); gap: 34px; }\n.factor-list, .fix-list { margin: 0; padding: 0; list-style: none; }\n.factor-row { display: grid; grid-template-columns: minmax(0, 1fr) minmax(150px, .42fr); gap: 16px; align-items: center; border-top: 1px solid var(--border); padding: 12px 0; }\n.factor-row:last-child { border-bottom: 1px solid var(--border); }\n.factor-row p, .fix-list p { margin: 0; color: var(--text-strong); font-weight: 550; }\n.factor-row > div > span, .fix-list span { display: block; margin-top: 2px; color: var(--secondary); font-size: 13px; }\n.factor-score { display: flex; align-items: center; gap: 9px; }\n.factor-score meter { width: 100%; height: 9px; accent-color: var(--secondary); }\n.factor-positive meter { accent-color: var(--positive); }\n.factor-caution meter { accent-color: var(--caution); }\n.factor-negative meter { accent-color: var(--negative); }\n.factor-score strong { min-width: 58px; color: var(--text-strong); font-family: var(--mono); font-size: 13px; text-align: right; white-space: nowrap; }\n.factor-state { color: var(--muted); font-size: 13px; text-align: right; }\n.fix-list { display: grid; gap: 0; border-top: 1px solid var(--border); }\n.fix-list li { display: grid; grid-template-columns: 25px minmax(0, 1fr); gap: 9px; border-bottom: 1px solid var(--border); padding: 12px 0; }\n.fix-index { display: grid; width: 20px; height: 20px; place-items: center; border: 1px solid var(--border-strong); border-radius: 50%; color: var(--secondary); font-family: var(--mono); font-size: 11px; }\n.worst-pages { margin-top: 34px; }\n.url-cell a { display: inline-block; max-width: 48ch; overflow: hidden; color: var(--text-strong); text-overflow: ellipsis; white-space: nowrap; }\n.score-cell { color: var(--text-strong); font-family: var(--mono); white-space: nowrap; }\n.page-detail > div { max-width: 60ch; padding: 10px 0 2px; }\n.page-detail ul { display: grid; gap: 4px; margin: 0; padding-left: 18px; color: var(--secondary); }\n.page-indexability { margin: 10px 0 0; color: var(--secondary); }\n.sample-scope > p { max-width: 70ch; margin: 9px 0 0; color: var(--secondary); font-size: 13px; }\n.sample-scope .sample-provenance { color: var(--muted); font-family: var(--mono); font-size: 12px; }\n.no-js-site-health { padding-top: 34px; }\n.app-footer { display: flex; justify-content: space-between; gap: 14px; padding: 23px 0 4px; color: var(--muted); font-size: 12px; }\n.app-footer a { color: var(--secondary); }\n.app-footer > span:first-child { max-width: 62ch; }\n.footer-links { display: flex; align-items: baseline; gap: 13px; white-space: nowrap; }\n.footer-links code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; color: var(--secondary); }\n.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; }\n[hidden] { display: none !important; }\n@media (max-width: 860px) {\n .canonry-demo { padding: 0 20px 24px; }\n .app-header { align-items: flex-start; flex-direction: column; padding: 18px 0; }\n .domain-form { width: 100%; max-width: none; grid-template-columns: 1fr; }\n .domain-form > p, .verification-slot { grid-column: 1; }\n .domain-form > label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; }\n .report-header { padding: 28px 0 24px; }\n .site-grid { grid-template-columns: 1fr; gap: 28px; }\n}\n@media (max-width: 600px) {\n body { font-size: 14px; }\n .canonry-demo { padding: 0 14px 20px; }\n .report-header, .section-heading, .trend-heading { align-items: flex-start; flex-direction: column; }\n .signal-summary { justify-content: flex-start; text-align: left; }\n .chart-toolbar { align-items: flex-start; flex-direction: column; }\n .chart-legend { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }\n .chart-legend li { min-width: 0; flex-wrap: wrap; gap: 5px; }\n .chart-legend code { display: none; }\n .trend-chart, .trend-svg { min-height: 225px; height: 225px; }\n .site-score { margin-top: -10px; }\n .snapshot-metrics { grid-template-columns: 1fr; gap: 12px; }\n .factor-row { grid-template-columns: 1fr; gap: 8px; }\n .factor-state { text-align: left; }\n .sample-facts { display: grid; gap: 5px; }\n .sample-facts span + span::before { display: none; }\n .notice { grid-template-columns: auto minmax(0, 1fr); }\n .notice-link { grid-column: 2; }\n}\n@media (prefers-reduced-motion: reduce) {\n *, *::before, *::after { scroll-behavior: auto !important; transition-duration: .01ms !important; animation-duration: .01ms !important; animation-iteration-count: 1 !important; }\n}\n`\n",[],[184,346,348],"9d0af8f4-4821-482d-a8f5-0411cfb49b7c","render.ts","9343b730-a63e-11f1-a6d3-1607ee4eb77e",24,["D",1788292311388],"import type {\n CanonryDemoViewModel,\n DemoUiStatus,\n EvidenceSource,\n QueryEvidenceViewModel,\n SiteHealthFactorViewModel,\n SiteHealthPageViewModel,\n UiNotice,\n VisibilityMetric,\n VisibilityViewModel,\n} from './types.ts'\n\nconst DEFAULT_CSS_HREF = '/assets/canonry-ui.css'\nconst DEFAULT_SCRIPT_SRC = '/assets/canonry-ui.js'\nconst MAX_ANSWER_CHARS = 1_400\n\nfunction escapeHtml(value: unknown): string {\n return String(value ?? '')\n .replaceAll('&', '&')\n .replaceAll('<', '<')\n .replaceAll('>', '>')\n .replaceAll('\"', '"')\n .replaceAll(\"'\", ''')\n}\n\nfunction escapeAttr(value: unknown): string {\n return escapeHtml(value).replaceAll('`', '`')\n}\n\nfunction safeUrl(value: string): string | null {\n try {\n const url = new URL(value)\n return url.protocol === 'https:' || url.protocol === 'http:' ? url.toString() : null\n } catch {\n return null\n }\n}\n\nfunction safeHref(value: string): string | null {\n if (value.startsWith('/') && !value.startsWith('//')) return value\n return safeUrl(value)\n}\n\nfunction safeFormAction(value: string): string {\n return value.startsWith('/') && !value.startsWith('//') ? value : '/check'\n}\n\nfunction safeHost(value: string): string {\n const url = safeUrl(value)\n if (!url) return 'Unavailable source'\n return new URL(url).hostname\n}\n\nfunction clip(value: string | null | undefined, limit = MAX_ANSWER_CHARS): string {\n if (!value) return ''\n return value.length > limit ? `${value.slice(0, limit - 1).trimEnd()}…` : value\n}\n\nfunction isFiniteNumber(value: number | null | undefined): value is number {\n return typeof value === 'number' && Number.isFinite(value)\n}\n\nfunction asPercent(value: number | null | undefined): string {\n if (!isFiniteNumber(value)) return 'Not measured'\n return `${Number.isInteger(value) ? value : value.toFixed(1)}%`\n}\n\nfunction asScore(value: number | null | undefined): string {\n return isFiniteNumber(value) ? `${Math.round(value)} / 100` : 'Not measured'\n}\n\nfunction formatTime(value: string | null | undefined): string | null {\n if (!value) return null\n const date = new Date(value)\n if (Number.isNaN(date.valueOf())) return null\n return new Intl.DateTimeFormat('en-US', {\n month: 'short',\n day: 'numeric',\n year: 'numeric',\n hour: 'numeric',\n minute: '2-digit',\n }).format(date)\n}\n\nfunction statusCopy(status: DemoUiStatus): UiNotice | null {\n switch (status) {\n case 'loading':\n return {\n tone: 'neutral',\n title: 'Checking this domain',\n detail: 'The report will appear here when the bounded checks finish.',\n }\n case 'partial':\n return {\n tone: 'caution',\n title: 'Partial result',\n detail: 'Only completed checks are included below. Failed checks are shown separately.',\n }\n case 'error':\n return {\n tone: 'negative',\n title: 'This check could not finish',\n detail: 'Try again later or use a domain that responds publicly.',\n }\n case 'rate-limited':\n return {\n tone: 'caution',\n title: 'Check limit reached',\n detail: 'This public sample has reached its current limit. Try again later.',\n }\n case 'empty':\n return { tone: 'neutral', title: 'No report yet', detail: 'Enter a public domain to create a bounded snapshot.' }\n default:\n return null\n }\n}\n\nfunction renderNotice(notice: UiNotice | undefined): string {\n if (!notice) return ''\n const href = notice.action?.href ? safeHref(notice.action.href) : null\n const action = href && notice.action\n ? `${escapeHtml(notice.action.label)}`\n : ''\n return `\n `\n}\n\nfunction providerSeriesClass(index: number): string {\n return `series-${index % 5}`\n}\n\nfunction chartPointX(index: number, count: number): number {\n const left = 56\n const right = 892\n if (count <= 1) return (left + right) / 2\n return left + ((right - left) * index) / (count - 1)\n}\n\nfunction chartPointY(value: number): number {\n const top = 18\n const bottom = 218\n const normalized = Math.max(0, Math.min(100, value))\n return bottom - ((bottom - top) * normalized) / 100\n}\n\nfunction renderTrendPath(values: Array, pointCount: number): string {\n let segment = ''\n let started = false\n for (let index = 0; index < pointCount; index += 1) {\n const value = values[index]\n if (!isFiniteNumber(value)) {\n started = false\n continue\n }\n const command = started ? 'L' : 'M'\n segment += `${command}${chartPointX(index, pointCount).toFixed(1)},${chartPointY(value).toFixed(1)} `\n started = true\n }\n return segment.trim()\n}\n\nfunction renderTrendSvg(visibility: VisibilityViewModel, metric: VisibilityMetric): string {\n const trend = visibility.trend ?? []\n const gridLabels = [100, 75, 50, 25, 0]\n const grids = gridLabels.map((value) => {\n const y = chartPointY(value)\n return `${value}%`\n }).join('')\n const labels = trend.map((point, index) => (\n `${\n escapeHtml(point.label)\n }`\n )).join('')\n const paths = visibility.providers.map((provider, index) => {\n const values = trend.map((point) => point.values[provider.id]?.[metric] ?? null)\n const path = renderTrendPath(values, trend.length)\n const series = providerSeriesClass(index)\n const dots = values.map((value, pointIndex) =>\n isFiniteNumber(value)\n ? ``\n : ''\n ).join('')\n return path ? `${dots}` : ''\n }).join('')\n const title = metric === 'mentioned' ? 'Mentioned in answer trend' : 'Cited in source trend'\n return `\n `\n}\n\nfunction renderTrendData(visibility: VisibilityViewModel, metric: VisibilityMetric): string {\n const trend = visibility.trend ?? []\n if (trend.length === 0) return ''\n const columns = visibility.providers.map((provider) => `${escapeHtml(provider.label)}`).join('')\n const rows = trend.map((point) => {\n const cells = visibility.providers.map((provider) =>\n `${asPercent(point.values[provider.id]?.[metric] ?? null)}`\n ).join('')\n return `${escapeHtml(point.label)}${cells}`\n }).join('')\n return `\n

Trend data

${columns}${rows}

Date

`\n}\n\nfunction metricLabel(metric: VisibilityMetric): string {\n return metric === 'mentioned' ? 'Mentioned' : 'Cited'\n}\n\nfunction renderMetricSummary(visibility: VisibilityViewModel, metric: VisibilityMetric, hidden = false): string {\n const summary = visibility.summaries[metric]\n return `

\n ${metricLabel(metric)}${asPercent(summary.rate)}${\n isFiniteNumber(summary.deltaPoints)\n ? `= 0 ? 'up' : 'down'}\">${summary.deltaPoints >= 0 ? '+' : ''}${\n summary.deltaPoints.toFixed(1)\n } pts`\n : ''\n }\n

`\n}\n\nfunction renderTrendLegend(visibility: VisibilityViewModel, metric: VisibilityMetric): string {\n const latest = visibility.trend?.at(-1)\n const rows = visibility.providers.map((provider, index) => {\n const latestValue = latest?.values[provider.id]?.[metric] ?? null\n return `

${\n escapeHtml(provider.label)\n }${provider.model ? `${escapeHtml(provider.model)}` : ''}${\n asPercent(latestValue)\n }

`\n }).join('')\n return `

${rows}`\n}\n\nfunction renderTrendMetricPanel(visibility: VisibilityViewModel, metric: VisibilityMetric, hidden = false): string {\n return `

\n ${renderTrendLegend(visibility, metric)}\n

${renderTrendSvg(visibility, metric)}

Mentioned is answer text. Cited is a source link to this domain. They are independent signals.

${renderTrendData(visibility, metric)}

`\n}\n\nfunction renderVisibilityChart(visibility: VisibilityViewModel): string {\n const isHistory = visibility.historyKind === 'demo-history' && (visibility.trend?.length ?? 0) > 1\n const mention = visibility.summaries.mentioned\n const cite = visibility.summaries.cited\n const checkedAt = formatTime(visibility.checkedAt)\n if (!isHistory) {\n return `\n

AI visibility

Fresh snapshot

\n ${checkedAt ? `

Checked ${escapeHtml(checkedAt)}

` : ''}\n

\n ○\n

No trend yet

A fresh domain is measured once. Canonry does not invent prior history.

Mentioned: ${\n asPercent(mention.rate)\n }
Cited: ${\n asPercent(cite.rate)\n }

`\n }\n return `\n

Trend

Answer-engine trend

\n ${renderMetricSummary(visibility, 'mentioned')}\n ${renderMetricSummary(visibility, 'cited', true)}\n

\n \n ${renderTrendMetricPanel(visibility, 'mentioned')}\n ${renderTrendMetricPanel(visibility, 'cited', true)}\n

`\n}\n\nfunction signalLabel(value: boolean | null, positive: string, negative: string): string {\n if (value === true) return positive\n if (value === false) return negative\n return 'Not measured'\n}\n\nfunction signalClass(value: boolean | null): string {\n if (value === true) return 'signal-positive'\n if (value === false) return 'signal-neutral'\n return 'signal-unavailable'\n}\n\nfunction renderSource(source: EvidenceSource): string {\n const url = safeUrl(source.url)\n const title = source.title?.trim() || safeHost(source.url)\n if (!url) {\n return `

${\n escapeHtml(title)\n }Unavailable URL

`\n }\n return `

${\n escapeHtml(title)\n }${escapeHtml(safeHost(url))}${\n source.isTargetDomain ? ' · target source' : ''\n }

`\n}\n\nfunction renderEvidenceDetails(row: QueryEvidenceViewModel): string {\n const answer = row.answerText\n ? `

${escapeHtml(clip(row.answerText))}

`\n : '

Answer text was not retained for this result.

'\n const sources = row.sources?.length\n ? `

${row.sources.map(renderSource).join('')}`\n : '

No source URLs were recorded.

'\n const matched = row.matchedTerms?.length\n ? `

Matched terms${escapeHtml(row.matchedTerms.join(', '))}

`\n : ''\n const models = [\n row.requestedModel ? `Requested: ${escapeHtml(row.requestedModel)}` : '',\n row.servedModel ? `Served: ${escapeHtml(row.servedModel)}` : '',\n ].filter(Boolean).join('')\n const searches = row.searchQueries?.length\n ? `

Search queries${escapeHtml(row.searchQueries.join(', '))}

`\n : ''\n const error = row.error\n ? `

Unavailable${escapeHtml(row.error)}

`\n : ''\n return `\n

View evidence

${models}${\n row.completedAt && formatTime(row.completedAt)\n ? `Completed: ${escapeHtml(formatTime(row.completedAt)!)}`\n : ''\n }

Answer

${answer}

\n ${matched}${searches}${error}\n

Sources

${sources}

`\n}\n\nfunction renderEvidence(visibility: VisibilityViewModel): string {\n const rows = visibility.evidence.map((row) => `\n \n ${escapeHtml(row.query)}\n ${escapeHtml(row.providerLabel ?? row.provider)}\n ${\n row.mentioned === true ? '✓' : row.mentioned === false ? '−' : '?'\n }${signalLabel(row.mentioned, 'Mentioned', 'Not mentioned')}\n ${\n row.cited === true ? '✓' : row.cited === false ? '−' : '?'\n }${signalLabel(row.cited, 'Cited', 'Not cited')}\n ${renderEvidenceDetails(row)}\n `).join('')\n const empty =\n '

No completed query evidence

Evidence appears after a check returns an answer.

'\n return `\n

Evidence

Query evidence

Mentioned means the brand appears in answer text. Cited means a source URL belongs to the checked domain.

\n ${visibility.notice ? renderNotice(visibility.notice) : ''}\n ${\n visibility.evidence.length\n ? `

${rows}

Query	Engine	Mentioned	Cited	Evidence

`\n : empty\n }\n

`\n}\n\nfunction factorTone(factor: SiteHealthFactorViewModel): string {\n if (factor.state !== 'measured' || !isFiniteNumber(factor.score)) return 'factor-unavailable'\n if (factor.score >= 80) return 'factor-positive'\n if (factor.score >= 60) return 'factor-caution'\n return 'factor-negative'\n}\n\nfunction renderFactor(factor: SiteHealthFactorViewModel): string {\n const content = factor.state === 'measured' && isFiniteNumber(factor.score)\n ? `

${\n asScore(factor.score)\n }

`\n : `${factor.state === 'not-applicable' ? 'Not applicable' : 'Unavailable'}`\n return `

${escapeHtml(factor.label)}

${\n escapeHtml(factor.detail)\n }

${content}

`\n}\n\nfunction pageStatusLabel(status: SiteHealthPageViewModel['status']): string {\n if (status === 'good') return 'Good'\n if (status === 'needs-attention') return 'Needs attention'\n return 'Unavailable'\n}\n\nfunction renderPageDetails(page: SiteHealthPageViewModel): string {\n const facts = page.findings.length\n ? `

${escapeHtml(finding)}

`\n : '

No page-level findings were retained.

'\n return `

View findings

${facts}${\n page.indexable != null\n ? `

${\n page.indexable ? 'Indexable in this sample.' : 'Not indexable in this sample.'\n }

`\n : ''\n }

`\n}\n\nfunction readableValue(value: string): string {\n return value.replaceAll(/[-_]+/g, ' ').replaceAll(/\\s+/g, ' ').trim()\n}\n\nfunction renderSiteHealth(siteHealth: CanonryDemoViewModel['siteHealth'], idPrefix = 'site-health'): string {\n const headingId = `${idPrefix}-heading`\n const factorHeadingId = `${idPrefix}-factors`\n const fixHeadingId = `${idPrefix}-fixes`\n const worstPagesHeadingId = `${idPrefix}-worst-pages`\n if (!siteHealth) {\n return `\n

Site health

Technical AEO sample

No site-health sample

A bounded crawl can appear with a domain check.

`\n }\n const checkedAt = formatTime(siteHealth.checkedAt)\n const pages = siteHealth.worstPages.map((page) => {\n const url = safeUrl(page.url)\n const label = escapeHtml(page.url.replace(/^https?:\\/\\//, ''))\n const pageLink = url\n ? `${label}`\n : `${label}`\n return `${pageLink}${escapeHtml(pageStatusLabel(page.status))}${asScore(page.score)}${\n renderPageDetails(page)\n }`\n }).join('')\n const fixes = siteHealth.topFixes.map((fix, index) =>\n `

${index + 1}

${escapeHtml(fix.title)}

${\n escapeHtml(fix.detail)\n }${\n isFiniteNumber(fix.affectedPages)\n ? ` ${fix.affectedPages} sampled ${fix.affectedPages === 1 ? 'page' : 'pages'}.`\n : ''\n }

`\n ).join('')\n const termination = siteHealth.terminationReason\n ? `

Partial termination: ${escapeHtml(readableValue(siteHealth.terminationReason))}.

`\n : ''\n const provenance = [\n siteHealth.provenance?.schemaVersion ? `Crawl schema ${siteHealth.provenance.schemaVersion}` : '',\n siteHealth.provenance?.engineVersion ? `Engine ${siteHealth.provenance.engineVersion}` : '',\n ].filter(Boolean).join(' · ')\n return `\n

Site health

${escapeHtml(siteHealth.sampleLabel)}

Sample score${asScore(siteHealth.score)}

${siteHealth.completedPages} of ${siteHealth.attemptedPages} pages completed${siteHealth.discoveredPages} pages discovered${\n siteHealth.failedPages === 0\n ? 'No failed pages'\n : `${siteHealth.failedPages} failed ${siteHealth.failedPages === 1 ? 'page' : 'pages'}`\n }${checkedAt ? `Checked ${escapeHtml(checkedAt)}` : ''}

\n ${siteHealth.notice ? renderNotice(siteHealth.notice) : ''}\n

Factors

${\n siteHealth.factors.map(renderFactor).join('')\n }

Top fixes

${\n siteHealth.topFixes.length\n ? `

${fixes}`\n : '

No prioritized fixes in this sample.

'\n }

Worst sampled pages

${\n pages\n ? `

${pages}

Page	Status	Score	Findings

`\n : '

No page audit evidence is available.

'\n }

Sample scope

This is a bounded page sample, not a complete technical audit. A score applies only to the pages and factors checked here.

${termination}${\n provenance ? `

${escapeHtml(provenance)}

` : ''\n }

`\n}\n\nfunction renderCheckForm(model: CanonryDemoViewModel): 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 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 return `\n `\n}\n\nfunction renderMain(model: CanonryDemoViewModel): string {\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 return `\n

\n \n

${model.status === 'demo' ? 'Demo report' : 'Domain report'}

${escapeHtml(model.displayName)}AI visibility and site health

${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)}${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} | Canonry`\n return `\n\n \n \n \n \n ${escapeHtml(title)}\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",[],[184,346,356],"97e365c1-708a-43b8-8d79-ebbb0b4a4610","index.ts","93608ea0-a63e-11f1-9b04-1607ee4eb77e",28,["D",1788292311400],"export { demoCanonryViewModel } from '../fixtures/demo-report.ts'\nexport { createPublicCheckForm } from './check-form.ts'\nexport { canonryDemoClientScript } from './client.ts'\nexport { toCanonryDemoViewModel } from './from-check-record.ts'\nexport type { CheckRecordViewOptions } from './from-check-record.ts'\nexport { renderCanonryDemo, renderCanonryDemoBody } from './render.ts'\nexport { canonryDemoStyles } from './styles.ts'\nexport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n DemoUiStatus,\n EvidenceSource,\n EvidenceState,\n ProviderDescriptor,\n QueryEvidenceViewModel,\n SiteHealthFactorState,\n SiteHealthFactorViewModel,\n SiteHealthFixViewModel,\n SiteHealthPageViewModel,\n SiteHealthProvenanceViewModel,\n SiteHealthViewModel,\n UiAction,\n UiNotice,\n VisibilityMetric,\n VisibilitySummaryMetric,\n VisibilityTrendPoint,\n VisibilityViewModel,\n} from './types.ts'\n",[],[184,346,364],"6b5562ec-bdd4-495a-93a1-30472a334cc6","from-check-record.ts","9329ca82-a63e-11f1-9b04-1607ee4eb77e",21,["D",1788292311210],"import type {\n CheckRecord,\n CheckResult,\n SiteHealthPageSample,\n SiteHealthSample,\n VisibilityEvidence,\n VisibilityReport,\n} from '../runtime/types.ts'\nimport { PUBLIC_RATE_LIMITED_ERROR_CODE } from '../runtime/types.ts'\nimport type {\n CanonryDemoViewModel,\n CheckFormViewModel,\n QueryEvidenceViewModel,\n SiteHealthFactorViewModel,\n SiteHealthFixViewModel,\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\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 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 detail: 'Mention and citation rates use completed checks only.',\n }\n : undefined,\n }\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 factors: sample.factors.map((factor) => {\n const state = factorState(sample, factor.id, factor.count)\n return {\n id: factor.id,\n label: factor.name,\n state,\n score: state === 'measured' ? factor.averageScore : null,\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 topFixes: topFixes(sample),\n worstPages: sample.pages.map(mapSiteHealthPage),\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\nfunction topFixes(sample: SiteHealthSample): SiteHealthFixViewModel[] {\n const fixes = new Map\n }>()\n for (const page of sample.pages) {\n for (const defect of page.criticalDefects) {\n addFix(fixes, page.url, defect.recommendation || defect.detail, defect.detail)\n }\n for (const factor of page.factors) {\n for (const recommendation of factor.recommendations) {\n addFix(fixes, page.url, recommendation, factor.name)\n }\n }\n }\n return [...fixes.values()].slice(0, 3).map((fix) => ({\n id: fix.id,\n title: fix.title,\n detail: fix.detail,\n affectedPages: fix.affectedPageUrls.size,\n }))\n}\n\nfunction addFix(\n fixes: Map }>,\n pageUrl: string,\n recommendation: string,\n detail: string,\n): void {\n const title = firstSentence(recommendation || detail)\n const key = title.toLocaleLowerCase('en-US')\n if (!title) return\n const known = fixes.get(key)\n if (known) {\n known.affectedPageUrls.add(pageUrl)\n return\n }\n fixes.set(key, {\n id: `${fixes.size + 1}:${key}`,\n title,\n detail: recommendation && recommendation !== title ? recommendation : detail,\n affectedPageUrls: new Set([pageUrl]),\n })\n}\n\nfunction firstSentence(value: string): string {\n const sentence = value.split(/[.!?]\\s|[.!?]$/)[0] ?? value\n return sentence.trim().slice(0, 110)\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",[],[184,346,372],"30630697-9c4a-43ce-a84d-3c67ca3a125b","client.ts","933a30f2-a63e-11f1-aa2a-1607ee4eb77e",23,["D",1788292311298],"/** 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 metricButtons = Array.from(document.querySelectorAll('[data-visibility-metric]'));\n const metricPanels = Array.from(document.querySelectorAll('[data-visibility-panel]'));\n const metricSummaries = Array.from(document.querySelectorAll('[data-visibility-summary]'));\n metricButtons.forEach((button) => {\n button.addEventListener('click', () => {\n const metric = button.dataset.visibilityMetric;\n metricButtons.forEach((item) => {\n const active = item === button;\n item.classList.toggle('is-active', active);\n item.setAttribute('aria-pressed', String(active));\n });\n metricPanels.forEach((panel) => { panel.hidden = panel.dataset.visibilityPanel !== metric; });\n metricSummaries.forEach((summary) => { summary.hidden = summary.dataset.visibilitySummary !== metric; });\n });\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 form.addEventListener('submit', () => {\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.textContent = 'Starting check…';\n }\n });\n }\n})();\n`\n",[],[184,346,380],"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",[],[184,346,388],"860a6741-04fd-4cac-81b8-88fa850c061e",2,["D",1788292309086],[243,244,245,246,247,248,249],[184,346],"557649bd-7156-4137-9af2-6a32e284decc","memory.ts","95930b94-a63e-11f1-93d2-1607ee4eb77e","927bf83a-a63e-11f1-8d00-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",[],[184,409,401],"storage","01568ee8-b51f-43e3-8630-3492a546a4c6",9,["D",1788292310084],[241],[184,409],"9872971b-6df7-4db3-a940-d575fb5071df","site-health","92bd6c2a-a63e-11f1-9f99-1607ee4eb77e",12,["D",1788292310513],[],[184,416],"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",[],[184,431,423],"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",[],[184,431,433],"b8bce09a-c6af-4a10-812e-6d794b08426b",6,["D",1788292309698],[237,238],[184,431],"e28b7a02-6dfe-4e71-8516-ee38c41cd453","93a5c9fc-a63e-11f1-8fd4-1607ee4eb77e","9256932e-a63e-11f1-9a7d-1607ee4eb77e",36,["D",1788292311987],"/**\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\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 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 /** 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\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 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 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",[],[184,453,338],"runtime","32337a79-34bd-4825-bc29-e031191682b9","records.ts","93b29a9c-a63e-11f1-965f-1607ee4eb77e",38,["D",1788292312042],"/**\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/**\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 */\nexport function checkFingerprint(domain: string): string {\n return `visibility-v1:${domain}`\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",[],[184,453,455],"eb2d53de-7095-4756-867a-252fd03349cc",["D",1788292309828],[234,235],[184,453],"01c6d3d9-d0c9-45d6-a1e5-c8cd31e1cc50","tools.ts","93d9894a-a63e-11f1-8fd4-1607ee4eb77e","9269bbca-a63e-11f1-8d00-1607ee4eb77e",41,["D",1788292312291],"/**\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 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) => 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 { error: fail(`No check found for ID \"${checkId}\".`, 'Public checks expire; run a new one from the web UI.') }\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\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 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 returns the cached result immediately and costs nothing. Daily limits apply.',\n inputSchema: {\n type: 'object',\n properties: { domain: { type: 'string', description: 'A domain such as \"example.com\".' } },\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.',\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. 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:\n '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 return ok({\n ...recordEnvelope(resolved.record),\n summary: visibilitySummary(resolved.record),\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 factors: siteHealth.factors,\n pages: siteHealth.pages,\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 { record, reused } = await context.startCheck(domain, context.remoteIp ?? null)\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:\n '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",[],[184,475,467],"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",[],[184,475,477],"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",[],[184,475,485],"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",[],[184,475,493],"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",[],[184,475,509,501],"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",[],[184,475,509,511],"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",[],[184,475,509,519],"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",[],[184,475,509,527],"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",[],[184,475,509,535],"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",[],[184,475,509,551],"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",[],[184,475,509,559],"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",[],[184,475,509,567],"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",[],[184,475,509,575],"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",[],[184,475,509,583],"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",[],[184,475,509,591],"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",[],[184,475,509,599],"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",[],[184,475,509,607],"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",[],[184,475,509,615],"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",[],[184,475,509,623],"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",[],[184,475,509,631],"b605cbd6-3f6c-41a7-9331-771bbb222029",13,["D",1788292310636],[212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228],[184,475,509],"ae91bccc-3e31-4356-834f-cb508c834a4f",8,["D",1788292309949],[211,229,230,231,232],[184,475],"97e47c06-2369-4a04-9d9c-2b35edaee5cf","92af4352-a63e-11f1-9f99-1607ee4eb77e",["D",1788292315934],[],[184,653,32],"jobs","96780fc5-c060-4b02-86a2-4b51b47199f6",11,["D",1788292310414],[209],[184,653],"8cd807e0-17bd-4493-b23a-245103ca10ec","demo-report.ts","95b96410-a63e-11f1-a2db-1607ee4eb77e","929d710e-a63e-11f1-8621-1607ee4eb77e",61,["D",1788292315457],"import type { CanonryDemoViewModel } from '../ui/types.ts'\n\n/**\n * Explicitly synthetic history for the first impression. Runtime-created\n * reports must use `historyKind: 'snapshot'` until another observation exists.\n */\nexport const demoCanonryViewModel: CanonryDemoViewModel = {\n status: 'demo',\n title: 'Canonry sample',\n displayName: 'Cedar Creek Plumbing',\n domain: 'cedarcreekplumbing.example',\n locale: 'US / EN',\n form: {\n action: '/check',\n method: 'post',\n verificationFieldName: 'cf-turnstile-response',\n verificationStatus: 'not-required',\n submitLabel: 'Check a domain',\n },\n notice: {\n tone: 'neutral',\n title: 'Sample data',\n detail: 'Try a domain to create a fresh, single-engine snapshot.',\n },\n visibility: {\n historyKind: 'demo-history',\n checkedAt: '2026-08-28T15:12:00.000Z',\n providers: [\n { id: 'claude', label: 'Claude', model: 'claude-sonnet-4-6', color: '#fb923c' },\n { id: 'gemini', label: 'Gemini', model: 'gemini-2.5-flash', color: '#60a5fa' },\n { id: 'openai', label: 'OpenAI', model: 'gpt-5.4', color: '#34d399' },\n { id: 'perplexity', label: 'Perplexity', model: 'sonar', color: '#22d3ee' },\n ],\n summaries: {\n mentioned: { rate: 52.5, numerator: 21, denominator: 40, deltaPoints: 4.5 },\n cited: { rate: 37.5, numerator: 15, denominator: 40, deltaPoints: 2.5 },\n },\n trend: [\n {\n label: 'May 06',\n values: {\n claude: { mentioned: 50, cited: 40 },\n gemini: { mentioned: 60, cited: 50 },\n openai: { mentioned: 20, cited: 10 },\n perplexity: { mentioned: 50, cited: 40 },\n },\n },\n {\n label: 'Jun 03',\n values: {\n claude: { mentioned: 47, cited: 37 },\n gemini: { mentioned: 64, cited: 53 },\n openai: { mentioned: 28, cited: 18 },\n perplexity: { mentioned: 53, cited: 43 },\n },\n },\n {\n label: 'Jul 01',\n values: {\n claude: { mentioned: 44, cited: 35 },\n gemini: { mentioned: 67, cited: 57 },\n openai: { mentioned: 34, cited: 27 },\n perplexity: { mentioned: 56, cited: 46 },\n },\n },\n {\n label: 'Aug 28',\n values: {\n claude: { mentioned: 40, cited: 32 },\n gemini: { mentioned: 70, cited: 60 },\n openai: { mentioned: 40, cited: 31 },\n perplexity: { mentioned: 60, cited: 47 },\n },\n },\n ],\n completedChecks: 40,\n requestedChecks: 40,\n failedChecks: 0,\n evidence: [\n {\n id: 'cedar-plumber-gemini',\n query: 'Best plumber in Cedar Creek',\n provider: 'gemini',\n providerLabel: 'Gemini',\n requestedModel: 'gemini-2.5-flash',\n servedModel: 'gemini-2.5-flash',\n completedAt: '2026-08-28T15:12:00.000Z',\n mentioned: true,\n cited: true,\n matchedTerms: ['Cedar Creek Plumbing'],\n answerText: 'Cedar Creek Plumbing is a local option for emergency repairs and fixture installation.',\n sources: [\n { url: 'https://cedarcreekplumbing.example/services', title: 'Plumbing services', isTargetDomain: true },\n { url: 'https://example.org/local-services', title: 'Local service guide' },\n ],\n searchQueries: ['best plumber Cedar Creek'],\n retrievalStatus: 'success',\n },\n {\n id: 'water-heater-claude',\n query: 'Who installs tankless water heaters near Cedar Creek?',\n provider: 'claude',\n providerLabel: 'Claude',\n requestedModel: 'claude-sonnet-4-6',\n servedModel: 'claude-sonnet-4-6',\n completedAt: '2026-08-28T15:12:00.000Z',\n mentioned: true,\n cited: false,\n matchedTerms: ['Cedar Creek Plumbing'],\n answerText:\n 'Cedar Creek Plumbing offers tankless water heater installation, alongside several regional providers.',\n sources: [{ url: 'https://example.org/water-heater-guide', title: 'Tankless water heater guide' }],\n retrievalStatus: 'success',\n },\n {\n id: 'emergency-plumber-openai',\n query: 'Emergency plumber in Cedar Creek',\n provider: 'openai',\n providerLabel: 'OpenAI',\n requestedModel: 'gpt-5.4',\n servedModel: 'gpt-5.4',\n completedAt: '2026-08-28T15:12:00.000Z',\n mentioned: false,\n cited: true,\n matchedTerms: [],\n answerText:\n 'The response listed emergency-plumbing advice and linked to a service page without naming the company.',\n sources: [{\n url: 'https://cedarcreekplumbing.example/emergency',\n title: 'Emergency plumbing',\n isTargetDomain: true,\n }],\n retrievalStatus: 'success',\n },\n {\n id: 'drain-cleaning-perplexity',\n query: 'Drain cleaning in Cedar Creek',\n provider: 'perplexity',\n providerLabel: 'Perplexity',\n requestedModel: 'sonar',\n servedModel: 'sonar',\n completedAt: '2026-08-28T15:12:00.000Z',\n mentioned: false,\n cited: false,\n matchedTerms: [],\n answerText: 'The response named other local options and did not link to Cedar Creek Plumbing.',\n sources: [{ url: 'https://example.org/drain-cleaning', title: 'Drain cleaning directory' }],\n retrievalStatus: 'success',\n },\n ],\n },\n siteHealth: {\n sampleLabel: '5-page Technical AEO sample',\n score: 73,\n discoveredPages: 5,\n attemptedPages: 5,\n completedPages: 5,\n failedPages: 0,\n checkedAt: '2026-08-28T15:12:00.000Z',\n factors: [\n {\n id: 'indexability',\n label: 'Indexability',\n state: 'measured',\n score: 100,\n detail: '5 of 5 sampled pages can be indexed.',\n },\n {\n id: 'metadata',\n label: 'Metadata',\n state: 'measured',\n score: 72,\n detail: 'Two sampled pages need clearer titles or descriptions.',\n },\n {\n id: 'structured-data',\n label: 'Structured data',\n state: 'measured',\n score: 50,\n detail: 'Service markup appears on two of five sampled pages.',\n },\n {\n id: 'internal-links',\n label: 'Internal links',\n state: 'measured',\n score: 68,\n detail: 'One sampled service page has only one internal link.',\n },\n {\n id: 'dead-links',\n label: 'Dead links',\n state: 'not-applicable',\n score: null,\n detail: 'Not checked in this bounded sample.',\n },\n ],\n topFixes: [\n {\n id: 'service-schema',\n title: 'Add service structured data',\n detail: 'Give answer engines a clearer service-level description.',\n affectedPages: 3,\n },\n {\n id: 'titles',\n title: 'Clarify two page titles',\n detail: 'Use the service and location in the page title.',\n affectedPages: 2,\n },\n {\n id: 'internal-links',\n title: 'Link to the emergency page',\n detail: 'Add a contextual link from the main services page.',\n affectedPages: 1,\n },\n ],\n worstPages: [\n {\n url: 'https://cedarcreekplumbing.example/tankless-water-heaters',\n score: 52,\n status: 'needs-attention',\n indexable: true,\n findings: ['No service structured data', 'Single internal link'],\n },\n {\n url: 'https://cedarcreekplumbing.example/emergency',\n score: 64,\n status: 'needs-attention',\n indexable: true,\n findings: ['Title does not name the service area'],\n },\n {\n url: 'https://cedarcreekplumbing.example/services',\n score: 76,\n status: 'needs-attention',\n indexable: true,\n findings: ['Description could name the core services'],\n },\n ],\n },\n}\n",[],[184,668,660],"fixtures","6ddf4a2e-04bf-4c6c-bba6-3dc1c98830a9",10,["D",1788292310299],[207],[184,668],"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",[],[184,682,364],"config","5b29d0bc-67f9-4641-abd9-7035be8a9b71",5,["D",1788292309530],[205],[184,682],"b63d1832-e923-4d48-889b-33fad39743a9","app.ts","9349f686-a63e-11f1-b64b-1607ee4eb77e","91f8f4bc-a63e-11f1-8621-1607ee4eb77e",25,["D",1788292311428],"import { Hono } from 'hono'\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 } 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}\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) => {\n const outcome = await submitCheck(deps, { domain, token: null, remoteIp, now: now(), admission: 'mcp' })\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 app.get('/assets/canonry-ui.css', (context) => {\n context.header('Cache-Control', 'public, max-age=3600')\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=3600')\n return context.body(deps.assets.script, 200, { 'content-type': 'application/javascript; 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 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 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 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 viaMcp = input.admission === 'mcp'\n if (!viaMcp) await deps.config.humanVerifier.verify({ token: input.token, remoteIp: input.remoteIp })\n const fingerprint = checkFingerprint(target.domain)\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({ id: crypto.randomUUID(), fingerprint, domain: target.domain, now: input.now }),\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\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 'none'\",\n \"form-action 'self'\",\n `script-src 'self'${turnstile}`,\n \"style-src 'self'\",\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 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",[],[184,697,689],"app","099c2e2e-a5d0-494f-ae81-754dd43458ad",3,["D",1788292309199],[203],[184,697],["D",1788292308897],[202,204,206,208,210,233,236,239,240,242,250],[184],["D",1788292195151],["D",1789514495229],{"_100":99,"_108":104},{"_100":99,"_101":102,"_103":104,"_18":-5,"_105":106,"_107":24},{"_13":89,"_31":90,"_42":41,"_91":43,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":-5,"_97":44,"_98":99},"ctx",{"_82":-5,"_128":744,"_745":746,"_747":748,"_749":24,"_750":24,"_751":24,"_752":59,"_753":-5,"_754":-7,"_755":-7,"_756":63,"_757":24,"_758":24,"_759":-5,"_760":24,"_761":24,"_762":24,"_763":-5},"ENV",{"_715":716,"_717":718,"_719":90,"_720":721,"_722":723,"_724":725,"_726":727,"_728":729,"_730":731,"_732":733,"_734":735,"_736":737,"_738":739,"_740":741,"_742":743},"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"]

Diff · v62