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

package/bin/bitboss-ui.mjs

@@ -11,8 +11,10 @@
  *             - .github/copilot-instructions.md fragment (GitHub Copilot)
  *             - .claude/skills/bitboss-ui/SKILL.md (Claude Code)
  *             - .windsurf/rules/bitboss-ui.md (Windsurf)
- *             Accepts an optional --mcp flag (combinable with --update) to also
- *             register the `bitboss-ui mcp` server in .mcp.json.
+ *             Also registers the `bitboss-ui mcp` server for Claude Code,
+ *             Cursor and VS Code and installs its optional peers
+ *             (`@modelcontextprotocol/sdk`, `zod`) with the project's package
+ *             manager; pass --no-mcp to skip both.
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
  *             v-models, unknown `<template #slot>` names, `href`/`to`/
@@ -22,38 +24,81 @@
  *             `bitboss-ui.allowComponents`) exempts an app-owned component
  *             whose name happens to start with `Bb`.
  *
+ *             `--manifest <path>` judges against ANOTHER version's
+ *             components.json instead of the installed one — answers "what
+ *             breaks if I upgrade" BEFORE upgrading. A path, not a version:
+ *             no network call inside a CI validator.
+ *
  *             SCOPE: `check` knows the INSTALLED v3 API and nothing about v2.
  *             "was removed from X" is a recorded v2→v3 break; "is not in X's
  *             API" only says the prop is not a v3 prop of that component —
  *             it may never have been one anywhere. `printFindingLegend` says
  *             so in the output, because two migrating fleets each spent real
  *             time discovering it the hard way.
+ *   changelog Breaking changes between two releases — `--since <version>`
+ *             answers "what breaks if I bump", without MCP. Reads the
+ *             installed `dist/ai/changelog.json`.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
- *             (search_components, get_component, list_recipes, get_recipe,
- *             validate) to MCP-capable agent harnesses.
+ *             (search_docs, search_components, get_component, get_composable,
+ *             list_tokens, list_guides, get_guide, list_changes, list_recipes,
+ *             get_recipe, validate) to MCP-capable agent harnesses.
  *
  * Plain ESM JavaScript on purpose: shipped as-is in the package, no build.
  */
 
+import { spawnSync } from 'node:child_process';
+// `globSync` is read off the namespace, not imported by name: it only exists
+// from Node 22, and a named import of a missing builtin export is a
+// SyntaxError at load time, which killed every command on Node 20 (Sail
+// images still ship it). Only quoted glob arguments need it (Q46.4).
+import * as fs from 'node:fs';
 import {
 	existsSync,
-	globSync,
 	mkdirSync,
 	readdirSync,
 	readFileSync,
 	statSync,
 	writeFileSync,
 } from 'node:fs';
-import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
-import { dirname, isAbsolute, join, relative } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import {
+	findHandRollHints,
+	loadKnownTokens,
+} from '../scripts/lib/hand-roll-hints.mjs';
+import {
+	disabledChecker,
+	ruleForFinding,
+} from '../scripts/lib/eslint-disable.mjs';
+import {
+	localBbImports,
+	localBbWarning,
+	projectLocalBbComponents,
+} from '../scripts/lib/local-components.mjs';
+import { applyBitbossFixes } from '../scripts/lib/check-fix.mjs';
+import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
+import {
+	cssLocalFindings,
+	libraryTokens,
+	localReads,
+} from '../scripts/lib/css-local-check.mjs';
+import {
+	HAND_IMPORTED_STYLES_EXTENSIONS,
+	handImportedStylesFindings,
+} from '../scripts/lib/hand-imported-styles.mjs';
+import { syncProjectVariantDts } from '../scripts/lib/project-variant-dts.mjs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
+	detectPackageManager,
+	devInstallCommand,
 	ensureMcpConfigs,
 	missingMcpPeers,
+	MCP_BIN_PATH,
+	MCP_PEERS,
 } from '../scripts/lib/mcp-config.mjs';
 import {
 	loadManifest,
+	registeredRuleNames,
 	validateMarkdown,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
@@ -83,23 +128,33 @@ function coreRules(version) {
 
 1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
 2. **Obey the agent contract**: \`${CONTRACT}\`.
-3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` is consumer API; most other \`BbBase*\` form primitives are not.)
+3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
 4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or validate against \`${KNOWLEDGE_BASE}/components.json\`.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
-8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\` — \`--bb-*\` tokens only; one primary action per view region.
-9. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
-10. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
+8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\`. Paint as data is \`${KNOWLEDGE_BASE}/design-tokens.json\` and \`design-tokens.manifest.yaml\` (DESIGN.md-shaped). Grep \`--bb-*\`, not \`--color-*\` or \`--radius-*\`. A repo-root DESIGN.md is not this library. Two token tiers, and reaching for the wrong one is why apps end up re-skinning by class: \`--bb-*\` is the small GLOBAL theme tier (brand knobs, no numeric ramp — there is no \`--bb-primary-800\`), while each component declares its own **unprefixed** \`--*\` tokens for its look (\`.bb-table { --cell-h: 32px }\`). A missing \`--bb-*\` name is not a gap in the library — it means the knob you want is a component token. Set it on the element that DECLARES it (grep \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`); a value set further out is masked, not inherited. Prefer tokens, variants and \`pt\`; CSS on \`.bb-*__*\` internals is allowed for fine-tuning but unsupported: it can break on upgrade. \`.bb-common-*\` / \`.bb-field*\` internals: expect it to break. (\`.bb-base-button\` and the three \`.bb-base-*-icon\` glyph classes are consumer API — a supported hook, not an internal.) An override on an internal is a signal to check for a \`pt\` part or request one. A Tailwind utility on a \`Bb*\` component that does nothing is rule 9, not a library bug. One primary action per view region.
+9. **Tailwind v4 app: turn on cascade layers when you set bitboss-ui up**, not later when a class "doesn't work". In the build plugin: \`import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite'\` and \`bitbossUi({ cssLayers: TAILWIND_V4_LAYERS })\` (Nuxt: \`bitboss: { cssLayers: TAILWIND_V4_LAYERS }\`, same import). Tailwind v4 emits layered CSS; without this the library's CSS is unlayered and beats every utility you put on a \`Bb*\` component or a \`pt:*\` part, whatever the specificity. With it, your utilities win. You still need the runtime plugin (\`app.use(bitbossUiPlugin)\`; Nuxt does it for you): it is what injects the sheet, into that layer. **Do not also \`@import 'bitboss-ui/styles.css'\`**: a hand import adds a second, unlayered copy and undoes the setting. Tailwind v3 or plain CSS: leave it unset. Details: \`${KNOWLEDGE_BASE}/guides/installation-and-plugin-setup.md\` § Cascade layers.
+10. **Set a \`font-family\` on \`body\`** (components inherit it; there is no font token), e.g. \`body { font-family: system-ui, sans-serif; }\`. Without one the whole app renders in the browser's default serif.
+11. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. After registering, run \`npx bitboss-ui check\`: it writes the project's \`bitboss-ui.d.ts\` so the new name type-checks before Vite has run. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
+12. **Never name your own components \`Bb…\`** — that prefix is bitboss-ui's. Use your app's prefix (\`App…\`, \`Acme…\`). \`check\` leaves an app's own \`Bb*\` component alone but warns: a future bitboss-ui component could take the name.
+13. **Set \`locale\` explicitly** in the build plugin (\`bitbossUi({ locale: 'it' })\` / nuxt \`bitboss: { locale: 'it' }\`) for any app that is not English: the built-in strings default to English (\`'en'\`, since 3.0.0-beta.41; it was \`'it'\`).
+14. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
 
 After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
 }
 
+// A blank line after the start marker and before the end marker: an HTML
+// comment butting against a heading or a paragraph is not Prettier-stable
+// markdown, and a consumer running `prettier --check` on their AGENTS.md
+// (as our own fixture does in CI) would fail on text we wrote.
 function agentsFragment(version) {
 	return `${START_MARKER}
+
 ## bitboss-ui (v${version})
 
 ${coreRules(version)}
+
 ${END_MARKER}`;
 }
 
@@ -190,7 +245,7 @@ function tryWrite(label, fn) {
 	}
 }
 
-function aiInit({ mcp = false } = {}) {
+function aiInit({ mcp = true } = {}) {
 	const projectRoot = process.cwd();
 	const version = packageVersion();
 
@@ -239,11 +294,7 @@ function aiInit({ mcp = false } = {}) {
 	];
 
 	if (mcp) {
-		// Explicit command → register every harness, including Windsurf's global
-		// (home-dir) config.
-		for (const result of ensureMcpConfigs(projectRoot, {
-			includeWindsurf: true,
-		})) {
+		for (const result of ensureMcpConfigs(projectRoot)) {
 			const suffix = result.reason ? ` (${result.reason})` : '';
 			results.push({
 				path: `${result.path} [${result.label}]${suffix}`,
@@ -252,18 +303,34 @@ function aiInit({ mcp = false } = {}) {
 		}
 
 		// The harness launches the server on demand, long after this command
-		// ran — so a missing peer would surface inside an agent as a server
-		// that never starts. Say it here, where the person is still watching.
+		// ran — a missing peer would surface inside an agent as a server that
+		// never starts. They are optional peers (~12 MB only the server loads),
+		// so installing the library never adds them; registering the server is
+		// the moment the project opts in, so install them here.
 		const missing = missingMcpPeers(projectRoot);
 		if (missing.length > 0) {
-			console.warn(
-				`[bitboss-ui] the MCP server needs ${missing.join(' and ')}, which ${
-					missing.length > 1 ? 'are' : 'is'
-				} not installed:\n` +
-					`\n  npm i -D ${missing.join(' ')}\n\n` +
-					'  Optional peers, not dependencies — ~12 MB that only the MCP\n' +
-					'  server uses. The harness entries above are written either way.'
+			const [cmd, ...args] = devInstallCommand(
+				detectPackageManager(projectRoot),
+				missing
 			);
+			const printed = [cmd, ...args].join(' ');
+			console.log(`[bitboss-ui] installing the MCP server's peers: ${printed}`);
+			const installed = spawnSync(cmd, args, {
+				cwd: projectRoot,
+				stdio: 'inherit',
+				// npm/pnpm/yarn are .cmd shims on Windows, which only a shell runs.
+				shell: process.platform === 'win32',
+			});
+			if (installed.status === 0) {
+				results.push({ path: missing.join(', '), action: 'installed' });
+			} else {
+				console.warn(
+					`[bitboss-ui] could not install ${missing.join(' and ')} — run it yourself:\n` +
+						`\n  ${printed}\n\n` +
+						'  The harness entries are written either way; the server starts\n' +
+						'  once the peers are installed.'
+				);
+			}
 		}
 	}
 
@@ -276,11 +343,11 @@ function aiInit({ mcp = false } = {}) {
 	);
 	if (mcp) {
 		console.log(
-			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium global) — restart your harness to pick it up.'
+			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json) and VS Code/Copilot (.vscode/mcp.json) — restart your harness to pick it up. `--no-mcp` skips this.'
 		);
 	} else {
 		console.log(
-			'Tip: `npx bitboss-ui ai-init --mcp` also registers the MCP server across Claude Code / Cursor / VS Code / Windsurf so agents can query the knowledge base instead of reading files.'
+			'MCP: skipped (--no-mcp). Re-run without it to let agents query the knowledge base through the bitboss-ui MCP server instead of reading files.'
 		);
 	}
 	console.log('Re-run after upgrading bitboss-ui to refresh the pointers.');
@@ -348,7 +415,7 @@ function inSkippedDir(relPath) {
  * `recursive: true` readdir) is what keeps a multi-thousand-file `vendor/`
  * tree from being walked at all.
  */
-function collectCheckFiles(dir, relBase = dir) {
+function collectCheckFiles(dir, relBase = dir, extensions = CHECK_EXTENSIONS) {
 	let entries;
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
@@ -361,11 +428,11 @@ function collectCheckFiles(dir, relBase = dir) {
 		if (entry.isDirectory()) {
 			if (isSkippedSegment(entry.name)) continue;
 			if (isSkippedSubpath(relative(relBase, full))) continue;
-			out.push(...collectCheckFiles(full, relBase));
+			out.push(...collectCheckFiles(full, relBase, extensions));
 			continue;
 		}
 		if (!entry.isFile()) continue;
-		if (!CHECK_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) continue;
+		if (!extensions.some((ext) => entry.name.endsWith(ext))) continue;
 		out.push(full);
 	}
 	return out;
@@ -401,7 +468,13 @@ function resolveCheckFiles(cwd, patterns) {
 				continue;
 			}
 		}
-		const dirents = globSync(pattern, {
+		if (typeof fs.globSync !== 'function') {
+			console.error(
+				`[bitboss-ui] quoted glob patterns need Node >= 22 (this is ${process.version}): "${pattern}". Pass the directory, or leave the pattern unquoted so the shell expands it.`
+			);
+			process.exit(1);
+		}
+		const dirents = fs.globSync(pattern, {
 			cwd,
 			withFileTypes: true,
 			// Pruning is a traversal shortcut; the inSkippedDir filter below is
@@ -507,7 +580,12 @@ function printFindingLegend(findings) {
 	const rows = [];
 	if (kinds.has('removed-prop'))
 		rows.push(
-			'  "was removed from X"   a v2→v3 break. X really had this prop; fix the call site.'
+			'  "was removed from X"   a recorded break (v2→v3, or a v3 beta rename). X really\n' +
+				'  / "was renamed on X"   had this prop or pt key; `check --fix` rewrites the renames.'
+		);
+	if (kinds.has('renamed-slot'))
+		rows.push(
+			'  "slot … was renamed"   a recorded slot rename; `check --fix` rewrites it.'
 		);
 	if (kinds.has('unknown-prop'))
 		rows.push(
@@ -519,6 +597,29 @@ function printFindingLegend(findings) {
 				'                         "restoring" anything: the second case needs deleting,\n' +
 				'                         not porting.'
 		);
+	// A type written as a tag is its own category: the name IS ours, so neither
+	// "check the spelling" nor the allowlist applies, and a reader who skims the
+	// message alone would reach for one of them.
+	if (
+		findings.some((f) => / is a type export, not a component$/.test(f.message))
+	)
+		rows.push(
+			'  "is a type export"     a real export, but a TYPE — it types a prop, it does not\n' +
+				'                         render. Import it (`import type { … }`) and pass the\n' +
+				'                         value; never allowlist it, which would only silence\n' +
+				'                         every other check on that tag.'
+		);
+	if (findings.some((f) => f.fallthrough))
+		rows.push(
+			'  ⚠ (vs ✗)               markup that is not a typo and may work today: an\n' +
+				'                         undeclared listener Vue binds to the root ELEMENT,\n' +
+				'                         so whether it fires depends on what that root is —\n' +
+				"                         an internal detail, on the component's schedule or\n" +
+				"                         the element's. `<BbDialog @close>` runs (that root is\n" +
+				'                         a native <dialog>); `<BbAlert @close>` does not.\n' +
+				'                         Still reported, because neither is the contract. In\n' +
+				'                         ESLint this is `no-unknown-event`, a warning.'
+		);
 	if (rows.length === 0) return;
 	console.error('\nReading these findings:');
 	for (const row of rows) console.error(row);
@@ -532,18 +633,203 @@ function printFindingLegend(findings) {
  * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
  * the installed components.json manifest.
  */
-function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
+/**
+ * The version a components.json describes. `loadManifest` returns the indexed
+ * component map, not the envelope, so read the field straight off the file.
+ */
+/**
+ * `changelog [--since <v>] [--until <v>] [--json]` — what breaks between two
+ * releases, for anyone not driving the MCP server (a human at a terminal, CI,
+ * or an agent whose harness has no MCP). Same data and same range rules as the
+ * `list_changes` tool; this is the transport-free path to it.
+ */
+function changelogCommand({ since, until, json: jsonMode }) {
+	const path = join(PACKAGE_ROOT, 'dist', 'ai', 'changelog.json');
+	if (!existsSync(path)) {
+		console.error(
+			`[bitboss-ui] changelog: not found at ${path} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+		);
+		process.exit(1);
+	}
+	const doc = JSON.parse(readFileSync(path, 'utf-8'));
+	const releases = doc.releases ?? [];
+
+	for (const [label, value] of [
+		['--since', since],
+		['--until', until],
+	]) {
+		if (value != null && !releases.includes(value)) {
+			// A tagged-but-never-published version (beta.34): say where its
+			// changes went instead of "unknown", which reads like a typo.
+			const unpublished = (doc.unpublished ?? []).includes(value);
+			const next = releases.find((r) => compareReleaseVersions(r, value) > 0);
+			console.error(
+				(unpublished
+					? `[bitboss-ui] changelog: ${label} ${value} was never published to npm; its changes shipped in ${next ?? 'the next release'}.\n`
+					: `[bitboss-ui] changelog: unknown ${label} version '${value}'.\n`) +
+					`Known releases: ${releases.join(', ')}`
+			);
+			process.exit(1);
+		}
+	}
+
+	const ranged = since != null || until != null;
+	const rows = (doc.breaking ?? []).filter((entry) => {
+		if (!ranged) return true;
+		const at = entry.firstReleasedIn;
+		if (at == null) return until == null;
+		if (since != null && compareReleaseVersions(at, since) <= 0) return false;
+		if (until != null && compareReleaseVersions(at, until) > 0) return false;
+		return true;
+	});
+
+	if (jsonMode) {
+		console.log(
+			JSON.stringify(
+				{
+					version: doc.version,
+					since: since ?? null,
+					until: until ?? doc.version,
+					count: rows.length,
+					breaking: rows,
+					guide: doc.guide,
+				},
+				null,
+				2
+			)
+		);
+		return;
+	}
+
+	const range = ranged
+		? `${since ?? 'the start of v3'} → ${until ?? doc.version}`
+		: `the whole v2 → v3 upgrade`;
+	if (rows.length === 0) {
+		// "Nothing breaks" and "I could not tell you" must not look alike.
+		console.log(
+			`[bitboss-ui] changelog: no BREAKING changes in ${range}.\n` +
+				'            Features and fixes are deliberately not tracked here, so this\n' +
+				'            means nothing breaks — not that nothing changed.'
+		);
+		return;
+	}
+	console.log(
+		`[bitboss-ui] changelog: ${rows.length} breaking change(s), ${range}\n`
+	);
+	for (const entry of rows) {
+		const at = entry.firstReleasedIn ?? 'unreleased';
+		if (entry.kind === 'rename') {
+			// `surface` says what kind of name it is (Q51.19); a slot reads `#…`.
+			const spell = (name) => (entry.surface === 'slot' ? `#${name}` : name);
+			const surface =
+				entry.surface && entry.surface !== 'prop' ? `${entry.surface} ` : '';
+			console.log(
+				`  [${at}] ${entry.components.join(', ')}: ${surface}\`${spell(entry.from)}\` → ` +
+					(entry.to == null ? 'removed' : `\`${spell(entry.to)}\``) +
+					(entry.note ? ` (${entry.note})` : '')
+			);
+		} else {
+			console.log(`  [${at}] ${entry.description}`);
+		}
+		if (entry.guide) console.log(`           ${entry.guide}`);
+	}
+	console.log(`\nFull migration guide: ${doc.guide}`);
+}
+
+/** Numeric, prerelease-aware ordering; the twin of the MCP server's copy. */
+function compareReleaseVersions(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);
+	}
+	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;
+	return x.n - y.n;
+}
+
+function manifestVersionOf(manifestPath) {
+	try {
+		return JSON.parse(readFileSync(manifestPath, 'utf-8')).version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+async function checkCommand(
+	globs,
+	{
+		json: jsonMode,
+		allowEmpty,
+		allowComponents,
+		manifest: manifestOverride,
+		fix,
+	}
+) {
 	const projectRoot = process.cwd();
 
-	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
+	/*
+	 * `--manifest` answers the question `check` could not: "which of my files
+	 * break in the version I am about to move to?" (reported 2026-09-09). By
+	 * default the manifest is the INSTALLED one, so the only way to see an
+	 * upgrade's damage was to perform the upgrade first — exactly backwards for
+	 * the one moment the answer is worth having.
+	 *
+	 * Deliberately a PATH, not a version: fetching a version would put a network
+	 * call inside a validator that consumers run in CI, with a registry outage
+	 * as a new failure mode. Getting the file is one documented command
+	 * (`npm pack bitboss-ui@<version>`, or the public CDN copy), and pointing at
+	 * it keeps this offline and reproducible.
+	 */
+	const installedManifest = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
+	const manifestPath = manifestOverride
+		? resolve(projectRoot, manifestOverride)
+		: installedManifest;
 	if (!existsSync(manifestPath)) {
 		console.error(
-			`[bitboss-ui] Manifest not found at ${manifestPath} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+			manifestOverride
+				? `[bitboss-ui] --manifest: no file at ${manifestPath}.\n` +
+						'Point it at a components.json from the version you are moving to:\n' +
+						'  npm pack bitboss-ui@<version> && tar -xzf bitboss-ui-<version>.tgz\n' +
+						'  npx bitboss-ui check --manifest package/dist/ai/components.json'
+				: `[bitboss-ui] Manifest not found at ${manifestPath} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
 		);
 		process.exit(1);
 	}
 	const manifest = loadManifest(manifestPath);
 
+	/*
+	 * Q53.23: write the project's `bitboss-ui.d.ts` from the build config, the
+	 * file the Vite plugin writes when Vite starts. Agents run `vue-tsc` before
+	 * any dev start, so a name registered in `badgeVariants` was a type error
+	 * (and an `as any`) until then. Same generator as the plugin; a config it
+	 * cannot read is left alone. Not under `--manifest` (an upgrade preview
+	 * must not touch the project).
+	 */
+	if (!manifestOverride) {
+		try {
+			const projectDts = await import(
+				pathToFileURL(join(PACKAGE_ROOT, 'dist', 'project-dts.js')).href
+			);
+			const synced = syncProjectVariantDts(projectRoot, projectDts);
+			if (synced.status === 'written' && !jsonMode)
+				console.log(
+					`[bitboss-ui] Wrote ${synced.path} from your build config: registered variant names now type-check. Commit it.`
+				);
+		} catch {
+			// No built `dist/project-dts.js` (the library repo before a build):
+			// nothing to write with, and nothing for `check` to fail over.
+		}
+	}
+
 	/*
 	 * Every `--bb-*` the INSTALLED package declares, read from the stylesheet
 	 * the consumer actually ships. Read from disk rather than hardcoded so this
@@ -551,34 +837,123 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 	 * Absent stylesheet → an empty set → the unknown-token hint stays silent,
 	 * which is the right failure: no data, no accusation.
 	 */
-	const stylesPath = join(PACKAGE_ROOT, 'dist', 'styles.css');
-	const knownTokens = existsSync(stylesPath)
-		? new Set(
-				[
-					...readFileSync(stylesPath, 'utf-8').matchAll(
-						/(--bb-[a-z0-9-]+)\s*:/gi
-					),
-				].map((m) => m[1].toLowerCase())
-			)
-		: new Set();
+	// Under `--manifest`, take the sheet from beside THAT manifest
+	// (`<pkg>/dist/ai/components.json` → `<pkg>/dist/styles.css`). Reading the
+	// installed sheet while judging props against another version would mix two
+	// releases in one verdict — the exact confusion this flag exists to end.
+	const stylesPath = manifestOverride
+		? join(dirname(dirname(manifestPath)), 'styles.css')
+		: join(PACKAGE_ROOT, 'dist', 'styles.css');
+	const knownTokens = loadKnownTokens(stylesPath);
 	const files = resolveCheckFiles(projectRoot, globs);
 
 	// CHK-ALLOWCOMPONENTS: `Bb` is a naming convention, not proof of ownership.
 	// An app component called `BbRichEditor` is not invalid library markup, and
 	// before this the only way to silence it was to rename the component.
-	const allowedComponents = [
+	const explicitlyAllowed = new Set([
 		...configuredAllowComponents(projectRoot),
 		...allowComponents,
-	];
-	const validateOptions = { allowComponents: allowedComponents };
+	]);
+	// Q53.18: the app's own `Bb*` components (`.vue` files in its `components`
+	// dirs, Nuxt path-prefix names included) are skipped with zero config;
+	// imports from the app's own paths are handled per file by the validator.
+	const projectLocal = projectLocalBbComponents(projectRoot);
+	const allowedComponents = [...explicitlyAllowed, ...projectLocal.keys()];
+
+	// Q46.8: `--fix` applies the ESLint plugin's fixes (the registered v2→v3
+	// migrations) with ONLY the bitboss rules, then the check below reports
+	// what is left, so one command migrates and verifies.
+	if (fix) {
+		const outcome = await applyBitbossFixes({
+			projectRoot,
+			files,
+			manifestPath: manifestOverride ? manifestPath : undefined,
+			allowComponents: allowedComponents,
+		});
+		if ('error' in outcome) {
+			console.error(`[bitboss-ui] ${outcome.error}`);
+			process.exit(1);
+		}
+		const log = jsonMode ? console.error : console.log;
+		log(
+			outcome.fixed.length
+				? `[bitboss-ui] check --fix: fixed ${outcome.fixed.length} file(s):\n${outcome.fixed
+						.map((file) => `  ${relative(projectRoot, file)}`)
+						.join('\n')}`
+				: '[bitboss-ui] check --fix: nothing to fix.'
+		);
+		if (outcome.skipped?.length)
+			log(
+				`[bitboss-ui] check --fix: ESLint ignored ${outcome.skipped.length} file(s), not fixed:\n${outcome.skipped
+					.map((file) => `  ${relative(projectRoot, file)}`)
+					.join('\n')}`
+			);
+	}
+	// Q46.6: every `var(--x)` the project reads, from a whole-project sweep
+	// (explicit paths included): a local or token the app reads itself is its
+	// own, never "set and unread".
+	const projectReads = new Set();
+	for (const path of collectCheckFiles(
+		projectRoot,
+		projectRoot,
+		HAND_IMPORTED_STYLES_EXTENSIONS
+	))
+		try {
+			for (const name of localReads(readFileSync(path, 'utf-8')))
+				projectReads.add(name);
+		} catch {
+			/* unreadable: its reads are unknown, which only means fewer passes */
+		}
+	// The tokens of the sheet `check` judges against (the installed one, or
+	// the one beside `--manifest`) — read AND declared names both count.
+	if (manifest.localSurface && existsSync(stylesPath))
+		manifest.localSurface.knownTokens = libraryTokens([
+			readFileSync(stylesPath, 'utf-8'),
+			...[join(dirname(stylesPath), 'reset.css')]
+				.filter((path) => existsSync(path))
+				.map((path) => readFileSync(path, 'utf-8')),
+		]);
+	// Q54.2: the rules the project registers with `defineRule`, from the same
+	// whole-project sweep, so a string rule nobody registered is caught.
+	const registeredRules = { names: new Set(), dynamic: false };
+	for (const path of collectCheckFiles(projectRoot, projectRoot, [
+		'.ts',
+		'.js',
+		'.mjs',
+		'.cjs',
+		'.vue',
+	]))
+		try {
+			const found = registeredRuleNames(readFileSync(path, 'utf-8'));
+			for (const name of found.names) registeredRules.names.add(name);
+			if (found.dynamic) registeredRules.dynamic = true;
+		} catch {
+			/* unreadable: fewer names, which only means more caution below */
+			registeredRules.dynamic = true;
+		}
+	const validateOptions = {
+		allowComponents: allowedComponents,
+		projectReads,
+		registeredRules,
+	};
 
 	const findings = [];
+	let suppressed = 0;
+	/** One warning per local `Bb*` component, unless allowlisted (Q53.18). */
+	const warnedLocal = new Set();
+	const warnLocal = (name, file, line) => {
+		if (explicitlyAllowed.has(name) || warnedLocal.has(name)) return;
+		warnedLocal.add(name);
+		warnings.push(localBbWarning(name, file, line));
+	};
 	/*
 	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
 	 * exit code, so a guess can never fail a consumer's build. `--no-hints`
 	 * silences them for anyone who finds them noisy.
 	 */
 	const hints = [];
+	/** Findings graded `severity: 'warning'` — printed, never fatal. */
+	const warnings = [];
 	const wantHints = !process.argv.includes('--no-hints');
 	for (const file of files) {
 		const relPath = relative(projectRoot, file);
@@ -586,8 +961,26 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		const { findings: fileFindings } = file.endsWith('.md')
 			? validateMarkdown(content, manifest, validateOptions)
 			: validateVueSnippet(content, manifest, validateOptions);
+		// Q46.9: a finding the author silenced for ESLint (`eslint-disable*`,
+		// usually with a reason) is silenced here too, or `check` cannot gate
+		// CI next to a lint step that passes. `.md` lines are fence-relative,
+		// and docs carry no directives, so only `.vue` files are filtered.
+		const isDisabled = file.endsWith('.vue')
+			? disabledChecker(content)
+			: () => false;
+		if (file.endsWith('.vue'))
+			for (const [name, line] of localBbImports(content))
+				warnLocal(name, relPath, line);
 		for (const finding of fileFindings) {
-			findings.push({ file: relPath, ...finding });
+			if (isDisabled(finding.line, ruleForFinding(finding))) {
+				suppressed++;
+				continue;
+			}
+			// A `severity: 'warning'` finding (Q53.15 C9b: a slot spelled the
+			// pre-reset way) is shown and suppressible, but never fails the run.
+			if (finding.severity === 'warning')
+				warnings.push({ file: relPath, ...finding });
+			else findings.push({ file: relPath, ...finding });
 		}
 		// .md files are documentation ABOUT components; a round <img> in a doc
 		// example is illustrative, not a hand-roll.
@@ -598,6 +991,61 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		}
 	}
 
+	for (const [name, file] of projectLocal) warnLocal(name, file);
+
+	// Q25: a hand import of `bitboss-ui/styles.css` while the runtime plugin
+	// injects it. Project-level — the answer needs the build config — so it
+	// reads the style and script files too; with explicit paths, only those.
+	const styleScan = globs.length
+		? files
+		: collectCheckFiles(
+				projectRoot,
+				projectRoot,
+				HAND_IMPORTED_STYLES_EXTENSIONS
+			);
+	findings.push(
+		...handImportedStylesFindings(
+			projectRoot,
+			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) }))
+		)
+	);
+	// Q46.5: `.bb-*` selectors in the app's stylesheets (the `.vue` `<style>`
+	// blocks are read by the validator above).
+	for (const path of styleScan) {
+		if (!/\.(?:css|scss|sass|less|pcss|postcss|styl)$/.test(path)) continue;
+		const relPath = relative(projectRoot, path);
+		const content = readFileSync(path, 'utf-8');
+		for (const finding of [
+			...cssClassFindings(content, manifest.cssSurface, { stylesheet: true }),
+			// Q46.6: custom properties set where nothing reads them.
+			...cssLocalFindings(content, manifest.cssSurface, manifest.localSurface, {
+				stylesheet: true,
+				projectReads,
+			}),
+		])
+			findings.push({ file: relPath, ...finding });
+	}
+
+	/** One line, so a silenced finding is never invisible. */
+	const printSuppressed = () => {
+		if (suppressed === 0) return;
+		console.log(
+			`[bitboss-ui] ${suppressed} finding(s) silenced by eslint-disable comments.`
+		);
+	};
+
+	/** Warning block, printed on success and on failure alike. Never fatal. */
+	const printWarnings = () => {
+		if (warnings.length === 0) return;
+		console.log(
+			`\n[bitboss-ui] ${warnings.length} warning(s) — not fatal, but likely wrong:`
+		);
+		for (const warning of warnings) {
+			const at = warning.line != null ? `:${warning.line}` : '';
+			console.log(`  ⚠ ${warning.file}${at} ${warning.message}`);
+		}
+	};
+
 	/** Advisory block, printed on success and on failure alike. Never fatal. */
 	const printHints = () => {
 		if (hints.length === 0) return;
@@ -613,9 +1061,39 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		);
 	};
 
+	/*
+	 * Which API the verdict is against. Silent when it is the installed one —
+	 * that is the assumption, and a banner on every run trains people to skip
+	 * it. Loud under `--manifest`, because "12 findings" means something
+	 * completely different when it describes a version you have not installed
+	 * yet, and a scrollback with no marker is indistinguishable from a normal
+	 * run.
+	 */
+	const judgedAgainst = manifestOverride
+		? manifestVersionOf(manifestPath)
+		: packageVersion();
+	if (manifestOverride && !jsonMode) {
+		console.log(
+			`[bitboss-ui] check: judging against bitboss-ui ${judgedAgainst} (--manifest), NOT the installed ${packageVersion()}.\n` +
+				'            Findings describe the version you are moving TO.'
+		);
+	}
+
 	if (jsonMode) {
 		console.log(
-			JSON.stringify({ findings, hints, files: files.length }, null, 2)
+			JSON.stringify(
+				{
+					findings,
+					warnings,
+					hints,
+					suppressed,
+					files: files.length,
+					manifestVersion: judgedAgainst,
+					installedVersion: packageVersion(),
+				},
+				null,
+				2
+			)
 		);
 		if (findings.length > 0) process.exit(1);
 		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
@@ -646,10 +1124,14 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		console.log(
 			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
+		printSuppressed();
+		printWarnings();
 		printHints();
 		return;
 	}
 
+	printSuppressed();
+	printWarnings();
 	const fileCount = new Set(findings.map((f) => f.file)).size;
 	console.error(
 		`[bitboss-ui] check FAILED — ${findings.length} finding(s) across ${fileCount} file(s):`
@@ -668,8 +1150,13 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		// were indistinguishable, so every automated fix had to re-parse the
 		// file to place them. The line comes straight off the template AST.
 		const at = finding.line != null ? `line ${finding.line}: ` : '';
+		// A `fallthrough` finding is not a typo and may be doing something
+		// today — a native listener reaching the root element. It still counts,
+		// but marking it `✗` alongside a genuinely broken prop is what let one
+		// migration report read a live `<BbDialog @close>` as dead code.
+		const mark = finding.fallthrough ? '⚠' : '✗';
 		console.error(
-			`    ✗ ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
+			`    ${mark} ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
 		);
 		if (finding.hint) console.error(`      hint: ${finding.hint}`);
 	}
@@ -688,16 +1175,18 @@ Usage:
   npx bitboss-ui <command>
 
 Commands:
-  ai-init [--update] [--mcp]
+  ai-init [--update] [--no-mcp]
                       Inject AI-agent knowledge-base pointers into the current
                       project (AGENTS.md, Cursor rules, Copilot instructions,
-                      Claude skill, Windsurf rules). Idempotent — safe to re-run
-                      after upgrades. \`--mcp\` also registers the bitboss-ui MCP
-                      server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
-                      VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
-                      global) — merges, never overwrites other servers.
+                      Claude skill, Windsurf rules), register the bitboss-ui MCP
+                      server for Claude Code (.mcp.json), Cursor
+                      (.cursor/mcp.json) and VS Code/Copilot (.vscode/mcp.json) —
+                      merges, never overwrites other servers — and install its
+                      optional peers with the project's package manager.
+                      \`--no-mcp\` skips the server and the install. Idempotent —
+                      safe to re-run after upgrades.
   check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
-                      [--no-hints]
+                      [--no-hints] [--manifest <path>] [--fix]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -710,6 +1199,36 @@ Commands:
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
 
+                      It also writes your project's \`bitboss-ui.d.ts\` (the
+                      file the Vite plugin writes on start) from the variant
+                      options in vite.config / nuxt.config, so a newly
+                      registered variant name type-checks before Vite runs.
+                      Left alone when the options are not inline literals, and
+                      under \`--manifest\`.
+
+                      \`--fix\` first applies the ESLint plugin's fixes (the
+                      registered v2→v3 renames, polarity flips and value
+                      remaps) to the matched .vue files with ONLY the
+                      bitboss-ui rules — your own ESLint config is not used —
+                      then reports what is left. Needs \`eslint\` and
+                      \`vue-eslint-parser\` in the project.
+
+                      Honours ESLint disable comments in .vue files: a finding
+                      silenced for the matching \`bitboss-ui/*\` rule (or by a
+                      bare \`eslint-disable\`) is not reported, only counted:
+                        <!-- eslint-disable-next-line bitboss-ui/require-table-slot-prop -- why -->
+
+                      \`--manifest <path>\` judges against another version's
+                      components.json instead of the installed one — the answer
+                      to "which of my files break if I upgrade", BEFORE you
+                      upgrade. The banner names both versions so a findings list
+                      is never mistaken for one about your current install.
+                        npm pack bitboss-ui@3.0.0-beta.21
+                        tar -xzf bitboss-ui-3.0.0-beta.21.tgz
+                        npx bitboss-ui check --manifest package/dist/ai/components.json
+                      A path, not a version, on purpose: fetching one would put
+                      a registry call inside a validator people run in CI.
+
                       \`--allow-component <Name>\` (repeatable) exempts a
                       component your APP owns whose name starts with \`Bb\` —
                       the prefix is a convention, not proof of provenance.
@@ -719,20 +1238,101 @@ Commands:
                       Same option name as the ESLint rules' \`allowComponents\`,
                       so both gates configure alike.
 
-                      \`--json\` prints \`{ findings: [...], hints: [...], files }\`.
+                      \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
+                      suppressed, files, manifestVersion, installedVersion }\`.
                       Each finding: \`{ file, line, component, attr, kind,
                       message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
                       inside a markdown fence; \`line\` is absolute in the file).
-                      \`kind\` is one of: \`removed-prop\` (a v2→v3 break — fix
-                      it), \`unknown-prop\` (not a v3 prop of that component;
+                      \`kind\` is one of: \`removed-prop\` (a recorded break on a
+                      prop or a \`pt\` key, v2→v3 or a v3 beta; \`to\` is the new
+                      name when there is one and \`--fix\` writes it, else the
+                      message says what to do), \`unknown-prop\` (not a v3 prop of that component;
                       may never have been one — see the legend the text output
-                      prints), \`unknown-model\`, \`unknown-slot\`,
+                      prints), \`unknown-component\` (a \`Bb*\` tag the
+                      manifest doesn't have; \`attr\` is the tag),
+                      \`unknown-model\`, \`unknown-event\`, \`unknown-slot\`,
+                      \`unknown-pt-key\` (a key of the \`pt\` object form that
+                      matches no part / state; \`to\` when the part was renamed),
                       \`no-default-slot\`, \`inert-nav-attr\`,
-                      \`missing-partner-prop\`, \`partner-prop\`,
-                      \`validated-only-prop\`.
+                      \`nameless-control\` (an icon-only BbButton or BbBadge,
+                      or a BbProgress, with no accessible name),
+                      \`removed-css-local\` (a component CSS local the
+                      library removed, e.g. \`--day-slot-allowance\`),
+                      \`private-import\` (an import from inside the package's
+                      \`dist/\`), \`not-exported-type\` (a \`Pt*\` pt type
+                      imported from bitboss-ui: type pt through
+                      \`<Component>Props['pt']\` instead),
+                      \`missing-key\` / \`duplicate-row-text\` (a
+                      BbDropdown row or group that needs a \`key\`: selectable,
+                      or identical keyless text in one group),
+                      \`unknown-variant\` (a variant name from another
+                      library, e.g. \`danger\` on BbAlert / BbBadge; the
+                      message names ours),
+                      \`duplicate-field-identity\` (two validated fields in
+                      one \`BbForm\` on the same path: the same \`name\`,
+                      or the same label with no \`name\`),
+                      \`rules-ignored-by-schema\` (a validated field's
+                      \`rules\` inside a \`BbForm\` that has a \`schema\`:
+                      vee-validate reads only the schema),
+                      \`row-without-name\` (a form control in a \`v-for\`
+                      inside a \`BbForm\` with a bound label and no \`name\`),
+                      \`retired-entrypoint\` (an import from
+                      \`bitboss-ui/validated\`, retired: everything is in
+                      \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
+                      \`unregistered-rule\` (a string rule no
+                      \`defineRule\` in the project registers; silent when
+                      the project registers rules in a loop),
+                      \`wrapper-drops-props\` (a wrapper whose
+                      \`defineProps\` declares a \`Bb*Props\` type, bare,
+                      \`Omit\` or \`Pick\`, and never binds or reads some
+                      of those props: a caller's value is dropped),
+                      \`renamed-slot\` (a slot the library renamed;
+                      \`--fix\` rewrites it), \`missing-partner-prop\`,
+                      \`partner-prop\`,
+                      \`validated-only-prop\`, \`object-items-without-text\`
+                      (object \`items\` with no \`item-text\`; reads only
+                      an inline array, or a \`const\` array, \`ref([…])\` or
+                      \`reactive([…])\` in the same file's
+                      \`<script setup>\`), \`reserved-key\` (a key
+                      whose slot name is one of the component's own slots,
+                      e.g. a BbTable column keyed \`actions\`; read from the
+                      manifest, same-file keys only), \`hand-imported-styles\`
+                      (\`bitboss-ui/styles.css\` imported in CSS, a script or
+                      Nuxt's \`css\` while \`injectStyles\` is on: delete it;
+                      read only when vite.config / nuxt.config says so),
+                      \`unknown-class\` (a selector on a \`.bb-*\` class the
+                      library does not render, in a stylesheet or a
+                      \`<style>\` block; \`suggestion\` is the nearest real
+                      one), \`renamed-class\` (a class the library renamed;
+                      \`to\` is its successor). Your own classes are never
+                      read, nor a \`bb-*\` class the same file adds itself
+                      (\`class\`, \`:class\`, \`pt:*\`), \`inert-token\` (a
+                      \`--bb-*\` SET that the library neither declares nor
+                      reads; \`suggestion\` = the nearest token),
+                      \`inert-local\` (a local set on a \`.bb-*\` block whose
+                      component, and what it mounts, never reads it; \`to\`
+                      when it was renamed). A local on your own ancestor
+                      element, or one your CSS reads, is never judged.
+                      \`warnings[]\` (never fail the run) use the same shape with
+                      \`severity: "warning"\`: \`likely-squashed-slot\` (a slot
+                      name that looks like a camelCase key squashed, e.g.
+                      \`#createdat\`), \`local-bb-component\` (your own
+                      component uses the \`Bb\` prefix; rename it).
+  changelog [--since <version>] [--until <version>] [--json]
+                      Breaking changes between two releases — "what breaks if I
+                      bump". \`--since\` is the version you are ON, and is
+                      exclusive. With no range, every break in the v2 → v3
+                      upgrade. Only BREAKING changes are tracked, so an empty
+                      result means nothing breaks, not that nothing changed.
+                        npx bitboss-ui changelog --since 3.0.0-beta.20
+                      Pair it with \`check --manifest\` to turn the list into the
+                      files in YOUR app that break.
+
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
-                      base (search_components, get_component, list_recipes,
-                      get_recipe, validate) to MCP-capable agent harnesses.
+                      base (search_docs, search_components, get_component,
+                      get_composable, list_tokens, list_guides, get_guide,
+                      list_changes, list_recipes, get_recipe, validate) to
+                      MCP-capable agent harnesses.
   help                Show this help.
 `);
 }
@@ -763,9 +1363,11 @@ switch (command) {
 	case 'ai-init': {
 		const { values } = parseCommandArgs(command, commandArgs, {
 			update: { type: 'boolean' },
-			mcp: { type: 'boolean' },
+			// The MCP server is registered by default: people ran ai-init, got
+			// the pointers, and never learned the server existed.
+			'no-mcp': { type: 'boolean' },
 		});
-		aiInit({ mcp: values.mcp ?? false });
+		aiInit({ mcp: !values['no-mcp'] });
 		break;
 	}
 	case 'check': {
@@ -776,16 +1378,33 @@ switch (command) {
 				json: { type: 'boolean' },
 				'allow-empty': { type: 'boolean' },
 				'allow-component': { type: 'string', multiple: true },
+				fix: { type: 'boolean' },
+				manifest: { type: 'string' },
 				// Accepted and ignored here — read straight off argv inside
 				// checkCommand, but parseArgs is strict, so it must be declared.
 				'no-hints': { type: 'boolean' },
 			},
 			{ allowPositionals: true }
 		);
-		checkCommand(positionals, {
+		await checkCommand(positionals, {
+			fix: values.fix ?? false,
 			json: values.json ?? false,
 			allowEmpty: values['allow-empty'] ?? false,
 			allowComponents: values['allow-component'] ?? [],
+			manifest: values.manifest,
+		});
+		break;
+	}
+	case 'changelog': {
+		const { values } = parseCommandArgs(command, commandArgs, {
+			since: { type: 'string' },
+			until: { type: 'string' },
+			json: { type: 'boolean' },
+		});
+		changelogCommand({
+			since: values.since,
+			until: values.until,
+			json: values.json ?? false,
 		});
 		break;
 	}
@@ -802,9 +1421,34 @@ switch (command) {
 			({ main } = await import('./bitboss-ui-mcp.mjs'));
 		} catch (error) {
 			if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+			// Running from an npx cache is a DIFFERENT failure wearing the same
+			// error: the peers resolve relative to the package we were launched
+			// from, so a cached copy can never see the project's node_modules no
+			// matter what is installed there. Telling that user to install peers
+			// they already have is what sent a consumer down a dead end
+			// (2026-09-09). `ai-init` now writes the local binary instead
+			// of `npx`, so the fix is to rewrite the config.
+			const fromNpxCache = /[/\\]_npx[/\\]/.test(
+				fileURLToPath(import.meta.url)
+			);
+			const projectHasPeers = missingMcpPeers(process.cwd()).length === 0;
+			if (fromNpxCache && projectHasPeers) {
+				console.error(
+					'bitboss-ui mcp was launched through `npx`, which runs it from the npx cache —\n' +
+						'its optional peers resolve there, not in your project, so the server cannot start\n' +
+						`even though this project has them installed (${MCP_PEERS.join(', ')}).\n\n` +
+						'Fix the harness config to invoke the installed binary:\n\n' +
+						'  npx bitboss-ui ai-init\n\n' +
+						`which writes \`node ${MCP_BIN_PATH} mcp\`. To run it right now:\n\n` +
+						`  node ${MCP_BIN_PATH} mcp\n\n` +
+						`Resolution failed with: ${error.message}`
+				);
+				process.exitCode = 1;
+				break;
+			}
 			console.error(
 				'bitboss-ui mcp needs two optional peer dependencies that are not installed:\n' +
-					'\n  npm i -D @modelcontextprotocol/sdk zod\n\n' +
+					`\n  npm i -D ${MCP_PEERS.join(' ')}\n\n` +
 					'They are optional because they are ~12 MB and only this subcommand uses them.\n' +
 					`Resolution failed with: ${error.message}`
 			);