@askalf/deepdive 0.13.2 → 0.15.0

package/dist/cli.js

@@ -9,7 +9,9 @@
 // Prints the cited markdown report to stdout (or JSON with --json). Progress
 // events go to stderr when --verbose is set or DEEPDIVE_VERBOSE=1.
 import { writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { resolveConfig } from "./config.js";
 import { parseMaxCost, BudgetExceededError } from "./budget.js";
@@ -21,7 +23,15 @@ import { renderSourcesMarkdown, renderAnswerMarkdown } from "./citations.js";
 import { synthesize } from "./synthesize.js";
 import { verifyCitations as runVerify } from "./verify.js";
 import { formatCostLine, looksLikeDario, estimateCost, } from "./pricing.js";
-import { generateSessionId, saveSession, loadSession, listSessions, resolveSessionId, renderSessionsList, } from "./sessions.js";
+import { generateSessionId, saveSession, loadSession, listSessions, resolveSessionId, renderSessionsList, deleteSession, pruneSessions, parseDuration, } from "./sessions.js";
+import { renderHtmlReport } from "./html-export.js";
+import { assessConfidence, formatConfidenceLine } from "./confidence.js";
+import { loadConfigFile, fileConfigToEnv } from "./config-file.js";
+import { resolveProfile } from "./profiles.js";
+import { completionScript } from "./completion.js";
+import { browserOpenCommand } from "./open.js";
+import { diffSessions, renderDiffText, DIFF_NARRATE_SYSTEM, buildDiffNarrateUser, } from "./diff.js";
+import { callLLM } from "./llm.js";
 import { runDoctor, renderDoctorText, renderDoctorJson, exitCodeFor, scrubPath, } from "./doctor.js";
 const USAGE = `deepdive — local research agent
 
@@ -35,6 +45,18 @@ Usage:
   deepdive continue <id> [<question>]      Full agent run seeded with the saved session's
                                            sources (plans + searches + fetches new pages;
                                            saved as a new session linked via parentId)
+  deepdive export <id> [--format=html|md]  Render a saved session as a shareable artifact
+                                           (--out=report.html). Format inferred from --out.
+  deepdive diff <id-a> <id-b> [--narrate]  Show how the answer + source set changed between
+                                           two saved runs. --narrate adds an LLM summary.
+  deepdive sessions rm <id> [<id>...]      Delete one or more saved sessions
+  deepdive sessions prune --older-than=30d Delete old sessions (and/or --keep=<n> newest;
+                                           --dry-run to preview)
+  deepdive search "<query>"                Run just the search adapter, print raw results
+                                           (no LLM/fetch). Honors --search / --json.
+  deepdive open <id>                       Render a session to HTML and open it in the
+                                           browser (--out to keep the file)
+  deepdive completion <bash|zsh|fish>      Print a shell completion script
   deepdive --help                          Show this help
 
 Flags:
@@ -50,11 +72,13 @@ Flags:
                                 dollar cap. e.g. --max-cost=$0.50 or --max-cost=5.
                                 Env: DEEPDIVE_MAX_COST. Exit code 2 on cap-hit.
   --max-tokens=<n>              Output max tokens per LLM call. Default: 4096
-  --search=<adapter>            Search adapter: duckduckgo | searxng | brave | tavily | exa | auto
-                                Default: duckduckgo (no key required). 'auto' runs
-                                DDG first and falls back to Brave (if
-                                DEEPDIVE_BRAVE_KEY is set) when DDG fails or
-                                returns no results.
+  --search=<adapter>            Search adapter: duckduckgo | searxng | brave | tavily | exa |
+                                auto | wikipedia | arxiv | github | hackernews |
+                                stackexchange | pubmed
+                                Default: duckduckgo (no key required). wikipedia, arxiv,
+                                hackernews, stackexchange, and pubmed need no key; github
+                                works keyless (DEEPDIVE_GITHUB_TOKEN raises the limit).
+                                'auto' runs DDG first, Brave fallback (if DEEPDIVE_BRAVE_KEY).
   --results-per-query=<n>       Results per sub-query. Default: 5
   --max-sources=<n>             Total sources to fetch. Default: 12
   --max-words-per-source=<n>    Per-source content cap before synthesis. Default: 2000
@@ -68,6 +92,9 @@ Flags:
   --deep[=<n>]                  Iterative research: run N additional critic-driven
                                 rounds after the first synthesis. Default when
                                 bare: 2. No deep pass when flag absent.
+  --profile=<name>              Apply a named preset: deep | thorough | fast | cheap |
+                                strict, or one defined in your config file. Layered
+                                beneath env + flags. See ~/.deepdive/config.json.
   --concurrency=<n>             Parallel fetches. Default: 4
   --no-cache                    Disable the on-disk page cache (default: enabled)
   --cache-ttl-ms=<ms>           Page cache TTL. Default: 3600000 (1 hour)
@@ -84,13 +111,23 @@ Flags:
                                 exclusively (e.g. github.com,docs.anthropic.com).
   --deny-domain=<list>          Comma-separated hostname suffixes to drop
                                 (e.g. pinterest.com,quora.com).
+  --since=<date|duration>       Drop sources published before this — an absolute
+                                date (2024, 2024-06, 2024-06-15) or a duration
+                                (30d, 12h, 2w = that long ago). Sources with no
+                                detectable date are kept. Env: DEEPDIVE_SINCE.
   --api-format=<anthropic|openai>
                                 Wire format for the LLM endpoint. Default:
                                 auto-detected from --base-url (api.openai.com,
                                 :11434 (Ollama), :8000 default to openai;
                                 everything else to anthropic).
+  --tldr                        Lead the answer with a one-paragraph TL;DR (env: DEEPDIVE_TLDR)
   --json                        Emit a JSON result to stdout instead of markdown
   --out=<path>                  Write the output (markdown or json) to a file too
+  --format=<html|md>            export: output format (default: inferred from --out, else html)
+  --narrate                     diff: add a one-shot LLM summary of what changed
+  --older-than=<dur>            sessions prune: age cutoff — 30d, 12h, 90m, 2w
+  --keep=<n>                    sessions prune: always retain the newest <n> sessions
+  --dry-run                     sessions prune: report what would be deleted, delete nothing
   --verbose, -v                 Stream progress events to stderr
   --no-stream                   Buffer the final answer instead of streaming
                                 tokens to stdout (auto-off for --json and
@@ -101,15 +138,22 @@ Flags:
 Environment:
   DEEPDIVE_BASE_URL, DEEPDIVE_API_KEY, DEEPDIVE_MODEL, DEEPDIVE_SEARCH,
   DEEPDIVE_SEARXNG_URL, DEEPDIVE_BRAVE_KEY, DEEPDIVE_TAVILY_KEY, DEEPDIVE_EXA_KEY,
+  DEEPDIVE_WIKIPEDIA_LANG, DEEPDIVE_GITHUB_TOKEN, DEEPDIVE_STACKEXCHANGE_SITE,
   DEEPDIVE_MAX_SOURCES, DEEPDIVE_FETCH_TIMEOUT_MS, DEEPDIVE_HEADED,
   DEEPDIVE_DEEP_ROUNDS, DEEPDIVE_CONCURRENCY, DEEPDIVE_NO_CACHE,
-  DEEPDIVE_CACHE_DIR, DEEPDIVE_CACHE_TTL_MS, DEEPDIVE_JSON, DEEPDIVE_VERBOSE,
+  DEEPDIVE_CACHE_DIR, DEEPDIVE_CACHE_TTL_MS, DEEPDIVE_JSON, DEEPDIVE_VERBOSE, DEEPDIVE_TLDR,
   DEEPDIVE_LLM_TIMEOUT_MS, DEEPDIVE_LLM_ATTEMPTS,
   DEEPDIVE_NO_VERIFY_CITES, DEEPDIVE_STRICT_CITES, DEEPDIVE_CITE_MIN_RECALL,
   DEEPDIVE_NO_COST, DEEPDIVE_PRICE_INPUT_PER_MTOK, DEEPDIVE_PRICE_OUTPUT_PER_MTOK,
   DEEPDIVE_INCLUDE, DEEPDIVE_PDF_MAX_PAGES,
-  DEEPDIVE_ALLOW_DOMAIN, DEEPDIVE_DENY_DOMAIN, DEEPDIVE_API_FORMAT,
-  DEEPDIVE_NO_SESSIONS, DEEPDIVE_SESSIONS_DIR
+  DEEPDIVE_ALLOW_DOMAIN, DEEPDIVE_DENY_DOMAIN, DEEPDIVE_SINCE, DEEPDIVE_API_FORMAT,
+  DEEPDIVE_NO_SESSIONS, DEEPDIVE_SESSIONS_DIR, DEEPDIVE_CONFIG
+
+Config file:
+  ~/.deepdive/config.json (override path with DEEPDIVE_CONFIG) — JSON object of
+  default settings (friendly keys: model, search, deep, concurrency, …), an
+  optional "profiles" map, and an optional "defaultProfile". Precedence:
+  CLI flags > env vars > --profile > config-file base > built-in defaults.
 `;
 // Verbs that accept additional positional arguments. Anything else
 // triggers the "wrap your question in quotes" error when more than one
@@ -120,6 +164,11 @@ const SUBCOMMAND_VERBS = new Set([
     "show",
     "resume",
     "continue",
+    "export",
+    "diff",
+    "completion",
+    "search",
+    "open",
 ]);
 // Exported for unit tests.
 export function parseArgs(argv) {
@@ -169,6 +218,18 @@ export function parseArgs(argv) {
             flags.noStream = true;
             continue;
         }
+        if (a === "--tldr") {
+            flags.tldr = true;
+            continue;
+        }
+        if (a === "--narrate") {
+            flags.narrate = true;
+            continue;
+        }
+        if (a === "--dry-run") {
+            flags.dryRun = true;
+            continue;
+        }
         if (a === "--deep") {
             flags.deepRounds = 2;
             continue;
@@ -274,6 +335,21 @@ export function parseArgs(argv) {
                 case "out":
                     outPath = value;
                     break;
+                case "profile":
+                    flags.profile = value;
+                    break;
+                case "since":
+                    flags.since = value;
+                    break;
+                case "format":
+                    flags.format = value.toLowerCase();
+                    break;
+                case "older-than":
+                    flags.olderThan = value;
+                    break;
+                case "keep":
+                    flags.keep = parseNonNegativeInt(value);
+                    break;
                 default:
                     throw new Error(`unknown flag: --${key}`);
             }
@@ -440,6 +516,17 @@ async function main(argv) {
         process.stdout.write(USAGE);
         return 0;
     }
+    // `completion` needs no config; everything else gets config-file + profile
+    // defaults layered beneath env (real env wins). Do this before any
+    // resolveConfig so all subcommands see the same effective settings.
+    if (parsed.question === "completion") {
+        return completionCommand(parsed);
+    }
+    const cfgErr = applyConfigToEnv(parsed.flags);
+    if (cfgErr) {
+        process.stderr.write(`deepdive: ${cfgErr}\n`);
+        return 2;
+    }
     if (parsed.question === "doctor") {
         const config = resolveConfig(parsed.flags, process.env);
         const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -462,6 +549,18 @@ async function main(argv) {
     if (parsed.question === "continue") {
         return await continueCommand(parsed);
     }
+    if (parsed.question === "export") {
+        return await exportCommand(parsed);
+    }
+    if (parsed.question === "diff") {
+        return await diffCommand(parsed);
+    }
+    if (parsed.question === "search") {
+        return await searchCommand(parsed);
+    }
+    if (parsed.question === "open") {
+        return await openCommand(parsed);
+    }
     if (!parsed.question) {
         process.stderr.write(`deepdive: missing question.\n\n${USAGE}`);
         return 2;
@@ -469,8 +568,144 @@ async function main(argv) {
     const config = resolveConfig(parsed.flags, process.env);
     return await runResearch({ question: parsed.question, parsed, config });
 }
+// Layer config-file base + selected-profile settings into process.env, filling
+// only keys the real environment hasn't already set — so the effective
+// precedence is: CLI flags > env vars > profile > config-file base > defaults.
+// Returns an error string for a fatal problem (unknown profile); a malformed
+// config file is a non-fatal warning. Mutating process.env keeps every
+// downstream resolveConfig(flags, process.env) call config-aware with no
+// plumbing changes.
+function applyConfigToEnv(flags) {
+    const loaded = loadConfigFile(process.env);
+    if (loaded.error) {
+        process.stderr.write(`deepdive: warning: ${loaded.error}; ignoring config file\n`);
+    }
+    const profileName = flags.profile ?? loaded.defaultProfile;
+    let profileEnv = {};
+    if (profileName) {
+        try {
+            profileEnv = fileConfigToEnv(resolveProfile(profileName, loaded.profiles));
+        }
+        catch (err) {
+            return safeErrorMessage(err);
+        }
+    }
+    // Profile wins over the file base within the file layer.
+    const fileEnv = { ...fileConfigToEnv(loaded.base), ...profileEnv };
+    for (const [k, v] of Object.entries(fileEnv)) {
+        if (process.env[k] === undefined)
+            process.env[k] = v;
+    }
+    return undefined;
+}
+function completionCommand(parsed) {
+    const shell = parsed.extras[0];
+    if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
+        process.stderr.write(`deepdive: completion requires a shell: bash | zsh | fish\n` +
+            `  e.g. source <(deepdive completion bash)\n`);
+        return 2;
+    }
+    process.stdout.write(completionScript(shell));
+    return 0;
+}
+// `deepdive search "<query>" [--search=<adapter>] [--json]` — run just the
+// search adapter and print the raw candidate list. No LLM, no fetch, no
+// browser — a cheap way to preview what a backend returns or debug an adapter.
+async function searchCommand(parsed) {
+    const config = resolveConfig(parsed.flags, process.env);
+    const query = parsed.extras[0];
+    if (!query) {
+        process.stderr.write(`deepdive: search requires a query (e.g. deepdive search "rust async" --search=hackernews)\n`);
+        return 2;
+    }
+    let adapter;
+    try {
+        adapter = await resolveSearchAdapter(config.searchAdapter, process.env);
+    }
+    catch (err) {
+        process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        return 1;
+    }
+    const ac = new AbortController();
+    const sigint = () => ac.abort();
+    process.on("SIGINT", sigint);
+    process.on("SIGTERM", sigint);
+    try {
+        const count = parsed.flags.resultsPerQuery ?? 10;
+        const results = await adapter.search(query, count, ac.signal);
+        if (config.jsonOutput) {
+            process.stdout.write(JSON.stringify({ adapter: adapter.name, query, results }, null, 2) + "\n");
+            return 0;
+        }
+        if (results.length === 0) {
+            process.stdout.write(`(no results from ${adapter.name} for "${query}")\n`);
+            return 0;
+        }
+        const lines = results.map((r) => {
+            const snip = r.snippet
+                ? `\n     ${ellipsize(r.snippet.replace(/\s+/g, " "), 100)}`
+                : "";
+            return `${String(r.rank).padStart(2)}. ${r.title || r.url}\n     ${r.url}${snip}`;
+        });
+        process.stdout.write(lines.join("\n") + "\n");
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", sigint);
+        process.off("SIGTERM", sigint);
+    }
+}
+// `deepdive open <id> [--out=path]` — render a saved session to a self-
+// contained HTML file (temp dir, or --out) and open it in the default browser.
+// The browser spawn is best-effort; the file path is always printed so a
+// headless box can open it manually.
+async function openCommand(parsed) {
+    const config = resolveConfig(parsed.flags, process.env);
+    const idArg = parsed.extras[0];
+    if (!idArg) {
+        process.stderr.write(`deepdive: open requires a session id (try \`deepdive sessions ls\`)\n`);
+        return 2;
+    }
+    try {
+        const id = await resolveSessionId(idArg, { dir: config.sessions.dir });
+        const record = await loadSession(id, { dir: config.sessions.dir });
+        const file = parsed.outPath
+            ? resolve(parsed.outPath)
+            : join(tmpdir(), `deepdive-${id}.html`);
+        writeFileSync(file, renderHtmlReport(record), "utf-8");
+        const { cmd, args } = browserOpenCommand(process.platform, file);
+        try {
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            // Opener missing (e.g. headless box with no xdg-open) is non-fatal — the
+            // path is printed for manual opening.
+            child.on("error", () => undefined);
+            child.unref();
+        }
+        catch {
+            /* non-fatal */
+        }
+        process.stderr.write(`opened ${file}\n`);
+        process.stdout.write(file + "\n");
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        return 1;
+    }
+}
 async function runResearch(opts) {
     const { question, parsed, config, preKept, parentId } = opts;
+    // A --since value that was supplied but didn't parse is a user error — fail
+    // loud rather than silently running with no recency filter.
+    if (config.sinceRaw && config.sinceMs === undefined) {
+        process.stderr.write(`deepdive: --since must be a date (2024, 2024-06, 2024-06-15) or a duration ` +
+            `(30d, 12h, 2w); got: ${config.sinceRaw}\n`);
+        return 2;
+    }
     const search = await resolveSearchAdapter(config.searchAdapter, process.env);
     const cache = config.cache.enabled
         ? createCache({ dir: config.cache.dir, ttlMs: config.cache.ttlMs })
@@ -513,6 +748,8 @@ async function runResearch(opts) {
             pdfMaxPages: config.pdfMaxPages,
             include: config.include,
             domainFilter: config.domainFilter,
+            tldr: config.tldr,
+            sinceMs: config.sinceMs,
             env: process.env,
             onEvent: (e) => {
                 if (config.verbose)
@@ -560,6 +797,14 @@ async function runResearch(opts) {
         const costLine = config.costEnabled && !config.jsonOutput
             ? renderMultiModelCostSummary(result.cost, config.llm.baseUrl)
             : "";
+        // Coverage/confidence signal — computed always (goes into --json), shown on
+        // stderr alongside the cost summary (suppressed by --no-cost / --json).
+        const confidence = assessConfidence({
+            sources: result.usage.kept,
+            citationsTotal: result.usage.citationsTotal,
+            citationsSupported: result.usage.citationsSupported,
+        });
+        const confidenceLine = config.costEnabled && !config.jsonOutput ? formatConfidenceLine(confidence) : "";
         if (streaming && streamed) {
             // Streaming mode already wrote the header + answer tokens. Close with
             // the sources block, optional citation-health footer, and (if
@@ -575,6 +820,8 @@ async function runResearch(opts) {
             }
             if (costLine)
                 process.stderr.write(costLine + "\n");
+            if (confidenceLine)
+                process.stderr.write(confidenceLine + "\n");
             if (sessionId)
                 writeSessionHint(sessionId);
             return strictFail ? 1 : 0;
@@ -589,11 +836,13 @@ async function runResearch(opts) {
                     url: s.url,
                     title: s.title,
                     fetchedAt: s.fetchedAt,
+                    publishedAt: s.publishedAt,
                 })),
                 answer: result.answer,
                 verification: result.verification,
                 cost: result.cost,
                 usage: result.usage,
+                confidence,
             }, null, 2) + "\n"
             : result.markdown +
                 (result.markdown.endsWith("\n") ? "" : "\n") +
@@ -606,6 +855,8 @@ async function runResearch(opts) {
         }
         if (costLine)
             process.stderr.write(costLine + "\n");
+        if (confidenceLine)
+            process.stderr.write(confidenceLine + "\n");
         if (sessionId)
             writeSessionHint(sessionId);
         return strictFail ? 1 : 0;
@@ -654,10 +905,19 @@ function writeSessionHint(id) {
 async function sessionsCommand(parsed) {
     const config = resolveConfig(parsed.flags, process.env);
     const sub = parsed.extras[0] ?? "ls";
-    if (sub !== "ls") {
-        process.stderr.write(`deepdive: unknown sessions sub-command: ${sub}\n`);
-        return 2;
+    switch (sub) {
+        case "ls":
+            return await sessionsLs(config);
+        case "rm":
+            return await sessionsRm(parsed, config);
+        case "prune":
+            return await sessionsPrune(parsed, config);
+        default:
+            process.stderr.write(`deepdive: unknown sessions sub-command: ${sub} (try: ls | rm | prune)\n`);
+            return 2;
     }
+}
+async function sessionsLs(config) {
     const { sessions, bad } = await listSessions({ dir: config.sessions.dir });
     if (config.jsonOutput) {
         process.stdout.write(JSON.stringify({ sessions, bad }, null, 2) + "\n");
@@ -669,6 +929,151 @@ async function sessionsCommand(parsed) {
     }
     return 0;
 }
+async function sessionsRm(parsed, config) {
+    const idArgs = parsed.extras.slice(1);
+    if (idArgs.length === 0) {
+        process.stderr.write(`deepdive: sessions rm requires at least one session id (try \`deepdive sessions ls\`)\n`);
+        return 2;
+    }
+    let failed = 0;
+    for (const idArg of idArgs) {
+        try {
+            const id = await resolveSessionId(idArg, { dir: config.sessions.dir });
+            await deleteSession(id, { dir: config.sessions.dir });
+            process.stdout.write(`removed ${id}\n`);
+        }
+        catch (err) {
+            failed++;
+            process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        }
+    }
+    return failed > 0 ? 1 : 0;
+}
+async function sessionsPrune(parsed, config) {
+    const { olderThan, keep, dryRun } = parsed.flags;
+    if (olderThan === undefined && keep === undefined) {
+        process.stderr.write(`deepdive: sessions prune needs --older-than=<dur> and/or --keep=<n>\n` +
+            `  e.g. deepdive sessions prune --older-than=30d\n` +
+            `       deepdive sessions prune --keep=20\n` +
+            `       deepdive sessions prune --older-than=7d --keep=5 --dry-run\n`);
+        return 2;
+    }
+    let olderThanMs;
+    if (olderThan !== undefined) {
+        olderThanMs = parseDuration(olderThan);
+        if (olderThanMs === undefined) {
+            process.stderr.write(`deepdive: --older-than must be a duration like 30d, 12h, 90m, 2w (got: ${olderThan})\n`);
+            return 2;
+        }
+    }
+    const { removed, remaining, bad } = await pruneSessions({ dir: config.sessions.dir }, { olderThanMs, keep, dryRun });
+    if (config.jsonOutput) {
+        process.stdout.write(JSON.stringify({ removed, remaining, bad, dryRun: !!dryRun }, null, 2) + "\n");
+        return 0;
+    }
+    const verb = dryRun ? "would remove" : "removed";
+    process.stdout.write(`${verb} ${removed.length} session${removed.length === 1 ? "" : "s"} · ${remaining} remaining\n`);
+    for (const m of removed) {
+        const q = m.question.length > 60 ? m.question.slice(0, 59) + "…" : m.question;
+        process.stdout.write(`  ${dryRun ? "-" : "✓"} ${m.id}  ${q}\n`);
+    }
+    if (bad.length > 0) {
+        process.stderr.write(`\n(${bad.length} unparsable session file${bad.length === 1 ? "" : "s"} left in place)\n`);
+    }
+    return 0;
+}
+// `deepdive export <id> [--format=html|md] [--out=path]` — render a saved
+// session as a shareable artifact. HTML is a single self-contained document;
+// md re-renders the original cited markdown. Format is inferred from --out's
+// extension when not given, defaulting to html.
+async function exportCommand(parsed) {
+    const config = resolveConfig(parsed.flags, process.env);
+    const idArg = parsed.extras[0];
+    if (!idArg) {
+        process.stderr.write(`deepdive: export requires a session id (try \`deepdive sessions ls\`)\n`);
+        return 2;
+    }
+    const format = parsed.flags.format ?? inferFormatFromPath(parsed.outPath) ?? "html";
+    if (format !== "html" && format !== "md" && format !== "markdown") {
+        process.stderr.write(`deepdive: --format must be html or md (got: ${format})\n`);
+        return 2;
+    }
+    try {
+        const id = await resolveSessionId(idArg, { dir: config.sessions.dir });
+        const record = await loadSession(id, { dir: config.sessions.dir });
+        const output = format === "html"
+            ? renderHtmlReport(record)
+            : renderAnswerMarkdown(record.question, record.answer, record.sources) +
+                renderCitationHealthFooter(record.verification);
+        if (parsed.outPath) {
+            const path = resolve(parsed.outPath);
+            writeFileSync(path, output, "utf-8");
+            process.stderr.write(`wrote ${path}\n`);
+        }
+        else {
+            process.stdout.write(output + (output.endsWith("\n") ? "" : "\n"));
+        }
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        return 1;
+    }
+}
+function inferFormatFromPath(p) {
+    if (!p)
+        return undefined;
+    const lower = p.toLowerCase();
+    if (lower.endsWith(".html") || lower.endsWith(".htm"))
+        return "html";
+    if (lower.endsWith(".md") || lower.endsWith(".markdown"))
+        return "md";
+    return undefined;
+}
+// `deepdive diff <id-a> <id-b> [--narrate] [--json]` — show how the answer
+// (and the sources behind it) changed between two saved runs. The local-only
+// longitudinal view. `--narrate` adds a one-shot LLM summary of the change.
+async function diffCommand(parsed) {
+    const config = resolveConfig(parsed.flags, process.env);
+    const [idArgA, idArgB] = parsed.extras;
+    if (!idArgA || !idArgB) {
+        process.stderr.write(`deepdive: diff requires two session ids (try \`deepdive sessions ls\`)\n`);
+        return 2;
+    }
+    const ac = new AbortController();
+    const sigint = () => ac.abort();
+    process.on("SIGINT", sigint);
+    process.on("SIGTERM", sigint);
+    try {
+        const dir = { dir: config.sessions.dir };
+        const a = await loadSession(await resolveSessionId(idArgA, dir), dir);
+        const b = await loadSession(await resolveSessionId(idArgB, dir), dir);
+        const diff = diffSessions(a, b);
+        let narration;
+        if (parsed.flags.narrate) {
+            const { text } = await callLLM([{ role: "user", content: buildDiffNarrateUser(a, b) }], DIFF_NARRATE_SYSTEM, config.llm, ac.signal);
+            narration = text.trim();
+        }
+        if (config.jsonOutput) {
+            process.stdout.write(JSON.stringify({ diff, narration }, null, 2) + "\n");
+            return 0;
+        }
+        const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+        process.stdout.write(renderDiffText(diff, { color: useColor }) + "\n");
+        if (narration) {
+            process.stdout.write(`\n## What changed (narrated)\n\n${narration}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`deepdive: ${safeErrorMessage(err)}\n`);
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", sigint);
+        process.off("SIGTERM", sigint);
+    }
+}
 async function showCommand(parsed) {
     const config = resolveConfig(parsed.flags, process.env);
     const idArg = parsed.extras[0];
@@ -717,12 +1122,16 @@ async function resumeCommand(parsed) {
         // v0.10.0 — resume re-synthesizes against saved sources, so use the
         // synth-stage model (no plan / critic stages in resume mode).
         const synthLLM = { ...config.llm, model: config.models.synth };
-        const answer = await synthesize(newQuestion, record.sources, synthLLM, ac.signal, streaming
-            ? (chunk) => {
-                streamed = true;
-                process.stdout.write(chunk);
-            }
-            : undefined, onUsage);
+        const answer = await synthesize(newQuestion, record.sources, synthLLM, ac.signal, {
+            onToken: streaming
+                ? (chunk) => {
+                    streamed = true;
+                    process.stdout.write(chunk);
+                }
+                : undefined,
+            onUsage,
+            tldr: config.tldr,
+        });
         // Cite verification (final only — no in-loop because there's no loop)
         let verification;
         if (config.verifyCitations !== false && answer) {