@signal4/s4 2.2.0 → 2.4.0

package/dist/cli.js

@@ -9,9 +9,15 @@ import { createInterface } from "node:readline/promises";
 function parseArgs(argv, specs) {
     const flags = {};
     const positionals = [];
-    // Apply defaults
-    for (const s of specs)
-        flags[s.name] = s.default ?? (s.type === "boolean" ? false : s.type === "number" ? 0 : "");
+    // 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) {
@@ -63,6 +69,15 @@ function daysRange(days) {
     const start = new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
     return { start_date: start, end_date: end };
 }
+function parseSegmentId(raw) {
+    // Quote listings display IDs as "seg:12345" — accept that form verbatim.
+    const id = Number(raw.replace(/^seg:/, ""));
+    if (!Number.isInteger(id)) {
+        print(`Error: invalid segment ID "${raw}" (expected a number or seg:<number>).`);
+        process.exit(1);
+    }
+    return id;
+}
 function print(text) {
     process.stdout.write(text + "\n");
 }
@@ -104,9 +119,9 @@ const COMMANDS = {
             const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : daysRange(days);
             const fullHistory = f["full-history"];
             const params = {
-                topic, speaker_name: f.speaker || undefined,
+                topic, speaker: f.speaker || undefined,
                 speaker_id: Number(f["speaker-id"]) || undefined,
-                channel_name: f.channel || undefined,
+                channel: f.channel || undefined,
                 language: f.language || undefined,
                 country: f.country || undefined,
                 days, ...dr,
@@ -116,8 +131,9 @@ const COMMANDS = {
             };
             if (json)
                 return printJson(await client.searchQuotes({
-                    topic: params.topic, speaker_name: params.speaker_name,
-                    speaker_identity_id: params.speaker_id, channel_name: params.channel_name,
+                    topic: params.topic, speaker_name: params.speaker,
+                    speaker_identity_id: params.speaker_id,
+                    channel_names: params.channel ? params.channel.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
                     start_date: params.start_date, end_date: params.end_date,
                     language: params.language, country: params.country,
                     mode: params.mode !== "semantic" ? params.mode : undefined,
@@ -135,6 +151,9 @@ const COMMANDS = {
             FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_MODE, FLAG_KEYWORD,
             { name: "sort", type: "string", default: "relevance" },
             { name: "min-obs", type: "number", default: 1 },
+            { name: "min-similarity", type: "number" },
+            { name: "political-lean-min", type: "number" }, { name: "political-lean-max", type: "number" },
+            { name: "source", type: "string" },
             FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_START, FLAG_END, FLAG_JSON],
         run: async (args, json) => {
             const [positionalTopic] = args.positionals;
@@ -144,33 +163,319 @@ const COMMANDS = {
             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;
+            const leanMin = f["political-lean-min"] !== undefined ? Number(f["political-lean-min"]) : undefined;
+            const leanMax = f["political-lean-max"] !== undefined ? Number(f["political-lean-max"]) : undefined;
+            const minSim = f["min-similarity"] !== undefined ? Number(f["min-similarity"]) : undefined;
             const params = {
                 topic, entity: f.entity || undefined,
-                speaker_name: f.speaker || undefined,
-                channel_name: f.channel || undefined,
+                speaker: f.speaker || undefined,
+                channel: f.channel || undefined,
                 category: f.category || undefined,
                 stance: f.stance || undefined,
                 language: f.language || undefined,
                 country: f.country || undefined,
+                political_lean_min: leanMin, political_lean_max: leanMax,
+                min_similarity: minSim,
+                source: f.source || undefined,
                 days, mode,
                 sort: f.sort, min_observations: Number(f["min-obs"]) || 1,
                 limit: Number(f.limit), offset: Number(f.offset),
                 ...dr,
             };
+            const claimsDr = dr ?? daysRange(days);
             if (json)
                 return printJson(await client.searchClaims({
-                    topic: params.topic, entity: params.entity, speaker_name: params.speaker_name,
-                    channel_names: params.channel_name ? [params.channel_name] : undefined,
-                    primary_topic: params.category, stance: params.stance, language: params.language,
+                    topic: params.topic, entity: params.entity, speaker_name: params.speaker,
+                    channel_names: params.channel ? params.channel.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
+                    category: params.category, stance: params.stance, language: params.language,
                     country: params.country,
-                    start_date: params.start_date, end_date: params.end_date,
-                    days: params.days, mode: params.mode, sort: params.sort,
+                    political_lean_min: leanMin, political_lean_max: leanMax,
+                    min_similarity: minSim,
+                    start_date: claimsDr.start_date, end_date: claimsDr.end_date,
+                    mode: params.mode, sort: params.sort,
                     min_observations: params.min_observations > 1 ? params.min_observations : undefined,
                     limit: params.limit, offset: params.offset,
                 }));
             await runHandler("search_claims", params);
         },
     },
+    "analyze-claims": {
+        tool: "analyze_claims",
+        description: "Analyze a topic over extracted claims — themes with observation stats (fast, no LLM)",
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_DAYS,
+            { name: "min-obs", type: "number", default: 1 }, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const channelArg = f.channel || undefined;
+            const params = {
+                topic,
+                speaker: f.speaker || undefined,
+                channels: channelArg?.split(",").map((s) => s.trim()).filter(Boolean),
+                language: f.language || undefined,
+                days: Number(f.days) || undefined,
+                min_observations: Number(f["min-obs"]) || undefined,
+            };
+            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,
+                }));
+            await runHandler("analyze_claims", params);
+        },
+    },
+    "trend-claims": {
+        tool: "trend_claims",
+        description: "Detect whether a topic is surging/fading by claim volume (fast)",
+        specs: [{ name: "recent-days", type: "number", default: 7 },
+            { name: "baseline-days", type: "number", default: 30 },
+            { name: "min-similarity", type: "number" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const params = {
+                topic,
+                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,
+            };
+            if (json)
+                return printJson(await client.detectTrendClaims(params));
+            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, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const speaker = f.speaker || undefined;
+            if (!speaker) {
+                print("Error: --speaker is required.");
+                process.exit(1);
+            }
+            const params = { topic, speaker, days: Number(f.days) || undefined };
+            if (json)
+                return printJson(await client.checkContradictionsClaims({
+                    topic, speaker_name: speaker, days: params.days,
+                }));
+            await runHandler("contradict_claims", params);
+        },
+    },
+    "compare-claims": {
+        tool: "compare_claims",
+        description: "Compare 2-5 speakers' claims on a topic — side-by-side stance (fast)",
+        specs: [{ name: "speakers", type: "string" }, FLAG_SPEAKER, FLAG_DAYS, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("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.");
+                process.exit(1);
+            }
+            const params = { topic, speakers, days: Number(f.days) || undefined };
+            if (json)
+                return printJson(await client.compareSpeakersClaims({
+                    topic, speaker_names: speakers, days: params.days,
+                }));
+            await runHandler("compare_claims", params);
+        },
+    },
+    "channel-dossier": {
+        tool: "channel_dossier",
+        description: "Claims dossier of what a channel (show) platformed on a topic (fast)",
+        specs: [FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const channel = f.channel || undefined;
+            if (!channel) {
+                print("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,
+                }));
+            await runHandler("channel_dossier", { topic, channels, days });
+        },
+    },
+    "compare-channels": {
+        tool: "compare_channels",
+        description: "Compare 2-5 channels' claims on a topic — stance + speaker overlap (fast)",
+        specs: [{ name: "channels", type: "string" }, FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("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.");
+                process.exit(1);
+            }
+            const days = Number(f.days) || undefined;
+            if (json)
+                return printJson(await client.compareChannelsClaims({
+                    topic, channel_names: channels, days,
+                }));
+            await runHandler("compare_channels", { topic, channels, days });
+        },
+    },
+    "channel-contradictions": {
+        tool: "check_channel_contradictions",
+        description: "Contradictory claims a channel platforms on a topic (fast)",
+        specs: [FLAG_CHANNEL, FLAG_DAYS, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const channel = f.channel || undefined;
+            if (!channel) {
+                print("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,
+                }));
+            await runHandler("check_channel_contradictions", { topic, channels, days });
+        },
+    },
+    "entities": {
+        tool: "find_entities",
+        description: "Fuzzy search canonical entities by name/alias (people, orgs, places, subjects)",
+        specs: [{ name: "type", type: "string" }, FLAG_LIMIT, FLAG_JSON],
+        run: async (args, json) => {
+            const [query] = args.positionals;
+            if (!query) {
+                print("Error: query is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const entityType = f.type || undefined;
+            const limit = Number(f.limit) || undefined;
+            if (json)
+                return printJson(await client.searchEntities({ query, entity_type: entityType, limit }));
+            await runHandler("find_entities", { query, entity_type: entityType, limit });
+        },
+    },
+    "entity-claims": {
+        tool: "entity_claims",
+        description: "Claims about a resolved canonical entity, ranked, with stance distribution",
+        specs: [{ name: "sort", type: "string", default: "spread" }, { name: "stance", type: "string" },
+            FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
+        run: async (args, json) => {
+            const [name] = args.positionals;
+            if (!name) {
+                print("Error: entity name is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const params = {
+                entity: name, sort: f.sort || undefined, stance: f.stance || undefined,
+                limit: Number(f.limit) || undefined, offset: Number(f.offset) || undefined,
+            };
+            if (json)
+                return printJson(await client.getEntityClaims({
+                    name, sort: params.sort, stance: params.stance, limit: params.limit, offset: params.offset,
+                }));
+            await runHandler("entity_claims", params);
+        },
+    },
+    "claim-graph": {
+        tool: "claim_graph",
+        description: "A claim's parent, children, and sibling (variant) claims",
+        specs: [FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id || !/^\d+$/.test(id)) {
+                print("Error: claim_id (numeric) required.");
+                process.exit(1);
+            }
+            const claimId = Number(id);
+            if (json)
+                return printJson(await client.getClaimGraph(claimId));
+            await runHandler("claim_graph", { claim_id: claimId });
+        },
+    },
+    "top-claims": {
+        tool: "top_claims",
+        description: "Leaderboard of the most widely-spread or most-contested claims",
+        specs: [{ name: "metric", type: "string", default: "spread" }, { name: "category", type: "string" },
+            { name: "min-obs", type: "number", default: 2 }, FLAG_DAYS, FLAG_LIMIT, FLAG_JSON],
+        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,
+            };
+            if (json)
+                return printJson(await client.getTopClaims(params));
+            await runHandler("top_claims", params);
+        },
+    },
+    claim: {
+        tool: "get_claim",
+        description: "Get full claim detail with observations and related claims",
+        specs: [{ name: "observations", type: "boolean" }, { name: "related", type: "boolean" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id || !/^\d+$/.test(id)) {
+                print("Error: claim_id (numeric) required.");
+                process.exit(1);
+            }
+            const claimId = Number(id);
+            if (json) {
+                const detail = await client.getClaim(claimId);
+                if (args.flags.observations)
+                    detail.observations = await client.getClaimObservations({ claim_id: claimId });
+                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_related: args.flags.related,
+            });
+        },
+    },
     trend: {
         tool: "detect_trend",
         description: "Detect topic volume trends",
@@ -185,19 +490,53 @@ const COMMANDS = {
                 process.exit(1);
             }
             const f = args.flags;
+            const trendChannel = f.channel || undefined;
             const params = {
-                topic, speaker_name: f.speaker || undefined,
-                channel_name: f.channel || undefined,
+                topic, speaker: f.speaker || undefined,
+                channel: trendChannel,
                 language: f.language || undefined,
                 country: f.country || undefined,
                 recent_days: Number(f.recent) || 7, baseline_days: Number(f.baseline) || 30,
                 min_similarity: Number(f["min-similarity"]) || undefined,
             };
             if (json)
-                return printJson(await client.detectTrend(params));
+                return printJson(await client.detectTrend({
+                    ...params,
+                    channel_names: trendChannel?.split(",").map((s) => s.trim()).filter(Boolean),
+                }));
             await runHandler("detect_trend", params);
         },
     },
+    timeline: {
+        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" },
+            FLAG_START, FLAG_END, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const days = Number(f.days) || 30;
+            const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : daysRange(days);
+            const tlChannel = f.channel || undefined;
+            const tlParams = {
+                topic,
+                speaker: f.speaker || undefined,
+                channel_names: tlChannel?.split(",").map((s) => s.trim()).filter(Boolean),
+                start_date: dr.start_date,
+                end_date: dr.end_date,
+                language: f.language || undefined,
+                granularity: f.granularity || "day",
+            };
+            if (json)
+                return printJson(await client.getTimeline(tlParams));
+            await runHandler("get_timeline", { ...tlParams, days, channel: tlChannel });
+        },
+    },
     speaker: {
         tool: "find_speakers",
         description: "Speaker search, profile, or discourse",
@@ -219,13 +558,13 @@ const COMMANDS = {
             if (isId) {
                 const sid = Number(identity);
                 if (f.segments) {
-                    const params = { speaker_id: sid, sort: "chronological", days, limit, offset, channel_name: channelName };
+                    const params = { speaker_id: sid, sort: "chronological", days, limit, offset, channel: channelName };
                     if (json)
                         return printJson(await client.getSpeakerSegments({ identity_id: sid, days, limit, offset }));
                     await runHandler("search_quotes", params);
                 }
                 else if (topic) {
-                    const params = { speaker_id: sid, topic, days, limit, offset, channel_name: channelName };
+                    const params = { speaker_id: sid, topic, days, limit, offset, channel: channelName };
                     if (json)
                         return printJson(await client.searchSpeakerSegments({ identity_id: sid, query: topic, days, limit, offset }));
                     await runHandler("search_quotes", params);
@@ -239,7 +578,7 @@ const COMMANDS = {
             }
             // Segments by name
             if (f.segments) {
-                const params = { speaker_name: identity, sort: "chronological", days, limit, offset, channel_name: channelName };
+                const params = { speaker: identity, sort: "chronological", days, limit, offset, channel: channelName };
                 if (json) {
                     const byName = await client.getSpeakerByName(identity);
                     const sid = byName.speaker_id ?? byName.id;
@@ -252,9 +591,9 @@ const COMMANDS = {
             }
             // Discourse search (name + topic)
             if (topic) {
-                const params = { speaker_name: identity, topic, days, limit, offset, channel_name: channelName };
+                const params = { speaker: identity, topic, days, limit, offset, channel: channelName };
                 if (json)
-                    return printJson(await client.searchQuotes({ topic, speaker_name: identity, channel_name: channelName, limit, offset }));
+                    return printJson(await client.searchQuotes({ topic, speaker_name: identity, channel_names: channelName ? [channelName] : undefined, limit, offset }));
                 await runHandler("search_quotes", params);
                 return;
             }
@@ -291,12 +630,12 @@ const COMMANDS = {
                 const offset = Number(f.offset) || 0;
                 const dr = daysRange(days);
                 const params = {
-                    channel_name: channelName, topic: undefined, sort: "chronological",
+                    channel: channelName, topic: undefined, sort: "chronological",
                     days, ...dr, limit, offset,
                 };
                 if (json)
                     return printJson(await client.searchQuotes({
-                        channel_name: channelName, start_date: dr.start_date, end_date: dr.end_date,
+                        channel_names: channelName ? [channelName] : undefined, start_date: dr.start_date, end_date: dr.end_date,
                         limit, offset,
                     }));
                 await runHandler("search_quotes", params);
@@ -304,7 +643,7 @@ const COMMANDS = {
             }
             if (json)
                 return printJson(isId ? await client.getChannel(Number(id)) : await client.getChannelByName(id));
-            await runHandler("get_channel", isId ? { channel_id: Number(id) } : { channel_name: id });
+            await runHandler("get_channel", isId ? { channel_id: Number(id) } : { channel: id });
         },
     },
     episode: {
@@ -336,9 +675,10 @@ const COMMANDS = {
                 print("Error: segment ID required.");
                 process.exit(1);
             }
+            const segId = parseSegmentId(id);
             if (json)
-                return printJson(await client.getSegment(Number(id)));
-            await runHandler("get_segment", { segment_id: Number(id) });
+                return printJson(await client.getSegment(segId));
+            await runHandler("get_segment", { segment_id: segId });
         },
     },
     thread: {
@@ -351,10 +691,11 @@ const COMMANDS = {
                 print("Error: segment ID required.");
                 process.exit(1);
             }
+            const segId = parseSegmentId(id);
             const n = Number(args.flags.n) || 5;
             if (json)
-                return printJson(await client.getSegmentThread(Number(id), n));
-            await runHandler("get_thread", { segment_id: Number(id), n });
+                return printJson(await client.getSegmentThread(segId, n));
+            await runHandler("get_thread", { segment_id: segId, n });
         },
     },
     analyze: {
@@ -371,10 +712,11 @@ const COMMANDS = {
             }
             const f = args.flags;
             process.stderr.write("Analyzing... (this may take up to 60 seconds)\n");
+            const channelArg = f.channel || undefined;
             const params = {
                 query, workflow: f.workflow,
-                speaker_name: f.speaker || undefined,
-                channel: f.channel || undefined,
+                speaker: f.speaker || undefined,
+                channels: channelArg?.split(",").map((s) => s.trim()).filter(Boolean),
                 language: f.language || undefined,
                 country: f.country || undefined,
                 days: Number(f.days) || undefined,
@@ -385,6 +727,35 @@ const COMMANDS = {
             await runHandler("analyze_topic", params);
         },
     },
+    frames: {
+        tool: "compare_frames",
+        description: "Compare left vs right media framing on a topic",
+        specs: [FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            process.stderr.write("Comparing left vs right framing... (this may take up to 60 seconds)\n");
+            const params = {
+                topic, days: Number(f.days) || 30,
+                language: f.language || undefined,
+                country: f.country || undefined,
+                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 [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 }),
+                ]);
+                return printJson({ left, right });
+            }
+            await runHandler("compare_frames", params);
+        },
+    },
     compare: {
         tool: "compare_speakers",
         description: "Compare speakers on a topic",
@@ -435,7 +806,7 @@ const COMMANDS = {
             }
             process.stderr.write("Building dossier... (this may take up to 60 seconds)\n");
             const params = {
-                topic, speaker_name: speaker, days: Number(args.flags.days) || 180, skip_cache: args.flags["skip-cache"],
+                topic, speaker: speaker, days: Number(args.flags.days) || 180, skip_cache: args.flags["skip-cache"],
             };
             if (json)
                 return printJson(await client.analyze({ query: topic, workflow: "speaker_dossier", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
@@ -459,7 +830,7 @@ const COMMANDS = {
             }
             process.stderr.write("Checking contradictions...\n");
             const params = {
-                topic, speaker_name: speaker, days: Number(args.flags.days) || 365, skip_cache: args.flags["skip-cache"],
+                topic, speaker: speaker, days: Number(args.flags.days) || 365, skip_cache: args.flags["skip-cache"],
             };
             if (json)
                 return printJson(await client.analyze({ query: topic, workflow: "contradiction_check", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
@@ -537,15 +908,18 @@ const COMMANDS = {
     topics: {
         tool: "get_topics",
         description: "Trending topic clusters",
-        specs: [FLAG_LANGUAGE, FLAG_LIMIT, { name: "query", alias: "q", type: "string" },
+        specs: [FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_LIMIT, FLAG_DAYS, { name: "query", alias: "q", type: "string" },
             { name: "min-segments", type: "number", default: 50 },
             { name: "start", type: "string" }, { name: "end", type: "string" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
+            const dr = f.days ? daysRange(Number(f.days)) : undefined;
             const params = {
                 language: f.language || "en", limit: Number(f.limit) || 20,
-                query: f.query || undefined, min_segments: Number(f["min-segments"]) || 50,
-                start_date: f.start || undefined, end_date: f.end || undefined,
+                query: f.query || undefined, country: f.country || undefined,
+                min_segments: Number(f["min-segments"]) || 50,
+                start_date: f.start || dr?.start_date || undefined,
+                end_date: f.end || dr?.end_date || undefined,
             };
             if (json)
                 return printJson(await client.getTopics(params));
@@ -643,6 +1017,8 @@ const COMMANDS = {
         },
     },
 };
+// The backend's whoami guide advertises "quotes" — keep it working as an alias.
+COMMANDS.quotes = COMMANDS.search;
 // ---------------------------------------------------------------------------
 // Setup command
 // ---------------------------------------------------------------------------