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

package/README.md

@@ -18,15 +18,16 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, and **`index.css`*
 
 ### Composables
 
-| Composable                    | Role                                                      |
-| ----------------------------- | --------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).      |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging. |
-| `useConfirm`                  | Programmatic confirm / modal flows.                       |
-| `useCountdown`                | Countdown timer state.                                    |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                     |
-| `useQueue`                    | Simple async task queue.                                  |
-| `useToast`                    | Toast notifications API.                                  |
+| Composable                    | Role                                                       |
+| ----------------------------- | ---------------------------------------------------------- |
+| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
+| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
+| `useConfirm`                  | Programmatic confirm / modal flows.                        |
+| `useCountdown`                | Countdown timer state.                                     |
+| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
+| `useQueue`                    | Simple async task queue.                                   |
+| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
+| `useToast`                    | Toast notifications API.                                   |
 
 ### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
 
@@ -70,7 +71,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 +95,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
@@ -199,7 +207,8 @@ markup) instead of reading files blind:
 npx bitboss-ui ai-init --mcp
 ```
 
-The agent harness launches the server itself (`npx bitboss-ui mcp`) on demand —
+The agent harness launches the server itself (`npx bitboss-ui@<installed version> mcp`,
+pinned so npx can never fall back to fetching a different version from the registry) on demand —
 you never run it by hand. `--mcp` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
@@ -236,13 +245,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

@@ -17,7 +17,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {
@@ -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 90 `check:tokens` counts).
  *
- * 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.
+ * 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.
+ *
+ * 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');
@@ -319,12 +405,28 @@ function getRecipe({ platform, name, maxChars } = {}) {
 			error: `Unknown platform '${platform}' — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
 		};
 	}
-	const fileName = String(name ?? '').endsWith('.md')
-		? String(name)
-		: `${name}.md`;
-	const filePath = join(AI_ROOT, 'recipes', platform, fileName);
-	if (!existsSync(filePath)) {
-		return { found: false, error: `Recipe not found: ${platform}/${fileName}` };
+	// Contain reads to the platform's recipe dir — no traversal out of the
+	// knowledge base. `platform` is already allow-listed above, but `name` is
+	// free text, so it gets the same treatment as `get_guide`'s: leading
+	// separators stripped, `..` rejected outright, and the joined path checked
+	// to still sit under the recipe dir.
+	const rel = String(name ?? '').replace(/^\/+/, '');
+	if (!rel || rel.includes('..')) {
+		return {
+			found: false,
+			error: `Invalid recipe name '${name}'.`,
+			hint: 'Call list_recipes for the available names.',
+		};
+	}
+	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
+	const recipesDir = join(AI_ROOT, 'recipes', platform);
+	const filePath = join(recipesDir, fileName);
+	if (!filePath.startsWith(`${recipesDir}${sep}`) || !existsSync(filePath)) {
+		return {
+			found: false,
+			error: `Recipe not found: ${platform}/${fileName}`,
+			hint: 'Call list_recipes for the available names.',
+		};
 	}
 	const { content, ...meta } = truncateMarkdown(
 		readFileSync(filePath, 'utf-8'),
@@ -384,7 +486,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 +652,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

@@ -16,7 +16,9 @@
  *   locale    Generate a custom locale blueprint (.locale.ts)
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
- *             v-models). Exits 1 on findings; supports --json output.
+ *             v-models, unknown `<template #slot>` names, `href`/`to`/
+ *             `method` on a component that doesn't declare them). Exits 1
+ *             on findings; supports --json output.
  *   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.
@@ -370,33 +372,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 +452,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();
@@ -451,10 +505,41 @@ function resolveCheckFiles(cwd, patterns) {
 }
 
 /**
- * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup in `.vue`
- * and `.md` files against the installed components.json manifest.
+ * `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 checkCommand(globs, jsonMode) {
+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 (props,
+ * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
+ * the installed components.json manifest.
+ */
+function checkCommand(globs, jsonMode, allowEmpty = false) {
 	const projectRoot = process.cwd();
 
 	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
@@ -480,12 +565,26 @@ function checkCommand(globs, jsonMode) {
 	}
 
 	if (jsonMode) {
-		console.log(JSON.stringify({ findings }, null, 2));
+		console.log(JSON.stringify({ findings, files: files.length }, null, 2));
 		if (findings.length > 0) process.exit(1);
+		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
 		return;
 	}
 
 	if (files.length === 0) {
+		// An EXPLICIT pattern that matched nothing is almost always a typo'd or
+		// stale CI path, and answering it with exit 0 means the step goes green
+		// having validated nothing — the check that was meant to catch bad
+		// 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 (globs.length > 0 && !allowEmpty) {
+			console.error(
+				`[bitboss-ui] check: no .vue/.md files matched ${globs.map((g) => `\`${g}\``).join(', ')} — nothing was validated. ` +
+					'Fix the path, or pass `--allow-empty` if an empty match is expected.'
+			);
+			process.exit(1);
+		}
 		console.log(
 			'[bitboss-ui] check: no .vue/.md files matched — nothing to do.'
 		);
@@ -494,7 +593,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/slots/nav-attrs.`
 		);
 		return;
 	}
@@ -539,12 +638,19 @@ Commands:
                       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.
-  check [glob…] [--json]
+  check [glob…] [--json] [--allow-empty]
                       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).
-                      Exits 1 on findings; \`--json\` prints \`{ findings: [...] }\`.
+                      bad v-models, unknown \`<template #slot>\` names,
+                      \`href\`/\`to\`/\`method\` on a component that doesn't declare
+                      them). Defaults to every .vue/.md file under the 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, and on an explicit glob that matched
+                      nothing (a typo'd CI path validates zero files silently) —
+                      pass \`--allow-empty\` when an empty match is expected.
+                      \`--json\` prints \`{ findings: [...], files }\`.
   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.
@@ -590,10 +696,17 @@ switch (command) {
 		const { values, positionals } = parseCommandArgs(
 			command,
 			commandArgs,
-			{ json: { type: 'boolean' } },
+			{
+				json: { type: 'boolean' },
+				'allow-empty': { type: 'boolean' },
+			},
 			{ allowPositionals: true }
 		);
-		checkCommand(positionals, values.json ?? false);
+		checkCommand(
+			positionals,
+			values.json ?? false,
+			values['allow-empty'] ?? false
+		);
 		break;
 	}
 	case 'mcp': {