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

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.',
 	};
 }
 
@@ -176,16 +476,297 @@ 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/, '');
+	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);
+}
+
+/** Sections every agent needs, served whole in the default answer. */
+const ALWAYS_SECTIONS = [/^gotchas/i, /^accessibility/i];
+
+/**
+ * `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 } = {}) {
 	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 +774,143 @@ 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 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)
+	) {
+		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(', ');
+		component.history = [
+			...(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}` : ''}`
+				),
+		];
+		delete component.removed;
+		delete component.renamed;
+	}
+
+	const { picked, missing } = pickSections(guide, sections);
+	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 +924,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|\.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".
  */
-const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+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 +979,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 +1004,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 +1040,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 +1061,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 +1098,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 +1112,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 +1140,412 @@ 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 = 16000;
+
+/**
+ * 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 } = {}) {
+	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);
 		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 } : {}),
+			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 guidesDir = join(AI_ROOT, 'guides');
-	const filePath = join(guidesDir, fileName);
-	if (!filePath.startsWith(guidesDir) || !existsSync(filePath)) {
+	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 {
-			found: false,
-			error: `Guide not found: ${fileName}`,
-			hint: 'Call list_guides for the available names.',
+			...base,
+			sections: picked.map((s) => ({ title: s.title, text: s.text })),
+			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
 		};
 	}
-	const { content, ...meta } = truncateMarkdown(
-		readFileSync(filePath, 'utf-8'),
+	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.`
+		'Guides are ordered narrative — the cut tail is later sections.'
 	);
-	return { found: true, name: fileName, content, ...meta };
+	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');
+	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 ?? ''}`,
+				read: { tool: 'get_component', args: { name: component.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 } },
+			});
+		}
+		/*
+		 * 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)) {
+		addSections('README', readFileSync(readme, 'utf-8'), () => ({
+			tool: 'read file',
+			args: { path: 'node_modules/bitboss-ui/README.md' },
+		}));
+	}
+	cachedDocIndex = entries;
+	return entries;
+}
+
+function searchDocs({ query, limit } = {}) {
+	const max = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 20) : 8;
+	const { tokens, total, results } = searchSections(docIndex(), query, max);
+	return {
+		query: query ?? '',
+		tokens,
+		count: results.length,
+		...(total > results.length ? { totalMatches: total } : {}),
+		results,
+		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 } = {}) {
+	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: `Composable not found: ${name}`,
+			available: files.map((f) => f.slice(0, -3)),
+		};
+	}
+	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];
+	return {
+		found: true,
+		name: file.slice(0, -3),
+		...(host ? { requires: host } : {}),
+		content: stripFrontmatter(markdown),
+	};
 }
 
 function listRecipes({ platform } = {}) {
@@ -398,21 +1557,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, maxChars } = {}) {
 	if (!RECIPE_PLATFORMS.includes(platform)) {
 		return {
 			found: false,
@@ -442,9 +1620,26 @@ 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),
+			sections: picked.map((section) => ({
+				title: section.title,
+				text: section.text,
+			})),
+			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
+		};
+	}
+	// Whole by default (review D6-14): a recipe is copied whole, and 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 +1654,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,12 +1673,178 @@ 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.';
+
+function listChanges({ since: rawSince, until: rawUntil } = {}) {
+	// The repo's own tags are spelled `v3.0.0-beta.33` (review D6-12).
+	const since =
+		rawSince == null ? rawSince : 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, or omit both to get every break in the v2 → v3 upgrade.',
+			};
+		}
+	}
+
+	const all = doc.breaking ?? [];
+	// 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;
+	});
+
+	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) }],
+				// Compact JSON: indentation was a quarter of every answer (review D6).
+				content: [{ type: 'text', text: JSON.stringify(result) }],
 				isError: false,
 			};
 		} catch (error) {
@@ -489,18 +1859,34 @@ 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 }) — compact; pass sections for guide prose, include for more.',
+	'- 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). Which release changed something, or what a bump breaks: list_changes({ since }), each row has firstReleasedIn.',
+	"- pt in <script> (a const, a wrapper's prop): type it <Name>Props['pt']; Pt* types are not exported.",
+	'- Composables (useToast, useConfirm…): get_composable. Whole pages: list_recipes, get_recipe. Long guides 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 }
 	);
 
 	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.',
+				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Multi-word queries are matched per word, so "data table" finds BbTable. Also returns `notInLibrary`: the component picker\'s authoritative verdicts for names agents commonly invent — either a redirect ("BbDrawer" is BbOffCanvas) or a confirmation that it does not exist and what to do instead. Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code. 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 +1903,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 +1914,39 @@ 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: every prop, event, slot, v-model and pt part (never cut), the types its API uses with their values, the guide's outline and its Gotchas + Accessibility sections. Compact by default; pass `sections` for guide prose and `include` for more. Also answers for a public TYPE name (its definition and values), a v2/beta name that was removed or renamed (what replaced it), 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).`
 					),
 			},
 		},
@@ -571,17 +1980,46 @@ function buildServer() {
 		toolCallback(listGuides)
 	);
 
+	server.registerTool(
+		'list_changes',
+		{
+			description:
+				'Breaking changes between two bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on> before upgrading. Omit both arguments for every break in the v2 → v3 upgrade. 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.'
+					),
+			},
+		},
+		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 +2037,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 +2051,12 @@ function buildServer() {
 		'get_recipe',
 		{
 			description:
-				'Read the full markdown content of one recipe by platform and name.',
+				'Read one recipe by platform and name — whole by default (recipes are copied whole); pass `sections` to read part of a long one.',
 			inputSchema: {
+				sections: z
+					.array(z.string())
+					.optional()
+					.describe('Section titles to return instead of the whole recipe.'),
 				platform: platformSchema.describe(
 					'Which platform variant of the recipe to read.'
 				),
@@ -626,19 +2068,51 @@ function buildServer() {
 					.int()
 					.min(0)
 					.optional()
+					.describe('Optional cap on the returned markdown (default: no cap).'),
+			},
+		},
+		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(
-						`Cap on the returned markdown (default ${MARKDOWN_DEFAULT_MAX_CHARS}; 0 = no cap).`
+						"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(getRecipe)
+		toolCallback(searchDocs)
+	);
+
+	server.registerTool(
+		'get_composable',
+		{
+			description:
+				"Read one composable's doc (useToast, useConfirm, useBbTableContext, useMobile…): what it returns, what host it needs, examples.",
+			inputSchema: {
+				name: z.string().describe("Composable name, e.g. 'useToast'."),
+			},
+		},
+		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 +2133,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 +2162,11 @@ export const start = main;
  * concurrently. Importing this module does not start a server.
  */
 export {
+	buildServer,
+	SERVER_INSTRUCTIONS,
 	searchComponents,
+	searchDocs,
+	getComposable,
 	getComponent,
 	listTokens,
 	listGuides,