@signal4/s4 2.1.2 → 2.4.0

package/dist/format.js

@@ -1,6 +1,32 @@
 /** Shared formatting utilities — markdown output for MCP tools. */
 const PUBLIC_URL = "https://api.signal4.ca";
 // ---------------------------------------------------------------------------
+// Political lean parsing
+// ---------------------------------------------------------------------------
+const LEAN_PRESETS = {
+    left: [0.0, 0.3],
+    "center-left": [0.2, 0.4],
+    center: [0.35, 0.65],
+    "center-right": [0.6, 0.8],
+    right: [0.7, 1.0],
+};
+export function parsePoliticalLean(lean) {
+    if (!lean)
+        return {};
+    const key = lean.trim().toLowerCase();
+    const preset = LEAN_PRESETS[key];
+    if (preset)
+        return { min: preset[0], max: preset[1] };
+    if (key.includes("-")) {
+        const [a, b] = key.split("-", 2);
+        const min = parseFloat(a);
+        const max = parseFloat(b);
+        if (!isNaN(min) && !isNaN(max))
+            return { min, max };
+    }
+    return {};
+}
+// ---------------------------------------------------------------------------
 // Primitives
 // ---------------------------------------------------------------------------
 export function fmtTime(seconds) {
@@ -80,6 +106,17 @@ function simTier(sim) {
         return "weak";
     return "";
 }
+function claimSimTier(sim) {
+    if (sim >= 0.45)
+        return "strong";
+    if (sim >= 0.35)
+        return "good";
+    if (sim >= 0.25)
+        return "relevant";
+    if (sim > 0)
+        return "weak";
+    return "";
+}
 function topicRelevanceTier(relevance) {
     if (relevance >= 0.35)
         return "strong";
@@ -146,7 +183,7 @@ export function formatQuotes(data) {
         const sim = q.similarity ?? 0;
         const ch = q.channel_name ?? "?";
         const date = fmtDate(q.episode_date);
-        const text = (q.text ?? "").slice(0, 300);
+        const text = (q.text ?? "").slice(0, 400);
         const segId = q.segment_id ?? "?";
         const contentId = q.content_id ?? "?";
         const tStart = q.timestamp_start ?? q.start_time;
@@ -155,7 +192,7 @@ export function formatQuotes(data) {
         const tier = simTier(sim);
         const tierStr = tier ? ` ${tier}` : "";
         const idStr = spkId ? ` id:${spkId}` : "";
-        const clipTag = appear === "clipped" ? " **[clipped]**" : "";
+        const clipTag = appear !== "featured" && appear ? " **[played]**" : "";
         const timeStr = tStart != null ? ` ${fmtTime(tStart)}-${fmtTime(tEnd)}` : "";
         lines.push(`${i + 1}. **${spkName}**${clipTag} (conf:${Math.round(conf * 100)}%${idStr}) on ${ch} ` +
             `[${date}${timeStr}] sim:${sim.toFixed(2)}${tierStr}`);
@@ -183,12 +220,16 @@ export function formatClaims(data) {
     for (let i = 0; i < claims.length; i++) {
         const c = claims[i];
         const sim = c.similarity;
-        const simStr = sim != null ? ` sim:${sim.toFixed(2)}` : "";
+        const tier = sim != null ? claimSimTier(sim) : "";
+        const tierStr = tier ? ` ${tier}` : "";
+        const simStr = sim != null ? ` sim:${sim.toFixed(2)}${tierStr}` : "";
         const stanceStr = c.stance ? ` [${c.stance}]` : "";
         const topicStr = c.topic ? ` (${c.topic})` : "";
         const span = [fmtDate(c.first_seen), fmtDate(c.last_seen)].filter((d) => d !== "?").join(" – ");
         lines.push(`${i + 1}. **${c.summary}**${stanceStr}${topicStr}${simStr}`);
-        lines.push(`   ${c.observation_count} observations across ${c.episode_count} episodes, ${c.channel_count} channels` +
+        const av = c.episode_count - (c.text_count ?? 0);
+        const spread = `${av} episode${av === 1 ? "" : "s"}`;
+        lines.push(`   ${c.observation_count} observations across ${spread}, ${c.channel_count} channels` +
             (span ? ` (${span})` : ""));
         if (c.entities.length) {
             lines.push(`   Entities: ${c.entities.join(", ")}`);
@@ -225,6 +266,276 @@ export function formatClaims(data) {
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
+// Claims analysis (/api/v1/analysis/claims/*)
+// ---------------------------------------------------------------------------
+export function formatClaimsTopicAnalysis(data, topic) {
+    if (!data.themes?.length) {
+        return `No claims found for "${topic}". Try a wider time window (days), lower min_observations, or a broader topic.`;
+    }
+    const m = data.quantitative_metrics ?? {};
+    const lines = [`# Claims analysis: "${topic}"`, ""];
+    const stat = (label, v) => (v != null ? `${v} ${label}` : null);
+    const summaryParts = [
+        stat("claims", m.total_claims),
+        stat("observations", m.total_observations),
+        stat("channels", m.unique_channels),
+        stat("speakers", m.unique_speakers),
+        stat("themes", m.theme_count),
+    ].filter(Boolean);
+    if (summaryParts.length)
+        lines.push(summaryParts.join(" · "), "");
+    for (const theme of data.themes) {
+        lines.push(`## ${theme.name} — ${theme.claim_count} claims, ${theme.total_observations} obs across ${theme.channel_count} channels`);
+        if (theme.entities?.length)
+            lines.push(`Entities: ${theme.entities.slice(0, 8).join(", ")}`);
+        for (const c of theme.claims) {
+            const stanceStr = c.stance ? ` [${c.stance}]` : "";
+            const span = [fmtDate(c.first_seen), fmtDate(c.last_seen)].filter((d) => d !== "?").join(" – ");
+            lines.push(`- **${c.summary}**${stanceStr} — ${c.observation_count} obs / ${c.channel_count} channels${span ? ` (${span})` : ""}`);
+            const speakers = (c.top_speakers ?? []).slice(0, 3).map((s) => `${s.name} (${s.observation_count})`);
+            if (speakers.length)
+                lines.push(`  Speakers: ${speakers.join(", ")}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+const TREND_ARROW = {
+    surging: "🚀", rising: "↗", steady: "→", declining: "↘", fading: "📉", new: "✨", no_data: "∅",
+};
+export function formatClaimsTrend(data, topic) {
+    if (data.direction === "no_data") {
+        return `No claim volume data for "${topic}" in the baseline window. Try a broader topic or longer baseline_days.`;
+    }
+    const arrow = TREND_ARROW[data.direction] ?? "";
+    const pct = data.change_pct != null ? `${data.change_pct >= 0 ? "+" : ""}${data.change_pct.toFixed(0)}%` : "n/a";
+    const lines = [
+        `# Claim trend: "${topic}" — ${arrow} ${data.direction.toUpperCase()} (${pct})`,
+        "",
+        `Recent (${data.recent.days}d): ${data.recent.claims} claims` +
+            (data.recent.new_claims != null ? ` (${data.recent.new_claims} new)` : "") +
+            `, ${data.recent.observations} obs, ${data.recent.per_day}/day`,
+        `Baseline (${data.baseline.days}d): ${data.baseline.claims} claims, ${data.baseline.observations} obs, ${data.baseline.per_day}/day`,
+    ];
+    return lines.join("\n");
+}
+export function formatClaimsContradictions(data, speaker, topic) {
+    if (data.verdict === "no_data") {
+        return `No claims found from ${speaker} on "${topic}". Try a longer time window (days) or check the speaker name.`;
+    }
+    const lines = [`# Contradiction check: ${speaker} on "${topic}"`, "", `Verdict: **${data.verdict.replace(/_/g, " ")}** (${data.claims_analyzed} claims analyzed)`, ""];
+    if (data.contradictions.length) {
+        lines.push("## Contradictions");
+        for (const c of data.contradictions) {
+            lines.push(`- [${c.severity}] ${c.description}`);
+            lines.push(`  • ${c.earlier.stance}: "${truncate(c.earlier.claim, 120)}" (${fmtDate(c.earlier.date)}, ${c.earlier.observations} obs)`);
+            lines.push(`  • ${c.later.stance}: "${truncate(c.later.claim, 120)}" (${fmtDate(c.later.date)}, ${c.later.observations} obs)`);
+        }
+        lines.push("");
+    }
+    else {
+        lines.push("No contradictions detected.", "");
+    }
+    if (data.consistent_positions.length) {
+        lines.push("## Consistent positions");
+        for (const p of data.consistent_positions) {
+            lines.push(`- [${p.stance}] "${truncate(p.claim, 120)}" (${p.observations} obs)`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatClaimsComparison(data, topic) {
+    const lines = [`# Speaker comparison on claims: "${topic}"`, ""];
+    for (const sp of data.speakers) {
+        lines.push(`## ${sp.name} — ${sp.claim_count} claims${sp.framing ? ` (${sp.framing})` : ""}`);
+        if (sp.position_summary)
+            lines.push(sp.position_summary);
+        const sb = Object.entries(sp.stance_breakdown ?? {});
+        if (sb.length)
+            lines.push(`Stance: ${sb.map(([k, v]) => `${k}: ${v}`).join(", ")}`);
+        for (const kc of (sp.key_claims ?? []).slice(0, 3)) {
+            lines.push(`- "${truncate(kc.claim, 120)}"${kc.stance ? ` [${kc.stance}]` : ""} (${kc.observations} obs)`);
+        }
+        lines.push("");
+    }
+    if (data.agreements?.length) {
+        lines.push("## Agreements", ...data.agreements.map((a) => `- ${a}`), "");
+    }
+    if (data.disagreements?.length) {
+        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${d}`), "");
+    }
+    return lines.join("\n");
+}
+export function formatChannelDossier(data) {
+    const label = data.channels.join(", ");
+    if (!data.claims_analyzed) {
+        return `No claims found from ${label} on "${data.topic}". Try a longer time window (days) or check the channel name.`;
+    }
+    const lines = [`# Channel dossier: ${label} on "${data.topic}"`, ""];
+    lines.push(`${data.claims_analyzed} claims analyzed${data.total_claims_available ? ` (${data.total_claims_available} available)` : ""}`);
+    const sb = Object.entries(data.stance_breakdown ?? {});
+    if (sb.length)
+        lines.push(`Stance: ${sb.map(([k, v]) => `${k}: ${v}`).join(", ")}`);
+    lines.push("");
+    if (data.themes.length) {
+        lines.push("## Themes");
+        for (const t of data.themes) {
+            lines.push(`- **${t.name}** — ${t.claim_count} claims, ${t.total_observations} obs`);
+            if (t.summary)
+                lines.push(`  ${truncate(t.summary, 200)}`);
+        }
+        lines.push("");
+    }
+    if (data.key_speakers.length) {
+        lines.push(`Key speakers: ${data.key_speakers.map((s) => `${s.name} (${s.claim_count})`).join(", ")}`, "");
+    }
+    if (data.key_claims.length) {
+        lines.push("## Key claims");
+        for (const kc of data.key_claims) {
+            lines.push(`- "${truncate(kc.claim, 140)}"${kc.stance ? ` [${kc.stance}]` : ""} (id:${kc.claim_id}, ${kc.observations} obs)`);
+        }
+        lines.push("");
+    }
+    if (data.trajectory.length > 1) {
+        lines.push(`Trajectory: ${data.trajectory.map((t) => `${t.month}: ${t.claims}`).join(" · ")}`);
+    }
+    return lines.join("\n");
+}
+export function formatChannelClaimsComparison(data, topic) {
+    const lines = [`# Channel comparison on claims: "${topic}"`, ""];
+    for (const ch of data.channels) {
+        lines.push(`## ${ch.name} — ${ch.claim_count} claims${ch.framing ? ` (${ch.framing})` : ""}`);
+        if (ch.position_summary)
+            lines.push(ch.position_summary);
+        const sb = Object.entries(ch.stance_breakdown ?? {});
+        if (sb.length)
+            lines.push(`Stance: ${sb.map(([k, v]) => `${k}: ${v}`).join(", ")}`);
+        if (ch.key_speakers?.length) {
+            lines.push(`Key speakers: ${ch.key_speakers.slice(0, 5).map((s) => s.name).join(", ")}`);
+        }
+        for (const kc of (ch.key_claims ?? []).slice(0, 3)) {
+            lines.push(`- "${truncate(kc.claim, 120)}"${kc.stance ? ` [${kc.stance}]` : ""} (${kc.observations} obs)`);
+        }
+        lines.push("");
+    }
+    if (data.agreements?.length) {
+        lines.push("## Agreements", ...data.agreements.map((a) => `- ${a}`), "");
+    }
+    if (data.disagreements?.length) {
+        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${d}`), "");
+    }
+    if (data.speaker_overlap?.length) {
+        lines.push("## Shared speakers");
+        for (const o of data.speaker_overlap) {
+            lines.push(`- ${o.channels.join(" & ")}: ${o.shared_speakers.join(", ")}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Claims graph (entity-centric, hierarchy/relations, leaderboard)
+// ---------------------------------------------------------------------------
+/**
+ * Per-claim content breakdown. Text (substack) observations are excluded
+ * from the tool surface, so only the AV episode count is shown.
+ */
+export function contentBreakdown(c) {
+    const av = c.episode_count - (c.text_count ?? 0);
+    return `${av} ep`;
+}
+/** One compact line for a claim in a list (used by graph/top/entity views). */
+function claimLine(c, idx) {
+    const stanceStr = c.stance ? ` [${c.stance}]` : "";
+    const span = [fmtDate(c.first_seen), fmtDate(c.last_seen)].filter((d) => d !== "?").join(" – ");
+    const sim = c.similarity;
+    const simStr = sim != null ? ` sim:${sim.toFixed(2)}` : "";
+    const prefix = idx != null ? `${idx}. ` : "- ";
+    return `${prefix}**${c.summary}**${stanceStr}${simStr}\n   id:${c.claim_id} · ${c.observation_count} obs / ${contentBreakdown(c)} / ${c.channel_count} ch${span ? ` (${span})` : ""}`;
+}
+export function formatEntitySearch(data) {
+    if (!data.entities.length) {
+        return `No entities found matching "${data.query}". Try a shorter or differently-spelled query.`;
+    }
+    const lines = [`# Entities matching "${data.query}"`, ""];
+    for (const e of data.entities) {
+        const meta = [];
+        if (e.entity_type)
+            meta.push(e.entity_type);
+        meta.push(`${e.claim_count.toLocaleString()} claims`, `${e.channel_count.toLocaleString()} channels`);
+        const span = [fmtDate(e.first_seen_date), fmtDate(e.last_seen_date)].filter((d) => d !== "?").join(" – ");
+        if (span)
+            meta.push(span);
+        lines.push(`- **${e.name}** (${meta.join(" · ")})`);
+        if (e.aliases?.length)
+            lines.push(`  Aliases: ${e.aliases.slice(0, 5).join(", ")}`);
+    }
+    lines.push("", "_Use entity_claims with the exact name for the claims themselves._");
+    return lines.join("\n");
+}
+export function formatEntityClaims(data) {
+    if (!data.entity_id) {
+        return `No entity found matching "${data.entity}". Try a different spelling, or use search_claims?entity= for fuzzy matching.`;
+    }
+    const lines = [`# Claims about ${data.entity}`];
+    const meta = [];
+    if (data.entity_type)
+        meta.push(data.entity_type);
+    if (data.claim_count_rollup != null)
+        meta.push(`${data.claim_count_rollup.toLocaleString()} claims`);
+    if (data.channel_count != null)
+        meta.push(`${data.channel_count.toLocaleString()} channels`);
+    if (meta.length)
+        lines.push(meta.join(" · "));
+    if (data.aliases?.length)
+        lines.push(`Aliases: ${data.aliases.slice(0, 6).join(", ")}`);
+    if (data.stance_distribution?.length) {
+        const total = data.stance_distribution.reduce((s, x) => s + x.count, 0) || 1;
+        const parts = data.stance_distribution
+            .map((s) => `${s.stance}: ${s.count.toLocaleString()} (${Math.round((s.count / total) * 100)}%)`);
+        lines.push(`\nStance: ${parts.join(", ")}`);
+    }
+    lines.push(`\n## Top claims (${data.claims.length} of ${data.total_claims.toLocaleString()})`);
+    data.claims.forEach((c, i) => lines.push(claimLine(c, i + 1)));
+    if (data.has_more)
+        lines.push(`\n_More available (use offset)._`);
+    return lines.join("\n");
+}
+export function formatClaimGraph(data) {
+    const lines = [`# Claim graph`, "", `**${data.claim.summary}**`,
+        `id:${data.claim.claim_id} · ${data.claim.observation_count} obs / ${data.claim.channel_count} channels`, ""];
+    if (data.parent) {
+        lines.push("## Broader claim (parent)", claimLine(data.parent), "");
+    }
+    if (data.children?.length) {
+        lines.push(`## More specific claims (${data.children.length} children)`);
+        data.children.forEach((c) => lines.push(claimLine(c)));
+        lines.push("");
+    }
+    if (data.siblings?.length) {
+        lines.push(`## Variant phrasings (${data.siblings.length} siblings)`);
+        data.siblings.forEach((c) => lines.push(claimLine(c)));
+        lines.push("");
+    }
+    if (!data.parent && !data.children?.length && !data.siblings?.length) {
+        lines.push("_No parent, children, or sibling claims found. This claim stands alone in the hierarchy._");
+    }
+    return lines.join("\n");
+}
+export function formatTopClaims(data) {
+    if (!data.claims?.length) {
+        return `No ${data.metric} claims found in the window. Try a wider days range or lower min_observations.`;
+    }
+    const label = data.metric === "contested" ? "Most contested claims" : "Most widely-spread claims";
+    const lines = [`# ${label}`, ""];
+    data.claims.forEach((c, i) => {
+        lines.push(claimLine(c, i + 1));
+        const speakers = (c.top_speakers ?? []).slice(0, 3).map((s) => `${s.name} (${s.observation_count})`);
+        if (speakers.length)
+            lines.push(`   Speakers: ${speakers.join(", ")}`);
+    });
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
 // Speaker
 // ---------------------------------------------------------------------------
 export function formatSpeaker(data) {
@@ -364,8 +675,12 @@ export function formatSegment(data) {
 export function formatAnalysis(data) {
     if (data.error)
         return `Error: ${data.error}`;
-    const lines = ["**Analysis complete**\n"];
     const q = data.quantitative_metrics ?? {};
+    const themes = data.themes ?? [];
+    if (!themes.length && !q.total_segments && !data.summary) {
+        return "No analysis results found. The topic may not appear in the corpus for the given time window. Try broader keywords or a wider date range (days=90).";
+    }
+    const lines = ["**Analysis complete**\n"];
     const centrality = q.discourse_centrality;
     if (centrality?.label) {
         lines.push(`Discourse centrality: ${centrality.label} (${centrality.level ?? "?"}/5)`);
@@ -379,7 +694,6 @@ export function formatAnalysis(data) {
         parts.push(`${q.unique_videos ?? q.episode_count} episodes`);
     if (parts.length)
         lines.push(parts.join(", ") + "\n");
-    const themes = data.themes ?? [];
     if (themes.length) {
         lines.push("**Themes:**");
         for (let i = 0; i < themes.length; i++) {
@@ -401,13 +715,62 @@ export function formatAnalysis(data) {
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
+// Frame comparison (left vs right)
+// ---------------------------------------------------------------------------
+export function formatFrameComparison(left, right, topic) {
+    if (left.error && right.error)
+        return `Error: left=${left.error}, right=${right.error}`;
+    const leftEmpty = !left.error && !(left.themes ?? []).length && !left.summary && !(left.quantitative_metrics?.total_segments);
+    const rightEmpty = !right.error && !(right.themes ?? []).length && !right.summary && !(right.quantitative_metrics?.total_segments);
+    if (leftEmpty && rightEmpty) {
+        return `No frame comparison data found for "${topic}". The topic may not appear in enough left-leaning and right-leaning channels. Try broader keywords or a wider date range (days=90).`;
+    }
+    const lines = [`**Frame comparison: ${topic}**\n`];
+    function sideBlock(label, data) {
+        if (data.error) {
+            lines.push(`### ${label}\nError: ${data.error}\n`);
+            return;
+        }
+        const q = data.quantitative_metrics ?? {};
+        const parts = [];
+        if (q.total_segments)
+            parts.push(`${q.total_segments} segments`);
+        if (q.unique_channels)
+            parts.push(`${q.unique_channels} channels`);
+        if (q.unique_speakers)
+            parts.push(`${q.unique_speakers} speakers`);
+        lines.push(`### ${label}${parts.length ? ` (${parts.join(", ")})` : ""}`);
+        const themes = (data.themes ?? []).slice(0, 8);
+        if (themes.length) {
+            lines.push("**Key themes:**");
+            for (const t of themes) {
+                const name = (t.name ?? t.theme_name ?? t.label);
+                const desc = (t.summary ?? t.description);
+                if (name)
+                    lines.push(`- **${name}**${desc ? ": " + desc.slice(0, 150) : ""}`);
+            }
+        }
+        if (data.summary) {
+            lines.push("");
+            lines.push(data.summary);
+        }
+        lines.push("");
+    }
+    sideBlock("Left-leaning media", left);
+    sideBlock("Right-leaning media", right);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
 // Comparison
 // ---------------------------------------------------------------------------
 export function formatComparison(data, topic) {
     if (data.error)
         return `Error: ${data.error}`;
-    const lines = [`**Speaker comparison: ${topic}**\n`];
     const speakers = data.speakers ?? {};
+    if (!Object.keys(speakers).length && !data.summary) {
+        return `No comparison data found for these speakers on "${topic}". The speakers may not have discussed this topic in the given time window. Try broader keywords or a wider date range.`;
+    }
+    const lines = [`**Speaker comparison: ${topic}**\n`];
     for (const [name, sp] of Object.entries(speakers)) {
         const count = sp.segment_count ?? 0;
         lines.push(`### ${name} (${count} segments)`);
@@ -439,8 +802,11 @@ export function formatComparison(data, topic) {
 export function formatDossier(data, speakerName, topic) {
     if (data.error)
         return `Error: ${data.error}`;
-    const lines = [`**Dossier: ${speakerName} on ${topic}**\n`];
     const sp = data.speaker ?? {};
+    if (!sp.segment_count && !data.summary) {
+        return `No data found for ${speakerName} on "${topic}". This speaker may not appear in the corpus for this topic. Use find_speakers to verify the name, or try broader keywords.`;
+    }
+    const lines = [`**Dossier: ${speakerName} on ${topic}**\n`];
     if (sp.occupation)
         lines.push(`*${sp.occupation}*`);
     if (sp.segment_count)
@@ -463,9 +829,12 @@ export function formatDossier(data, speakerName, topic) {
 export function formatContradictions(data, speakerName, topic) {
     if (data.error)
         return `Error: ${data.error}`;
-    const lines = [`**Contradiction check: ${speakerName} on ${topic}**\n`];
     const contras = data.contradictions ?? {};
     const verdict = contras.verdict ?? "unknown";
+    if (verdict === "unknown" && !(contras.contradictions ?? []).length && !data.summary) {
+        return `No data found for contradiction check on ${speakerName} regarding "${topic}". This speaker may not have enough content on this topic. Use find_speakers to verify the name, or try broader keywords.`;
+    }
+    const lines = [`**Contradiction check: ${speakerName} on ${topic}**\n`];
     lines.push(`**Verdict:** ${verdict.replace(/_/g, " ")}\n`);
     for (const c of contras.contradictions ?? []) {
         lines.push(`### [${c.severity ?? "?"}] ${c.description ?? "?"}`);
@@ -708,4 +1077,81 @@ export function formatAdTrends(data) {
     }
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Claim Detail
+// ---------------------------------------------------------------------------
+export function formatClaimDetail(detail, observations, related) {
+    const c = detail.claim;
+    const lines = [];
+    lines.push(`# Claim #${c.claim_id}`);
+    lines.push(`**${c.summary}**\n`);
+    const stance = c.stance ?? "unknown";
+    const topic = c.topic ?? "uncategorized";
+    lines.push(`Stance: ${stance} | Category: ${topic}`);
+    lines.push(`${c.observation_count} observations across ${c.episode_count} episodes, ${c.channel_count} channels`);
+    const span = [fmtDate(c.first_seen), fmtDate(c.last_seen)].filter(d => d !== "?").join(" – ");
+    if (span)
+        lines.push(`Period: ${span}`);
+    if (c.entities?.length) {
+        lines.push(`Entities: ${c.entities.join(", ")}`);
+    }
+    lines.push("");
+    if (c.top_speakers?.length) {
+        lines.push("**Speakers:**");
+        for (const s of c.top_speakers.slice(0, 10)) {
+            const idStr = s.identity_id ? ` (id:${s.identity_id})` : "";
+            lines.push(`- ${s.name}${idStr} — ${s.observation_count} observations`);
+        }
+        lines.push("");
+    }
+    if (c.top_channels?.length) {
+        lines.push("**Channels:**");
+        for (const ch of c.top_channels.slice(0, 10)) {
+            lines.push(`- ${ch.name} — ${ch.observation_count} observations`);
+        }
+        lines.push("");
+    }
+    const obs = observations?.observations ?? c.sample_observations ?? [];
+    if (obs.length) {
+        const label = observations ? `**Observations** (${observations.total} total)` : "**Sample Observations**";
+        lines.push(label);
+        for (const o of obs.slice(0, 20)) {
+            const date = fmtDate(o.publish_date);
+            const meta = [o.speaker_name, o.channel_name, date].filter(Boolean).join(", ");
+            lines.push(`- "${truncate(o.chunk_text, 150)}" — ${meta}`);
+            if (o.clip_url)
+                lines.push(`  🔊 ${o.clip_url}`);
+        }
+        lines.push("");
+    }
+    if (related?.claims?.length) {
+        lines.push("**Related Claims:**");
+        for (const r of related.claims) {
+            const sim = r.similarity != null ? ` (sim:${r.similarity.toFixed(2)})` : "";
+            lines.push(`- ${r.summary} — ${r.observation_count} observations${sim}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Timeline
+// ---------------------------------------------------------------------------
+export function formatTimeline(data) {
+    const buckets = data.buckets ?? [];
+    if (!buckets.length)
+        return "No data found for this topic in the given time range.";
+    const maxCount = Math.max(...buckets.map(b => b.count));
+    const barWidth = 30;
+    const lines = [
+        `**"${data.topic}"** — ${data.total} segments (${data.granularity}, ${data.search_mode})\n`,
+    ];
+    for (const b of buckets) {
+        const barLen = maxCount > 0 ? Math.round((b.count / maxCount) * barWidth) : 0;
+        const bar = "█".repeat(barLen);
+        const countStr = String(b.count).padStart(4);
+        lines.push(`${b.start}  ${countStr} ${bar}`);
+    }
+    return lines.join("\n");
+}
 //# sourceMappingURL=format.js.map