@signal4/s4 2.6.0 → 2.7.0

package/dist/cli.js

@@ -1,105 +1,57 @@
 /** Signal4 CLI — terminal interface sharing handlers with the MCP server. */
 import { applyConfig } from "./config.js";
 import { HANDLERS } from "./handlers/registry.js";
+import { descriptionTag, estimate, startNotice, REPORT_ELAPSED_OVER_S } from "./speed.js";
 import * as client from "./client.js";
 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";
+import { parseArgs as parseArgsRaw, UsageError, didYouMean } from "./cli_args.js";
+import { setSurface } from "./surface.js";
+/** Parse or exit 1 with the usage error on stderr. */
 function parseArgs(argv, specs) {
-    const flags = {};
-    const positionals = [];
-    // Apply defaults. Flags without a declared default stay undefined —
-    // pre-filling numbers with 0 turns optional filters into active ones
-    // (political-lean-min=0 + political-lean-max=0 matched zero claims).
-    for (const s of specs) {
-        if (s.default !== undefined)
-            flags[s.name] = s.default;
-        else if (s.type === "boolean")
-            flags[s.name] = false;
-    }
-    // Build lookup: --name and -alias -> spec
-    const lookup = new Map();
-    for (const s of specs) {
-        lookup.set(`--${s.name}`, s);
-        if (s.alias)
-            lookup.set(`-${s.alias}`, s);
-    }
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        const spec = lookup.get(arg);
-        if (spec) {
-            if (spec.type === "boolean") {
-                flags[spec.name] = true;
-            }
-            else {
-                const val = argv[++i];
-                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 !== "-") {
-            // 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);
-        }
+    try {
+        return parseArgsRaw(argv, specs);
     }
-    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`);
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`Error: ${err.message}\n`);
             process.exit(1);
         }
+        throw err;
     }
-    return { positionals, flags };
 }
 // ---------------------------------------------------------------------------
 // Shared flag specs
 // ---------------------------------------------------------------------------
-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_DAYS = { name: "days", alias: "d", type: "number", default: 30, desc: "Time window in days (report commands cap at 365; search/claims/timeline do not)" };
+const FLAG_LIMIT = { name: "limit", alias: ["n", "k"], type: "number", default: 20, desc: "Number of results (-n, -k)" };
+const FLAG_OFFSET = { name: "offset", type: "number", default: 0, desc: "Skip this many results (pagination)" };
 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_LANGUAGE = { name: "language", type: "string", desc: "Filter by language code (en, fr, ...)" };
 const FLAG_COUNTRY = { name: "country", type: "string", desc: "Filter by channel country code" };
+const FLAG_COLLECTION = { name: "collection", long: ["project"], type: "string", desc: "Restrict to one collection (see: s4 collections). Default: whole corpus" };
 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_START = { name: "start", long: ["since"], type: "string", desc: "Start date: YYYY, YYYY-MM or YYYY-MM-DD (overrides --days)" };
+const FLAG_END = { name: "end", long: ["until"], type: "string", desc: "End date: YYYY, YYYY-MM or YYYY-MM-DD (default today)" };
+const FLAG_KEYWORD = { name: "keyword", type: "string", desc: "Exact phrase 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_OUT = { name: "out", alias: "o", long: ["output"], 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" };
+const GRANULARITIES = ["day", "week", "month", "quarter", "year"];
+const COUNT_GROUPS = ["none", ...GRANULARITIES, "channel", "episode", "language", "country", "platform", "collection", "lean"];
+/** --start/--end as tool params (already normalized to YYYY-MM-DD by parseArgs); absent when not given. */
+function dateFlags(f) {
+    const out = {};
+    if (f.start)
+        out.start_date = f.start;
+    if (f.end)
+        out.end_date = f.end;
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Progress reporting for long-running analysis commands
 // ---------------------------------------------------------------------------
@@ -210,11 +162,15 @@ function parseSegmentId(raw) {
     // 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, seg:<number>, or seg_<number>).`);
+        printErr(`Error: invalid segment ID "${raw}" (expected a number, seg:<number>, or seg_<number>).`);
         process.exit(1);
     }
     return id;
 }
+function printErr(text) {
+    activeProgress?.finish();
+    process.stderr.write(text + "\n");
+}
 function print(text) {
     activeProgress?.finish();
     process.stdout.write(text + "\n");
@@ -238,13 +194,25 @@ function toCsv(rows, columns) {
 function printJson(data) {
     print(JSON.stringify(data, null, 2));
 }
+/** The parsed --collection for the running command; injected into every handler call. */
+let activeCollection;
 async function runHandler(tool, params, out) {
     const handler = HANDLERS[tool];
     if (!handler) {
-        print(`Error: handler "${tool}" not found.`);
+        printErr(`Error: handler "${tool}" not found.`);
         process.exit(1);
     }
+    if (params.collection === undefined && activeCollection)
+        params = { ...params, collection: activeCollection };
+    // Slow calls say how long to expect before they start; stderr, so stdout stays the answer.
+    const expected = estimate(tool, params);
+    if (expected.tier === "slow")
+        process.stderr.write(`${startNotice(expected)}\n`);
+    const started = Date.now();
     const result = await handler(params);
+    const took = (Date.now() - started) / 1000;
+    if (took > REPORT_ELAPSED_OVER_S)
+        process.stderr.write(`Took ${took.toFixed(1)}s.\n`);
     if (result.isError) {
         process.stderr.write((result.content[0]?.text ?? "Unknown error") + "\n");
         process.exit(1);
@@ -255,6 +223,41 @@ async function runHandler(tool, params, out) {
     else
         print(text);
 }
+// A `--channel` name that doesn't resolve to a real channel must fail loudly
+// in keyword mode, not fall through as an unfiltered corpus-wide query
+// (signal4#85). Keyword-mode search silently drops channel_names server-side
+// (a server-side defect, out of scope here) so an unresolvable name there
+// would otherwise read as a channel-scoped count that is actually
+// corpus-wide. Semantic mode is NOT gated: the server already returns an
+// empty result set for an unknown channel there, which is the correct UX —
+// adding a second, client-side source of truth on that path risks disagreeing
+// with the server and regressing it.
+//
+// Resolved against /entities/channels/by-name — the one client-reachable
+// place this can be caught. Multiple names resolve concurrently. A non-404
+// failure (network blip, 5xx, timeout) fails OPEN: warn on stderr and let the
+// search proceed rather than blocking a query that might otherwise succeed.
+async function assertChannelsExistForKeywordMode(channelArg, mode) {
+    if (!channelArg || mode !== "keyword")
+        return;
+    const names = channelArg.split(",").map((s) => s.trim()).filter(Boolean);
+    await Promise.all(names.map(async (name) => {
+        try {
+            await client.getChannelByName(name);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/^HTTP 404\b/.test(msg)) {
+                process.stderr.write(`Error: channel "${name}" not found. This checks the channels registry ` +
+                    `(display_name) only — a name that exists only as a content-level ` +
+                    `channel_name variant may still be valid; verify against the exact ` +
+                    `registry name (s4 channel "${name}" or s4 top-channels).\n`);
+                process.exit(1);
+            }
+            process.stderr.write(`Warning: could not verify channel "${name}" exists (${msg}) — proceeding without the check.\n`);
+        }
+    }));
+}
 // ---------------------------------------------------------------------------
 // Batch dossiers (surrogate-roster sweeps): s4 dossier "<topic>" --speakers file.txt --out dir/
 // ---------------------------------------------------------------------------
@@ -408,21 +411,22 @@ 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,
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_MODE, { ...FLAG_LIMIT, default: 10 }, FLAG_OFFSET, FLAG_LANGUAGE, FLAG_COUNTRY,
             { 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", desc: "Speaker identity ID (from s4 speaker)" }, FLAG_OUT,
-            FLAG_START, FLAG_END,
+            FLAG_START, FLAG_END, FLAG_COLLECTION,
             FLAG_JSON],
         run: async (args, json) => {
             const [positionalTopic] = args.positionals;
             const f = args.flags;
             const keyword = f.keyword || undefined;
-            const topic = positionalTopic || keyword || undefined;
+            const topic = keyword || positionalTopic || undefined;
             const mode = keyword ? "keyword" : f.mode;
+            await assertChannelsExistForKeywordMode(f.channel || undefined, mode);
             const days = Number(f.days) || 30;
             const fullHistory = f["full-history"];
             // Full history means FULL history — only pass dates given explicitly,
@@ -441,6 +445,7 @@ const COMMANDS = {
                 count_only: f.count, sort: f.sort,
                 full_history: fullHistory,
                 min_similarity: f["min-similarity"] !== undefined ? Number(f["min-similarity"]) : undefined,
+                project: f.collection || undefined,
             };
             const out = f.out;
             if (json || (out && out.endsWith(".csv"))) {
@@ -455,6 +460,7 @@ const COMMANDS = {
                     full_history: fullHistory || undefined,
                     count_only: params.count_only || undefined,
                     min_similarity: params.min_similarity,
+                    project: params.project,
                 });
                 if (out && out.endsWith(".csv")) {
                     const rows = (data.quotes ?? []).map((q) => ({
@@ -484,7 +490,7 @@ const COMMANDS = {
     claims: {
         tool: "search_claims",
         description: "Search extracted claims",
-        specs: [{ name: "entity", alias: "e", type: "string", desc: "Filter by entity name (person, org, place, subject)" }, FLAG_SPEAKER, FLAG_CHANNEL,
+        specs: [{ name: "entity", 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,
@@ -494,12 +500,12 @@ const COMMANDS = {
             { 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],
+            FLAG_DAYS, { ...FLAG_LIMIT, default: 10 }, FLAG_OFFSET, FLAG_START, FLAG_END, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [positionalTopic] = args.positionals;
             const f = args.flags;
             const keyword = f.keyword || undefined;
-            const topic = positionalTopic || keyword || undefined;
+            const topic = keyword || positionalTopic || 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) } : undefined;
@@ -520,6 +526,7 @@ const COMMANDS = {
                 days, mode,
                 sort: f.sort, min_observations: Number(f["min-obs"]) || 1,
                 limit: Number(f.limit), offset: Number(f.offset),
+                project: f.collection || undefined,
                 ...dr,
             };
             const claimsDr = dr ?? daysRange(days);
@@ -535,6 +542,7 @@ const COMMANDS = {
                     mode: params.mode, sort: params.sort,
                     min_observations: params.min_observations > 1 ? params.min_observations : undefined,
                     limit: params.limit, offset: params.offset,
+                    project: params.project,
                 }));
             await runHandler("search_claims", params, f.out);
         },
@@ -542,12 +550,12 @@ const COMMANDS = {
     "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,
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_DAYS, FLAG_START, FLAG_END, FLAG_COLLECTION,
             { 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) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -559,11 +567,13 @@ const COMMANDS = {
                 language: f.language || undefined,
                 days: Number(f.days) || undefined,
                 min_observations: Number(f["min-obs"]) || undefined,
+                ...dateFlags(f),
             };
             if (json)
                 return printJson(await client.analyzeTopicClaims({
                     topic, speaker_name: params.speaker, channel_names: params.channels,
                     language: params.language, days: params.days, min_observations: params.min_observations,
+                    project: f.collection || undefined, ...dateFlags(f),
                 }));
             await runHandler("analyze_claims", params);
         },
@@ -573,11 +583,12 @@ const COMMANDS = {
         description: "Detect whether a topic is surging/fading by claim volume (fast)",
         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],
+            { name: "min-similarity", type: "number", desc: "Minimum similarity threshold (0.0-1.0)" },
+            FLAG_LANGUAGE, FLAG_COLLECTION, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -586,32 +597,34 @@ const COMMANDS = {
                 recent_days: Number(f["recent-days"]) || undefined,
                 baseline_days: Number(f["baseline-days"]) || undefined,
                 min_similarity: f["min-similarity"] !== undefined ? Number(f["min-similarity"]) : undefined,
+                language: f.language || undefined,
             };
             if (json)
-                return printJson(await client.detectTrendClaims(params));
+                return printJson(await client.detectTrendClaims({ ...params, project: f.collection || undefined }));
             await runHandler("trend_claims", params);
         },
     },
     "contradict-claims": {
         tool: "contradict_claims",
         description: "Find a speaker's contradictory claims on a topic via stance analysis (fast)",
-        specs: [FLAG_SPEAKER, { ...FLAG_DAYS, default: 365 }, FLAG_OUT, FLAG_JSON],
+        specs: [FLAG_SPEAKER, { ...FLAG_DAYS, default: 365 }, FLAG_START, FLAG_END, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const speaker = f.speaker || undefined;
             if (!speaker) {
-                print("Error: --speaker is required.");
+                printErr("Error: --speaker is required.");
                 process.exit(1);
             }
-            const params = { topic, speaker, days: Number(f.days) || undefined };
+            const params = { topic, speaker, days: Number(f.days) || undefined, ...dateFlags(f) };
             if (json)
                 return printJson(await client.checkContradictionsClaims({
                     topic, speaker_name: speaker, days: params.days,
+                    project: f.collection || undefined, ...dateFlags(f),
                 }));
             await runHandler("contradict_claims", params, f.out);
         },
@@ -619,24 +632,26 @@ const COMMANDS = {
     "compare-claims": {
         tool: "compare_claims",
         description: "Compare 2-5 speakers' claims on a topic — side-by-side stance (fast)",
-        specs: [{ name: "speakers", type: "string", desc: "2-5 comma-separated speaker names" }, FLAG_SPEAKER, { ...FLAG_DAYS, default: 90 }, FLAG_OUT, FLAG_JSON],
+        specs: [{ name: "speakers", type: "string", desc: "2-5 comma-separated speaker names" }, FLAG_SPEAKER, { ...FLAG_DAYS, default: 90 },
+            FLAG_START, FLAG_END, FLAG_LANGUAGE, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const speakersStr = f.speakers || f.speaker || "";
             const speakers = speakersStr.split(",").map((s) => s.trim()).filter(Boolean);
             if (speakers.length < 2) {
-                print("Error: --speakers requires 2-5 comma-separated names.");
+                printErr("Error: --speakers requires 2-5 comma-separated names.");
                 process.exit(1);
             }
-            const params = { topic, speakers, days: Number(f.days) || undefined };
+            const params = { topic, speakers, days: Number(f.days) || undefined, language: f.language || undefined, ...dateFlags(f) };
             if (json)
                 return printJson(await client.compareSpeakersClaims({
-                    topic, speaker_names: speakers, days: params.days,
+                    topic, speaker_names: speakers, days: params.days, language: params.language,
+                    project: f.collection || undefined, ...dateFlags(f),
                 }));
             await runHandler("compare_claims", params, f.out);
         },
@@ -644,24 +659,24 @@ const COMMANDS = {
     "channel-dossier": {
         tool: "channel_dossier",
         description: "Claims dossier of what a channel (show) platformed on a topic (fast)",
-        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 180 }, FLAG_OUT, FLAG_JSON],
+        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 180 }, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const channel = f.channel || undefined;
             if (!channel) {
-                print("Error: --channel is required.");
+                printErr("Error: --channel is required.");
                 process.exit(1);
             }
             const channels = channel.split(",").map((s) => s.trim()).filter(Boolean);
             const days = Number(f.days) || undefined;
             if (json)
                 return printJson(await client.buildChannelDossier({
-                    topic, channel_names: channels, days,
+                    topic, channel_names: channels, days, project: f.collection || undefined,
                 }));
             await runHandler("channel_dossier", { topic, channels, days }, f.out);
         },
@@ -669,24 +684,24 @@ const COMMANDS = {
     "compare-channels": {
         tool: "compare_channels",
         description: "Compare 2-5 channels' claims on a topic — stance + speaker overlap (fast)",
-        specs: [{ name: "channels", type: "string", desc: "2-5 comma-separated channel names" }, FLAG_CHANNEL, { ...FLAG_DAYS, default: 90 }, FLAG_OUT, FLAG_JSON],
+        specs: [{ name: "channels", type: "string", desc: "2-5 comma-separated channel names" }, FLAG_CHANNEL, { ...FLAG_DAYS, default: 90 }, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const channelsStr = f.channels || f.channel || "";
             const channels = channelsStr.split(",").map((s) => s.trim()).filter(Boolean);
             if (channels.length < 2) {
-                print("Error: --channels requires 2-5 comma-separated names.");
+                printErr("Error: --channels requires 2-5 comma-separated names.");
                 process.exit(1);
             }
             const days = Number(f.days) || undefined;
             if (json)
                 return printJson(await client.compareChannelsClaims({
-                    topic, channel_names: channels, days,
+                    topic, channel_names: channels, days, project: f.collection || undefined,
                 }));
             await runHandler("compare_channels", { topic, channels, days }, f.out);
         },
@@ -694,24 +709,24 @@ const COMMANDS = {
     "channel-contradictions": {
         tool: "check_channel_contradictions",
         description: "Contradictory claims a channel platforms on a topic (fast)",
-        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 365 }, FLAG_OUT, FLAG_JSON],
+        specs: [FLAG_CHANNEL, { ...FLAG_DAYS, default: 365 }, FLAG_COLLECTION, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const channel = f.channel || undefined;
             if (!channel) {
-                print("Error: --channel is required.");
+                printErr("Error: --channel is required.");
                 process.exit(1);
             }
             const channels = channel.split(",").map((s) => s.trim()).filter(Boolean);
             const days = Number(f.days) || undefined;
             if (json)
                 return printJson(await client.checkChannelContradictionsClaims({
-                    topic, channel_names: channels, days,
+                    topic, channel_names: channels, days, project: f.collection || undefined,
                 }));
             await runHandler("check_channel_contradictions", { topic, channels, days }, f.out);
         },
@@ -723,7 +738,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [query] = args.positionals;
             if (!query) {
-                print("Error: query is required.");
+                printErr("Error: query is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -739,11 +754,11 @@ const COMMANDS = {
         description: "Claims about a resolved canonical entity, ranked, with stance distribution",
         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],
+            FLAG_LIMIT, FLAG_OFFSET, FLAG_COLLECTION, FLAG_JSON],
         run: async (args, json) => {
             const [name] = args.positionals;
             if (!name) {
-                print("Error: entity name is required.");
+                printErr("Error: entity name is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -754,6 +769,7 @@ const COMMANDS = {
             if (json)
                 return printJson(await client.getEntityClaims({
                     name, sort: params.sort, stance: params.stance, limit: params.limit, offset: params.offset,
+                    project: f.collection || undefined,
                 }));
             await runHandler("entity_claims", params);
         },
@@ -761,16 +777,16 @@ const COMMANDS = {
     "claim-graph": {
         tool: "claim_graph",
         description: "A claim's parent, children, and sibling (variant) claims",
-        specs: [FLAG_JSON],
+        specs: [FLAG_COLLECTION, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id || !/^\d+$/.test(id)) {
-                print("Error: claim_id (numeric) required.");
+                printErr("Error: claim_id (numeric) required.");
                 process.exit(1);
             }
             const claimId = Number(id);
             if (json)
-                return printJson(await client.getClaimGraph(claimId));
+                return printJson(await client.getClaimGraph(claimId, args.flags.collection || undefined));
             await runHandler("claim_graph", { claim_id: claimId });
         },
     },
@@ -779,16 +795,18 @@ const COMMANDS = {
         description: "Leaderboard of the most widely-spread or most-contested claims",
         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],
+            { name: "min-obs", type: "number", default: 2, desc: "Minimum observation count per claim" }, FLAG_DAYS, FLAG_START, FLAG_END,
+            FLAG_LANGUAGE, FLAG_COLLECTION, FLAG_LIMIT, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             const params = {
                 metric: f.metric || undefined, category: f.category || undefined,
                 days: Number(f.days) || undefined, min_observations: Number(f["min-obs"]) || undefined,
-                limit: Number(f.limit) || undefined,
+                limit: Number(f.limit) || undefined, language: f.language || undefined,
+                ...dateFlags(f),
             };
             if (json)
-                return printJson(await client.getTopClaims(params));
+                return printJson(await client.getTopClaims({ ...params, project: f.collection || undefined }));
             await runHandler("top_claims", params);
         },
     },
@@ -800,7 +818,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id || !/^\d+$/.test(id)) {
-                print("Error: claim_id (numeric) required.");
+                printErr("Error: claim_id (numeric) required.");
                 process.exit(1);
             }
             const claimId = Number(id);
@@ -822,15 +840,17 @@ const COMMANDS = {
     trend: {
         tool: "detect_trend",
         description: "Detect topic volume trends",
-        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_COUNTRY,
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION,
             { 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" },
+            { ...FLAG_START, desc: "Baseline start: YYYY, YYYY-MM or YYYY-MM-DD (pins the baseline window)" },
+            { ...FLAG_END, desc: "Baseline end, inclusive (default today); recent = its last --recent days" },
             { name: "min-similarity", type: "number", desc: "Minimum similarity threshold" }, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -843,6 +863,8 @@ const COMMANDS = {
                 recent_days: Number(f.recent) || 7,
                 baseline_days: Number(f.days) || Number(f.baseline) || 30,
                 min_similarity: Number(f["min-similarity"]) || undefined,
+                project: f.collection || undefined,
+                ...dateFlags(f),
             };
             if (json)
                 return printJson(await client.detectTrend({
@@ -856,18 +878,28 @@ 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", desc: "Bucket size: day | week" },
+            { name: "granularity", alias: "g", type: "string", default: "day", desc: "Bucket size: day | week | month | quarter | year (calendar buckets)" },
             { name: "min-similarity", type: "string", desc: "Relevance threshold 0-1 (default 0.30, same as quote search)" },
-            FLAG_START, FLAG_END, FLAG_JSON],
+            FLAG_START, FLAG_END, FLAG_COLLECTION, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
+            if (!GRANULARITIES.includes(f.granularity)) {
+                printErr(`Error: --granularity must be one of ${GRANULARITIES.join(", ")} (got "${f.granularity}").`);
+                process.exit(1);
+            }
             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);
+            if (!f.start && f.end) {
+                // --end alone: the --days days ending there, not ending today.
+                const end = Date.parse(f.end);
+                dr.start_date = new Date(end - days * 86400000).toISOString().slice(0, 10);
+                dr.end_date = f.end;
+            }
             const tlChannel = f.channel || undefined;
             const tlParams = {
                 topic,
@@ -878,10 +910,62 @@ const COMMANDS = {
                 language: f.language || undefined,
                 granularity: f.granularity || "day",
                 min_similarity: f["min-similarity"] != null ? Number(f["min-similarity"]) : undefined,
+                project: f.collection || undefined,
             };
             if (json)
                 return printJson(await client.getTimeline(tlParams));
-            await runHandler("get_timeline", { ...tlParams, days, channel: tlChannel });
+            await runHandler("get_timeline", {
+                ...tlParams, days, channel: tlChannel,
+                // Explicit dates only, so the footer states them instead of "last N days".
+                start_date: f.start || f.end ? dr.start_date : undefined,
+                end_date: f.start || f.end ? dr.end_date : undefined,
+            });
+        },
+    },
+    count: {
+        tool: "count_mentions",
+        description: "Count segments, episodes and channels for a topic — by month, channel, episode, ...",
+        specs: [FLAG_DAYS, FLAG_START, FLAG_END, FLAG_COLLECTION, FLAG_SPEAKER, FLAG_CHANNEL,
+            { ...FLAG_LANGUAGE, desc: "Language code(s), comma-separated (default: every language)" },
+            FLAG_COUNTRY,
+            { name: "mode", alias: "m", type: "string", default: "semantic", desc: "semantic (estimate) | keyword (exact phrase, exact count)" },
+            { name: "by", long: ["group-by"], alias: "g", type: "string", default: "none", desc: `Break down by: ${COUNT_GROUPS.join(" | ")}` },
+            { name: "vs", type: "string", desc: "More topics to count side by side, comma-separated (up to 5 in all)" },
+            { name: "order", type: "string", default: "segments", desc: "Episode breakdown order: segments | date" },
+            { name: "min-similarity", type: "number", desc: "Semantic threshold (default 0.35)" },
+            { ...FLAG_LIMIT, desc: "Rows for channel/episode/... breakdowns (-n, -k; max 1000)" }, FLAG_OFFSET, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const topic = args.positionals.join(" ").trim() || undefined;
+            const vs = f.vs?.split(",").map((s) => s.trim()).filter(Boolean);
+            if (!COUNT_GROUPS.includes(f.by)) {
+                printErr(`Error: --by must be one of ${COUNT_GROUPS.join(", ")} (got "${f.by}").`);
+                process.exit(1);
+            }
+            if (f.mode !== "semantic" && f.mode !== "keyword") {
+                printErr(`Error: --mode must be semantic or keyword for count (got "${f.mode}").`);
+                process.exit(1);
+            }
+            const params = {
+                topic,
+                topics: vs?.length ? [...(topic ? [topic] : []), ...vs] : undefined,
+                mode: f.mode,
+                group_by: f.by,
+                days: f.start || f.end ? undefined : Number(f.days) || 30,
+                ...dateFlags(f),
+                collection: f.collection || undefined,
+                speaker: f.speaker || undefined,
+                channel: f.channel || undefined,
+                language: f.language || undefined,
+                country: f.country || undefined,
+                min_similarity: f["min-similarity"] != null ? Number(f["min-similarity"]) : undefined,
+                limit: Number(f.limit) || 20,
+                offset: Number(f.offset) || 0,
+                order: f.order,
+            };
+            if (json)
+                params.response_format = "json";
+            await runHandler("count_mentions", params);
         },
     },
     speaker: {
@@ -892,7 +976,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [identity, topic] = args.positionals;
             if (!identity) {
-                print("Error: speaker name or ID required.");
+                printErr("Error: speaker name or ID required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -965,7 +1049,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
-                print("Error: channel ID or name required.");
+                printErr("Error: channel ID or name required.");
                 process.exit(1);
             }
             const isId = /^\d+$/.test(id);
@@ -1000,7 +1084,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
-                print("Error: content ID required.");
+                printErr("Error: content ID required.");
                 process.exit(1);
             }
             if (json) {
@@ -1019,7 +1103,7 @@ const COMMANDS = {
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
-                print("Error: segment ID required.");
+                printErr("Error: segment ID required.");
                 process.exit(1);
             }
             const segId = parseSegmentId(id);
@@ -1031,15 +1115,15 @@ const COMMANDS = {
     thread: {
         tool: "get_thread",
         description: "Conversation context around a quote",
-        specs: [{ name: "n", type: "number", default: 5, desc: "Segments of context before and after the quote" }, FLAG_JSON],
+        specs: [{ name: "context", alias: "C", long: ["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) {
-                print("Error: segment ID required.");
+                printErr("Error: segment ID required.");
                 process.exit(1);
             }
             const segId = parseSegmentId(id);
-            const n = Number(args.flags.n) || 5;
+            const n = Number(args.flags.context) || 5;
             if (json)
                 return printJson(await client.getSegmentThread(segId, n));
             await runHandler("get_thread", { segment_id: segId, n });
@@ -1048,13 +1132,13 @@ const COMMANDS = {
     analyze: {
         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", desc: "Workflow: simple_rag | speaker_focus | entity_network | narrative_timeline | hierarchical_summary | discourse_summary" },
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION,
+            { name: "workflow", 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) {
-                print("Error: query is required.");
+                printErr("Error: query is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -1068,6 +1152,7 @@ const COMMANDS = {
                 country: f.country || undefined,
                 days: Number(f.days) || undefined,
                 skip_cache: f["skip-cache"],
+                project: f.collection || undefined,
             };
             if (json)
                 return printJson(await client.analyze(params));
@@ -1077,11 +1162,11 @@ const COMMANDS = {
     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_OUT, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION, FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -1093,7 +1178,7 @@ const COMMANDS = {
                 skip_cache: f["skip-cache"],
             };
             if (json) {
-                const shared = { query: topic, workflow: "deep_analysis", days: params.days, language: params.language, country: params.country, skip_cache: params.skip_cache };
+                const shared = { query: topic, workflow: "deep_analysis", days: params.days, language: params.language, country: params.country, skip_cache: params.skip_cache, project: f.collection || undefined };
                 const [left, right] = await Promise.all([
                     client.analyze({ ...shared, political_lean_min: 0.0, political_lean_max: 0.35 }),
                     client.analyze({ ...shared, political_lean_min: 0.65, political_lean_max: 1.0 }),
@@ -1108,18 +1193,18 @@ const COMMANDS = {
         description: "Compare speakers on a topic",
         // 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],
+        specs: [{ name: "speakers", type: "string", desc: "2-5 comma-separated speaker names" }, FLAG_SPEAKER, { ...FLAG_DAYS, default: 90 }, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION, FLAG_SKIP_CACHE, FLAG_OUT, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const speakersStr = f.speakers || f.speaker || "";
             const speakers = speakersStr.split(",").map((s) => s.trim()).filter(Boolean);
             if (speakers.length < 2) {
-                print("Error: --speakers requires 2-5 comma-separated names.");
+                printErr("Error: --speakers requires 2-5 comma-separated names.");
                 process.exit(1);
             }
             process.stderr.write("Comparing speakers... (may take 1-3 minutes)\n");
@@ -1133,7 +1218,7 @@ const COMMANDS = {
                 return printJson(await client.analyze({
                     query: topic, workflow: "speaker_compare", speaker_names: speakers,
                     language: params.language, country: params.country,
-                    days: params.days, skip_cache: params.skip_cache,
+                    days: params.days, skip_cache: params.skip_cache, project: f.collection || undefined,
                 }));
             await runHandler("compare_speakers", params, f.out);
         },
@@ -1150,14 +1235,14 @@ const COMMANDS = {
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("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 (or --speakers <file> for batch mode).");
+                printErr("Error: --speaker is required (or --speakers <file> for batch mode).");
                 process.exit(1);
             }
             process.stderr.write("Building dossier... (may take 1-3 minutes)\n");
@@ -1178,18 +1263,18 @@ const COMMANDS = {
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const f = args.flags;
             const speaker = f.speaker;
             if (!speaker) {
-                print("Error: --speaker is required.");
+                printErr("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).");
+                printErr("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");
@@ -1200,7 +1285,7 @@ const COMMANDS = {
             if (json)
                 return printJson(data);
             if (data.error) {
-                print(`Error: ${data.error}`);
+                printErr(`Error: ${data.error}`);
                 process.exit(1);
             }
             const lines = [`**Speaker evolution: ${speaker} on ${topic} (${periods.join(" vs ")})**\n`];
@@ -1233,12 +1318,12 @@ const COMMANDS = {
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
-                print("Error: topic is required.");
+                printErr("Error: topic is required.");
                 process.exit(1);
             }
             const speaker = args.flags.speaker;
             if (!speaker) {
-                print("Error: --speaker is required.");
+                printErr("Error: --speaker is required.");
                 process.exit(1);
             }
             process.stderr.write("Checking contradictions... (may take 1-3 minutes)\n");
@@ -1253,22 +1338,32 @@ const COMMANDS = {
     briefing: {
         tool: "get_briefing",
         description: "AI discourse briefing",
-        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],
+        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_COLLECTION, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
             const params = { days: Number(f.days) || 3, max_topics: Number(f["max-topics"]) || 8 };
             if (json)
-                return printJson(await client.getDiscourseSummary(params));
+                return printJson(await client.getDiscourseSummary({ ...params, project: f.collection || undefined }));
             await runHandler("get_briefing", params);
         },
     },
+    collections: {
+        tool: "list_collections",
+        description: "List searchable collections (use with --collection)",
+        specs: [FLAG_JSON],
+        run: async (_args, json) => {
+            if (json)
+                return printJson(await client.getCollections());
+            await runHandler("list_collections", {});
+        },
+    },
     stats: {
         tool: "get_platform_stats",
         description: "Platform statistics",
-        specs: [FLAG_DAYS, { name: "projects", type: "boolean", desc: "Per-project stats instead of platform totals" }, FLAG_JSON],
+        specs: [FLAG_DAYS, { name: "collections", long: ["projects"], type: "boolean", desc: "Per-collection stats instead of platform totals" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
-            if (f.projects) {
+            if (f.collections) {
                 if (json)
                     return printJson(await client.getProjectStats());
                 await runHandler("get_project_stats", {});
@@ -1284,23 +1379,23 @@ const COMMANDS = {
     "top-channels": {
         tool: "get_top_channels",
         description: "Top channels by episode count",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_START, FLAG_END, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION, 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 || undefined, country: f.country || undefined };
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, language: f.language || undefined, country: f.country || undefined, ...dateFlags(f) };
             if (json)
-                return printJson(await client.getTopChannels(params));
+                return printJson(await client.getTopChannels({ ...params, project: f.collection || undefined }));
             await runHandler("get_top_channels", params);
         },
     },
     "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", desc: "Rank by: appearances | talkative (talk time) | clipped" }, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_START, FLAG_END, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION,
+            { name: "ranking", 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.collection || undefined, ...dateFlags(f) };
             if (json)
                 return printJson(await client.getTopSpeakers(params));
             await runHandler("get_top_speakers", params);
@@ -1309,10 +1404,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_COLLECTION, 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.collection || undefined };
             if (json)
                 return printJson(await client.getSpeakerNetwork(params));
             await runHandler("get_speaker_network", params);
@@ -1322,7 +1417,7 @@ const COMMANDS = {
         tool: "get_topics",
         description: "Trending topic clusters",
         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: "query", 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) => {
@@ -1381,7 +1476,7 @@ const COMMANDS = {
                     const profile = await client.getChannelByName(channelArg);
                     const resolvedId = profile.channel_id ?? profile.id;
                     if (!resolvedId) {
-                        print(`Error: channel "${channelArg}" not found.`);
+                        printErr(`Error: channel "${channelArg}" not found.`);
                         process.exit(1);
                     }
                     if (json)
@@ -1451,7 +1546,7 @@ async function cmdSetup(force) {
     const key = await rl.question("API key: ");
     rl.close();
     if (!key.trim()) {
-        print("Error: no API key provided.");
+        printErr("Error: no API key provided.");
         process.exit(1);
     }
     process.env.SIGNAL4_API_KEY = key.trim();
@@ -1460,7 +1555,7 @@ async function cmdSetup(force) {
         print(`Authenticated as ${who.user_email ?? who.key_prefix ?? "unknown"}`);
     }
     catch (err) {
-        print(`Error: invalid API key (${err instanceof Error ? err.message : String(err)})`);
+        printErr(`Error: invalid API key (${err instanceof Error ? err.message : String(err)})`);
         process.exit(1);
     }
     if (!existsSync(configDir))
@@ -1552,7 +1647,7 @@ async function showHelp() {
                 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(`  ${c.name.padEnd(19)}${c.desc}${speedWord(c.name)}`);
                 }
                 lines.push("");
             }
@@ -1563,7 +1658,7 @@ async function showHelp() {
                 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(`  ${c.name.padEnd(19)}${c.desc}${speedWord(c.name)}`);
                 }
                 lines.push("");
             }
@@ -1576,7 +1671,7 @@ async function showHelp() {
                 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(`  ${pad}${COMMANDS[n].description}${speedWord(n)}`);
                 }
                 lines.push("");
             }
@@ -1595,11 +1690,14 @@ async function showHelp() {
             lines.push(`  ${data.available_commands.join(", ")}`);
             lines.push("");
         }
+        lines.push("Speed: instant <0.5s · fast 0.5–2.5s · slow >2.5s (at default settings; longer windows take longer — see s4 <command> --help). Slow commands print an estimate to stderr first.");
+        lines.push("");
         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("  --collection NAME       Scope to one collection (s4 collections); omit = whole corpus");
+        lines.push("  -V, --version          Version and build time");
         lines.push("");
         lines.push("MCP server:");
         lines.push("  s4 --mcp               Start MCP server for Claude Desktop / Cursor");
@@ -1614,10 +1712,17 @@ async function showHelp() {
         ].join("\n"));
     }
 }
+/** " (fast)" after a command in the global help, from speed.ts; nothing for unknown commands. */
+function speedWord(name) {
+    const cmd = COMMANDS[name];
+    return cmd ? `  (${estimate(cmd.tool, {}).tier})` : "";
+}
 function showCommandHelp(name, cmd) {
     const lines = [
         `s4 ${name} — ${cmd.description}`,
         "",
+        `Speed: ${descriptionTag(cmd.tool).slice(1, -1)} (instant <0.5s · fast 0.5–2.5s · slow >2.5s)`,
+        "",
         `Usage: s4 ${name} [args] [flags]`,
         "",
         "Flags:",
@@ -1634,12 +1739,35 @@ function showCommandHelp(name, cmd) {
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
+const COMMANDS_WITH_TOPIC = new Set([
+    "search", "quotes", "claims", "analyze-claims", "trend-claims", "contradict-claims", "compare-claims",
+    "channel-dossier", "compare-channels", "channel-contradictions", "trend", "timeline", "analyze",
+    "frames", "compare", "dossier", "contradictions", "compare-periods", "entities",
+]);
+/** Commands whose backend takes explicit dates, so --days has no ceiling. */
+const DATE_RANGE_COMMANDS = new Set(["search", "quotes", "claims", "timeline", "count"]);
+const BUILD_INFO = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        const built = statSync(new URL("./cli.js", import.meta.url)).mtime.toISOString().slice(0, 16).replace("T", " ");
+        return `s4 ${pkg.version} (built ${built} UTC)`;
+    }
+    catch {
+        return "s4 (version unknown)";
+    }
+})();
+const BUILTIN_COMMANDS = ["setup", "whoami", "version", "mcp", "help"];
 export async function main() {
     applyConfig();
+    setSurface("cli");
     const argv = process.argv.slice(2);
+    if (argv[0] === "version" || argv[0] === "-V" || argv[0] === "--version") {
+        print(BUILD_INFO);
+        process.exit(0);
+    }
     // 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]])) {
+    if (!argv.length || argv[0] === "help" || (wantsHelp && !COMMANDS[argv[0]])) {
         await showHelp();
         process.exit(0);
     }
@@ -1652,6 +1780,8 @@ export async function main() {
         await import("./index.js");
         return;
     }
+    // CLI mode gets its own UA (MCP entry points keep the default).
+    client.setUserAgent("Signal4-S4CLI/2.7");
     const command = argv[0];
     const rest = argv.slice(1);
     // Setup (no API key needed)
@@ -1672,12 +1802,24 @@ export async function main() {
     // Lookup command
     const cmd = COMMANDS[command];
     if (!cmd) {
-        process.stderr.write(`Unknown command: ${command}\n\nRun s4 --help for usage.\n`);
+        const near = didYouMean(command, [...Object.keys(COMMANDS), ...BUILTIN_COMMANDS]);
+        process.stderr.write(`Error: unknown command "${command}"${near ? ` — did you mean "${near}"?` : ""}\nRun s4 --help for usage.\n`);
         process.exit(1);
     }
     // Parse args
     const args = parseArgs(rest, cmd.specs);
+    // Unquoted multi-word topics: `s4 search immigration policy`.
+    if (COMMANDS_WITH_TOPIC.has(command) && args.positionals.length > 1) {
+        args.positionals = [args.positionals.join(" ")];
+    }
     const json = args.flags.json;
+    activeCollection = args.flags.collection || undefined;
+    // --days has no ceiling where the backend takes dates; report endpoints cap at 365.
+    const days = args.flags.days;
+    if (typeof days === "number" && days > 365 && !args.flags.start && !DATE_RANGE_COMMANDS.has(command)) {
+        process.stderr.write(`Error: --days is capped at 365 for "${command}". For older material use s4 search / claims / timeline (any --days, or --since 2023).\n`);
+        process.exit(1);
+    }
     // Narrate pipeline steps on stderr while analytical commands stream.
     let progress = null;
     if (PROGRESS_COMMANDS.has(command)) {