beaver-build 1.0.6 → 1.0.7

package/dist/index.js

@@ -44,7 +44,7 @@ var init_constants = __esm({
 });
 
 // src/options/react-vite/constants/index.ts
-var REACT_MENU_LAYOUT, REACT_MENU_ROUTER, REACT_MENU_STATE_MANAGEMENT, REACT_MENU_QUERY, REACT_MENU_CSS, REACT_MENU_LINTER;
+var REACT_MENU_LAYOUT, REACT_MENU_ROUTER, REACT_MENU_STATE_MANAGEMENT, REACT_MENU_QUERY, REACT_MENU_CSS, REACT_MENU_LINTER, REACT_MENU_TESTING, REACT_MENU_AI;
 var init_constants2 = __esm({
   "src/options/react-vite/constants/index.ts"() {
     "use strict";
@@ -138,6 +138,40 @@ var init_constants2 = __esm({
         disabled: false
       }
     };
+    REACT_MENU_TESTING = {
+      notUsing: {
+        display: "Not Using",
+        value: "NOT_USING",
+        description: "No testing setup",
+        disabled: false
+      },
+      vitest: {
+        display: "Vitest",
+        value: "VITEST",
+        description: "Unit + component testing with Vitest v3.2.4 + Testing Library",
+        disabled: false
+      },
+      playwright: {
+        display: "Playwright",
+        value: "PLAYWRIGHT",
+        description: "End-to-end testing with Playwright v1.52.0",
+        disabled: false
+      }
+    };
+    REACT_MENU_AI = {
+      notUsing: {
+        display: "Not Using",
+        value: "NOT_USING",
+        description: "No AI setup",
+        disabled: false
+      },
+      claude: {
+        display: "Claude (Claude Code)",
+        value: "CLAUDE",
+        description: "CLAUDE.md + .claude/ agents + feature docs structure",
+        disabled: false
+      }
+    };
   }
 });
 
@@ -225,6 +259,16 @@ var init_package_json = __esm({
         devDeps["globals"] = "15.15.0";
         devDeps["typescript-eslint"] = "8.26.0";
       }
+      if (cart.testing === "VITEST") {
+        devDeps["vitest"] = "3.2.4";
+        devDeps["@vitest/coverage-v8"] = "3.2.4";
+        devDeps["@testing-library/react"] = "16.3.0";
+        devDeps["@testing-library/jest-dom"] = "6.6.3";
+        devDeps["jsdom"] = "26.1.0";
+      }
+      if (cart.testing === "PLAYWRIGHT") {
+        devDeps["@playwright/test"] = "1.52.0";
+      }
       const scripts = {
         dev: "vite",
         build: "tsc && vite build",
@@ -236,6 +280,18 @@ var init_package_json = __esm({
       } else if (cart.linter === "ESLINT") {
         scripts["lint"] = "eslint .";
       }
+      if (cart.testing === "VITEST") {
+        scripts["test"] = "vitest";
+        scripts["test:run"] = "vitest run";
+        scripts["coverage"] = "vitest run --coverage";
+      }
+      if (cart.testing === "PLAYWRIGHT") {
+        scripts["test:e2e"] = "playwright test";
+      }
+      if (cart.ai === "CLAUDE") {
+        scripts["docs:index"] = "node .claude/scripts/build-docs-index.mjs";
+        scripts["docs:lint"] = "node .claude/scripts/lint-docs-frontmatter.mjs";
+      }
       return JSON.stringify(
         {
           name: cart.projectName,
@@ -714,555 +770,999 @@ declare module '*.css' {
   }
 });
 
-// src/scaffold/react-vite/templates/copilot-instructions.ts
-var FSD_PATHS, BPR_PATHS, frontmatter, generalTemplate, componentsTemplate, hooksTemplate, routerTemplate, zustandTemplate, queryTemplate, tailwindTemplate, importsTemplate, linterTemplate, getCopilotInstructionFiles;
-var init_copilot_instructions = __esm({
-  "src/scaffold/react-vite/templates/copilot-instructions.ts"() {
+// src/scaffold/shared/claude-setup.ts
+var STATUS_ENUM, LANG_ENUM, docsTemplateMdTemplate, docsReadmeTemplate, docsIndexPlaceholderTemplate, docsSharedMjsTemplate, buildDocsIndexMjsTemplate, lintDocsFrontmatterMjsTemplate, docsFirstReminderShTemplate, claudeSettingsTemplate, docsSkillTemplate, docsWriterAgentTemplate, agentMemorySeedTemplate, buildClaudeFileMap;
+var init_claude_setup = __esm({
+  "src/scaffold/shared/claude-setup.ts"() {
     "use strict";
-    FSD_PATHS = {
-      components: "src/**/ui/**/*.tsx,src/shared/ui/**/*.tsx",
-      hooks: "src/**/model/**/*.ts,src/**/lib/**/*.ts",
-      stores: "src/shared/lib/store.ts,src/**/model/**/*.ts",
-      apis: "src/**/api/**/*.ts",
-      routes: "src/routes/**/*.tsx"
-    };
-    BPR_PATHS = {
-      components: "src/components/**/*.tsx,src/features/*/components/**/*.tsx",
-      hooks: "src/hooks/**/*.ts,src/features/*/hooks/**/*.ts",
-      stores: "src/stores/**/*.ts,src/features/*/stores/**/*.ts",
-      apis: "src/features/*/api/**/*.ts,src/lib/**/*.ts",
-      routes: "src/routes/**/*.tsx"
-    };
-    frontmatter = (applyTo) => `---
-applyTo: "${applyTo}"
+    STATUS_ENUM = ["active", "draft", "deprecated"];
+    LANG_ENUM = ["en", "vi"];
+    docsTemplateMdTemplate = (flowEnum3, layerEnum3) => `---
+title: <Concise title; mirror the H1 below>
+feature: _app        # feature folder name under docs/features/ | _app (cross-cutting)
+flow: _meta          # enum: ${flowEnum3.join(" | ")}
+layer: _cross        # enum: ${layerEnum3.join(" | ")}
+status: active       # enum: ${STATUS_ENUM.join(" | ")}
+lang: en             # enum: ${LANG_ENUM.join(" | ")}
+related: []          # array of doc paths relative to docs/
+keywords: []         # lowercase kebab-case; prefer real symbol/file names from the repo
+updated: YYYY-MM-DD
 ---
 
+# <Title>
+
+## Context
+What problem was being solved and why it was non-obvious.
+
+## Root Cause / Key Finding
+The core discovery that unblocked the task.
+
+## Solution / Pattern
+What was implemented and why.
+
+## Key Decisions
+Trade-offs made and alternatives rejected.
+
+## Related Files
+- path/to/relevant/file.ts
 `;
-    generalTemplate = (cart) => {
-      const isFsd = cart.layout === "FSD";
-      const stackLines = [
-        "- React 19 + Vite 6 + TypeScript 5",
-        `- Architecture: ${isFsd ? "Feature-Sliced Design (FSD)" : "Bulletproof React (BPR)"}`,
-        cart.router === "TANSTACK_ROUTER" ? "- Routing: TanStack Router (file-based)" : "- Routing: none",
-        cart.stateManagement === "ZUSTAND" ? "- State: Zustand" : "- State: local React state only",
-        cart.query === "TANSTACK_QUERY" ? "- Server state: TanStack Query" : "- Server state: none",
-        cart.css === "TAILWIND" ? "- CSS: Tailwind CSS v4.1.3 (Vite plugin, `src/index.css`)" : "- CSS: plain CSS",
-        cart.linter === "BIOME" ? "- Linter/formatter: Biome (`biome.json`)" : cart.linter === "ESLINT" ? "- Linter: ESLint (`eslint.config.js`)" : "- Linter: none"
-      ].join("\n");
-      const layoutBlock = isFsd ? `## Architecture \u2014 Feature-Sliced Design
-
-Layer order (top \u2192 bottom): \`app \u2192 pages \u2192 widgets \u2192 features \u2192 entities \u2192 shared\`.
-A layer may only import from layers **below** it. Never import from \`features\` inside \`shared\`, never import from \`pages\` inside \`widgets\`, and so on.
-
-Inside every slice, only these segments are allowed \u2014 do not invent new ones:
-
-- \`ui/\` \u2014 React components for the slice
-- \`model/\` \u2014 state, hooks, selectors, slice-local types
-- \`api/\` \u2014 network calls, request/response types
-- \`lib/\` \u2014 pure helpers specific to the slice
-- \`config/\` \u2014 constants, enums
-
-Where new code belongs:
-
-- Reusable primitive (Button, Input) \u2192 \`src/shared/ui/<Name>/\`
-- Cross-cutting helper \u2192 \`src/shared/lib/\`
-- Domain model (User, Post) \u2192 \`src/entities/<name>/\`
-- User-facing interaction (LoginForm) \u2192 \`src/features/<name>/\`
-- Composition of features \u2192 \`src/widgets/<name>/\`
-- Page-level composition \u2192 \`src/pages/<name>/ui/<Name>Page.tsx\` with \`src/pages/<name>/index.ts\` barrel
-
-Pages **compose** widgets/features \u2014 no business logic inside \`pages/*/ui\`.
-` : `## Architecture \u2014 Bulletproof React
-
-Global, cross-feature folders directly under \`src/\`:
-
-- \`components/\` \u2014 app-wide reusable UI primitives. No feature-specific UI.
-- \`hooks/\` \u2014 hooks used by more than one feature.
-- \`utils/\` \u2014 pure, framework-agnostic helpers.
-- \`lib/\` \u2014 configured third-party clients (axios, dayjs).
-- \`types/\` \u2014 types shared across features.
-- \`config/\` \u2014 env readers, constants, feature flags.
-- \`stores/\` \u2014 global stores.
-- \`providers/\` \u2014 root-level providers. \`providers/index.tsx\` wraps the tree \u2014 compose new providers there.
-
-Feature-scoped code lives under \`src/features/<feature>/\` with its own \`components/\`, \`hooks/\`, \`api/\`, \`stores/\`, \`types/\`, \`utils/\`.
-
-Rule of thumb: if only one feature uses it, it stays inside that feature. Promote to \`src/\` only when a second feature needs it.
+    docsReadmeTemplate = () => `# Docs \u2014 Knowledge Base
+
+Frontmatter-indexed task docs. \`INDEX.md\` is auto-generated \u2014 never hand-edit it.
+
+## Where to put new docs
+
+| Doc type | Directory |
+|---|---|
+| Feature spec / feature-scoped finding | \`docs/features/<feature>/\` |
+| Cross-cutting architecture / patterns | \`docs/architecture/\` |
+| Onboarding material | \`docs/onboarding/\` |
+
+## File naming
+
+| Case | Name |
+|---|---|
+| Main spec of a feature | \`<feature>.spec.en.md\` |
+| Spec translation alongside | \`<feature>.spec.vi.md\` |
+| Topic doc (English) | \`<topic>.en.md\` |
+| Translation alongside | \`<topic>.vi.md\` |
+
+## Workflow
+
+1. Copy \`docs/_template.md\`, fill ALL frontmatter fields (the index and lint are built from it).
+2. Save to the right directory per the table above.
+3. \`npm run docs:index\` \u2014 regenerates \`INDEX.md\`.
+4. \`npm run docs:lint\` \u2014 must pass before committing.
+5. Commit the doc and \`INDEX.md\` together.
 `;
-      return `# Copilot Instructions \u2014 ${cart.projectName}
+    docsIndexPlaceholderTemplate = () => `# Docs Index
+
+> Auto-generated by \`.claude/scripts/build-docs-index.mjs\` \u2014 do not edit by hand.
+> Run \`npm run docs:index\` to regenerate.
+`;
+    docsSharedMjsTemplate = (flowEnum3, layerEnum3) => `// Shared helpers for docs tooling \u2014 single source of truth for the frontmatter schema.
+import { readdirSync, readFileSync } from 'fs';
+import { join, relative } from 'path';
+
+export const DOCS_DIR = 'docs';
+export const SKIP_FILES = new Set(['INDEX.md', 'README.md', '_template.md']);
+
+export const ENUMS = {
+  flow: ${JSON.stringify(flowEnum3)},
+  layer: ${JSON.stringify(layerEnum3)},
+  status: ${JSON.stringify(STATUS_ENUM)},
+  lang: ${JSON.stringify(LANG_ENUM)},
+};
 
-These are the project-wide conventions GitHub Copilot must follow. Match the structure below exactly \u2014 do not invent new top-level folders.
+export const REQUIRED_FIELDS = ['title', 'feature', 'flow', 'layer', 'status', 'lang', 'keywords', 'updated'];
+
+// Minimal YAML frontmatter parser: scalar values and inline arrays ([a, b]).
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\\n([\\s\\S]*?)\\n---/);
+  if (!match) return null;
+  const meta = {};
+  for (const line of match[1].split('\\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).replace(/\\s+#.*$/, '').trim();
+    if (!key) continue;
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      meta[key] = inner === ''
+        ? []
+        : inner.split(',').map((item) => item.trim().replace(/^['"]|['"]$/g, ''));
+    } else {
+      meta[key] = value.replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return meta;
+}
 
-Path-specific rules live in \`.github/instructions/*.instructions.md\` \u2014 those files apply automatically to the files their \`applyTo\` glob matches.
+export function firstHeading(content) {
+  const match = content.match(/^#\\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}
 
-## Behavioral Guidelines
+// Walks docs/**/*.md (excluding SKIP_FILES) and returns parsed records.
+export function walkDocs(dir = DOCS_DIR, records = []) {
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, item.name);
+    if (item.isDirectory()) {
+      walkDocs(fullPath, records);
+    } else if (item.name.endsWith('.md') && !SKIP_FILES.has(item.name)) {
+      const content = readFileSync(fullPath, 'utf-8');
+      records.push({
+        path: relative(DOCS_DIR, fullPath),
+        fm: parseFrontmatter(content),
+        title: firstHeading(content),
+      });
+    }
+  }
+  return records;
+}
+`;
+    buildDocsIndexMjsTemplate = () => `// Regenerates docs/INDEX.md from frontmatter. Deterministic (sorted) so diffs stay clean.
+// Run via: npm run docs:index
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { walkDocs, DOCS_DIR } from './_docs-shared.mjs';
+
+const records = walkDocs().sort((a, b) => a.path.localeCompare(b.path));
+const withFm = records.filter((record) => record.fm !== null).length;
+const today = new Date().toISOString().slice(0, 10);
+
+function entryLine(record) {
+  const fm = record.fm ?? {};
+  const title = fm.title ?? record.title ?? record.path;
+  const tags = ['feature', 'flow', 'layer']
+    .map((key) => '\`' + key + ':' + (fm[key] ?? '_unknown') + '\`')
+    .join(' ');
+  const keywords = Array.isArray(fm.keywords) && fm.keywords.length > 0
+    ? ' \u2014 ' + fm.keywords.join(', ')
+    : '';
+  return '- [' + title + '](' + record.path + ') \u2014 ' + tags + keywords;
+}
+
+function section(heading, key) {
+  const groups = new Map();
+  for (const record of records) {
+    const groupKey = record.fm?.[key] ?? '_unknown';
+    if (!groups.has(groupKey)) groups.set(groupKey, []);
+    groups.get(groupKey).push(record);
+  }
+  const lines = ['## ' + heading, ''];
+  for (const [name, group] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push('### ' + name + ' (' + group.length + ')');
+    lines.push(...group.map(entryLine));
+    lines.push('');
+  }
+  return lines;
+}
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+function keywordIndex() {
+  const map = new Map();
+  for (const record of records) {
+    for (const keyword of record.fm?.keywords ?? []) {
+      if (!map.has(keyword)) map.set(keyword, []);
+      map.get(keyword).push(record.path);
+    }
+  }
+  if (map.size === 0) return [];
+  return [
+    '## Keyword Index',
+    ...[...map.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([keyword, paths]) =>
+        '- \`' + keyword + '\` \u2192 ' + paths.map((path) => '[' + path + '](' + path + ')').join(', ')
+      ),
+    '',
+  ];
+}
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+const lines = [
+  '# Docs Index',
+  '',
+  '> Auto-generated by \`.claude/scripts/build-docs-index.mjs\` \u2014 do not edit by hand.',
+  '> Generated: ' + today + ' from ' + records.length + ' files (' + withFm + ' with frontmatter, ' + (records.length - withFm) + ' without).',
+  '',
+];
 
-### 1. Think Before Coding
+if (records.length === 0) {
+  lines.push('_(No docs yet. Copy docs/_template.md to get started.)_', '');
+} else {
+  lines.push(...section('By Feature', 'feature'));
+  lines.push(...section('By Flow', 'flow'));
+  lines.push(...section('By Layer', 'layer'));
+  lines.push(...keywordIndex());
+}
+
+writeFileSync(join(DOCS_DIR, 'INDEX.md'), lines.join('\\n').replace(/\\n+$/, '\\n'));
+console.log('docs/INDEX.md updated \u2014 ' + records.length + ' doc(s), ' + withFm + ' with frontmatter.');
+`;
+    lintDocsFrontmatterMjsTemplate = () => `// Validates every doc against the frontmatter schema. Exits non-zero on violation \u2192 CI-ready.
+// Run via: npm run docs:lint
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { walkDocs, ENUMS, REQUIRED_FIELDS, DOCS_DIR } from './_docs-shared.mjs';
+
+const errors = [];
+
+for (const record of walkDocs()) {
+  const where = 'docs/' + record.path;
+  if (record.fm === null) {
+    errors.push(where + ': missing frontmatter block');
+    continue;
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (record.fm[field] === undefined || record.fm[field] === '') {
+      errors.push(where + ': missing required field "' + field + '"');
+    }
+  }
+  for (const [field, allowed] of Object.entries(ENUMS)) {
+    const value = record.fm[field];
+    if (value !== undefined && !allowed.includes(value)) {
+      errors.push(where + ': invalid ' + field + ' "' + value + '" (allowed: ' + allowed.join(', ') + ')');
+    }
+  }
+  if (record.fm.updated !== undefined && !/^\\d{4}-\\d{2}-\\d{2}$/.test(record.fm.updated)) {
+    errors.push(where + ': "updated" must be YYYY-MM-DD (got "' + record.fm.updated + '")');
+  }
+  if (Array.isArray(record.fm.keywords)) {
+    for (const keyword of record.fm.keywords) {
+      if (keyword !== keyword.toLowerCase()) {
+        errors.push(where + ': keyword "' + keyword + '" must be lowercase');
+      }
+    }
+  }
+  for (const related of record.fm.related ?? []) {
+    if (!existsSync(join(DOCS_DIR, related))) {
+      errors.push(where + ': related path "' + related + '" does not exist under docs/');
+    }
+  }
+}
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+if (errors.length > 0) {
+  console.error('docs:lint failed with ' + errors.length + ' error(s):');
+  for (const error of errors) console.error('  - ' + error);
+  process.exit(1);
+}
+console.log('docs:lint passed.');
+`;
+    docsFirstReminderShTemplate = (trigger) => `#!/usr/bin/env bash
+# UserPromptSubmit hook: inject a docs-first reminder when the prompt mentions
+# a documented feature/flow/domain topic. Silent otherwise to avoid noise.
+# The harness runs this on every user prompt, so the reminder cannot be skipped.
+payload="$(cat)"
+
+# Keep in sync with feature folders under docs/features/ + key domain nouns.
+# Add an alternation entry whenever a new feature doc is created.
+trigger='${trigger}'
+
+if echo "$payload" | grep -iqE "$trigger"; then
+  cat <<'EOF'
+[docs-first guard] This request appears to touch a documented feature/flow.
+BEFORE opening source code:
+  1. Read docs/INDEX.md (grouped by feature / flow / layer + keyword index).
+  2. Narrow with frontmatter grep, e.g.:
+       grep -rlE '^feature: <feature>' docs/ | xargs grep -lE '^flow: <flow>'
+  3. Read candidate doc bodies (<=5 files), then follow \`related:\` links.
+  4. Open source only if docs are insufficient \u2014 and state what the docs covered.
+EOF
+fi
+exit 0
+`;
+    claudeSettingsTemplate = () => JSON.stringify(
+      {
+        permissions: {
+          deny: [
+            "Bash(git push*)",
+            "Bash(git commit*)",
+            "Bash(git merge*)",
+            "Bash(git rebase*)",
+            "Bash(git tag*)",
+            "Bash(git branch -D*)",
+            "Bash(git branch -d*)",
+            "Bash(git reset --hard*)",
+            "Bash(git clean*)"
+          ],
+          allow: []
+        },
+        hooks: {
+          UserPromptSubmit: [
+            {
+              hooks: [
+                {
+                  type: "command",
+                  command: 'bash "$CLAUDE_PROJECT_DIR/.claude/scripts/docs-first-reminder.sh"'
+                }
+              ]
+            }
+          ]
+        },
+        sandbox: {
+          filesystem: { denyRead: ["**/.env", "**/.env.*"] }
+        }
+      },
+      null,
+      2
+    );
+    docsSkillTemplate = (projectName, slug, flowEnum3, layerEnum3) => `---
+name: ${slug}-docs
+description: How to find and write knowledge-base docs for ${projectName}. Use when asked "is there a doc about\u2026", "explain the X feature/flow", "document this", "write a spec", or the Vietnamese equivalents ("c\xF3 t\xE0i li\u1EC7u v\u1EC1\u2026", "gi\u1EA3i th\xEDch flow\u2026", "vi\u1EBFt docs/spec\u2026"). Also use before modifying any documented feature.
+---
 
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
+# ${projectName} Docs Guide
 
-### 2. Simplicity First
+## Finding docs (DOCS-FIRST)
 
-**Minimum code that solves the problem. Nothing speculative.**
+1. Start at \`docs/INDEX.md\` \u2014 grouped By Feature / By Flow / By Layer, plus a keyword reverse-index.
+2. Narrow with frontmatter grep (never semantic-search bodies):
+   \`\`\`bash
+   grep -rlE '^feature: home' docs/
+   grep -rlE '^feature: home' docs/ | xargs grep -lE '^flow: ui'
+   \`\`\`
+3. Read candidate doc bodies (\u22645 files), then follow their \`related:\` links.
+4. Only open source when docs are insufficient \u2014 and state what the docs already covered.
 
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
+## Writing docs
 
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+1. Copy \`docs/_template.md\`; every field is required (see \`docs/README.md\` for placement + naming).
+2. Frontmatter axes: \`feature\` (folder under docs/features/ or \`_app\`), \`flow\` (${flowEnum3.join("/")}), \`layer\` (${layerEnum3.join("/")}).
+3. Keywords: lowercase, prefer real symbol/file names an engineer would grep for.
+4. Rebuild + validate, then commit doc and INDEX.md together:
+   \`\`\`bash
+   npm run docs:index && npm run docs:lint
+   \`\`\`
+`;
+    docsWriterAgentTemplate = (projectName, slug) => `---
+name: docs-writer
+description: "Documentation agent for ${projectName} \u2014 analyzes requirements from any source (conversation, tickets, Slack) and maintains docs/. <example>user: 'Here are the requirements for the profile page, write them up' \u2192 docs-writer <commentary>synthesizing requirements into a feature spec</commentary></example> <example>user: 'We just finished the auth refactor, document what changed' \u2192 docs-writer <commentary>post-task knowledge capture</commentary></example> <example>user: 'Update the home spec \u2014 the hero section was redesigned' \u2192 docs-writer <commentary>doc maintenance</commentary></example>"
+model: haiku
+memory: project
+---
 
-### 3. Surgical Changes
+You are the documentation agent for ${projectName}. You own \`docs/\`.
 
-**Touch only what you must. Clean up only your own mess.**
+## Onboarding protocol
 
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
+1. Read \`.claude/agent-memory/docs-writer/MEMORY.md\`.
+2. Read \`docs/README.md\` (placement + naming rules) and \`docs/INDEX.md\` (what already exists).
+3. Load the \`${slug}-docs\` skill.
 
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
+## Workflow
 
-The test: Every changed line should trace directly to the user's request.
+1. Understand the requirement; if sources conflict, surface the conflict instead of guessing.
+2. Check INDEX.md for an existing doc to update before creating a new one.
+3. Copy \`docs/_template.md\`; fill ALL frontmatter fields (feature, flow, layer, status, lang, keywords, updated). Specs describe WHAT, not HOW.
+4. Save per docs/README.md rules: \`docs/features/<feature>/<feature>.spec.en.md\` for feature specs, \`<topic>.en.md\` for findings, \`docs/architecture/\` for cross-cutting topics.
+5. Run \`npm run docs:index\` then \`npm run docs:lint\` \u2014 both must succeed.
+6. If the feature introduces new domain nouns, add them to the \`trigger\` list in \`.claude/scripts/docs-first-reminder.sh\`.
+7. Report created/updated paths. Append lessons to \`.claude/agent-memory/docs-writer/MEMORY.md\`.
 
-### 4. Goal-Driven Execution
+## Hard rules
 
-**Define success criteria. Loop until verified.**
+- Never hand-edit \`docs/INDEX.md\`.
+- Never edit application code \u2014 you write markdown and run the docs scripts only.
+- Never commit or push.
+`;
+    agentMemorySeedTemplate = (agentName) => `# ${agentName} \u2014 Agent Memory
 
-Transform tasks into verifiable goals:
-- "Add validation" \u2192 "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" \u2192 "Write a test that reproduces it, then make it pass"
-- "Refactor X" \u2192 "Ensure tests pass before and after"
+Append durable, non-obvious gotchas and patterns discovered while working \u2014 one bullet each, newest first. Link related docs/ files. Read this file at the start of every session.
 
-For multi-step tasks, state a brief plan:
+_(no entries yet)_
+`;
+    buildClaudeFileMap = (params) => {
+      const { projectName, slug, flowEnum: flowEnum3, layerEnum: layerEnum3 } = params;
+      const files = [
+        { relativePath: "CLAUDE.md", content: params.claudeMd },
+        { relativePath: ".claude/settings.json", content: claudeSettingsTemplate() },
+        { relativePath: ".claude/scripts/_docs-shared.mjs", content: docsSharedMjsTemplate(flowEnum3, layerEnum3) },
+        { relativePath: ".claude/scripts/build-docs-index.mjs", content: buildDocsIndexMjsTemplate() },
+        { relativePath: ".claude/scripts/lint-docs-frontmatter.mjs", content: lintDocsFrontmatterMjsTemplate() },
+        { relativePath: ".claude/scripts/docs-first-reminder.sh", content: docsFirstReminderShTemplate(params.reminderTrigger) },
+        { relativePath: `.claude/skills/${slug}-conventions/SKILL.md`, content: params.conventionsSkill },
+        { relativePath: `.claude/skills/${slug}-docs/SKILL.md`, content: docsSkillTemplate(projectName, slug, flowEnum3, layerEnum3) },
+        { relativePath: ".claude/agents/dev.md", content: params.devAgent },
+        { relativePath: ".claude/agents/docs-writer.md", content: docsWriterAgentTemplate(projectName, slug) },
+        { relativePath: ".claude/agent-memory/dev/MEMORY.md", content: agentMemorySeedTemplate("dev") },
+        { relativePath: ".claude/agent-memory/docs-writer/MEMORY.md", content: agentMemorySeedTemplate("docs-writer") },
+        { relativePath: "docs/README.md", content: docsReadmeTemplate() },
+        { relativePath: "docs/INDEX.md", content: docsIndexPlaceholderTemplate() },
+        { relativePath: "docs/_template.md", content: docsTemplateMdTemplate(flowEnum3, layerEnum3) },
+        ...params.seedDocs
+      ];
+      if (params.testing) {
+        files.push(
+          { relativePath: ".claude/agents/test-writer.md", content: params.testing.testWriterAgent },
+          { relativePath: ".claude/agent-memory/test-writer/MEMORY.md", content: agentMemorySeedTemplate("test-writer") },
+          { relativePath: `.claude/skills/${slug}-test-author/SKILL.md`, content: params.testing.testAuthorSkill }
+        );
+      }
+      return files;
+    };
+  }
+});
 
+// src/scaffold/react-vite/templates/claude-setup.ts
+var projectSlug, fsdLayers, bprLayers, layerEnum, flowEnum, reminderTrigger, claudeMdTemplate, docsHomeSpecTemplate, conventionsSkillTemplate, testAuthorSkillTemplate, devAgentTemplate, testWriterAgentTemplate, getClaudeFileMap;
+var init_claude_setup2 = __esm({
+  "src/scaffold/react-vite/templates/claude-setup.ts"() {
+    "use strict";
+    init_claude_setup();
+    projectSlug = (cart) => cart.projectName.toLowerCase().replace(/_/g, "-");
+    fsdLayers = ["app", "pages", "widgets", "features", "entities", "shared"];
+    bprLayers = ["app", "pages", "components", "features", "hooks", "stores", "lib", "utils"];
+    layerEnum = (cart) => [...cart.layout === "FSD" ? fsdLayers : bprLayers, "_cross"];
+    flowEnum = (cart) => [
+      "ui",
+      "data",
+      ...cart.router === "TANSTACK_ROUTER" ? ["routing"] : [],
+      ...cart.stateManagement === "ZUSTAND" ? ["state"] : [],
+      "infra",
+      "architecture",
+      "onboarding",
+      "_meta"
+    ];
+    reminderTrigger = (cart) => `home|landing${cart.router === "TANSTACK_ROUTER" ? "|route|routing" : ""}${cart.stateManagement === "ZUSTAND" ? "|store|state" : ""}${cart.query === "TANSTACK_QUERY" ? "|query|fetch" : ""}`;
+    claudeMdTemplate = (cart) => {
+      const isFsd = cart.layout === "FSD";
+      const hasRouter = cart.router === "TANSTACK_ROUTER";
+      const hasZustand = cart.stateManagement === "ZUSTAND";
+      const hasQuery = cart.query === "TANSTACK_QUERY";
+      const hasVitest = cart.testing === "VITEST";
+      const hasPlaywright = cart.testing === "PLAYWRIGHT";
+      const hasTesting = cart.testing !== "NOT_USING";
+      const slug = projectSlug(cart);
+      const stack = [
+        "React 19, TypeScript 5.8, Vite 6",
+        hasRouter ? "TanStack Router v1.144.0 (file-based routes in src/routes/)" : null,
+        hasZustand ? "Zustand v5.0.5" : null,
+        hasQuery ? "TanStack Query v5.74.4" : null,
+        cart.css === "TAILWIND" ? "Tailwind CSS v4.1.3" : null,
+        cart.linter === "BIOME" ? "Biome v1.9.4" : cart.linter === "ESLINT" ? "ESLint v9" : null,
+        hasVitest ? "Vitest v3.2.4 + Testing Library" : null,
+        hasPlaywright ? "Playwright v1.52.0" : null
+      ].filter(Boolean);
+      const commands = [
+        "- `npm run dev` \u2014 start dev server (http://localhost:5173)",
+        "- `npm run build` \u2014 type-check + production build",
+        cart.linter !== "NOT_USING" ? "- `npm run lint` \u2014 lint code" : null,
+        hasVitest ? "- `npm run test:run` \u2014 run unit/component tests once (`npm test` for watch)" : null,
+        hasPlaywright ? "- `npm run test:e2e` \u2014 run Playwright E2E tests" : null,
+        "- `npm run docs:index` \u2014 regenerate docs/INDEX.md (run after any doc change)",
+        "- `npm run docs:lint` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)"
+      ].filter(Boolean);
+      const fsdArchitecture = `\`\`\`
+app        \u2192 app shell, providers, global setup
+pages      \u2192 route-level pages (one folder per page: ui/ + index.ts barrel)
+widgets    \u2192 composite UI blocks assembled from features/entities
+features   \u2192 user interactions with business value
+entities   \u2192 business domain objects (model, api, ui)
+shared     \u2192 reusable foundation: ui/, lib/, api/, config/
 \`\`\`
-1. [Step] \u2192 verify: [check]
-2. [Step] \u2192 verify: [check]
-3. [Step] \u2192 verify: [check]
+
+**Hard rules:**
+- Upper layers import lower layers only \u2014 NEVER the reverse (shared must not import pages).
+- Cross-imports inside one layer are forbidden (a feature must not import another feature).
+- Every page exposes its public API through \`index.ts\` \u2014 import \`@/pages/home\`, never \`@/pages/home/ui/HomePage\`.`;
+      const bprArchitecture = `\`\`\`
+pages      \u2192 route-level pages
+components \u2192 shared presentational components
+features   \u2192 feature folders (components + hooks + api per feature)
+hooks      \u2192 shared React hooks
+stores     \u2192 global state${hasZustand ? " (Zustand)" : ""}
+lib        \u2192 third-party wrappers / configured clients
+utils      \u2192 pure utility functions
 \`\`\`
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+**Hard rules:**
+- A feature may import from shared folders (components/, hooks/, lib/, utils/) \u2014 shared folders must NEVER import from features/ or pages/.
+- Cross-feature imports are forbidden; lift shared logic into hooks/ or lib/ instead.
+- Keep components presentational; data fetching and state live in hooks.`;
+      const keyPatterns = [];
+      if (hasZustand) {
+        keyPatterns.push(`**Zustand \u2014 select narrowly, never the whole store:**
+\`\`\`ts
+const count = useAppStore((state) => state.count); // \u2705 re-renders on count only
+const store = useAppStore();                       // \u274C re-renders on every change
+\`\`\``);
+      }
+      if (hasQuery) {
+        keyPatterns.push(`**TanStack Query \u2014 key factories, not inline keys:**
+\`\`\`ts
+const todoKeys = {
+  all: ['todos'] as const,
+  detail: (id: string) => [...todoKeys.all, id] as const,
+};
+useQuery({ queryKey: todoKeys.detail(id), queryFn: () => fetchTodo(id) });
+\`\`\``);
+      }
+      if (hasRouter) {
+        keyPatterns.push(`**TanStack Router \u2014 one file per route in src/routes/; never edit routeTree.gen.ts:**
+\`\`\`ts
+export const Route = createFileRoute('/about')({ component: AboutPage });
+\`\`\``);
+      }
+      if (keyPatterns.length === 0) {
+        keyPatterns.push("_(Add canonical code snippets here as the project establishes its patterns.)_");
+      }
+      const namingRows = isFsd ? `| Pattern | Example | Layer |
+|---|---|---|
+| PascalCase component, named export | \`HomePage.tsx\` \u2192 \`export const HomePage\` | pages/widgets/features ui |
+| \`use\` prefix, camelCase | \`useAuth.ts\` | hooks (in lib/ or feature) |
+| camelCase barrel | \`index.ts\` re-exporting public API | every slice |
+| kebab-case folders | \`src/features/add-todo/\` | all layers |` : `| Pattern | Example | Layer |
+|---|---|---|
+| PascalCase component, default export for pages | \`Home.tsx\` \u2192 \`export default Home\` | pages |
+| PascalCase component, named export | \`Button.tsx\` \u2192 \`export const Button\` | components |
+| \`use\` prefix, camelCase | \`useAuth.ts\` | hooks |${hasZustand ? "\n| camelCase store, `use*Store` | `appStore.ts` \u2192 `useAppStore` | stores |" : ""}`;
+      const testSection = hasTesting ? `## Centralized Test Pattern
+
+All test code lives in the top-level \`test/\` folder \u2014 never inside \`src/\`:
 
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+\`\`\`
+test/
+\u251C\u2500\u2500 README.md          # conventions + how to run
+${hasVitest ? "\u251C\u2500\u2500 unit/              # mirrors src/ layer structure; *.test.tsx\n" : ""}${hasPlaywright ? "\u251C\u2500\u2500 e2e/               # mirrors business flows; *.spec.ts\n" : ""}\u251C\u2500\u2500 _shared/           # fixtures/, helpers/, mocks/${hasPlaywright ? ", pages/ (Page Objects)" : ""}
+\u2514\u2500\u2500 specs/             # paired human-readable *.spec.md contracts \u2014 documentation, never executed
+\`\`\`
 
-## Stack
-${stackLines}
+Every test file has a paired \`test/specs/.../<name>.spec.md\` describing WHAT it covers. See \`test/README.md\`.
 
-## Import aliases
+` : "";
+      const testWriterRow = hasTesting ? "\n| Writing or updating tests | `test-writer` | writes only under `test/`; requires a feature spec first |" : "";
+      return `# ${cart.projectName}
 
-Always use path aliases instead of relative imports. Project-wide aliases are pre-configured in \`tsconfig.json\` and \`vite.config.ts\`:
+## Behavioral Guidelines
 
-- \`@/*\` \u2192 \`./src/\` \u2014 use for any import from src, e.g. \`import Button from '@/components/Button'\`.
-- \`@components/*\` \u2192 \`./src/components/\` \u2014 e.g. \`import { Modal } from '@components/Modal'\`.
-- \`@pages/*\` \u2192 \`./src/pages/\` \u2014 e.g. \`import { HomePage } from '@pages/Home'\`.
-- \`@utils/*\` \u2192 \`./src/utils/\` \u2014 e.g. \`import { cn } from '@utils/cn'\`.
-- \`@types/*\` \u2192 \`./src/types/\` \u2014 e.g. \`import type { User } from '@types/user'\`.
-- \`@hooks/*\` \u2192 \`./src/hooks/\` \u2014 e.g. \`import { useAuth } from '@hooks/useAuth'\`.
-- \`@layouts/*\` \u2192 \`./src/layouts/\` \u2014 e.g. \`import { MainLayout } from '@layouts/MainLayout'\`.
-- \`@assets/*\` \u2192 \`./src/assets/\` \u2014 e.g. \`import logo from '@assets/logo.svg'\`.
+**Think Before Coding** \u2014 state assumptions explicitly; if multiple interpretations exist, present them; if something is unclear, stop and ask.
+**Simplicity First** \u2014 minimum code that solves the problem; no speculative features, abstractions, or configurability.
+**Surgical Changes** \u2014 touch only what the request requires; match existing style; every changed line traces to the request.
+**Goal-Driven Execution** \u2014 turn tasks into verifiable success criteria before starting; loop until verified.
 
-**Never use relative imports** like \`import Foo from '../../../components/Foo'\`. Always resolve through an alias.
+## Project Overview
 
-## Naming conventions
+${stack.map((s) => `- ${s}`).join("\n")}
 
-- **Components**: \`PascalCase.tsx\`, one component per file, named export (no default).
-- **Hooks**: \`useXxx.ts\`, camelCase, named export, must start with \`use\`.
-- **Stores** (Zustand): camelCase ending in \`Store.ts\` (e.g. \`authStore.ts\`). Export a typed hook, never the raw store.
-- **Types / interfaces**: PascalCase, in \`*.types.ts\` or inline when used in one file only.
-- **Constants**: \`UPPER_SNAKE_CASE\`, grouped in \`constants.ts\` per slice/feature.
-- **Utility functions**: camelCase, one concern per file, named exports.
+Architecture: **${isFsd ? "Feature Slice Design (FSD)" : "Bulletproof React (BPR)"}**. Reference implementation: \`src/pages/home${isFsd ? "/" : ".tsx"}\` \u2014 consult it before generating new pages. Verify actual directory names with \`ls\` before writing paths.
 
-${layoutBlock}
-## When unsure
+## Commands
 
-Open the closest existing file of the same kind and match its location, casing, and export style.
-`;
-    };
-    componentsTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      const placement = cart.layout === "FSD" ? `- Reusable primitives (Button, Input, Modal) \u2192 \`src/shared/ui/<Name>/<Name>.tsx\`.
-- Slice-specific components \u2192 \`src/<layer>/<slice>/ui/<Name>.tsx\`.
-- Never put a component directly under \`src/pages/<name>/\` \u2014 use \`src/pages/<name>/ui/\`.` : `- App-wide reusable UI \u2192 \`src/components/<Name>/<Name>.tsx\`.
-- Feature-specific UI \u2192 \`src/features/<feature>/components/<Name>.tsx\`.
-- Do **not** put feature-specific components under \`src/components\`.`;
-      return frontmatter(paths.components) + `# React components
-
-- File name matches the component name exactly: \`UserCard.tsx\` exports \`UserCard\`.
-- One component per file. Named export only \u2014 never \`export default\`.
-- Functional components with TypeScript props interface named \`<Name>Props\`, defined in the same file unless reused.
-- Keep JSX return focused. Extract sub-trees into smaller components when the return exceeds ~60 lines.
-- Hooks run at the top of the component body, before any conditional return.
-- No business logic in components \u2014 delegate to hooks, stores, or query functions.
-- Co-locate component-scoped styles, stories, and tests next to the component file.
-
-## Where to place a new component
-
-${placement}
-`;
-    };
-    hooksTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      const placement = cart.layout === "FSD" ? `- Slice-specific hook \u2192 \`src/<layer>/<slice>/model/useXxx.ts\` (stateful) or \`src/<layer>/<slice>/lib/useXxx.ts\` (pure helper).
-- Reusable across slices \u2192 \`src/shared/lib/useXxx.ts\`.` : `- Cross-feature hook \u2192 \`src/hooks/useXxx.ts\`.
-- Feature-specific hook \u2192 \`src/features/<feature>/hooks/useXxx.ts\`.`;
-      return frontmatter(paths.hooks) + `# Custom hooks
+${commands.join("\n")}
 
-- File name starts with \`use\` and matches the exported hook: \`useDebouncedValue.ts\` exports \`useDebouncedValue\`.
-- One hook per file. Named export only.
-- Must call other hooks \u2014 if a function does not use any hook, it is a utility, not a hook.
-- Return either a tuple \`[value, setter]\` or an object with named fields. Do not mix patterns within one hook.
-- Keep hooks focused on one concern. Compose multiple hooks rather than building a single large one.
-- Do not call hooks conditionally. Do not rename destructured return values unless renaming makes usage clearer.
+## Architecture Layers
 
-## Where to place a new hook
+${isFsd ? fsdArchitecture : bprArchitecture}
 
-${placement}
-`;
-    };
-    routerTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      return frontmatter(paths.routes) + `# TanStack Router (file-based)
-
-- Every file in \`src/routes/\` is a route. Do not create unrelated helper files here.
-- Root layout lives in \`src/routes/__root.tsx\` \u2014 wrap \`<Outlet />\` with app-wide chrome (header, devtools, providers that need router context).
-- Leaf routes use \`createFileRoute('/path')\` and export \`Route\`. File name matches the URL segment.
-- Dynamic segments use \`$param\` file names: \`src/routes/posts/$postId.tsx\`.
-- Co-locate the route's \`loader\`, \`beforeLoad\`, and \`component\` in the same file. Push heavy logic into hooks / query functions imported from the feature folder.
-- **Never edit \`src/routes/routeTree.gen.ts\`** \u2014 it is regenerated on dev/build.
-- Internal navigation uses \`<Link to="..." />\` from \`@tanstack/react-router\`. Do not use \`<a href>\` for in-app links.
-- Type-safe search params: declare them in the route's \`validateSearch\` and read via \`Route.useSearch()\`.
-`;
-    };
-    zustandTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      const initialPath = cart.layout === "FSD" ? "src/shared/lib/store.ts" : "src/stores/appStore.ts";
-      const newStorePath = cart.layout === "FSD" ? "- New global store \u2192 `src/shared/lib/<name>Store.ts`.\n- Entity-owned store \u2192 `src/entities/<name>/model/store.ts`." : "- New global store \u2192 `src/stores/<name>Store.ts`.\n- Feature-scoped store \u2192 `src/features/<feature>/stores/<name>Store.ts`.";
-      return frontmatter(paths.stores) + `# Zustand stores
+## Key Patterns
 
-- Initial store lives at \`${initialPath}\`.
-- One slice per concern \u2014 never pile unrelated state into a single store.
-- Export a **typed hook** (e.g. \`useAuthStore\`). Never export the raw store object or the \`create\` result directly.
-- Use selectors at call sites to read only what you need: \`const user = useAuthStore(s => s.user)\`. This avoids re-rendering on unrelated state changes.
-- Derived values belong in selectors, not inside the store.
-- Async actions go inside the store definition. They read/write state via \`set\` / \`get\`.
-- Shape a store as \`{ ...state, ...actions }\`. Actions are methods, not separate exports.
-- For cross-slice reads, use individual selectors \u2014 do not merge stores.
+${keyPatterns.join("\n\n")}
 
-## Where to place a new store
+## Naming Conventions
 
-${newStorePath}
-`;
-    };
-    queryTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      const keysPath = cart.layout === "FSD" ? `- Query keys, query functions, and hooks live in \`src/<layer>/<slice>/api/\`:
-  - \`keys.ts\` \u2014 exported query key factories
-  - \`queries.ts\` \u2014 \`useXxxQuery\` / \`useXxxMutation\` hooks wrapping \`useQuery\` / \`useMutation\`` : `- Query keys, query functions, and hooks live in \`src/features/<feature>/api/\`:
-  - \`keys.ts\` \u2014 exported query key factories
-  - \`queries.ts\` \u2014 \`useXxxQuery\` / \`useXxxMutation\` hooks wrapping \`useQuery\` / \`useMutation\``;
-      return frontmatter(paths.apis) + `# TanStack Query
+${namingRows}
 
-- A single \`QueryClient\` is already instantiated in the root provider. Do **not** create additional clients.
-- Do not call \`useQuery\` / \`useMutation\` directly in leaf components unless the component is a page-level container. Wrap them in a hook inside the feature/slice.
+## Anti-Patterns
 
-## Query keys
+| Anti-pattern | Correct approach |
+|---|---|
+${isFsd ? "| Importing a slice's internals (`@/pages/home/ui/HomePage`) | Import the barrel: `@/pages/home` |\n| Business logic in `shared/` | `shared/` is generic-only; domain logic goes in `entities/` or `features/` |" : "| Cross-feature imports (`features/a` \u2192 `features/b`) | Lift shared code into `hooks/` or `lib/` |\n| Fetching data inside presentational components | Move fetching into a hook; pass data via props |"}
+| \`useEffect\` for derived state | Compute during render or use \`useMemo\` |
+| Hand-editing generated files${hasRouter ? " (`routeTree.gen.ts`)" : ""} | Regenerate via the owning tool |
 
-- Use a **query key factory** per feature/slice \u2014 do not scatter string literals.
-- Factory shape: \`export const postKeys = { all: ['posts'] as const, list: (f) => [...postKeys.all, 'list', f] as const, detail: (id) => [...postKeys.all, 'detail', id] as const };\`
-- Invalidate via the factory: \`queryClient.invalidateQueries({ queryKey: postKeys.all })\`.
+> Fill this table from real review feedback over time \u2014 it is the highest-leverage section for code quality.
 
-## Query functions
+${testSection}## Agent Routing
 
-- Query functions return parsed, typed data \u2014 no raw \`Response\`. Throw on non-2xx.
-- Mutations invalidate relevant keys in \`onSuccess\`; never manually refetch by calling queries.
-- Prefer \`select\` for view-model transforms so the cached data stays normalized.
+| Task / trigger | Agent | Notes |
+|---|---|---|
+| Feature work or bug fix in \`src/\` | \`dev\` | MUST read relevant \`docs/features/\` spec before coding |
+| Analyzing requirements, writing/updating feature docs | \`docs-writer\` | owns \`docs/\`; rebuilds INDEX.md after every change |${testWriterRow}
 
-## Where to place queries
+Each agent has persistent memory at \`.claude/agent-memory/<agent>/MEMORY.md\` \u2014 agents read it on start and append new gotchas. Do NOT use the general assistant for work an agent owns \u2014 always delegate.
 
-${keysPath}
-`;
-    };
-    tailwindTemplate = (cart) => {
-      const paths = cart.layout === "FSD" ? FSD_PATHS : BPR_PATHS;
-      return frontmatter(paths.components) + `# Tailwind CSS v4
+## Task Documentation Convention
 
-> **This project uses Tailwind CSS v4.** v4 removes \`tailwind.config.js\` entirely.
-> All theme customization is done inside \`src/index.css\` using the \`@theme\` directive.
-> Do NOT create or reference \`tailwind.config.js\`, \`tailwind.config.ts\`, or \`postcss.config.*\`.
+After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`npm run docs:index\` and commit the doc together with \`INDEX.md\`. Validate with \`npm run docs:lint\`.
 
-## Entry point
+## Further Reading + DOCS-FIRST RULE
 
-\`src/index.css\` is the single Tailwind entry point \u2014 the only file that contains \`@import "tailwindcss"\`.
-Import it once in \`src/main.tsx\`. Do not add additional Tailwind imports elsewhere.
+Skills: \`.claude/skills/${slug}-conventions\` (architecture depth), \`.claude/skills/${slug}-docs\` (how to query the knowledge base)${hasTesting ? `, \`.claude/skills/${slug}-test-author\` (test conventions)` : ""}.
 
-## Using utilities
+**DOCS-FIRST RULE:** for any request to describe, explain, or modify a documented feature, you MUST grep \`docs/\` frontmatter and read the relevant docs BEFORE opening source files \u2014 and state what the docs already covered. Start at \`docs/INDEX.md\`.
 
-- Use Tailwind utility classes directly in JSX \`className\`. Do not write custom CSS for layout or spacing that a utility already covers.
-- Prefer composing utilities over \`@apply\`. Only use \`@apply\` inside \`@layer components\` or \`@layer base\` in \`src/index.css\`, never in component files.
-- Do not use inline \`style={{}}\` for values that a Tailwind utility can express.
-- Responsive variants go smallest \u2192 largest: \`sm:\`, \`md:\`, \`lg:\`, \`xl:\`, \`2xl:\`.
-- Dark mode: use the \`dark:\` variant. Do not add a separate CSS file or a manual class toggle.
+**Operating loop:** finish a non-trivial task \u2192 write a doc from \`docs/_template.md\` \u2192 rebuild \`INDEX.md\` \u2192 commit together; agents update their \`MEMORY.md\` when they learn a gotcha.
+`;
+    };
+    docsHomeSpecTemplate = (cart) => {
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      return `---
+title: Home Page \u2014 Feature Spec
+feature: home
+flow: ui
+layer: pages
+status: draft
+lang: en
+related: []
+keywords: [home, landing]
+updated: ${today}
+---
 
-## Theme customization \u2014 colors, spacing, and CSS variables
+# Home Page \u2014 Feature Spec
 
-All design tokens live in \`src/index.css\` under the \`@theme\` block, **not** in a config file.
+## Context
+Starter page generated by the scaffold. Replace this spec with the real requirements for ${cart.projectName}'s home page.
 
-### Adding custom colors
+## Root Cause / Key Finding
+_(For feature specs, use this section for key constraints or discoveries.)_
 
-\`\`\`css
-@import "tailwindcss";
+## Solution / Pattern
+- Requirements: [list what the page must do]
+- UI/UX: [screens and interactions]
+- Data: [data structures, API requirements]
+- Edge cases: [what must not break]
 
-@theme {
-  --color-brand: oklch(0.55 0.22 265);
-  --color-brand-light: oklch(0.72 0.14 265);
-  --color-brand-dark: oklch(0.38 0.22 265);
-}
-\`\`\`
+## Key Decisions
+_(Trade-offs made and alternatives rejected.)_
 
-This generates \`bg-brand\`, \`text-brand\`, \`border-brand\`, \`fill-brand\`, etc. automatically.
+## Related Files
+- src/pages/${cart.layout === "FSD" ? "home/ui/HomePage.tsx" : "Home.tsx"}
+`;
+    };
+    conventionsSkillTemplate = (cart) => {
+      const isFsd = cart.layout === "FSD";
+      const slug = projectSlug(cart);
+      return `---
+name: ${slug}-conventions
+description: Coding conventions and architecture rules for ${cart.projectName}. Use when writing or reviewing ANY code under src/ \u2014 components, pages, hooks${cart.stateManagement === "ZUSTAND" ? ", stores" : ""}${cart.router === "TANSTACK_ROUTER" ? ", routes" : ""}, or styling. Triggers on tasks mentioning components, pages, layout, naming, imports, or project structure.
+---
 
-### Namespace \u2192 utility mapping (do not invent names outside these namespaces)
+# ${cart.projectName} Conventions
 
-| CSS variable | Generated utilities |
-|---|---|
-| \`--color-*\` | \`bg-*\`, \`text-*\`, \`border-*\`, \`fill-*\`, \`stroke-*\` |
-| \`--font-*\` | \`font-*\` (font family) |
-| \`--text-*\` | \`text-*\` (font size) |
-| \`--font-weight-*\` | \`font-*\` (weight) |
-| \`--spacing-*\` | \`p-*\`, \`m-*\`, \`w-*\`, \`h-*\`, \`gap-*\`, etc. |
-| \`--radius-*\` | \`rounded-*\` |
-| \`--shadow-*\` | \`shadow-*\` |
-| \`--breakpoint-*\` | responsive variants (\`sm:\`, \`md:\`, \u2026) |
-| \`--animate-*\` | \`animate-*\` |
-
-### Extending vs. replacing defaults
-
-**Extend** (keep defaults, add yours):
-\`\`\`css
-@theme {
-  --color-tahiti: #3ab7bf;   /* new color, defaults kept */
-}
-\`\`\`
+In-depth companion to CLAUDE.md. CLAUDE.md states the rules; this skill explains how to apply them.
 
-**Replace an entire namespace** (remove all defaults in that group):
-\`\`\`css
-@theme {
-  --color-*: initial;        /* wipe default palette */
-  --color-white: #fff;
-  --color-primary: oklch(0.55 0.22 265);
-}
-\`\`\`
+## Layer boundaries (${isFsd ? "FSD" : "BPR"})
 
-**Replace everything** (no defaults at all):
-\`\`\`css
-@theme {
-  --*: initial;
-  --spacing: 4px;
-  --color-primary: oklch(0.55 0.22 265);
-}
-\`\`\`
+${isFsd ? `Import direction is one-way: \`app \u2192 pages \u2192 widgets \u2192 features \u2192 entities \u2192 shared\`.
+- Adding a page: create \`src/pages/<name>/ui/<Name>Page.tsx\` + \`src/pages/<name>/index.ts\` barrel.
+- Adding a feature: \`src/features/<name>/\` with its own ui/, model/, api/ as needed.
+- Anything used by 2+ slices and free of domain logic belongs in \`shared/\`.
+- NEVER deep-import another slice's internals; only its \`index.ts\` barrel.` : `- Adding a page: \`src/pages/<Name>.tsx\`, default export.
+- Adding a feature: \`src/features/<name>/\` holding that feature's components, hooks, and api together.
+- Shared folders (components/, hooks/, lib/, utils/) must stay feature-agnostic \u2014 no imports from features/ or pages/.
+- Cross-feature reuse: lift into hooks/ or lib/, never import feature \u2192 feature.`}
 
-### Variables that reference other variables
+## Import alias
 
-Use \`@theme inline\` when a token references another CSS variable:
-\`\`\`css
-@theme inline {
-  --font-sans: var(--font-inter);   /* resolves the value, not the reference */
-}
-\`\`\`
+Use \`@/\` for everything under src/ (e.g. \`import { HomePage } from '@/pages/home'\`). Never use long relative chains (\`../../..\`).
 
-### Regular CSS variables vs. theme tokens
+${cart.stateManagement === "ZUSTAND" ? `## Zustand
 
-- \`@theme { --color-brand: \u2026 }\` \u2192 creates utility classes (\`bg-brand\`, etc.)
-- \`:root { --brand-opacity: 0.9; }\` \u2192 plain CSS variable, no utility generated
+- One store per domain; name \`use<Domain>Store\`.
+- Components select narrow slices: \`useAppStore((s) => s.count)\`.
+- Async actions live inside the store, setting loading/error state themselves.
 
-Use \`:root\` for runtime values (e.g., animation targets, JS-readable tokens) that must **not** produce utility classes.
+` : ""}${cart.query === "TANSTACK_QUERY" ? `## TanStack Query
 
-### Defining custom animations
+- Define a key factory per entity next to its query functions.
+- Mutations invalidate via the same factory: \`queryClient.invalidateQueries({ queryKey: todoKeys.all })\`.
+- Server state belongs in Query \u2014 do not mirror it into ${cart.stateManagement === "ZUSTAND" ? "Zustand" : "local state"}.
 
-\`\`\`css
-@theme {
-  --animate-slide-in: slide-in 0.3s ease-out;
+` : ""}${cart.router === "TANSTACK_ROUTER" ? `## TanStack Router
 
-  @keyframes slide-in {
-    from { transform: translateY(-8px); opacity: 0; }
-    to   { transform: translateY(0);    opacity: 1; }
-  }
-}
-\`\`\`
+- One file per route under \`src/routes/\`; the Vite plugin regenerates \`routeTree.gen.ts\` \u2014 never edit it.
+- Route files export \`Route = createFileRoute('<path>')({ component })\`; keep components in their layer and import them.
 
-### Color format \u2014 prefer oklch
+` : ""}${cart.css === "TAILWIND" ? `## Tailwind CSS v4
 
-Tailwind v4's built-in palette uses oklch. Use oklch for custom colors too so tokens stay perceptually uniform and mix cleanly with the defaults:
+- Theme tokens live in \`src/index.css\` under \`@theme\` \u2014 extend there, not in a JS config.
+- Prefer semantic class composition in components over @apply.
 
-\`\`\`css
-@theme {
-  --color-primary: oklch(0.55 0.22 265);   /* L  C  H */
-  --color-muted:   oklch(0.62 0.01 265);
-}
-\`\`\`
+` : ""}## When unsure
 
-Avoid hex or \`rgb()\` unless matching a fixed brand value.
+Check the reference implementation (\`src/pages/home${isFsd ? "/" : ".tsx"}\`) first, then the docs (\`docs/INDEX.md\`), then ask.
+`;
+    };
+    testAuthorSkillTemplate = (cart) => {
+      const slug = projectSlug(cart);
+      const hasVitest = cart.testing === "VITEST";
+      return `---
+name: ${slug}-test-author
+description: Centralized test conventions for ${cart.projectName}. Use when asked to "write a test", "add a spec", "cover this with tests", or fix a failing test. All test code lives under test/ \u2014 never inside src/.
+---
 
-### Theme variables are also CSS custom properties
+# ${cart.projectName} Test Conventions
 
-Every \`@theme\` variable is a real CSS custom property \u2014 read it anywhere:
+## Layout
 
-\`\`\`css
-.my-element {
-  color: var(--color-primary);   /* same value as the text-primary utility */
-}
+\`\`\`
+test/
+${hasVitest ? "\u251C\u2500\u2500 unit/              # mirrors src/ layers; <name>.test.tsx\n" : "\u251C\u2500\u2500 e2e/               # mirrors business flows; <flow>.spec.ts\n"}\u251C\u2500\u2500 _shared/           # fixtures/, helpers/, mocks/${hasVitest ? "" : ", pages/ (Page Object Models)"}
+\u2514\u2500\u2500 specs/             # paired *.spec.md contracts \u2014 documentation, never executed
 \`\`\`
 
-Use \`var()\` for CSS that Tailwind utilities cannot express (e.g. complex \`box-shadow\`, SVG \`fill\`, pseudo-element content).
+## Rules
 
-### Semantic token pattern \u2014 naming convention
+- Tests go under \`test/\` ONLY \u2014 never create __tests__ folders or *.test.* files inside src/.
+- Every test file gets a paired contract: \`test/specs/<same-path>/<name>.spec.md\` listing what each case covers and which feature spec (docs/features/) it traces to.
+${hasVitest ? `- Unit tests import via the \`@/\` alias and explicit vitest imports (\`import { describe, it, expect } from 'vitest'\`).
+- Component tests use Testing Library; query by role/label, never by class name.
+- Run: \`npm run test:run\` (CI) / \`npm test\` (watch).` : `- E2E tests use Page Object Models from \`test/_shared/pages/\`; specs stay thin.
+- Run: \`npm run test:e2e\` (starts the dev server automatically).`}
+- Test behavior, not implementation; cover the edge cases listed in the feature spec.
+`;
+    };
+    devAgentTemplate = (cart) => {
+      const slug = projectSlug(cart);
+      const hasTesting = cart.testing !== "NOT_USING";
+      const testWriterExample = hasTesting ? " <example>user: 'Cover the login form with tests' \u2192 test-writer, NOT dev <commentary>test authoring belongs to test-writer</commentary></example>" : "";
+      const delegationRule = hasTesting ? "- Never write tests (delegate to test-writer) or docs (delegate to docs-writer); flag when they are needed." : "- Never write docs (delegate to docs-writer); flag when they are needed.";
+      return `---
+name: dev
+description: "Implementation agent for ${cart.projectName} \u2014 all feature work and bug fixes under src/. <example>user: 'Add a dark-mode toggle to the header' \u2192 dev <commentary>feature work in src/; dev reads the feature spec first, then implements</commentary></example> <example>user: 'The home page crashes on empty data \u2014 fix it' \u2192 dev <commentary>bug fix inside a documented feature</commentary></example> <example>user: 'Write a spec for the checkout flow' \u2192 docs-writer, NOT dev <commentary>doc authoring belongs to docs-writer</commentary></example>${testWriterExample}"
+model: sonnet
+memory: project
+---
 
-Prefer **semantic names** (\`surface\`, \`text-muted\`, \`border\`) over raw scale names (\`slate-900\`, \`zinc-300\`). Semantic names decouple the design from the specific value and make theming easy:
+You are the implementation agent for ${cart.projectName}.
 
-\`\`\`css
-@theme {
-  /* Brand */
-  --color-primary:       oklch(0.55 0.22 265);
-  --color-primary-fg:    oklch(0.97 0.01 265);
+## Onboarding protocol (in order, before any code)
 
-  /* Surfaces (dark-first) */
-  --color-surface:       oklch(0.11 0.015 265);
-  --color-surface-muted: oklch(0.16 0.012 265);
-  --color-surface-high:  oklch(0.21 0.010 265);
+1. Read \`.claude/agent-memory/dev/MEMORY.md\` \u2014 your accumulated gotchas.
+2. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec for the task.
+3. Load the \`${slug}-conventions\` skill for layer rules and patterns.
+4. Read the code under change.
 
-  /* Text */
-  --color-text:          oklch(0.97 0.000 0);
-  --color-text-muted:    oklch(0.62 0.010 265);
-  --color-text-subtle:   oklch(0.42 0.010 265);
+If no relevant feature spec exists, STOP and tell the user to run the docs-writer agent first.
 
-  /* Border */
-  --color-border:        oklch(0.28 0.010 265);
-}
-\`\`\`
+## Workflow
+
+1. State assumptions and success criteria.
+2. Implement the minimum change that satisfies the spec; match existing style.
+3. Verify (build${hasTesting ? " + run the relevant tests" : ""}); report results faithfully.
+4. Append newly discovered gotchas/patterns to \`.claude/agent-memory/dev/MEMORY.md\`.
 
-This generates: \`bg-primary\`, \`text-primary-fg\`, \`bg-surface\`, \`bg-surface-high/60\`, \`text-text\`, \`text-text-muted\`, \`border-border\`, etc. The \`/opacity\` modifier works on all generated utilities.
+## Hard rules
+
+- Never commit or push \u2014 a human does that.
+${delegationRule}
+- Never edit generated files${cart.router === "TANSTACK_ROUTER" ? " (`src/routes/routeTree.gen.ts`)" : ""} or \`docs/INDEX.md\` by hand.
 `;
     };
-    importsTemplate = () => {
-      return frontmatter("**") + `# Import aliases and code organization
+    testWriterAgentTemplate = (cart) => {
+      const slug = projectSlug(cart);
+      return `---
+name: test-writer
+description: "Test authoring agent for ${cart.projectName} \u2014 writes tests and their paired spec.md contracts, only under test/. Runs after docs-writer has produced the feature spec. <example>user: 'Cover the home page with tests' \u2192 test-writer <commentary>test authoring from an existing feature spec</commentary></example> <example>user: 'Add edge-case tests for the date validator' \u2192 test-writer <commentary>narrow test scope, reads the spec for edge cases</commentary></example> <example>user: 'Fix the validation bug the test caught' \u2192 dev, NOT test-writer <commentary>app-code changes belong to dev</commentary></example>"
+model: haiku
+memory: project
+---
 
-All imports use path aliases defined in \`tsconfig.json\` and \`vite.config.ts\`. This avoids fragile relative paths and makes moving files safe.
+You are the test-writing agent for ${cart.projectName}. You write ONLY under \`test/\`.
 
-## Available aliases
+## Onboarding protocol
 
-- \`@/*\` \u2192 \`./src/\` \u2014 shortest form, use when unambiguous
-- \`@components/*\` \u2014 components in \`./src/components/\`
-- \`@pages/*\` \u2014 pages in \`./src/pages/\`
-- \`@utils/*\` \u2014 utilities in \`./src/utils/\`
-- \`@types/*\` \u2014 types in \`./src/types/\`
-- \`@hooks/*\` \u2014 hooks in \`./src/hooks/\`
-- \`@layouts/*\` \u2014 layouts in \`./src/layouts/\`
-- \`@assets/*\` \u2014 assets in \`./src/assets/\`
+1. Read \`.claude/agent-memory/test-writer/MEMORY.md\`.
+2. Read the feature spec: \`docs/features/<feature>/<feature>.spec.en.md\` \u2014 requirements and edge cases drive the test plan. If it does not exist, STOP and request docs-writer first.
+3. Load the \`${slug}-test-author\` skill and \`test/README.md\`.
 
-## Rules
+## Workflow
 
-- **Never use relative imports** (\`../../../\`). Always use an alias.
-- **Group imports**: standard library, third-party, then project aliases.
-- **Organize by type within a file**: imports, types, constants, then code.
+1. Derive the test plan from the spec's requirements and edge cases.
+2. Write tests under ${cart.testing === "VITEST" ? "`test/unit/` (mirroring src/ layers)" : "`test/e2e/` (mirroring business flows, using Page Objects from `test/_shared/pages/`)"}.
+3. Write the paired contract at \`test/specs/<same-path>/<name>.spec.md\`: what each case covers, which feature spec it traces to.
+4. Run ${cart.testing === "VITEST" ? "`npm run test:run`" : "`npm run test:e2e`"} and report results faithfully \u2014 including failures.
+5. Append lessons to \`.claude/agent-memory/test-writer/MEMORY.md\`.
 
-### Examples
+## Hard rules
 
-\u2705 Good:
-\`\`\`typescript
-import { ReactNode } from 'react';
-import { QueryClient } from '@tanstack/react-query';
+- Never create test files inside \`src/\` \u2014 \`test/\` only.
+- Never edit application code, configs, or docs/ \u2014 if a test exposes a bug, report it for the dev agent.
+- Never weaken a test to make it pass.
+- Never commit or push.
+`;
+    };
+    getClaudeFileMap = (cart) => {
+      const hasTesting = cart.testing !== "NOT_USING";
+      return buildClaudeFileMap({
+        projectName: cart.projectName,
+        slug: projectSlug(cart),
+        flowEnum: flowEnum(cart),
+        layerEnum: layerEnum(cart),
+        reminderTrigger: reminderTrigger(cart),
+        claudeMd: claudeMdTemplate(cart),
+        conventionsSkill: conventionsSkillTemplate(cart),
+        devAgent: devAgentTemplate(cart),
+        seedDocs: [{ relativePath: "docs/features/home/home.spec.en.md", content: docsHomeSpecTemplate(cart) }],
+        testing: hasTesting ? {
+          testWriterAgent: testWriterAgentTemplate(cart),
+          testAuthorSkill: testAuthorSkillTemplate(cart)
+        } : void 0
+      });
+    };
+  }
+});
 
-import { Button } from '@components/Button';
-import { useUser } from '@hooks/useUser';
-import type { User } from '@types/user';
-import { cn } from '@utils/cn';
-\`\`\`
+// src/scaffold/react-vite/templates/testing-setup.ts
+var vitestConfigTemplate, vitestSetupTemplate, testTsconfigTemplate, unitHomeTestTemplate, unitHomeSpecMdTemplate, playwrightConfigTemplate, e2eHomePageObjectTemplate, e2eHomeSpecTemplate, e2eHomeSpecMdTemplate, testReadmeTemplate, getTestingFileMap;
+var init_testing_setup = __esm({
+  "src/scaffold/react-vite/templates/testing-setup.ts"() {
+    "use strict";
+    vitestConfigTemplate = () => `import { defineConfig, mergeConfig } from 'vitest/config';
+import viteConfig from './vite.config';
+
+export default mergeConfig(viteConfig, defineConfig({
+  test: {
+    environment: 'jsdom',
+    include: ['test/unit/**/*.test.{ts,tsx}'],
+    setupFiles: ['./test/_shared/setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**'],
+    },
+  },
+}));
+`;
+    vitestSetupTemplate = () => `import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
 
-\u274C Bad:
-\`\`\`typescript
-import { Button } from '../../../components/Button';  // relative path
-import Button from '@components/Button/Button';       // no file extension in alias
-\`\`\`
+afterEach(cleanup);
+`;
+    testTsconfigTemplate = (hasVitest) => JSON.stringify(
+      {
+        extends: "../tsconfig.json",
+        compilerOptions: hasVitest ? { types: ["@testing-library/jest-dom"] } : {},
+        include: ["."]
+      },
+      null,
+      2
+    );
+    unitHomeTestTemplate = (cart) => {
+      const importLine = cart.layout === "FSD" ? `import { HomePage } from '@/pages/home';` : `import Home from '@/pages/Home';`;
+      const component = cart.layout === "FSD" ? "HomePage" : "Home";
+      return `import { render } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+${importLine}
+
+// Paired contract: test/specs/unit/pages/home.spec.md
+describe('${component}', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<${component} />);
+    expect(container.firstChild).not.toBeNull();
+  });
+});
 `;
     };
-    linterTemplate = (cart) => {
-      if (cart.linter === "BIOME") {
-        return frontmatter("**") + `# Biome
+    unitHomeSpecMdTemplate = () => `# home.test.tsx \u2014 Contract
+
+Traces to: \`docs/features/home/home.spec.en.md\`
 
-- Configuration: \`biome.json\` at the repo root. Respect the rules it enforces.
-- Run \`npm run lint\` and \`npm run format\` before committing.
-- Do not disable rules inline (\`// biome-ignore\`) without a comment explaining why.
-- Import order, formatting, and unused imports are enforced by Biome \u2014 do not manually format differently.
+| Case | Covers |
+|---|---|
+| renders without crashing | The home page mounts with no props and produces DOM output |
+
+Add a row here for every new test case in \`test/unit/pages/home.test.tsx\`.
 `;
-      }
-      if (cart.linter === "ESLINT") {
-        return frontmatter("**") + `# ESLint
-
-- Configuration: \`eslint.config.js\` (flat config) at the repo root.
-- Run \`npm run lint\` before committing; fix all errors and warnings.
-- Do not add \`// eslint-disable\` or \`/* eslint-disable */\` without a short comment explaining why.
-- React hooks rules are enforced \u2014 never call hooks conditionally or in loops.
-- Unused variables must be prefixed with \`_\` or removed.
+    playwrightConfigTemplate = () => `import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './test/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+`;
+    e2eHomePageObjectTemplate = () => `import { Page } from '@playwright/test';
+
+export class HomePage {
+  constructor(private page: Page) {}
+
+  async goto() {
+    await this.page.goto('/');
+  }
+}
+`;
+    e2eHomeSpecTemplate = (projectName) => `import { test, expect } from '@playwright/test';
+import { HomePage } from '../_shared/pages/home.page';
+
+// Paired contract: test/specs/e2e/home.spec.md
+test('home page loads', async ({ page }) => {
+  const homePage = new HomePage(page);
+  await homePage.goto();
+  await expect(page).toHaveTitle(/${projectName}/i);
+});
+`;
+    e2eHomeSpecMdTemplate = () => `# home.spec.ts \u2014 Contract
+
+Traces to: \`docs/features/home/home.spec.en.md\`
+
+| Case | Covers |
+|---|---|
+| home page loads | Navigating to \`/\` renders the home page with the project title |
+
+Add a row here for every new test case in \`test/e2e/home.spec.ts\`.
+`;
+    testReadmeTemplate = (cart) => {
+      const hasVitest = cart.testing === "VITEST";
+      return `# test/ \u2014 Centralized Tests
+
+All test code lives here \u2014 never inside \`src/\`. One reviewable location, no test pollution in the source tree, no test-runner config changes needed when adding tests.
+
+## Layout
+
+\`\`\`
+test/
+${hasVitest ? `\u251C\u2500\u2500 unit/              # mirrors src/ layer structure; <name>.test.{ts,tsx}
+` : `\u251C\u2500\u2500 e2e/               # mirrors business flows; <flow>.spec.ts
+`}\u251C\u2500\u2500 _shared/           # fixtures/, helpers/, mocks/${hasVitest ? "" : ", pages/ (Page Object Models)"}
+\u251C\u2500\u2500 specs/             # paired *.spec.md contracts \u2014 documentation, NEVER executed
+\u2514\u2500\u2500 tsconfig.json      # extends root tsconfig for editor support
+\`\`\`
+
+## Conventions
+
+- Every test file has a paired contract at \`test/specs/<same-path>/<name>.spec.md\` listing what each case covers and which feature spec (\`docs/features/\`) it traces to. Update both together.
+${hasVitest ? `- Unit tests import app code via the \`@/\` alias and use explicit vitest imports.
+- Component tests use Testing Library \u2014 query by role/label, never by class name.
+
+## Running
+
+- \`npm test\` \u2014 watch mode
+- \`npm run test:run\` \u2014 single run (CI)
+- \`npm run coverage\` \u2014 with coverage report` : `- E2E specs stay thin \u2014 page interactions belong in Page Object Models under \`test/_shared/pages/\`.
+
+## Running
+
+- \`npm run test:e2e\` \u2014 runs Playwright (starts the dev server automatically)`}
 `;
-      }
-      return "";
     };
-    getCopilotInstructionFiles = (cart) => {
-      const hasRouter = cart.router === "TANSTACK_ROUTER";
-      const hasZustand = cart.stateManagement === "ZUSTAND";
-      const hasQuery = cart.query === "TANSTACK_QUERY";
-      const hasLinter = cart.linter !== "NOT_USING";
-      const files = [
-        { relativePath: ".github/copilot-instructions.md", content: generalTemplate(cart) },
-        { relativePath: ".github/instructions/imports.instructions.md", content: importsTemplate() },
-        { relativePath: ".github/instructions/components.instructions.md", content: componentsTemplate(cart) },
-        { relativePath: ".github/instructions/hooks.instructions.md", content: hooksTemplate(cart) }
-      ];
-      if (hasRouter) {
-        files.push({
-          relativePath: ".github/instructions/tanstack-router.instructions.md",
-          content: routerTemplate(cart)
-        });
-      }
-      if (hasZustand) {
-        files.push({
-          relativePath: ".github/instructions/zustand.instructions.md",
-          content: zustandTemplate(cart)
-        });
-      }
-      if (hasQuery) {
-        files.push({
-          relativePath: ".github/instructions/tanstack-query.instructions.md",
-          content: queryTemplate(cart)
-        });
-      }
-      if (cart.css === "TAILWIND") {
-        files.push({
-          relativePath: ".github/instructions/tailwind.instructions.md",
-          content: tailwindTemplate(cart)
-        });
+    getTestingFileMap = (cart) => {
+      const files = [];
+      if (cart.testing === "VITEST") {
+        files.push(
+          { relativePath: "vitest.config.ts", content: vitestConfigTemplate() },
+          { relativePath: "test/README.md", content: testReadmeTemplate(cart) },
+          { relativePath: "test/tsconfig.json", content: testTsconfigTemplate(true) },
+          { relativePath: "test/_shared/setup.ts", content: vitestSetupTemplate() },
+          { relativePath: "test/_shared/fixtures/.gitkeep", content: "" },
+          { relativePath: "test/_shared/helpers/.gitkeep", content: "" },
+          { relativePath: "test/_shared/mocks/.gitkeep", content: "" },
+          { relativePath: "test/unit/pages/home.test.tsx", content: unitHomeTestTemplate(cart) },
+          { relativePath: "test/specs/unit/pages/home.spec.md", content: unitHomeSpecMdTemplate() }
+        );
       }
-      if (hasLinter) {
-        files.push({
-          relativePath: `.github/instructions/${cart.linter === "BIOME" ? "biome" : "eslint"}.instructions.md`,
-          content: linterTemplate(cart)
-        });
+      if (cart.testing === "PLAYWRIGHT") {
+        files.push(
+          { relativePath: "playwright.config.ts", content: playwrightConfigTemplate() },
+          { relativePath: "test/README.md", content: testReadmeTemplate(cart) },
+          { relativePath: "test/tsconfig.json", content: testTsconfigTemplate(false) },
+          { relativePath: "test/_shared/fixtures/.gitkeep", content: "" },
+          { relativePath: "test/_shared/helpers/.gitkeep", content: "" },
+          { relativePath: "test/_shared/mocks/.gitkeep", content: "" },
+          { relativePath: "test/_shared/pages/home.page.ts", content: e2eHomePageObjectTemplate() },
+          { relativePath: "test/e2e/home.spec.ts", content: e2eHomeSpecTemplate(cart.projectName) },
+          { relativePath: "test/specs/e2e/home.spec.md", content: e2eHomeSpecMdTemplate() }
+        );
       }
       return files;
     };
@@ -1507,7 +2007,8 @@ var init_fsd_layout = __esm({
     init_gitignore();
     init_styles();
     init_vite_env_d_ts();
-    init_copilot_instructions();
+    init_claude_setup2();
+    init_testing_setup();
     init_home_page();
     getFsdFileMap = (cart) => {
       const hasRouter = cart.router === "TANSTACK_ROUTER";
@@ -1520,7 +2021,8 @@ var init_fsd_layout = __esm({
         { relativePath: "tsconfig.node.json", content: tsconfigNodeTemplate() },
         { relativePath: "index.html", content: indexHtmlTemplate(cart.projectName) },
         { relativePath: ".gitignore", content: gitignoreTemplate() },
-        ...getCopilotInstructionFiles(cart),
+        ...cart.ai === "CLAUDE" ? getClaudeFileMap(cart) : [],
+        ...cart.testing !== "NOT_USING" ? getTestingFileMap(cart) : [],
         { relativePath: "src/vite-env.d.ts", content: viteEnvDtsTemplate() },
         { relativePath: "src/main.tsx", content: mainTsxTemplate(cart) },
         { relativePath: "src/app/index.tsx", content: appTsxFsdTemplate(hasRouter, hasQuery) },
@@ -1611,7 +2113,8 @@ var init_bpr_layout = __esm({
     init_gitignore();
     init_styles();
     init_vite_env_d_ts();
-    init_copilot_instructions();
+    init_claude_setup2();
+    init_testing_setup();
     init_home_page();
     getBprFileMap = (cart) => {
       const hasRouter = cart.router === "TANSTACK_ROUTER";
@@ -1624,7 +2127,8 @@ var init_bpr_layout = __esm({
         { relativePath: "tsconfig.node.json", content: tsconfigNodeTemplate() },
         { relativePath: "index.html", content: indexHtmlTemplate(cart.projectName) },
         { relativePath: ".gitignore", content: gitignoreTemplate() },
-        ...getCopilotInstructionFiles(cart),
+        ...cart.ai === "CLAUDE" ? getClaudeFileMap(cart) : [],
+        ...cart.testing !== "NOT_USING" ? getTestingFileMap(cart) : [],
         { relativePath: "src/vite-env.d.ts", content: viteEnvDtsTemplate() },
         { relativePath: "src/main.tsx", content: mainTsxTemplate(cart) },
         { relativePath: "src/App.tsx", content: appTsxBprTemplate(hasRouter, hasQuery) },
@@ -1675,8 +2179,8 @@ __export(react_vite_exports, {
   scaffoldReactVite: () => scaffoldReactVite
 });
 import path2 from "path";
-import chalk from "chalk";
-import { createSpinner } from "nanospinner";
+import chalk2 from "chalk";
+import { createSpinner as createSpinner2 } from "nanospinner";
 var scaffoldReactVite;
 var init_react_vite = __esm({
   "src/scaffold/react-vite/index.ts"() {
@@ -1695,33 +2199,33 @@ var init_react_vite = __esm({
           `Directory "${projectName}" already exists. Please choose a different project name or remove the existing directory.`
         );
       }
-      const spinner = createSpinner(`Scaffolding ${chalk.cyan(projectName)}...`).start();
+      const spinner = createSpinner2(`Scaffolding ${chalk2.cyan(projectName)}...`).start();
       try {
         const fileMap = cart.layout === "FSD" ? getFsdFileMap(cart) : getBprFileMap(cart);
         for (const { relativePath, content } of fileMap) {
           await writeProjectFile(projectRoot, relativePath, content);
         }
         spinner.success({
-          text: chalk.green(`Project ${chalk.bold(projectName)} created successfully!`)
+          text: chalk2.green(`Project ${chalk2.bold(projectName)} created successfully!`)
         });
         console.log("");
-        console.log(chalk.whiteBright("Next steps:"));
-        console.log(chalk.cyan(`  cd ${projectName}`));
-        console.log(chalk.cyan("  npm install"));
-        console.log(chalk.cyan("  npm run dev"));
+        console.log(chalk2.whiteBright("Next steps:"));
+        console.log(chalk2.cyan(`  cd ${projectName}`));
+        console.log(chalk2.cyan("  npm install"));
+        console.log(chalk2.cyan("  npm run dev"));
         if (cart.router === "TANSTACK_ROUTER") {
           console.log("");
-          console.log(chalk.gray("  Note: TanStack Router will auto-generate routeTree.gen.ts on first dev run."));
+          console.log(chalk2.gray("  Note: TanStack Router will auto-generate routeTree.gen.ts on first dev run."));
         }
         console.log("");
       } catch (err) {
-        spinner.error({ text: chalk.red("Scaffolding failed.") });
+        spinner.error({ text: chalk2.red("Scaffolding failed.") });
         if (err instanceof ScaffoldError) {
-          console.error(chalk.red(err.message));
+          console.error(chalk2.red(err.message));
         } else if (isNodeError(err)) {
-          console.error(chalk.red(`File system error (${err.code}): ${err.message}`));
+          console.error(chalk2.red(`File system error (${err.code}): ${err.message}`));
         } else {
-          console.error(chalk.red("An unexpected error occurred."), err);
+          console.error(chalk2.red("An unexpected error occurred."), err);
         }
         try {
           const { rm } = await import("fs/promises");
@@ -1738,16 +2242,18 @@ var init_react_vite = __esm({
 var react_vite_exports2 = {};
 __export(react_vite_exports2, {
   flowReactVite: () => flowReactVite,
+  menuAI: () => menuAI,
   menuCss: () => menuCss,
   menuLayout: () => menuLayout,
   menuLinter: () => menuLinter,
   menuQuery: () => menuQuery,
   menuRouter: () => menuRouter,
-  menuStateManagement: () => menuStateManagement
+  menuStateManagement: () => menuStateManagement,
+  menuTesting: () => menuTesting
 });
 import { select, input, Separator } from "@inquirer/prompts";
-import chalk2 from "chalk";
-var selectFromMenu, menuProjectName, menuLayout, menuRouter, menuStateManagement, menuQuery, menuCss, menuLinter, flowReactVite;
+import chalk3 from "chalk";
+var selectFromMenu, menuProjectName, menuLayout, menuRouter, menuStateManagement, menuQuery, menuCss, menuLinter, menuTesting, menuAI, flowReactVite;
 var init_react_vite2 = __esm({
   "src/options/react-vite/index.ts"() {
     "use strict";
@@ -1762,7 +2268,7 @@ var init_react_vite2 = __esm({
         description: menuOptions[key].description
       }));
       const answer = await select({
-        message: chalk2.whiteBright(message),
+        message: chalk3.whiteBright(message),
         choices: [...choices, new Separator()]
       });
       return answer;
@@ -1770,7 +2276,7 @@ var init_react_vite2 = __esm({
     menuProjectName = async (cart) => {
       if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ReactVite.value) return;
       cart.projectName = await input({
-        message: chalk2.whiteBright("Project name:"),
+        message: chalk3.whiteBright("Project name:"),
         validate: (value) => {
           if (!value.trim()) return "Project name cannot be empty";
           if (!/^[a-zA-Z0-9_-]+$/.test(value.trim()))
@@ -1813,6 +2319,14 @@ var init_react_vite2 = __esm({
         "Choose a Linter / Formatter"
       );
     };
+    menuTesting = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ReactVite.value) return;
+      cart.testing = await selectFromMenu(REACT_MENU_TESTING, "Choose a Testing setup");
+    };
+    menuAI = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ReactVite.value) return;
+      cart.ai = await selectFromMenu(REACT_MENU_AI, "Choose an AI setup");
+    };
     flowReactVite = async (cart) => {
       if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ReactVite.value) return;
       await menuProjectName(cart);
@@ -1822,6 +2336,8 @@ var init_react_vite2 = __esm({
       await menuQuery(cart);
       await menuCss(cart);
       await menuLinter(cart);
+      await menuTesting(cart);
+      await menuAI(cart);
       const { scaffoldReactVite: scaffoldReactVite2 } = await Promise.resolve().then(() => (init_react_vite(), react_vite_exports));
       await scaffoldReactVite2(cart);
     };
@@ -1829,7 +2345,7 @@ var init_react_vite2 = __esm({
 });
 
 // src/options/chrome-extension/constants/index.ts
-var CHROME_MENU_STATE_MANAGEMENT, CHROME_MENU_QUERY, CHROME_MENU_CSS, CHROME_MENU_LINTER;
+var CHROME_MENU_STATE_MANAGEMENT, CHROME_MENU_QUERY, CHROME_MENU_CSS, CHROME_MENU_AI, CHROME_MENU_LINTER;
 var init_constants3 = __esm({
   "src/options/chrome-extension/constants/index.ts"() {
     "use strict";
@@ -1875,6 +2391,20 @@ var init_constants3 = __esm({
         disabled: false
       }
     };
+    CHROME_MENU_AI = {
+      notUsing: {
+        display: "Not Using",
+        value: "NOT_USING",
+        description: "No AI setup",
+        disabled: false
+      },
+      claude: {
+        display: "Claude (Claude Code)",
+        value: "CLAUDE",
+        description: "CLAUDE.md + .claude/ agents + feature docs structure",
+        disabled: false
+      }
+    };
     CHROME_MENU_LINTER = {
       notUsing: {
         display: "Not Using",
@@ -1948,6 +2478,10 @@ var init_package_json2 = __esm({
       } else if (cart.linter === "ESLINT") {
         scripts["lint"] = "eslint .";
       }
+      if (cart.ai === "CLAUDE") {
+        scripts["docs:index"] = "node .claude/scripts/build-docs-index.mjs";
+        scripts["docs:lint"] = "node .claude/scripts/lint-docs-frontmatter.mjs";
+      }
       return JSON.stringify(
         {
           name: cart.projectName,
@@ -2115,6 +2649,285 @@ export default App;
   }
 });
 
+// src/scaffold/chrome-extension/templates/claude-setup.ts
+var projectSlug2, layerEnum2, flowEnum2, reminderTrigger2, claudeMdTemplate2, docsPopupSpecTemplate, conventionsSkillTemplate2, devAgentTemplate2, getClaudeFileMap2;
+var init_claude_setup3 = __esm({
+  "src/scaffold/chrome-extension/templates/claude-setup.ts"() {
+    "use strict";
+    init_claude_setup();
+    projectSlug2 = (cart) => cart.projectName.toLowerCase().replace(/_/g, "-");
+    layerEnum2 = (cart) => [
+      "popup",
+      "components",
+      "hooks",
+      "lib",
+      ...cart.stateManagement === "ZUSTAND" ? ["stores"] : [],
+      "types",
+      "utils",
+      "_cross"
+    ];
+    flowEnum2 = (cart) => [
+      "ui",
+      "data",
+      ...cart.stateManagement === "ZUSTAND" ? ["state"] : [],
+      "extension",
+      "infra",
+      "architecture",
+      "onboarding",
+      "_meta"
+    ];
+    reminderTrigger2 = (cart) => `popup|manifest${cart.stateManagement === "ZUSTAND" ? "|store|state" : ""}${cart.query === "TANSTACK_QUERY" ? "|query|fetch" : ""}`;
+    claudeMdTemplate2 = (cart) => {
+      const hasZustand = cart.stateManagement === "ZUSTAND";
+      const hasQuery = cart.query === "TANSTACK_QUERY";
+      const slug = projectSlug2(cart);
+      const stack = [
+        "React 19, TypeScript 5.8, Vite 6",
+        "Chrome Extension Manifest V3 (popup-only)",
+        hasZustand ? "Zustand v5.0.5" : null,
+        hasQuery ? "TanStack Query v5.74.4" : null,
+        cart.css === "TAILWIND" ? "Tailwind CSS v4.1.3" : null,
+        cart.linter === "BIOME" ? "Biome v1.9.4" : cart.linter === "ESLINT" ? "ESLint v9" : null
+      ].filter(Boolean);
+      const commands = [
+        "- `npm run dev` \u2014 develop the popup as a normal Vite page (http://localhost:5173)",
+        "- `npm run build` \u2014 type-check + production build into `dist/`",
+        "- `npm run build-extension` \u2014 build + copy `manifest.json` into `dist/`; load `dist/` as an unpacked extension at chrome://extensions",
+        cart.linter !== "NOT_USING" ? "- `npm run lint` \u2014 lint code" : null,
+        "- `npm run docs:index` \u2014 regenerate docs/INDEX.md (run after any doc change)",
+        "- `npm run docs:lint` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)"
+      ].filter(Boolean);
+      const keyPatterns = [
+        `**Popup lifecycle \u2014 the popup unmounts when it closes:**
+React state dies with the popup window. Anything that must survive a close (settings, session data) belongs in \`chrome.storage\`, not in component state${hasZustand ? " or the Zustand store" : ""}.`
+      ];
+      if (hasZustand) {
+        keyPatterns.push(`**Zustand \u2014 select narrowly, never the whole store:**
+\`\`\`ts
+const count = useAppStore((state) => state.count); // \u2705 re-renders on count only
+const store = useAppStore();                       // \u274C re-renders on every change
+\`\`\``);
+      }
+      if (hasQuery) {
+        keyPatterns.push(`**TanStack Query \u2014 key factories, not inline keys:**
+\`\`\`ts
+const todoKeys = {
+  all: ['todos'] as const,
+  detail: (id: string) => [...todoKeys.all, id] as const,
+};
+useQuery({ queryKey: todoKeys.detail(id), queryFn: () => fetchTodo(id) });
+\`\`\``);
+      }
+      return `# ${cart.projectName}
+
+## Behavioral Guidelines
+
+**Think Before Coding** \u2014 state assumptions explicitly; if multiple interpretations exist, present them; if something is unclear, stop and ask.
+**Simplicity First** \u2014 minimum code that solves the problem; no speculative features, abstractions, or configurability.
+**Surgical Changes** \u2014 touch only what the request requires; match existing style; every changed line traces to the request.
+**Goal-Driven Execution** \u2014 turn tasks into verifiable success criteria before starting; loop until verified.
+
+## Project Overview
+
+${stack.map((s) => `- ${s}`).join("\n")}
+
+This is a **popup-only MV3 extension**: \`index.html\` \u2192 \`src/main.tsx\` \u2192 \`src/App.tsx\` is the popup root. No background service worker or content scripts are configured \u2014 adding one requires registering it in \`manifest.json\` AND adding a Rollup input in \`vite.config.ts\`.
+
+## Commands
+
+${commands.join("\n")}
+
+## Architecture
+
+\`\`\`
+manifest.json  \u2192 MV3 source of truth (root of the repo)
+src/App.tsx    \u2192 popup root component
+components     \u2192 shared presentational components
+hooks          \u2192 shared React hooks
+lib            \u2192 third-party wrappers / configured clients
+${hasZustand ? "stores         \u2192 global state (Zustand)\n" : ""}types          \u2192 shared TypeScript types
+utils          \u2192 pure utility functions
+\`\`\`
+
+**Hard rules:**
+- \`manifest.json\` at the repo root is the single source of truth \u2014 NEVER edit \`dist/manifest.json\` (it is a build artifact copied by \`npm run build-extension\`).
+- Shared folders (components/, hooks/, lib/, utils/) must stay feature-agnostic.
+- Keep components presentational; data fetching and chrome.* API calls live in hooks or lib/.
+
+## Key Patterns
+
+${keyPatterns.join("\n\n")}
+
+## Import Aliases
+
+\`@/\` (src root), \`@components\`, \`@hooks\`, \`@lib\`, \`@types\`, \`@utils\` \u2014 defined in \`vite.config.ts\`. Never use long relative chains (\`../../..\`).
+
+## Anti-Patterns
+
+| Anti-pattern | Correct approach |
+|---|---|
+| Editing \`dist/manifest.json\` | Edit root \`manifest.json\`; rebuild with \`npm run build-extension\` |
+| Persisting data in React state${hasZustand ? "/Zustand" : ""} that must survive popup close | Use \`chrome.storage\` |
+| \`useEffect\` for derived state | Compute during render or use \`useMemo\` |
+
+> Fill this table from real review feedback over time \u2014 it is the highest-leverage section for code quality.
+
+## Agent Routing
+
+| Task / trigger | Agent | Notes |
+|---|---|---|
+| Feature work or bug fix in \`src/\` or \`manifest.json\` | \`dev\` | MUST read relevant \`docs/features/\` spec before coding |
+| Analyzing requirements, writing/updating feature docs | \`docs-writer\` | owns \`docs/\`; rebuilds INDEX.md after every change |
+
+Each agent has persistent memory at \`.claude/agent-memory/<agent>/MEMORY.md\` \u2014 agents read it on start and append new gotchas. Do NOT use the general assistant for work an agent owns \u2014 always delegate.
+
+## Task Documentation Convention
+
+After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`npm run docs:index\` and commit the doc together with \`INDEX.md\`. Validate with \`npm run docs:lint\`.
+
+## Further Reading + DOCS-FIRST RULE
+
+Skills: \`.claude/skills/${slug}-conventions\` (architecture depth), \`.claude/skills/${slug}-docs\` (how to query the knowledge base).
+
+**DOCS-FIRST RULE:** for any request to describe, explain, or modify a documented feature, you MUST grep \`docs/\` frontmatter and read the relevant docs BEFORE opening source files \u2014 and state what the docs already covered. Start at \`docs/INDEX.md\`.
+
+**Operating loop:** finish a non-trivial task \u2192 write a doc from \`docs/_template.md\` \u2192 rebuild \`INDEX.md\` \u2192 commit together; agents update their \`MEMORY.md\` when they learn a gotcha.
+`;
+    };
+    docsPopupSpecTemplate = (cart) => {
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      return `---
+title: Popup \u2014 Feature Spec
+feature: popup
+flow: ui
+layer: popup
+status: draft
+lang: en
+related: []
+keywords: [popup, manifest]
+updated: ${today}
+---
+
+# Popup \u2014 Feature Spec
+
+## Context
+Starter popup generated by the scaffold. Replace this spec with the real requirements for ${cart.projectName}'s popup.
+
+## Root Cause / Key Finding
+_(For feature specs, use this section for key constraints or discoveries.)_
+
+## Solution / Pattern
+- Requirements: [list what the popup must do]
+- UI/UX: [screens and interactions]
+- Data: [data structures, chrome.storage keys, API requirements]
+- Edge cases: [what must not break \u2014 remember the popup unmounts on close]
+
+## Key Decisions
+_(Trade-offs made and alternatives rejected.)_
+
+## Related Files
+- src/App.tsx
+- manifest.json
+`;
+    };
+    conventionsSkillTemplate2 = (cart) => {
+      const slug = projectSlug2(cart);
+      const hasZustand = cart.stateManagement === "ZUSTAND";
+      return `---
+name: ${slug}-conventions
+description: Coding conventions and architecture rules for ${cart.projectName} (Chrome extension, MV3 popup). Use when writing or reviewing ANY code under src/ \u2014 components, hooks${hasZustand ? ", stores" : ""}, or styling \u2014 or when touching manifest.json. Triggers on tasks mentioning popup, manifest, components, naming, imports, or project structure.
+---
+
+# ${cart.projectName} Conventions
+
+In-depth companion to CLAUDE.md. CLAUDE.md states the rules; this skill explains how to apply them.
+
+## Structure
+
+- Popup root: \`src/App.tsx\` (entry: \`index.html\` \u2192 \`src/main.tsx\`).
+- Shared folders (components/, hooks/, lib/, utils/) must stay feature-agnostic.
+- \`manifest.json\` at the repo root is the MV3 source of truth; \`npm run build-extension\` copies it into \`dist/\` \u2014 never edit the copy.
+- No background service worker / content scripts are configured. Adding one = register it in \`manifest.json\` + add a Rollup input in \`vite.config.ts\`.
+
+## Import aliases
+
+\`@/\`, \`@components\`, \`@hooks\`, \`@lib\`, \`@types\`, \`@utils\` (see \`vite.config.ts\`). Never use long relative chains (\`../../..\`).
+
+## Chrome APIs
+
+- Wrap \`chrome.*\` calls in \`lib/\` or hooks \u2014 components stay presentational.
+- State that must survive popup close goes in \`chrome.storage\`, not React state${hasZustand ? " or Zustand" : ""}.
+
+${hasZustand ? `## Zustand
+
+- One store per domain; name \`use<Domain>Store\`.
+- Components select narrow slices: \`useAppStore((s) => s.count)\`.
+- Async actions live inside the store, setting loading/error state themselves.
+
+` : ""}${cart.query === "TANSTACK_QUERY" ? `## TanStack Query
+
+- Define a key factory per entity next to its query functions.
+- Mutations invalidate via the same factory: \`queryClient.invalidateQueries({ queryKey: todoKeys.all })\`.
+- Server state belongs in Query \u2014 do not mirror it into ${hasZustand ? "Zustand" : "local state"}.
+
+` : ""}${cart.css === "TAILWIND" ? `## Tailwind CSS v4
+
+- Theme tokens live in \`src/index.css\` under \`@theme\` \u2014 extend there, not in a JS config.
+- Prefer semantic class composition in components over @apply.
+
+` : ""}## When unsure
+
+Check \`src/App.tsx\` first, then the docs (\`docs/INDEX.md\`), then ask.
+`;
+    };
+    devAgentTemplate2 = (cart) => {
+      const slug = projectSlug2(cart);
+      return `---
+name: dev
+description: "Implementation agent for ${cart.projectName} \u2014 all feature work and bug fixes under src/ and manifest.json. <example>user: 'Add a settings toggle to the popup' \u2192 dev <commentary>feature work in src/; dev reads the feature spec first, then implements</commentary></example> <example>user: 'The popup crashes on empty data \u2014 fix it' \u2192 dev <commentary>bug fix inside a documented feature</commentary></example> <example>user: 'Write a spec for the options page' \u2192 docs-writer, NOT dev <commentary>doc authoring belongs to docs-writer</commentary></example>"
+model: sonnet
+memory: project
+---
+
+You are the implementation agent for ${cart.projectName}.
+
+## Onboarding protocol (in order, before any code)
+
+1. Read \`.claude/agent-memory/dev/MEMORY.md\` \u2014 your accumulated gotchas.
+2. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec for the task.
+3. Load the \`${slug}-conventions\` skill for structure rules and patterns.
+4. Read the code under change.
+
+If no relevant feature spec exists, STOP and tell the user to run the docs-writer agent first.
+
+## Workflow
+
+1. State assumptions and success criteria.
+2. Implement the minimum change that satisfies the spec; match existing style.
+3. Verify (build; for manifest/extension changes run \`npm run build-extension\` and report what to check at chrome://extensions); report results faithfully.
+4. Append newly discovered gotchas/patterns to \`.claude/agent-memory/dev/MEMORY.md\`.
+
+## Hard rules
+
+- Never commit or push \u2014 a human does that.
+- Never write docs (delegate to docs-writer); flag when they are needed.
+- Never edit \`dist/\` (build artifact, including \`dist/manifest.json\`) or \`docs/INDEX.md\` by hand.
+`;
+    };
+    getClaudeFileMap2 = (cart) => buildClaudeFileMap({
+      projectName: cart.projectName,
+      slug: projectSlug2(cart),
+      flowEnum: flowEnum2(cart),
+      layerEnum: layerEnum2(cart),
+      reminderTrigger: reminderTrigger2(cart),
+      claudeMd: claudeMdTemplate2(cart),
+      conventionsSkill: conventionsSkillTemplate2(cart),
+      devAgent: devAgentTemplate2(cart),
+      seedDocs: [{ relativePath: "docs/features/popup/popup.spec.en.md", content: docsPopupSpecTemplate(cart) }]
+    });
+  }
+});
+
 // src/scaffold/chrome-extension/templates/layout.ts
 var getChromeExtensionFileMap;
 var init_layout = __esm({
@@ -2126,6 +2939,7 @@ var init_layout = __esm({
     init_build_extension_script();
     init_main_tsx2();
     init_app_tsx2();
+    init_claude_setup3();
     init_vite_env_d_ts();
     init_tsconfig();
     init_index_html();
@@ -2143,6 +2957,7 @@ var init_layout = __esm({
         { relativePath: "index.html", content: indexHtmlTemplate(cart.projectName) },
         { relativePath: "manifest.json", content: manifestJsonTemplate(cart.projectName) },
         { relativePath: ".gitignore", content: gitignoreTemplate() },
+        ...cart.ai === "CLAUDE" ? getClaudeFileMap2(cart) : [],
         { relativePath: "scripts/build-extension.js", content: buildExtensionScriptTemplate() },
         { relativePath: "src/vite-env.d.ts", content: viteEnvDtsTemplate() },
         { relativePath: "src/main.tsx", content: mainTsxTemplate2(cart) },
@@ -2175,8 +2990,8 @@ __export(chrome_extension_exports, {
   scaffoldChromeExtension: () => scaffoldChromeExtension
 });
 import path3 from "path";
-import chalk3 from "chalk";
-import { createSpinner as createSpinner2 } from "nanospinner";
+import chalk4 from "chalk";
+import { createSpinner as createSpinner3 } from "nanospinner";
 var scaffoldChromeExtension;
 var init_chrome_extension = __esm({
   "src/scaffold/chrome-extension/index.ts"() {
@@ -2194,33 +3009,33 @@ var init_chrome_extension = __esm({
           `Directory "${projectName}" already exists. Please choose a different project name or remove the existing directory.`
         );
       }
-      const spinner = createSpinner2(`Scaffolding ${chalk3.cyan(projectName)}...`).start();
+      const spinner = createSpinner3(`Scaffolding ${chalk4.cyan(projectName)}...`).start();
       try {
         const fileMap = getChromeExtensionFileMap(cart);
         for (const { relativePath, content } of fileMap) {
           await writeProjectFile(projectRoot, relativePath, content);
         }
         spinner.success({
-          text: chalk3.green(`Project ${chalk3.bold(projectName)} created successfully!`)
+          text: chalk4.green(`Project ${chalk4.bold(projectName)} created successfully!`)
         });
         console.log("");
-        console.log(chalk3.whiteBright("Next steps:"));
-        console.log(chalk3.cyan(`  cd ${projectName}`));
-        console.log(chalk3.cyan("  npm install"));
-        console.log(chalk3.cyan("  npm run dev"));
+        console.log(chalk4.whiteBright("Next steps:"));
+        console.log(chalk4.cyan(`  cd ${projectName}`));
+        console.log(chalk4.cyan("  npm install"));
+        console.log(chalk4.cyan("  npm run dev"));
         console.log("");
-        console.log(chalk3.whiteBright("To build the extension:"));
-        console.log(chalk3.cyan("  npm run build-extension"));
-        console.log(chalk3.gray("  Then load the dist/ folder in Chrome at chrome://extensions"));
+        console.log(chalk4.whiteBright("To build the extension:"));
+        console.log(chalk4.cyan("  npm run build-extension"));
+        console.log(chalk4.gray("  Then load the dist/ folder in Chrome at chrome://extensions"));
         console.log("");
       } catch (err) {
-        spinner.error({ text: chalk3.red("Scaffolding failed.") });
+        spinner.error({ text: chalk4.red("Scaffolding failed.") });
         if (err instanceof ScaffoldError) {
-          console.error(chalk3.red(err.message));
+          console.error(chalk4.red(err.message));
         } else if (isNodeError(err)) {
-          console.error(chalk3.red(`File system error (${err.code}): ${err.message}`));
+          console.error(chalk4.red(`File system error (${err.code}): ${err.message}`));
         } else {
-          console.error(chalk3.red("An unexpected error occurred."), err);
+          console.error(chalk4.red("An unexpected error occurred."), err);
         }
         try {
           const { rm } = await import("fs/promises");
@@ -2239,8 +3054,8 @@ __export(chrome_extension_exports2, {
   flowChromeExtension: () => flowChromeExtension
 });
 import { select as select2, input as input2, Separator as Separator2 } from "@inquirer/prompts";
-import chalk4 from "chalk";
-var selectFromMenu2, menuProjectName2, menuStateManagement2, menuQuery2, menuCss2, menuLinter2, flowChromeExtension;
+import chalk5 from "chalk";
+var selectFromMenu2, menuProjectName2, menuStateManagement2, menuQuery2, menuCss2, menuLinter2, menuAI2, flowChromeExtension;
 var init_chrome_extension2 = __esm({
   "src/options/chrome-extension/index.ts"() {
     "use strict";
@@ -2255,7 +3070,7 @@ var init_chrome_extension2 = __esm({
         description: menuOptions[key].description
       }));
       const answer = await select2({
-        message: chalk4.whiteBright(message),
+        message: chalk5.whiteBright(message),
         choices: [...choices, new Separator2()]
       });
       return answer;
@@ -2263,7 +3078,7 @@ var init_chrome_extension2 = __esm({
     menuProjectName2 = async (cart) => {
       if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ChromeExtension.value) return;
       cart.projectName = await input2({
-        message: chalk4.whiteBright("Project name:"),
+        message: chalk5.whiteBright("Project name:"),
         validate: (value) => {
           if (!value.trim()) return "Project name cannot be empty";
           if (!/^[a-zA-Z0-9_-]+$/.test(value.trim()))
@@ -2292,6 +3107,10 @@ var init_chrome_extension2 = __esm({
       if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ChromeExtension.value) return;
       cart.linter = await selectFromMenu2(CHROME_MENU_LINTER, "Choose a Linter / Formatter");
     };
+    menuAI2 = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ChromeExtension.value) return;
+      cart.ai = await selectFromMenu2(CHROME_MENU_AI, "Choose an AI setup");
+    };
     flowChromeExtension = async (cart) => {
       if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.ChromeExtension.value) return;
       await menuProjectName2(cart);
@@ -2299,16 +3118,62 @@ var init_chrome_extension2 = __esm({
       await menuQuery2(cart);
       await menuCss2(cart);
       await menuLinter2(cart);
+      await menuAI2(cart);
       const { scaffoldChromeExtension: scaffoldChromeExtension2 } = await Promise.resolve().then(() => (init_chrome_extension(), chrome_extension_exports));
       await scaffoldChromeExtension2(cart);
     };
   }
 });
 
+// src/commands/update.ts
+import { exec } from "child_process";
+import { promisify } from "util";
+import chalk from "chalk";
+import { createSpinner } from "nanospinner";
+var execAsync = promisify(exec);
+var PACKAGE_NAME = "beaver-build";
+var runUpdate = async (currentVersion) => {
+  const spinner = createSpinner("Checking for updates...").start();
+  let latestVersion;
+  try {
+    const { stdout } = await execAsync(`npm view ${PACKAGE_NAME} version`);
+    latestVersion = stdout.trim();
+  } catch {
+    spinner.error({ text: chalk.red("Failed to check the latest version from npm.") });
+    console.error(chalk.red("Please check your network connection and try again."));
+    process.exit(1);
+  }
+  if (latestVersion === currentVersion) {
+    spinner.success({
+      text: chalk.green(`Already on the latest version (v${currentVersion}).`)
+    });
+    return;
+  }
+  spinner.update({
+    text: `Updating ${chalk.cyan(PACKAGE_NAME)} v${currentVersion} \u2192 v${latestVersion}...`
+  });
+  try {
+    await execAsync(`npm install -g ${PACKAGE_NAME}@latest`);
+    spinner.success({
+      text: chalk.green(`Updated to ${chalk.bold(`v${latestVersion}`)}!`)
+    });
+  } catch (err) {
+    spinner.error({ text: chalk.red("Update failed.") });
+    const message = err instanceof Error ? err.message : String(err);
+    if (/EACCES|permission/i.test(message)) {
+      console.error(chalk.red("Permission denied while installing globally."));
+      console.error(chalk.yellow(`Try: sudo npm install -g ${PACKAGE_NAME}@latest`));
+    } else {
+      console.error(chalk.red(message));
+    }
+    process.exit(1);
+  }
+};
+
 // src/options/index.ts
 init_constants();
 import { select as select3, Separator as Separator3 } from "@inquirer/prompts";
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 var menu = async () => {
   const keys = Object.keys(MENU_OPTIONS_LEVEL_1);
   const enabledKeys = keys.filter((key) => !MENU_OPTIONS_LEVEL_1[key].disabled);
@@ -2326,7 +3191,7 @@ var menu = async () => {
     }
   ];
   const answer = await select3({
-    message: chalk5.whiteBright("How can I help you \u{1F468}\u200D\u{1F373}"),
+    message: chalk6.whiteBright("How can I help you \u{1F468}\u200D\u{1F373}"),
     choices
   });
   const cart = { type: answer };
@@ -2352,6 +3217,23 @@ var typeWriter = async (text, colorFunc, speed = 50) => {
   process.stdout.write("\n");
 };
 
+// src/utils/check-node-version.ts
+import chalk7 from "chalk";
+var MIN_NODE_MAJOR = 20;
+var checkNodeVersion = () => {
+  const major = parseInt(process.version.slice(1).split(".")[0], 10);
+  if (major < MIN_NODE_MAJOR) {
+    console.error(
+      chalk7.red(
+        `\u2716 beaver requires Node.js v${MIN_NODE_MAJOR} or higher.
+  You are running ${process.version}.
+  Please upgrade Node.js: https://nodejs.org`
+      )
+    );
+    process.exit(1);
+  }
+};
+
 // src/utils/user.ts
 import { execSync } from "child_process";
 var getUserName = () => {
@@ -2360,7 +3242,7 @@ var getUserName = () => {
 };
 
 // src/index.ts
-import chalk6 from "chalk";
+import chalk8 from "chalk";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -2374,6 +3256,7 @@ var getVersion = () => {
   }
 };
 var main = async () => {
+  checkNodeVersion();
   const args = process.argv.slice(2);
   if (args.includes("--version") || args.includes("-v")) {
     console.log(`beaver-build v${getVersion()}`);
@@ -2384,7 +3267,10 @@ var main = async () => {
 beaver-build - Interactive CLI for scaffolding modern web projects
 
 Usage:
-  beaver [options]
+  beaver [command] [options]
+
+Commands:
+  update            Update beaver to the latest version from npm
 
 Options:
   -v, --version     Show version
@@ -2392,13 +3278,17 @@ Options:
     `);
     process.exit(0);
   }
-  await typeWriter(`Hi! ${getUserName()} \u{1F646}`, chalk6.whiteBright, 50);
+  if (args[0] === "update") {
+    await runUpdate(getVersion());
+    process.exit(0);
+  }
+  await typeWriter(`Hi! ${getUserName()} \u{1F646}`, chalk8.whiteBright, 50);
   await sleep(500);
   try {
     await menu();
   } catch (err) {
     if (err instanceof Error) {
-      console.error(chalk6.red(err.message));
+      console.error(chalk8.red(err.message));
     }
     process.exit(1);
   }