bsmnt 0.0.2 → 0.1.0

package/tasks/archive/2026-02-09-next-starter-dynamic-layers/prd.json

@@ -0,0 +1,153 @@
+{
+  "project": "basement-cli",
+  "branchName": "ralph/next-starter-dynamic-layers",
+  "description": "Replace 4 static templates with next-starter clone + dynamic technology layers to eliminate maintenance burden",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Create layer configuration system",
+      "description": "As a CLI maintainer, I want technology layers defined in a config file so that adding or modifying layers only requires changing one file.",
+      "acceptanceCriteria": [
+        "Add LAYER_CONFIG export to src/mergers/config.js alongside existing CMS_CONFIG",
+        "Each layer config defines: replaceFiles, additivePaths, dependencies, devDependencies",
+        "Add getLayerConfig(layer) helper function export",
+        "Config contains entries for webgl, webgpu, and experiment",
+        "webgpu is a deps-only layer (empty replaceFiles and additivePaths arrays)",
+        "webgl dependencies: @react-three/fiber ^9.5.0, @react-three/drei ^10.7.7, three ^0.182.0, @gsap/react ^2.0.0, @radix-ui/react-navigation-menu ^1.2.5, leva ^0.9.35, devDeps: @types/three ^0.182.0",
+        "webgpu dependencies: @react-three/fiber 10.0.0-alpha.2, @react-three/drei ^11.0.0-alpha.4, three ^0.182.0, leva ^0.9.35, lucide-react ^0.474.0, @radix-ui/react-navigation-menu ^1.2.5, devDeps: @types/three ^0.182.0",
+        "experiment dependencies: @react-three/fiber ^9.5.0, @react-three/drei ^10.7.7, three ^0.172.0, leva ^0.9.35, lucide-react ^0.474.0, @radix-ui/react-navigation-menu ^1.2.5, devDeps: @types/three ^0.182.0",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-002",
+      "title": "Extract layer files from templates",
+      "description": "As a CLI maintainer, I need the unique files from each template extracted into a layers/ directory so they can be overlaid on next-starter.",
+      "acceptanceCriteria": [
+        "Create layers/webgl/app/page.tsx copied from template/webgl/app/page.tsx (the one that imports DynamicCanvas)",
+        "Create layers/webgl/components/webgl/canvas/dynamic.tsx from template/webgl/components/webgl/canvas/dynamic.tsx",
+        "Create layers/webgl/components/webgl/canvas/index.tsx from template/webgl/components/webgl/canvas/index.tsx",
+        "Create layers/webgl/components/webgl/components/scene/index.tsx from template/webgl/components/webgl/components/scene/index.tsx",
+        "Create layers/experiment/components/layout/header/index.tsx from template/experiment/components/layout/header/index.tsx",
+        "Create layers/experiment/components/layout/navigation-menu.tsx from template/experiment/components/layout/navigation-menu.tsx",
+        "Create layers/experiment/lib/constats.ts from template/experiment/lib/constats.ts",
+        "Create layers/experiment/lib/utils/cn.ts from template/experiment/lib/utils/cn.ts",
+        "Create empty layers/webgpu/ directory with a .gitkeep file",
+        "All copied files are byte-for-byte identical to their template source files",
+        "Typecheck passes"
+      ],
+      "priority": 2,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-003",
+      "title": "Implement layer injection function",
+      "description": "As the CLI system, I need to overlay layer-specific files on top of the next-starter base so that WebGL/WebGPU/Experiment projects get their unique components.",
+      "acceptanceCriteria": [
+        "Add injectLayer(targetDir, layer, spinner) function to src/mergers/index.js",
+        "Function resolves layer directory from CLI repo's layers/{type}/ path using __dirname",
+        "Function calls existing detectPathPrefix() to handle src/ directory structure",
+        "Function copies additive files from local layers/ directory (no tiged clone needed)",
+        "Function replaces files listed in replaceFiles config (overwrites base version with overwrite: true)",
+        "Function uses existing transformPath() for path prefix support",
+        "Function returns results object with replaced, copied, skipped, and failed arrays",
+        "When layer is 'default' or not found in config, function returns early with skipped result (no error)",
+        "Extend formatMergeResults() to display replaced entries with checkmark prefix",
+        "Typecheck passes"
+      ],
+      "priority": 3,
+      "passes": true,
+      "notes": "Reuses existing detectPathPrefix() and transformPath() from src/mergers/index.js. Layer files are local (no network request)."
+    },
+    {
+      "id": "US-004",
+      "title": "Change create.js to clone next-starter instead of template",
+      "description": "As a developer using the CLI, I want my project scaffolded from the latest next-starter repo so I always get the most up-to-date base.",
+      "acceptanceCriteria": [
+        "Change tiged source on line 124 of src/commands/create.js from 'github:basementstudio/basement-cli/template/${type}#${branch}' to 'github:basementstudio/next-starter#main'",
+        "Remove the BASEMENT_CLI_BRANCH env var usage for template (keep if used elsewhere)",
+        "Delete bun.lock file after clone if it exists (since dependencies will be modified)",
+        "Update download spinner text to say 'Downloading next-starter from GitHub...' instead of mentioning template type",
+        "Update error/troubleshooting message in catch block to reference basementstudio/next-starter instead of basementstudio/basement-cli/template/{type}",
+        "Typecheck passes"
+      ],
+      "priority": 4,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-005",
+      "title": "Wire layer injection into create flow",
+      "description": "As the CLI system, I need the layer injection step between template download and CMS integration so layers are applied at the right time.",
+      "acceptanceCriteria": [
+        "Add new step between template download (step 3) and CMS integration (step 3.5) in src/commands/create.js",
+        "Layer injection only runs when type !== 'default'",
+        "Import injectLayer and formatMergeResults from src/mergers/index.js",
+        "Show ora spinner with layer name during injection (e.g. 'Applying webgl layer...')",
+        "Display injection results to user using formatMergeResults",
+        "On failure, show warning (not hard error) and continue with project creation",
+        "Typecheck passes"
+      ],
+      "priority": 5,
+      "passes": true,
+      "notes": "Must run BEFORE CMS integration because layers don't modify layout.tsx, and CMS mergers need the base layout intact."
+    },
+    {
+      "id": "US-006",
+      "title": "Config-driven dependency injection in package.json hydration",
+      "description": "As the CLI system, I need package.json hydration to read layer dependencies from LAYER_CONFIG instead of being hardcoded.",
+      "acceptanceCriteria": [
+        "Import getLayerConfig from src/mergers/config.js in create.js",
+        "Read layer dependencies from LAYER_CONFIG and merge into package.json: pkg.dependencies = { ...pkg.dependencies, ...layerConfig.dependencies }",
+        "Also merge devDependencies from layer config",
+        "CMS dependency injection (Sanity/BaseHub) still works unchanged",
+        "Animation library injection (GSAP/Framer Motion) still works unchanged",
+        "Simplify package.json handling: next-starter uses package.json directly (not package.template.json), remove the rename logic",
+        "Project name still set to user-provided name, version still set to 0.1.0",
+        "Typecheck passes"
+      ],
+      "priority": 6,
+      "passes": true,
+      "notes": "next-starter uses package.json not package.template.json, so the existsSync check for package.template.json can be simplified."
+    },
+    {
+      "id": "US-007",
+      "title": "Delete template directory",
+      "description": "As a CLI maintainer, I want the template/ directory removed so there's no duplicated code to maintain.",
+      "acceptanceCriteria": [
+        "Delete template/default/ directory and all contents",
+        "Delete template/webgl/ directory and all contents",
+        "Delete template/webgpu/ directory and all contents",
+        "Delete template/experiment/ directory and all contents",
+        "Grep source code for any remaining references to 'template/' paths and remove them",
+        "Grep source code for any remaining references to 'basementstudio/basement-cli/template/' and remove them",
+        "Typecheck passes"
+      ],
+      "priority": 7,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-008",
+      "title": "End-to-end verification of all template types",
+      "description": "As a CLI maintainer, I need to verify all template + CMS + animation combinations produce working projects.",
+      "acceptanceCriteria": [
+        "Run npm link to install CLI locally",
+        "Run: basement -c test-default -d -no-cms -no-animation -claude -no-hooks — project creates successfully",
+        "Run: basement -c test-webgl -webgl -no-cms -no-animation -claude -no-hooks — project has R3F components in components/webgl/",
+        "Run: basement -c test-webgpu -webgpu -no-cms -no-animation -claude -no-hooks — project has WebGPU deps in package.json",
+        "Run: basement -c test-experiment -exp -no-cms -no-animation -claude -no-hooks — project has custom header with NavigationMenu",
+        "Run: basement -c test-sanity -webgl -sanity -gsap -claude -no-hooks — project has CMS + animation + layer deps",
+        "All generated projects pass bun install without errors",
+        "Typecheck passes"
+      ],
+      "priority": 8,
+      "passes": true,
+      "notes": "This is the final validation step. Each test project should be cleaned up after verification."
+    }
+  ]
+}

package/tasks/archive/2026-02-09-next-starter-dynamic-layers/progress.txt

@@ -0,0 +1,115 @@
+## Codebase Patterns
+- This is a plain JS (ESM) CLI project - no TypeScript, no typecheck command. "Typecheck passes" = no syntax errors.
+- Config pattern: export const CONFIG object + getXConfig(name) helper that returns config or null
+- src/mergers/config.js holds all configuration (CMS_CONFIG, LAYER_CONFIG)
+- src/mergers/index.js holds injection/merge logic (injectIntegration for CMS, injectLayer for layers)
+- src/commands/create.js is the main CLI flow
+- next-starter uses package.json directly (no template rename needed)
+- Layer files are local (in layers/ directory), CMS integration files are remote (fetched via tiged)
+- ESM requires __dirname workaround: `path.dirname(fileURLToPath(import.meta.url))`
+- CLI binary is basement (defined in package.json bin field)
+- Dependency injection order in create.js: layer deps → CMS deps → animation deps
+
+---
+
+## 2026-02-09 - US-001
+- Implemented LAYER_CONFIG export with webgl, webgpu, experiment entries
+- Added getLayerConfig() helper function
+- Each layer config has: replaceFiles, additivePaths, dependencies, devDependencies
+- webgpu is deps-only (empty replaceFiles and additivePaths)
+- Files changed: src/mergers/config.js
+- **Learnings for future iterations:**
+  - The CLI project is plain JS ESM, verified by running `node --input-type=module -e "import {...}"`
+  - Config pattern follows existing CMS_CONFIG style - object + getter helper
+  - experiment uses three ^0.172.0 (not ^0.182.0 like webgl/webgpu) per PRD
+---
+
+## 2026-02-09 - US-002
+- Created layers/webgl/ with app/page.tsx and 3 webgl component files from template/webgl/
+- Created layers/experiment/ with header, navigation-menu, constats.ts, cn.ts from template/experiment/
+- Created layers/webgpu/.gitkeep (empty layer, deps-only)
+- Verified all files are byte-for-byte identical using diff
+- Files changed: 9 new files in layers/
+- **Learnings for future iterations:**
+  - Layer files are local to CLI repo (no network clone needed, unlike CMS integrations)
+  - webgl is the only layer with a different app/page.tsx (imports DynamicCanvas)
+  - experiment has its own header and navigation-menu components
+---
+
+## 2026-02-09 - US-003
+- Added injectLayer(targetDir, layer, spinner) function to src/mergers/index.js
+- Uses __dirname (via import.meta.url + fileURLToPath) to resolve layers/ directory
+- Reuses detectPathPrefix() and transformPath() for src/ directory support
+- Handles replaceFiles (overwrite: true) and additivePaths (overwrite: false) separately
+- Returns results with replaced, copied, skipped, failed arrays
+- Extended formatMergeResults() with defensive optional chaining for replaced/merged/copied/etc
+- Files changed: src/mergers/index.js
+- **Learnings for future iterations:**
+  - ESM doesn't have __dirname, must use: `const __dirname = path.dirname(fileURLToPath(import.meta.url))`
+  - Layer injection is purely local file copy (no network), unlike CMS integration which uses tiged
+  - formatMergeResults now handles both CMS results (merged) and layer results (replaced) gracefully
+---
+
+## 2026-02-09 - US-004
+- Changed tiged source from basement/template/${type} to basementstudio/next-starter#main
+- Removed BASEMENT_CLI_BRANCH env var usage (was only used for template, not used elsewhere)
+- Added bun.lock deletion after clone (since deps will be modified by layers/CMS/animation)
+- Updated spinner text to "Downloading next-starter from GitHub..."
+- Updated troubleshooting message to reference basementstudio/next-starter
+- Kept dotenv import as it may be used by merger modules
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - dotenv is loaded in create.js but env vars are only used in merger modules (check-integration-merger.js)
+  - bun.lock must be deleted before modifying package.json deps, otherwise bun install may conflict
+---
+
+## 2026-02-09 - US-005
+- Added layer injection step (3.2) between template download and CMS integration (3.5)
+- Layer injection only runs when type !== 'default'
+- Uses dynamic import for injectLayer and formatMergeResults from mergers/index.js
+- Shows ora spinner with layer name during injection
+- On failure, shows warning and continues (not a hard error)
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - Layer injection MUST happen before CMS integration to keep layout.tsx intact for CMS mergers
+  - Uses dynamic import (await import) consistent with existing CMS integration pattern
+---
+
+## 2026-02-09 - US-006
+- Imported getLayerConfig from src/mergers/config.js at top of create.js
+- Layer deps injected from LAYER_CONFIG before CMS and animation deps
+- Simplified package.json handling: removed package.template.json logic (next-starter uses package.json directly)
+- CMS and animation dependency injection unchanged
+- Project name and version still set correctly
+- Files changed: src/commands/create.js
+- **Learnings for future iterations:**
+  - Dependency injection order matters: layer deps first, then CMS, then animation (later ones override earlier)
+  - next-starter uses package.json directly, no need for package.template.json rename logic
+---
+
+## 2026-02-09 - US-007
+- Deleted template/default/, template/webgl/, template/webgpu/, template/experiment/ directories
+- Removed entire template/ directory (281 files, -27,778 lines)
+- Verified no remaining references to template/ paths in source code (src/)
+- Updated CLAUDE.md to reflect new architecture (layers/ instead of template/)
+- Files changed: template/ deleted, CLAUDE.md updated
+- **Learnings for future iterations:**
+  - CLAUDE.md should be kept in sync with architecture changes
+  - Only documentation files (CLAUDE.md, PRD) had remaining references to template/ paths, not source code
+---
+
+## 2026-02-09 - US-008
+- Installed CLI locally via npm link
+- E2E test results (all passed):
+  - test-default: Created successfully, name=test-default, version=0.1.0, has next dep, no R3F deps
+  - test-webgl: Created with layer applied (replaced page.tsx, added 3 webgl components), R3F ^9.5.0, three ^0.182.0, @types/three ^0.182.0
+  - test-webgpu: Created with deps-only layer, R3F 10.0.0-alpha.2, drei ^11.0.0-alpha.4, lucide-react ^0.474.0
+  - test-experiment: Created with layer (header, navigation-menu, constats.ts, cn.ts), three ^0.172.0
+  - test-sanity: Combined webgl + sanity + gsap - all deps present (R3F, next-sanity, sanity, gsap, @gsap/react, sanity:extract script)
+- All 4 projects pass bun install without errors
+- CLI command is basement (not basement-starter as PRD mentions)
+- **Learnings for future iterations:**
+  - Skills installation may fail without network (bunx skills add), but it's non-blocking
+  - The sanity integration triggers an interactive Sanity setup prompt after project creation
+  - bun install correctly resolves all dependency versions including alpha packages
+---

package/tasks/prd-project-restructure.md

@@ -0,0 +1,375 @@
+# PRD: Project Restructure — Separation of CLI and Templates
+
+## Introduction
+
+The `@basementstudio/cli` project has grown organically into a monolithic structure where CLI logic, templates, integrations, mergers, and hooks are tangled together in a flat directory with fragmented configuration. This restructure separates the project into a clean monorepo with two primary packages: the CLI tool (`packages/cli`) and the template scaffolder (`packages/create-basement-app`), following the pattern established by [basementstudio/xmcp](https://github.com/basementstudio/xmcp).
+
+### Problem
+
+1. **No separation of concerns** — CLI routing, prompting, template downloading, file merging, package hydration, agent setup, and hook copying all live in a single 415-line function (`create.js`)
+2. **Fragmented configuration** — Layer deps live in `config.js`, CMS deps are hardcoded in `create.js`, animation deps are hardcoded elsewhere. No single source of truth.
+3. **Templates are not standalone** — You can't preview, test, or lint a template in isolation. They're partial overlays that only make sense after being merged onto `next-starter` at runtime.
+4. **Hardcoded paths everywhere** — `../../layers`, `../../template-hooks`, `../../.env` — brittle references that break when you move files.
+5. **Duplicate/dead code** — Both `chalk` and `picocolors`, unused `inquirer` dependency, orphaned `next-config-merger.js`.
+6. **Hard to contribute** — A designer or dev who wants to update a template must understand the merger system, config files, and the full CLI pipeline.
+
+### Solution
+
+Move to a **bun workspaces monorepo** with full standalone templates. Each template is a complete, working Next.js project. The CLI simply copies the right template and applies optional integrations on top.
+
+## Goals
+
+- Each folder has a single responsibility and a clear owner
+- Templates are complete, standalone Next.js projects that can be previewed and tested independently
+- CLI code is isolated from template content — modifying one doesn't require understanding the other
+- All dependency/script declarations for each integration type live in one config file (single source of truth)
+- Contributors can update templates by editing familiar Next.js files, no knowledge of merger internals needed
+- Dead code, duplicate libraries, and orphaned files are eliminated
+- The merger system is refactored with proper validation and error handling
+
+## User Stories
+
+### US-001: Set up bun workspaces monorepo structure
+**Description:** As a maintainer, I want the project organized as a bun workspaces monorepo so that packages are properly isolated with clear boundaries.
+
+**Acceptance Criteria:**
+- [ ] Root `package.json` with `"workspaces": ["packages/*"]` configuration
+- [ ] Root `biome.json` shared across all packages
+- [ ] `packages/cli/` — CLI entry point and command routing
+- [ ] `packages/create-basement-app/` — Templates, integrations, hooks, and scaffolding logic
+- [ ] Each package has its own `package.json` with correct name, version, bin, and dependencies
+- [ ] `bun install` at root installs all workspace dependencies
+- [ ] Existing `.changeset/`, `.github/workflows/`, and release infrastructure updated for workspaces
+- [ ] Typecheck passes
+
+### US-002: Create standalone templates in create-basement-app
+**Description:** As a contributor, I want each template (default, webgl, webgpu, experiment) to be a complete, self-contained Next.js project so I can preview, lint, and test it without running the full CLI.
+
+**Acceptance Criteria:**
+- [ ] `packages/create-basement-app/templates/default/` — Full Next.js project (cloned from next-starter baseline)
+- [ ] `packages/create-basement-app/templates/webgl/` — Full Next.js project with R3F canvas, scene components, and all WebGL deps in its `package.json`
+- [ ] `packages/create-basement-app/templates/webgpu/` — Full Next.js project with WebGPU setup and alpha R3F deps
+- [ ] `packages/create-basement-app/templates/experiment/` — Full Next.js project with experiment navigation, header, and constants
+- [ ] Each template has a valid `package.json` with all its dependencies (no external hydration needed)
+- [ ] Each template can be installed and run independently (`cd templates/webgl && bun install && bun dev`)
+- [ ] The old `layers/` directory and overlay-based injection for templates is removed
+- [ ] `_gitignore` convention used (renamed to `.gitignore` during scaffolding, since npm strips dotfiles)
+
+### US-003: Move integrations into create-basement-app
+**Description:** As a maintainer, I want CMS integrations co-located with templates inside `create-basement-app` so the scaffolding package is self-contained.
+
+**Acceptance Criteria:**
+- [ ] `packages/create-basement-app/integrations/sanity/` — All Sanity integration files (currently downloaded from remote branch)
+- [ ] `packages/create-basement-app/integrations/basehub/` — All BaseHub integration files
+- [ ] Integration config (file paths, merge rules, dependencies, scripts) lives in a single `integrations/{cms}/config.js` manifest
+- [ ] No more runtime downloading from remote GitHub branches via tiged for integrations
+- [ ] Merger functions co-located with their integration: `integrations/sanity/mergers/`
+- [ ] CMS dependencies and scripts declared in the integration config, not hardcoded in the create command
+- [ ] Typecheck passes
+
+### US-004: Move template-hooks into create-basement-app
+**Description:** As a maintainer, I want optional hooks co-located with the scaffolding package as copyable files.
+
+**Acceptance Criteria:**
+- [ ] `packages/create-basement-app/template-hooks/` contains all four hooks
+- [ ] Hook discovery (for the interactive prompt) reads from this co-located directory
+- [ ] Hook copying uses the co-located path, no `../../` navigation
+- [ ] Hooks with external dependencies (`use-battery.ts` -> `lodash-es`, `use-device-perf.ts` -> `detect-gpu`, `react-device-detect`, `zustand`) have their deps declared in a manifest or config so the scaffolder can inject them into the generated project's `package.json`
+- [ ] Typecheck passes
+
+### US-005: Extract CLI package with clean command routing
+**Description:** As a developer, I want the CLI package to only handle argument parsing and command routing, delegating all scaffolding logic to `create-basement-app`.
+
+**Acceptance Criteria:**
+- [ ] `packages/cli/bin/index.js` — Entry point with `"basement"` bin command
+- [ ] `packages/cli/src/commands/` — Command modules that import from `create-basement-app`
+- [ ] `packages/cli/` has `create-basement-app` as a workspace dependency
+- [ ] Argument parsing is decoupled from hardcoded template/CMS/animation names — reads available options from `create-basement-app` exports
+- [ ] Single color library (`picocolors`) — remove `chalk`
+- [ ] Remove unused `inquirer` dependency
+- [ ] The `worktree` command stays in the CLI package (it's a dev tool, not scaffolding)
+- [ ] Typecheck passes
+
+### US-006: Refactor the create pipeline into composable steps
+**Description:** As a maintainer, I want the project creation pipeline broken into small, testable, single-purpose functions instead of one 415-line monolith.
+
+**Acceptance Criteria:**
+- [ ] Scaffolding logic lives in `packages/create-basement-app/src/` with separate modules:
+  - `copy-template.ts` — Copy the selected template to target directory
+  - `apply-integration.ts` — Apply CMS integration (merge + additive files)
+  - `hydrate-package.ts` — Inject dependencies, scripts, and metadata into package.json
+  - `setup-agent.ts` — Agent skills installation and MCP setup
+  - `copy-hooks.ts` — Copy selected hooks and inject their dependencies
+  - `setup-sanity.ts` — Automated Sanity project creation (moved from CLI)
+- [ ] Each module is independently importable and testable
+- [ ] The CLI's `create` command orchestrates these modules in sequence
+- [ ] The `add-integration` command reuses `apply-integration.ts` instead of duplicating logic
+- [ ] Typecheck passes
+
+### US-007: Centralize all dependency and script declarations
+**Description:** As a maintainer, I want a single source of truth for each integration's dependencies and scripts so I never have to update multiple files when a version changes.
+
+**Acceptance Criteria:**
+- [ ] Each integration (sanity, basehub) has a `config.js` manifest declaring: `dependencies`, `devDependencies`, `scripts`, `mergeFiles`, `additivePaths`
+- [ ] Animation library configs (`gsap`, `motion`) declared in a `packages/create-basement-app/src/configs/animations.js` manifest
+- [ ] Template configs (if any template needs runtime dep injection beyond what's in its own `package.json`) live alongside the template
+- [ ] `create.js` reads ALL dependency info from config manifests — zero hardcoded version strings in the pipeline
+- [ ] Typecheck passes
+
+### US-008: Clean up dead code and duplicate dependencies
+**Description:** As a maintainer, I want all unused code, duplicate libraries, and orphaned files removed.
+
+**Acceptance Criteria:**
+- [ ] Remove `inquirer` from dependencies (unused — `prompts` is used instead)
+- [ ] Remove `chalk` — standardize on `picocolors` everywhere
+- [ ] Remove or integrate orphaned `next-config-merger.js` (defined but never registered in CMS_MERGERS)
+- [ ] Remove `dotenv` if only used for CLI development (move to devDependencies or remove entirely)
+- [ ] Remove empty `layers/webgpu/.gitkeep` and the entire old `layers/` directory
+- [ ] Remove the old `integrations/` reference directory from root (files now live in create-basement-app)
+- [ ] Remove old `template-hooks/` from root
+- [ ] Verify no dead imports or unreachable code paths remain
+- [ ] Typecheck passes
+
+### US-009: Migrate to TypeScript for CLI and scaffolder
+**Description:** As a developer, I want the CLI and scaffolding code in TypeScript so we get type safety, better IDE support, and catch errors at build time.
+
+**Acceptance Criteria:**
+- [ ] `packages/cli/src/` — All files in TypeScript with `strict: true`
+- [ ] `packages/create-basement-app/src/` — All files in TypeScript with `strict: true`
+- [ ] `tsconfig.json` in each package with proper `paths`, `outDir`, `rootDir`
+- [ ] Config files typed with proper interfaces (`LayerConfig`, `CmsConfig`, `AnimationConfig`)
+- [ ] No `any` types — use `unknown` and narrow
+- [ ] Build step compiles TS to JS for the published package
+- [ ] Typecheck passes with zero errors
+
+### US-010: Add validation for config-filesystem consistency
+**Description:** As a maintainer, I want the scaffolder to validate that config manifests match the actual filesystem so mismatches are caught early instead of failing silently at runtime.
+
+**Acceptance Criteria:**
+- [ ] On startup (or as a test), validate that every path in `additivePaths` and `mergeFiles` exists in the corresponding template/integration directory
+- [ ] Validate that every merger function referenced in config has a corresponding implementation
+- [ ] Clear error messages when validation fails: "Integration sanity references file X but it doesn't exist in integrations/sanity/"
+- [ ] Validation runs as part of CI
+- [ ] Typecheck passes
+
+## Functional Requirements
+
+- FR-1: The project MUST be a bun workspaces monorepo with `packages/cli` and `packages/create-basement-app`
+- FR-2: The `basement` CLI command MUST work identically to the current version after restructuring (same flags, same prompts, same output)
+- FR-3: Templates MUST be full standalone Next.js projects that can be independently installed and run
+- FR-4: CMS integrations MUST be local files in `create-basement-app/integrations/`, not downloaded from remote branches at runtime
+- FR-5: All dependency version declarations MUST live in config manifests, not hardcoded in pipeline code
+- FR-6: The `add-integration` command MUST share implementation with the `create` command's integration step (no duplication)
+- FR-7: The CLI package MUST depend on `create-basement-app` as a workspace dependency for all scaffolding operations
+- FR-8: Template file paths MUST NOT use relative `../../` navigation — use proper package resolution or `__dirname`-based paths relative to the package root
+- FR-9: The `worktree` command MUST remain in the CLI package (not in create-basement-app)
+- FR-10: The changeset/release pipeline MUST be updated to publish both packages independently
+- FR-11: All source code MUST be TypeScript with `strict: true`
+
+## Non-Goals (Out of Scope)
+
+- Changing the generated project's structure or conventions (output remains identical)
+- Adding new templates, integrations, or hooks (only restructuring existing ones)
+- Migrating from `prompts` to another prompt library
+- Adding a test suite (beyond config validation — full test coverage is a separate effort)
+- Changing the CLI command name from `basement`
+- Moving to a different monorepo tool (no Turborepo, just bun workspaces)
+- Rewriting mergers to use proper AST parsing (regex-based mergers stay, just reorganized)
+- Publishing templates as separate npm packages
+
+## Target Directory Structure
+
+```
+basement-starter-cli/
+├── package.json                          # Root: workspaces config, shared scripts
+├── biome.json                            # Shared linting/formatting
+├── bun.lock
+├── .changeset/                           # Changeset config (updated for workspaces)
+├── .github/workflows/release.yml         # Updated for multi-package publish
+│
+├── packages/
+│   ├── cli/                              # @basementstudio/cli
+│   │   ├── package.json                  # bin: "basement", depends on create-basement-app
+│   │   ├── tsconfig.json
+│   │   ├── bin/
+│   │   │   └── index.js                  # CLI entry point (thin loader → dist/)
+│   │   └── src/
+│   │       ├── index.ts                  # Arg parsing + command routing
+│   │       ├── commands/
+│   │       │   ├── create.ts             # Orchestrates create-basement-app modules
+│   │       │   ├── add-integration.ts    # Reuses apply-integration from create-basement-app
+│   │       │   └── worktree.ts           # Git worktree management (stays here)
+│   │       └── utils/
+│   │           └── display.ts            # Banner, help text, success messages
+│   │
+│   └── create-basement-app/              # @basementstudio/create-basement-app
+│       ├── package.json                  # Standalone scaffolding package
+│       ├── tsconfig.json
+│       ├── src/
+│       │   ├── index.ts                  # Public API: exports all scaffolding functions
+│       │   ├── copy-template.ts          # Copy selected template to target dir
+│       │   ├── apply-integration.ts      # Apply CMS integration (merge + copy)
+│       │   ├── hydrate-package.ts        # Inject deps, scripts, metadata into package.json
+│       │   ├── setup-agent.ts            # Agent skills + MCP registration
+│       │   ├── setup-sanity.ts           # Automated Sanity project/token creation
+│       │   ├── copy-hooks.ts             # Copy selected hooks + inject their deps
+│       │   ├── utils/
+│       │   │   ├── paths.ts              # Path resolution, src/ prefix detection
+│       │   │   └── merge-utils.ts        # Shared merge utilities
+│       │   └── configs/
+│       │       ├── animations.ts         # GSAP and Motion dep declarations
+│       │       └── agents.ts             # Agent skill repos per template type
+│       │
+│       ├── templates/                    # Full standalone Next.js projects
+│       │   ├── default/                  # Base next-starter
+│       │   │   ├── package.json
+│       │   │   ├── _gitignore
+│       │   │   ├── app/
+│       │   │   ├── components/
+│       │   │   ├── lib/
+│       │   │   └── ...
+│       │   ├── webgl/                    # next-starter + R3F canvas/scene
+│       │   │   ├── package.json          # Includes @react-three/fiber, three, etc.
+│       │   │   ├── _gitignore
+│       │   │   ├── app/page.tsx          # WebGL page (not an overlay — the actual file)
+│       │   │   ├── components/webgl/     # Canvas + scene components
+│       │   │   └── ...
+│       │   ├── webgpu/                   # next-starter + WebGPU setup
+│       │   │   ├── package.json          # Includes alpha R3F, WebGPU deps
+│       │   │   └── ...
+│       │   └── experiment/               # next-starter + experiment nav
+│       │       ├── package.json          # Includes experiment deps
+│       │       ├── components/layout/    # Experiment header + nav menu
+│       │       ├── lib/constants.ts
+│       │       └── ...
+│       │
+│       ├── integrations/                 # CMS integrations (applied on top of any template)
+│       │   ├── sanity/
+│       │   │   ├── config.ts             # Single source of truth: deps, scripts, paths, mergeFiles
+│       │   │   ├── files/                # All Sanity files to copy/merge
+│       │   │   │   ├── app/
+│       │   │   │   │   ├── layout.tsx    # Integration version (for merging)
+│       │   │   │   │   ├── sitemap.ts
+│       │   │   │   │   ├── api/
+│       │   │   │   │   └── studio/
+│       │   │   │   ├── components/ui/sanity-image/
+│       │   │   │   └── lib/integrations/sanity/
+│       │   │   └── mergers/              # Sanity-specific merge logic
+│       │   │       ├── layout-merger.ts
+│       │   │       ├── sitemap-merger.ts
+│       │   │       └── check-integration-merger.ts
+│       │   └── basehub/
+│       │       ├── config.ts
+│       │       └── files/
+│       │           └── lib/integrations/basehub/
+│       │
+│       ├── template-hooks/               # Optional hooks (copied during scaffolding)
+│       │   ├── config.ts                 # Hook metadata: name, file, external deps
+│       │   ├── use-battery.ts
+│       │   ├── use-device-perf.ts
+│       │   ├── use-intersection-observer.ts
+│       │   └── use-media.ts
+│       │
+│       └── plugins/                      # Biome Grit lint rules
+│           ├── no-anchor-element.grit
+│           ├── no-relative-parent-imports.grit
+│           └── no-unnecessary-forwardref.grit
+```
+
+## Technical Considerations
+
+### Bun Workspaces Setup
+
+Root `package.json`:
+```json
+{
+  "name": "basement-starter-cli",
+  "private": true,
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "bun run --filter '*' build",
+    "typecheck": "bun run --filter '*' typecheck",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write ."
+  }
+}
+```
+
+### Package Dependencies
+
+- `packages/cli` depends on `packages/create-basement-app` via workspace protocol: `"@basementstudio/create-basement-app": "workspace:*"`
+- `packages/create-basement-app` is independently usable: `npx @basementstudio/create-basement-app`
+- Shared dev dependencies (biome, changesets) live at the root
+
+### Template Creation Strategy
+
+To create the four standalone templates:
+
+1. Clone `basementstudio/next-starter#main` as the `default` template
+2. For `webgl`: clone default, apply the current WebGL layer files, add R3F deps to its `package.json`
+3. For `webgpu`: clone default, add WebGPU/alpha deps to its `package.json`, add any WebGPU-specific files
+4. For `experiment`: clone default, apply experiment layer files, add experiment deps
+
+After initial creation, each template is maintained independently — no more runtime overlay system for templates.
+
+### Integration Application (Preserved)
+
+CMS integrations still use the merge approach because they cross-cut all four templates. The difference:
+- **Before:** Downloaded from remote GitHub branches at runtime via tiged
+- **After:** Local files in `create-basement-app/integrations/{cms}/files/`, with merger functions co-located in `integrations/{cms}/mergers/`
+
+### Migration Path
+
+This is a breaking change for the internal structure but NOT for end users. The `basement` CLI command, its flags, prompts, and generated output must remain identical. The migration should:
+
+1. Create the new structure alongside the old one
+2. Move files incrementally
+3. Verify the CLI produces identical output before removing old files
+4. Update changeset config for workspace-aware publishing
+
+### Config Manifest Format
+
+Each integration config (`integrations/{cms}/config.ts`) should follow this shape:
+
+```typescript
+interface IntegrationConfig {
+  name: string
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+  scripts: Record<string, string>
+  additivePaths: string[]           // Files to copy directly
+  mergeFiles: {                     // Files requiring smart merge
+    path: string
+    merger: () => Promise<MergerFn>
+  }[]
+}
+```
+
+Similarly, `template-hooks/config.ts`:
+
+```typescript
+interface HookConfig {
+  name: string          // Display name for the prompt
+  file: string          // Filename
+  dependencies: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+```
+
+## Success Metrics
+
+- The `basement` CLI produces byte-identical project output before and after the restructure (verified by diffing generated projects)
+- Each template can be independently installed and run (`cd templates/webgl && bun install && bun dev`)
+- Adding a new template requires creating ONE new directory in `templates/` — no config files, no merger code, no CLI changes
+- Adding a new CMS integration requires creating ONE new directory in `integrations/` with a `config.ts` and `files/` — no changes to CLI or pipeline code
+- Zero hardcoded dependency versions in pipeline code (all from config manifests)
+- Config-filesystem validation catches 100% of mismatches in CI
+- TypeScript strict mode with zero errors across both packages
+
+## Open Questions
+
+1. **Should `create-basement-app` also be directly invocable via `npx @basementstudio/create-basement-app`?** (Like `create-xmcp-app` is.) This would mean it needs its own interactive prompts, not just exported functions. The xmcp pattern supports this.
+2. **How should templates be kept in sync with upstream `next-starter` changes?** With standalone templates, each one needs to be individually updated when the base starter evolves. Should there be a script or CI job that diffs templates against `next-starter` and flags drift?
+3. **Should the `next-config-merger.js` be integrated or removed?** It's currently orphaned (defined but never called). If Sanity's `next.config.ts` changes are needed, the merger should be registered. If not, it should be deleted.
+4. **Should plugins (Biome Grit rules) live in `create-basement-app` or at the root?** They're copied into generated projects but also used to lint this repo itself.
+5. **Version strategy for workspaces** — Should both packages share a version number or be independently versioned? Independent versioning is more flexible but harder to coordinate.