@canonry/canonry 7.98.0 → 7.100.0

package/dist/{chunk-RTH5JVC3.js → chunk-FBO25TA3.js}

@@ -15,7 +15,7 @@ import {
   formatCanonryPluginUpdateHint,
   formatCanonryPluginVersionMismatch,
   skillsClientSchema
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // src/commands/skills.ts
 import crypto from "crypto";

package/dist/{chunk-2Q7JEC6N.js → chunk-FZ3MUTU3.js}

@@ -5,7 +5,7 @@ import {
   siteCrawlGraphNodes,
   siteCrawlPages,
   siteCrawlSnapshots
-} from "./chunk-KK3Z34AN.js";
+} from "./chunk-2DV7F6XA.js";
 import {
   SITE_CRAWL_GRAPH_MAX_EDGES,
   SITE_CRAWL_GRAPH_MAX_NODES,
@@ -15,7 +15,7 @@ import {
   factorStatusFromDistribution,
   factorStatusFromScore,
   roundPreservingTotal
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // src/site-audit-factors.ts
 function recordedSharePct(factor) {

package/dist/{chunk-64R66MWZ.js → chunk-G6QN4VFS.js}

@@ -3,16 +3,16 @@ import {
   CANONRY_MCP_TOOLKIT_NAMES,
   isCanonryMcpToolkitName,
   resolveAeroSkillDir
-} from "./chunk-MTW37GXF.js";
+} from "./chunk-2FWYWGIR.js";
 import {
   createApiClient,
   runWithUsageTags
-} from "./chunk-OL2L5ANJ.js";
+} from "./chunk-UGO2FO6V.js";
 import {
   canonryMcpTools,
   mcpOutputSchema,
   toolOperationAccess
-} from "./chunk-3GMBHGQ5.js";
+} from "./chunk-F46TBLXK.js";
 import {
   PACKAGE_VERSION
 } from "./chunk-AOJU5LKX.js";
@@ -25,7 +25,7 @@ import {
   isReadOnlyKey,
   restrictedWriteScopes,
   upgradeCaveatFor
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // src/mcp/server.ts
 import { randomUUID } from "crypto";
@@ -131,6 +131,9 @@ function zodErrorMessage(error) {
 }
 
 // src/mcp/dynamic-catalog.ts
+function isListed(entry) {
+  return entry.tool.deprecatedAliasOf === void 0;
+}
 var DynamicToolCatalog = class {
   entries;
   loaded = /* @__PURE__ */ new Set();
@@ -168,8 +171,9 @@ var DynamicToolCatalog = class {
     if (matches.length === 0) {
       return { status: "empty", name, tools: [] };
     }
+    const listed = matches.filter(isListed).map((entry) => entry.tool.name);
     if (this.loaded.has(name)) {
-      return { status: "already-loaded", name, tools: matches.map((entry) => entry.tool.name) };
+      return { status: "already-loaded", name, tools: listed };
     }
     this.batchListChanged(() => {
       for (const entry of matches) {
@@ -177,14 +181,16 @@ var DynamicToolCatalog = class {
       }
     });
     this.loaded.add(name);
-    return { status: "loaded", name, tools: matches.map((entry) => entry.tool.name) };
+    return { status: "loaded", name, tools: listed };
   }
   helpResult() {
     return {
       scope: this.scope,
       eager: this.eager,
       loadedToolkits: [...this.loaded].sort(),
-      coreTools: this.entries.filter((entry) => entry.tool.tier === "core").map((entry) => entry.tool.name),
+      coreTools: this.entries.filter((entry) => entry.tool.tier === "core" && isListed(entry)).map((entry) => entry.tool.name),
+      // An approval list, so it stays complete: a live tool needs approval
+      // under any name it answers to.
       liveTools: this.entries.filter((entry) => entry.tool.tier === "core" && toolOperationAccess(entry.tool) === OperationAccesses.live).map((entry) => entry.tool.name),
       toolkits: CANONRY_MCP_TOOLKITS.map((toolkit) => this.toolkitEntry(toolkit)).filter((entry) => entry.toolCount > 0),
       usage: this.eager ? "All tools available on this connection are already loaded. Use their listed schemas; tool visibility does not grant server permissions." : "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session. Wait for its response before calling any newly enabled tool."
@@ -204,7 +210,7 @@ var DynamicToolCatalog = class {
     };
   }
   toolsForToolkit(name) {
-    return this.entries.filter((entry) => entry.tool.tier === name).map((entry) => entry.tool.name);
+    return this.entries.filter((entry) => entry.tool.tier === name && isListed(entry)).map((entry) => entry.tool.name);
   }
   // RegisteredTool.enable/disable each call sendToolListChanged on the McpServer
   // we registered with. Loading an 11-tool toolkit emits 11 notifications under
@@ -232,7 +238,7 @@ var OPERATIONS_GUIDE = {
   "guideVersion": "v1",
   "operationsGuideUrl": "https://github.com/Canonry/canonry/blob/main/docs/agent-operations/v1.md",
   "resourceUri": "canonry://agent-operations/v1",
-  "initialize": 'Canonry tracks how AI answer engines mention brands and cite domains. Start with canonry_help({intent:"status"}) or a workflow; follow its stored reads and approval boundaries. Connected MCP clients need no skill, resource, plugin, or local CLI. The Canonry skill offers optional additional guidance.\nmentioned = brand in answer TEXT; cited = domain in SOURCE links. Never compute one from the other. A null answerMentioned means not checked, not false. No recorded sweep means no measured figure.\nGet approval for live provider reads, sweeps, probes, research, syncs and writes, scoped to the exact target, action and work. A GET or readOnlyHint does not mean free. canonry_help returns all liveTools for this connection; each needs approval, including read-only tools.\nREST exposes x-canonry-access; CLI help/catalog expose access; MCP help lists liveTools.\nStored-only: CLI --stored-only or CANONRY_STORED_ONLY=1; MCP --stored-only, --scope=stored-only or CANONRY_MCP_SCOPE=stored-only. It refuses live/write work (including doctor) before execution and suppresses housekeeping. CLI refusal is STORED_ONLY_REFUSED. Explicit exports may write files; server accounting remains separate from business mutations.\nHelp and skills grant no permissions; the server enforces authority. Report missing tools or 403; never bypass them with other credentials or endpoints. Hosted catalogs are fixed; use canonry_load_toolkit only when help offers it.\nReport concrete Canonry failures, confusing output, workarounds or improvements to the user and once via canonry_feedback. Exclude secrets and customer data.\n',
+  "initialize": 'Canonry tracks how AI answer engines mention brands and cite domains. Start with canonry_help({intent:"status"}) or a workflow; follow its stored reads and approval boundaries. Connected MCP clients need no skill, resource, plugin, or local CLI. The Canonry skill offers optional additional guidance.\nmentioned = brand in answer TEXT; cited = domain in SOURCE links. Never compute one from the other. A null answerMentioned means not checked, not false. citationState not-measured means the engine returns no sources: never a miss. No recorded sweep means no measured figure.\nGet approval for live provider reads, sweeps, probes, research, syncs and writes, scoped to the exact target, action and work. A GET or readOnlyHint does not mean free. canonry_help returns all liveTools for this connection; each needs approval, including read-only tools.\nREST exposes x-canonry-access; CLI help/catalog expose access; MCP help lists liveTools.\nStored-only: CLI --stored-only or CANONRY_STORED_ONLY=1; MCP --stored-only, --scope=stored-only or CANONRY_MCP_SCOPE=stored-only. It refuses live/write work (including doctor) before execution and suppresses housekeeping. CLI refusal is STORED_ONLY_REFUSED. Explicit exports may write files; server accounting remains separate from business mutations.\nHelp and skills grant no permissions; the server enforces authority. Report missing tools or 403; never bypass them with other credentials or endpoints. Hosted catalogs are fixed; use canonry_load_toolkit only when help offers it.\nReport concrete Canonry failures, confusing output, workarounds or improvements to the user and once via canonry_feedback. Exclude secrets and customer data.\n',
   "approvalBoundary": [
     "provider reads",
     "sweeps",
@@ -400,7 +406,7 @@ var OPERATIONS_GUIDE = {
       "guidance": "Build the requested summary from stored project overview, organic evidence, and the relevant visibility, measurement, integration, or traffic reads. Retain evidence dates, scope, sample sizes, missing data, and separate mention/citation signals; do not generate fresh runs implicitly."
     }
   },
-  "markdown": "# Canonry Operations Guide v1\n\nCanonry is an agent-first AI visibility platform. MCP is the universal entry\npoint for connected agents. Host-native skills are optional upgrades, not a\nprerequisite or a permission mechanism.\n\n## Connect and choose a route\n\nRead the initialization guidance, then call `canonry_help` with an `intent`:\n`status`, `diagnose`, `operations`, `prospecting`, `measurement`, `integrations`,\n`reports`, or a short task\ndescription. Select an accessible project with `canonry_projects_list` before\nusing its exact name in project tools. Inspect each listed tool's input schema;\nhelp suggests tool names, not invented arguments or authorization.\n\nHelp returns a versioned, compact route: connection `mode`, available `next`\ntools, workflow guidance, approval boundaries, and this guide's URL. It performs\nno provider calls, reads no project data, and changes no permissions.\n`next` lists stored reads. Optional `actions` lists loaded tools for work that\nrequires approval; listing an action does not authorize or execute it.\n`includeCatalog: true` additionally returns toolkit details when needed.\n\nAnalysis routes also return `playbooks`: Canonry's analyst playbooks for that\nwork, the same files its built-in agent reads. Read each one before\ninterpreting results. `canonry_help({ playbook: \"<slug>\" })` returns its full\ntext, a note on using it over MCP, and every available slug. Playbooks are\nguidance, not permission.\n\nHosted connections use a fixed catalog. Help only suggests tools offered by that\nconnection; it never tells a hosted agent to dynamically load a toolkit. A\nprogressive local stdio connection may return `loadToolkits`: call\n`canonry_load_toolkit` with one returned name, await it, then call help again.\nLoading only changes local tool discovery, never server authority.\n\nThe optional `canonry://agent-operations/v1` MCP resource contains this same\nguide. If the host cannot read resources or open links, continue through help.\nDo not install a plugin, local runtime, or skill merely to use connected MCP.\nAn installed Codex or Claude Canonry skill contains a generated copy of this\nguide plus links to host-native references. It does not replace runtime help.\n\n## Vocabulary and evidence\n\n- **Mentioned** means the brand appears in answer text. **Cited** means its\n  domain appears in source links. Either, both, or neither can occur; never\n  compute one signal from the other.\n- `answerMentioned: null` means not checked, not false. Missing runs and empty\n  populations mean no measurement, not zero visibility.\n- Preserve project, time window, provider, requested/served model, location,\n  sample size, and query class when comparing evidence. Use server-returned\n  metrics; do not invent a score from incompatible populations.\n- Simple projects and Advanced portfolios share the workflow. For Advanced\n  results, preserve Property, Target, market, plan revision, and class scope.\n  Groups organize navigation; do not infer an unrequested fan-out.\n- Research is isolated evidence, not tracked measurement. A probe still spends\n  quota and persists evidence but is excluded from normal tracking metrics.\n\n## Workflows\n\n**Status:** read the stored overview and freshness first. Say when evidence is\nmissing instead of silently creating it.\n\n**Setup:** Page Health needs no answer-engine provider; AI Visibility does.\nAfter a Page Health result on an install with no provider (a `NO_PROVIDER`\nnotice, or doctor's `providers.none-configured`), propose AI Visibility setup\nas the next step. The operator adds the provider key in the dashboard or in\ntheir own terminal; never ask for it in chat.\nRerunning `canonry bootstrap` after a provider change reloads saved provider\nsettings on a matching running local server and reports whether they became\nactive. If the server is offline, start it to apply the saved settings. For an\nexplicit reload of the connected server's own config, use\n`canonry settings reload-providers` or `canonry_providers_reload` with install\nadministrator authority. Remote servers are never reloaded automatically by\nbootstrap, and a local server that belongs to another install is left alone.\nPorts and database settings still need a restart.\n\n**Diagnose:** inspect stored history and comparable evidence. Explain what\nchanged separately from why it might have changed. A hypothesis is not a\nmeasured cause. Propose bounded verification if stored evidence is insufficient.\n\n**Site Health:** read `canonry_site_health_issues` for stored technical findings,\naffected-page counts and example URLs, then `canonry_site_health_issue_pages`\nfor a selected issue's remaining pages. Pin subsequent reads to the returned\nrun. Inspect coverage and omissions: a passing score can still have findings,\nan older scan may lack cross-page evidence, and a partial scan cannot establish\nsite-wide absence. Advisory findings require judgment before proposing a repair.\nAudit evidence informs technical repairs and existing-page recommendations;\nit does not itself establish a new-blog opportunity or authorize any edit.\n\n**Prospecting:** generate a one-shot company snapshot without creating a project.\nInspect stored provider settings first. Agree on the company, domain, selected\nproviders, and queries before starting the quota-spending snapshot action.\nBrowser-only selection requires manual queries. Progressive stdio help offers\nthe discovery toolkit when this connection permits snapshots; load it, then\ncall help again. Fixed catalogs offer only already available actions. Read-only\nand restricted connections must not bypass missing snapshot access.\n\n**Measurement:** inspect the existing setup and results before proposing edits.\nKeep research, query tracking, plan publication, and sweep execution separate.\nFor direct research, submit the final editable query text in one context. For a\nreviewed batch, submit each explicit destination with its final text and one\nidempotency key. Pattern substitution happens in the client before either\nrequest; choosing a market or Property records a destination only and never\nrewrites a query or creates an automatic fan-out. `research.run` does not\nauthorize saving patterns, changing tracking, publishing plans, or settings.\nUse a supported preview where available, inspect its exact destination and\nrevision, then seek approval for the actual change. A preview may itself require\nwrite permission; never treat a dry-run flag as a universal safety guarantee.\n\n**Integrations:** inspect stored connection state and snapshot freshness first.\nProvider configuration evidence does not prove a browser event fired or a\nconversion was recorded. Connection, resource selection, refresh/sync, and live\nreads are separate actions. Credentials belong in the operator's secure setup\nflow, never in chat, tool arguments, reports, or public guidance.\n\n**Reports:** use saved evidence for the requested period and scope. Keep mention\nand citation signals separate, include dates and sample sizes, and state missing\nor stale inputs. For Advanced Property mention rankings, use\n`canonry_measurement_portfolio_summary` and its `mentionRanking.strongest`,\n`.weakest`, and `.excluded` lists. It defaults to non-brand questions; state the\nreturned class and report branded results separately. An unavailable portfolio\naggregate does not invalidate available Property mention rates. Flag excluded\nProperties individually; do not silently replace mention ranking with citation\nranking. Compact `nextCursor` completes only `pageList`; use `list` to enumerate\none ranking, markets, observed names or cited domains, preserving filters.\nFirst-page sibling lists are bounded summaries. Keep sample sizes and ties\nvisible. Preparing a report does not\nauthorize new measurement.\n\n## Authority and approval\n\n### Agent operations\n\nUse `canonry_key_self` (CLI `canonry key whoami --format json`) to inspect the\ncurrent credential's scopes, project boundary, and host-derived `operator`\nauthority without exposing its token. Missing `operator` means unapproved.\n`canonry_settings_get` and\n`canonry_telemetry_get` describe the connected server, not the agent's local\nmachine. Telemetry reports configured preference, effective state, and any\nenvironment override; inspecting status never creates an anonymous identifier.\nAfter approval, `canonry_telemetry_update` changes that preference and\n`canonry_provider_settings_update` changes an already-configured provider's\nmodel/quota. Both require `settings.write`; neither accepts credentials.\nServer telemetry reads and updates additionally require operator authority.\nOrdinary audit-history reads omit internal telemetry events and their state.\n\nOperator authority is deny-by-default and separate from customer admin roles.\nThe deployment owner must approve a dedicated, instance-wide API key's ID in\nthe server environment variable `CANONRY_OPERATOR_KEY_IDS` (comma-separated IDs),\nthen restart the server. Empty/unset approves nobody; wildcards are invalid.\nKeep the bearer private to internal operators; never approve a customer-held or\nshared proxy/bootstrap key. Use `logs.read` for read-only diagnostics, adding\n`settings.write` only when telemetry control is required. Ordinary key creation,\naccount roles, OAuth consent, and caller headers cannot grant operator status.\nRevoking an approved key invalidates it immediately. Host enrollment is a trust\nbootstrap step, intentionally unavailable through customer-facing APIs.\nAPI, CLI, and MCP enforce the same boundary; MCP hides internal tools unless\nthe server confirms operator authority, including in explicit read-only mode.\nProject analytics, research, and normal project permissions are unchanged.\n\n`canonry_logs_list` reads bounded, redacted runtime events from both the\napplication logger and Fastify request/error logging. It requires an\ninstance-wide `logs.read` grant (or wildcard) and a host-approved direct bearer.\nBrowser sessions, OAuth/delegated credentials, customer admins, and project-scoped\nkeys cannot use it, even with a project filter or a matching allowlist ID.\nA `logs.read`-only key is read-only automatically, without a\nsecond `read` marker. Named `*.read` scopes cannot grant mutations; an explicit\nwrite grant is needed and remains subject to its route gates. Returned messages\nare sanitized and bounded; raw request or response bodies, headers, cookies,\nprovider payloads, and stacks are not\npart of the queryable surface. The same secret-redaction policy runs before\nconsole output and storage. Do not deliberately log secrets: redaction is a\ndefense in depth, not permission to put credentials into diagnostic strings.\nOpaque escaped payloads containing secret assignments are omitted when safe\npartial masking cannot be guaranteed; correlate their retained error codes and IDs.\n\nFile-backed hosts retain runtime logs in SQLite across restarts, bounded to\n10,000 events and seven days. In-memory hosts report `retention: \"process\"`.\nFilter by `actor`, `requestId`, `runId`, `projectId`, `module`, `level`, or an\ninclusive `since`/`until` interval. Keep filters unchanged when resuming an\nopaque cursor; retention eviction can invalidate it. Inspect `retentionPolicy`,\n`captureErrors`, `dropped`, `truncated`, and `retention` before drawing\nconclusions. Missing logs are not proof that an action did not happen. Use\n`canonry_project_history` or `canonry_history_global` for persistent audit events;\noffset pages have deterministic ordering but are not snapshots of concurrent writes.\n\nAudit `actor` comes from authenticated identity (`user:<id>` or `api-key:<id>`),\nnot a caller-supplied header. A delegated MCP credential records its originating\nuser as actor and the actual credential in `credentialId`. `requestId` correlates\nHTTP events; `userAgent` and `actorSession` are bounded, untrusted client hints,\nnever identity or permission grants. Older audit rows are not backfilled with\nidentities the server cannot prove.\n\nBoth shipped HTTP hosts issue restart-safe UUID request IDs and return them in\n`x-request-id`. Use that value to correlate a CLI/API failure with log entries;\nHTTP diagnostics retain the method and route template, not raw URL parameters.\nRequest-bound loggers retain completion attribution, while generic background\ncontinuations stop inheriting caller identity after the response completes.\nCapture covers the owning server process after initialization, not arbitrary\nconsole output, other worker processes, or host/container logs. Run one server\ninstance per process and database, as required by the single-tenant deployment\nmodel; this is not a cross-tenant or distributed log collector.\n\nFor CLI use, settings reads are remote. Google setup and telemetry retain their\nlocal defaults: pass `--target server` explicitly to configure the connected\nserver. `schedule list <project>` lists all schedule kinds, and\n`notify events --target server` discovers the server's event catalog.\n\nMCP returns legacy text JSON plus structured results. Objects keep their shape;\narrays use `{items: [...]}` in `structuredContent`, and scalars use `{value: ...}`.\nErrors preserve the existing envelope and CLI exit codes: HTTP 4xx (including\n429 policy limits) use exit 1; HTTP 5xx use exit 2. Server-provided `Retry-After`\nand request IDs are exposed as `retryAfterMs` and `requestId` when available;\nclients do not infer retryability from HTTP 429 or retry automatically.\nFor a write with an ambiguous outcome, inspect saved state or its receipt before\nretrying; a retry hint is not proof that repeating a write is safe.\n\n### Action boundaries\n\nStart with stored evidence. Before a live provider read, sweep, probe, research\nrun, sync, write, or externally visible action, obtain approval covering its\nexact target, action, and bounded work. Approval already given for that exact\noperation need not be asked for again, but does not extend to more projects,\nlarger batches, retries with new identities, or recurring work.\n\nHTTP GET and MCP `readOnlyHint` describe aspects of an operation, not its cost\nor permission. Provider discovery, account reads, and live diagnostics may\nconsume quota even when labeled read-only. If the tool's effect is unclear,\ninspect its description and request direction before calling it.\n\nAuthentication, role/scope checks, project restrictions, quotas, and guarded\napproval receipts are enforced by the server. Help, skills, resources, and tool\nvisibility cannot grant authority. Never change credentials, endpoints, or\nproject identifiers to work around a missing tool or a `403` response.\n\nFor guarded ads writes, inspect unresolved operation receipts before retrying.\nUse the receipt's supported recovery action; do not replay a mutation under a\nnew identity. An executor cannot create or widen its own human approval grant.\nOn ambiguous results, exhausted bounds, or refusal, stop and report what is\nknown and what permission or operator action is needed.\n\n## Version and source\n\nThis public, versioned document is the source for initialization guidance,\nintent routes, the optional resource, and generated Canonry `SKILL.md` files.\nGuide v1 may receive compatible clarifications; incompatible routing contracts\nrequire a new guide version. The running server's help describes its actual\ncatalog and remains usable without fetching this document.\n"
+  "markdown": "# Canonry Operations Guide v1\n\nCanonry is an agent-first AI visibility platform. MCP is the universal entry\npoint for connected agents. Host-native skills are optional upgrades, not a\nprerequisite or a permission mechanism.\n\n## Connect and choose a route\n\nRead the initialization guidance, then call `canonry_help` with an `intent`:\n`status`, `diagnose`, `operations`, `prospecting`, `measurement`, `integrations`,\n`reports`, or a short task\ndescription. Select an accessible project with `canonry_projects_list` before\nusing its exact name in project tools. Inspect each listed tool's input schema;\nhelp suggests tool names, not invented arguments or authorization.\n\nHelp returns a versioned, compact route: connection `mode`, available `next`\ntools, workflow guidance, approval boundaries, and this guide's URL. It performs\nno provider calls, reads no project data, and changes no permissions.\n`next` lists stored reads. Optional `actions` lists loaded tools for work that\nrequires approval; listing an action does not authorize or execute it.\n`includeCatalog: true` additionally returns toolkit details when needed.\n\nAnalysis routes also return `playbooks`: Canonry's analyst playbooks for that\nwork, the same files its built-in agent reads. Read each one before\ninterpreting results. `canonry_help({ playbook: \"<slug>\" })` returns its full\ntext, a note on using it over MCP, and every available slug. Playbooks are\nguidance, not permission.\n\nHosted connections use a fixed catalog. Help only suggests tools offered by that\nconnection; it never tells a hosted agent to dynamically load a toolkit. A\nprogressive local stdio connection may return `loadToolkits`: call\n`canonry_load_toolkit` with one returned name, await it, then call help again.\nLoading only changes local tool discovery, never server authority.\n\nThe optional `canonry://agent-operations/v1` MCP resource contains this same\nguide. If the host cannot read resources or open links, continue through help.\nDo not install a plugin, local runtime, or skill merely to use connected MCP.\nAn installed Codex or Claude Canonry skill contains a generated copy of this\nguide plus links to host-native references. It does not replace runtime help.\n\n## Vocabulary and evidence\n\n- **Mentioned** means the brand appears in answer text. **Cited** means its\n  domain appears in source links. Either, both, or neither can occur; never\n  compute one signal from the other.\n- `answerMentioned: null` means not checked, not false. Missing runs and empty\n  populations mean no measurement, not zero visibility.\n- `citationState: not-measured` (with `cited: null`) means the engine returns no\n  sources, such as a local model without web access, so whether it cites the\n  domain was never observed. It is never a miss: cited rates leave it out and\n  count it as `citationNotMeasured`, and a cited rate with nothing measured is\n  null, not 0. Mention is still measured on those answers. Other reads show the\n  same state in their own shape:\n  - visibility report: an answer's `citationUnavailableReason:\n    citation-not-measured`, or a rate's `reason: citation-not-measured`;\n  - Advanced metrics: `{state: unavailable, reason: citation_not_measured}`;\n  - research and snapshot answers: `citationMeasured: false` (research also\n    sends `citationState: null`);\n  - overview: `citationNotMeasuredQueries`, `citationNotMeasuredPairs` and\n    `citationNotMeasuredCount`;\n  - analytics: the gaps bucket `citationNotMeasured[]` and sources'\n    `citationNotMeasuredAnswers`;\n  - visibility compare: `excludedNotMeasured`.\n- Preserve project, time window, provider, requested/served model, location,\n  sample size, and query class when comparing evidence. Use server-returned\n  metrics; do not invent a score from incompatible populations.\n- Simple projects and Advanced portfolios share the workflow. For Advanced\n  results, preserve Property, Target, market, plan revision, and class scope.\n  Groups organize navigation; do not infer an unrequested fan-out.\n- Research is isolated evidence, not tracked measurement. A probe still spends\n  quota and persists evidence but is excluded from normal tracking metrics.\n\n## Workflows\n\n**Status:** read the stored overview and freshness first. Say when evidence is\nmissing instead of silently creating it.\n\n**Setup:** Agent Readiness needs no answer-engine provider; AI Visibility does.\nAfter an Agent Readiness result on an install with no provider (a `NO_PROVIDER`\nnotice, or doctor's `providers.none-configured`), propose AI Visibility setup\nas the next step. The operator adds the provider key in the dashboard or in\ntheir own terminal; never ask for it in chat. A saved key is not a verified one:\nwith approval, `canonry settings provider test <name>` or `canonry_provider_test`\nchecks the saved connection with the provider now (usually one tiny prompt on\nthe operator's account) and reports `connected`, `failed` with the provider's\nreason, or `not-verified`. It needs install administrator authority and\n`settings.write`; while a connection's test is still running, another test of it\nreturns `OPERATION_IN_PROGRESS`, so wait for that result. The latest result is\nkept as the connection's `lastTest` (`canonry settings provider-info <name>` or\n`canonry_provider_settings_get`) until its key, endpoint, model, Vertex project,\nregion or credentials, or CDP endpoint changes, or the connection is\ndisconnected; read it before testing again.\nRerunning `canonry bootstrap` after a provider change reloads saved provider\nsettings on a matching running local server and reports whether they became\nactive. If the server is offline, start it to apply the saved settings. For an\nexplicit reload of the connected server's own config, use\n`canonry settings reload-providers` or `canonry_providers_reload` with install\nadministrator authority. Remote servers are never reloaded automatically by\nbootstrap, and a local server that belongs to another install is left alone.\nPorts and database settings still need a restart.\n\n**Diagnose:** inspect stored history and comparable evidence. Explain what\nchanged separately from why it might have changed. A hypothesis is not a\nmeasured cause. Propose bounded verification if stored evidence is insufficient.\n\n**Agent Readiness:** read `canonry_agent_readiness_issues` for stored findings,\naffected-page counts and example URLs, then `canonry_agent_readiness_issue_pages`\nfor a selected issue's remaining pages. Pin subsequent reads to the returned\nrun. Inspect coverage and omissions: a passing score can still have findings,\nan older scan may lack cross-page evidence, and a partial scan cannot establish\nsite-wide absence. Advisory findings require judgment before proposing a repair.\nAudit evidence informs technical repairs and existing-page recommendations;\nit does not itself establish a new-blog opportunity or authorize any edit.\n\n**Prospecting:** generate a one-shot company snapshot without creating a project.\nInspect stored provider settings first. Agree on the company, domain, selected\nproviders, and queries before starting the quota-spending snapshot action.\nBrowser-only selection requires manual queries. Progressive stdio help offers\nthe discovery toolkit when this connection permits snapshots; load it, then\ncall help again. Fixed catalogs offer only already available actions. Read-only\nand restricted connections must not bypass missing snapshot access.\n\n**Measurement:** inspect the existing setup and results before proposing edits.\nKeep research, query tracking, plan publication, and sweep execution separate.\nFor direct research, submit the final editable query text in one context. For a\nreviewed batch, submit each explicit destination with its final text and one\nidempotency key. Pattern substitution happens in the client before either\nrequest; choosing a market or Property records a destination only and never\nrewrites a query or creates an automatic fan-out. `research.run` does not\nauthorize saving patterns, changing tracking, publishing plans, or settings.\nUse a supported preview where available, inspect its exact destination and\nrevision, then seek approval for the actual change. A preview may itself require\nwrite permission; never treat a dry-run flag as a universal safety guarantee.\n\n**Integrations:** inspect stored connection state and snapshot freshness first.\nProvider configuration evidence does not prove a browser event fired or a\nconversion was recorded. Connection, resource selection, refresh/sync, and live\nreads are separate actions. Credentials belong in the operator's secure setup\nflow, never in chat, tool arguments, reports, or public guidance.\n\n**Reports:** use saved evidence for the requested period and scope. Keep mention\nand citation signals separate, include dates and sample sizes, and state missing\nor stale inputs. For Advanced Property mention rankings, use\n`canonry_measurement_portfolio_summary` and its `mentionRanking.strongest`,\n`.weakest`, and `.excluded` lists. It defaults to non-brand questions; state the\nreturned class and report branded results separately. An unavailable portfolio\naggregate does not invalidate available Property mention rates. Flag excluded\nProperties individually; do not silently replace mention ranking with citation\nranking. Compact `nextCursor` completes only `pageList`; use `list` to enumerate\none ranking, markets, observed names or cited domains, preserving filters.\nFirst-page sibling lists are bounded summaries. Keep sample sizes and ties\nvisible. Preparing a report does not\nauthorize new measurement.\n\n## Authority and approval\n\n### Agent operations\n\nUse `canonry_key_self` (CLI `canonry key whoami --format json`) to inspect the\ncurrent credential's scopes, project boundary, and host-derived `operator`\nauthority without exposing its token. Missing `operator` means unapproved.\n`canonry_settings_get` and\n`canonry_telemetry_get` describe the connected server, not the agent's local\nmachine. Telemetry reports configured preference, effective state, and any\nenvironment override; inspecting status never creates an anonymous identifier.\nAfter approval, `canonry_telemetry_update` changes that preference and\n`canonry_provider_settings_update` changes or resets an already-configured\nprovider's model and quota, restores its built-in endpoint, or removes an\noptional Local key. Both require `settings.write`; neither accepts credentials.\nA reset, restoring the endpoint and removing the Local key included, also\nrequires install administrator authority. Pass the `revision` from\n`canonry_provider_settings_get` as `expectedRevision` to reject a stale edit.\nServer telemetry reads and updates additionally require operator authority.\nOrdinary audit-history reads omit internal telemetry events and their state.\n\nOperator authority is deny-by-default and separate from customer admin roles.\nThe deployment owner must approve a dedicated, instance-wide API key's ID in\nthe server environment variable `CANONRY_OPERATOR_KEY_IDS` (comma-separated IDs),\nthen restart the server. Empty/unset approves nobody; wildcards are invalid.\nKeep the bearer private to internal operators; never approve a customer-held or\nshared proxy/bootstrap key. Use `logs.read` for read-only diagnostics, adding\n`settings.write` only when telemetry control is required. Ordinary key creation,\naccount roles, OAuth consent, and caller headers cannot grant operator status.\nRevoking an approved key invalidates it immediately. Host enrollment is a trust\nbootstrap step, intentionally unavailable through customer-facing APIs.\nAPI, CLI, and MCP enforce the same boundary; MCP hides internal tools unless\nthe server confirms operator authority, including in explicit read-only mode.\nProject analytics, research, and normal project permissions are unchanged.\n\n`canonry_logs_list` reads bounded, redacted runtime events from both the\napplication logger and Fastify request/error logging. It requires an\ninstance-wide `logs.read` grant (or wildcard) and a host-approved direct bearer.\nBrowser sessions, OAuth/delegated credentials, customer admins, and project-scoped\nkeys cannot use it, even with a project filter or a matching allowlist ID.\nA `logs.read`-only key is read-only automatically, without a\nsecond `read` marker. Named `*.read` scopes cannot grant mutations; an explicit\nwrite grant is needed and remains subject to its route gates. Returned messages\nare sanitized and bounded; raw request or response bodies, headers, cookies,\nprovider payloads, and stacks are not\npart of the queryable surface. The same secret-redaction policy runs before\nconsole output and storage. Do not deliberately log secrets: redaction is a\ndefense in depth, not permission to put credentials into diagnostic strings.\nOpaque escaped payloads containing secret assignments are omitted when safe\npartial masking cannot be guaranteed; correlate their retained error codes and IDs.\n\nFile-backed hosts retain runtime logs in SQLite across restarts, bounded to\n10,000 events and seven days. In-memory hosts report `retention: \"process\"`.\nFilter by `actor`, `requestId`, `runId`, `projectId`, `module`, `level`, or an\ninclusive `since`/`until` interval. Keep filters unchanged when resuming an\nopaque cursor; retention eviction can invalidate it. Inspect `retentionPolicy`,\n`captureErrors`, `dropped`, `truncated`, and `retention` before drawing\nconclusions. Missing logs are not proof that an action did not happen. Use\n`canonry_project_history` or `canonry_history_global` for persistent audit events;\noffset pages have deterministic ordering but are not snapshots of concurrent writes.\n\nAudit `actor` comes from authenticated identity (`user:<id>` or `api-key:<id>`),\nnot a caller-supplied header. A delegated MCP credential records its originating\nuser as actor and the actual credential in `credentialId`. `requestId` correlates\nHTTP events; `userAgent` and `actorSession` are bounded, untrusted client hints,\nnever identity or permission grants. Older audit rows are not backfilled with\nidentities the server cannot prove.\n\nBoth shipped HTTP hosts issue restart-safe UUID request IDs and return them in\n`x-request-id`. Use that value to correlate a CLI/API failure with log entries;\nHTTP diagnostics retain the method and route template, not raw URL parameters.\nRequest-bound loggers retain completion attribution, while generic background\ncontinuations stop inheriting caller identity after the response completes.\nCapture covers the owning server process after initialization, not arbitrary\nconsole output, other worker processes, or host/container logs. Run one server\ninstance per process and database, as required by the single-tenant deployment\nmodel; this is not a cross-tenant or distributed log collector.\n\nFor CLI use, settings reads are remote. Google setup and telemetry retain their\nlocal defaults: pass `--target server` explicitly to configure the connected\nserver. `schedule list <project>` lists all schedule kinds, and\n`notify events --target server` discovers the server's event catalog.\n\nMCP returns legacy text JSON plus structured results. Objects keep their shape;\narrays use `{items: [...]}` in `structuredContent`, and scalars use `{value: ...}`.\nErrors preserve the existing envelope and CLI exit codes: HTTP 4xx (including\n429 policy limits) use exit 1; HTTP 5xx use exit 2. Server-provided `Retry-After`\nand request IDs are exposed as `retryAfterMs` and `requestId` when available;\nclients do not infer retryability from HTTP 429 or retry automatically.\nFor a write with an ambiguous outcome, inspect saved state or its receipt before\nretrying; a retry hint is not proof that repeating a write is safe.\n\n### Action boundaries\n\nStart with stored evidence. Before a live provider read, sweep, probe, research\nrun, sync, write, or externally visible action, obtain approval covering its\nexact target, action, and bounded work. Approval already given for that exact\noperation need not be asked for again, but does not extend to more projects,\nlarger batches, retries with new identities, or recurring work.\n\nHTTP GET and MCP `readOnlyHint` describe aspects of an operation, not its cost\nor permission. Provider discovery, account reads, and live diagnostics may\nconsume quota even when labeled read-only. If the tool's effect is unclear,\ninspect its description and request direction before calling it.\n\nAuthentication, role/scope checks, project restrictions, quotas, and guarded\napproval receipts are enforced by the server. Help, skills, resources, and tool\nvisibility cannot grant authority. Never change credentials, endpoints, or\nproject identifiers to work around a missing tool or a `403` response.\n\nFor guarded ads writes, inspect unresolved operation receipts before retrying.\nUse the receipt's supported recovery action; do not replay a mutation under a\nnew identity. An executor cannot create or widen its own human approval grant.\nOn ambiguous results, exhausted bounds, or refusal, stop and report what is\nknown and what permission or operator action is needed.\n\n## Version and source\n\nThis public, versioned document is the source for initialization guidance,\nintent routes, the optional resource, and generated Canonry `SKILL.md` files.\nGuide v1 may receive compatible clarifications; incompatible routing contracts\nrequire a new guide version. The running server's help describes its actual\ncatalog and remains usable without fetching this document.\n"
 };
 
 // src/mcp/operations-guide.ts

package/dist/{chunk-ISIJ2NS4.js → chunk-HBHLYWKE.js}

@@ -1,6 +1,8 @@
 import {
-  hostMatchesDomain
-} from "./chunk-ZBTUISPG.js";
+  CitationStates,
+  hostMatchesDomain,
+  isCitationMeasurable
+} from "./chunk-O7S7OHLE.js";
 
 // src/citation-utils.ts
 function pickProjectCitedDomain(citedDomains, projectDomains) {
@@ -10,16 +12,17 @@ function pickProjectCitedDomain(citedDomains, projectDomains) {
   return void 0;
 }
 function determineCitationState(normalized, domains) {
+  if (!isCitationMeasurable(normalized)) return CitationStates["not-measured"];
   for (const canonicalDomain of domains) {
     if (normalized.citedDomains.some((d) => hostMatchesDomain(d, canonicalDomain))) {
-      return "cited";
+      return CitationStates.cited;
     }
     for (const source of normalized.groundingSources) {
-      if (hostMatchesDomain(source.uri, canonicalDomain)) return "cited";
-      if (source.title && hostMatchesDomain(source.title, canonicalDomain)) return "cited";
+      if (hostMatchesDomain(source.uri, canonicalDomain)) return CitationStates.cited;
+      if (source.title && hostMatchesDomain(source.title, canonicalDomain)) return CitationStates.cited;
     }
   }
-  return "not-cited";
+  return CitationStates["not-cited"];
 }
 function computeCitedCompetitorDomains(citedDomains, competitorDomains) {
   const citedCompetitors = /* @__PURE__ */ new Set();

package/dist/{chunk-EJZ444VV.js → chunk-HL2LGRTI.js}

@@ -28,7 +28,7 @@ import {
   unknownUsageObservation,
   usdToMicros,
   withRetry
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // ../provider-answer-services/src/core/http.ts
 var MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
@@ -189,9 +189,10 @@ function retryOptions(options, isRetryable) {
   return {
     maxRetries: 2,
     baseDelayMs: 2e3,
-    isRetryable: (error) => !options.signal?.aborted && isRetryable(error),
+    isRetryable,
     computeDelayMs: (_attempt, error, delay) => retryAfterDelayMs(error) ?? delay,
-    ...options.sleep ? { sleep: options.sleep } : {}
+    ...options.sleep ? { sleep: options.sleep } : {},
+    ...options.signal ? { signal: options.signal } : {}
   };
 }
 function requestJson(descriptor, request, options, errorMessage) {
@@ -430,19 +431,20 @@ function createAnswerServiceAdapter(definition, options = {}) {
       citationMeasurable: raw.citationMeasurable ?? raw.evidence?.citationMeasurable ?? false
     };
   }
-  async function healthcheck(config) {
+  async function healthcheck(config, signal) {
     const problem = configProblem(descriptor, config);
     if (problem) return { ok: false, provider: config.provider, message: problem };
     const keyCheck = descriptor.settings.keyCheck;
     if (!keyCheck) {
-      return { ok: true, provider: config.provider, message: `${descriptor.displayName} key saved, not verified: the service documents no free key check.` };
+      return { ok: true, verified: false, provider: config.provider, message: `${descriptor.displayName} key saved, not verified: the service documents no free key check.` };
     }
     try {
       await requestKeyCheck(descriptor, { method: keyCheck.method, path: keyCheck.path }, {
         apiKey: config.apiKey ?? "",
         timeoutMs: 15e3,
         ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {},
-        ...options.sleep ? { sleep: options.sleep } : {}
+        ...options.sleep ? { sleep: options.sleep } : {},
+        ...signal ? { signal } : {}
       });
       return { ok: true, provider: config.provider, message: `${descriptor.displayName} connected` };
     } catch (error) {

package/dist/chunk-J6536OL6.js

@@ -0,0 +1,31 @@
+import {
+  CitationStates
+} from "./chunk-O7S7OHLE.js";
+
+// src/snapshot-cell.ts
+var SNAPSHOT_CELL_LEGEND = "(cell = [citation][mention];  C=cited c=not \xB7=not measured, M=mentioned m=not, \u2013=no data)";
+function citationGlyph(state) {
+  switch (state) {
+    case CitationStates.cited:
+      return "C";
+    case CitationStates["not-cited"]:
+      return "c";
+    case CitationStates["not-measured"]:
+      return "\xB7";
+  }
+}
+function citedBase(total, notMeasured) {
+  return total - (notMeasured ?? 0);
+}
+function mentionGlyph(mentioned) {
+  if (mentioned === true) return "M";
+  if (mentioned === false) return "m";
+  return "\u2013";
+}
+
+export {
+  SNAPSHOT_CELL_LEGEND,
+  citationGlyph,
+  citedBase,
+  mentionGlyph
+};

package/dist/{chunk-RLKI2QF7.js → chunk-KVRX7YIH.js}

@@ -5,11 +5,11 @@ import {
   isStoredPageReadTool,
   isStoredReadTool,
   truncateToolResult
-} from "./chunk-Q5SNOMRB.js";
+} from "./chunk-56VVRWJM.js";
 import {
   CANONRY_MCP_TOOLKITS,
   resolveAeroSkillDir
-} from "./chunk-MTW37GXF.js";
+} from "./chunk-2FWYWGIR.js";
 import {
   AGENT_REASONING_LEVELS,
   aeroStreamFn,
@@ -23,18 +23,18 @@ import {
   resolveApiKeyFor,
   resolveModelForProvider,
   validateAgentProviderRegistry
-} from "./chunk-BLW327AU.js";
+} from "./chunk-EE3QTCLS.js";
 import {
   CanonryMcpToolNames,
   canonryMcpTools
-} from "./chunk-3GMBHGQ5.js";
+} from "./chunk-F46TBLXK.js";
 import {
   createLogger
-} from "./chunk-UXXZXXNG.js";
+} from "./chunk-7SNMIXEQ.js";
 import {
   agentToolEvents,
   llmUsageEvents
-} from "./chunk-KK3Z34AN.js";
+} from "./chunk-2DV7F6XA.js";
 import {
   MeasurementPortfolioLists,
   SeoCapabilities,
@@ -43,7 +43,7 @@ import {
   describeError,
   validationError,
   visibilityReportRequestSchema
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // src/agent/session.ts
 import fs2 from "fs";
@@ -503,12 +503,16 @@ function nearToolNames(name, known) {
 function isReadTool(name) {
   return name === DISCOVER || name === LOAD || metadata.get(name)?.access === "read";
 }
+function canonicalToolName(name) {
+  return metadata.get(name)?.deprecatedAliasOf ?? name;
+}
 function correctToolNames(runtime, message, visible) {
   let known;
   for (const block of message.content) {
     if (block.type !== "toolCall" || visible.has(block.name)) continue;
     known ??= /* @__PURE__ */ new Set([...metadata.keys(), ...runtime.allowed.map((tool) => tool.name), ...visible]);
-    const matches = nearToolNames(block.name, known);
+    const renamed = canonicalToolName(block.name);
+    const matches = renamed === block.name ? nearToolNames(block.name, known) : [renamed];
     if (matches.length !== 1 || !visible.has(matches[0]) || !isReadTool(matches[0])) continue;
     runtime.corrected.set(block.id, block.name);
     block.name = matches[0];
@@ -540,6 +544,12 @@ function withCorrectedToolNames(runtime, response, visible, wrapUp, signal) {
 }
 function suggestToolName(runtime, name) {
   const visible = visibleTools(runtime).map((tool) => tool.name);
+  const renamed = canonicalToolName(name);
+  if (renamed !== name) {
+    if (!visible.includes(renamed) && !runtime.allowed.some((tool) => tool.name === renamed)) return void 0;
+    const toolkit2 = metadata.get(renamed)?.tier;
+    return visible.includes(renamed) || !toolkit2 ? `${name} is now ${renamed}. Call ${renamed} instead.` : `${name} is now ${renamed}. Call ${LOAD} with toolkit "${toolkit2}", then call ${renamed}.`;
+  }
   const matches = nearToolNames(name, /* @__PURE__ */ new Set([...visible, ...runtime.allowed.map((tool) => tool.name)]));
   if (matches.length === 0 || matches.length > MAX_NAME_SUGGESTIONS || matches.includes(name)) return void 0;
   if (matches.length > 1) return `${name} is not a tool. Did you mean one of: ${matches.join(", ")}? Call the one you meant by its exact name.`;
@@ -771,11 +781,11 @@ async function readAeroViewEvidence(options) {
     if (!context.page?.nodeKey) {
       const overview = await client.getTechnicalAeoCrawl(projectName, context.page);
       const search2 = new URLSearchParams(overview.runId ? { siteHealthRunId: overview.runId } : {});
-      return { context, retrievedAt: (/* @__PURE__ */ new Date()).toISOString(), source: { label: "Open Site Health", href: `${base}/projects/${encodeURIComponent(projectName)}/technical-aeo?${search2}` }, overview, instruction: "No page is selected. Ask which page if the prompt is ambiguous. Retrieval time is not the crawl date." };
+      return { context, retrievedAt: (/* @__PURE__ */ new Date()).toISOString(), source: { label: "Open Agent Readiness", href: `${base}/projects/${encodeURIComponent(projectName)}/agent-readiness?${search2}` }, overview, instruction: "No page is selected. Ask which page if the prompt is ambiguous. Retrieval time is not the crawl date." };
     }
     const audit = await client.getTechnicalAeoPageAudit(projectName, context.page);
     const search = new URLSearchParams({ nodeKey: context.page.nodeKey, ...audit.runId || context.page.runId ? { runId: audit.runId ?? context.page.runId } : {} });
-    return { context, retrievedAt: (/* @__PURE__ */ new Date()).toISOString(), source: { label: "Open stored page audit", href: `${base}/api/v1/projects/${encodeURIComponent(projectName)}/technical-aeo/crawl/pages/audit?${search}` }, audit, interpretation: "A stored technical audit is not proof of a cause for mention or citation changes." };
+    return { context, retrievedAt: (/* @__PURE__ */ new Date()).toISOString(), source: { label: "Open stored page audit", href: `${base}/api/v1/projects/${encodeURIComponent(projectName)}/agent-readiness/crawl/pages/audit?${search}` }, audit, interpretation: "A stored Agent Readiness audit scan is not proof of a cause for mention or citation changes." };
   }
   const request = visibilityReportRequestSchema.parse(context?.selection ?? { queryClass: "all", limit: 10 });
   const report = await client.getVisibilityReport(projectName, request);

package/dist/{chunk-3BA75QYU.js → chunk-LJO2BKWU.js}

@@ -1,7 +1,7 @@
 import {
   USAGE_TELEMETRY_HEADERS,
   redactLogString
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // ../api-routes/src/request-context.ts
 import { AsyncLocalStorage } from "async_hooks";

package/dist/{chunk-CN6MVUY3.js → chunk-LNVFERI4.js}

@@ -15,7 +15,7 @@ import {
   hostMatchesDomain,
   hostOf,
   isLocationRedirectStatus
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // ../integration-traffic/src/agent-trust.ts
 var AGENT_TRUST_RULES_VERSION = 2;

package/dist/{chunk-ZADRESLB.js → chunk-NQYJHKML.js}

@@ -1,6 +1,11 @@
+import {
+  SNAPSHOT_CELL_LEGEND,
+  citationGlyph,
+  mentionGlyph
+} from "./chunk-J6536OL6.js";
 import {
   createApiClient
-} from "./chunk-OL2L5ANJ.js";
+} from "./chunk-UGO2FO6V.js";
 import {
   emitJsonl
 } from "./chunk-Z7IUAJOF.js";
@@ -10,7 +15,6 @@ import {
   isMachineFormat
 } from "./chunk-HGMYEDAQ.js";
 import {
-  CitationStates,
   MentionIdentities,
   OUTSTANDING_PROVIDER_BATCH_STATUSES,
   ProviderBatchStatuses,
@@ -19,12 +23,38 @@ import {
   formatMicros,
   formatRunErrorOneLine,
   resolveProviderInput
-} from "./chunk-ZBTUISPG.js";
+} from "./chunk-O7S7OHLE.js";
 
 // src/commands/run.ts
 function getClient() {
   return createApiClient();
 }
+async function previewRun(project, format) {
+  const preview = await getClient().previewRun(project);
+  if (format === "jsonl") {
+    emitJsonl([preview]);
+    return;
+  }
+  if (format === "json") {
+    console.log(JSON.stringify(preview, null, 2));
+    return;
+  }
+  const reasons = {
+    "unpublished-plan": "Publish the Advanced Measurement draft first.",
+    "no-queries": "Add queries first.",
+    "no-provider": "Connect an answer provider first.",
+    "providers-failing": "Fix the held provider accounts first.",
+    "run-in-progress": `A sweep is already active (${preview.activeRunId}).`
+  };
+  console.log(`Sweep preview: ${project}${preview.revision === null ? "" : ` \xB7 published revision ${preview.revision}`}`);
+  console.log(`  ${preview.queryCount} queries${preview.assignmentCount === null ? "" : ` \xB7 ${preview.assignmentCount} assignments`}`);
+  for (const population of preview.queryClasses) console.log(`  ${population.queryCount} ${population.queryClass} queries${population.assignmentCount === null ? "" : ` \xB7 ${population.assignmentCount} assignments`}`);
+  console.log(`  ${preview.requestCount} runnable requests \xB7 ${preview.expectedRequestCount} planned answers`);
+  for (const engine of preview.engines) console.log(`  ${engine.provider}${engine.models.length ? ` (${engine.models.join(", ")})` : ""}: ${engine.requestCount} requests${engine.available ? "" : " \xB7 unavailable"}`);
+  for (const location of preview.locations) console.log(`  Location: ${location.location ?? "No location"} \xB7 ${location.requestCount} requests`);
+  for (const [provider, held] of Object.entries(preview.admission.providers)) console.log(`  Held: ${providerAccountStreakLine(provider, held)}`);
+  console.log(preview.blockedReason === null ? "  Ready to start." : `  ${reasons[preview.blockedReason]}`);
+}
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "partial", "failed", "cancelled"]);
 function shellArg(value) {
   return /^[\w.-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
@@ -444,6 +474,9 @@ function printRunDetail(run) {
   if (run.createdAt) console.log(`  Created:  ${run.createdAt}`);
   const skipped = Object.entries(run.skippedProviders ?? {});
   for (const [provider, streak] of skipped) console.log(`  Skipped:  ${providerAccountStreakLine(provider, streak)}`);
+  for (const [provider, failure] of Object.entries(run.providerFailures ?? {})) {
+    console.log(`  Failing:  ${provider}: ${failure.failedQueries} ${failure.failedQueries === 1 ? "query" : "queries"} failed${failure.stopped ? ", no longer called this run" : ""}. ${failure.message}`);
+  }
   if (run.error) {
     if (run.error.message) console.log(`  Error:    ${run.error.message}`);
     if (run.error.providers) {
@@ -462,15 +495,13 @@ function printRunDetail(run) {
   if (run.usage && run.usage.length > 0) printUsageTable(run.usage);
   if (run.snapshots && run.snapshots.length > 0) {
     console.log(`
-  Snapshots: ${run.snapshots.length}  (cell = [citation][mention];  C=cited c=not, M=mentioned m=not, \u2013=no data)`);
+  Snapshots: ${run.snapshots.length}  ${SNAPSHOT_CELL_LEGEND}`);
     let differentSubject = 0;
     for (const s of run.snapshots) {
-      const citationGlyph = s.citationState === CitationStates.cited ? "C" : "c";
-      const mentionGlyph = typeof s.answerMentioned === "boolean" ? s.answerMentioned ? "M" : "m" : "\u2013";
       const modelLabel = s.model ? ` (${s.model})` : "";
       const ruledOut = s.mentionIdentity === MentionIdentities["wrong-subject"];
       if (ruledOut) differentSubject++;
-      console.log(`    [${citationGlyph}${mentionGlyph}]  ${s.provider}${modelLabel}  ${s.query}${ruledOut ? "  \xB7 different subject" : ""}`);
+      console.log(`    [${citationGlyph(s.citationState)}${mentionGlyph(s.answerMentioned)}]  ${s.provider}${modelLabel}  ${s.query}${ruledOut ? "  \xB7 different subject" : ""}`);
     }
     if (differentSubject > 0) {
       console.log("  \xB7 different subject: the answer uses your name, but sentiment found it is about something else, so it is not counted as mentioned.");
@@ -604,6 +635,7 @@ async function fillRun(runId, opts = {}) {
 }
 
 export {
+  previewRun,
   providerAccountStreakLine,
   runAdmissionLines,
   triggerRun,