@ainyc/canonry 4.193.2 → 4.195.0

package/dist/{chunk-24JHDZ7H.js → chunk-B2XM6AQ6.js}

@@ -21,6 +21,7 @@ import {
   adsOperationReconcileRequestSchema,
   adsPauseRequestSchema,
   adsUnresolvedOperationListQuerySchema,
+  apiKeyDtoSchema,
   backlinkSourceSchema,
   canonicalizeGtmAccountId,
   canonicalizeGtmResourceSelection,
@@ -38,8 +39,10 @@ import {
   googleAdsMetricsWindowSchema,
   gscPerformanceOrderBySchema,
   isReadOnlyKey,
+  isSensitiveDiagnosticQueryKey,
   keywordBatchRequestSchema,
   keywordGenerateRequestSchema,
+  logQuerySchema,
   measurementChangesQuerySchema,
   measurementDataQualityQuerySchema,
   measurementDiscoveryRequestSchema,
@@ -79,12 +82,15 @@ import {
   measurementQueryTemplateApplyRequestSchema,
   measurementQueryTemplateUpsertRequestSchema,
   measurementQuestionResultQuerySchema,
+  normalizeTelemetryStatus,
   notificationCreateRequestSchema,
   notificationEventSchema,
+  operationalLogListDtoSchema,
   organicEvidencePeriodSchema,
   projectConfigSchema,
   projectUpsertRequestSchema,
   providerQuotaPolicySchema,
+  providerSummaryEntryDtoSchema,
   queryBatchRequestSchema,
   queryGenerateRequestSchema,
   queryTrackingCommitRequestSchema,
@@ -97,15 +103,19 @@ import {
   runListFilterQuerySchema,
   runTriggerRequestSchema,
   schedulableRunKindSchema,
+  scheduleDtoSchema,
   scheduleUpsertRequestSchema,
+  settingsDtoSchema,
   skillsClientSchema,
+  snapshotRequestInputSchema,
+  telemetryStatusDtoSchema,
   trafficConnectCloudRunRequestSchema,
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
   trafficSeriesGranularitySchema,
   visibilityReportRequestSchema
-} from "./chunk-5CXUV3ZX.js";
+} from "./chunk-3WODA4JF.js";
 
 // src/cli-error.ts
 function isMachineFormat(format) {
@@ -592,6 +602,58 @@ function configExists() {
   return fs.existsSync(getConfigPath());
 }
 
+// src/client-reliability.ts
+function parseRetryAfterMs(header, now = Date.now()) {
+  if (!header) return void 0;
+  const value = header.trim();
+  if (!value) return void 0;
+  if (/^\d+(?:\.\d+)?$/.test(value)) {
+    const delayMs2 = Number(value) * 1e3;
+    return Number.isFinite(delayMs2) && delayMs2 >= 0 && delayMs2 <= Number.MAX_SAFE_INTEGER ? delayMs2 : void 0;
+  }
+  if (!/^[a-z]{3},\s/i.test(value)) return void 0;
+  const target = Date.parse(value);
+  if (!Number.isFinite(target)) return void 0;
+  const delayMs = Math.max(0, target - now);
+  return Number.isSafeInteger(delayMs) ? delayMs : void 0;
+}
+function httpErrorDetails(serverDetails, response) {
+  const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+  const requestId = response.headers.get("x-request-id") ?? response.headers.get("request-id");
+  return {
+    ...serverDetails && typeof serverDetails === "object" && !Array.isArray(serverDetails) ? serverDetails : {},
+    httpStatus: response.status,
+    ...retryAfterMs === void 0 ? {} : { retryAfterMs },
+    ...requestId ? { requestId } : {}
+  };
+}
+function isConnectionFailure(message) {
+  return message.includes("fetch failed") || message.includes("ECONNREFUSED") || message.includes("connect ECONNREFUSED");
+}
+function connectionFailureMessage(target) {
+  return `Could not connect to canonry server at ${redactRequestTarget(target)}. Check that this URL is reachable and the server is running. For a local Canonry instance, start it with "canonry serve" (or "canonry serve &" to run in background).`;
+}
+function redactRequestTarget(target) {
+  try {
+    const url = new URL(target);
+    url.username = "";
+    url.password = "";
+    for (const key of [...url.searchParams.keys()]) {
+      if (isSensitiveDiagnosticQueryKey(key)) {
+        url.searchParams.set(key, "<redacted>");
+      }
+    }
+    return url.toString();
+  } catch {
+    return target.replace(/\/\/[^/@]*@/, "//");
+  }
+}
+
+// src/package-version.ts
+import { createRequire } from "module";
+var _require = createRequire(import.meta.url);
+var PACKAGE_VERSION = _require("../package.json").version;
+
 // ../api-client-generated/src/generated/core/bodySerializer.gen.ts
 var jsonBodySerializer = {
   bodySerializer: (body) => JSON.stringify(
@@ -2929,6 +2991,22 @@ var putApiV1SettingsProvidersByName = (options) => {
     }
   });
 };
+var putApiV1SettingsGoogle = (options) => {
+  return (options.client ?? client).put({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/settings/google",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers
+    }
+  });
+};
 var getApiV1Keys = (options) => {
   return (options?.client ?? client).get({
     security: [
@@ -3077,6 +3155,30 @@ var putApiV1ProjectsByNameSchedule = (options) => {
     }
   });
 };
+var getApiV1ProjectsByNameSchedules = (options) => {
+  return (options.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/projects/{name}/schedules",
+    ...options
+  });
+};
+var getApiV1NotificationsEvents = (options) => {
+  return (options?.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/notifications/events",
+    ...options
+  });
+};
 var getApiV1ProjectsByNameNotifications = (options) => {
   return (options.client ?? client).get({
     security: [
@@ -3129,6 +3231,18 @@ var postApiV1ProjectsByNameNotificationsByIdTest = (options) => {
     ...options
   });
 };
+var getApiV1OperationsLogs = (options) => {
+  return (options?.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/operations/logs",
+    ...options
+  });
+};
 var getApiV1Telemetry = (options) => {
   return (options?.client ?? client).get({
     security: [
@@ -5900,10 +6014,18 @@ function createClient2(opts) {
 }
 
 // src/client.ts
-function createApiClient() {
+var SAFE_CLIENT_NAME = /^\w[\w./-]{0,127}$/;
+var SAFE_ACTOR_SESSION = /^\w[\w.:-]{0,127}$/;
+function safeClientName(value) {
+  return value && SAFE_CLIENT_NAME.test(value) ? value : `canonry-cli/${PACKAGE_VERSION}`;
+}
+function safeActorSession(value) {
+  return value && SAFE_ACTOR_SESSION.test(value) ? value : void 0;
+}
+function createApiClient(opts = {}) {
   const config = loadConfig();
   const basePathResolved = !!config.basePath || "CANONRY_BASE_PATH" in process.env;
-  return new ApiClient(config.apiUrl, config.apiKey, { skipProbe: basePathResolved });
+  return new ApiClient(config.apiUrl, config.apiKey, { ...opts, skipProbe: basePathResolved || opts.skipProbe });
 }
 var ApiClient = class {
   originUrl;
@@ -5911,6 +6033,7 @@ var ApiClient = class {
   probePromise = null;
   probeSkipped;
   heyClient;
+  requestHeaders;
   /** Tracks the base URL most recently applied to `heyClient` so probe-driven updates only re-configure when something actually changed. */
   heyClientBaseUrl;
   constructor(baseUrl, apiKey, opts) {
@@ -5918,7 +6041,13 @@ var ApiClient = class {
     this.apiKey = apiKey;
     this.probeSkipped = opts?.skipProbe ?? false;
     this.heyClientBaseUrl = this.originUrl;
-    this.heyClient = createClient2({ baseUrl: this.originUrl, apiKey: this.apiKey });
+    const actorSession = safeActorSession(opts?.actorSession);
+    this.requestHeaders = {
+      authorization: `Bearer ${this.apiKey}`,
+      "user-agent": safeClientName(opts?.clientName),
+      ...actorSession ? { "x-canonry-actor-session": actorSession } : {}
+    };
+    this.heyClient = createClient2({ baseUrl: this.originUrl, apiKey: this.apiKey, headers: this.requestHeaders });
   }
   /**
    * On first API call, probe /health to auto-discover basePath when the user
@@ -5953,7 +6082,7 @@ var ApiClient = class {
   /** Apply the probe's discovered base URL to `heyClient` if it changed since last call. */
   refreshHeyClientBaseUrl() {
     if (this.originUrl !== this.heyClientBaseUrl) {
-      this.heyClient.setConfig({ baseUrl: this.originUrl, headers: { authorization: `Bearer ${this.apiKey}` } });
+      this.heyClient.setConfig({ baseUrl: this.originUrl, headers: this.requestHeaders });
       this.heyClientBaseUrl = this.originUrl;
     }
   }
@@ -5977,10 +6106,10 @@ var ApiClient = class {
         process.stderr.write(`[trace] (sdk-call) \u2192 ERROR (${Date.now() - traceStart}ms): ${msg}
 `);
       }
-      if (msg.includes("fetch failed") || msg.includes("ECONNREFUSED") || msg.includes("connect ECONNREFUSED")) {
+      if (isConnectionFailure(msg)) {
         throw new CliError({
           code: "CONNECTION_ERROR",
-          message: `Could not connect to canonry server at ${this.originUrl}. Start it with "canonry serve" (or "canonry serve &" to run in background).`,
+          message: connectionFailureMessage(this.originUrl),
           exitCode: EXIT_SYSTEM_ERROR
         });
       }
@@ -5989,7 +6118,7 @@ var ApiClient = class {
     if (traceEnabled) {
       const durMs = Date.now() - traceStart;
       process.stderr.write(
-        `[trace] ${result.request.method} ${result.request.url} \u2192 ${result.response.status} (${durMs}ms)
+        `[trace] ${result.request.method} ${redactRequestTarget(result.request.url)} \u2192 ${result.response.status} (${durMs}ms)
 `
       );
     }
@@ -5997,17 +6126,17 @@ var ApiClient = class {
     if (result.response.ok && contentType?.toLowerCase().startsWith("text/html")) {
       throw new CliError({
         code: "UNEXPECTED_RESPONSE_FORMAT",
-        message: `Expected a JSON response from the canonry API at ${result.request.url}, but received ${contentType} (HTTP ${result.response.status}). Check the server URL and base path.`,
+        message: `Expected a JSON response from the canonry API at ${redactRequestTarget(result.request.url)}, but received ${contentType} (HTTP ${result.response.status}). Check the server URL and base path.`,
         exitCode: EXIT_SYSTEM_ERROR,
         details: {
-          requestUrl: result.request.url,
+          requestUrl: redactRequestTarget(result.request.url),
           contentType,
           httpStatus: result.response.status
         }
       });
     }
     if (result.error !== void 0 && result.error !== null) {
-      const errorObj = typeof result.error === "object" && result.error !== null && "error" in result.error && typeof result.error.error === "object" && result.error.error !== null ? result.error.error : null;
+      const errorObj = typeof result.error === "object" && "error" in result.error && typeof result.error.error === "object" && result.error.error !== null ? result.error.error : null;
       const msg = errorObj?.message ? String(errorObj.message) : `HTTP ${result.response.status}: ${result.response.statusText}`;
       const code = errorObj?.code ? String(errorObj.code) : "API_ERROR";
       const exitCode = result.response.status >= 500 ? EXIT_SYSTEM_ERROR : EXIT_USER_ERROR;
@@ -6015,7 +6144,7 @@ var ApiClient = class {
         code,
         message: msg,
         exitCode,
-        details: { ...errorObj?.details ?? {}, httpStatus: result.response.status }
+        details: httpErrorDetails(errorObj?.details, result.response)
       });
     }
     return result.data;
@@ -6080,7 +6209,7 @@ var ApiClient = class {
     await this.probeBasePath();
     const url = `${this.originUrl}/api/v1${path3}`;
     const headers = {
-      Authorization: `Bearer ${this.apiKey}`,
+      ...this.requestHeaders,
       "Content-Type": "application/json",
       Accept: "text/event-stream"
     };
@@ -6090,10 +6219,10 @@ var ApiClient = class {
     } catch (err) {
       if (err instanceof CliError) throw err;
       const msg = describeError(err);
-      if (msg.includes("fetch failed") || msg.includes("ECONNREFUSED") || msg.includes("connect ECONNREFUSED")) {
+      if (isConnectionFailure(msg)) {
         throw new CliError({
           code: "CONNECTION_ERROR",
-          message: `Could not connect to canonry server at ${this.originUrl}. Start it with "canonry serve" (or "canonry serve &" to run in background).`,
+          message: connectionFailureMessage(this.originUrl),
           exitCode: EXIT_SYSTEM_ERROR
         });
       }
@@ -6110,7 +6239,7 @@ var ApiClient = class {
       const msg = errorObj?.message ? String(errorObj.message) : `HTTP ${res.status}: ${res.statusText}`;
       const code = errorObj?.code ? String(errorObj.code) : "API_ERROR";
       const exitCode = res.status >= 500 ? EXIT_SYSTEM_ERROR : EXIT_USER_ERROR;
-      throw new CliError({ code, message: msg, exitCode, details: { httpStatus: res.status } });
+      throw new CliError({ code, message: msg, exitCode, details: httpErrorDetails(errorObj?.details, res) });
     }
     return res;
   }
@@ -6961,16 +7090,32 @@ var ApiClient = class {
       () => putApiV1SettingsProvidersByName({ client: this.heyClient, path: { name }, body })
     );
   }
+  async updateGoogleSettings(body) {
+    return this.invoke(
+      () => putApiV1SettingsGoogle({ client: this.heyClient, body })
+    );
+  }
   async createSnapshot(body) {
     return this.invoke(() => postApiV1Snapshot({ client: this.heyClient, body }));
   }
   async getTelemetry() {
-    return this.invoke(() => getApiV1Telemetry({ client: this.heyClient }));
+    return normalizeTelemetryStatus(await this.invoke(() => getApiV1Telemetry({ client: this.heyClient })));
+  }
+  async listOperationalLogs(query = {}) {
+    return this.invoke(() => getApiV1OperationsLogs({ client: this.heyClient, query }));
   }
   async updateTelemetry(enabled) {
-    return this.invoke(() => putApiV1Telemetry({ client: this.heyClient, body: { enabled } }));
+    return normalizeTelemetryStatus(await this.invoke(() => putApiV1Telemetry({ client: this.heyClient, body: { enabled } })));
   }
   // ── Schedules / notifications / locations ───────────────────────────────
+  async listSchedules(project) {
+    return this.invoke(
+      () => getApiV1ProjectsByNameSchedules({ client: this.heyClient, path: { name: project } })
+    );
+  }
+  async listNotificationEvents() {
+    return this.invoke(() => getApiV1NotificationsEvents({ client: this.heyClient }));
+  }
   async putSchedule(project, body) {
     return this.invoke(
       () => putApiV1ProjectsByNameSchedule({
@@ -8790,11 +8935,6 @@ var ApiClient = class {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z5 } from "zod";
 
-// src/package-version.ts
-import { createRequire } from "module";
-var _require = createRequire(import.meta.url);
-var PACKAGE_VERSION = _require("../package.json").version;
-
 // src/mcp/tool-registry.ts
 import { z as z4 } from "zod";
 
@@ -9478,6 +9618,8 @@ var scheduleReadInputSchema = z4.object({
   project: projectNameSchema,
   kind: schedulableRunKindSchema.optional().describe('Schedulable run kind. Defaults to "answer-visibility" if omitted.')
 });
+var scheduleListOutputSchema = z4.object({ items: z4.array(scheduleDtoSchema) });
+var notificationEventsOutputSchema = z4.object({ items: z4.array(notificationEventSchema) });
 var agentWebhookAttachInputSchema = z4.object({
   project: projectNameSchema,
   url: z4.string().url()
@@ -10274,6 +10416,30 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/schedule"],
     handler: (client2, input) => client2.getSchedule(input.project, input.kind)
   }),
+  defineTool({
+    name: "canonry_schedules_list",
+    title: "List project schedules",
+    description: "List every stored schedule for a Canonry project, including each schedulable run kind. This reads configuration only and never starts work.",
+    access: "read",
+    tier: "setup",
+    inputSchema: projectInputSchema,
+    outputSchema: scheduleListOutputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/schedules"],
+    handler: (client2, input) => client2.listSchedules(input.project)
+  }),
+  defineTool({
+    name: "canonry_notification_events",
+    title: "List notification event types",
+    description: "List the supported stored notification event names. This is a static capability read; it does not send, test, or change notifications.",
+    access: "read",
+    tier: "setup",
+    inputSchema: emptyInputSchema,
+    outputSchema: notificationEventsOutputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/notifications/events"],
+    handler: (client2) => client2.listNotificationEvents()
+  }),
   defineTool({
     name: "canonry_backlinks_latest_release",
     title: "Discover latest Common Crawl release",
@@ -10318,10 +10484,73 @@ var canonryMcpTools = [
     access: "read",
     tier: "core",
     inputSchema: emptyInputSchema,
+    outputSchema: settingsDtoSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/settings"],
     handler: (client2) => client2.getSettings()
   }),
+  defineTool({
+    name: "canonry_key_self",
+    title: "Get current API key identity",
+    description: "Read safe metadata for the credential backing this MCP connection, including its scopes, project reach, and derived read-only status. It never exposes the bearer token or stored hash and does not grant mutation access.",
+    access: "read",
+    tier: "core",
+    inputSchema: emptyInputSchema,
+    outputSchema: apiKeyDtoSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/keys/self"],
+    handler: (client2) => client2.getApiKeySelf()
+  }),
+  defineTool({
+    name: "canonry_logs_list",
+    title: "Read runtime logs",
+    description: "Read bounded, redacted runtime logs, including application and HTTP failures. Filter by actor, request, run, project, level, module, or time. Inspect retention, retentionPolicy, dropped, and captureErrors for coverage; file-backed hosts retain logs across restarts. Separate from audit history. Requires instance-wide logs.read (or wildcard), and an admin role for user sessions; project-scoped keys are refused even with a project filter. Cursors expire on retention eviction; reuse with the same filters. No provider calls.",
+    access: "read",
+    tier: "setup",
+    inputSchema: logQuerySchema,
+    outputSchema: operationalLogListDtoSchema,
+    annotations: readAnnotations(false),
+    openApiOperations: ["GET /api/v1/operations/logs"],
+    handler: async (client2, input) => client2.listOperationalLogs(input)
+  }),
+  defineTool({
+    name: "canonry_telemetry_update",
+    title: "Update server telemetry preference",
+    description: "Set the connected server telemetry preference with explicit approval and settings.write. Returns effective state including environment overrides. Does not change the agent machine configuration.",
+    access: "write",
+    requiredScope: "settings.write",
+    tier: "setup",
+    inputSchema: z4.object({ enabled: z4.boolean() }).strict(),
+    outputSchema: telemetryStatusDtoSchema,
+    annotations: writeAnnotations({ idempotentHint: true }),
+    openApiOperations: ["PUT /api/v1/telemetry"],
+    handler: async (client2, input) => client2.updateTelemetry(input.enabled)
+  }),
+  defineTool({
+    name: "canonry_provider_settings_update",
+    title: "Update non-secret provider settings",
+    description: "Change model or quota for an already-configured provider, with explicit approval and settings.write. Preserves existing credentials. Does not accept API keys, base URLs, or credential rotation; use the secure operator setup flow for those.",
+    access: "write",
+    requiredScope: "settings.write",
+    tier: "setup",
+    inputSchema: z4.object({ provider: z4.string().min(1), model: z4.string().trim().min(1).optional(), quota: providerQuotaPolicySchema.partial().strict().optional() }).strict().refine((input) => input.model !== void 0 || input.quota !== void 0 && Object.keys(input.quota).length > 0, "Provide a model or at least one quota field"),
+    outputSchema: providerSummaryEntryDtoSchema,
+    annotations: writeAnnotations({ idempotentHint: true }),
+    openApiOperations: ["PUT /api/v1/settings/providers/{name}"],
+    handler: async (client2, { provider, ...request }) => client2.updateProvider(provider, request)
+  }),
+  defineTool({
+    name: "canonry_telemetry_get",
+    title: "Get telemetry status",
+    description: "Read the server telemetry status and effective reason. This safe settings read does not change telemetry collection.",
+    access: "read",
+    tier: "setup",
+    inputSchema: emptyInputSchema,
+    outputSchema: telemetryStatusDtoSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/telemetry"],
+    handler: (client2) => client2.getTelemetry()
+  }),
   defineTool({
     name: "canonry_google_connections_list",
     title: "List Google connections",
@@ -10828,6 +11057,17 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/projects/{name}/traffic/sources/{id}/reset"],
     handler: (client2, input) => client2.trafficReset(input.project, input.sourceId)
   }),
+  defineTool({
+    name: "canonry_snapshot",
+    title: "Generate a prospect snapshot",
+    description: "Generate a one-shot AI perception report for a company and domain without creating a project. Spends provider quota and fetches the site. Optional providers and providerMode constrain both answers and analysis; omitted selection uses all configured providers. Browser-only selection requires manual queries.",
+    access: "write",
+    tier: "discovery",
+    inputSchema: snapshotRequestInputSchema,
+    annotations: writeAnnotations({ idempotentHint: false, openWorldHint: true }),
+    openApiOperations: ["POST /api/v1/snapshot"],
+    handler: (client2, input) => client2.createSnapshot(input)
+  }),
   defineTool({
     name: "canonry_project_upsert",
     title: "Create or replace project",
@@ -12398,6 +12638,7 @@ import { ZodError } from "zod";
 function jsonToolResult(value) {
   const result = value === void 0 ? { ok: true } : value;
   return {
+    structuredContent: toStructuredContent(result),
     content: [
       {
         type: "text",
@@ -12407,16 +12648,23 @@ function jsonToolResult(value) {
   };
 }
 function errorToolResult(error) {
+  const envelope = toCanonryErrorEnvelope(error);
   return {
     isError: true,
+    structuredContent: envelope,
     content: [
       {
         type: "text",
-        text: JSON.stringify(toCanonryErrorEnvelope(error), null, 2)
+        text: JSON.stringify(envelope, null, 2)
       }
     ]
   };
 }
+function toStructuredContent(value) {
+  if (Array.isArray(value)) return { items: value };
+  if (value !== null && typeof value === "object") return value;
+  return { value };
+}
 async function withToolErrors(handler) {
   try {
     return jsonToolResult(await handler());
@@ -12585,8 +12833,8 @@ var CANONRY_MCP_TOOLKITS = [
   {
     name: "discovery",
     title: "Query discovery and research",
-    description: "Two linked workflows: find queries expands an ICP into a promotable tracked-query basket; research queries runs saved free-form experiments against one API model. Research never adds queries to tracking.",
-    whenToLoad: "Load when the operator wants to find ICP-led candidates for a tracked basket, or research specific free-form queries, model answers, sources, and location effects without changing tracking."
+    description: "Find queries expands an ICP into a promotable tracked-query basket; research queries runs saved free-form experiments against one API model. Research never adds queries to tracking. Prospect snapshots generate a company report without creating a project.",
+    whenToLoad: "Load for prospect snapshots, ICP-led candidates for a tracked basket, or research into free-form queries, model answers, sources, and location effects without changing tracking."
   }
 ];
 function isCanonryMcpToolkitName(value) {
@@ -12702,6 +12950,23 @@ var OPERATIONS_GUIDE = {
   "approvalRule": "Get explicit approval for the exact target, action, and bounded provider work before crossing a boundary. Existing approval covers only its stated scope; stop on refusal or ambiguous results.",
   "authority": "Guidance and tool visibility are not permission grants. Server-side roles, scopes, project boundaries, quotas, and approval receipts remain authoritative. Never bypass a refusal with different credentials or endpoints.",
   "workflows": {
+    "operations": {
+      "keywords": [
+        "operations",
+        "permissions",
+        "settings",
+        "telemetry",
+        "logs",
+        "configuration"
+      ],
+      "next": [
+        "canonry_key_self",
+        "canonry_settings_get",
+        "canonry_telemetry_get",
+        "canonry_logs_list"
+      ],
+      "guidance": "Inspect current credential and server state before proposing changes. Runtime logs require instance-wide logs.read; inspect retention, dropped, and captureErrors before drawing conclusions. File-backed hosts retain bounded redacted logs across restarts. Logs are separate from audit history. Respect a 403; never substitute credentials to bypass it. Settings writes require settings.write and explicit approval."
+    },
     "status": {
       "keywords": [
         "status",
@@ -12730,6 +12995,21 @@ var OPERATIONS_GUIDE = {
       ],
       "guidance": "Compare stored history in the same project, period, provider/model, location, and query-class scope. Separate observed changes from possible causes; propose any live verification for approval."
     },
+    "prospecting": {
+      "keywords": [
+        "prospect",
+        "prospects",
+        "prospecting",
+        "snapshot"
+      ],
+      "next": [
+        "canonry_settings_get"
+      ],
+      "actions": [
+        "canonry_snapshot"
+      ],
+      "guidance": "Inspect stored provider settings, then agree on the company, domain, providers, and queries. Snapshot generation spends quota and fetches the site; approval must cover that work. No project is required. Use the snapshot action only when offered by this connection; its absence does not grant permission to bypass access restrictions."
+    },
     "measurement": {
       "keywords": [
         "measurement",
@@ -12783,7 +13063,7 @@ var OPERATIONS_GUIDE = {
       "guidance": "Read the stored report for the selected project and period. 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`, `measurement`, `integrations`, `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`includeCatalog: true` additionally returns toolkit details when needed.\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**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**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. Keep sample sizes and ties visible. Preparing a report does not\nauthorize new measurement.\n\n## Authority and approval\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\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**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**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. Keep sample sizes and ties visible. Preparing a report does not\nauthorize new measurement.\n\n## Authority and approval\n\n### Agent operations\n\nUse `canonry_key_self` to inspect the current credential's scopes and project\nboundary without exposing its token. `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.\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\nadmin role for signed-in users. Project-scoped keys cannot use it, even with a\nproject filter. A `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
@@ -12793,11 +13073,14 @@ function operationsHelp(catalog, mode, intent = "", includeCatalog = false) {
   const workflow = workflows.find((name) => OPERATIONS_GUIDE.workflows[name].keywords.some((word) => words.has(word))) ?? "status";
   const route = OPERATIONS_GUIDE.workflows[workflow];
   const available = /* @__PURE__ */ new Set([...catalog.coreTools, ...catalog.toolkits.filter((t) => t.loaded).flatMap((t) => t.tools)]);
-  const next = route.next.filter((name) => available.has(name)).slice(0, 4);
-  if (next.length < 2 && available.has("canonry_project_overview") && !next.includes("canonry_project_overview")) {
+  const reads = route.next;
+  const requestedActions = "actions" in route ? route.actions : [];
+  const next = reads.filter((name) => available.has(name)).slice(0, 4);
+  const actions = requestedActions.filter((name) => available.has(name));
+  if (reads.includes("canonry_projects_list") && next.length < 2 && available.has("canonry_project_overview") && !next.includes("canonry_project_overview")) {
     next.push("canonry_project_overview");
   }
-  const wanted = route.next;
+  const wanted = [...reads, ...requestedActions];
   const loadToolkits = mode === "stdio-progressive" ? catalog.toolkits.filter((t) => !t.loaded && t.tools.some((name) => wanted.includes(name))).map((t) => t.name) : [];
   return {
     guideVersion: OPERATIONS_GUIDE.guideVersion,
@@ -12805,6 +13088,7 @@ function operationsHelp(catalog, mode, intent = "", includeCatalog = false) {
     scope: catalog.scope,
     workflow,
     next,
+    ...actions.length ? { actions } : {},
     workflows,
     guidance: route.guidance,
     approvalBoundary: OPERATIONS_GUIDE.approvalBoundary,
@@ -12822,7 +13106,7 @@ function createCanonryMcpServer(options = {}) {
 }
 var SERVER_INSTRUCTIONS = OPERATIONS_GUIDE.initialize;
 function createCanonryMcpServerWithCatalog(options = {}) {
-  const clientFactory = options.clientFactory ?? createApiClient;
+  const clientFactory = options.clientFactory ?? (() => createApiClient({ clientName: "canonry-mcp" }));
   const client2 = clientFactory();
   const scope = options.scope ?? "all";
   const server = new McpServer({
@@ -12842,6 +13126,7 @@ function createCanonryMcpServerWithCatalog(options = {}) {
         title: tool.title,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
         annotations: tool.annotations
       },
       async (input) => withToolErrors(async () => {
@@ -12867,7 +13152,7 @@ var loadToolkitInputSchema = z5.object({
   name: z5.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
 });
 var helpInputSchema = z5.object({
-  intent: z5.string().max(200).optional().describe("Workflow (status, diagnose, measurement, integrations, reports) or a short task description."),
+  intent: z5.string().max(200).optional().describe("Workflow (status, diagnose, prospecting, measurement, integrations, reports) or a short task description."),
   includeCatalog: z5.boolean().optional().describe("Include full toolkit details. Omit for a compact, actionable route.")
 });
 function registerMetaTools(server, catalog, opts) {
@@ -12875,7 +13160,7 @@ function registerMetaTools(server, catalog, opts) {
     "canonry_help",
     {
       title: "Guide a Canonry workflow",
-      description: "Start here: route an intent to available stored-evidence tools, workflow guidance, and approval boundaries. No provider calls or installation required. Optionally include full toolkit details.",
+      description: "Start here: route an intent to available stored-evidence tools, separately listed actions requiring approval, and workflow guidance. No provider calls or installation required. Optionally include full toolkit details.",
       inputSchema: helpInputSchema.shape,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },