@poodle64/librarian 2026.9.8 → 2026.9.9

package/README.md

@@ -14,12 +14,14 @@ Change it here, consume it there.
 src/lib/
   client.ts                ask(): streams Claude Code's OWN events, unaltered
   transcript.svelte.ts     Transcript state, the fold/segment/describe helpers
-  citations.ts             the Citation shape, `[n]` markers, "## Sources"
+  citations.ts             the Citation shape, `[n]` markers, the trust mark
+  copy.ts                  every word this package says, and the host's overrides
   attachments.ts           what a reader may attach, and the limits
   follow-scroll.svelte.ts  follow the stream until the reader disagrees
   history.svelte.ts        the browser-held conversation list, per caller
   components/
     conversation/          the whole reading surface: scroll, pill, pane, composer slot
+    scope-statement/       what this room answers from, and what it does not hold
     agent-transcript/      one question and everything Milton did answering it
     document-pane/         the cited document, open at the cited passage
     composer/              the input box: attachments, scope chips, send/stop
@@ -99,6 +101,7 @@ gives it a height and a composer and nothing else:
 					live.blocks = transcript.blocks;
 					live.outcome = transcript.outcome;
 					live.citations = transcript.citations;
+					live.suggestions = transcript.suggestions;
 				}
 			}
 		} finally {
@@ -123,6 +126,8 @@ gives it a height and a composer and nothing else:
 		examples={['How much recreation leave do I get?']}
 		onexample={(q) => (question = q)}
 		onregenerate={() => run(asked, [])}
+		onsuggest={(q) => run(q, [])}
+		scope="Milton answers from the ADF Pay and Conditions Manual (PACMAN). He does not hold your own pay records or anything about your individual case."
 		{loadDocument}
 	>
 		{#snippet composer()}
@@ -152,7 +157,10 @@ on it fires once and never again.
 | Attachments              | nothing: `ask()` posts multipart (`question`, `resume`, `collections[]`, `files[]`) whenever `files` is non-empty, and JSON when it is not. The route must accept both                      |
 | Reading a cited document | `loadDocument(document_id) => Promise<{title, sections: [{anchor, heading, text}]}>`, proxied through the app's own authenticated route (cadmus: `GET /api/sources/documents/{id}/content`) |
 | Asking again             | `onregenerate`: re-send the last question as a NEW turn; the package exposes the action and never re-asks by itself                                                                        |
+| Asking a follow-up       | `onsuggest(question)`: ask it as a NEW turn. Without the handler the chips do not render at all — a chip that does nothing is worse than no chip                                            |
 | The empty state          | `welcome` and up to three `examples`                                                                                                                                                        |
+| What this surface covers | `scope`: one statement per room, in the host's own words. Rendered above the first turn and folded to a line once the conversation starts                                                   |
+| The words themselves     | `copy`: a partial of `LibrarianCopy`. Every component resolves it itself, so overriding one line does not mean restating the rest                                                            |
 
 Nothing here fetches on its own behalf. The library's document read is
 authenticated, and a package that called it directly would be reaching past
@@ -166,7 +174,15 @@ The library emits one SSE frame after the final assistant text:
 {
 	"type": "citations",
 	"items": [
-		{ "n": 1, "document_id": "…", "title": "…", "section": "…", "anchor": "…", "snippet": "…" }
+		{
+			"n": 1,
+			"document_id": "…",
+			"title": "…",
+			"section": "…",
+			"anchor": "…",
+			"snippet": "…",
+			"verified_at": "2026-06-23"
+		}
 	]
 }
 ```
@@ -177,6 +193,57 @@ section. Until that frame ships everywhere, the same chips are DERIVED from
 a trailing "## Sources" block in the answer: those render and read, and are
 inert, because a title and a section are not an id.
 
+### The trust mark
+
+`verified_at` is the date the last recheck found the document unchanged at
+its publisher, `YYYY-MM-DD`, resolved by the library from its own catalogue —
+never from what the model wrote, because a trust mark a model can author is
+not a trust mark. Null means nothing has ever confirmed it.
+
+Both the source list and the pane render it in words: **verified 23 Jun 2026**
+or **not verified**, in the same muted register as the section beside it. An
+unverified source is not an error and is not dressed as one — the words carry
+the difference, and a red one would have a colleague discount a document that
+is simply new.
+
+A DERIVED citation carries no mark at all. It has no catalogued document
+behind it, so "not verified" would be a claim about a record nothing here
+ever read.
+
+An answer that settles having cited nothing says so, once, under the prose:
+"Milton answered this one without a source. He may not hold a document that
+covers it." Only on a turn whose stream this surface actually watched finish
+— a turn read back out of `createHistory()` has no citations because history
+stores none, and labelling it as holding nothing would be a lie about an
+answer that may have cited three documents.
+
+### Follow-ups
+
+One more frame follows the citations, and only when the librarian named any:
+
+```json
+{ "type": "suggestions", "items": ["Can I carry leave over when I post?"] }
+```
+
+At most three, each short enough to fit a chip. `Transcript.suggestions`
+carries them; `Conversation` offers them under the LAST answer, and clicking
+one asks it through `onsuggest` and takes the whole row with it — the moment
+between the click and the new turn arriving is otherwise long enough to ask a
+second question by mistake.
+
+### Changing the words
+
+Every user-visible string this package renders lives in
+`@poodle64/librarian/copy`, and every component takes a partial of it:
+
+```svelte
+<Conversation {turns} {running} copy={{ notVerified: 'not checked yet' }} />
+```
+
+Overriding one line leaves the rest as the package wrote them, and a key
+passed as `undefined` — the shape a host produces from state that has not
+loaded — is ignored rather than rendering nothing where a word belongs.
+
 ### The system preamble
 
 A host prepends its own instruction to every question (cadmus sends
@@ -204,12 +271,15 @@ pnpm run test         # build + vitest
 pnpm run screenshots  # the state grid, real engine (see below)
 ```
 
-`docs/screenshots/` is eight states x three widths x both themes, taken by
+`docs/screenshots/` is ten states x three widths x both themes, taken by
 `scripts/screenshots.mjs` against the console's `/librarian` lab route
 running from its own static build. The same script asserts what a screenshot
-cannot: that nothing scrolls sideways at any width, and that the source pane
-opens and closes from the keyboard with focus returning to the chip. It
-exits non-zero on either.
+cannot: that nothing scrolls sideways at any width, that the source pane
+opens and closes from the keyboard with focus returning to the chip and is
+really draggable, that the scope statement folds once there is a
+conversation over it and reopens from that line, and that a follow-up chip
+asks its question and takes the rest of the row with it. It exits non-zero
+on any of them.
 
 ```bash
 pnpm --filter @poodle64/console run build
@@ -221,17 +291,6 @@ pnpm --filter @poodle64/librarian run screenshots
 1. Change a component; bump `version` in `package.json` (CalVer).
 2. `pnpm build`, which runs `svelte-package` then `publint`.
 3. Commit, tag `librarian-v<version>`, push the tag.
-4. `.github/workflows/publish.yaml` runs on that push and should publish via
-   npm OIDC trusted publishing: check it with
-   `gh run list --workflow=publish.yaml`. As of 2026.9.5 every run since
-   `ui-v2026.9.2` fails at the `npm publish` step with
-   `E404 Not Found - PUT .../@poodle64%2flibrarian` (an OIDC/trusted-publisher
-   binding issue, since `Build and test package` passes first). Until that
-   is diagnosed and fixed, publish manually from `packages/librarian/`:
-   ```bash
-   printf '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n' > .npmrc
-   signet exec --identity huginn-claude --broker https://portcullis.godswood.au \
-     --credential npm-publish-token --env-var NODE_AUTH_TOKEN -- npm publish
-   rm -f .npmrc
-   ```
-   Confirm with `npm view @poodle64/librarian version`.
+4. `.github/workflows/publish.yaml` runs on that push and publishes through
+   npm's trusted publisher. Watch it: `gh run list --workflow=publish.yaml`,
+   then `npm view @poodle64/librarian version`.

package/dist/citations.d.ts

@@ -8,6 +8,7 @@
  * a title and a section but no id: those chips render and read, and cannot
  * open a pane. A derived citation is marked `derived` so the UI can tell.
  */
+import type { LibrarianCopy } from './copy';
 export interface Citation {
     n: number;
     document_id: string;
@@ -15,6 +16,16 @@ export interface Citation {
     section?: string;
     anchor?: string;
     snippet?: string;
+    /**
+     * The date the last recheck found this document unchanged at its
+     * publisher, `YYYY-MM-DD`. Null when nothing has ever confirmed it.
+     *
+     * The library resolves this from its own catalogue, never from what the
+     * model wrote — a trust mark a model can author is not a trust mark — so
+     * a DERIVED citation carries none at all, and absent is not the same fact
+     * as null.
+     */
+    verified_at?: string | null;
     /** True when this came from the prose block rather than the wire event. */
     derived?: boolean;
 }
@@ -50,6 +61,30 @@ export declare function splitSources(markdown: string): SplitAnswer;
  * ids attached — so a turn never shows both.
  */
 export declare function resolveCitations(fromEvent: Citation[], fromProse: Citation[]): Citation[];
+/**
+ * `2026-06-23` as `23 Jun 2026`, or null if it is not a date.
+ *
+ * Read off the string rather than through `new Date()`: a date-only string is
+ * parsed as UTC midnight and then RENDERED in the reader's own zone, so every
+ * reader west of Greenwich would be shown the day before the one the library
+ * recorded. There is no time here to convert — a date is what was stored.
+ *
+ * `Intl` is not used either: `en-AU` abbreviates June as "June", so the mark
+ * would change length month to month for no reason a reader benefits from.
+ */
+export declare function formatVerified(iso: string): string | null;
+/**
+ * How current this source is, in words a reader already has.
+ *
+ * Three outcomes, and the third is the one worth stating: a citation the
+ * package DERIVED from a "## Sources" block gets no mark at all. It has no
+ * catalogued document behind it, so "not verified" would be a claim about a
+ * record we never read — and a wrong trust mark is worse than none.
+ *
+ * A `verified_at` that is present but not a date is treated as no date, for
+ * the same reason: what is shown must be what is known.
+ */
+export declare function trustMark(citation: Citation, copy: LibrarianCopy): string | null;
 /** One addressable slice of a document — the granularity a citation names. */
 export interface DocumentSection {
     anchor: string;

package/dist/citations.js

@@ -100,3 +100,43 @@ function parseSource(text) {
 export function resolveCitations(fromEvent, fromProse) {
     return fromEvent.length > 0 ? fromEvent : fromProse;
 }
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/**
+ * `2026-06-23` as `23 Jun 2026`, or null if it is not a date.
+ *
+ * Read off the string rather than through `new Date()`: a date-only string is
+ * parsed as UTC midnight and then RENDERED in the reader's own zone, so every
+ * reader west of Greenwich would be shown the day before the one the library
+ * recorded. There is no time here to convert — a date is what was stored.
+ *
+ * `Intl` is not used either: `en-AU` abbreviates June as "June", so the mark
+ * would change length month to month for no reason a reader benefits from.
+ */
+export function formatVerified(iso) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso.trim());
+    if (!match)
+        return null;
+    const [, year, month, day] = match;
+    const index = Number(month) - 1;
+    const date = Number(day);
+    if (index < 0 || index > 11 || date < 1 || date > 31)
+        return null;
+    return `${date} ${MONTHS[index]} ${year}`;
+}
+/**
+ * How current this source is, in words a reader already has.
+ *
+ * Three outcomes, and the third is the one worth stating: a citation the
+ * package DERIVED from a "## Sources" block gets no mark at all. It has no
+ * catalogued document behind it, so "not verified" would be a claim about a
+ * record we never read — and a wrong trust mark is worse than none.
+ *
+ * A `verified_at` that is present but not a date is treated as no date, for
+ * the same reason: what is shown must be what is known.
+ */
+export function trustMark(citation, copy) {
+    if (citation.derived)
+        return null;
+    const when = citation.verified_at ? formatVerified(citation.verified_at) : null;
+    return when ? `${copy.verified} ${when}` : copy.notVerified;
+}

package/dist/client.d.ts

@@ -40,8 +40,13 @@ export interface AgentEvent {
     detail?: string;
     tools?: string[];
     model?: string;
-    /** `citations` frames only: the library's sources for the answer just sent. */
-    items?: Citation[];
+    /**
+     * The payload of the library's own two trailing frames, which share a key
+     * and not a shape: `citations` carries sources, `suggestions` carries
+     * follow-up questions as plain strings. Narrowed on `type` by whoever
+     * reads it (`Transcript.apply`).
+     */
+    items?: Citation[] | string[];
     [key: string]: unknown;
 }
 export interface AskOptions {

package/dist/components/agent-transcript/agent-transcript.svelte

@@ -22,8 +22,10 @@
 		citationMarkers,
 		resolveCitations,
 		splitSources,
+		trustMark,
 		type Citation
 	} from '../../citations';
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
 	import Working from '../working/working.svelte';
 	import ActivityGroup from '../activity-group/activity-group.svelte';
 	import Markdown from '../markdown/markdown.svelte';
@@ -38,10 +40,17 @@
 		citations?: Citation[];
 		/** Forwarded to Markdown; omit if the caller has no collections to chip. */
 		collectionNames?: Set<string>;
+		/** Follow-ups from the library's `suggestions` frame. */
+		suggestions?: string[];
 		/** Opens the document pane. Omit and chips render but do not open. */
 		oncite?: (citation: Citation) => void;
 		/** Offered on the LAST answer only — re-asks the same question. */
 		onregenerate?: () => void;
+		/** Asks a follow-up. Offered on the LAST answer only; omit and the
+		 *  chips do not render, because a chip that does nothing is worse than
+		 *  no chip. */
+		onsuggest?: (question: string) => void;
+		copy?: Partial<LibrarianCopy>;
 	}
 
 	let {
@@ -51,10 +60,15 @@
 		running,
 		citations = [],
 		collectionNames = new Set(),
+		suggestions = [],
 		oncite,
-		onregenerate
+		onregenerate,
+		onsuggest,
+		copy
 	}: Props = $props();
 
+	const words = $derived(resolveCopy(copy));
+
 	const asked = $derived(readerQuestion(question));
 
 	// An activity group stays live — and therefore labelled "Working…" — only
@@ -95,8 +109,31 @@
 	// from it — there is just nothing to copy.
 	const settled = $derived(!running && (hasAnswer || Boolean(outcome?.error)));
 
+	/**
+	 * Milton answered and cited nothing, and we WATCHED him do it.
+	 *
+	 * `outcome` is the gate, not merely an empty source list: a turn read back
+	 * out of the conversation history is prose with no citations and no
+	 * outcome, because history stores neither — and a stored answer that cited
+	 * three documents would be labelled as holding nothing. Same for an answer
+	 * a reader stopped: the frame naming its sources never arrived, so nothing
+	 * here knows whether there were any.
+	 */
+	const notHeld = $derived(
+		settled && hasAnswer && sources.length === 0 && Boolean(outcome) && !outcome?.error
+	);
+
+	// A follow-up is offered once. Clicking it asks the question, which puts a
+	// new turn below this one — and leaving the row up for the moment before
+	// that arrives invites a second click on a third suggestion, asking two
+	// questions the reader only meant to ask one of.
+	let used = $state(false);
+	const followUps = $derived(!used && onsuggest ? suggestions : []);
+
 	let copied = $state(false);
-	async function copy() {
+	// Not `copy`: the prop of that name is the package's own words, and a
+	// function shadowing it here would be a redeclaration, not a shadow.
+	async function copyToClipboard() {
 		try {
 			await navigator.clipboard.writeText(answer);
 			copied = true;
@@ -146,10 +183,11 @@
 	{#if sources.length > 0}
 		<section class="max-w-[72ch]">
 			<h2 class="text-muted-foreground mb-1.5 text-xs font-medium tracking-wide uppercase">
-				Sources
+				{words.sources}
 			</h2>
 			<ol class="flex flex-col gap-1">
 				{#each sources as source (source.n)}
+					{@const mark = trustMark(source, words)}
 					<li>
 						<button
 							type="button"
@@ -166,6 +204,12 @@
 								{#if source.section}<span class="text-muted-foreground">
 										· {source.section}</span
 									>{/if}
+								<!-- Same muted register as the section, deliberately. An
+								     unverified source is not an error and must not be
+								     dressed as one; the words carry the difference, and a
+								     red one would have a colleague discount a document
+								     that is simply new. -->
+								{#if mark}<span class="text-muted-foreground/80"> · {mark}</span>{/if}
 							</span>
 						</button>
 					</li>
@@ -174,6 +218,36 @@
 		</section>
 	{/if}
 
+	{#if notHeld}
+		<p class="text-muted-foreground max-w-[72ch] text-sm">{words.notHeld}</p>
+	{/if}
+
+	{#if followUps.length > 0}
+		<section class="max-w-[72ch]">
+			<h2 class="text-muted-foreground mb-1.5 text-xs font-medium tracking-wide uppercase">
+				{words.suggestions}
+			</h2>
+			<!-- Wrapping, not scrolling: at 390 a question is most of a line, so a
+			     row of three would clip two of them to fragments. -->
+			<ul class="flex flex-wrap gap-2">
+				{#each followUps as followUp (followUp)}
+					<li class="max-w-full">
+						<button
+							type="button"
+							onclick={() => {
+								used = true;
+								onsuggest?.(followUp);
+							}}
+							class="border-border hover:border-border-strong hover:bg-surface-2 focus-visible:ring-ring text-foreground max-w-full rounded-full border px-3.5 py-2 text-left text-sm transition-colors focus-visible:ring-2 focus-visible:outline-none"
+						>
+							{followUp}
+						</button>
+					</li>
+				{/each}
+			</ul>
+		</section>
+	{/if}
+
 	{#if outcome?.error}
 		<p
 			class="border-status-error/40 bg-status-error/10 text-foreground max-w-[72ch] rounded-lg border px-3 py-2 text-sm"
@@ -188,23 +262,23 @@
 			{#if hasAnswer}
 				<button
 					type="button"
-					onclick={copy}
-					aria-label={copied ? 'Copied' : 'Copy answer'}
+					onclick={copyToClipboard}
+					aria-label={copied ? words.copiedAnswer : words.copyAnswer}
 					class="hover:text-foreground hover:bg-surface-2 focus-visible:ring-ring flex items-center gap-1.5 rounded-md px-1.5 py-1 text-xs transition-colors focus-visible:ring-2 focus-visible:outline-none"
 				>
 					{#if copied}<CheckIcon class="size-3.5" />{:else}<CopyIcon class="size-3.5" />{/if}
-					<span>{copied ? 'Copied' : 'Copy'}</span>
+					<span>{copied ? words.copiedAnswer : words.copyAnswer}</span>
 				</button>
 			{/if}
 			{#if onregenerate}
 				<button
 					type="button"
 					onclick={onregenerate}
-					aria-label="Ask again"
+					aria-label={words.askAgain}
 					class="hover:text-foreground hover:bg-surface-2 focus-visible:ring-ring flex items-center gap-1.5 rounded-md px-1.5 py-1 text-xs transition-colors focus-visible:ring-2 focus-visible:outline-none"
 				>
 					<RefreshCwIcon class="size-3.5" />
-					<span>Ask again</span>
+					<span>{words.askAgain}</span>
 				</button>
 			{/if}
 			{#if outcome && !outcome.error}

package/dist/components/agent-transcript/agent-transcript.svelte.d.ts

@@ -1,5 +1,6 @@
 import { type Block, type Outcome } from '../../transcript.svelte';
 import { type Citation } from '../../citations';
+import { type LibrarianCopy } from '../../copy';
 interface Props {
     question: string;
     blocks: Block[];
@@ -10,10 +11,17 @@ interface Props {
     citations?: Citation[];
     /** Forwarded to Markdown; omit if the caller has no collections to chip. */
     collectionNames?: Set<string>;
+    /** Follow-ups from the library's `suggestions` frame. */
+    suggestions?: string[];
     /** Opens the document pane. Omit and chips render but do not open. */
     oncite?: (citation: Citation) => void;
     /** Offered on the LAST answer only — re-asks the same question. */
     onregenerate?: () => void;
+    /** Asks a follow-up. Offered on the LAST answer only; omit and the
+     *  chips do not render, because a chip that does nothing is worse than
+     *  no chip. */
+    onsuggest?: (question: string) => void;
+    copy?: Partial<LibrarianCopy>;
 }
 declare const AgentTranscript: import("svelte").Component<Props, {}, "">;
 type AgentTranscript = ReturnType<typeof AgentTranscript>;

package/dist/components/conversation/conversation.svelte

@@ -13,9 +13,11 @@
 	import ArrowDownIcon from '@lucide/svelte/icons/arrow-down';
 	import type { Turn } from '../../transcript.svelte';
 	import type { Citation, LoadDocument } from '../../citations';
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
 	import { FollowScroll } from '../../follow-scroll.svelte';
 	import AgentTranscript from '../agent-transcript/agent-transcript.svelte';
 	import DocumentPane from '../document-pane/document-pane.svelte';
+	import ScopeStatement from '../scope-statement/scope-statement.svelte';
 
 	interface Props {
 		turns: Turn[];
@@ -27,8 +29,17 @@
 		/** Up to three, shown in the empty state as tappable pills. */
 		examples?: string[];
 		onexample?: (question: string) => void;
+		/** What this surface answers from and what it does not hold, in the
+		 *  host's own words. One statement per room, above the first turn,
+		 *  folded once the conversation starts. */
+		scope?: string;
 		/** Re-asks the last question. Offered on the last answer only. */
 		onregenerate?: () => void;
+		/** Asks a follow-up the librarian suggested. Offered on the last answer
+		 *  only; without it the suggestion chips do not render. */
+		onsuggest?: (question: string) => void;
+		/** Overrides for the package's own words. */
+		copy?: Partial<LibrarianCopy>;
 		/** Enables the source pane. Without it, chips render but do not open. */
 		loadDocument?: LoadDocument;
 		collectionNames?: Set<string>;
@@ -45,12 +56,17 @@
 		welcome = 'Ask Milton a question about the library.',
 		examples = [],
 		onexample,
+		scope,
 		onregenerate,
+		onsuggest,
+		copy,
 		loadDocument,
 		collectionNames = new Set(),
 		composer
 	}: Props = $props();
 
+	const words = $derived(resolveCopy(copy));
+
 	let viewport = $state<HTMLElement | null>(null);
 	let open = $state<Citation | null>(null);
 	const follow = new FollowScroll();
@@ -139,6 +155,14 @@
 					</div>
 				{/if}
 
+				<!-- Above the first turn, and in ONE place in the markup: the empty
+				     state carries the welcome, this carries the boundary, and both
+				     sit at the top of the same column so a reader meets them in
+				     the same order whether or not they have asked anything yet. -->
+				{#if scope}
+					<ScopeStatement statement={scope} expanded={turns.length === 0} {copy} />
+				{/if}
+
 				{#each turns as turn, index (turn.id)}
 					<AgentTranscript
 						question={turn.question}
@@ -146,9 +170,12 @@
 						outcome={turn.outcome}
 						running={running && index === turns.length - 1}
 						citations={turn.citations ?? []}
+						suggestions={turn.suggestions ?? []}
 						{collectionNames}
+						{copy}
 						oncite={cite}
 						onregenerate={index === turns.length - 1 && !running ? onregenerate : undefined}
+						onsuggest={index === turns.length - 1 && !running ? onsuggest : undefined}
 					/>
 				{/each}
 			</div>
@@ -161,7 +188,7 @@
 				class="border-border bg-surface-1 text-foreground hover:bg-surface-2 focus-visible:ring-ring absolute bottom-3 left-1/2 flex -translate-x-1/2 items-center gap-1.5 rounded-full border px-3 py-1.5 text-xs shadow-lg transition-colors focus-visible:ring-2 focus-visible:outline-none"
 			>
 				<ArrowDownIcon class="size-3.5" />
-				Jump to latest
+				{words.jumpToLatest}
 			</button>
 		{/if}
 		</div>
@@ -175,6 +202,6 @@
 	</div>
 
 	{#if open && loadDocument}
-		<DocumentPane citation={open} {loadDocument} onclose={() => (open = null)} />
+		<DocumentPane citation={open} {loadDocument} {copy} onclose={() => (open = null)} />
 	{/if}
 </div>

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

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { Turn } from '../../transcript.svelte';
 import type { LoadDocument } from '../../citations';
+import { type LibrarianCopy } from '../../copy';
 interface Props {
     turns: Turn[];
     running: boolean;
@@ -11,8 +12,17 @@ interface Props {
     /** Up to three, shown in the empty state as tappable pills. */
     examples?: string[];
     onexample?: (question: string) => void;
+    /** What this surface answers from and what it does not hold, in the
+     *  host's own words. One statement per room, above the first turn,
+     *  folded once the conversation starts. */
+    scope?: string;
     /** Re-asks the last question. Offered on the last answer only. */
     onregenerate?: () => void;
+    /** Asks a follow-up the librarian suggested. Offered on the last answer
+     *  only; without it the suggestion chips do not render. */
+    onsuggest?: (question: string) => void;
+    /** Overrides for the package's own words. */
+    copy?: Partial<LibrarianCopy>;
     /** Enables the source pane. Without it, chips render but do not open. */
     loadDocument?: LoadDocument;
     collectionNames?: Set<string>;

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

@@ -9,16 +9,25 @@
 -->
 <script lang="ts">
 	import XIcon from '@lucide/svelte/icons/x';
-	import type { Citation, LoadDocument, LoadedDocument } from '../../citations';
+	import { trustMark, type Citation, type LoadDocument, type LoadedDocument } from '../../citations';
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
 	import Markdown from '../markdown/markdown.svelte';
 
 	interface Props {
 		citation: Citation;
 		loadDocument: LoadDocument;
 		onclose: () => void;
+		copy?: Partial<LibrarianCopy>;
 	}
 
-	let { citation, loadDocument, onclose }: Props = $props();
+	let { citation, loadDocument, onclose, copy }: Props = $props();
+
+	const words = $derived(resolveCopy(copy));
+	// The same mark the chip carried, repeated where the reader has the
+	// document open in front of them: this is the moment they decide whether
+	// to act on it, and a currency they had to remember from a chip two
+	// scrolls up is one they will not have.
+	const mark = $derived(trustMark(citation, words));
 
 	const MIN_WIDTH = 320;
 	/** ~40% of a 1440 desktop, which is the width the pane is designed at. */
@@ -143,12 +152,15 @@
 			{#if citation.section}
 				<p class="text-muted-foreground truncate text-xs">{citation.section}</p>
 			{/if}
+			{#if mark}
+				<p class="text-muted-foreground/80 text-xs">{mark}</p>
+			{/if}
 		</div>
 		<button
 			bind:this={closeButton}
 			type="button"
 			onclick={onclose}
-			aria-label="Close source"
+			aria-label={words.closeSource}
 			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" />
@@ -157,7 +169,7 @@
 
 	<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>
+			<p class="text-muted-foreground text-sm">{words.documentUnavailable}</p>
 		{:else if !document_}
 			<div class="flex flex-col gap-2" aria-hidden="true">
 				{#each [0, 1, 2, 3] as row (row)}

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

@@ -1,8 +1,10 @@
-import type { Citation, LoadDocument } from '../../citations';
+import { type Citation, type LoadDocument } from '../../citations';
+import { type LibrarianCopy } from '../../copy';
 interface Props {
     citation: Citation;
     loadDocument: LoadDocument;
     onclose: () => void;
+    copy?: Partial<LibrarianCopy>;
 }
 declare const DocumentPane: import("svelte").Component<Props, {}, "">;
 type DocumentPane = ReturnType<typeof DocumentPane>;

package/dist/components/scope-statement/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ScopeStatement } from './scope-statement.svelte';
+export { default } from './scope-statement.svelte';

package/dist/components/scope-statement/index.js

@@ -0,0 +1,2 @@
+export { default as ScopeStatement } from './scope-statement.svelte';
+export { default } from './scope-statement.svelte';

package/dist/components/scope-statement/scope-statement.svelte

@@ -0,0 +1,71 @@
+<!--
+  What Milton answers from, and what he does not hold.
+
+  A colleague's first question about a room is not the one they type — it is
+  whether the answer they are about to read covers their case at all. Saying it
+  once, in the room's own words, is cheaper than every answer hedging.
+
+  It leads while there is nothing else on the surface, and folds to one line as
+  soon as there is: a boundary a reader has already read is a banner in the way
+  of the conversation they came for. Folded is not gone — the same line reopens
+  it, and a reader who opened it stays opened until the surface itself changes
+  state.
+-->
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+	import InfoIcon from '@lucide/svelte/icons/info';
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
+
+	interface Props {
+		/** The statement itself, in the host's own words. */
+		statement: string;
+		/** Open on arrival. Goes false once the conversation has a first turn. */
+		expanded?: boolean;
+		copy?: Partial<LibrarianCopy>;
+	}
+
+	let { statement, expanded = true, copy }: Props = $props();
+
+	const words = $derived(resolveCopy(copy));
+
+	// `untrack`, not a bare read: capturing the ARRIVING value is the intent —
+	// the effect below owns every later change — and Svelte rightly warns
+	// about a prop read in a position that will never see one.
+	let open = $state(untrack(() => expanded));
+	// Plain, not `$state`: the effect below both reads and writes it, and
+	// nothing renders it. It exists so the effect fires on a CHANGE of the
+	// prop rather than on every re-render — a reader who opened the statement
+	// back up mid-conversation keeps it open until the surface itself moves on.
+	let followed = untrack(() => expanded);
+	$effect(() => {
+		if (expanded === followed) return;
+		followed = expanded;
+		open = expanded;
+	});
+</script>
+
+<section
+	class="border-border bg-surface-2/60 rounded-xl border px-3 py-2"
+	aria-label={words.scope}
+>
+	<button
+		type="button"
+		onclick={() => (open = !open)}
+		aria-expanded={open}
+		class="text-muted-foreground hover:text-foreground focus-visible:ring-ring flex w-full items-center gap-2 rounded-md text-left text-xs transition-colors focus-visible:ring-2 focus-visible:outline-none"
+	>
+		<InfoIcon class="size-3.5 shrink-0" />
+		<span class="min-w-0 flex-1 truncate font-medium tracking-wide uppercase">{words.scope}</span>
+		<ChevronDownIcon class="size-3.5 shrink-0 transition-transform {open ? 'rotate-180' : ''}" />
+	</button>
+
+	{#if open}
+		<!-- No measure of its own: the card IS the measure, and a paragraph
+		     capped narrower than the border around it leaves a hand's width of
+		     empty card down the right at 1440. -->
+		<p class="text-muted-foreground mt-1.5 text-sm leading-6 whitespace-pre-line">
+			{statement}
+		</p>
+	{/if}
+</section>

package/dist/components/scope-statement/scope-statement.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type LibrarianCopy } from '../../copy';
+interface Props {
+    /** The statement itself, in the host's own words. */
+    statement: string;
+    /** Open on arrival. Goes false once the conversation has a first turn. */
+    expanded?: boolean;
+    copy?: Partial<LibrarianCopy>;
+}
+declare const ScopeStatement: import("svelte").Component<Props, {}, "">;
+type ScopeStatement = ReturnType<typeof ScopeStatement>;
+export default ScopeStatement;

package/dist/copy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Every word this package puts in front of a reader, in one place.
+ *
+ * Here rather than inline in each component because these sentences are the
+ * package's opinion about how Milton talks to a colleague, and an app that
+ * needs a different register — a different name for the librarian, a room
+ * whose boundary is worded by its own subject-matter owner — must be able to
+ * change one string without forking a component.
+ *
+ * Every component takes `copy` as a PARTIAL and resolves it itself, so a host
+ * overriding one line does not have to restate the other eleven, and a
+ * component used directly behaves the same as one reached through
+ * `Conversation`.
+ */
+export interface LibrarianCopy {
+    /** Prefixes the date on a verified source: "verified 23 Jun 2026". */
+    verified: string;
+    /** A source the catalogue has never confirmed against its publisher. */
+    notVerified: string;
+    /** Shown under an answer that finished without citing anything. */
+    notHeld: string;
+    /** Heading over the list of what an answer cited. */
+    sources: string;
+    /** Heading over the follow-up questions the librarian offered. */
+    suggestions: string;
+    /** The collapsed scope statement's own label. */
+    scope: string;
+    copyAnswer: string;
+    copiedAnswer: string;
+    askAgain: string;
+    jumpToLatest: string;
+    closeSource: string;
+    documentUnavailable: string;
+}
+export declare const DEFAULT_COPY: LibrarianCopy;
+/**
+ * The package's words with a host's overrides on top.
+ *
+ * An explicitly `undefined` key is dropped rather than spread, because
+ * `{...defaults, ...{ sources: undefined }}` leaves a component rendering
+ * nothing at all — and that is exactly the shape a host produces by passing a
+ * value it computed from state that has not loaded yet.
+ */
+export declare function resolveCopy(overrides?: Partial<LibrarianCopy>): LibrarianCopy;

package/dist/copy.js

@@ -0,0 +1,46 @@
+/**
+ * Every word this package puts in front of a reader, in one place.
+ *
+ * Here rather than inline in each component because these sentences are the
+ * package's opinion about how Milton talks to a colleague, and an app that
+ * needs a different register — a different name for the librarian, a room
+ * whose boundary is worded by its own subject-matter owner — must be able to
+ * change one string without forking a component.
+ *
+ * Every component takes `copy` as a PARTIAL and resolves it itself, so a host
+ * overriding one line does not have to restate the other eleven, and a
+ * component used directly behaves the same as one reached through
+ * `Conversation`.
+ */
+export const DEFAULT_COPY = {
+    verified: 'verified',
+    notVerified: 'not verified',
+    // Two sentences, both plain: what happened, and the likeliest reason. It
+    // says nothing about collections, indexes or retrieval — a colleague
+    // reading it has no model of any of those, and the room's own instruction
+    // to Milton forbids him naming them either.
+    notHeld: 'Milton answered this one without a source. He may not hold a document that covers it.',
+    sources: 'Sources',
+    suggestions: 'Ask next',
+    scope: 'What Milton answers from',
+    copyAnswer: 'Copy',
+    copiedAnswer: 'Copied',
+    askAgain: 'Ask again',
+    jumpToLatest: 'Jump to latest',
+    closeSource: 'Close source',
+    documentUnavailable: "That document can't be opened right now."
+};
+/**
+ * The package's words with a host's overrides on top.
+ *
+ * An explicitly `undefined` key is dropped rather than spread, because
+ * `{...defaults, ...{ sources: undefined }}` leaves a component rendering
+ * nothing at all — and that is exactly the shape a host produces by passing a
+ * value it computed from state that has not loaded yet.
+ */
+export function resolveCopy(overrides) {
+    if (!overrides)
+        return DEFAULT_COPY;
+    const given = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined));
+    return { ...DEFAULT_COPY, ...given };
+}

package/dist/transcript.svelte.d.ts

@@ -84,6 +84,8 @@ export declare class Transcript {
     outcome: Outcome | null;
     /** Sources for the answer, from the library's own `citations` frame. */
     citations: Citation[];
+    /** Follow-ups the librarian named, from the `suggestions` frame after it. */
+    suggestions: string[];
     other: AgentEvent[];
     reset(): void;
     apply(event: AgentEvent): void;
@@ -115,6 +117,9 @@ export interface Turn {
     blocks: Block[];
     outcome: Outcome | null;
     citations?: Citation[];
+    /** Follow-ups offered after this answer. Absent on a turn read back from
+     *  history: they belonged to the moment it was asked. */
+    suggestions?: string[];
 }
 /**
  * Fold a turn's flat block list into what a reader should actually see.

package/dist/transcript.svelte.js

@@ -20,7 +20,8 @@
 export function readerQuestion(question) {
     const parts = question.split(/\n{2,}/);
     let start = 0;
-    while (start < parts.length - 1 && /^(you are|you're|your role|act as|system:)\b/i.test(parts[start].trim()))
+    while (start < parts.length - 1 &&
+        /^(you are|you're|your role|act as|system:)\b/i.test(parts[start].trim()))
         start += 1;
     return parts.slice(start).join('\n\n').trim();
 }
@@ -138,6 +139,8 @@ export class Transcript {
     outcome = $state(null);
     /** Sources for the answer, from the library's own `citations` frame. */
     citations = $state([]);
+    /** Follow-ups the librarian named, from the `suggestions` frame after it. */
+    suggestions = $state([]);
     other = $state([]);
     /** Content-block index is per MESSAGE, so it repeats across turns; this
      * maps the live index onto a position in the flat list. Cleared whenever a
@@ -151,6 +154,7 @@ export class Transcript {
         this.blocks = [];
         this.outcome = null;
         this.citations = [];
+        this.suggestions = [];
         this.other = [];
         this.#open.clear();
     }
@@ -171,9 +175,18 @@ export class Transcript {
             return;
         }
         // Emitted after the final assistant text, so it lands on a turn that is
-        // otherwise complete.
+        // otherwise complete. Both frames put their payload on `items`, so each
+        // keeps only what its own shape admits: a `citations` frame carrying
+        // strings, or a `suggestions` frame carrying objects, is the library
+        // having changed under us, and rendering it would be worse than
+        // rendering nothing.
         if (event.type === 'citations') {
-            this.citations = event.items ?? [];
+            this.citations = (event.items ?? []).filter((item) => typeof item === 'object' && item !== null);
+            return;
+        }
+        // Last of the two, and only when the librarian named any.
+        if (event.type === 'suggestions') {
+            this.suggestions = (event.items ?? []).filter((item) => typeof item === 'string' && item.trim().length > 0);
             return;
         }
         if (event.type === 'library_error') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/librarian",
-	"version": "2026.9.8",
+	"version": "2026.9.9",
 	"description": "Milton's conversation surface as a consumable Svelte 5 package: the stream client, transcript state and chat components (transcript, composer, markdown) every household app renders instead of rebuilding.",
 	"type": "module",
 	"license": "MIT",
@@ -34,6 +34,10 @@
 			"types": "./dist/citations.d.ts",
 			"svelte": "./dist/citations.js"
 		},
+		"./copy": {
+			"types": "./dist/copy.d.ts",
+			"svelte": "./dist/copy.js"
+		},
 		"./attachments": {
 			"types": "./dist/attachments.d.ts",
 			"svelte": "./dist/attachments.js"