bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.42

package/bin/bitboss-ui-mcp.mjs

@@ -25,7 +25,8 @@
  * is stable across zod 3 and 4, so the lower bound costs nothing.
  *
  * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
- * Register with an MCP-capable harness via `npx bitboss-ui ai-init --mcp`.
+ * Registered with every MCP-capable harness by `npx bitboss-ui ai-init`
+ * (on by default; `--no-mcp` skips it).
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -34,8 +35,17 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
+import {
+	frontmatter,
+	outline,
+	pickSections,
+	searchSections,
+	splitSections,
+	stripFrontmatter,
+} from '../scripts/lib/doc-sections.mjs';
 import {
 	loadManifest,
+	possessive,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
 
@@ -70,26 +80,217 @@ function getManifestMap() {
 	return cachedManifestMap;
 }
 
-/** `search_components({ query })` — substring match over name/description. */
+/** `search_components({ query })` — token match over name/description. */
 const SEARCH_DEFAULT_LIMIT = 20;
 
 /**
- * Relevance score for one component against a lowercased needle. Higher wins;
+ * Ranking for the manifest's type tiers. `api` types are the ones an app is
+ * expected to reach for — they appear in a component's own props or events —
+ * so they lead. `wrapper` (`<Component>Props`) matters only when wrapping one
+ * of our components, and `advanced` is registries, contexts and adapters.
+ * Publishing 166 exports as a flat list made every one look equally important.
+ */
+const TYPE_USAGE_RANK = { api: 0, wrapper: 1, advanced: 2 };
+
+/**
+ * WHY THIS IS NOT A PLAIN SUBSTRING MATCH ANY MORE.
+ *
+ * It was, and a consumer pilot (2026-09-09) hand-rolled three components the
+ * library ships because the whole query string had to appear verbatim in one
+ * field. `table` found BbTable; `data table` — the term most of the industry
+ * uses — found NOTHING, because no name or description contains that exact
+ * pair. Same for `command palette`, `stepper wizard`, `skeleton loading`.
+ *
+ * An empty result is the worst possible answer for a tool whose stated job is
+ * "find the right Bb* component before writing usage code": it is
+ * indistinguishable from "nothing here, build it yourself". So two things
+ * changed. Multi-word queries are TOKENISED, and every search — hit or miss —
+ * consults the component picker's "Not in this library" table, which is where
+ * the authoritative answers for the invented names already lived.
+ */
+
+/** English filler that would otherwise match half the corpus on its own. */
+const SEARCH_STOPWORDS = new Set([
+	'a',
+	'an',
+	'the',
+	'and',
+	'or',
+	'not',
+	'no',
+	'is',
+	'it',
+	'in',
+	'on',
+	'for',
+	'of',
+	'to',
+	'with',
+	'component',
+	'components',
+	'ui',
+	'view',
+	'widget',
+	'element',
+]);
+
+/**
+ * `'data table view'` → `['data', 'table']`. Order is not significant.
+ *
+ * Names arrive as tags and identifiers too (review D6-6): `bb-select` used to
+ * return all 60 components on the token `bb`, and `BbCheckboxIcon` nothing.
+ * So a CamelCase word is also split into its words, the joined word loses a
+ * leading `bb`, and a bare `bb` is dropped.
+ */
+function tokenize(query) {
+	const raw = String(query ?? '')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.flatMap((word) => {
+			const lower = word.toLowerCase();
+			const parts = word
+				.replace(/^Bb(?=[A-Z])/, '')
+				.split(/(?<=[a-z0-9])(?=[A-Z])/)
+				.map((part) => part.toLowerCase());
+			return [
+				lower.replace(/^bb(?=.)/, ''),
+				...(parts.length > 1 ? parts : []),
+			];
+		})
+		.filter((token) => token && token !== 'bb');
+	const meaningful = [...new Set(raw)].filter((t) => !SEARCH_STOPWORDS.has(t));
+	// An all-stopword query ('the view') still deserves its literal reading
+	// rather than an empty token list that matches everything.
+	return meaningful.length > 0 ? meaningful : raw;
+}
+
+/**
+ * Relevance score for one component against ONE lowercased token. Higher wins;
  * 0 means "no match". Name hits always outrank description hits so
  * `search_components({ query: 'table' })` leads with BbTable, not with every
  * component whose prose mentions a table.
  */
-function scoreComponent(component, needle) {
+function scoreToken(component, needle) {
 	const name = component.name.toLowerCase();
 	const description = (component.description ?? '').toLowerCase();
 	if (name === needle) return 100;
 	if (name === `bb${needle}`) return 95; // 'button' → BbButton
 	if (name.startsWith(needle) || name.startsWith(`bb${needle}`)) return 80;
 	if (name.includes(needle)) return 60;
-	if (description.includes(needle)) return 30;
+	// Descriptions match at a WORD START, never mid-word: a plain substring made
+	// 'not' hit "notification" and returned four components for a nonsense
+	// query. Trailing suffixes still count, so 'card' finds "cards".
+	if (new RegExp(`\\b${needle}`).test(description)) return 30;
 	return 0;
 }
 
+/**
+ * Score against every token. A component that matches MORE of the query ranks
+ * above one that matches a single token harder, so `data table` puts BbTable
+ * (both tokens) above a component whose description merely says "data".
+ */
+function scoreComponent(component, tokens) {
+	let total = 0;
+	let matched = 0;
+	for (const token of tokens) {
+		const score = scoreToken(component, token);
+		if (score > 0) {
+			matched += 1;
+			total += score;
+		}
+	}
+	return matched === 0 ? { matched: 0, score: 0 } : { matched, score: total };
+}
+
+/**
+ * The picker's "Not in this library" table, parsed from the shipped guide so
+ * there is exactly one source of truth. Rows carry both kinds of answer:
+ * redirects (`BbDrawer` → "It is BbOffCanvas") and verdicts (`BbCard` → "Does
+ * not exist — a card is a <div> with tokens"). Both are better answers to a
+ * miss than an empty array.
+ */
+const PICKER_PATH = join(AI_ROOT, 'guides', 'component-picker.md');
+let cachedNotInLibrary = null;
+
+/** `'BbDataTable'` → `['bbdatatable', 'data', 'table']`. */
+function aliasTokens(cell) {
+	const words = cell
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links → their text
+		.replace(/[`*_]/g, '')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean);
+	const tokens = new Set();
+	for (const word of words) {
+		tokens.add(word.toLowerCase());
+		// Split CamelCase so `BbDataTable` is reachable by 'data' and 'table'.
+		for (const part of word.replace(/^Bb/, '').split(/(?=[A-Z])/))
+			if (part.length > 1) tokens.add(part.toLowerCase());
+	}
+	return [...tokens].filter((t) => !SEARCH_STOPWORDS.has(t) && t !== 'bb');
+}
+
+function loadNotInLibrary() {
+	if (cachedNotInLibrary) return cachedNotInLibrary;
+	cachedNotInLibrary = [];
+	if (!existsSync(PICKER_PATH)) return cachedNotInLibrary;
+	const md = readFileSync(PICKER_PATH, 'utf-8');
+	const section = md.split(/^## Not in this library\s*$/m)[1];
+	if (!section) return cachedNotInLibrary;
+	for (const line of section.split('\n')) {
+		if (!line.startsWith('|')) continue;
+		// Tolerate a missing trailing `|`: markdown renders such a row fine, so
+		// dropping it here would silently lose an answer (it already did once).
+		const cells = line
+			.replace(/^\|/, '')
+			.replace(/\|\s*$/, '')
+			.split('|');
+		if (cells.length < 2) continue;
+		const assumed = cells[0].trim();
+		const reality = cells[1].trim();
+		// Skip the header and its `---` separator.
+		if (!assumed || /^-+$/.test(assumed) || /^Assumed\b/i.test(assumed))
+			continue;
+		cachedNotInLibrary.push({
+			assumed,
+			reality,
+			tokens: aliasTokens(assumed),
+			// The names the row is ABOUT: `BbSkeleton` → 'skeleton'.
+			names: [...assumed.matchAll(/`(\w+)`/g)].map(([, name]) =>
+				name.toLowerCase().replace(/^(bb|use)(?=.)/, '')
+			),
+		});
+	}
+	return cachedNotInLibrary;
+}
+
+/**
+ * Picker rows the query is about. A row matches when the query names the
+ * row's own component (`skeleton loading` → BbSkeleton, `drawer` → BbDrawer),
+ * or when every word of a multi-word query is in the row (`data table`),
+ * counting a shared 6-letter stem (`scheduler` / `scheduling`). One shared
+ * generic word is not enough any more: 'text input' answered with the
+ * rich-text-editor verdict as "the authoritative answer", 'tab' with the
+ * cross-tab live-feed row (review D6-7).
+ */
+function matchNotInLibrary(tokens) {
+	if (!tokens.length) return [];
+	const covers = (row, token) =>
+		row.tokens.some(
+			(t) =>
+				t === token ||
+				(t.length >= 6 &&
+					token.length >= 6 &&
+					t.slice(0, 6) === token.slice(0, 6))
+		);
+	return loadNotInLibrary()
+		.filter(
+			(row) =>
+				tokens.some((t) => row.names.includes(t)) ||
+				(tokens.length > 1 && tokens.every((t) => covers(row, t)))
+		)
+		.map((row) => ({ assumed: row.assumed, reality: row.reality }));
+}
+
 function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 	const manifest = loadComponentsManifest();
 	const needle = String(query ?? '')
@@ -104,13 +305,88 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 		? manifest.components
 		: manifest.components.filter((c) => !c.referenceOnly);
 
+	// No query: the catalog, one line per component (review D6-19) — the
+	// answer to "which components exist?", which no tool gave before.
+	if (!needle || needle === '*') {
+		return {
+			query: query ?? '',
+			count: pool.length,
+			catalog: pool.map((c) => `${c.name} (${c.group}): ${c.description}`),
+			hint: 'The whole consumer catalog. get_component({ name }) for one; search_components({ query }) to rank by a need.',
+		};
+	}
+
+	const tokens = tokenize(needle);
+	const notInLibrary = matchNotInLibrary(tokens);
+
+	// A matched picker row NAMES the real component ("`BbDrawer` / `BbSheet` →
+	// It is BbOffCanvas"). Rank those first: the picker knows the answer, and
+	// returning nothing for `drawer` while BbOffCanvas ships is the whole bug.
+	const redirected = new Set();
+	for (const { reality } of notInLibrary)
+		for (const name of reality.match(/\bBb[A-Z][A-Za-z]+/g) ?? [])
+			redirected.add(name);
+
 	const scored = pool
-		.map((c) => ({ c, score: scoreComponent(c, needle) }))
+		.map((c) => {
+			const base = scoreComponent(c, tokens);
+			const bonus = redirected.has(c.name) ? 90 : 0;
+			return bonus > 0
+				? { c, matched: base.matched + 1, score: base.score + bonus }
+				: { c, ...base };
+		})
 		.filter(({ score }) => score > 0)
-		// Ties break alphabetically so results are stable between calls.
-		.sort((a, b) => b.score - a.score || a.c.name.localeCompare(b.c.name));
+		// More of the query matched wins first; then strength; then alphabetical
+		// so results are stable between calls.
+		.sort(
+			(a, b) =>
+				b.matched - a.matched ||
+				b.score - a.score ||
+				a.c.name.localeCompare(b.c.name)
+		);
 
 	const shown = scored.slice(0, max);
+
+	// Internal components an exact search would have found (review D6-15):
+	// 'CommonPopover' answered "No manifest match" although it is in the
+	// manifest, only filtered out as reference-only.
+	const hiddenReferenceOnly = includeReferenceOnly
+		? []
+		: manifest.components
+				.filter((c) => c.referenceOnly)
+				.filter((c) => scoreComponent(c, tokens).score >= 80)
+				.map((c) => c.name);
+
+	/**
+	 * Public type exports whose name matches the query. Scored the same way as
+	 * a component name (exact, prefix, substring) but never mixed into the
+	 * component list — a type is not something you render, and ranking it
+	 * beside components is how it gets written as a tag.
+	 */
+	const matchedTypes = (manifest.types ?? [])
+		.filter((type) => {
+			const lower = type.name.toLowerCase();
+			return tokens.some(
+				(token) => lower === token || lower.includes(token.toLowerCase())
+			);
+		})
+		// `api` first: those are the types you meet writing markup. The rest are
+		// wrapper props and internals, which rank below anything you would use.
+		.sort((a, b) => TYPE_USAGE_RANK[a.usage] - TYPE_USAGE_RANK[b.usage])
+		.slice(0, max)
+		.map((type) => ({
+			name: type.name,
+			kind: 'type',
+			usage: type.usage,
+			component: type.component,
+			...(type.deprecated ? { deprecated: true } : {}),
+			...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
+			usedBy: type.usedBy ?? [],
+			// The short answer only; get_component(name) has the definition.
+			...(type.values ? { values: type.values } : {}),
+			import: `import type { ${type.replacedBy ?? type.name} } from 'bitboss-ui';`,
+		}));
+
 	return {
 		query: query ?? '',
 		count: shown.length,
@@ -128,6 +404,30 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 			referenceOnly: Boolean(c.referenceOnly),
 			contract: c.contract,
 		})),
+		// Authoritative answers for names agents invent. Present on hits too: a
+		// `card` query that ranks BbBaseButton (its description mentions cards)
+		// still needs the picker's verdict that there is no BbCard.
+		...(notInLibrary.length > 0 ? { notInLibrary } : {}),
+		// A query that names a public TYPE gets it back as a type, so the answer
+		// to "is BbTableColumn a thing" is never an empty component list. The
+		// consumer who hit this concluded the export was undocumented and
+		// allowlisted the tag.
+		...(matchedTypes.length > 0 ? { types: matchedTypes } : {}),
+		...(hiddenReferenceOnly.length
+			? {
+					hiddenReferenceOnly,
+					referenceOnlyHint:
+						'Internal building blocks, not consumer API: never write them in a template. Use the ranked components; pass includeReferenceOnly: true only to read how one works.',
+				}
+			: {}),
+		guidance:
+			notInLibrary.length > 0
+				? 'The `notInLibrary` entries are the authoritative answer for this query — prefer them over the ranked components, and do not hand-roll what they redirect you to.'
+				: shown.length > 0
+					? 'Ranked by relevance. Confirm props with `get_component` before writing usage code.'
+					: matchedTypes.length > 0
+						? 'No component matches, but `types` does: these are TYPE exports. Import one for the value you pass to the prop named in its `usedBy` — never write it as a tag, and never allowlist it.'
+						: 'No manifest match and no picker entry. Zero results does NOT mean "not covered" — search a single plain noun (`table`, not `data table`), then read the guide `component-picker` (its "Not in this library" table is the full list of names that do not exist and what to use instead) before building anything by hand.',
 	};
 }
 
@@ -141,7 +441,7 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
  * is what makes an agent invent API, which is precisely what this server
  * exists to prevent.
  */
-const MARKDOWN_DEFAULT_MAX_CHARS = 40000;
+const MARKDOWN_DEFAULT_MAX_CHARS = 16000; // was 40 000 (MCP panel 2026-09-26)
 
 /**
  * Cut `text` to `maxChars` on a line boundary, reporting what was dropped.
@@ -176,16 +476,683 @@ function truncateMarkdown(text, maxChars, readHint) {
 	};
 }
 
-function getComponent({ name, maxChars } = {}) {
+/**
+ * Names an agent brings from v2, from an older beta or from habit, mapped to
+ * what replaced them. Parsed from the shipped docs so there is one source of
+ * truth: the v2 → v3 guide's § 5.1 component table, and changelog rows that
+ * say "BbX is renamed BbY". Without it `get_component('BbChip')` answered
+ * "unknown component" although the guide had the exact answer (review D6-5).
+ */
+let cachedRetired = null;
+function loadRetired() {
+	if (cachedRetired) return cachedRetired;
+	cachedRetired = new Map();
+	const guidePath = join(AI_ROOT, 'guides', 'migration', 'v2-to-v3.md');
+	if (existsSync(guidePath)) {
+		const md = readFileSync(guidePath, 'utf-8');
+		const table = md.split(/^### 5\.1 .*$/m)[1]?.split(/^### /m)[0] ?? '';
+		for (const line of table.split('\n')) {
+			if (!line.startsWith('|')) continue;
+			const [was, now, todo] = line
+				.replace(/^\|/, '')
+				.replace(/\|\s*$/, '')
+				.split('|')
+				.map((cell) => cell.trim());
+			if (!was || !now || /^-+$/.test(was) || was === 'v2') continue;
+			for (const [, retired] of was.matchAll(/`(\w+)`/g)) {
+				cachedRetired.set(retired, {
+					now: now.replace(/\*\*/g, ''),
+					todo: (todo ?? '').replace(/\*\*/g, '').split(/(?<=\.)\s/)[0],
+					guide: 'migration/v2-to-v3.md',
+					section: '5.1 Components renamed, split, or removed',
+				});
+			}
+		}
+	}
+	if (existsSync(CHANGELOG_PATH)) {
+		const doc = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+		for (const row of doc.breaking ?? []) {
+			const match = String(row.description ?? '').match(
+				/\b(Bb[A-Z]\w+) is renamed (Bb[A-Z]\w+)/
+			);
+			if (match && !cachedRetired.has(match[1])) {
+				cachedRetired.set(match[1], {
+					now: `\`${match[2]}\``,
+					todo: row.description.split(/(?<=\.)\s|—/)[0].trim(),
+					guide: row.guide ?? null,
+					firstReleasedIn: row.firstReleasedIn ?? null,
+				});
+			}
+		}
+	}
+	return cachedRetired;
+}
+
+/** `bb-date-picker-input` → `BbDatePickerInput`; `button` → `Button`. */
+const pascal = (value) =>
+	String(value ?? '')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((part) => part[0].toUpperCase() + part.slice(1))
+		.join('');
+
+/** Levenshtein distance, small inputs only. */
+function editDistance(a, b) {
+	const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i += 1) {
+		let previous = row[0];
+		row[0] = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const current = row[j];
+			row[j] = Math.min(
+				row[j] + 1,
+				row[j - 1] + 1,
+				previous + (a[i - 1] === b[j - 1] ? 0 : 1)
+			);
+			previous = current;
+		}
+	}
+	return row[b.length];
+}
+
+/**
+ * Find the component an agent meant. Exact first; then the spellings agents
+ * really send — `bb-button`, `bbbutton`, `Button` (review D6-2) — before
+ * giving up with the nearest names.
+ */
+function resolveComponent(manifest, name) {
+	const raw = String(name ?? '').trim();
+	const exact = manifest.components.find((c) => c.name === raw);
+	if (exact) return { entry: exact };
+	const byLower = new Map(
+		manifest.components.map((c) => [c.name.toLowerCase(), c])
+	);
+	const candidates = [raw, pascal(raw)].flatMap((value) => [
+		value.toLowerCase(),
+		`bb${value.toLowerCase().replace(/^bb/, '')}`,
+	]);
+	for (const candidate of candidates) {
+		const hit = byLower.get(candidate);
+		if (hit) return { entry: hit, resolvedFrom: raw };
+	}
+	return null;
+}
+
+function nearestComponents(manifest, name, count = 3) {
+	const needle = pascal(name).toLowerCase().replace(/^bb/, '');
+	// A partial name (`BbInput`) matches the components that contain it
+	// (BbTextInput, BbNumberInput…) before any edit-distance guess.
+	const containing = manifest.components
+		.filter((c) => !c.referenceOnly)
+		.map((c) => c.name)
+		.filter((n) => needle.length >= 3 && n.toLowerCase().includes(needle));
+	if (containing.length) return containing.slice(0, Math.max(count, 5));
+	return manifest.components
+		.filter((c) => !c.referenceOnly)
+		.map((c) => ({
+			name: c.name,
+			distance: editDistance(needle, c.name.toLowerCase().replace(/^bb/, '')),
+		}))
+		.sort((a, b) => a.distance - b.distance)
+		.slice(0, count)
+		.filter(({ distance }) => distance <= Math.max(3, needle.length / 2))
+		.map(({ name: found }) => found);
+}
+
+/**
+ * A component whose props are generic over its ROW (`BbTableProps<Row>`,
+ * `BbSelectProps<Item>`): a prop type names the parameter `T`.
+ */
+const isGeneric = (entry) =>
+	entry.props.some((p) =>
+		/(^|[^A-Za-z0-9_])T([^A-Za-z0-9_]|$)/.test(p.type ?? '')
+	);
+
+const propsType = (entry) =>
+	`${entry.name}Props${isGeneric(entry) ? '<Row>' : ''}['pt']`;
+
+/** `row: '…', 'row:selected': '…'` — the object form, from the real parts. */
+function ptExample(entry) {
+	const names = entry.pt.parts.map((p) => p.name);
+	const part =
+		['row', 'option', 'item', 'icon', 'label'].find((n) => names.includes(n)) ??
+		names[0];
+	// A state that is on for this part: per-node states name their parts.
+	const state = (
+		entry.pt.states?.find((s) =>
+			new RegExp(`\`${part}\``).test(s.description ?? '')
+		) ??
+		entry.pt.states?.find((s) => /^Component-wide/.test(s.description ?? ''))
+	)?.name;
+	return `${part}: '…'${state ? `, '${part}:${state}': '…'` : ''}`;
+}
+
+const PT_TYPING_READ =
+	"get_guide({ name: 'passthrough.md', sections: ['Typing `pt` in `<script>`'] })";
+
+function ptTyping(entry) {
+	// Both after-bench misses (2026-09-24) typed a table-agnostic preset
+	// `BbTableProps<any>['pt']`: say what to write when there is no row type.
+	const anyRow = isGeneric(entry)
+		? ` (\`${entry.name}Props['pt']\` for a preset that fits any row type, never \`<any>\`)`
+		: '';
+	return `In <script> (a const, a preset, a wrapper's \`pt\` prop) type it as \`${propsType(entry)}\`${anyRow} with \`satisfies\` for a const; a split global map uses \`definePt\` from 'bitboss-ui/vite'. PtValue / PtMap are not exported. ${PT_TYPING_READ}`;
+}
+
+/**
+ * The next reads a component answer points at, each one call. Built from what
+ * the contract itself links, so it cannot name a guide the package lacks.
+ */
+function seeAlso(entry, contract) {
+	const out = [];
+	// The option-list family links the items playbook; its wrapper section is
+	// where "write a MemberSelect around BbSelect" is answered (Q52.6.1).
+	if (/options-items-playbook\.md/.test(contract) && isGeneric(entry))
+		out.push(
+			`Your own ${entry.name} with fixed items (a CustomerSelect): a preset, one call to definePreset (a helper you copy from the guide, not a bitboss-ui export): get_guide({ name: 'preset-components.md' }). Wrapping BbSelect in your own component with its own logic: get_guide({ name: 'options-items-playbook.md', sections: ['Wrapping BbSelect in your own component'] })`
+		);
+	if (entry.validated)
+		out.push(
+			`Validation (rules or a Zod / Valibot / Yup schema): get_guide({ name: 'validated-forms.md' })`
+		);
+	return out;
+}
+
+/** Guide sections of a contract: everything under `## Usage & Guidelines`. */
+function contractGuideSections(markdown) {
+	const all = splitSections(markdown);
+	const start = all.findIndex(
+		(s) => s.level === 2 && /^Usage & Guidelines/i.test(s.title)
+	);
+	if (start === -1) return [];
+	const end = all.findIndex((s, i) => i > start && s.level === 2);
+	return all.slice(start + 1, end === -1 ? undefined : end);
+}
+
+/*
+ * A section is served whole up to SECTION_CAP chars. Past that (the review
+ * found a 142.9K `migration/v2-to-v3.md` section behind one search hit) it
+ * answers its own outline: ask again for a sub-section, or pass maxChars: 0.
+ */
+const SECTION_CAP = 16000;
+function sectionAnswer(sec, all, maxChars) {
+	if (maxChars === 0) return { title: sec.title, text: sec.text };
+	const cap = maxChars > 0 ? maxChars : SECTION_CAP;
+	if (sec.text.length <= cap) return { title: sec.title, text: sec.text };
+	const inner = all.filter(
+		(other) =>
+			other !== sec && other.level > sec.level && sec.text.includes(other.text)
+	);
+	// No sub-sections to point at (v2-to-v3 § 5.6, 68K), or an explicit cap:
+	// the text itself, cut — never an empty outline (adversarial review 2).
+	if (!inner.length || maxChars > 0) {
+		const cut = sec.text.slice(0, cap);
+		const end = cut.lastIndexOf('\n');
+		return {
+			title: sec.title,
+			text: end > cap / 2 ? cut.slice(0, end) : cut,
+			truncated: true,
+			chars: sec.text.length,
+			hint: `Cut at ${cap} of ${sec.text.length} chars. maxChars: 0 returns all of it${inner.length ? ', or ask for a sub-section by title' : ''}.`,
+		};
+	}
+	// Sub-sections: the section's own lead-in (up to 4K) and its outline.
+	const own = sec.own.length > 4000 ? `${sec.own.slice(0, 4000)} …` : sec.own;
+	return {
+		title: sec.title,
+		chars: sec.text.length,
+		text: own,
+		outline: outline(inner),
+		hint: `This section is ${sec.text.length} chars: its lead-in is above; ask for a sub-section by title, or pass maxChars: 0 for all of it.`,
+	};
+}
+
+/*
+ * A multi-part answer (several sections, members or recipe files) stops at
+ * ANSWER_CAP chars and names the rest: one call per part never came to 149K
+ * (BbTable, every section at once) or 52K (every member) by accident.
+ */
+const ANSWER_CAP = 24000;
+function capParts(parts, label) {
+	const kept = [];
+	let size = 0;
+	for (const part of parts) {
+		const n = JSON.stringify(part).length;
+		if (kept.length && size + n > ANSWER_CAP) break;
+		kept.push(part);
+		size += n;
+	}
+	const rest = parts.slice(kept.length);
+	return {
+		kept,
+		...(rest.length
+			? {
+					[`remaining${label}`]: rest.map((part) => part.title ?? part.name),
+				}
+			: {}),
+	};
+}
+
+/** Sections every agent needs, served whole in the full answer. */
+const ALWAYS_SECTIONS = [/^gotchas/i, /^accessibility/i];
+/** The summary keeps only these whole; the rest are in the outline (MCP panel 2026-09-26). */
+const SUMMARY_SECTIONS = [/^gotchas/i];
+
+/*
+ * SUMMARY ROWS (MCP panel 2026-09-26, owner: compact by default, expand on
+ * request). Blind Haiku runs saved `get_component BbTable` (38–47 KB) to a file
+ * to read it; Claude Code warns above ~10K tokens of tool output. The summary
+ * keeps EVERY name (a partial prop list is what makes agents invent API) as one
+ * line — name, type, default, the description's first sentence — and marks a
+ * cut sentence with " …": `members: ['name']` returns the full row.
+ */
+function firstSentence(text, cap = 160) {
+	const flat = String(text ?? '')
+		.replace(/\s+/g, ' ')
+		.trim();
+	if (!flat) return '';
+	// A sentence ends at ". " before a capital, a backtick or a bracket — not
+	// inside "1.234,56", "v3.0.0" or after "e.g." / "i.e." / "etc.".
+	const ends = [...flat.matchAll(/[.!?](?=\s+[A-Z`([]|$)/g)]
+		.map((m) => m.index)
+		.filter((i) => !/\b(e\.g|i\.e|etc|vs|approx)$/i.test(flat.slice(0, i)));
+	let stop = ends[0] ?? flat.length - 1;
+	// A second sentence that limits the first ("Only …", "Ignored with …",
+	// "Not called in …") changes what the first one means: keep it.
+	const next = flat.slice(stop + 1).trim();
+	if (
+		ends[1] != null &&
+		/^(Only|Not|Never|Ignored|Mutually|Takes precedence|Requires|Must|Has no effect|Without|Unless|Deprecated|Wins over|Overrides)\b/.test(
+			next
+		)
+	)
+		stop = ends[1];
+	// A short, generic first sentence ("The id.") says little: add the next.
+	if (stop + 1 < 60 && ends[ends.indexOf(stop) + 1] != null)
+		stop = ends[ends.indexOf(stop) + 1];
+	let out = flat.slice(0, stop + 1);
+	if (out.length > cap) {
+		let cut = out.lastIndexOf(' ', cap);
+		if (cut < 40) cut = cap;
+		let head = out.slice(0, cut);
+		// Never end inside a code span: an unpaired backtick reads as code.
+		if ((head.match(/`/g) ?? []).length % 2)
+			head = head.slice(0, head.lastIndexOf('`')).trimEnd();
+		out = `${head} …`;
+	} else if (out.length < flat.length) out += ' …';
+	return out;
+}
+
+/** A type as the summary prints it: no ` | undefined` tail, long ones cut. */
+function shortType(type, cap = 180) {
+	const t = String(type ?? '')
+		.replace(/\s*\|\s*undefined$/, '')
+		.replace(/\s+/g, ' ');
+	return t.length > cap ? `${t.slice(0, cap)}…` : t;
+}
+
+let sharedPropKeys = null;
+/**
+ * A prop folds only when EVERYTHING an agent reads off it is the same on
+ * every component: type, default, values and description (the adversarial
+ * review found `items` / `multiple` / `padding` folded with different types
+ * and defaults). A required prop never folds: its own line carries the fact.
+ */
+const foldKey = (p) =>
+	[
+		p.name,
+		p.type,
+		p.default ?? '',
+		(p.values ?? []).join('|'),
+		p.description ?? '',
+	].join('\u0000');
+/**
+ * Prop rows that are identical (name AND description) on 3+ public components:
+ * the form-field set on 16 controls, the Inertia link props on the buttons.
+ * The summary lists them by name once (`common`) instead of repeating ~4–8 KB
+ * of the same prose per component; `members` returns any of them whole.
+ */
+function sharedProps(manifest) {
+	if (sharedPropKeys) return sharedPropKeys;
+	const count = new Map();
+	for (const component of manifest.components ?? []) {
+		if (component.referenceOnly) continue;
+		for (const prop of component.props ?? []) {
+			if (!prop.description || prop.name.startsWith('pt')) continue;
+			const key = foldKey(prop);
+			if (prop.required) continue;
+			count.set(key, (count.get(key) ?? 0) + 1);
+		}
+	}
+	sharedPropKeys = new Set(
+		[...count].filter(([, n]) => n >= 3).map(([key]) => key)
+	);
+	return sharedPropKeys;
+}
+
+const propLine = (p) => {
+	const values =
+		p.values?.length &&
+		!/Registry|VariantType|BbPtScopeName|LocaleKey/.test(String(p.type)) &&
+		!p.values.some((v) => /\s/.test(String(v))) &&
+		!p.values.every((v) => String(p.type).includes(String(v)))
+			? ` ∈ ${p.values.map((v) => String(v)).join('|')}`.slice(0, 120)
+			: '';
+	return `${p.name}${p.required ? '' : '?'}: ${shortType(p.type)}${values}${p.default != null && p.default !== '' ? ` = ${p.default}` : ''}${p.description ? ` — ${firstSentence(p.description)}` : ''}`;
+};
+const eventLine = (e) =>
+	`${e.name}${String(e.signature ?? '').replace(/: void$/, '')}${e.description ? ` — ${firstSentence(e.description)}` : ''}`;
+/** The top-level keys of a slot scope type `{ a?: …; b: … }`. */
+function scopeKeys(type) {
+	const t = String(type ?? '').trim();
+	if (!t.startsWith('{')) return [];
+	const keys = [];
+	let depth = 0;
+	let token = '';
+	const inner = t.slice(1, -1);
+	for (let i = 0; i < inner.length; i++) {
+		const ch = inner[i];
+		if ('{([<'.includes(ch)) depth++;
+		// The `>` of an arrow `=>` closes nothing.
+		else if ('})]'.includes(ch) || (ch === '>' && inner[i - 1] !== '='))
+			depth--;
+		if (depth === 0 && (ch === ';' || ch === ',')) {
+			const key = token.trim().match(/^([\w$]+)\??\s*:/)?.[1];
+			if (key) keys.push(key);
+			token = '';
+		} else token += ch;
+	}
+	const last = token.trim().match(/^([\w$]+)\??\s*:/)?.[1];
+	if (last) keys.push(last);
+	return keys;
+}
+const slotLine = (sl) => {
+	// A named scope type (BbSelectOptionSlotProps…) carries resolved `fields`.
+	const keys = sl.fields?.length
+		? sl.fields.map((f) => String(f).match(/^([\w$]+)/)?.[1]).filter(Boolean)
+		: scopeKeys(sl.type);
+	return `#${sl.name}${keys.length ? ` { ${keys.join(', ')} }` : ''}${sl.description ? ` — ${firstSentence(sl.description)}` : ''}`;
+};
+
+/** One line per v2/beta rename or removal (include 'history' for the records). */
+function historyLines(entry) {
+	const renamedFrom = new Set((entry.renamed ?? []).map((r) => r.from));
+	// A slot row reads as a slot (`#no-data → #empty`), a removal with no
+	// single successor carries its hint (Q51.16).
+	const spell = (r, name) => (r.surface === 'slot' ? `#${name}` : name);
+	// A rename that also maps VALUES says which: `inputDirection →
+	// listLayout` alone sent 2 of 3 answerers to `list-layout="vertical"`
+	// when the map is vertical → vertical-stretch (2026-09-24).
+	const values = (r) =>
+		Object.entries(r.fix?.valueMap ?? {})
+			.filter(([from, to]) => from !== to)
+			.map(([from, to]) => `"${from}" → "${to}"`)
+			.join(', ');
+	return [
+		...(entry.renamed ?? []).map(
+			(r) =>
+				`${spell(r, r.from)} → ${spell(r, r.to)}${r.fix?.kind && r.fix.kind !== 'rename' ? ` (${r.fix.kind})` : ''}${values(r) ? ` (values: ${values(r)})` : ''}`
+		),
+		...(entry.removed ?? [])
+			.filter((r) => !renamedFrom.has(r.name))
+			.map(
+				(r) =>
+					`${spell(r, r.name)} removed${r.new ? ` → ${spell(r, r.new)}` : ''}${r.hint ? ` — ${r.hint}` : ''}`
+			),
+	];
+}
+
+/** The compact `component` of the summary answer. */
+function summarizeComponent(entry, manifest) {
+	const shared = sharedProps(manifest);
+	const own = [];
+	const common = [];
+	for (const p of entry.props ?? []) {
+		if (p.name === 'pt' || p.name.startsWith('pt:')) continue;
+		if (!p.required && shared.has(foldKey(p))) common.push(p.name);
+		else own.push(propLine(p));
+	}
+	return {
+		name: entry.name,
+		...(entry.group ? { group: entry.group } : {}),
+		...(entry.description ? { description: entry.description } : {}),
+		props: own,
+		...(common.length
+			? {
+					commonProps: `${common.join(', ')} — optional props identical (type, default, description) on 3+ components (form fields, link props); members: ['${common[0]}'] returns one whole`,
+				}
+			: {}),
+		...(entry.models?.length
+			? {
+					models: entry.models.map(
+						(m) =>
+							`v-model${m.name === 'modelValue' ? '' : `:${m.name}`}: ${shortType(m.type)}`
+					),
+				}
+			: {}),
+		...(entry.events?.length ? { events: entry.events.map(eventLine) } : {}),
+		...(entry.slots?.length ? { slots: entry.slots.map(slotLine) } : {}),
+		...(entry.exposed?.length
+			? { exposed: entry.exposed.map((x) => `${x.name}: ${shortType(x.type)}`) }
+			: {}),
+		...(entry.pt?.parts?.length
+			? {
+					pt: `parts: ${entry.pt.parts.map((x) => x.name).join(', ')}${entry.pt.states?.length ? `; states: ${entry.pt.states.map((x) => x.name).join(', ')}` : ''}. Each is a \`pt:<part>\` / \`pt:<part>:<state>\` prop; the \`pt\` object takes the same keys WITHOUT the \`pt:\` prefix: { ${ptExample(entry)} }. What a part or state is: members: ['<part>'].`,
+				}
+			: {}),
+		...(entry.cssProps?.length
+			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
+			: {}),
+		...(entry.removed?.length || entry.renamed?.length
+			? { history: historyLines(entry) }
+			: {}),
+		...(entry.attrTargets ? { attrTargets: entry.attrTargets } : {}),
+		...(entry.referenceOnly ? { referenceOnly: true } : {}),
+	};
+}
+
+/**
+ * `members`: the whole rows for the names asked — props, events, slots
+ * (`#name` or `name`), v-models (`v-model:sort`) and pt parts / states
+ * (`pt:row`, `row`), whose descriptions the summary line leaves out.
+ */
+function pickMembers(entry, names) {
+	const norm = (n) =>
+		String(n)
+			.trim()
+			.replace(/^#/, '')
+			.replace(/^v-model:/, '')
+			.toLowerCase();
+	const wanted = names.map(norm);
+	const hit = new Set();
+	const take = (list, key = (x) => x.name) =>
+		(list ?? []).filter((x) => {
+			const k = String(key(x)).toLowerCase();
+			const ok = wanted.includes(k);
+			if (ok) wanted.forEach((w, i) => w === k && hit.add(i));
+			return ok;
+		});
+	const props = take(entry.props);
+	const events = take(entry.events);
+	const slots = take(entry.slots);
+	const models = (entry.models ?? []).filter((m) =>
+		names.some(
+			(n) =>
+				String(n).trim() ===
+				(m.name === 'modelValue' ? 'v-model' : `v-model:${m.name}`)
+		)
+	);
+	names.forEach((n, i) => {
+		if (/^v-model$/.test(String(n).trim()) && models.length) hit.add(i);
+	});
+	// pt: `row`, `pt:row`, `row:selected` / `pt:row:selected` (the part AND
+	// the state, both with their descriptions).
+	const ptWanted = names.map((n) =>
+		String(n).trim().replace(/^pt:/, '').toLowerCase().split(':')
+	);
+	const parts = (entry.pt?.parts ?? []).filter((x) =>
+		ptWanted.some(([part], i) => {
+			const ok = part === x.name.toLowerCase();
+			if (ok) hit.add(i);
+			return ok;
+		})
+	);
+	const states = (entry.pt?.states ?? []).filter((x) =>
+		ptWanted.some((segments, i) => {
+			const ok = segments.at(-1) === x.name.toLowerCase();
+			if (ok) hit.add(i);
+			return ok;
+		})
+	);
+	const notFound = names.filter((_, i) => !hit.has(i));
+	// Names built from a requested WORD (`loading` → `interactiveWhileLoading`,
+	// `loadingText`): a members-only call skips the summary, and a blind run
+	// concluded v2's enabled-while-loading had no v3 equivalent. Whole camel
+	// words only (`key` does not match `keyboardNavigation`).
+	const words = (n) =>
+		n
+			.replace(/^#/, '')
+			.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+			.toLowerCase()
+			.split(/[\s:_-]+/);
+	const asked = names.map(norm).filter((n) => n.length >= 3);
+	const related = [
+		...(entry.props ?? []).map((p) => p.name),
+		...(entry.events ?? []).map((e) => e.name),
+		...(entry.slots ?? []).map((sl) => `#${sl.name}`),
+	].filter(
+		(n) =>
+			!n.startsWith('pt:') &&
+			!asked.includes(n.replace(/^#/, '').toLowerCase()) &&
+			asked.some((a) => words(n).includes(a))
+	);
+	return {
+		...(props.length ? { props } : {}),
+		...(events.length ? { events } : {}),
+		...(slots.length ? { slots } : {}),
+		...(models.length ? { models } : {}),
+		...(parts.length || states.length
+			? {
+					pt: {
+						...(parts.length ? { parts } : {}),
+						...(states.length ? { states } : {}),
+					},
+				}
+			: {}),
+		...(related.length ? { related } : {}),
+		...(notFound.length ? { notFound } : {}),
+	};
+}
+
+/**
+ * `get_component({ name, sections?, include?, maxChars? })`.
+ *
+ * COMPACT BY DEFAULT (release review 2026-09-23, D6-4). The old answer was
+ * the manifest entry plus the whole contract cut at 40 000 chars: 76–101 KB,
+ * and the cut dropped `Gotchas` on six components while the tail it kept
+ * repeated the structured entry. Blind Haiku answerers could not read it and
+ * guessed. Now the default is the structured entry (props never cut — a
+ * partial prop list is what makes agents invent API) minus the parts that
+ * repeat it (`pt:*` prop rows: the `pt` section lists every part and state),
+ * the guide's outline, and its Gotchas + Accessibility sections. Guide
+ * sections, the component tree, the CSS variables with their descriptions
+ * and the whole contract come on request.
+ */
+function getComponent({
+	name,
+	sections,
+	include,
+	maxChars,
+	detail,
+	members,
+} = {}) {
 	const manifest = loadComponentsManifest();
-	const entry = manifest.components.find((c) => c.name === name);
+	const resolved = resolveComponent(manifest, name);
+	const entry = resolved?.entry;
 	if (!entry) {
+		/*
+		 * A public TYPE asked for as a component. `BbTableColumn`,
+		 * `BbDropdownItem`, `BbTabsItem` and `BbBreadcrumbsItem` are exports an
+		 * agent meets in a props table and reasonably looks up here; answering
+		 * "unknown component — try search_components" sent one consumer to the
+		 * `allowComponents` allowlist instead, which silences every check on the
+		 * tag. Answer the real question: what it is, and where it is used.
+		 */
+		const type = (manifest.types ?? []).find((t) => t.name === name);
+		if (type) {
+			const use = type.usedBy?.[0];
+			return {
+				found: true,
+				kind: 'type',
+				name,
+				usage: type.usage,
+				...(type.deprecated ? { deprecated: true } : {}),
+				...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
+				component: type.component,
+				usedBy: type.usedBy ?? [],
+				// What it is (Q50.2): the declaration, the accepted values when
+				// finite (open when `extensibleVia` names a registry), and the
+				// resolved fields when the declaration leans on a private type.
+				...(type.definition ? { definition: type.definition } : {}),
+				...(type.values ? { values: type.values } : {}),
+				...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
+				...(type.fields ? { fields: type.fields } : {}),
+				// A union of private members: each member's fields (Q51.21).
+				...(type.members ? { members: type.members } : {}),
+				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
+				hint: use
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. \`definition\` above is the type itself; call get_component('${use.component}') to see it in use.`
+					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
+			};
+		}
+		// A directive (`v-bb-tooltip`, `vBbTooltip`) — review D3-13.
+		const directiveName = String(name ?? '')
+			.trim()
+			.replace(/^vBb([A-Z]\w*)$/, (_, word) => `v-bb-${word.toLowerCase()}`)
+			.toLowerCase();
+		const directive = (manifest.directives ?? []).find(
+			(d) => d.name === directiveName
+		);
+		if (directive) {
+			const value = (manifest.types ?? []).find(
+				(t) => t.name === directive.value
+			);
+			return {
+				found: true,
+				kind: 'directive',
+				...directive,
+				...(value?.definition ? { valueDefinition: value.definition } : {}),
+				...(value?.fields ? { valueFields: value.fields } : {}),
+				hint: `A directive, the floating twin of ${directive.mirrors}: read get_component({ name: '${directive.mirrors}', sections: ['directive'] }) for its guide section.`,
+			};
+		}
+		const retired = loadRetired().get(String(name ?? '').trim());
+		if (retired) {
+			return {
+				found: false,
+				name,
+				retired: true,
+				now: retired.now,
+				todo: retired.todo,
+				guide: retired.guide,
+				...(retired.section ? { section: retired.section } : {}),
+				hint: `\`${name}\` is not in this version. \`now\` says what replaced it; read get_guide({ name: '${retired.guide}'${retired.section ? `, sections: ['${retired.section}']` : ''} }) for the full row.`,
+			};
+		}
+		const picker = matchNotInLibrary(tokenize(name));
+		const didYouMean = nearestComponents(manifest, name);
 		return {
 			found: false,
 			name,
-			hint: 'Unknown component name — try search_components first.',
+			...(didYouMean.length ? { didYouMean } : {}),
+			...(picker.length ? { notInLibrary: picker.slice(0, 3) } : {}),
+			hint: picker.length
+				? "Not a component here — `notInLibrary` is the picker's verdict for this name."
+				: 'Unknown component name. Try one of `didYouMean`, or search_components with a plain noun.',
 		};
 	}
+
+	const wanted = new Set(include ?? []);
 	const contractPath = entry.contract ?? null;
 	const contractAbsPath = contractPath
 		? join(PACKAGE_ROOT, 'dist', contractPath)
@@ -193,19 +1160,219 @@ function getComponent({ name, maxChars } = {}) {
 	const raw =
 		contractAbsPath && existsSync(contractAbsPath)
 			? readFileSync(contractAbsPath, 'utf-8')
-			: null;
-	const { content, ...meta } = truncateMarkdown(
-		raw,
-		maxChars,
-		`The structured \`component\` field above is COMPLETE (all props/events/slots) — the cut text is guidance prose only.`
+			: '';
+	const guide = contractGuideSections(raw);
+
+	/*
+	 * The types this component's own API names, so "what do I import to build
+	 * the value for `columns`?" is answered where the question is asked. Without
+	 * it an agent reads `BbTableColumn<T>[]` in the props table and has nowhere
+	 * to go — one consumer concluded the export was undocumented and allowlisted
+	 * the tag. Only types the component actually uses, never the whole export
+	 * list: a menu is not an answer.
+	 */
+	const types = (manifest.types ?? [])
+		.filter((type) =>
+			(type.usedBy ?? []).some((use) => use.component === entry.name)
+		)
+		.filter((type) => !type.deprecated)
+		.map((type) => ({
+			name: type.name,
+			usedBy: (type.usedBy ?? []).filter((use) => use.component === entry.name),
+			import: `import type { ${type.name} } from 'bitboss-ui';`,
+			...(type.values ? { values: type.values } : {}),
+			...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
+			...(type.fields ? { fields: type.fields } : {}),
+			// The union's shape, then what each private member takes (Q51.21).
+			...(!type.values && !type.fields && type.definition
+				? { definition: type.definition }
+				: {}),
+			...(type.members ? { members: type.members } : {}),
+		}));
+
+	const ptRows = entry.props.filter(
+		(p) => p.name === 'pt' || p.name.startsWith('pt:')
 	);
+	const found = {
+		found: true,
+		...(resolved.resolvedFrom ? { resolvedFrom: resolved.resolvedFrom } : {}),
+	};
+
+	// `members`: exactly the rows asked for, nothing else.
+	if (members?.length) {
+		const picked = pickMembers(entry, members);
+		// Rows past the cap are named, not dropped.
+		for (const kind of ['props', 'events', 'slots']) {
+			if (!picked[kind]) continue;
+			const { kept, ...rest } = capParts(picked[kind], 'Members');
+			picked[kind] = kept;
+			if (rest.remainingMembers)
+				picked.remainingMembers = [
+					...(picked.remainingMembers ?? []),
+					...rest.remainingMembers,
+				];
+		}
+		return { ...found, name: entry.name, ...picked };
+	}
+
+	const full = detail === 'full';
+	const asked = (sections?.length ?? 0) + (include?.length ?? 0) > 0;
+	const { picked, missing } = pickSections(guide, sections);
+	const guideOutline = guide
+		.filter((s) => s.level === 3)
+		.map((s) => ({ title: s.title, chars: s.text.length }));
+
+	// A follow-up for sections / include parts returns ONLY those parts: the
+	// summary was already read (it used to be resent whole: BbTable + one
+	// section was 49K chars for a ~9K section).
+	if (asked && !full) {
+		return {
+			...found,
+			name: entry.name,
+			...(picked.length
+				? (() => {
+						const { kept, ...rest } = capParts(
+							picked.map((sec) => sectionAnswer(sec, guide, maxChars)),
+							'Sections'
+						);
+						return { sections: kept, ...rest };
+					})()
+				: {}),
+			// A missed title gets the outline, never the whole answer.
+			...(missing.length ? { notFound: missing, outline: guideOutline } : {}),
+			...(wanted.has('tree') && entry.tree ? { tree: entry.tree } : {}),
+			...(wanted.has('cssProps') && entry.cssProps
+				? { cssProps: entry.cssProps }
+				: {}),
+			...(wanted.has('css') && entry.css ? { css: entry.css } : {}),
+			...(wanted.has('ptProps')
+				? (() => {
+						const { kept, ...rest } = capParts(ptRows, 'PtProps');
+						return { ptProps: kept, ...rest, pt: entry.pt };
+					})()
+				: {}),
+			...(wanted.has('history')
+				? { removed: entry.removed ?? [], renamed: entry.renamed ?? [] }
+				: {}),
+			...(wanted.has('contract')
+				? (() => {
+						const c = truncateMarkdown(
+							raw,
+							maxChars,
+							'Pass maxChars: 0 for the whole contract.'
+						);
+						return {
+							contract: c.content,
+							...(c.truncated
+								? { contractTruncated: true, contractHint: c.hint }
+								: {}),
+						};
+					})()
+				: {}),
+		};
+	}
+
+	if (!full) {
+		const kept = guide.filter((s) =>
+			SUMMARY_SECTIONS.some((re) => re.test(s.title))
+		);
+		return {
+			...found,
+			component: summarizeComponent(entry, manifest),
+			...(types.length > 0 ? { types } : {}),
+			...(entry.pt?.parts?.length ? { ptTyping: ptTyping(entry) } : {}),
+			...(seeAlso(entry, raw).length ? { seeAlso: seeAlso(entry, raw) } : {}),
+			contractPath,
+			guide: {
+				sections: guideOutline,
+				...(kept.length
+					? { always: kept.map((s) => ({ title: s.title, text: s.text })) }
+					: {}),
+			},
+			hint: `Summary: every name is listed; a line ending " …" is cut. Whole rows: members: ['<name>']; guide prose: sections: ['<title>']; include: ['tree' | 'cssProps' | 'css' | 'ptProps' | 'history' | 'contract']; detail: 'full' for the whole entry.`,
+		};
+	}
+
+	const component = {
+		...entry,
+		props: (wanted.has('ptProps')
+			? entry.props
+			: entry.props.filter((p) => !ptRows.includes(p))
+		).map(({ required, ...prop }) => (required ? { ...prop, required } : prop)),
+		...(entry.cssProps && !wanted.has('cssProps')
+			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
+			: {}),
+	};
+	if (!wanted.has('tree')) delete component.tree;
+	// The rendered `.bb-*` classes (Q46.5) are for tools (`check`, `validate`);
+	// an agent restyles through pt and the locals. include: ['css'] lists them.
+	if (!wanted.has('css')) delete component.css;
+	// `removed` and `renamed` repeat each other with migration metadata; one
+	// line per old name answers "what happened to X" (include 'history' for
+	// the records the fixers use).
+	if (
+		!wanted.has('history') &&
+		(entry.removed?.length || entry.renamed?.length)
+	) {
+		component.history = historyLines(entry);
+		delete component.removed;
+		delete component.renamed;
+	}
+
+	const always = guide.filter(
+		(s) => ALWAYS_SECTIONS.some((re) => re.test(s.title)) && !picked.includes(s)
+	);
+	const contract = wanted.has('contract')
+		? truncateMarkdown(
+				raw,
+				maxChars,
+				'The structured `component` field above is complete; the cut text is guide prose.'
+			)
+		: null;
+
 	return {
 		found: true,
-		// Never truncated: the precision-critical surface.
-		component: entry,
+		...(resolved.resolvedFrom ? { resolvedFrom: resolved.resolvedFrom } : {}),
+		component,
+		...(types.length > 0 ? { types } : {}),
+		...(ptRows.length && !wanted.has('ptProps')
+			? {
+					ptProps: `${ptRows.length} pt:* props not listed: every \`pt:<part>\` and \`pt:<part>:<state>\` in \`component.pt\` is a prop taking a class string (or object / array), and \`pt\` takes the same entries as one object keyed WITHOUT the \`pt:\` prefix: { ${ptExample(entry)} }.`,
+				}
+			: {}),
+		/*
+		 * Where agents land when they type `pt` in <script> (Q52.7.1 receipts):
+		 * 5 of 6 blind Haiku runs opened get_component first, never saw the
+		 * passthrough guide's typing section, and hand-copied the part unions
+		 * or invented a `PtValue`. The one that found the section scored 4/4.
+		 */
+		...(entry.pt?.parts?.length ? { ptTyping: ptTyping(entry) } : {}),
+		...(seeAlso(entry, raw).length ? { seeAlso: seeAlso(entry, raw) } : {}),
+		guide: {
+			sections: guide
+				.filter((s) => s.level === 3)
+				.map((s) => ({ title: s.title, chars: s.text.length })),
+			...(picked.length
+				? { requested: picked.map((s) => ({ title: s.title, text: s.text })) }
+				: {}),
+			...(missing.length ? { notFound: missing } : {}),
+			...(always.length
+				? { always: always.map((s) => ({ title: s.title, text: s.text })) }
+				: {}),
+		},
 		contractPath,
-		contractContent: content,
-		...meta,
+		...(contract
+			? {
+					contract: contract.content,
+					...(contract.truncated
+						? {
+								contractTruncated: true,
+								contractHint: contract.hint,
+							}
+						: {}),
+				}
+			: {}),
+		hint: `Structured API above is complete. Read guide sections with get_component({ name: '${entry.name}', sections: ['<title from guide.sections>'] }); add include: ['tree' | 'cssProps' | 'css' | 'ptProps' | 'history' | 'contract'] for the component tree, CSS variables with descriptions, the .bb-* classes it renders, every pt:* row, the full v2/beta rename records, or the whole contract. search_docs finds a topic across all docs.`,
 	};
 }
 
@@ -219,16 +1386,53 @@ const STYLES_CSS = join(PACKAGE_ROOT, 'dist', 'styles.css');
  * every comma-part is built solely from these — `:root`, `.light`, `:root.dark`
  * and `html.dark` are theme roots; `.bb-tooltip .bb-common-popover__bubble` is
  * not, however many `--bb-*` it redeclares.
+ *
+ * `.bb-theme` is a theme root too: it is the island boundary the derived block
+ * re-specifies its formulas on (design-tokens.md § the CSS mechanic).
  */
-const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark|\.bb-theme)+$/;
+
+/**
+ * Unwrap the `:where(…)` / `:is(…)` a selector list may be wrapped in. The
+ * derived-token block ships as `:where(:root,.light,.dark,.bb-theme)`, and
+ * splitting THAT on commas yields `:where(:root` and `.bb-theme)` — neither of
+ * which is a theme root, so without this every derived token is misreported as
+ * a component rebind with no value. That is not a cosmetic slip: `localRebinds`
+ * is documented to agents as "not something to copy".
+ */
+function unwrapSelectorList(selector) {
+	const trimmed = selector.trim();
+	const match = /^:(?:where|is)\((.*)\)$/s.exec(trimmed);
+	return match ? match[1] : trimmed;
+}
+
 function isThemeSelector(selector) {
-	return selector
+	return unwrapSelectorList(selector)
 		.split(',')
 		.every((part) =>
 			THEME_ROOT_PART.test(part.replace(/[\s>+~]+/g, '').trim())
 		);
 }
 
+/**
+ * A theme token is a KNOB (the consumer sets it) or DERIVED (a formula the
+ * library recomputes at every theme boundary). Setting a derived value is the
+ * documented trap — it stops tracking the knob it was computed from.
+ *
+ * The split is structural in the shipped sheet, so it needs no curated list to
+ * drift: knobs are declared on the plain scheme roots, formulas inside the
+ * `:where(…)` boundary block. A name in BOTH is a knob that TRACKS another one
+ * until pinned — and because the boundary block re-specifies it, a pin has to
+ * be repeated at every boundary it is used on, `.dark` included.
+ */
+const isDerivedBlock = (selector) => /^:(?:where|is)\(/.test(selector.trim());
+const tokenKind = (inKnobBlock, inDerivedBlock) =>
+	inKnobBlock && inDerivedBlock
+		? 'knob-tracking'
+		: inDerivedBlock
+			? 'derived'
+			: 'knob';
+
 /**
  * Walk a stylesheet and yield every `--bb-*` declaration WITH the selector that
  * owns it. A flat regex cannot do this: it sees a declaration but not its
@@ -237,6 +1441,11 @@ function isThemeSelector(selector) {
  * tolerant of the missing final semicolon that minified CSS emits) is the
  * cheapest way to keep the scope — and this file ships in the package, so it
  * may not reach for postcss the way the dev-only `check:tokens` script does.
+ *
+ * `when` carries the enclosing `@supports` condition(s), if any: a value there
+ * is not the theme value but one browser path — `--bb-primary-fg` ships an
+ * auto-contrast formula with literal fallbacks, and folding the fallbacks into
+ * the theme values tells an agent to pin a literal that defeats the formula.
  */
 function* eachTokenDeclaration(css) {
 	const stack = [];
@@ -257,11 +1466,23 @@ function* eachTokenDeclaration(css) {
 			quote = char;
 			buffer += char;
 		} else if (char === '{') {
-			stack.push(buffer.trim());
+			// A comment before a rule would otherwise prefix its selector or
+			// hide the `@supports` it opens.
+			stack.push(buffer.replace(/\/\*[\s\S]*?\*\//g, '').trim());
 			buffer = '';
 		} else if (char === '}' || char === ';') {
 			const decl = declaration();
-			if (decl) yield { ...decl, selector: stack[stack.length - 1] ?? '' };
+			if (decl) {
+				const supports = stack
+					.slice(0, -1)
+					.filter((scope) => scope.startsWith('@supports'))
+					.map((scope) => scope.replace(/^@supports\s*/, ''));
+				yield {
+					...decl,
+					selector: stack[stack.length - 1] ?? '',
+					...(supports.length ? { when: supports.join(' and ') } : {}),
+				};
+			}
 			if (char === '}') stack.pop();
 		} else {
 			buffer += char;
@@ -281,7 +1502,8 @@ function* eachTokenDeclaration(css) {
  * different components and is only meaningful inside that component's scope.
  * Serving them as one flat list would invite exactly the wrong move — an agent
  * writing `:root { --gap: … }` and wondering why nothing changed. They are
- * documented per component, which `get_component` already serves.
+ * documented per component: `get_component` carries them as `cssProps`, each
+ * with the root class to set it on, its default, and what it is.
  *
  * WHY `dist/styles.css` AND NOT `src/assets/css/variables.css`: `src/` is not
  * in the published package, so the source file does not exist for the consumer
@@ -301,9 +1523,27 @@ function listTokens({ filter } = {}) {
 	}
 	const css = readFileSync(STYLES_CSS, 'utf-8');
 	const byName = new Map();
-	for (const { name, value, selector } of eachTokenDeclaration(css)) {
-		const entry = byName.get(name) ?? { theme: [], local: [] };
+	for (const { name, value, selector, when } of eachTokenDeclaration(css)) {
+		const entry = byName.get(name) ?? {
+			theme: [],
+			local: [],
+			conditional: [],
+			knobBlock: false,
+			derivedBlock: false,
+		};
 		if (isThemeSelector(selector)) {
+			if (isDerivedBlock(selector)) entry.derivedBlock = true;
+			else entry.knobBlock = true;
+		}
+		if (when) {
+			// One browser path, not the theme value nor a dark override.
+			if (
+				!entry.conditional.some(
+					(c) => c.when === when && c.selector === selector
+				)
+			)
+				entry.conditional.push({ when, selector, value });
+		} else if (isThemeSelector(selector)) {
 			// Light first, dark after: report both rather than let one win.
 			if (!entry.theme.includes(value)) entry.theme.push(value);
 		} else if (!entry.local.some((r) => r.selector === selector)) {
@@ -320,11 +1560,13 @@ function listTokens({ filter } = {}) {
 	const tokens = [...byName.entries()]
 		.filter(([name]) => !needle || name.toLowerCase().includes(needle))
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, { theme, local }]) => ({
+		.map(([name, { theme, local, conditional, knobBlock, derivedBlock }]) => ({
 			name,
+			kind: tokenKind(knobBlock, derivedBlock),
 			value: theme[0],
 			...(theme.length > 1 ? { themeOverrides: theme.slice(1) } : {}),
 			...(local.length > 0 ? { localRebinds: local } : {}),
+			...(conditional.length > 0 ? { conditional } : {}),
 		}));
 	return {
 		count: tokens.length,
@@ -332,11 +1574,19 @@ function listTokens({ filter } = {}) {
 		tokens,
 		hint:
 			needle && tokens.length === 0
-				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours.`
-				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
+				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours. ${FONT_NOTE}`
+				: FONT_NOTE +
+					' Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. `conditional` is a value that applies only under an @supports condition (`when`) — e.g. an auto-contrast formula with literal fallbacks for older browsers; pinning a fallback literal defeats the formula. `kind` says what you may set: "knob" is yours; "derived" is a formula recomputed at every theme boundary, so setting it stops it tracking the knob it came from — set that knob instead; "knob-tracking" is a knob that follows another until you pin it, and the pin must be repeated at every boundary you use, .dark included. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
 	};
 }
 
+/**
+ * Q53.11: there is no font-family token, by ruling; agents kept looking for
+ * one. Said in every list_tokens answer.
+ */
+const FONT_NOTE =
+	"Components have no font token; they inherit the page's `font-family`. Set it on `body` (or a `.bb-theme` island) to theme it.";
+
 /** Every guide markdown path under dist/ai/guides, relative to that dir. */
 function collectGuidePaths(dir, prefix = '') {
 	const out = [];
@@ -352,41 +1602,509 @@ function collectGuidePaths(dir, prefix = '') {
 
 /** `list_guides()` — the shipped prose guides an agent can read. */
 function listGuides() {
-	const guides = collectGuidePaths(join(AI_ROOT, 'guides')).sort();
+	const guidesDir = join(AI_ROOT, 'guides');
+	const all = collectGuidePaths(guidesDir).sort();
+	/*
+	 * Title + summary per guide (review D6-13): 57 bare paths could not tell an
+	 * agent which one answers its question. The 40 per-component migration
+	 * pages collapse to one row — get_guide('migration/components/<kebab>').
+	 */
+	const perComponent = all.filter((p) => p.startsWith('migration/components/'));
+	const guides = all
+		.filter((p) => !perComponent.includes(p))
+		.map((path) => {
+			const markdown = readFileSync(join(guidesDir, path), 'utf-8');
+			const meta = frontmatter(markdown);
+			const title =
+				meta.title ??
+				stripFrontmatter(markdown)
+					.match(/^# (.+)$/m)?.[1]
+					?.trim();
+			return {
+				name: path,
+				...(title ? { title } : {}),
+				...(meta.summary ? { summary: meta.summary } : {}),
+			};
+		});
 	return {
-		count: guides.length,
+		count: all.length,
 		guides,
-		hint: 'Read one with get_guide({ name }). Start at `ai-router.md`, then `agent-contract.md` — do not read them all.',
+		...(perComponent.length
+			? {
+					perComponentMigration: `${perComponent.length} pages: get_guide({ name: 'migration/components/<kebab-name>' }), e.g. 'migration/components/bb-select'.`,
+				}
+			: {}),
+		hint: 'Read one with get_guide({ name }); a long guide answers with its outline — then pass sections. search_docs finds the section for a question across every guide. Start at `ai-router.md` — do not read them all.',
 	};
 }
 
-/** `get_guide({ name, maxChars })` — read one guide by relative path. */
-function getGuide({ name, maxChars } = {}) {
-	const rel = String(name ?? '').replace(/^\/+/, '');
-	// Contain reads to the guides dir — no traversal out of the knowledge base.
-	if (!rel || rel.includes('..')) {
+/** Guides this size or larger answer with an outline unless asked for more. */
+// The router (13 KB, the documented entry point) still comes whole.
+const GUIDE_OUTLINE_OVER = 8000; // was 16 000: ai-router.md (16K, "a tiny map") came back whole (MCP panel 2026-09-26)
+
+/**
+ * The shipped guide a pointer means. Pointers come from everywhere — the
+ * changelog (`components/bb-table.md (CSS table)`), contracts
+ * (`guides/passthrough.md`), the repo layout (`ai/guides/…`) — and every form
+ * used to answer "Guide not found" (review D6-11).
+ */
+function resolveGuidePath(name) {
+	const guidesDir = join(AI_ROOT, 'guides');
+	const all = collectGuidePaths(guidesDir);
+	let rel = String(name ?? '')
+		.trim()
+		.replace(/\s*\(.*\)\s*$/, '')
+		.replace(/^\/+/, '')
+		.replace(/^(dist\/)?(ai\/)?(guides\/)?/, '');
+	if (!rel || rel.includes('..')) return null;
+	if (!rel.endsWith('.md')) rel = `${rel}.md`;
+	const tries = [rel, `migration/${rel}`, `migration/components/${rel}`];
+	for (const attempt of tries) if (all.includes(attempt)) return attempt;
+	const base = rel.split('/').pop();
+	const byBase = all.filter((p) => p.split('/').pop() === base);
+	return byBase.length === 1 ? byBase[0] : null;
+}
+
+/** `get_guide({ name, sections?, maxChars? })`. */
+function getGuide({ name, sections, maxChars } = {}) {
+	// The package README, which search_docs indexes (MCP panel 2026-09-26).
+	if (/^readme(\.md)?$/i.test(String(name ?? '').trim())) {
+		const readme = join(PACKAGE_ROOT, 'README.md');
+		if (existsSync(readme)) {
+			const markdown = readFileSync(readme, 'utf-8');
+			const all = splitSections(markdown);
+			if (sections?.length) {
+				const { picked, missing } = pickSections(all, sections);
+				return {
+					found: true,
+					name: 'README',
+					...(() => {
+						const { kept, ...rest } = capParts(
+							picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+							'Sections'
+						);
+						return { sections: kept, ...rest };
+					})(),
+					...(missing.length
+						? { notFound: missing, outline: outline(all) }
+						: {}),
+				};
+			}
+			return {
+				found: true,
+				name: 'README',
+				chars: markdown.length,
+				outline: outline(all),
+				hint: "Read what you need: get_guide({ name: 'README', sections: ['<title>'] }).",
+			};
+		}
+	}
+	const resolved = resolveGuidePath(name);
+	if (!resolved) {
+		const all = collectGuidePaths(join(AI_ROOT, 'guides'));
+		const needle = String(name ?? '').toLowerCase();
+		const near = all
+			.filter((p) =>
+				needle
+					.split(/[^a-z0-9]+/)
+					.some((w) => w.length > 3 && p.toLowerCase().includes(w))
+			)
+			.slice(0, 5);
+		// A dead end cost the agent a turn (`get_guide('theming')`): answer with
+		// the sections that match the name as a query.
+		let found = [];
+		try {
+			found = searchSections(docIndex(), String(name ?? ''), 3).results;
+		} catch {
+			/* an unbuilt package has no index: the plain miss still answers */
+		}
+		const hits = found.map((r) => ({
+			section: `${r.source} › ${r.section}`,
+			read: r.read?.tool
+				? `${r.read.tool}(${JSON.stringify(r.read.args ?? {})})`
+				: r.read,
+		}));
 		return {
 			found: false,
-			error: `Invalid guide name '${name}'.`,
-			hint: 'Call list_guides for the available names.',
+			error: `Guide not found: ${name}`,
+			...(near.length ? { didYouMean: near } : {}),
+			...(hits.length ? { related: hits } : {}),
+			hint: 'Call list_guides for the names, or search_docs to find the section by topic.',
 		};
 	}
-	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
+	const markdown = readFileSync(join(AI_ROOT, 'guides', resolved), 'utf-8');
+	const meta = frontmatter(markdown);
+	const all = splitSections(markdown);
+	const base = {
+		found: true,
+		name: resolved,
+		...(resolved !== name ? { resolvedFrom: name } : {}),
+		...(meta.title ? { title: meta.title } : {}),
+	};
+	if (sections?.length) {
+		const { picked, missing } = pickSections(all, sections);
+		return {
+			...base,
+			...(() => {
+				const { kept, ...rest } = capParts(
+					picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+					'Sections'
+				);
+				return { sections: kept, ...rest };
+			})(),
+			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
+		};
+	}
+	const body = stripFrontmatter(markdown);
+	if (maxChars === undefined && body.length >= GUIDE_OUTLINE_OVER) {
+		const intro = body.split(/^## /m)[0].trim();
+		return {
+			...base,
+			...(meta.summary ? { summary: meta.summary } : {}),
+			chars: body.length,
+			intro: intro.slice(0, 2000),
+			outline: outline(all),
+			hint: `This guide is ${body.length} chars. Read what you need: get_guide({ name: '${resolved}', sections: ['<title from outline>'] }) — a ## section includes its ### children. maxChars: 0 returns the whole guide.`,
+		};
+	}
+	const { content, ...cut } = truncateMarkdown(
+		markdown,
+		maxChars,
+		'Guides are ordered narrative — the cut tail is later sections.'
+	);
+	return { ...base, content, ...cut };
+}
+
+/**
+ * `search_docs({ query, limit? })` — the section that answers a question,
+ * across guides, composables, component guides, component props and recipes.
+ *
+ * WHY (review 2026-09-23). The facts Haiku missed were all shipped — the
+ * `.dark` class, `cssLayers`, `passthroughDeduper`, `ssrViewportWidth`, the
+ * `ai-init` and `changelog` commands, `prefill: false` — but each sat in one
+ * section of a long document, and no tool could say which. Each result is a
+ * snippet plus the exact call that reads the whole section.
+ */
+let cachedDocIndex = null;
+function docIndex() {
+	if (cachedDocIndex) return cachedDocIndex;
+	const entries = [];
+	const addSections = (source, markdown, read) => {
+		for (const section of splitSections(markdown)) {
+			if (section.own.length < 40) continue;
+			entries.push({
+				source,
+				section: section.title,
+				text: section.own,
+				read: read(section.title),
+			});
+		}
+	};
 	const guidesDir = join(AI_ROOT, 'guides');
-	const filePath = join(guidesDir, fileName);
-	if (!filePath.startsWith(guidesDir) || !existsSync(filePath)) {
+	for (const path of collectGuidePaths(guidesDir)) {
+		addSections(
+			`guide ${path}`,
+			readFileSync(join(guidesDir, path), 'utf-8'),
+			(title) => ({
+				tool: 'get_guide',
+				args: { name: path, sections: [title] },
+			})
+		);
+	}
+	const composablesDir = join(AI_ROOT, 'composables');
+	if (existsSync(composablesDir)) {
+		for (const file of readdirSync(composablesDir).filter((f) =>
+			f.endsWith('.md')
+		)) {
+			const markdown = readFileSync(join(composablesDir, file), 'utf-8');
+			const name = file.slice(0, -3);
+			entries.push({
+				source: `composable ${name}`,
+				section: frontmatter(markdown).summary ?? name,
+				text: stripFrontmatter(markdown).slice(0, 4000),
+				read: { tool: 'get_composable', args: { name } },
+			});
+		}
+	}
+	const manifest = loadComponentsManifest();
+	for (const component of manifest.components.filter((c) => !c.referenceOnly)) {
+		const path = join(PACKAGE_ROOT, 'dist', component.contract ?? '');
+		if (component.contract && existsSync(path)) {
+			for (const section of contractGuideSections(
+				readFileSync(path, 'utf-8')
+			)) {
+				if (section.own.length < 40) continue;
+				entries.push({
+					source: `component ${component.name}`,
+					section: section.title,
+					text: section.own,
+					read: {
+						tool: 'get_component',
+						args: { name: component.name, sections: [section.title] },
+					},
+				});
+			}
+		}
+		for (const prop of component.props) {
+			if (prop.name.startsWith('pt')) continue;
+			entries.push({
+				source: `component ${component.name}`,
+				section: `prop ${prop.name}`,
+				text: `${prop.name}: ${prop.type}${prop.default ? ` = ${prop.default}` : ''}. ${prop.description ?? ''}`,
+				// The one row, not the component (~0.5K instead of up to 39K).
+				read: {
+					tool: 'get_component',
+					args: { name: component.name, members: [prop.name] },
+				},
+			});
+		}
+		for (const event of component.events ?? []) {
+			entries.push({
+				source: `component ${component.name}`,
+				section: `event ${event.name}`,
+				text: `@${event.name} ${event.signature}. ${event.description ?? ''}`,
+				read: {
+					tool: 'get_component',
+					args: { name: component.name, members: [event.name] },
+				},
+			});
+		}
+		/*
+		 * The rename registry: an agent upgrading an app searches the OLD name
+		 * (`enabled-while-loading`, `pt:input`, `#no-data`), which no current
+		 * section spells. One entry per row, with the name written every way a
+		 * query may (camel, kebab, split words), read = its migration guide.
+		 */
+		for (const row of component.removed ?? []) {
+			const spell = (name) => (row.surface === 'slot' ? `#${name}` : name);
+			const ways = (name) =>
+				[
+					...new Set([
+						name,
+						name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`),
+						name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase(),
+					]),
+				].join(' / ');
+			const kind = row.surface ?? 'prop';
+			const guide = row.migration?.replace(/^ai\/guides\//, '');
+			entries.push({
+				source: `component ${component.name}`,
+				section: `${row.new ? 'renamed' : 'removed'} ${kind} ${spell(row.name)}`,
+				text:
+					`${kind} ${ways(spell(row.name))} ` +
+					(row.new
+						? `was renamed to ${ways(spell(row.new))} on ${component.name}`
+						: `was removed from ${component.name}`) +
+					`${row.since && !/unreleased/.test(row.since) ? ` in ${row.since}` : ''}.` +
+					Object.entries(row.fix?.valueMap ?? {})
+						.filter(([from, to]) => from !== to)
+						.map(([from, to]) => ` The value "${from}" becomes "${to}".`)
+						.join('') +
+					`${row.hint ? ` ${row.hint}.` : ''} \`bitboss-ui check --fix\` rewrites a rename.`,
+				read: guide
+					? { tool: 'get_guide', args: { name: guide } }
+					: { tool: 'get_component', args: { name: component.name } },
+			});
+		}
+	}
+	for (const platform of RECIPE_PLATFORMS) {
+		const dir = join(AI_ROOT, 'recipes', platform);
+		if (!existsSync(dir)) continue;
+		for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+			const name = file.slice(0, -3);
+			const markdown = readFileSync(join(dir, file), 'utf-8');
+			entries.push({
+				source: `recipe ${platform}/${name}`,
+				section: frontmatter(markdown).title ?? name,
+				text: frontmatter(markdown).summary ?? name,
+				read: { tool: 'get_recipe', args: { platform, name } },
+			});
+		}
+	}
+	// Class renames (the sweep map rows of changelog.json): an app's
+	// stylesheet names the OLD class, so the old class must find the new one.
+	if (existsSync(CHANGELOG_PATH)) {
+		const changelog = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+		for (const row of changelog.breaking ?? []) {
+			if (row.surface !== 'class' || !String(row.id).startsWith('css:'))
+				continue;
+			entries.push({
+				source: `class ${row.components?.[0] ?? ''}`.trim(),
+				section: `renamed class ${row.from}`,
+				text:
+					`class ${row.from} was renamed to ${row.to}` +
+					`${row.firstReleasedIn ? ` in ${row.firstReleasedIn}` : ''}` +
+					(row.from.includes('--')
+						? '.'
+						: `; its modifiers follow (${row.from}--x → ${row.to}--x).`) +
+					`${row.note ? ` ${row.note}.` : ''}`,
+				read: {
+					tool: 'get_guide',
+					args: { name: 'migration/v3-beta-css-classes.md' },
+				},
+			});
+		}
+		/*
+		 * Every other break, with the release that first shipped it. "In which
+		 * version did the activator scope lose `isOpen`?" had no search path: the
+		 * answer (f202, firstReleasedIn 3.0.0-beta.35) lived only in
+		 * list_changes, which 1 answerer in 12 called (ai-docs access push,
+		 * 2026-09-24). Prop / pt / slot renames are already indexed from the
+		 * components' registry rows above, so only the rest comes in here.
+		 */
+		const releases = changelog.releases ?? [];
+		for (const row of changelog.breaking ?? []) {
+			if (row.surface === 'class') continue;
+			if (row.kind === 'rename' && ['prop', 'pt', 'slot'].includes(row.surface))
+				continue;
+			const what =
+				row.kind === 'rename'
+					? `${row.surface ?? ''} ${row.from} → ${row.to ?? '(removed)'}`.trim()
+					: String(row.description ?? '');
+			if (!what) continue;
+			const at = row.firstReleasedIn;
+			const before = at
+				? releases.filter((r) => compareVersions(r, at) < 0).at(-1)
+				: releases.at(-1);
+			entries.push({
+				source: `change ${row.id}`,
+				section: `breaking change: ${what.length > 90 ? `${what.slice(0, 90)}…` : what}`,
+				text:
+					`${what}${row.note ? ` (${row.note})` : ''}. ` +
+					(at
+						? `First released in ${at}.`
+						: 'Not released yet: it ships in the next release.') +
+					`${row.guide ? ` Migration: ${row.guide}.` : ''}`,
+				read: {
+					tool: 'list_changes',
+					args: before ? { since: before, ...(at ? { until: at } : {}) } : {},
+				},
+			});
+		}
+	}
+	/*
+	 * The public types an app builds values with (`api` tier: BbTreeItem,
+	 * BbTableColumn, ButtonVariantType). "What shape must each BbTree item
+	 * have?" matched only the prop row `items: BbTreeItem<Meta>[]`, never the
+	 * type's fields, so 2 of 3 answerers guessed `{ label, children }`.
+	 */
+	for (const type of manifest.types ?? []) {
+		if (type.usage !== 'api' || type.deprecated) continue;
+		const use = (type.usedBy ?? [])
+			.map((u) => `${u.component} ${u.name} ${u.surface}`)
+			.join(', ');
+		entries.push({
+			source: `type ${type.name}`,
+			section: `type ${type.name}${use ? ` (${use})` : ''}`,
+			// The words questions use ("shape", "fields", "values") are spelled
+			// out: the declaration alone never says them.
+			text:
+				`${type.name}${use ? `, the type of ${use}` : ''}: ` +
+				(type.values
+					? `accepted values ${type.values.join(' | ')}`
+					: type.fields
+						? `object shape, fields ${type.fields.join('; ')}`
+						: String(type.definition ?? '')) +
+				`. import type { ${type.name} } from 'bitboss-ui'.`,
+			read: { tool: 'get_component', args: { name: type.name } },
+		});
+	}
+	const readme = join(PACKAGE_ROOT, 'README.md');
+	if (existsSync(readme)) {
+		// Served by get_guide under the name 'README' (it used to point at a
+		// "read file" call, which is not a tool).
+		addSections('README', readFileSync(readme, 'utf-8'), (title) => ({
+			tool: 'get_guide',
+			args: { name: 'README', sections: [title] },
+		}));
+	}
+	cachedDocIndex = entries;
+	return entries;
+}
+
+function searchDocs({ query, limit } = {}) {
+	const max = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 20) : 8;
+	const { total, results } = searchSections(docIndex(), query, max);
+	// `read` as the call itself, one string: the object form cost ~100 chars a
+	// result and agents copy the call anyway.
+	const call = (read) =>
+		read?.tool ? `${read.tool}(${JSON.stringify(read.args ?? {})})` : read;
+	return {
+		query: query ?? '',
+		count: results.length,
+		...(total > results.length ? { totalMatches: total } : {}),
+		results: results.map((r) => ({ ...r, read: call(r.read) })),
+		hint: results.length
+			? 'Each result is one section; `read` is the call that returns it whole. Prefer the top results: they match the most query words.'
+			: 'Nothing matched. Use fewer, more specific words (a prop, option or component name), or search_components for components.',
+	};
+}
+
+/** `get_composable({ name })` — one composable's doc (useToast, useConfirm…). */
+function getComposable({ name, sections, maxChars } = {}) {
+	const dir = join(AI_ROOT, 'composables');
+	const files = existsSync(dir)
+		? readdirSync(dir).filter((f) => f.endsWith('.md'))
+		: [];
+	const wanted = String(name ?? '').replace(/\.md$/, '');
+	const file = files.find(
+		(f) => f.slice(0, -3).toLowerCase() === wanted.toLowerCase()
+	);
+	if (!file) {
 		return {
 			found: false,
-			error: `Guide not found: ${fileName}`,
-			hint: 'Call list_guides for the available names.',
+			error: `Composable not found: ${name}`,
+			available: files.map((f) => f.slice(0, -3)),
 		};
 	}
-	const { content, ...meta } = truncateMarkdown(
-		readFileSync(filePath, 'utf-8'),
+	const markdown = readFileSync(join(dir, file), 'utf-8');
+	/*
+	 * A composable that needs a host component says so FIRST, as a field: with
+	 * no `<BbConfirm />`, `await confirm()` never settles. Every blind answerer
+	 * of "await an Are-you-sure dialog" (4 of 4, 2026-09-24) left the host out,
+	 * although the doc's second paragraph states it.
+	 */
+	const host = frontmatter(markdown).summary?.match(
+		/Requires (exactly one <Bb\w+ \/> host[^.]*)\./
+	)?.[1];
+	const base = {
+		found: true,
+		name: file.slice(0, -3),
+		...(host ? { requires: host } : {}),
+	};
+	const body = stripFrontmatter(markdown);
+	const all = splitSections(markdown);
+	if (sections?.length) {
+		const { picked, missing } = pickSections(all, sections);
+		return {
+			...base,
+			...(() => {
+				const { kept, ...rest } = capParts(
+					picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+					'Sections'
+				);
+				return { sections: kept, ...rest };
+			})(),
+			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
+		};
+	}
+	// Same rule as get_guide (MCP panel 2026-09-26): past 8K, the intro and the
+	// outline; useConfirm's doc was 18K in one answer.
+	if (maxChars === undefined && body.length >= GUIDE_OUTLINE_OVER) {
+		return {
+			...base,
+			chars: body.length,
+			intro: body.split(/^## /m)[0].trim().slice(0, 3000),
+			outline: outline(all),
+			hint: `Read what you need: get_composable({ name: '${base.name}', sections: ['<title from outline>'] }); maxChars: 0 returns it whole.`,
+		};
+	}
+	const { content, ...cut } = truncateMarkdown(
+		markdown,
 		maxChars,
-		`Guides are ordered narrative — the cut tail is later sections.`
+		'The cut tail is later sections.'
 	);
-	return { found: true, name: fileName, content, ...meta };
+	return { ...base, content: stripFrontmatter(content), ...cut };
 }
 
 function listRecipes({ platform } = {}) {
@@ -398,21 +2116,40 @@ function listRecipes({ platform } = {}) {
 			error: `Unknown platform(s): ${invalid.join(', ')} — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
 		};
 	}
-	const recipes = [];
+	/*
+	 * One row per recipe with its platforms, title, summary and size (review
+	 * D6-13): records-workspace / inline-edit-workspace / approvals-inbox could
+	 * not be told apart by name, and each costs 11–61 KB to open.
+	 */
+	const byName = new Map();
 	for (const p of platforms) {
 		const dir = join(AI_ROOT, 'recipes', p);
 		if (!existsSync(dir)) continue;
 		for (const file of readdirSync(dir)) {
-			if (file.endsWith('.md')) {
-				recipes.push({ platform: p, name: file.slice(0, -3) });
-			}
+			if (!file.endsWith('.md')) continue;
+			const name = file.slice(0, -3);
+			const markdown = readFileSync(join(dir, file), 'utf-8');
+			const meta = frontmatter(markdown);
+			const row = byName.get(name) ?? {
+				name,
+				...(meta.title ? { title: meta.title } : {}),
+				...(meta.summary ? { summary: meta.summary } : {}),
+				platforms: [],
+				chars: {},
+			};
+			row.platforms.push(p);
+			row.chars[p] = markdown.length;
+			byName.set(name, row);
 		}
 	}
-	return { recipes };
+	return {
+		recipes: [...byName.values()],
+		hint: 'get_recipe({ platform, name }) returns the whole recipe (they are copied whole); pass sections to read only part of a long one.',
+	};
 }
 
 /** `get_recipe({ platform, name })` — read one recipe's markdown content. */
-function getRecipe({ platform, name, maxChars } = {}) {
+function getRecipe({ platform, name, sections, files, maxChars } = {}) {
 	if (!RECIPE_PLATFORMS.includes(platform)) {
 		return {
 			found: false,
@@ -442,9 +2179,113 @@ function getRecipe({ platform, name, maxChars } = {}) {
 			hint: 'Call list_recipes for the available names.',
 		};
 	}
+	const markdown = readFileSync(filePath, 'utf-8');
+	if (sections?.length) {
+		const all = splitSections(markdown);
+		const { picked, missing } = pickSections(all, sections);
+		return {
+			found: true,
+			platform,
+			name: fileName.slice(0, -3),
+			...(() => {
+				const { kept, ...rest } = capParts(
+					picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+					'Sections'
+				);
+				return { sections: kept, ...rest };
+			})(),
+			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
+		};
+	}
+	/*
+	 * OUTLINE FIRST (MCP panel 2026-09-26, owner ruling M3). Whole recipes were
+	 * median ~59K chars, max 129K (~32K tokens): past Claude Code's 25K cut, so
+	 * "whole by default" did not reach agents whole anyway. The default is the
+	 * prose that explains the page (every section outside "The code"), the code
+	 * files with their sizes, and the shipped file's path — an agent that can
+	 * read files copies it from there; one that can't asks for `files`.
+	 * `maxChars: 0` still returns the markdown whole.
+	 */
+	const all = splitSections(markdown);
+	const code = all.find(
+		(sec) => sec.level === 2 && /^the (code|files)\b/i.test(sec.title)
+	);
+	const codeFiles = code
+		? all.filter(
+				(sec) => sec.level === 3 && code.text.includes(sec.text) && sec !== code
+			)
+		: [];
+	if (files?.length) {
+		// An exact title first, else a substring: `RejectDialog.vue` must not
+		// also return BulkRejectDialog.vue.
+		const hits = [];
+		for (const f of files) {
+			const w = String(f).toLowerCase();
+			const exact = codeFiles.filter((sec) => sec.title.toLowerCase() === w);
+			for (const sec of exact.length
+				? exact
+				: codeFiles.filter((sec) => sec.title.toLowerCase().includes(w)))
+				if (!hits.includes(sec)) hits.push(sec);
+		}
+		const missingFiles = files.filter(
+			(f) =>
+				!codeFiles.some((sec) =>
+					sec.title.toLowerCase().includes(String(f).toLowerCase())
+				)
+		);
+		return {
+			found: true,
+			platform,
+			name: fileName.slice(0, -3),
+			...(() => {
+				const { kept, ...rest } = capParts(
+					hits.map((sec) => ({ title: sec.title, text: sec.text })),
+					'Files'
+				);
+				return { files: kept, ...rest };
+			})(),
+			...(missingFiles.length
+				? {
+						notFound: missingFiles,
+						available: codeFiles.map((sec) => sec.title),
+					}
+				: {}),
+		};
+	}
+	if (maxChars == null && code) {
+		const prose = all.filter((sec) => sec.level === 2 && sec !== code);
+		const meta = frontmatter(markdown);
+		// The words between the title and the first ## (the adversarial review:
+		// "read the XSRF-TOKEN cookie … or every upload 419s" lived there), and
+		// the lead-in of the code section before its first file.
+		const body = stripFrontmatter(markdown);
+		const intro = body
+			.split(/^## /m)[0]
+			.replace(/^# .*$/m, '')
+			.trim();
+		const codeIntro = code.own.replace(/^## .*$/m, '').trim();
+		return {
+			found: true,
+			platform,
+			name: fileName.slice(0, -3),
+			...(meta.title ? { title: meta.title } : {}),
+			path: filePath,
+			chars: markdown.length,
+			...(intro ? { intro } : {}),
+			prose: prose.map((sec) => ({ title: sec.title, text: sec.text })),
+			...(codeIntro ? { codeIntro } : {}),
+			files: codeFiles.map((sec) => ({
+				title: sec.title,
+				chars: sec.text.length,
+			})),
+			hint: `Copy the page whole: read the file at \`path\`, or fetch the code with files: ['<title>'] (a few per call). maxChars: 0 returns the whole markdown in one answer.`,
+		};
+	}
+	// Whole on request (review D6-14): the old 40 000-char default cut 7 of 9
+	// vue recipes inside their page code.
 	const { content, ...meta } = truncateMarkdown(
-		readFileSync(filePath, 'utf-8'),
-		maxChars,
+		markdown,
+		maxChars ?? 0,
 		`Recipes are ordered narrative — the cut tail is later sections.`
 	);
 	return {
@@ -459,8 +2300,17 @@ function getRecipe({ platform, name, maxChars } = {}) {
 /** `validate({ code })` — Phase 2 validator core over a Vue snippet. */
 function validateCode({ code } = {}) {
 	const manifest = getManifestMap();
-	const { findings } = validateVueSnippet(String(code ?? ''), manifest);
-	return { ok: findings.length === 0, findings };
+	const { findings: all } = validateVueSnippet(String(code ?? ''), manifest);
+	// `severity: 'warning'` findings (a slot spelled the pre-reset way, Q53.15
+	// C9b) are reported apart and never make the snippet invalid — the same
+	// split `bitboss-ui check` prints.
+	const findings = all.filter((f) => f.severity !== 'warning');
+	const warnings = all.filter((f) => f.severity === 'warning');
+	return {
+		ok: findings.length === 0,
+		findings,
+		...(warnings.length ? { warnings } : {}),
+	};
 }
 
 /**
@@ -469,13 +2319,393 @@ function validateCode({ code } = {}) {
  * becomes an `isError` result carrying `Error: <message>` — preserving the
  * exact result shape of the previous hand-rolled dispatch.
  */
+const CHANGELOG_PATH = join(AI_ROOT, 'changelog.json');
+
+/**
+ * Order two versions on this library's line: `3.0.0-beta.21` after
+ * `3.0.0-beta.9` (numeric, not lexical — the bug every hand-rolled compare
+ * has), and any prerelease before its own stable release.
+ */
+function compareVersions(a, b) {
+	const parse = (v) => {
+		const [core, pre = ''] = String(v).split('-');
+		const nums = core.split('.').map((n) => Number.parseInt(n, 10) || 0);
+		const [tag = '', n = ''] = pre.split('.');
+		return { nums, tag, n: Number.parseInt(n, 10) || 0 };
+	};
+	const x = parse(a);
+	const y = parse(b);
+	for (let i = 0; i < 3; i += 1) {
+		if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0))
+			return (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+	}
+	// No prerelease tag outranks any prerelease of the same core version.
+	if (!x.tag && y.tag) return 1;
+	if (x.tag && !y.tag) return -1;
+	if (x.tag !== y.tag) return x.tag < y.tag ? -1 : 1; // alpha < beta < rc
+	return x.n - y.n;
+}
+
+/**
+ * `list_changes({ since, until })` — the breaking changes between two releases.
+ *
+ * WHY THIS TOOL EXISTS. A consumer agent on 2026-09-09 asked "what changed
+ * between beta.20 and beta.21?", found nothing in the knowledge base that could
+ * answer it, and diffed the two published tarballs by hand. The data existed
+ * (`dist/ai/changelog.json`) but no tool served it, and its rows carried no
+ * release, so even reading the file could not have answered the question. Both
+ * halves are fixed: rows are stamped with `firstReleasedIn` at build time, and
+ * this serves the slice.
+ */
+/*
+ * The answer's rows, compact (owner rule: compact by default): empty fields,
+ * `ruling` and `since` dropped, and the class renames (85 one-to-one pairs from the sweep map,
+ * Q51.19) folded into ONE `{ ".old": ".new" }` map — complete, and a tenth of
+ * the size of 85 row objects. Everything else stays a full row.
+ */
+function compactChanges(rows) {
+	const classRenames = {};
+	const breaking = [];
+	for (const row of rows) {
+		if (row.surface === 'class' && String(row.id).startsWith('css:')) {
+			classRenames[row.from] = row.to;
+			continue;
+		}
+		// `ruling` is the library's internal decision id and `since` the
+		// register's authoring-date note (firstReleasedIn is the release): both
+		// stay in changelog.json, neither helps an upgrade.
+		breaking.push(
+			Object.fromEntries(
+				Object.entries(row).filter(
+					([key, value]) =>
+						key !== 'ruling' &&
+						key !== 'since' &&
+						value !== '' &&
+						value !== undefined &&
+						!(Array.isArray(value) && value.length === 0)
+				)
+			)
+		);
+	}
+	return Object.keys(classRenames).length
+		? {
+				breaking,
+				classRenames,
+				classRenamesNote:
+					'class renames from the beta.36 sweep map: modifiers follow (.old--x → .new--x); ai/guides/migration/v3-beta-css-classes.md',
+			}
+		: { breaking };
+}
+
+/*
+ * Rows carry `kind` AND `surface`; 2 of 3 answerers told a script to switch on
+ * `kind` to tell a class rename from a prop rename (2026-09-24).
+ */
+const ROW_FIELDS =
+	'`surface` says what a rename names (prop | slot | pt | cssVar | class | option); `kind` is only rename vs behaviour; `firstReleasedIn` is the first npm release with the change.';
+
+/*
+ * STAGED ANSWERS (MCP panel 2026-09-26). The whole v2 → v3 list was 93K chars
+ * (~23K tokens, over Claude Code's 25K cap with the envelope) and one upgrade
+ * hop 20–33K, 59% of it behaviour prose. Now: no range → counts per release;
+ * a range or filter → ONE LINE per change, grouped by release, behaviour rows
+ * as their hand-written `summary`; `detail: 'rows'` → the full rows as before.
+ */
+const CHANGES_PAGE = 60;
+
+function changeLine(row, focus) {
+	// 16 form controls in full is ~250 chars of the line; the component filter
+	// and `detail: 'rows'` name them all.
+	const list = row.components ?? [];
+	// The component asked about always shows, never hidden in "+N more".
+	const shown =
+		focus && list.includes(focus)
+			? [focus, ...list.filter((c) => c !== focus)]
+			: list;
+	const who =
+		shown.length > 3
+			? `${shown.slice(0, 2).join(' / ')} +${shown.length - 2} more`
+			: shown.join(' / ');
+	if (row.kind === 'rename') {
+		const to = row.to == null ? 'removed' : row.to;
+		return `${row.id} ${who ? `${who} ` : ''}${row.surface ?? 'prop'} ${row.from} → ${to}${row.note ? ` — ${firstSentence(row.note, 140)}` : ''}`;
+	}
+	return `${row.id} ${row.summary ?? firstSentence(row.description, 160)}`;
+}
+
+function changeLines(rows, cursor, withClassMap = false, focus) {
+	const lines = [];
+	const classRenames = {};
+	for (const row of rows) {
+		if (row.surface === 'class' && String(row.id).startsWith('css:')) {
+			classRenames[row.from] = row.to;
+			continue;
+		}
+		lines.push([row.firstReleasedIn ?? 'unreleased', changeLine(row, focus)]);
+	}
+	// Release order, unreleased last, so pages read oldest → newest.
+	lines.sort(([a], [b]) =>
+		a === b
+			? 0
+			: a === 'unreleased'
+				? 1
+				: b === 'unreleased'
+					? -1
+					: compareVersions(a, b)
+	);
+	const start = Math.max(0, Number(cursor ?? 0) || 0);
+	const page = lines.slice(start, start + CHANGES_PAGE);
+	const byRelease = {};
+	for (const [release, line] of page) (byRelease[release] ??= []).push(line);
+	return {
+		changes: byRelease,
+		...(start + CHANGES_PAGE < lines.length
+			? {
+					nextCursor: String(start + CHANGES_PAGE),
+					remaining: lines.length - start - CHANGES_PAGE,
+				}
+			: {}),
+		...(Object.keys(classRenames).length && start === 0 && !withClassMap
+			? {
+					classRenames: `${Object.keys(classRenames).length} .bb-* class renames (the beta.36 sweep): the map with surface: 'class'`,
+				}
+			: {}),
+		...(Object.keys(classRenames).length && start === 0 && withClassMap
+			? {
+					classRenames,
+					classRenamesNote:
+						'class renames from the beta.36 sweep map: modifiers follow (.old--x → .new--x); ai/guides/migration/v3-beta-css-classes.md',
+				}
+			: {}),
+	};
+}
+
+function listChanges({
+	since: rawSince,
+	until: rawUntil,
+	component,
+	surface,
+	kind,
+	detail,
+	cursor,
+} = {}) {
+	// The repo's own tags are spelled `v3.0.0-beta.33` (review D6-12). A v2
+	// version means "the whole v2 → v3 upgrade": every row, one line each.
+	const fromV2 = rawSince != null && /^v?2(\.|$)/.test(String(rawSince));
+	const since =
+		rawSince == null || fromV2 ? undefined : String(rawSince).replace(/^v/, '');
+	const until =
+		rawUntil == null ? rawUntil : String(rawUntil).replace(/^v/, '');
+	if (!existsSync(CHANGELOG_PATH)) {
+		return {
+			error: `changelog.json not found at ${CHANGELOG_PATH} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`,
+		};
+	}
+	const doc = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+	const releases = doc.releases ?? [];
+	const known = new Set(releases);
+
+	// A typo'd version must not silently return "nothing changed" — that reads
+	// as a clean upgrade and is the worst possible wrong answer here.
+	for (const [label, value] of [
+		['since', since],
+		['until', until],
+	]) {
+		if (value != null && !known.has(String(value))) {
+			if ((doc.unpublished ?? []).includes(String(value))) {
+				const next = releases.find(
+					(r) => compareVersions(r, String(value)) > 0
+				);
+				return {
+					error: `${value} was never published to npm; its changes shipped in ${next ?? 'the next release'}.`,
+					knownReleases: releases,
+					hint: `Pass the version you installed from npm (for example the one before it, since=${releases.filter((r) => compareVersions(r, String(value)) < 0).at(-1) ?? '…'}).`,
+				};
+			}
+			return {
+				error: `Unknown ${label} version '${value}'.`,
+				knownReleases: releases,
+				hint: 'Pass a version exactly as listed in knownReleases; coming from v2, pass since: "2" for every break of the v2 → v3 upgrade.',
+			};
+		}
+	}
+
+	if (
+		since != null &&
+		until != null &&
+		compareVersions(String(since), String(until)) >= 0
+	) {
+		return {
+			error: `since (${since}) must be older than until (${until}).`,
+			knownReleases: releases,
+		};
+	}
+	// Resolve the component the way get_component does ('bb-select',
+	// 'Select'), and say so when it is no component at all — an empty list
+	// would read as "nothing breaks".
+	if (component) {
+		const resolved = resolveComponent(loadComponentsManifest(), component);
+		// A retired name (BbTabsPanes) is still a key in the rows it renamed.
+		const retiredName =
+			!resolved?.entry && loadRetired().has(String(component).trim());
+		if (!resolved?.entry && !retiredName) {
+			return {
+				error: `Unknown component '${component}'.`,
+				didYouMean: nearestComponents(loadComponentsManifest(), component),
+			};
+		}
+		if (resolved?.entry) component = resolved.entry.name;
+	}
+	const rows = detail === 'rows';
+	const filtered = (doc.breaking ?? []).filter(
+		(row) =>
+			(!component ||
+				(row.components ?? []).some(
+					(c) => c.toLowerCase() === String(component).toLowerCase()
+				)) &&
+			(!surface ||
+				(row.surface ?? (row.kind === 'rename' ? 'prop' : null)) === surface) &&
+			(!kind || row.kind === kind)
+	);
+	const all = filtered;
+	const filteredBy = {
+		...(component ? { component } : {}),
+		...(surface ? { surface } : {}),
+		...(kind ? { kind } : {}),
+	};
+
+	// No range and no filter: counts per release — the map, not the territory.
+	if (
+		since == null &&
+		until == null &&
+		!rows &&
+		!fromV2 &&
+		!Object.keys(filteredBy).length
+	) {
+		const perRelease = {};
+		for (const row of all) {
+			const at = row.firstReleasedIn ?? 'unreleased';
+			const bucket = (perRelease[at] ??= {
+				renames: 0,
+				behaviour: 0,
+				classRenames: 0,
+			});
+			if (row.surface === 'class' && String(row.id).startsWith('css:'))
+				bucket.classRenames++;
+			else if (row.kind === 'rename') bucket.renames++;
+			else bucket.behaviour++;
+		}
+		return {
+			version: doc.version,
+			upgrade: doc.upgrade,
+			guide: doc.guide,
+			count: all.length,
+			releases,
+			perRelease: Object.fromEntries(
+				Object.entries(perRelease).sort(([a], [b]) =>
+					a === 'unreleased'
+						? 1
+						: b === 'unreleased'
+							? -1
+							: compareVersions(a, b)
+				)
+			),
+			hint: 'Counts only. What breaks when you bump: list_changes({ since: "<the version you have>" }) — one line per change; coming from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
+		};
+	}
+
+	// A filter with no range, or `since` a v2 version: one line per change
+	// (the v2 → v3 upgrade, or that slice of it).
+	if (since == null && until == null && !rows) {
+		return {
+			version: doc.version,
+			filteredBy,
+			count: all.length,
+			...changeLines(all, cursor, surface === 'class', component),
+			guide: doc.guide,
+			...(component
+				? {
+						libraryWide: (doc.breaking ?? []).filter((row) => row.libraryWide)
+							.length,
+					}
+				: {}),
+			hint: `One line per change (id, components, old → new, or the break in one sentence).${component ? ' `libraryWide` more changes touch every app (CLI, plugin, machine-readable files): list_changes({ kind: "behaviour" }).' : ''} Whole rows: detail: "rows" with the same filter. Next page: cursor: nextCursor.`,
+		};
+	}
+
+	// No range asked for: the whole v2 → v3 set, which is what the file has
+	// always meant.
+	if (since == null && until == null) {
+		return {
+			version: doc.version,
+			upgrade: doc.upgrade,
+			guide: doc.guide,
+			releases,
+			summary: doc.summary,
+			count: all.length,
+			...compactChanges(all),
+			hint: `Narrow to one upgrade hop with list_changes({ since: "<your current version>" }) — that answers "what breaks if I bump". ${ROW_FIELDS}`,
+		};
+	}
+
+	const inRange = all.filter((entry) => {
+		const at = entry.firstReleasedIn;
+		// Unreleased rows belong to the future: they ship in whatever comes
+		// next, so they count only when the caller left `until` open.
+		if (at == null) return until == null;
+		if (since != null && compareVersions(at, String(since)) <= 0) return false;
+		if (until != null && compareVersions(at, String(until)) > 0) return false;
+		return true;
+	});
+
+	if (!rows) {
+		return {
+			version: doc.version,
+			since: since ?? null,
+			until: until ?? doc.version,
+			...(Object.keys(filteredBy).length ? { filteredBy } : {}),
+			count: inRange.length,
+			...changeLines(inRange, cursor, surface === 'class', component),
+			guide: doc.guide,
+			hint:
+				inRange.length === 0
+					? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
+					: 'One line per change, grouped by the release that shipped it (id, components, old → new, or the break in one sentence). Whole rows: detail: "rows". The `guide` page explains each. Next page: cursor: nextCursor.',
+		};
+	}
+
+	return {
+		version: doc.version,
+		since: since ?? null,
+		until: until ?? doc.version,
+		count: inRange.length,
+		...compactChanges(inRange),
+		guide: doc.guide,
+		hint:
+			inRange.length === 0
+				? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
+				: `Each entry names the component and the new spelling; \`guide\` is the migration page with the full explanation. ${ROW_FIELDS}`,
+	};
+}
+
 function toolCallback(fn) {
 	return (args) => {
 		try {
 			const result = fn(args ?? {});
 			return {
-				content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-				isError: false,
+				// Compact JSON: indentation was a quarter of every answer (review D6).
+				content: [{ type: 'text', text: JSON.stringify(result) }],
+				// A miss is an error the model should act on (MCP spec: tool
+				// execution errors go in the result with isError). Every miss
+				// still carries its next step: didYouMean, related, hint.
+				// A redirect (a retired v2 name, a picker verdict like BbDrawer →
+				// BbOffCanvas) is an ANSWER, not an error: some clients collapse or
+				// raise on isError (adversarial review 2026-09-26).
+				isError:
+					(result?.found === false &&
+						!result?.retired &&
+						!result?.notInLibrary?.length) ||
+					typeof result?.error === 'string',
 			};
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -489,18 +2719,55 @@ function toolCallback(fn) {
 
 const platformSchema = z.enum(RECIPE_PLATFORMS);
 
+/**
+ * Sent once at initialize (review D6-1): an MCP-only agent otherwise had no
+ * way to know which tool answers which question, and read whole guides.
+ */
+const SERVER_INSTRUCTIONS = [
+	'bitboss-ui: a Vue 3 component library. Answer from these tools, never from memory — agents that guess invent props.',
+	"- Tailwind v4 app: set cssLayers: TAILWIND_V4_LAYERS ('bitboss-ui/vite') at setup, or utilities lose.",
+	'- A topic or "how do I…" question (dark mode, cascade layers, SSR, a plugin option, a CLI command): search_docs, then open the section it points to.',
+	'- Which component: search_components (empty query = the whole catalog). One component: get_component({ name }), one line per member; members: [names] for whole rows, sections for prose.',
+	'- A type in a props table (BbTableColumn, ButtonVariantType): get_component({ name }) returns its definition and values.',
+	'- After writing markup: validate. Before custom CSS: list_tokens.',
+	'- An old name (v2 or earlier-beta prop, slot, pt key, class) that stopped working: search_docs(the old name). What a bump breaks: list_changes({ since: <your version> }), one line per change.',
+	"- pt in <script> (a const, a wrapper's prop): type it <Name>Props['pt']; Pt* types are not exported.",
+	'- Composables: get_composable. Whole pages: list_recipes, get_recipe (prose + files). Long docs answer with an outline: pass sections.',
+].join('\n');
+
 /** Register the knowledge-base tools on a fresh McpServer instance. */
 function buildServer() {
 	const server = new McpServer(
 		{ name: 'bitboss-ui', version: packageVersion() },
-		{ capabilities: { tools: {} } }
+		{ capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
 	);
+	// Every tool reads the installed package and nothing else: say so, so a
+	// client can call them without a confirmation (MCP tool annotations).
+	const registerTool = server.registerTool.bind(server);
+	server.registerTool = (name, config, callback) =>
+		registerTool(
+			name,
+			{
+				title: name
+					.split('_')
+					.map((w, i) => (i ? w : w[0].toUpperCase() + w.slice(1)))
+					.join(' '),
+				...config,
+				annotations: {
+					readOnlyHint: true,
+					destructiveHint: false,
+					idempotentHint: true,
+					openWorldHint: false,
+				},
+			},
+			callback
+		);
 
 	server.registerTool(
 		'search_components',
 		{
 			description:
-				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code.',
+				'Find the right Bb* component by name or need ("data table" → BbTable). Also returns `notInLibrary`: verdicts for names agents invent ("BbDrawer" is BbOffCanvas). An empty result does not mean the need is uncovered: read the component-picker guide before hand-rolling anything.',
 			inputSchema: {
 				query: z
 					.string()
@@ -517,7 +2784,7 @@ function buildServer() {
 					.boolean()
 					.optional()
 					.describe(
-						'Include reference-only internal components (BbBase*, Common*). Default false — these are not consumer API and should not be recommended.'
+						'Include reference-only internal components (Common*, listbox internals). Default false — these are not consumer API and should not be recommended. BbBaseButton and the BbBase*Icon glyphs are consumer API and are always included.'
 					),
 			},
 		},
@@ -528,16 +2795,51 @@ function buildServer() {
 		'get_component',
 		{
 			description:
-				'Get the full manifest entry (props/events/slots/models, removed/renamed history) for one bitboss-ui component by exact name, plus the rendered contract markdown content.',
+				"One bitboss-ui component, compact: every prop, event and slot as one line (props: name, type, allowed values, default, first sentence; optional props identical across components folded into `commonProps`), v-models, pt parts and states, the types its API uses, the guide's outline and its Gotchas. Then ask for exactly what you need: `members` for whole rows, `sections` for guide prose, `include` for extra parts (each returns only that), `detail: 'full'` for everything. Also answers for a public TYPE name, a removed or renamed v2/beta name, and near-miss spellings ('bb-button', 'Button').",
 			inputSchema: {
-				name: z.string().describe("Exact component name, e.g. 'BbButton'."),
+				name: z
+					.string()
+					.describe("Component name, e.g. 'BbButton' ('bb-button' works too)."),
+				sections: z
+					.array(z.string())
+					.optional()
+					.describe(
+						"Guide sections to return whole, by title from `guide.sections`, e.g. ['Toggle buttons']. Case-insensitive; a partial title matches."
+					),
+				include: z
+					.array(
+						z.enum([
+							'tree',
+							'cssProps',
+							'css',
+							'ptProps',
+							'history',
+							'contract',
+						])
+					)
+					.optional()
+					.describe(
+						'Extra parts: tree = the component tree, cssProps = CSS variables with descriptions, css = the .bb-* classes it renders (by block; for a selector you must write), ptProps = every pt:* prop row, history = full v2/beta rename records, contract = the whole contract markdown.'
+					),
 				maxChars: z
 					.number()
 					.int()
 					.min(0)
 					.optional()
 					.describe(
-						`Cap on the returned contract markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap). The structured props/events/slots are never truncated.`
+						`With include: ['contract'] only — cap on the contract markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap).`
+					),
+				members: z
+					.array(z.string())
+					.optional()
+					.describe(
+						"Props, events or slots to return whole, by name, e.g. ['columns', 'click:row', '#actions']. Returns only those rows."
+					),
+				detail: z
+					.enum(['summary', 'full'])
+					.optional()
+					.describe(
+						"'summary' (default): one line per member. 'full': the whole manifest entry, every description, the Gotchas and Accessibility sections."
 					),
 			},
 		},
@@ -571,17 +2873,70 @@ function buildServer() {
 		toolCallback(listGuides)
 	);
 
+	server.registerTool(
+		'list_changes',
+		{
+			description:
+				'Breaking changes between bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on>: one line per change, grouped by release. No arguments: counts per release. Narrow with component / surface / kind; detail: "rows" for the full records. Only BREAKING changes are tracked; features and fixes are not.',
+			inputSchema: {
+				since: z
+					.string()
+					.optional()
+					.describe(
+						"Exclusive lower bound — the version you are currently on, e.g. '3.0.0-beta.20'. Its own breaks are excluded; you already have them."
+					),
+				until: z
+					.string()
+					.optional()
+					.describe(
+						'Inclusive upper bound (default: the installed version). Unreleased breaks are included only when this is omitted.'
+					),
+				component: z
+					.string()
+					.optional()
+					.describe("Only this component's breaks, e.g. 'BbSelect'."),
+				surface: z
+					.enum(['prop', 'slot', 'pt', 'cssVar', 'class', 'option', 'method'])
+					.optional()
+					.describe('Only renames of this surface.'),
+				kind: z
+					.enum(['rename', 'behaviour'])
+					.optional()
+					.describe('Only renames, or only behaviour changes.'),
+				detail: z
+					.enum(['lines', 'rows'])
+					.optional()
+					.describe(
+						"'lines' (default): one line per change. 'rows': the full records (description, guide, default, fix)."
+					),
+				cursor: z
+					.string()
+					.optional()
+					.describe(
+						'The `nextCursor` of the previous answer, for the next page.'
+					),
+			},
+		},
+		toolCallback(listChanges)
+	);
+
 	server.registerTool(
 		'get_guide',
 		{
 			description:
-				"Read one bitboss-ui guide by name (as listed by list_guides, e.g. 'ai-router.md' or 'migration/v2-to-v3.md').",
+				"Read one bitboss-ui guide (names from list_guides, e.g. 'design-tokens' or 'migration/v2-to-v3'). A long guide answers with its outline: then pass `sections`. Pointers such as 'ai/guides/passthrough.md' or 'components/bb-table.md' resolve too.",
 			inputSchema: {
 				name: z
 					.string()
 					.describe(
 						"Guide path relative to the guides dir, e.g. 'design-tokens.md'. The '.md' suffix is optional."
 					),
+				sections: z
+					.array(z.string())
+					.optional()
+					.describe(
+						"Section titles from the outline, e.g. ['Dark mode']. A ## section includes its ### children."
+					),
 				maxChars: z
 					.number()
 					.int()
@@ -599,7 +2954,7 @@ function buildServer() {
 		'list_recipes',
 		{
 			description:
-				'List available page-level recipes (whole-page compositions), optionally filtered by platform.',
+				'List the page-level recipes (whole-page compositions) with title, summary, platforms and size, optionally filtered by platform.',
 			inputSchema: {
 				platform: platformSchema
 					.optional()
@@ -613,8 +2968,18 @@ function buildServer() {
 		'get_recipe',
 		{
 			description:
-				'Read the full markdown content of one recipe by platform and name.',
+				'Read one page recipe by platform and name: its prose (anatomy, key ideas, why), the list of code files with sizes, and the path of the shipped markdown to copy from. Fetch code with `files`, other parts with `sections`; `maxChars: 0` returns the whole markdown.',
 			inputSchema: {
+				sections: z
+					.array(z.string())
+					.optional()
+					.describe('Section titles to return instead of the default.'),
+				files: z
+					.array(z.string())
+					.optional()
+					.describe(
+						"Code files to return whole, by title from `files`, e.g. ['Index.vue', 'context.ts']."
+					),
 				platform: platformSchema.describe(
 					'Which platform variant of the recipe to read.'
 				),
@@ -627,18 +2992,62 @@ function buildServer() {
 					.min(0)
 					.optional()
 					.describe(
-						`Cap on the returned markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap).`
+						'Return the markdown itself instead of the outline: 0 = whole, N = cut at N chars.'
 					),
 			},
 		},
 		toolCallback(getRecipe)
 	);
 
+	server.registerTool(
+		'search_docs',
+		{
+			description:
+				'Find the section that answers a question, across every guide, component guide, component prop and event, composable, recipe and the README. Use it for "how do I…" and "is there…" questions (dark mode, cascade layers, SSR, a plugin option, a CLI command, a migration). Each result is a snippet plus the exact call that reads the whole section.',
+			inputSchema: {
+				query: z
+					.string()
+					.describe(
+						"A few specific words, e.g. 'dark mode class' or 'tailwind cascade layers'."
+					),
+				limit: z
+					.number()
+					.int()
+					.positive()
+					.optional()
+					.describe('Max results (default 8, max 20).'),
+			},
+		},
+		toolCallback(searchDocs)
+	);
+
+	server.registerTool(
+		'get_composable',
+		{
+			description:
+				"Read one composable's doc (useToast, useConfirm, useBbTableContext, useMobile…): what it returns, what host it needs, examples. A long doc answers its intro and outline; pass `sections`.",
+			inputSchema: {
+				name: z.string().describe("Composable name, e.g. 'useToast'."),
+				sections: z
+					.array(z.string())
+					.optional()
+					.describe('Section titles to return, from `outline`.'),
+				maxChars: z
+					.number()
+					.int()
+					.min(0)
+					.optional()
+					.describe('Return the doc itself: 0 = whole, N = cut at N chars.'),
+			},
+		},
+		toolCallback(getComposable)
+	);
+
 	server.registerTool(
 		'validate',
 		{
 			description:
-				'Validate a Vue template/SFC snippet against the installed components.json manifest: reports unknown Bb* props, unknown v-models, and removed/renamed props. Run this after writing bitboss-ui markup.',
+				'Validate a Vue template/SFC snippet against the installed components.json manifest: reports unknown Bb* props, unknown v-models, removed/renamed props, and imports that are not public (a file inside bitboss-ui/dist, a Pt* type). Run this after writing bitboss-ui markup.',
 			inputSchema: {
 				code: z
 					.string()
@@ -659,8 +3068,21 @@ export async function main() {
 	const server = buildServer();
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
+	// Settle on stdin's end as well as the transport's close. `onclose` does
+	// not fire when the host simply closes the pipe, so awaiting it alone left
+	// the caller's top-level `await main()` pending at exit and Node printed
+	// "Detected unsettled top-level await" on every clean shutdown (2026-09-09).
+	// `once` on both, and idempotent resolve, so whichever arrives first wins.
 	return new Promise((resolve) => {
-		transport.onclose = () => resolve();
+		let done = false;
+		const settle = () => {
+			if (done) return;
+			done = true;
+			resolve();
+		};
+		transport.onclose = settle;
+		process.stdin.once('end', settle);
+		process.stdin.once('close', settle);
 	});
 }
 
@@ -675,7 +3097,11 @@ export const start = main;
  * concurrently. Importing this module does not start a server.
  */
 export {
+	buildServer,
+	SERVER_INSTRUCTIONS,
 	searchComponents,
+	searchDocs,
+	getComposable,
 	getComponent,
 	listTokens,
 	listGuides,