create-bestax 3.5.0 → 3.6.0

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,MAoEF,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;;;;;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,MAwEF,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

@@ -100,6 +100,9 @@ ${setupLines.join('\n')}
 - Compose existing components before writing custom CSS; theme via \`Theme\` and \`--bulma-*\`
   variables, never hardcoded colors.
 - There is no test runner or Storybook in this app — don't assume one.
+- \`index.html\`'s \`<title>\` starts as the project name and \`README.md\` is stock template
+  boilerplate — once this app has a real identity, set the title (and any meta tags) to match
+  it and rewrite the README to describe *this* app, not the template.
 
 ## AI skills
 
@@ -112,6 +115,7 @@ automatically when the task matches:
 - **bestax-layout-scaffold** — scaffold full pages (app shell, landing, centered, card grid).
 - **bestax-icons** — icons via \`Icon\`/\`IconText\`: library setup, name formats, variants, a11y.
 - **bestax-optimize** — shrink the built CSS: measure raw+gzip, then flavor switch or a modular Sass build.
+- **bestax-migrate** — migrate code off react-bulma-components (v4): run the codemod, resolve its TODOs.
 
 Prefer the library's components and these skills over hand-written Bulma markup or custom CSS.
 

package/dist/project-creator.d.ts

@@ -20,6 +20,7 @@ export declare class ProjectCreator {
     checkExistingDirectory(targetPath: string, targetDir: string): Promise<boolean>;
     getTemplatePath(template: string): string;
     copyTemplate(template: string, targetPath: string): Promise<void>;
+    updateIndexHtmlTitle(targetPath: string, projectName: string): Promise<void>;
     setupSkills(targetPath: string, projectName: string, options: ClaudeMdOptions): Promise<void>;
     setupBulmaFlavor(targetPath: string, bulmaFlavor: string, template: string): Promise<void>;
     private getIconName;

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;AAIxB,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,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;CAwIvE"}
+{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA2BA,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAIxB,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"}

package/dist/project-creator.js

@@ -45,6 +45,18 @@ export class ProjectCreator {
         await ensureDirectory(targetPath);
         await copyDirectory(templatePath, targetPath);
     }
+    async updateIndexHtmlTitle(targetPath, projectName) {
+        const indexHtmlPath = path.join(targetPath, 'index.html');
+        if (!fs.existsSync(indexHtmlPath))
+            return;
+        const htmlContent = await fs.readFile(indexHtmlPath, 'utf8');
+        // projectName is validated against PROJECT_NAME_REGEX (letters, digits,
+        // dots, dashes, underscores only), so it needs no HTML escaping.
+        const updated = htmlContent.replace(/<title>[^<]*<\/title>/, `<title>${projectName}</title>`);
+        if (updated !== htmlContent) {
+            await fs.writeFile(indexHtmlPath, updated);
+        }
+    }
     async setupSkills(targetPath, projectName, options) {
         const skillsSrc = path.join(this.templatesDir, 'skills');
         if (!(await checkDirectoryExists(skillsSrc))) {
@@ -392,6 +404,7 @@ export class ProjectCreator {
         try {
             await this.copyTemplate(template, targetPath);
             await updatePackageJson(targetPath, projectName);
+            await this.updateIndexHtmlTitle(targetPath, projectName);
             await this.setupBulmaFlavor(targetPath, bulmaFlavor, template);
             await this.setupIconLibrary(targetPath, iconLibrary, template);
             await this.setupConfigProvider(targetPath, bulmaFlavor, iconLibrary, template);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,78 @@
+---
+name: bestax-migrate
+description: Migrate an existing app from react-bulma-components (v4) to @allxsmith/bestax-bulma on Bulma v1 — run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the mapping references. Use when a repo imports react-bulma-components and wants to move to bestax-bulma, when TODO(bestax-migrate) comments are present in a codebase, or when asked to migrate off an unmaintained React Bulma library.
+license: MIT
+---
+
+# Migrating from react-bulma-components to bestax-bulma
+
+`react-bulma-components` is unmaintained (last release 2022, Bulma 0.9.x).
+`@allxsmith/bestax-bulma` is an actively maintained React library for **Bulma v1**. The
+`bestax-migrate` codemod automates most of the conversion; this skill drives the codemod and
+finishes what it flags.
+
+## Workflow
+
+Run these steps in order. Don't hand-convert what the codemod converts automatically.
+
+1. **Dry-run the codemod** on the source directory and review the report:
+
+   ```sh
+   pnpm dlx bestax-migrate react-bulma-components src/ --dry
+   ```
+
+2. **Apply it** (same command without `--dry`), then run the project's formatter — the
+   codemod preserves surrounding formatting but doesn't prettify what it rewrites.
+   Besides the components, it also migrates **stylesheets** (CSS imports →
+   `@allxsmith/bestax-bulma/bestax.css`; SCSS `@import 'bulma/bulma'` + `$var` overrides
+   → `@use 'bulma/sass' with (…)` plus the bestax extras) and **package.json**
+   (react-bulma-components removed, bestax-bulma added, bulma → ^1, node-sass → sass).
+   Flags: `--css bulma|keep` for other stylesheet targets, `--no-deps` to leave
+   package.json alone.
+
+3. **Install** — the codemod edits package.json but never runs a package manager:
+
+   ```sh
+   npm install   # or pnpm/yarn
+   ```
+
+   The report's `peer-deps` entries predict install failures: bestax-bulma needs
+   **React 18/19** (RBC also ran on 17 — upgrade react/react-dom first) and its optional
+   Font Awesome peer wants **FA ≥ 6.7** (an app pinned to FA 5 either upgrades or
+   installs with `npm install --legacy-peer-deps`).
+
+4. **Resolve every TODO**: `grep -rn "TODO(bestax-migrate)" src/`. Each comment names the
+   prop/component and a hint. Recipes for every recurring case are in
+   [references/unmappables.md](references/unmappables.md); the full component and prop
+   tables are in [references/component-map.md](references/component-map.md) and
+   [references/prop-map.md](references/prop-map.md). Delete each comment as you resolve it.
+
+5. **Finish the stylesheet layer** — flagged Sass cases (computed variables,
+   indented-syntax `.sass` files), CSS flavor choice, and Bulma 0.9→1 styling changes:
+   follow [references/css-migration.md](references/css-migration.md).
+
+6. **Finish**: typecheck/build, and review the rendered app side by side against the
+   pre-migration UI.
+
+## What the codemod handles vs. flags
+
+All 32 react-bulma-components v4 components have a mapping. Imports (named, namespace, and
+`const { Input } = Form` destructuring), component renames, prop renames/value conversions,
+responsive breakpoint objects, CSS/SCSS stylesheet imports, and package.json dependencies
+convert automatically. It flags with
+`TODO(bestax-migrate)` instead of guessing: `Element` and `Tile` (no bestax equivalent —
+Tile is replaced by Bulma v1's Grid), controlled `Dropdown`/`Dropdown.Item value`,
+`touch`/`until*` breakpoints, dynamic prop values it can't rewrite, and props with no
+bestax counterpart. Files in formats it can't parse (`.astro`, `.vue`, `.svelte`, `.mdx`)
+that import react-bulma-components are reported as `unsupported-file` — migrate those by
+hand with the component map. Never "fix" a TODO by silencing it — convert the code per the
+references, or deliberately keep the old markup with `className` styling.
+
+## Rules
+
+- The codemod is idempotent on already-migrated files (it only touches files importing
+  `react-bulma-components`) — safe to re-run after partial manual work.
+- Don't downgrade converted props back to RBC names; bestax uses `is*` booleans
+  (`isLoading`), string size unions (`textSize="4"`), and `as` instead of `renderAs`.
+- If a component the app uses isn't in the component map, it wasn't part of RBC v4 —
+  check for a local wrapper component and migrate its internals instead.

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

@@ -0,0 +1,91 @@
+# Component map: react-bulma-components v4 → @allxsmith/bestax-bulma
+
+Every RBC v4 export and compound sub-component, with its bestax target. **Auto** = the
+codemod converts it; **Flagged** = it leaves a `TODO(bestax-migrate)` comment (see
+[unmappables.md](unmappables.md) for the recipes).
+
+## 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`                                   |
+
+## Compound sub-components
+
+| RBC                                                         | bestax                                                                   |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `Breadcrumb.Item`                                           | plain `<li><a href=…>` (`active` → `is-active`)                          |
+| `Button.Group`                                              | `Buttons` (`align="right"`→`isRight`)                                    |
+| `Card.Header` / `.Title` / `.Icon`                          | `Card.Header` / `.Header.Title` / `.Header.Icon`                         |
+| `Card.Image`                                                | `Card.Image` wrapping an inner `<Image>`                                 |
+| `Card.Content`                                              | `Card.Content`                                                           |
+| `Card.Footer` / `Card.Footer.Item`                          | `Card.Footer` / `Card.FooterItem`                                        |
+| `Columns.Column`                                            | `Column` (flat import)                                                   |
+| `Dropdown.Item` / `.Divider`                                | `Dropdown.Item` / `Dropdown.Divider`                                     |
+| `Hero.Header` / `.Body` / `.Footer`                         | `Hero.Head` / `Hero.Body` / `Hero.Foot`                                  |
+| `Icon.Text`                                                 | `IconText`                                                               |
+| `Level.Side align` / `Level.Item`                           | `Level.Left` or `Level.Right` / `Level.Item`                             |
+| `Media.Item align`                                          | `MediaLeft` / `MediaContent` / `MediaRight` (flat)                       |
+| `Menu.List` (+ `title`)                                     | `Menu.List` (+ a `Menu.Label` sibling)                                   |
+| `Menu.List.Item`                                            | `Menu.Item`                                                              |
+| `Message.Header` / `.Body`                                  | `Message.Header` / `Message.Body`                                        |
+| `Modal.Content`                                             | `Modal.Content`                                                          |
+| `Modal.Card` `.Header`/`.Body`/`.Footer`/`.Title`           | `Modal.Card` `.Head`/`.Body`/`.Foot`/`.Title`                            |
+| `Navbar.Brand`/`.Burger`/`.Menu`/`.Item`/`.Link`/`.Divider` | same names                                                               |
+| `Navbar.Container align`                                    | `Navbar.Start` / `Navbar.End`                                            |
+| `Navbar.Item` wrapping a dropdown                           | `Navbar.Dropdown` (container)                                            |
+| `Navbar.Dropdown` (the menu)                                | `Navbar.DropdownMenu`                                                    |
+| `Panel.Header`                                              | `Panel.Heading`                                                          |
+| `Panel.Tabs` / `Panel.Tabs.Tab`                             | `Panel.Tabs` / plain `<a>` children                                      |
+| `Panel.Block` / `Panel.Icon`                                | `Panel.Block` / `Panel.Icon` (icon child → `name`)                       |
+| `Table.Container`                                           | `isResponsive` on the child `Table` (or `<div class="table-container">`) |
+| `Tabs.Tab`                                                  | `Tabs.Item` (inside a generated `Tabs.List`)                             |
+| `Tag.Group`                                                 | `Tags` (`gapless` → `hasAddons`)                                         |
+
+## Form namespace → flat imports
+
+| RBC                | bestax                                                                                                                           |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `Form.Field`       | `Field` (`kind="group"`→`grouped`, `kind="addons"`→`hasAddons`, `align` folds into the value, `multiline`→`grouped="multiline"`) |
+| `Form.Field.Label` | `FieldLabel`                                                                                                                     |
+| `Form.Field.Body`  | `FieldBody`                                                                                                                      |
+| `Form.Control`     | `Control` (`fullwidth`→`isExpanded`, `loading`→`isLoading`)                                                                      |
+| `Form.Input`       | `Input` (`rounded`→`isRounded`, `status="focus"`→`isFocused`)                                                                    |
+| `Form.Label`       | plain `<label className="label">`                                                                                                |
+| `Form.Textarea`    | `TextArea` (`fixedSize`→`hasFixedSize`)                                                                                          |
+| `Form.Select`      | `Select` (`loading`→`isLoading`, `fullwidth`→`isFullwidth`)                                                                      |
+| `Form.Checkbox`    | `Checkbox`                                                                                                                       |
+| `Form.Radio`       | `Radio`                                                                                                                          |
+| `Form.Help`        | plain `<p className="help is-…">` (prefer Field `message`/`messageColor`)                                                        |
+| `Form.InputFile`   | `File` (`filename`→`fileName`+`hasName`, `boxed`→`isBoxed`, `label`→`buttonLabel`)                                               |

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

@@ -0,0 +1,100 @@
+# Stylesheets: Bulma 0.9 → Bulma v1 + bestax
+
+react-bulma-components apps style with Bulma 0.9.x; bestax-bulma targets Bulma v1. The
+codemod automates most of this layer — this reference explains what it did and how to
+finish what it flagged.
+
+## What the codemod already did (default `--css bestax`)
+
+- **CSS imports**: `bulma/css/bulma(.min).css` and v3-era
+  `react-bulma-components/dist/*.css` imports became the recommended combined bundle
+  `@allxsmith/bestax-bulma/bestax.css` (Bulma v1 + the bestax extras that themed
+  Radio/Checkbox and the advanced form controls need). A separate `extras.css` import
+  next to it is collapsed.
+  **Visual note**: `bestax.css` ships with `$primary` set to bestax blue (`#1e6b99`),
+  not Bulma's stock turquoise — `is-primary` surfaces (hero, navbar, buttons) change
+  color. Keep the stock Bulma look with `--css bulma`, or set your own brand color via
+  `--bulma-primary-*` CSS variables / a Sass build.
+
+- **SCSS files**: Bulma 0.9's `@import 'bulma/bulma.sass'` (plus preceding
+  `$var: value !default;` overrides) became Bulma v1 module syntax, with simple literal
+  overrides folded in:
+
+  ```scss
+  @use 'bulma/sass' with (
+      $primary: #ff6b35,
+      $family-primary: 'Nunito',
+      sans-serif
+    );
+  @use '@allxsmith/bestax-bulma/scss/extras';
+  ```
+
+  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,
+  and the extras `@use` then points at the shipped file
+  (`…/node_modules/@allxsmith/bestax-bulma/src/scss/extras`) since such toolchains
+  resolve raw paths, not package specifiers. Building Bulma v1 from Sass needs
+  **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).
+
+- **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
+  afterwards — the codemod never installs anything.
+
+Flag reference: `--css bulma` keeps plain `bulma/css/bulma.min.css` and adds a separate
+`@allxsmith/bestax-bulma/extras.css` import; `--css keep` leaves stylesheets alone;
+`--no-deps` skips the package.json step.
+
+## Finishing the flagged cases
+
+- **Computed Sass variables** (`$primary: lighten(#333, 10%);` and anything with
+  functions/interpolation): move them into the `with (…)` configuration by hand —
+  `with (…)` values must be compile-time literals, so resolve the expression or compute
+  it after the `@use`.
+- **Indented-syntax `.sass` files**: flagged, not rewritten. Convert `@import` lines to
+  `@use "bulma/sass" with (…)` manually (same rules as SCSS, minus semicolons/braces).
+- **Unknown 0.9 partial paths**: the v1 sass tree is `bulma/sass/{utilities,base,
+elements,form,components,grid,layout,helpers,themes}` with leaf partials like
+  `bulma/sass/utilities/initial-variables` — find the equivalent module and `@use` it.
+- **Third-party Bulma extensions** (`bulma-checkradio`, `bulma-switch`, `bulma-tooltip`,
+  …): flagged, left in place. These are 0.9-era add-ons — check each one's Bulma v1
+  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.
+
+## Choosing a CSS flavor (optional)
+
+`bestax.css` is right for almost every app. Alternatives (swap the import specifier):
+
+| Import                                                            | Use when                                                                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `@allxsmith/bestax-bulma/versions/bestax-prefixed.css`            | class conflicts with another framework — pair with `<ConfigProvider classPrefix="bestax-">` |
+| `@allxsmith/bestax-bulma/versions/bestax-no-helpers.css`          | smallest CSS; **helper props like `mt="4"` stop working**                                   |
+| `@allxsmith/bestax-bulma/versions/bestax-no-helpers-prefixed.css` | both of the above                                                                           |
+| `@allxsmith/bestax-bulma/versions/bestax-no-dark-mode.css`        | light-mode-only product                                                                     |
+
+## Custom SCSS builds with bestax
+
+Do **not** `@use '@allxsmith/bestax-bulma/scss/bestax'` when you need your own
+`$variable` overrides — that entry pre-configures `bulma/sass` and Sass forbids
+configuring a module twice. The correct pairing (what the codemod emits) is:
+
+```scss
+@use 'bulma/sass' with (
+  $primary: …
+);
+@use '@allxsmith/bestax-bulma/scss/extras';
+```
+
+Per-component partials also exist (`@use '@allxsmith/bestax-bulma/scss/components/dialog';`,
+`…/scss/form/autocomplete`, …) for modular builds.
+
+## Runtime theming
+
+Bulma v1 themes with `--bulma-*` CSS variables at runtime (dark mode is automatic).
+Sass `with (…)` is for compile-time tokens; for brand/dark-mode work use the bestax
+`Theme` component — see the `bestax-theming` skill and
+https://bestax.io/docs/guides/getting-started/migration/bulma-0-9-to-1 for the broader
+0.9 → 1 changes (Tiles → Grid, `is-bold` gradients removed, automatic dark mode).

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

@@ -0,0 +1,48 @@
+# Universal prop map (RBC modifier props → bestax helper props)
+
+react-bulma-components spreads a modifier-prop set onto every component. bestax-bulma has
+the same idea via `useBulmaClasses`, with these differences. The codemod applies all of
+this automatically for literal values; dynamic values get TODOs.
+
+## Renames and value changes
+
+| RBC                               | bestax                                                                                                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `renderAs`                        | `as` — **only** on polymorphic components (Button, Title/SubTitle, Footer, Level.Item, Media\*, Menu.Item, Navbar.Item/Link, Dropdown.Item); elsewhere flagged |
+| `domRef`                          | flagged — use a `ref` on a DOM child instead                                                                                                                   |
+| `backgroundColor`                 | `bgColor`                                                                                                                                                      |
+| `textColor`                       | `textColor` (same)                                                                                                                                             |
+| `colorVariant`                    | flagged — use `isLight` or a color shade                                                                                                                       |
+| `textSize={4}`                    | `textSize="4"` (string union `'1'`–`'7'`)                                                                                                                      |
+| `textAlign="center"`              | `textAlign="centered"` (`justify`→`justified`)                                                                                                                 |
+| `textFamily`                      | `fontFamily`                                                                                                                                                   |
+| `italic`                          | `textTransform="italic"`                                                                                                                                       |
+| `m/mt/…/py={3}`                   | `m="3"` (string union `'0'`–`'6'`)                                                                                                                             |
+| `pull="right"`                    | `float="right"`                                                                                                                                                |
+| `marginless` / `paddingless`      | `m="0"` / `p="0"`                                                                                                                                              |
+| `clipped`                         | `overflow="clipped"`                                                                                                                                           |
+| `radiusless` / `shadowless`       | `radius="radiusless"` / `shadow="shadowless"`                                                                                                                  |
+| `unselectable`                    | `interaction="unselectable"`                                                                                                                                   |
+| `hidden` / `invisible` / `srOnly` | `visibility="hidden"` / `"invisible"` / `"sr-only"`                                                                                                            |
+| `display="hidden"`                | `visibility="hidden"`                                                                                                                                          |
+| `display="relative"`              | boolean `relative`                                                                                                                                             |
+| flexbox props                     | same names/values (`flexDirection`, `justifyContent`, …)                                                                                                       |
+| `clearfix`, `overlay`             | same                                                                                                                                                           |
+
+## Boolean modifier convention
+
+RBC uses bare booleans (`loading`, `outlined`, `rounded`, `fullwidth`); bestax prefixes
+with `is`/`has` (`isLoading`, `isOutlined`, `isRounded`, `isFullWidth`). Per-component
+tables live in [component-map.md](component-map.md).
+
+## Responsive breakpoint objects → flat per-viewport props
+
+| RBC                                                                           | bestax                                                      |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `mobile={{ display: 'flex' }}`                                                | `displayMobile="flex"`                                      |
+| `tablet={{ textSize: 5 }}`                                                    | `textSizeTablet="5"`                                        |
+| `desktop={{ textAlign: 'center' }}`                                           | `textAlignDesktop="centered"`                               |
+| `widescreen={{ invisible: true }}`                                            | `visibilityWidescreen="invisible"`                          |
+| `Columns.Column mobile={{ size: 4, offset: 2, narrow: true }}`                | `sizeMobile={4} offsetMobile={2} isNarrowMobile`            |
+| `Columns tablet={{ gap: 3 }}`                                                 | `gapTablet={3}`                                             |
+| `touch={{…}}`, `untilWidescreen={{…}}`, `untilFullhd={{…}}`, `{ only: true }` | flagged — no bestax helper variants; use `className` or CSS |

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

@@ -0,0 +1,124 @@
+# Recipes for every TODO(bestax-migrate) the codemod leaves
+
+Work through `grep -rn "TODO(bestax-migrate)" src/` with these. Delete each comment once
+the site is converted.
+
+## `unsupported-file` — `.astro` / `.vue` / `.svelte` / `.mdx` imports
+
+The codemod can't parse these formats, so files in them that import
+react-bulma-components are reported (not rewritten). Migrate them by hand: swap the
+import to `@allxsmith/bestax-bulma` and apply the same renames the component/prop maps
+describe — the mapping is identical, only the rewriting is manual.
+
+## `peer-deps` — install-blocking version conflicts
+
+Reported from package.json, not a code TODO. bestax-bulma's peers: **React ^18 || ^19**
+(upgrade react/react-dom before installing — RBC v4 also ran on 17) and optional
+**@fortawesome/fontawesome-free ^6.7 || ^7** (FA 5 apps: upgrade, or
+`npm install --legacy-peer-deps` and keep FA 5 for your own `<i>` tags).
+
+## `Element` — no generic element
+
+bestax has no `Element`. Pick the semantic component (`Block`, `Box`, `Content`, …) that
+matches the usage, or plain JSX with classes:
+
+```tsx
+// Before
+<Element renderAs="span" textColor="grey" m={2}>…</Element>
+// After
+<Span textColor="grey" m="2">…</Span>   // bestax exports Span/Paragraph/Strong/etc.
+```
+
+## `Tile` — Bulma v1 replaced tiles with Grid
+
+Convert ancestor/parent/child tile trees to `Grid`/`Cell` (docs:
+https://bestax.io/docs/api/grid/grid):
+
+```tsx
+// Before
+<Tile kind="ancestor"><Tile kind="parent" size={8}><Tile kind="child">A</Tile></Tile></Tile>
+// After
+<Grid><Cell colSpan={8}>A</Cell></Grid>
+```
+
+Match the old proportions with `Cell` span props; tiles' `vertical` becomes grid flow.
+
+## Controlled `Dropdown` (`value` / `onChange`, `Dropdown.Item value`)
+
+bestax `Dropdown` is compositional — you own the selection state:
+
+```tsx
+const [choice, setChoice] = useState('a');
+<Dropdown label={labels[choice]} closeOnClick>
+  <Dropdown.Item active={choice === 'a'} onClick={() => setChoice('a')}>
+    First
+  </Dropdown.Item>
+  <Dropdown.Item active={choice === 'b'} onClick={() => setChoice('b')}>
+    Second
+  </Dropdown.Item>
+</Dropdown>;
+```
+
+## `Pagination` extras (`delta`, `next`/`previous`, `showFirstLast`, `showPrevNext`, `autoHide`)
+
+bestax `Pagination` renders from `total`/`current`/`onPageChange` with its own windowing.
+Drop `delta` (built-in), render conditionally instead of `autoHide`
+(`{total > 1 && <Pagination …/>}`), and compose `Pagination.Previous`/`Pagination.Next`
+manually if custom labels are essential.
+
+## `Modal` (`closeOnEsc`, `closeOnBlur`, `showClose`)
+
+bestax `Modal` already closes on Esc and background click and shows the close button
+whenever `onClose` is set — usually just delete these props. To hide the close button,
+omit `onClose` and render your own close control.
+
+## `touch` / `untilWidescreen` / `untilFullhd` / `{ only: true }` breakpoints
+
+No bestax helper-prop variants exist. Use Bulma classes directly:
+`className="is-hidden-touch"`, `is-flex-tablet-only`, etc. (all still exist in Bulma v1).
+
+## Icon children the parser couldn't read
+
+bestax `Icon` renders from `name` + `library` (+ `variant` for Font Awesome styles):
+
+```tsx
+<Icon name="github" library="fa" variant="brands" ariaLabel="GitHub" />
+```
+
+For icon fonts other than Font Awesome/MDI, see the `bestax-icons` skill.
+
+## Dynamic values (`state={x}`, `textSize={n}`, `align={side}`, …)
+
+The codemod only rewrites literals. Convert the expression at its source, e.g.:
+
+```tsx
+// Before: <Button state={hovered ? 'hover' : undefined}>
+<Button isHovered={hovered}>
+// Before: <Block textSize={n}>
+<Block textSize={String(n) as '1' | '2' | '3' | '4' | '5' | '6' | '7'}>
+```
+
+## Button shade colors (`black-bis`, `grey-light`, …) and `isSelected`
+
+bestax `Button` colors are the semantic set + `text`/`ghost`. For shades use
+`bgColor`/`textColor` (they accept the full palette incl. shades), and replace
+`isSelected` with `className="is-selected"` inside grouped buttons.
+
+## `colorVariant` / Hero `gradient` / Hero `halfheight`
+
+- `colorVariant="light"` → `isLight` where supported (Button, Notification), otherwise a
+  shade: `bgColor="primary-90"`.
+- Bulma v1 removed `is-bold` hero gradients — delete `gradient` or restyle with CSS.
+- `halfheight` has no bestax size; use `size="medium"` or a CSS height.
+
+## `domRef`
+
+bestax components don't take `domRef`. Most don't forward refs either — attach the ref to
+a DOM element inside, or wrap the component in a `<div ref={…}>`.
+
+## Helper props dropped from plain-element replacements
+
+Where the codemod produced a plain element (`Form.Label` → `<label>`, `Breadcrumb.Item` →
+`<li>`, `Table.Container` fallback `<div>`), Bulma helper props were dropped with a TODO.
+Re-express them as classes: `m={2}` → `className="m-2"`, `textAlign="center"` →
+`className="has-text-centered"`.