@f-o-h/cli 0.1.4 → 0.1.6

package/dist/foh.js

@@ -6046,7 +6046,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve5.call(this, root, ref);
+      let _sch = resolve8.call(this, root, ref);
       if (_sch === void 0) {
         const schema2 = (_a2 = root.localRefs) === null || _a2 === void 0 ? void 0 : _a2[ref];
         const { schemaId } = this.opts;
@@ -6073,7 +6073,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve5(root, ref) {
+    function resolve8(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -6648,7 +6648,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve5(baseURI, relativeURI, options) {
+    function resolve8(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -6875,7 +6875,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve5,
+      resolve: resolve8,
       resolveComponent,
       equal,
       serialize,
@@ -9889,6 +9889,8 @@ var FohError = class extends Error {
   remediation;
   statusCode;
   detail;
+  reasonCode;
+  nextCommands;
   constructor(opts) {
     super(opts.error);
     this.name = "FohError";
@@ -9898,6 +9900,8 @@ var FohError = class extends Error {
     this.remediation = opts.remediation;
     this.statusCode = opts.statusCode;
     this.detail = opts.detail;
+    this.reasonCode = opts.reasonCode;
+    this.nextCommands = opts.nextCommands;
   }
   toJSON() {
     return {
@@ -9905,6 +9909,8 @@ var FohError = class extends Error {
       status: this.status,
       error: this.error,
       remediation: this.remediation,
+      reason_code: this.reasonCode,
+      next_commands: this.nextCommands,
       status_code: this.statusCode,
       detail: this.detail
     };
@@ -9913,6 +9919,34 @@ var FohError = class extends Error {
 
 // src/lib/output.ts
 var import_picocolors = __toESM(require_picocolors());
+
+// src/lib/cli-envelope.ts
+function envelopeOk(status) {
+  return status === "pass" || status === "success" || status === "exported";
+}
+function dedupeCommands(commands = []) {
+  return Array.from(new Set(commands.map((command) => String(command || "").trim()).filter(Boolean)));
+}
+function cliEnvelope(input) {
+  return {
+    schema_version: input.schemaVersion ?? "foh_cli_envelope.v1",
+    ok: envelopeOk(input.status),
+    status: input.status,
+    reason_code: input.reasonCode,
+    summary: input.summary,
+    ids: input.ids ?? {},
+    checks: input.checks ?? [],
+    artifacts: input.artifacts ?? {},
+    next_commands: dedupeCommands(input.nextCommands),
+    ...input.extra ?? {}
+  };
+}
+function reasonCodeFromStep(step, fallback = "cli_command_failed") {
+  const normalized = step.trim().toLowerCase().replace(/^\/+/, "").replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return normalized ? `${normalized}_failed` : fallback;
+}
+
+// src/lib/output.ts
 function resolveJsonMode(opts = {}) {
   return Boolean(opts.json || process.argv.includes("--json"));
 }
@@ -9927,13 +9961,21 @@ function formatError(e, opts = {}) {
   if (resolveJsonMode(opts)) {
     process.stderr.write(
       JSON.stringify(
-        {
-          error: {
-            step: e.step,
-            message: e.error,
-            remediation: e.remediation
+        cliEnvelope({
+          status: "fail",
+          reasonCode: e.reasonCode ?? reasonCodeFromStep(e.step),
+          summary: e.error,
+          nextCommands: e.nextCommands,
+          extra: {
+            error: {
+              step: e.step,
+              message: e.error,
+              remediation: e.remediation,
+              status_code: e.statusCode,
+              detail: e.detail
+            }
           }
-        },
+        }),
         null,
         2
       ) + "\n"
@@ -10063,21 +10105,21 @@ async function promptLine(label, {
   allowEmpty = false,
   defaultValue
 } = {}) {
-  return await new Promise((resolve5) => {
+  return await new Promise((resolve8) => {
     const suffix = defaultValue ? ` [${defaultValue}]` : "";
     const rl = (0, import_readline.createInterface)({ input: process.stdin, output: process.stdout, terminal: true });
     rl.question(`${label}${suffix}: `, (answer) => {
       rl.close();
       const value = String(answer ?? "").trim();
       if (!value && typeof defaultValue === "string") {
-        resolve5(defaultValue);
+        resolve8(defaultValue);
         return;
       }
       if (!value && !allowEmpty) {
-        resolve5("");
+        resolve8("");
         return;
       }
-      resolve5(value);
+      resolve8(value);
     });
   });
 }
@@ -10085,7 +10127,7 @@ async function promptSecret(label) {
   if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== "function") {
     return await promptLine(label);
   }
-  return await new Promise((resolve5) => {
+  return await new Promise((resolve8) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     const wasRaw = Boolean(stdin.isRaw);
@@ -10099,7 +10141,7 @@ async function promptSecret(label) {
     const finish = () => {
       cleanup();
       stdout.write("\n");
-      resolve5(value);
+      resolve8(value);
     };
     const onData = (chunk) => {
       const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
@@ -10108,7 +10150,7 @@ async function promptSecret(label) {
           cleanup();
           process.exitCode = 130;
           stdout.write("\n");
-          return resolve5("");
+          return resolve8("");
         }
         if (char === "\r" || char === "\n") {
           finish();
@@ -10377,7 +10419,7 @@ async function storeAuthenticatedSession(params) {
   return output;
 }
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function runDeviceLogin(opts) {
   const jsonMode = Boolean(opts.json);
@@ -10915,7 +10957,7 @@ async function pollUntil(check2, opts) {
   }
 }
 function sleep2(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // src/commands/compliance.ts
@@ -13718,6 +13760,176 @@ function agentDraftFromManifest(manifest) {
   return patch;
 }
 
+// src/lib/local-replay-packet.ts
+var import_fs2 = require("fs");
+
+// src/lib/transcript-export.ts
+var EMAIL_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+var PHONE_RE = /(?<!\w)(?:\+?\d[\d\s().-]{7,}\d)(?!\w)/g;
+var SECRET_RE = /\b(?:sk|pk|xai|whsec|EAAN)[A-Za-z0-9_\-]{16,}\b/g;
+function redactString(value) {
+  return value.replace(EMAIL_RE, "[redacted_email]").replace(SECRET_RE, "[redacted_secret]").replace(PHONE_RE, "[redacted_phone]");
+}
+function redactObject(value) {
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) return value.map((entry) => redactObject(entry));
+  if (!value || typeof value !== "object") return value;
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = redactObject(entry);
+  }
+  return result;
+}
+function extractUserTurns(transcriptText) {
+  const turns = [];
+  for (const line of transcriptText.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:user|customer|lead)\s*:\s*(.+)\s*$/i);
+    if (match?.[1]?.trim()) turns.push({ user: match[1].trim() });
+  }
+  if (turns.length === 0 && transcriptText.trim()) {
+    turns.push({ user: transcriptText.trim().slice(0, 500) });
+  }
+  return turns;
+}
+function buildReplayReadyConversation(input) {
+  const conversationId = String(input.conversation.id || "");
+  const transcriptText = String(input.conversation.transcript_text || "");
+  return {
+    ...input.conversation,
+    replay_command: conversationId ? `foh agent replay --agent ${input.agentId} --conversation ${conversationId} --json` : null,
+    test_fixture: {
+      schema_version: "foh_scenario_fixture.v1",
+      conversation_id: conversationId || null,
+      turns: extractUserTurns(transcriptText)
+    }
+  };
+}
+
+// src/lib/local-replay-packet.ts
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function nonEmpty(value) {
+  const text = String(value ?? "").trim();
+  return text.length > 0 ? text : void 0;
+}
+function arrayOfRecords(value) {
+  return Array.isArray(value) ? value.map(asRecord).filter(Boolean) : [];
+}
+function collectStrings(value, keys) {
+  const found = /* @__PURE__ */ new Set();
+  const visit = (entry) => {
+    if (Array.isArray(entry)) {
+      for (const item of entry) visit(item);
+      return;
+    }
+    const record2 = asRecord(entry);
+    if (!record2) return;
+    for (const key of keys) {
+      const text = nonEmpty(record2[key]);
+      if (text) found.add(text);
+    }
+    for (const nested of Object.values(record2)) visit(nested);
+  };
+  visit(value);
+  return Array.from(found);
+}
+function selectConversation(artifact, agentId) {
+  const conversations = arrayOfRecords(artifact.conversations);
+  if (conversations.length > 0) {
+    if (agentId) {
+      const byAgent = conversations.find((conversation) => nonEmpty(conversation.agent_id) === agentId);
+      if (byAgent) return byAgent;
+    }
+    return conversations[0] ?? null;
+  }
+  if (artifact.transcript_text || artifact.test_fixture || artifact.traces) return artifact;
+  return null;
+}
+function buildDiff(conversation) {
+  const expectedTurns = arrayOfRecords(conversation.expected_turns);
+  const fixtureTurns = arrayOfRecords((asRecord(conversation.test_fixture) ?? {}).turns);
+  const actualTurns = fixtureTurns.length > 0 ? fixtureTurns : extractUserTurns(String(conversation.transcript_text ?? ""));
+  if (expectedTurns.length === 0) {
+    return {
+      status: "not_evaluated",
+      reason_code: "expected_turns_missing",
+      expected_turn_count: 0,
+      actual_turn_count: actualTurns.length,
+      differences: []
+    };
+  }
+  const differences = [];
+  const max = Math.max(expectedTurns.length, actualTurns.length);
+  for (let i = 0; i < max; i += 1) {
+    const expected = nonEmpty(expectedTurns[i]?.user);
+    const actual = nonEmpty(actualTurns[i]?.user);
+    if (expected !== actual) differences.push(`turn_${i + 1}: expected "${expected ?? ""}" got "${actual ?? ""}"`);
+  }
+  return {
+    status: differences.length === 0 ? "match" : "diff",
+    reason_code: differences.length === 0 ? "replay_diff_match" : "replay_diff_mismatch",
+    expected_turn_count: expectedTurns.length,
+    actual_turn_count: actualTurns.length,
+    differences
+  };
+}
+function buildLocalReplayPacket(input) {
+  const artifact = JSON.parse((0, import_fs2.readFileSync)(input.filePath, "utf-8"));
+  const conversation = selectConversation(artifact, input.agentId);
+  if (!conversation) {
+    return {
+      schema_version: "foh_agent_replay_packet.v1",
+      status: "local_artifact_not_replayable",
+      source: { type: "file", file: input.filePath, agent_id: input.agentId ?? null },
+      not_replayable_reason: "file_has_no_conversation_payload",
+      next_commands: ["foh transcripts export --agent <agent-id> --hydrate --include-traces --format json --out transcript-export.json --json"]
+    };
+  }
+  const traces = arrayOfRecords(conversation.traces ?? artifact.traces);
+  const traceIds = traces.map((trace) => nonEmpty(trace.id)).filter(Boolean);
+  const agentId = input.agentId ?? nonEmpty(conversation.agent_id) ?? nonEmpty(artifact.agent_id);
+  const conversationId = nonEmpty(conversation.id) ?? nonEmpty((asRecord(conversation.test_fixture) ?? {}).conversation_id);
+  const firstTraceId = traceIds[0];
+  return {
+    schema_version: "foh_agent_replay_packet.v1",
+    status: "local_replay_packet_created",
+    source: {
+      type: "file",
+      file: input.filePath,
+      agent_id: agentId ?? null,
+      conversation_id: conversationId ?? null
+    },
+    replay_runtime: {
+      mode: "local_artifact",
+      version: "foh_agent_replay_local_v1"
+    },
+    agent_reference: {
+      agent_id: agentId ?? null,
+      agent_version: conversation.agent_version ?? artifact.agent_version ?? null,
+      config_ref: conversation.config_ref ?? artifact.config_ref ?? null
+    },
+    trace_ids: traceIds,
+    correlation_ids: collectStrings([conversation, artifact], ["correlation_id", "correlationId"]),
+    tool_references: collectStrings(traces, ["tool_name", "toolName", "name"]),
+    knowledge_snapshot_refs: collectStrings([conversation, artifact], ["knowledge_snapshot_id", "knowledgeSnapshotId", "knowledge_ref"]),
+    conversation,
+    trace_count: traces.length,
+    traces,
+    diff: buildDiff(conversation),
+    not_replayable_reason: null,
+    next_commands: [
+      ...agentId && firstTraceId ? [
+        `foh agent replay --agent ${agentId} --trace ${firstTraceId} --json`,
+        `foh tests from-trace --agent ${agentId} --trace ${firstTraceId} --json`
+      ] : [],
+      ...agentId && conversationId ? [
+        `foh test run --suite <suite.yml> --agent ${agentId} --json`
+      ] : []
+    ]
+  };
+}
+
 // src/commands/agent-candidate-decision.ts
 function registerAgentCandidateDecisionCommands(agent) {
   const candidateDecision = agent.command("candidate-decision").description("Read/write candidate promotion decisions");
@@ -13783,8 +13995,8 @@ function registerAgentGuardrailCommands(agent) {
     try {
       rule = JSON.parse(opts.rule);
     } catch {
-      const { readFileSync: readFileSync6 } = await import("fs");
-      rule = JSON.parse(readFileSync6(opts.rule, "utf-8"));
+      const { readFileSync: readFileSync9 } = await import("fs");
+      rule = JSON.parse(readFileSync9(opts.rule, "utf-8"));
     }
     const data = await apiFetch(`/v1/console/agents/${opts.agent}/guardrails`, {
       method: "POST",
@@ -14190,6 +14402,74 @@ function registerAgent(program3) {
     const data = await apiFetch(`/v1/console/agents/${opts.agent}`, { apiUrlOverride: opts.apiUrl });
     format(data, { json: opts.json ?? false });
   }));
+  agent.command("replay").description("Create a replay/debug packet from a trace or conversation").option("--trace <id>", "Trace event ID to replay through the server trace replay endpoint").option("--conversation <id>", "Conversation ID to package with transcript and traces").option("--file <path>", "Local transcript/replay artifact JSON to package without API access").option("--agent <id>", "Agent ID").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const sourceCount = [opts.trace, opts.conversation, opts.file].filter(Boolean).length;
+    if (sourceCount === 0) {
+      throw new FohError({
+        step: "agent.replay",
+        error: "Missing replay source",
+        remediation: "Pass --trace <id>, --conversation <id>, or --file <transcript.json>.",
+        statusCode: 400
+      });
+    }
+    if (sourceCount > 1) {
+      throw new FohError({
+        step: "agent.replay",
+        error: "Ambiguous replay source",
+        remediation: "Pass only one of --trace, --conversation, or --file.",
+        statusCode: 400
+      });
+    }
+    if ((opts.trace || opts.conversation) && !opts.agent) {
+      throw new FohError({
+        step: "agent.replay",
+        error: "Missing agent id for server replay source",
+        remediation: "Pass --agent <id>, or use --file with a local transcript artifact that includes agent_id.",
+        statusCode: 400
+      });
+    }
+    if (opts.file) {
+      format(buildLocalReplayPacket({
+        filePath: String(opts.file),
+        agentId: opts.agent ? String(opts.agent) : void 0
+      }), { json: opts.json ?? false });
+      return;
+    }
+    if (opts.trace) {
+      const data2 = await apiFetch(`/v1/console/traces/${opts.trace}/replay`, {
+        method: "POST",
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      });
+      format({
+        schema_version: "foh_agent_replay_packet.v1",
+        status: "server_replay_completed",
+        source: { type: "trace", trace_id: opts.trace, agent_id: opts.agent },
+        replay: data2,
+        next_commands: [`foh tests from-trace --agent ${opts.agent} --trace ${opts.trace} --json`]
+      }, { json: opts.json ?? false });
+      return;
+    }
+    const data = await apiFetch(`/v1/console/agents/${opts.agent}/conversations/${opts.conversation}?include_traces=true`, {
+      orgId: opts.org,
+      apiUrlOverride: opts.apiUrl
+    });
+    const traces = Array.isArray(data.traces) ? data.traces : [];
+    const firstTraceId = traces.map((trace) => String(trace.id || "").trim()).find(Boolean);
+    format({
+      schema_version: "foh_agent_replay_packet.v1",
+      status: firstTraceId ? "conversation_replay_packet_created" : "conversation_not_replayable",
+      source: { type: "conversation", conversation_id: opts.conversation, agent_id: opts.agent },
+      conversation: data.conversation ?? null,
+      trace_count: traces.length,
+      traces,
+      not_replayable_reason: firstTraceId ? null : "conversation_has_no_trace_events",
+      next_commands: firstTraceId ? [
+        `foh agent replay --agent ${opts.agent} --trace ${firstTraceId} --json`,
+        `foh tests from-trace --agent ${opts.agent} --trace ${firstTraceId} --json`
+      ] : [`foh transcripts get --agent ${opts.agent} --conversation ${opts.conversation} --include-traces --json`]
+    }, { json: opts.json ?? false });
+  }));
   const blueprint = agent.command("blueprint").description("Compile or apply Conversation Blueprint v1");
   blueprint.command("compile").description("Compile a Conversation Blueprint v1 file to the current policy graph draft without saving it").requiredOption("--agent <id>", "Agent ID").requiredOption("--blueprint <json|@file>", "Conversation Blueprint v1 JSON or @path").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
     const parsedBlueprint = await parseJsonOption(opts.blueprint, "--blueprint");
@@ -14316,9 +14596,9 @@ function registerAgent(program3) {
       process.stdout.write(yaml);
       return;
     }
-    const { writeFileSync: writeFileSync4 } = await import("fs");
+    const { writeFileSync: writeFileSync6 } = await import("fs");
     const outputPath = opts.output ?? "tenant.yaml";
-    writeFileSync4(
+    writeFileSync6(
       outputPath,
       `# tenant.yaml - Front Of House agent manifest
 # Edit this file and run: foh plan tenant.yaml
@@ -15753,11 +16033,11 @@ function registerVoice(program3) {
     }
     const outputPath = String(opts.out || `foh-voice-preview-${provider}-${voiceId}.mp3`).trim();
     const audio = Buffer.from(await res.arrayBuffer());
-    const { mkdirSync: mkdirSync4, writeFileSync: writeFileSync4 } = await import("fs");
-    const { dirname: dirname5, resolve: resolve5 } = await import("path");
-    const absolutePath = resolve5(outputPath);
+    const { mkdirSync: mkdirSync4, writeFileSync: writeFileSync6 } = await import("fs");
+    const { dirname: dirname5, resolve: resolve8 } = await import("path");
+    const absolutePath = resolve8(outputPath);
     mkdirSync4(dirname5(absolutePath), { recursive: true });
-    writeFileSync4(absolutePath, audio);
+    writeFileSync6(absolutePath, audio);
     format({
       status: "ok",
       provider,
@@ -30238,7 +30518,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve5) => setTimeout(resolve5, pollInterval));
+        await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -30255,7 +30535,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve5, reject) => {
+    return new Promise((resolve8, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -30333,7 +30613,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve5(parseResult.data);
+            resolve8(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -30594,12 +30874,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve5, reject) => {
+    return new Promise((resolve8, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve5, interval);
+      const timeoutId = setTimeout(resolve8, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -31699,7 +31979,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve5) => setTimeout(resolve5, pollInterval));
+      await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -32348,19 +32628,19 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve5) => {
+    return new Promise((resolve8) => {
       const json3 = serializeMessage(message);
       if (this._stdout.write(json3)) {
-        resolve5();
+        resolve8();
       } else {
-        this._stdout.once("drain", resolve5);
+        this._stdout.once("drain", resolve8);
       }
     });
   }
 };
 
 // src/lib/cli-version.ts
-var CLI_VERSION = "0.1.4";
+var CLI_VERSION = "0.1.6";
 
 // src/commands/mcp-serve.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -32545,7 +32825,7 @@ async function runFohCli(params) {
     effectiveArgv.push("--json");
   }
   const command = `foh ${effectiveArgv.join(" ")}`;
-  return await new Promise((resolve5) => {
+  return await new Promise((resolve8) => {
     const child = (0, import_node_child_process.spawn)(process.execPath, [cliEntry, ...effectiveArgv], {
       stdio: ["ignore", "pipe", "pipe"],
       env: {
@@ -32570,7 +32850,7 @@ async function runFohCli(params) {
     });
     child.once("error", (error2) => {
       clearTimeout(timeoutHandle);
-      resolve5({
+      resolve8({
         ok: false,
         command,
         argv: effectiveArgv,
@@ -32586,7 +32866,7 @@ async function runFohCli(params) {
       const stderrText = finalizeBoundedText(stderrBuffer);
       const exitCode = Number.isFinite(code ?? NaN) ? Number(code) : 1;
       const stdoutJson = tryParseJson(stdoutText);
-      resolve5({
+      resolve8({
         ok: !timedOut && exitCode === 0,
         command,
         argv: effectiveArgv,
@@ -33359,18 +33639,143 @@ function registerMcp(program3) {
 }
 
 // src/commands/knowledge.ts
-var import_fs2 = require("fs");
+var import_fs3 = require("fs");
 var import_path2 = require("path");
+
+// src/lib/query-options.ts
+function parsePositiveInt(value, fallback, min, max) {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(parsed)));
+}
+function withQuery(path2, params) {
+  const query = params.toString();
+  return query ? `${path2}?${query}` : path2;
+}
+
+// src/commands/knowledge.ts
 function readDraftKnowledgeText(draft) {
   const fromRaw = typeof draft.knowledge_base_raw === "string" ? draft.knowledge_base_raw : "";
   if (fromRaw.trim().length > 0) return fromRaw;
   const fromLegacy = typeof draft.knowledge_base === "string" ? draft.knowledge_base : "";
   return fromLegacy;
 }
+function tokenize(value) {
+  return value.toLowerCase().split(/[^a-z0-9]+/g).map((token) => token.trim()).filter((token) => token.length >= 3);
+}
+function chunkKnowledgeText(text) {
+  return text.split(/\n\s*\n|---+/g).map((chunk) => chunk.trim()).filter(Boolean).map((chunk, index) => ({ index, text: chunk }));
+}
+function scoreChunk(queryTokens, chunkText) {
+  if (queryTokens.size === 0) return 0;
+  const chunkTokens = new Set(tokenize(chunkText));
+  let overlap = 0;
+  for (const token of queryTokens) {
+    if (chunkTokens.has(token)) overlap += 1;
+  }
+  return Number((overlap / queryTokens.size).toFixed(6));
+}
 function registerKnowledge(program3) {
   const knowledge = program3.command("knowledge").description("Manage agent knowledge base");
+  knowledge.command("query").description("Debug agent knowledge retrieval for a question").requiredOption("--agent <id>", "Agent ID").requiredOption("--text <query>", "Question/query text").option("--limit <n>", "Max chunks to return (1-20)", "5").option("--min-score <n>", "Minimum overlap score for pass threshold", "0.2").option("--explain", "Include token/scoring metadata").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const query = String(opts.text || "").trim();
+    if (query.length < 3) {
+      throw new FohError({
+        step: "knowledge.query",
+        error: "Query text must be at least 3 characters",
+        remediation: 'Pass --text "<question>" with 3+ characters.',
+        statusCode: 400
+      });
+    }
+    const draft = await apiFetch(`/v1/console/agents/${opts.agent}/draft`, {
+      orgId: opts.org,
+      apiUrlOverride: opts.apiUrl
+    });
+    const knowledgeText = readDraftKnowledgeText(draft);
+    const chunks = chunkKnowledgeText(knowledgeText);
+    const queryTokens = new Set(tokenize(query));
+    const minScore = Math.max(0, Math.min(1, Number(opts.minScore ?? 0.2) || 0.2));
+    const limit = parsePositiveInt(opts.limit, 5, 1, 20);
+    const matches = chunks.map((chunk) => ({
+      chunk_id: `agent-draft-${opts.agent}#${chunk.index + 1}`,
+      source: "agent_draft_knowledge",
+      citation: `agent:${opts.agent}:chunk:${chunk.index + 1}`,
+      score: scoreChunk(queryTokens, chunk.text),
+      lineage: {
+        source: "agent_draft_direct",
+        agent_id: opts.agent,
+        chunk_index: chunk.index + 1
+      },
+      text: chunk.text.slice(0, 1200)
+    })).filter((chunk) => chunk.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+    const topScore = matches[0]?.score ?? 0;
+    const status = matches.length === 0 ? "no_match" : topScore >= minScore ? "pass" : "low_confidence";
+    const reasonCode = status === "pass" ? "knowledge_query_match" : status === "low_confidence" ? "knowledge_query_low_confidence" : "knowledge_query_no_match";
+    const packet = status === "pass" ? null : {
+      schema_version: "foh_knowledge_query_failure_packet.v1",
+      agent_id: opts.agent,
+      query,
+      reason_code: reasonCode,
+      top_score: topScore,
+      chunk_count: chunks.length,
+      lineage: {
+        source: "agent_draft_direct",
+        agent_id: opts.agent,
+        candidate_chunk_count: chunks.length
+      },
+      next_commands: [
+        `foh knowledge ingest-file --agent ${opts.agent} --file <path> --json`,
+        `foh knowledge query --agent ${opts.agent} --text "${query.replace(/"/g, '\\"')}" --explain --json`
+      ]
+    };
+    format({
+      schema_version: "foh_knowledge_query_debug.v1",
+      ok: status === "pass",
+      status,
+      reason_code: reasonCode,
+      summary: status === "pass" ? `Knowledge query matched ${matches.length} chunk(s).` : status === "low_confidence" ? `Knowledge query matched weakly; top score ${topScore}.` : "Knowledge query returned no usable matches.",
+      ids: {
+        agent_id: opts.agent
+      },
+      checks: [{
+        name: "knowledge_retrieval",
+        status,
+        reason_code: reasonCode,
+        top_score: topScore,
+        min_score: minScore,
+        match_count: matches.length
+      }],
+      artifacts: {},
+      next_commands: status === "pass" ? [] : [
+        `foh knowledge ingest-file --agent ${opts.agent} --file <path> --json`,
+        `foh knowledge query --agent ${opts.agent} --text "${query.replace(/"/g, '\\"')}" --explain --json`
+      ],
+      agent_id: opts.agent,
+      query,
+      retrieval: {
+        source: "agent_draft_direct",
+        chunk_count: chunks.length,
+        match_count: matches.length,
+        top_score: topScore,
+        min_score: minScore,
+        lineage: {
+          agent_id: opts.agent,
+          source: "agent_draft_direct",
+          candidate_chunk_count: chunks.length
+        }
+      },
+      matches,
+      failure_packet: packet,
+      ...opts.explain ? {
+        explain: {
+          query_tokens: Array.from(queryTokens),
+          scoring: "token_overlap_ratio_v1"
+        }
+      } : {}
+    }, { json: opts.json ?? false });
+  }));
   knowledge.command("ingest-file").description("Ingest a local file into the knowledge base").requiredOption("--file <path>", "Path to file to ingest").option("--agent <id>", "Scope to agent").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
-    const content = (0, import_fs2.readFileSync)(opts.file, "utf-8");
+    const content = (0, import_fs3.readFileSync)(opts.file, "utf-8");
     let data;
     if (opts.agent) {
       const draft = await apiFetch(`/v1/console/agents/${opts.agent}/draft`, {
@@ -33529,7 +33934,7 @@ var import_crypto3 = require("crypto");
 
 // src/lib/signed-report.ts
 var import_crypto2 = require("crypto");
-var import_fs3 = require("fs");
+var import_fs4 = require("fs");
 var import_path3 = require("path");
 function canonicalize(value) {
   if (value === null || value === void 0) return null;
@@ -33561,13 +33966,13 @@ function signReport(reportPayload) {
 }
 function writeSignedJsonArtifact(path2, value) {
   const absolutePath = (0, import_path3.resolve)(path2);
-  (0, import_fs3.mkdirSync)((0, import_path3.dirname)(absolutePath), { recursive: true });
-  (0, import_fs3.writeFileSync)(absolutePath, stableStringify(value), "utf-8");
+  (0, import_fs4.mkdirSync)((0, import_path3.dirname)(absolutePath), { recursive: true });
+  (0, import_fs4.writeFileSync)(absolutePath, stableStringify(value), "utf-8");
   return absolutePath;
 }
 
 // src/commands/manifest.ts
-var import_fs4 = require("fs");
+var import_fs5 = require("fs");
 var import_picocolors3 = __toESM(require_picocolors());
 function formatDiff(diffs) {
   if (diffs.length === 0) return "No changes";
@@ -33603,7 +34008,7 @@ function formatDiff(diffs) {
 function loadManifestFile(filePath) {
   let raw;
   try {
-    raw = (0, import_fs4.readFileSync)(filePath, "utf-8");
+    raw = (0, import_fs5.readFileSync)(filePath, "utf-8");
   } catch {
     throw new FohError({
       step: "manifest.load",
@@ -33871,27 +34276,32 @@ function optionNameToFlag(key) {
 function buildMissingOptionsPlan(missing, opts) {
   const missingFlags = missing.map(optionNameToFlag);
   const signInUrl = buildConsoleSignInUrl(resolveConsoleBaseUrl(opts.consoleUrl));
-  return {
+  return cliEnvelope({
     status: "blocked",
-    code: "setup_required_options_missing",
-    missing_options: missingFlags,
-    reason: "setup requires an authenticated org, an agent template, and an agent name before it can mutate customer resources",
-    sign_in_url: signInUrl,
-    next_commands: [
+    reasonCode: "setup_required_options_missing",
+    summary: "Setup requires an authenticated org, an agent template, and an agent name before it can mutate customer resources.",
+    ids: {},
+    nextCommands: [
       "foh auth signup --web --json",
       "foh auth login --web --json",
       ...buildCliAuthFallbackCommands(),
       "foh templates list --json",
       'foh setup --org <org-id> --agent-template <template-id> --agent-name "Demo Agent" --widget-domains <domain> --report-out setup-report.json --json'
     ],
-    text_fallback: buildCliAuthFallbackInstructions(signInUrl),
-    ai_agent_instruction: [
-      "Do not guess org IDs, template IDs, or customer domains.",
-      "If no browser is available, print sign_in_url and ask the user to sign in.",
-      "After auth, discover orgs and templates with the listed commands.",
-      "Rerun setup only after all missing_options are resolved."
-    ]
-  };
+    extra: {
+      code: "setup_required_options_missing",
+      missing_options: missingFlags,
+      reason: "setup requires an authenticated org, an agent template, and an agent name before it can mutate customer resources",
+      sign_in_url: signInUrl,
+      text_fallback: buildCliAuthFallbackInstructions(signInUrl),
+      ai_agent_instruction: [
+        "Do not guess org IDs, template IDs, or customer domains.",
+        "If no browser is available, print sign_in_url and ask the user to sign in.",
+        "After auth, discover orgs and templates with the listed commands.",
+        "Rerun setup only after all missing_options are resolved."
+      ]
+    }
+  });
 }
 function emitMissingOptionsPlan(missing, opts) {
   const plan = buildMissingOptionsPlan(missing, { consoleUrl: opts.consoleUrl });
@@ -33997,7 +34407,7 @@ function registerSetup(program3) {
       const startedAtIso = nowIso();
       const startedAtMs = Date.now();
       if (shouldResumeSkip(name)) {
-        const skipped = timedStepResult(
+        const skipped2 = timedStepResult(
           {
             step: name,
             status: "skipped",
@@ -34006,10 +34416,10 @@ function registerSetup(program3) {
           startedAtIso,
           startedAtMs
         );
-        completed.push(skipped);
+        completed.push(skipped2);
         process.stderr.write(import_picocolors4.default.dim(`  [RESUME] ${name}: skipped (resume-from ${resumeState.resumeFrom})
 `));
-        return skipped;
+        return skipped2;
       }
       if (opts.dryRun) {
         const dryRunResult = timedStepResult(
@@ -34365,8 +34775,8 @@ function registerSetup(program3) {
         }
         try {
           const manifest = await agentExport(resolvedAgentId, { apiUrlOverride: opts.apiUrl });
-          const { writeFileSync: writeFileSync4 } = await import("fs");
-          writeFileSync4(
+          const { writeFileSync: writeFileSync6 } = await import("fs");
+          writeFileSync6(
             "tenant.yaml",
             `# tenant.yaml - Front Of House agent manifest
 # Edit this file and run: foh plan tenant.yaml
@@ -34382,7 +34792,15 @@ ${serialiseManifest(manifest)}`,
       });
       const reportMeta = emitSetupReport("success");
       const summary = {
+        schema_version: "foh_cli_setup_summary.v1",
+        ok: true,
         status: "success",
+        reason_code: "setup_completed",
+        summary: "Setup completed and produced a signed setup report.",
+        ids: {
+          org_id: opts.org,
+          agent_id: agentId ?? null
+        },
         org_id: opts.org,
         agent_id: agentId,
         phone_number: phoneNumber,
@@ -34394,7 +34812,15 @@ ${serialiseManifest(manifest)}`,
         manifest_written: manifestWritten ? "tenant.yaml" : null,
         resume_from: resumeState.resumeFrom,
         setup_report_hash: reportMeta.reportHash,
-        setup_report_path: reportMeta.reportPath
+        setup_report_path: reportMeta.reportPath,
+        artifacts: {
+          setup_report_path: reportMeta.reportPath,
+          tenant_manifest_path: manifestWritten ? "tenant.yaml" : null
+        },
+        next_commands: agentId ? [
+          `foh prove --agent ${agentId} --json --out test-results/foh-proof.latest.json`,
+          `foh agent publish --agent ${agentId} --json`
+        ] : []
       };
       format(summary, { json: opts.json ?? false });
     } catch (error2) {
@@ -34407,13 +34833,25 @@ ${serialiseManifest(manifest)}`,
         });
         format(
           {
+            schema_version: "foh_cli_setup_failure.v1",
+            ok: false,
             status: "failed",
+            reason_code: error2.reasonCode ?? "setup_failed",
+            summary: error2.error,
+            ids: {
+              org_id: opts.org,
+              agent_id: agentId ?? null
+            },
             step: error2.step,
             completed_steps: completed.map((stepResult) => stepResult.step),
             error: error2.error,
             remediation: error2.remediation,
             setup_report_hash: reportMeta.reportHash,
-            setup_report_path: reportMeta.reportPath
+            setup_report_path: reportMeta.reportPath,
+            artifacts: {
+              setup_report_path: reportMeta.reportPath
+            },
+            next_commands: error2.nextCommands ?? [error2.remediation.replace(/^Run:\s*/, "")].filter(Boolean)
           },
           { json: opts.json ?? false }
         );
@@ -34506,8 +34944,8 @@ function registerSim(program3) {
       }
       const cert = response.certificate;
       if (opts.out) {
-        const { writeFileSync: writeFileSync4 } = await import("fs");
-        writeFileSync4(opts.out, JSON.stringify(cert, null, 2) + "\n", "utf-8");
+        const { writeFileSync: writeFileSync6 } = await import("fs");
+        writeFileSync6(opts.out, JSON.stringify(cert, null, 2) + "\n", "utf-8");
         process.stderr.write(`  Certificate written to ${opts.out}
 `);
       }
@@ -34557,8 +34995,8 @@ function registerSim(program3) {
         });
       }
       if (opts.out) {
-        const { writeFileSync: writeFileSync4 } = await import("fs");
-        writeFileSync4(opts.out, JSON.stringify(response.certificate, null, 2) + "\n", "utf-8");
+        const { writeFileSync: writeFileSync6 } = await import("fs");
+        writeFileSync6(opts.out, JSON.stringify(response.certificate, null, 2) + "\n", "utf-8");
         process.stderr.write(`  Final certificate written to ${opts.out}
 `);
       }
@@ -34595,19 +35033,6 @@ ${passIcon}  Certification loop summary
 
 // src/commands/conversations.ts
 var import_crypto4 = require("crypto");
-
-// src/lib/query-options.ts
-function parsePositiveInt(value, fallback, min, max) {
-  const parsed = Number(value ?? fallback);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.min(max, Math.trunc(parsed)));
-}
-function withQuery(path2, params) {
-  const query = params.toString();
-  return query ? `${path2}?${query}` : path2;
-}
-
-// src/commands/conversations.ts
 function registerConversations(program3) {
   const conversations = program3.command("conversations").description("Search and operate on conversation traces and lead data");
   conversations.command("list").description("List/search conversations for an agent").requiredOption("--agent <id>", "Agent ID").option("--q <query>", "Full-text transcript query").option("--from <iso-date>", "Start datetime (ISO8601)").option("--to <iso-date>", "End datetime (ISO8601)").option("--terminal-state <value>", "Terminal state filter").option("--journey <value>", "Journey filter").option("--has-tool-call <value>", "Tool outcome/tool id filter").option("--scope <value>", "Scope: agent or org").option("--scope-agent-id <id>", "Optional scoped agent id when --scope org").option("--guardrail-triggered", "Only conversations with guardrail_triggered trace events").option("--provider <value>", "Provider filter from trace payload").option("--page <n>", "Page number", "1").option("--limit <n>", "Page size (1-100)", "20").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
@@ -34769,6 +35194,227 @@ function registerConversations(program3) {
   }));
 }
 
+// src/commands/transcripts.ts
+var import_fs6 = require("fs");
+var import_path4 = require("path");
+function listPath(agentId, opts) {
+  const params = new URLSearchParams();
+  if (opts.q) params.set("q", String(opts.q));
+  if (opts.from) params.set("from", String(opts.from));
+  if (opts.to) params.set("to", String(opts.to));
+  params.set("page", String(parsePositiveInt(opts.page, 1, 1, 1e4)));
+  params.set("limit", String(parsePositiveInt(opts.limit, 20, 1, 100)));
+  return withQuery(`/v1/console/agents/${agentId}/conversations`, params);
+}
+function jsonl(rows) {
+  return rows.map((row) => JSON.stringify(row)).join("\n") + (rows.length > 0 ? "\n" : "");
+}
+async function hydrateRows(input) {
+  const hydrated = [];
+  for (const row of input.rows) {
+    const conversationId = String(row.id || "").trim();
+    if (!conversationId) {
+      hydrated.push(row);
+      continue;
+    }
+    const params = new URLSearchParams();
+    if (input.includeTraces) params.set("include_traces", "true");
+    const detail = await apiFetch(
+      withQuery(`/v1/console/agents/${input.agentId}/conversations/${conversationId}`, params),
+      { orgId: input.orgId, apiUrlOverride: input.apiUrl }
+    );
+    hydrated.push({
+      ...detail.conversation || row,
+      ...input.includeTraces ? { traces: Array.isArray(detail.traces) ? detail.traces : [] } : {}
+    });
+  }
+  return hydrated;
+}
+function registerTranscripts(program3) {
+  const transcripts = program3.command("transcripts").description("List, fetch, and export conversation transcripts");
+  transcripts.command("list").description("List transcript-bearing conversations for an agent").requiredOption("--agent <id>", "Agent ID").option("--q <query>", "Full-text transcript query").option("--from <iso-date>", "Start datetime (ISO8601)").option("--to <iso-date>", "End datetime (ISO8601)").option("--page <n>", "Page number", "1").option("--limit <n>", "Page size (1-100)", "20").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const data = await apiFetch(listPath(opts.agent, opts), { orgId: opts.org, apiUrlOverride: opts.apiUrl });
+    format(data, { json: opts.json ?? false });
+  }));
+  transcripts.command("get").description("Fetch one conversation transcript and optional trace events").requiredOption("--agent <id>", "Agent ID").requiredOption("--conversation <id>", "Conversation ID").option("--include-traces", "Include ordered trace events").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const params = new URLSearchParams();
+    if (opts.includeTraces) params.set("include_traces", "true");
+    const path2 = withQuery(`/v1/console/agents/${opts.agent}/conversations/${opts.conversation}`, params);
+    const data = await apiFetch(path2, { orgId: opts.org, apiUrlOverride: opts.apiUrl });
+    format(data, { json: opts.json ?? false });
+  }));
+  transcripts.command("export").description("Export recent transcripts as JSON or JSONL").requiredOption("--agent <id>", "Agent ID").option("--q <query>", "Full-text transcript query").option("--from <iso-date>", "Start datetime (ISO8601)").option("--to <iso-date>", "End datetime (ISO8601)").option("--limit <n>", "Rows to export (1-100)", "100").option("--format <value>", "Export format: jsonl or json", "jsonl").option("--hydrate", "Fetch full conversation detail for every exported row").option("--include-traces", "Hydrate each conversation with ordered trace events").option("--no-redact", "Disable default redaction of emails, phone numbers, and obvious secrets").option("--out <path>", "Output file path").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const exportFormat = String(opts.format || "jsonl").trim().toLowerCase();
+    if (!["jsonl", "json"].includes(exportFormat)) {
+      throw new FohError({
+        step: "transcripts.export",
+        error: `Invalid format: ${opts.format}`,
+        remediation: "Use --format jsonl or --format json.",
+        statusCode: 400
+      });
+    }
+    const data = await apiFetch(listPath(opts.agent, { ...opts, page: "1" }), {
+      orgId: opts.org,
+      apiUrlOverride: opts.apiUrl
+    });
+    const listRows = Array.isArray(data.conversations) ? data.conversations : [];
+    const shouldHydrate = Boolean(opts.hydrate || opts.includeTraces);
+    const includeTraces = Boolean(opts.includeTraces);
+    const rawRows = shouldHydrate ? await hydrateRows({
+      agentId: opts.agent,
+      rows: listRows,
+      includeTraces,
+      orgId: opts.org,
+      apiUrl: opts.apiUrl
+    }) : listRows;
+    const replayReadyRows = rawRows.map((conversation) => buildReplayReadyConversation({
+      agentId: opts.agent,
+      conversation
+    }));
+    const rows = opts.redact === false ? replayReadyRows : redactObject(replayReadyRows);
+    const exportPacket = {
+      schema_version: "foh_transcript_export.v2",
+      redaction: {
+        enabled: opts.redact !== false,
+        fields: opts.redact === false ? [] : ["email", "phone", "secret-like-token"]
+      },
+      hydration: {
+        enabled: shouldHydrate,
+        include_traces: includeTraces
+      },
+      conversations: rows
+    };
+    const content = exportFormat === "json" ? stableStringify(exportPacket) : jsonl(rows);
+    if (opts.out) {
+      const outputPath = (0, import_path4.resolve)(String(opts.out));
+      (0, import_fs6.writeFileSync)(outputPath, content, "utf-8");
+      format({
+        schema_version: "foh_transcript_export_result.v1",
+        ok: true,
+        status: "exported",
+        reason_code: "transcripts_exported",
+        summary: `Exported ${rows.length} transcript row(s).`,
+        ids: { agent_id: opts.agent },
+        artifacts: { output_path: outputPath },
+        next_commands: [
+          `foh agent replay --agent ${opts.agent} --conversation <conversation-id> --json`,
+          `foh test run --suite <suite.yml> --agent ${opts.agent} --json`
+        ],
+        format: exportFormat,
+        count: rows.length,
+        redaction: exportPacket.redaction,
+        hydration: exportPacket.hydration,
+        output_path: outputPath
+      }, { json: opts.json ?? false });
+      return;
+    }
+    if (opts.json || exportFormat === "json") {
+      format({
+        schema_version: "foh_transcript_export.v1",
+        ok: true,
+        status: "pass",
+        reason_code: "transcripts_exported",
+        summary: `Prepared ${rows.length} transcript row(s).`,
+        ids: { agent_id: opts.agent },
+        artifacts: {},
+        next_commands: [
+          `foh agent replay --agent ${opts.agent} --conversation <conversation-id> --json`,
+          `foh test run --suite <suite.yml> --agent ${opts.agent} --json`
+        ],
+        redaction: exportPacket.redaction,
+        hydration: exportPacket.hydration,
+        conversations: exportPacket.conversations
+      }, { json: opts.json ?? false });
+      return;
+    }
+    process.stdout.write(content);
+  }));
+}
+
+// src/commands/analytics.ts
+function parsePreset(raw) {
+  const value = String(raw || "7d").trim().toLowerCase();
+  if (value === "today" || value === "7d" || value === "failed" || value === "lead-capture") return value;
+  throw new FohError({
+    step: "analytics.fetch",
+    error: `Invalid preset: ${raw}`,
+    remediation: "Use --preset today, 7d, failed, or lead-capture.",
+    statusCode: 400
+  });
+}
+function presetWindowDays(preset, rawWindowDays) {
+  if (rawWindowDays !== void 0) return parsePositiveInt(String(rawWindowDays), preset === "today" ? 1 : 7, 1, 90);
+  if (preset === "today") return 1;
+  return 7;
+}
+function registerAnalytics(program3) {
+  const analytics = program3.command("analytics").description("Fetch runtime analytics and inspection summaries");
+  analytics.command("fetch").description("Fetch an agent analytics summary from existing reporting lanes").requiredOption("--agent <id>", "Agent ID").option("--preset <value>", "Preset: today, 7d, failed, lead-capture", "7d").option("--window-days <n>", "Lookback window override (1-90)").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const preset = parsePreset(opts.preset);
+    const windowDays = presetWindowDays(preset, opts.windowDays);
+    const qualityParams = new URLSearchParams({ windowDays: String(windowDays), environment: "production" });
+    const conversationParams = new URLSearchParams({
+      page: "1",
+      limit: "10"
+    });
+    if (preset === "failed") conversationParams.set("terminal_state", "failed_visible");
+    if (preset === "lead-capture") conversationParams.set("journey", "lead_capture");
+    const [qualityScorecard, leadDataTrends, loopKpis, conversations, voiceSlo] = await Promise.all([
+      apiFetch(`/v1/console/agents/${opts.agent}/quality-scorecard?${qualityParams.toString()}`, {
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      }),
+      apiFetch(`/v1/console/agents/${opts.agent}/lead-data-trends?windowDays=${windowDays}`, {
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      }),
+      apiFetch(`/v1/console/agents/${opts.agent}/loop-kpis?windowDays=${windowDays}`, {
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      }),
+      apiFetch(withQuery(`/v1/console/agents/${opts.agent}/conversations`, conversationParams), {
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      }),
+      apiFetch(`/v1/console/voice-slo?agentId=${opts.agent}&days=${windowDays}`, {
+        orgId: opts.org,
+        apiUrlOverride: opts.apiUrl
+      }).catch((error2) => ({
+        ok: false,
+        skipped: true,
+        reason_code: "voice_slo_unavailable",
+        message: error2 instanceof Error ? error2.message : String(error2)
+      }))
+    ]);
+    format({
+      schema_version: "foh_analytics_fetch.v1",
+      ok: true,
+      status: "pass",
+      reason_code: "analytics_fetch_completed",
+      summary: `Fetched analytics summary for preset ${preset}.`,
+      ids: {
+        agent_id: opts.agent
+      },
+      checks: [],
+      artifacts: {},
+      agent_id: opts.agent,
+      preset,
+      window_days: windowDays,
+      summaries: {
+        quality_scorecard: qualityScorecard,
+        lead_data_trends: leadDataTrends,
+        loop_kpis: loopKpis,
+        conversations,
+        voice_slo: voiceSlo
+      },
+      next_commands: [
+        `foh transcripts list --agent ${opts.agent} --limit 10 --json`,
+        `foh ops reporting weekly-report --agent ${opts.agent} --window-days ${Math.min(30, windowDays)} --json`
+      ]
+    }, { json: opts.json ?? false });
+  }));
+}
+
 // src/commands/tests.ts
 function registerTests(program3) {
   const tests = program3.command("tests").description("Manage agent test catalog and test-run lifecycle");
@@ -34953,19 +35599,361 @@ function registerTests(program3) {
   }));
 }
 
-// src/commands/ops.ts
-function parseClientErrorSource(raw) {
-  if (!raw) return void 0;
-  const source = String(raw).trim().toLowerCase();
-  if (source === "window" || source === "react" || source === "unhandledrejection") {
-    return source;
-  }
-  throw new FohError({
-    step: "ops.client-errors.report",
-    error: `Invalid --source "${raw}"`,
-    remediation: "Use one of: window, react, unhandledrejection.",
-    statusCode: 400
-  });
+// src/commands/test.ts
+var import_fs8 = require("fs");
+var import_path6 = require("path");
+
+// src/lib/scenario-suite.ts
+var import_fs7 = require("fs");
+var import_path5 = require("path");
+function asStringList(value) {
+  if (typeof value === "string" && value.trim()) return [value.trim()];
+  if (Array.isArray(value)) return value.map((entry) => String(entry || "").trim()).filter(Boolean);
+  return [];
+}
+function getPath(source, path2) {
+  if (!source || typeof source !== "object") return void 0;
+  return path2.split(".").reduce((current, part) => {
+    if (!current || typeof current !== "object") return void 0;
+    return current[part];
+  }, source);
+}
+function valuesEqual(actual, expected) {
+  if (Array.isArray(expected)) {
+    return expected.some((entry) => valuesEqual(actual, entry));
+  }
+  if (expected && typeof expected === "object") {
+    return JSON.stringify(actual) === JSON.stringify(expected);
+  }
+  return String(actual ?? "") === String(expected ?? "");
+}
+function parseStructuredFile(path2) {
+  const raw = (0, import_fs7.readFileSync)(path2, "utf-8");
+  return path2.toLowerCase().endsWith(".json") ? JSON.parse(raw) : load(raw);
+}
+function parseSuiteFile(path2) {
+  const parsed = parseStructuredFile(path2);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new FohError({
+      step: "test.run",
+      error: "Suite file must contain an object",
+      remediation: "Use a JSON/YAML object with scenarios[].turns[].",
+      statusCode: 400
+    });
+  }
+  return parsed;
+}
+function turnFromFixtureEntry(entry) {
+  if (typeof entry === "string" && entry.trim()) return { user: entry.trim() };
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const row = entry;
+  const role = typeof row.role === "string" ? row.role.toLowerCase() : "";
+  if (role && role !== "user") return null;
+  const content = row.user ?? row.message ?? row.content ?? row.text;
+  if (typeof content !== "string" || !content.trim()) return null;
+  return {
+    user: content.trim(),
+    expect: row.expect && typeof row.expect === "object" && !Array.isArray(row.expect) ? row.expect : void 0
+  };
+}
+function loadFixtureTurns(path2) {
+  const parsed = parseStructuredFile(path2);
+  const entries = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.turns) ? parsed.turns : parsed && typeof parsed === "object" && Array.isArray(parsed.messages) ? parsed.messages : [];
+  return entries.map(turnFromFixtureEntry).filter((entry) => !!entry);
+}
+function resolveScenarioTurns(scenario, suitePath) {
+  const inlineTurns = Array.isArray(scenario.turns) ? scenario.turns : [];
+  const fixture = scenario.transcript_fixture || scenario.fixture_transcript || scenario.fixture;
+  if (!fixture) return inlineTurns;
+  const fixturePath = (0, import_path5.resolve)(suitePath, "..", fixture);
+  const fixtureTurns = loadFixtureTurns(fixturePath);
+  return [...fixtureTurns, ...inlineTurns];
+}
+function validateSuite(suite, suitePath) {
+  const scenarios = Array.isArray(suite.scenarios) ? suite.scenarios : [];
+  if (scenarios.length === 0) {
+    throw new FohError({
+      step: "test.run",
+      error: "Suite contains no scenarios",
+      remediation: "Add at least one scenarios[] entry with turns[].",
+      statusCode: 400
+    });
+  }
+  return scenarios.map((scenario) => {
+    const turns = resolveScenarioTurns(scenario, suitePath);
+    if (turns.length === 0) {
+      throw new FohError({
+        step: "test.run",
+        error: `Scenario "${scenario.id || scenario.name || "(unnamed)"}" has no turns`,
+        remediation: "Add inline turns or a fixture_transcript file with user messages.",
+        statusCode: 400
+      });
+    }
+    return { ...scenario, turns };
+  });
+}
+function evaluateReply(reply, expect) {
+  const lowerReply = reply.toLowerCase();
+  const contains = asStringList(expect?.contains);
+  const notContains = asStringList(expect?.not_contains);
+  const failures = [];
+  for (const expected of contains) {
+    if (!lowerReply.includes(expected.toLowerCase())) {
+      failures.push(`missing expected text: ${expected}`);
+    }
+  }
+  for (const forbidden of notContains) {
+    if (lowerReply.includes(forbidden.toLowerCase())) {
+      failures.push(`contained forbidden text: ${forbidden}`);
+    }
+  }
+  return failures;
+}
+function pickVariables(response) {
+  for (const key of ["variables", "context_variables", "lead_data", "extracted_variables"]) {
+    const value = response[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  }
+  return null;
+}
+function pickToolCalls(response) {
+  for (const path2 of ["tool_calls", "toolCalls", "telemetry.tool_calls", "trace.tool_calls"]) {
+    const value = getPath(response, path2);
+    if (Array.isArray(value)) return value;
+  }
+  return [];
+}
+function toolCallName(call) {
+  if (typeof call === "string") return call;
+  if (!call || typeof call !== "object") return "";
+  const row = call;
+  return String(row.name ?? row.tool ?? row.tool_id ?? row.id ?? getPath(row, "function.name") ?? "");
+}
+function pickLeadCapture(response) {
+  for (const key of ["lead_capture", "lead", "lead_data"]) {
+    const value = response[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  }
+  if (response.lead_id || response.leadId) {
+    return { id: response.lead_id ?? response.leadId };
+  }
+  return null;
+}
+function evaluateStructuredExpectations(response, expect, latencyMs) {
+  if (!expect) return [];
+  const failures = [];
+  if (typeof expect.trace_present === "boolean") {
+    const present = Boolean(response.trace_id);
+    if (present !== expect.trace_present) failures.push(`trace presence expected ${expect.trace_present} but got ${present}`);
+  }
+  if (typeof expect.correlation_present === "boolean") {
+    const present = Boolean(response.correlation_id);
+    if (present !== expect.correlation_present) failures.push(`correlation presence expected ${expect.correlation_present} but got ${present}`);
+  }
+  const expectedActions = asStringList(expect.action);
+  if (expectedActions.length > 0) {
+    const actual = String(response.action ?? "");
+    if (!expectedActions.includes(actual)) failures.push(`action expected ${expectedActions.join("|")} but got ${actual || "(empty)"}`);
+  }
+  const expectedTerminalStates = asStringList(expect.terminal_state);
+  if (expectedTerminalStates.length > 0) {
+    const actual = String(response.terminal_state ?? response.terminalState ?? response.action ?? "");
+    if (!expectedTerminalStates.includes(actual)) {
+      failures.push(`terminal_state expected ${expectedTerminalStates.join("|")} but got ${actual || "(empty)"}`);
+    }
+  }
+  const minLatency = expect.latency_ms?.min;
+  const maxLatency = expect.latency_ms?.max ?? expect.max_latency_ms;
+  if (typeof minLatency === "number" && latencyMs < minLatency) {
+    failures.push(`latency_ms expected >=${minLatency} but got ${latencyMs}`);
+  }
+  if (typeof maxLatency === "number" && latencyMs > maxLatency) {
+    failures.push(`latency_ms expected <=${maxLatency} but got ${latencyMs}`);
+  }
+  if (expect.variables && typeof expect.variables === "object") {
+    const variables = pickVariables(response);
+    if (!variables) failures.push("variables expected but response had none");
+    else {
+      for (const [path2, expected] of Object.entries(expect.variables)) {
+        const actual = getPath(variables, path2);
+        if (!valuesEqual(actual, expected)) failures.push(`variables.${path2} expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}`);
+      }
+    }
+  }
+  if (expect.tool_calls) {
+    const calls = pickToolCalls(response);
+    const names = calls.map(toolCallName).filter(Boolean);
+    const includes = asStringList(expect.tool_calls.includes);
+    const excludes = asStringList(expect.tool_calls.excludes);
+    for (const name of includes) {
+      if (!names.includes(name)) failures.push(`tool_calls missing expected tool: ${name}`);
+    }
+    for (const name of excludes) {
+      if (names.includes(name)) failures.push(`tool_calls contained forbidden tool: ${name}`);
+    }
+    if (typeof expect.tool_calls.min_count === "number" && calls.length < expect.tool_calls.min_count) {
+      failures.push(`tool_calls expected >=${expect.tool_calls.min_count} but got ${calls.length}`);
+    }
+    if (typeof expect.tool_calls.max_count === "number" && calls.length > expect.tool_calls.max_count) {
+      failures.push(`tool_calls expected <=${expect.tool_calls.max_count} but got ${calls.length}`);
+    }
+  }
+  if (expect.escalation) {
+    const requested = Boolean(getPath(response, "escalation.requested") ?? response.handoff?.requested);
+    if (typeof expect.escalation.requested === "boolean" && requested !== expect.escalation.requested) {
+      failures.push(`escalation.requested expected ${expect.escalation.requested} but got ${requested}`);
+    }
+    const expectedReasons = asStringList(expect.escalation.reason);
+    if (expectedReasons.length > 0) {
+      const actual = String(getPath(response, "escalation.reason") ?? response.handoff?.reason ?? "");
+      if (!expectedReasons.includes(actual)) failures.push(`escalation.reason expected ${expectedReasons.join("|")} but got ${actual || "(empty)"}`);
+    }
+  }
+  if (expect.lead_capture) {
+    const lead = pickLeadCapture(response);
+    if (expect.lead_capture.required === true && !lead) failures.push("lead_capture expected but response had none");
+    for (const field of expect.lead_capture.fields || []) {
+      const actual = lead ? getPath(lead, field) : void 0;
+      if (actual == null || actual === "") failures.push(`lead_capture.${field} missing`);
+    }
+  }
+  if (expect.fields && typeof expect.fields === "object") {
+    for (const [path2, expected] of Object.entries(expect.fields)) {
+      const actual = getPath(response, path2);
+      if (!valuesEqual(actual, expected)) failures.push(`fields.${path2} expected ${JSON.stringify(expected)} but got ${JSON.stringify(actual)}`);
+    }
+  }
+  return failures;
+}
+
+// src/commands/test.ts
+function registerTest(program3) {
+  const test = program3.command("test").description("Run local scenario suites against runtime channels");
+  test.command("run").description("Run a local YAML/JSON scenario suite").requiredOption("--suite <path>", "Suite YAML/JSON path").option("--agent <id>", "Agent ID (defaults to suite.agent)").option("--out <path>", "Write report JSON to path").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const suitePath = (0, import_path6.resolve)(String(opts.suite));
+    const suite = parseSuiteFile(suitePath);
+    const agentId = String(opts.agent || suite.agent || "").trim();
+    if (!agentId) {
+      throw new FohError({
+        step: "test.run",
+        error: "Missing agent ID",
+        remediation: "Pass --agent <id> or include agent in the suite file.",
+        statusCode: 400
+      });
+    }
+    const scenarios = validateSuite(suite, suitePath);
+    const ensure = await apiFetch("/v1/console/channels/widget/ensure", {
+      method: "POST",
+      body: JSON.stringify({ agentId }),
+      orgId: opts.org,
+      apiUrlOverride: opts.apiUrl
+    });
+    const publicKey = ensure.channel?.public_key;
+    if (!publicKey) {
+      throw new FohError({
+        step: "test.run",
+        error: "Widget channel public key missing",
+        remediation: `Run: foh widget ensure --agent ${agentId} --json`,
+        statusCode: 409
+      });
+    }
+    let passed = 0;
+    let failed = 0;
+    const scenarioResults = [];
+    for (let scenarioIndex = 0; scenarioIndex < scenarios.length; scenarioIndex += 1) {
+      const scenario = scenarios[scenarioIndex];
+      let conversationId;
+      const turnResults = [];
+      for (let turnIndex = 0; turnIndex < scenario.turns.length; turnIndex += 1) {
+        const turn = scenario.turns[turnIndex];
+        const message = String(turn.user || turn.message || "").trim();
+        if (!message) {
+          failed += 1;
+          turnResults.push({ turn: turnIndex + 1, ok: false, failures: ["missing user/message"] });
+          continue;
+        }
+        const start = Date.now();
+        const response = await apiFetch("/v1/widget/inbound", {
+          method: "POST",
+          body: JSON.stringify({
+            channel_public_key: publicKey,
+            message_body: message,
+            preview: true,
+            ...conversationId ? { conversation_id: conversationId } : {}
+          }),
+          apiUrlOverride: opts.apiUrl
+        });
+        const latencyMs = Date.now() - start;
+        conversationId = response.conversationId || conversationId;
+        const reply = String(response.reply || "");
+        const failures = reply ? [
+          ...evaluateReply(reply, turn.expect),
+          ...evaluateStructuredExpectations(response, turn.expect, latencyMs)
+        ] : ["empty reply"];
+        if (failures.length === 0) passed += 1;
+        else failed += 1;
+        turnResults.push({
+          turn: turnIndex + 1,
+          ok: failures.length === 0,
+          message,
+          reply,
+          failures,
+          latency_ms: latencyMs,
+          conversation_id: response.conversationId ?? null,
+          trace_id: response.trace_id ?? null,
+          correlation_id: response.correlation_id ?? null,
+          action: response.action ?? null,
+          handoff: response.handoff ?? null
+        });
+      }
+      scenarioResults.push({
+        id: scenario.id || `scenario-${scenarioIndex + 1}`,
+        name: scenario.name ?? null,
+        ok: turnResults.every((turn) => turn.ok),
+        turns: turnResults
+      });
+    }
+    const report = {
+      schema_version: "foh_local_scenario_suite_report.v1",
+      ok: failed === 0,
+      status: failed === 0 ? "pass" : "fail",
+      reason_code: failed === 0 ? "scenario_suite_passed" : "scenario_suite_failed",
+      summary: failed === 0 ? "All scenario-suite assertions passed." : `${failed} scenario-suite assertion(s) failed.`,
+      ids: {
+        agent_id: agentId
+      },
+      artifacts: {},
+      next_commands: failed === 0 ? [`foh prove --agent ${agentId} --json`] : [`foh transcripts list --agent ${agentId} --limit 10 --json`],
+      suite_path: suitePath,
+      agent_id: agentId,
+      passed,
+      failed,
+      scenarios: scenarioResults
+    };
+    if (opts.out) {
+      const out = (0, import_path6.resolve)(String(opts.out));
+      (0, import_fs8.writeFileSync)(out, stableStringify(report), "utf-8");
+      format({ ...report, output_path: out }, { json: opts.json ?? false });
+    } else {
+      format(report, { json: opts.json ?? false });
+    }
+    if (failed > 0) markCommandFailed(1);
+  }));
+}
+
+// src/commands/ops.ts
+function parseClientErrorSource(raw) {
+  if (!raw) return void 0;
+  const source = String(raw).trim().toLowerCase();
+  if (source === "window" || source === "react" || source === "unhandledrejection") {
+    return source;
+  }
+  throw new FohError({
+    step: "ops.client-errors.report",
+    error: `Invalid --source "${raw}"`,
+    remediation: "Use one of: window, react, unhandledrejection.",
+    statusCode: 400
+  });
 }
 function registerOps(program3) {
   const ops = program3.command("ops").description("Operational/reporting workflows (incidents, recommendations, traces, evidence)");
@@ -35367,8 +36355,210 @@ function registerDiag(program3) {
 }
 
 // src/commands/bug.ts
-var import_fs5 = require("fs");
-var import_path4 = require("path");
+var import_fs10 = require("fs");
+var import_path8 = require("path");
+
+// src/lib/improvement-packet.ts
+var import_fs9 = require("fs");
+var import_path7 = require("path");
+var IMPROVEMENT_SOURCE_TYPES = [
+  "setup_failure",
+  "proof_failure",
+  "replay_failure",
+  "knowledge_miss",
+  "runtime_miss",
+  "live_proof_failure"
+];
+var IMPROVEMENT_DECISIONS = [
+  "ignore",
+  "fix_docs",
+  "fix_config",
+  "fix_runtime",
+  "add_test"
+];
+var SECRET_LEAK_RE = /\b(?:sk|pk|xai|whsec|EAAN)[A-Za-z0-9_\-]{16,}\b/i;
+var MAX_REDACTED_SOURCE_BYTES = 4e3;
+function asRecord2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function nonEmpty2(value) {
+  const text = String(value ?? "").trim();
+  return text.length > 0 ? text : void 0;
+}
+function getPath2(value, path2) {
+  let current = value;
+  for (const segment of path2.split(".")) {
+    const record2 = asRecord2(current);
+    if (!record2) return void 0;
+    current = record2[segment];
+  }
+  return current;
+}
+function parseEnum(raw, allowed, label) {
+  const value = nonEmpty2(raw);
+  if (!value) return void 0;
+  if (allowed.includes(value)) return value;
+  throw new FohError({
+    step: "bug.improve",
+    error: `Invalid ${label} "${value}"`,
+    remediation: `Use one of: ${allowed.join(", ")}.`,
+    statusCode: 400
+  });
+}
+function inferSourceType(artifact) {
+  const schema2 = nonEmpty2(getPath2(artifact, "schema_version")) || "";
+  const status = nonEmpty2(getPath2(artifact, "status")) || "";
+  if (schema2.includes("knowledge_query") || nonEmpty2(getPath2(artifact, "failure_packet.schema_version"))?.includes("knowledge_query")) {
+    return "knowledge_miss";
+  }
+  if (schema2.includes("agent_replay") || status.includes("replay")) return "replay_failure";
+  if (schema2.includes("proof") || schema2.includes("live_proof")) return schema2.includes("live") ? "live_proof_failure" : "proof_failure";
+  if (schema2.includes("setup")) return "setup_failure";
+  return "runtime_miss";
+}
+function inferReasonCode(artifact) {
+  const direct = nonEmpty2(getPath2(artifact, "reason_code"));
+  if (direct) return direct;
+  const nested = nonEmpty2(getPath2(artifact, "failure_packet.reason_code"));
+  if (nested) return nested;
+  const checks = getPath2(artifact, "checks");
+  if (Array.isArray(checks)) {
+    for (const check2 of checks) {
+      const reason = nonEmpty2(getPath2(check2, "reason_code"));
+      const status = nonEmpty2(getPath2(check2, "status"));
+      if (reason && status !== "pass" && status !== "success") return reason;
+    }
+  }
+  return nonEmpty2(getPath2(artifact, "status"));
+}
+function inferPromotionDecision(sourceType) {
+  if (sourceType === "knowledge_miss") return "fix_docs";
+  if (sourceType === "setup_failure" || sourceType === "proof_failure" || sourceType === "live_proof_failure") return "fix_config";
+  if (sourceType === "replay_failure" || sourceType === "runtime_miss") return "add_test";
+  return "fix_runtime";
+}
+function collectIds(artifact, explicit = {}) {
+  const source = getPath2(artifact, "source");
+  const ids = {
+    org_id: explicit.org_id ?? nonEmpty2(getPath2(artifact, "ids.org_id")) ?? nonEmpty2(getPath2(artifact, "org_id")),
+    agent_id: explicit.agent_id ?? nonEmpty2(getPath2(source, "agent_id")) ?? nonEmpty2(getPath2(artifact, "ids.agent_id")) ?? nonEmpty2(getPath2(artifact, "agent_id")),
+    conversation_id: explicit.conversation_id ?? nonEmpty2(getPath2(source, "conversation_id")) ?? nonEmpty2(getPath2(artifact, "ids.conversation_id")) ?? nonEmpty2(getPath2(artifact, "conversation_id")),
+    trace_id: explicit.trace_id ?? nonEmpty2(getPath2(source, "trace_id")) ?? nonEmpty2(getPath2(artifact, "ids.trace_id")) ?? nonEmpty2(getPath2(artifact, "trace_id")),
+    correlation_id: explicit.correlation_id ?? nonEmpty2(getPath2(artifact, "ids.correlation_id")) ?? nonEmpty2(getPath2(artifact, "correlation_id")),
+    proof_artifact: explicit.proof_artifact
+  };
+  return Object.fromEntries(Object.entries(ids).filter(([, value]) => value !== void 0));
+}
+function compactSourceArtifact(artifact) {
+  const redacted = redactObject(artifact);
+  const text = JSON.stringify(redacted);
+  if (text.length <= MAX_REDACTED_SOURCE_BYTES) {
+    return { truncated: false, value: redacted };
+  }
+  return {
+    truncated: true,
+    bytes_before_truncate: text.length,
+    value_preview: text.slice(0, MAX_REDACTED_SOURCE_BYTES)
+  };
+}
+function defaultNextCommands(input) {
+  const commands = [];
+  if (input.ids.trace_id && input.ids.agent_id) {
+    commands.push(`foh tests from-trace --agent ${input.ids.agent_id} --trace ${input.ids.trace_id} --json`);
+    commands.push(`foh agent replay --agent ${input.ids.agent_id} --trace ${input.ids.trace_id} --json`);
+  }
+  if (input.ids.conversation_id && input.ids.agent_id) {
+    commands.push(`foh agent replay --agent ${input.ids.agent_id} --conversation ${input.ids.conversation_id} --json`);
+  }
+  if (input.sourceType === "knowledge_miss" && input.ids.agent_id) {
+    commands.push(`foh knowledge query --agent ${input.ids.agent_id} --text "<question>" --explain --json`);
+  }
+  if (input.sourceArtifactPath) {
+    commands.push(`foh bug report --out test-results/bug-report.from-improvement.json --command "investigate ${input.reasonCode}" --request-url https://front-of-house-api.stldocs.app/api --response-status 500 --next-check "Review ${(0, import_path7.basename)(input.sourceArtifactPath)}" --json`);
+  }
+  return commands;
+}
+function assertOrgBoundary(artifact, explicitOrgId) {
+  const artifactOrgId = nonEmpty2(getPath2(artifact, "ids.org_id")) ?? nonEmpty2(getPath2(artifact, "org_id"));
+  if (explicitOrgId && artifactOrgId && explicitOrgId !== artifactOrgId) {
+    throw new FohError({
+      step: "bug.improve",
+      error: "Org boundary check failed for improvement packet.",
+      remediation: "Use the org id from the source artifact, or omit --org when building a local redacted packet.",
+      statusCode: 403
+    });
+  }
+}
+function assertRedacted(value) {
+  const text = JSON.stringify(value);
+  if (SECRET_LEAK_RE.test(text)) {
+    throw new FohError({
+      step: "bug.improve",
+      error: "Improvement packet still contains a secret-like value after redaction.",
+      remediation: "Remove raw credentials from the source artifact and rebuild the packet.",
+      statusCode: 400
+    });
+  }
+}
+function readSourceArtifact(path2) {
+  if (!path2) return null;
+  try {
+    return JSON.parse((0, import_fs9.readFileSync)(path2, "utf-8"));
+  } catch (error2) {
+    throw new FohError({
+      step: "bug.improve",
+      error: `Failed to read source artifact: ${error2 instanceof Error ? error2.message : String(error2)}`,
+      remediation: "Pass --from-file with a readable JSON artifact.",
+      statusCode: 400
+    });
+  }
+}
+function buildImprovementPacket(input) {
+  const artifact = input.sourceArtifact ?? null;
+  const sourceType = parseEnum(input.sourceType, IMPROVEMENT_SOURCE_TYPES, "--source-type") ?? inferSourceType(artifact);
+  const promotionDecision = parseEnum(input.promotionDecision, IMPROVEMENT_DECISIONS, "--recommendation") ?? inferPromotionDecision(sourceType);
+  const ids = collectIds(artifact, input.ids);
+  assertOrgBoundary(artifact, input.ids?.org_id);
+  const reasonCode = nonEmpty2(input.reasonCode) ?? inferReasonCode(artifact);
+  if (!reasonCode) {
+    throw new FohError({
+      step: "bug.improve",
+      error: "Missing improvement reason code.",
+      remediation: "Pass --reason-code <code> or build from a source artifact that includes reason_code/status.",
+      statusCode: 400
+    });
+  }
+  const evidenceSummary = redactString(
+    nonEmpty2(input.evidenceSummary) ?? nonEmpty2(getPath2(artifact, "summary")) ?? `Improvement candidate generated from ${sourceType} with reason ${reasonCode}.`
+  );
+  const nextCommands = Array.from(new Set([
+    ...input.nextCommands ?? [],
+    ...defaultNextCommands({ sourceType, ids, sourceArtifactPath: input.sourceArtifactPath, reasonCode })
+  ].map((command) => command.trim()).filter(Boolean)));
+  const packet = {
+    schema_version: "foh_improvement_packet.v1",
+    created_at: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    source_type: sourceType,
+    reason_code: reasonCode,
+    promotion_decision: promotionDecision,
+    ids,
+    evidence: {
+      summary: evidenceSummary,
+      source_artifact_path: input.sourceArtifactPath ?? null,
+      source_command: input.sourceCommand ?? null,
+      redaction: {
+        enabled: true,
+        fields: ["email", "phone", "secret-like-token"]
+      },
+      redacted_source: artifact ? compactSourceArtifact(artifact) : null
+    },
+    next_commands: nextCommands
+  };
+  assertRedacted(packet);
+  return packet;
+}
+
+// src/commands/bug.ts
 var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 var MAX_BODY_PREVIEW_LENGTH = 200;
 function parseMethod(raw) {
@@ -35484,14 +36674,18 @@ function parseRequestBody(raw) {
   }
 }
 function writeJsonArtifact(path2, value) {
-  const absolutePath = (0, import_path4.resolve)(path2);
-  (0, import_fs5.mkdirSync)((0, import_path4.dirname)(absolutePath), { recursive: true });
-  (0, import_fs5.writeFileSync)(absolutePath, stableStringify(value), "utf-8");
+  const absolutePath = (0, import_path8.resolve)(path2);
+  (0, import_fs10.mkdirSync)((0, import_path8.dirname)(absolutePath), { recursive: true });
+  (0, import_fs10.writeFileSync)(absolutePath, stableStringify(value), "utf-8");
   return absolutePath;
 }
 function defaultArtifactPath() {
   const timestamp2 = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  return (0, import_path4.resolve)(`test-results/bug-report.${timestamp2}.json`);
+  return (0, import_path8.resolve)(`test-results/bug-report.${timestamp2}.json`);
+}
+function defaultImprovementArtifactPath() {
+  const timestamp2 = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return (0, import_path8.resolve)(`test-results/improvement-packet.${timestamp2}.json`);
 }
 async function resolveBugReportWizardInputs(opts) {
   if (!opts.wizard) return opts;
@@ -35641,6 +36835,44 @@ function registerBug(program3) {
       throw e;
     }
   });
+  bug.command("improve").description("Write a redacted failure-to-improvement packet from a setup/proof/replay/knowledge/runtime artifact").option("--from-file <path>", "Source JSON artifact to convert into an improvement packet").option("--out <path>", "Output JSON file path for improvement packet").option("--source-type <type>", "setup_failure|proof_failure|replay_failure|knowledge_miss|runtime_miss|live_proof_failure").option("--reason-code <code>", "Deterministic failure reason code").option("--recommendation <decision>", "ignore|fix_docs|fix_config|fix_runtime|add_test").option("--evidence-summary <text>", "Compact redacted evidence summary").option("--source-command <text>", "Command or operation that produced the source artifact").option("--org <id>", "Org ID for boundary check and packet IDs").option("--agent <id>", "Agent ID to attach").option("--conversation <id>", "Conversation ID to attach").option("--trace <id>", "Trace ID to attach").option("--correlation <id>", "Correlation ID to attach").option("--proof-artifact <path>", "Proof artifact path to attach").option(
+    "--next-command <text>",
+    "Deterministic next command (repeat this flag for multiple commands)",
+    (value, previous = []) => [...previous, value],
+    []
+  ).option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const sourceArtifact = readSourceArtifact(opts.fromFile);
+    const outPath = String(opts.out || defaultImprovementArtifactPath());
+    const packet = buildImprovementPacket({
+      sourceArtifact,
+      sourceArtifactPath: opts.fromFile,
+      sourceType: opts.sourceType,
+      reasonCode: opts.reasonCode,
+      evidenceSummary: opts.evidenceSummary,
+      promotionDecision: opts.recommendation,
+      sourceCommand: opts.sourceCommand,
+      ids: {
+        org_id: opts.org,
+        agent_id: opts.agent,
+        conversation_id: opts.conversation,
+        trace_id: opts.trace,
+        correlation_id: opts.correlation,
+        proof_artifact: opts.proofArtifact
+      },
+      nextCommands: Array.isArray(opts.nextCommand) ? opts.nextCommand : []
+    });
+    const artifactPath = writeJsonArtifact(outPath, packet);
+    format(cliEnvelope({
+      schemaVersion: "foh_improvement_packet_result.v1",
+      status: "exported",
+      reasonCode: "improvement_packet_created",
+      summary: "Improvement packet created.",
+      ids: packet.ids,
+      artifacts: { improvement_packet: artifactPath },
+      nextCommands: packet.next_commands,
+      extra: { packet }
+    }), { json: opts.json ?? false });
+  }));
   bug.command("list").description("List bug reports from the FOH bug inbox").option("--state <state>", "Filter by state: open, triaged, closed").option("--severity <level>", "Filter by severity: low, medium, high, critical").option("--source <source>", "Filter by source: cli, eval, api").option("--request-id <id>", "Filter by request id").option("--search <text>", "Case-insensitive command search").option("--limit <n>", "Result limit (1-200)", "50").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "Internal API base URL override (operators only)").option("--json", "Output as JSON").action(async (opts) => {
     try {
       const params = new URLSearchParams();
@@ -35683,6 +36915,344 @@ function registerBug(program3) {
   });
 }
 
+// src/commands/prove.ts
+function categoryForCheck(name) {
+  if (name === "auth") return "auth";
+  if (name === "contact_channel" || name === "voice_realtime_health") return "voice";
+  if (name.startsWith("widget_")) return "widget";
+  if (name === "simulation_certification") return "certification";
+  if (name === "agent_validation") return "publish_readiness";
+  return "setup";
+}
+function pass(name, summary, detail) {
+  return { name, category: categoryForCheck(name), status: "pass", reason_code: `${name}_ok`, summary, detail };
+}
+function hold(name, reasonCode, summary, nextCommand, detail) {
+  return { name, category: categoryForCheck(name), status: "hold", reason_code: reasonCode, summary, next_command: nextCommand, detail };
+}
+function fail(name, reasonCode, error2, nextCommand) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return { name, category: categoryForCheck(name), status: "fail", reason_code: reasonCode, summary: message, next_command: nextCommand };
+}
+function skipped(name, reasonCode, summary, nextCommand) {
+  return { name, category: categoryForCheck(name), status: "skipped", reason_code: reasonCode, summary, next_command: nextCommand };
+}
+function hasBlockingChecks(checks) {
+  return checks.some((check2) => check2.status === "hold" || check2.status === "fail");
+}
+function publicKeyFromEnsureResponse(response) {
+  const record2 = response && typeof response === "object" ? response : {};
+  const channel = record2.channel && typeof record2.channel === "object" ? record2.channel : {};
+  const publicKey = channel.public_key ?? record2.widget_public_key ?? record2.public_key;
+  return typeof publicKey === "string" && publicKey.trim() ? publicKey.trim() : void 0;
+}
+function publicKeyFromEmbedResponse(response) {
+  const record2 = response && typeof response === "object" ? response : {};
+  const publicKey = record2.widget_public_key ?? record2.public_key;
+  return typeof publicKey === "string" && publicKey.trim() ? publicKey.trim() : void 0;
+}
+function normalizeMission(raw) {
+  const value = String(raw || "setup").trim().toLowerCase();
+  if (value === "setup" || value === "widget" || value === "voice" || value === "publish") return value;
+  return "setup";
+}
+function normalizeMutationMode(raw, repair) {
+  if (repair) return "ensure";
+  const value = String(raw || "read-only").trim().toLowerCase();
+  return value === "ensure" ? "ensure" : "read-only";
+}
+function agentIdFromList(response) {
+  const agents = Array.isArray(response.agents) ? response.agents : [];
+  const usable = agents.filter((agent) => typeof agent.id === "string" && agent.id.trim());
+  if (usable.length === 1) return { agentId: usable[0].id, count: usable.length };
+  if (usable.length === 0) return { count: 0, reason: "no_agents" };
+  return { count: usable.length, reason: "multiple_agents" };
+}
+function firstUsableOrgId(response) {
+  const record2 = response && typeof response === "object" ? response : {};
+  const orgs = Array.isArray(record2.orgs) ? record2.orgs : [];
+  const usable = orgs.map((org) => org && typeof org === "object" ? org : {}).map((org) => String(org.org_id ?? org.id ?? "").trim()).filter(Boolean);
+  return { orgId: usable.length === 1 ? usable[0] : void 0, count: usable.length };
+}
+function registerProve(program3) {
+  program3.command("prove").description("Produce one setup/runtime proof bundle for an agent").option("--agent <id>", "Agent ID to prove").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--cert-mode <m>", "Simulation cert mode: quick, full, stress", "quick").option("--cert-adaptive-runs <n>", "Adaptive runs for full/stress certification", "30").option("--cert-max-improvement-rounds <n>", "Max prompt improvement rounds in cert loop (0-5)", "1").option("--mission <mission>", "Proof mission: setup, widget, voice, publish", "setup").option("--mutation-mode <mode>", "Proof mutation mode: read-only or ensure", "read-only").option("--repair", "Alias for --mutation-mode ensure").option("--require-phone", "Hold proof if no phone/contact number is provisioned").option("--skip-cert", "Skip simulation certification check").option("--skip-smoke", "Skip widget runtime smoke check").option("--skip-voice-health", "Skip realtime voice provider health check").option("--out <path>", "Write signed proof report JSON to this path").option("--strict", "Exit non-zero unless all non-skipped checks pass").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const checks = [];
+    const mission = normalizeMission(opts.mission);
+    const mutationMode = normalizeMutationMode(opts.mutationMode, Boolean(opts.repair));
+    const ctx = {
+      tokenPresent: false,
+      traceIds: [],
+      correlationIds: []
+    };
+    try {
+      const creds = loadCredentials(opts.apiUrl);
+      ctx.apiUrl = creds.apiUrl;
+      ctx.tokenPresent = Boolean(creds.token);
+      ctx.orgId = opts.org || creds.orgId;
+      checks.push(pass("auth", "CLI credentials are present and not expired.", {
+        api_url: creds.apiUrl,
+        org_id_from_credentials: creds.orgId ?? null
+      }));
+    } catch (error2) {
+      checks.push(hold("auth", "auth_missing_or_expired", "CLI is not authenticated.", "foh auth login --web", {
+        message: error2 instanceof Error ? error2.message : String(error2)
+      }));
+    }
+    if (ctx.tokenPresent && !ctx.orgId) {
+      try {
+        const orgs = await apiFetch("/v1/console/auth/my-orgs", { apiUrlOverride: opts.apiUrl });
+        const resolved = firstUsableOrgId(orgs);
+        if (resolved.orgId) {
+          ctx.orgId = resolved.orgId;
+          checks.push(pass("org", "Resolved the only available org.", { org_id: resolved.orgId }));
+        } else {
+          checks.push(hold(
+            "org",
+            resolved.count === 0 ? "org_missing" : "org_ambiguous",
+            resolved.count === 0 ? "No usable org was found for this account." : `Found ${resolved.count} orgs; choose one explicitly.`,
+            "foh org list --json && foh org use --org <org-id>",
+            { org_count: resolved.count }
+          ));
+        }
+      } catch (error2) {
+        checks.push(fail("org", "org_resolution_failed", error2, "foh org list --json"));
+      }
+    } else if (ctx.orgId) {
+      checks.push(pass("org", "Org context is selected.", { org_id: ctx.orgId }));
+    } else {
+      checks.push(skipped("org", "auth_required", "Skipped until authentication is fixed.", "foh auth login --web"));
+    }
+    if (ctx.orgId) {
+      if (opts.agent) {
+        ctx.agentId = String(opts.agent);
+        checks.push(pass("agent_selection", "Using explicitly supplied agent.", { agent_id: ctx.agentId }));
+      } else {
+        try {
+          const list = await apiFetch("/v1/console/agents", {
+            orgId: ctx.orgId,
+            apiUrlOverride: opts.apiUrl
+          });
+          const resolved = agentIdFromList(list);
+          if (resolved.agentId) {
+            ctx.agentId = resolved.agentId;
+            checks.push(pass("agent_selection", "Resolved the only available agent.", { agent_id: resolved.agentId }));
+          } else {
+            checks.push(hold(
+              "agent_selection",
+              resolved.reason === "no_agents" ? "agent_missing" : "agent_ambiguous",
+              resolved.reason === "no_agents" ? "No agent exists in this org." : `Found ${resolved.count} agents; choose one explicitly.`,
+              resolved.reason === "no_agents" ? "foh setup --json" : "foh agent list --json && foh prove --agent <agent-id> --json",
+              { agent_count: resolved.count }
+            ));
+          }
+        } catch (error2) {
+          checks.push(fail("agent_selection", "agent_selection_failed", error2, "foh agent list --json"));
+        }
+      }
+    } else {
+      checks.push(skipped("agent_selection", "org_required", "Skipped until org context is fixed.", "foh org use --org <org-id>"));
+    }
+    if (ctx.agentId) {
+      try {
+        const validation = await apiFetch(`/v1/console/agents/${ctx.agentId}/validate`, {
+          method: "POST",
+          orgId: ctx.orgId,
+          apiUrlOverride: opts.apiUrl
+        });
+        const issues = Array.isArray(validation.issues) ? validation.issues : [];
+        if (validation.ok === false || issues.length > 0) {
+          checks.push(hold("agent_validation", "agent_validation_issues", `Agent validation returned ${issues.length} issue(s).`, `foh agent validate --agent ${ctx.agentId} --json`, validation));
+        } else {
+          checks.push(pass("agent_validation", "Agent validation passed.", validation));
+        }
+      } catch (error2) {
+        checks.push(fail("agent_validation", "agent_validation_failed", error2, `foh agent validate --agent ${ctx.agentId} --json`));
+      }
+      if (ctx.orgId) {
+        try {
+          const onboarding = await apiFetch(`/v1/console/org/${ctx.orgId}/onboarding`, {
+            orgId: ctx.orgId,
+            apiUrlOverride: opts.apiUrl
+          });
+          const phoneNumber = typeof onboarding.phone_number === "string" && onboarding.phone_number.trim() ? onboarding.phone_number.trim() : null;
+          if (phoneNumber) {
+            checks.push(pass("contact_channel", "Contact phone number is provisioned.", {
+              phone_number_present: true,
+              provisioning_status: onboarding.provisioning_status ?? null
+            }));
+          } else if (opts.requirePhone || mission === "voice") {
+            checks.push(hold("contact_channel", "contact_phone_missing", "No phone/contact number is provisioned for this org.", `foh provision buy --org ${ctx.orgId} --json`, {
+              provisioning_status: onboarding.provisioning_status ?? null,
+              mission
+            }));
+          } else {
+            checks.push(skipped("contact_channel", "contact_phone_not_required", "No phone/contact number is provisioned; pass --require-phone to make this a blocker.", `foh provision buy --org ${ctx.orgId} --json`));
+          }
+        } catch (error2) {
+          checks.push(fail("contact_channel", "contact_channel_check_failed", error2, `foh provision status --org ${ctx.orgId} --json`));
+        }
+      }
+      if (opts.skipVoiceHealth) {
+        checks.push(skipped("voice_realtime_health", "operator_skipped", "Skipped by --skip-voice-health.", "foh voice realtime-health --json"));
+      } else {
+        try {
+          const health = await apiFetch(
+            "/v1/console/realtime/health",
+            { apiUrlOverride: opts.apiUrl }
+          );
+          const providers = Array.isArray(health.providers) ? health.providers : [];
+          if (providers.length === 0) {
+            checks.push(skipped("voice_realtime_health", "voice_health_no_providers", "Realtime voice health returned no providers.", "foh voice realtime-health --json"));
+          } else if (providers.every((provider) => provider?.ready === true)) {
+            checks.push(pass("voice_realtime_health", "Realtime voice providers are ready.", {
+              provider_count: providers.length
+            }));
+          } else {
+            checks.push(hold("voice_realtime_health", "voice_realtime_provider_not_ready", "One or more realtime voice providers are not ready.", "foh voice realtime-health --json", {
+              providers
+            }));
+          }
+        } catch (error2) {
+          checks.push(fail("voice_realtime_health", "voice_realtime_health_failed", error2, "foh voice realtime-health --json"));
+        }
+      }
+      try {
+        const embed = await apiFetch("/v1/console/channels/widget/embed-snippet", {
+          orgId: ctx.orgId,
+          apiUrlOverride: opts.apiUrl,
+          headers: { "x-agent-id": ctx.agentId }
+        });
+        const publicKey = publicKeyFromEmbedResponse(embed);
+        if (publicKey) {
+          ctx.widgetPublicKey = publicKey;
+          checks.push(pass("widget_channel", "Widget channel is available in read-only proof mode.", {
+            public_key_present: true,
+            mutation_mode: mutationMode
+          }));
+        }
+        if (typeof embed.snippet === "string" && embed.snippet.trim()) {
+          checks.push(pass("widget_embed", "Widget embed snippet is available.", { snippet_present: true }));
+        } else {
+          checks.push(hold("widget_embed", "widget_embed_missing", "Widget embed snippet is missing.", `foh widget embed-snippet --agent ${ctx.agentId}`));
+        }
+      } catch (error2) {
+        if (mutationMode === "ensure") {
+          try {
+            const ensure = await apiFetch("/v1/console/channels/widget/ensure", {
+              method: "POST",
+              body: JSON.stringify({ agentId: ctx.agentId }),
+              orgId: ctx.orgId,
+              apiUrlOverride: opts.apiUrl
+            });
+            const publicKey = publicKeyFromEnsureResponse(ensure);
+            if (!publicKey) {
+              checks.push(hold("widget_channel", "widget_public_key_missing", "Widget channel ensure returned no public key.", `foh widget ensure --agent ${ctx.agentId} --json`, ensure));
+            } else {
+              ctx.widgetPublicKey = publicKey;
+              checks.push(pass("widget_channel", "Widget channel was ensured explicitly.", {
+                public_key_present: true,
+                mutation_mode: mutationMode
+              }));
+            }
+            checks.push(skipped("widget_embed", "widget_embed_recheck_required", "Widget channel was ensured; rerun read-only proof to verify embed snippet.", `foh prove --agent ${ctx.agentId} --mutation-mode read-only --json`));
+          } catch (ensureError) {
+            checks.push(fail("widget_channel", "widget_channel_ensure_failed", ensureError, `foh widget ensure --agent ${ctx.agentId} --json`));
+            checks.push(skipped("widget_embed", "widget_channel_required", "Skipped because widget channel could not be ensured.", `foh widget ensure --agent ${ctx.agentId} --json`));
+          }
+        } else {
+          checks.push(hold("widget_channel", "widget_channel_missing_read_only", "Widget channel/embed was not observable in read-only proof mode.", `foh prove --agent ${ctx.agentId} --mutation-mode ensure --json`, {
+            message: error2 instanceof Error ? error2.message : String(error2),
+            mutation_mode: mutationMode
+          }));
+          checks.push(skipped("widget_embed", "widget_channel_required", "Skipped because widget channel was not observable.", `foh widget ensure --agent ${ctx.agentId} --json`));
+        }
+      }
+      if (opts.skipSmoke) {
+        checks.push(skipped("widget_smoke", "operator_skipped", "Skipped by --skip-smoke.", `foh widget smoke --agent ${ctx.agentId} --json`));
+      } else if (!ctx.widgetPublicKey) {
+        checks.push(skipped("widget_smoke", "widget_public_key_required", "Skipped because widget public key is unavailable.", `foh widget ensure --agent ${ctx.agentId} --json`));
+      } else {
+        try {
+          const smoke = await runWidgetSmoke(ctx.widgetPublicKey, opts.apiUrl);
+          ctx.conversationId = smoke.conversation_id;
+          ctx.traceIds = smoke.trace_ids;
+          ctx.correlationIds = smoke.correlation_ids;
+          if (smoke.failed > 0) {
+            checks.push(hold("widget_smoke", "widget_smoke_failed", `${smoke.failed} widget smoke turn(s) failed.`, `foh widget smoke --agent ${ctx.agentId} --json`, smoke));
+          } else {
+            checks.push(pass("widget_smoke", "Widget runtime smoke passed.", smoke));
+          }
+        } catch (error2) {
+          checks.push(fail("widget_smoke", "widget_smoke_failed", error2, `foh widget smoke --agent ${ctx.agentId} --json`));
+        }
+      }
+      if (opts.skipCert) {
+        checks.push(skipped("simulation_certification", "operator_skipped", "Skipped by --skip-cert.", `foh sim certify-loop --agent ${ctx.agentId} --json`));
+      } else {
+        try {
+          const certMode = normalizeAgentCertMode(opts.certMode);
+          const loop = await runSetupCertifyLoop(ctx.agentId, {
+            mode: certMode,
+            adaptiveRuns: Math.max(1, Number(opts.certAdaptiveRuns ?? 30) || 30),
+            maxImprovementRounds: Math.max(0, Math.min(5, Number(opts.certMaxImprovementRounds ?? 1) || 1)),
+            orgId: ctx.orgId,
+            apiUrlOverride: opts.apiUrl
+          });
+          if (!loop.overall_pass) {
+            checks.push(hold("simulation_certification", "simulation_certification_failed", "Simulation certification did not pass.", `foh sim certify-loop --agent ${ctx.agentId} --${certMode === "quick" ? "full" : certMode} --json`, loop));
+          } else {
+            checks.push(pass("simulation_certification", "Simulation certification passed.", {
+              mode: loop.mode,
+              attempts: loop.attempts?.length ?? 0,
+              improvement_runs: loop.improvement_runs,
+              scenario_summary: loop.certificate?.scenario_summary
+            }));
+          }
+        } catch (error2) {
+          checks.push(fail("simulation_certification", "simulation_certification_failed", error2, `foh sim certify-loop --agent ${ctx.agentId} --json`));
+        }
+      }
+    } else {
+      checks.push(skipped("agent_validation", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("contact_channel", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("voice_realtime_health", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("widget_channel", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("widget_embed", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("widget_smoke", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+      checks.push(skipped("simulation_certification", "agent_required", "Skipped until an agent is selected.", "foh agent list --json"));
+    }
+    const status = hasBlockingChecks(checks) ? "hold" : "pass";
+    const nextCommands = Array.from(new Set(checks.map((check2) => check2.next_command).filter((command) => Boolean(command))));
+    if (status === "pass" && ctx.agentId) {
+      nextCommands.push(`foh agent publish --agent ${ctx.agentId} --json`);
+    }
+    const report = signReport(cliEnvelope({
+      schemaVersion: "foh_cli_proof_report.v1",
+      status,
+      reasonCode: status === "pass" ? "proof_passed" : "proof_held",
+      summary: status === "pass" ? "All non-skipped proof checks passed." : "One or more proof checks require operator action.",
+      ids: {
+        org_id: ctx.orgId ?? null,
+        agent_id: ctx.agentId ?? null,
+        mission,
+        mutation_mode: mutationMode,
+        widget_public_key_present: Boolean(ctx.widgetPublicKey),
+        conversation_id: ctx.conversationId ?? null,
+        trace_ids: ctx.traceIds,
+        correlation_ids: ctx.correlationIds
+      },
+      checks,
+      nextCommands,
+      extra: {
+        generated_at: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    }));
+    const artifactPath = opts.out ? writeSignedJsonArtifact(String(opts.out), report) : void 0;
+    format(artifactPath ? { ...report, artifact_path: artifactPath } : report, { json: opts.json ?? false });
+    if (opts.strict && status !== "pass") markCommandFailed(1);
+  }));
+}
+
 // src/tui/command-palette.ts
 function tokenizeInput(value) {
   const tokens = [];
@@ -36128,7 +37698,7 @@ async function runSelf(args, apiUrlOverride) {
   if (apiUrlOverride && !spawnArgs.includes("--api-url")) {
     spawnArgs.push("--api-url", apiUrlOverride);
   }
-  return await new Promise((resolve5, reject) => {
+  return await new Promise((resolve8, reject) => {
     const child = (0, import_child_process2.spawn)(process.execPath, [process.argv[1], ...spawnArgs], {
       stdio: "inherit",
       env: {
@@ -36138,7 +37708,7 @@ async function runSelf(args, apiUrlOverride) {
       }
     });
     child.once("error", reject);
-    child.once("close", (code) => resolve5(typeof code === "number" ? code : 1));
+    child.once("close", (code) => resolve8(typeof code === "number" ? code : 1));
   });
 }
 function shouldUseInteractiveHome(argv) {
@@ -36428,8 +37998,8 @@ function maybeDefaultToHome(argv = process.argv) {
 }
 
 // src/lib/update.ts
-var import_fs6 = require("fs");
-var import_path5 = require("path");
+var import_fs11 = require("fs");
+var import_path9 = require("path");
 var import_child_process3 = require("child_process");
 var import_crypto5 = require("crypto");
 function parseSemver(version2) {
@@ -36450,7 +38020,7 @@ function compareSemver(a, b) {
 }
 function readPackageJsonVersion(path2) {
   try {
-    const raw = (0, import_fs6.readFileSync)(path2, "utf-8");
+    const raw = (0, import_fs11.readFileSync)(path2, "utf-8");
     const parsed = JSON.parse(raw);
     const version2 = String(parsed.version ?? "").trim();
     return version2 || void 0;
@@ -36459,13 +38029,13 @@ function readPackageJsonVersion(path2) {
   }
 }
 function findRepoRoot(startCwd = process.cwd()) {
-  let current = (0, import_path5.resolve)(startCwd);
+  let current = (0, import_path9.resolve)(startCwd);
   while (true) {
-    const rootPackageJsonPath = (0, import_path5.join)(current, "package.json");
-    const cliPackageJsonPath = (0, import_path5.join)(current, "packages", "cli", "package.json");
-    if ((0, import_fs6.existsSync)(rootPackageJsonPath) && (0, import_fs6.existsSync)(cliPackageJsonPath)) {
+    const rootPackageJsonPath = (0, import_path9.join)(current, "package.json");
+    const cliPackageJsonPath = (0, import_path9.join)(current, "packages", "cli", "package.json");
+    if ((0, import_fs11.existsSync)(rootPackageJsonPath) && (0, import_fs11.existsSync)(cliPackageJsonPath)) {
       try {
-        const raw = (0, import_fs6.readFileSync)(rootPackageJsonPath, "utf-8");
+        const raw = (0, import_fs11.readFileSync)(rootPackageJsonPath, "utf-8");
         const parsed = JSON.parse(raw);
         if (String(parsed.name ?? "").trim() === "front-of-house") {
           return current;
@@ -36473,7 +38043,7 @@ function findRepoRoot(startCwd = process.cwd()) {
       } catch {
       }
     }
-    const parent = (0, import_path5.dirname)(current);
+    const parent = (0, import_path9.dirname)(current);
     if (parent === current) return void 0;
     current = parent;
   }
@@ -36487,7 +38057,7 @@ function detectUpdateAvailability(currentVersion, cwd = process.cwd()) {
       remediation: "Run this command from the Front Of House repo root to compare/install the latest CLI."
     };
   }
-  const cliPackageJsonPath = (0, import_path5.join)(repoRoot, "packages", "cli", "package.json");
+  const cliPackageJsonPath = (0, import_path9.join)(repoRoot, "packages", "cli", "package.json");
   const latestVersion = readPackageJsonVersion(cliPackageJsonPath);
   if (!latestVersion) {
     return {
@@ -36514,19 +38084,19 @@ function detectUpdateAvailability(currentVersion, cwd = process.cwd()) {
   };
 }
 async function applyRepoUpdate(repoRoot) {
-  const scriptPath = (0, import_path5.join)(repoRoot, "scripts", "Install-FohCli.ps1");
+  const scriptPath = (0, import_path9.join)(repoRoot, "scripts", "Install-FohCli.ps1");
   if (process.platform === "win32") {
-    return await new Promise((resolve5, reject) => {
+    return await new Promise((resolve8, reject) => {
       const child = (0, import_child_process3.spawn)(
         "powershell",
         ["-ExecutionPolicy", "Bypass", "-File", scriptPath],
         { stdio: "inherit" }
       );
       child.once("error", reject);
-      child.once("close", (code) => resolve5(typeof code === "number" ? code : 1));
+      child.once("close", (code) => resolve8(typeof code === "number" ? code : 1));
     });
   }
-  return await new Promise((resolve5, reject) => {
+  return await new Promise((resolve8, reject) => {
     const child = (0, import_child_process3.spawn)(
       "corepack",
       ["pnpm", "cli:install:global"],
@@ -36536,7 +38106,7 @@ async function applyRepoUpdate(repoRoot) {
       }
     );
     child.once("error", reject);
-    child.once("close", (code) => resolve5(typeof code === "number" ? code : 1));
+    child.once("close", (code) => resolve8(typeof code === "number" ? code : 1));
   });
 }
 function shouldShowUpdateNotice(argv = process.argv) {
@@ -36550,7 +38120,7 @@ function shouldShowUpdateNotice(argv = process.argv) {
 }
 function hashFileSha256(filePath) {
   try {
-    const bytes = (0, import_fs6.readFileSync)(filePath);
+    const bytes = (0, import_fs11.readFileSync)(filePath);
     return (0, import_crypto5.createHash)("sha256").update(bytes).digest("hex");
   } catch {
     return void 0;
@@ -36560,10 +38130,10 @@ function verifyCliArtifactIntegrity(params = {}) {
   const cwd = params.cwd ?? process.cwd();
   const argv = params.argv ?? process.argv;
   const expectedSha256 = String(params.expectedSha256 ?? "").trim().toLowerCase() || void 0;
-  const runtimePath = (0, import_path5.resolve)(String(argv[1] || ""));
+  const runtimePath = (0, import_path9.resolve)(String(argv[1] || ""));
   const runtimeHash = runtimePath ? hashFileSha256(runtimePath) : void 0;
   const warnings = [];
-  if (!runtimePath || !(0, import_fs6.existsSync)(runtimePath)) {
+  if (!runtimePath || !(0, import_fs11.existsSync)(runtimePath)) {
     warnings.push("runtime_path_unreadable");
   }
   if (!runtimeHash) {
@@ -36581,8 +38151,8 @@ function verifyCliArtifactIntegrity(params = {}) {
   let repoDistHash;
   let runtimeMatchesRepoDist;
   if (repoRoot) {
-    repoDistPath = (0, import_path5.join)(repoRoot, "packages", "cli", "dist", "foh.js");
-    if ((0, import_fs6.existsSync)(repoDistPath)) {
+    repoDistPath = (0, import_path9.join)(repoRoot, "packages", "cli", "dist", "foh.js");
+    if ((0, import_fs11.existsSync)(repoDistPath)) {
       repoDistHash = hashFileSha256(repoDistPath);
       if (runtimeHash && repoDistHash) {
         runtimeMatchesRepoDist = runtimeHash === repoDistHash;
@@ -36770,13 +38340,19 @@ function writeKnownError(message, remediation) {
   if (jsonRequested()) {
     process.stderr.write(
       JSON.stringify(
-        {
-          error: {
-            step: "cli.run",
-            message,
-            remediation
+        cliEnvelope({
+          status: "fail",
+          reasonCode: reasonCodeFromStep(message, "cli_run_failed"),
+          summary: message,
+          nextCommands: remediation.startsWith("Run: ") ? [remediation.slice("Run: ".length)] : [],
+          extra: {
+            error: {
+              step: "cli.run",
+              message,
+              remediation
+            }
           }
-        },
+        }),
         null,
         2
       ) + "\n"
@@ -36805,6 +38381,9 @@ registerMcp(program2);
 registerKnowledge(program2);
 registerLeads(program2);
 registerConversations(program2);
+registerTranscripts(program2);
+registerAnalytics(program2);
+registerTest(program2);
 registerTests(program2);
 registerOps(program2);
 registerSetup(program2);
@@ -36812,6 +38391,7 @@ registerManifest(program2);
 registerSim(program2);
 registerDiag(program2);
 registerBug(program2);
+registerProve(program2);
 registerUpdate(program2);
 registerHome(program2);
 hideInternalApiUrlOptions(program2);
@@ -36849,13 +38429,19 @@ program2.parseAsync(process.argv).catch((e) => {
   if (jsonRequested()) {
     process.stderr.write(
       JSON.stringify(
-        {
-          error: {
-            step: "cli.unhandled",
-            message: e instanceof Error ? e.message : String(e),
-            remediation: `Report this as a bug at ${BUG_REPORT_URL}`
+        cliEnvelope({
+          status: "fail",
+          reasonCode: "cli_unhandled_failed",
+          summary: e instanceof Error ? e.message : String(e),
+          nextCommands: [],
+          extra: {
+            error: {
+              step: "cli.unhandled",
+              message: e instanceof Error ? e.message : String(e),
+              remediation: `Report this as a bug at ${BUG_REPORT_URL}`
+            }
           }
-        },
+        }),
         null,
         2
       ) + "\n"