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

package/README.md

@@ -6,19 +6,21 @@ Vue 3 component library used across BitBoss products. It ships typed building bl
 
 ## What’s in the package
 
-Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
+Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components.bitboss.it/).
 
 ### Styles
 
-- **Global stylesheet** — import `bitboss-ui/styles.css` once. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
-- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`).
+- **Global stylesheet** — `bitboss-ui/styles.css`, injected for you by the runtime plugin (`injectStyles`, on by default); import it by hand only with `injectStyles: false`. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
+- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`). A reset is a **prerequisite** of the components, not a nicety: their sizes are written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Use this one, or your own — Tailwind's Preflight covers it, which is why `resetCss` defaults to off. The component test suite runs against this file.
+- **Cascade layers (opt-in)** — on Tailwind v4 the library must sit in your layer order or its unlayered rules outrank every utility you put on a component. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin (both exported from `bitboss-ui/vite`) places it after Preflight and before the utilities. Details in `dist/ai/guides/installation-and-plugin-setup.md` § Cascade layers.
 
 ### TypeScript: use `vue-tsc` 3
 
 Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
-silently checks **nothing** about the props of the nine components declared with
-`generic="T"` — `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`,
-`BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` —
+silently checks **nothing** about the props of the ten public components that
+use `<script setup generic="…">` — `BbSelect`, `BbSelectPopover`, `BbTable`,
+`BbTabs`, `BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`,
+`BbSwitchGroup`, and `BbForm` —
 because they emit as generic functions rather than `DefineComponent<…>`, a shape
 Vue Language Tools 2 cannot read props out of.
 
@@ -28,54 +30,84 @@ gate looks like it is working. A real consumer shipped
 `<BbRadioGroup label="…">` (the prop is `legend`) through six release slices on
 `vue-tsc@^2.2.12` with a green `--noEmit`.
 
-Full detail: `ai/guides/installation-and-plugin-setup.md`.
+Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### TypeScript: icons
 
-- **`IconType`**, **`IconRegistry`** — types used by icon-aware components; extend `IconRegistry` in your app to register project-specific icons.
+- **`IconType`** — the type of every icon prop: a plain `prefix:name` string (`lucide:save`, or `local:<name>` for an SVG in `iconDir`). There is no registry to extend; the build plugin ships what your code names (see Icons below).
 
 ### 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.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
+| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`           | Programmatic confirm / modal flows.                                   |
+| `useCountdown`         | Countdown timer state.                                                |
+| `useId`                | SSR-safe unique ids.                                                  |
+| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
+| `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)_
+### Utilities
 
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
 
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Internal building blocks
+
+The shared field chrome (`CommonField`, `CommonFieldInput` — label,
+prepend/append, prefix/suffix, clear button, spacing) and the other `Common*`
+pieces are **internal and are not exported**; every form control renders them
+itself. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbCalendar`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanels`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
-
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
+- **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbFormContext`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).
+- **Schema validation, no adapter:** pass a Zod, Valibot, ArkType or Yup schema (any [Standard Schema](https://standardschema.dev)) to `BbForm`'s `schema` as it is. Messages land on the field by path (`address.city`, `lines.0.qty`), `@submit` receives the schema's parsed output typed from the schema, the required asterisk comes from the schema, and a failed submit focuses the first invalid field on screen. Per-step schemas plus `keep-values-on-unmount` cover multi-step wizards. No extra runtime dependency.
+- **Passthrough scopes:** `BbPtScope` + `definePt` — a named `pt` map applied to one area of the app.
+
+### Passthrough (`pt`)
+
+Every component names a short list of **parts** and **states**, and a
+`pt:<part>` / `pt:<part>:<state>` prop reaches that part with a class list —
+or, in the object form, a style and attributes — typed and linted in the
+attribute form, on top of any variant. Classes append to ours, attributes win, listeners run after the
+component's own handler. A build-time `pt` map in the Vite / Nuxt plugin seeds
+every instance. Grammar, merge rules and the per-component vocabulary:
+[`passthrough.md`](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/passthrough.md) (installed: `dist/ai/guides/passthrough.md`).
+
+```vue
+<BbButton
+	prepend:icon="lucide:save"
+	pt:icon="text-emerald-600"
+	pt:icon:loading="animate-pulse"
+>Save</BbButton>
+<BbTable :items="rows" pt:row:highlighted="bg-amber-50" />
+```
 
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 
@@ -83,20 +115,20 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 **Primary docs (components, props, guides):**
 
-- [BitBoss UI documentation](https://ui-components-docs.vercel.app/) — site with guides and API reference.
+- [BitBoss UI documentation](https://ui-components.bitboss.it/) — site with guides and API reference.
 
 **For AI coding agents:**
 
 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.5`) for stable
+an agent can read it before anything is installed. `@beta` tracks the latest
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-beta.32`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~19 KB) — link index into every document.
-- [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (about 200 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (about 20 KB) — link index into every document.
+- [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (about 5 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -114,24 +146,24 @@ This package is developed and maintained by [BitBoss](https://www.bitboss.it/),
 
 ## Installation
 
-**v3 is a prerelease: the `@alpha` tag is required.** A bare
+**v3 is a prerelease: the `@beta` 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@alpha
+npm install bitboss-ui@beta
 ```
 
 ```bash
-pnpm add bitboss-ui@alpha
+pnpm add bitboss-ui@beta
 ```
 
 ```bash
-yarn add bitboss-ui@alpha
+yarn add bitboss-ui@beta
 ```
 
-Verify with `npm ls bitboss-ui` — it must report `3.0.0-alpha.*`.
+Verify with `npm ls bitboss-ui` — it must report `3.0.0-beta.*`.
 
 ---
 
@@ -147,14 +179,15 @@ import { BbButton, BbTextInput, useToast } from 'bitboss-ui';
 
 ### Styles
 
-Bundled CSS is published under the `styles` export:
+Bundled CSS is published under the `styles` export. **You do not import it**:
+the runtime plugin injects it (`injectStyles`, on by default), into its cascade
+layer when `cssLayers` is set. A hand import on top adds a second, unlayered
+copy that outranks your Tailwind v4 utilities. Only with `injectStyles: false`:
 
 ```ts
 import 'bitboss-ui/styles.css';
 ```
 
-Use this once in your app entry (or in Nuxt/Vite global CSS) so components match the intended look and layout.
-
 ### Vite plugin
 
 Use the Vite export to enable icon virtual modules and typed registry integration:
@@ -162,27 +195,45 @@ Use the Vite export to enable icon virtual modules and typed registry integratio
 ```ts
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import { bitbossUi } from 'bitboss-ui/vite';
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
 
 export default defineConfig({
 	plugins: [
 		vue(),
 		bitbossUi({
 			iconDir: './src/assets/icons',
+			// Tailwind v4: keep this, or your utilities on Bb* components lose to
+			// the library's CSS. Tailwind v3 or plain CSS: drop it.
+			cssLayers: TAILWIND_V4_LAYERS,
 		}),
 	],
 });
 ```
 
+**Icons, in one paragraph.** `local:` ships every SVG in `iconDir`. Provider
+icons (`lucide:*`, `tabler:*`, any installed `@iconify-json/*` set) ship only
+what the plugin finds as a `prefix:name` literal anywhere in the project — it
+reads every file under the Vite root as bytes, PHP included, skipping only
+gitignored, hidden, binary, `node_modules`/`vendor`/`storage`/`outDir` and
+`iconsScanner.exclude` paths — plus whatever you list in `iconWhitelist`
+(exact names or globs, for names composed at runtime or stored in a database).
+This holds in dev exactly as in prod: dev registers the same set and re-scans a
+file on every save. A name that does not resolve renders a built-in placeholder
+(`data-bb-icon-missing="<name>"`) and logs one error with the fix; it never
+throws. Details: `dist/ai/guides/icons-policy.md` and
+`dist/ai/guides/installation-and-plugin-setup.md` § Icons.
+
 ### Nuxt module
 
 ```ts
+import { TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
 export default defineNuxtConfig({
 	modules: ['bitboss-ui/nuxt'],
 	bitboss: {
 		iconDir: './assets/icons',
+		cssLayers: TAILWIND_V4_LAYERS, // Tailwind v4 only
 	},
-	css: ['bitboss-ui/styles.css'],
 });
 ```
 
@@ -203,7 +254,8 @@ npx bitboss-ui ai-init
 # same as: npx bitboss-ui ai-init --update
 ```
 
-Idempotently writes:
+Idempotently writes the pointer files below **and** sets up the MCP server
+(next section); `--no-mcp` skips the server:
 
 | File                                    | Harness                  |
 | --------------------------------------- | ------------------------ |
@@ -215,48 +267,48 @@ Idempotently writes:
 
 Re-run after upgrading `bitboss-ui` so versioned pointers stay fresh.
 
-### MCP server (optional)
+### MCP server
 
-The kickstart above writes static pointer files. Add `--mcp` to also register a
-live [Model Context Protocol](https://modelcontextprotocol.io) server so agents
-can **query** the knowledge base (search components, read a contract, validate
-markup) instead of reading files blind:
+Besides the static pointer files, `ai-init` registers a live
+[Model Context Protocol](https://modelcontextprotocol.io) server so agents can
+**query** the knowledge base (search components, read a contract, validate
+markup) instead of reading files blind. It is on by default; opt out with:
 
 ```bash
-npm i -D @modelcontextprotocol/sdk zod
-npx bitboss-ui ai-init --mcp
+npx bitboss-ui ai-init --no-mcp
 ```
 
-Those two are **optional peer dependencies**, not dependencies: together they
-weigh ~12 MB — more than every runtime dependency of the component library
-combined — and nothing but the MCP server loads them, so installing
-`bitboss-ui` never drags them in. `ai-init --mcp` warns if they are missing,
-and `bitboss-ui mcp` tells you what to install rather than dying on a module
-resolution error.
-
-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
+The server needs `@modelcontextprotocol/sdk` and `zod`. They are **optional
+peer dependencies**, not dependencies: together they weigh ~12 MB — more than
+every runtime dependency of the component library combined — and nothing but
+the MCP server loads them, so installing `bitboss-ui` never drags them in.
+`ai-init` installs them as dev dependencies with your package manager (npm,
+pnpm, yarn or bun, from your lockfile); if that fails it prints the command to
+run, and `bitboss-ui mcp` tells you what to install rather than dying on a
+module resolution error. `--no-mcp` skips the install too.
+
+The agent harness launches the server itself (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp`,
+the installed binary rather than `npx`, so it can never fetch from the registry, its optional
+peers resolve in your project, and it cannot drift behind an upgrade) on demand —
+you never run it by hand. `ai-init` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
 
-| File                                  | Harness           | Scope                      |
-| ------------------------------------- | ----------------- | -------------------------- |
-| `.mcp.json`                           | Claude Code       | project                    |
-| `.cursor/mcp.json`                    | Cursor            | project                    |
-| `.vscode/mcp.json`                    | VS Code / Copilot | project                    |
-| `~/.codeium/windsurf/mcp_config.json` | Windsurf          | **global (whole machine)** |
+| File               | Harness           |
+| ------------------ | ----------------- |
+| `.mcp.json`        | Claude Code       |
+| `.cursor/mcp.json` | Cursor            |
+| `.vscode/mcp.json` | VS Code / Copilot |
 
-> **Windsurf is global.** Cascade only reads one config in your home directory —
-> it has no per-project scope — so registering it affects **every** project on
-> your machine, not just this one. That is why the dev-server auto-registration
-> below deliberately skips Windsurf; only the explicit `ai-init --mcp` command
-> writes it.
+Windsurf only reads a global config in your home directory, so the server is
+not registered for it — add the same entry to
+`~/.codeium/windsurf/mcp_config.json` yourself if you use it. Its
+`.windsurf/rules` pointer is written as above.
 
-**Zero-command option (dev server):** instead of running `ai-init --mcp`, pass
+**Zero-command option (dev server):** instead of running `ai-init`, pass
 `mcp: true` to the Vite/Nuxt plugin and the dev server registers the
-project-scoped harnesses (Claude Code, Cursor, VS Code) automatically on boot —
-idempotent, and it leaves Windsurf's global config alone:
+same harnesses automatically on boot — idempotent, and it never installs
+anything (run `ai-init` once for the peers):
 
 ```ts
 bitbossUi({ iconDir: './assets/icons', mcp: true });
@@ -264,6 +316,23 @@ bitbossUi({ iconDir: './assets/icons', mcp: true });
 
 Restart your agent harness once after either path so it picks up the new server.
 
+The server's tools: `search_docs` (the section that answers a "how do I…"
+question, across every guide and component), `search_components` (empty query
+= the catalogue), `get_component` (compact: every prop, event, slot and pt
+part, plus guide sections on request; also answers for type names and for v2 /
+beta names that were renamed), `get_guide`, `get_composable`, `list_recipes` /
+`get_recipe`, `list_tokens`, `list_changes` and `validate`.
+
+### CLI commands
+
+| Command                                                                   | What it does                                                                                                             |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                               |
+| `npx bitboss-ui check [paths…] [--fix] [--json]`                          | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first. |
+| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.           |
+| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                            |
+| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                  |
+
 ### ESLint plugin
 
 `bitboss-ui/eslint-plugin` flags unknown props, unknown `v-model`s, and
@@ -321,6 +390,156 @@ migrations — a value that must move to a slot, directive, or CSS — are repor
 with a migration-guide link but left for you. Run `eslint --fix`, then the
 remaining reports are exactly the by-hand cases.
 
+#### The one v2 break a codemod cannot own: `reverse`
+
+`reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its **name** and
+inverted its **meaning** in v3. Both versions render the same default layout,
+so only explicit values moved:
+
+| v2                            | v3        |
+| ----------------------------- | --------- |
+| `:reverse="false"`            | `reverse` |
+| `reverse` / `:reverse="true"` | delete it |
+
+That is invisible to every other check — `:reverse="false"` is a declared prop,
+correctly typed, holding its own default value — and it cannot go in the
+rename table above, because the table is keyed by prop _name_: an entry for
+`reverse` would rewrite the legitimate v3 spellings too.
+
+So it has its own rule, `bitboss-ui/no-reverse-false` (in `recommended`). It
+flags only a **literal** `:reverse="false"` and offers both corrections as
+editor suggestions — a dynamic `:reverse="isRtl"` that merely evaluates false
+is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
+
+```js
+{
+	rules: {
+		'bitboss-ui/no-reverse-false': ['error', { assumeV2: true }],
+	},
+}
+```
+
+`assumeV2` is off by default because the two readings produce opposite
+layouts — turn it on only for files you know came from v2, then turn it off.
+
+#### Glyph state colours: `no-state-text-color`
+
+`bitboss-ui/no-state-text-color` flags a colour-shade text utility —
+`text-red-800`, not `text-xs` — in a toggle glyph's state entry:
+`pt:icon:errors` / `warnings` / `disabled` on `BbCheckbox`, `BbRadio`,
+`BbSwitch` and their groups, or `pt:root:<state>` on their standalone glyphs. Those states paint
+from the glyph's own `--accent`, never from `color`, so the class lands and
+paints nothing. CSS cannot let a state entry's colour win while a resting
+`pt:icon` colour loses — both are just a `color` utility by then — so the rule
+says so where the class is written, and for errors and warnings offers the
+spelling that works:
+
+```vue
+<!-- warns: paints nothing -->
+<BbCheckbox pt:icon="text-blue-500" pt:icon:errors="text-red-800" />
+<!-- blue at rest, red-800 while erroring -->
+<BbCheckbox
+	pt:icon="text-blue-500"
+	pt:icon:errors="[--accent:var(--color-red-800)]"
+/>
+```
+
+It reads literal classes only (the attribute, a bound string or `{ class }`,
+and a literal `:pt` object); a dynamic value is not checked.
+
+#### Field box borders: `no-box-border-color`
+
+`bitboss-ui/no-box-border-color` flags a colour-shade border utility —
+`border-green-500`, not `border-2` — in the **base** `pt:box` of a text-like
+control. The box paints its errors / warnings frame over the resting border,
+but a border utility sets `border-color` itself and wins, so the field keeps
+looking valid. The rule suggests the resting-border token instead; a state
+entry is the state itself and is never reported:
+
+```vue
+<!-- errors: hides the error frame -->
+<BbTextInput pt:box="border-green-500" />
+<!-- green at rest, the error frame while erroring, red-800 as the error style -->
+<BbTextInput
+	pt:box="[--border-color:var(--color-green-500)]"
+	pt:box:errors="border-red-800"
+/>
+```
+
+#### Nameless controls: `require-accessible-name`
+
+`bitboss-ui/require-accessible-name` flags an icon-only `BbButton` with no
+words (no default-slot content, no `text`, no `aria-label` / `aria-labelledby`
+/ `title`), an icon-only `BbBadge` with an empty default slot (its label), and
+a `BbProgress` with no `label`: all three render with no accessible name. Put the words in the slot; with `icon` set they are visually hidden and
+still name the button:
+
+```vue
+<BbButton icon="lucide:trash">Elimina</BbButton>
+<BbProgress label="Upload" :model-value="progress" />
+```
+
+`BbSpinner` is not covered: without `label` it is decorative, which is correct.
+For raw HTML controls, use `eslint-plugin-vuejs-accessibility`.
+
+#### Rating star colours: `no-star-color`
+
+`bitboss-ui/no-star-color` flags any colour utility in `BbRating`'s `pt:item`,
+in the base entry or any state: `text-*`, `fill-*` and `stroke-*`, whether a
+shade (`text-amber-500`), a keyword (`fill-current`), a variable
+(`text-(--bb-text-faint)`) or an arbitrary colour (`text-[#f59e0b]`). Sizes and
+widths (`text-sm`, `stroke-2`) are never reported. The rating paints each
+star's colour per state (filled, the hover preview, the error tint), and a
+colour utility beats those rules, so it looks right at rest and freezes the
+stars. The fix lives on another attribute, so the rule explains it rather
+than rewriting:
+
+```vue
+<!-- errors: no hover preview, no error tint -->
+<BbRating pt:item="text-(--bb-text-faint)" pt:item:selected="text-amber-500" />
+<!-- same look, the preview and the states keep working -->
+<BbRating
+	pt:root="[--empty:var(--bb-text-faint)] [--accent:var(--color-amber-500)]"
+/>
+```
+
+#### The one rule that reads CSS: `no-unknown-token`
+
+`bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the
+installed package does not declare, in a `<style>` block or a static
+`style="…"` attribute. It is a `warn`, like `no-unknown-event`.
+
+An invented token is not a near miss that degrades — CSS treats an undefined
+custom property as invalid-at-computed-value-time and throws away the **whole
+declaration**, so the rule silently does nothing and the element keeps whatever
+it inherited. One pilot lost a calendar grid's separators that way and read it
+as a layout bug.
+
+**A fallback disarms it**, because that is defined behaviour rather than a
+silent drop:
+
+```css
+.panel {
+	background: var(--bb-canvas); /* warns: no such token */
+	background: var(--bb-canvas, #f8fafc); /* fine: yours to define */
+}
+```
+
+The token list is read from the `dist/styles.css` you installed, so the rule
+can never claim a token is invented when your version declares it; with no
+stylesheet to read it stays silent. `allowTokens: string[]` exempts names you
+define yourself, and `stylesPath` points it at a different sheet.
+
+Remember the two tiers before reaching for a `--bb-*` name at all: `--bb-*` is
+the small global theme set, while each component declares its own **unprefixed**
+tokens (`.bb-table { --cell-h: 32px }`). A missing `--bb-*` name usually means
+the knob you want is a component token, not a gap in the library.
+
+Two sibling checks stay in `bitboss-ui check` and are deliberately **not**
+ESLint rules: the hand-rolled avatar and spinner hints. Those are guesses (a
+round `<img>` is sometimes a logo), and a lint rule that fires on correct code
+spends the trust the rest of these depend on.
+
 Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
 attribute inheritance is never flagged. Escape hatches when you do need one:
 
@@ -346,17 +565,17 @@ A standard `llms.txt` discovery file is also published at:
 
 ### Knowledge-base layout
 
-| Path                                  | Contents                                  |
-| ------------------------------------- | ----------------------------------------- |
-| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next  |
-| `dist/ai/index.md`                    | Full catalogue + agent rules              |
-| `dist/ai/components.json`             | Machine-readable API (props/events/slots) |
-| `dist/ai/<ComponentName>.md`          | Guide-first contract per component        |
-| `dist/ai/composables/<name>.md`       | Composable docs                           |
-| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                     |
-| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit |
-| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                    |
-| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (11 × 3)            |
+| Path                                  | Contents                                                                             |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next                                             |
+| `dist/ai/index.md`                    | Full catalogue + agent rules                                                         |
+| `dist/ai/components.json`             | Machine-readable API (props/events/slots)                                            |
+| `dist/ai/<ComponentName>.md`          | Guide-first contract per component                                                   |
+| `dist/ai/composables/<name>.md`       | Composable docs                                                                      |
+| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                                                                |
+| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit                                            |
+| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                                                               |
+| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (9 vue / 9 nuxt / 10 inertia; Ownership Atlas is inertia-only) |
 
 ### Package exports
 
@@ -399,7 +618,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 ## Support
 
-- **Usage and APIs:** see the [documentation](https://ui-components-docs.vercel.app/).
+- **Usage and APIs:** see the [documentation](https://ui-components.bitboss.it/).
 - **Company / licensing / commercial:** [BitBoss](https://www.bitboss.it/).
 
 ### Reporting a bug
@@ -416,9 +635,9 @@ To make a report actionable, include:
 - whether it reproduces in dev, in a production build, or only under SSR
 - the smallest component snippet that shows it
 
-v3 ships as a prerelease (`npm i bitboss-ui@alpha`). Expect breaking changes
-between alphas; each one is recorded in the migration guides under
-[`ai/guides/migration/`](ai/guides/migration/).
+v3 ships as a prerelease (`npm i bitboss-ui@beta`). Expect breaking changes
+between prereleases; each one is recorded in the migration guides under
+[`migration/v2-to-v3.md`](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/migration/v2-to-v3.md) (installed: `dist/ai/guides/migration/`).
 
 ---