@signal4/s4 2.6.1 → 2.8.0

package/dist/cli.js

@@ -1,106 +1,63 @@
 /** 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 { formatDossier, parsePoliticalLean } 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_PAGE = { name: "page", type: "number", desc: "Page number, 1-based, in pages of --limit (sets --offset)" };
+const FLAG_ALL = { name: "all", type: "boolean", desc: `Follow every page (up to ${50} pages)` };
+/** Paging flags for every list command (signal4#329). */
+const PAGING = [FLAG_OFFSET, FLAG_PAGE, FLAG_ALL];
+/** --all stops after this many pages; the last page then says how to continue. */
+const MAX_ALL_PAGES = 50;
 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_PROJECT = { name: "project", type: "string", desc: "Restrict to a project (e.g. Big_Channels)" };
+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", "speaker", "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
 // ---------------------------------------------------------------------------
@@ -211,11 +168,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");
@@ -239,23 +200,98 @@ 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);
     }
-    const text = result.content[0]?.text ?? "";
+    let text = result.content[0]?.text ?? "";
+    // --all: follow the next-page hint every list answer ends with, until it stops.
+    let pages = 1;
+    let next = nextPage(text);
+    while (followAllPages && next && pages < MAX_ALL_PAGES) {
+        const current = Number(params[next.param] ?? 0);
+        if (next.offset <= current)
+            break;
+        params = { ...params, [next.param]: next.offset };
+        const more = await handler(params);
+        if (more.isError)
+            break;
+        const pageText = more.content[0]?.text ?? "";
+        text += `\n\n--- page ${++pages} (${next.param} ${next.offset}) ---\n` + pageText;
+        next = nextPage(pageText);
+    }
+    if (followAllPages && next && pages >= MAX_ALL_PAGES) {
+        text += `\n\n(--all stopped after ${MAX_ALL_PAGES} pages; continue with --offset ${next.offset})`;
+    }
     if (out)
         writeOut(out, text);
     else
         print(text);
 }
+/** Set by main from --all. */
+let followAllPages = false;
+/** The next page a list answer offers ("--offset 40", "--obs-offset 40"), or null. */
+function nextPage(text) {
+    const obs = [...text.matchAll(/--obs-offset (\d+)/g)].pop();
+    if (obs)
+        return { param: "observations_offset", offset: Number(obs[1]) };
+    const m = [...text.matchAll(/(?<![-\w])--offset (\d+)/g)].pop();
+    return m ? { param: "offset", offset: Number(m[1]) } : null;
+}
+// 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/
 // ---------------------------------------------------------------------------
@@ -409,21 +445,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 }, ...PAGING, 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,
@@ -442,6 +479,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"))) {
@@ -456,6 +494,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) => ({
@@ -485,7 +524,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,
@@ -495,12 +534,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 }, ...PAGING, 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;
@@ -521,6 +560,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);
@@ -536,6 +576,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);
         },
@@ -543,12 +584,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;
@@ -560,11 +601,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);
         },
@@ -574,11 +617,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;
@@ -587,32 +631,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);
         },
@@ -620,24 +666,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);
         },
@@ -645,24 +693,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);
         },
@@ -670,24 +718,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);
         },
@@ -695,56 +743,57 @@ 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);
         },
     },
     "entities": {
         tool: "find_entities",
-        description: "Fuzzy search canonical entities by name/alias (people, orgs, places, subjects)",
-        specs: [{ name: "type", type: "string", desc: "Entity type filter: person | organization | place | subject" }, FLAG_LIMIT, FLAG_JSON],
+        description: "Find entities by name (people, orgs, places, subjects); the first row is what entity-claims uses",
+        specs: [{ name: "type", type: "string", desc: "Entity type filter: person | organization | place | subject" }, FLAG_LIMIT, ...PAGING, 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;
             const entityType = f.type || undefined;
             const limit = Number(f.limit) || undefined;
+            const offset = Number(f.offset) || undefined;
             if (json)
-                return printJson(await client.searchEntities({ query, entity_type: entityType, limit }));
-            await runHandler("find_entities", { query, entity_type: entityType, limit });
+                return printJson(await client.searchEntities({ query, entity_type: entityType, limit, offset }));
+            await runHandler("find_entities", { query, entity_type: entityType, limit, offset });
         },
     },
     "entity-claims": {
         tool: "entity_claims",
-        description: "Claims about a resolved canonical entity, ranked, with stance distribution",
+        description: "Most-spread claims about an entity (every row of that name or alias, merges included)",
         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, ...PAGING, 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;
@@ -755,6 +804,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);
         },
@@ -762,16 +812,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 });
         },
     },
@@ -780,42 +830,53 @@ 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, ...PAGING, 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, offset: Number(f.offset) || 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);
         },
     },
     claim: {
         tool: "get_claim",
         description: "Get full claim detail with observations and related claims",
-        specs: [{ name: "observations", type: "boolean", desc: "Include the full observation list" },
+        specs: [{ name: "observations", type: "boolean", desc: "Include the observation list (20 a page)" },
+            { name: "obs-offset", type: "number", desc: "Observations: skip this many (implies --observations)" },
+            { name: "obs-limit", type: "number", desc: "Observations per page (max 100)" },
+            FLAG_ALL,
             { name: "related", type: "boolean", desc: "Include semantically related claims" }, 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);
+            const obsOffset = args.flags["obs-offset"] != null ? Number(args.flags["obs-offset"]) : undefined;
+            const obsLimit = args.flags["obs-limit"] != null ? Number(args.flags["obs-limit"]) : undefined;
             if (json) {
                 const detail = await client.getClaim(claimId);
-                if (args.flags.observations)
-                    detail.observations = await client.getClaimObservations({ claim_id: claimId });
+                if (args.flags.observations || obsOffset != null || obsLimit != null) {
+                    detail.observations = await client.getClaimObservations({ claim_id: claimId, limit: obsLimit, offset: obsOffset });
+                }
                 if (args.flags.related)
                     detail.related = await client.getRelatedClaims(claimId);
                 return printJson(detail);
             }
             await runHandler("get_claim", {
                 claim_id: claimId,
-                include_observations: args.flags.observations,
+                include_observations: args.flags.observations || followAllPages,
+                observations_offset: obsOffset,
+                observations_limit: obsLimit,
                 include_related: args.flags.related,
             });
         },
@@ -823,15 +884,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;
@@ -844,6 +907,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({
@@ -857,18 +922,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,
@@ -879,21 +954,73 @@ 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)" }, ...PAGING, 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: {
         tool: "find_speakers",
         description: "Speaker search, profile, or discourse",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_CHANNEL,
+        specs: [FLAG_DAYS, FLAG_LIMIT, ...PAGING, FLAG_CHANNEL,
             { 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) {
-                print("Error: speaker name or ID required.");
+                printErr("Error: speaker name or ID required.");
                 process.exit(1);
             }
             const f = args.flags;
@@ -962,11 +1089,11 @@ const COMMANDS = {
     channel: {
         tool: "get_channel",
         description: "Channel profile or episode listing",
-        specs: [{ name: "episodes", type: "boolean", desc: "List the channel's recent episodes instead of the profile" }, 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, ...PAGING, FLAG_JSON],
         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);
@@ -1001,7 +1128,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) {
@@ -1020,7 +1147,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);
@@ -1032,15 +1159,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 });
@@ -1049,13 +1176,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;
@@ -1069,6 +1196,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));
@@ -1078,11 +1206,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;
@@ -1094,7 +1222,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 }),
@@ -1109,18 +1237,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");
@@ -1134,7 +1262,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);
         },
@@ -1151,14 +1279,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");
@@ -1179,18 +1307,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");
@@ -1201,7 +1329,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`];
@@ -1234,12 +1362,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");
@@ -1254,22 +1382,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,36 +1422,48 @@ 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],
+        description: "Top channels by episode count; with --topic, by how much they say about it",
+        specs: [FLAG_DAYS, FLAG_START, FLAG_END, FLAG_LIMIT, ...PAGING, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_COLLECTION,
+            { name: "topic", type: "string", desc: "Rank by matching segments per channel, from the transcripts" },
+            { name: "lean", type: "string", desc: "Channel lean: left | center-left | center | center-right | right | 0.0-0.5" },
+            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 };
-            if (json)
-                return printJson(await client.getTopChannels(params));
+            const topic = f.topic || args.positionals.join(" ") || undefined;
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, offset: Number(f.offset) || undefined, language: f.language || undefined, country: f.country || undefined, topic, political_lean: f.lean || undefined, ...dateFlags(f) };
+            if (json) {
+                const lean = parsePoliticalLean(params.political_lean);
+                return printJson(await client.getTopChannels({ ...params, political_lean_min: lean.min, political_lean_max: lean.max, 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, FLAG_PROJECT,
-            { name: "ranking", alias: "r", type: "string", default: "appearances", desc: "Rank by: appearances | talkative (talk time) | clipped" }, FLAG_JSON],
+        description: "Top speakers by appearances, talk time or clips; with --topic, by how much they talk about it",
+        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" },
+            { name: "topic", type: "string", desc: "Rank by matching segments each speaker speaks in, from the transcripts (overrides --ranking)" },
+            { name: "lean", type: "string", desc: "Channel lean: left | center-left | center | center-right | right | 0.0-0.5" },
+            ...PAGING, 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, project: f.project || undefined };
-            if (json)
-                return printJson(await client.getTopSpeakers(params));
+            const topic = f.topic || args.positionals.join(" ") || undefined;
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, offset: Number(f.offset) || undefined, ranking: f.ranking, language: f.language || undefined, country: f.country || undefined, project: f.collection || undefined, topic, political_lean: f.lean || undefined, ...dateFlags(f) };
+            if (json) {
+                const lean = parsePoliticalLean(params.political_lean);
+                return printJson(await client.getTopSpeakers({ ...params, political_lean_min: lean.min, political_lean_max: lean.max }));
+            }
             await runHandler("get_top_speakers", params);
         },
     },
     network: {
         tool: "get_speaker_network",
         description: "Speaker co-appearance network",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_PROJECT, 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", project: f.project || undefined };
+            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);
@@ -1323,7 +1473,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) => {
@@ -1344,7 +1494,7 @@ const COMMANDS = {
     ads: {
         tool: "get_ad_analytics",
         description: "Ad intelligence",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
+        specs: [FLAG_DAYS, FLAG_LIMIT, ...PAGING,
             { name: "advertisers", type: "boolean", desc: "List advertisers instead of the overview" },
             { name: "trending", type: "boolean", desc: "Show growing/declining/new advertisers" },
             FLAG_CHANNEL,
@@ -1382,7 +1532,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)
@@ -1402,7 +1552,7 @@ const COMMANDS = {
         description: "Manage bookmarks",
         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,
+            FLAG_LIMIT, ...PAGING,
             { name: "note", type: "string", desc: "Note to attach when adding a bookmark" }, FLAG_JSON],
         run: async (args, json) => {
             const [sub, entityType, entityId] = args.positionals;
@@ -1452,7 +1602,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();
@@ -1461,7 +1611,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))
@@ -1553,7 +1703,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("");
             }
@@ -1564,7 +1714,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("");
             }
@@ -1577,7 +1727,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("");
             }
@@ -1596,11 +1746,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");
@@ -1615,10 +1768,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:",
@@ -1635,12 +1795,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);
     }
@@ -1653,6 +1836,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)
@@ -1673,12 +1858,38 @@ 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;
+    // --page N is --offset (N-1)*limit; --all follows the next-page hint (signal4#329).
+    const page = Number(args.flags.page);
+    if (page) {
+        if (page < 1 || !Number.isInteger(page)) {
+            printErr("Error: --page is a whole number from 1.");
+            process.exit(1);
+        }
+        args.flags.offset = (page - 1) * (Number(args.flags.limit) || 20);
+    }
+    followAllPages = !!args.flags.all;
+    if (followAllPages && json) {
+        printErr("Error: --all pages the text output. For JSON, page with --offset, or use paginate() from @signal4/s4/client.");
+        process.exit(1);
+    }
+    // --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)) {