@poodle64/librarian 2026.9.5 → 2026.9.7

package/dist/components/document-pane/document-pane.svelte

@@ -0,0 +1,177 @@
+<!--
+  The cited document, open at the cited passage.
+
+  One element, two shapes. On a desktop it is a real column in the flow at
+  about 40% of the width and draggable — the transcript narrows beside it and
+  nothing is covered. Below `lg` there is no width to give it, so the same
+  element becomes a bottom sheet over the conversation. Two components would
+  have meant two behaviours to keep honest; a class list is cheaper than that.
+-->
+<script lang="ts">
+	import XIcon from '@lucide/svelte/icons/x';
+	import type { Citation, LoadDocument, LoadedDocument } from '../../citations';
+	import Markdown from '../markdown/markdown.svelte';
+
+	interface Props {
+		citation: Citation;
+		loadDocument: LoadDocument;
+		onclose: () => void;
+	}
+
+	let { citation, loadDocument, onclose }: Props = $props();
+
+	const MIN_WIDTH = 320;
+	/** ~40% of a 1440 desktop, which is the width the pane is designed at. */
+	const DEFAULT_WIDTH = 560;
+
+	let width = $state(DEFAULT_WIDTH);
+	let document_ = $state<LoadedDocument | null>(null);
+	let failed = $state(false);
+	let scroller = $state<HTMLElement | null>(null);
+	let closeButton = $state<HTMLButtonElement | null>(null);
+
+	// Keyed on the id, so re-citing the same document while the pane is open
+	// moves to the new section without a second fetch and without a flash of
+	// the loading state.
+	// Plain, not `$state`: the effect below both reads and writes it, and
+	// nothing renders it.
+	let loadedId: string | null = null;
+
+	$effect(() => {
+		const id = citation.document_id;
+		if (!id || id === loadedId) return;
+		let cancelled = false;
+		document_ = null;
+		failed = false;
+		loadDocument(id)
+			.then((doc) => {
+				if (cancelled) return;
+				document_ = doc;
+				loadedId = id;
+			})
+			.catch(() => {
+				if (!cancelled) failed = true;
+			});
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	// The anchor is the citation's own address; the section heading is the
+	// fallback for a citation that carries only prose-derived words.
+	const activeAnchor = $derived.by(() => {
+		const sections = document_?.sections ?? [];
+		if (citation.anchor && sections.some((s) => s.anchor === citation.anchor))
+			return citation.anchor;
+		return sections.find((s) => s.heading === citation.section)?.anchor ?? sections[0]?.anchor ?? '';
+	});
+
+	$effect(() => {
+		if (!scroller || !activeAnchor) return;
+		const target = scroller.querySelector(`[data-anchor="${CSS.escape(activeAnchor)}"]`);
+		target?.scrollIntoView({ block: 'center' });
+	});
+
+	// Opening a pane a reader reached with the keyboard must move focus into
+	// it, or Escape and Tab both act on the transcript behind it.
+	$effect(() => {
+		const returnTo = globalThis.document?.activeElement as HTMLElement | null;
+		closeButton?.focus();
+		return () => returnTo?.focus?.();
+	});
+
+	function keydown(event: KeyboardEvent) {
+		if (event.key === 'Escape') {
+			event.stopPropagation();
+			onclose();
+		}
+	}
+
+	let dragFrom: { x: number; width: number } | null = null;
+
+	function startDrag(event: PointerEvent) {
+		dragFrom = { x: event.clientX, width };
+		(event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
+	}
+
+	function drag(event: PointerEvent) {
+		if (!dragFrom) return;
+		// The handle is on the pane's LEFT edge, so dragging left widens it.
+		const next = dragFrom.width - (event.clientX - dragFrom.x);
+		width = Math.max(MIN_WIDTH, Math.min(next, window.innerWidth * 0.7));
+	}
+
+	function endDrag(event: PointerEvent) {
+		dragFrom = null;
+		(event.currentTarget as HTMLElement).releasePointerCapture(event.pointerId);
+	}
+</script>
+
+<svelte:window onkeydown={keydown} />
+
+<aside
+	style="--pane-width: {width}px"
+	aria-label="Source document"
+	class="bg-surface-1 border-border fixed inset-x-0 bottom-0 z-40 flex h-[80svh] flex-col rounded-t-2xl border-t shadow-2xl lg:static lg:h-auto lg:w-[var(--pane-width)] lg:shrink-0 lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none"
+>
+	<!-- svelte-ignore a11y_no_static_element_interactions -- a pointer-only
+	     affordance for a width that has a keyboard-independent default; the
+	     pane is fully usable without ever touching it. -->
+	<div
+		onpointerdown={startDrag}
+		onpointermove={drag}
+		onpointerup={endDrag}
+		class="hover:bg-primary/40 absolute inset-y-0 left-0 hidden w-1.5 cursor-col-resize lg:block"
+	></div>
+
+	<!-- The sheet's grabber. Below `lg` this is an overlay a reader has to be
+	     able to see the top edge of; on a desktop it is a column, and a column
+	     with a handle on it reads as draggable in the wrong axis. -->
+	<div class="flex justify-center pt-2 pb-1 lg:hidden" aria-hidden="true">
+		<span class="bg-border h-1 w-9 rounded-full"></span>
+	</div>
+
+	<header class="border-border flex items-start gap-2 border-b px-4 py-3 lg:pt-3">
+		<div class="min-w-0 flex-1">
+			<h2 class="text-foreground truncate text-sm font-semibold">
+				{document_?.title ?? citation.title}
+			</h2>
+			{#if citation.section}
+				<p class="text-muted-foreground truncate text-xs">{citation.section}</p>
+			{/if}
+		</div>
+		<button
+			bind:this={closeButton}
+			type="button"
+			onclick={onclose}
+			aria-label="Close source"
+			class="text-muted-foreground hover:text-foreground hover:bg-surface-2 focus-visible:ring-ring -mt-1 flex size-8 shrink-0 items-center justify-center rounded-lg transition-colors focus-visible:ring-2 focus-visible:outline-none"
+		>
+			<XIcon class="size-4" />
+		</button>
+	</header>
+
+	<div bind:this={scroller} class="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-3">
+		{#if failed}
+			<p class="text-muted-foreground text-sm">That document can't be opened right now.</p>
+		{:else if !document_}
+			<div class="flex flex-col gap-2" aria-hidden="true">
+				{#each [0, 1, 2, 3] as row (row)}
+					<div class="bg-muted h-4 animate-pulse rounded" style="width: {90 - row * 12}%"></div>
+				{/each}
+			</div>
+		{:else}
+			{#each document_.sections as section (section.anchor)}
+				<section
+					data-anchor={section.anchor}
+					class="scroll-mt-4 rounded-lg px-3 py-2 {section.anchor === activeAnchor
+						? 'border-primary/50 bg-primary/8 border-l-2'
+						: ''}"
+				>
+					<h3 class="text-foreground mb-1 text-sm font-semibold">{section.heading}</h3>
+					<Markdown content={section.text} dense />
+				</section>
+			{/each}
+		{/if}
+	</div>
+</aside>

package/dist/components/document-pane/document-pane.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Citation, LoadDocument } from '../../citations';
+interface Props {
+    citation: Citation;
+    loadDocument: LoadDocument;
+    onclose: () => void;
+}
+declare const DocumentPane: import("svelte").Component<Props, {}, "">;
+type DocumentPane = ReturnType<typeof DocumentPane>;
+export default DocumentPane;

package/dist/components/document-pane/index.d.ts

@@ -0,0 +1,2 @@
+export { default as DocumentPane } from './document-pane.svelte';
+export { default } from './document-pane.svelte';

package/dist/components/document-pane/index.js

@@ -0,0 +1,2 @@
+export { default as DocumentPane } from './document-pane.svelte';
+export { default } from './document-pane.svelte';

package/dist/components/markdown/index.d.ts

@@ -1,3 +1,3 @@
 export { default as Markdown } from './markdown.svelte';
 export { default } from './markdown.svelte';
-export { balance, render, markCollections, highlight } from './markdown';
+export { balance, render, markCollections, markCitations, highlight } from './markdown';

package/dist/components/markdown/index.js

@@ -1,3 +1,3 @@
 export { default as Markdown } from './markdown.svelte';
 export { default } from './markdown.svelte';
-export { balance, render, markCollections, highlight } from './markdown';
+export { balance, render, markCollections, markCitations, highlight } from './markdown';

package/dist/components/markdown/markdown.d.ts

@@ -29,6 +29,19 @@ export declare function render(markdown: string, { streaming }?: {
  * cannot drift out of sync with the rendering.
  */
 export declare function markCollections(root: HTMLElement, collections: Set<string>): void;
+/**
+ * Turn every inline `[n]` marker into a citation chip.
+ *
+ * Done against the rendered DOM rather than the markdown string, for the same
+ * reason `markCollections` is: a `[3]` inside a fenced code block or a link
+ * label is not a citation, and `closest()` settles that in one call where a
+ * string-level regex would need to re-implement the parser to know.
+ *
+ * `sup` rather than `button`: the sanitiser strips `button` (it is in
+ * `FORBID_TAGS`, and rightly — this is model output), so the chip carries the
+ * button ROLE and a tab stop, and the component delegates the events.
+ */
+export declare function markCitations(root: HTMLElement, valid: Set<number>): void;
 /**
  * Replace every `<pre><code>` in a rendered fragment with a highlighted one.
  * Runs against the DOM node rather than the HTML string so it can be applied

package/dist/components/markdown/markdown.js

@@ -39,7 +39,7 @@ export function render(markdown, { streaming = false } = {}) {
     const source = streaming ? balance(markdown) : markdown;
     const html = marked.parse(source, { async: false });
     return DOMPurify.sanitize(html, {
-        ADD_ATTR: ['target', 'rel'],
+        ADD_ATTR: ['target', 'rel', 'data-cite', 'tabindex', 'role'],
         FORBID_TAGS: ['style', 'form', 'input', 'button'],
         FORBID_ATTR: ['style', 'onerror', 'onload']
     });
@@ -89,6 +89,54 @@ export function markCollections(root, collections) {
             code.dataset.collection = 'true';
     }
 }
+/**
+ * Turn every inline `[n]` marker into a citation chip.
+ *
+ * Done against the rendered DOM rather than the markdown string, for the same
+ * reason `markCollections` is: a `[3]` inside a fenced code block or a link
+ * label is not a citation, and `closest()` settles that in one call where a
+ * string-level regex would need to re-implement the parser to know.
+ *
+ * `sup` rather than `button`: the sanitiser strips `button` (it is in
+ * `FORBID_TAGS`, and rightly — this is model output), so the chip carries the
+ * button ROLE and a tab stop, and the component delegates the events.
+ */
+export function markCitations(root, valid) {
+    if (valid.size === 0)
+        return;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const targets = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        const text = node;
+        if (text.parentElement?.closest('pre, code, a, sup'))
+            continue;
+        if (/\[\d{1,3}\]/.test(text.data))
+            targets.push(text);
+    }
+    for (const text of targets) {
+        const fragment = document.createDocumentFragment();
+        let cursor = 0;
+        for (const match of text.data.matchAll(/\[(\d{1,3})\]/g)) {
+            const n = Number(match[1]);
+            if (!valid.has(n) || match.index === undefined)
+                continue;
+            fragment.append(text.data.slice(cursor, match.index));
+            const chip = document.createElement('sup');
+            chip.className = 'ds-cite';
+            chip.dataset.cite = String(n);
+            chip.setAttribute('role', 'button');
+            chip.setAttribute('tabindex', '0');
+            chip.setAttribute('aria-label', `Source ${n}`);
+            chip.textContent = String(n);
+            fragment.append(chip);
+            cursor = match.index + match[0].length;
+        }
+        if (cursor === 0)
+            continue;
+        fragment.append(text.data.slice(cursor));
+        text.replaceWith(fragment);
+    }
+}
 /**
  * Replace every `<pre><code>` in a rendered fragment with a highlighted one.
  * Runs against the DOM node rather than the HTML string so it can be applied

package/dist/components/markdown/markdown.svelte

@@ -7,16 +7,29 @@
   consuming app.
 -->
 <script lang="ts">
-	import { highlight, markCollections, render } from './markdown';
+	import { highlight, markCitations, markCollections, render } from './markdown';
 
 	interface Props {
 		content: string;
 		streaming?: boolean;
 		/** Collection names to chip in backticks; omit if the caller has none. */
 		collectionNames?: Set<string>;
+		/** `[n]` markers to turn into chips; omit and the markers stay as text. */
+		citationNumbers?: Set<number>;
+		oncite?: (n: number) => void;
+		/** A step down, for prose that is reference material beside an answer
+		 *  rather than the answer itself — the source pane's sections. */
+		dense?: boolean;
 	}
 
-	let { content, streaming = false, collectionNames = new Set() }: Props = $props();
+	let {
+		content,
+		streaming = false,
+		collectionNames = new Set(),
+		citationNumbers = new Set(),
+		oncite,
+		dense = false
+	}: Props = $props();
 	let host = $state<HTMLElement | null>(null);
 
 	const html = $derived(render(content, { streaming }));
@@ -27,12 +40,42 @@
 		if (!host || !html) return;
 		// Chips are cheap and wanted DURING streaming; highlighting is not.
 		markCollections(host, collectionNames);
+		markCitations(host, citationNumbers);
 		if (streaming) return;
 		void highlight(host);
 	});
+
+	// Delegated, because the chips are created by the sanitiser's output rather
+	// than by this template — there is no element here to put a handler on.
+	function citeFrom(target: EventTarget | null): number | null {
+		const chip = (target as HTMLElement | null)?.closest?.('[data-cite]');
+		const n = Number((chip as HTMLElement | undefined)?.dataset.cite);
+		return Number.isFinite(n) && n > 0 ? n : null;
+	}
+
+	function click(event: MouseEvent) {
+		const n = citeFrom(event.target);
+		if (n !== null) oncite?.(n);
+	}
+
+	function keydown(event: KeyboardEvent) {
+		if (event.key !== 'Enter' && event.key !== ' ') return;
+		const n = citeFrom(event.target);
+		if (n === null) return;
+		event.preventDefault();
+		oncite?.(n);
+	}
 </script>
 
-<div bind:this={host} class="agent-prose text-foreground text-base leading-7">
+<!-- svelte-ignore a11y_no_static_element_interactions -- the interactive
+     elements are the sanitiser-created chips, which carry role and tabindex;
+     this element only delegates their events. -->
+<div
+	bind:this={host}
+	onclick={click}
+	onkeydown={keydown}
+	class="agent-prose text-foreground {dense ? 'text-sm leading-6' : 'text-base leading-7'}"
+>
 	<!-- eslint-disable-next-line svelte/no-at-html-tags -- sanitised in render() -->
 	{@html html}
 </div>
@@ -169,6 +212,10 @@
 		border-radius: var(--radius);
 		padding: 0.85em 1em;
 		overflow-x: auto;
+		/* A fenced block is the one thing here allowed to be wider than the
+		   measure, so it must scroll INSIDE itself: without this a 90-column
+		   line makes the whole transcript scroll sideways at 390px. */
+		max-width: 100%;
 	}
 
 	.agent-prose :global(pre code) {
@@ -190,8 +237,11 @@
 		color: var(--shiki-dark);
 	}
 
+	/* `display: block` is what makes the overflow scroll: a real `table` box
+	   ignores overflow-x and widens its container instead. */
 	.agent-prose :global(table) {
 		width: 100%;
+		max-width: 100%;
 		border-collapse: collapse;
 		font-size: 0.9em;
 		display: block;
@@ -203,6 +253,9 @@
 		border: 1px solid var(--border);
 		padding: 0.4em 0.6em;
 		text-align: start;
+		/* A cell must not be squeezed to one character per line by a narrow
+		   viewport; the table scrolls instead. */
+		white-space: nowrap;
 	}
 
 	.agent-prose :global(th) {
@@ -220,6 +273,35 @@
 		font-weight: 500;
 	}
 
+	/* The citation chip. A superscript number a reader can press: small enough
+	   to sit inside a sentence without breaking its rhythm, big enough that a
+	   thumb finds it — the padding, not the glyph, carries the target size. */
+	.agent-prose :global(sup.ds-cite) {
+		display: inline-block;
+		min-width: 1.35em;
+		margin-inline: 0.15em;
+		padding: 0.1em 0.3em;
+		border-radius: 0.4em;
+		background: color-mix(in oklab, var(--primary) 16%, transparent);
+		color: var(--foreground);
+		font-family: var(--ds-font-mono, monospace);
+		font-size: 0.7em;
+		font-weight: 600;
+		line-height: 1.4;
+		text-align: center;
+		vertical-align: 0.35em;
+		cursor: pointer;
+	}
+
+	.agent-prose :global(sup.ds-cite:hover) {
+		background: color-mix(in oklab, var(--primary) 30%, transparent);
+	}
+
+	.agent-prose :global(sup.ds-cite:focus-visible) {
+		outline: 2px solid var(--ring);
+		outline-offset: 2px;
+	}
+
 	.agent-prose :global(hr) {
 		border: 0;
 		border-top: 1px solid var(--border);

package/dist/components/markdown/markdown.svelte.d.ts

@@ -3,6 +3,12 @@ interface Props {
     streaming?: boolean;
     /** Collection names to chip in backticks; omit if the caller has none. */
     collectionNames?: Set<string>;
+    /** `[n]` markers to turn into chips; omit and the markers stay as text. */
+    citationNumbers?: Set<number>;
+    oncite?: (n: number) => void;
+    /** A step down, for prose that is reference material beside an answer
+     *  rather than the answer itself — the source pane's sections. */
+    dense?: boolean;
 }
 declare const Markdown: import("svelte").Component<Props, {}, "">;
 type Markdown = ReturnType<typeof Markdown>;

package/dist/components/tool-row/tool-row.svelte

@@ -5,14 +5,13 @@
   dimmed sub-line. Borders and badge pills make a run of five calls read as
   five separate events rather than one train of thought.
 
-  The row says what the agent is DOING, not what it typed. A reader here is
-  asking about documents, not reading a terminal, and `Bash ls -1 .` looks
-  like a leak from the machine room. The raw command is one click away, so
-  nothing is hidden from anyone who wants it.
+  The row says what Milton DID, in a reader's own words — never the tool's
+  name or the raw command it ran. Expanding a settled row shows what came
+  back, never what was typed.
 -->
 <script lang="ts">
 	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
-	import { describe, summarise, type ToolBlock } from '../../transcript.svelte';
+	import { describe, type ToolBlock } from '../../transcript.svelte';
 
 	interface Props {
 		block: ToolBlock;
@@ -53,17 +52,12 @@
 		<span class="text-muted-foreground truncate">
 			<span class="text-foreground font-medium">{said.verb}</span>
 			{#if said.object}<span class="text-foreground/80">{said.object}</span>{/if}
-			{#if repeats > 1}<span class="text-muted-foreground">· {repeats} sections</span>{/if}
+			{#if repeats > 1}<span class="text-muted-foreground">· {repeats} pages</span>{/if}
 		</span>
 	</button>
 
 	{#if open}
 		<div class="border-border mt-1 ml-5.5 border-l pl-3">
-			<!-- The real command, for anyone who wants it. -->
-			<p class="text-muted-foreground font-mono text-xs break-all">
-				{block.name}
-				{summarise(block)}
-			</p>
 			{#if block.result}
 				<pre
 					class="text-muted-foreground mt-1 max-h-72 overflow-auto font-mono text-xs whitespace-pre-wrap">{block.result}</pre>

package/dist/components/working/working.svelte

@@ -18,15 +18,7 @@
 
 	let { label }: Props = $props();
 
-	const WORDS = [
-		'Starting',
-		'Reading the shelves',
-		'Rummaging',
-		'Cross-checking',
-		'Thumbing pages',
-		'Following a reference',
-		'Chasing it down'
-	];
+	const WORDS = ['Milton is looking', 'Milton is reading'];
 
 	let tick = $state(0);
 	let elapsed = $state(0);

package/dist/follow-scroll.svelte.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Follow the stream until the reader disagrees.
+ *
+ * The whole behaviour is one rule stated three ways: a viewport already at the
+ * bottom is following; a reader who scrolls UP has stopped following; a reader
+ * who comes back to the bottom is following again. Nothing else — no timers,
+ * no "was that scroll ours or theirs" bookkeeping — because the auto-scroll
+ * this drives always lands AT the bottom, which the first clause re-affirms
+ * rather than fights.
+ *
+ * Growing content moves the bottom away from a parked reader without moving
+ * their scrollTop, so distance alone cannot say who moved: the direction of
+ * scrollTop can, and that is the only thing `measure` remembers between calls.
+ */
+/** Distance from the bottom, in px, still counted as being at the bottom.
+ *  A line of prose is ~28px; two lines of slack survives sub-pixel layout
+ *  rounding and a caret-height change without unpinning the reader. */
+export declare const FOLLOW_THRESHOLD = 64;
+export interface ScrollMetrics {
+    scrollTop: number;
+    clientHeight: number;
+    scrollHeight: number;
+}
+export declare function distanceFromBottom(m: ScrollMetrics): number;
+export declare function atBottom(m: ScrollMetrics, threshold?: number): boolean;
+export declare class FollowScroll {
+    #private;
+    /** True while the viewport should be dragged along with new content. */
+    following: boolean;
+    /** Feed every scroll event, and the metrics after every content change. */
+    measure(m: ScrollMetrics, threshold?: number): void;
+    /** A new question re-pins: the reader asked for the thing about to arrive. */
+    pin(): void;
+}

package/dist/follow-scroll.svelte.js

@@ -0,0 +1,46 @@
+/**
+ * Follow the stream until the reader disagrees.
+ *
+ * The whole behaviour is one rule stated three ways: a viewport already at the
+ * bottom is following; a reader who scrolls UP has stopped following; a reader
+ * who comes back to the bottom is following again. Nothing else — no timers,
+ * no "was that scroll ours or theirs" bookkeeping — because the auto-scroll
+ * this drives always lands AT the bottom, which the first clause re-affirms
+ * rather than fights.
+ *
+ * Growing content moves the bottom away from a parked reader without moving
+ * their scrollTop, so distance alone cannot say who moved: the direction of
+ * scrollTop can, and that is the only thing `measure` remembers between calls.
+ */
+/** Distance from the bottom, in px, still counted as being at the bottom.
+ *  A line of prose is ~28px; two lines of slack survives sub-pixel layout
+ *  rounding and a caret-height change without unpinning the reader. */
+export const FOLLOW_THRESHOLD = 64;
+export function distanceFromBottom(m) {
+    return m.scrollHeight - m.scrollTop - m.clientHeight;
+}
+export function atBottom(m, threshold = FOLLOW_THRESHOLD) {
+    return distanceFromBottom(m) <= threshold;
+}
+export class FollowScroll {
+    /** True while the viewport should be dragged along with new content. */
+    following = $state(true);
+    #lastTop = 0;
+    /** Feed every scroll event, and the metrics after every content change. */
+    measure(m, threshold = FOLLOW_THRESHOLD) {
+        // 1px of tolerance: a trackpad's fractional scrollTop otherwise reads as
+        // an upward flick on a viewport that has not actually moved.
+        const wentUp = m.scrollTop < this.#lastTop - 1;
+        this.#lastTop = m.scrollTop;
+        if (atBottom(m, threshold)) {
+            this.following = true;
+            return;
+        }
+        if (wentUp)
+            this.following = false;
+    }
+    /** A new question re-pins: the reader asked for the thing about to arrive. */
+    pin() {
+        this.following = true;
+    }
+}

package/dist/transcript.svelte.d.ts

@@ -7,6 +7,7 @@
  * verbatim under `other`, so nothing is silently dropped.
  */
 import type { AgentEvent } from './client';
+import type { Citation } from './citations';
 export interface TextBlock {
     kind: 'text';
     index: number;
@@ -34,12 +35,25 @@ export interface Outcome {
     isError?: boolean;
     error?: string;
 }
-/** What the agent is DOING, in words a reader who has never seen a shell knows.
+/**
+ * The question as the READER asked it.
+ *
+ * A host prepends a system preamble to every question before it goes to the
+ * library — cadmus sends `{room.preamble}\n\n{question}` — and echoing that
+ * back into the transcript shows a colleague the machine room. Leading
+ * blank-line-separated paragraphs addressed to the model are dropped.
+ *
+ * The LAST paragraph is never dropped, whatever it starts with: someone whose
+ * entire question is "You are wrong about the leave rule" must still see it.
+ */
+export declare function readerQuestion(question: string): string;
+/** What Milton DID, in a reader's own words — never the tool's name or the
+ * raw command it ran.
  *
  * The collapsed row is read by someone asking a question about documents, not
  * by an engineer: `Bash ls -1 .` tells them nothing and looks like a leak from
- * the machine room. The raw command is still one click away on expand, so this
- * hides nothing — it just stops the transcript opening with jargon.
+ * the machine room. Milton never narrates how he searched, so a tool this
+ * does not recognise falls back to something that names no mechanism at all.
  */
 export declare function describe(block: ToolBlock): {
     verb: string;
@@ -68,6 +82,8 @@ export declare class Transcript {
     sessionId: string | null;
     model: string | null;
     outcome: Outcome | null;
+    /** Sources for the answer, from the library's own `citations` frame. */
+    citations: Citation[];
     other: AgentEvent[];
     reset(): void;
     apply(event: AgentEvent): void;
@@ -88,6 +104,18 @@ export interface ActivityGroup {
     searches: number;
 }
 export type Segment = ActivityGroup | TextBlock;
+/** One question and the answer to it, as the transcript renders it.
+ *
+ * A finished turn is a plain object the host keeps in a list; the LIVE turn is
+ * a `Transcript` spread into the same shape. Both render identically, which is
+ * what stops a conversation flickering as the last turn settles. */
+export interface Turn {
+    id: string;
+    question: string;
+    blocks: Block[];
+    outcome: Outcome | null;
+    citations?: Citation[];
+}
 /**
  * Fold a turn's flat block list into what a reader should actually see.
  *
@@ -101,5 +129,9 @@ export type Segment = ActivityGroup | TextBlock;
  *    steps with the same label collapse to one row carrying a count.
  */
 export declare function segment(blocks: Block[]): Segment[];
-/** One line describing a whole investigation, for the collapsed state. */
+/** One line describing a whole investigation, for the collapsed state.
+ *
+ * Counts of what Milton did are fine ("1 search · 2 documents read"); how he
+ * organises what he knows is not — no collection count, no shelf, no corpus.
+ */
 export declare function summariseActivity(group: ActivityGroup): string;