create-bestax 4.2.17 → 4.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.17",
+  "version": "4.2.19",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -34,26 +34,26 @@
     "url": "https://github.com/allxsmith/bestax/issues"
   },
   "dependencies": {
-    "chalk": "^6.0.0",
+    "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "figures": "^6.1.0",
-    "fs-extra": "^11.4.0",
+    "fs-extra": "^11.4.1",
     "prompts": "^2.4.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@allxsmith/bestax-bulma": "^5.34.3"
+    "@allxsmith/bestax-bulma": "^5.44.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
-    "@playwright/test": "^1.63.0",
+    "@playwright/test": "^1.64.1",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",
     "@types/wait-on": "^5.3.4",
     "jest": "^30.2.0",
     "semver": "^7.8.5",
-    "ts-jest": "^29.4.14",
+    "ts-jest": "^29.4.15",
     "typescript": "^6.0.3",
     "wait-on": "^9.5.1"
   },
@@ -78,5 +78,5 @@
     "clean": "rimraf dist",
     "release": "npx semantic-release"
   },
-  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name (and, if that directory already holds files, confirm removing them;\n   nothing is removed until you have answered the last question)\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (the `--bulma` options below)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] -- [options]\n```\n\nPut the options after `--`. npm needs it to pass them on at all, and so does bun, whose\n`bun create` rejects short flags such as `-t` and `-y` itself. pnpm and Yarn 1 accept the options\nwith or without it.\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory name. It also becomes the `package.json`\n  name, lower-cased the way `npm init` does and without a leading `_`, since npm rejects both.\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n  `-y` never deletes files. If the target directory is not empty, the run stops, lists what is\n  there, and changes nothing; add `--overwrite` to empty it first. Earlier versions emptied the\n  directory under `-y` alone, so a script that relied on that now needs `--overwrite`.\n\n- `--overwrite` - Remove existing files if the target directory is not empty, without asking.\n  Every other flag is checked first, so a typo stops the run before anything is deleted.\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -- -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -- -y\n\n# The same with bun\nbun create bestax@latest my-app -- -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
+  "readme": "# create-bestax\n\n[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://badge.socket.dev/npm/package/create-bestax/latest)](https://socket.dev/npm/package/create-bestax/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14361/badge)](https://www.bestpractices.dev/projects/14361)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nThe scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.\n\nPart of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.\n\n## Requirements\n\n- **Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the\n  CLI exits immediately with an explicit upgrade message.\n- npm 10 or newer (ships with Node 22), or yarn/pnpm.\n\n## Usage\n\n### Quick Start\n\n```bash\n# Using npm\nnpm create bestax@latest my-app\n\n# Using npx\nnpx create-bestax@latest my-app\n```\n\n### Interactive Mode\n\nRunning without arguments will prompt you for all options:\n\n```bash\nnpm create bestax@latest\n```\n\nYou'll be asked to:\n\n1. Enter a project name or path (and, if that directory already holds files, confirm removing\n   them; nothing is removed until you have answered the last question)\n2. Select a framework (Vite or Vite + TypeScript)\n3. Choose a Bulma CSS flavor (the `--bulma` options below)\n4. Select an icon library (Font Awesome, Material Icons, etc.)\n5. Choose whether to install the bestax AI skills into `.claude/skills/`\n\nEvery prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.\n\n### Command Line Options\n\n```bash\nnpm create bestax@latest [project-directory] -- [options]\n```\n\nPut the options after `--`. npm needs it to pass them on at all, and so does bun, whose\n`bun create` rejects short flags such as `-t` and `-y` itself. pnpm and Yarn 1 accept the options\nwith or without it.\n\n**Arguments:**\n\n- `[project-directory]` - Optional project directory: a name such as `my-app`, or a path,\n  absolute or relative, such as `../apps/my-app`, whose missing folders are created. Its last\n  part is the project name, held to the same rules as a bare name. It becomes the page title as\n  typed, and the `package.json` name lower-cased the way `npm init` does and without a leading\n  `_`, since npm rejects both. A path ending in `.` or `..` is refused, like a bare `.` or `..`,\n  so name the directory you want.\n\n**Options:**\n\n- `-t, --template <template>` - Template to use: `vite` or `vite-ts`  \n  **Default:** `vite`\n- `-b, --bulma <flavor>` - Bulma CSS flavor:\n  - `complete` - Full Bulma CSS with all components and helpers\n  - `prefixed` - Prefixed version for compatibility\n  - `no-helpers` - Without helper classes\n  - `no-helpers-prefixed` - Prefixed without helpers\n  - `no-dark-mode` - Without dark mode support  \n    **Default:** `complete`\n- `-i, --icon <library>` - Icon library:\n  - `none` - No icon library\n  - `fontawesome` - Font Awesome\n  - `mdi` - Material Design Icons\n  - `ionicons` - Ionicons\n  - `material-icons` - Material Icons\n  - `material-symbols` - Material Symbols  \n    **Default:** `none`\n- `--skills` / `--no-skills` - Install (or skip) the bestax AI skills into\n  `.claude/skills/` (with a `CLAUDE.md`) so a Claude Code session picks them up\n  automatically. When omitted you're prompted; with `-y` the default is to install.\n- `-y, --yes` - Skip prompts and use defaults or provided options.  \n  When used, the following defaults are selected unless overridden by flags:\n  - Template: `vite`\n  - Bulma flavor: `complete`\n  - Icon library: `none`\n  - AI skills: installed (pass `--no-skills` to opt out)\n\n  `-y` never deletes files. If the target directory is not empty, the run stops, lists what is\n  there, and changes nothing; add `--overwrite` to empty it first. Earlier versions emptied the\n  directory under `-y` alone, so a script that relied on that now needs `--overwrite`.\n\n- `--overwrite` - Remove existing files if the target directory is not empty, without asking.\n  Every other flag is checked first, so a typo stops the run before anything is deleted. It\n  never empties the current directory or a folder that holds it, however the path is written.\n\n**Example:**\n\n```bash\n# Create a TypeScript project with Font Awesome icons\nnpm create bestax@latest my-app -- -t vite-ts -i fontawesome -b complete\n\n# Use all defaults (skip prompts)\nnpm create bestax@latest my-app -- -y\n\n# Scaffold into a path; the package is named my-app\nnpm create bestax@latest ../apps/my-app -- -y\n\n# The same with bun\nbun create bestax@latest my-app -- -y\n```\n\n## Templates\n\nAvailable templates:\n\n- `vite` - Vite + JavaScript\n- `vite-ts` - Vite + TypeScript\n\nEach template includes:\n\n- Pre-configured bestax-bulma integration (React 19)\n- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically\n- Icon library support (Font Awesome, Material Design, etc.)\n- Sample components demonstrating library usage\n- Development and build scripts\n\n## For AI Tools\n\nScaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax\nAgent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot\nbuild the bestax way from the start. The library also ships LLM-optimized docs:\n\n- [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot\n- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions\n- [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)\n\n## Development\n\n```bash\nnpm run build    # Build the CLI\nnpm run dev      # Watch mode\nnpm test         # Run tests\nnpm run lint     # Lint CLI source code\nnpm run typecheck # Type check CLI source code\n```\n\n**Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing.\n\n## Hardened by default\n\nA scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI.\n- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`create-bestax` can send one **anonymous** usage event after a successful\nscaffold — only if you opt in when asked (once, at the end of a scaffold). The\nevent is just the choices you made — template, Bulma flavor, icon library,\nskills, package manager — plus the CLI version, Node major version, and OS\nplatform; never names, IPs, machine IDs, paths, or file contents, and no\nidentifier exists that could link two events together. Opt out any time with\n`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## Publishing\n\nThis package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.\n"
 }

package/templates/skills/bestax-custom-component/references/component-catalog.md

@@ -37,7 +37,7 @@ instead of hand-writing markup.
 - Raw `*Base` form exports (`InputBase`, `SelectBase`, `TextAreaBase`, …) are
   escape-hatch variants of the convenience wrappers above them; see the Form docs.
 
-100 documented components. Generated from the API docs — every exported
+104 documented components. Generated from the API docs — every exported
 component is guaranteed to appear (the generator fails if one lacks an API page).
 
 ## Elements
@@ -104,14 +104,17 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [Sidebar](https://bestax.io/docs/api/components/sidebar) — The `Sidebar` component provides a slide-out navigation panel that appears from the left or right side of the screen.
 - [Steps](https://bestax.io/docs/api/components/steps) — The `Steps` component provides a multi-step progress indicator for wizard flows, checkout processes, or any multi-step workflow.
 - [Tabs](https://bestax.io/docs/api/components/tabs) — The `Tabs` component provides flexible and fully-featured Bulma tab navigation for your Bulma React UI.
+- [Timeline](https://bestax.io/docs/api/components/timeline) — The `Timeline` component renders a list of events in the order they happened, each with a marker on a line down the side.
 - [Toast](https://bestax.io/docs/api/components/toast) — The `Toast` component provides brief notification messages with optional action and cancel buttons.
 - [Tooltip](https://bestax.io/docs/api/components/tooltip) — The `Tooltip` component displays helpful information when users hover over or focus on an element.
+- [TreeView](https://bestax.io/docs/api/components/treeview) — The `TreeView` component renders a tree of items you browse and pick from, the way a file explorer works: one tab stop, the arrow keys to move…
 
 ## Form
 
 - [Autocomplete](https://bestax.io/docs/api/form/autocomplete) — The `Autocomplete` component provides an input field with dropdown suggestions that filter based on user input.
 - [Checkbox](https://bestax.io/docs/api/form/checkbox) — The `Checkbox` component provides a Bulma-styled checkbox input.
 - [Checkboxes](https://bestax.io/docs/api/form/checkboxes) — The `Checkboxes` component wraps multiple `Checkbox` components in a Bulma-styled group.
+- [Combobox](https://bestax.io/docs/api/form/combobox) — The `Combobox` component is a text field with a list to pick from under it, for a searchable select, a multi-select with tags, grouped items or a server search…
 - [Control](https://bestax.io/docs/api/form/control) — The `Control` component is a Bulma-styled wrapper for form controls (`Input`, `Select`, `TextArea`, etc.), supporting icons (left/right), loading state…
 - [DateInput](https://bestax.io/docs/api/form/datetime/dateinput) — The `DateInput` component is a form input that opens a popover calendar for date selection.
 - [DateRangeInput](https://bestax.io/docs/api/form/datetime/daterangeinput) — The `DateRangeInput` component is a form input for a start and end date, picked from one popover calendar or typed into two segmented inputs.
@@ -120,6 +123,7 @@ component is guaranteed to appear (the generator fails if one lacks an API page)
 - [File](https://bestax.io/docs/api/form/file) — The `File` component provides a Bulma-styled file input, supporting color, size, boxed/fullwidth/align styles, icons, "has name", and filename display.
 - [Input](https://bestax.io/docs/api/form/input) — The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static state, hover/focus/loading states…
 - [Numberinput](https://bestax.io/docs/api/form/numberinput) — The `Numberinput` component provides a number input with increment/decrement buttons.
+- [PinInput](https://bestax.io/docs/api/form/pininput) — The `PinInput` component is a field for a short code, such as a one-time code or a PIN, drawn as a row of boxes with one character in each.
 - [Radio](https://bestax.io/docs/api/form/radio) — The `Radio` component provides a Bulma-styled radio button input with flexible labels and helper classes.
 - [Radios](https://bestax.io/docs/api/form/radios) — The `Radios` component wraps multiple `Radio` components in a Bulma-styled group.
 - [Rate](https://bestax.io/docs/api/form/rate) — The `Rate` component provides a star/icon-based rating system.

package/templates/skills/bestax-form/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bestax-form
-description: Build forms with @allxsmith/bestax-bulma — Field/Control/Label/Help composition, inputs, selects, checkboxes, radios, switches, and advanced controls (Autocomplete, Slider, Numberinput, Rate, Taginput, File, date/time). There is no form/validation library; this skill shows the components and the validate-it-yourself error pattern. Use when building a form, wiring inputs to state, or showing validation/error state.
+description: Build forms with @allxsmith/bestax-bulma — Field/Control/Label/Help composition, inputs, selects, checkboxes, radios, switches, and advanced controls (Autocomplete, Combobox, Slider, Numberinput, PinInput, Rate, Taginput, File, date/time). There is no form/validation library; this skill shows the components and the validate-it-yourself error pattern. Use when building a form, wiring inputs to state, or showing validation/error state.
 license: MIT
 ---
 
@@ -65,7 +65,7 @@ using context (`useInsideField` / `useInsideControl`) to detect their surroundin
 ```tsx
 <Field hasAddons>
   <Control isExpanded>
-    <InputBase placeholder="Search" />
+    <InputBase placeholder="Search" aria-label="Search" />
   </Control>
   <Control>
     <Button color="primary">Go</Button>
@@ -73,6 +73,10 @@ using context (`useInsideField` / `useInsideControl`) to detect their surroundin
 </Field>
 ```
 
+A `grouped` or `hasAddons` Field names none of its controls, and a placeholder disappears once
+the user types, so give each input in the row an `aria-label`, or a visible label on an outer
+`Field` (`references/patterns.md`, "Grouped controls and addons").
+
 ## Component inventory
 
 All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Field+Control;
@@ -89,9 +93,11 @@ All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Fiel
 | `Radio` / `Radios`                                      | Single radio / managed single-select group.                               |
 | `Switch`                                                | Toggle switch (`isRounded`, `isThin`, `isOutlined`, RTL).                 |
 | `File`                                                  | File upload input with label/message.                                     |
-| `Autocomplete`                                          | Input with filtered dropdown suggestions + keyboard nav.                  |
+| `Autocomplete`                                          | Free text with suggestions it filters for you, + keyboard nav.            |
+| `Combobox`                                              | A value from a list: `data` for a select, tags or groups, or parts.       |
 | `Slider`                                                | Range slider; single/dual thumbs, steps, tooltips, vertical.              |
 | `Numberinput`                                           | Numeric input with increment/decrement, min/max, step, stepper.           |
+| `PinInput`                                              | A one-time code or PIN as a row of boxes, all in one real input.          |
 | `Rate`                                                  | Star rating; `max`, `precision` (half/quarter), custom icons, `disabled`. |
 | `Taginput`                                              | Tag/chip input; suggestions, confirm keys, closable tags.                 |
 | `DateInput` / `TimeInput` / `DateTimeInput` (+ `*Base`) | Date / time / datetime pickers; month or year via `granularity`.          |
@@ -100,6 +106,27 @@ All import from `@allxsmith/bestax-bulma`. Convenience components auto-wrap Fiel
 (`NumberInput` and `TagInput` also exist as deprecated aliases of `Numberinput`/`Taginput` —
 same components; prefer the lowercase-second-word spellings.)
 
+**Autocomplete or Combobox?** A field whose text is the value, with suggestions to help type it,
+is `Autocomplete`, which filters its `data` itself. A value picked from a list is `Combobox`. Given
+`data`, it filters by label, keeps the value (`value`/`onChange`) and shows the picks as tags with
+`multiple`, so a searchable select, a multi-select or a grouped list is one element. Build it from
+parts for a server search whose answer must show unfiltered, or a "Create" item: then it keeps no
+value and never sets the field's text, so you filter the items, keep the value and set the text in
+`onSelect`.
+
+**A verification code or a PIN is `PinInput`**, not a row of one-character `Input`s with focus
+moved by hand. It holds the code in one real input under a row of boxes, so a screen reader hears
+one field named by its `label`, and paste, autofill from a text message (`autoComplete` is
+`"one-time-code"`) and password managers work as they do on any input. Give it `length` (6 by
+default), `value`/`onChange` with the code as a string, and verify in `onComplete`, which fires
+once each time a change fills the last box. It takes digits unless `type="alphanumeric"`, turns a
+digit from any script (Arabic-Indic, Persian) into its ASCII digit, drops anything else typed or
+pasted, and `isMasked` shows dots for a PIN. A paste replaces the whole code. Its default `pattern`
+asks for the full length, so `required` rejects a partial code, not just an empty one. Say the
+length in the `label` ("Enter the 6-digit code"): the boxes are hidden from a screen reader, and the
+`message` isn't tied to the input, so it isn't read on focus. Separate help text needs
+`aria-describedby` on the PinInput.
+
 ## Common props
 
 Across the convenience inputs (`Input`, `Select`, `TextArea`, and similar):
@@ -126,13 +153,15 @@ spellings compile only where they historically existed: `isFullWidth` everywhere
 `Sidebar`, `fullwidth` on `Tabs` only, `fullWidth` on `Sidebar` only.
 
 **Labels.** Default to the convenience `label` prop, with `horizontal` for a side-by-side row.
-`Input`, `Select`, `TextArea`, `File`, `Numberinput`, `Slider`, `DateInput`, `TimeInput`,
-`DateTimeInput`, `Autocomplete` and `Taginput` then render the `Field` and the label and wire
-`htmlFor`/`id`, to your `id` when you pass one (`<Input label="Email" id="email" horizontal />`);
-an explicit `labelProps={{ htmlFor }}` wins. The group inputs (`Checkboxes`, `Radios`, `Rate`,
-`DateRangeInput`) name their `role="group"`/`"radiogroup"` wrapper through `aria-labelledby`
-instead. Inside a `Field` a convenience input drops its `label`, and an `inline` date/time picker
-or a `Taginput` at `maxTags` has no visible input to wire.
+`Input`, `Select`, `TextArea`, `File`, `Numberinput`, `PinInput`, `Slider`, `DateInput`,
+`TimeInput`, `DateTimeInput`, `Autocomplete` and `Taginput` then render the `Field` and the label
+and wire `htmlFor`/`id`, to your `id` when you pass one
+(`<Input label="Email" id="email" horizontal />`); an explicit `labelProps={{ htmlFor }}` wins. `Combobox` renders its `Field` and label too, and wires
+them to its field. Given `data`, its `id`, `aria-label` and `aria-labelledby` go to the field;
+built from parts, put them on `Combobox.Input`, since on the `Combobox` they land on its wrapper
+`div`. The group inputs (`Checkboxes`, `Radios`, `Rate`, `DateRangeInput`) name their
+`role="group"`/`"radiogroup"` wrapper through `aria-labelledby` instead. Inside a `Field` a
+convenience input drops its `label`, and an `inline` date/time picker has no visible input to wire.
 
 Composed, a labeled `Field` names the one control it holds: a composed `InputBase`/`SelectBase`/
 `TextAreaBase`, a composed `DateInputBase`/`TimeInputBase`/`DateTimeInputBase` that is not
@@ -148,9 +177,9 @@ unmatched `for` out of server-rendered HTML.
 
 A `range` `Slider` points the `for` at its low thumb and starts both thumbs' names with the label
 ("Price range Minimum value"); its `ariaLabel={[low, high]}` replaces those names outright, so
-leave it off when a label already names the Slider. Those thumbs and an `Autocomplete`'s or
-`Taginput`'s suggestion list point `aria-labelledby` at the label's `id`, which a label wired by
-hand has only when you pass one, `labelProps={{ htmlFor, id }}`; without it they keep their
+leave it off when a label already names the Slider. Those thumbs and an `Autocomplete`'s, a
+`Combobox`'s or a `Taginput`'s list point `aria-labelledby` at the label's `id`, which a label
+wired by hand has only when you pass one, `labelProps={{ htmlFor, id }}`; without it they keep their
 fallback names ("Minimum value"/"Maximum value", "Suggestions"). A `<label htmlFor>` you put in
 `Field.Label` yourself (`references/patterns.md`) names its control through the `for` alone, so
 label a row holding either with the `Field`'s `label` prop. An `aria-label` or `aria-labelledby`
@@ -239,9 +268,9 @@ multi-field form plus the advanced inputs.
 
 ## Reuse the shipped components
 
-bestax ships the whole form surface — Input, Select, TextArea, Checkbox(es), Radio(s), Switch,
-File, Autocomplete, Slider, Numberinput, Rate, Taginput, and the date/time inputs (see the
-inventory above). **Compose these; don't hand-roll raw `<input class="input">` markup or
+bestax ships the whole form surface — Input, Select, TextArea, Checkbox(es), Radio(s), Switch, File,
+Autocomplete, Combobox, Slider, Numberinput, PinInput, Rate, Taginput, and the date/time inputs (see
+the inventory above). **Compose these; don't hand-roll raw `<input class="input">` markup or
 reinvent a control.** If you think a control is missing, check `bulma-ui/src/index.ts` and
 `docs/docs/api/form/` first — it's probably already there under a different name.
 

package/templates/skills/bestax-form/references/api.md

@@ -19,7 +19,7 @@ Container and layout. Compound parts: `Field.Label`, `Field.Body`.
 | `labelProps`            | label attributes                                  | Props for the `<label>`. An explicit `htmlFor` (even `undefined`) takes over the association; otherwise it is set automatically. For its `id`, see below.                                                                          |
 | `textColor` / `bgColor` | Bulma color                                       | Helper colors for the field.                                                                                                                                                                                                       |
 
-An `id` in `labelProps` is what a group's, a range `Slider`'s and an `Autocomplete` or `Taginput` suggestion list's `aria-labelledby` points at. A label wired by hand with `htmlFor` gets no generated id, so give it one, `labelProps={{ htmlFor, id }}`, for a range `Slider`, an `Autocomplete` or a `Taginput`. No group points at a label wired by hand.
+An `id` in `labelProps` is what a group's, a range `Slider`'s and an `Autocomplete`'s, a `Combobox`'s or a `Taginput`'s list's `aria-labelledby` points at. A label wired by hand with `htmlFor` gets no generated id, so give it one, `labelProps={{ htmlFor, id }}`, for a range `Slider`, an `Autocomplete`, a `Combobox` or a `Taginput`. No group points at a label wired by hand.
 
 ## Control — `form/Control.tsx`
 
@@ -70,6 +70,9 @@ Field/Control/message props. `TextArea` adds `rows` and `hasFixedSize`.
 
 - `Checkbox` / `Radio` — single controls with `color`, `size`, `checked`/`defaultChecked`,
   `onChange`, `disabled`.
+- `Checkbox` also takes `indeterminate`, the mixed state of a "Select all" box over a partly
+  checked list. It changes the look and the announcement, not the value: `checked` stays the
+  value, so set both from the list.
 - `Checkboxes` — group wrapper managing an **array** value.
 - `Radios` — group wrapper managing a **single** selected value.
 
@@ -84,13 +87,15 @@ File input with `label`, `message`, color/size, and icon support.
 
 ## Advanced inputs
 
-| Component      | Key props                                                                                                                                                                                                                                                 |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Autocomplete` | `data` (`string[]` or item objects), `value`, `onInput(value)` for typing, `onSelect(item)` for picks, `clearable` (the clear button hides while `loading`, or a loading `Control` around it, puts a spinner at the same edge), `openOnFocus`, `loading`. |
-| `Slider`       | `min`, `max`, `step`, single or dual thumb (`value` number or `[number, number]`), `tooltip` (`'auto' \| 'always' \| 'hidden'`), vertical orientation, `color`, `size`.                                                                                   |
-| `Numberinput`  | `value`/`onChange`, `min`, `max`, `step`, increment/decrement buttons, stepper variant, `color`, `size`, `isLoading` (set it here, not on a `Control` around it, whose spinner covers the right-hand button).                                             |
-| `Rate`         | `value`/`onChange`, `max`, `precision` (1 / 0.5 / 0.25), `customIcon` or `iconName`, `showScore`/`showText`/`texts`, `disabled`.                                                                                                                          |
-| `Taginput`     | `value` (array)/`onChange`, autocomplete suggestions, configurable confirm keys, closable tags, `color`, `size`.                                                                                                                                          |
+| Component      | Key props                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Autocomplete` | `data` (`string[]` or item objects), `value`, `onInput(value)` for typing, `onSelect(item)` for picks, `clearable` (the clear button hides while `loading`, or a loading `Control` around it, puts a spinner at the same edge), `openOnFocus`, `loading`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `Combobox`     | Either way: `multiple`, `keepFirst`, `inline`, `size`, `position` (`'auto'` keeps the list in the viewport), `appendToBody` (in a `Modal`, point a `ConfigProvider`'s `portalContainer` inside the modal), `open`/`defaultOpen`/`onOpenChange`, `onSelect(value)` and the Field props. Given `data` (strings or `{ value, label?, disabled?, group? }`): `value`/`defaultValue`/`onChange` (`string \| null`, or `string[]` with `multiple`, shown as tags), `placeholder`, `name`, `empty`, `itemTemplate`, and `disabled`, `required`, `form`, `id`, `aria-label`/`aria-labelledby` for the field; leaving the field empty clears one value. From parts: `.Input` (an `Input`, with `size` and the Field props on the root), `.Menu`, `.List`, `.Item` (`value`, `checked`, `disabled`), `.Group` (`label`), `.Empty`; you filter, keep the value and set the field's text in `onSelect`. |
+| `Slider`       | `min`, `max`, `step`, single or dual thumb (`value` number or `[number, number]`), `tooltip` (`'auto' \| 'always' \| 'hidden'`), vertical orientation, `color`, `size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Numberinput`  | `value`/`onChange`, `min`, `max`, `step`, increment/decrement buttons, stepper variant, `color`, `size`, `isLoading` (set it here, not on a `Control` around it, whose spinner covers the right-hand button).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `PinInput`     | `length` (6), `value`/`defaultValue`/`onChange` (the code as a string), `onComplete(code)` once a change fills the last box, `type` (`'number'` or `'alphanumeric'`), `isMasked`, `name`, `color`, `size`, `isRounded`, `disabled` and the Field props. One input holds the code (`autoComplete="one-time-code"`); a paste replaces it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `Rate`         | `value`/`onChange`, `max`, `precision` (1 / 0.5 / 0.25), `customIcon` or `iconName`, `showScore`/`showText`/`texts`, `disabled`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `Taginput`     | `value` (array)/`onChange`, autocomplete suggestions, configurable confirm keys, closable tags, `color`, `size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Date / time inputs
 

package/templates/skills/bestax-form/references/patterns.md

@@ -131,7 +131,7 @@ Notes:
 // Search box: input + button attached.
 <Field hasAddons>
   <Control isExpanded>
-    <InputBase placeholder="Search" />
+    <InputBase placeholder="Search" aria-label="Search" />
   </Control>
   <Control>
     <Button color="primary">Search</Button>
@@ -141,14 +141,18 @@ Notes:
 // Two controls on one row.
 <Field grouped>
   <Control>
-    <InputBase placeholder="First" />
+    <InputBase placeholder="First" aria-label="First name" />
   </Control>
   <Control>
-    <InputBase placeholder="Last" />
+    <InputBase placeholder="Last" aria-label="Last name" />
   </Control>
 </Field>
 ```
 
+A `grouped` or `hasAddons` Field names none of the controls it holds, and a placeholder
+disappears once the user types, so each input above carries an `aria-label`. For a visible
+label instead, see the last item below.
+
 Recipes built on addons, each written out in full in the docs:
 
 - **Password reveal** ([docs](https://bestax.io/docs/api/form/input#password-reveal)): the
@@ -210,6 +214,60 @@ const [city, setCity] = useState('');
   openOnFocus
 />;
 
+// Combobox: a value from a list. Given data, it filters by label, keeps the
+// value and shows its label in the field.
+const [country, setCountry] = useState<string | null>(null);
+<Combobox
+  label="Country"
+  data={['Canada', 'France', 'Japan']}
+  value={country}
+  onChange={setCountry}
+  empty="No countries match"
+/>;
+
+// Several values, shown as tags under the field; groups come from `group`.
+const [labels, setLabels] = useState<string[]>([]);
+<Combobox
+  label="Labels"
+  multiple
+  data={[
+    { value: 'bug', label: 'Bug', group: 'Type' },
+    { value: 'docs', label: 'Docs', group: 'Area' },
+  ]}
+  value={labels}
+  onChange={setLabels}
+/>;
+
+// From parts, when data doesn't fit (a server search, a "Create" item): you
+// filter, keep the value and set the text, and a pick calls onSelect.
+const countries = ['Canada', 'France', 'Japan'];
+const [choice, setChoice] = useState<string | null>(null);
+const [query, setQuery] = useState('');
+const term = query === choice ? '' : query.trim().toLowerCase();
+const matches = countries.filter(c => c.toLowerCase().includes(term));
+<Combobox
+  label="Country"
+  onSelect={picked => {
+    setChoice(picked);
+    setQuery(picked);
+  }}
+>
+  <Combobox.Input value={query} onChange={e => setQuery(e.target.value)} />
+  <Combobox.Menu>
+    {matches.length > 0 ? (
+      <Combobox.List>
+        {matches.map(c => (
+          <Combobox.Item key={c} value={c} checked={c === choice}>
+            {c}
+          </Combobox.Item>
+        ))}
+      </Combobox.List>
+    ) : (
+      <Combobox.Empty>No countries match</Combobox.Empty>
+    )}
+  </Combobox.Menu>
+</Combobox>;
+
 // Slider (single and dual thumb)
 const [volume, setVolume] = useState(50);
 <Slider value={volume} onChange={setVolume} min={0} max={100} tooltip="auto" />;
@@ -229,6 +287,20 @@ const [range, setRange] = useState<[number, number]>([20, 80]);
 const [qty, setQty] = useState(1);
 <Numberinput value={qty} onChange={setQty} min={1} max={10} step={1} />;
 
+// PinInput: a one-time code or PIN, a box per character, all in one input.
+// onComplete fires once each time a change fills the last box.
+const [code, setCode] = useState('');
+const verify = (otp: string) => {
+  // Send it to your server, then show the result with color and message.
+};
+<PinInput
+  label="Enter the 6-digit code"
+  name="otp"
+  value={code}
+  onChange={setCode}
+  onComplete={verify}
+/>;
+
 // Rate
 const [stars, setStars] = useState(3);
 <Rate value={stars} onChange={setStars} max={5} />;

package/templates/skills/bestax-layout-scaffold/SKILL.md

@@ -97,6 +97,31 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   "Clear search" put focus back in the field. While data loads show a `Skeleton` or a `Loader`,
   and a failed load is a `Message` or a `Notification`, never an EmptyState. The archetypes
   reference has the full pattern under Card grid.
+- **An order's history, a ticket's activity, a changelog or an activity feed is `Timeline`**,
+  not a hand-built list with a border down the side: `<Timeline titleAs="h3">` with a
+  `<Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14">` per event, any
+  detail as its children, and the whole date in `time`. `titleAs` is the level under the
+  section's heading, or `"p"` in a busy feed. For something that moves along on its own, like a
+  parcel or a deployment, `active={i}` marks progress and `pending="Out for delivery"` ends it on
+  what's under way, oldest first. A journey the user moves through, like a wizard or a checkout,
+  stays `Steps`.
+- **A file browser, a checkbox tree (permissions, filters) or an outline you browse is
+  `TreeView`**, with `<TreeView.Item value="…" label="…" icon="folder">` items nested inside each
+  other: `<TreeView aria-label="Files" selectionMode="single">` with `selected`/`onSelectedChange`
+  picks one, and `selectionMode="checkbox"` with `checked`/`onCheckedChange` draws boxes with
+  mixed parents, where a parent's value checks its whole branch. Map the data with a recursive
+  function, and render an item's children whether it's open or not. A folder that loads when it
+  opens takes `hasChildren`, `isLoading` while its children are on their way, and
+  `loadError="Couldn't load src"` with `onRetry` when the load fails, setting `isLoading` again
+  while the retry runs: the tree draws the Loading… and Retry rows and announces them, so don't
+  hand-write a placeholder item. Its items aren't
+  links, so the app's sidebar and any list of pages stay on `Menu` with `Menu.Item href`.
+- **A sidebar whose groups of links open and close is `Menu.Section`**, one per group, directly
+  in `Menu` (never inside a `Menu.Item` or `Menu.List`):
+  `<Menu.Section label="Components" defaultOpen>` around that group's `Menu.List`, with
+  `defaultOpen` on the group holding the current page (or `open`/`onOpenChange` to hold the state).
+  Its heading is a real button with `aria-expanded`, and its links stay links, each a tab stop.
+  Not `TreeView`, and not a `Collapse` inside a hand-written `<li>`.
 - Link lists (footer nav, sidebars): a bare `UnorderedList` of `ListItem`s is already
   marker-less and flush — Bulma's reset unstyles `ul` — so no prop or CSS is needed;
   bullets appear only inside `Content`.
@@ -152,9 +177,10 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi
   (`Hero color="primary"`, a dark banner), use **filled** buttons — `color="light"` or
   `color="primary" isInverted` — never a thin `isOutlined` secondary: a light outline + light
   label on a dark surface is low-contrast and gets worse under OS dark mode. And when the page's
-  design is single-mode (a fixed light or dark look), pin it at the root —
-  `<Theme isRoot colorMode="light">` — so a visitor's OS dark mode can't flip Bulma's text
-  colors out from under the fixed palette (details: the `bestax-theming` skill's contrast rules).
+  design is single-mode (a fixed light or dark look), pin it on the `<html>` in `index.html`,
+  `<html lang="en" data-theme="light">`, so a visitor's OS dark mode can't flip Bulma's text
+  colors out from under the fixed palette, from the first paint on (details: the
+  `bestax-theming` skill's contrast rules).
 
 ## Three components core Bulma will talk you out of
 
@@ -199,9 +225,11 @@ background comes from the semantic `color` prop, not `bgColor`.
 | `display: 'none'`                        | `visibility="hidden"`, or responsive `display*` props (`displayMobile`, `displayTablet`, …)                                                                    |
 | `gap: '1rem'` (flex or grid)             | `gap="2"`, or one axis: `columnGap`, `rowGap`; gap scale: `1`=0.5rem, `2`=1rem, `4`=2rem, half steps (`"1.5"`)                                                 |
 
-No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project
-stylesheet (`src/App.css` in a scaffolded app) and pass it via `className` — still never
-inline `style`.
+No helper matches (e.g. `maxWidth`, a one-off gradient)? Add a named class to the project's
+global stylesheet and pass it via `className` — still never inline `style`. In a create-bestax
+app that is `src/index.css`, which its entry file imports after bestax's stylesheet, so the
+class wins over a Bulma rule of the same weight. The starter page's `src/App.css` loads after
+bestax's too, but only while the starter's `App` imports it.
 
 ## References
 

package/templates/skills/bestax-layout-scaffold/references/archetypes.md

@@ -164,8 +164,8 @@ style, so bands cost zero custom CSS. The same values work on `Hero` (and its
 **Hero CTAs:** on a colored hero use **filled** buttons only — `color="light"` for the primary
 CTA and `color="primary" isInverted` (solid white, primary text) for a secondary. A thin
 `isOutlined` button on a fixed-color surface is low-contrast and degrades further under OS dark
-mode. Single-mode page designs should also pin the scheme at the root
-(`<Theme isRoot colorMode="light">`) — see the `bestax-theming` skill's contrast rules.
+mode. Single-mode page designs should also pin the scheme on the `<html>` in `index.html`
+(`<html lang="en" data-theme="light">`); see the `bestax-theming` skill's contrast rules.
 
 ---
 

package/templates/skills/bestax-layout-scaffold/references/layout-components.md

@@ -39,12 +39,16 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 
 | Prop                              | Type                                    | Notes                                     |
 | --------------------------------- | --------------------------------------- | ----------------------------------------- |
+| `as`                              | `'div'` (default) or a landmark tag     | Renders that tag in place of the `div`.   |
 | `fluid`                           | `boolean`                               | Full width with a small gutter.           |
 | `widescreen` / `fullhd`           | `boolean`                               | Only constrain at that breakpoint and up. |
 | `breakpoint`                      | `'tablet' \| 'desktop' \| 'widescreen'` | Max-width breakpoint.                     |
 | `isMax`                           | `boolean`                               | Use the `is-max-*` width.                 |
 | `color` / `textColor` / `bgColor` | Bulma color                             | —                                         |
 
+`as` takes `'main' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'nav'`, so
+`<Container as="main">` renders `<main class="container">` with no wrapper.
+
 ## Section
 
 `<Section>` adds vertical page rhythm (padding).
@@ -63,6 +67,7 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 | `color`                | `primary \| link \| info \| success \| warning \| danger \| black \| white \| light \| dark` (CSS-backed). Also accepted but deprecated, no CSS, dev-warn: every other `validColors` member, plus `inherit` and `current` |
 | `size`                 | `'small' \| 'medium' \| 'large' \| 'fullheight' \| 'fullheight-with-navbar'`                                                                                                                                              |
 | `fullheightWithNavbar` | `boolean`                                                                                                                                                                                                                 |
+| `as`                   | `'section'` (default) \| `'div'` \| `'main'` \| `'header'` \| `'footer'` \| `'article'` \| `'aside'`                                                                                                                      |
 
 ```tsx
 <Hero color="primary" size="medium">
@@ -70,6 +75,11 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te
 </Hero>
 ```
 
+`Hero.Head` takes `as="header"` or `as="nav"` and `Hero.Foot` `as="footer"` or `as="nav"` (both
+`div` by default), so a page that is all hero is `<Hero as="main">` with no wrapper. A `header` or
+`footer` is the page's banner or footer landmark only outside a `section`, `article`, `aside`,
+`nav` or `main`, so for that render the hero itself `as="div"`.
+
 ## Footer
 
 `<Footer>` is the page footer.
@@ -230,6 +240,8 @@ flexDirection="column"` + `flexGrow="1"` pattern applies to `Cell` + `Card`.
 | --------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `fixed`         | `'top' \| 'bottom'`                                                                                              |
 | `transparent`   | `boolean`                                                                                                        |
+| `isSpaced`      | `boolean` (Bulma's `is-spaced`, from desktop up)                                                                 |
+| `hasShadow`     | `boolean` (default `false`, unlike `Card`'s; Bulma's `has-shadow`)                                               |
 | `color`         | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'black' \| 'dark' \| 'light' \| 'white'` |
 | `Navbar.Item`   | `as?`, `active?`, `href`                                                                                         |
 | `Navbar.Burger` | `active?`, `onClick`                                                                                             |
@@ -239,7 +251,12 @@ The burger/menu is controlled state — toggle `Navbar.Burger active`/`onClick`
 flag to `Navbar.Menu active`. **A `fixed="top"` navbar requires `has-navbar-fixed-top` on `<html>`**
 (Bulma offsets the page from it); the library adds no helper. Set it statically —
 `<html class="has-navbar-fixed-top">` in `index.html` — reserving a `classList.add` effect for
-a navbar that mounts conditionally.
+a navbar that mounts conditionally. **With `isSpaced`, add `has-spaced-navbar-fixed-top` too**
+(`<html class="has-navbar-fixed-top has-spaced-navbar-fixed-top">`): from desktop up the spaced
+navbar is taller than the plain class pads the page for, and there the spaced class pads it for
+the taller navbar, so with the plain class alone the top of the page sits under the navbar. A
+`fixed="bottom"` navbar takes `has-navbar-fixed-bottom`, and `has-spaced-navbar-fixed-bottom`
+beside it with `isSpaced`.
 
 **Routing:** in a routed app, don't use `href="#"` — render items as the router's link
 component. `Menu.Item as={Link} to="/x"` and `Navbar.Item as={Link} to="/x"` both compile
@@ -250,11 +267,13 @@ https://bestax.io/docs/guides/features/routing.
 
 ## Menu
 
-`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.
+`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`,
+`Menu.Section`.
 
-| Prop        | Type                                                                                              |
-| ----------- | ------------------------------------------------------------------------------------------------- |
-| `Menu.Item` | `active?`, `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
+| Prop           | Type                                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Menu.Item`    | `active?` (the current page: `is-active` plus `aria-current="page"`, so don't add your own), `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus                                             |
+| `Menu.Section` | `label` (the heading, a `ReactNode`), `defaultOpen?`, or `open?` with `onOpenChange?(open)` to hold the state yourself, as `Collapse` does; its child is the group's `Menu.List`, and a closed section's links are out of reach |
 
 ```tsx
 <Menu>
@@ -268,6 +287,34 @@ https://bestax.io/docs/guides/features/routing.
 </Menu>
 ```
 
+A sidebar whose groups of links open and close (a docs sidebar, an admin app's sections) puts each
+group's `Menu.List` in a `Menu.Section`. Its heading is a real button drawn like `Menu.Label`, with
+`aria-expanded` and a chevron, and its links stay ordinary links, each a tab stop. Open the
+section that holds the current page. A section goes directly in `Menu`, never inside a `Menu.Item`
+(it would render inside the item's link) or a `Menu.List` (it isn't a list item). Don't build this
+from `TreeView` (its items aren't links) or from a `Collapse` in a hand-written `<li>` (its trigger
+is a `div` with `role="button"`).
+
+```tsx
+<nav aria-label="Documentation">
+  <Menu>
+    <Menu.Section label="Getting started">
+      <Menu.List>
+        <Menu.Item href="/docs/install">Installation</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+    <Menu.Section label="Components" defaultOpen>
+      <Menu.List>
+        <Menu.Item href="/docs/button" active>
+          Button
+        </Menu.Item>
+        <Menu.Item href="/docs/card">Card</Menu.Item>
+      </Menu.List>
+    </Menu.Section>
+  </Menu>
+</nav>
+```
+
 ## Card
 
 `<Card>` for catalog/grid items. Use the props form (`header`, `image`, `footer`) or the compound