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

package/README.md

@@ -327,13 +327,13 @@ part you need.
 
 ### CLI commands
 
-| Command                                                                   | What it does                                                                                                             |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                               |
-| `npx bitboss-ui check [paths…] [--fix] [--json]`                          | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first. |
-| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.           |
-| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                            |
-| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                  |
+| Command                                                                   | What it does                                                                                                                                                                                          |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                                                                                                            |
+| `npx bitboss-ui check [paths… \| --changed] [--fix] [--json]`             | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first; `--changed` checks only the files git sees changed vs HEAD (plus untracked). |
+| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.                                                                                        |
+| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                                                                                                         |
+| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                                                                                               |
 
 ### ESLint plugin
 
@@ -482,6 +482,9 @@ still name the button:
 ```
 
 `BbSpinner` is not covered: without `label` it is decorative, which is correct.
+A `BbBadge` or `BbProgress` marked `aria-hidden="true"` (or `:aria-hidden="true"`)
+is decorative too and is skipped (a `BbButton` is not: it stays focusable); a dynamic `:aria-hidden="flag"` is still checked, since it
+needs a name whenever it is `false`.
 For raw HTML controls, use `eslint-plugin-vuejs-accessibility`.
 
 #### v-model on a const reactive(): `no-reactive-v-model`

package/bin/bitboss-ui-mcp.mjs

@@ -891,6 +891,96 @@ function historyLines(entry) {
 	];
 }
 
+/**
+ * Q57.6: the `css.classes` of the internal parts a component mounts
+ * (`CommonPopover`, `CommonField`, the listboxes), by part. The class surface
+ * lists a block once, on its owner, and an internal owner is no component a
+ * consumer asks about: `.bb-common-popover__bubble` was on no BbDropdown or
+ * BbPopover answer. A public child (BbBaseButton) answers for its own.
+ */
+function internalClasses(entry, manifest) {
+	const byName = new Map(manifest.components.map((c) => [c.name, c]));
+	const out = {};
+	const walk = (nodes = []) => {
+		for (const node of nodes) {
+			if (node.kind !== 'internal') continue;
+			const classes = byName.get(node.name)?.css?.classes;
+			if (classes && !out[node.name]) out[node.name] = classes;
+			walk(node.children);
+		}
+	};
+	walk(entry.tree?.nodes);
+	return out;
+}
+
+/** `css` of a get_component answer: its own classes, plus `shared` (Q57.6). */
+function cssAnswer(entry, manifest) {
+	const shared = internalClasses(entry, manifest);
+	return Object.keys(shared).length ? { ...entry.css, shared } : entry.css;
+}
+
+/** Every `.bb-*` block a component renders, its own and its internal parts'. */
+function renderedBlocks(entry, manifest) {
+	return new Set([
+		...Object.keys(entry.css?.classes ?? {}),
+		...Object.values(internalClasses(entry, manifest)).flatMap(Object.keys),
+	]);
+}
+
+/**
+ * Q57.7: does a changelog row reach this component? By name, or — for a CSS
+ * rename (`surface: cssVar | class`), whose Component cell is a selector
+ * (`.bb-table`) or prose ("every form control") — by a `.bb-*` block of the
+ * row the component renders: `--padding-y → --py` on `.bb-table` never
+ * reached BbTable's history or `list_changes({ component: 'BbTable' })`.
+ */
+function rowReaches(row, name, blocks) {
+	if (
+		(row.components ?? []).some((c) => c.toLowerCase() === name.toLowerCase())
+	)
+		return true;
+	if (!blocks || (row.surface !== 'cssVar' && row.surface !== 'class'))
+		return false;
+	const text = [...(row.components ?? []), row.from, row.to].join(' ');
+	return [...text.matchAll(/\.(bb-[a-z0-9]+(?:-[a-z0-9]+)*)/g)].some((m) =>
+		blocks.has(m[1])
+	);
+}
+
+/** The CSS renames (cssVar, class) that reach a component, one line each. */
+function cssRenameLines(entry, manifest) {
+	if (!existsSync(CHANGELOG_PATH)) return [];
+	const doc = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+	const blocks = renderedBlocks(entry, manifest);
+	return (doc.breaking ?? [])
+		.filter(
+			(row) =>
+				(row.surface === 'cssVar' || row.surface === 'class') &&
+				rowReaches(row, entry.name, blocks)
+		)
+		.map(
+			(row) =>
+				`${/^f\d/.test(row.id) ? `${row.id} ` : ''}${row.surface} ${row.from} → ${row.to ?? 'removed'}${row.firstReleasedIn ? ` (${row.firstReleasedIn})` : ''}`
+		);
+}
+
+/**
+ * The history lines, plus the CSS locals renamed on the component's blocks;
+ * the class renames only as a count (include: ['history'] lists them).
+ */
+function historyWithCss(entry, manifest) {
+	const css = cssRenameLines(entry, manifest);
+	const vars = css.filter((line) => / cssVar |^cssVar /.test(line));
+	const classes = css.length - vars.length;
+	return [
+		...historyLines(entry),
+		...vars,
+		...(classes
+			? [`${classes} .bb-* class rename(s) on its blocks: include: ['history']`]
+			: []),
+	];
+}
+
 /** The compact `component` of the summary answer. */
 function summarizeComponent(entry, manifest) {
 	const shared = sharedProps(manifest);
@@ -932,9 +1022,10 @@ function summarizeComponent(entry, manifest) {
 		...(entry.cssProps?.length
 			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
 			: {}),
-		...(entry.removed?.length || entry.renamed?.length
-			? { history: historyLines(entry) }
-			: {}),
+		...(() => {
+			const history = historyWithCss(entry, manifest);
+			return history.length ? { history } : {};
+		})(),
 		...(entry.attrTargets ? { attrTargets: entry.attrTargets } : {}),
 		...(entry.referenceOnly ? { referenceOnly: true } : {}),
 	};
@@ -1233,7 +1324,9 @@ function getComponent({
 			...(wanted.has('cssProps') && entry.cssProps
 				? { cssProps: entry.cssProps }
 				: {}),
-			...(wanted.has('css') && entry.css ? { css: entry.css } : {}),
+			...(wanted.has('css') && entry.css
+				? { css: cssAnswer(entry, manifest) }
+				: {}),
 			...(wanted.has('ptProps')
 				? (() => {
 						const { kept, ...rest } = capParts(ptRows, 'PtProps');
@@ -1241,7 +1334,11 @@ function getComponent({
 					})()
 				: {}),
 			...(wanted.has('history')
-				? { removed: entry.removed ?? [], renamed: entry.renamed ?? [] }
+				? {
+						removed: entry.removed ?? [],
+						renamed: entry.renamed ?? [],
+						cssRenames: cssRenameLines(entry, manifest),
+					}
 				: {}),
 			...(wanted.has('contract')
 				? (() => {
@@ -1308,15 +1405,19 @@ function getComponent({
 		...(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 } : {}),
+		...(wanted.has('css') && entry.css
+			? { css: cssAnswer(entry, manifest) }
+			: {}),
 	};
 	// `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')) {
 		if (entry.renamed) component.renamed = entry.renamed;
-	} else if (entry.removed?.length || entry.renamed?.length) {
-		component.history = historyLines(entry);
+		component.cssRenames = cssRenameLines(entry, manifest);
+	} else {
+		const history = historyWithCss(entry, manifest);
+		if (history.length) component.history = history;
 		delete component.removed;
 	}
 
@@ -1373,7 +1474,7 @@ function getComponent({
 						: {}),
 				}
 			: {}),
-		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.`,
+		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 (css.shared: the ones its internal parts render), every pt:* row, the full v2/beta rename records (cssRenames: the CSS local and class renames on its blocks), or the whole contract. search_docs finds a topic across all docs.`,
 	};
 }
 
@@ -1590,7 +1691,7 @@ function listTokens({ filter } = {}) {
 			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. ${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.',
+					' 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: theme-wide, set the knob it came from (a derived value you set stops tracking it); a scoped override (one `.bb-table`) is fine, but stops at a nested .dark / .bb-theme; "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.',
 	};
 }
 
@@ -2557,6 +2658,7 @@ function listChanges({
 	// 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".
+	let blocks = null;
 	if (component) {
 		const resolved = resolveComponent(loadComponentsManifest(), component);
 		// A retired name (BbTabsPanes) is still a key in the rows it renamed.
@@ -2568,15 +2670,17 @@ function listChanges({
 				didYouMean: nearestComponents(loadComponentsManifest(), component),
 			};
 		}
-		if (resolved?.entry) component = resolved.entry.name;
+		if (resolved?.entry) {
+			component = resolved.entry.name;
+			// Q57.7: a CSS rename reaches it through the blocks it renders.
+			blocks = renderedBlocks(resolved.entry, loadComponentsManifest());
+		}
 	}
+
 	const rows = detail === 'rows';
 	const filtered = (doc.breaking ?? []).filter(
 		(row) =>
-			(!component ||
-				(row.components ?? []).some(
-					(c) => c.toLowerCase() === String(component).toLowerCase()
-				)) &&
+			(!component || rowReaches(row, String(component), blocks)) &&
 			(!surface ||
 				(row.surface ?? (row.kind === 'rename' ? 'prop' : null)) === surface) &&
 			(!kind || row.kind === kind)

package/bin/bitboss-ui.mjs

@@ -11,6 +11,8 @@
  *             - .github/copilot-instructions.md fragment (GitHub Copilot)
  *             - .claude/skills/bitboss-ui/SKILL.md (Claude Code)
  *             - .windsurf/rules/bitboss-ui.md (Windsurf)
+ *             - `vueCompilerOptions.checkUnknownComponents: true` in the
+ *               tsconfig (Q60.6), unless the project already names it
  *             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
@@ -85,6 +87,11 @@ import {
 	handImportedStylesFindings,
 } from '../scripts/lib/hand-imported-styles.mjs';
 import { syncProjectVariantDts } from '../scripts/lib/project-variant-dts.mjs';
+import { refuseLinkedTarget } from '../scripts/lib/linked-target.mjs';
+import {
+	ensureCheckUnknownComponents,
+	toolchainWarnings,
+} from '../scripts/lib/toolchain-check.mjs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -99,6 +106,7 @@ import {
 import {
 	loadManifest,
 	registeredRuleNames,
+	presetDefinitions,
 	validateMarkdown,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
@@ -141,7 +149,7 @@ function coreRules(version) {
 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.
+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. In an edit loop, \`npx bitboss-ui check --changed\` checks only the files git sees changed; run the full check before you finish.
 
 After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
 }
@@ -204,6 +212,7 @@ ${coreRules(version)}
 }
 
 function upsertMarkedFile(filePath, fragment, { createHeader } = {}) {
+	refuseLinkedTarget(filePath);
 	const existed = existsSync(filePath);
 
 	if (!existed) {
@@ -231,6 +240,7 @@ function upsertMarkedFile(filePath, fragment, { createHeader } = {}) {
 }
 
 function writeWholeFile(filePath, content) {
+	refuseLinkedTarget(filePath);
 	const existed = existsSync(filePath);
 	mkdirSync(dirname(filePath), { recursive: true });
 	writeFileSync(filePath, content, 'utf-8');
@@ -294,6 +304,15 @@ function aiInit({ mcp = true } = {}) {
 			)
 		),
 	];
+	// Q60.6: unknown-component checking is opt-in in Vue Language Tools 3.
+	const flag = tryWrite('tsconfig checkUnknownComponents', () =>
+		ensureCheckUnknownComponents(projectRoot)
+	);
+	if (flag)
+		results.push({
+			...flag,
+			path: flag.reason ? `${flag.path} (${flag.reason})` : flag.path,
+		});
 
 	if (mcp) {
 		for (const result of ensureMcpConfigs(projectRoot)) {
@@ -352,6 +371,10 @@ function aiInit({ mcp = true } = {}) {
 			'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.'
 		);
 	}
+	// Q61.7: Laravel's vue-starter-kit (and others) git-ignore these.
+	console.log(
+		"Some starters (Laravel's vue-starter-kit) git-ignore AGENTS.md, CLAUDE.md, .claude, .cursor and .mcp.json: teammates won't see these files until you un-ignore them."
+	);
 	console.log('Re-run after upgrading bitboss-ui to refresh the pointers.');
 	console.log(
 		'Tip: `npx bitboss-ui ai-init --update` is the same command (idempotent).'
@@ -500,6 +523,45 @@ function resolveCheckFiles(cwd, patterns) {
 	return [...matched].sort();
 }
 
+/**
+ * `check --changed` (Q57.11): the files git reports changed against HEAD
+ * (staged or not) plus the untracked ones, under `cwd`, minus the sweep's skip
+ * list. `files` are the .vue/.md ones `check` validates; `all` (any extension)
+ * feeds the stylesheet and styles-import scans, which read other files too.
+ * @returns {{ files: string[], all: string[] } | { error: string }}
+ */
+function changedCheckFiles(cwd) {
+	const git = (args) =>
+		spawnSync('git', args, {
+			cwd,
+			encoding: 'utf-8',
+			maxBuffer: 64 * 1024 * 1024,
+		});
+	const diff = git(['diff', '--name-only', '--relative', '-z', 'HEAD', '--']);
+	const untracked = git(['ls-files', '--others', '--exclude-standard', '-z']);
+	const failed = [diff, untracked].find((r) => r.error || r.status !== 0);
+	if (failed)
+		return {
+			error:
+				'check --changed: git could not list the changed files here (not a git repository, git missing, or no commit yet): ' +
+				(failed.error?.message ?? failed.stderr.trim().split('\n')[0]),
+		};
+	const all = [
+		...new Set(`${diff.stdout}${untracked.stdout}`.split('\0').filter(Boolean)),
+	]
+		.filter((rel) => !inSkippedDir(rel))
+		.map((rel) => join(cwd, rel))
+		// A deleted file is a change with nothing left to check.
+		.filter((path) => existsSync(path) && statSync(path).isFile())
+		.sort();
+	return {
+		files: all.filter((path) =>
+			CHECK_EXTENSIONS.some((ext) => path.endsWith(ext))
+		),
+		all,
+	};
+}
+
 /**
  * `4 .vue + 8 .md` — a plain file count on its own ("715 file(s)") reads as
  * "715 files carefully checked" when SNT-007 showed it can just as easily be
@@ -774,9 +836,19 @@ async function checkCommand(
 		allowComponents,
 		manifest: manifestOverride,
 		fix,
+		changed: changedOnly,
 	}
 ) {
 	const projectRoot = process.cwd();
+	if (changedOnly && globs.length) {
+		console.error('[bitboss-ui] check: pass paths or `--changed`, not both.');
+		process.exit(1);
+	}
+	const changed = changedOnly ? changedCheckFiles(projectRoot) : null;
+	if (changed && 'error' in changed) {
+		console.error(`[bitboss-ui] ${changed.error}`);
+		process.exit(1);
+	}
 
 	/*
 	 * `--manifest` answers the question `check` could not: "which of my files
@@ -847,7 +919,7 @@ async function checkCommand(
 		? join(dirname(dirname(manifestPath)), 'styles.css')
 		: join(PACKAGE_ROOT, 'dist', 'styles.css');
 	const knownTokens = loadKnownTokens(stylesPath);
-	const files = resolveCheckFiles(projectRoot, globs);
+	const files = changed ? changed.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
@@ -894,15 +966,22 @@ async function checkCommand(
 	// 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(
+	// Q57.11: one walk and one read per file serve every project-wide sweep
+	// below (reads, registered rules, the style scan) and the per-file loop.
+	const projectSources = collectCheckFiles(
 		projectRoot,
 		projectRoot,
 		HAND_IMPORTED_STYLES_EXTENSIONS
-	))
+	);
+	const texts = new Map();
+	const readText = (path) => {
+		if (!texts.has(path)) texts.set(path, readFileSync(path, 'utf-8'));
+		return texts.get(path);
+	};
+	const projectReads = new Set();
+	for (const path of projectSources)
 		try {
-			for (const name of localReads(readFileSync(path, 'utf-8')))
-				projectReads.add(name);
+			for (const name of localReads(readText(path))) projectReads.add(name);
 		} catch {
 			/* unreadable: its reads are unknown, which only means fewer passes */
 		}
@@ -918,15 +997,17 @@ async function checkCommand(
 	// 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',
-	]))
+	const presets = new Map();
+	const RULE_EXTENSIONS = ['.ts', '.js', '.mjs', '.cjs', '.vue'];
+	for (const path of projectSources.filter((file) =>
+		RULE_EXTENSIONS.some((ext) => file.endsWith(ext))
+	))
 		try {
-			const found = registeredRuleNames(readFileSync(path, 'utf-8'));
+			const text = readText(path);
+			// Q57.3: the project's `definePreset` wrappers, by name.
+			for (const [name, preset] of presetDefinitions(text))
+				presets.set(name, preset);
+			const found = registeredRuleNames(text);
 			for (const name of found.names) registeredRules.names.add(name);
 			if (found.dynamic) registeredRules.dynamic = true;
 		} catch {
@@ -937,6 +1018,7 @@ async function checkCommand(
 		allowComponents: allowedComponents,
 		projectReads,
 		registeredRules,
+		presets,
 	};
 
 	const findings = [];
@@ -959,7 +1041,7 @@ async function checkCommand(
 	const wantHints = !process.argv.includes('--no-hints');
 	for (const file of files) {
 		const relPath = relative(projectRoot, file);
-		const content = readFileSync(file, 'utf-8');
+		const content = readText(file);
 		const { findings: fileFindings } = file.endsWith('.md')
 			? validateMarkdown(content, manifest, validateOptions)
 			: validateVueSnippet(content, manifest, validateOptions);
@@ -994,21 +1076,24 @@ async function checkCommand(
 	}
 
 	for (const [name, file] of projectLocal) warnLocal(name, file);
+	// Q60.6: a `vue-tsc` below 3 and a missing `checkUnknownComponents`, read
+	// from package.json and the tsconfig. One line each, never fatal.
+	warnings.push(...toolchainWarnings(projectRoot));
 
 	// 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
-			);
+	// `--changed`: every changed file, stylesheets and scripts included.
+	const styleScan = changed
+		? changed.all
+		: globs.length
+			? files
+			: projectSources;
 	findings.push(
 		...handImportedStylesFindings(
 			projectRoot,
-			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) }))
+			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) })),
+			readText
 		)
 	);
 	// Q46.5: `.bb-*` selectors in the app's stylesheets (the `.vue` `<style>`
@@ -1016,7 +1101,7 @@ async function checkCommand(
 	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');
+		const content = readText(path);
 		for (const finding of [
 			...cssClassFindings(content, manifest.cssSurface, { stylesheet: true }),
 			// Q46.6: custom properties set where nothing reads them.
@@ -1074,6 +1159,14 @@ async function checkCommand(
 	const judgedAgainst = manifestOverride
 		? manifestVersionOf(manifestPath)
 		: packageVersion();
+	if (changed && !jsonMode) {
+		console.log(
+			`[bitboss-ui] check --changed: ${files.length} .vue/.md file(s) changed vs HEAD (untracked included).\n` +
+				'            Unchanged files are not validated, and the styles-import scan reads only the\n' +
+				'            changed files; the project-wide context (var() reads, defineRule names, local\n' +
+				'            Bb* components) still comes from the whole project. Run a full `check` before merging.'
+		);
+	}
 	if (manifestOverride && !jsonMode) {
 		console.log(
 			`[bitboss-ui] check: judging against bitboss-ui ${judgedAgainst} (--manifest), NOT the installed ${packageVersion()}.\n` +
@@ -1090,6 +1183,7 @@ async function checkCommand(
 					hints,
 					suppressed,
 					files: files.length,
+					...(changed ? { changed: true } : {}),
 					manifestVersion: judgedAgainst,
 					installedVersion: packageVersion(),
 				},
@@ -1109,6 +1203,12 @@ async function checkCommand(
 		// markup is itself the thing that broke, silently (SWP-016). A bare
 		// sweep finding nothing is a different, legitimate case (a package with
 		// no .vue files yet), so it still passes.
+		if (changed) {
+			console.log(
+				'[bitboss-ui] check --changed: no changed .vue/.md files — nothing to validate.'
+			);
+			return;
+		}
 		if (globs.length > 0 && !allowEmpty) {
 			console.error(
 				`[bitboss-ui] check: no .vue/.md files matched ${globs.map((g) => `\`${g}\``).join(', ')} — nothing was validated. ` +
@@ -1184,10 +1284,12 @@ Commands:
                       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.
+                      optional peers with the project's package manager. Sets
+                      \`vueCompilerOptions.checkUnknownComponents: true\` in the
+                      tsconfig unless it is already named (Nuxt: says where).
                       \`--no-mcp\` skips the server and the install. Idempotent —
                       safe to re-run after upgrades.
-  check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
+  check [glob…] [--changed] [--json] [--allow-empty] [--allow-component <Name>]
                       [--no-hints] [--manifest <path>] [--fix]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
@@ -1201,6 +1303,16 @@ Commands:
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
 
+                      \`--changed\` validates only the .vue/.md files git reports
+                      changed against HEAD (staged or not) plus untracked ones —
+                      the fast loop after an edit. Unchanged files are not
+                      validated and the styles-import scan reads only the
+                      changed files; what a finding depends on elsewhere (the
+                      project's var() reads, defineRule names, local Bb*
+                      components) is still read from the whole project. Nothing
+                      changed → exit 0. Not with paths. Run a full \`check\`
+                      before merging.
+
                       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
@@ -1241,7 +1353,8 @@ Commands:
                       so both gates configure alike.
 
                       \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
-                      suppressed, files, manifestVersion, installedVersion }\`.
+                      suppressed, files, manifestVersion, installedVersion }\`
+                      (plus \`changed: true\` under \`--changed\`).
                       Each finding: \`{ file, line, component, attr, kind,
                       message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
                       inside a markdown fence; \`line\` is absolute in the file).
@@ -1281,11 +1394,18 @@ Commands:
                       \`form-v-model\` (\`v-model\`, \`:model-value\` or an
                       \`@update:model-value\` listener on a \`BbForm\`: it
                       takes its object one way, \`:model="draft"\`),
+                      \`positional-provider\` (an \`items\` provider with
+                      positional arguments: it receives one object,
+                      \`({ query, reason, modelValue, signal })\`),
                       \`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\`),
+                      \`field-without-name\` (a field with its own
+                      \`v-model\` and no \`name\` in a \`BbForm\` with
+                      \`field-errors\`: its errors never reach it; your
+                      \`definePreset\` wrappers count as their Bb* control),
                       \`retired-entrypoint\` (an import from
                       \`bitboss-ui/validated\`, retired: everything is in
                       \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
@@ -1322,15 +1442,24 @@ Commands:
                       (\`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
+                      \`inert-local\` (a local set on a \`.bb-*\` block, nested
+                      rules included, or on a Bb* tag's \`style\` / \`:style\` /
+                      \`[--x:…]\` class, 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).
+                      component uses the \`Bb\` prefix; rename it),
+                      \`single-reason\` (an \`items\` provider that tests
+                      \`reason\` against one cause other than \`'search'\`;
+                      check \`reason !== 'search'\`), \`vue-tsc-major\`
+                      (\`vue-tsc\` below 3 in package.json: the generic
+                      components' props go unchecked),
+                      \`check-unknown-components\` (no
+                      \`vueCompilerOptions.checkUnknownComponents: true\` in
+                      the tsconfig; \`ai-init\` writes 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
@@ -1393,6 +1522,7 @@ switch (command) {
 				'allow-component': { type: 'string', multiple: true },
 				fix: { type: 'boolean' },
 				manifest: { type: 'string' },
+				changed: { type: 'boolean' },
 				// Accepted and ignored here — read straight off argv inside
 				// checkCommand, but parseArgs is strict, so it must be declared.
 				'no-hints': { type: 'boolean' },
@@ -1405,6 +1535,7 @@ switch (command) {
 			allowEmpty: values['allow-empty'] ?? false,
 			allowComponents: values['allow-component'] ?? [],
 			manifest: values.manifest,
+			changed: values.changed ?? false,
 		});
 		break;
 	}