bestax-mcp 0.0.0

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

@@ -0,0 +1,269 @@
+# Layout component inventory
+
+Self-contained reference for the `@allxsmith/bestax-bulma` layout components. All values are
+source-verified. Import everything from the package root:
+
+```tsx
+import {
+  Container,
+  Section,
+  Hero,
+  Footer,
+  Level,
+  Columns,
+  Column,
+  Grid,
+  Cell,
+  Navbar,
+  Menu,
+  Card,
+} from '@allxsmith/bestax-bulma';
+```
+
+Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `textAlign`,
+`textColor`, `bgColor`, etc.). Flex helpers take the standard CSS values spelled in full:
+`justifyContent="space-between"`, `alignItems="center"`.
+
+> **Use helper props, never inline `style`, for spacing / alignment / color.** `mt="4"` (= 1rem)
+> not `style={{ marginTop: '1rem' }}`; `textAlign="centered"` not `style={{ textAlign: 'center' }}`;
+> `textColor="grey"` / `bgColor="light"` not `style={{ color }}`. Spacing scale is `0`–`6` | `auto`
+> (`4` = 1rem). Reserve `style`/CSS vars only for values the design system doesn't tokenize.
+
+> **There is no `Tile` component.** For uniform grids (cards, galleries) use `Grid` / `Cell` —
+> equal-height cells for free; for proportional or per-breakpoint layouts use
+> `Columns` / `Column`.
+
+## Container
+
+`<Container>` centers and constrains page content.
+
+| Prop                              | Type                                    | Notes                                     |
+| --------------------------------- | --------------------------------------- | ----------------------------------------- |
+| `fluid`                           | `boolean`                               | Full width with a small gutter.           |
+| `widescreen` / `fullhd`           | `boolean`                               | Only constrain at that breakpoint and up. |
+| `breakpoint`                      | `'tablet' \| 'desktop' \| 'widescreen'` | Max-width breakpoint.                     |
+| `isMax`                           | `boolean`                               | Use the `is-max-*` width.                 |
+| `color` / `textColor` / `bgColor` | Bulma color                             | —                                         |
+
+## Section
+
+`<Section>` adds vertical page rhythm (padding).
+
+| Prop                              | Type                                     |
+| --------------------------------- | ---------------------------------------- |
+| `size`                            | `'medium' \| 'large'` (omit for default) |
+| `color` / `textColor` / `bgColor` | Bulma color                              |
+
+## Hero
+
+`<Hero>` is a full-width banner. Subcomponents: `Hero.Head`, `Hero.Body`, `Hero.Foot`.
+
+| Prop                   | Type                                                                                                                                                                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color`                | `primary \| link \| info \| success \| warning \| danger \| black \| white \| light \| dark` (CSS-backed). Also accepted but deprecated, no CSS, dev-warn: `black-bis`, `black-ter`, the greys, `inherit`, `current` |
+| `size`                 | `'small' \| 'medium' \| 'large' \| 'fullheight' \| 'fullheight-with-navbar'`                                                                                                                                         |
+| `fullheightWithNavbar` | `boolean`                                                                                                                                                                                                            |
+
+```tsx
+<Hero color="primary" size="medium">
+  <Hero.Body>…</Hero.Body>
+</Hero>
+```
+
+## Footer
+
+`<Footer>` is the page footer.
+
+| Prop                              | Type                |
+| --------------------------------- | ------------------- |
+| `as`                              | `'footer' \| 'div'` |
+| `color` / `textColor` / `bgColor` | Bulma color         |
+
+## Level
+
+`<Level>` is a horizontal toolbar (left/right groups). Subcomponents: `Level.Left`, `Level.Right`,
+`Level.Item`.
+
+| Prop                         | Type                                  |
+| ---------------------------- | ------------------------------------- |
+| `Level.isMobile`             | `boolean` (keep horizontal on mobile) |
+| `Level.Item.as`              | `'div' \| 'p' \| 'a'`                 |
+| `Level.Item.hasTextCentered` | `boolean`                             |
+
+## Columns / Column
+
+The responsive grid. `Columns` is the row; `Column` is a cell (also reachable as
+`Columns.Column`).
+
+**Columns**
+
+| Prop                                                                             | Type                                                     |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `isMultiline`                                                                    | `boolean` (wrap cells onto new rows)                     |
+| `isCentered`                                                                     | `boolean` (center the row)                               |
+| `isVCentered`                                                                    | `boolean` (vertical centering — capital V)               |
+| `isGapless`                                                                      | `boolean`                                                |
+| `isMobile`                                                                       | `boolean` (stay side-by-side on mobile)                  |
+| `isDesktop`                                                                      | `boolean`                                                |
+| `gap` / `gapMobile` / `gapTablet` / `gapDesktop` / `gapWidescreen` / `gapFullhd` | `0`–`8` (number or string, same scale as `Grid`'s `gap`) |
+
+**Column**
+
+| Prop                                                                                                                                               | Type              |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `size` (+ `sizeMobile` / `sizeTablet` / `sizeDesktop` / `sizeWidescreen` / `sizeFullhd`)                                                           | `BulmaColumnSize` |
+| `offset` (+ per-breakpoint)                                                                                                                        | `BulmaColumnSize` |
+| `isNarrow` (+ per-breakpoint: `isNarrowMobile` / `isNarrowTablet` / `isNarrowTouch` / `isNarrowDesktop` / `isNarrowWidescreen` / `isNarrowFullhd`) | `boolean`         |
+
+```ts
+type BulmaColumnSize =
+  | number // 1–12
+  | 'full'
+  | 'half'
+  | 'one-third'
+  | 'two-thirds'
+  | 'one-quarter'
+  | 'three-quarters'
+  | 'one-fifth'
+  | 'two-fifths'
+  | 'three-fifths'
+  | 'four-fifths';
+```
+
+Numeric sizes are **numbers** — `sizeDesktop={7}`, never `"7"`; only the fraction names are
+strings. (`gap` is the exception that accepts number **or** string.)
+
+> Columns **stack on mobile** by default and go side-by-side at the tablet breakpoint and up.
+> Use the per-breakpoint `size*` props to control how many cells share a row at each width.
+
+**Equal-height cards inside Columns** — columns are equal height, but a card inside one does
+**not** stretch to fill it (and `height: 100%` on the card doesn't help — it resolves against
+the column's auto height). Make the `Column` a flex container and let the card grow:
+
+```tsx
+<Columns isMultiline>
+  {items.map(item => (
+    <Column
+      key={item.id}
+      sizeTablet="half"
+      sizeDesktop="one-third"
+      display="flex"
+      flexDirection="column"
+    >
+      <Card flexGrow="1">{item.blurb}</Card>
+    </Column>
+  ))}
+</Columns>
+```
+
+`display`, `flexDirection`, and `flexGrow` are helper props every component accepts;
+`flexGrow` takes a string (`"1"`).
+
+## Grid / Cell
+
+Bulma's CSS Grid (`Cell` is also reachable as `Grid.Cell`). **Preferred for uniform grids** — same-shaped items in a repeating pattern
+(card grids, galleries, dashboards): CSS Grid gives **equal-height cells for free** (per row —
+each row's cells match its tallest), with no flex recipe needed. Reach for `Columns`/`Column` instead when you need proportional or
+per-breakpoint column _sizes_ (a 2/3 + 1/3 split, different counts per breakpoint).
+
+**Grid**
+
+| Prop                                                                                                                   | Type                                                         |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `gap` / `columnGap` / `rowGap`                                                                                         | `0`–`8` (number or string, same scale as Columns' `gap`)     |
+| `minCol`                                                                                                               | `1`–`32` (smart grid: min column width step, `is-col-min-X`) |
+| `isFixed`                                                                                                              | `boolean` (fixed column count instead of auto-fill)          |
+| `fixedCols` (+ `fixedColsMobile` / `fixedColsTablet` / `fixedColsDesktop` / `fixedColsWidescreen` / `fixedColsFullhd`) | `0`–`12` or `'auto'` (fixed grid only)                       |
+
+**Cell**
+
+| Prop                                  | Type                                    |
+| ------------------------------------- | --------------------------------------- |
+| `colStart` / `colFromEnd` / `colSpan` | `number` (manual column placement/span) |
+| `rowStart` / `rowFromEnd` / `rowSpan` | `number` (manual row placement/span)    |
+
+By default the smart grid **auto-fills**: cells flow into as many columns as fit (tune the
+minimum width with `minCol`). `isFixed` + `fixedCols*` pins an exact column count per
+breakpoint instead.
+
+```tsx
+// Uniform card grid — equal heights for free, responsive column count for free.
+<Grid
+  isFixed
+  fixedColsMobile={1}
+  fixedColsTablet={2}
+  fixedColsDesktop={3}
+  gap={4}
+>
+  {items.map(item => (
+    <Cell key={item.id}>
+      <Card header={item.name}>{item.blurb}</Card>
+    </Cell>
+  ))}
+</Grid>
+```
+
+> To stretch each card to its cell's full (equal) height, the same `display="flex"
+flexDirection="column"` + `flexGrow="1"` pattern applies to `Cell` + `Card`.
+
+## Navbar
+
+`<Navbar>` is the top bar. Subcomponents: `Navbar.Brand`, `Navbar.Item`, `Navbar.Link`,
+`Navbar.Burger`, `Navbar.Menu`, `Navbar.Start`, `Navbar.End`, `Navbar.Dropdown`,
+`Navbar.DropdownMenu`, `Navbar.Divider`.
+
+| Prop            | Type                                                                                                             |
+| --------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `fixed`         | `'top' \| 'bottom'`                                                                                              |
+| `transparent`   | `boolean`                                                                                                        |
+| `color`         | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'black' \| 'dark' \| 'light' \| 'white'` |
+| `Navbar.Item`   | `as?`, `active?`, `href`                                                                                         |
+| `Navbar.Burger` | `active?`, `onClick`                                                                                             |
+| `Navbar.Menu`   | `active?` (toggled open on mobile)                                                                               |
+
+The burger/menu is controlled state — toggle `Navbar.Burger active`/`onClick` and pass the same
+flag to `Navbar.Menu active`. **A `fixed="top"` navbar requires `has-navbar-fixed-top` on `<html>`**
+(Bulma offsets the page from it); the library adds no helper. Set it statically —
+`<html class="has-navbar-fixed-top">` in `index.html` — reserving a `classList.add` effect for
+a navbar that mounts conditionally.
+
+**Routing:** in a routed app, don't use `href="#"` — render items as the router's link
+component. `Menu.Item as={Link} to="/x"` and `Navbar.Item as={Link} to="/x"` both compile
+without casts (their props allow extra keys). Drive `active` from `useLocation().pathname`.
+Full patterns (including Buttons that navigate and Next.js `href`): the docs guide at
+https://bestax.io/docs/guides/features/routing.
+
+## Menu
+
+`<Menu>` is a vertical sidebar menu. Subcomponents: `Menu.Label`, `Menu.List`, `Menu.Item`.
+
+| Prop        | Type                                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| `Menu.Item` | `active?`, `href?`, `as?` (custom link component); nest a `Menu.List` inside an item for submenus |
+
+```tsx
+<Menu>
+  <Menu.Label>General</Menu.Label>
+  <Menu.List>
+    <Menu.Item active href="#">
+      Dashboard
+    </Menu.Item>
+    <Menu.Item href="#">Customers</Menu.Item>
+  </Menu.List>
+</Menu>
+```
+
+## Card
+
+`<Card>` for catalog/grid items. Use the props form (`header`, `image`, `footer`) or the compound
+subcomponents (`Card.Header` + `.Title`/`.Icon`, `Card.Image`, `Card.Content`, `Card.Footer`,
+`Card.FooterItem`).
+
+| Prop                            | Type                          |
+| ------------------------------- | ----------------------------- |
+| `header`                        | `ReactNode`                   |
+| `image`                         | `string` (URL) or `ReactNode` |
+| `imageAlt`                      | `string`                      |
+| `footer`                        | `ReactNode \| ReactNode[]`    |
+| `hasShadow`                     | `boolean` (default `true`)    |
+| `headerCentered` / `headerIcon` | `boolean` / `ReactNode`       |

package/data/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/data/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/data/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/data/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 |