@signal4/s4 2.1.2 → 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) {
@@ -32,8 +38,8 @@ function parseArgs(argv, specs) {
                 flags[spec.name] = spec.type === "number" ? Number(val) : (val ?? "");
             }
         }
-        else if (arg.startsWith("-")) {
-            // Unknown flag — skip
+        else if (arg.startsWith("-") && arg !== "-") {
+            process.stderr.write(`Warning: unknown flag "${arg}"\n`);
         }
         else {
             positionals.push(arg);
@@ -53,6 +59,9 @@ const FLAG_CHANNEL = { name: "channel", alias: "c", type: "string" };
 const FLAG_LANGUAGE = { name: "language", alias: "l", type: "string" };
 const FLAG_COUNTRY = { name: "country", type: "string" };
 const FLAG_MODE = { name: "mode", alias: "m", type: "string", default: "semantic" };
+const FLAG_START = { name: "start", type: "string" };
+const FLAG_END = { name: "end", type: "string" };
+const FLAG_KEYWORD = { name: "keyword", alias: "k", type: "string" };
 const FLAG_SKIP_CACHE = { name: "skip-cache", type: "boolean" };
 const FLAG_JSON = { name: "json", type: "boolean" };
 function daysRange(days) {
@@ -60,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");
 }
@@ -86,32 +104,41 @@ const COMMANDS = {
         specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_MODE, FLAG_LIMIT, FLAG_OFFSET, FLAG_LANGUAGE, FLAG_COUNTRY,
             { name: "sort", type: "string", default: "relevance" },
             { name: "count", type: "boolean" },
+            { name: "full-history", type: "boolean" },
+            FLAG_KEYWORD,
             { name: "speaker-id", type: "number" },
-            { name: "start", type: "string" }, { name: "end", type: "string" },
+            FLAG_START, FLAG_END,
             FLAG_JSON],
         run: async (args, json) => {
-            const [topic] = args.positionals;
+            const [positionalTopic] = args.positionals;
             const f = args.flags;
+            const keyword = f.keyword || undefined;
+            const topic = positionalTopic || keyword || undefined;
+            const mode = keyword ? "keyword" : f.mode;
             const days = Number(f.days) || 30;
             const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : daysRange(days);
+            const fullHistory = f["full-history"];
             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,
-                mode: f.mode, limit: Number(f.limit), offset: Number(f.offset),
+                mode, limit: Number(f.limit), offset: Number(f.offset),
                 count_only: f.count, sort: f.sort,
+                full_history: fullHistory,
             };
             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,
-                    limit: params.count_only ? 1 : Math.min(params.limit, 50), offset: params.offset,
+                    limit: params.count_only ? 1 : params.limit, offset: params.offset,
+                    full_history: fullHistory || undefined,
                 }));
             await runHandler("search_quotes", params);
         },
@@ -121,41 +148,339 @@ const COMMANDS = {
         description: "Search extracted claims",
         specs: [{ name: "entity", alias: "e", type: "string" }, FLAG_SPEAKER, FLAG_CHANNEL,
             { name: "category", type: "string" }, { name: "stance", type: "string" },
-            FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_MODE,
+            FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_MODE, FLAG_KEYWORD,
             { name: "sort", type: "string", default: "relevance" },
             { name: "min-obs", type: "number", default: 1 },
-            FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
+            { 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 [topic] = args.positionals;
+            const [positionalTopic] = args.positionals;
             const f = args.flags;
+            const keyword = f.keyword || undefined;
+            const topic = positionalTopic || keyword || undefined;
+            const mode = keyword ? "keyword" : f.mode;
             const days = Number(f.days) || 30;
+            const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : 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,
-                days, mode: f.mode,
+                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,
-                    days: params.days, mode: params.mode, sort: params.sort,
+                    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,
+                    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: Math.min(params.limit, 50), offset: params.offset,
+                    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",
-        specs: [{ name: "recent", type: "number", default: 7 },
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_LANGUAGE, FLAG_COUNTRY,
+            { name: "recent", type: "number", default: 7 },
             { name: "baseline", type: "number", default: 30 },
             { name: "min-similarity", type: "number" }, FLAG_JSON],
         run: async (args, json) => {
@@ -165,19 +490,57 @@ const COMMANDS = {
                 process.exit(1);
             }
             const f = args.flags;
+            const trendChannel = f.channel || undefined;
             const params = {
-                topic, recent_days: Number(f.recent) || 7, baseline_days: Number(f.baseline) || 30,
+                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",
-        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_CHANNEL,
             { name: "segments", type: "boolean" }, FLAG_JSON],
         run: async (args, json) => {
             const [identity, topic] = args.positionals;
@@ -189,19 +552,21 @@ const COMMANDS = {
             const isId = /^\d+$/.test(identity);
             const days = Number(f.days) || 30;
             const limit = Number(f.limit) || 20;
+            const offset = Number(f.offset) || 0;
+            const channelName = f.channel || undefined;
             // Profile by ID
             if (isId) {
                 const sid = Number(identity);
                 if (f.segments) {
-                    const params = { speaker_id: sid, sort: "chronological", days, limit, offset: Number(f.offset) };
+                    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: Number(f.offset) }));
+                        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 };
+                    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 }));
+                        return printJson(await client.searchSpeakerSegments({ identity_id: sid, query: topic, days, limit, offset }));
                     await runHandler("search_quotes", params);
                 }
                 else {
@@ -213,12 +578,12 @@ const COMMANDS = {
             }
             // Segments by name
             if (f.segments) {
-                const params = { speaker_name: identity, sort: "chronological", days, limit, offset: Number(f.offset) };
+                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;
                     if (sid)
-                        return printJson(await client.getSpeakerSegments({ identity_id: sid, days, limit, offset: Number(f.offset) }));
+                        return printJson(await client.getSpeakerSegments({ identity_id: sid, days, limit, offset }));
                     return printJson({ error: `Speaker "${identity}" not found` });
                 }
                 await runHandler("search_quotes", params);
@@ -226,9 +591,9 @@ const COMMANDS = {
             }
             // Discourse search (name + topic)
             if (topic) {
-                const params = { speaker_name: identity, topic, days, limit };
+                const params = { speaker: identity, topic, days, limit, offset, channel: channelName };
                 if (json)
-                    return printJson(await client.searchQuotes({ topic, speaker_name: identity, limit }));
+                    return printJson(await client.searchQuotes({ topic, speaker_name: identity, channel_names: channelName ? [channelName] : undefined, limit, offset }));
                 await runHandler("search_quotes", params);
                 return;
             }
@@ -248,8 +613,8 @@ const COMMANDS = {
     },
     channel: {
         tool: "get_channel",
-        description: "Channel profile",
-        specs: [FLAG_JSON],
+        description: "Channel profile or episode listing",
+        specs: [{ name: "episodes", type: "boolean" }, FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
         run: async (args, json) => {
             const [id] = args.positionals;
             if (!id) {
@@ -257,9 +622,28 @@ const COMMANDS = {
                 process.exit(1);
             }
             const isId = /^\d+$/.test(id);
+            const f = args.flags;
+            if (f.episodes) {
+                const channelName = isId ? undefined : id;
+                const days = Number(f.days) || 30;
+                const limit = Number(f.limit) || 20;
+                const offset = Number(f.offset) || 0;
+                const dr = daysRange(days);
+                const params = {
+                    channel: channelName, topic: undefined, sort: "chronological",
+                    days, ...dr, limit, offset,
+                };
+                if (json)
+                    return printJson(await client.searchQuotes({
+                        channel_names: channelName ? [channelName] : undefined, start_date: dr.start_date, end_date: dr.end_date,
+                        limit, offset,
+                    }));
+                await runHandler("search_quotes", params);
+                return;
+            }
             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: {
@@ -291,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: {
@@ -306,16 +691,17 @@ 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: {
         tool: "analyze_topic",
         description: "AI-powered topic analysis",
-        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS,
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY,
             { name: "workflow", alias: "w", type: "string", default: "simple_rag" },
             FLAG_SKIP_CACHE, FLAG_JSON],
         run: async (args, json) => {
@@ -326,10 +712,13 @@ 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,
                 skip_cache: f["skip-cache"],
             };
@@ -338,10 +727,39 @@ 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",
-        specs: [{ name: "speakers", type: "string" }, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        specs: [{ name: "speakers", type: "string" }, FLAG_SPEAKER, FLAG_DAYS, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_SKIP_CACHE, FLAG_JSON],
         run: async (args, json) => {
             const [topic] = args.positionals;
             if (!topic) {
@@ -349,17 +767,25 @@ const COMMANDS = {
                 process.exit(1);
             }
             const f = args.flags;
-            const speakers = (f.speakers || "").split(",").map((s) => s.trim()).filter(Boolean);
+            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);
             }
             process.stderr.write("Comparing speakers... (this may take up to 60 seconds)\n");
             const params = {
-                topic, speakers, days: Number(f.days) || 90, skip_cache: f["skip-cache"],
+                topic, speakers, days: Number(f.days) || 90,
+                language: f.language || undefined,
+                country: f.country || undefined,
+                skip_cache: f["skip-cache"],
             };
             if (json)
-                return printJson(await client.analyze({ query: topic, workflow: "speaker_compare", speaker_names: speakers, days: params.days, skip_cache: params.skip_cache }));
+                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,
+                }));
             await runHandler("compare_speakers", params);
         },
     },
@@ -380,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 }));
@@ -404,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 }));
@@ -448,7 +874,7 @@ const COMMANDS = {
         specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
-            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 15, language: f.language || undefined, country: f.country || undefined };
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, language: f.language || undefined, country: f.country || undefined };
             if (json)
                 return printJson(await client.getTopChannels(params));
             await runHandler("get_top_channels", params);
@@ -457,10 +883,11 @@ const COMMANDS = {
     "top-speakers": {
         tool: "get_top_speakers",
         description: "Top speakers by appearances, talk time, or clips",
-        specs: [FLAG_DAYS, FLAG_LIMIT, { name: "ranking", alias: "r", type: "string", default: "appearances" }, FLAG_JSON],
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_COUNTRY,
+            { name: "ranking", alias: "r", type: "string", default: "appearances" }, FLAG_JSON],
         run: async (args, json) => {
             const f = args.flags;
-            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 15, ranking: f.ranking };
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, ranking: f.ranking, language: f.language || undefined, country: f.country || undefined };
             if (json)
                 return printJson(await client.getTopSpeakers(params));
             await runHandler("get_top_speakers", params);
@@ -481,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));
@@ -501,13 +931,14 @@ const COMMANDS = {
         description: "Ad intelligence",
         specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
             { name: "advertisers", type: "boolean" }, { name: "trending", type: "boolean" },
-            { name: "channel", alias: "c", type: "number" },
+            FLAG_CHANNEL,
             { name: "category", type: "string" }, { name: "sort", type: "string", default: "episodes" },
             FLAG_JSON],
         run: async (args, json) => {
             const [adId] = args.positionals;
             const f = args.flags;
             const days = Number(f.days) || 30;
+            const channelArg = f.channel || undefined;
             if (adId && /^\d+$/.test(adId)) {
                 if (json)
                     return printJson(await client.getAdvertiser(Number(adId)));
@@ -523,10 +954,24 @@ const COMMANDS = {
                     return printJson(await client.getAdTrends(days));
                 await runHandler("get_ad_analytics", { view: "trending", days });
             }
-            else if (Number(f.channel)) {
-                if (json)
-                    return printJson(await client.getAdsByChannel(Number(f.channel), days));
-                await runHandler("get_ad_analytics", { view: "channel", channel_id: Number(f.channel), days });
+            else if (channelArg) {
+                const channelId = /^\d+$/.test(channelArg) ? Number(channelArg) : undefined;
+                if (channelId) {
+                    if (json)
+                        return printJson(await client.getAdsByChannel(channelId, days));
+                    await runHandler("get_ad_analytics", { view: "channel", channel_id: channelId, days });
+                }
+                else {
+                    const profile = await client.getChannelByName(channelArg);
+                    const resolvedId = profile.channel_id ?? profile.id;
+                    if (!resolvedId) {
+                        print(`Error: channel "${channelArg}" not found.`);
+                        process.exit(1);
+                    }
+                    if (json)
+                        return printJson(await client.getAdsByChannel(resolvedId, days));
+                    await runHandler("get_ad_analytics", { view: "channel", channel_id: resolvedId, days });
+                }
             }
             else {
                 if (json)
@@ -572,6 +1017,8 @@ const COMMANDS = {
         },
     },
 };
+// The backend's whoami guide advertises "quotes" — keep it working as an alias.
+COMMANDS.quotes = COMMANDS.search;
 // ---------------------------------------------------------------------------
 // Setup command
 // ---------------------------------------------------------------------------