create-bestax 4.2.13 → 4.2.14

package/README.md

@@ -29,9 +29,6 @@ npm create bestax@latest my-app
 
 # Using npx
 npx create-bestax@latest my-app
-
-# Alternative naming
-npm create bestax-bulma@latest my-app
 ```
 
 ### Interactive Mode
@@ -47,7 +44,7 @@ You'll be asked to:
 1. Enter a project name (and, if that directory already holds files, confirm removing them;
    nothing is removed until you have answered the last question)
 2. Select a framework (Vite or Vite + TypeScript)
-3. Choose a Bulma CSS flavor (Complete or Minimal)
+3. Choose a Bulma CSS flavor (the `--bulma` options below)
 4. Select an icon library (Font Awesome, Material Icons, etc.)
 5. Choose whether to install the bestax AI skills into `.claude/skills/`
 
@@ -56,9 +53,13 @@ Every prompt has a flag equivalent, so the whole flow is scriptable and CI-frien
 ### Command Line Options
 
 ```bash
-npm create bestax@latest [project-directory] [options]
+npm create bestax@latest [project-directory] -- [options]
 ```
 
+Put the options after `--`. npm needs it to pass them on at all, and so does bun, whose
+`bun create` rejects short flags such as `-t` and `-y` itself. pnpm and Yarn 1 accept the options
+with or without it.
+
 **Arguments:**
 
 - `[project-directory]` - Optional project directory name. It also becomes the `package.json`
@@ -104,10 +105,13 @@ npm create bestax@latest [project-directory] [options]
 
 ```bash
 # Create a TypeScript project with Font Awesome icons
-npm create bestax@latest my-app -t vite-ts -i fontawesome -b complete
+npm create bestax@latest my-app -- -t vite-ts -i fontawesome -b complete
 
 # Use all defaults (skip prompts)
-npm create bestax@latest my-app -y
+npm create bestax@latest my-app -- -y
+
+# The same with bun
+bun create bestax@latest my-app -- -y
 ```
 
 ## Templates

package/dist/cli.d.ts

@@ -16,5 +16,15 @@ export declare function copyTemplate(templatePath: string, targetPath: string):
 export declare function createProject(projectDir?: string, options?: CLIOptions): Promise<void>;
 export declare function createCLI(): Command;
 export declare function isMainModule(importMetaUrl: string, argv1: string): boolean;
-export declare function runCLI(): Promise<void>;
+/**
+ * pnpm, bun and bunx hand a `--` to the scaffolder as it was typed, where npm
+ * and Yarn 1 strip it, so `pnpm create bestax my-app -- -t vite-ts` arrives as
+ * `my-app -- -t vite-ts`. Commander reads `--` as the end of the options, and
+ * every flag after it became an extra argument: "too many arguments" (#950).
+ * Bun users need that `--`, because `bun create` rejects short flags such as
+ * `-t` and `-y` itself. So the first `--` after the script path is dropped
+ * before parsing, and a second keeps its usual meaning.
+ */
+export declare function dropForwardedSeparator(argv: readonly string[]): string[];
+export declare function runCLI(argv?: readonly string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EACL,cAAc,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,IAAI,cAAc,EAChC,iBAAiB,IAAI,iBAAiB,EACtC,iBAAiB,IAAI,iBAAiB,GACvC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,wBAAsB,cAAc,CAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAGhC;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,aAAa,CACjC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf;AAcD,wBAAgB,SAAS,IAAI,OAAO,CAsCnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EACL,cAAc,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,IAAI,cAAc,EAChC,iBAAiB,IAAI,iBAAiB,EACtC,iBAAiB,IAAI,iBAAiB,GACvC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,wBAAsB,cAAc,CAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAGhC;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,aAAa,CACjC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf;AAcD,wBAAgB,SAAS,IAAI,OAAO,CAsCnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAKxE;AAED,wBAAsB,MAAM,CAC1B,IAAI,GAAE,SAAS,MAAM,EAAiB,GACrC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/cli.js

@@ -71,9 +71,24 @@ export function createCLI() {
 export function isMainModule(importMetaUrl, argv1) {
     return importMetaUrl === `file://${argv1}`;
 }
-export async function runCLI() {
+/**
+ * pnpm, bun and bunx hand a `--` to the scaffolder as it was typed, where npm
+ * and Yarn 1 strip it, so `pnpm create bestax my-app -- -t vite-ts` arrives as
+ * `my-app -- -t vite-ts`. Commander reads `--` as the end of the options, and
+ * every flag after it became an extra argument: "too many arguments" (#950).
+ * Bun users need that `--`, because `bun create` rejects short flags such as
+ * `-t` and `-y` itself. So the first `--` after the script path is dropped
+ * before parsing, and a second keeps its usual meaning.
+ */
+export function dropForwardedSeparator(argv) {
+    const separator = argv.indexOf('--', 2);
+    return separator === -1
+        ? [...argv]
+        : [...argv.slice(0, separator), ...argv.slice(separator + 1)];
+}
+export async function runCLI(argv = process.argv) {
     const program = createCLI();
-    await program.parseAsync();
+    await program.parseAsync(dropForwardedSeparator(argv));
 }
 // Only run if this is the main module
 /* istanbul ignore next */

package/dist/index.js

@@ -14,6 +14,6 @@ if (majorVersion < MINIMUM_NODE_VERSION) {
         `Please upgrade your Node.js version.`);
     process.exit(1);
 }
-const { createCLI } = await import('./cli.js');
-await createCLI().parseAsync(process.argv);
+const { runCLI } = await import('./cli.js');
+await runCLI();
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.13",
+  "version": "4.2.14",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "prompts": "^2.4.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@allxsmith/bestax-bulma": "^5.27.0"
+    "@allxsmith/bestax-bulma": "^5.27.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
@@ -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# Alternative naming\nnpm create bestax-bulma@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 (Complete or Minimal)\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\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\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 (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"
 }

package/templates/skills/bestax-custom-component/examples/stat-card.tsx

@@ -64,8 +64,8 @@ export function StatCard({
           name={icon}
           size="large"
           textColor={color}
-          // Decorative: the label below already says it, so hide it from AT —
-          // Icon otherwise emits its default aria-label="icon". (To *label* an
+          // Decorative: the label below already says it, so it stays hidden
+          // from AT, as an Icon with no `ariaLabel` is anyway. (To *label* an
           // icon, use Icon's own camelCase `ariaLabel`; most components take
           // the plain aria-label attribute.)
           aria-hidden="true"

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

@@ -89,16 +89,18 @@ to `iconLeftName`/`iconRightName` if one is given, otherwise leaving the icon co
 
 ## Accessibility
 
-Every `Icon` renders `aria-label` (default `"icon"`), set via its camelCase `ariaLabel` prop.
-Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`) — everything
-else takes the standard `aria-label` attribute, e.g. `<Navbar.Burger aria-label="menu" />`.
+An `Icon` is decorative unless it is named: with no `ariaLabel` it renders `aria-hidden="true"`
+and no name. Name it with its camelCase `ariaLabel` prop, and it renders `role="img"` with that
+`aria-label`. Only a few components declare that prop (`Icon`, `Delete`, `Slider`, `Carousel`):
+everything else takes the standard `aria-label` attribute, e.g.
+`<Navbar.Burger aria-label="menu" />`.
 
 - **Meaningful icon** (stands alone, conveys information): pass a descriptive
   `ariaLabel="Delete item"`.
 - **Decorative icon** (next to visible text that says the same thing, e.g. inside `IconText`
-  or a labeled `Button`): hide it from screen readers with `aria-hidden`:
-  `<Icon name="check" aria-hidden="true" />` — otherwise "icon" (or a duplicate label) is
-  announced alongside the text.
+  or a labeled `Button`): leave `ariaLabel` off, and the icon stays out of the accessible
+  name. An explicit `aria-hidden="true"`, as in the examples here, says the same thing.
+- **Icon-only control:** name the control (`<Button aria-label="Delete item">`), not the icon.
 
 ## References
 

package/templates/skills/bestax-icons/examples/icon-usage.tsx

@@ -6,7 +6,6 @@
 // Set the library ONCE on ConfigProvider ('fa' | 'mdi' | 'ion' |
 // 'material-icons' | 'material-symbols' — Ionicons is 'ion', NOT 'ionicons');
 // every <Icon> below then omits `library`.
-import React from 'react';
 import {
   ConfigProvider,
   Icon,
@@ -22,7 +21,7 @@ export function IconShowcase() {
       <Box>
         <Title size="5">Meaningful icons carry their own label</Title>
         {/* Standalone icons convey information — give them a descriptive
-            ariaLabel (the default is just "icon"). */}
+            ariaLabel, which also makes the icon an image. */}
         <Icon
           name="triangle-exclamation"
           textColor="warning"
@@ -34,7 +33,8 @@ export function IconShowcase() {
           Decorative icons hide from screen readers
         </Title>
         {/* Next to visible text the icon repeats the message — aria-hidden
-            stops "icon" (or a duplicate) being announced. */}
+            keeps a duplicate from being announced. An Icon with no ariaLabel
+            renders it anyway; writing it out says so. */}
         <IconText iconProps={{ name: 'star', 'aria-hidden': 'true' }}>
           Starred
         </IconText>

package/templates/skills/bestax-icons/references/icon-libraries.md

@@ -2,7 +2,7 @@
 
 Facts an agent can act on for each of the five libraries `Icon` supports. The library ships no
 icon fonts: the app must install the chosen library (the `npm create bestax` scaffold's
-`--icon` flag does this; in an existing app, follow Setup below).
+`--icon` flag wires it in; in an existing app, follow Setup below).
 
 ## How `Icon` renders
 
@@ -126,5 +126,5 @@ Multiple segments via `items`:
 />
 ```
 
-Icons inside `IconText` sit next to their visible text — mark them decorative with
-`aria-hidden` (see SKILL.md's accessibility rules).
+Icons inside `IconText` sit next to their visible text, so leave them decorative: no
+`ariaLabel`, or an explicit `aria-hidden` (see SKILL.md's accessibility rules).

package/templates/skills/bestax-layout-scaffold/examples/app-shell.tsx

@@ -10,7 +10,7 @@
 //
 // `ConfigProvider` wraps the shell once at the root to set the app-wide icon
 // library (so <Icon> needs no `library` prop) and, optionally, a class prefix.
-import React, { useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   ConfigProvider,
   Navbar,

package/templates/skills/bestax-layout-scaffold/examples/card-grid.tsx

@@ -5,7 +5,6 @@
 // it (flexGrow="1"), so short blurbs don't leave ragged card bottoms.
 // (`height: 100%` on the card would NOT work — it resolves against auto
 // height. For uniform grids, Grid/Cell gives equal heights for free.)
-import React from 'react';
 import {
   Section,
   Container,

package/templates/skills/bestax-layout-scaffold/examples/centered.tsx

@@ -1,7 +1,6 @@
 // Centered single-column page — auth, settings, focused forms.
 // A narrow column is centered with `<Columns isCentered>`; on mobile the column
 // becomes full width automatically.
-import React from 'react';
 import {
   Section,
   Container,

package/templates/skills/bestax-layout-scaffold/examples/content-page.tsx

@@ -7,7 +7,6 @@
 //      e.g. mt="4" (1rem) instead of style={{ marginTop: '1rem' }},
 //           textAlign="centered" instead of style={{ textAlign: 'center' }},
 //           textColor="grey" instead of style={{ color: '#…' }}.
-import React from 'react';
 import {
   ConfigProvider,
   Hero,

package/templates/skills/bestax-layout-scaffold/examples/landing.tsx

@@ -10,7 +10,7 @@
 // also needs the `has-navbar-fixed-top` class on <html> so the page is padded
 // below it (never an inline padding offset) — Bulma requires this and the
 // library does NOT add it for you.
-import React, { useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 import {
   Navbar,
   Hero,

package/templates/skills/bestax-migrate/references/bulma-classes/component-map.md

@@ -145,7 +145,8 @@ A `.tabs` converts around its `<ul>`, and the `<li>`s and `<a>`s inside stay as
 renders its own `<a>` with tab roles and puts its label in a `<span>`, so converting the tabs
 themselves is by hand (something that sat beside the text in the `<a>`, a `Tag` say, then wants a
 `Span display="flex" alignItems="center"` around it and the label). A `.icon` converts around the
-`<i>` inside it when it carries an `aria-label`, which `Icon` writes otherwise.
+`<i>` inside it when it carries the attribute `Icon` writes otherwise: `aria-hidden` with no name,
+no `role` and no `tabIndex`, and `role="img"` beside an `aria-label` or `aria-labelledby`.
 
 A `.menu` converts with its `.menu-label`s and `.menu-list`s, and so do the items in a list. An
 item has no class to go by, so the codemod finds it by where it sits: a `<li>` whose nearest
@@ -264,20 +265,20 @@ as `items`.
 
 ```jsx
 <span className="icon-text">
-  <span className="icon" aria-label="Home">
+  <span className="icon" aria-hidden="true">
     <i className="fas fa-home"></i>
   </span>
   <span>Home</span>
 </span>
 // becomes
-<IconText iconProps={{ library: "fa", name: "home", ariaLabel: "Home" }}>Home</IconText>
+<IconText iconProps={{ library: "fa", name: "home", "aria-hidden": "true" }}>Home</IconText>
 ```
 
 The glyph is read from the `<i>`: its Font Awesome style class (`fas`, `far`, `fa-solid`, ...) or
 `mdi`, the one class that names the glyph (`fa-home` as `name: "home"`), and the rest as
 `features`. `library` is always written, so a `ConfigProvider` with another `iconLibrary` doesn't
 change what renders. The `.icon`'s own classes and attributes join the glyph's props as they
-would on `Icon`, with `aria-label` as `ariaLabel`.
+would on `Icon`, under their own names.
 
 It converts only when every `.icon` inside converts to `Icon` on its own and holds a bare, empty
 `<i>` naming a Font Awesome or Material Design Icons glyph, and the only other children are those

package/templates/skills/bestax-migrate/references/bulma-classes/unmappables.md

@@ -76,7 +76,11 @@ attributes you want (usually both, with a real label), then re-run. `Navbar` ren
 `role="navigation"` and `aria-label="main navigation"`, which Bulma's own navbar markup carries;
 give the `<nav>` both, with your own label if you like. `Breadcrumb` renders
 `aria-label="breadcrumbs"`, so give its `<nav>` an `aria-label`, whatever it says.
-`Icon` renders `aria-label="icon"`, so give a `.icon` an `aria-label` that says what the icon means.
+`Icon` hides an icon with no name, no `role` and no `tabIndex`, with `aria-hidden="true"`, and
+makes one named by `aria-label` or `aria-labelledby` an image, with `role="img"`. Give a decorative
+`.icon` `aria-hidden="true"`, and a meaningful one an `aria-label` that says what it means and
+`role="img"`. One whose name is an expression may render with no name, so it needs a `role` of its
+own.
 `Pagination` renders Bulma's own `role="navigation"` and `aria-label="pagination"`, and
 `Pagination.Previous`, `Pagination.Next` and `Pagination.Link` render `tabIndex={0}`, so give each
 element the attribute it's missing.

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

@@ -6,7 +6,7 @@ license: MIT
 
 # Optimizing CSS size with @allxsmith/bestax-bulma
 
-The JS side is tree-shakable (the **entire** library is ~49 KB min+gzip). The stylesheet is
+The JS side is tree-shakable (the **entire** library is ~65 KB min+gzip). The stylesheet is
 not: a prebuilt flavor ships all of Bulma + the bestax extras regardless of which components
 the app renders. Judge stylesheet weight by the **gzipped** transfer size — never the raw
 `dist/` number.
@@ -77,10 +77,14 @@ recommending it, grep the app's source for helper props on bestax components:
 
 ## Lever 2 — modular Sass build
 
-Compile only the Bulma modules + bestax extras partials the app actually uses. Needs the
-`sass` compiler as a dev dependency (Bulma's own build tool — Vite compiles `.scss` natively):
+Compile only the Bulma modules + bestax extras partials the app actually uses. Needs `bulma`
+as a dependency of the app itself (under pnpm, the app's Sass can only load what the app lists)
+and the `sass` compiler as a dev dependency (Bulma's own build tool — Vite compiles `.scss`
+natively):
 
 ```sh
+# with the project's own package manager (pnpm add, yarn add) if it isn't npm
+npm install bulma
 npm install -D sass
 ```
 
@@ -114,9 +118,9 @@ partial inventory, and a worked example are in `references/modular-build.md`.
 
 ## Lever 3 — import & icon-asset hygiene (minor)
 
-- **Named imports.** `import * as Bestax from '@allxsmith/bestax-bulma'` defeats tree
-  shaking. Convert to named imports (`import { Button, Card } from …`) — a JS-side saving
-  (whole library ≈ 49 KB min+gzip), so report it honestly as minor.
+- **Named imports.** Convert `import * as Bestax from '@allxsmith/bestax-bulma'` to named
+  imports (`import { Button, Card } from …`). Any saving is on the JS side, so report it
+  honestly as minor.
 - **Unused icon libraries.** Scaffolded apps may carry an icon library the app never uses:
   icon-font packages in `package.json` (`@fortawesome/fontawesome-free`, `@mdi/font`,
   `material-icons`, `material-symbols`) with their CSS imports in `src/main.*`, or Ionicons

package/templates/skills/bestax-optimize/references/modular-build.md

@@ -7,11 +7,14 @@ This is the "Option C" pattern from the
 ## Prerequisites
 
 ```sh
+# with the project's own package manager (pnpm add, yarn add) if it isn't npm
+npm install bulma
 npm install -D sass
 ```
 
 `sass` is Bulma's own compiler, dev-only. Vite compiles `.scss` out of the box — no plugin.
-`bulma` is already present as a dependency of `@allxsmith/bestax-bulma`, and the library
+`bulma` has to be a dependency of the app itself: bestax-bulma depends on it, but under pnpm's
+default layout the app's Sass can only load the packages the app lists. The library
 publishes its SCSS sources (`src/scss` ships in the npm package, exposed via the
 `@allxsmith/bestax-bulma/scss/*` export).
 

package/templates/skills/bestax-theming/examples/dark-mode.tsx

@@ -5,7 +5,7 @@
 // under a ConfigProvider `classPrefix`, which the prefixed flavors read. This
 // is global (even on a scoped Theme); `'system'` removes the attributes so
 // Bulma follows the OS `prefers-color-scheme`. Wrap the app once at the root.
-import React, { useState } from 'react';
+import { useState } from 'react';
 import {
   Theme,
   Box,

package/templates/skills/bestax-theming/examples/theme-config.tsx

@@ -6,7 +6,7 @@
 // palette. The <Theme> component writes those CSS variables for you:
 //   - isRoot          -> inject the variables globally at :root (use once, at the app root)
 //   - without isRoot  -> wrap children in a <div> and scope the variables to it
-import React from 'react';
+import type { ReactNode } from 'react';
 import {
   Theme,
   Button,
@@ -17,7 +17,7 @@ import {
 
 // 1) Global brand theme at the app root.
 //    Hue is unitless; saturation and lightness are percentages.
-export function ThemedApp({ children }: { children: React.ReactNode }) {
+export function ThemedApp({ children }: { children: ReactNode }) {
   return (
     <Theme
       isRoot

package/templates/skills/bestax-theming/references/css-variables.md

@@ -246,7 +246,9 @@ list it, so set it in your CSS or through a `style` prop.)
 The two `range` variables paint a range calendar (`DateRangeInput`): the band between a range's
 ends, and the fainter band shown while the end is still being picked. Both are mixed from
 `--bulma-dateinput-cell-selected-bg`, so `color` and an override of the selected fill re-tint
-them too.
+them too. Inside a band, a nearby month's day reads `--bulma-dateinput-cell-color` rather than
+`--bulma-dateinput-cell-other-month-color`, and today's tint leans a fifth of the way toward
+`--bulma-text-strong`, so both stay readable on the band's color.
 
 ### DateRangeInput