bitboss-ui 3.0.0-alpha.1 → 3.0.0-alpha.4

package/README.md

@@ -70,7 +70,7 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 The same knowledge base the npm package ships is served publicly over a CDN, so
 an agent can read it before anything is installed. `@alpha` tracks the latest
-v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.1`) for stable
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.4`) for stable
 links.
 
 - [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~74 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
@@ -94,18 +94,25 @@ This package is developed and maintained by [BitBoss](https://www.bitboss.it/),
 
 ## Installation
 
+**v3 is a prerelease: the `@alpha` tag is required.** A bare
+`npm install bitboss-ui` resolves to the v2 line, which has no build plugin and
+no `dist/ai` knowledge base — if you are following the v3 docs, that install
+will not work.
+
 ```bash
-npm install bitboss-ui
+npm install bitboss-ui@alpha
 ```
 
 ```bash
-pnpm add bitboss-ui
+pnpm add bitboss-ui@alpha
 ```
 
 ```bash
-yarn add bitboss-ui
+yarn add bitboss-ui@alpha
 ```
 
+Verify with `npm ls bitboss-ui` — it must report `3.0.0-alpha.*`.
+
 ---
 
 ## Quick start
@@ -236,13 +243,33 @@ manifest checks as `bitboss-ui check`, so editor, CLI, and CI agree. It reuses
 your existing `vue-eslint-parser` setup (from `eslint-plugin-vue`) and no-ops on
 non-Vue files.
 
+**Needs the TypeScript parser wired for `.ts` and `.vue`.** This library is
+TS-first — recipes ship `<script setup lang="ts">`, some with `generic="T"` —
+and without the two blocks below, `vue-eslint-parser` throws a `Parsing error`
+on those files. A parsing error means **no rule runs on that file at all**,
+`no-unknown-attributes` included, so the safety net silently goes dark on
+exactly the files it matters most for.
+
+```bash
+npm i -D @typescript-eslint/parser
+```
+
 ```js
 // eslint.config.js (flat config)
 import vue from 'eslint-plugin-vue';
+import tsParser from '@typescript-eslint/parser';
 import bitbossUi from 'bitboss-ui/eslint-plugin';
 
 export default [
 	...vue.configs['flat/recommended'],
+	{
+		files: ['**/*.ts'],
+		languageOptions: { parser: tsParser },
+	},
+	{
+		files: ['**/*.vue'],
+		languageOptions: { parserOptions: { parser: tsParser } },
+	},
 	...bitbossUi.configs.recommended, // enables no-unknown-attributes on **/*.vue
 ];
 ```

package/bin/bitboss-ui-mcp.mjs

@@ -81,7 +81,8 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 	const needle = String(query ?? '')
 		.toLowerCase()
 		.trim();
-	const max = Number.isFinite(limit) && limit > 0 ? limit : SEARCH_DEFAULT_LIMIT;
+	const max =
+		Number.isFinite(limit) && limit > 0 ? limit : SEARCH_DEFAULT_LIMIT;
 
 	// Consumer-first: reference-only internals are excluded unless explicitly
 	// requested — recommending them is an agent-contract violation.
@@ -198,13 +199,83 @@ function getComponent({ name, maxChars } = {}) {
 /** Shipped stylesheet that carries every resolved `--bb-*` theme token. */
 const STYLES_CSS = join(PACKAGE_ROOT, 'dist', 'styles.css');
 
+/**
+ * Selectors that carry a THEME value rather than a component-local rebind:
+ * the root scopes a consumer themes on. A selector list qualifies only when
+ * every comma-part is built solely from these — `:root`, `.light`, `:root.dark`
+ * and `html.dark` are theme roots; `.bb-tooltip .bb-common-popover__bubble` is
+ * not, however many `--bb-*` it redeclares.
+ */
+const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+function isThemeSelector(selector) {
+	return selector
+		.split(',')
+		.every((part) =>
+			THEME_ROOT_PART.test(part.replace(/[\s>+~]+/g, '').trim())
+		);
+}
+
+/**
+ * Walk a stylesheet and yield every `--bb-*` declaration WITH the selector that
+ * owns it. A flat regex cannot do this: it sees a declaration but not its
+ * scope, so a component that locally rebinds a theme token is indistinguishable
+ * from the dark theme redefining it. Brace-depth scanning (quote-aware, and
+ * tolerant of the missing final semicolon that minified CSS emits) is the
+ * cheapest way to keep the scope — and this file ships in the package, so it
+ * may not reach for postcss the way the dev-only `check:tokens` script does.
+ */
+function* eachTokenDeclaration(css) {
+	const stack = [];
+	let buffer = '';
+	let quote = null;
+	const declaration = () => {
+		const m = buffer.match(/(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
+		buffer = '';
+		return m ? { name: m[1], value: m[2].trim() } : null;
+	};
+	for (const char of css) {
+		if (quote) {
+			buffer += char;
+			if (char === quote) quote = null;
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			buffer += char;
+		} else if (char === '{') {
+			stack.push(buffer.trim());
+			buffer = '';
+		} else if (char === '}' || char === ';') {
+			const decl = declaration();
+			if (decl) yield { ...decl, selector: stack[stack.length - 1] ?? '' };
+			if (char === '}') stack.pop();
+		} else {
+			buffer += char;
+		}
+	}
+}
+
 /**
  * `list_tokens({ filter })` — the `--bb-*` design tokens with their values,
- * read from the shipped stylesheet (the same set `check:tokens` counts).
+ * read from the shipped stylesheet (the same 89 `check:tokens` counts).
+ *
+ * WHY ONLY `--bb-*` — and why there is no opt-in for the unprefixed ones, even
+ * though `search_components` has `includeReferenceOnly`. The two tiers are not
+ * the same kind of thing. `--bb-*` is a flat, global, consumer-settable
+ * contract. Unprefixed component tokens are *sealed to the file that consumes
+ * them* (`check:tokens` rule 3), so the same name means different things in
+ * different components and is only meaningful inside that component's scope.
+ * Serving them as one flat list would invite exactly the wrong move — an agent
+ * writing `:root { --gap: … }` and wondering why nothing changed. They are
+ * documented per component, which `get_component` already serves.
+ *
+ * WHY `dist/styles.css` AND NOT `src/assets/css/variables.css`: `src/` is not
+ * in the published package, so the source file does not exist for the consumer
+ * this server runs inside. The shipped sheet also carries *resolved* values.
  *
- * A token declared more than once is a theme override: the first value is the
- * light/base one, later values are dark-theme overrides, so both are reported
- * rather than one silently winning.
+ * There is no `limit`/`maxChars` here by design: the whole set is ~9 KB, and a
+ * half-list of tokens is the same failure as a half-list of props — it makes an
+ * agent invent the missing ones.
  */
 function listTokens({ filter } = {}) {
 	if (!existsSync(STYLES_CSS)) {
@@ -216,12 +287,18 @@ function listTokens({ filter } = {}) {
 	}
 	const css = readFileSync(STYLES_CSS, 'utf-8');
 	const byName = new Map();
-	for (const m of css.matchAll(/(--bb-[a-z0-9-]+)\s*:\s*([^;}]+)/gi)) {
-		const name = m[1];
-		const value = m[2].trim();
-		const values = byName.get(name) ?? [];
-		if (!values.includes(value)) values.push(value);
-		byName.set(name, values);
+	for (const { name, value, selector } of eachTokenDeclaration(css)) {
+		const entry = byName.get(name) ?? { theme: [], local: [] };
+		if (isThemeSelector(selector)) {
+			// Light first, dark after: report both rather than let one win.
+			if (!entry.theme.includes(value)) entry.theme.push(value);
+		} else if (!entry.local.some((r) => r.selector === selector)) {
+			// A component rebinding a theme token for its own subtree. Reporting
+			// this as a `themeOverride` is a lie an agent acts on — it reads
+			// `--bb-arrow: 0` as "the dark theme hides arrows".
+			entry.local.push({ selector, value });
+		}
+		byName.set(name, entry);
 	}
 	const needle = String(filter ?? '')
 		.toLowerCase()
@@ -229,16 +306,20 @@ function listTokens({ filter } = {}) {
 	const tokens = [...byName.entries()]
 		.filter(([name]) => !needle || name.toLowerCase().includes(needle))
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, values]) => ({
+		.map(([name, { theme, local }]) => ({
 			name,
-			value: values[0],
-			...(values.length > 1 ? { themeOverrides: values.slice(1) } : {}),
+			value: theme[0],
+			...(theme.length > 1 ? { themeOverrides: theme.slice(1) } : {}),
+			...(local.length > 0 ? { localRebinds: local } : {}),
 		}));
 	return {
 		count: tokens.length,
 		...(needle ? { filter: needle } : { total: byName.size }),
 		tokens,
-		hint: 'Theme tokens are set by the consumer app (e.g. on :root / .dark). Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
+		hint:
+			needle && tokens.length === 0
+				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours.`
+				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
 	};
 }
 
@@ -248,7 +329,8 @@ function collectGuidePaths(dir, prefix = '') {
 	if (!existsSync(dir)) return out;
 	for (const entry of readdirSync(dir, { withFileTypes: true })) {
 		const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-		if (entry.isDirectory()) out.push(...collectGuidePaths(join(dir, entry.name), rel));
+		if (entry.isDirectory())
+			out.push(...collectGuidePaths(join(dir, entry.name), rel));
 		else if (entry.name.endsWith('.md')) out.push(rel);
 	}
 	return out;
@@ -269,7 +351,11 @@ function getGuide({ name, maxChars } = {}) {
 	const rel = String(name ?? '').replace(/^\/+/, '');
 	// Contain reads to the guides dir — no traversal out of the knowledge base.
 	if (!rel || rel.includes('..')) {
-		return { found: false, error: `Invalid guide name '${name}'.` };
+		return {
+			found: false,
+			error: `Invalid guide name '${name}'.`,
+			hint: 'Call list_guides for the available names.',
+		};
 	}
 	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
 	const guidesDir = join(AI_ROOT, 'guides');
@@ -384,7 +470,7 @@ function buildServer() {
 		'search_components',
 		{
 			description:
-				"Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code.",
+				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code.',
 			inputSchema: {
 				query: z
 					.string()
@@ -550,6 +636,25 @@ export async function main() {
 
 export const start = main;
 
+/**
+ * The knowledge-base half, exported for in-process callers that want the same
+ * answers an MCP client gets without paying for a subprocess and a handshake —
+ * today, `scripts/run-eval-agent.mjs`, which hands these to a model as tools so
+ * the benchmark measures the knowledge base this server actually serves. Pure
+ * functions of the installed `dist/`: no transport, no state, safe to call
+ * concurrently. Importing this module does not start a server.
+ */
+export {
+	searchComponents,
+	getComponent,
+	listTokens,
+	listGuides,
+	getGuide,
+	listRecipes,
+	getRecipe,
+	validateCode,
+};
+
 const isDirectRun =
 	process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
 if (isDirectRun) {

package/bin/bitboss-ui.mjs

@@ -370,33 +370,79 @@ export default ${localeObjectLiteral(template)} satisfies LocaleOverrides;
 	console.log(`  ${dayjsHint}`);
 }
 
-const CHECK_SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
+// SNT-007: a bare-segment skip list of `node_modules`/`dist`/`.git` let a
+// default (no-glob) `check` sweep straight through a Laravel-style consumer's
+// `vendor/`, `storage/`, and `public/` trees — hundreds of vendored
+// `README.md`s outnumbering the app's own `.vue`/`.md` files 20:1. These are
+// all directories no project authors `Bb*` markup into, so they're safe
+// blanket exclusions; framework build caches (`.nuxt`, `.output`) get the
+// same treatment.
+const CHECK_SKIP_DIRS = new Set([
+	'node_modules',
+	'dist',
+	'.git',
+	'vendor',
+	'storage',
+	'public',
+	'.output',
+	'.nuxt',
+]);
+// Composite (multi-segment) skips: too narrow to earn a bare-segment entry —
+// skipping all of `bootstrap/` would also hide a project's own
+// `bootstrap/*.md` — but `bootstrap/cache` specifically is Laravel's compiled
+// config/routes cache, never hand-authored.
+const CHECK_SKIP_SUBPATHS = ['bootstrap/cache'];
 const CHECK_EXTENSIONS = ['.vue', '.md'];
 
-/** True when any path segment is a directory `check` never descends into. */
+/** True when a path segment (by itself) is a directory `check` never descends into. */
+function isSkippedSegment(name) {
+	return CHECK_SKIP_DIRS.has(name);
+}
+
+/** True when the relative path IS, or falls under, a skipped multi-segment subpath. */
+function isSkippedSubpath(relPath) {
+	const normalized = relPath.split(/[\\/]/).join('/');
+	return CHECK_SKIP_SUBPATHS.some(
+		(sub) => normalized === sub || normalized.startsWith(`${sub}/`)
+	);
+}
+
+/** True when any path segment (or composite subpath) is skipped. */
 function inSkippedDir(relPath) {
-	return relPath.split(/[\\/]/).some((segment) => CHECK_SKIP_DIRS.has(segment));
+	return (
+		relPath.split(/[\\/]/).some((segment) => isSkippedSegment(segment)) ||
+		isSkippedSubpath(relPath)
+	);
 }
 
 /**
- * Every `.vue`/`.md` file under `dir`, excluding node_modules/dist/.git at any
- * depth. Recursive readdir rather than `globSync` because glob's `**` never
- * traverses dot-directories (and there is no `dot` option) — the sweep must
- * keep matching files like `.github/copilot-instructions.md`.
+ * Every `.vue`/`.md` file under `dir`, excluding the skip list (see
+ * `CHECK_SKIP_DIRS`/`CHECK_SKIP_SUBPATHS`) at any depth. A hand-rolled
+ * recursive walk rather than `globSync` because glob's `**` never traverses
+ * dot-directories (and there is no `dot` option) — the sweep must keep
+ * matching files like `.github/copilot-instructions.md`. Pruning skipped
+ * directories BEFORE descending (rather than filtering after a flat
+ * `recursive: true` readdir) is what keeps a multi-thousand-file `vendor/`
+ * tree from being walked at all.
  */
-function collectCheckFiles(dir) {
+function collectCheckFiles(dir, relBase = dir) {
 	let entries;
 	try {
-		entries = readdirSync(dir, { recursive: true, withFileTypes: true });
+		entries = readdirSync(dir, { withFileTypes: true });
 	} catch {
 		return [];
 	}
 	const out = [];
 	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (isSkippedSegment(entry.name)) continue;
+			if (isSkippedSubpath(relative(relBase, full))) continue;
+			out.push(...collectCheckFiles(full, relBase));
+			continue;
+		}
 		if (!entry.isFile()) continue;
 		if (!CHECK_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) continue;
-		const full = join(entry.parentPath, entry.name);
-		if (inSkippedDir(relative(dir, full))) continue;
 		out.push(full);
 	}
 	return out;
@@ -404,10 +450,16 @@ function collectCheckFiles(dir) {
 
 /**
  * Resolve the file list for `check`: explicit globs/paths if given, otherwise
- * every `.vue`/`.md` file under `cwd` (excluding node_modules/dist/.git).
- * Literal paths resolve directly (files of any extension as-is, directories
- * swept recursively); glob patterns (`*`, `**`, `?`, `{a,b}`) go through
- * `node:fs` globSync, restricted to `.vue`/`.md` outside the skipped dirs.
+ * every `.vue`/`.md` file under `cwd` (excluding `CHECK_SKIP_DIRS`/
+ * `CHECK_SKIP_SUBPATHS` — node_modules, dist, .git, vendor, storage, public,
+ * .output, .nuxt, bootstrap/cache). Literal paths resolve directly: a literal
+ * FILE is always included (even one that lives inside a skipped dir — asking
+ * for it by name is the widen-the-scan escape hatch), a literal DIRECTORY is
+ * swept recursively and only its descendants are checked against the skip
+ * list (so `check vendor/some-pkg` still works even though a bare sweep would
+ * never enter `vendor/` on its own). Glob patterns (`*`, `**`, `?`, `{a,b}`)
+ * go through `node:fs` globSync, restricted to `.vue`/`.md` outside the
+ * skipped dirs.
  */
 function resolveCheckFiles(cwd, patterns) {
 	if (patterns.length === 0) return collectCheckFiles(cwd).sort();
@@ -450,6 +502,36 @@ function resolveCheckFiles(cwd, patterns) {
 	return [...matched].sort();
 }
 
+/**
+ * `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
+ * "701 vendored READMEs + 14 real files"; splitting by extension makes the
+ * number honest about what was actually covered. `.vue`/`.md` sort first
+ * (the extensions `check` targets by default); any other extension a literal
+ * path argument pulled in — see `resolveCheckFiles` — sorts after, A-Z.
+ */
+function summarizeFileCounts(files) {
+	const counts = new Map();
+	for (const file of files) {
+		const base = file.split(/[\\/]/).pop() ?? file;
+		const dot = base.lastIndexOf('.');
+		const ext = dot === -1 ? '(no extension)' : base.slice(dot);
+		counts.set(ext, (counts.get(ext) ?? 0) + 1);
+	}
+	const priority = ['.vue', '.md'];
+	const exts = [...counts.keys()].sort((a, b) => {
+		const pa = priority.indexOf(a);
+		const pb = priority.indexOf(b);
+		if (pa !== -1 || pb !== -1) {
+			return (
+				(pa === -1 ? priority.length : pa) - (pb === -1 ? priority.length : pb)
+			);
+		}
+		return a.localeCompare(b);
+	});
+	return exts.map((ext) => `${counts.get(ext)} ${ext}`).join(' + ');
+}
+
 /**
  * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup in `.vue`
  * and `.md` files against the installed components.json manifest.
@@ -494,7 +576,7 @@ function checkCommand(globs, jsonMode) {
 
 	if (findings.length === 0) {
 		console.log(
-			`[bitboss-ui] check OK — ${files.length} file(s), zero unknown Bb* props/v-models.`
+			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models.`
 		);
 		return;
 	}
@@ -543,7 +625,9 @@ Commands:
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models). Defaults to every .vue/.md file under the
-                      current directory (node_modules/dist/.git excluded).
+                      current directory (node_modules, dist, .git, vendor,
+                      storage, public, .output, .nuxt, bootstrap/cache
+                      excluded — pass an explicit glob/path to widen the scan).
                       Exits 1 on findings; \`--json\` prints \`{ findings: [...] }\`.
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,

package/bin/bitboss-ui.node.test.mjs

@@ -0,0 +1,113 @@
+/**
+ * `npx bitboss-ui check` integration tests.
+ *
+ * The CLI entrypoint (`bitboss-ui.mjs`) runs its command dispatch as a
+ * top-level side effect keyed off `process.argv` — importing it directly
+ * would execute the dispatcher against the TEST RUNNER's own argv. So this
+ * spawns the real binary as a subprocess against a scratch directory, which
+ * also happens to be the most faithful reproduction of SNT-007: a Laravel-
+ * shaped consumer tree where `check` used to report on `vendor/**` READMEs
+ * as if they were the project's own markup.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const BIN = fileURLToPath(new URL('./bitboss-ui.mjs', import.meta.url));
+
+let scratch;
+
+afterEach(() => {
+	if (scratch) rmSync(scratch, { recursive: true, force: true });
+	scratch = undefined;
+});
+
+/** Build a temp Laravel-shaped consumer tree: vendored noise + real markup. */
+function makeLaravelLikeFixture() {
+	const dir = mkdtempSync(join(tmpdir(), 'bitboss-ui-check-'));
+
+	// Noise a default sweep must now skip.
+	mkdirSync(join(dir, 'vendor', 'some', 'package'), { recursive: true });
+	writeFileSync(
+		join(dir, 'vendor', 'some', 'package', 'README.md'),
+		'# Vendored package\n'
+	);
+	mkdirSync(join(dir, 'storage', 'logs'), { recursive: true });
+	writeFileSync(join(dir, 'storage', 'logs', 'notes.md'), '# log notes\n');
+	mkdirSync(join(dir, 'public', 'build'), { recursive: true });
+	writeFileSync(join(dir, 'public', 'build', 'manifest.md'), '# build\n');
+	mkdirSync(join(dir, 'bootstrap', 'cache'), { recursive: true });
+	writeFileSync(
+		join(dir, 'bootstrap', 'cache', 'config.md'),
+		'# compiled config\n'
+	);
+
+	// A hand-authored doc that happens to live next to (not inside) the
+	// skipped `bootstrap/cache` dir — must still be counted.
+	writeFileSync(join(dir, 'bootstrap', 'README.md'), '# real bootstrap doc\n');
+
+	// Real app markup: one .vue, one .md.
+	mkdirSync(join(dir, 'resources', 'js', 'components'), { recursive: true });
+	writeFileSync(
+		join(dir, 'resources', 'js', 'components', 'Widget.vue'),
+		'<template><div>hi</div></template>\n'
+	);
+	writeFileSync(join(dir, 'GUIDE.md'), '# guide\n');
+
+	return dir;
+}
+
+function runCheck(cwd, args = []) {
+	try {
+		const stdout = execFileSync(process.execPath, [BIN, 'check', ...args], {
+			cwd,
+			encoding: 'utf-8',
+		});
+		return { status: 0, stdout };
+	} catch (error) {
+		return {
+			status: error.status,
+			stdout: error.stdout ?? '',
+			stderr: error.stderr ?? '',
+		};
+	}
+}
+
+describe('bitboss-ui check — default sweep skip list (SNT-007)', () => {
+	it('skips vendor/storage/public/bootstrap-cache and splits the summary by extension', () => {
+		scratch = makeLaravelLikeFixture();
+		const { status, stdout } = runCheck(scratch);
+
+		expect(status).toBe(0);
+		// Exactly the two real files: Widget.vue + (GUIDE.md + bootstrap/README.md).
+		expect(stdout).toMatch(
+			/\[bitboss-ui\] check OK — 1 \.vue \+ 2 \.md file\(s\), zero unknown Bb\* props\/v-models\./
+		);
+	});
+
+	it('still reports findings when a real file has an unknown prop', () => {
+		scratch = makeLaravelLikeFixture();
+		writeFileSync(
+			join(scratch, 'resources', 'js', 'components', 'Bad.vue'),
+			'<template><BbButton totallyBogusProp="x" /></template>\n'
+		);
+		const { status, stdout, stderr } = runCheck(scratch);
+
+		expect(status).toBe(1);
+		expect(stdout + stderr).toMatch(/check FAILED/);
+		expect(stdout + stderr).toMatch(/totallyBogusProp|totallybogusprop/i);
+	});
+
+	it('an explicit path still widens the scan into a normally-skipped dir', () => {
+		scratch = makeLaravelLikeFixture();
+		const { status, stdout } = runCheck(scratch, [
+			join('vendor', 'some', 'package', 'README.md'),
+		]);
+
+		expect(status).toBe(0);
+		expect(stdout).toMatch(/check OK — 1 \.md file\(s\)/);
+	});
+});

package/dist/ai/BbAccordion.md

@@ -69,7 +69,7 @@ collapsed state and strips padding/borders you put on the panel itself.
 				</div>
 			</template>
 
-			<p class="px-3 pb-2.5 text-sm text-gray-500">
+			<p class="px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]">
 				{{ faq.answer }}
 			</p>
 		</BbAccordion>
@@ -145,7 +145,9 @@ on the row, badge included, toggles the panel.
 			</template>
 
 			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
-				<p class="text-xs text-gray-500">{{ endpoint.summary }}</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					{{ endpoint.summary }}
+				</p>
 				<dl class="flex flex-col gap-1 text-xs">
 					<div
 						v-for="param in endpoint.params"
@@ -153,7 +155,7 @@ on the row, badge included, toggles the panel.
 						class="flex items-baseline gap-2"
 					>
 						<dt class="shrink-0 font-mono">{{ param.name }}</dt>
-						<dd class="text-gray-500">
+						<dd class="text-[color:var(--bb-text-muted)]">
 							{{ param.type }} · {{ param.description }}
 						</dd>
 					</div>
@@ -279,7 +281,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 			</template>
 			<template #default="{ toggle }">
 				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
-					<p class="text-sm text-gray-500">
+					<p class="text-sm text-[color:var(--bb-text-muted)]">
 						Dropdown keyboard navigation, smoother select popovers, and a new
 						color picker.
 					</p>
@@ -329,7 +331,9 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
 				>
 					<span class="font-medium">{{ plan.name }}</span>
-					<span class="flex items-center gap-1.5 text-gray-500">
+					<span
+						class="flex items-center gap-1.5 text-[color:var(--bb-text-muted)]"
+					>
 						{{ plan.price }}
 						<span
 							class="shrink-0 transition-transform duration-200"
@@ -341,7 +345,9 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 				</div>
 			</template>
 
-			<ul class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-gray-500">
+			<ul
+				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]"
+			>
 				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
 			</ul>
 		</BbAccordion>
@@ -410,7 +416,7 @@ padding on the nested body content.
 				<BbAccordion v-model="advanced">
 					<template #header="{ value }">
 						<div
-							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-gray-500"
+							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-[color:var(--bb-text-muted)]"
 						>
 							<span>Advanced</span>
 							<span
@@ -525,7 +531,7 @@ is generated for you.
 | --- | --- | --- | --- | --- |
 | `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
-| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. |
+| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
 | `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds |
 
 ## Events