@ainyc/canonry 4.193.2 → 4.195.0

package/dist/cli.js

@@ -17,6 +17,7 @@ import {
   formatAuditFactorScore,
   getCloudflareTrafficConnectionBySourceId,
   getOrCreateAnonymousId,
+  getTelemetryStatus,
   isAeroToolProfile,
   isFirstRun,
   isLoopbackBindHost,
@@ -28,11 +29,11 @@ import {
   trackCliCommandFinished,
   trackEvent,
   waitForServerRuntimeStartup
-} from "./chunk-KJJMIWVD.js";
+} from "./chunk-H3RVNMOO.js";
 import {
   autoSyncSkills,
   formatAutoSyncNotice
-} from "./chunk-LIMWYFHS.js";
+} from "./chunk-LJKAB4CX.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -58,7 +59,7 @@ import {
   saveConfigPatch,
   systemError,
   usageError
-} from "./chunk-24JHDZ7H.js";
+} from "./chunk-B2XM6AQ6.js";
 import {
   CLOUDFLARE_WORKER_BINDINGS,
   CLOUDFLARE_WORKER_GENERATED_MARKER,
@@ -72,7 +73,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-Q5KGSOT7.js";
+} from "./chunk-UMU3IBXM.js";
 import {
   AdsDeliverySnapshotStatuses,
   AdsHistoricalCampaignRollupStatuses,
@@ -122,6 +123,7 @@ import {
   formatRatio,
   formatRunErrorOneLine,
   googleAdsMetricsWindowSchema,
+  logQuerySchema,
   measurementChangesQuerySchema,
   measurementDataQualityQuerySchema,
   measurementDiscoveryRequestSchema,
@@ -138,6 +140,7 @@ import {
   measurementQueryTemplateUpsertRequestSchema,
   measurementQuestionResultQuerySchema,
   normalizeProjectAliases,
+  normalizeTelemetryStatus,
   notificationEventSchema,
   queryTrackingCommitRequestSchema,
   queryTrackingPreviewRequestSchema,
@@ -146,9 +149,10 @@ import {
   resultsClearRequestSchema,
   shareOfVoiceLabel,
   shareOfVoiceReason,
+  snapshotProviderModeSchema,
   visibilityReportRequestSchema,
   winnabilityClassSchema
-} from "./chunk-5CXUV3ZX.js";
+} from "./chunk-3WODA4JF.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -10931,8 +10935,12 @@ var EVENT_DESCRIPTIONS = {
   "health.degraded": "A scheduled health check found the measurement itself degraded (sent on change, not every pass)",
   "health.recovered": "A previously degraded health check is passing again"
 };
-function listEvents(format) {
-  const events = notificationEventSchema.options;
+function listEvents(format, target = "local") {
+  if (target === "server") return getClient16().listNotificationEvents().then((events) => printEvents(events, format));
+  if (target !== "local") throw usageError("--target must be local or server");
+  printEvents(notificationEventSchema.options, format);
+}
+function printEvents(events, format) {
   const catalog = events.map((e) => ({ event: e, description: EVENT_DESCRIPTIONS[e] ?? "" }));
   if (format === "json") {
     console.log(JSON.stringify(catalog, null, 2));
@@ -10958,9 +10966,10 @@ function printNotification(n) {
 var NOTIFY_CLI_COMMANDS = [
   {
     path: ["notify", "events"],
-    usage: "canonry notify events [--format json]",
-    run: (input) => {
-      listEvents(input.format);
+    usage: "canonry notify events [--target local|server] [--format json|jsonl]",
+    options: { target: stringOption() },
+    run: async (input) => {
+      await listEvents(input.format, getString(input.values, "target"));
     }
   },
   {
@@ -11500,6 +11509,7 @@ async function showHistory(project, format, opts = {}) {
       if (entry.diff != null) console.log(`    diff: ${JSON.stringify(entry.diff)}`);
     }
   } catch (err) {
+    if (err instanceof CliError) throw err;
     const message = describeError(err);
     throw new CliError({
       code: "HISTORY_FETCH_FAILED",
@@ -11596,6 +11606,21 @@ function parseResultsExportFormat(value) {
 Usage: ${RESULTS_EXPORT_USAGE}`);
 }
 var RESULTS_CLEAR_USAGE = "canonry results clear <project> [--run <id> ...] [--research-run <id> ...] [--confirm] [--format json|jsonl]";
+function parseHistoryPageOption(input, key, usage) {
+  const value = getString(input.values, key);
+  if (value === void 0) return void 0;
+  if (!/^\d+$/.test(value)) {
+    throw usageError(`Error: --${key} must be a ${key === "limit" ? "whole number from 1 to 500" : "nonnegative integer"}
+Usage: ${usage}`);
+  }
+  const parsed = Number(value);
+  const valid = Number.isSafeInteger(parsed) && (key === "limit" ? parsed >= 1 && parsed <= 500 : parsed >= 0);
+  if (!valid) {
+    throw usageError(`Error: --${key} must be a ${key === "limit" ? "whole number from 1 to 500" : "nonnegative integer"}
+Usage: ${usage}`);
+  }
+  return parsed;
+}
 var OPERATOR_CLI_COMMANDS = [
   {
     path: ["results", "clear"],
@@ -11648,20 +11673,22 @@ var OPERATOR_CLI_COMMANDS = [
   },
   {
     path: ["history"],
-    usage: "canonry history <project> [--limit <n>] [--since <ISO>] [--action <action>] [--actor <actor>] [--entity-type <type>] [--format json|jsonl]\n       canonry history --all [same filters]",
+    usage: "canonry history <project> [--limit <1..500>] [--offset <n>] [--since <ISO>] [--action <action>] [--actor <actor>] [--entity-type <type>] [--format json|jsonl]\n       canonry history --all [same filters]",
     options: {
       all: { type: "boolean", default: false },
       limit: stringOption(),
+      offset: stringOption(),
       since: stringOption(),
       action: stringOption(),
       actor: stringOption(),
       "entity-type": stringOption()
     },
     run: async (input) => {
-      const usage = "canonry history <project> [--limit <n>] [--since <ISO>] [--action <action>] [--actor <actor>] [--entity-type <type>] [--format json|jsonl]\n       canonry history --all [same filters]";
+      const usage = "canonry history <project> [--limit <1..500>] [--offset <n>] [--since <ISO>] [--action <action>] [--actor <actor>] [--entity-type <type>] [--format json|jsonl]\n       canonry history --all [same filters]";
       const project = getBoolean(input.values, "all") ? void 0 : requireProject(input, "history", usage);
       await showHistory(project, input.format, {
-        limit: parseIntegerOption(input, "limit", { command: "history", usage, message: "--limit must be an integer" }),
+        limit: parseHistoryPageOption(input, "limit", usage),
+        offset: parseHistoryPageOption(input, "offset", usage),
         since: getString(input.values, "since"),
         action: getString(input.values, "action"),
         actor: getString(input.values, "actor"),
@@ -12799,6 +12826,19 @@ var RUN_CLI_COMMANDS = [
 ];
 
 // src/commands/schedule.ts
+async function listSchedules(project, format) {
+  const schedules = await getClient24().listSchedules(project);
+  if (format === "jsonl") {
+    emitJsonl(schedules);
+    return;
+  }
+  if (format === "json") {
+    console.log(JSON.stringify(schedules, null, 2));
+    return;
+  }
+  if (!schedules.length) console.log(`No schedules configured for "${project}"`);
+  for (const schedule of schedules) printSchedule(schedule);
+}
 function getClient24() {
   return createApiClient();
 }
@@ -12903,6 +12943,13 @@ function printSchedule(s) {
 
 // src/cli-commands/schedule.ts
 var SCHEDULE_CLI_COMMANDS = [
+  {
+    path: ["schedule", "list"],
+    usage: "canonry schedule list <project> [--format json|jsonl]",
+    run: async (input) => {
+      await listSchedules(requireProject(input, "schedule.list", "canonry schedule list <project>"), input.format);
+    }
+  },
   {
     path: ["schedule", "set"],
     usage: "canonry schedule set <project> (--preset <preset> | --cron <expr> | --every-days <n> --start-date <YYYY-MM-DD> --at <HH:mm>) [--kind answer-visibility|traffic-sync|gbp-sync|data-refresh|backlinks-sync] [--source <id>] [--timezone <tz>] [--provider <name>...] [--format json]",
@@ -12991,12 +13038,12 @@ var SCHEDULE_CLI_COMMANDS = [
   },
   {
     path: ["schedule"],
-    usage: "canonry schedule <set|show|enable|disable|remove> <project>",
+    usage: "canonry schedule <list|set|show|enable|disable|remove> <project>",
     run: async (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "schedule",
-        usage: "canonry schedule <set|show|enable|disable|remove> <project>",
-        available: ["set", "show", "enable", "disable", "remove"]
+        usage: "canonry schedule <list|set|show|enable|disable|remove> <project>",
+        available: ["list", "set", "show", "enable", "disable", "remove"]
       });
     }
   }
@@ -13024,15 +13071,9 @@ async function setProvider(name, opts) {
 }
 async function showSettings(format) {
   const client = getClient25();
-  const config = loadConfig();
   const settings = await client.getSettings();
   if (isMachineFormat(format)) {
-    console.log(JSON.stringify({
-      ...settings,
-      google: {
-        configured: Boolean(config.google?.clientId && config.google?.clientSecret)
-      }
-    }, null, 2));
+    console.log(JSON.stringify(settings, null, 2));
     return;
   }
   console.log("Provider settings:\n");
@@ -13048,9 +13089,21 @@ async function showSettings(format) {
     }
   }
   console.log("\nGoogle OAuth:\n");
-  console.log(`  ${config.google?.clientId && config.google?.clientSecret ? "configured" : "not configured"}`);
+  console.log(`  ${settings.google.configured ? "configured" : "not configured"}`);
 }
-function setGoogleAuth(opts) {
+async function setGoogleAuth(opts) {
+  if (opts.target === "server") {
+    const result = await getClient25().updateGoogleSettings({
+      clientId: opts.clientId,
+      clientSecret: opts.clientSecret
+    });
+    if (isMachineFormat(opts.format)) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log("Google OAuth credentials updated on the server.");
+    return;
+  }
   const config = loadConfig();
   setGoogleAuthConfig(config, {
     clientId: opts.clientId,
@@ -13090,8 +13143,25 @@ var SETTINGS_CLI_COMMANDS = [
       });
       const apiKey = getString(input.values, "api-key");
       const baseUrl = getString(input.values, "base-url");
+      const model = getString(input.values, "model");
+      const maxConcurrency = parseIntegerOption(input, "max-concurrent", {
+        command: "settings.provider",
+        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
+        message: "--max-concurrent must be an integer"
+      });
+      const maxRequestsPerMinute = parseIntegerOption(input, "max-per-minute", {
+        command: "settings.provider",
+        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
+        message: "--max-per-minute must be an integer"
+      });
+      const maxRequestsPerDay = parseIntegerOption(input, "max-per-day", {
+        command: "settings.provider",
+        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
+        message: "--max-per-day must be an integer"
+      });
+      const hasNonCredentialEdit = Boolean(model) || maxConcurrency != null || maxRequestsPerMinute != null || maxRequestsPerDay != null;
       if (name === "local") {
-        if (!baseUrl) {
+        if (!baseUrl && !hasNonCredentialEdit) {
           throw usageError(
             "Error: --base-url is required for the local provider\nUsage: canonry settings provider local --base-url <url> [--api-key <key>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
             {
@@ -13104,7 +13174,7 @@ var SETTINGS_CLI_COMMANDS = [
             }
           );
         }
-      } else if (!apiKey) {
+      } else if (!apiKey && !baseUrl && !hasNonCredentialEdit) {
         throw usageError(
           `Error: --api-key is required
 Usage: canonry settings provider ${name} --api-key <key> [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]`,
@@ -13118,21 +13188,6 @@ Usage: canonry settings provider ${name} --api-key <key> [--model <model>] [--ma
           }
         );
       }
-      const maxConcurrency = parseIntegerOption(input, "max-concurrent", {
-        command: "settings.provider",
-        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
-        message: "--max-concurrent must be an integer"
-      });
-      const maxRequestsPerMinute = parseIntegerOption(input, "max-per-minute", {
-        command: "settings.provider",
-        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
-        message: "--max-per-minute must be an integer"
-      });
-      const maxRequestsPerDay = parseIntegerOption(input, "max-per-day", {
-        command: "settings.provider",
-        usage: "canonry settings provider <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--max-concurrent <n>] [--max-per-minute <n>] [--max-per-day <n>] [--format json]",
-        message: "--max-per-day must be an integer"
-      });
       const quota = maxConcurrency != null || maxRequestsPerMinute != null || maxRequestsPerDay != null ? {
         ...maxConcurrency != null ? { maxConcurrency } : {},
         ...maxRequestsPerMinute != null ? { maxRequestsPerMinute } : {},
@@ -13141,7 +13196,7 @@ Usage: canonry settings provider ${name} --api-key <key> [--model <model>] [--ma
       await setProvider(name, {
         apiKey,
         baseUrl,
-        model: getString(input.values, "model"),
+        model,
         quota,
         format: input.format
       });
@@ -13149,10 +13204,11 @@ Usage: canonry settings provider ${name} --api-key <key> [--model <model>] [--ma
   },
   {
     path: ["settings", "google"],
-    usage: "canonry settings google --client-id <id> --client-secret <secret> [--format json]",
+    usage: "canonry settings google --client-id <id> --client-secret <secret> [--target local|server] [--format json]",
     options: {
       "client-id": stringOption(),
-      "client-secret": stringOption()
+      "client-secret": stringOption(),
+      target: stringOption()
     },
     run: async (input) => {
       const clientId = getString(input.values, "client-id");
@@ -13170,9 +13226,25 @@ Usage: canonry settings provider ${name} --api-key <key> [--model <model>] [--ma
           }
         );
       }
-      setGoogleAuth({
+      const target = getString(input.values, "target") ?? "local";
+      if (target !== "local" && target !== "server") {
+        throw usageError(
+          "Error: invalid --target; must be local or server\nUsage: canonry settings google --client-id <id> --client-secret <secret> [--target local|server] [--format json]",
+          {
+            message: "invalid --target; must be local or server",
+            details: {
+              command: "settings.google",
+              usage: "canonry settings google --client-id <id> --client-secret <secret> [--target local|server] [--format json]",
+              option: "target",
+              value: target
+            }
+          }
+        );
+      }
+      await setGoogleAuth({
         clientId,
         clientSecret,
+        target,
         format: input.format
       });
     }
@@ -13588,6 +13660,8 @@ async function createSnapshotReport(companyName, opts) {
   const report = await client.createSnapshot({
     companyName,
     domain: opts.domain,
+    ...opts.providers !== void 0 ? { providers: opts.providers } : {},
+    ...opts.providerMode !== void 0 ? { providerMode: opts.providerMode } : {},
     ...opts.queries && opts.queries.length > 0 ? { queries: opts.queries } : {},
     ...opts.competitors && opts.competitors.length > 0 ? { competitors: opts.competitors } : {}
   });
@@ -13754,6 +13828,7 @@ function formatProviderLine(result) {
 }
 
 // src/cli-commands/snapshot.ts
+var SNAPSHOT_USAGE = 'canonry snapshot <company-name> --domain <domain> [--provider <name>...] [--provider-mode all|api|browser] [--queries "a,b"] [--phrases "a,b" (legacy alias)] [--competitors "x,y"] [--md] [--output <path>] [--pdf] [--format table|json]';
 function parseCsvOption(value) {
   if (!value) return void 0;
   const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
@@ -13762,9 +13837,11 @@ function parseCsvOption(value) {
 var SNAPSHOT_CLI_COMMANDS = [
   {
     path: ["snapshot"],
-    usage: 'canonry snapshot <company-name> --domain <domain> [--queries "a,b"] [--phrases "a,b" (legacy alias)] [--competitors "x,y"] [--md] [--output <path>] [--pdf] [--format table|json]',
+    usage: SNAPSHOT_USAGE,
     options: {
       domain: stringOption(),
+      provider: multiStringOption(),
+      "provider-mode": stringOption(),
       queries: stringOption(),
       phrases: stringOption(),
       competitors: stringOption(),
@@ -13773,7 +13850,7 @@ var SNAPSHOT_CLI_COMMANDS = [
       output: stringOption()
     },
     run: async (input) => {
-      const usage = 'canonry snapshot <company-name> --domain <domain> [--queries "a,b"] [--phrases "a,b" (legacy alias)] [--competitors "x,y"] [--md] [--output <path>] [--pdf] [--format table|json]';
+      const usage = SNAPSHOT_USAGE;
       const companyName = requirePositional(input, 0, {
         command: "snapshot",
         usage,
@@ -13784,12 +13861,23 @@ var SNAPSHOT_CLI_COMMANDS = [
         usage,
         message: "--domain is required"
       });
+      const rawMode = getString(input.values, "provider-mode");
+      const mode = snapshotProviderModeSchema.optional().safeParse(rawMode);
+      if (!mode.success) {
+        throw usageError("Error: --provider-mode must be all, api, or browser", {
+          details: { command: "snapshot", usage }
+        });
+      }
+      const providers = getStringArray(input.values, "provider")?.map((name) => name.trim());
+      if (providers?.some((name) => !name)) throw usageError("Error: --provider must not be blank");
       const outputPath = getString(input.values, "output");
       const explicitMd = getBoolean(input.values, "md");
       const wantsPdf = getBoolean(input.values, "pdf");
       const wantsMd = explicitMd || !!outputPath && !wantsPdf;
       await createSnapshotReport(companyName, {
         domain,
+        providers: providers === void 0 ? void 0 : [...new Set(providers)],
+        providerMode: mode.data,
         queries: parseCsvOption(getString(input.values, "queries") ?? getString(input.values, "phrases")),
         competitors: parseCsvOption(getString(input.values, "competitors")),
         md: wantsMd,
@@ -15645,131 +15733,117 @@ Canonry server running at ${url}`);
 }
 
 // src/commands/telemetry.ts
-function telemetryCommand(subcommand, format = "text") {
+function telemetryTarget(value) {
+  if (value === void 0 || value === "local") return "local";
+  if (value === "server") return "server";
+  throw usageError('Error: --target must be "local" or "server"', {
+    message: '--target must be "local" or "server"',
+    details: { command: "telemetry", target: value, allowed: ["local", "server"] }
+  });
+}
+function emitStatus(payload, format, mutation = false) {
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const targetSuffix = payload.target === "server" ? " (server)" : "";
+  if (mutation && payload.enabled === payload.configuredEnabled) {
+    console.log(`Telemetry${targetSuffix} ${payload.enabled ? "enabled." : "disabled. No data will be sent."}`);
+  } else if (payload.reason === "CANONRY_TELEMETRY_DISABLED") {
+    console.log(`Telemetry${targetSuffix}: disabled (CANONRY_TELEMETRY_DISABLED=1)`);
+  } else if (payload.reason === "DO_NOT_TRACK") {
+    console.log(`Telemetry${targetSuffix}: disabled (DO_NOT_TRACK=1)`);
+  } else if (payload.reason === "CI") {
+    console.log(`Telemetry${targetSuffix}: disabled (CI environment detected)`);
+  } else if (payload.reason === "NO_CONFIG") {
+    console.log(`Telemetry${targetSuffix}: enabled (no config yet \u2014 run "canonry bootstrap" first)`);
+  } else {
+    console.log(`Telemetry${targetSuffix}: ${payload.enabled ? "enabled" : "disabled"}`);
+  }
+  if (payload.enabled !== payload.configuredEnabled) {
+    console.log(`Configured telemetry: ${payload.configuredEnabled ? "enabled" : "disabled"}; effective state overridden by ${payload.reason}.`);
+  }
+  if (payload.anonymousId) console.log(`Anonymous ID: ${payload.anonymousId}`);
+}
+function localStatus() {
+  const status = getTelemetryStatus();
+  return {
+    ...status,
+    ...status.anonymousId ? { anonymousIdMasked: status.anonymousId } : {},
+    ...configExists() ? { configPath: getConfigPath() } : {}
+  };
+}
+function requireLocalConfig(command) {
+  if (!configExists()) {
+    throw new CliError({
+      code: "CONFIG_REQUIRED",
+      message: 'No config found. Run "canonry bootstrap" first.',
+      displayMessage: 'No config found. Run "canonry bootstrap" first.',
+      details: { command }
+    });
+  }
+}
+async function serverTelemetryCommand(subcommand, format) {
+  const client = createApiClient();
+  const response = subcommand === "status" ? await client.getTelemetry() : await client.updateTelemetry(subcommand === "enable");
+  emitStatus(normalizeTelemetryStatus(response), format, subcommand !== "status");
+}
+function telemetryCommand(subcommand, format = "text", targetValue) {
   const available = ["status", "enable", "disable"];
+  const target = telemetryTarget(targetValue);
+  if (target === "server") {
+    if (subcommand === "status" || subcommand === "enable" || subcommand === "disable") {
+      return serverTelemetryCommand(subcommand, format);
+    }
+  }
   switch (subcommand) {
     case "status": {
-      const payload = {
-        enabled: true
-      };
-      if (process.env.CANONRY_TELEMETRY_DISABLED === "1") {
-        payload.enabled = false;
-        payload.reason = "CANONRY_TELEMETRY_DISABLED";
-        if (isMachineFormat(format)) {
-          console.log(JSON.stringify(payload, null, 2));
-          return;
-        }
-        console.log("Telemetry: disabled (CANONRY_TELEMETRY_DISABLED=1)");
-        return;
-      }
-      if (process.env.DO_NOT_TRACK === "1") {
-        payload.enabled = false;
-        payload.reason = "DO_NOT_TRACK";
-        if (isMachineFormat(format)) {
-          console.log(JSON.stringify(payload, null, 2));
-          return;
-        }
-        console.log("Telemetry: disabled (DO_NOT_TRACK=1)");
-        return;
-      }
-      if (process.env.CI) {
-        payload.enabled = false;
-        payload.reason = "CI";
-        if (isMachineFormat(format)) {
-          console.log(JSON.stringify(payload, null, 2));
-          return;
-        }
-        console.log("Telemetry: disabled (CI environment detected)");
-        return;
-      }
-      if (!configExists()) {
-        payload.reason = "NO_CONFIG";
-        if (isMachineFormat(format)) {
-          console.log(JSON.stringify(payload, null, 2));
-          return;
-        }
-        console.log('Telemetry: enabled (no config yet \u2014 run "canonry bootstrap" first)');
-        return;
-      }
-      const config = loadConfig();
-      payload.enabled = config.telemetry !== false;
-      payload.configPath = getConfigPath();
-      if (config.anonymousId) {
-        payload.anonymousIdMasked = config.anonymousId.slice(0, 8) + "...";
-      }
-      if (isMachineFormat(format)) {
-        console.log(JSON.stringify(payload, null, 2));
-        return;
-      }
-      const enabled = payload.enabled;
-      console.log(`Telemetry: ${enabled ? "enabled" : "disabled"}`);
-      if (config.anonymousId) {
-        const masked = config.anonymousId.slice(0, 8) + "...";
-        console.log(`Anonymous ID: ${masked}`);
-      }
+      emitStatus(localStatus(), format);
       break;
     }
     case "enable": {
-      if (!configExists()) {
-        throw new CliError({
-          code: "CONFIG_REQUIRED",
-          message: 'No config found. Run "canonry bootstrap" first.',
-          displayMessage: 'No config found. Run "canonry bootstrap" first.',
-          details: {
-            command: "telemetry.enable"
-          }
-        });
-      }
+      requireLocalConfig("telemetry.enable");
       const config = loadConfig();
       config.telemetry = true;
       saveConfigPatch(config);
-      if (isMachineFormat(format)) {
-        console.log(JSON.stringify({
-          enabled: true,
-          configPath: getConfigPath()
-        }, null, 2));
-        return;
-      }
-      console.log("Telemetry enabled.");
+      emitStatus(localStatus(), format, true);
       break;
     }
     case "disable": {
-      if (!configExists()) {
-        throw new CliError({
-          code: "CONFIG_REQUIRED",
-          message: 'No config found. Run "canonry bootstrap" first.',
-          displayMessage: 'No config found. Run "canonry bootstrap" first.',
-          details: {
-            command: "telemetry.disable"
-          }
-        });
-      }
+      requireLocalConfig("telemetry.disable");
       const config = loadConfig();
       config.telemetry = false;
       saveConfigPatch(config);
-      if (isMachineFormat(format)) {
-        console.log(JSON.stringify({
-          enabled: false,
-          configPath: getConfigPath()
-        }, null, 2));
-        return;
-      }
-      console.log("Telemetry disabled. No data will be sent.");
+      emitStatus(localStatus(), format, true);
       break;
     }
     default:
       throw usageError(`Error: unknown telemetry subcommand: ${subcommand ?? "(none)"}
-Usage: canonry telemetry <status|enable|disable> [--format json]`, {
+Usage: canonry telemetry <status|enable|disable> [--target local|server] [--format json]`, {
         message: `unknown telemetry subcommand: ${subcommand ?? "(none)"}`,
         details: {
           command: "telemetry",
-          usage: "canonry telemetry <status|enable|disable> [--format json]",
+          usage: "canonry telemetry <status|enable|disable> [--target local|server] [--format json]",
           available
         }
       });
   }
 }
 
+// src/commands/logs.ts
+async function showOperationalLogs(query, format) {
+  const parsed = logQuerySchema.safeParse(query);
+  if (!parsed.success) throw usageError("Invalid logs filters", { details: { issues: parsed.error.issues } });
+  const result = await createApiClient().listOperationalLogs(parsed.data);
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Runtime logs (${result.retention}; ${result.entries.length} entries; ${result.dropped} evicted; ${result.captureErrors ?? 0} capture errors). Separate from audit history.`);
+  for (const entry of result.entries) console.log(`${entry.ts} ${entry.level} [${entry.module}] ${entry.action}${entry.message ? ` ${entry.message}` : ""} ${JSON.stringify(entry.context)}`);
+  if (result.nextCursor) console.log(`Next cursor: ${result.nextCursor}`);
+}
+
 // src/cli-commands/system.ts
 function applyServerEnv(values) {
   const port = typeof values.port === "string" ? values.port : void 0;
@@ -15788,6 +15862,25 @@ function applyServerEnv(values) {
     process.env.CANONRY_EMBED_PROJECT_TABS = embedProjectTabs.join(",");
 }
 var SYSTEM_CLI_COMMANDS = [
+  {
+    path: ["logs"],
+    usage: "canonry logs [--level trace|debug|info|warn|error|fatal] [--module <name>] [--run-id <id>] [--project-id <id>] [--actor <user:id|api-key:id>] [--request-id <id>] [--since <ISO>] [--until <ISO>] [--limit <1..200>] [--cursor <cursor>] [--format json|jsonl]",
+    help: "Read bounded, redacted runtime logs. Inspect retention and captureErrors for coverage. Requires an instance-wide logs.read grant; project filters do not grant access. Use history for audit events.",
+    options: { level: stringOption(), module: stringOption(), "run-id": stringOption(), "project-id": stringOption(), actor: stringOption(), "request-id": stringOption(), since: stringOption(), until: stringOption(), limit: stringOption(), cursor: stringOption() },
+    allowPositionals: false,
+    run: async (input) => showOperationalLogs({
+      level: getString(input.values, "level"),
+      module: getString(input.values, "module"),
+      runId: getString(input.values, "run-id"),
+      projectId: getString(input.values, "project-id"),
+      actor: getString(input.values, "actor"),
+      requestId: getString(input.values, "request-id"),
+      since: getString(input.values, "since"),
+      until: getString(input.values, "until"),
+      limit: getString(input.values, "limit"),
+      cursor: getString(input.values, "cursor")
+    }, input.format)
+  },
   {
     path: ["init"],
     usage: "canonry init [--force] [--gemini-key <key>] [--openai-key <key>] [--claude-key <key>] [--perplexity-key <key>] [--local-url <url>] [--local-model <name>] [--local-key <key>] [--google-client-id <id>] [--google-client-secret <key>] [--skip-skills] [--skip-mcp] [--skills-dir <path>] [--format json]",
@@ -15896,35 +15989,38 @@ var SYSTEM_CLI_COMMANDS = [
   },
   {
     path: ["telemetry", "status"],
-    usage: "canonry telemetry status [--format json]",
+    usage: "canonry telemetry status [--target local|server] [--format json]",
+    options: { target: stringOption() },
     allowPositionals: false,
-    run: (input) => {
-      telemetryCommand("status", input.format);
+    run: async (input) => {
+      await telemetryCommand("status", input.format, getString(input.values, "target"));
     }
   },
   {
     path: ["telemetry", "enable"],
-    usage: "canonry telemetry enable [--format json]",
+    usage: "canonry telemetry enable [--target local|server] [--format json]",
+    options: { target: stringOption() },
     allowPositionals: false,
-    run: (input) => {
-      telemetryCommand("enable", input.format);
+    run: async (input) => {
+      await telemetryCommand("enable", input.format, getString(input.values, "target"));
     }
   },
   {
     path: ["telemetry", "disable"],
-    usage: "canonry telemetry disable [--format json]",
+    usage: "canonry telemetry disable [--target local|server] [--format json]",
+    options: { target: stringOption() },
     allowPositionals: false,
-    run: (input) => {
-      telemetryCommand("disable", input.format);
+    run: async (input) => {
+      await telemetryCommand("disable", input.format, getString(input.values, "target"));
     }
   },
   {
     path: ["telemetry"],
-    usage: "canonry telemetry <status|enable|disable> [--format json]",
+    usage: "canonry telemetry <status|enable|disable> [--target local|server] [--format json]",
     run: (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "telemetry",
-        usage: "canonry telemetry <status|enable|disable> [--format json]",
+        usage: "canonry telemetry <status|enable|disable> [--target local|server] [--format json]",
         available: ["status", "enable", "disable"]
       });
     }