@ainyc/canonry 1.38.0 → 1.39.1

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node --import tsx
 import {
+  IntelligenceService,
   apiKeys,
   configExists,
   createClient,
@@ -26,7 +27,7 @@ import {
   setGoogleAuthConfig,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-SAVCFB5B.js";
+} from "./chunk-2MJBBEGP.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -125,7 +126,49 @@ function withFormatOption(options) {
 function toFormat(value, fallbackFormat) {
   return value === "json" ? "json" : fallbackFormat;
 }
+function printGroupHelp(group, specs) {
+  const parentSpec = specs.find((s) => s.path.length === 1 && s.path[0] === group);
+  const groupSpecs = specs.filter((s) => s.path[0] === group && s.path.length > 1).sort((a, b) => a.path.join(" ").localeCompare(b.path.join(" ")));
+  if (groupSpecs.length === 0) return;
+  console.log(`
+Usage:  canonry ${group} <command> [options]
+`);
+  if (parentSpec) {
+    console.log(`  ${parentSpec.usage}
+`);
+  }
+  console.log("Subcommands:");
+  for (const spec of groupSpecs) {
+    console.log(`  ${spec.usage}`);
+  }
+  console.log();
+}
 async function dispatchRegisteredCommand(args, fallbackFormat, specs) {
+  if (args.length >= 1 && (args.includes("--help") || args.includes("-h"))) {
+    const argsWithoutHelp = args.filter((a) => a !== "--help" && a !== "-h");
+    const exactMatch = [...specs].sort((a, b) => b.path.length - a.path.length).find((candidate) => matchesPath(argsWithoutHelp, candidate.path));
+    if (exactMatch && exactMatch.path.length > 1) {
+      console.log(`
+Usage:  ${exactMatch.usage}
+`);
+      return true;
+    }
+    const group = argsWithoutHelp[0];
+    if (group) {
+      const groupSpecs = specs.filter((s) => s.path[0] === group && s.path.length > 1);
+      if (groupSpecs.length > 0) {
+        printGroupHelp(group, specs);
+        return true;
+      }
+      const single = specs.find((s) => s.path.length === 1 && s.path[0] === group);
+      if (single) {
+        console.log(`
+Usage:  ${single.usage}
+`);
+        return true;
+      }
+    }
+  }
   const spec = [...specs].sort((a, b) => b.path.length - a.path.length).find((candidate) => matchesPath(args, candidate.path));
   if (!spec) return false;
   const remainingArgs = args.slice(spec.path.length);
@@ -227,6 +270,41 @@ async function backfillAnswerVisibilityCommand(opts) {
   console.log(`  Updated:  ${updated}`);
   console.log(`  Visible:  ${visible}`);
 }
+async function backfillInsightsCommand(project, opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const service = new IntelligenceService(db);
+  const isJson = opts?.format === "json";
+  if (!isJson) {
+    process.stderr.write(`Backfilling insights for "${project}"...
+`);
+  }
+  const result = service.backfill(project, {
+    fromRunId: opts?.fromRun,
+    toRunId: opts?.toRun
+  }, (info) => {
+    if (!isJson) {
+      process.stderr.write(`  [${info.index}/${info.total}] ${info.runId} \u2014 ${info.insights} insights
+`);
+    }
+  });
+  const output = {
+    project,
+    processed: result.processed,
+    skipped: result.skipped,
+    totalInsights: result.totalInsights
+  };
+  if (isJson) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(`
+Backfill complete.`);
+  console.log(`  Processed: ${result.processed}`);
+  console.log(`  Skipped:   ${result.skipped}`);
+  console.log(`  Insights:  ${result.totalInsights}`);
+}
 
 // src/cli-command-helpers.ts
 function getString(values, key) {
@@ -324,14 +402,31 @@ var BACKFILL_CLI_COMMANDS = [
       });
     }
   },
+  {
+    path: ["backfill", "insights"],
+    usage: "canonry backfill insights <project> [--from-run <id>] [--to-run <id>] [--format json]",
+    options: {
+      "from-run": stringOption(),
+      "to-run": stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry backfill insights <project> [--from-run <id>] [--to-run <id>] [--format json]";
+      const project = requireProject(input, "backfill insights", usage);
+      await backfillInsightsCommand(project, {
+        fromRun: getString(input.values, "from-run"),
+        toRun: getString(input.values, "to-run"),
+        format: input.format
+      });
+    }
+  },
   {
     path: ["backfill"],
-    usage: "canonry backfill <answer-visibility> [--project <name>] [--format json]",
+    usage: "canonry backfill <answer-visibility|insights> [options]",
     run: async (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "backfill",
-        usage: "canonry backfill <answer-visibility> [--project <name>] [--format json]",
-        available: ["answer-visibility"]
+        usage: "canonry backfill <answer-visibility|insights> [options]",
+        available: ["answer-visibility", "insights"]
       });
     }
   }
@@ -754,6 +849,24 @@ var ApiClient = class {
   async wordpressStagingPush(project) {
     return this.request("POST", `/projects/${encodeURIComponent(project)}/wordpress/staging/push`);
   }
+  // ── Intelligence ──────────────────────────────────────────────────────
+  async getInsights(project, opts) {
+    const params = new URLSearchParams();
+    if (opts?.dismissed) params.set("dismissed", "true");
+    if (opts?.runId) params.set("runId", opts.runId);
+    const qs = params.toString();
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/insights${qs ? `?${qs}` : ""}`);
+  }
+  async dismissInsight(project, id) {
+    return this.request("POST", `/projects/${encodeURIComponent(project)}/insights/${encodeURIComponent(id)}/dismiss`);
+  }
+  async getHealth(project) {
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/health/latest`);
+  }
+  async getHealthHistory(project, limit) {
+    const qs = limit ? `?limit=${limit}` : "";
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/health/history${qs}`);
+  }
 };
 
 // src/commands/bing.ts
@@ -1071,17 +1184,17 @@ var BING_CLI_COMMANDS = [
   },
   {
     path: ["bing", "status"],
-    usage: "canonry bing status <project>",
+    usage: "canonry bing status <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "bing.status", "canonry bing status <project>");
+      const project = requireProject(input, "bing.status", "canonry bing status <project> [--format json]");
       await bingStatus(project, input.format);
     }
   },
   {
     path: ["bing", "sites"],
-    usage: "canonry bing sites <project>",
+    usage: "canonry bing sites <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "bing.sites", "canonry bing sites <project>");
+      const project = requireProject(input, "bing.sites", "canonry bing sites <project> [--format json]");
       await bingSites(project, input.format);
     }
   },
@@ -1100,20 +1213,20 @@ var BING_CLI_COMMANDS = [
   },
   {
     path: ["bing", "coverage"],
-    usage: "canonry bing coverage <project>",
+    usage: "canonry bing coverage <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "bing.coverage", "canonry bing coverage <project>");
+      const project = requireProject(input, "bing.coverage", "canonry bing coverage <project> [--format json]");
       await bingCoverage(project, input.format);
     }
   },
   {
     path: ["bing", "inspect"],
-    usage: "canonry bing inspect <project> <url>",
+    usage: "canonry bing inspect <project> <url> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "bing.inspect", "canonry bing inspect <project> <url>");
+      const project = requireProject(input, "bing.inspect", "canonry bing inspect <project> <url> [--format json]");
       const url = requirePositional(input, 1, {
         command: "bing.inspect",
-        usage: "canonry bing inspect <project> <url>",
+        usage: "canonry bing inspect <project> <url> [--format json]",
         message: "project name and URL are required"
       });
       await bingInspect(project, url, input.format);
@@ -1161,9 +1274,9 @@ var BING_CLI_COMMANDS = [
   },
   {
     path: ["bing", "performance"],
-    usage: "canonry bing performance <project>",
+    usage: "canonry bing performance <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "bing.performance", "canonry bing performance <project>");
+      const project = requireProject(input, "bing.performance", "canonry bing performance <project> [--format json]");
       await bingPerformance(project, input.format);
     }
   },
@@ -1334,7 +1447,7 @@ var CDP_CLI_COMMANDS = [
   },
   {
     path: ["cdp", "status"],
-    usage: "canonry cdp status",
+    usage: "canonry cdp status [--format json]",
     allowPositionals: false,
     run: async (input) => {
       await cdpStatus(input.format);
@@ -1342,7 +1455,7 @@ var CDP_CLI_COMMANDS = [
   },
   {
     path: ["cdp", "targets"],
-    usage: "canonry cdp targets",
+    usage: "canonry cdp targets [--format json]",
     allowPositionals: false,
     run: async (input) => {
       await cdpTargets(input.format);
@@ -1744,7 +1857,7 @@ var COMPETITOR_CLI_COMMANDS = [
   },
   {
     path: ["competitor", "list"],
-    usage: "canonry competitor list <project>",
+    usage: "canonry competitor list <project> [--format json]",
     run: async (input) => {
       const project = requireProject(input, "competitor.list", "canonry competitor list <project>");
       await listCompetitors(project, input.format);
@@ -2355,17 +2468,17 @@ var GOOGLE_CLI_COMMANDS = [
   },
   {
     path: ["google", "status"],
-    usage: "canonry google status <project>",
+    usage: "canonry google status <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.status", "canonry google status <project>");
+      const project = requireProject(input, "google.status", "canonry google status <project> [--format json]");
       await googleStatus(project, input.format);
     }
   },
   {
     path: ["google", "properties"],
-    usage: "canonry google properties <project>",
+    usage: "canonry google properties <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.properties", "canonry google properties <project>");
+      const project = requireProject(input, "google.properties", "canonry google properties <project> [--format json]");
       await googleProperties(project, input.format);
     }
   },
@@ -2397,9 +2510,9 @@ var GOOGLE_CLI_COMMANDS = [
   },
   {
     path: ["google", "list-sitemaps"],
-    usage: "canonry google list-sitemaps <project>",
+    usage: "canonry google list-sitemaps <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.list-sitemaps", "canonry google list-sitemaps <project>");
+      const project = requireProject(input, "google.list-sitemaps", "canonry google list-sitemaps <project> [--format json]");
       await googleListSitemaps(project, { format: input.format });
     }
   },
@@ -2451,12 +2564,12 @@ var GOOGLE_CLI_COMMANDS = [
   },
   {
     path: ["google", "inspect"],
-    usage: "canonry google inspect <project> <url>",
+    usage: "canonry google inspect <project> <url> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.inspect", "canonry google inspect <project> <url>");
+      const project = requireProject(input, "google.inspect", "canonry google inspect <project> <url> [--format json]");
       const url = requirePositional(input, 1, {
         command: "google.inspect",
-        usage: "canonry google inspect <project> <url>",
+        usage: "canonry google inspect <project> <url> [--format json]",
         message: "project name and URL are required"
       });
       await googleInspect(project, url, input.format);
@@ -2494,9 +2607,9 @@ var GOOGLE_CLI_COMMANDS = [
   },
   {
     path: ["google", "coverage"],
-    usage: "canonry google coverage <project>",
+    usage: "canonry google coverage <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.coverage", "canonry google coverage <project>");
+      const project = requireProject(input, "google.coverage", "canonry google coverage <project> [--format json]");
       await googleCoverage(project, input.format);
     }
   },
@@ -2520,9 +2633,9 @@ var GOOGLE_CLI_COMMANDS = [
   },
   {
     path: ["google", "deindexed"],
-    usage: "canonry google deindexed <project>",
+    usage: "canonry google deindexed <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "google.deindexed", "canonry google deindexed <project>");
+      const project = requireProject(input, "google.deindexed", "canonry google deindexed <project> [--format json]");
       await googleDeindexed(project, input.format);
     }
   },
@@ -3618,7 +3731,7 @@ var PROJECT_CLI_COMMANDS = [
   },
   {
     path: ["project", "show"],
-    usage: "canonry project show <name>",
+    usage: "canonry project show <name> [--format json]",
     run: async (input) => {
       const name = requireProject(input, "project.show", "canonry project show <name>");
       await showProject(name, input.format);
@@ -3634,7 +3747,7 @@ var PROJECT_CLI_COMMANDS = [
   },
   {
     path: ["project", "add-location"],
-    usage: "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country>",
+    usage: "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country> [--format json]",
     options: {
       label: stringOption(),
       city: stringOption(),
@@ -3646,7 +3759,7 @@ var PROJECT_CLI_COMMANDS = [
       const name = requireProject(
         input,
         "project.add-location",
-        "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country>"
+        "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country> [--format json]"
       );
       const label = getString(input.values, "label");
       const city = getString(input.values, "city");
@@ -3657,7 +3770,7 @@ var PROJECT_CLI_COMMANDS = [
           message: "location label, city, region, and country are required",
           details: {
             command: "project.add-location",
-            usage: "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country>",
+            usage: "canonry project add-location <name> --label <label> --city <city> --region <region> --country <country> [--format json]",
             required: ["label", "city", "region", "country"]
           }
         });
@@ -3674,20 +3787,20 @@ var PROJECT_CLI_COMMANDS = [
   },
   {
     path: ["project", "locations"],
-    usage: "canonry project locations <name>",
+    usage: "canonry project locations <name> [--format json]",
     run: async (input) => {
-      const name = requireProject(input, "project.locations", "canonry project locations <name>");
+      const name = requireProject(input, "project.locations", "canonry project locations <name> [--format json]");
       await listLocations(name, input.format);
     }
   },
   {
     path: ["project", "remove-location"],
-    usage: "canonry project remove-location <name> <label>",
+    usage: "canonry project remove-location <name> <label> [--format json]",
     run: async (input) => {
-      const name = requireProject(input, "project.remove-location", "canonry project remove-location <name> <label>");
+      const name = requireProject(input, "project.remove-location", "canonry project remove-location <name> <label> [--format json]");
       const label = requirePositional(input, 1, {
         command: "project.remove-location",
-        usage: "canonry project remove-location <name> <label>",
+        usage: "canonry project remove-location <name> <label> [--format json]",
         message: "project name and location label are required"
       });
       await removeLocation(name, label, input.format);
@@ -3695,12 +3808,12 @@ var PROJECT_CLI_COMMANDS = [
   },
   {
     path: ["project", "set-default-location"],
-    usage: "canonry project set-default-location <name> <label>",
+    usage: "canonry project set-default-location <name> <label> [--format json]",
     run: async (input) => {
-      const name = requireProject(input, "project.set-default-location", "canonry project set-default-location <name> <label>");
+      const name = requireProject(input, "project.set-default-location", "canonry project set-default-location <name> <label> [--format json]");
       const label = requirePositional(input, 1, {
         command: "project.set-default-location",
-        usage: "canonry project set-default-location <name> <label>",
+        usage: "canonry project set-default-location <name> <label> [--format json]",
         message: "project name and location label are required"
       });
       await setDefaultLocation(name, label, input.format);
@@ -3984,7 +4097,7 @@ var RUN_CLI_COMMANDS = [
   },
   {
     path: ["run"],
-    usage: "canonry run <project> [--provider <name>] [--wait] [--format json]",
+    usage: "canonry run <project|--all> [--provider <name>] [--location <label>] [--all-locations] [--no-location] [--wait] [--format json]",
     options: {
       provider: stringOption(),
       wait: { type: "boolean", default: false },
@@ -4855,6 +4968,126 @@ var SNAPSHOT_CLI_COMMANDS = [
   }
 ];
 
+// src/commands/insights.ts
+async function listInsights(project, opts) {
+  const client = createApiClient();
+  const insights = await client.getInsights(project, { dismissed: opts.dismissed });
+  if (opts.format === "json") {
+    console.log(JSON.stringify(insights, null, 2));
+    return;
+  }
+  if (insights.length === 0) {
+    console.log("No insights found.");
+    return;
+  }
+  for (const insight of insights) {
+    const severity = insight.severity.toUpperCase().padEnd(8);
+    const dismissed = insight.dismissed ? " [dismissed]" : "";
+    console.log(`${severity} ${insight.type.padEnd(12)} ${insight.title}${dismissed}`);
+    if (insight.recommendation) {
+      console.log(`         Action: ${insight.recommendation.action}${insight.recommendation.target ? ` \u2192 ${insight.recommendation.target}` : ""}`);
+      console.log(`         Reason: ${insight.recommendation.reason}`);
+    }
+    if (insight.cause) {
+      console.log(`         Cause: ${insight.cause.cause}${insight.cause.competitorDomain ? ` (${insight.cause.competitorDomain})` : ""}`);
+    }
+    console.log("");
+  }
+}
+async function dismissInsight(project, id, opts) {
+  const client = createApiClient();
+  const result = await client.dismissInsight(project, id);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Insight ${id} dismissed.`);
+}
+
+// src/commands/health-cmd.ts
+async function showHealth(project, opts) {
+  const client = createApiClient();
+  if (opts.history) {
+    const snapshots = await client.getHealthHistory(project, opts.limit);
+    if (opts.format === "json") {
+      console.log(JSON.stringify(snapshots, null, 2));
+      return;
+    }
+    if (snapshots.length === 0) {
+      console.log("No health history available.");
+      return;
+    }
+    console.log("Date                      Cited Rate   Cited/Total");
+    console.log("\u2500".repeat(55));
+    for (const snap of snapshots) {
+      const rate2 = (snap.overallCitedRate * 100).toFixed(1).padStart(5) + "%";
+      const ratio = `${snap.citedPairs}/${snap.totalPairs}`;
+      const date = snap.createdAt.slice(0, 19).padEnd(25);
+      console.log(`${date} ${rate2}        ${ratio}`);
+    }
+    return;
+  }
+  const health = await client.getHealth(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(health, null, 2));
+    return;
+  }
+  const rate = (health.overallCitedRate * 100).toFixed(1);
+  console.log(`Health: ${rate}% cited (${health.citedPairs}/${health.totalPairs} pairs)`);
+  console.log("");
+  if (health.providerBreakdown && Object.keys(health.providerBreakdown).length > 0) {
+    console.log("Provider Breakdown:");
+    for (const [provider, stats] of Object.entries(health.providerBreakdown)) {
+      const pRate = (stats.citedRate * 100).toFixed(1);
+      console.log(`  ${provider.padEnd(15)} ${pRate}% (${stats.cited}/${stats.total})`);
+    }
+  }
+}
+
+// src/cli-commands/intelligence.ts
+var INTELLIGENCE_CLI_COMMANDS = [
+  {
+    path: ["insights"],
+    usage: "canonry insights <project> [--dismissed] [--format json]",
+    options: {
+      dismissed: { type: "boolean" }
+    },
+    run: async (input) => {
+      const usage = "canonry insights <project> [--dismissed] [--format json]";
+      const project = requireProject(input, "insights", usage);
+      const dismissed = input.values.dismissed === true;
+      await listInsights(project, { dismissed, format: input.format });
+    }
+  },
+  {
+    path: ["insights", "dismiss"],
+    usage: "canonry insights dismiss <project> <id> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry insights dismiss <project> <id> [--format json]";
+      const project = requireProject(input, "insights dismiss", usage);
+      const id = requirePositional(input, 1, { command: "insights dismiss", usage, message: "insight ID is required" });
+      await dismissInsight(project, id, { format: input.format });
+    }
+  },
+  {
+    path: ["health"],
+    usage: "canonry health <project> [--history] [--limit <n>] [--format json]",
+    options: {
+      history: { type: "boolean" },
+      limit: { type: "string" }
+    },
+    run: async (input) => {
+      const usage = "canonry health <project> [--history] [--limit <n>] [--format json]";
+      const project = requireProject(input, "health", usage);
+      const history = input.values.history === true;
+      const limitStr = getString(input.values, "limit");
+      const limit = limitStr ? Number.parseInt(limitStr, 10) : void 0;
+      await showHealth(project, { history, limit, format: input.format });
+    }
+  }
+];
+
 // src/commands/bootstrap.ts
 import crypto from "crypto";
 import path2 from "path";
@@ -5035,15 +5268,17 @@ async function bootstrapCommand(_opts) {
   const keyPrefix = rawApiKey.slice(0, 9);
   const db = createClient(databasePath);
   migrate(db);
-  db.delete(apiKeys).where(eq2(apiKeys.name, "default")).run();
-  db.insert(apiKeys).values({
-    id: crypto.randomUUID(),
-    name: "default",
-    keyHash,
-    keyPrefix,
-    scopes: '["*"]',
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  }).run();
+  db.transaction((tx) => {
+    tx.delete(apiKeys).where(eq2(apiKeys.name, "default")).run();
+    tx.insert(apiKeys).values({
+      id: crypto.randomUUID(),
+      name: "default",
+      keyHash,
+      keyPrefix,
+      scopes: '["*"]',
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    }).run();
+  });
   saveConfig({
     apiUrl: env.apiUrl || existingConfig?.apiUrl || `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
     database: databasePath,
@@ -6814,7 +7049,8 @@ var REGISTERED_CLI_COMMANDS = [
   ...BING_CLI_COMMANDS,
   ...WORDPRESS_CLI_COMMANDS,
   ...CDP_CLI_COMMANDS,
-  ...GA_CLI_COMMANDS
+  ...GA_CLI_COMMANDS,
+  ...INTELLIGENCE_CLI_COMMANDS
 ];
 
 // src/cli.ts
@@ -6822,160 +7058,53 @@ import { createRequire } from "module";
 var USAGE = `
 canonry \u2014 AEO monitoring CLI
 
-Usage:
-  canonry init [--force]               Initialize config and database (interactive)
-  canonry init --gemini-key <key>     Initialize non-interactively (also reads env vars)
-  canonry bootstrap [--force]          Bootstrap config/database from env vars
-  canonry backfill answer-visibility   Backfill answer-level visibility from stored answers
-  canonry serve                       Start the local server (foreground)
-  canonry start                       Start the server as a background daemon
-  canonry stop                        Stop the background daemon
-  canonry project create <name>       Create a project
-  canonry project update <name>       Update project settings
-  canonry project list                List all projects
-  canonry project show <name>         Show project details
-  canonry project delete <name>       Delete a project
-  canonry project add-location <name> Add a location (--label, --city, --region, --country)
-  canonry project locations <name>    List locations for a project
-  canonry project remove-location <name> <label>  Remove a location
-  canonry project set-default-location <name> <label>  Set default location
-  canonry keyword add <project> <kw>  Add key phrases to a project
-  canonry keyword remove <project> <kw>  Remove key phrases from a project
-  canonry keyword list <project>      List key phrases for a project
-  canonry keyword import <project> <file>  Import key phrases from file
-  canonry keyword generate <project>  Auto-generate key phrases (--provider, --count, --save)
-  canonry competitor add <project> <domain>  Add competitors
-  canonry competitor list <project>   List competitors
-  canonry snapshot <company> --domain <domain>  One-shot AI perception report
-  canonry run <project>               Trigger a run (all providers)
-  canonry run <project> --provider <name>  Trigger a run for a specific provider
-  canonry run <project> --location <label> Run with a specific location
-  canonry run <project> --all-locations    Run for every configured location (N\xD7 API calls)
-  canonry run <project> --no-location      Explicitly skip location context
-  canonry run <project> --wait        Trigger and wait for completion
-  canonry run --all                   Trigger runs for all projects
-  canonry run show <id>               Show run details and snapshots
-  canonry runs <project>              List runs for a project (--limit <n>)
-  canonry status <project>            Show project summary [--format json]
-  canonry evidence <project>          Show per-phrase results [--format json]
-  canonry analytics <project>         Show analytics (--feature metrics|gaps|sources, --window 7d|30d|90d|all)
-  canonry history <project>           Show audit trail [--format json]
-  canonry export <project>            Export project as YAML
-  canonry apply <file...>              Apply declarative config (multi-doc YAML supported)
-  canonry schedule set <project>      Set schedule (--preset or --cron)
-  canonry schedule show <project>     Show schedule
-  canonry schedule enable <project>   Enable schedule
-  canonry schedule disable <project>  Disable schedule
-  canonry schedule remove <project>   Remove schedule
-  canonry notify add <project>        Add webhook notification
-  canonry notify list <project>       List notifications
-  canonry notify remove <project> <id>  Remove notification
-  canonry notify test <project> <id>  Send test webhook
-  canonry notify events               List available notification event types
-  canonry google connect <project>     Connect Google Search Console (--type gsc|ga4, --public-url <url>)
-  canonry google disconnect <project> Disconnect Google integration
-  canonry google status <project>     Show Google connection status
-  canonry google properties <project> List available GSC properties
-  canonry google set-property <project> <url>  Set GSC property URL
-  canonry google set-sitemap <project> <url>   Set GSC sitemap URL
-  canonry google list-sitemaps <project>       List submitted sitemaps from GSC (no run queued)
-  canonry google discover-sitemaps <project>   Auto-discover sitemaps from GSC and queue inspection (--wait)
-  canonry google sync <project>       Sync GSC data (--days 30, --full, --wait)
-  canonry google performance <project>  Show GSC search performance data
-  canonry google inspect <project> <url>  Inspect a URL via GSC
-  canonry google inspect-sitemap <project>  Bulk inspect all URLs from sitemap (--sitemap-url, --wait)
-  canonry google request-indexing <project> <url>  Request Google indexing for a URL
-  canonry google request-indexing <project> --all-unindexed  Request indexing for all unindexed URLs
-  canonry google coverage <project>  Show index coverage summary
-  canonry google refresh <project>  Force-fetch fresh GSC coverage data and display updated summary
-  canonry google inspections <project>  Show URL inspection history (--url <url>)
-  canonry google deindexed <project>  Show pages that lost indexing
-  canonry bing connect <project>     Connect Bing Webmaster Tools (prompted for API key)
-  canonry bing disconnect <project>  Disconnect Bing integration
-  canonry bing status <project>      Show Bing connection status
-  canonry bing sites <project>       List registered Bing sites
-  canonry bing set-site <project> <url>  Set active Bing site
-  canonry bing coverage <project>    Show Bing index coverage summary
-  canonry bing refresh <project>    Force-fetch fresh Bing coverage data and display updated summary
-  canonry bing inspect <project> <url>  Inspect a URL via Bing
-  canonry bing inspections <project>  Show Bing URL inspection history (--url <url>)
-  canonry bing request-indexing <project> <url>  Submit URL to Bing for indexing
-  canonry bing request-indexing <project> --all-unindexed  Submit all unindexed URLs to Bing
-  canonry bing performance <project>  Show Bing search performance data
-  canonry wordpress connect <project>  Connect WordPress REST access (--url, --user, --staging-url)
-  canonry wordpress disconnect <project>  Disconnect WordPress integration
-  canonry wordpress status <project>  Show WordPress connection status
-  canonry wordpress pages <project>  List WordPress pages (--live|--staging)
-  canonry wordpress page <project> <slug>  Show a WordPress page
-  canonry wordpress create-page <project>  Create a WordPress page (--title, --slug, --content/--content-file)
-  canonry wordpress update-page <project> <slug>  Update a WordPress page (--content/--content-file)
-  canonry wordpress set-meta <project> <slug>  Update REST-exposed SEO meta
-  canonry wordpress set-meta <project> --from <file>  Bulk update SEO meta from JSON file
-  canonry wordpress schema <project> <slug>  Read rendered JSON-LD schema
-  canonry wordpress schema deploy <project> --profile <file>  Deploy JSON-LD schema to pages
-  canonry wordpress schema status <project>  Show schema status per page
-  canonry wordpress set-schema <project> <slug>  Generate manual schema handoff
-  canonry wordpress onboard <project> --url <url> --user <user>  Full onboarding workflow
-  canonry wordpress llms-txt <project>  Read /llms.txt
-  canonry wordpress set-llms-txt <project>  Generate manual llms.txt handoff
-  canonry wordpress audit <project>  Audit WordPress pages for SEO/content issues
-  canonry wordpress diff <project> <slug>  Compare live vs staging for a page
-  canonry wordpress staging status <project>  Show staging configuration
-  canonry wordpress staging push <project>  Generate manual staging push instructions
-  canonry settings                    Show active provider and quota settings
-  canonry settings provider <name>    Update a provider config
-  canonry settings google             Update Google OAuth credentials
-  canonry telemetry status            Show telemetry status
-  canonry telemetry enable            Enable anonymous telemetry
-  canonry telemetry disable           Disable anonymous telemetry
-  canonry --help                      Show this help
-  canonry --version                   Show version
+Usage:  canonry <command> [options]
+
+Setup:
+  init                  Initialize config and database
+  bootstrap             Bootstrap config/database from env vars
+  serve                 Start the local server (foreground)
+  start / stop          Start/stop as a background daemon
+
+Projects:
+  project               Create, update, list, show, delete projects
+  keyword               Add, remove, list, import, generate key phrases
+  competitor            Add, list competitors
+
+Monitoring:
+  run                   Trigger visibility sweeps
+  snapshot              One-shot AI perception report
+  status <project>      Show project summary
+  evidence <project>    Show per-phrase results
+  analytics <project>   Show analytics (metrics, gaps, sources)
+  insights <project>    Show intelligence insights
+  health <project>      Show citation health
+
+Config-as-Code:
+  apply <file...>       Apply declarative config (YAML)
+  export <project>      Export project as YAML
 
-Options:
-  --gemini-key <key>   Gemini API key (or GEMINI_API_KEY env var)
-  --openai-key <key>   OpenAI API key (or OPENAI_API_KEY env var)
-  --claude-key <key>   Anthropic API key (or ANTHROPIC_API_KEY env var)
-  --perplexity-key <key> Perplexity API key (or PERPLEXITY_API_KEY env var)
-  --local-url <url>    Local LLM base URL (or LOCAL_BASE_URL env var)
-  --local-model <name> Local LLM model name (default: llama3)
-  --local-key <key>    Local LLM API key (or LOCAL_API_KEY env var)
-  --google-client-id <id>      Google OAuth client ID (or GOOGLE_CLIENT_ID env var)
-  --google-client-secret <key> Google OAuth client secret (or GOOGLE_CLIENT_SECRET env var)
-  --port <port>        Server port (default: 4100)
-  --host <host>        Server bind address (default: 127.0.0.1)
-  --domain <domain>    Canonical domain for project create/update
-  --owned-domain <domain>  Additional owned domain for citation matching (repeatable)
-  --add-domain <domain>    Add an owned domain (project update, repeatable)
-  --remove-domain <domain> Remove an owned domain (project update, repeatable)
-  --display-name <name>    Display name for project create/update
-  --country <code>     Country code (default: US)
-  --language <lang>    Language code (default: en)
-  --provider <name>    Provider to use (gemini, openai, claude, perplexity, local, cdp:chatgpt, or cdp for all CDP targets)
-  --format <fmt>       Output format: text (default) or json
-  --phrases <list>     Comma-separated category queries (snapshot)
-  --competitors <list> Comma-separated competitor hints (snapshot)
-  --pdf <path>         Write a PDF snapshot report to a file
-  --location <label>   Run with a specific configured location
-  --all-locations      Run for every configured location
-  --no-location        Explicitly skip location context
-  --wait               Wait for run to complete before returning
-  --all                Run all projects (with 'run' command)
-  --project <name>     Restrict maintenance commands to a single project
-  --include-results    Include results in export
-  --preset <preset>    Schedule preset (daily, weekly, twice-daily, daily@HH, weekly@DAY)
-  --cron <expr>        Cron expression for schedule
-  --timezone <tz>      IANA timezone for schedule (default: UTC)
-  --webhook <url>      Webhook URL for notifications
-  --events <list>      Comma-separated notification events
-  --limit <n>          Maximum number of results to return where supported
-  --api-key <key>      Provider API key (settings provider)
-  --base-url <url>     Provider base URL (settings provider)
-  --model <name>       Provider model name (settings provider)
-  --client-id <id>     Google OAuth client ID (settings google)
-  --client-secret <key> Google OAuth client secret (settings google)
-  --max-concurrent <n> Max concurrent requests per provider
-  --max-per-minute <n> Max requests per minute per provider
-  --max-per-day <n>    Max requests per day per provider
+Integrations:
+  google                Google Search Console / Analytics
+  bing                  Bing Webmaster Tools
+  wordpress             WordPress REST API
+
+Automation:
+  schedule              Manage scheduled runs
+  notify                Manage webhook notifications
+
+Admin:
+  settings              Show/update provider and quota settings
+  backfill              Backfill answer visibility or insights
+  telemetry             Manage anonymous telemetry
+  history <project>     Show audit trail
+
+Global options:
+  --format json         Machine-readable output (all commands)
+  --help, -h            Show help (use with any command group)
+  --version, -v         Show version
+
+Run 'canonry <command> --help' for details on a specific command.
 `.trim();
 var _require = createRequire(import.meta.url);
 var { version: VERSION } = _require("../package.json");
@@ -6985,7 +7114,7 @@ function extractFormat(cmdArgs) {
   return "text";
 }
 async function runCli(args = process.argv.slice(2)) {
-  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
     console.log(USAGE);
     return 0;
   }
@@ -6995,13 +7124,25 @@ async function runCli(args = process.argv.slice(2)) {
   }
   const command = args[0];
   const format = extractFormat(args);
-  if (command !== "telemetry" && command !== "init" && isTelemetryEnabled() && isFirstRun()) {
+  const isHelpRequest = args.includes("--help") || args.includes("-h");
+  if (!isHelpRequest && command !== "telemetry" && command !== "init" && isTelemetryEnabled() && isFirstRun()) {
     showFirstRunNotice();
     getOrCreateAnonymousId();
   }
   const SUBCOMMAND_COMMANDS = /* @__PURE__ */ new Set(["backfill", "project", "keyword", "competitor", "schedule", "notify", "settings", "telemetry", "google", "bing", "wordpress", "cdp"]);
-  const resolvedCommand = SUBCOMMAND_COMMANDS.has(command) && args[1] && !args[1].startsWith("-") ? `${command}.${args[1]}` : command;
-  if (command !== "telemetry") {
+  const MIXED_SUBCOMMANDS = {
+    insights: /* @__PURE__ */ new Set(["dismiss"]),
+    run: /* @__PURE__ */ new Set(["show", "cancel"])
+  };
+  let resolvedCommand;
+  if (SUBCOMMAND_COMMANDS.has(command) && args[1] && !args[1].startsWith("-")) {
+    resolvedCommand = `${command}.${args[1]}`;
+  } else if (MIXED_SUBCOMMANDS[command] && args[1] && MIXED_SUBCOMMANDS[command].has(args[1])) {
+    resolvedCommand = `${command}.${args[1]}`;
+  } else {
+    resolvedCommand = command;
+  }
+  if (!isHelpRequest && command !== "telemetry") {
     trackEvent("cli.command", { command: resolvedCommand });
   }
   try {