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

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

@@ -221,7 +221,10 @@ describe('ProjectCreator', () => {
         >
       ).mockResolvedValue(true);
 
-      await projectCreator.setupSkills('/target/path', 'my-app');
+      await projectCreator.setupSkills('/target/path', 'my-app', {
+        bulmaFlavor: 'complete',
+        iconLibrary: 'none',
+      });
 
       expect(fs.default.copy).toHaveBeenCalledWith(
         expect.stringContaining('skills'),
@@ -231,6 +234,32 @@ describe('ProjectCreator', () => {
         expect.stringContaining('CLAUDE.md'),
         expect.stringContaining('my-app')
       );
+      const written = (
+        fs.default.writeFile as unknown as jest.Mock
+      ).mock.calls.find(([p]) => String(p).includes('CLAUDE.md'))?.[1];
+      expect(written).toContain('Bulma flavor: **complete**');
+      expect(written).toContain('No icon library is installed');
+      expect(written).not.toContain('classPrefix');
+    });
+
+    it('documents the prefix caveat and icon library for a prefixed scaffold', async () => {
+      (
+        fileSystem.checkDirectoryExists as jest.MockedFunction<
+          typeof fileSystem.checkDirectoryExists
+        >
+      ).mockResolvedValue(true);
+
+      await projectCreator.setupSkills('/target/path', 'my-app', {
+        bulmaFlavor: 'prefixed',
+        iconLibrary: 'fontawesome',
+      });
+
+      const written = (
+        fs.default.writeFile as unknown as jest.Mock
+      ).mock.calls.find(([p]) => String(p).includes('CLAUDE.md'))?.[1];
+      expect(written).toContain('classPrefix="bestax-"');
+      expect(written).toContain('bestax-prefixed.css');
+      expect(written).toContain('Icon library: **Font Awesome**');
     });
 
     it('skips when the skills bundle is missing', async () => {
@@ -240,7 +269,10 @@ describe('ProjectCreator', () => {
         >
       ).mockResolvedValue(false);
 
-      await projectCreator.setupSkills('/target/path', 'my-app');
+      await projectCreator.setupSkills('/target/path', 'my-app', {
+        bulmaFlavor: 'complete',
+        iconLibrary: 'none',
+      });
 
       expect(fs.default.copy).not.toHaveBeenCalled();
       expect(fs.default.writeFile).not.toHaveBeenCalled();

create-bestax/src/constants.ts

@@ -44,12 +44,54 @@ export const PROMPTS = {
 } as const;
 
 // Minimal CLAUDE.md scaffolded alongside the skills so an AI agent knows the
-// stack and where the skills live.
-export const CLAUDE_MD = (projectName: string): string => `# ${projectName}
+// stack, this app's scaffold choices, and where the skills live. Kept short:
+// it loads into every agent session.
+export interface ClaudeMdOptions {
+  bulmaFlavor: string;
+  iconLibrary: string;
+}
+
+export const CLAUDE_MD = (
+  projectName: string,
+  { bulmaFlavor, iconLibrary }: ClaudeMdOptions
+): string => {
+  const flavor = BULMA_FLAVORS.find(f => f.name === bulmaFlavor);
+  const icon = ICON_LIBRARIES.find(lib => lib.name === iconLibrary);
+  const setupLines = [
+    `- Bulma flavor: **${bulmaFlavor}** — the app imports **prebuilt** CSS` +
+      (flavor ? ` (\`${flavor.importStatement.trim()}\`)` : '') +
+      `; there is no Sass pipeline unless you add \`sass\`.`,
+  ];
+  if (flavor?.needsPrefix) {
+    setupLines.push(
+      `- Every Bulma class carries the \`bestax-\` prefix and the app is wrapped in ` +
+        `\`<ConfigProvider classPrefix="bestax-">\` — custom CSS selectors must match the prefix.`
+    );
+  }
+  setupLines.push(
+    iconLibrary === 'none'
+      ? `- No icon library is installed — add one before using \`<Icon>\` ` +
+          `(https://bestax.io/docs/api/elements/icon).`
+      : `- Icon library: **${icon?.display ?? iconLibrary}** — use \`<Icon name="..." />\`.`
+  );
+  return `# ${projectName}
 
 This app is built with [\`@allxsmith/bestax-bulma\`](https://bestax.io) — React components for
 Bulma 1.x.
 
+## This app's setup
+
+${setupLines.join('\n')}
+
+## House style
+
+- Never inline \`style={{}}\` — use the helper props every component accepts (\`m*\`/\`p*\`
+  spacing, \`textColor\`/\`bgColor\`, \`display="flex"\`, \`flexDirection\`, \`alignItems\`).
+  There is no \`gap\` helper — space children with margins.
+- 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.
+
 ## AI skills
 
 \`.claude/skills/\` contains Agent Skills that teach Claude how to build with this library. They load
@@ -68,6 +110,7 @@ Prefer the library's components and these skills over hand-written Bulma markup
 - LLM-ready docs: https://bestax.io/llms.txt (curated index) and https://bestax.io/llms-full.txt
 - Using bestax with AI tools: https://bestax.io/docs/guides/llms
 `;
+};
 
 export interface IconLibrary {
   name: string;

create-bestax/src/project-creator.ts

@@ -30,6 +30,7 @@ import {
   ICON_LIBRARIES,
   BULMA_FLAVORS,
   CLAUDE_MD,
+  type ClaudeMdOptions,
 } from './constants.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -101,7 +102,11 @@ export class ProjectCreator {
     await copyDirectory(templatePath, targetPath);
   }
 
-  async setupSkills(targetPath: string, projectName: string): Promise<void> {
+  async setupSkills(
+    targetPath: string,
+    projectName: string,
+    options: ClaudeMdOptions
+  ): Promise<void> {
     const skillsSrc = path.join(this.templatesDir, 'skills');
     if (!(await checkDirectoryExists(skillsSrc))) {
       console.log(
@@ -113,7 +118,7 @@ export class ProjectCreator {
     await fs.copy(skillsSrc, path.join(targetPath, '.claude', 'skills'));
     await fs.writeFile(
       path.join(targetPath, 'CLAUDE.md'),
-      CLAUDE_MD(projectName)
+      CLAUDE_MD(projectName, options)
     );
     console.log(chalk.green(MESSAGES.SKILLS_ADDED));
   }
@@ -557,7 +562,10 @@ export class ProjectCreator {
         template
       );
       if (installSkills) {
-        await this.setupSkills(targetPath, projectName);
+        await this.setupSkills(targetPath, projectName, {
+          bulmaFlavor,
+          iconLibrary,
+        });
       }
       displaySuccess(targetDir);
     } catch (error) {