bitboss-ui 3.0.0-alpha.9 → 3.0.0-beta.1

package/bin/bitboss-ui.mjs

@@ -17,7 +17,17 @@
  *             components.json manifest (unknown props, removed props, bad
  *             v-models, unknown `<template #slot>` names, `href`/`to`/
  *             `method` on a component that doesn't declare them). Exits 1
- *             on findings; supports --json output.
+ *             on findings; supports --json output. Every finding carries the
+ *             source line. `--allow-component <Name>` (or package.json's
+ *             `bitboss-ui.allowComponents`) exempts an app-owned component
+ *             whose name happens to start with `Bb`.
+ *
+ *             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.
  *   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.
@@ -445,12 +455,84 @@ function summarizeFileCounts(files) {
 	return exts.map((ext) => `${counts.get(ext)} ${ext}`).join(' + ');
 }
 
+/**
+ * Component names the PROJECT owns despite the `Bb` prefix, read from disk so
+ * CI, the editor and a local run agree without repeating a flag.
+ *
+ * Two sources, merged: `bitboss-ui.check.json`'s `allowComponents`, and
+ * package.json's `bitboss-ui.allowComponents`. The package.json key is the one
+ * to reach for — it sits next to the `eslint.config.js` that already carries
+ * the same list for `no-unknown-attributes`, so the two gates stay in sync.
+ * Unreadable/malformed files are ignored: a broken config must not turn into a
+ * check failure about markup.
+ * @returns {string[]}
+ */
+function configuredAllowComponents(projectRoot) {
+	const out = [];
+	const readList = (path, pick) => {
+		try {
+			if (!existsSync(path)) return;
+			const value = pick(JSON.parse(readFileSync(path, 'utf-8')));
+			if (Array.isArray(value))
+				for (const name of value) if (typeof name === 'string') out.push(name);
+		} catch {
+			/* malformed config — ignore, never fail the check on it */
+		}
+	};
+	readList(
+		join(projectRoot, 'bitboss-ui.check.json'),
+		(cfg) => cfg?.allowComponents
+	);
+	readList(
+		join(projectRoot, 'package.json'),
+		(pkg) => pkg?.['bitboss-ui']?.allowComponents
+	);
+	return out;
+}
+
+/**
+ * CHK-SINCE-V2 — the two unknown-prop message shapes mean OPPOSITE things and
+ * nothing in the output said so. One migrating fleet filed two non-findings
+ * against the library, and the other told the categories apart only by
+ * installing v2 alongside and diffing by hand. Printed once per failing run,
+ * and only for the kinds actually present.
+ *
+ * `check` is honest about its limits here: it validates against the INSTALLED
+ * v3 manifest and holds no record of v2, so "is not in X's API" is a statement
+ * about v3 alone. Deciding whether such a prop ever worked is the reader's job,
+ * and the greps in the migration guide are how it is done.
+ */
+function printFindingLegend(findings) {
+	const kinds = new Set(findings.map((f) => f.kind));
+	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.'
+		);
+	if (kinds.has('unknown-prop'))
+		rows.push(
+			'  "is not in X\'s API"    X does not declare this prop in v3 — and `check` cannot\n' +
+				'                         say whether it ever did. It may be a v3 removal that\n' +
+				'                         predates the removal register, or a name that was never\n' +
+				'                         a prop at all and has always fallen through to the DOM\n' +
+				'                         as an inert attribute. Check the v2 source before\n' +
+				'                         "restoring" anything: the second case needs deleting,\n' +
+				'                         not porting.'
+		);
+	if (rows.length === 0) return;
+	console.error('\nReading these findings:');
+	for (const row of rows) console.error(row);
+	console.error(
+		'  `check` reads the installed v3 manifest only; the package carries no v2 API.'
+	);
+}
+
 /**
  * `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) {
+function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 	const projectRoot = process.cwd();
 
 	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
@@ -481,6 +563,15 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		: new Set();
 	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 = [
+		...configuredAllowComponents(projectRoot),
+		...allowComponents,
+	];
+	const validateOptions = { allowComponents: allowedComponents };
+
 	const findings = [];
 	/*
 	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
@@ -493,8 +584,8 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		const relPath = relative(projectRoot, file);
 		const content = readFileSync(file, 'utf-8');
 		const { findings: fileFindings } = file.endsWith('.md')
-			? validateMarkdown(content, manifest)
-			: validateVueSnippet(content, manifest);
+			? validateMarkdown(content, manifest, validateOptions)
+			: validateVueSnippet(content, manifest, validateOptions);
 		for (const finding of fileFindings) {
 			findings.push({ file: relPath, ...finding });
 		}
@@ -573,14 +664,19 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 			finding.fenceInfo != null
 				? `fence#${finding.fenceIndex}${finding.fenceInfo ? ` (${finding.fenceInfo})` : ''} `
 				: '';
+		// CHK-LINE: three identical `full-screen` findings under one filename
+		// 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}: ` : '';
 		console.error(
-			`    ✗ ${where ? `[${where.trim()}] ` : ''}${finding.message}`
+			`    ✗ ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
 		);
 		if (finding.hint) console.error(`      hint: ${finding.hint}`);
 	}
 	console.error(
 		'\nFix the markup (or the component API) so it stays copy-safe for agents.'
 	);
+	printFindingLegend(findings);
 	printHints();
 	process.exit(1);
 }
@@ -600,7 +696,8 @@ 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] [--allow-empty]
+  check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
+                      [--no-hints]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -612,7 +709,27 @@ Commands:
                       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 }\`.
+
+                      \`--allow-component <Name>\` (repeatable) exempts a
+                      component your APP owns whose name starts with \`Bb\` —
+                      the prefix is a convention, not proof of provenance.
+                      Persist the list instead of repeating the flag:
+                        package.json  { "bitboss-ui": { "allowComponents": ["BbRichEditor"] } }
+                      or \`bitboss-ui.check.json\` \`{ "allowComponents": [...] }\`.
+                      Same option name as the ESLint rules' \`allowComponents\`,
+                      so both gates configure alike.
+
+                      \`--json\` prints \`{ findings: [...], hints: [...], files }\`.
+                      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;
+                      may never have been one — see the legend the text output
+                      prints), \`unknown-model\`, \`unknown-slot\`,
+                      \`no-default-slot\`, \`inert-nav-attr\`,
+                      \`missing-partner-prop\`, \`partner-prop\`,
+                      \`validated-only-prop\`.
   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.
@@ -658,14 +775,18 @@ switch (command) {
 			{
 				json: { type: 'boolean' },
 				'allow-empty': { type: 'boolean' },
+				'allow-component': { type: 'string', multiple: true },
+				// 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,
-			values.json ?? false,
-			values['allow-empty'] ?? false
-		);
+		checkCommand(positionals, {
+			json: values.json ?? false,
+			allowEmpty: values['allow-empty'] ?? false,
+			allowComponents: values['allow-component'] ?? [],
+		});
 		break;
 	}
 	case 'mcp': {

package/dist/ai/BbIcon.md

@@ -135,7 +135,12 @@ The `icon` prop takes a name in one of three forms:
 - **`local:name`** — an SVG in the configured `iconDir` (brand marks, custom
   illustrations). Each `.svg` file becomes `local:<basename>`.
 - **bare `name`** — an unprefixed name **normalizes to `local:`**; it never
-  searches provider sets.
+  searches provider sets. Prefer writing the prefix anyway: the Iconify editor
+  extension keys off `prefix:name`, so `local:user-circle` gets an inline
+  preview and name autocomplete in the template while a bare `user-circle`
+  reads as an ordinary string and gets neither. It also puts your own art in
+  the same shape as `mdi:home` / `lucide:check`, so the source of every icon is
+  legible without inferring it from a missing prefix.
 
 Discovery-first: **only use names you have verified exist** — a missing icon
 **throws at mount** (dev shows an actionable Vite overlay with the exact

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-alpha.9",
+	"version": "3.0.0-beta.1",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-alpha.9",
-	"generatedAt": "2026-08-24T11:02:05.896Z",
+	"version": "3.0.0-beta.1",
+	"generatedAt": "2026-08-24T19:52:26.526Z",
 	"composables": [
 		{
 			"name": "useBbConfig",

package/dist/ai/guides/ai-router.md

@@ -15,9 +15,9 @@ Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
 Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.
 
 **Not installed, or can only fetch URLs?** The same files are served from the
-published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/…`.
+published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/…`.
 If you can make only one request, fetch
-[`…@alpha/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt)
+[`…@beta/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt)
 — this router plus the agent contract, setup, component picker, design language
 and the full component catalogue, in ~110 KB.
 

package/dist/ai/guides/design-tokens.md

@@ -295,6 +295,51 @@ Component tokens are still real affordances: a consumer can retune one
 instance (`<BbTabs style="--list-h: 40px">`) or a whole page scope. They are
 just not global namespace.
 
+### Overriding one from a consumer app
+
+Three rules, in order of how often they are broken.
+
+**1. Override only what you actually render.** Several components expose a
+per-size lookup table (`--icon-size-xs … --icon-size-2xl`, `--h-xs … --h-2xl`)
+plus an _active_ token the size class re-points. Setting the whole family
+because you want one value is not "thorough" — it silently opts you out of the
+size scale for variants you may start using later, and it buries the one line
+that mattered. Retune the sizes you use:
+
+```css
+/* we render sm and md buttons; leave the rest on the library's scale */
+.bb-button {
+	--icon-size-sm: 12px;
+	--icon-size-md: 12px;
+}
+```
+
+**2. Override the per-size entry, not the active token.** The active token is
+re-resolved by the size class, which is _more specific_ than the root class:
+
+```css
+.bb-button {
+	--icon-size: var(--icon-size-md);
+} /* 0,1,0 */
+.bb-button--sm {
+	--icon-size: var(--icon-size-sm);
+} /* 0,2,0 — nested */
+```
+
+So `.bb-button { --icon-size: 12px }` appears to work on default buttons and
+silently does nothing on every `size="sm"` one — the confusing half-failure that
+sends people to the shotgun in rule 1. The per-size entry has no competing
+declaration, so it always wins. (A scope selector of equal-or-greater
+specificity also works, but you have to keep winning that race; overriding the
+entry does not.)
+
+**3. Scope it to the component, never `:root`.** Short names are deliberately
+reused across components — `--icon-size` is read by `BbButton`, `BbBadge` and
+`CloseIcon`; `--gap`, `--px`, `--h` are everywhere. Hoisting one to `:root`
+retunes every component that happens to share the name, which is exactly what
+tier-2's sealing rule exists to prevent. Put it on the component's class, a page
+scope, or the instance's `style=`.
+
 ## The emphasis ladder
 
 All translucency/tinting goes through **one ladder** of `color-mix()`
@@ -379,12 +424,40 @@ scope (`.brand { --bb-primary: … }`) does not re-derive them — re-apply the
 `light`/`dark` class on that scope, or override the derived tokens directly.
 Root-level theming (what the theme builder emits) is unaffected.
 
-### Animated themes
+### Registered knobs (`@property`)
+
+Nine tokens are registered in `variables.css`: the eight color knobs with
+`syntax: '<color>'`, and `--bb-ring-opacity` with `syntax: '<percentage>'`.
+All are `inherits: true`.
+
+**Registration types them, and a typed property rejects.** A declaration that
+does not parse as the declared syntax is invalid at computed-value time — the
+value is discarded, and because these inherit, an override at `:root` (no
+parent to inherit from) lands on the registered `initial-value`. That is the
+fail-soft half: an unparseable `--bb-panel` falls back instead of detonating
+every derivation that mixes it. It is also the trap. Write
 
-The color knobs (and `--bb-ring-opacity`) are registered with `@property`
-(typed `<color>`, `inherits: true`), which makes them **animatable** and
-fail-soft (an invalid `--bb-panel` falls back to the registered initial
-value instead of detonating every derivation). Add `.theme-animated`
+```css
+:root {
+	--bb-ring-opacity: 0.15;
+} /* wrong: not a <percentage> */
+```
+
+and nothing errors — not the build, not the console. The computed value is
+just `25%`, and every ring paints 1.67× stronger than the `15%` you asked for
+(opacity is the ring's strength; its thickness is `--bb-ring-size`).
+Percentages need the `%`; colors must be a `<color>` (`transparent` and
+`currentColor` qualify, `none` and a mistyped hex do not). Nothing in the
+toolchain catches it either: `bitboss-ui check` reads `.vue`/`.md`, never
+stylesheets.
+
+Fail-soft is only soft when the initial value is close to the real one. Every
+color knob is registered at its light default, so a rejected color override
+renders the library's own light theme. `--bb-ring-opacity` is registered at
+`25%`, which matches neither shipped scope (light `15%`, dark `40%`), so a
+rejected value there is the one that shows.
+
+Typed knobs are also **animatable**. Add `.theme-animated`
 (main.css) to the element that carries the scheme class or theme overrides:
 
 ```html
@@ -525,7 +598,7 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `color-mix(in srgb, …)`                                                                                                                                          | `color-mix(in oklab, …)` everywhere                                          |
 | dialog/offcanvas `--radius-multiplier` ×1.8, literal `6px`/`8px`/`0.375rem` radii                                                                                | `--bb-radius-surface` / `--bb-radius-sm`                                     |
 | `--bb-contrasting`                                                                                                                                               | `--bb-primary-fg`                                                            |
-| `--bb-easing-bezier`                                                                                                                                             | `--bb-ease`                                                                  |
+| hard-coded `cubic-bezier()` literals (v2 exposed no easing token)                                                                                                | `--bb-ease`                                                                  |
 | `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                 | `--bb-muted`                                                                 |
 | `--bb-muted-color`, `--bb-hint`, `--bb-placeholder`, `--bb-icon-color`, `--bb-prefix-color`                                                                      | `--bb-text-muted`                                                            |
 | `--bb-input-color`, `--bb-input-bg`                                                                                                                              | `--bb-text`, `--bb-panel`                                                    |
@@ -542,6 +615,18 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
 | `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |
 
+**This table maps names, not values.** A token that is absent from it survived
+the rename — which is not the same as surviving unchanged. Six kept their v2
+name and their global scope and moved default anyway (input height, input
+vertical padding, prefix column width, label weight, ring size, leading); the
+before/after numbers are tabled in the v2→v3 migration guide, §3. The rule
+generalizes past this migration: a `--bb-*` name is a slot in the derivation
+graph, not a promise about the number in it. An override you carried forward
+keeps working and keeps your old look; an override you deleted because "the
+name still exists" hands you whatever `variables.css` declares today. Check
+each survivor against `variables.css` and delete only the ones that were
+restating a default.
+
 ## Enforcement
 
 `npm run check:tokens` (see `scripts/check-tokens.mjs`) fails the build when:

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -13,16 +13,21 @@ Source of truth for integrating `bitboss-ui`. Two pieces are always required:
 ## 1) Install
 
 ```bash
-# v3 is a prerelease — the `@alpha` tag is REQUIRED.
+# v3 is a prerelease — a dist-tag is REQUIRED.
 # A bare `npm install bitboss-ui` still resolves to v2, which has no build
 # plugin and no `dist/ai` knowledge base, so everything below silently fails.
-npm install bitboss-ui@alpha
+npm install bitboss-ui@beta
 # recommended default icon set (any @iconify-json/* works)
 npm install -D @iconify-json/lucide
 ```
 
 Confirm you got v3 before continuing — `npm ls bitboss-ui` must report a
-`3.0.0-alpha.*` version. If it reports `2.x`, nothing in this guide applies.
+`3.0.0-*` version. If it reports `2.x`, nothing in this guide applies.
+
+**`@beta` is the current v3 channel.** `@alpha` still resolves, but it is
+frozen at the last alpha and does not receive fixes — it is not simply an older
+copy of the same line. `@latest` is the **v2** line and always will be until v3
+goes stable, so never reach for it here.
 
 Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.
 
@@ -219,6 +224,48 @@ import 'bitboss-ui/styles.css';
 import 'bitboss-ui/reset.css';
 ```
 
+**Exception — an app that needs its own CSS to load _before_ the library.**
+Auto-injection is library-first and not configurable: the runtime plugin
+inserts its `<style>` **before the first** `style`/`link[rel="stylesheet"]`
+already in `<head>` (`src/utils/injectLibraryStyles.ts`), so the guaranteed
+order above is exactly what you get and every app stylesheet — your Tailwind
+entry included — lands after the library. There is no option to inject later.
+
+That is the order most apps want. It is the wrong order if you need library
+rules to beat Tailwind's Preflight **by source order**, which is the case on
+**Tailwind v3**: `@tailwind base` compiles to ordinary unlayered CSS, so under
+auto-injection Preflight sits after the library sheet and its element resets
+(`button`, `input`, `h1`, …) win every equal-specificity tie. `injectStyles:
+false` + `resetCss: false` (the default) disables injection entirely and hands
+you the order:
+
+```ts
+// vite.config.ts / the `bitboss` key in nuxt.config.ts
+bitbossUi({ iconDir: '…', injectStyles: false, resetCss: false });
+```
+
+```ts
+// app entry — order is yours now
+import './app.css'; // your Tailwind entry
+import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
+```
+
+Leave `resetCss` at `false` here — Preflight already reset everything.
+Nothing else about the plugin changes; `injectStyles` controls only whether the
+library injects its own `<style>`.
+
+**Tailwind v4 apps do not need this** — source order does not decide their ties
+at all. `@import 'tailwindcss'` puts Preflight in a real `@layer base` and
+utilities in `@layer utilities`, and layered rules lose to unlayered rules of
+equal specificity **regardless of source order**. `dist/styles.css` declares no
+`@layer`, so the library wins those ties wherever it is injected: leave
+auto-injection on. The same mechanic bites the other way, and silently — a
+utility cannot re-size a Bb component either. `<BbButton class="h-12 px-6">`
+loses to the library's own `.bb-button { height: var(--h); padding-left:
+var(--px); padding-right: var(--px) }` (equal specificity, unlayered), with no
+warning from anything. Size Bb components through their props and tokens, never
+utilities. (Same trap as the scoped-`<style>` case above, one level up.)
+
 ## 6) Icons
 
 - `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
@@ -260,6 +307,15 @@ When `true`, the **dev server** adds `./node_modules/.bitboss-ui/local-icons.jso
 
 When `true`, the **dev server** registers the bitboss-ui MCP server in each project-scoped agent-harness config on boot — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code / Copilot) — so agents can query the knowledge base with no manual setup. The write is merge-safe (leaves other servers alone) and idempotent (only logs when it actually changes a file). Windsurf is intentionally **not** written here: its config is global (`~/.codeium`), and silently editing a home-dir file that affects every project on the machine from a dev-server boot would be surprising — run `npx bitboss-ui ai-init --mcp` to register Windsurf too. This flag is the zero-command equivalent of that command's project-scoped writes. The MCP server's own runtime — `@modelcontextprotocol/sdk` and `zod` — ships as **optional peer dependencies** (~12 MB, more than every runtime dependency of the library combined, and loaded by nothing else), so install them with `npm i -D @modelcontextprotocol/sdk zod` before the harness first launches the server; both this flag and `ai-init --mcp` warn when they are missing.
 
+**MCP is a convenience, not a requirement, and skipping it costs no
+knowledge.** The server is a reader over files the install already put on disk
+— every tool `readFileSync`s out of `node_modules/bitboss-ui/dist/ai/` (plus
+`dist/styles.css` for the token lookup). An agent that opens that directory
+itself has the identical knowledge base, `npx bitboss-ui check` runs without the
+peers, and `ai-init` (no `--mcp`) still writes the harness pointers. If you are
+migrating under a "no new dependencies" constraint, leave `mcp` at `false`,
+skip `--mcp`, and point your agent at `dist/ai/guides/ai-router.md`.
+
 ### `inertiaLinkName?: string` (default: `'Link'`)
 
 Global component name used for Inertia links. **Optional** — when nothing is
@@ -438,7 +494,17 @@ than inventing hues.
 
 The package ships its agent docs in `node_modules/bitboss-ui/dist/ai/`. **Start at** `guides/ai-router.md`, then the catalogue `index.md`. Run `npx bitboss-ui ai-init` in the consumer project to inject harness-agnostic pointers (AGENTS.md, Cursor rules, Copilot instructions, Claude skill, Windsurf rules) so coding agents discover them without a vendor lock-in. After generating Bb\* markup, run `npx bitboss-ui check` (supports `--json`) so unknown props fail before review.
 
-Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent.
+**Three tiers ship under `dist/ai/`**, and the third one is easy to miss:
+`guides/` + `recipes/` are the authored prose; `<Name>.md` at the root is the
+generated typed contract for each component (props, slots, events, examples);
+`source/<Name>.md` is that same component's **complete implementation** —
+`.vue` template, `types.ts` and `index.css` in one file, one per component
+including the internal ones the package does not export. Read the source tier
+when the contract cannot answer the question — the usual case is rebuilding
+chrome around a control the library does not ship, since the class names such a
+template emits are already styled by the public `bitboss-ui/styles.css`.
+
+Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
 
 For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
 
@@ -458,7 +524,7 @@ It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without it
 - [ ] build plugin configured: `bitboss-ui/vite` plugin or `bitboss-ui/nuxt` module (`bitboss` config key);
 - [ ] `iconDir` points at an existing SVG folder;
 - [ ] runtime plugin installed: `app.use(bitbossUiPlugin)` (automatic in Nuxt);
-- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'`;
+- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'` — auto injection is always library-first, so a Tailwind **v3** app that needs Preflight to load before the library must take the second option (§5);
 - [ ] if a reset is required: `resetCss: true` or `import 'bitboss-ui/reset.css'`;
 - [ ] Inertia apps: `@inertiajs/vue3` installed (no link registration needed; set `inertiaLinkName` only if you register your own link wrapper).
 - [ ] building the [Layout Scaffold](../recipes/vue/layout-scaffold.md)? `npm i @vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal` from it. This library depends on it too, so it can resolve via hoisting without being declared — don't rely on that; declare it in your own `package.json` or a strict installer (pnpm, Yarn PnP) will fail to resolve it.

package/dist/ai/guides/migration/components/bb-alert.md

@@ -35,3 +35,40 @@ prop now actually carries `text` (v2 mistakenly passed `title`).
 A hand-applied `class="bb-alert--warning"` also becomes `variant="warning"` —
 see [main guide §7](../v2-to-v3.md). Custom `theme` names: register via the
 plugin's `alertVariants` option and keep your CSS.
+
+## ⚠ `theme` painted nothing in v2 — and now two identical call sites diverge
+
+v2's stylesheet shipped **zero** `.bb-alert--*` rules. The component emitted
+`bb-alert--${theme}` faithfully, but unless your own CSS defined the rule, every
+value rendered the same default surface. `theme="success"`, `theme="blue"` and
+`theme="warning"` were the same alert.
+
+In v3 the string is live, and what happens next depends on nothing but whether
+the name collides with a built-in (`outline`, `primary`, `destructive`,
+`warning`):
+
+```diff
+  <!-- these two rendered identically in v2 -->
+- <BbAlert theme="success" title="Saved" />
++ <BbAlert variant="success" title="Saved" />
+  <!-- `success` is not an alert built-in → compile error until you register it. You will notice. -->
+
+- <BbAlert theme="warning" title="Quota almost reached" />
++ <BbAlert variant="warning" title="Quota almost reached" />
+  <!-- `warning` IS a built-in → compiles, and silently repaints amber (#fffbea on #fee685). You will not. -->
+```
+
+The rename diff above is a **visual change** for `warning`, not a no-op. Before
+converting any `theme=` value, grep your own stylesheets for
+`.bb-alert--<value>`:
+
+- **Nothing styled it** → the value was decoration. Drop the prop and take the
+  v3 default, or register the name via `alertVariants` and ship no CSS for it,
+  which holds v2's appearance exactly.
+- **Your CSS styled it** → register the name and keep your rule; `warning` is
+  the one case where your rule now lands on top of a library skin, so check
+  that you override every property it sets (background, border, `--main-color`,
+  `--muted-color`) and not just the ones your v2 rule needed.
+
+The same trap applies to `BbTooltip` and `toast()` — v2 styled none of their
+theme classes either.

package/dist/ai/guides/migration/components/bb-avatar.md

@@ -1,16 +1,16 @@
 ---
 title: 'Migration v2→v3: BbAvatar'
-summary: The color prop is removed — the initials fallback is always primary.
+summary: The color prop is removed — retheme the fallback through the --bg-color / --text-color locals.
 ---
 
 # BbAvatar — v2 → v3
 
 ## Changes
 
-| v2               | v3                                                                                            | Kind                                                                                            |
-| ---------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `color?: string` | removed                                                                                       | initials fallback always uses the primary tokens; override `.bb-avatar` CSS for anything custom |
-| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                               |
+| v2               | v3                                                                                            | Kind                                                                                                |
+| ---------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `color?: string` | removed                                                                                       | the fallback surface paints from two locals on `.bb-avatar` — `--bg-color` / `--text-color` (below) |
+| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                                   |
 
 ## Edits
 
@@ -19,6 +19,45 @@ summary: The color prop is removed — the initials fallback is always primary.
 + <BbAvatar :src="user.photo" :alt="user.name" />
 ```
 
-If per-user colors mattered, set them in CSS on a wrapper
-(`.team-avatar--purple .bb-avatar { … }`) — the component no longer carries
-presentation-by-prop.
+## Where the color went
+
+`.bb-avatar` declares three locals and reads them for the fallback (initials,
+slotted content, or the built-in person glyph — an image covers all of them):
+
+| local                  | default                                    | paints                      |
+| ---------------------- | ------------------------------------------ | --------------------------- |
+| `--bg-color`           | `var(--bb-primary)`                        | the avatar background       |
+| `--text-color`         | `var(--bb-primary-fg)`                     | initials / slotted fallback |
+| `--default-icon-color` | 80% mix of `--bb-primary-fg` over the fill | the built-in person glyph   |
+
+Set them on a scope, not on the component:
+
+```css
+.team-avatar .bb-avatar {
+	--bg-color: #7c3aed;
+	--text-color: #fff;
+}
+```
+
+⚠ Set **both**. `--bg-color` alone leaves the initials at `--bb-primary-fg`,
+which is the contrast pair for the _primary_ color, not for yours — the symptom
+is white-on-pale or black-on-dark initials.
+
+Use this for a color that genuinely varies per instance (per-team, per-tenant).
+If the v2 `color` was your brand color repeated at every call site, retheme
+`--bb-primary` / `--bb-primary-fg` once instead and write no per-avatar rules.
+That is the order the BbAvatar usage guide prescribes: retheme the tokens
+first, reach for the locals only when the value is per-instance.
+
+## `.bb-avatar--square` was never a library modifier
+
+If your app has a `.bb-avatar--square` rule, it is **your** CSS. v2 shipped no
+such modifier — its entire avatar stylesheet was four rules, all hardcoding
+`border-radius: 50%`, and the string `square` appears nowhere in the v2
+package. v3 bakes in the same circle.
+
+So nothing was removed and there is no v3 modifier to rename to. Your rule
+keeps working: it has the same specificity as the library's `.bb-avatar` rule
+and the library sheet is injected above your app CSS, so yours wins the tie.
+Rename the class to an app-owned block (`.p-avatar--square`) anyway, so the
+next reader does not take it for library API and go hunting for a `shape` prop.