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

package/bin/bitboss-ui-mcp.mjs

@@ -31,7 +31,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
@@ -48,6 +48,10 @@ import {
 	possessive,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
+import {
+	agentComponent,
+	firstSentence,
+} from '../scripts/lib/agent-manifest.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const AI_ROOT = join(PACKAGE_ROOT, 'dist', 'ai');
@@ -65,19 +69,38 @@ function packageVersion() {
 	}
 }
 
+/*
+ * Parsed once per build of components.json (Q56.46): the 1.2 MB file was
+ * re-read and re-parsed on every tool call. Both caches below (the raw
+ * manifest for the lookup tools, the validator's map for `validate`) are
+ * keyed on the file's mtime, so a rebuild under a running server (library
+ * repo, `npm run build`) is picked up by every tool.
+ */
+let cachedManifest = null;
 function loadComponentsManifest() {
 	if (!existsSync(MANIFEST_PATH)) {
 		throw new Error(
 			`components.json not found at ${MANIFEST_PATH} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
 		);
 	}
-	return JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'));
+	const mtime = statSync(MANIFEST_PATH).mtimeMs;
+	if (cachedManifest?.mtime !== mtime)
+		cachedManifest = {
+			mtime,
+			value: JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8')),
+		};
+	return cachedManifest.value;
 }
 
 let cachedManifestMap = null;
 function getManifestMap() {
-	cachedManifestMap ??= loadManifest(MANIFEST_PATH);
-	return cachedManifestMap;
+	// Missing file: loadManifest throws the install hint.
+	const mtime = existsSync(MANIFEST_PATH)
+		? statSync(MANIFEST_PATH).mtimeMs
+		: null;
+	if (cachedManifestMap?.mtime !== mtime || mtime === null)
+		cachedManifestMap = { mtime, value: loadManifest(MANIFEST_PATH) };
+	return cachedManifestMap.value;
 }
 
 /** `search_components({ query })` — token match over name/description. */
@@ -441,7 +464,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.
@@ -580,6 +603,13 @@ function resolveComponent(manifest, name) {
 
 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) => ({
@@ -662,8 +692,346 @@ function contractGuideSections(markdown) {
 	return all.slice(start + 1, end === -1 ? undefined : end);
 }
 
-/** Sections every agent needs, served whole in the default answer. */
+/*
+ * 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.
+ * `firstSentence` lives in scripts/lib/agent-manifest.mjs: the manifest
+ * index (Q56.46) cuts descriptions the same way.
+ */
+
+/** 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? })`.
@@ -679,7 +1047,14 @@ const ALWAYS_SECTIONS = [/^gotchas/i, /^accessibility/i];
  * sections, the component tree, the CSS variables with their descriptions
  * and the whole contract come on request.
  */
-function getComponent({ name, sections, include, maxChars } = {}) {
+function getComponent({
+	name,
+	sections,
+	include,
+	maxChars,
+	detail,
+	members,
+} = {}) {
 	const manifest = loadComponentsManifest();
 	const resolved = resolveComponent(manifest, name);
 	const entry = resolved?.entry;
@@ -807,56 +1182,144 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 	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.`,
+		};
+	}
+
+	/*
+	 * The whole entry is the shipped agent file, dist/ai/manifest/components/
+	 * <Name>.json (Q56.46: one builder), with the MCP's own compaction on top:
+	 * the types go in the answer's `types` (with import lines), the cssProps
+	 * as names, the register as one history line per old name.
+	 */
+	const { types: _agentTypes, ...agent } = agentComponent(entry, manifest);
 	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) }
+		...agent,
+		...(wanted.has('ptProps')
+			? {
+					props: entry.props.map(({ required, ...prop }) =>
+						required ? { ...prop, required } : prop
+					),
+				}
 			: {}),
+		...(entry.cssProps
+			? {
+					cssProps: wanted.has('cssProps')
+						? entry.cssProps
+						: entry.cssProps.map((c) => c.name ?? c),
+				}
+			: {}),
+		...(wanted.has('tree') && entry.tree ? { tree: entry.tree } : {}),
+		// The rendered `.bb-*` classes (Q46.5) are for tools (`check`,
+		// `validate`); an agent restyles through pt and the locals.
+		...(wanted.has('css') && entry.css ? { css: entry.css } : {}),
 	};
-	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}` : ''}`
-				),
-		];
+	if (wanted.has('history')) {
+		if (entry.renamed) component.renamed = entry.renamed;
+	} else if (entry.removed?.length || entry.renamed?.length) {
+		component.history = historyLines(entry);
 		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)
 	);
@@ -989,8 +1452,16 @@ function* eachTokenDeclaration(css) {
 	const stack = [];
 	let buffer = '';
 	let quote = null;
+	// Parenthesis depth: CSS `if()` separates its branches with `;`, and a
+	// branch may read `style(--bb-x: …)`. Only a top-level `;` ends a
+	// declaration, and only a name at its START is the property it sets
+	// (Q56.48: `--fg-hover: if(style(--bb-primary-fg: …)…)` was served as a
+	// local rebind of --bb-primary-fg).
+	let depth = 0;
 	const declaration = () => {
-		const m = buffer.match(/(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
+		const m = buffer
+			.replace(/\/\*[\s\S]*?\*\//g, '')
+			.match(/^\s*(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
 		buffer = '';
 		return m ? { name: m[1], value: m[2].trim() } : null;
 	};
@@ -1003,6 +1474,11 @@ function* eachTokenDeclaration(css) {
 		if (char === '"' || char === "'") {
 			quote = char;
 			buffer += char;
+		} else if (char === '(' || char === ')') {
+			depth = Math.max(0, depth + (char === '(' ? 1 : -1));
+			buffer += char;
+		} else if (depth > 0) {
+			buffer += char;
 		} else if (char === '{') {
 			// A comment before a rule would otherwise prefix its selector or
 			// hide the `@supports` it opens.
@@ -1178,7 +1654,7 @@ function listGuides() {
 
 /** 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;
+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
@@ -1205,6 +1681,38 @@ function resolveGuidePath(name) {
 
 /** `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'));
@@ -1216,10 +1724,25 @@ function getGuide({ name, sections, maxChars } = {}) {
 					.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: `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.',
 		};
 	}
@@ -1236,7 +1759,13 @@ function getGuide({ name, sections, maxChars } = {}) {
 		const { picked, missing } = pickSections(all, sections);
 		return {
 			...base,
-			sections: picked.map((s) => ({ title: s.title, text: s.text })),
+			...(() => {
+				const { kept, ...rest } = capParts(
+					picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+					'Sections'
+				);
+				return { sections: kept, ...rest };
+			})(),
 			...(missing.length ? { notFound: missing, outline: outline(all) } : {}),
 		};
 	}
@@ -1336,7 +1865,11 @@ function docIndex() {
 				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 } },
+				// 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 ?? []) {
@@ -1344,7 +1877,10 @@ function docIndex() {
 				source: `component ${component.name}`,
 				section: `event ${event.name}`,
 				text: `@${event.name} ${event.signature}. ${event.description ?? ''}`,
-				read: { tool: 'get_component', args: { name: component.name } },
+				read: {
+					tool: 'get_component',
+					args: { name: component.name, members: [event.name] },
+				},
 			});
 		}
 		/*
@@ -1489,9 +2025,11 @@ function docIndex() {
 	}
 	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' },
+		// 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;
@@ -1500,13 +2038,16 @@ function docIndex() {
 
 function searchDocs({ query, limit } = {}) {
 	const max = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 20) : 8;
-	const { tokens, total, results } = searchSections(docIndex(), query, max);
+	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 ?? '',
-		tokens,
 		count: results.length,
 		...(total > results.length ? { totalMatches: total } : {}),
-		results,
+		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.',
@@ -1514,7 +2055,7 @@ function searchDocs({ query, limit } = {}) {
 }
 
 /** `get_composable({ name })` — one composable's doc (useToast, useConfirm…). */
-function getComposable({ name } = {}) {
+function getComposable({ name, sections, maxChars } = {}) {
 	const dir = join(AI_ROOT, 'composables');
 	const files = existsSync(dir)
 		? readdirSync(dir).filter((f) => f.endsWith('.md'))
@@ -1540,12 +2081,44 @@ function getComposable({ name } = {}) {
 	const host = frontmatter(markdown).summary?.match(
 		/Requires (exactly one <Bb\w+ \/> host[^.]*)\./
 	)?.[1];
-	return {
+	const base = {
 		found: true,
 		name: file.slice(0, -3),
 		...(host ? { requires: host } : {}),
-		content: stripFrontmatter(markdown),
 	};
+	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,
+		'The cut tail is later sections.'
+	);
+	return { ...base, content: stripFrontmatter(content), ...cut };
 }
 
 function listRecipes({ platform } = {}) {
@@ -1590,7 +2163,7 @@ function listRecipes({ platform } = {}) {
 }
 
 /** `get_recipe({ platform, name })` — read one recipe's markdown content. */
-function getRecipe({ platform, name, sections, maxChars } = {}) {
+function getRecipe({ platform, name, sections, files, maxChars } = {}) {
 	if (!RECIPE_PLATFORMS.includes(platform)) {
 		return {
 			found: false,
@@ -1628,15 +2201,102 @@ function getRecipe({ platform, name, sections, maxChars } = {}) {
 			found: true,
 			platform,
 			name: fileName.slice(0, -3),
-			sections: picked.map((section) => ({
-				title: section.title,
-				text: section.text,
-			})),
+			...(() => {
+				const { kept, ...rest } = capParts(
+					picked.map((sec) => sectionAnswer(sec, all, maxChars)),
+					'Sections'
+				);
+				return { sections: kept, ...rest };
+			})(),
 			...(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.
+	/*
+	 * 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(
 		markdown,
 		maxChars ?? 0,
@@ -1758,10 +2418,96 @@ function compactChanges(rows) {
 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).
+/*
+ * 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 ? rawSince : String(rawSince).replace(/^v/, '');
+		rawSince == null || fromV2 ? undefined : String(rawSince).replace(/^v/, '');
 	const until =
 		rawUntil == null ? rawUntil : String(rawUntil).replace(/^v/, '');
 	if (!existsSync(CHANGELOG_PATH)) {
@@ -1793,12 +2539,114 @@ function listChanges({ since: rawSince, until: rawUntil } = {}) {
 			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.',
+				hint: 'Pass a version exactly as listed in knownReleases; coming from v2, pass since: "2" for every break of the v2 → v3 upgrade.',
 			};
 		}
 	}
 
-	const all = doc.breaking ?? [];
+	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) {
@@ -1824,6 +2672,22 @@ function listChanges({ since: rawSince, until: rawUntil } = {}) {
 		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,
@@ -1845,7 +2709,17 @@ function toolCallback(fn) {
 			return {
 				// Compact JSON: indentation was a quarter of every answer (review D6).
 				content: [{ type: 'text', text: JSON.stringify(result) }],
-				isError: false,
+				// 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);
@@ -1867,12 +2741,12 @@ 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.',
+	'- 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). Which release changed something, or what a bump breaks: list_changes({ since }), each row has firstReleasedIn.',
+	'- 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 (useToast, useConfirm…): get_composable. Whole pages: list_recipes, get_recipe. Long guides answer with an outline: pass sections.',
+	'- 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. */
@@ -1881,12 +2755,33 @@ function buildServer() {
 		{ name: 'bitboss-ui', version: packageVersion() },
 		{ 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). 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.',
+				'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()
@@ -1914,7 +2809,7 @@ function buildServer() {
 		'get_component',
 		{
 			description:
-				"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').",
+				"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()
@@ -1948,6 +2843,18 @@ function buildServer() {
 					.describe(
 						`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."
+					),
 			},
 		},
 		toolCallback(getComponent)
@@ -1984,7 +2891,7 @@ function buildServer() {
 		'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.',
+				'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()
@@ -1998,6 +2905,30 @@ function buildServer() {
 					.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)
@@ -2051,12 +2982,18 @@ function buildServer() {
 		'get_recipe',
 		{
 			description:
-				'Read one recipe by platform and name — whole by default (recipes are copied whole); pass `sections` to read part of a long one.',
+				'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 whole recipe.'),
+					.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.'
 				),
@@ -2068,7 +3005,9 @@ function buildServer() {
 					.int()
 					.min(0)
 					.optional()
-					.describe('Optional cap on the returned markdown (default: no cap).'),
+					.describe(
+						'Return the markdown itself instead of the outline: 0 = whole, N = cut at N chars.'
+					),
 			},
 		},
 		toolCallback(getRecipe)
@@ -2100,9 +3039,19 @@ function buildServer() {
 		'get_composable',
 		{
 			description:
-				"Read one composable's doc (useToast, useConfirm, useBbTableContext, useMobile…): what it returns, what host it needs, examples.",
+				"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)