codealmanac 0.2.2 → 0.2.4

package/dist/{register-commands-7QCIENRZ.js → register-commands-XTK2G2FB.js}

@@ -1,16 +1,26 @@
 #!/usr/bin/env node
 import {
   collectOption,
+  deprecationWarning,
   emit,
   parsePositiveInt,
-  readStdin
-} from "./chunk-P3LDTCLB.js";
+  readStdin,
+  withWarning
+} from "./chunk-H37GKBWI.js";
 import {
-  assertAgentAuth,
+  runAgentsDoctor,
   runAgentsList,
-  runSetAgentModel,
-  runSetDefaultAgent
-} from "./chunk-R3URPHGH.js";
+  runAgentsModel,
+  runAgentsUse,
+  runDeprecatedSetAgentModel,
+  runDeprecatedSetDefaultAgent
+} from "./chunk-UU6FBRQO.js";
+import {
+  runConfigGet,
+  runConfigList,
+  runConfigSet,
+  runConfigUnset
+} from "./chunk-TT6ZP4GS.js";
 import {
   addEntry,
   ancestorsInFile,
@@ -36,8 +46,8 @@ import {
 } from "./chunk-KQUVMF27.js";
 import {
   runDoctor
-} from "./chunk-B2AGSRXL.js";
-import "./chunk-V3QOQSXI.js";
+} from "./chunk-CW4HRLMS.js";
+import "./chunk-TILAKDN6.js";
 import "./chunk-4CODZRHH.js";
 import {
   BLUE,
@@ -47,26 +57,30 @@ import {
 } from "./chunk-FM3VRDK7.js";
 import {
   runUninstall
-} from "./chunk-MX2EW5MR.js";
+} from "./chunk-H6QKCB7M.js";
 import {
   runSetup
-} from "./chunk-ZDJSJIB6.js";
+} from "./chunk-QRK3JLFX.js";
 import {
   runHookInstall,
   runHookStatus,
   runHookUninstall
 } from "./chunk-447U3GQJ.js";
 import {
-  resolveClaudeExecutable
-} from "./chunk-SSYMRT4I.js";
+  DEFAULT_AGENT_MODEL,
+  assertAgentAuth,
+  getAgentProvider,
+  getProviderDefaultModel,
+  parseAgentSelection
+} from "./chunk-BF2J4XTC.js";
 import {
   runUpdate
-} from "./chunk-QQHIVTXT.js";
+} from "./chunk-MRRX4UQB.js";
 import "./chunk-F53U6JQG.js";
 import {
   isAgentProviderId,
   readConfig
-} from "./chunk-WRUSDYYE.js";
+} from "./chunk-P5WGG4FJ.js";
 import {
   findNearestAlmanacDir,
   getRepoAlmanacDir
@@ -1695,11 +1709,11 @@ function registerQueryCommands(program) {
     "--mentions <path>",
     "pages referencing this path; matches exact file, trailing-slash folders, and any file under a folder prefix"
   ).option("--since <duration>", "updated within duration, by file mtime (e.g. 2w, 30d)").option("--stale <duration>", "NOT updated within duration, by file mtime").option("--orphan", "pages with no topics").option("--include-archive", "include archived pages").option("--archived", "archived pages only").option("--wiki <name>", "target a specific registered wiki").option("--json", "emit structured JSON").option("--limit <n>", "cap results", parsePositiveInt).action(
-    async (query2, opts) => {
+    async (query, opts) => {
       await autoRegisterIfNeeded(process.cwd());
       const result = await runSearch({
         cwd: process.cwd(),
-        query: query2,
+        query,
         topics: opts.topic ?? [],
         mentions: opts.mentions,
         since: opts.since,
@@ -1714,7 +1728,7 @@ function registerQueryCommands(program) {
       emit(result);
     }
   );
-  program.command("show [slug]").description("print a page (metadata + body; flags to narrow)").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").option("--json", "structured JSON (overrides other view/field flags)").option("--raw", "body only (alias: --body)").option("--body", "body only (alias: --raw)").option("--meta", "metadata only, no body").option("--lead", "first paragraph of the body only").option("--title", "print title").option("--topics", "print topics").option("--files", "print file refs").option("--links", "print outgoing wikilinks").option("--backlinks", "print incoming wikilinks").option("--xwiki", "print cross-wiki links").option("--lineage", "print archived_at / supersedes / superseded_by").option("--updated", "print updated timestamp").option("--path", "print absolute file path").action(
+  program.command("show [slug]").description("print a page (metadata + body; flags to narrow)").option("--stdin", "read slugs from stdin (one per line)").option("--wiki <name>", "target a specific registered wiki").option("--json", "structured JSON (overrides other view/field flags)").option("--body", "body only").option("--raw", "deprecated alias for --body").option("--meta", "metadata only, no body").option("--lead", "first paragraph of the body only").option("--title", "print title").option("--topics", "print topics").option("--files", "print file refs").option("--links", "print outgoing wikilinks").option("--backlinks", "print incoming wikilinks").option("--xwiki", "print cross-wiki links").option("--lineage", "print archived_at / supersedes / superseded_by").option("--updated", "print updated timestamp").option("--path", "print absolute file path").action(
     async (slug, opts) => {
       await autoRegisterIfNeeded(process.cwd());
       const result = await runShow({
@@ -1737,7 +1751,10 @@ function registerQueryCommands(program) {
         updated: opts.updated,
         path: opts.path
       });
-      emit(result);
+      emit(opts.raw === true ? withWarning(
+        result,
+        deprecationWarning("almanac show <slug> --raw", "almanac show <slug> --body")
+      ) : result);
     }
   );
   program.command("health").description("report graph integrity problems").option("--topic <name>", "scope to a topic + its descendants").option("--stale <duration>", "stale threshold (default 90d)").option("--stdin", "read page slugs from stdin (limit to these pages)").option("--json", "emit structured JSON").option("--wiki <name>", "target a specific registered wiki").action(
@@ -1776,13 +1793,39 @@ function registerSetupCommands(program) {
   agents.command("list").description("show Claude, Codex, and Cursor provider status").action(async () => {
     emit(await runAgentsList());
   });
+  agents.command("doctor").description("diagnose supported AI agent providers").action(async () => {
+    emit(await runAgentsDoctor());
+  });
+  agents.command("use").description("set the default AI agent provider").argument("<provider>", "claude, codex, cursor, or claude/<model>").action(async (provider) => {
+    emit(await runAgentsUse({ provider }));
+  });
+  agents.command("model").description("set or reset a provider model").argument("<provider>", "claude, codex, or cursor").argument("[model]", "provider-specific model id").option("--default", "reset to provider default").action(async (provider, model, opts) => {
+    emit(await runAgentsModel({
+      provider,
+      model,
+      defaultModel: opts.default
+    }));
+  });
+  const config = program.command("config").description("read and write codealmanac settings");
+  config.command("list").description("show supported config keys").option("--json", "emit structured JSON").option("--show-origin", "show whether each value came from file or default").action(async (opts) => {
+    emit(await runConfigList(opts));
+  });
+  config.command("get").description("print one config value").argument("<key>", "config key").option("--json", "emit structured JSON").option("--show-origin", "show whether the value came from file or default").action(async (key, opts) => {
+    emit(await runConfigGet({ key, ...opts }));
+  });
+  config.command("set").description("set one config value").argument("<key>", "config key").argument("<value>", "config value").option("--project", "write .almanac/config.toml for this repo").action(async (key, value, opts) => {
+    emit(await runConfigSet({ key, value, project: opts.project }));
+  });
+  config.command("unset").description("restore one config value to default").argument("<key>", "config key").option("--project", "remove from .almanac/config.toml for this repo").action(async (key, opts) => {
+    emit(await runConfigUnset({ key, project: opts.project }));
+  });
   program.command("set").description("configure codealmanac defaults").argument("<key>", "setting key, e.g. default-agent or model").argument("[value...]", "setting value").action(async (key, value) => {
     if (key === "default-agent") {
-      emit(await runSetDefaultAgent({ provider: value[0] ?? "" }));
+      emit(await runDeprecatedSetDefaultAgent({ provider: value[0] ?? "" }));
       return;
     }
     if (key === "model") {
-      emit(await runSetAgentModel({
+      emit(await runDeprecatedSetAgentModel({
         provider: value[0] ?? "",
         model: value[1]
       }));
@@ -1794,11 +1837,12 @@ function registerSetupCommands(program) {
       exitCode: 1
     });
   });
-  program.command("setup").description("install the hook + CLAUDE.md guides (bare codealmanac alias)").option("-y, --yes", "skip prompts; install everything").option("--agent <agent>", "default agent: claude, codex, or cursor").option("--skip-hook", "opt out of the SessionEnd hook").option("--skip-guides", "opt out of the CLAUDE.md guides").action(
+  program.command("setup").description("install the hook + CLAUDE.md guides (bare codealmanac alias)").option("-y, --yes", "skip prompts; install everything").option("--agent <agent>", "default agent: claude, codex, or cursor").option("--model <model>", "default model for the selected agent").option("--skip-hook", "opt out of the SessionEnd hook").option("--skip-guides", "opt out of the CLAUDE.md guides").action(
     async (opts) => {
       const result = await runSetup({
         yes: opts.yes,
         agent: opts.agent,
+        model: opts.model,
         skipHook: opts.skipHook,
         skipGuides: opts.skipGuides
       });
@@ -1821,10 +1865,10 @@ function registerSetupCommands(program) {
     "silence the update banner for the current `latest_version` without installing"
   ).option("--check", "force a registry check now (bypasses the 24h cache); no install").option(
     "--enable-notifier",
-    "re-enable the pre-command update banner (writes ~/.almanac/config.json)"
+    "deprecated: use `almanac config set update_notifier true`"
   ).option(
     "--disable-notifier",
-    "silence the pre-command update banner (writes ~/.almanac/config.json)"
+    "deprecated: use `almanac config set update_notifier false`"
   ).action(
     async (opts) => {
       const result = await runUpdate({
@@ -1902,277 +1946,74 @@ async function loadPrompt(name) {
   return readFile4(path.join(dir, `${name}.md`), "utf8");
 }
 
-// src/agent/sdk.ts
-import { spawn } from "child_process";
-import { query } from "@anthropic-ai/claude-agent-sdk";
-var DEFAULT_AGENT_MODEL = "claude-sonnet-4-6";
-async function runAgent(opts) {
-  const provider = opts.provider ?? "claude";
-  if (provider === "codex") {
-    return await runCodexAgent(opts);
-  }
-  if (provider === "cursor") {
-    return await runCursorAgent(opts);
-  }
-  return await runClaudeAgent(opts);
-}
-async function runClaudeAgent(opts) {
-  const claudeExecutable = resolveClaudeExecutable();
-  const q = query({
-    prompt: opts.prompt,
-    options: {
-      systemPrompt: opts.systemPrompt,
-      allowedTools: opts.allowedTools,
-      agents: opts.agents ?? {},
-      cwd: opts.cwd,
-      model: opts.model ?? DEFAULT_AGENT_MODEL,
-      maxTurns: opts.maxTurns ?? 100,
-      ...claudeExecutable !== void 0 ? { pathToClaudeCodeExecutable: claudeExecutable } : {},
-      env: {
-        ...process.env,
-        CODEALMANAC_INTERNAL_SESSION: "1"
-      },
-      // REQUIRED for streaming text deltas. Without it, `stream_event`
-      // messages never fire and the CLI has no progress visibility during
-      // long turns. See docs/research/agent-sdk.md §12 pitfall #1.
-      includePartialMessages: true
-    }
-  });
-  let cost = 0;
-  let turns = 0;
-  let result = "";
-  let sessionId;
-  let success = false;
-  let errorMsg;
-  try {
-    for await (const msg of q) {
-      opts.onMessage?.(msg);
-      if (sessionId === void 0 && typeof msg.session_id === "string") {
-        sessionId = msg.session_id;
-      }
-      if (msg.type === "result") {
-        cost = msg.total_cost_usd;
-        turns = msg.num_turns;
-        if (msg.subtype === "success") {
-          success = true;
-          result = msg.result;
-        } else {
-          success = false;
-          errorMsg = // `SDKResultError` variants don't carry a `result` string; the
-          // useful detail lives in `errors` (array of strings) or the
-          // subtype itself (e.g. "error_max_turns").
-          (msg.errors?.join("; ") ?? "") || `agent error: ${msg.subtype}`;
-        }
-      }
-    }
-  } catch (err) {
-    errorMsg = err instanceof Error ? err.message : String(err);
-    success = false;
+// src/agent/selection.ts
+async function resolveAgentSelection(args) {
+  const config = await readConfig({ cwd: args.cwd });
+  const rawAgent = args.agent ?? process.env.ALMANAC_AGENT ?? config.agent.default;
+  const agentSource = args.agent !== void 0 ? "flag" : process.env.ALMANAC_AGENT !== void 0 ? "env" : "config";
+  const parsed = parseAgentSelection(rawAgent);
+  if (parsed.provider === null || !isAgentProviderId(parsed.provider)) {
+    return {
+      ok: false,
+      error: `unknown agent '${rawAgent}'. Expected one of: claude, codex, cursor.`
+    };
   }
-  return { success, cost, turns, result, sessionId, error: errorMsg };
+  const provider = parsed.provider;
+  const configuredModel = config.agent.models[provider] ?? void 0;
+  const model = args.model !== void 0 ? args.model : parsed.model !== void 0 && agentSource === "flag" ? parsed.model : process.env.ALMANAC_MODEL !== void 0 ? process.env.ALMANAC_MODEL : parsed.model !== void 0 ? parsed.model : configuredModel === null ? void 0 : configuredModel;
+  return { ok: true, provider, model };
 }
-function combinedPrompt(opts) {
-  const reviewerFallback = buildReviewerFallback(opts);
-  return `${opts.systemPrompt}${reviewerFallback}
 
----
-
-${opts.prompt}`;
-}
-function buildReviewerFallback(opts) {
-  if ((opts.provider ?? "claude") === "claude") return "";
-  const reviewer = opts.agents?.reviewer;
-  if (reviewer === void 0) return "";
-  return "\n\nNon-Claude provider note: this runtime does not receive Claude's nested Agent tool contract. When the writer prompt asks you to invoke the reviewer subagent, perform that review pass yourself before final wiki edits. Treat this reviewer prompt as read-only review guidance:\n\n" + reviewer.prompt;
-}
-async function runCodexAgent(opts) {
-  const args = [
-    "exec",
-    "--json",
-    "--sandbox",
-    "workspace-write",
-    "--skip-git-repo-check",
-    "-C",
-    opts.cwd
-  ];
-  if (opts.model !== void 0 && opts.model.length > 0) {
-    args.push("--model", opts.model);
-  }
-  args.push(combinedPrompt(opts));
-  return await runJsonlCli({
-    command: "codex",
-    args,
-    cwd: opts.cwd,
-    env: { ...process.env, CODEALMANAC_INTERNAL_SESSION: "1" },
-    onMessage: opts.onMessage,
-    parseFinal: parseCodexFinal
-  });
-}
-async function runCursorAgent(opts) {
-  const args = [
-    "--print",
-    "--output-format",
-    "stream-json",
-    "--stream-partial-output",
-    "--trust",
-    "--workspace",
-    opts.cwd
-  ];
-  if (opts.model !== void 0 && opts.model.length > 0) {
-    args.push("--model", opts.model);
-  }
-  args.push(combinedPrompt(opts));
-  return await runJsonlCli({
-    command: "cursor-agent",
-    args,
-    cwd: opts.cwd,
-    env: { ...process.env, CODEALMANAC_INTERNAL_SESSION: "1" },
-    onMessage: opts.onMessage,
-    parseFinal: parseCursorFinal
-  });
-}
-function runJsonlCli(opts) {
-  return new Promise((resolve) => {
-    const child = spawn(opts.command, opts.args, {
-      cwd: opts.cwd,
-      env: opts.env,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    let stdoutBuf = "";
-    let stderr = "";
-    let cost = 0;
-    let turns = 0;
-    let result = "";
-    let sessionId;
-    let usage;
-    let success = false;
-    let finalSeen = false;
-    let error;
-    const observe = (msg) => {
-      opts.onMessage?.(msg);
-      if (sessionId === void 0 && typeof msg.session_id === "string" && msg.session_id.length > 0) {
-        sessionId = msg.session_id;
-      }
-      if (sessionId === void 0 && typeof msg.thread_id === "string" && msg.thread_id.length > 0) {
-        sessionId = msg.thread_id;
-      }
-      const final = opts.parseFinal(msg);
-      if (final === null) return;
-      finalSeen = true;
-      if (final.cost !== void 0) cost = final.cost;
-      if (final.turns !== void 0) turns = final.turns;
-      if (final.result !== void 0) result = final.result;
-      if (final.sessionId !== void 0) sessionId = final.sessionId;
-      if (final.usage !== void 0) usage = final.usage;
-      if (final.success !== void 0) success = final.success;
-      if (final.error !== void 0) error = final.error;
-    };
-    const flushLines = () => {
-      let idx = stdoutBuf.indexOf("\n");
-      while (idx !== -1) {
-        const rawLine = stdoutBuf.slice(0, idx);
-        stdoutBuf = stdoutBuf.slice(idx + 1);
-        const line = rawLine.trim();
-        if (line.length > 0) {
-          try {
-            const parsed = JSON.parse(line);
-            observe(parsed);
-          } catch {
-          }
-        }
-        idx = stdoutBuf.indexOf("\n");
-      }
+// src/cli/outcome.ts
+function renderOutcome(outcome, opts = {}) {
+  const exitCode = opts.exitCode ?? defaultExitCode(outcome);
+  if (opts.json === true) {
+    return {
+      stdout: `${JSON.stringify(outcome, null, 2)}
+`,
+      stderr: "",
+      exitCode
     };
-    child.stdout.on("data", (chunk) => {
-      stdoutBuf += chunk.toString("utf8");
-      flushLines();
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString("utf8");
-    });
-    child.on("error", (err) => {
-      resolve({
-        success: false,
-        cost,
-        turns,
-        result,
-        sessionId,
-        usage,
-        error: err.code === "ENOENT" ? `${opts.command} not found on PATH` : err.message
-      });
-    });
-    child.on("close", (code) => {
-      flushLines();
-      if (stdoutBuf.trim().length > 0) {
-        try {
-          observe(JSON.parse(stdoutBuf.trim()));
-        } catch {
-        }
-      }
-      if (code === 0 && finalSeen && success) {
-        resolve({ success, cost, turns, result, sessionId, usage });
-        return;
-      }
-      const firstStderr = stderr.trim().split("\n")[0];
-      resolve({
-        success: false,
-        cost,
-        turns,
-        result,
-        sessionId,
-        usage,
-        error: error ?? (firstStderr !== void 0 && firstStderr.length > 0 ? firstStderr : `${opts.command} exited ${code ?? 1}`)
-      });
-    });
-  });
-}
-function parseCodexFinal(msg) {
-  if (msg.type === "item.completed") {
-    const item = msg.item;
-    if (item !== null && typeof item === "object") {
-      const obj = item;
-      if (obj.type === "agent_message" && typeof obj.text === "string") {
-        return { result: obj.text };
-      }
-    }
-    return null;
   }
-  if (msg.type === "turn.completed") {
-    return { success: true, turns: 1, usage: parseUsage(msg.usage) };
+  if (outcome.type === "needs-action") {
+    return {
+      stdout: opts.stdout ?? "",
+      stderr: `almanac: ${outcome.message}
+${outcome.fix}
+`,
+      exitCode
+    };
   }
-  if (msg.type === "turn.failed" || msg.type === "error") {
+  if (outcome.type === "error") {
     return {
-      success: false,
-      error: typeof msg.message === "string" ? msg.message : typeof msg.error === "string" ? msg.error : "codex turn failed"
+      stdout: opts.stdout ?? "",
+      stderr: `almanac: ${outcome.message}
+`,
+      exitCode
     };
   }
-  return null;
-}
-function parseUsage(value) {
-  if (value === null || typeof value !== "object") return void 0;
-  const obj = value;
   return {
-    inputTokens: numberField(obj, "input_tokens") ?? numberField(obj, "inputTokens"),
-    cachedInputTokens: numberField(obj, "cached_input_tokens") ?? numberField(obj, "cachedInputTokens") ?? numberField(obj, "cacheReadTokens"),
-    outputTokens: numberField(obj, "output_tokens") ?? numberField(obj, "outputTokens"),
-    reasoningOutputTokens: numberField(obj, "reasoning_output_tokens") ?? numberField(obj, "reasoningOutputTokens")
+    stdout: opts.stdout ?? `${outcome.message}
+`,
+    stderr: "",
+    exitCode
   };
 }
-function numberField(input, key) {
-  const value = input[key];
-  return typeof value === "number" ? value : void 0;
+function defaultExitCode(outcome) {
+  switch (outcome.type) {
+    case "success":
+    case "noop":
+      return 0;
+    case "needs-action":
+    case "error":
+      return 1;
+  }
 }
-function parseCursorFinal(msg) {
-  if (msg.type !== "result") return null;
-  const isError = msg.is_error === true || msg.subtype !== "success";
-  return {
-    success: !isError,
-    turns: 1,
-    result: typeof msg.result === "string" ? msg.result : "",
-    sessionId: typeof msg.session_id === "string" ? msg.session_id : void 0,
-    usage: parseUsage(msg.usage),
-    error: isError ? typeof msg.result === "string" ? msg.result : `cursor result: ${String(msg.subtype ?? "error")}` : void 0
-  };
+
+// src/agent/sdk.ts
+async function runAgent(opts) {
+  const provider = opts.provider ?? "claude";
+  return await getAgentProvider(provider).run(opts);
 }
 
 // src/commands/init.ts
@@ -2318,42 +2159,47 @@ and optional \`files:\`. The rest is prose.
 // src/commands/bootstrap.ts
 var BOOTSTRAP_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep", "Bash"];
 async function runBootstrap(options) {
+  const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
   const providerResolution = await resolveAgentSelection({
     agent: options.agent,
-    model: options.model
+    model: options.model,
+    cwd: repoRoot
   });
   if (!providerResolution.ok) {
-    return {
-      stdout: "",
-      stderr: `almanac: ${providerResolution.error}
-`,
-      exitCode: 1
-    };
+    return renderOutcome(
+      { type: "error", message: providerResolution.error },
+      { json: options.json }
+    );
   }
   const { provider, model } = providerResolution;
   try {
     await assertAgentAuth({ provider, spawnCli: options.spawnCli });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return {
-      stdout: "",
-      stderr: `almanac: ${msg}
-`,
-      exitCode: 1
-    };
+    return renderOutcome(
+      {
+        type: "needs-action",
+        message: msg,
+        fix: authFixFor(provider),
+        data: { provider }
+      },
+      { json: options.json }
+    );
   }
-  const repoRoot = findNearestAlmanacDir(options.cwd) ?? options.cwd;
   const almanacDir = getRepoAlmanacDir(repoRoot);
   const pagesDir = join6(almanacDir, "pages");
   if (options.force !== true && existsSync5(pagesDir)) {
     const existing = await countMarkdownPages(pagesDir);
     if (existing > 0) {
-      return {
-        stdout: "",
-        stderr: `almanac: .almanac/ already initialized with ${existing} page${existing === 1 ? "" : "s"}. Use 'almanac capture' instead, or --force to overwrite.
-`,
-        exitCode: 1
-      };
+      return renderOutcome(
+        {
+          type: "needs-action",
+          message: `.almanac/ already initialized with ${existing} page${existing === 1 ? "" : "s"}.`,
+          fix: "run: almanac capture  (or pass --force to overwrite)",
+          data: { pages: existing }
+        },
+        { json: options.json }
+      );
     }
   }
   if (!existsSync5(almanacDir)) {
@@ -2361,12 +2207,10 @@ async function runBootstrap(options) {
       await initWiki({ cwd: repoRoot });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      return {
-        stdout: "",
-        stderr: `almanac: init failed during bootstrap: ${msg}
-`,
-        exitCode: 1
-      };
+      return renderOutcome(
+        { type: "error", message: `init failed during bootstrap: ${msg}` },
+        { json: options.json }
+      );
     }
   }
   const systemPrompt = await loadPrompt("bootstrap");
@@ -2379,7 +2223,7 @@ async function runBootstrap(options) {
   const out = process.stdout;
   const formatter = new StreamingFormatter({
     write: (line) => {
-      if (options.quiet !== true) out.write(line);
+      if (options.quiet !== true && options.json !== true) out.write(line);
     }
   });
   const onMessage = (msg) => {
@@ -2408,33 +2252,47 @@ async function runBootstrap(options) {
   }
   const finalLine = formatFinalLine(result, logPath, repoRoot);
   if (result.success) {
-    return {
-      stdout: `${finalLine}
-`,
-      stderr: "",
-      exitCode: 0
-    };
+    return renderOutcome(
+      {
+        type: "success",
+        message: finalLine,
+        data: runData(result, logPath, repoRoot)
+      },
+      { json: options.json }
+    );
   }
-  return {
-    stdout: options.quiet === true ? "" : `${finalLine}
-`,
-    stderr: `almanac: bootstrap failed: ${result.error ?? "unknown error"}
-`,
-    exitCode: 1
-  };
+  return renderOutcome(
+    {
+      type: "error",
+      message: `bootstrap failed: ${result.error ?? "unknown error"}`,
+      data: runData(result, logPath, repoRoot)
+    },
+    {
+      json: options.json,
+      stdout: options.quiet === true || options.json === true ? "" : `${finalLine}
+`
+    }
+  );
 }
-async function resolveAgentSelection(args) {
-  const config = await readConfig();
-  const rawProvider = args.agent ?? config.agent.default;
-  if (!isAgentProviderId(rawProvider)) {
-    return {
-      ok: false,
-      error: `unknown agent '${rawProvider}'. Expected one of: claude, codex, cursor.`
-    };
+function authFixFor(provider) {
+  switch (provider) {
+    case "claude":
+      return "run: claude auth login --claudeai  (or export ANTHROPIC_API_KEY)";
+    case "codex":
+      return "run: codex login";
+    case "cursor":
+      return "run: cursor-agent login";
+    default:
+      return "run: almanac agents doctor";
   }
-  const configuredModel = config.agent.models[rawProvider] ?? void 0;
-  const model = args.model !== void 0 ? args.model : configuredModel === null ? void 0 : configuredModel;
-  return { ok: true, provider: rawProvider, model };
+}
+function runData(result, logPath, repoRoot) {
+  return {
+    transcript: relative(repoRoot, logPath),
+    cost: result.cost,
+    turns: result.turns,
+    sessionId: result.sessionId
+  };
 }
 function formatFinalLine(result, logPath, repoRoot) {
   const status = result.success ? "done" : "failed";
@@ -2898,37 +2756,46 @@ var WRITER_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent"];
 var REVIEWER_TOOLS = ["Read", "Grep", "Glob", "Bash"];
 var REVIEWER_DESCRIPTION = "Reviews proposed wiki changes against the full knowledge base for cohesion, duplication, missing links, notability, and writing conventions.";
 async function runCapture(options) {
-  const providerResolution = await resolveAgentSelection2({
+  const repoRoot = findNearestAlmanacDir(options.cwd);
+  if (repoRoot === null) {
+    return renderOutcome(
+      {
+        type: "needs-action",
+        message: "no .almanac/ found in this directory or any parent.",
+        fix: "run: almanac bootstrap"
+      },
+      { json: options.json }
+    );
+  }
+  const providerResolution = await resolveAgentSelection({
     agent: options.agent,
-    model: options.model
+    model: options.model,
+    cwd: repoRoot
   });
   if (!providerResolution.ok) {
-    return {
-      stdout: "",
-      stderr: `almanac: ${providerResolution.error}
-`,
-      exitCode: 1
-    };
+    return renderOutcome(
+      { type: "error", message: providerResolution.error },
+      { json: options.json }
+    );
   }
   const { provider, model } = providerResolution;
+  const statusModel = model ?? getProviderDefaultModel(provider) ?? "provider default";
   try {
-    await assertAgentAuth({ provider, spawnCli: options.spawnCli });
+    await (options.assertAgentAuthFn ?? assertAgentAuth)({
+      provider,
+      spawnCli: options.spawnCli
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return {
-      stdout: "",
-      stderr: `almanac: ${msg}
-`,
-      exitCode: 1
-    };
-  }
-  const repoRoot = findNearestAlmanacDir(options.cwd);
-  if (repoRoot === null) {
-    return {
-      stdout: "",
-      stderr: "almanac: no .almanac/ found in this directory or any parent. Run 'almanac bootstrap' first.\n",
-      exitCode: 1
-    };
+    return renderOutcome(
+      {
+        type: "needs-action",
+        message: msg,
+        fix: authFixFor2(provider),
+        data: { provider }
+      },
+      { json: options.json }
+    );
   }
   const almanacDir = getRepoAlmanacDir(repoRoot);
   const pagesDir = join8(almanacDir, "pages");
@@ -2939,12 +2806,14 @@ async function runCapture(options) {
     claudeProjectsDir: options.claudeProjectsDir
   });
   if (!transcriptResolution.ok) {
-    return {
-      stdout: "",
-      stderr: `almanac: ${transcriptResolution.error}
-`,
-      exitCode: 1
-    };
+    return renderOutcome(
+      {
+        type: "needs-action",
+        message: transcriptResolution.error,
+        fix: transcriptFix(transcriptResolution.error)
+      },
+      { json: options.json }
+    );
   }
   const transcriptPath = transcriptResolution.path;
   const snapshotBefore = await snapshotPages(pagesDir);
@@ -2970,7 +2839,7 @@ async function runCapture(options) {
     stem: logStem,
     sessionId: options.sessionId,
     transcriptPath,
-    model: options.model,
+    model: statusModel,
     startedAt
   });
   await writeCaptureRunRecord(statePath, stateRecord).catch(() => {
@@ -2979,7 +2848,7 @@ async function runCapture(options) {
   const out = process.stdout;
   const formatter = new StreamingFormatter({
     write: (line) => {
-      if (options.quiet !== true) out.write(line);
+      if (options.quiet !== true && options.json !== true) out.write(line);
     }
   });
   formatter.setAgent("writer");
@@ -3034,13 +2903,18 @@ Working directory: ${repoRoot}.`;
       })
     ).catch(() => {
     });
-    return {
-      stdout: "",
-      stderr: `almanac: capture failed: ${result.error ?? "unknown error"}
-(transcript: ${relative3(repoRoot, logPath)})
-`,
-      exitCode: 1
-    };
+    return renderOutcome(
+      {
+        type: "error",
+        message: `capture failed: ${result.error ?? "unknown error"}
+(transcript: ${relative3(repoRoot, logPath)})`,
+        data: captureOutcomeData(result, delta, logPath, repoRoot)
+      },
+      {
+        json: options.json,
+        stdout: ""
+      }
+    );
   }
   await writeCaptureRunRecord(
     statePath,
@@ -3053,25 +2927,46 @@ Working directory: ${repoRoot}.`;
   ).catch(() => {
   });
   const summary = formatSummary2(result, delta, logPath, repoRoot);
+  return renderOutcome(
+    {
+      type: isNoopDelta(delta) ? "noop" : "success",
+      message: summary,
+      data: captureOutcomeData(result, delta, logPath, repoRoot)
+    },
+    { json: options.json }
+  );
+}
+function transcriptFix(error) {
+  if (error.includes("transcript not found")) {
+    return "pass a valid <transcript-path>";
+  }
+  return "pass --session <id> or <transcript-path>";
+}
+function authFixFor2(provider) {
+  switch (provider) {
+    case "claude":
+      return "run: claude auth login --claudeai  (or export ANTHROPIC_API_KEY)";
+    case "codex":
+      return "run: codex login";
+    case "cursor":
+      return "run: cursor-agent login";
+    default:
+      return "run: almanac agents doctor";
+  }
+}
+function captureOutcomeData(result, delta, logPath, repoRoot) {
   return {
-    stdout: `${summary}
-`,
-    stderr: "",
-    exitCode: 0
+    transcript: relative3(repoRoot, logPath),
+    updated: delta.updated,
+    created: delta.created,
+    archived: delta.archived,
+    cost: result.cost,
+    turns: result.turns,
+    sessionId: result.sessionId
   };
 }
-async function resolveAgentSelection2(args) {
-  const config = await readConfig();
-  const rawProvider = args.agent ?? config.agent.default;
-  if (!isAgentProviderId(rawProvider)) {
-    return {
-      ok: false,
-      error: `unknown agent '${rawProvider}'. Expected one of: claude, codex, cursor.`
-    };
-  }
-  const configuredModel = config.agent.models[rawProvider] ?? void 0;
-  const model = args.model !== void 0 ? args.model : configuredModel === null ? void 0 : configuredModel;
-  return { ok: true, provider: rawProvider, model };
+function isNoopDelta(delta) {
+  return delta.created === 0 && delta.updated === 0 && delta.archived === 0;
 }
 async function resolveTranscript(args) {
   if (args.explicit !== void 0 && args.explicit.length > 0) {
@@ -3251,19 +3146,20 @@ async function runReindex(options) {
 function registerWikiLifecycleCommands(program) {
   program.command("bootstrap").description(
     "scaffold a wiki in this repo via an AI agent (requires ANTHROPIC_API_KEY or Claude subscription)"
-  ).option("--quiet", "suppress per-tool streaming; print only the final line").option("--agent <agent>", "agent provider: claude, codex, or cursor").option("--model <model>", "override the agent model").option("--force", "overwrite an existing populated wiki (default: refuse)").action(
+  ).option("--quiet", "suppress per-tool streaming; print only the final line").option("--agent <agent>", "agent provider: claude, codex, or cursor").option("--model <model>", "override the agent model").option("--force", "overwrite an existing populated wiki (default: refuse)").option("--json", "emit structured CommandOutcome JSON").action(
     async (opts) => {
       const result = await runBootstrap({
         cwd: process.cwd(),
         quiet: opts.quiet,
         agent: opts.agent,
         model: opts.model,
-        force: opts.force
+        force: opts.force,
+        json: opts.json
       });
       emit(result);
     }
   );
-  const capture = program.command("capture [transcript]").alias("c").description("run the writer/reviewer pipeline on a session (usually automatic)").option("--session <id>", "target a specific session by ID").option("--quiet", "suppress per-tool streaming; print only the final summary").option("--agent <agent>", "agent provider: claude, codex, or cursor").option("--model <model>", "override the agent model").action(
+  const capture = program.command("capture [transcript]").alias("c").description("run the writer/reviewer pipeline on a session (usually automatic)").option("--session <id>", "target a specific session by ID").option("--quiet", "suppress per-tool streaming; print only the final summary").option("--agent <agent>", "agent provider: claude, codex, or cursor").option("--model <model>", "override the agent model").option("--json", "emit structured CommandOutcome JSON").action(
     async (transcript, opts) => {
       await autoRegisterIfNeeded(process.cwd());
       const result = await runCapture({
@@ -3272,7 +3168,8 @@ function registerWikiLifecycleCommands(program) {
         sessionId: opts.session,
         quiet: opts.quiet,
         agent: opts.agent,
-        model: opts.model
+        model: opts.model,
+        json: opts.json
       });
       emit(result);
     }
@@ -3285,13 +3182,16 @@ function registerWikiLifecycleCommands(program) {
     });
     emit(result);
   });
-  program.command("ps").description("show running and recent capture jobs").option("--json", "emit structured JSON").action(async (opts) => {
+  program.command("ps").description("deprecated alias for capture status").option("--json", "emit structured JSON").action(async (opts) => {
     await autoRegisterIfNeeded(process.cwd());
     const result = await runCaptureStatus({
       cwd: process.cwd(),
       json: opts.json
     });
-    emit(result);
+    emit(withWarning(
+      result,
+      deprecationWarning("almanac ps", "almanac capture status")
+    ));
   });
   const hook = program.command("hook").description("manage the SessionEnd auto-capture hook");
   hook.command("install").description("add a SessionEnd entry that runs 'almanac capture' on session end").option("--source <source>", "claude, codex, cursor, or all").action(async (opts) => {
@@ -3335,4 +3235,4 @@ function registerCommands(program) {
 export {
   registerCommands
 };
-//# sourceMappingURL=register-commands-7QCIENRZ.js.map
+//# sourceMappingURL=register-commands-XTK2G2FB.js.map