@signal4/s4 2.5.0 → 2.6.0

package/dist/format.js

@@ -1,13 +1,21 @@
-/** Shared formatting utilities — markdown output for MCP tools. */
+/**
+ * Shared formatting utilities — markdown output for MCP tools.
+ *
+ * Implements RESPONSE_SPEC.md (v1). This file is the reference renderer;
+ * the golden fixtures in test/drift/ are the byte-authoritative contract for
+ * any port. Canonical tokens, truncation markers, and footers all live
+ * here — do not invent per-tool vocabulary in handlers.
+ */
 const PUBLIC_URL = "https://api.signal4.ca";
 // ---------------------------------------------------------------------------
-// Political lean parsing
+// Political lean — single canonical bucket table (spec §5), shared with the
+// query presets so a `lean:` label always round-trips into the same filter.
 // ---------------------------------------------------------------------------
 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],
+    "center-left": [0.3, 0.42],
+    center: [0.42, 0.58],
+    "center-right": [0.58, 0.7],
     right: [0.7, 1.0],
 };
 export function parsePoliticalLean(lean) {
@@ -26,6 +34,21 @@ export function parsePoliticalLean(lean) {
     }
     return {};
 }
+export function leanLabel(lean) {
+    if (lean < 0.3)
+        return "left";
+    if (lean < 0.42)
+        return "center-left";
+    if (lean <= 0.58)
+        return "center";
+    if (lean <= 0.7)
+        return "center-right";
+    return "right";
+}
+/** `lean:0.72 (right)` — numeric always present (spec §3). */
+export function leanToken(lean) {
+    return `lean:${lean.toFixed(2)} (${leanLabel(lean)})`;
+}
 // ---------------------------------------------------------------------------
 // Primitives
 // ---------------------------------------------------------------------------
@@ -40,17 +63,24 @@ export function fmtTime(seconds) {
         return `${h}:${String(m).padStart(2, "0")}:${String(sec).padStart(2, "0")}`;
     return `${m}:${String(sec).padStart(2, "0")}`;
 }
+/** `t:512.4-598.2s (8:32-9:58)` — raw seconds, humanized in parens (spec §3). */
+export function fmtTimeRange(start, end) {
+    if (start == null)
+        return "t:n/a";
+    const rawEnd = end ?? start;
+    return `t:${start.toFixed(1)}-${rawEnd.toFixed(1)}s (${fmtTime(start)}-${fmtTime(rawEnd)})`;
+}
 export function fmtHours(seconds) {
     if (!seconds)
-        return "?";
+        return "n/a";
     const h = seconds / 3600;
     if (h >= 1)
-        return `${h.toLocaleString("en", { maximumFractionDigits: 1 })}h`;
+        return `${h.toFixed(1)}h`;
     return fmtTime(seconds);
 }
 export function fmtDuration(seconds) {
     if (!seconds)
-        return "?";
+        return "n/a";
     const m = Math.floor(seconds / 60);
     const s = Math.floor(seconds % 60);
     if (m >= 60) {
@@ -60,6 +90,32 @@ export function fmtDuration(seconds) {
     }
     return `${m}m${String(s).padStart(2, "0")}s`;
 }
+export function fmtDate(iso) {
+    return iso ? iso.slice(0, 10) : "n/a";
+}
+/** `conf:87%` or `conf:unverified` — null is NEVER 0% (spec §3/§9). */
+export function confToken(confidence) {
+    if (confidence == null)
+        return "conf:unverified";
+    return `conf:${Math.round(confidence * 100)}%`;
+}
+/** `trend:surging (+340%)` / `trend:new` / `trend:steady (n/a)` (spec §5). */
+export function trendToken(direction, changePct) {
+    if (direction === "new")
+        return "trend:new";
+    const pct = changePct != null ? `${changePct >= 0 ? "+" : ""}${changePct.toFixed(0)}%` : "n/a";
+    return `trend:${direction} (${pct})`;
+}
+/** `lang:es` when non-English; empty string for en/unknown. */
+export function langToken(language) {
+    if (!language || language === "en")
+        return "";
+    return `lang:${language}`;
+}
+export const NON_ENGLISH_NOTE = "note: non-English claim extraction is beta (elevated error rate)";
+/** Plain word-boundary truncation with no marker — ONLY for synthesized text
+ * where a retrieval pointer exists nearby. Verbatim text must use
+ * truncateWithPointer instead. */
 export function truncate(text, maxlen = 200) {
     if (!text)
         return "";
@@ -70,20 +126,75 @@ export function truncate(text, maxlen = 200) {
     const last = cut.lastIndexOf(" ");
     return (last > maxlen * 0.5 ? cut.slice(0, last) : cut) + "...";
 }
-export function fmtDate(iso) {
-    return iso ? iso.slice(0, 10) : "?";
+/** Default budget for verbatim quote text (spec §4). */
+export const QUOTE_BUDGET = 600;
+/**
+ * Truncation with mandatory marker + retrieval pointer (spec §4):
+ * `…[truncated — full text: get_segment seg:42314442]`.
+ * When no retrieval pointer exists, the text is NOT cut — nothing is
+ * silently unrecoverable.
+ */
+export function truncateWithPointer(text, pointer, maxlen = QUOTE_BUDGET) {
+    if (!text)
+        return "";
+    const clean = text.replace(/\n/g, " ").trim();
+    if (clean.length <= maxlen || !pointer)
+        return clean;
+    const cut = clean.slice(0, maxlen);
+    const last = cut.lastIndexOf(" ");
+    const body = last > maxlen * 0.5 ? cut.slice(0, last) : cut;
+    return `${body}…[truncated — full text: ${pointer}]`;
+}
+/** Rewrite LLM `{seg_N}` / `{{seg_N}}` citations to the spec token `seg:N`. */
+export function rewriteSegCitations(text) {
+    if (!text)
+        return text;
+    return text.replace(/\{\{?seg[_:](\d+)\}?\}/g, "seg:$1");
+}
+// ---------------------------------------------------------------------------
+// Footers (spec §7): provenance footer → paging note → next-call hint
+// ---------------------------------------------------------------------------
+/** `showing 20 of 249 — offset:20 for more` (spec §7.2). */
+export function pagingNote(opts) {
+    if (opts.countCapped) {
+        return `\nshowing ${opts.shown} of ${opts.total ?? "n/a"} (count_capped — true total unknown) — offset:${(opts.offset ?? 0) + opts.shown} for more`;
+    }
+    if (opts.total != null && opts.total > opts.shown + (opts.offset ?? 0)) {
+        return `\nshowing ${opts.shown} of ${opts.total} — offset:${(opts.offset ?? 0) + opts.shown} for more`;
+    }
+    return "";
+}
+/** `→ get_claim claim:1499738 include_observations:true · get_segment seg:42314442` */
+export function nextCallHint(...calls) {
+    const real = calls.filter((c) => !!c);
+    if (!real.length)
+        return "";
+    return `\n→ ${real.join(" · ")}`;
+}
+/** Assemble body + footers in spec order. */
+function withFooters(body, footer, paging, hint) {
+    return body + footer + paging + hint;
 }
 // ---------------------------------------------------------------------------
-// Quote dedup
+// Quote dedup — episode + timestamp + full-text hash (spec / audit M8)
 // ---------------------------------------------------------------------------
+function textHash(text) {
+    // djb2 — stable, dependency-free, over the FULL text so distinct quotes
+    // sharing an 80-char prefix never collapse.
+    let h = 5381;
+    for (let i = 0; i < text.length; i++) {
+        h = ((h << 5) + h + text.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16);
+}
 export function dedupQuotes(quotes) {
     const seen = new Set();
     const out = [];
     for (const q of quotes) {
         const key = [
-            q.episode_title ?? q.content_id ?? "",
+            q.content_id ?? q.episode_title ?? "",
             q.timestamp_start ?? q.start_time ?? 0,
-            (q.text ?? "").slice(0, 80),
+            textHash(q.text ?? ""),
         ].join("|");
         if (!seen.has(key)) {
             seen.add(key);
@@ -93,38 +204,6 @@ export function dedupQuotes(quotes) {
     return out;
 }
 // ---------------------------------------------------------------------------
-// Similarity tier
-// ---------------------------------------------------------------------------
-function simTier(sim) {
-    if (sim >= 0.60)
-        return "strong";
-    if (sim >= 0.45)
-        return "relevant";
-    if (sim >= 0.40)
-        return "borderline";
-    if (sim > 0)
-        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";
-    if (relevance >= 0.28)
-        return "good";
-    return "weak";
-}
-// ---------------------------------------------------------------------------
 // Clip URL
 // ---------------------------------------------------------------------------
 function clipUrl(contentId, start, end, existing) {
@@ -135,28 +214,45 @@ function clipUrl(contentId, start, end, existing) {
     }
     return "";
 }
+/** Missing clips are disclosed, never silently omitted (spec §9). */
+function clipLine(contentType, url) {
+    if (url)
+        return `clip:${url}`;
+    if (contentType === "text")
+        return "clip:n/a (text source)";
+    return "clip:n/a (unresolved segment)";
+}
 // ---------------------------------------------------------------------------
 // Empty state
 // ---------------------------------------------------------------------------
 export function emptyStateSuggestions(params) {
     const suggestions = [];
-    if (params.days && params.days < 30)
-        suggestions.push("Try a wider window: days=30");
-    else if (params.days && params.days < 90)
-        suggestions.push("Try a wider window: days=90");
-    if (params.mode === "semantic" && params.topic)
-        suggestions.push("Try hybrid mode: mode='hybrid'");
-    if (params.mode === "keyword" && params.topic)
-        suggestions.push("Try semantic mode: mode='semantic'");
-    if (params.speaker_name && params.topic)
-        suggestions.push("Drop speaker_name to search all speakers");
-    if (params.channel_name)
-        suggestions.push(`Drop channel_name to search all channels (the topic may not appear on "${params.channel_name}")`);
+    if (params.fullHistory) {
+        suggestions.push("Try lower min_similarity (e.g. 0.3) or broader phrasing of the topic");
+        if (params.speaker_name)
+            suggestions.push("Verify the speaker name with find_speakers");
+    }
+    else {
+        if (params.days && params.days < 30)
+            suggestions.push("Try a wider window: days=30");
+        else if (params.days && params.days < 90)
+            suggestions.push("Try a wider window: days=90");
+        if (params.mode === "semantic" && params.topic)
+            suggestions.push("Try hybrid mode: mode='hybrid'");
+        if (params.mode === "keyword" && params.topic)
+            suggestions.push("Try semantic mode: mode='semantic'");
+        if (params.speaker_name && params.topic)
+            suggestions.push("Drop speaker_name to search all speakers");
+        if (params.channel_name)
+            suggestions.push(`Drop channel_name to search all channels (the topic may not appear on "${params.channel_name}")`);
+    }
     const query = params.topic || params.speaker_name || "this query";
     let msg = `No matching content for "${query}"`;
     if (params.channel_name)
         msg += ` on channel "${params.channel_name}"`;
-    if (params.days)
+    if (params.fullHistory)
+        msg += ` in the full corpus history`;
+    else if (params.days)
         msg += ` in the last ${params.days} days`;
     msg += ".";
     if (suggestions.length)
@@ -166,111 +262,140 @@ export function emptyStateSuggestions(params) {
 // ---------------------------------------------------------------------------
 // Quotes
 // ---------------------------------------------------------------------------
-export function formatQuotes(data) {
+export function formatQuotes(data, footer = "", offset = 0) {
     const quotes = dedupQuotes(data.quotes ?? []);
     if (!quotes.length)
-        return "No quotes found matching your search criteria.";
+        return "No quotes found matching your search criteria." + footer;
     const total = data.total_results ?? quotes.length;
     const ms = data.processing_time_ms ?? 0;
     const lines = [`**${total} results** (showing ${quotes.length}, ${ms.toFixed(0)}ms)\n`];
     for (let i = 0; i < quotes.length; i++) {
         const q = quotes[i];
         const spk = q.speaker ?? {};
-        const spkName = spk.name ?? "Unknown";
-        const spkId = spk.identity_id;
-        const conf = spk.confidence ?? 0;
-        const appear = spk.appearance_type ?? "";
-        const sim = q.similarity ?? 0;
-        const ch = q.channel_name ?? "?";
-        const date = fmtDate(q.episode_date);
-        const text = (q.text ?? "").slice(0, 400);
-        const segId = q.segment_id ?? "?";
-        const contentId = q.content_id ?? "?";
+        const resolved = spk.identity_id != null;
+        const spkName = resolved ? (spk.name ?? `Speaker ${spk.identity_id}`) : "Unresolved speaker";
+        const spkToken = resolved ? `speaker:${spk.identity_id}` : "speaker:unresolved (diarization cluster)";
+        const sim = q.similarity;
+        const date = fmtDate(q.episode_date ?? q.publish_date);
+        const segId = q.segment_id;
         const tStart = q.timestamp_start ?? q.start_time;
         const tEnd = q.timestamp_end ?? q.end_time;
+        const tokens = [spkToken, confToken(spk.confidence)];
+        if (spk.appearance_type)
+            tokens.push(`appearance:${spk.appearance_type}`);
+        if (sim != null)
+            tokens.push(`sim:${sim.toFixed(2)}`);
+        tokens.push(`date:${date}`);
+        if (tStart != null)
+            tokens.push(fmtTimeRange(tStart, tEnd));
+        const lt = langToken(q.language);
+        if (lt)
+            tokens.push(lt);
+        if (q.channel_id != null)
+            tokens.push(`channel_id:${q.channel_id}`);
+        tokens.push(`channel:${q.channel_name ?? "n/a"}`);
+        lines.push(`${i + 1}. **${spkName}** — ${tokens.join(" ")}`);
+        lines.push(`   seg:${segId ?? "n/a"} episode:${q.content_id ?? "n/a"}`);
         const clip = clipUrl(q.content_id, tStart ?? undefined, tEnd ?? undefined, q.clip_url);
-        const tier = simTier(sim);
-        const tierStr = tier ? ` ${tier}` : "";
-        const idStr = spkId ? ` id:${spkId}` : "";
-        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}`);
-        lines.push(`   seg:${segId} | episode:${contentId}`);
-        if (clip)
-            lines.push(`   🔊 ${clip}`);
-        lines.push(`   > ${text}\n`);
-    }
-    if (total > quotes.length) {
-        lines.push(`_${total - quotes.length} more results available (use offset parameter)_`);
-    }
-    return lines.join("\n");
+        lines.push(`   ${clipLine(q.content_type, clip)}`);
+        const pointer = segId != null ? `get_segment seg:${segId}` : undefined;
+        lines.push(`   > ${truncateWithPointer(q.text, pointer)}\n`);
+    }
+    const first = quotes[0];
+    const hint = nextCallHint(first?.segment_id != null ? `get_segment seg:${first.segment_id}` : undefined, first?.speaker?.identity_id != null ? `get_speaker speaker_id:${first.speaker.identity_id}` : undefined);
+    const paging = pagingNote({ shown: quotes.length, total, offset, countCapped: data.count_capped });
+    return withFooters(lines.join("\n"), footer, paging, hint);
 }
 // ---------------------------------------------------------------------------
 // Claims
 // ---------------------------------------------------------------------------
-export function formatClaims(data) {
+/** Episode-count harmonization (spec §9): `episodes:` is the full count across
+ * modalities; the AV-only subset is labeled `av_episodes:` when text exists. */
+function episodeTokens(c) {
+    let s = `episodes:${c.episode_count}`;
+    if (c.text_count)
+        s += ` av_episodes:${c.episode_count - c.text_count}`;
+    return s;
+}
+/** One compact claim line — used on EVERY claim list surface (spec §3). */
+export function claimLine(c, idx, opts = {}) {
+    const tokens = [`claim:${c.claim_id}`];
+    if (c.stance)
+        tokens.push(`stance:${c.stance}`);
+    if (c.topic)
+        tokens.push(`topic:${c.topic}`);
+    if (c.similarity != null)
+        tokens.push(`sim:${c.similarity.toFixed(2)}`);
+    const lt = langToken(c.language);
+    if (lt)
+        tokens.push(lt);
+    const detail = [`obs:${c.observation_count}`, episodeTokens(c), `channels:${c.channel_count}`];
+    // Only render the split when BOTH counts are known — a lone count with the
+    // other defaulted to 0 would fabricate a zero (spec §4/§9 unknown ≠ zero).
+    if (opts.assertDeny && c.assert_count != null && c.deny_count != null) {
+        detail.push(`assert:${c.assert_count} deny:${c.deny_count}`);
+    }
+    if (c.first_seen)
+        detail.push(`first_seen:${fmtDate(c.first_seen)}`);
+    if (c.last_seen)
+        detail.push(`last_seen:${fmtDate(c.last_seen)}`);
+    const prefix = idx != null ? `${idx}. ` : "- ";
+    return `${prefix}**${c.summary}** — ${tokens.join(" ")}\n   ${detail.join(" ")}`;
+}
+function anyNonEnglish(claims) {
+    return claims.some((c) => c.language && c.language !== "en");
+}
+function claimSpeakerParts(speakers, n = 4) {
+    return speakers.slice(0, n)
+        .map((s) => `${s.name} (speaker:${s.identity_id ?? "n/a"}, ${s.observation_count})`)
+        .join(", ");
+}
+export function formatClaims(data, footer = "", offset = 0) {
     const claims = data.claims ?? [];
     if (!claims.length)
-        return "No claims found matching your search criteria.";
+        return "No claims found matching your search criteria." + footer;
     const total = data.total_results ?? claims.length;
     const ms = data.processing_time_ms ?? 0;
-    const mode = data.search_mode ?? "?";
+    const mode = data.search_mode ?? "n/a";
     const lines = [`**${total} claims** (showing ${claims.length}, ${mode}, ${ms.toFixed(0)}ms)\n`];
     for (let i = 0; i < claims.length; i++) {
         const c = claims[i];
-        const sim = c.similarity;
-        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}`);
-        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})` : ""));
+        lines.push(claimLine(c, i + 1));
         if (c.entities.length) {
-            lines.push(`   Entities: ${c.entities.join(", ")}`);
+            lines.push(`   entities:${c.entities.join(",")}`);
         }
         const speakers = c.top_speakers ?? [];
         if (speakers.length) {
-            const parts = speakers.slice(0, 4).map((s) => {
-                const idStr = s.identity_id ? ` id:${s.identity_id}` : "";
-                return `${s.name}${idStr} (${s.observation_count})`;
-            });
-            lines.push(`   Speakers: ${parts.join(", ")}`);
+            lines.push(`   speakers: ${claimSpeakerParts(speakers)}`);
         }
         const channels = c.top_channels ?? [];
         if (channels.length) {
-            const parts = channels.slice(0, 4).map((ch) => `${ch.name} (${ch.observation_count})`);
-            lines.push(`   Channels: ${parts.join(", ")}`);
+            const parts = channels.slice(0, 4).map((ch) => `${ch.name} (channel_id:${ch.channel_id}, ${ch.observation_count})`);
+            lines.push(`   channels: ${parts.join(", ")}`);
         }
         const obs = c.sample_observations ?? [];
         if (obs.length) {
             const o = obs[0];
             const clip = clipUrl(o.content_id, o.start_time ?? undefined, o.end_time ?? undefined, o.clip_url);
             const label = [o.speaker_name, o.channel_name, fmtDate(o.publish_date)].filter(Boolean).join(", ");
-            lines.push(`   Sample: "${truncate(o.chunk_text, 150)}" — ${label}`);
-            if (o.segment_id)
-                lines.push(`   seg:${o.segment_id} | episode:${o.content_id}`);
-            if (clip)
-                lines.push(`   🔊 ${clip}`);
+            const pointer = o.segment_id != null ? `get_segment seg:${o.segment_id}` : undefined;
+            lines.push(`   sample: "${truncateWithPointer(o.chunk_text, pointer)}" — ${label}`);
+            lines.push(`   seg:${o.segment_id ?? "n/a"} episode:${o.content_id ?? "n/a"} ${clipLine(o.content_type, clip)}`);
         }
         lines.push("");
     }
-    if (data.has_more) {
-        lines.push(`_${total - claims.length} more claims available (use offset parameter)_`);
-    }
-    return lines.join("\n");
+    if (anyNonEnglish(claims))
+        lines.push(NON_ENGLISH_NOTE, "");
+    const paging = pagingNote({ shown: claims.length, total, offset });
+    const hint = nextCallHint(`get_claim claim:${claims[0].claim_id} include_observations:true`);
+    return withFooters(lines.join("\n"), footer, paging, hint);
 }
 // ---------------------------------------------------------------------------
 // Claims analysis (/api/v1/analysis/claims/*)
 // ---------------------------------------------------------------------------
-export function formatClaimsTopicAnalysis(data, topic) {
+export function formatClaimsTopicAnalysis(data, topic, footer = "") {
     if (!data.themes?.length) {
-        return `No claims found for "${topic}". Try a wider time window (days), lower min_observations, or a broader topic.`;
+        return `No claims found for "${topic}". Try a wider time window (days), lower min_observations, or a broader topic.` + footer;
     }
     const m = data.quantitative_metrics ?? {};
     const lines = [`# Claims analysis: "${topic}"`, ""];
@@ -284,52 +409,70 @@ export function formatClaimsTopicAnalysis(data, topic) {
     ].filter(Boolean);
     if (summaryParts.length)
         lines.push(summaryParts.join(" · "), "");
+    let firstClaimId;
     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(", ")}`);
+            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})`);
+            const tokens = [`claim:${c.claim_id ?? "n/a"}`];
+            if (firstClaimId == null && c.claim_id != null)
+                firstClaimId = c.claim_id;
+            if (c.stance)
+                tokens.push(`stance:${c.stance}`);
+            const detail = [`obs:${c.observation_count}`, `channels:${c.channel_count}`];
+            if (c.first_seen)
+                detail.push(`first_seen:${fmtDate(c.first_seen)}`);
+            if (c.last_seen)
+                detail.push(`last_seen:${fmtDate(c.last_seen)}`);
+            lines.push(`- **${c.summary}** — ${tokens.join(" ")}`);
+            lines.push(`   ${detail.join(" ")}`);
+            const speakers = (c.top_speakers ?? []).slice(0, 3);
             if (speakers.length)
-                lines.push(`  Speakers: ${speakers.join(", ")}`);
+                lines.push(`   speakers: ${claimSpeakerParts(speakers, 3)}`);
         }
         lines.push("");
     }
-    return lines.join("\n");
+    const hint = nextCallHint(firstClaimId != null ? `get_claim claim:${firstClaimId} include_observations:true` : undefined);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
-const TREND_ARROW = {
-    surging: "🚀", rising: "↗", steady: "→", declining: "↘", fading: "📉", new: "✨", no_data: "∅",
-};
-export function formatClaimsTrend(data, topic) {
+export function formatClaimsTrend(data, topic, footer = "") {
     if (data.direction === "no_data") {
-        return `No claim volume data for "${topic}" in the baseline window. Try a broader topic or longer baseline_days.`;
+        return `No claim volume data for "${topic}" in the baseline window. Try a broader topic or longer baseline_days.` + footer;
     }
-    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})`,
+        `# Claim trend: "${topic}" — ${trendToken(data.direction, data.change_pct)}`,
         "",
-        `Recent (${data.recent.days}d): ${data.recent.claims} claims` +
+        `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`,
+        `baseline (${data.baseline.days}d): ${data.baseline.claims} claims, ${data.baseline.observations} obs, ${data.baseline.per_day}/day`,
     ];
-    return lines.join("\n");
+    const hint = nextCallHint(`search_claims topic:"${topic}"`, `get_timeline topic:"${topic}"`);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
-export function formatClaimsContradictions(data, speaker, topic) {
+export function formatClaimsContradictions(data, speaker, topic, footer = "") {
     if (data.verdict === "no_data") {
-        return `No claims found from ${speaker} on "${topic}". Try a longer time window (days) or check the speaker name.`;
+        return `No claims found from ${speaker} on "${topic}". Try a longer time window (days) or check the speaker name.` + footer;
     }
-    const lines = [`# Contradiction check: ${speaker} on "${topic}"`, "", `Verdict: **${data.verdict.replace(/_/g, " ")}** (${data.claims_analyzed} claims analyzed)`, ""];
+    const lines = [
+        `# Contradiction check: ${speaker} on "${topic}"`, "",
+        `Verdict: **${data.verdict.replace(/_/g, " ")}** (${data.claims_analyzed} claims analyzed)`, "",
+    ];
+    let firstClaimId;
+    // Contradiction claim texts are synthesized summaries (never quote-marked)
+    // and are NEVER truncated (spec §4/§6).
+    const side = (label, s) => {
+        if (firstClaimId == null && s.claim_id != null)
+            firstClaimId = s.claim_id;
+        return `  • ${label} — claim:${s.claim_id ?? "n/a"} stance:${s.stance} date:${fmtDate(s.date)} obs:${s.observations}\n    ${s.claim}`;
+    };
     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(side("earlier", c.earlier));
+            lines.push(side("later", c.later));
         }
         lines.push("");
     }
@@ -339,170 +482,181 @@ export function formatClaimsContradictions(data, speaker, topic) {
     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)`);
+            lines.push(`- **${p.claim}** — claim:${p.claim_id ?? "n/a"} stance:${p.stance} obs:${p.observations}`);
+            if (firstClaimId == null && p.claim_id != null)
+                firstClaimId = p.claim_id;
         }
+        lines.push("");
     }
-    return lines.join("\n");
+    lines.push("(synthesized claim — observations carry verbatim quotes)");
+    const hint = nextCallHint(firstClaimId != null ? `get_claim claim:${firstClaimId} include_observations:true` : undefined);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
-export function formatClaimsComparison(data, topic) {
+export function formatClaimsComparison(data, topic, footer = "") {
     const lines = [`# Speaker comparison on claims: "${topic}"`, ""];
+    let firstClaimId;
     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);
+            lines.push(rewriteSegCitations(sp.position_summary));
         const sb = Object.entries(sp.stance_breakdown ?? {});
         if (sb.length)
-            lines.push(`Stance: ${sb.map(([k, v]) => `${k}: ${v}`).join(", ")}`);
+            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)`);
+            // Key-claim texts are synthesized and never truncated (spec §4/§6).
+            lines.push(`- **${kc.claim}** — claim:${kc.claim_id ?? "n/a"}${kc.stance ? ` stance:${kc.stance}` : ""} obs:${kc.observations}`);
+            if (firstClaimId == null && kc.claim_id != null)
+                firstClaimId = kc.claim_id;
         }
         lines.push("");
     }
     if (data.agreements?.length) {
-        lines.push("## Agreements", ...data.agreements.map((a) => `- ${a}`), "");
+        lines.push("## Agreements", ...data.agreements.map((a) => `- ${rewriteSegCitations(a)}`), "");
     }
     if (data.disagreements?.length) {
-        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${d}`), "");
+        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${rewriteSegCitations(d)}`), "");
     }
-    return lines.join("\n");
+    lines.push("(synthesized claim — observations carry verbatim quotes)");
+    const hint = nextCallHint(firstClaimId != null ? `get_claim claim:${firstClaimId} include_observations:true` : undefined);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
-export function formatChannelDossier(data) {
+export function formatChannelDossier(data, footer = "") {
     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.`;
+        return `No claims found from ${label} on "${data.topic}". Try a longer time window (days) or check the channel name.` + footer;
     }
     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(`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(`  ${rewriteSegCitations(t.summary)}`);
         }
         lines.push("");
     }
     if (data.key_speakers.length) {
-        lines.push(`Key speakers: ${data.key_speakers.map((s) => `${s.name} (${s.claim_count})`).join(", ")}`, "");
+        lines.push(`Key speakers: ${data.key_speakers.map((s) => `${s.name} (speaker:${s.speaker_id ?? "n/a"}, ${s.claim_count})`).join(", ")}`, "");
     }
+    let firstClaimId;
     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)`);
+            if (firstClaimId == null)
+                firstClaimId = kc.claim_id;
+            lines.push(`- **${kc.claim}** — claim:${kc.claim_id}${kc.stance ? ` stance:${kc.stance}` : ""} obs:${kc.observations}`);
         }
         lines.push("");
     }
     if (data.trajectory.length > 1) {
-        lines.push(`Trajectory: ${data.trajectory.map((t) => `${t.month}: ${t.claims}`).join(" · ")}`);
+        lines.push(`Trajectory: ${data.trajectory.map((t) => `${t.month}: ${t.claims}`).join(" · ")}`, "");
     }
-    return lines.join("\n");
+    lines.push("(synthesized claim — observations carry verbatim quotes)");
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
+    const hint = nextCallHint(firstClaimId != null ? `get_claim claim:${firstClaimId} include_observations:true` : undefined);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
-export function formatChannelClaimsComparison(data, topic) {
+export function formatChannelClaimsComparison(data, topic, footer = "") {
     const lines = [`# Channel comparison on claims: "${topic}"`, ""];
+    let firstClaimId;
     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);
+            lines.push(rewriteSegCitations(ch.position_summary));
         const sb = Object.entries(ch.stance_breakdown ?? {});
         if (sb.length)
-            lines.push(`Stance: ${sb.map(([k, v]) => `${k}: ${v}`).join(", ")}`);
+            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(", ")}`);
+            lines.push(`Key speakers: ${ch.key_speakers.slice(0, 5).map((s) => `${s.name} (speaker:${s.speaker_id ?? "n/a"})`).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(`- **${kc.claim}** — claim:${kc.claim_id ?? "n/a"}${kc.stance ? ` stance:${kc.stance}` : ""} obs:${kc.observations}`);
+            if (firstClaimId == null && kc.claim_id != null)
+                firstClaimId = kc.claim_id;
         }
         lines.push("");
     }
     if (data.agreements?.length) {
-        lines.push("## Agreements", ...data.agreements.map((a) => `- ${a}`), "");
+        lines.push("## Agreements", ...data.agreements.map((a) => `- ${rewriteSegCitations(a)}`), "");
     }
     if (data.disagreements?.length) {
-        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${d}`), "");
+        lines.push("## Disagreements", ...data.disagreements.map((d) => `- ${rewriteSegCitations(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(", ")}`);
         }
+        lines.push("");
     }
-    return lines.join("\n");
+    lines.push("(synthesized claim — observations carry verbatim quotes)");
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
+    const hint = nextCallHint(firstClaimId != null ? `get_claim claim:${firstClaimId} include_observations:true` : undefined);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
 // ---------------------------------------------------------------------------
 // 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 = [];
+        const tokens = [`entity:${e.id}`];
         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(" · ")})`);
+            tokens.push(`type:${e.entity_type}`);
+        tokens.push(`claims:${e.claim_count}`, `channels:${e.channel_count}`);
+        if (e.first_seen_date)
+            tokens.push(`first_seen:${fmtDate(e.first_seen_date)}`);
+        if (e.last_seen_date)
+            tokens.push(`last_seen:${fmtDate(e.last_seen_date)}`);
+        lines.push(`- **${e.name}** — ${tokens.join(" ")}`);
         if (e.aliases?.length)
-            lines.push(`  Aliases: ${e.aliases.slice(0, 5).join(", ")}`);
+            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");
+    const hint = nextCallHint(`entity_claims entity:"${data.entities[0].name}"`);
+    return lines.join("\n") + hint;
 }
-export function formatEntityClaims(data) {
+export function formatEntityClaims(data, footer = "", offset = 0) {
     if (!data.entity_id) {
-        return `No entity found matching "${data.entity}". Try a different spelling, or use search_claims?entity= for fuzzy matching.`;
+        return `No entity found matching "${data.entity}". Try a different spelling, or use search_claims?entity= for fuzzy matching.` + footer;
     }
     const lines = [`# Claims about ${data.entity}`];
-    const meta = [];
+    const tokens = [`entity:${data.entity_id}`];
     if (data.entity_type)
-        meta.push(data.entity_type);
+        tokens.push(`type:${data.entity_type}`);
     if (data.claim_count_rollup != null)
-        meta.push(`${data.claim_count_rollup.toLocaleString()} claims`);
+        tokens.push(`claims:${data.claim_count_rollup}`);
     if (data.channel_count != null)
-        meta.push(`${data.channel_count.toLocaleString()} channels`);
-    if (meta.length)
-        lines.push(meta.join(" · "));
+        tokens.push(`channels:${data.channel_count}`);
+    lines.push(tokens.join(" "));
     if (data.aliases?.length)
-        lines.push(`Aliases: ${data.aliases.slice(0, 6).join(", ")}`);
+        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(", ")}`);
+            .map((s) => `${s.stance}:${s.count} (${Math.round((s.count / total) * 100)}%)`);
+        lines.push(`\nstance: ${parts.join(" ")}`);
     }
-    lines.push(`\n## Top claims (${data.claims.length} of ${data.total_claims.toLocaleString()})`);
+    lines.push(`\n## Top claims (${data.claims.length} of ${data.total_claims})`);
     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");
+    if (anyNonEnglish(data.claims))
+        lines.push("", NON_ENGLISH_NOTE);
+    const paging = pagingNote({ shown: data.claims.length, total: data.total_claims, offset });
+    const hint = data.claims.length
+        ? nextCallHint(`get_claim claim:${data.claims[0].claim_id} include_observations:true`)
+        : "";
+    return withFooters(lines.join("\n"), footer, paging, hint);
 }
 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`, ""];
+        `claim:${data.claim.claim_id} obs:${data.claim.observation_count} channels:${data.claim.channel_count}`, ""];
     if (data.parent) {
         lines.push("## Broader claim (parent)", claimLine(data.parent), "");
     }
@@ -519,21 +673,27 @@ export function formatClaimGraph(data) {
     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");
+    const next = data.children?.[0] ?? data.siblings?.[0] ?? data.parent;
+    const hint = nextCallHint(`get_claim claim:${data.claim.claim_id} include_observations:true`, next ? `claim_graph claim_id:${next.claim_id}` : undefined);
+    return lines.join("\n") + hint;
 }
-export function formatTopClaims(data) {
+export function formatTopClaims(data, footer = "") {
     if (!data.claims?.length) {
-        return `No ${data.metric} claims found in the window. Try a wider days range or lower min_observations.`;
+        return `No ${data.metric} claims found in the window. Try a wider days range or lower min_observations.` + footer;
     }
-    const label = data.metric === "contested" ? "Most contested claims" : "Most widely-spread claims";
+    const contested = data.metric === "contested";
+    const label = 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})`);
+        lines.push(claimLine(c, i + 1, { assertDeny: contested }));
+        const speakers = (c.top_speakers ?? []).slice(0, 3);
         if (speakers.length)
-            lines.push(`   Speakers: ${speakers.join(", ")}`);
+            lines.push(`   speakers: ${claimSpeakerParts(speakers, 3)}`);
     });
-    return lines.join("\n");
+    if (anyNonEnglish(data.claims))
+        lines.push("", NON_ENGLISH_NOTE);
+    const hint = nextCallHint(`get_claim claim:${data.claims[0].claim_id} include_observations:true`);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
 // ---------------------------------------------------------------------------
 // Speaker
@@ -561,31 +721,31 @@ export function formatSpeaker(data) {
         lines.push(`**Stats:** ${stats.join(", ")}`);
     const sid = data.speaker_id ?? data.id;
     if (sid)
-        lines.push(`Speaker ID: \`${sid}\``);
+        lines.push(`speaker:${sid}`);
     const topChannels = data.top_channels ?? [];
     if (topChannels.length) {
         lines.push("\n**Top Channels:**");
         for (const ch of topChannels.slice(0, 8)) {
-            lines.push(`- ${ch.name ?? "?"} (ID: ${ch.channel_id ?? "?"}, ${ch.count ?? 0} appearances)`);
+            lines.push(`- ${ch.name ?? "n/a"} — channel_id:${ch.channel_id ?? "n/a"} appearances:${ch.count ?? 0}`);
         }
     }
     const related = data.related_speakers ?? [];
     if (related.length) {
         lines.push("\n**Co-appearances:**");
         for (const r of related.slice(0, 10)) {
-            const count = r.appearance_count ?? r.co_appearances ?? "?";
-            lines.push(`- ${r.name ?? "?"} (${count})`);
+            const count = r.appearance_count ?? r.co_appearances ?? "n/a";
+            lines.push(`- ${r.name ?? "n/a"} — speaker:${r.speaker_id ?? r.identity_id ?? "n/a"} count:${count}`);
         }
     }
     const recent = data.recent_episodes ?? [];
     if (recent.length) {
         lines.push("\n**Recent Episodes:**");
         for (const ep of recent.slice(0, 8)) {
-            const date = fmtDate(ep.publish_date);
-            lines.push(`- [${date}] ${ep.channel_name ?? "?"} — ${ep.title ?? "?"}`);
+            lines.push(`- date:${fmtDate(ep.publish_date)} episode:${ep.content_id ?? "n/a"} ${ep.channel_name ?? "n/a"} — ${ep.title ?? "n/a"}`);
         }
     }
-    return lines.join("\n");
+    const hint = nextCallHint(sid ? `search_quotes speaker_id:${sid} sort:chronological` : undefined, recent[0]?.content_id ? `get_episode content_id:${recent[0].content_id}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Channel
@@ -602,12 +762,10 @@ export function formatChannel(data) {
         meta.push(`**Language:** ${data.language}`);
     if (meta.length)
         lines.push(meta.join(" | "));
-    lines.push(`Channel ID: \`${data.channel_id ?? data.id ?? ""}\``);
-    const lean = data.political_lean;
-    if (lean != null) {
-        const label = lean <= 0.35 ? "left" : lean <= 0.45 ? "center-left" : lean <= 0.55 ? "center" : lean <= 0.65 ? "center-right" : "right";
-        lines.push(`**Political lean:** ${lean.toFixed(2)} (${label})`);
-    }
+    const cid = data.channel_id ?? data.id;
+    lines.push(`channel_id:${cid ?? "n/a"}`);
+    if (data.political_lean != null)
+        lines.push(leanToken(data.political_lean));
     if (data.description)
         lines.push(`\n${data.description.slice(0, 500)}`);
     if (data.primary_url)
@@ -622,52 +780,58 @@ export function formatChannel(data) {
         if (parts.length)
             lines.push(`\n**Ranking:** ${parts.join(", ")}`);
         for (const cp of (ranking.chart_positions ?? []).slice(0, 5)) {
-            lines.push(`- Chart: ${cp.platform ?? "?"} ${cp.country ?? "?"}/${cp.category ?? "?"} #${cp.rank ?? "?"}`);
+            lines.push(`- Chart: ${cp.platform ?? "n/a"} ${cp.country ?? "n/a"}/${cp.category ?? "n/a"} #${cp.rank ?? "n/a"}`);
         }
     }
     const speakers = data.regular_speakers ?? data.speakers ?? [];
     if (speakers.length) {
         lines.push("\n**Speakers:**");
         for (const s of speakers.slice(0, 10)) {
-            const count = s.appearance_count ?? s.count ?? "?";
-            lines.push(`- ${s.name ?? "?"} (${count} appearances)`);
+            const count = s.appearance_count ?? s.count ?? "n/a";
+            lines.push(`- ${s.name ?? "n/a"} — speaker:${s.speaker_id ?? s.identity_id ?? "n/a"} appearances:${count}`);
         }
     }
     const recent = data.recent_episodes ?? [];
     if (recent.length) {
         lines.push("\n**Recent Episodes:**");
         for (const ep of recent.slice(0, 8)) {
-            lines.push(`- [${fmtDate(ep.publish_date)}] ${ep.title ?? "?"}`);
+            lines.push(`- date:${fmtDate(ep.publish_date)} episode:${ep.content_id ?? "n/a"} ${ep.title ?? "n/a"}`);
         }
     }
-    return lines.join("\n");
+    const hint = nextCallHint(cid != null ? `search_quotes channel_id:${cid}` : undefined, recent[0]?.content_id ? `get_episode content_id:${recent[0].content_id}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Segment
 // ---------------------------------------------------------------------------
 export function formatSegment(data) {
-    const segId = data.segment_id ?? "?";
-    const spk = data.speaker_name ?? "Unknown";
-    const ch = data.channel_name ?? "?";
-    const title = data.episode_title ?? "?";
-    const contentId = data.content_id ?? "?";
-    const date = fmtDate(data.episode_date);
-    const tStart = data.start_time;
-    const tEnd = data.end_time;
-    const clip = clipUrl(data.content_id, tStart ?? undefined, tEnd ?? undefined, data.clip_url);
+    const segId = data.segment_id;
+    const spk = data.speaker ?? {};
+    const spkName = data.speaker_name ?? spk.name;
+    const resolved = spk.identity_id != null;
+    const clip = clipUrl(data.content_id, data.start_time ?? undefined, data.end_time ?? undefined, data.clip_url);
+    const speakerTokens = [];
+    if (resolved)
+        speakerTokens.push(`speaker:${spk.identity_id}`);
+    else if (!spkName)
+        speakerTokens.push("speaker:unresolved (diarization cluster)");
+    if (spk.confidence !== undefined || resolved)
+        speakerTokens.push(confToken(spk.confidence));
+    if (spk.appearance_type)
+        speakerTokens.push(`appearance:${spk.appearance_type}`);
     const lines = [
-        `**Segment ${segId}**`,
-        `- **Speaker:** ${spk}`,
-        `- **Channel:** ${ch}`,
-        `- **Episode:** ${title} (\`${contentId}\`)`,
-        `- **Date:** ${date}`,
+        `**Segment ${segId ?? "n/a"}**`,
+        `- **Speaker:** ${spkName ?? "unresolved (diarization cluster)"}${speakerTokens.length ? ` — ${speakerTokens.join(" ")}` : ""}`,
+        `- **Channel:** ${data.channel_name ?? "n/a"}${data.channel_id != null ? ` — channel_id:${data.channel_id}` : ""}`,
+        `- **Episode:** ${data.episode_title ?? "n/a"} — episode:${data.content_id ?? "n/a"}`,
+        `- **Date:** date:${fmtDate(data.episode_date)}`,
     ];
-    if (tStart != null)
-        lines.push(`- **Time:** ${fmtTime(tStart)} – ${fmtTime(tEnd)}`);
-    if (clip)
-        lines.push(`- **Audio clip:** ${clip}`);
+    if (data.start_time != null)
+        lines.push(`- **Time:** ${fmtTimeRange(data.start_time, data.end_time)}`);
+    lines.push(`- ${clipLine(data.content_type, clip)}`);
     lines.push(`\n> ${data.text ?? ""}`);
-    return lines.join("\n");
+    const hint = nextCallHint(segId != null ? `get_thread segment_id:${segId}` : undefined, data.content_id ? `get_episode content_id:${data.content_id}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Analysis
@@ -683,7 +847,7 @@ export function formatAnalysis(data) {
     const lines = ["**Analysis complete**\n"];
     const centrality = q.discourse_centrality;
     if (centrality?.label) {
-        lines.push(`Discourse centrality: ${centrality.label} (${centrality.level ?? "?"}/5)`);
+        lines.push(`Discourse centrality: ${centrality.label} (${centrality.level ?? "n/a"}/5)`);
     }
     const parts = [];
     if (q.total_segments)
@@ -704,19 +868,45 @@ export function formatAnalysis(data) {
             const count = (t.segment_count ?? t.count);
             const countStr = count ? ` (${count} segments)` : "";
             lines.push(`${i + 1}. ${name}${countStr}`);
-            const desc = (t.summary ?? t.description);
+            const desc = rewriteSegCitations((t.summary ?? t.description));
             if (desc)
-                lines.push(`   ${desc.slice(0, 200)}`);
+                lines.push(`   ${desc}`);
         }
         lines.push("");
     }
     if (data.summary)
-        lines.push(data.summary);
-    return lines.join("\n");
+        lines.push(rewriteSegCitations(data.summary));
+    const firstSeg = (data.segment_ids ?? [])[0];
+    const hint = nextCallHint(firstSeg != null ? `get_segment seg:${firstSeg}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Frame comparison (left vs right)
 // ---------------------------------------------------------------------------
+// LLM theme summaries can still hit the token ceiling and stop mid-sentence or
+// mid-citation ("...to leave {seg_4225"). Drop any trailing incomplete {seg_...}
+// citation, then cut back to the last complete sentence and flag the trim.
+function trimTruncatedSummary(text) {
+    if (!text)
+        return text;
+    let s = text.trimEnd();
+    let trimmed = false;
+    // Dangling open citation at the end (an unclosed "{...")
+    const lastOpen = s.lastIndexOf("{");
+    if (lastOpen !== -1 && s.indexOf("}", lastOpen) === -1) {
+        s = s.slice(0, lastOpen).trimEnd();
+        trimmed = true;
+    }
+    // Mid-sentence cut: back up to the last sentence/citation boundary.
+    if (!/[.!?…}"”')\]]$/.test(s)) {
+        const m = s.match(/^[\s\S]*[.!?…}]/);
+        if (m) {
+            s = m[0];
+            trimmed = true;
+        }
+    }
+    return trimmed ? `${s} [summary truncated]` : s;
+}
 export function formatFrameComparison(left, right, topic) {
     if (left.error && right.error)
         return `Error: left=${left.error}, right=${right.error}`;
@@ -726,6 +916,7 @@ export function formatFrameComparison(left, right, topic) {
         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`];
+    let firstSeg;
     function sideBlock(label, data) {
         if (data.error) {
             lines.push(`### ${label}\nError: ${data.error}\n`);
@@ -740,25 +931,34 @@ export function formatFrameComparison(left, right, topic) {
         if (q.unique_speakers)
             parts.push(`${q.unique_speakers} speakers`);
         lines.push(`### ${label}${parts.length ? ` (${parts.join(", ")})` : ""}`);
-        const themes = (data.themes ?? []).slice(0, 8);
+        // Render EVERY theme, numbered — the synthesis prose refers to themes by
+        // number, so truncating the list left it citing "Themes 12–19" that were
+        // never displayed. Include per-theme prose and segment citations so a
+        // reader can verify any claim (seg:<id> works with get_segment).
+        const themes = data.themes ?? [];
         if (themes.length) {
             lines.push("**Key themes:**");
-            for (const t of themes) {
+            themes.forEach((t, i) => {
                 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) : ""}`);
-            }
+                const desc = rewriteSegCitations(trimTruncatedSummary((t.summary ?? t.description)));
+                const segs = t.segment_count ? ` — ${t.segment_count} segments` : "";
+                const cites = (t.segment_ids ?? []).slice(0, 4).map((id) => `seg:${id}`).join(" ");
+                if (firstSeg == null && (t.segment_ids ?? []).length)
+                    firstSeg = t.segment_ids[0];
+                lines.push(`${i + 1}. **${name ?? `Theme ${i + 1}`}**${segs}${desc ? ": " + desc : ""}${cites ? ` [${cites}]` : ""}`);
+            });
         }
         if (data.summary) {
             lines.push("");
-            lines.push(data.summary);
+            lines.push(rewriteSegCitations(data.summary));
         }
         lines.push("");
     }
     sideBlock("Left-leaning media", left);
     sideBlock("Right-leaning media", right);
-    return lines.join("\n");
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
+    const hint = nextCallHint(firstSeg != null ? `get_segment seg:${firstSeg}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Comparison
@@ -773,11 +973,12 @@ export function formatComparison(data, topic) {
     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)`);
+        const gated = sp.gated_out ? `, ${sp.gated_out} weak matches excluded` : "";
+        lines.push(`### ${name} (${count} on-topic segments${gated})`);
         if (sp.position_summary)
-            lines.push(`**Position:** ${sp.position_summary}`);
+            lines.push(`**Position:** ${rewriteSegCitations(sp.position_summary)}`);
         if (sp.framing)
-            lines.push(`**Framing:** ${sp.framing}`);
+            lines.push(`**Framing:** ${rewriteSegCitations(sp.framing)}`);
         if (sp.tone)
             lines.push(`**Tone:** ${sp.tone}`);
         const claims = sp.key_claims ?? [];
@@ -785,20 +986,45 @@ export function formatComparison(data, topic) {
             lines.push("**Key claims:**");
             for (const c of claims.slice(0, 5)) {
                 const text = typeof c === "string" ? c : c.claim ?? String(c);
-                lines.push(`- ${text}`);
+                const cid = typeof c === "object" && c ? c.claim_id : undefined;
+                const idTok = cid != null ? ` — claim:${cid}` : "";
+                lines.push(`- ${rewriteSegCitations(text)}${idTok}`);
             }
         }
         lines.push("");
     }
     if (data.comparison || data.summary) {
-        lines.push("---");
-        lines.push(data.comparison ?? data.summary ?? "");
+        lines.push("## Synthesis");
+        lines.push(rewriteSegCitations(data.comparison ?? data.summary ?? ""));
+        lines.push("");
     }
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
 // Dossier
 // ---------------------------------------------------------------------------
+// Render the retrieval/provenance line shared by dossier and contradictions:
+// window searched, dates the evidence spans, match strength, gating stats.
+function pushRetrievalProvenance(lines, ret) {
+    if (!ret)
+        return;
+    const parts = [];
+    if (ret.window_days)
+        parts.push(`window: last ${ret.window_days} days`);
+    if (ret.date_range?.length === 2)
+        parts.push(`evidence spans ${ret.date_range[0].slice(0, 10)} → ${ret.date_range[1].slice(0, 10)}`);
+    if (ret.similarity_range?.length === 2)
+        parts.push(`relevance ${ret.similarity_range[0].toFixed(2)}–${ret.similarity_range[1].toFixed(2)}`);
+    if (ret.gated_out)
+        parts.push(`${ret.gated_out} weak matches (<${(ret.min_similarity ?? 0.4).toFixed(2)}) excluded`);
+    if (ret.weak_match_count)
+        parts.push(`${ret.weak_match_count} weak matches (<0.40) included`);
+    if (parts.length)
+        lines.push(`_${parts.join(" · ")}_`);
+    if (ret.thin_evidence)
+        lines.push(`_⚠ Thin evidence: fewer than 5 on-topic segments met the relevance threshold — treat conclusions as provisional._`);
+}
 export function formatDossier(data, speakerName, topic) {
     if (data.error)
         return `Error: ${data.error}`;
@@ -810,17 +1036,23 @@ export function formatDossier(data, speakerName, topic) {
     if (sp.occupation)
         lines.push(`*${sp.occupation}*`);
     if (sp.segment_count)
-        lines.push(`${sp.segment_count} segments analyzed\n`);
+        lines.push(`${sp.segment_count} segments analyzed`);
+    // Show the working: window searched, dates the evidence actually spans, and
+    // match strength — a dossier built from one recent episode must not pass
+    // for a longitudinal record.
+    pushRetrievalProvenance(lines, sp.retrieval);
+    lines.push("");
     const contras = data.contradictions;
     if (contras?.verdict) {
         lines.push(`**Contradiction check:** ${contras.verdict.replace(/_/g, " ")}`);
         for (const c of contras.contradictions ?? []) {
-            lines.push(`- [${c.severity ?? "?"}] ${c.description ?? "?"}`);
+            lines.push(`- [${c.severity ?? "n/a"}] ${c.description ?? "n/a"}`);
         }
         lines.push("");
     }
     if (data.summary)
-        lines.push(data.summary);
+        lines.push(rewriteSegCitations(data.summary), "");
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
@@ -835,13 +1067,15 @@ export function formatContradictions(data, speakerName, topic) {
         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`];
+    pushRetrievalProvenance(lines, data.speaker?.retrieval);
     lines.push(`**Verdict:** ${verdict.replace(/_/g, " ")}\n`);
+    // Contradiction evidence is NEVER truncated (spec §4).
     for (const c of contras.contradictions ?? []) {
-        lines.push(`### [${c.severity ?? "?"}] ${c.description ?? "?"}`);
+        lines.push(`### [${c.severity ?? "n/a"}] ${c.description ?? "n/a"}`);
         if (c.earlier?.claim)
-            lines.push(`**Earlier** (${c.earlier.date ?? "?"}): ${c.earlier.claim}`);
+            lines.push(`**Earlier** (date:${fmtDate(c.earlier.date)}): ${rewriteSegCitations(c.earlier.claim)}`);
         if (c.later?.claim)
-            lines.push(`**Later** (${c.later.date ?? "?"}): ${c.later.claim}`);
+            lines.push(`**Later** (date:${fmtDate(c.later.date)}): ${rewriteSegCitations(c.later.claim)}`);
         if (c.possible_context)
             lines.push(`*Context:* ${c.possible_context}`);
         lines.push("");
@@ -850,18 +1084,22 @@ export function formatContradictions(data, speakerName, topic) {
     if (consistent.length) {
         lines.push("**Consistent positions:**");
         for (const pos of consistent)
-            lines.push(`- ${pos}`);
+            lines.push(`- ${rewriteSegCitations(pos)}`);
         lines.push("");
     }
     const timeline = data.stance_timeline ?? [];
     if (timeline.length) {
         lines.push("**Stance timeline:**");
         for (const t of timeline.slice(0, 20)) {
-            lines.push(`- ${t.segment_id ?? "?"}: ${t.stance ?? "?"} — ${(t.claim ?? "").slice(0, 100)}`);
+            const pointer = t.segment_id != null ? `get_segment seg:${t.segment_id}` : undefined;
+            lines.push(`- seg:${t.segment_id ?? "n/a"} stance:${t.stance ?? "n/a"} — ${truncateWithPointer(t.claim, pointer)}`);
         }
+        lines.push("");
     }
-    if (data.summary && !(contras.contradictions ?? []).length)
-        lines.push(data.summary);
+    lines.push("quotes are model-extracted; verify via cited seg: before publication");
+    // Note: data.summary is deliberately NOT appended — the backend builds it
+    // from the same verdict/contradictions/consistent_positions fields rendered
+    // above, so it duplicated the report as a dangling stub.
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
@@ -871,13 +1109,13 @@ export function formatBriefing(data) {
     const lines = [];
     const stats = data.statistics ?? {};
     if (stats.total_episodes || stats.total_channels) {
-        lines.push(`**Briefing:** ${stats.total_episodes ?? "?"} episodes, ` +
-            `${stats.total_channels ?? "?"} channels, ` +
+        lines.push(`**Briefing:** ${stats.total_episodes ?? "n/a"} episodes, ` +
+            `${stats.total_channels ?? "n/a"} channels, ` +
             `${(stats.total_duration_hours ?? 0).toFixed(0)}h\n`);
     }
     for (let i = 0; i < (data.topics ?? []).length; i++) {
         const t = data.topics[i];
-        const title = t.title ?? t.label ?? "?";
+        const title = t.title ?? t.label ?? "n/a";
         const segs = t.segment_count ?? 0;
         const chs = t.channel_count ?? 0;
         const score = t.score ?? 0;
@@ -887,8 +1125,16 @@ export function formatBriefing(data) {
             lines.push(`   ${truncate(summary, 250)}`);
         for (const c of (t.citations ?? []).slice(0, 2)) {
             const label = [c.speaker_name, c.channel_name].filter(Boolean).join(" on ");
+            const ids = [];
+            if (c.segment_id != null)
+                ids.push(`seg:${c.segment_id}`);
+            if (c.content_id)
+                ids.push(`episode:${c.content_id}`);
+            if (c.publish_date)
+                ids.push(`date:${fmtDate(c.publish_date)}`);
+            const pointer = c.segment_id != null ? `get_segment seg:${c.segment_id}` : undefined;
             if (c.text)
-                lines.push(`   "${truncate(c.text, 120)}" — ${label}`);
+                lines.push(`   "${truncateWithPointer(c.text, pointer)}" — ${label}${ids.length ? ` (${ids.join(" ")})` : ""}`);
         }
         lines.push("");
     }
@@ -896,18 +1142,20 @@ export function formatBriefing(data) {
     if (events.length) {
         lines.push("**Key events:**");
         for (const ev of events.slice(0, 5)) {
-            lines.push(`- ${ev.title ?? ev.description ?? "?"}`);
+            lines.push(`- ${ev.title ?? ev.description ?? "n/a"}`);
         }
         lines.push("");
     }
     const speakers = data.key_speakers ?? [];
     if (speakers.length) {
-        const parts = speakers.slice(0, 8).map((s) => `${s.name ?? "?"} (${s.segment_count ?? "?"} seg)`);
+        const parts = speakers.slice(0, 8).map((s) => `${s.name ?? "n/a"} (speaker:${s.speaker_id ?? "n/a"}, ${s.segment_count ?? "n/a"} seg)`);
         lines.push(`**Key speakers:** ${parts.join(", ")}\n`);
     }
     if (data.synthesis)
-        lines.push(data.synthesis);
-    return lines.join("\n") || "No briefing data available.";
+        lines.push(rewriteSegCitations(data.synthesis));
+    const firstTopic = data.topics?.[0];
+    const hint = nextCallHint(firstTopic?.title ? `analyze_topic query:"${firstTopic.title}"` : undefined);
+    return (lines.join("\n") || "No briefing data available.") + hint;
 }
 export function formatDiscourseSummary(data) {
     const lines = [];
@@ -935,7 +1183,7 @@ export function formatDiscourseSummary(data) {
     if (speakers.length) {
         lines.push("\n**Key Speakers:**");
         for (const s of speakers.slice(0, 10)) {
-            lines.push(`- ${s.name ?? "?"}`);
+            lines.push(`- ${s.name ?? "n/a"} (speaker:${s.speaker_id ?? "n/a"})`);
         }
     }
     return lines.join("\n") || "No discourse data available.";
@@ -954,45 +1202,48 @@ export function formatTopics(topics, totalClusters, partition, query) {
             return `No topics matched "${query}" above the relevance threshold.`;
     }
     const lines = [
-        `**${filtered.length} of ${totalClusters ?? filtered.length} topic clusters** (${partition ?? "?"})\n`,
+        `**${filtered.length} of ${totalClusters ?? filtered.length} topic clusters** (${partition ?? "n/a"})\n`,
     ];
     for (let i = 0; i < filtered.length; i++) {
         const t = filtered[i];
-        const catTag = t.category ? ` [${t.category}]` : "";
-        const rel = t.relevance;
-        const relTag = rel != null ? ` (${topicRelevanceTier(rel)} match)` : "";
-        lines.push(`${i + 1}. **${t.title ?? "?"}**${catTag}${relTag}`);
+        const tokens = [`cluster_id:${t.cluster_id ?? "n/a"}`];
+        if (t.category)
+            tokens.push(`category:${t.category}`);
+        if (t.relevance != null)
+            tokens.push(`sim:${t.relevance.toFixed(2)}`);
+        lines.push(`${i + 1}. **${t.title ?? "n/a"}** — ${tokens.join(" ")}`);
         lines.push(`   ${t.segment_count ?? 0} segments across ${t.channel_count ?? 0} channels`);
         const speakers = t.top_speakers ?? [];
         if (speakers.length) {
-            lines.push(`   Voices: ${speakers.slice(0, 3).map((s) => s.name ?? "?").join(", ")}`);
+            lines.push(`   voices: ${speakers.slice(0, 3).map((s) => `${s.name ?? "n/a"} (speaker:${s.speaker_id ?? "n/a"})`).join(", ")}`);
         }
         const topSeg = (t.top_segments ?? [])[0];
         if (topSeg?.text) {
-            lines.push(`   "${truncate(topSeg.text, 120)}" — ${topSeg.channel_name ?? ""}`);
+            const pointer = topSeg.segment_id != null ? `get_segment seg:${topSeg.segment_id}` : undefined;
+            lines.push(`   "${truncateWithPointer(topSeg.text, pointer)}" — ${topSeg.channel_name ?? ""} (seg:${topSeg.segment_id ?? "n/a"})`);
         }
         lines.push("");
     }
-    lines.push("---");
-    lines.push("Use `search_quotes` to find specific quotes within a topic, or `analyze_topic` for an AI-generated summary with themes and key voices.");
-    return lines.join("\n");
+    const firstSeg = filtered.map((t) => (t.top_segments ?? [])[0]?.segment_id).find((id) => id != null);
+    const hint = nextCallHint(filtered[0]?.title ? `analyze_topic query:"${filtered[0].title}"` : undefined, firstSeg != null ? `get_segment seg:${firstSeg}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Ad formatters
 // ---------------------------------------------------------------------------
 export function formatAdStats(data) {
     const lines = ["# Ad Analytics Overview\n"];
-    lines.push(`**${(data.total_ad_hashes ?? 0).toLocaleString()}** confirmed ad sentences`);
+    lines.push(`**${data.total_ad_hashes ?? 0}** confirmed ad sentences`);
     lines.push(`**${data.total_brands ?? 0}** advertisers (+ ${(data.total_advertisers ?? 0) - (data.total_brands ?? 0)} network promos)`);
-    lines.push(`**${(data.ad_reads_in_window ?? 0).toLocaleString()}** ad reads in last ${data.time_window_days ?? 30}d`);
-    lines.push(`**${(data.episodes_with_ads_in_window ?? 0).toLocaleString()}** episodes with ads`);
+    lines.push(`**${data.ad_reads_in_window ?? 0}** ad reads in last ${data.time_window_days ?? 30}d`);
+    lines.push(`**${data.episodes_with_ads_in_window ?? 0}** episodes with ads`);
     lines.push(`**${data.avg_ad_read_duration_seconds ?? 0}s** avg ad read duration`);
     const byCat = data.ads_by_category ?? data.by_category ?? {};
     if (Object.keys(byCat).length) {
         lines.push("\n**By Category:**");
         const sorted = Object.entries(byCat).sort((a, b) => b[1] - a[1]);
         for (const [cat, count] of sorted) {
-            lines.push(`- ${cat}: ${count.toLocaleString()}`);
+            lines.push(`- ${cat}: ${count}`);
         }
     }
     const top = data.top_advertisers ?? [];
@@ -1000,11 +1251,13 @@ export function formatAdStats(data) {
         lines.push("\n**Top Advertisers:**");
         for (let i = 0; i < top.length; i++) {
             const a = top[i];
-            lines.push(`${i + 1}. **${a.name}** (${a.category ?? "?"}) — ` +
-                `${a.total_episode_count.toLocaleString()} episodes, ${a.total_channel_count} channels`);
+            lines.push(`${i + 1}. **${a.name}** — advertiser:${a.id ?? "n/a"} category:${a.category ?? "n/a"} ` +
+                `episodes:${a.total_episode_count} channels:${a.total_channel_count}`);
         }
     }
-    return lines.join("\n");
+    const firstId = top.find((a) => a.id != null)?.id;
+    const hint = nextCallHint(firstId != null ? `get_ad_analytics view:advertiser advertiser_id:${firstId}` : "get_ad_analytics view:advertisers");
+    return lines.join("\n") + hint;
 }
 export function formatAdvertiserList(data) {
     const advs = data.advertisers ?? [];
@@ -1015,29 +1268,33 @@ export function formatAdvertiserList(data) {
     for (let i = 0; i < advs.length; i++) {
         const a = advs[i];
         const aliases = a.aliases?.length ? ` (aka ${a.aliases.slice(0, 3).join(", ")})` : "";
-        lines.push(`${i + 1}. **${a.name}**${aliases} [${a.category ?? "?"}] — ` +
-            `${a.total_episode_count.toLocaleString()} episodes, ${a.total_channel_count} channels`);
+        lines.push(`${i + 1}. **${a.name}**${aliases} — advertiser:${a.id ?? "n/a"} category:${a.category ?? "n/a"} ` +
+            `episodes:${a.total_episode_count} channels:${a.total_channel_count}`);
     }
-    return lines.join("\n");
+    const paging = pagingNote({ shown: advs.length, total });
+    const firstId = advs.find((a) => a.id != null)?.id;
+    const hint = nextCallHint(firstId != null ? `get_ad_analytics view:advertiser advertiser_id:${firstId}` : undefined);
+    return lines.join("\n") + paging + hint;
 }
 export function formatAdvertiserDetail(data) {
     if (data.error)
         return `Error: ${data.error}`;
     const lines = [`# ${data.name}`];
+    lines.push(`advertiser:${data.id ?? "n/a"}`);
     if (data.category)
         lines.push(`**Category:** ${data.category}`);
     if (data.aliases?.length)
         lines.push(`**Also known as:** ${data.aliases.join(", ")}`);
     if (data.website)
         lines.push(`**Website:** ${data.website}`);
-    lines.push(`**Episodes:** ${data.total_episode_count.toLocaleString()} | **Channels:** ${data.total_channel_count}`);
+    lines.push(`**Episodes:** ${data.total_episode_count} | **Channels:** ${data.total_channel_count}`);
     if (data.first_seen)
-        lines.push(`**Active:** ${fmtDate(data.first_seen)} — ${fmtDate(data.last_seen)}`);
+        lines.push(`**Active:** date:${fmtDate(data.first_seen)} — date:${fmtDate(data.last_seen)}`);
     const channels = data.top_channels ?? [];
     if (channels.length) {
         lines.push("\n**Top Channels:**");
         for (const ch of channels.slice(0, 10)) {
-            lines.push(`- ${ch.name} (${ch.platform ?? "?"}) — ${ch.episode_count} episodes`);
+            lines.push(`- ${ch.name} — channel_id:${ch.channel_id ?? "n/a"} platform:${ch.platform ?? "n/a"} episodes:${ch.episode_count}`);
         }
     }
     const samples = data.sample_reads ?? [];
@@ -1045,113 +1302,135 @@ export function formatAdvertiserDetail(data) {
         lines.push("\n**Recent Ad Reads:**");
         for (const s of samples) {
             const dur = s.duration_seconds ? ` (${s.duration_seconds}s)` : "";
-            lines.push(`- [${fmtDate(s.date)}] ${s.episode_title ?? "?"}${dur}`);
+            lines.push(`- date:${fmtDate(s.date)} ${s.episode_title ?? "n/a"}${dur}`);
+            // Ad-read text has no per-read retrieval tool — never cut it silently.
             if (s.text)
-                lines.push(`  > ${s.text.slice(0, 200)}`);
+                lines.push(`  > ${s.text}`);
         }
     }
-    return lines.join("\n");
+    const firstCh = channels.find((ch) => ch.channel_id != null)?.channel_id;
+    const hint = nextCallHint(firstCh != null ? `get_ad_analytics view:channel channel_id:${firstCh}` : undefined);
+    return lines.join("\n") + hint;
 }
 export function formatChannelAds(data) {
     if (data.error)
         return `Error: ${data.error}`;
     const chName = data.channel?.name ?? data.channel_name ?? "Channel";
     const lines = [`# Ads on ${chName}`];
-    lines.push(`**${(data.total_ad_reads ?? 0).toLocaleString()}** ad reads in last ${data.time_window_days ?? 30}d\n`);
+    lines.push(`**${data.total_ad_reads ?? 0}** ad reads in last ${data.time_window_days ?? 30}d\n`);
     for (let i = 0; i < data.advertisers.length; i++) {
         const a = data.advertisers[i];
         const promo = a.is_network_promo ? " [network]" : "";
-        lines.push(`${i + 1}. **${a.name}**${promo} [${a.category ?? "?"}] — ` +
-            `${a.episode_count} episodes, ${a.read_count} reads`);
+        lines.push(`${i + 1}. **${a.name}**${promo} — advertiser:${a.advertiser_id ?? a.id ?? "n/a"} category:${a.category ?? "n/a"} ` +
+            `episodes:${a.episode_count} reads:${a.read_count}`);
     }
-    return lines.join("\n") || "No ad data for this channel.";
+    const firstId = data.advertisers.find((a) => (a.advertiser_id ?? a.id) != null);
+    const hint = nextCallHint(firstId ? `get_ad_analytics view:advertiser advertiser_id:${firstId.advertiser_id ?? firstId.id}` : undefined);
+    return (lines.join("\n") || "No ad data for this channel.") + hint;
 }
 export function formatAdTrends(data) {
     if (!data.advertisers?.length)
         return "No trending data available.";
     const lines = [`# Ad Trends (${data.comparison ?? ""})\n`];
     for (const a of data.advertisers) {
-        const icon = { growing: "+", declining: "-", new: "NEW", gone: "GONE", stable: "=" }[a.trend] ?? "?";
-        lines.push(`[${icon}] **${a.name}** (${a.category ?? "?"}) — ` +
-            `${a.current_episodes} eps (was ${a.prior_episodes}, ${a.change_pct > 0 ? "+" : ""}${a.change_pct.toFixed(0)}%)`);
+        lines.push(`- **${a.name}** — advertiser:${a.advertiser_id ?? a.id ?? "n/a"} category:${a.category ?? "n/a"} ` +
+            `${trendToken(a.trend, a.change_pct)} episodes:${a.current_episodes} (was ${a.prior_episodes})`);
     }
-    return lines.join("\n");
+    const firstId = data.advertisers.find((a) => (a.advertiser_id ?? a.id) != null);
+    const hint = nextCallHint(firstId ? `get_ad_analytics view:advertiser advertiser_id:${firstId.advertiser_id ?? firstId.id}` : undefined);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Claim Detail
 // ---------------------------------------------------------------------------
+function observationLine(o) {
+    const date = fmtDate(o.publish_date);
+    const meta = [o.speaker_name ?? "speaker:unresolved (diarization cluster)", o.channel_name, `date:${date}`]
+        .filter(Boolean).join(", ");
+    const pointer = o.segment_id != null ? `get_segment seg:${o.segment_id}` : undefined;
+    const clip = clipUrl(o.content_id, o.start_time ?? undefined, o.end_time ?? undefined, o.clip_url);
+    return [
+        `- "${truncateWithPointer(o.chunk_text, pointer)}" — ${meta}`,
+        `  seg:${o.segment_id ?? "n/a"} episode:${o.content_id ?? "n/a"} ${clipLine(o.content_type, clip)}`,
+    ];
+}
 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}`);
+    lines.push(`# Claim claim:${c.claim_id}`);
+    lines.push(`**${c.summary}**`);
+    lines.push(`(synthesized claim — observations carry verbatim quotes)\n`);
+    const tokens = [`stance:${c.stance ?? "n/a"}`, `topic:${c.topic ?? "n/a"}`];
+    const lt = langToken(c.language);
+    if (lt)
+        tokens.push(lt);
+    lines.push(tokens.join(" "));
+    lines.push(`obs:${c.observation_count} ${episodeTokens(c)} channels:${c.channel_count}`);
+    const span = [fmtDate(c.first_seen), fmtDate(c.last_seen)].filter(d => d !== "n/a");
+    if (span.length === 2)
+        lines.push(`first_seen:${span[0]} last_seen:${span[1]}`);
     if (c.entities?.length) {
-        lines.push(`Entities: ${c.entities.join(", ")}`);
+        lines.push(`entities:${c.entities.join(",")}`);
     }
+    if (c.language && c.language !== "en")
+        lines.push(NON_ENGLISH_NOTE);
     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(`- ${s.name} — speaker:${s.identity_id ?? "n/a"} obs:${s.observation_count}`);
         }
         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(`- ${ch.name} — channel_id:${ch.channel_id} obs:${ch.observation_count}`);
         }
         lines.push("");
     }
     const obs = observations?.observations ?? c.sample_observations ?? [];
+    let firstObsSeg;
     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}`);
+            if (firstObsSeg == null && o.segment_id != null)
+                firstObsSeg = o.segment_id;
+            lines.push(...observationLine(o));
+        }
+        if (observations && observations.total > Math.min(obs.length, 20)) {
+            lines.push(`showing ${Math.min(obs.length, 20)} of ${observations.total} — page:${(observations.page ?? 1) + 1} for more`);
         }
         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(claimLine(r));
         }
         lines.push("");
     }
-    return lines.join("\n");
+    const hint = nextCallHint(firstObsSeg != null ? `get_segment seg:${firstObsSeg}` : undefined, `claim_graph claim_id:${c.claim_id}`);
+    return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Timeline
 // ---------------------------------------------------------------------------
-export function formatTimeline(data) {
+/** MCP timeline: `date<TAB>count` rows (spec §5 — bar glyphs retired). */
+export function formatTimeline(data, footer = "") {
     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;
+        return "No data found for this topic in the given time range." + footer;
     const lines = [
         `**"${data.topic}"** — ${data.total} segments (${data.granularity}, ${data.search_mode})\n`,
+        "date\tcount",
     ];
     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}`);
+        lines.push(`${b.start}\t${b.count}`);
     }
-    return lines.join("\n");
+    const peak = buckets.reduce((best, b) => (b.count > best.count ? b : best), buckets[0]);
+    const hint = nextCallHint(`search_quotes topic:"${data.topic}" start_date:${peak.start.slice(0, 10)}`);
+    return withFooters(lines.join("\n"), footer, "", hint);
 }
 //# sourceMappingURL=format.js.map