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

package/README.md

@@ -10,17 +10,17 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheet
 
 ### Styles
 
-- **Global stylesheet** — import `bitboss-ui/styles.css` once. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
+- **Global stylesheet** — `bitboss-ui/styles.css`, injected for you by the runtime plugin (`injectStyles`, on by default); import it by hand only with `injectStyles: false`. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
 - **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`). A reset is a **prerequisite** of the components, not a nicety: their sizes are written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Use this one, or your own — Tailwind's Preflight covers it, which is why `resetCss` defaults to off. The component test suite runs against this file.
 - **Cascade layers (opt-in)** — on Tailwind v4 the library must sit in your layer order or its unlayered rules outrank every utility you put on a component. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin (both exported from `bitboss-ui/vite`) places it after Preflight and before the utilities. Details in `dist/ai/guides/installation-and-plugin-setup.md` § Cascade layers.
 
 ### TypeScript: use `vue-tsc` 3
 
 Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
-silently checks **nothing** about the props of the nine public components that
+silently checks **nothing** about the props of the ten public components that
 use `<script setup generic="…">` — `BbSelect`, `BbSelectPopover`, `BbTable`,
 `BbTabs`, `BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`,
-`BbSwitchGroup` —
+`BbSwitchGroup`, and `BbForm` —
 because they emit as generic functions rather than `DefineComponent<…>`, a shape
 Vue Language Tools 2 cannot read props out of.
 
@@ -82,7 +82,8 @@ Product-ready components with labels, hints, errors, and consistent styling:
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
-- **Validated forms** (`bitboss-ui/validated`, needs `vee-validate`): `BbForm`, `useBbFormContext`, and validated twins of 16 form controls (same names, plus `rules` / `vid`; not yet `BbRadio` or the pickers without an input).
+- **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbFormContext`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).
+- **Schema validation, no adapter:** pass a Zod, Valibot, ArkType or Yup schema (any [Standard Schema](https://standardschema.dev)) to `BbForm`'s `schema` as it is. Messages land on the field by path (`address.city`, `lines.0.qty`), `@submit` receives the schema's parsed output typed from the schema, the required asterisk comes from the schema, and a failed submit focuses the first invalid field on screen. Per-step schemas plus `keep-values-on-unmount` cover multi-step wizards. No extra runtime dependency.
 - **Passthrough scopes:** `BbPtScope` + `definePt` — a named `pt` map applied to one area of the app.
 
 ### Passthrough (`pt`)
@@ -178,14 +179,15 @@ import { BbButton, BbTextInput, useToast } from 'bitboss-ui';
 
 ### Styles
 
-Bundled CSS is published under the `styles` export:
+Bundled CSS is published under the `styles` export. **You do not import it**:
+the runtime plugin injects it (`injectStyles`, on by default), into its cascade
+layer when `cssLayers` is set. A hand import on top adds a second, unlayered
+copy that outranks your Tailwind v4 utilities. Only with `injectStyles: false`:
 
 ```ts
 import 'bitboss-ui/styles.css';
 ```
 
-Use this once in your app entry (or in Nuxt/Vite global CSS) so components match the intended look and layout.
-
 ### Vite plugin
 
 Use the Vite export to enable icon virtual modules and typed registry integration:
@@ -193,13 +195,16 @@ Use the Vite export to enable icon virtual modules and typed registry integratio
 ```ts
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import { bitbossUi } from 'bitboss-ui/vite';
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
 
 export default defineConfig({
 	plugins: [
 		vue(),
 		bitbossUi({
 			iconDir: './src/assets/icons',
+			// Tailwind v4: keep this, or your utilities on Bb* components lose to
+			// the library's CSS. Tailwind v3 or plain CSS: drop it.
+			cssLayers: TAILWIND_V4_LAYERS,
 		}),
 	],
 });
@@ -221,12 +226,14 @@ throws. Details: `dist/ai/guides/icons-policy.md` and
 ### Nuxt module
 
 ```ts
+import { TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
 export default defineNuxtConfig({
 	modules: ['bitboss-ui/nuxt'],
 	bitboss: {
 		iconDir: './assets/icons',
+		cssLayers: TAILWIND_V4_LAYERS, // Tailwind v4 only
 	},
-	css: ['bitboss-ui/styles.css'],
 });
 ```
 
@@ -459,6 +466,22 @@ entry is the state itself and is never reported:
 />
 ```
 
+#### Nameless controls: `require-accessible-name`
+
+`bitboss-ui/require-accessible-name` flags an icon-only `BbButton` with no
+words (no default-slot content, no `text`, no `aria-label` / `aria-labelledby`
+/ `title`), an icon-only `BbBadge` with an empty default slot (its label), and
+a `BbProgress` with no `label`: all three render with no accessible name. Put the words in the slot; with `icon` set they are visually hidden and
+still name the button:
+
+```vue
+<BbButton icon="lucide:trash">Elimina</BbButton>
+<BbProgress label="Upload" :model-value="progress" />
+```
+
+`BbSpinner` is not covered: without `label` it is decorative, which is correct.
+For raw HTML controls, use `eslint-plugin-vuejs-accessibility`.
+
 #### Rating star colours: `no-star-color`
 
 `bitboss-ui/no-star-color` flags any colour utility in `BbRating`'s `pt:item`,

package/bin/bitboss-ui-mcp.mjs

@@ -592,6 +592,65 @@ function nearestComponents(manifest, name, count = 3) {
 		.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);
@@ -652,6 +711,8 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 				...(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.`
@@ -736,9 +797,11 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 			...(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(
@@ -755,6 +818,9 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 			: {}),
 	};
 	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).
@@ -763,14 +829,28 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 		(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) =>
-					`${r.from} → ${r.to}${r.fix?.kind && r.fix.kind !== 'rename' ? ` (${r.fix.kind})` : ''}`
+					`${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) => `${r.name} removed${r.new ? ` → ${r.new}` : ''}`),
+				.map(
+					(r) =>
+						`${spell(r, r.name)} removed${r.new ? ` → ${spell(r, r.new)}` : ''}${r.hint ? ` — ${r.hint}` : ''}`
+				),
 		];
 		delete component.removed;
 		delete component.renamed;
@@ -795,9 +875,17 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 		...(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 keys as one object.`,
+					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)
@@ -822,7 +910,7 @@ function getComponent({ name, sections, include, maxChars } = {}) {
 						: {}),
 				}
 			: {}),
-		hint: `Structured API above is complete. Read guide sections with get_component({ name: '${entry.name}', sections: ['<title from guide.sections>'] }); add include: ['tree' | 'cssProps' | 'ptProps' | 'history' | 'contract'] for the component tree, CSS variables with descriptions, every pt:* row, the full v2/beta rename records, or the whole contract. search_docs finds a topic across all docs.`,
+		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.`,
 	};
 }
 
@@ -1024,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. `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.',
+				? `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 = [];
@@ -1251,6 +1347,43 @@ function docIndex() {
 				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);
@@ -1266,6 +1399,94 @@ function docIndex() {
 			});
 		}
 	}
+	// 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'), () => ({
@@ -1309,10 +1530,21 @@ function getComposable({ 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),
-		content: stripFrontmatter(readFileSync(join(dir, file), 'utf-8')),
+		...(host ? { requires: host } : {}),
+		content: stripFrontmatter(markdown),
 	};
 }
 
@@ -1422,8 +1654,17 @@ function getRecipe({ platform, name, sections, 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 } : {}),
+	};
 }
 
 /**
@@ -1470,6 +1711,53 @@ function compareVersions(a, b) {
  * 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 =
@@ -1492,6 +1780,16 @@ function listChanges({ since: rawSince, until: rawUntil } = {}) {
 		['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,
@@ -1511,8 +1809,8 @@ function listChanges({ since: rawSince, until: rawUntil } = {}) {
 			releases,
 			summary: doc.summary,
 			count: all.length,
-			breaking: all,
-			hint: 'Narrow to one upgrade hop with list_changes({ since: "<your current version>" }) — that answers "what breaks if I bump".',
+			...compactChanges(all),
+			hint: `Narrow to one upgrade hop with list_changes({ since: "<your current version>" }) — that answers "what breaks if I bump". ${ROW_FIELDS}`,
 		};
 	}
 
@@ -1531,12 +1829,12 @@ function listChanges({ since: rawSince, until: rawUntil } = {}) {
 		since: since ?? null,
 		until: until ?? doc.version,
 		count: inRange.length,
-		breaking: inRange,
+		...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.',
+				: `Each entry names the component and the new spelling; \`guide\` is the migration page with the full explanation. ${ROW_FIELDS}`,
 	};
 }
 
@@ -1567,12 +1865,14 @@ const platformSchema = z.enum(RECIPE_PLATFORMS);
  */
 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. Before bumping the version: list_changes({ since }).',
-	'- Composables (useToast, useConfirm…): get_composable. Whole pages: list_recipes, get_recipe.',
-	'- Long guides answer with an outline: pass sections.',
+	'- 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. */
@@ -1626,10 +1926,19 @@ function buildServer() {
 						"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', 'ptProps', 'history', 'contract']))
+					.array(
+						z.enum([
+							'tree',
+							'cssProps',
+							'css',
+							'ptProps',
+							'history',
+							'contract',
+						])
+					)
 					.optional()
 					.describe(
-						'Extra parts: tree = the component tree, cssProps = CSS variables with descriptions, ptProps = every pt:* prop row, history = full v2/beta rename records, contract = the whole contract markdown.'
+						'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()
@@ -1803,7 +2112,7 @@ function buildServer() {
 		'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()