@signal4/s4 2.5.0 → 2.6.1

package/dist/cli.js

@@ -2,8 +2,9 @@
 import { applyConfig } from "./config.js";
 import { HANDLERS } from "./handlers/registry.js";
 import * as client from "./client.js";
-import { writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { writeFileSync, mkdirSync, existsSync, chmodSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { formatDossier } from "./format.js";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline/promises";
 function parseArgs(argv, specs) {
@@ -35,56 +36,210 @@ function parseArgs(argv, specs) {
             }
             else {
                 const val = argv[++i];
-                flags[spec.name] = spec.type === "number" ? Number(val) : (val ?? "");
+                if (spec.type === "number") {
+                    const num = Number(val);
+                    if (val === undefined || val === "" || Number.isNaN(num)) {
+                        process.stderr.write(`Error: --${spec.name} expects a number, got "${val ?? ""}".\n`);
+                        process.exit(1);
+                    }
+                    flags[spec.name] = num;
+                }
+                else {
+                    flags[spec.name] = val ?? "";
+                }
             }
         }
         else if (arg.startsWith("-") && arg !== "-") {
-            process.stderr.write(`Warning: unknown flag "${arg}"\n`);
+            // Hard error, not a warning: a silently-dropped flag falls through to
+            // default behavior, and the caller reads the wrong answer as the right one.
+            const valid = specs.map((s) => `--${s.name}${s.alias ? ` (-${s.alias})` : ""}`).join(", ");
+            process.stderr.write(`Error: unknown flag "${arg}" for this command.\nValid flags: ${valid}\nRun with --help for details.\n`);
+            process.exit(1);
         }
         else {
             positionals.push(arg);
         }
         i++;
     }
+    // Post-parse validation for shared flags — a silently NaN-coerced --days or
+    // a raw backend error for a malformed date both read as broken tooling.
+    const days = flags.days;
+    if (typeof days === "number" && specs.some((s) => s.name === "days")) {
+        if (!Number.isInteger(days) || days < 1) {
+            process.stderr.write(`Error: --days must be a positive integer (got "${days}").\n`);
+            process.exit(1);
+        }
+        if (days > 365) {
+            process.stderr.write(`Error: --days is capped at 365. Use --start YYYY-MM-DD for older material (s4 search also supports --full-history).\n`);
+            process.exit(1);
+        }
+    }
+    for (const name of ["start", "end"]) {
+        const v = flags[name];
+        if (typeof v === "string" && v && !/^\d{4}-\d{2}-\d{2}$/.test(v)) {
+            process.stderr.write(`Error: --${name} must be YYYY-MM-DD (e.g. 2026-07-13), got "${v}".\n`);
+            process.exit(1);
+        }
+    }
     return { positionals, flags };
 }
 // ---------------------------------------------------------------------------
 // Shared flag specs
 // ---------------------------------------------------------------------------
-const FLAG_DAYS = { name: "days", alias: "d", type: "number", default: 30 };
-const FLAG_LIMIT = { name: "limit", alias: "n", type: "number", default: 20 };
-const FLAG_OFFSET = { name: "offset", alias: "o", type: "number", default: 0 };
-const FLAG_SPEAKER = { name: "speaker", alias: "s", type: "string" };
-const FLAG_CHANNEL = { name: "channel", alias: "c", type: "string" };
-const FLAG_LANGUAGE = { name: "language", alias: "l", type: "string" };
-const FLAG_COUNTRY = { name: "country", type: "string" };
-const FLAG_MODE = { name: "mode", alias: "m", type: "string", default: "semantic" };
-const FLAG_START = { name: "start", type: "string" };
-const FLAG_END = { name: "end", type: "string" };
-const FLAG_KEYWORD = { name: "keyword", alias: "k", type: "string" };
-const FLAG_SKIP_CACHE = { name: "skip-cache", type: "boolean" };
-const FLAG_JSON = { name: "json", type: "boolean" };
+const FLAG_DAYS = { name: "days", alias: "d", type: "number", default: 30, desc: "Time window in days (max 365 — use --start for older material)" };
+const FLAG_LIMIT = { name: "limit", alias: "n", type: "number", default: 20, desc: "Max results" };
+const FLAG_OFFSET = { name: "offset", alias: "o", type: "number", default: 0, desc: "Pagination offset" };
+const FLAG_SPEAKER = { name: "speaker", alias: "s", type: "string", desc: "Filter by speaker name (full name)" };
+const FLAG_CHANNEL = { name: "channel", alias: "c", type: "string", desc: "Filter by channel name (comma-separated for multiple)" };
+const FLAG_LANGUAGE = { name: "language", alias: "l", type: "string", desc: "Filter by language code (en, fr, ...)" };
+const FLAG_COUNTRY = { name: "country", type: "string", desc: "Filter by channel country code" };
+const FLAG_PROJECT = { name: "project", type: "string", desc: "Restrict to a project (e.g. Big_Channels)" };
+const FLAG_MODE = { name: "mode", alias: "m", type: "string", default: "semantic", desc: "Search mode: semantic | keyword | hybrid" };
+const FLAG_START = { name: "start", type: "string", desc: "Start date YYYY-MM-DD (no cap — overrides --days)" };
+const FLAG_END = { name: "end", type: "string", desc: "End date YYYY-MM-DD (default today)" };
+const FLAG_KEYWORD = { name: "keyword", alias: "k", type: "string", desc: "Exact keyword search (implies --mode keyword)" };
+const FLAG_SKIP_CACHE = { name: "skip-cache", type: "boolean", desc: "Force fresh analysis (bypass cache)" };
+const FLAG_OUT = { name: "out", type: "string", desc: "Write the rendered output to a file (.md, or .csv on search)" };
+const FLAG_JSON = { name: "json", type: "boolean", desc: "Raw JSON output" };
+// ---------------------------------------------------------------------------
+// Progress reporting for long-running analysis commands
+// ---------------------------------------------------------------------------
+/** Human phrases for backend pipeline step names (unknown steps print as-is). */
+const STEP_LABELS = {
+    expand_query: "expanding query",
+    retrieve_segments: "retrieving evidence",
+    retrieve_segments_by_search: "retrieving evidence",
+    generate_summaries: "writing summaries",
+    retrieve_all_segments: "retrieving evidence",
+    retrieve_clustered_segments: "retrieving evidence",
+    retrieve_per_speaker: "retrieving evidence per speaker",
+    retrieve_per_period: "retrieving evidence per period",
+    resolve_speakers: "resolving speakers",
+    cluster_segments: "clustering segments",
+    quick_cluster_check: "checking clusters",
+    filter_clusters: "filtering clusters",
+    rank_and_select: "ranking evidence",
+    select_segments: "selecting segments",
+    select_segments_per_bucket: "selecting segments",
+    name_themes: "naming themes",
+    analyze_themes_with_subthemes: "analyzing themes",
+    extract_subthemes: "extracting subthemes",
+    extract_stances: "extracting stances",
+    extract_co_mentions: "extracting co-mentions",
+    detect_contradictions: "detecting contradictions",
+    detect_stance_shifts: "detecting stance shifts",
+    detect_trajectory: "detecting trajectory",
+    detect_velocity: "measuring velocity",
+    quantitative_analysis: "computing metrics",
+    corpus_analysis: "analyzing corpus",
+    group_by_time: "grouping by time",
+    entity_timeline: "building timeline",
+    build_relationship_graph: "building relationship graph",
+    pack_channel_segments: "packing channel evidence",
+    generate_summary: "writing summary",
+    generate_dossier: "writing dossier",
+    generate_comparison: "writing comparison",
+    generate_evolution: "writing evolution analysis",
+    generate_temporal_evolution: "writing temporal evolution",
+};
+function stepLabel(step) {
+    return STEP_LABELS[step] ?? step.replace(/_/g, " ");
+}
+/**
+ * Stderr progress line for analytical commands. TTY: a single line rewritten
+ * in place with elapsed seconds. Non-TTY: one plain line per step change,
+ * plus a heartbeat every 15s so piped/captured stderr shows liveness.
+ * Everything goes to stderr — stdout (--json, --out, pipes) stays clean.
+ */
+function createProgress() {
+    const t0 = Date.now();
+    const tty = process.stderr.isTTY === true;
+    let current = "working";
+    let finished = false;
+    let lastWrite = Date.now();
+    const secs = () => Math.round((Date.now() - t0) / 1000);
+    const write = (line) => {
+        if (tty)
+            process.stderr.write(`\r\x1b[2K${line}`);
+        else
+            process.stderr.write(line + "\n");
+        lastWrite = Date.now();
+    };
+    const timer = setInterval(() => {
+        if (finished)
+            return;
+        if (tty)
+            write(`⏳ ${current}… [${secs()}s]`);
+        else if (Date.now() - lastWrite >= 15000)
+            write(`still working (${current})… [${secs()}s]`);
+    }, 1000);
+    timer.unref?.();
+    return {
+        update(step) {
+            if (finished)
+                return;
+            const label = stepLabel(step);
+            if (label === current)
+                return;
+            current = label;
+            write(`⏳ ${label}… [${secs()}s]`);
+        },
+        finish() {
+            if (finished)
+                return;
+            finished = true;
+            clearInterval(timer);
+            if (tty)
+                process.stderr.write("\r\x1b[2K");
+        },
+    };
+}
+/** Commands that stream the analysis pipeline and deserve step narration. */
+const PROGRESS_COMMANDS = new Set([
+    "analyze", "frames", "compare", "dossier", "compare-periods", "contradictions",
+]);
+/** Active reporter — print()/writeOut() finish it before emitting output so a
+ *  TTY progress line (no trailing newline) never collides with results. */
+let activeProgress = null;
 function daysRange(days) {
     const end = new Date().toISOString().slice(0, 10);
     const start = new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
     return { start_date: start, end_date: end };
 }
 function parseSegmentId(raw) {
-    // Quote listings display IDs as "seg:12345" — accept that form verbatim.
-    const id = Number(raw.replace(/^seg:/, ""));
+    // Quote listings display IDs as "seg:12345"; dossier citations as "{seg_12345}".
+    // Accept all of: N, seg:N, seg_N, {seg_N}, {seg:N}.
+    const id = Number(raw.replace(/^\{(.*)\}$/, "$1").replace(/^seg[:_]/, ""));
     if (!Number.isInteger(id)) {
-        print(`Error: invalid segment ID "${raw}" (expected a number or seg:<number>).`);
+        print(`Error: invalid segment ID "${raw}" (expected a number, seg:<number>, or seg_<number>).`);
         process.exit(1);
     }
     return id;
 }
 function print(text) {
+    activeProgress?.finish();
     process.stdout.write(text + "\n");
 }
+/** Write a deliverable to disk (markdown as rendered; CSV via toCsv). */
+function writeOut(path, text) {
+    activeProgress?.finish();
+    writeFileSync(path, text.endsWith("\n") ? text : text + "\n");
+    process.stderr.write(`Wrote ${path}\n`);
+}
+function csvEscape(v) {
+    const s = v == null ? "" : String(v);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+function toCsv(rows, columns) {
+    const lines = [columns.join(",")];
+    for (const r of rows)
+        lines.push(columns.map((c) => csvEscape(r[c])).join(","));
+    return lines.join("\n");
+}
 function printJson(data) {
     print(JSON.stringify(data, null, 2));
 }
-async function runHandler(tool, params) {
+async function runHandler(tool, params, out) {
     const handler = HANDLERS[tool];
     if (!handler) {
         print(`Error: handler "${tool}" not found.`);
@@ -95,18 +250,172 @@ async function runHandler(tool, params) {
         process.stderr.write((result.content[0]?.text ?? "Unknown error") + "\n");
         process.exit(1);
     }
-    print(result.content[0]?.text ?? "");
+    const text = result.content[0]?.text ?? "";
+    if (out)
+        writeOut(out, text);
+    else
+        print(text);
+}
+// ---------------------------------------------------------------------------
+// Batch dossiers (surrogate-roster sweeps): s4 dossier "<topic>" --speakers file.txt --out dir/
+// ---------------------------------------------------------------------------
+function slugify(name) {
+    const slug = name.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug || "speaker";
+}
+function readRoster(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`Error: cannot read roster file "${path}": ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const seen = new Set();
+    const names = [];
+    for (const line of raw.split("\n")) {
+        const name = line.trim();
+        if (!name || name.startsWith("#"))
+            continue;
+        if (seen.has(name.toLowerCase()))
+            continue;
+        seen.add(name.toLowerCase());
+        names.push(name);
+    }
+    return names;
+}
+function writeBatchIndex(dir, topic, days, rows) {
+    const lines = [
+        `# Dossier batch: ${topic}`,
+        "",
+        `Generated ${new Date().toISOString().slice(0, 16).replace("T", " ")} UTC · window: last ${days} days · ${rows.length} speakers`,
+        "",
+        "| Speaker | On-topic segments | Gated out | Thin evidence | Contradictions | Dossier |",
+        "|---|---|---|---|---|---|",
+    ];
+    const cell = (v) => (v === undefined || v === null ? "—" : String(v));
+    for (const r of rows) {
+        const file = r.file ? `[${r.file}](./${r.file})` : "—";
+        if (r.status === "error") {
+            lines.push(`| ${r.speaker} | — | — | — | — | ERROR: ${(r.error ?? "unknown").replace(/\|/g, "/").replace(/\n/g, " ")} |`);
+        }
+        else if (r.status === "skipped") {
+            lines.push(`| ${r.speaker} | — | — | — | — | ${file} (existing, not re-analyzed) |`);
+        }
+        else {
+            lines.push(`| ${r.speaker} | ${cell(r.segments)} | ${cell(r.gatedOut)} | ${r.thin ? "⚠ yes" : "no"} | ${cell(r.contradictions)} | ${file} |`);
+        }
+    }
+    lines.push("");
+    writeFileSync(join(dir, "INDEX.md"), lines.join("\n"));
+}
+async function runDossierBatch(topic, args, json) {
+    const f = args.flags;
+    if (json) {
+        process.stderr.write("Error: --json is not supported with --speakers (batch mode writes markdown files).\n");
+        process.exit(1);
+    }
+    const outDir = f.out;
+    if (!outDir) {
+        process.stderr.write("Error: batch mode (--speakers) requires --out <directory> — one <speaker>.md per speaker plus INDEX.md are written there.\n");
+        process.exit(1);
+    }
+    if (outDir.endsWith(".md")) {
+        process.stderr.write(`Error: with --speakers, --out must be a directory, not a .md file (got "${outDir}").\n`);
+        process.exit(1);
+    }
+    if (existsSync(outDir) && !statSync(outDir).isDirectory()) {
+        process.stderr.write(`Error: --out "${outDir}" exists and is not a directory.\n`);
+        process.exit(1);
+    }
+    mkdirSync(outDir, { recursive: true });
+    const names = readRoster(f.speakers);
+    if (!names.length) {
+        process.stderr.write(`Error: roster file "${f.speakers}" contains no speaker names.\n`);
+        process.exit(1);
+    }
+    const days = Number(f.days) || 180;
+    const skipCache = f["skip-cache"];
+    const force = f.force;
+    // The outer progress reporter from main() would smear step updates across
+    // speakers — retire it and run a fresh reporter per dossier.
+    activeProgress?.finish();
+    activeProgress = null;
+    const rows = [];
+    let failures = 0;
+    for (let i = 0; i < names.length; i++) {
+        const speaker = names[i];
+        const file = `${slugify(speaker)}.md`;
+        const path = join(outDir, file);
+        const tag = `[${i + 1}/${names.length}]`;
+        if (!force && existsSync(path)) {
+            process.stderr.write(`${tag} skipping ${speaker} (exists)\n`);
+            rows.push({ speaker, file, status: "skipped" });
+            writeBatchIndex(outDir, topic, days, rows);
+            continue;
+        }
+        process.stderr.write(`${tag} Building dossier: ${speaker}…\n`);
+        const progress = createProgress();
+        activeProgress = progress;
+        client.setAnalysisProgressListener((e) => {
+            if (e.step && (e.type === "progress" || e.type === "result"))
+                progress.update(e.step);
+        });
+        try {
+            const data = await client.analyze({
+                query: topic, workflow: "speaker_dossier", speaker_name: speaker,
+                days, skip_cache: skipCache || undefined,
+            });
+            progress.finish();
+            if (data.error)
+                throw new Error(data.error);
+            const text = formatDossier(data, speaker, topic);
+            writeFileSync(path, text.endsWith("\n") ? text : text + "\n");
+            process.stderr.write(`${tag} Wrote ${path}\n`);
+            const sp = (data.speaker ?? {});
+            const ret = (sp.retrieval ?? {});
+            rows.push({
+                speaker, file, status: "ok",
+                segments: sp.segment_count ?? 0,
+                gatedOut: ret.gated_out,
+                thin: Boolean(ret.thin_evidence),
+                contradictions: data.contradictions?.contradictions?.length,
+            });
+        }
+        catch (err) {
+            progress.finish();
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`${tag} ERROR for ${speaker}: ${msg}\n`);
+            rows.push({ speaker, status: "error", error: msg });
+            failures++;
+        }
+        finally {
+            client.setAnalysisProgressListener(null);
+            activeProgress = null;
+        }
+        // Rewrite the index after every speaker so a killed batch leaves a usable summary.
+        writeBatchIndex(outDir, topic, days, rows);
+    }
+    writeBatchIndex(outDir, topic, days, rows);
+    const ok = rows.filter((r) => r.status === "ok").length;
+    const skipped = rows.filter((r) => r.status === "skipped").length;
+    process.stderr.write(`Done: ${ok} built, ${skipped} skipped, ${failures} failed → ${join(outDir, "INDEX.md")}\n`);
+    if (failures)
+        process.exitCode = 1;
 }
 const COMMANDS = {
     search: {
         tool: "search_quotes",
         description: "Search quotes by topic and/or speaker",
         specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_MODE, FLAG_LIMIT, FLAG_OFFSET, FLAG_LANGUAGE, FLAG_COUNTRY,
-            { name: "sort", type: "string", default: "relevance" },
-            { name: "count", type: "boolean" },
-            { name: "full-history", type: "boolean" },
+            { name: "sort", type: "string", default: "relevance", desc: "relevance | chronological" },
+            { name: "count", type: "boolean", desc: "Return only the match count" },
+            { name: "full-history", type: "boolean", desc: "Search the entire corpus (requires topic + speaker)" },
+            { name: "min-similarity", type: "number", desc: "Minimum similarity threshold (0.0-1.0, default 0.40)" },
             FLAG_KEYWORD,
-            { name: "speaker-id", type: "number" },
+            { name: "speaker-id", type: "number", desc: "Speaker identity ID (from s4 speaker)" }, FLAG_OUT,
             FLAG_START, FLAG_END,
             FLAG_JSON],
         run: async (args, json) => {
@@ -116,8 +425,12 @@ const COMMANDS = {
             const topic = positionalTopic || keyword || undefined;
             const mode = keyword ? "keyword" : f.mode;
             const days = Number(f.days) || 30;
-            const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : daysRange(days);
             const fullHistory = f["full-history"];
+            // Full history means FULL history — only pass dates given explicitly,
+            // or the default range silently re-windows the search to --days.
+            const dr = f.start
+                ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) }
+                : (fullHistory ? {} : daysRange(days));
             const params = {
                 topic, speaker: f.speaker || undefined,
                 speaker_id: Number(f["speaker-id"]) || undefined,
@@ -128,9 +441,11 @@ const COMMANDS = {
                 mode, limit: Number(f.limit), offset: Number(f.offset),
                 count_only: f.count, sort: f.sort,
                 full_history: fullHistory,
+                min_similarity: f["min-similarity"] !== undefined ? Number(f["min-similarity"]) : undefined,
             };
-            if (json)
-                return printJson(await client.searchQuotes({
+            const out = f.out;
+            if (json || (out && out.endsWith(".csv"))) {
+                const data = await client.searchQuotes({
                     topic: params.topic, speaker_name: params.speaker,
                     speaker_identity_id: params.speaker_id,
                     channel_names: params.channel ? params.channel.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
@@ -140,22 +455,47 @@ const COMMANDS = {
                     limit: params.limit, offset: params.offset,
                     full_history: fullHistory || undefined,
                     count_only: params.count_only || undefined,
-                }));
-            await runHandler("search_quotes", params);
+                    min_similarity: params.min_similarity,
+                });
+                if (out && out.endsWith(".csv")) {
+                    const rows = (data.quotes ?? []).map((q) => ({
+                        segment_id: q.segment_id,
+                        date: (q.publish_date ?? q.episode_date ?? "").slice(0, 10),
+                        speaker: q.speaker?.name,
+                        speaker_confidence: q.speaker?.confidence,
+                        appearance_type: q.speaker?.appearance_type,
+                        channel: q.channel_name,
+                        episode: q.episode_title,
+                        similarity: q.similarity,
+                        start_time: q.start_time ?? q.timestamp_start,
+                        end_time: q.end_time ?? q.timestamp_end,
+                        text: q.text,
+                        audio_url: q.clip_url,
+                    }));
+                    return writeOut(out, toCsv(rows, [
+                        "segment_id", "date", "speaker", "speaker_confidence", "appearance_type",
+                        "channel", "episode", "similarity", "start_time", "end_time", "text", "audio_url",
+                    ]));
+                }
+                return printJson(data);
+            }
+            await runHandler("search_quotes", params, out);
         },
     },
     claims: {
         tool: "search_claims",
         description: "Search extracted claims",
-        specs: [{ name: "entity", alias: "e", type: "string" }, FLAG_SPEAKER, FLAG_CHANNEL,
-            { name: "category", type: "string" }, { name: "stance", type: "string" },
+        specs: [{ name: "entity", alias: "e", type: "string", desc: "Filter by entity name (person, org, place, subject)" }, FLAG_SPEAKER, FLAG_CHANNEL,
+            { name: "category", type: "string", desc: "Topic category filter" },
+            { name: "stance", type: "string", desc: "Filter by stance: assert | deny | speculate | attribute" },
             FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_MODE, FLAG_KEYWORD,
-            { name: "sort", type: "string", default: "relevance" },
-            { name: "min-obs", type: "number", default: 1 },
-            { name: "min-similarity", type: "number" },
-            { name: "political-lean-min", type: "number" }, { name: "political-lean-max", type: "number" },
-            { name: "source", type: "string" },
-            FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_START, FLAG_END, FLAG_JSON],
+            { name: "sort", type: "string", default: "relevance", desc: "Sort: relevance | observations | recent | spread" },
+            { name: "min-obs", type: "number", default: 1, desc: "Minimum observation count per claim" },
+            { name: "min-similarity", type: "number", desc: "Min semantic similarity (0.0-1.0, default 0.4) — raise to tighten matching" },
+            { name: "political-lean-min", type: "number", desc: "Min channel political lean (0=left, 1=right)" },
+            { name: "political-lean-max", type: "number", desc: "Max channel political lean (0=left, 1=right)" },
+            { name: "source", type: "string", desc: "Claim source filter" },
+            FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_START, FLAG_END, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [positionalTopic] = args.positionals;
             const f = args.flags;
@@ -197,14 +537,14 @@ const COMMANDS = {
                     min_observations: params.min_observations > 1 ? params.min_observations : undefined,
                     limit: params.limit, offset: params.offset,
                 }));
-            await runHandler("search_claims", params);
+            await runHandler("search_claims", params, f.out);
         },
     },
     "analyze-claims": {
         tool: "analyze_claims",
         description: "Analyze a topic over extracted claims — themes with observation stats (fast, no LLM)",
         specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_DAYS,
-            { name: "min-obs", type: "number", default: 1 }, FLAG_JSON],
+            { name: "min-obs", type: "number", default: 1, desc: "Minimum observation count per claim" }, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -232,9 +572,9 @@ const COMMANDS = {
     "trend-claims": {
         tool: "trend_claims",
         description: "Detect whether a topic is surging/fading by claim volume (fast)",
-        specs: [{ name: "recent-days", type: "number", default: 7 },
-            { name: "baseline-days", type: "number", default: 30 },
-            { name: "min-similarity", type: "number" }, FLAG_JSON],
+        specs: [{ name: "recent-days", type: "number", default: 7, desc: "Recent window in days" },
+            { name: "baseline-days", type: "number", default: 30, desc: "Baseline window in days" },
+            { name: "min-similarity", type: "number", desc: "Minimum similarity threshold (0.0-1.0)" }, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -256,7 +596,7 @@ const COMMANDS = {
     "contradict-claims": {
         tool: "contradict_claims",
         description: "Find a speaker's contradictory claims on a topic via stance analysis (fast)",
-        specs: [FLAG_SPEAKER, FLAG_DAYS, FLAG_JSON],
+        specs: [FLAG_SPEAKER, { ...FLAG_DAYS, default: 365 }, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -274,13 +614,13 @@ const COMMANDS = {
                 return printJson(await client.checkContradictionsClaims({
                     topic, speaker_name: speaker, days: params.days,
                 }));
-            await runHandler("contradict_claims", params);
+            await runHandler("contradict_claims", params, f.out);
         },
     },
     "compare-claims": {
         tool: "compare_claims",
         description: "Compare 2-5 speakers' claims on a topic — side-by-side stance (fast)",
-        specs: [{ name: "speakers", type: "string" }, FLAG_SPEAKER, FLAG_DAYS, FLAG_JSON],
+        specs: [{ name: "speakers", type: "string", desc: "2-5 comma-separated speaker names" }, FLAG_SPEAKER, { ...FLAG_DAYS, default: 90 }, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -299,13 +639,13 @@ const COMMANDS = {
                 return printJson(await client.compareSpeakersClaims({
                     topic, speaker_names: speakers, days: params.days,
                 }));
-            await runHandler("compare_claims", params);
+            await runHandler("compare_claims", params, f.out);
         },
     },
     "channel-dossier": {
         tool: "channel_dossier",
         description: "Claims dossier of what a channel (show) platformed on a topic (fast)",
-        specs: [FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 180 }, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -324,13 +664,13 @@ const COMMANDS = {
                 return printJson(await client.buildChannelDossier({
                     topic, channel_names: channels, days,
                 }));
-            await runHandler("channel_dossier", { topic, channels, days });
+            await runHandler("channel_dossier", { topic, channels, days }, f.out);
         },
     },
     "compare-channels": {
         tool: "compare_channels",
         description: "Compare 2-5 channels' claims on a topic — stance + speaker overlap (fast)",
-        specs: [{ name: "channels", type: "string" }, FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        specs: [{ name: "channels", type: "string", desc: "2-5 comma-separated channel names" }, FLAG_CHANNEL, { ...FLAG_DAYS, default: 90 }, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -349,13 +689,13 @@ const COMMANDS = {
                 return printJson(await client.compareChannelsClaims({
                     topic, channel_names: channels, days,
                 }));
-            await runHandler("compare_channels", { topic, channels, days });
+            await runHandler("compare_channels", { topic, channels, days }, f.out);
         },
     },
     "channel-contradictions": {
         tool: "check_channel_contradictions",
         description: "Contradictory claims a channel platforms on a topic (fast)",
-        specs: [FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 365 }, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -374,13 +714,13 @@ const COMMANDS = {
                 return printJson(await client.checkChannelContradictionsClaims({
                     topic, channel_names: channels, days,
                 }));
-            await runHandler("check_channel_contradictions", { topic, channels, days });
+            await runHandler("check_channel_contradictions", { topic, channels, days }, f.out);
         },
     },
     "entities": {
         tool: "find_entities",
         description: "Fuzzy search canonical entities by name/alias (people, orgs, places, subjects)",
-        specs: [{ name: "type", type: "string" }, FLAG_LIMIT, FLAG_JSON],
+        specs: [{ name: "type", type: "string", desc: "Entity type filter: person | organization | place | subject" }, FLAG_LIMIT, FLAG_JSON],
         run: async (args, json) => {
             const [query] = args.positionals;
             if (!query) {
@@ -398,7 +738,8 @@ const COMMANDS = {
     "entity-claims": {
         tool: "entity_claims",
         description: "Claims about a resolved canonical entity, ranked, with stance distribution",
-        specs: [{ name: "sort", type: "string", default: "spread" }, { name: "stance", type: "string" },
+        specs: [{ name: "sort", type: "string", default: "spread", desc: "Sort: spread | observations | recent" },
+            { name: "stance", type: "string", desc: "Filter by stance: assert | deny | speculate | attribute" },
             FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
         run: async (args, json) => {
             const [name] = args.positionals;
@@ -437,8 +778,9 @@ const COMMANDS = {
     "top-claims": {
         tool: "top_claims",
         description: "Leaderboard of the most widely-spread or most-contested claims",
-        specs: [{ name: "metric", type: "string", default: "spread" }, { name: "category", type: "string" },
-            { name: "min-obs", type: "number", default: 2 }, FLAG_DAYS, FLAG_LIMIT, FLAG_JSON],
+        specs: [{ name: "metric", type: "string", default: "spread", desc: "Ranking: spread (reach) | contested (assert vs deny balance)" },
+            { name: "category", type: "string", desc: "Optional topic-category filter" },
+            { name: "min-obs", type: "number", default: 2, desc: "Minimum observation count per claim" }, FLAG_DAYS, FLAG_LIMIT, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             const params = {
@@ -454,7 +796,8 @@ const COMMANDS = {
     claim: {
         tool: "get_claim",
         description: "Get full claim detail with observations and related claims",
-        specs: [{ name: "observations", type: "boolean" }, { name: "related", type: "boolean" }, FLAG_JSON],
+        specs: [{ name: "observations", type: "boolean", desc: "Include the full observation list" },
+            { name: "related", type: "boolean", desc: "Include semantically related claims" }, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id || !/^\d+$/.test(id)) {
@@ -481,9 +824,10 @@ const COMMANDS = {
         tool: "detect_trend",
         description: "Detect topic volume trends",
         specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_COUNTRY,
-            { name: "recent", type: "number", default: 7 },
-            { name: "baseline", type: "number", default: 30 },
-            { name: "min-similarity", type: "number" }, FLAG_JSON],
+            { name: "recent", type: "number", default: 7, desc: "Recent window in days" },
+            { name: "baseline", type: "number", default: 30, desc: "Baseline window in days" },
+            { name: "days", alias: "d", type: "number", desc: "Alias for --baseline" },
+            { name: "min-similarity", type: "number", desc: "Minimum similarity threshold" }, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -497,7 +841,8 @@ const COMMANDS = {
                 channel: trendChannel,
                 language: f.language || undefined,
                 country: f.country || undefined,
-                recent_days: Number(f.recent) || 7, baseline_days: Number(f.baseline) || 30,
+                recent_days: Number(f.recent) || 7,
+                baseline_days: Number(f.days) || Number(f.baseline) || 30,
                 min_similarity: Number(f["min-similarity"]) || undefined,
             };
             if (json)
@@ -512,7 +857,8 @@ const COMMANDS = {
         tool: "get_timeline",
         description: "Topic mention volume over time",
         specs: [FLAG_DAYS, FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE,
-            { name: "granularity", alias: "g", type: "string", default: "day" },
+            { name: "granularity", alias: "g", type: "string", default: "day", desc: "Bucket size: day | week" },
+            { name: "min-similarity", type: "string", desc: "Relevance threshold 0-1 (default 0.30, same as quote search)" },
             FLAG_START, FLAG_END, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
@@ -532,6 +878,7 @@ const COMMANDS = {
                 end_date: dr.end_date,
                 language: f.language || undefined,
                 granularity: f.granularity || "day",
+                min_similarity: f["min-similarity"] != null ? Number(f["min-similarity"]) : undefined,
             };
             if (json)
                 return printJson(await client.getTimeline(tlParams));
@@ -542,7 +889,7 @@ const COMMANDS = {
         tool: "find_speakers",
         description: "Speaker search, profile, or discourse",
         specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_CHANNEL,
-            { name: "segments", type: "boolean" }, FLAG_JSON],
+            { name: "segments", type: "boolean", desc: "List the speaker's recent segments (chronological)" }, FLAG_JSON],
         run: async (args, json) => {
             const [identity, topic] = args.positionals;
             if (!identity) {
@@ -615,7 +962,7 @@ const COMMANDS = {
     channel: {
         tool: "get_channel",
         description: "Channel profile or episode listing",
-        specs: [{ name: "episodes", type: "boolean" }, FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
+        specs: [{ name: "episodes", type: "boolean", desc: "List the channel's recent episodes instead of the profile" }, FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
@@ -650,7 +997,7 @@ const COMMANDS = {
     episode: {
         tool: "get_episode",
         description: "Episode details or transcript",
-        specs: [{ name: "transcript", type: "boolean" }, FLAG_JSON],
+        specs: [{ name: "transcript", type: "boolean", desc: "Include the full episode transcript" }, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
@@ -685,7 +1032,7 @@ const COMMANDS = {
     thread: {
         tool: "get_thread",
         description: "Conversation context around a quote",
-        specs: [{ name: "n", type: "number", default: 5 }, FLAG_JSON],
+        specs: [{ name: "n", type: "number", default: 5, desc: "Segments of context before and after the quote" }, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
@@ -703,8 +1050,8 @@ const COMMANDS = {
         tool: "analyze_topic",
         description: "AI-powered topic analysis",
         specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY,
-            { name: "workflow", alias: "w", type: "string", default: "simple_rag" },
-            FLAG_SKIP_CACHE, FLAG_JSON],
+            { name: "workflow", alias: "w", type: "string", default: "simple_rag", desc: "Workflow: simple_rag | speaker_focus | entity_network | narrative_timeline | hierarchical_summary | discourse_summary" },
+            FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [query] = args.positionals;
             if (!query) {
@@ -712,7 +1059,7 @@ const COMMANDS = {
                 process.exit(1);
             }
             const f = args.flags;
-            process.stderr.write("Analyzing... (this may take up to 60 seconds)\n");
+            process.stderr.write("Analyzing... (may take 1-3 minutes)\n");
             const channelArg = f.channel || undefined;
             const params = {
                 query, workflow: f.workflow,
@@ -725,13 +1072,13 @@ const COMMANDS = {
             };
             if (json)
                 return printJson(await client.analyze(params));
-            await runHandler("analyze_topic", params);
+            await runHandler("analyze_topic", params, f.out);
         },
     },
     frames: {
         tool: "compare_frames",
         description: "Compare left vs right media framing on a topic",
-        specs: [FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -739,7 +1086,7 @@ const COMMANDS = {
                 process.exit(1);
             }
             const f = args.flags;
-            process.stderr.write("Comparing left vs right framing... (this may take up to 60 seconds)\n");
+            process.stderr.write("Comparing left vs right framing... (may take 1-3 minutes)\n");
             const params = {
                 topic, days: Number(f.days) || 30,
                 language: f.language || undefined,
@@ -754,13 +1101,15 @@ const COMMANDS = {
                 ]);
                 return printJson({ left, right });
             }
-            await runHandler("compare_frames", params);
+            await runHandler("compare_frames", params, f.out);
         },
     },
     compare: {
         tool: "compare_speakers",
         description: "Compare speakers on a topic",
-        specs: [{ name: "speakers", type: "string" }, FLAG_SPEAKER, FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_JSON],
+        // FLAG_DAYS carries default:30, which silently overrode this command's
+        // intended 90d window — spread it with the right default.
+        specs: [{ name: "speakers", type: "string", desc: "2-5 comma-separated speaker names" }, FLAG_SPEAKER, { ...FLAG_DAYS, default: 90 }, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -774,7 +1123,7 @@ const COMMANDS = {
                 print("Error: --speakers requires 2-5 comma-separated names.");
                 process.exit(1);
             }
-            process.stderr.write("Comparing speakers... (this may take up to 60 seconds)\n");
+            process.stderr.write("Comparing speakers... (may take 1-3 minutes)\n");
             const params = {
                 topic, speakers, days: Number(f.days) || 90,
                 language: f.language || undefined,
@@ -787,37 +1136,101 @@ const COMMANDS = {
                     language: params.language, country: params.country,
                     days: params.days, skip_cache: params.skip_cache,
                 }));
-            await runHandler("compare_speakers", params);
+            await runHandler("compare_speakers", params, f.out);
         },
     },
     dossier: {
         tool: "build_dossier",
-        description: "Comprehensive speaker briefing on a topic",
-        specs: [FLAG_SPEAKER, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        description: "Comprehensive speaker briefing on a topic (single speaker, or batch via --speakers roster file)",
+        specs: [FLAG_SPEAKER,
+            { name: "speakers", type: "string", desc: "Roster file: one speaker name per line (# comments, blank lines ignored) — batch mode, requires --out <dir>" },
+            { name: "force", type: "boolean", desc: "Batch mode: rebuild dossiers whose output file already exists" },
+            { ...FLAG_DAYS, default: 180 }, FLAG_SKIP_CACHE,
+            { ...FLAG_OUT, desc: "Write output to a .md file; with --speakers: output directory (one .md per speaker + INDEX.md)" },
+            FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
                 print("Error: topic is required.");
                 process.exit(1);
             }
+            if (args.flags.speakers)
+                return runDossierBatch(topic, args, json);
             const speaker = args.flags.speaker;
             if (!speaker) {
-                print("Error: --speaker is required.");
+                print("Error: --speaker is required (or --speakers <file> for batch mode).");
                 process.exit(1);
             }
-            process.stderr.write("Building dossier... (this may take up to 60 seconds)\n");
+            process.stderr.write("Building dossier... (may take 1-3 minutes)\n");
             const params = {
                 topic, speaker: speaker, days: Number(args.flags.days) || 180, skip_cache: args.flags["skip-cache"],
             };
             if (json)
                 return printJson(await client.analyze({ query: topic, workflow: "speaker_dossier", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
-            await runHandler("build_dossier", params);
+            await runHandler("build_dossier", params, args.flags.out);
+        },
+    },
+    "compare-periods": {
+        tool: "compare_periods",
+        description: "How a speaker's positions on a topic changed between time periods",
+        specs: [FLAG_SPEAKER,
+            { name: "periods", type: "string", desc: "Comma-separated periods: 2024,2026 or 2024-01:2024-06,2026-01:2026-06" },
+            FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const speaker = f.speaker;
+            if (!speaker) {
+                print("Error: --speaker is required.");
+                process.exit(1);
+            }
+            const periods = (f.periods || "").split(",").map((s) => s.trim()).filter(Boolean);
+            if (periods.length < 2) {
+                print("Error: --periods requires 2+ comma-separated periods (e.g. 2024,2026).");
+                process.exit(1);
+            }
+            process.stderr.write("Comparing periods... (may take 1-3 minutes)\n");
+            const data = await client.analyze({
+                query: topic, workflow: "speaker_evolution", speaker_name: speaker,
+                periods, skip_cache: f["skip-cache"],
+            });
+            if (json)
+                return printJson(data);
+            if (data.error) {
+                print(`Error: ${data.error}`);
+                process.exit(1);
+            }
+            const lines = [`**Speaker evolution: ${speaker} on ${topic} (${periods.join(" vs ")})**\n`];
+            const sp = data.speaker;
+            for (const [label, p] of Object.entries(sp?.periods ?? {})) {
+                const parts = [`${p.segment_count ?? 0} on-topic segments`];
+                if (p.gated_out)
+                    parts.push(`${p.gated_out} weak matches excluded`);
+                if (p.date_range?.length === 2)
+                    parts.push(`evidence ${p.date_range[0]} → ${p.date_range[1]}`);
+                if (p.thin_evidence)
+                    parts.push("⚠ thin evidence");
+                lines.push(`- **${label}**: ${parts.join(" · ")}`);
+            }
+            lines.push("");
+            if (data.summary)
+                lines.push(data.summary);
+            const text = lines.join("\n");
+            const out = f.out;
+            if (out)
+                writeOut(out, text);
+            else
+                print(text);
         },
     },
     contradictions: {
         tool: "check_contradictions",
         description: "Find contradictory statements from a speaker",
-        specs: [FLAG_SPEAKER, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        specs: [FLAG_SPEAKER, { ...FLAG_DAYS, default: 365 }, FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -829,19 +1242,19 @@ const COMMANDS = {
                 print("Error: --speaker is required.");
                 process.exit(1);
             }
-            process.stderr.write("Checking contradictions...\n");
+            process.stderr.write("Checking contradictions... (may take 1-3 minutes)\n");
             const params = {
                 topic, speaker: speaker, days: Number(args.flags.days) || 365, skip_cache: args.flags["skip-cache"],
             };
             if (json)
                 return printJson(await client.analyze({ query: topic, workflow: "contradiction_check", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
-            await runHandler("check_contradictions", params);
+            await runHandler("check_contradictions", params, args.flags.out);
         },
     },
     briefing: {
         tool: "get_briefing",
         description: "AI discourse briefing",
-        specs: [FLAG_DAYS, { name: "max-topics", type: "number", default: 8 }, FLAG_JSON],
+        specs: [{ ...FLAG_DAYS, default: 3, desc: "days to cover (1-14)" }, { name: "max-topics", type: "number", default: 8, desc: "Max topics in the briefing" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             const params = { days: Number(f.days) || 3, max_topics: Number(f["max-topics"]) || 8 };
@@ -853,7 +1266,7 @@ const COMMANDS = {
     stats: {
         tool: "get_platform_stats",
         description: "Platform statistics",
-        specs: [FLAG_DAYS, { name: "projects", type: "boolean" }, FLAG_JSON],
+        specs: [FLAG_DAYS, { name: "projects", type: "boolean", desc: "Per-project stats instead of platform totals" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             if (f.projects) {
@@ -884,11 +1297,11 @@ const COMMANDS = {
     "top-speakers": {
         tool: "get_top_speakers",
         description: "Top speakers by appearances, talk time, or clips",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY,
-            { name: "ranking", alias: "r", type: "string", default: "appearances" }, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_PROJECT,
+            { name: "ranking", alias: "r", type: "string", default: "appearances", desc: "Rank by: appearances | talkative (talk time) | clipped" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
-            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, ranking: f.ranking, language: f.language || undefined, country: f.country || undefined };
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, ranking: f.ranking, language: f.language || undefined, country: f.country || undefined, project: f.project || undefined };
             if (json)
                 return printJson(await client.getTopSpeakers(params));
             await runHandler("get_top_speakers", params);
@@ -897,10 +1310,10 @@ const COMMANDS = {
     network: {
         tool: "get_speaker_network",
         description: "Speaker co-appearance network",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_PROJECT, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
-            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, language: f.language || "en" };
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, language: f.language || "en", project: f.project || undefined };
             if (json)
                 return printJson(await client.getSpeakerNetwork(params));
             await runHandler("get_speaker_network", params);
@@ -909,9 +1322,10 @@ const COMMANDS = {
     topics: {
         tool: "get_topics",
         description: "Trending topic clusters",
-        specs: [FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_LIMIT, FLAG_DAYS, { name: "query", alias: "q", type: "string" },
-            { name: "min-segments", type: "number", default: 50 },
-            { name: "start", type: "string" }, { name: "end", type: "string" }, FLAG_JSON],
+        specs: [FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_LIMIT, FLAG_DAYS,
+            { name: "query", alias: "q", type: "string", desc: "Semantic filter — only clusters relevant to this query" },
+            { name: "min-segments", type: "number", default: 50, desc: "Minimum segments per cluster" },
+            FLAG_START, FLAG_END, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             const dr = f.days ? daysRange(Number(f.days)) : undefined;
@@ -931,9 +1345,11 @@ const COMMANDS = {
         tool: "get_ad_analytics",
         description: "Ad intelligence",
         specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
-            { name: "advertisers", type: "boolean" }, { name: "trending", type: "boolean" },
+            { name: "advertisers", type: "boolean", desc: "List advertisers instead of the overview" },
+            { name: "trending", type: "boolean", desc: "Show growing/declining/new advertisers" },
             FLAG_CHANNEL,
-            { name: "category", type: "string" }, { name: "sort", type: "string", default: "episodes" },
+            { name: "category", type: "string", desc: "Advertiser category filter (e.g. Financial, Tech/VPN)" },
+            { name: "sort", type: "string", default: "episodes", desc: "Advertiser sort order" },
             FLAG_JSON],
         run: async (args, json) => {
             const [adId] = args.positionals;
@@ -984,8 +1400,10 @@ const COMMANDS = {
     bookmarks: {
         tool: "manage_bookmarks",
         description: "Manage bookmarks",
-        specs: [{ name: "type", type: "string" }, { name: "search", type: "string" },
-            FLAG_LIMIT, FLAG_OFFSET, { name: "note", type: "string" }, FLAG_JSON],
+        specs: [{ name: "type", type: "string", desc: "Filter by bookmark type: segment | episode | speaker | channel" },
+            { name: "search", type: "string", desc: "Filter bookmarks by search text" },
+            FLAG_LIMIT, FLAG_OFFSET,
+            { name: "note", type: "string", desc: "Note to attach when adding a bookmark" }, FLAG_JSON],
         run: async (args, json) => {
             const [sub, entityType, entityId] = args.positionals;
             const f = args.flags;
@@ -1107,7 +1525,7 @@ async function showHelp() {
             "",
         ];
         // Key info
-        lines.push(`  Key:      ${data.key_prefix ?? "?"}...`);
+        lines.push(`  Key:      ${data.key_prefix ?? "n/a"}...`);
         if (data.user_email)
             lines.push(`  Email:    ${data.user_email}`);
         lines.push(`  Access:   ${data.full_access ? "full" : "scoped"}`);
@@ -1127,16 +1545,42 @@ async function showHelp() {
                 tiers[tier].push({ name, desc: info.description, example: info.example });
             }
             const tierOrder = ["search", "explore", "analyze", "overview", "more"];
+            const shown = new Set();
             for (const tier of tierOrder) {
                 const cmds = tiers[tier];
                 if (!cmds?.length)
                     continue;
                 lines.push(`\u2500\u2500 ${tier} \u2500\u2500`);
                 for (const c of cmds) {
+                    shown.add(c.name);
+                    lines.push(`  ${c.name.padEnd(19)}${c.desc}`);
+                }
+                lines.push("");
+            }
+            // Any tier the backend guide doesn't know about
+            for (const [tier, cmds] of Object.entries(tiers)) {
+                if (tierOrder.includes(tier))
+                    continue;
+                lines.push(`\u2500\u2500 ${tier} \u2500\u2500`);
+                for (const c of cmds) {
+                    shown.add(c.name);
                     lines.push(`  ${c.name.padEnd(19)}${c.desc}`);
                 }
                 lines.push("");
             }
+            // Registered CLI commands the backend guide omits (e.g. timeline,
+            // top-claims) \u2014 a command absent from --help may as well not exist.
+            const missing = Object.keys(COMMANDS)
+                .filter((n) => n !== "quotes" && !shown.has(n))
+                .sort();
+            if (missing.length) {
+                lines.push("\u2500\u2500 also available \u2500\u2500");
+                for (const n of missing) {
+                    const pad = n.length >= 19 ? `${n}  ` : n.padEnd(19);
+                    lines.push(`  ${pad}${COMMANDS[n].description}`);
+                }
+                lines.push("");
+            }
             // Search tips
             const tips = data.guide.search_tips;
             if (tips?.length) {
@@ -1155,6 +1599,8 @@ async function showHelp() {
         lines.push("Flags:");
         lines.push("  --json                  Raw JSON output");
         lines.push("  --help, -h              Show this help");
+        lines.push("  s4 <command> --help     Flags for one command (flags vary by command)");
+        lines.push("  --days is capped at 365; use --start YYYY-MM-DD for older material");
         lines.push("");
         lines.push("MCP server:");
         lines.push("  s4 --mcp               Start MCP server for Claude Desktop / Cursor");
@@ -1169,17 +1615,39 @@ async function showHelp() {
         ].join("\n"));
     }
 }
+function showCommandHelp(name, cmd) {
+    const lines = [
+        `s4 ${name} — ${cmd.description}`,
+        "",
+        `Usage: s4 ${name} [args] [flags]`,
+        "",
+        "Flags:",
+    ];
+    for (const s of cmd.specs) {
+        const flag = `--${s.name}${s.alias ? `, -${s.alias}` : ""}`;
+        const def = s.default !== undefined ? ` (default: ${s.default})` : "";
+        lines.push(`  ${flag.padEnd(24)}${s.desc ?? ""}${def}`);
+    }
+    lines.push("");
+    lines.push("Run s4 --help for the full command list.");
+    print(lines.join("\n"));
+}
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 export async function main() {
     applyConfig();
     const argv = process.argv.slice(2);
-    // Help
-    if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+    // Global help — but `s4 <command> --help` gets that command's flags instead.
+    const wantsHelp = argv.includes("--help") || argv.includes("-h");
+    if (!argv.length || (wantsHelp && !COMMANDS[argv[0]])) {
         await showHelp();
         process.exit(0);
     }
+    if (wantsHelp) {
+        showCommandHelp(argv[0], COMMANDS[argv[0]]);
+        process.exit(0);
+    }
     // MCP mode
     if (argv[0] === "mcp" || argv.includes("--mcp")) {
         await import("./index.js");
@@ -1211,14 +1679,31 @@ export async function main() {
     // Parse args
     const args = parseArgs(rest, cmd.specs);
     const json = args.flags.json;
+    // Narrate pipeline steps on stderr while analytical commands stream.
+    let progress = null;
+    if (PROGRESS_COMMANDS.has(command)) {
+        progress = createProgress();
+        activeProgress = progress;
+        client.setAnalysisProgressListener((e) => {
+            // "progress" fires at step start (verbose mode); "result" at step end —
+            // either way the named step is the latest thing the pipeline touched.
+            if (e.step && (e.type === "progress" || e.type === "result"))
+                progress.update(e.step);
+        });
+    }
     try {
         await cmd.run(args, json);
     }
     catch (err) {
+        progress?.finish();
         const msg = err instanceof Error ? err.message : String(err);
         process.stderr.write(`Error: ${msg}\n`);
         process.exit(1);
     }
+    finally {
+        progress?.finish();
+        client.setAnalysisProgressListener(null);
+    }
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);