@merittdev/horus 0.1.14 → 0.1.16

package/dist/index.cjs

@@ -50314,7 +50314,7 @@ init_cjs_shims();
 
 // ../../packages/core/src/version.ts
 init_cjs_shims();
-var HORUS_VERSION = true ? "0.1.14" : "dev";
+var HORUS_VERSION = true ? "0.1.16" : "dev";
 var PINNED_AXON_VERSION = "1.0.7";
 var PINNED_SOURCE_VERSION = PINNED_AXON_VERSION;
 
@@ -69193,7 +69193,7 @@ function buildRuntimeSourceStatus(evidence2, connectors) {
   const metricsFailed = metricsConfigured && !connectors.metricsCollected;
   const stateCount = evidence2.filter((e) => e.source === "state").length;
   const stateConfigured = !!(connectors.redis || connectors.mongodb);
-  const queueConfigured = evidence2.some((e) => e.source === "queue");
+  const queueConfigured = connectors.queue ?? evidence2.some((e) => e.source === "queue");
   const queueCount = evidence2.filter((e) => e.kind === "queue-state").length;
   return {
     sources: [
@@ -70120,11 +70120,15 @@ async function investigate(input, deps) {
   const queueRuntimeEvIdsByQueue = /* @__PURE__ */ new Map();
   const queueBacklogEvIdsByQueue = /* @__PURE__ */ new Map();
   const queueStarvationEvIdsByQueue = /* @__PURE__ */ new Map();
-  if (deps.queue && queueHits.length > 0) {
+  if (deps.queue) {
     try {
-      const queueNames2 = [...new Set(queueHits.map((e) => e.queueName))];
-      queueRuntimeState = await deps.queue.analyzeQueues({ queueNames: queueNames2 });
-      for (const s of analyzeQueueRuntime(queueRuntimeState)) {
+      const staticNames = [...new Set(queueHits.map((e) => e.queueName))];
+      const discovered = await deps.queue.discoverQueues().catch(() => []);
+      const queueNames2 = [.../* @__PURE__ */ new Set([...staticNames, ...discovered])];
+      if (queueNames2.length > 0) {
+        queueRuntimeState = await deps.queue.analyzeQueues({ queueNames: queueNames2 });
+      }
+      for (const s of analyzeQueueRuntime(queueRuntimeState ?? { prefix: "", collectedAt: "", queues: [] })) {
         const ev = mkEv("queue-state", s.title, s.payload, { queueName: s.queueName }, s.timestamp, s.relevance);
         queueRuntimeEvIds.push(ev.id);
         const perQueue = queueRuntimeEvIdsByQueue.get(s.queueName) ?? [];
@@ -70571,10 +70575,21 @@ async function investigate(input, deps) {
     causeChains: causeChains.length > 0 ? causeChains : void 0,
     ...recentChanges !== void 0 ? { recentChanges } : {}
   };
-  const connectorFlags = deps.connectors ? { ...deps.connectors, metricsCollected, metricsFailureReason, logsCollected, logsCompatibilityError, sinceProvided: input.since !== void 0 } : {
+  const connectorFlags = deps.connectors ? {
+    ...deps.connectors,
+    // The queue connector is configured iff a BullMQ provider was constructed
+    // (queueForEnv returns null without a bullmq/queues Redis DB) — HOR-205.
+    queue: deps.queue != null,
+    metricsCollected,
+    metricsFailureReason,
+    logsCollected,
+    logsCompatibilityError,
+    sinceProvided: input.since !== void 0
+  } : {
     elasticsearch: deps.logs != null,
     mongodb: deps.mongo != null,
     grafana: deps.metrics != null,
+    queue: deps.queue != null,
     metricsCollected,
     metricsFailureReason,
     logsCollected,
@@ -73198,253 +73213,6 @@ async function runIndex(opts) {
 // ../../packages/cli/src/commands/queues.ts
 init_cjs_shims();
 var import_picocolors4 = __toESM(require_picocolors(), 1);
-async function runQueues(name, opts) {
-  try {
-    const config = await loadConfig(opts.config, { name: opts.name });
-    const { db, sql: sql2 } = createDb(config.database.url);
-    try {
-      let project = opts.project;
-      if (project === void 0) {
-        try {
-          project = resolveEnvironment(config, { project: opts.project }).project;
-        } catch {
-        }
-      }
-      const rows = await listQueueEdges(db, { project, queueName: name });
-      if (opts.json) {
-        const topology = topologyToJson(buildQueueMap(rows));
-        const out = { project: project ?? null, topology };
-        if (opts.live) out["live"] = await gatherLiveState(config, rows, name);
-        console.log(JSON.stringify(out, null, 2));
-        return 0;
-      }
-      console.log(
-        import_picocolors4.default.bold("Queue topology") + import_picocolors4.default.dim("  \xB7  source: code / source intelligence  \xB7  static (run horus index to refresh)")
-      );
-      console.log("");
-      if (rows.length === 0) {
-        console.log(import_picocolors4.default.dim("  No queue edges indexed. Run: horus index"));
-      } else {
-        const byQueue = buildQueueMap(rows);
-        printTopology(byQueue);
-      }
-      console.log("");
-      if (opts.live) {
-        await runLiveMode(config, rows, name);
-      } else {
-        console.log(
-          import_picocolors4.default.dim(
-            "  Tip: run horus queues --live to show real-time Redis/BullMQ depths and failed-job counts."
-          )
-        );
-      }
-    } finally {
-      await sql2.end();
-    }
-    return 0;
-  } catch (err) {
-    console.error(import_picocolors4.default.red(err.message));
-    return 1;
-  }
-}
-function buildQueueMap(rows) {
-  const byQueue = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    const existing = byQueue.get(row.queueName);
-    if (existing) {
-      existing.push(row);
-    } else {
-      byQueue.set(row.queueName, [row]);
-    }
-  }
-  return byQueue;
-}
-function endpoints(edges, symKey, fileKey) {
-  const seen = /* @__PURE__ */ new Map();
-  for (const e of edges) {
-    const symbol = e[symKey];
-    if (!symbol) continue;
-    if (!seen.has(symbol)) seen.set(symbol, { symbol, file: e[fileKey] ?? null });
-  }
-  return [...seen.values()];
-}
-function topologyToJson(byQueue) {
-  return [...byQueue.entries()].map(([queueName, edges]) => ({
-    queueName,
-    producers: endpoints(edges, "producerSymbol", "producerFile"),
-    workers: endpoints(edges, "workerSymbol", "workerFile")
-  }));
-}
-async function gatherLiveState(config, rows, nameFilter) {
-  let renv;
-  try {
-    renv = resolveEnvironment(config);
-  } catch (err) {
-    return { ok: false, error: err.message };
-  }
-  const queueProvider = queueForEnv(renv);
-  if (!queueProvider) return { ok: false, error: "Redis not configured" };
-  try {
-    const health = await queueProvider.health();
-    if (!health.ok) return { ok: false, error: health.detail };
-    const staticNames = new Set(buildQueueMap(rows).keys());
-    let queueNames;
-    if (nameFilter !== void 0) {
-      queueNames = [nameFilter];
-    } else {
-      const discovered = await queueProvider.discoverQueues().catch(() => []);
-      const union2 = /* @__PURE__ */ new Set([...staticNames, ...discovered]);
-      queueNames = union2.size > 0 ? [...union2] : void 0;
-    }
-    const state = await queueProvider.analyzeQueues({ queueNames });
-    return {
-      ok: true,
-      prefix: state.prefix,
-      collectedAt: state.collectedAt,
-      queues: state.queues.map((q) => ({ ...q, runtimeOnly: !staticNames.has(q.queueName) }))
-    };
-  } finally {
-    await queueProvider.close().catch(() => {
-    });
-  }
-}
-function printTopology(byQueue) {
-  for (const [queueName, edges] of byQueue) {
-    console.log(import_picocolors4.default.bold(queueName));
-    const producerSet = /* @__PURE__ */ new Set();
-    const producerDetails = /* @__PURE__ */ new Map();
-    for (const edge of edges) {
-      if (edge.producerSymbol) {
-        producerSet.add(edge.producerSymbol);
-        if (edge.producerFile) producerDetails.set(edge.producerSymbol, edge.producerFile);
-      }
-    }
-    if (producerSet.size === 0) {
-      console.log("  producers: " + import_picocolors4.default.dim("none"));
-    } else {
-      const list = Array.from(producerSet).map((sym) => {
-        const file = producerDetails.get(sym);
-        return file ? `${sym} (${file})` : sym;
-      }).join(", ");
-      console.log("  producers: " + list);
-    }
-    const workerSet = /* @__PURE__ */ new Set();
-    const workerDetails = /* @__PURE__ */ new Map();
-    for (const edge of edges) {
-      if (edge.workerSymbol) {
-        workerSet.add(edge.workerSymbol);
-        if (edge.workerFile) workerDetails.set(edge.workerSymbol, edge.workerFile);
-      }
-    }
-    if (workerSet.size === 0) {
-      console.log("  workers: " + import_picocolors4.default.dim("none"));
-    } else {
-      const list = Array.from(workerSet).map((sym) => {
-        const file = workerDetails.get(sym);
-        return file ? `${sym} (${file})` : sym;
-      }).join(", ");
-      console.log("  workers: " + list);
-    }
-    console.log("");
-  }
-}
-async function runLiveMode(config, rows, nameFilter) {
-  let renv;
-  try {
-    renv = resolveEnvironment(config);
-  } catch (err) {
-    console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
-    console.log(import_picocolors4.default.yellow(`  \u26A0 Cannot resolve environment: ${err.message}`));
-    return;
-  }
-  const queueProvider = queueForEnv(renv);
-  if (!queueProvider) {
-    console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
-    console.log(
-      import_picocolors4.default.yellow("  \u25CB Redis not configured \u2014 run: ") + import_picocolors4.default.bold("horus connect redis")
-    );
-    return;
-  }
-  let headerPrinted = false;
-  try {
-    const health = await queueProvider.health();
-    if (!health.ok) {
-      console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
-      console.log(import_picocolors4.default.red(`  \u2717 Redis unreachable: ${health.detail}`));
-      return;
-    }
-    const staticNames = new Set(buildQueueMap(rows).keys());
-    let queueNames;
-    if (nameFilter !== void 0) {
-      queueNames = [nameFilter];
-    } else {
-      const discovered = await queueProvider.discoverQueues().catch(() => []);
-      const union2 = /* @__PURE__ */ new Set([...staticNames, ...discovered]);
-      queueNames = union2.size > 0 ? [...union2] : void 0;
-    }
-    const state = await queueProvider.analyzeQueues({ queueNames });
-    const collectedAt = new Date(state.collectedAt).toLocaleTimeString();
-    console.log(
-      import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim(`  \xB7  source: Redis/BullMQ (prefix: ${state.prefix})  \xB7  collected: ${collectedAt}`)
-    );
-    headerPrinted = true;
-    console.log("");
-    if (state.queues.length === 0) {
-      console.log(import_picocolors4.default.dim("  No queues found in Redis."));
-      console.log(
-        import_picocolors4.default.dim(
-          "  If queues exist under a custom prefix, set the BullMQ prefix in your connector config."
-        )
-      );
-      return;
-    }
-    printLiveTable(state.queues, staticNames);
-  } catch (err) {
-    if (!headerPrinted) {
-      console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
-    }
-    console.log(import_picocolors4.default.red(`  \u2717 ${err.message}`));
-  } finally {
-    await queueProvider.close().catch(() => {
-    });
-  }
-}
-function printLiveTable(queues, staticNames = /* @__PURE__ */ new Set()) {
-  const nameWidth = Math.max(10, ...queues.map((q) => q.queueName.length));
-  const numWidth = 7;
-  const header = "  " + "queue".padEnd(nameWidth) + "  " + "waiting".padStart(numWidth) + "  " + "active".padStart(numWidth) + "  " + "failed".padStart(numWidth) + "  " + "delayed".padStart(numWidth) + "  " + "paused".padStart(numWidth);
-  console.log(import_picocolors4.default.dim(header));
-  console.log(import_picocolors4.default.dim("  " + "\u2500".repeat(header.length - 2)));
-  for (const q of queues) {
-    const hasIssue = q.failed > 0 || q.waiting > 100 || q.delayed > 50 || q.isPaused;
-    const color = hasIssue ? import_picocolors4.default.yellow : (s) => s;
-    const row = "  " + q.queueName.padEnd(nameWidth) + "  " + String(q.waiting).padStart(numWidth) + "  " + String(q.active).padStart(numWidth) + "  " + String(q.failed).padStart(numWidth) + "  " + String(q.delayed).padStart(numWidth) + "  " + (q.isPaused ? import_picocolors4.default.yellow("paused") : String(q.paused).padStart(numWidth));
-    console.log(color(row));
-    if (!staticNames.has(q.queueName)) {
-      console.log(import_picocolors4.default.dim("    runtime-only \xB7 no static producer/worker mapping"));
-    }
-    if (q.oldestWaitingMs !== void 0) {
-      const age = formatAge(q.oldestWaitingMs);
-      console.log(import_picocolors4.default.dim(`    oldest waiting: ${age}`));
-    }
-    if (q.failedBreakdown && q.failedBreakdown.length > 0) {
-      for (const { reason, count } of q.failedBreakdown.slice(0, 3)) {
-        console.log(import_picocolors4.default.red(`    \u2717 [${count}x] ${reason}`));
-      }
-    }
-  }
-  console.log("");
-}
-function formatAge(ms) {
-  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
-  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
-  if (ms < 864e5) return `${Math.round(ms / 36e5)}h`;
-  return `${Math.round(ms / 864e5)}d`;
-}
-
-// ../../packages/cli/src/commands/investigate.ts
-init_cjs_shims();
-var import_picocolors5 = __toESM(require_picocolors(), 1);
 
 // ../../packages/ai/src/index.ts
 init_cjs_shims();
@@ -73681,6 +73449,15 @@ var AnthropicNarrativeProvider = class {
     const raw = await this.callApi(prompt);
     return parseOutput(raw, input, ceiling);
   }
+  /**
+   * HOR-211 — generic command-level interpretation. Reuses the same Messages API
+   * call as render(), but with a caller-supplied command prompt (built by
+   * buildInterpretationPrompt) instead of the investigation narrative prompt.
+   * Returns the raw model text; the shared helper handles parsing/rendering.
+   */
+  async interpret(prompt) {
+    return this.callApi(prompt);
+  }
   async callApi(prompt) {
     const response = await fetch(`${this.baseUrl}/v1/messages`, {
       method: "POST",
@@ -73923,8 +73700,445 @@ init_cjs_shims();
 // ../../packages/ai/src/provider-execution.ts
 init_cjs_shims();
 
-// ../../packages/cli/src/commands/investigate.ts
-function extractEvidenceExcerpt(e) {
+// ../../packages/ai/src/interpretation.ts
+init_cjs_shims();
+var INTERPRETATION_GROUNDING_RULES = [
+  "You are interpreting Horus evidence, not gathering new evidence.",
+  "Do not invent files, commits, services, queues, logs, metrics, dashboards, owners, or timestamps.",
+  "Use only the evidence provided above \u2014 any fact not present in it is a hallucination.",
+  'Clearly separate "Evidence used" from "Interpretation".',
+  "State your confidence and call out any missing evidence that would change the conclusion.",
+  "When suggesting next checks, prefer exact follow-up Horus commands."
+];
+var PROMPT_KIND_GUIDANCE = {
+  "change-risk": "Assess which changes carry the most risk and why, ranking by likely impact, grounded only in the evidence.",
+  "timeline-narrative": "Narrate the ordering of changes and evidence into phases; flag suspicious ordering and gaps in coverage.",
+  "blast-radius": "Explain severity, likely user impact, containment, and safe mitigations for the affected dependencies.",
+  "system-explanation": "Explain how this system/subsystem works at onboarding quality, grounded in the evidence.",
+  readiness: "Summarize readiness and risk, then prioritize what to do next before proceeding.",
+  "evidence-summary": "Summarize what the evidence shows. Do not assert a root cause the evidence does not support."
+};
+function stringifyEvidence(evidence2) {
+  if (typeof evidence2 === "string") return evidence2;
+  try {
+    return JSON.stringify(evidence2, null, 2);
+  } catch {
+    return String(evidence2);
+  }
+}
+function buildInterpretationPrompt(req) {
+  const guidance = PROMPT_KIND_GUIDANCE[req.promptKind] ?? PROMPT_KIND_GUIDANCE["evidence-summary"];
+  const evidenceBlock = stringifyEvidence(req.evidence);
+  const rules = INTERPRETATION_GROUNDING_RULES.map((r) => `- ${r}`).join("\n");
+  return `You are the Horus AI interpretation layer for the \`${req.command}\` command.
+Task kind: ${req.promptKind}. ${guidance}
+${req.userIntent ? `
+User intent: ${req.userIntent}
+` : ""}
+Evidence used (this is the ONLY ground truth \u2014 interpret it, do not extend it):
+${evidenceBlock}
+
+Output contract:
+${req.outputContract}
+
+Rules:
+${rules}
+- End with a "Confidence:" line (low | medium | high) and a "Next checks:" list of concrete Horus commands.`;
+}
+async function generateInterpretation(req, provider, opts) {
+  const base2 = {
+    ok: false,
+    command: req.command,
+    promptKind: req.promptKind,
+    ...opts?.model ? { model: opts.model } : {}
+  };
+  if (!provider) {
+    return {
+      ...base2,
+      warning: "No AI provider configured. Run `horus connect ai` or set ANTHROPIC_API_KEY to enable --ai."
+    };
+  }
+  const prompt = buildInterpretationPrompt(req);
+  try {
+    const text2 = (await provider.interpret(prompt))?.trim() ?? "";
+    if (!text2) {
+      return { ...base2, provider: provider.name, warning: "AI provider returned an empty response." };
+    }
+    return {
+      ok: true,
+      command: req.command,
+      promptKind: req.promptKind,
+      provider: provider.name,
+      ...opts?.model ? { model: opts.model } : {},
+      text: text2
+    };
+  } catch (err) {
+    return {
+      ...base2,
+      provider: provider.name,
+      warning: `AI interpretation failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function renderInterpretation(result) {
+  const attribution = result.model ? ` (${result.provider ?? "ai"}, ${result.model})` : result.provider ? ` (${result.provider})` : "";
+  const header = `\u2500\u2500 AI Interpretation${attribution} \u2500\u2500`;
+  if (!result.ok) {
+    return `${header}
+${result.warning ?? "AI interpretation unavailable."}`;
+  }
+  return `${header}
+${result.text ?? ""}`;
+}
+
+// ../../packages/cli/src/lib/ai-provider.ts
+init_cjs_shims();
+var DEFAULT_MODEL = "claude-opus-4-8";
+async function resolveAiCredentials(opts) {
+  let apiKey;
+  let savedModel;
+  try {
+    const config = await loadConfig(opts.config);
+    const ai = resolveAiSettings(config);
+    apiKey = ai.anthropicApiKey;
+    savedModel = ai.model;
+  } catch {
+  }
+  apiKey = apiKey ?? process.env["ANTHROPIC_API_KEY"] ?? void 0;
+  return { apiKey, model: opts.modelOverride ?? savedModel ?? DEFAULT_MODEL };
+}
+async function buildNarrativeProvider(opts) {
+  let apiKey;
+  let savedModel;
+  try {
+    const config = await loadConfig(opts.config);
+    const ai = resolveAiSettings(config);
+    apiKey = ai.anthropicApiKey;
+    savedModel = ai.model;
+  } catch {
+  }
+  const model = opts.modelOverride ?? savedModel ?? DEFAULT_MODEL;
+  const provider = new AnthropicNarrativeProvider({
+    model,
+    ...apiKey !== void 0 ? { apiKey } : {}
+  });
+  return { provider, model };
+}
+async function renderAiInterpretation(opts) {
+  const { config, modelOverride, provider: injected, command, evidence: evidence2, promptKind, outputContract, userIntent } = opts;
+  const request = {
+    command,
+    evidence: evidence2,
+    promptKind,
+    outputContract,
+    ...userIntent ? { userIntent } : {}
+  };
+  if (injected) {
+    return generateInterpretation(request, injected);
+  }
+  const { apiKey, model } = await resolveAiCredentials({ config, modelOverride });
+  if (!apiKey) {
+    return generateInterpretation(request, null, { model });
+  }
+  const provider = new AnthropicNarrativeProvider({ model, apiKey });
+  return generateInterpretation(request, provider, { model });
+}
+
+// ../../packages/cli/src/commands/queues.ts
+var QUEUES_AI_CONTRACT = `Provide a clearly separated AI evidence narration with:
+
+Evidence used
+- Queue names, waiting/active/failed/delayed counts, and producer/worker mappings Horus found
+
+What stands out
+- Queues with high failed counts, unexpected backlog, or paused state
+- Runtime-only queues (live in Redis, no static producer/worker mapping)
+- Producer/worker mismatches or orphaned queues
+
+What this may indicate
+- Use "may suggest", "is consistent with", or "could indicate" \u2014 never "proves"
+- Do not invent queue names, Redis keys, or job data not in the evidence
+
+What is not proven
+- Claims about job contents, specific error messages, or data inside failed jobs
+
+Next checks
+- Exact Horus commands or Redis/BullMQ checks to inspect next`;
+async function runQueues(name, opts) {
+  try {
+    const config = await loadConfig(opts.config, { name: opts.name });
+    const { db, sql: sql2 } = createDb(config.database.url);
+    try {
+      let project = opts.project;
+      if (project === void 0) {
+        try {
+          project = resolveEnvironment(config, { project: opts.project }).project;
+        } catch {
+        }
+      }
+      const rows = await listQueueEdges(db, { project, queueName: name });
+      if (opts.json) {
+        const topology = topologyToJson(buildQueueMap(rows));
+        const out = { project: project ?? null, topology };
+        if (opts.live) out["live"] = await gatherLiveState(config, rows, name);
+        console.log(JSON.stringify(out, null, 2));
+        return 0;
+      }
+      console.log(
+        import_picocolors4.default.bold("Queue topology") + import_picocolors4.default.dim("  \xB7  source: code / source intelligence  \xB7  static (run horus index to refresh)")
+      );
+      console.log("");
+      if (rows.length === 0) {
+        console.log(import_picocolors4.default.dim("  No queue edges indexed. Run: horus index"));
+      } else {
+        const byQueue = buildQueueMap(rows);
+        printTopology(byQueue);
+      }
+      console.log("");
+      if (opts.live) {
+        await runLiveMode(config, rows, name, opts.ai ? {
+          config: opts.config,
+          aiModel: opts.aiModel,
+          _aiProvider: opts._aiProvider
+        } : void 0);
+      } else {
+        console.log(
+          import_picocolors4.default.dim(
+            "  Tip: run horus queues --live to show real-time Redis/BullMQ depths and failed-job counts."
+          )
+        );
+        if (opts.ai) {
+          console.log(import_picocolors4.default.dim("  Tip: --ai is most useful with --live (horus queues --live --ai)."));
+        }
+      }
+    } finally {
+      await sql2.end();
+    }
+    return 0;
+  } catch (err) {
+    console.error(import_picocolors4.default.red(err.message));
+    return 1;
+  }
+}
+function buildQueueMap(rows) {
+  const byQueue = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const existing = byQueue.get(row.queueName);
+    if (existing) {
+      existing.push(row);
+    } else {
+      byQueue.set(row.queueName, [row]);
+    }
+  }
+  return byQueue;
+}
+function endpoints(edges, symKey, fileKey) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const symbol = e[symKey];
+    if (!symbol) continue;
+    if (!seen.has(symbol)) seen.set(symbol, { symbol, file: e[fileKey] ?? null });
+  }
+  return [...seen.values()];
+}
+function topologyToJson(byQueue) {
+  return [...byQueue.entries()].map(([queueName, edges]) => ({
+    queueName,
+    producers: endpoints(edges, "producerSymbol", "producerFile"),
+    workers: endpoints(edges, "workerSymbol", "workerFile")
+  }));
+}
+async function gatherLiveState(config, rows, nameFilter) {
+  let renv;
+  try {
+    renv = resolveEnvironment(config);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const queueProvider = queueForEnv(renv);
+  if (!queueProvider) return { ok: false, error: "Redis not configured" };
+  try {
+    const health = await queueProvider.health();
+    if (!health.ok) return { ok: false, error: health.detail };
+    const staticNames = new Set(buildQueueMap(rows).keys());
+    let queueNames;
+    if (nameFilter !== void 0) {
+      queueNames = [nameFilter];
+    } else {
+      const discovered = await queueProvider.discoverQueues().catch(() => []);
+      const union2 = /* @__PURE__ */ new Set([...staticNames, ...discovered]);
+      queueNames = union2.size > 0 ? [...union2] : void 0;
+    }
+    const state = await queueProvider.analyzeQueues({ queueNames });
+    return {
+      ok: true,
+      prefix: state.prefix,
+      collectedAt: state.collectedAt,
+      queues: state.queues.map((q) => ({ ...q, runtimeOnly: !staticNames.has(q.queueName) }))
+    };
+  } finally {
+    await queueProvider.close().catch(() => {
+    });
+  }
+}
+function printTopology(byQueue) {
+  for (const [queueName, edges] of byQueue) {
+    console.log(import_picocolors4.default.bold(queueName));
+    const producerSet = /* @__PURE__ */ new Set();
+    const producerDetails = /* @__PURE__ */ new Map();
+    for (const edge of edges) {
+      if (edge.producerSymbol) {
+        producerSet.add(edge.producerSymbol);
+        if (edge.producerFile) producerDetails.set(edge.producerSymbol, edge.producerFile);
+      }
+    }
+    if (producerSet.size === 0) {
+      console.log("  producers: " + import_picocolors4.default.dim("none"));
+    } else {
+      const list = Array.from(producerSet).map((sym) => {
+        const file = producerDetails.get(sym);
+        return file ? `${sym} (${file})` : sym;
+      }).join(", ");
+      console.log("  producers: " + list);
+    }
+    const workerSet = /* @__PURE__ */ new Set();
+    const workerDetails = /* @__PURE__ */ new Map();
+    for (const edge of edges) {
+      if (edge.workerSymbol) {
+        workerSet.add(edge.workerSymbol);
+        if (edge.workerFile) workerDetails.set(edge.workerSymbol, edge.workerFile);
+      }
+    }
+    if (workerSet.size === 0) {
+      console.log("  workers: " + import_picocolors4.default.dim("none"));
+    } else {
+      const list = Array.from(workerSet).map((sym) => {
+        const file = workerDetails.get(sym);
+        return file ? `${sym} (${file})` : sym;
+      }).join(", ");
+      console.log("  workers: " + list);
+    }
+    console.log("");
+  }
+}
+async function runLiveMode(config, rows, nameFilter, aiOpts) {
+  let renv;
+  try {
+    renv = resolveEnvironment(config);
+  } catch (err) {
+    console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
+    console.log(import_picocolors4.default.yellow(`  \u26A0 Cannot resolve environment: ${err.message}`));
+    return;
+  }
+  const queueProvider = queueForEnv(renv);
+  if (!queueProvider) {
+    console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
+    console.log(
+      import_picocolors4.default.yellow("  \u25CB Redis not configured \u2014 run: ") + import_picocolors4.default.bold("horus connect redis")
+    );
+    return;
+  }
+  let headerPrinted = false;
+  try {
+    const health = await queueProvider.health();
+    if (!health.ok) {
+      console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
+      console.log(import_picocolors4.default.red(`  \u2717 Redis unreachable: ${health.detail}`));
+      return;
+    }
+    const staticNames = new Set(buildQueueMap(rows).keys());
+    let queueNames;
+    if (nameFilter !== void 0) {
+      queueNames = [nameFilter];
+    } else {
+      const discovered = await queueProvider.discoverQueues().catch(() => []);
+      const union2 = /* @__PURE__ */ new Set([...staticNames, ...discovered]);
+      queueNames = union2.size > 0 ? [...union2] : void 0;
+    }
+    const state = await queueProvider.analyzeQueues({ queueNames });
+    const collectedAt = new Date(state.collectedAt).toLocaleTimeString();
+    console.log(
+      import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim(`  \xB7  source: Redis/BullMQ (prefix: ${state.prefix})  \xB7  collected: ${collectedAt}`)
+    );
+    headerPrinted = true;
+    console.log("");
+    if (state.queues.length === 0) {
+      console.log(import_picocolors4.default.dim("  No queues found in Redis."));
+      console.log(
+        import_picocolors4.default.dim(
+          "  If queues exist under a custom prefix, set the BullMQ prefix in your connector config."
+        )
+      );
+      return;
+    }
+    printLiveTable(state.queues, staticNames);
+    if (aiOpts) {
+      const evidence2 = {
+        prefix: state.prefix,
+        collectedAt: state.collectedAt,
+        queues: state.queues.map((q) => ({ ...q, runtimeOnly: !staticNames.has(q.queueName) }))
+      };
+      const result = await renderAiInterpretation({
+        command: "queues",
+        evidence: evidence2,
+        promptKind: "evidence-summary",
+        outputContract: QUEUES_AI_CONTRACT,
+        config: aiOpts.config,
+        modelOverride: aiOpts.aiModel,
+        provider: aiOpts._aiProvider
+      });
+      console.log("\n" + renderInterpretation(result));
+      if (!result.ok) {
+        console.error(import_picocolors4.default.yellow(`[ai] ${result.warning}`));
+      }
+    }
+  } catch (err) {
+    if (!headerPrinted) {
+      console.log(import_picocolors4.default.bold("Live queue state") + import_picocolors4.default.dim("  \xB7  source: Redis/BullMQ"));
+    }
+    console.log(import_picocolors4.default.red(`  \u2717 ${err.message}`));
+  } finally {
+    await queueProvider.close().catch(() => {
+    });
+  }
+}
+function printLiveTable(queues, staticNames = /* @__PURE__ */ new Set()) {
+  const nameWidth = Math.max(10, ...queues.map((q) => q.queueName.length));
+  const numWidth = 7;
+  const header = "  " + "queue".padEnd(nameWidth) + "  " + "waiting".padStart(numWidth) + "  " + "active".padStart(numWidth) + "  " + "failed".padStart(numWidth) + "  " + "delayed".padStart(numWidth) + "  " + "paused".padStart(numWidth);
+  console.log(import_picocolors4.default.dim(header));
+  console.log(import_picocolors4.default.dim("  " + "\u2500".repeat(header.length - 2)));
+  for (const q of queues) {
+    const hasIssue = q.failed > 0 || q.waiting > 100 || q.delayed > 50 || q.isPaused;
+    const color = hasIssue ? import_picocolors4.default.yellow : (s) => s;
+    const row = "  " + q.queueName.padEnd(nameWidth) + "  " + String(q.waiting).padStart(numWidth) + "  " + String(q.active).padStart(numWidth) + "  " + String(q.failed).padStart(numWidth) + "  " + String(q.delayed).padStart(numWidth) + "  " + (q.isPaused ? import_picocolors4.default.yellow("paused") : String(q.paused).padStart(numWidth));
+    console.log(color(row));
+    if (!staticNames.has(q.queueName)) {
+      console.log(import_picocolors4.default.dim("    runtime-only \xB7 no static producer/worker mapping"));
+    }
+    if (q.oldestWaitingMs !== void 0) {
+      const age = formatAge(q.oldestWaitingMs);
+      console.log(import_picocolors4.default.dim(`    oldest waiting: ${age}`));
+    }
+    if (q.failedBreakdown && q.failedBreakdown.length > 0) {
+      for (const { reason, count } of q.failedBreakdown.slice(0, 3)) {
+        console.log(import_picocolors4.default.red(`    \u2717 [${count}x] ${reason}`));
+      }
+    }
+  }
+  console.log("");
+}
+function formatAge(ms) {
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  if (ms < 864e5) return `${Math.round(ms / 36e5)}h`;
+  return `${Math.round(ms / 864e5)}d`;
+}
+
+// ../../packages/cli/src/commands/investigate.ts
+init_cjs_shims();
+var import_picocolors5 = __toESM(require_picocolors(), 1);
+function extractEvidenceExcerpt(e) {
   if (!e.payload || typeof e.payload !== "object") return void 0;
   const p = e.payload;
   const candidate = (typeof p["pattern"] === "string" ? p["pattern"] : null) ?? (typeof p["message"] === "string" ? p["message"] : null) ?? (typeof p["label"] === "string" ? p["label"] : null) ?? (typeof p["summary"] === "string" ? p["summary"] : null) ?? (typeof p["valueLabel"] === "string" ? p["valueLabel"] : null);
@@ -74081,7 +74295,9 @@ async function runInvestigate(hint, opts) {
             elasticsearch: !!renv.connectors.elasticsearch?.url,
             grafana: !!renv.connectors.grafana?.url,
             mongodb: !!renv.connectors.mongodb?.url,
-            redis: !!renv.connectors.redis?.url
+            redis: !!renv.connectors.redis?.url,
+            // Queue runtime is configured iff a BullMQ provider was built (HOR-205).
+            queue: !!queue
           }
         }
       );
@@ -74146,6 +74362,23 @@ async function runInvestigate(hint, opts) {
 // ../../packages/cli/src/commands/changes.ts
 init_cjs_shims();
 var import_picocolors6 = __toESM(require_picocolors(), 1);
+var CHANGES_AI_CONTRACT = `Provide a clearly separated AI change-impact review with:
+
+Highest-risk changes
+- Files, symbols, or flows most likely to matter for correctness or stability
+- Explain why based on affected flows and change types (added/removed/modified)
+
+Review focus
+- What the reviewer should inspect first
+- Specific symbols or files worth extra attention
+
+Testing suggestions
+- Specific smoke tests or checks based on affected flows
+- Only reference flows and symbols Horus found
+
+Confidence / gaps
+- Where Horus evidence is strong (full flow coverage)
+- What is missing (e.g. no affected flows found \u2014 no source index, or no matching flows)`;
 async function runChanges(base2, compare, opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74158,7 +74391,27 @@ async function runChanges(base2, compare, opts) {
       return 1;
     }
     const report = await changeImpact({ base: base2, compare }, { code });
-    console.log(opts.json ? changeImpactToJSON(report) : renderChangeImpact(report));
+    if (opts.json) {
+      console.log(changeImpactToJSON(report));
+    } else {
+      console.log(renderChangeImpact(report));
+      if (opts.ai) {
+        const result = await renderAiInterpretation({
+          command: "changes",
+          userIntent: `base: ${base2}, compare: ${compare ?? "HEAD"}`,
+          evidence: report,
+          promptKind: "change-risk",
+          outputContract: CHANGES_AI_CONTRACT,
+          config: opts.config,
+          modelOverride: opts.aiModel,
+          provider: opts._aiProvider
+        });
+        console.log("\n" + renderInterpretation(result));
+        if (!result.ok) {
+          console.error(import_picocolors6.default.yellow(`[ai] ${result.warning}`));
+        }
+      }
+    }
     return 0;
   } catch (err) {
     console.error(import_picocolors6.default.red(err.message));
@@ -74175,6 +74428,22 @@ function resolveTimelineWindow(opts) {
   const since = opts.all ? void 0 : opts.since ?? DEFAULT_SINCE;
   return { since, usingDefault };
 }
+var TIMELINE_AI_CONTRACT = `Provide a clearly separated AI interpretation section with:
+
+Evidence used
+- List the timeline events, commits, and change-impact signals Horus found
+
+Narrative
+- Group events into phases (e.g. pre-change, change window, symptom onset, recovery)
+- Highlight any suspicious ordering (e.g. a change immediately before first error)
+- Note what happened before vs. after the first symptom if identifiable
+
+Confidence
+- High / Medium / Low with a one-line reason
+
+Gaps / Next checks
+- Missing evidence dimensions (logs, metrics, traces, etc.)
+- Exact Horus commands to fill the gaps`;
 async function runTimeline(service, opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74203,6 +74472,22 @@ async function runTimeline(service, opts) {
           )
         );
       }
+      if (opts.ai) {
+        const result = await renderAiInterpretation({
+          command: "timeline",
+          userIntent: service ? `service: ${service}` : void 0,
+          evidence: t,
+          promptKind: "timeline-narrative",
+          outputContract: TIMELINE_AI_CONTRACT,
+          config: opts.config,
+          modelOverride: opts.aiModel,
+          provider: opts._aiProvider
+        });
+        console.log("\n" + renderInterpretation(result));
+        if (!result.ok) {
+          console.error(import_picocolors7.default.yellow(`[ai] ${result.warning}`));
+        }
+      }
     }
     return 0;
   } catch (err) {
@@ -74215,6 +74500,21 @@ async function runTimeline(service, opts) {
 init_cjs_shims();
 var import_picocolors8 = __toESM(require_picocolors(), 1);
 var DEFAULT_SINCE2 = "7 days ago";
+var WHAT_CHANGED_AI_CONTRACT = `Provide a clearly separated AI interpretation section with:
+
+Evidence used
+- List the concrete changes/files/commits/timestamps Horus found
+
+Interpretation
+- Which change(s) look most incident-relevant and why
+- Which changes are likely noise and why
+- Any suspicious ordering or coverage gaps
+
+Confidence
+- High / Medium / Low with a one-line reason
+
+Next checks
+- Exact Horus commands or files to inspect next`;
 async function runWhatChanged(service, opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74232,6 +74532,22 @@ async function runWhatChanged(service, opts) {
       { code }
     );
     console.log(opts.json ? whatChangedToJSON(r) : renderWhatChanged(r));
+    if (opts.ai && !opts.json) {
+      const result = await renderAiInterpretation({
+        command: "what-changed",
+        userIntent: service ? `service: ${service}` : void 0,
+        evidence: r,
+        promptKind: "change-risk",
+        outputContract: WHAT_CHANGED_AI_CONTRACT,
+        config: opts.config,
+        modelOverride: opts.aiModel,
+        provider: opts._aiProvider
+      });
+      console.log("\n" + renderInterpretation(result));
+      if (!result.ok) {
+        console.error(import_picocolors8.default.yellow(`[ai] ${result.warning}`));
+      }
+    }
     return 0;
   } catch (err) {
     console.error(import_picocolors8.default.red(err.message));
@@ -74242,6 +74558,27 @@ async function runWhatChanged(service, opts) {
 // ../../packages/cli/src/commands/architecture.ts
 init_cjs_shims();
 var import_picocolors9 = __toESM(require_picocolors(), 1);
+var ARCHITECTURE_AI_CONTRACT = `Provide a clearly separated AI interpretation section with:
+
+System summary
+- What the system appears to do based on subsystems, external systems, and key flows Horus found
+- Major subsystems and their responsibilities
+
+Critical paths
+- Important flows and async boundaries found by Horus
+- Queues, workers, and external API touch points
+
+Fragility / risk points
+- Areas where coupling, queues, external systems, or unclear ownership create risk
+- Refer only to components and boundaries Horus discovered
+
+How to investigate this system
+- Useful Horus commands to explore further (blast-radius, investigate, timeline, etc.)
+- Specific files or symbols worth inspecting
+
+Confidence / gaps
+- Where Horus evidence was strong (e.g. indexed source, queue edges)
+- What evidence is missing and what to do to fill those gaps`;
 async function runArchitecture(opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74261,7 +74598,26 @@ async function runArchitecture(opts) {
     const { db, sql: sql2 } = createDb(config.database.url);
     try {
       const m = await discoverArchitecture({ code, db, project });
-      console.log(opts.json ? architectureToJSON(m) : renderArchitecture(m));
+      if (opts.json) {
+        console.log(architectureToJSON(m));
+      } else {
+        console.log(renderArchitecture(m));
+        if (opts.ai) {
+          const result = await renderAiInterpretation({
+            command: "architecture",
+            evidence: m,
+            promptKind: "system-explanation",
+            outputContract: ARCHITECTURE_AI_CONTRACT,
+            config: opts.config,
+            modelOverride: opts.aiModel,
+            provider: opts._aiProvider
+          });
+          console.log("\n" + renderInterpretation(result));
+          if (!result.ok) {
+            console.error(import_picocolors9.default.yellow(`[ai] ${result.warning}`));
+          }
+        }
+      }
     } finally {
       await sql2.end();
     }
@@ -74275,6 +74631,26 @@ async function runArchitecture(opts) {
 // ../../packages/cli/src/commands/blast-radius.ts
 init_cjs_shims();
 var import_picocolors10 = __toESM(require_picocolors(), 1);
+var BLAST_RADIUS_AI_CONTRACT = `Provide a clearly separated AI interpretation section with:
+
+Evidence used
+- The matched component(s), upstream dependencies, downstream callers, and async boundaries Horus found
+
+Likely impact
+- What users or operators would notice if this component fails
+- Which services/flows are inside the blast radius and at direct risk
+- Which services/flows appear outside the blast radius
+
+Containment ideas
+- Safe mitigations grounded only in the dependencies Horus found
+- Rollback or disable suggestions only when supported by the evidence (prefix with "verify before doing this")
+- Async boundaries to isolate (queues, workers, cron jobs, webhooks, external APIs)
+
+Confidence
+- High / Medium / Low with a one-line reason
+
+Next checks
+- Exact Horus commands or files to inspect next`;
 async function runBlastRadius(query, opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74302,7 +74678,27 @@ async function runBlastRadius(query, opts) {
           import_picocolors10.default.yellow(`  No exact match for "${query}"`) + import_picocolors10.default.dim(` \u2014 showing closest: "${r.seed.name}" (fuzzy match)`)
         );
       }
-      console.log(opts.json ? blastRadiusToJSON(r) : renderBlastRadius(r));
+      if (opts.json) {
+        console.log(blastRadiusToJSON(r));
+      } else {
+        console.log(renderBlastRadius(r));
+        if (opts.ai) {
+          const result = await renderAiInterpretation({
+            command: "blast-radius",
+            userIntent: `query: ${query}`,
+            evidence: r,
+            promptKind: "blast-radius",
+            outputContract: BLAST_RADIUS_AI_CONTRACT,
+            config: opts.config,
+            modelOverride: opts.aiModel,
+            provider: opts._aiProvider
+          });
+          console.log("\n" + renderInterpretation(result));
+          if (!result.ok) {
+            console.error(import_picocolors10.default.yellow(`[ai] ${result.warning}`));
+          }
+        }
+      }
     } finally {
       await sql2.end();
     }
@@ -74454,7 +74850,10 @@ async function runReplay(id, opts) {
         console.log(import_picocolors13.default.dim("[ai] Stored judgment replayed. Use --refresh-ai to regenerate."));
       } else {
         const narrativeInput = buildNarrativeInput(report);
-        const provider = new AnthropicNarrativeProvider({ model: opts.aiModel });
+        const { provider } = await buildNarrativeProvider({
+          config: opts.config,
+          modelOverride: opts.aiModel
+        });
         const { output, fromProvider, degraded, validationErrors } = await renderNarrative(
           narrativeInput,
           { provider }
@@ -74574,7 +74973,10 @@ async function runPostmortem(id, opts) {
         }
       } else {
         const narrativeInput = buildNarrativeInput(report);
-        const provider = new AnthropicNarrativeProvider({ model: opts.aiModel });
+        const { provider } = await buildNarrativeProvider({
+          config: opts.config,
+          modelOverride: opts.aiModel
+        });
         const { output, fromProvider, degraded, validationErrors } = await renderNarrative(
           narrativeInput,
           { provider }
@@ -74655,6 +75057,19 @@ _AI summary unavailable: ${validationErrors?.[0] ?? "provider error"}_
 // ../../packages/cli/src/commands/score.ts
 init_cjs_shims();
 var import_picocolors16 = __toESM(require_picocolors(), 1);
+var SCORE_AI_CONTRACT = `Provide a clearly separated AI score explanation with:
+
+Why this scored this way
+- Explain each weak dimension (low value, low weight contribution)
+- Ground each explanation in what Horus found or failed to find
+
+Biggest improvement lever
+- The single dimension where better evidence would move the score most
+- Exact investigation step or command to gather that evidence
+
+Suggested improvements
+- Specific ideas for how Horus could gather better evidence next time
+- Be concrete: what connector, query, or signal is missing`;
 async function runScore(id, opts) {
   const { db, sql: sql2 } = createDb(await resolveDbUrl(opts.config));
   try {
@@ -74668,7 +75083,27 @@ async function runScore(id, opts) {
       return 1;
     }
     const s = scoreInvestigation(migrateReport(row.report));
-    console.log(opts.json ? scoreToJSON(s) : renderScore(s));
+    if (opts.json) {
+      console.log(scoreToJSON(s));
+    } else {
+      console.log(renderScore(s));
+      if (opts.ai) {
+        const result = await renderAiInterpretation({
+          command: "score",
+          userIntent: `investigation: ${id}`,
+          evidence: s,
+          promptKind: "evidence-summary",
+          outputContract: SCORE_AI_CONTRACT,
+          config: opts.config,
+          modelOverride: opts.aiModel,
+          provider: opts._aiProvider
+        });
+        console.log("\n" + renderInterpretation(result));
+        if (!result.ok) {
+          console.error(import_picocolors16.default.yellow(`[ai] ${result.warning}`));
+        }
+      }
+    }
   } finally {
     await sql2.end();
   }
@@ -74755,6 +75190,26 @@ async function runAsk(id, directive, opts) {
 // ../../packages/cli/src/commands/onboard.ts
 init_cjs_shims();
 var import_picocolors18 = __toESM(require_picocolors(), 1);
+var ONBOARD_AI_CONTRACT = `Provide a clearly separated AI onboarding guide with:
+
+Start here
+- Files and components a new engineer should read first (only those Horus found)
+- Entry points, controllers, workers, or queue producers most relevant to the area
+
+Mental model
+- How this area works in plain language, grounded in what Horus discovered
+- Key data flows and async handoffs
+
+What breaks here
+- Common failure modes based on discovered components, async boundaries, and past incidents
+- Frame each as "if X fails, then Y" using only evidence Horus found
+
+Useful commands
+- Exact Horus commands to continue exploring this area
+
+Confidence / gaps
+- What Horus knows confidently (indexed source, queue edges, past incidents)
+- What is missing and would require manual inspection or a broader index`;
 async function runOnboard(area, opts) {
   try {
     const config = await loadConfig(opts.config);
@@ -74780,7 +75235,27 @@ async function runOnboard(area, opts) {
         { area },
         { code, db, repoPath: repo.path, project: renv.project }
       );
-      console.log(opts.json ? onboardingToJSON(g) : renderOnboarding(g));
+      if (opts.json) {
+        console.log(onboardingToJSON(g));
+      } else {
+        console.log(renderOnboarding(g));
+        if (opts.ai) {
+          const result = await renderAiInterpretation({
+            command: "onboard",
+            userIntent: area ? `area: ${area}` : void 0,
+            evidence: g,
+            promptKind: "system-explanation",
+            outputContract: ONBOARD_AI_CONTRACT,
+            config: opts.config,
+            modelOverride: opts.aiModel,
+            provider: opts._aiProvider
+          });
+          console.log("\n" + renderInterpretation(result));
+          if (!result.ok) {
+            console.error(import_picocolors18.default.yellow(`[ai] ${result.warning}`));
+          }
+        }
+      }
     } finally {
       await sql2.end();
     }
@@ -74846,6 +75321,24 @@ async function runSimulate(scenarioId, opts) {
 // ../../packages/cli/src/commands/logs.ts
 init_cjs_shims();
 var import_picocolors20 = __toESM(require_picocolors(), 1);
+var LOGS_AI_CONTRACT = `Provide a clearly separated AI evidence narration with:
+
+Evidence used
+- Exact error signatures, counts, first/last timestamps, and affected services Horus found
+
+What stands out
+- The most frequent or newest signatures
+- Services appearing disproportionately across signatures
+
+What this may indicate
+- Use "may suggest", "is consistent with", or "could indicate" \u2014 not "proves" or "caused by"
+- Correlation hints only (e.g. "the spike overlaps with the deployment window")
+
+What is not proven
+- Claims that cannot be made from error logs alone (root cause, user impact, fix)
+
+Next checks
+- Exact Horus commands, dashboards, or files to inspect next`;
 function sinceToIso(since) {
   if (since === void 0) return void 0;
   const match = /^(\d+)(m|h|d)$/.exec(since);
@@ -75050,6 +75543,27 @@ async function runLogs(service, opts) {
     }
     console.log("");
     console.log(import_picocolors20.default.dim("  (use --raw to see individual log lines)"));
+    if (opts.ai) {
+      const result = await renderAiInterpretation({
+        command: "logs",
+        userIntent: scopeService ? `service: ${scopeService}` : void 0,
+        evidence: {
+          totalErrors: analysis.totalErrors,
+          signatures: analysis.signatures,
+          newSignatures: analysis.newSignatures,
+          affectedServices: analysis.affectedServices
+        },
+        promptKind: "evidence-summary",
+        outputContract: LOGS_AI_CONTRACT,
+        config: opts.config,
+        modelOverride: opts.aiModel,
+        provider: opts._aiProvider
+      });
+      console.log("\n" + renderInterpretation(result));
+      if (!result.ok) {
+        console.error(import_picocolors20.default.yellow(`[ai] ${result.warning}`));
+      }
+    }
     return 0;
   } catch (err) {
     console.error(import_picocolors20.default.red(err.message));
@@ -75060,6 +75574,24 @@ async function runLogs(service, opts) {
 // ../../packages/cli/src/commands/metrics.ts
 init_cjs_shims();
 var import_picocolors21 = __toESM(require_picocolors(), 1);
+var METRICS_AI_CONTRACT = `Provide a clearly separated AI evidence narration with:
+
+Evidence used
+- Exact panel names, anomaly types, baseline vs. current values, and ratios Horus found
+
+What stands out
+- The most severe or highest-ratio anomalies
+- Any metric dimensions with correlated movement (e.g. error rate + latency both spiking)
+
+What this may indicate
+- Use "may suggest", "is consistent with", or "could indicate" \u2014 never "proves"
+- Do not invent dashboard panels or panel names not in the evidence
+
+What is not proven
+- Claims that cannot be made from metric anomalies alone (root cause, data loss, user scope)
+
+Next checks
+- Exact Horus commands or Grafana dashboards to inspect next`;
 function nowSecs() {
   return Math.floor(Date.now() / 1e3);
 }
@@ -75222,6 +75754,22 @@ async function runMetrics(hint, opts) {
       console.log("");
       console.log(import_picocolors21.default.dim(`  ${ok.length} panel series with no anomaly.`));
     }
+    if (opts.ai) {
+      const result = await renderAiInterpretation({
+        command: "metrics",
+        userIntent: hint ? `hint: ${hint}` : void 0,
+        evidence: findings2,
+        promptKind: "evidence-summary",
+        outputContract: METRICS_AI_CONTRACT,
+        config: opts.config,
+        modelOverride: opts.aiModel,
+        provider: opts._aiProvider
+      });
+      console.log("\n" + renderInterpretation(result));
+      if (!result.ok) {
+        console.error(import_picocolors21.default.yellow(`[ai] ${result.warning}`));
+      }
+    }
     return 0;
   } catch (err) {
     console.error(import_picocolors21.default.red(err.message));
@@ -75232,6 +75780,24 @@ async function runMetrics(hint, opts) {
 // ../../packages/cli/src/commands/state.ts
 init_cjs_shims();
 var import_picocolors22 = __toESM(require_picocolors(), 1);
+var STATE_AI_CONTRACT = `Provide a clearly separated AI evidence narration with:
+
+Evidence used
+- Exact collection names, document counts, staleness hours, and anomalous status values Horus found
+
+What stands out
+- Collections with stale records or anomalous status distributions
+- Any counts that seem unusually low or high
+
+What this may indicate
+- Use "may suggest", "is consistent with", or "could indicate" \u2014 never "proves"
+- Do not infer private data or claim access to document contents
+
+What is not proven
+- Claims that require reading actual document content or non-allowlisted collections
+
+Next checks
+- Exact Horus commands or database queries to inspect next`;
 async function runState(opts) {
   try {
     const config = await loadConfig(opts.config, { name: opts.name });
@@ -75316,6 +75882,21 @@ async function runState(opts) {
           );
         }
       }
+      if (opts.ai) {
+        const result = await renderAiInterpretation({
+          command: "state",
+          evidence: analysis,
+          promptKind: "evidence-summary",
+          outputContract: STATE_AI_CONTRACT,
+          config: opts.config,
+          modelOverride: opts.aiModel,
+          provider: opts._aiProvider
+        });
+        console.log("\n" + renderInterpretation(result));
+        if (!result.ok) {
+          console.error(import_picocolors22.default.yellow(`[ai] ${result.warning}`));
+        }
+      }
       return 0;
     } finally {
       await mongo.close();
@@ -77083,6 +77664,26 @@ async function runGenerateConfig(opts) {
 // ../../packages/cli/src/commands/readiness.ts
 init_cjs_shims();
 var import_picocolors34 = __toESM(require_picocolors(), 1);
+var READINESS_AI_CONTRACT = `Provide a clearly separated AI readiness summary with:
+
+Overall assessment
+- Release/demo readiness in plain language (Ready / Partially ready / Not ready)
+- One sentence explaining why
+
+Blockers
+- Each failing blocking check and what it means operationally
+- Only reference checks that Horus found failing
+
+Risks
+- Non-blocking warnings that could limit investigation depth or demo quality
+- Prioritize by likely impact
+
+Recommended next action
+- The single most impactful step to take right now
+- Exact command or config change based on the checks above
+
+Confidence / gaps
+- Which checks Horus could verify vs. which require manual confirmation`;
 var DEFAULT_DB_URL5 = "postgresql://horus:horus@localhost:5433/horus";
 function mark3(status) {
   if (status === "pass") return import_picocolors34.default.green("\u2713");
@@ -77280,6 +77881,21 @@ async function runReadiness(opts) {
     write(import_picocolors34.default.dim("  Re-run `horus readiness` after resolving the items above."));
   }
   write("");
+  if (opts?.ai) {
+    const result = await renderAiInterpretation({
+      command: "readiness",
+      evidence: checks,
+      promptKind: "readiness",
+      outputContract: READINESS_AI_CONTRACT,
+      config: opts.config,
+      modelOverride: opts.aiModel,
+      provider: opts._aiProvider
+    });
+    console.log("\n" + renderInterpretation(result));
+    if (!result.ok) {
+      console.error(import_picocolors34.default.yellow(`[ai] ${result.warning}`));
+    }
+  }
   return blockingFails.length > 0 ? 1 : 0;
 }
 
@@ -77323,8 +77939,8 @@ Examples:
   program2.command("generate-config").description("Create a starter horus.config.js with placeholders (HOR-90)").option("--out <path>", "output path (default: horus.config.js in cwd)").option("--name <name>", "project name placeholder (default: my-project)").option("--repo <path>", "repository path placeholder (default: /path/to/<name>)").option("--force", "overwrite an existing config file").action(async (opts) => {
     process.exitCode = await runGenerateConfig(opts);
   });
-  program2.command("readiness").description("Summarize release/demo readiness: DB, source intelligence, connectors, and local config (HOR-97)").option("-c, --config <path>", "path to horus.config.js").action(async (opts) => {
-    process.exitCode = await runReadiness({ config: opts.config });
+  program2.command("readiness").description("Summarize release/demo readiness: DB, source intelligence, connectors, and local config (HOR-97)").option("-c, --config <path>", "path to horus.config.js").option("--ai", "append AI readiness summary and recommended next action").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(async (opts) => {
+    process.exitCode = await runReadiness({ config: opts.config, ai: opts.ai, aiModel: opts.aiModel });
   });
   program2.command("connect <type>").description(
     "Add or update a connector (elasticsearch / mongodb / grafana / redis / ai) in .horus/config.json"
@@ -77391,14 +78007,16 @@ Examples:
       process.exitCode = await runIndex(opts);
     }
   );
-  program2.command("queues [name]").description("Show queue topology from source intelligence; --live adds real-time Redis/BullMQ state").option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via registry)").option("--project <name>", "filter edges by project").option("--live", "fetch real-time queue depths and failed-job counts from Redis/BullMQ").option("--json", "output JSON").action(
+  program2.command("queues [name]").description("Show queue topology from source intelligence; --live adds real-time Redis/BullMQ state").option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via registry)").option("--project <name>", "filter edges by project").option("--live", "fetch real-time queue depths and failed-job counts from Redis/BullMQ").option("--json", "output JSON").option("--ai", "append AI narration of queue topology and live state (most useful with --live)").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (name, opts) => {
       process.exitCode = await runQueues(name, {
         config: opts.config,
         name: opts.name,
         project: opts.project,
         live: opts.live,
-        json: opts.json
+        json: opts.json,
+        ai: opts.ai,
+        aiModel: opts.aiModel
       });
     }
   );
@@ -77430,12 +78048,12 @@ Examples:
 `);
   program2.command("changes <base> [compare]").description(
     "Show what changed between two git refs and which flows are affected (source change-impact)"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").action(async (base2, compare, opts) => {
-    process.exitCode = await runChanges(base2, compare, { config: opts.config, json: opts.json });
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").option("--ai", "append AI change-impact review").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(async (base2, compare, opts) => {
+    process.exitCode = await runChanges(base2, compare, { config: opts.config, json: opts.json, ai: opts.ai, aiModel: opts.aiModel });
   });
   program2.command("timeline [service]").description(
     "Reconstruct what changed in a time window (git + change-impact) \u2014 evidence, not conclusions"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--since <when>", 'git --since (default "7 days ago"; e.g. "30 days ago", a date)').option("--until <when>", "git --until").option("--all", "include all history instead of the default recent window").option("--json", "output JSON").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--since <when>", 'git --since (default "7 days ago"; e.g. "30 days ago", a date)').option("--until <when>", "git --until").option("--all", "include all history instead of the default recent window").option("--json", "output JSON").option("--ai", "append AI narrative interpretation of the timeline").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (service, opts) => {
       process.exitCode = await runTimeline(service, {
         config: opts.config,
@@ -77443,36 +78061,42 @@ Examples:
         since: opts.since,
         until: opts.until,
         all: opts.all,
-        json: opts.json
+        json: opts.json,
+        ai: opts.ai,
+        aiModel: opts.aiModel
       });
     }
   );
   program2.command("what-changed [service]").description(
     "Concise, evidence-backed summary of what changed for a service in a time window"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--since <when>", 'git --since (default "7 days ago")').option("--until <when>", "git --until").option("--json", "output JSON").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--since <when>", 'git --since (default "7 days ago")').option("--until <when>", "git --until").option("--json", "output JSON").option("--ai", "append AI interpretation of the changes").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (service, opts) => {
       process.exitCode = await runWhatChanged(service, {
         config: opts.config,
         repo: opts.repo,
         since: opts.since,
         until: opts.until,
-        json: opts.json
+        json: opts.json,
+        ai: opts.ai,
+        aiModel: opts.aiModel
       });
     }
   );
   program2.command("architecture").description(
     "Discover the living architecture (subsystems, async boundaries, external systems, fragility)"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").action(async (opts) => {
-    process.exitCode = await runArchitecture({ config: opts.config, json: opts.json });
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").option("--ai", "append AI system explanation grounded in discovered architecture").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(async (opts) => {
+    process.exitCode = await runArchitecture({ config: opts.config, json: opts.json, ai: opts.ai, aiModel: opts.aiModel });
   });
   program2.command("blast-radius <query>").description(
     "Failure-propagation analysis: upstream/downstream dependencies + blast radius across async boundaries"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("-d, --depth <n>", "traversal depth", (v) => parseInt(v, 10)).option("--json", "output JSON").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("-d, --depth <n>", "traversal depth", (v) => parseInt(v, 10)).option("--json", "output JSON").option("--ai", "append AI severity and containment interpretation").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (query, opts) => {
       process.exitCode = await runBlastRadius(query, {
         config: opts.config,
         depth: opts.depth,
-        json: opts.json
+        json: opts.json,
+        ai: opts.ai,
+        aiModel: opts.aiModel
       });
     }
   );
@@ -77536,8 +78160,8 @@ Examples:
   );
   program2.command("score <id>").description(
     "Score a saved investigation's quality (a feedback loop for Horus, not engineers)"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").action(async (id, opts) => {
-    process.exitCode = await runScore(id, { config: opts.config, json: opts.json });
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--json", "output JSON").option("--ai", "append AI score explanation and improvement suggestions").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(async (id, opts) => {
+    process.exitCode = await runScore(id, { config: opts.config, json: opts.json, ai: opts.ai, aiModel: opts.aiModel });
   });
   program2.command("ask <id> <directive>").description(
     'Ask about or refine a saved investigation \u2014 reuses evidence, no re-query.\n  Questions (direct answers):\n    "what evidence contradicts <topic>?"  \xB7 "what evidence is missing?"\n    "why is confidence not higher?"\n  Topic filters (deterministic scoping):\n    "focus on queue behavior" \xB7 "ignore deployment changes" \xB7 "retry"'
@@ -77549,11 +78173,13 @@ Examples:
   });
   program2.command("onboard [area]").description(
     "Understand a system fast: architecture, critical paths, what breaks, ownership, past incidents"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--json", "output JSON").action(async (area, opts) => {
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--repo <name>", "repository name from config").option("--json", "output JSON").option("--ai", "append AI onboarding guide grounded in discovered system evidence").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(async (area, opts) => {
     process.exitCode = await runOnboard(area, {
       config: opts.config,
       repo: opts.repo,
-      json: opts.json
+      json: opts.json,
+      ai: opts.ai,
+      aiModel: opts.aiModel
     });
   });
   program2.command("simulate [scenario]").description(
@@ -77566,21 +78192,21 @@ Examples:
   });
   program2.command("logs [service]").description(
     "Synthesize error evidence from logs (signatures, first/last, affected services); --raw for lines"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--project <name>", "project name").option("--env <name>", "environment name (e.g. production)").option("--since <when>", "time window, e.g. 24h, 7d, or an ISO date").option("--level <level>", "minimum level (with --raw): trace|debug|info|warn|error|fatal").option("--grep <text>", "match text in the message").option("--raw", "dump individual log lines instead of synthesized evidence (error+ by default)").option("--all-levels", "with --raw: show all severity levels, not just error+").option("--limit <n>", "max records (with --raw)").option("--json", "output JSON").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--project <name>", "project name").option("--env <name>", "environment name (e.g. production)").option("--since <when>", "time window, e.g. 24h, 7d, or an ISO date").option("--level <level>", "minimum level (with --raw): trace|debug|info|warn|error|fatal").option("--grep <text>", "match text in the message").option("--raw", "dump individual log lines instead of synthesized evidence (error+ by default)").option("--all-levels", "with --raw: show all severity levels, not just error+").option("--limit <n>", "max records (with --raw)").option("--json", "output JSON").option("--ai", "append AI narration of error signatures (default mode only, not --raw or --json)").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (service, opts) => {
       process.exitCode = await runLogs(service, opts);
     }
   );
   program2.command("state").description(
     "Surface application-state evidence from MongoDB (read-only, allowlisted): counts, staleness, anomalous statuses"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--project <name>", "project name").option("--env <name>", "environment name (e.g. production)").option("--stale-hours <n>", "staleness threshold in hours (default 24)").option("--json", "output JSON").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--project <name>", "project name").option("--env <name>", "environment name (e.g. production)").option("--stale-hours <n>", "staleness threshold in hours (default 24)").option("--json", "output JSON").option("--ai", "append AI narration of MongoDB state evidence").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (opts) => {
       process.exitCode = await runState(opts);
     }
   );
   program2.command("metrics [hint]").description(
     "Grafana metrics evidence: find dashboards/panels for a hint and detect latency spikes, error-rate changes, throughput drops, queue growth"
-  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--since <when>", "window, e.g. 1h, 6h, 24h").option("--step <secs>", "range step seconds").option("--dashboard <uid>", "restrict to a dashboard uid").option("--query <promql>", "raw datasource query escape hatch").option("--json", "JSON output").action(
+  ).option("-c, --config <path>", "path to horus.config.ts").option("--name <name>", "registered project name (resolves via the registry)").option("--since <when>", "window, e.g. 1h, 6h, 24h").option("--step <secs>", "range step seconds").option("--dashboard <uid>", "restrict to a dashboard uid").option("--query <promql>", "raw datasource query escape hatch").option("--json", "JSON output").option("--ai", "append AI narration of metric findings (default mode only, not --query or --json)").option("--ai-model <model>", "override the AI model (default: claude-opus-4-8)").action(
     async (hint, opts) => {
       process.exitCode = await runMetrics(hint, opts);
     }