@ainyc/canonry 4.180.7 → 4.182.3

package/dist/cli.js

@@ -19,18 +19,20 @@ import {
   getOrCreateAnonymousId,
   isAeroToolProfile,
   isFirstRun,
+  isLoopbackBindHost,
   isTelemetryEnabled,
   listAgentProviders,
   setGoogleAuthConfig,
   setTelemetrySource,
   showFirstRunNotice,
   trackCliCommandFinished,
-  trackEvent
-} from "./chunk-VZO6CLHY.js";
+  trackEvent,
+  waitForServerRuntimeStartup
+} from "./chunk-BDJT7XZL.js";
 import {
   autoSyncSkills,
   formatAutoSyncNotice
-} from "./chunk-XYTSKRO3.js";
+} from "./chunk-I3KSOMJA.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -55,7 +57,7 @@ import {
   saveConfigPatch,
   systemError,
   usageError
-} from "./chunk-CWXPBQR5.js";
+} from "./chunk-FVC7PGYQ.js";
 import {
   CLOUDFLARE_WORKER_BINDINGS,
   CLOUDFLARE_WORKER_GENERATED_MARKER,
@@ -69,7 +71,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-WJFBNCVD.js";
+} from "./chunk-K45YKXE4.js";
 import {
   AdsDeliverySnapshotStatuses,
   AdsHistoricalCampaignRollupStatuses,
@@ -138,7 +140,7 @@ import {
   providerQuotaPolicySchema,
   resolveProviderInput,
   winnabilityClassSchema
-} from "./chunk-RXXZ5BU5.js";
+} from "./chunk-DY5ZDKQW.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -184,6 +186,13 @@ import { parseArgs } from "util";
 function commandId(spec) {
   return spec.path.join(".");
 }
+function printCommandHelp(spec) {
+  console.log(`
+Usage:  ${spec.usage}
+`);
+  if (spec.help) console.log(`${spec.help}
+`);
+}
 function matchesPath(args, path13) {
   if (args.length < path13.length) return false;
   return path13.every((segment, index) => args[index] === segment);
@@ -222,9 +231,7 @@ async function dispatchRegisteredCommand(args, fallbackFormat, specs) {
     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}
-`);
+      printCommandHelp(exactMatch);
       return true;
     }
     const group = argsWithoutHelp[0];
@@ -236,9 +243,7 @@ Usage:  ${exactMatch.usage}
       }
       const single = specs.find((s) => s.path.length === 1 && s.path[0] === group);
       if (single) {
-        console.log(`
-Usage:  ${single.usage}
-`);
+        printCommandHelp(single);
         return true;
       }
     }
@@ -7564,8 +7569,95 @@ async function listCompetitors(project, format) {
     console.log(`  ${c.domain}`);
   }
 }
+async function showCompetitorLandscape(project, options) {
+  const client = getClient10();
+  const data = await client.getCompetitorLandscape(project, {
+    window: options.window,
+    scope: options.scope,
+    groupKey: options.groupKey,
+    provider: options.provider,
+    ...options.groupBy ? { groupBy: options.groupBy } : {},
+    ...options.model !== void 0 ? { model: options.model } : {},
+    queryClass: options.queryClass,
+    location: options.location,
+    runId: options.runId
+  });
+  if (options.format === "json") {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (options.format === "jsonl") {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  printCompetitorLandscape(data);
+}
+function printCompetitorLandscape(data) {
+  const scope = data.scope.kind === "group" ? `market ${data.scope.groupKey}` : data.scope.kind === "all-markets" ? "all markets" : "project";
+  console.log(`Competitor landscape \xB7 ${scope} \xB7 ${data.window}`);
+  if (data.filters.model !== void 0) {
+    console.log(`Requested model filter: ${data.filters.provider} \xB7 ${data.filters.model}`);
+  }
+  console.log("Mention share is answer-text evidence; citations are independent source-list evidence.");
+  console.log(
+    data.filters.queryClass === "all" ? "Share of voice is blank: branded and non-brand queries are pooled here. Add --query-class non-brand for a ratio." : `Counting ${data.filters.queryClass} queries only.`
+  );
+  if (data.truncated) console.log("Top 100 observed competitors and top 100 other cited sources shown; pinned competitors are complete.");
+  console.log("");
+  printLandscapeRows("Your brand", [data.project]);
+  printLandscapeRows("Pinned competitors", data.pinned);
+  printLandscapeRows("Observed competitors", data.observed);
+  printLandscapeRows("Other cited sources", data.otherSources);
+  console.log("");
+  console.log(
+    `Evidence: ${data.evidence.answeredResults} answer-text result(s), ${data.evidence.sourceResults} source result(s); excluded: ${data.evidence.excludedProbeResults} probe, ${data.evidence.excludedNonCompletedResults} non-completed.`
+  );
+  if (data.modelComparison) printModelComparison(data.modelComparison);
+}
+function describeServedModels(evidence) {
+  if (evidence.status === "unknown") return "Unknown (not disclosed)";
+  if (evidence.status === "known") return evidence.model;
+  return [...evidence.models, ...evidence.includesUnknown ? ["Unknown (not disclosed)"] : []].join(", ");
+}
+function printModelComparison(comparison) {
+  console.log("");
+  console.log(`Model comparison \xB7 requested-model basis \xB7 ${comparison.groups.length} of ${comparison.totalGroups} groups`);
+  console.log("Groups use stored observations. They do not form a matched-query or equal-weight comparison.");
+  if (comparison.truncated) console.log("The first 50 provider/model groups are shown. Additional groups are omitted.");
+  for (const group of comparison.groups) {
+    console.log("");
+    console.log(`${group.provider} \xB7 requested model: ${group.model ?? "Unknown (not recorded)"}`);
+    console.log(`Served model evidence: ${describeServedModels(group.servedModels)}`);
+    console.log(`Samples: ${group.snapshotCount} snapshot(s), ${group.evidence.answeredResults} answer-text result(s), ${group.evidence.sourceResults} source result(s).`);
+    printLandscapeRows("Your brand", [group.project], true);
+    printLandscapeRows("Pinned competitors", group.pinned, true);
+    printLandscapeRows("Observed competitors", group.observed, true);
+    printLandscapeRows("Other cited sources", group.otherSources, true);
+    if (group.truncated) console.log("Top 100 observed competitors and top 100 other sources shown. Pinned competitors are complete.");
+  }
+}
+function printLandscapeRows(heading, rows, showSampleCount = false) {
+  console.log(`${heading}:`);
+  if (rows.length === 0) {
+    console.log("  \u2014");
+    return;
+  }
+  for (const row of rows) {
+    const sov = row.shareOfVoice === null ? "\u2014" : `${row.shareOfVoice.toFixed(1)}%`;
+    console.log(`  ${row.domain}  mention ${row.mentionCount} \xB7 citation ${row.citationCount} \xB7 SOV ${sov}${showSampleCount ? ` \xB7 answers ${row.answeredResults}` : ""}`);
+  }
+}
 
 // src/cli-commands/competitor.ts
+var LANDSCAPE_USAGE = "canonry competitor landscape <project> [--window 7d|30d|90d|all] [--group-key <key>|--scope all-markets] [--by-model] [--provider <provider> [--model <id>]] [--query-class all|branded|non-brand] [--location <label>] [--run-id <id>] [--format json|jsonl]";
+function parseLandscapeScope(value) {
+  if (value === void 0 || value === "") return void 0;
+  if (value !== "all-markets") throw usageError(`--scope must be "all-markets" (got "${value}")`, {
+    message: '--scope must be "all-markets"',
+    details: { command: "competitor.landscape", usage: LANDSCAPE_USAGE }
+  });
+  return value;
+}
 var COMPETITOR_CLI_COMMANDS = [
   {
     path: ["competitor", "add"],
@@ -7629,14 +7721,60 @@ var COMPETITOR_CLI_COMMANDS = [
       await listCompetitors(project, input.format);
     }
   },
+  {
+    path: ["competitor", "landscape"],
+    usage: LANDSCAPE_USAGE,
+    options: {
+      window: stringOption(),
+      "group-key": stringOption(),
+      scope: stringOption(),
+      provider: stringOption(),
+      "by-model": { type: "boolean" },
+      model: stringOption(),
+      "query-class": stringOption(),
+      location: stringOption(),
+      "run-id": stringOption()
+    },
+    run: async (input) => {
+      const project = requireProject(input, "competitor.landscape", LANDSCAPE_USAGE);
+      const scope = parseLandscapeScope(getString(input.values, "scope"));
+      const groupKey = getString(input.values, "group-key");
+      const provider = getString(input.values, "provider");
+      const model = getString(input.values, "model");
+      if (model !== void 0 && !provider?.trim()) {
+        throw usageError("--model requires --provider", {
+          message: "--model requires --provider",
+          details: { command: "competitor.landscape", usage: LANDSCAPE_USAGE }
+        });
+      }
+      if (scope === "all-markets" && groupKey) {
+        throw usageError("--group-key cannot be combined with --scope all-markets", {
+          message: "--group-key cannot be combined with --scope all-markets",
+          details: { command: "competitor.landscape", usage: LANDSCAPE_USAGE }
+        });
+      }
+      await showCompetitorLandscape(project, {
+        window: getString(input.values, "window"),
+        groupKey,
+        scope,
+        provider,
+        ...getBoolean(input.values, "by-model") ? { groupBy: "model" } : {},
+        ...model !== void 0 ? { model } : {},
+        queryClass: getString(input.values, "query-class"),
+        location: getString(input.values, "location"),
+        runId: getString(input.values, "run-id"),
+        format: input.format
+      });
+    }
+  },
   {
     path: ["competitor"],
-    usage: "canonry competitor <add|remove|delete|list> <project> [args]",
+    usage: "canonry competitor <add|remove|delete|list|landscape> <project> [args]",
     run: async (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "competitor",
-        usage: "canonry competitor <add|remove|delete|list> <project> [args]",
-        available: ["add", "remove", "delete", "list"]
+        usage: "canonry competitor <add|remove|delete|list|landscape> <project> [args]",
+        available: ["add", "remove", "delete", "list", "landscape"]
       });
     }
   }
@@ -13866,6 +14004,7 @@ var CONTENT_CLI_COMMANDS = [
 // src/commands/bootstrap.ts
 import crypto from "crypto";
 import path9 from "path";
+import { isDeepStrictEqual } from "util";
 import { eq } from "drizzle-orm";
 
 // ../config/src/index.ts
@@ -14011,36 +14150,40 @@ function getBootstrapEnv(source, overrides) {
 }
 
 // src/commands/bootstrap.ts
-async function bootstrapCommand(_opts) {
-  const format = _opts?.format ?? "text";
-  const env = getBootstrapEnv(process.env);
-  const providers = env.providers;
-  const hasProvider = providers?.gemini || providers?.openai || providers?.claude || providers?.perplexity || providers?.local;
-  if (!hasProvider) {
-    console.warn(
-      "Warning: No provider env vars set (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY, or LOCAL_BASE_URL). You can configure providers later via the dashboard."
+function persistedValue(value) {
+  if (Array.isArray(value)) return value.map(persistedValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== void 0).map(([key, entry]) => [key, persistedValue(entry)])
     );
   }
+  return value;
+}
+async function bootstrapCommand(opts) {
+  const format = opts?.format ?? "text";
+  const env = getBootstrapEnv(process.env);
+  const providers = env.providers;
   const configDir = getConfigDir();
-  const databasePath = env.databasePath || path9.join(configDir, "data.db");
   const existing = configExists();
   const existingConfig = existing ? loadConfig() : void 0;
+  const existingRaw = existing ? loadConfigRaw() : null;
+  const databasePath = env.databasePath || existingRaw?.database || path9.join(configDir, "data.db");
   let rawApiKey;
   let generatedApiKey;
   if (env.apiKey) {
     rawApiKey = env.apiKey;
-  } else if (existingConfig) {
-    rawApiKey = existingConfig.apiKey;
+  } else if (existingRaw) {
+    rawApiKey = existingRaw.apiKey;
   } else {
     generatedApiKey = `cnry_${crypto.randomBytes(16).toString("hex")}`;
     rawApiKey = generatedApiKey;
   }
   const mergedProviders = { ...existingConfig?.providers };
-  if (providers?.gemini) mergedProviders.gemini = providers.gemini;
-  if (providers?.openai) mergedProviders.openai = providers.openai;
-  if (providers?.claude) mergedProviders.claude = providers.claude;
-  if (providers?.perplexity) mergedProviders.perplexity = providers.perplexity;
-  if (providers?.local) mergedProviders.local = providers.local;
+  if (providers.gemini) mergedProviders.gemini = providers.gemini;
+  if (providers.openai) mergedProviders.openai = providers.openai;
+  if (providers.claude) mergedProviders.claude = providers.claude;
+  if (providers.perplexity) mergedProviders.perplexity = providers.perplexity;
+  if (providers.local) mergedProviders.local = providers.local;
   if (env.googleClientId && !env.googleClientSecret || !env.googleClientId && env.googleClientSecret) {
     console.warn("Warning: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must both be set to configure Google OAuth. Skipping Google auth config.");
   }
@@ -14051,25 +14194,42 @@ async function bootstrapCommand(_opts) {
   } : existingConfig?.google;
   const keyHash = crypto.createHash("sha256").update(rawApiKey).digest("hex");
   const keyPrefix = rawApiKey.slice(0, 9);
-  const existingConfigKeyHash = existingConfig ? crypto.createHash("sha256").update(existingConfig.apiKey).digest("hex") : void 0;
+  const existingConfigKeyHash = existingRaw ? crypto.createHash("sha256").update(existingRaw.apiKey).digest("hex") : void 0;
   const db = createClient(databasePath);
   migrate(db);
-  db.transaction((tx) => {
+  const keyChanged = db.transaction((tx) => {
+    let changed = false;
     const rotatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const existingDefaults = tx.select({ id: apiKeys.id, keyHash: apiKeys.keyHash }).from(apiKeys).where(eq(apiKeys.name, "default")).all();
+    const existingDefaults = tx.select({
+      id: apiKeys.id,
+      keyHash: apiKeys.keyHash,
+      keyPrefix: apiKeys.keyPrefix,
+      scopes: apiKeys.scopes,
+      projectId: apiKeys.projectId,
+      lastUsedAt: apiKeys.lastUsedAt,
+      revokedAt: apiKeys.revokedAt
+    }).from(apiKeys).where(eq(apiKeys.name, "default")).all();
     const existingDefault = existingDefaults.find((key) => key.keyHash === existingConfigKeyHash) ?? existingDefaults.at(0);
     if (existingDefault) {
-      tx.update(apiKeys).set({
-        keyHash,
-        keyPrefix,
-        scopes: ["*"],
-        projectId: null,
-        lastUsedAt: null,
-        revokedAt: null
-      }).where(eq(apiKeys.id, existingDefault.id)).run();
+      const rotating = existingDefault.keyHash !== keyHash;
+      const needsUpdate = rotating || existingDefault.keyPrefix !== keyPrefix || !isDeepStrictEqual(existingDefault.scopes, ["*"]) || existingDefault.projectId !== null || existingDefault.revokedAt !== null;
+      if (needsUpdate) {
+        tx.update(apiKeys).set({
+          keyHash,
+          keyPrefix,
+          scopes: ["*"],
+          projectId: null,
+          ...rotating ? { lastUsedAt: null } : {},
+          revokedAt: null
+        }).where(eq(apiKeys.id, existingDefault.id)).run();
+        changed = true;
+      }
       for (const duplicate of existingDefaults) {
         if (duplicate.id === existingDefault.id) continue;
-        tx.update(apiKeys).set({ revokedAt: rotatedAt }).where(eq(apiKeys.id, duplicate.id)).run();
+        if (duplicate.revokedAt === null) {
+          tx.update(apiKeys).set({ revokedAt: rotatedAt }).where(eq(apiKeys.id, duplicate.id)).run();
+          changed = true;
+        }
       }
     } else {
       tx.insert(apiKeys).values({
@@ -14080,29 +14240,41 @@ async function bootstrapCommand(_opts) {
         scopes: ["*"],
         createdAt: rotatedAt
       }).run();
+      changed = true;
     }
+    return changed;
   });
-  saveConfig({
-    apiUrl: env.apiUrl || existingConfig?.apiUrl || `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
+  const apiUrl = env.apiUrl || existingRaw?.apiUrl || `http://127.0.0.1:${process.env.CANONRY_PORT || "4100"}`;
+  const nextConfig = {
+    ...existingRaw,
+    apiUrl,
     database: databasePath,
     apiKey: rawApiKey,
     providers: mergedProviders,
     google: mergedGoogle
-  });
+  };
+  const configChanged = !existingRaw || existingRaw.apiUrl !== apiUrl || existingRaw.database !== databasePath || existingRaw.apiKey !== rawApiKey || !isDeepStrictEqual(persistedValue(existingRaw.providers ?? {}), persistedValue(mergedProviders)) || !isDeepStrictEqual(persistedValue(existingRaw.google), persistedValue(mergedGoogle));
+  if (configChanged) saveConfig(nextConfig);
+  const status = !existing ? "created" : configChanged || keyChanged ? "updated" : "unchanged";
   if (format === "json") {
     console.log(JSON.stringify({
       bootstrapped: true,
+      status,
+      changed: status !== "unchanged",
       configPath: getConfigPath(),
       databasePath,
-      apiUrl: env.apiUrl || existingConfig?.apiUrl || `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
-      providers: Object.keys(mergedProviders ?? {}),
+      apiUrl,
+      providers: Object.keys(mergedProviders),
       googleConfigured: !!mergedGoogle,
       generatedApiKey
     }, null, 2));
     return;
   }
-  console.log(`Bootstrap complete. Config saved to ${getConfigPath()}`);
+  console.log(`Bootstrap ${status}. Config: ${getConfigPath()}`);
   console.log(`SQLite database path: ${databasePath}`);
+  if (Object.keys(mergedProviders).length === 0) {
+    console.log("Providers: none (Page Health works now; add one later to enable AI Visibility).");
+  }
   if (generatedApiKey) {
     console.log(`API key: ${generatedApiKey}`);
   }
@@ -14112,6 +14284,27 @@ async function bootstrapCommand(_opts) {
 import { spawn as spawn2 } from "child_process";
 import fs15 from "fs";
 import path10 from "path";
+
+// src/operator-url.ts
+function operatorHost(bindHost) {
+  if (bindHost === "0.0.0.0") return "127.0.0.1";
+  if (bindHost === "::" || bindHost === "[::]") return "::1";
+  return bindHost;
+}
+function operatorHttpUrl(bindHost, port) {
+  const host = operatorHost(bindHost);
+  const bare = host.replace(/^\[|\]$/g, "");
+  return `http://${bare.includes(":") ? `[${bare}]` : bare}:${port}`;
+}
+
+// src/serve-endpoint.ts
+function resolveServePort(envPort, configPort) {
+  const trimmed = envPort?.trim();
+  if (trimmed) return parseInt(trimmed, 10);
+  return configPort ?? 4100;
+}
+
+// src/commands/daemon.ts
 function getPidPath() {
   return path10.join(getConfigDir(), "canonry.pid");
 }
@@ -14125,7 +14318,7 @@ function isProcessAlive(pid) {
   }
 }
 async function waitForReady(host, port, maxMs = 1e4) {
-  const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/health`;
+  const url = `${operatorHttpUrl(host, port)}/health`;
   const deadline = Date.now() + maxMs;
   while (Date.now() < deadline) {
     try {
@@ -14137,6 +14330,13 @@ async function waitForReady(host, port, maxMs = 1e4) {
   }
   return false;
 }
+function resolveDaemonEndpoint(opts, env, configPort) {
+  const portInput = opts.port || env.CANONRY_PORT;
+  return {
+    host: opts.host || env.CANONRY_HOST || "127.0.0.1",
+    port: resolveServePort(portInput, configPort)
+  };
+}
 function buildServeForwardArgs(opts) {
   const args = [];
   if (opts.port) args.push("--port", opts.port);
@@ -14167,10 +14367,14 @@ async function startDaemon(opts) {
     }
     fs15.unlinkSync(pidPath);
   }
+  const config = loadConfig();
+  const endpoint = resolveDaemonEndpoint(opts, process.env, config.port);
+  const host = endpoint.host;
+  const port = String(endpoint.port);
   const cliPath = path10.resolve(new URL(import.meta.url).pathname);
   const inSourceMode = new URL(import.meta.url).pathname.endsWith(".ts");
   const args = inSourceMode ? ["--import", "tsx", cliPath, "serve"] : [cliPath, "serve"];
-  args.push(...buildServeForwardArgs(opts));
+  args.push(...buildServeForwardArgs({ ...opts, host, port }));
   const child = spawn2(process.execPath, args, {
     detached: true,
     stdio: "ignore"
@@ -14188,13 +14392,15 @@ async function startDaemon(opts) {
     fs15.mkdirSync(configDir, { recursive: true });
   }
   fs15.writeFileSync(pidPath, String(child.pid), "utf-8");
-  const port = opts.port ?? "4100";
-  const host = opts.host ?? "127.0.0.1";
   if (!isMachineFormat(format)) {
     process.stderr.write("Waiting for server to start...");
   }
   const ready = await waitForReady(host, port);
   if (!ready) {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+    }
     try {
       fs15.unlinkSync(pidPath);
     } catch {
@@ -14213,7 +14419,7 @@ async function startDaemon(opts) {
   if (!isMachineFormat(format)) {
     process.stderr.write("\n");
   }
-  const url = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+  const url = operatorHttpUrl(host, port);
   if (isMachineFormat(format)) {
     console.log(JSON.stringify({
       started: true,
@@ -14490,7 +14696,7 @@ async function initCommand(opts) {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   }).run();
   saveConfig({
-    apiUrl: `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
+    apiUrl: `http://127.0.0.1:${process.env.CANONRY_PORT || "4100"}`,
     database: databasePath,
     apiKey: rawApiKey,
     providers,
@@ -14537,7 +14743,7 @@ async function initCommand(opts) {
       initialized: true,
       configPath: getConfigPath(),
       databasePath,
-      apiUrl: `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
+      apiUrl: `http://127.0.0.1:${process.env.CANONRY_PORT || "4100"}`,
       apiKey: rawApiKey,
       providers: providerNames,
       googleConfigured: !!google,
@@ -14594,7 +14800,7 @@ ${mcpTip}`);
   }
   if (!isMachineFormat(format)) {
     showFirstRunNotice();
-    console.log("\nNext: canonry serve to open the dashboard, or canonry settings provider gemini --api-key <key> to configure Gemini.");
+    console.log("\nNext: canonry serve to map your site and capture a Page Health baseline.");
     console.log("\nNext steps:");
     for (const line of nextSteps) {
       console.log(`  ${line}`);
@@ -14630,27 +14836,27 @@ ${mcpTip}`);
     const answer = await prompt("\nStart the dashboard now? [Y/n]: ");
     if (!/^n/i.test(answer.trim())) {
       pendingServeHandoff = true;
-      console.log("Handing off to the dashboard. Finish setup at /setup once it is up.");
+      console.log("Handing off to the dashboard. Map your site at /setup once it is up.");
     }
   }
   return agentLLM;
 }
 function buildNextSteps() {
   return [
-    "1. Start the dashboard and open the setup wizard:",
+    "1. Start the dashboard and open Page Health setup:",
     "     canonry serve",
-    "     \u2192 http://localhost:4100/setup",
+    "     \u2192 http://127.0.0.1:4100/setup",
     "",
-    "   The wizard walks through project \u2192 queries \u2192 competitors \u2192 first sweep",
-    "   in 5 guided steps and shows your first results inline.",
+    "   Map your public site and capture a persisted Page Health baseline.",
+    "   AI Visibility is optional and can be configured after Page Health.",
     "   For remote/exposed hosts, complete dashboard password setup from loopback first.",
     "",
     "Prefer the terminal? The same flow as CLI commands:",
     "",
     "  a. canonry project create my-site --domain example.com --country US --language en",
-    '  b. canonry query add my-site "best <category> for <use case>"',
-    "  c. canonry run my-site --wait",
-    "  d. canonry overview my-site",
+    "  b. canonry technical-aeo run my-site --max-pages 100 --wait --format json",
+    "  c. canonry technical-aeo score my-site --format json",
+    "  d. canonry technical-aeo pages my-site --sort score-asc --limit 10 --format jsonl",
     "",
     'Tip: "canonry doctor" verifies your setup before you start.'
   ];
@@ -14869,10 +15075,8 @@ function detectCanonryAgentPlugin(opts = {}) {
 }
 
 // src/commands/serve.ts
-function resolveServePort(envPort, configPort) {
-  const trimmed = envPort?.trim();
-  if (trimmed) return parseInt(trimmed, 10);
-  return configPort ?? 4100;
+function shouldWarnAboutRemoteSetup(host) {
+  return !isLoopbackBindHost(host);
 }
 async function serveCommand(format = "text") {
   const config = loadConfig();
@@ -14911,26 +15115,29 @@ async function serveCommand(format = "text") {
     codexHome: process.env.CODEX_HOME
   });
   const app = await createServer({ config, db, host, getAgentPluginState });
-  let shuttingDown = false;
-  const shutdown = (signal) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    if (format === "text") {
-      console.log(`
-Received ${signal}, stopping server...`);
-    }
-    closeWithIdleSweep(app).then(() => {
-      process.exit(0);
-    }).catch((err) => {
-      console.error("Error during shutdown:", err);
-      process.exit(1);
-    });
-  };
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
-  process.on("SIGINT", () => shutdown("SIGINT"));
+  let listening = false;
   try {
     await app.listen({ host, port });
-    const url = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
+    await waitForServerRuntimeStartup(app);
+    listening = true;
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      if (format === "text") {
+        console.log(`
+Received ${signal}, stopping server...`);
+      }
+      closeWithIdleSweep(app).then(() => {
+        process.exit(0);
+      }).catch((err) => {
+        console.error("Error during shutdown:", err);
+        process.exit(1);
+      });
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    const url = operatorHttpUrl(host, port);
     if (isMachineFormat(format)) {
       console.log(JSON.stringify({
         started: true,
@@ -14941,8 +15148,8 @@ Received ${signal}, stopping server...`);
     } else {
       console.log(`
 Canonry server running at ${url}`);
-      console.log(`Open ${url}/setup to finish onboarding and run your first visibility check.`);
-      if (host === "0.0.0.0") {
+      console.log(`Open ${url}/setup to map your site and run your first Page Health scan.`);
+      if (shouldWarnAboutRemoteSetup(host)) {
         console.log("First-run dashboard password setup is unauthenticated only on loopback; complete setup from this machine first or use a bearer cnry_... key.");
       }
       console.log("Press Ctrl+C to stop.\n");
@@ -14960,6 +15167,17 @@ Canonry server running at ${url}`);
     });
   } catch (err) {
     const message = describeError(err);
+    if (listening) {
+      process.stderr.write(`warning: server started but post-startup reporting failed: ${message}
+`);
+      return;
+    }
+    try {
+      await closeWithIdleSweep(app);
+    } catch (closeErr) {
+      process.stderr.write(`warning: failed to close server after startup error: ${describeError(closeErr)}
+`);
+    }
     throw new CliError({
       code: "SERVE_START_FAILED",
       message: `Failed to start server: ${message}`,
@@ -15016,7 +15234,7 @@ function telemetryCommand(subcommand, format = "text") {
           console.log(JSON.stringify(payload, null, 2));
           return;
         }
-        console.log('Telemetry: enabled (no config yet \u2014 run "canonry init" first)');
+        console.log('Telemetry: enabled (no config yet \u2014 run "canonry bootstrap" first)');
         return;
       }
       const config = loadConfig();
@@ -15041,8 +15259,8 @@ function telemetryCommand(subcommand, format = "text") {
       if (!configExists()) {
         throw new CliError({
           code: "CONFIG_REQUIRED",
-          message: 'No config found. Run "canonry init" first.',
-          displayMessage: 'No config found. Run "canonry init" first.',
+          message: 'No config found. Run "canonry bootstrap" first.',
+          displayMessage: 'No config found. Run "canonry bootstrap" first.',
           details: {
             command: "telemetry.enable"
           }
@@ -15065,8 +15283,8 @@ function telemetryCommand(subcommand, format = "text") {
       if (!configExists()) {
         throw new CliError({
           code: "CONFIG_REQUIRED",
-          message: 'No config found. Run "canonry init" first.',
-          displayMessage: 'No config found. Run "canonry init" first.',
+          message: 'No config found. Run "canonry bootstrap" first.',
+          displayMessage: 'No config found. Run "canonry bootstrap" first.',
           details: {
             command: "telemetry.disable"
           }
@@ -15156,14 +15374,16 @@ var SYSTEM_CLI_COMMANDS = [
   },
   {
     path: ["bootstrap"],
-    usage: "canonry bootstrap [--force] [--format json]",
+    usage: "canonry bootstrap [--format json]",
+    help: "Create or reconcile the local config, SQLite database, and default API key from supported environment variables. Provider credentials are optional. Safe to rerun: existing settings are preserved and the result reports created, updated, or unchanged. The legacy --force/-f flag is accepted but has no effect.",
     options: {
+      // Compatibility for scripts written before bootstrap became idempotent.
+      // Keep this out of usage: the flag is unnecessary and has no behavior.
       force: { type: "boolean", short: "f", default: false }
     },
     allowPositionals: false,
     run: async (input) => {
       await bootstrapCommand({
-        force: getBoolean(input.values, "force"),
         format: input.format
       });
     }
@@ -18784,17 +19004,21 @@ function buildSetupNudgeLine(input) {
 // src/cli.ts
 import { createRequire as createRequire2 } from "module";
 var USAGE6 = `
-cnry \u2014 AEO monitoring CLI   ('canonry' also works)
+cnry \u2014 Page Health and AI visibility CLI   ('canonry' also works)
 
 Usage:  cnry <command> [options]
 
 Setup:
-  init                  Initialize config and database
-  bootstrap             Bootstrap config/database from env vars
+  bootstrap             Create local config/database (no provider required)
   serve                 Start the local server (foreground)
   start / stop          Start/stop as a background daemon
+  init                  Optional interactive provider/OAuth provisioning
   skills                List or install bundled agent skills (claude/codex)
 
+Page Health:
+  technical-aeo         Crawl, score, and inspect site health evidence
+  doctor                Diagnose runtime and integration health
+
 Projects:
   project               Create, update, list, show, delete projects
   query                 Add, replace, remove, list, import, generate queries