create-bestax 4.1.2 → 4.2.1

package/README.md

@@ -151,6 +151,18 @@ A scaffolder runs with write access to your filesystem and picks your starting d
 
 Full detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)
 
+## Telemetry
+
+`create-bestax` can send one **anonymous** usage event after a successful
+scaffold — only if you opt in when asked (once, at the end of a scaffold). The
+event is just the choices you made — template, Bulma flavor, icon library,
+skills, package manager — plus the CLI version, Node major version, and OS
+platform; never names, IPs, machine IDs, paths, or file contents, and no
+identifier exists that could link two events together. Opt out any time with
+`--no-telemetry`, `BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.
+
+Full disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)
+
 ## Publishing
 
 This package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases.

package/dist/cli.d.ts

@@ -16,5 +16,5 @@ 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(): void;
+export declare function runCLI(): 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,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvE,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,OAAO,CAAC,CAGlB;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,CA0BnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAgB,MAAM,IAAI,IAAI,CAG7B"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvE,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,OAAO,CAAC,CAGlB;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,CA+BnC;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5C"}

package/dist/cli.js

@@ -59,21 +59,23 @@ export function createCLI() {
         .option('-i, --icon <library>', 'icon library (none, fontawesome, mdi, ionicons, material-icons, material-symbols)')
         .option('--skills', 'install the bestax AI skills into .claude/skills')
         .option('--no-skills', 'do not install the bestax AI skills')
+        .option('--telemetry', 'enable anonymous usage telemetry (https://bestax.io/docs/guides/telemetry)')
+        .option('--no-telemetry', 'disable anonymous usage telemetry')
         .option('-y, --yes', 'skip prompts and use defaults or provided options')
-        .action((projectDir, options) => {
-        projectCreator.create(projectDir, options);
+        .action(async (projectDir, options) => {
+        await projectCreator.create(projectDir, options);
     });
     return program;
 }
 export function isMainModule(importMetaUrl, argv1) {
     return importMetaUrl === `file://${argv1}`;
 }
-export function runCLI() {
+export async function runCLI() {
     const program = createCLI();
-    program.parse();
+    await program.parseAsync();
 }
 // Only run if this is the main module
 /* istanbul ignore next */
 if (isMainModule(import.meta.url, process.argv[1])) {
-    runCLI();
+    await runCLI();
 }

package/dist/constants.d.ts

@@ -23,6 +23,10 @@ export declare const MESSAGES: {
     readonly NEXT_STEPS: "Next steps:";
     readonly HAPPY_CODING: "Happy coding! 🎉";
     readonly SKILLS_ADDED: "✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md, .claude/launch.json)";
+    readonly TELEMETRY_NOTICE: string;
+    readonly TELEMETRY_ACK_ON: "Thanks! Opt out anytime with --no-telemetry.";
+    readonly TELEMETRY_ACK_OFF: "No problem — we won't ask again.";
+    readonly TELEMETRY_ACK_UNSAVED: "Couldn't save your choice (config dir not writable) — you may be asked again.";
 };
 export declare const LAUNCH_JSON: string;
 export declare const PROMPTS: {
@@ -31,6 +35,7 @@ export declare const PROMPTS: {
     readonly SELECT_ICON_LIBRARY: "Would you like to add an icon library?";
     readonly SELECT_BULMA_FLAVOR: "Which Bulma CSS flavor would you like to use?";
     readonly INSTALL_SKILLS: "Install the bestax AI skills (.claude/skills) for Claude Code and other agents?";
+    readonly TELEMETRY_CONSENT: "Share anonymous usage stats?";
 };
 export declare const CONFIG_PROVIDER_ICON_VALUES: Record<string, string>;
 export interface ClaudeMdOptions {

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;;;wCAaQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;CAM7B,CAAC;AASX,eAAO,MAAM,WAAW,QAed,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;CAOV,CAAC;AAOX,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK9D,CAAC;AAKF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MAoIF,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EA6CvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA4CtC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;;;wCAaQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;;;;;CAiB7B,CAAC;AASX,eAAO,MAAM,WAAW,QAed,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;;CAQV,CAAC;AAOX,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK9D,CAAC;AAKF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MAoIF,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAIrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EA6CvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA4CtC,CAAC"}

package/dist/constants.js

@@ -24,6 +24,15 @@ export const MESSAGES = {
     NEXT_STEPS: 'Next steps:',
     HAPPY_CODING: 'Happy coding! 🎉',
     SKILLS_ADDED: '✔ Installed bestax AI skills into .claude/skills/ (+ CLAUDE.md, .claude/launch.json)',
+    TELEMETRY_NOTICE: 'Help improve bestax — share anonymous usage stats?\n' +
+        'Sends only the options you chose (template, Bulma flavor, icon library,\n' +
+        'skills, package manager) plus CLI version, Node major, and OS name.\n' +
+        'Never your name, paths, project names, or any personal data.\n' +
+        '  Details & opt-out: https://bestax.io/docs/guides/telemetry\n' +
+        '  Feedback welcome:  https://github.com/allxsmith/bestax/issues',
+    TELEMETRY_ACK_ON: 'Thanks! Opt out anytime with --no-telemetry.',
+    TELEMETRY_ACK_OFF: "No problem — we won't ask again.",
+    TELEMETRY_ACK_UNSAVED: "Couldn't save your choice (config dir not writable) — you may be asked again.",
 };
 // Dev-server manifest written into .claude/ with the skills opt-in so Claude
 // Code's browser preview (`preview_start`) can boot the app by name instead of
@@ -49,6 +58,7 @@ export const PROMPTS = {
     SELECT_ICON_LIBRARY: 'Would you like to add an icon library?',
     SELECT_BULMA_FLAVOR: 'Which Bulma CSS flavor would you like to use?',
     INSTALL_SKILLS: 'Install the bestax AI skills (.claude/skills) for Claude Code and other agents?',
+    TELEMETRY_CONSENT: 'Share anonymous usage stats?',
 };
 // Icon libraries that require a `ConfigProvider iconLibrary` wrapper, mapped
 // to the exact prop value the scaffolder writes into main.tsx/jsx ('none' and

package/dist/display.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"AAKA,wBAAgB,aAAa,IAAI,IAAI,CAMpC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA2BtD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../src/display.ts"],"names":[],"mappings":"AAKA,wBAAgB,aAAa,IAAI,IAAI,CAMpC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAiCtD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/display.js

@@ -30,6 +30,8 @@ export function displaySuccess(targetDir) {
     console.log(chalk.yellow(`${figures.star} If you enjoy using bestax-bulma, please star us on GitHub!`));
     console.log(chalk.dim('   https://github.com/allxsmith/bestax'));
     console.log();
+    console.log(chalk.dim('   Ideas or problems? Open an issue: https://github.com/allxsmith/bestax/issues'));
+    console.log();
 }
 export function displayError(message) {
     console.error(chalk.red(`${figures.cross} ${message}`));

package/dist/index.js

@@ -15,6 +15,5 @@ if (majorVersion < MINIMUM_NODE_VERSION) {
     process.exit(1);
 }
 const { createCLI } = await import('./cli.js');
-const program = createCLI();
-program.parse();
+await createCLI().parseAsync(process.argv);
 export {};

package/dist/package-manager.d.ts

@@ -1,4 +1,5 @@
 export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+export declare const KNOWN_PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
 /** Detect the package manager that invoked the CLI from npm_config_user_agent
  *  (e.g. "pnpm/9.12.0 npm/? node/v22 darwin arm64"). Falls back to npm. */
 export declare function detectPackageManager(userAgent?: string | undefined): PackageManager;

package/dist/package-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../src/package-manager.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAI7D;2EAC2E;AAC3E,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAAM,GAAG,SAA6C,GAChE,cAAc,CAKhB"}
+{"version":3,"file":"package-manager.d.ts","sourceRoot":"","sources":["../src/package-manager.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAI7D,eAAO,MAAM,sBAAsB,yCAA0C,CAAC;AAG9E;2EAC2E;AAC3E,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,MAAM,GAAG,SAA6C,GAChE,cAAc,CAKhB"}

package/dist/package-manager.js

@@ -1,4 +1,7 @@
-const KNOWN = ['npm', 'pnpm', 'yarn', 'bun'];
+// Exported so check:conformance can compare it against the telemetry
+// worker's allowlist by importing it, rather than regex-scraping the source.
+export const KNOWN_PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+const KNOWN = KNOWN_PACKAGE_MANAGERS;
 /** Detect the package manager that invoked the CLI from npm_config_user_agent
  *  (e.g. "pnpm/9.12.0 npm/? node/v22 darwin arm64"). Falls back to npm. */
 export function detectPackageManager(userAgent = process.env.npm_config_user_agent) {

package/dist/project-creator.d.ts

@@ -11,6 +11,7 @@ export interface CLIOptions {
     bulma?: string;
     icon?: string;
     skills?: boolean;
+    telemetry?: boolean;
     yes?: boolean;
 }
 export declare class ProjectCreator {
@@ -28,5 +29,15 @@ export declare class ProjectCreator {
     setupIconLibrary(targetPath: string, iconLibrary: string, template: string): Promise<void>;
     setupConfigProvider(targetPath: string, bulmaFlavor: string, iconLibrary: string, template: string): Promise<void>;
     create(projectDir?: string, options?: CLIOptions): Promise<void>;
+    /**
+     * Consent + beacon after a successful scaffold. Only success events are
+     * reported, the beacon is awaited (so no process.exit(1) site can kill an
+     * in-flight request), and nothing in here may throw or fail the scaffold.
+     * The prompt is skipped for -y, an explicit flag, DO_NOT_TRACK, or a
+     * missing TTY on EITHER end — with stdout redirected the question would
+     * render into the log while the CLI blocked on an invisible prompt
+     * (#192: the non-interactive path must never hang).
+     */
+    private handleTelemetry;
 }
 //# sourceMappingURL=project-creator.d.ts.map

package/dist/project-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA2BA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAWxB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAgBV,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAqBV,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAgJV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAyIvE"}
+{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA6BA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAWxB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAgBV,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAqBV,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IA+IV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgJtE;;;;;;;;OAQG;YACW,eAAe;CA2B9B"}

package/dist/project-creator.js

@@ -3,7 +3,8 @@ import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import { checkDirectoryExists, isDirectoryEmpty, emptyDirectory, ensureDirectory, copyDirectory, updatePackageJson, } from './file-system.js';
-import { promptProjectName, promptOverwriteDirectory, promptTemplate, promptIconLibrary, promptBulmaFlavor, promptInstallSkills, } from './prompts.js';
+import { promptProjectName, promptOverwriteDirectory, promptTemplate, promptIconLibrary, promptBulmaFlavor, promptInstallSkills, promptTelemetryConsent, } from './prompts.js';
+import { reportScaffold } from './telemetry.js';
 import { displayHeader, displaySuccess, displayError, displayCancelled, } from './display.js';
 import { validateProjectName } from './validators.js';
 import { MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, LAUNCH_JSON, CONFIG_PROVIDER_ICON_VALUES, } from './constants.js';
@@ -158,9 +159,8 @@ export class ProjectCreator {
                     // integrity attributes are deliberately not added: the ionicons ESM
                     // loader dynamically imports per-icon chunks that cannot carry
                     // integrity hashes, so entry-file SRI would give false assurance.
-                    const ioniconScripts = `    <!-- Ionicons -->
+                    const ioniconScripts = `    <!-- Ionicons (v8 is ESM-only; no legacy nomodule fallback exists) -->
     <script type="module" src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.esm.js"></script>
-    <script nomodule src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.js"></script>
   `;
                     htmlContent =
                         htmlContent.slice(0, insertPosition) +
@@ -421,10 +421,51 @@ export class ProjectCreator {
                 });
             }
             displaySuccess(targetDir);
+            await this.handleTelemetry(options, {
+                template,
+                bulmaFlavor,
+                iconLibrary,
+                skills: installSkills,
+            });
         }
         catch (error) {
             displayError(error.message);
             process.exit(1);
         }
     }
+    /**
+     * Consent + beacon after a successful scaffold. Only success events are
+     * reported, the beacon is awaited (so no process.exit(1) site can kill an
+     * in-flight request), and nothing in here may throw or fail the scaffold.
+     * The prompt is skipped for -y, an explicit flag, DO_NOT_TRACK, or a
+     * missing TTY on EITHER end — with stdout redirected the question would
+     * render into the log while the CLI blocked on an invisible prompt
+     * (#192: the non-interactive path must never hang).
+     */
+    async handleTelemetry(options, choices) {
+        try {
+            await reportScaffold(choices, options?.telemetry, {
+                interactive: process.stdin.isTTY === true &&
+                    process.stdout.isTTY === true &&
+                    options?.yes !== true,
+                promptConsent: promptTelemetryConsent,
+                onDecided: (enabled, persisted) => {
+                    // Worded on whether the write actually stuck: promising "we won't
+                    // ask again" after a swallowed write failure would be false.
+                    if (!persisted) {
+                        console.log(chalk.dim(MESSAGES.TELEMETRY_ACK_UNSAVED));
+                    }
+                    else if (enabled) {
+                        console.log(chalk.dim(MESSAGES.TELEMETRY_ACK_ON));
+                    }
+                    else {
+                        console.log(chalk.dim(MESSAGES.TELEMETRY_ACK_OFF));
+                    }
+                },
+            });
+        }
+        catch {
+            // Telemetry must never affect the scaffold's outcome.
+        }
+    }
 }

package/dist/prompts.d.ts

@@ -3,5 +3,13 @@ export declare function promptOverwriteDirectory(targetDir: string): Promise<boo
 export declare function promptInstallSkills(): Promise<boolean>;
 export declare function promptTemplate(): Promise<string | null>;
 export declare function promptIconLibrary(): Promise<string | null>;
+/**
+ * Consent for anonymous usage telemetry. Deliberately does NOT call
+ * ensureInteractive(): consent is optional, so without a TTY the caller skips
+ * the question instead of failing the run (#192). Returns null when the user
+ * cancels (Ctrl-C) — a cancel is not an answer and nothing is persisted, but
+ * the interrupt is honored via exit code 130 rather than swallowed.
+ */
+export declare function promptTelemetryConsent(): Promise<boolean | null>;
 export declare function promptBulmaFlavor(): Promise<string | null>;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAwBA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWhE;AAED,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAU5D;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAa7D;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAchE;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBhE"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAyBA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWhE;AAED,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAU5D;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAa7D;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAchE;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA2BtE;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBhE"}

package/dist/prompts.js

@@ -1,4 +1,5 @@
 import prompts from 'prompts';
+import chalk from 'chalk';
 import { TEMPLATES, DEFAULT_PROJECT_NAME, PROMPTS as PROMPT_MESSAGES, MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, } from './constants.js';
 import { validateProjectName } from './validators.js';
 import { displayError } from './display.js';
@@ -71,6 +72,37 @@ export async function promptIconLibrary() {
     });
     return response.iconLibrary || null;
 }
+/**
+ * Consent for anonymous usage telemetry. Deliberately does NOT call
+ * ensureInteractive(): consent is optional, so without a TTY the caller skips
+ * the question instead of failing the run (#192). Returns null when the user
+ * cancels (Ctrl-C) — a cancel is not an answer and nothing is persisted, but
+ * the interrupt is honored via exit code 130 rather than swallowed.
+ */
+export async function promptTelemetryConsent() {
+    console.log();
+    console.log(chalk.gray(MESSAGES.TELEMETRY_NOTICE));
+    let cancelled = false;
+    const response = await prompts({
+        type: 'confirm',
+        name: 'telemetry',
+        message: PROMPT_MESSAGES.TELEMETRY_CONSENT,
+        initial: false,
+    }, {
+        onCancel: () => {
+            cancelled = true;
+        },
+    });
+    if (cancelled) {
+        // A cancel is not an answer, but it IS an interrupt: without this, a ^C
+        // at the question would be swallowed and the run would exit 0 as if it
+        // had never been interrupted. 130 = 128 + SIGINT, the shell convention.
+        // The scaffold itself already succeeded, so no abrupt process.exit here.
+        process.exitCode = 130;
+        return null;
+    }
+    return typeof response.telemetry === 'boolean' ? response.telemetry : null;
+}
 export async function promptBulmaFlavor() {
     ensureInteractive();
     const response = await prompts({

package/dist/telemetry-core.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared CLI telemetry kernel (disclosure: https://bestax.io/docs/guides/telemetry).
+ *
+ * Copied byte-for-byte into create-bestax and bestax-migrate — both publish
+ * standalone, so this cannot be a workspace package. `check:conformance
+ * --only=telemetry-core` fails if the copies diverge. Edit this file in
+ * create-bestax and copy it over the migrate one.
+ *
+ * No identifier of any kind is generated. Undecided means off. Every failure
+ * here is silent: telemetry must never affect the CLI's outcome.
+ */
+export type TelemetryDecision = 'on' | 'off' | 'undecided';
+export type TelemetrySource = 'flag' | 'dnt' | 'env' | 'config' | 'default';
+export interface ResolvedTelemetry {
+    decision: TelemetryDecision;
+    source: TelemetrySource;
+}
+/** Shared across the bestax CLI family so consent is asked at most once. */
+export declare function telemetryConfigPath(): string;
+/**
+ * Precedence: flag (persisted by the caller) → DO_NOT_TRACK → BESTAX_TELEMETRY
+ * (per-run, never persisted) → config file → undecided (off).
+ */
+export declare function resolveTelemetry(flag?: boolean): Promise<ResolvedTelemetry>;
+/**
+ * Returns whether the decision was actually written: callers word their
+ * acknowledgement on it, because promising "we won't ask again" after a
+ * swallowed write failure would be false on every future run.
+ */
+export declare function persistTelemetryDecision(enabled: boolean, decidedBy: string): Promise<boolean>;
+export declare function sendTelemetry(payload: unknown): Promise<void>;
+export declare function getToolVersion(): string;
+export interface ReportRunOptions {
+    /** True only when a consent question could actually be answered. */
+    interactive: boolean;
+    /** Owns the consent UI up to the answer (notice, question); null = cancelled. */
+    promptConsent: () => Promise<boolean | null>;
+    /**
+     * Called after a prompted answer has been (attempted to be) saved, so the
+     * acknowledgement can tell the truth about whether it will stick.
+     */
+    onDecided?: (enabled: boolean, persisted: boolean) => void;
+}
+export declare function reportRun(flag: boolean | undefined, toolName: string, options: ReportRunOptions, payload: unknown): Promise<void>;
+//# sourceMappingURL=telemetry-core.d.ts.map

package/dist/telemetry-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-core.d.ts","sourceRoot":"","sources":["../src/telemetry-core.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;CACzB;AAYD,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AA6BD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,iBAAiB,CAAC,CAyB5B;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnE;AAED,wBAAgB,cAAc,IAAI,MAAM,CAUvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5D;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/telemetry-core.js

@@ -0,0 +1,141 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync } from 'fs';
+const DEFAULT_ENDPOINT = 'https://bestax.io/api/t';
+const TIMEOUT_MS = 1500;
+/** Shared across the bestax CLI family so consent is asked at most once. */
+export function telemetryConfigPath() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(base, 'bestax', 'telemetry.json');
+}
+async function readConfig() {
+    try {
+        const parsed = JSON.parse(await readFile(telemetryConfigPath(), 'utf-8'));
+        // Consent fails closed: only a well-formed v1 record is trusted. A bare
+        // {"enabled":true}, an array, or an unknown future schema version reads
+        // as "never asked" (prompt again) — never as an opt-in.
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed) &&
+            parsed.version === 1) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt config reads as "never asked".
+    }
+    return null;
+}
+function doNotTrack() {
+    const dnt = process.env.DO_NOT_TRACK;
+    return dnt !== undefined && dnt !== '' && dnt !== '0';
+}
+/**
+ * Precedence: flag (persisted by the caller) → DO_NOT_TRACK → BESTAX_TELEMETRY
+ * (per-run, never persisted) → config file → undecided (off).
+ */
+export async function resolveTelemetry(flag) {
+    if (flag !== undefined) {
+        return {
+            decision: flag ? 'on' : 'off',
+            source: 'flag',
+        };
+    }
+    if (doNotTrack()) {
+        return { decision: 'off', source: 'dnt' };
+    }
+    const env = process.env.BESTAX_TELEMETRY;
+    if (env === '0' || env === '1') {
+        return {
+            decision: env === '1' ? 'on' : 'off',
+            source: 'env',
+        };
+    }
+    const config = await readConfig();
+    if (config && typeof config.enabled === 'boolean') {
+        return {
+            decision: config.enabled ? 'on' : 'off',
+            source: 'config',
+        };
+    }
+    return { decision: 'undecided', source: 'default' };
+}
+/**
+ * Returns whether the decision was actually written: callers word their
+ * acknowledgement on it, because promising "we won't ask again" after a
+ * swallowed write failure would be false on every future run.
+ */
+export async function persistTelemetryDecision(enabled, decidedBy) {
+    try {
+        const config = {
+            version: 1,
+            enabled,
+            decidedAt: new Date().toISOString(),
+            decidedBy,
+        };
+        const filePath = telemetryConfigPath();
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        // An unwritable config dir must not break the CLI.
+        return false;
+    }
+}
+export async function sendTelemetry(payload) {
+    try {
+        await fetch(process.env.BESTAX_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Fire-and-forget: the response (or its absence) is never surfaced.
+    }
+}
+export function getToolVersion() {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const packageJson = JSON.parse(readFileSync(join(dir, '..', 'package.json'), 'utf-8'));
+        return packageJson.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export async function reportRun(flag, toolName, options, payload) {
+    const resolved = await resolveTelemetry(flag);
+    let decision = resolved.decision;
+    if (resolved.source === 'flag') {
+        // Flags are the scripted equivalent of the prompt: decided once,
+        // remembered — EXCEPT under DO_NOT_TRACK, where the flag still applies to
+        // this one run (an explicit ask on the command line wins) but is never
+        // written down, so a copied command containing --telemetry cannot enable
+        // telemetry beyond the run it was typed for.
+        if (!doNotTrack()) {
+            const persisted = await persistTelemetryDecision(decision === 'on', `${toolName}@${getToolVersion()}`);
+            // A silently unsaved flag is worse than an unsaved answer: with an
+            // opposite value already in the shared config, --no-telemetry would
+            // apply to this run only and the next family run would re-enable.
+            if (!persisted) {
+                options.onDecided?.(decision === 'on', false);
+            }
+        }
+    }
+    else if (decision === 'undecided' && options.interactive) {
+        const answer = await options.promptConsent();
+        if (answer !== null) {
+            const persisted = await persistTelemetryDecision(answer, `${toolName}@${getToolVersion()}`);
+            decision = answer ? 'on' : 'off';
+            options.onDecided?.(answer, persisted);
+        }
+    }
+    if (decision === 'on') {
+        await sendTelemetry(payload);
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,31 @@
+import type { ReportRunOptions } from './telemetry-core.js';
+/**
+ * create-bestax payload + reporter. The kernel lives in telemetry-core.ts
+ * (copied into bestax-migrate; see that file). Envelope and props are closed
+ * enums, a version string, or a bounded integer — never paths, project names,
+ * or free text.
+ */
+export interface ScaffoldChoices {
+    template: string;
+    bulmaFlavor: string;
+    iconLibrary: string;
+    skills: boolean;
+}
+export interface ScaffoldPayload {
+    v: 1;
+    tool: 'create-bestax';
+    event: 'scaffold';
+    toolVersion: string;
+    nodeMajor: number;
+    platform: string;
+    props: {
+        template: string;
+        bulmaFlavor: string;
+        iconLibrary: string;
+        skills: boolean;
+        packageManager: string;
+    };
+}
+export declare function buildScaffoldPayload(choices: ScaffoldChoices): ScaffoldPayload;
+export declare function reportScaffold(choices: ScaffoldChoices, flag: boolean | undefined, options: ReportRunOptions): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,OAAO,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,GACvB,eAAe,CAgBjB;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/telemetry.js

@@ -0,0 +1,22 @@
+import { detectPackageManager } from './package-manager.js';
+import { getToolVersion, reportRun } from './telemetry-core.js';
+export function buildScaffoldPayload(choices) {
+    return {
+        v: 1,
+        tool: 'create-bestax',
+        event: 'scaffold',
+        toolVersion: getToolVersion(),
+        nodeMajor: Number(process.versions.node.split('.')[0]),
+        platform: process.platform,
+        props: {
+            template: choices.template,
+            bulmaFlavor: choices.bulmaFlavor,
+            iconLibrary: choices.iconLibrary,
+            skills: choices.skills,
+            packageManager: detectPackageManager(),
+        },
+    };
+}
+export async function reportScaffold(choices, flag, options) {
+    await reportRun(flag, 'create-bestax', options, buildScaffoldPayload(choices));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.1.2",
+  "version": "4.2.1",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -74,5 +74,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://socket.dev/api/badge/npm/package/create-bestax)](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[![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\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\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**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## 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://socket.dev/api/badge/npm/package/create-bestax)](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[![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\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\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**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"
 }

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

@@ -52,12 +52,11 @@ Set it once on `ConfigProvider` and omit `library` everywhere else.
     type="module"
     src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.esm.js"
   ></script>
-  <script
-    nomodule
-    src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.js"
-  ></script>
   ```
 
+  Ionicons v8 is ESM-only — there is no legacy `nomodule` bundle, so a single
+  `type="module"` tag is all that is needed.
+
 - **Scaffold flag:** `--icon ionicons` — which maps to `iconLibrary="ion"`. Passing
   `'ionicons'` as the `library`/`iconLibrary` value renders nothing.
 - **Names:** kebab-case: `rocket`, `heart`, `settings`.

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

@@ -6,40 +6,40 @@ codemod converts it; **Flagged** = it leaves a `TODO(bestax-migrate)` comment (s
 
 ## Top-level components
 
-| RBC            | bestax                                       | Notes                                                                                 |
-| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `Block`        | `Block`                                      | Auto                                                                                  |
-| `Box`          | `Box`                                        | Auto                                                                                  |
-| `Breadcrumb`   | `Breadcrumb`                                 | Auto; `align` → `alignment` (`center`→`centered`)                                     |
-| `Button`       | `Button`                                     | Auto; `<Button remove/>` → `<Delete/>`; see prop map                                  |
-| `Card`         | `Card`                                       | Auto                                                                                  |
-| `Columns`      | `Columns`                                    | Auto; `breakpoint="mobile"`→`isMobile`, `multiline`→`isMultiline`, …                  |
-| `Container`    | `Container`                                  | Auto; `breakpoint="fluid"`→`fluid`, `max`→`isMax`                                     |
-| `Content`      | `Content`                                    | Auto                                                                                  |
-| `Dropdown`     | `Dropdown`                                   | Structure auto; controlled `value`/`onChange` flagged                                 |
-| `Element`      | —                                            | Flagged: no generic element; use a semantic component + helper props                  |
-| `Footer`       | `Footer`                                     | Auto                                                                                  |
-| `Form.*`       | flat imports                                 | See Form table below                                                                  |
-| `Heading`      | `Title` / `SubTitle` / `<p class="heading">` | Auto; `subtitle` picks `SubTitle`, `heading` picks the plain element                  |
-| `Hero`         | `Hero`                                       | Auto; `hasNavbar`→`fullheightWithNavbar`; `halfheight`/`gradient` flagged             |
-| `Icon`         | `Icon`                                       | `<i class="fas fa-x">` children → `name`/`library`/`variant` props; else flagged      |
-| `Image`        | `Image`                                      | Auto; numeric `size={128}` → `size="128x128"`, `rounded`→`isRounded`                  |
-| `Level`        | `Level`                                      | Auto; `breakpoint="mobile"`→`isMobile`                                                |
-| `Loader`       | plain `<div className="loader">`             | Auto (Bulma v1 still ships the class)                                                 |
-| `Media`        | `Media`                                      | Auto                                                                                  |
-| `Menu`         | `Menu`                                       | Auto                                                                                  |
-| `Message`      | `Message`                                    | Auto; `size` flagged                                                                  |
-| `Modal`        | `Modal`                                      | `show`→`active`; `closeOnEsc`/`closeOnBlur`/`showClose` flagged (defaults cover them) |
-| `Navbar`       | `Navbar`                                     | Auto; see dropdown note below                                                         |
-| `Notification` | `Notification`                               | Auto; `light`→`isLight`                                                               |
-| `Pagination`   | `Pagination`                                 | `onChange`→`onPageChange`; `delta`/labels/`showFirstLast`/`autoHide` flagged          |
-| `Panel`        | `Panel`                                      | Auto                                                                                  |
-| `Progress`     | `Progress`                                   | Auto                                                                                  |
-| `Section`      | `Section`                                    | Auto                                                                                  |
-| `Table`        | `Table`                                      | Auto; `size="fullwidth"`→`isFullwidth`, `striped`→`isStriped`, …                      |
-| `Tabs`         | `Tabs`                                       | Auto; children wrapped in `Tabs.List`; `type="toggle-rounded"`→`toggle rounded`       |
-| `Tag`          | `Tag`                                        | Auto; `remove`→`isDelete`, `rounded`→`isRounded`                                      |
-| `Tile`         | —                                            | Flagged: Bulma v1 replaced tiles with `Grid`/`Cell`                                   |
+| RBC            | bestax                                       | Notes                                                                                                                       |
+| -------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `Block`        | `Block`                                      | Auto                                                                                                                        |
+| `Box`          | `Box`                                        | Auto                                                                                                                        |
+| `Breadcrumb`   | `Breadcrumb`                                 | Auto; `align` → `alignment` (`center`→`centered`)                                                                           |
+| `Button`       | `Button`                                     | Auto for literal `remove` (by value, not presence — truthy → `<Delete/>`, `remove={false}` stays `Button`); dynamic flagged |
+| `Card`         | `Card`                                       | Auto                                                                                                                        |
+| `Columns`      | `Columns`                                    | Auto; `breakpoint="mobile"`→`isMobile`, `multiline`→`isMultiline`, …                                                        |
+| `Container`    | `Container`                                  | Auto; `breakpoint="fluid"`→`fluid`, `max`→`isMax`                                                                           |
+| `Content`      | `Content`                                    | Auto                                                                                                                        |
+| `Dropdown`     | `Dropdown`                                   | Structure auto; controlled `value`/`onChange` flagged                                                                       |
+| `Element`      | —                                            | Flagged: no generic element; use a semantic component + helper props                                                        |
+| `Footer`       | `Footer`                                     | Auto                                                                                                                        |
+| `Form.*`       | flat imports                                 | See Form table below                                                                                                        |
+| `Heading`      | `Title` / `SubTitle` / `<p class="heading">` | Auto for literal `subtitle`/`heading` (by value, not presence — `subtitle={false}` is `Title`); dynamic value flagged       |
+| `Hero`         | `Hero`                                       | Auto; `hasNavbar`→`fullheightWithNavbar`; `halfheight`/`gradient` flagged                                                   |
+| `Icon`         | `Icon`                                       | `<i class="fas fa-x">` children → `name`/`library`/`variant` props; else flagged                                            |
+| `Image`        | `Image`                                      | Auto; numeric `size={128}` → `size="128x128"`, `rounded`→`isRounded`                                                        |
+| `Level`        | `Level`                                      | Auto; `breakpoint="mobile"`→`isMobile`                                                                                      |
+| `Loader`       | plain `<div className="loader">`             | Auto (Bulma v1 still ships the class)                                                                                       |
+| `Media`        | `Media`                                      | Auto                                                                                                                        |
+| `Menu`         | `Menu`                                       | Auto                                                                                                                        |
+| `Message`      | `Message`                                    | Auto; `size` flagged                                                                                                        |
+| `Modal`        | `Modal`                                      | `show`→`active`; `closeOnEsc`/`closeOnBlur`/`showClose` flagged (defaults cover them)                                       |
+| `Navbar`       | `Navbar`                                     | Auto; see dropdown note below                                                                                               |
+| `Notification` | `Notification`                               | Auto; `light`→`isLight`                                                                                                     |
+| `Pagination`   | `Pagination`                                 | `onChange`→`onPageChange`; `delta`/labels/`showFirstLast`/`autoHide` flagged                                                |
+| `Panel`        | `Panel`                                      | Auto                                                                                                                        |
+| `Progress`     | `Progress`                                   | Auto                                                                                                                        |
+| `Section`      | `Section`                                    | Auto                                                                                                                        |
+| `Table`        | `Table`                                      | Auto; `size="fullwidth"`→`isFullwidth`, `striped`→`isStriped`, …                                                            |
+| `Tabs`         | `Tabs`                                       | Auto; children wrapped in `Tabs.List`; `type="toggle-rounded"`→`toggle rounded`                                             |
+| `Tag`          | `Tag`                                        | Auto; `remove`→`isDelete`, `rounded`→`isRounded`                                                                            |
+| `Tile`         | —                                            | Flagged: Bulma v1 replaced tiles with `Grid`/`Cell`                                                                         |
 
 ## Compound sub-components
 

package/templates/skills/bestax-migrate/references/css-migration.md

@@ -22,13 +22,18 @@ finish what it flagged.
 
   ```scss
   @use 'bulma/sass' with (
-      $primary: #ff6b35,
-      $family-primary: 'Nunito',
-      sans-serif
-    );
+    $primary: #ff6b35,
+    $family-primary: (
+      'Nunito',
+      sans-serif,
+    )
+  );
   @use '@allxsmith/bestax-bulma/scss/extras';
   ```
 
+  A comma-valued override (a font-family stack) is wrapped in parens so Dart Sass
+  reads it as one list value, not extra arguments to `with (…)`.
+
   0.9 `_all` aggregator imports (`bulma/sass/elements/_all`) became directory modules
   (`@use 'bulma/sass/elements';`). Relative node_modules paths
   (`@import '../../node_modules/bulma/bulma'`, common under Parcel) keep their prefix,
@@ -38,6 +43,31 @@ finish what it flagged.
   **dart-sass ≥ 1.79** — the codemod's node-sass replacement installs that, but check
   bundler-pinned older versions (Parcel's sass transformer pins 1.66).
 
+  react-bulma-components' own stylesheet — any `react-bulma-components/…` specifier,
+  bare, `~`-prefixed, or a relative `node_modules/` path, covering the documented v3
+  entry points (`src/index.sass`, `dist/react-bulma-components(.min).css`) as well as
+  deep partials and extensionless forms — is not a third-party extension; it's the
+  library being migrated away from. It targets Bulma 0.9, not the v1 your components now
+  use, and (unless `--no-deps` is passed) `package.json` no longer lists it, so the
+  import can never resolve once installed. Every `--css` mode rewrites it into a real
+  Bulma root rather than leaving a known-broken import — the **same shape the
+  `@import 'bulma/…'` root path emits**, so a file that starts from RBC and one that
+  starts from a Bulma import converge: `bestax` (default) emits
+  `@use 'bulma/sass';` (folding any leading `$var` overrides above the import into
+  `with (…)`) plus `@use '@allxsmith/bestax-bulma/scss/extras';`; `bulma` emits plain
+  `@use 'bulma/sass';`; `keep` does the same with a TODO explaining the replacement
+  (worded to match whether `--no-deps` kept the package). It deliberately does **not**
+  emit the hard-configured `scss/bestax` bundle here — that bundle can't carry the
+  user's own theme vars, and reconfiguring `bulma/sass` when another file already
+  configures it is a hard Sass error. If the file already has its own `bulma/…` root
+  (a `@use 'bulma/sass'` of its own, or a Bulma `@import` the codemod converts), the RBC
+  **root/index** line (`src/index`, the bundled `dist/*.css`, or the bare specifier) is
+  dropped instead of emitting a second root; in `bestax` mode the extras are added once
+  alongside that existing root. A dropped RBC **deep partial** (e.g.
+  `src/components/navbar.sass`) is different — `bulma/sass` doesn't necessarily carry a
+  given partial's styles, so it gets a `// TODO(bestax-migrate)` and a report entry
+  ("port any styles it carried beyond Bulma's own by hand") rather than vanishing silently.
+
 - **package.json**: `react-bulma-components` removed, `@allxsmith/bestax-bulma` added,
   `bulma` bumped to `^1.0.4` (or added when sources still import `bulma/…` directly),
   and dead `node-sass` replaced with dart `sass`. Run the package manager's install
@@ -63,6 +93,8 @@ elements,form,components,grid,layout,helpers,themes}` with leaf partials like
   compatibility. Class-based usage (`className="is-checkradio"`) keeps needing the
   extension; usage that migrated to bestax components (Radio, Checkbox, the advanced
   form controls) is already styled by the bestax extras, so the import can go.
+  react-bulma-components' own stylesheet is never flagged this way (see above) — only
+  packages actually named `bulma-*` are.
 
 ## Choosing a CSS flavor (optional)
 

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

@@ -124,9 +124,9 @@ same rule as the extras section below).
 
 ## Extras component variables
 
-Every "Beyond Bulma" extra registers its own `--bulma-<component>-*` variables. They are
-registered on the component's **own selector** (`.avatar`, `.dialog`, `.tooltip`, … —
-`.bestax-avatar` etc. with the prefixed CSS flavor), not on `:root`. A value set on a wrapping
+Every "Beyond Bulma" extra registers its own `--bulma-<component>-*` variables. Most are
+registered on the component's **own selector** (`.avatar`, `.dialog`, … — `.bestax-avatar`
+etc. with the prefixed CSS flavor), not on `:root`. A value set on a wrapping
 ancestor — including `Theme`'s `bulmaVars` on a wrapping `Theme` — is only _inherited_ and
 always loses to the component-level declaration, so it will NOT take effect. Working overrides
 target the component's own element instead: redeclare on the component's own class in your CSS
@@ -135,6 +135,20 @@ target the component's own element instead: redeclare on the component's own cla
 (`.avatar.big-avatar { --bulma-avatar-size: 3.5rem; }`), or set it via the component's `style`
 prop. Several default to core theme vars above, so they already flow through a custom theme.
 
+Two exceptions where that advice silently fails, because the declarations sit somewhere a
+lone class or the `style` prop cannot outrank:
+
+- **Compound selectors** — LinkButton's variables are declared on `.button.link-button`
+  (specificity 0-2-0). A single class added via `className` is 0-1-0 and loses regardless of
+  stylesheet order. Override with the `style` prop, or in CSS loaded after the library
+  styles with a selector that matches or exceeds the compound:
+  `.button.link-button { --bulma-link-button-ghost-color: … }`.
+- **Constituent elements** — Tooltip's variables (all but `--bulma-tooltip-dashed-color`)
+  are declared on `.tooltip-content`, and Sidebar's `--bulma-sidebar-overlay-background` on
+  `.sidebar-background`. Values set via `className` or `style` land on the component root and
+  are only inherited by the constituent, so they lose to its own declaration — target the
+  declaring element in your CSS: `.tooltip-content { --bulma-tooltip-background: … }`.
+
 ### Avatar / Avatars / Badge
 
 | Variable                                                          | Default                          |
@@ -238,6 +252,8 @@ own-selector override rule applies.
 
 ### LinkButton
 
+Declared on the compound `.button.link-button` — see the compound-selector exception above.
+
 `--bulma-link-button-ghost-color`, `--bulma-link-button-ghost-hover-color`,
 `--bulma-link-button-transition-duration`, `--bulma-link-button-underline-offset`
 
@@ -378,6 +394,9 @@ own-selector override rule applies.
 
 ### Tooltip
 
+All but `--bulma-tooltip-dashed-color` are declared on `.tooltip-content` — see the
+constituent-element exception above.
+
 `--bulma-tooltip-arrow-margin`, `--bulma-tooltip-arrow-size`, `--bulma-tooltip-background`,
 `--bulma-tooltip-color`, `--bulma-tooltip-dashed-color`, `--bulma-tooltip-font-size`,
 `--bulma-tooltip-font-weight`, `--bulma-tooltip-line-height`, `--bulma-tooltip-max-width`,