feat(create-bestax): scaffold-aware CLAUDE.md with setup facts and house style

[allxsmith]

Description

Part of the AI-enrichment plan (PR 5): the CLAUDE.md that npm create bestax writes into
scaffolded apps now tells the app's AI agent the facts it cannot infer from the code — the
scaffold choices — plus three house-style rules. Kept deliberately short (it loads into every
agent session in the generated app).

Affected package(s):

• create-bestax (create-bestax)

Related Issue(s)

Refs #263

Type of Change

• New feature

What changed

• CLAUDE_MD(projectName) → CLAUDE_MD(projectName, { bulmaFlavor, iconLibrary })
  (src/constants.ts), generating a "This app's setup" section: the chosen Bulma flavor
  with its exact CSS import and a no-Sass-pipeline note; for prefixed flavors, the
  bestax- prefix + ConfigProvider classPrefix caveat (custom CSS selectors must match);
  the icon library (or "none installed — add one before using <Icon>").
• A "House style" section (3 bullets): no inline style={{}} — helper props (no gap
  helper; margins); compose + theme via Theme/--bulma-* vars, never hardcoded colors;
  no test runner/Storybook present — don't assume one.
• setupSkills threads the options through (src/project-creator.ts).
• Tests: existing setupSkills specs updated; new spec asserts the prefixed+fontawesome
  output (prefix caveat, flavor import, icon line) and that the default output has no
  prefix caveat.

Example output (prefixed + Font Awesome): see the "This app's setup" section — verified by
building the package and scaffolding a real app
(node dist/index.js app-prefixed -t vite-ts --bulma prefixed --icon fontawesome -y).

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• All new and existing tests passed (179 tests; coverage 97.9% stmts / 87.9% branches,
  thresholds 95/78)
• The affected CLAUDE.md files are updated (create-bestax/CLAUDE.md's sync rule already
  covers "check the CLAUDE_MD template when conventions change" — unchanged)

Test plan

• pnpm --filter create-bestax run typecheck, lint, test:coverage, build
• pnpm run format:check on touched files
• End-to-end: built and scaffolded a real app with --bulma prefixed --icon fontawesome;
  generated CLAUDE.md contains the setup facts and house style verbatim

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Generated CLAUDE.md now adapts to the chosen Bulma flavor, including the correct CSS import guidance and “House style” notes.
  • CLAUDE.md documentation also reflects the selected icon library, with accurate setup instructions (including cases where no icon library is installed).

• Tests

  • Expanded test coverage for CLAUDE.md generation across multiple scaffolding configurations.
  • Updated and added assertions to verify behavior when the skills bundle is missing and when icon/CSS prefix options are customized.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9a527a38-1a1a-4e07-b998-be5c98244574

📥 Commits

Reviewing files that changed from the base of the PR and between 20013cc and be26af5.

📒 Files selected for processing (3)

• create-bestax/src/__tests__/project-creator.test.ts
• create-bestax/src/constants.ts
• create-bestax/src/project-creator.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• create-bestax/src/constants.ts
• create-bestax/src/tests/project-creator.test.ts

---

Walkthrough

Changes

Claude scaffold documentation

Layer / File(s)	Summary
Dynamic Claude markdown generation create-bestax/src/constants.ts	CLAUDE_MD now accepts Bulma and icon library options, adds setup and house-style sections, and shares mapped icon-provider values with scaffold generation.
Skills option wiring and validation create-bestax/src/project-creator.ts, create-bestax/src/__tests__/project-creator.test.ts	ProjectCreator forwards scaffold options to Claude documentation generation, and tests verify generated content for default, prefixed, MDI, Ionicons, and missing-bundle cases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ProjectCreator
  participant setupSkills
  participant CLAUDE_MD
  participant FileSystem
  ProjectCreator->>setupSkills: pass Bulma flavor and icon library
  setupSkills->>CLAUDE_MD: generate configured CLAUDE.md
  CLAUDE_MD-->>setupSkills: return markdown content
  setupSkills->>FileSystem: write CLAUDE.md

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: scaffold-aware CLAUDE.md generation with setup facts and house style.
Description check	✅ Passed	The description covers the change summary, affected package, issue reference, type, checklist, and test plan, matching the template well.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/create-bestax-claude-md

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview Deployment

Preview URL: https://9fe829f4.bestax.pages.dev

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

create-bestax/src/constants.ts (1)

49-52: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Widen ClaudeMdOptions types for compile-time safety.

bulmaFlavor/iconLibrary are typed as plain string, so a typo'd flavor/icon name compiles fine and silently falls through to the "not found" fallback text in CLAUDE_MD. Deriving a union from BULMA_FLAVORS/ICON_LIBRARIES names would catch mismatches at compile time.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@create-bestax/src/constants.ts` around lines 49 - 52, Update ClaudeMdOptions
so bulmaFlavor and iconLibrary use unions derived from the keys or names of
BULMA_FLAVORS and ICON_LIBRARIES rather than string, ensuring callers receive
compile-time validation and remain synchronized with the supported constants.

create-bestax/src/__tests__/project-creator.test.ts (1)

245-262: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Consider adding a test for icon libraries requiring ConfigProvider iconLibrary.

Given the doc gap flagged in constants.ts (missing caveat for mdi/ionicons/material-icons/material-symbols), a test asserting CLAUDE.md mentions the ConfigProvider iconLibrary="mdi" wrapper would lock in the fix and prevent regression.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@create-bestax/src/__tests__/project-creator.test.ts` around lines 245 - 262,
Extend the project-creator documentation tests with a case for an icon library
requiring ConfigProvider configuration, such as mdi. In the test covering
projectCreator.setupSkills and generated CLAUDE.md content, use the mdi
iconLibrary option and assert the output mentions the ConfigProvider
iconLibrary="mdi" wrapper and its required caveat.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@create-bestax/src/constants.ts`:
- Around line 60-76: CLAUDE.md generation in the setupLines construction omits
the ConfigProvider requirement for non-default icon libraries. Update the
icon-library documentation branch to add a bullet for mdi, ionicons,
material-icons, and material-symbols stating that App is already wrapped with
ConfigProvider iconLibrary="..." and custom configuration should avoid
duplicating or conflicting with it; keep the existing none and default-library
guidance intact.

---

Nitpick comments:
In `@create-bestax/src/__tests__/project-creator.test.ts`:
- Around line 245-262: Extend the project-creator documentation tests with a
case for an icon library requiring ConfigProvider configuration, such as mdi. In
the test covering projectCreator.setupSkills and generated CLAUDE.md content,
use the mdi iconLibrary option and assert the output mentions the ConfigProvider
iconLibrary="mdi" wrapper and its required caveat.

In `@create-bestax/src/constants.ts`:
- Around line 49-52: Update ClaudeMdOptions so bulmaFlavor and iconLibrary use
unions derived from the keys or names of BULMA_FLAVORS and ICON_LIBRARIES rather
than string, ensuring callers receive compile-time validation and remain
synchronized with the supported constants.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f1e0e1e9-d8c4-4f4c-9b73-f624926d4b33

📥 Commits

Reviewing files that changed from the base of the PR and between 306e3cb and 20013cc.

📒 Files selected for processing (3)

• create-bestax/src/__tests__/project-creator.test.ts
• create-bestax/src/constants.ts
• create-bestax/src/project-creator.ts

[claude]

Deep review — 0 finding(s)

No.	Severity	Area	Finding	Location
—	—	—	No blocking defects found.	—

Overall: This is a tightly-scoped documentation change to the CLAUDE_MD scaffold template plus its setupSkills call site, and it holds up. Every fact the generated CLAUDE.md now asserts checks out against the real code — the helper props (flexDirection, alignItems, bgColor, textColor, display) exist in useBulmaClasses/useFlexboxClasses/useColorClasses, the classPrefix="bestax-" string matches project-creator.ts:409, the prebuilt CSS import strings match BULMA_FLAVORS, and the templates genuinely ship no test runner. The riskiest surface would have been the new ClaudeMdOptions param flowing a possibly-null bulmaFlavor/iconLibrary into the template, but the upstream process.exit(1) branches narrow both to string, typecheck passes, and the new tests cover the prefixed/complete and fontawesome/none branches. The defensive fallbacks are unreachable given upstream validation but harmless.

🏄 Chill little docs wave, dude — the scaffold now whispers the right setup facts into every app's AI agent, and every claim actually lines up with the code. Clean paddle-out, no wipeouts. Good to go.

[github-actions]

Preview Deployment

Preview URL: https://e0107251.bestax.pages.dev

[claude]

Blanket "space children with margins" overreaches past the flex context — 🟡 Minor · API

What: The bullet lists flexbox helpers, then states There is no gap helper — space children with margins. That is accurate for the flex/generic helper props (useFlexboxClasses/useBulmaClasses emit no gap class), but read as blanket advice it contradicts the library's own grid API: Grid accepts gap, columnGap, and rowGap props (bulma-ui/src/grid/Grid.tsx), and Columns has its own gap controls.

Why it matters: This file ships as the authoritative CLAUDE.md loaded into every agent session in the scaffolded app, and one of the bundled skills (bestax-layout-scaffold) explicitly builds card grids. An agent told to "space children with margins" may hand-roll margins on a Grid/Columns layout instead of the idiomatic gap prop — the exact custom-styling the house-style section is trying to prevent.

Fix: scope the sentence to flex, so it no longer reads as universal.

Suggested change

	There is no \`gap\` helper — space children with margins.
	There is no flexbox `gap` helper — space flex children with margins (for
	grid/column layouts use `Grid`'s `gap`/`columnGap`/`rowGap` or `Columns`).

[claude]

Deep review — 1 finding

#	Severity	Area	Finding	Location
1	🟡 Minor	API	"Space children with margins" reads as blanket advice but Grid/Columns expose real gap props	create-bestax/src/constants.ts:90

Overall: The change is sound and low-risk — it threads the already-collected bulmaFlavor/iconLibrary into the generated CLAUDE.md and nothing else. I verified every factual claim in the new template against the library: textColor/bgColor, display/flexDirection/alignItems are genuine helper props (43 components expose the color pair), classPrefix/ConfigProvider exist, and both Vite templates really ship no test runner or Storybook. The signature change to CLAUDE_MD/setupSkills has no stray callers, tests pass (179/179), and the two new specs cover the prefixed and default branches. The only thing to weigh is guidance accuracy in shipped content: the flat "space children with margins" line can steer an agent away from the idiomatic gap prop on Grid/Columns — the human should decide whether to scope it to the flex context.

🏄 Clean little swell, dude — just docs riding into the generated app, all the facts check out and the tests are glassy. One tiny ripple where the "no gap" call paddles a bit past the flex break, but nothing's gonna wipe you out here. Good to go.

[github-actions]

Preview Deployment

Preview URL: https://371afcee.bestax.pages.dev

[github-actions]

🎉 This PR is included in version 3.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 5.4.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀