bsmnt 0.1.2 → 0.1.3

package/tasks/prd-next-starter-dynamic-layers.md

@@ -1,184 +0,0 @@
-# PRD: Replace Static Templates with next-starter + Dynamic Layers
-
-## Introduction
-
-The CLI currently maintains 4 complete, nearly-identical template copies (default, webgl, webgpu, experiment). Every bug fix, dependency bump, or structural change must be applied 4 times. The `default` template is essentially a stale snapshot of the `basementstudio/next-starter` repo.
-
-This feature replaces the static templates with a single `next-starter` clone as the base, then dynamically overlays technology-specific files and dependencies using a "layers" system — reusing the same smart-merge pattern already proven by the CMS integration system.
-
-## Goals
-
-- Eliminate template duplication by using `basementstudio/next-starter` as the single source of truth
-- Maintain the same user-facing CLI experience (same 4 template choices, same prompt flow)
-- Create a `layers/` system for technology-specific additions (WebGL, WebGPU, Experiment)
-- Reuse the existing merger infrastructure (`src/mergers/`) for layer injection
-- Delete the entire `template/` directory from the repo
-
-## User Stories
-
-### US-001: Clone next-starter as base template
-**Description:** As a developer using the CLI, I want my project to be scaffolded from the latest `next-starter` repo so that I always get the most up-to-date base configuration.
-
-**Acceptance Criteria:**
-- [ ] `create.js` clones from `github:basementstudio/next-starter#main` instead of `github:basementstudio/basement/template/{type}#main`
-- [ ] Selecting "Default" template produces a project identical to cloning next-starter directly
-- [ ] `bun.lock` is deleted after clone (since dependencies will be modified)
-- [ ] Download spinner text updated to reflect new source
-- [ ] Error/troubleshooting messages updated to reference `basementstudio/next-starter`
-- [ ] Typecheck passes
-
-### US-002: 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.
-
-**Acceptance Criteria:**
-- [ ] `LAYER_CONFIG` export added to `src/mergers/config.js` alongside existing `CMS_CONFIG`
-- [ ] Each layer config defines: `replaceFiles`, `additivePaths`, `dependencies`, `devDependencies`
-- [ ] `getLayerConfig(layer)` helper function exported
-- [ ] Config contains entries for `webgl`, `webgpu`, and `experiment`
-- [ ] `webgpu` is a deps-only layer (empty `replaceFiles` and `additivePaths`)
-- [ ] Dependencies match what's currently in each template's `package.template.json`
-
-### US-003: 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.
-
-**Acceptance Criteria:**
-- [ ] `injectLayer(targetDir, layer, spinner)` function added to `src/mergers/index.js`
-- [ ] Function copies additive files from local `layers/{type}/` directory (no tiged needed)
-- [ ] Function replaces files listed in `replaceFiles` (overwrites base version)
-- [ ] Function uses existing `detectPathPrefix()` and `transformPath()` for `src/` directory support
-- [ ] Function returns results object with `replaced`, `copied`, `skipped`, `failed` arrays
-- [ ] `formatMergeResults()` extended to handle `replaced` entries
-- [ ] Skipped layers (type === 'default') produce no errors
-
-### US-004: 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.
-
-**Acceptance Criteria:**
-- [ ] `layers/webgl/app/page.tsx` contains the WebGL-specific page (DynamicCanvas import)
-- [ ] `layers/webgl/components/webgl/canvas/dynamic.tsx` exists (from template/webgl)
-- [ ] `layers/webgl/components/webgl/canvas/index.tsx` exists (from template/webgl)
-- [ ] `layers/webgl/components/webgl/components/scene/index.tsx` exists (from template/webgl)
-- [ ] `layers/experiment/components/layout/header/index.tsx` exists (custom header with NavigationMenu)
-- [ ] `layers/experiment/components/layout/navigation-menu.tsx` exists
-- [ ] `layers/experiment/lib/constats.ts` exists
-- [ ] `layers/experiment/lib/utils/cn.ts` exists
-- [ ] `layers/webgpu/` directory exists (empty, deps-only layer)
-- [ ] Files are byte-for-byte identical to their template counterparts
-
-### US-005: Integrate layer injection into create flow
-**Description:** As the CLI system, I need the layer injection step wired into the project creation flow so it runs between template download and CMS integration.
-
-**Acceptance Criteria:**
-- [ ] Layer injection runs after next-starter clone, before CMS integration
-- [ ] Layer injection only runs when `type !== 'default'`
-- [ ] Progress spinner shows layer name during injection
-- [ ] Injection results displayed to user (files added/replaced)
-- [ ] Failures produce warnings, not hard errors
-- [ ] CMS integration (Sanity) still works correctly after layer injection
-- [ ] Typecheck passes
-
-### US-006: Config-driven dependency injection
-**Description:** As the CLI system, I need package.json hydration to read layer dependencies from config instead of being hardcoded in create.js.
-
-**Acceptance Criteria:**
-- [ ] Layer dependencies read from `LAYER_CONFIG` and merged into `package.json`
-- [ ] CMS dependencies still injected as before (unchanged)
-- [ ] Animation library dependencies still injected as before (unchanged)
-- [ ] `package.template.json` rename logic simplified (next-starter uses `package.json` directly)
-- [ ] Project name and version still set correctly
-- [ ] Typecheck passes
-
-### US-007: Delete template directory
-**Description:** As a CLI maintainer, I want the `template/` directory removed so there's no duplicated code to maintain.
-
-**Acceptance Criteria:**
-- [ ] `template/default/` deleted
-- [ ] `template/webgl/` deleted
-- [ ] `template/webgpu/` deleted
-- [ ] `template/experiment/` deleted
-- [ ] No remaining references to `template/` paths in source code
-- [ ] No remaining references to `basementstudio/basement/template/` in source code
-
-### US-008: End-to-end verification
-**Description:** As a CLI maintainer, I need to verify all template + CMS + animation combinations work correctly.
-
-**Acceptance Criteria:**
-- [ ] `basement -c test-default -d -no-cms -no-animation -claude -no-hooks` produces a working project
-- [ ] `basement -c test-webgl -webgl -no-cms -no-animation -claude -no-hooks` produces a working project with R3F components
-- [ ] `basement -c test-webgpu -webgpu -no-cms -no-animation -claude -no-hooks` produces a working project with WebGPU deps
-- [ ] `basement -c test-experiment -exp -no-cms -no-animation -claude -no-hooks` produces a working project with experiment header
-- [ ] `basement -c test-sanity -webgl -sanity -gsap -claude -no-hooks` produces a working project with CMS + animation + layer
-- [ ] All generated projects pass `bun install && bun dev` (dev server starts)
-
-## Functional Requirements
-
-- FR-1: The CLI must clone `basementstudio/next-starter#main` as the base for all template types
-- FR-2: When `type !== 'default'`, the CLI must apply the corresponding layer from the local `layers/` directory
-- FR-3: Layer injection must copy additive files without overwriting existing files
-- FR-4: Layer injection must replace files listed in `replaceFiles`, overwriting the base version
-- FR-5: Layer injection must respect `src/` directory structure (using existing `detectPathPrefix`)
-- FR-6: Layer dependencies must be merged into `package.json` from `LAYER_CONFIG`
-- FR-7: CMS integration must continue to work identically after layer injection
-- FR-8: The `bun.lock` file must be deleted after cloning next-starter
-- FR-9: The user-facing prompt flow must remain unchanged (same 4 template choices)
-- FR-10: The `template/` directory must be deleted from the repository
-
-## Non-Goals
-
-- No multi-layer support (combining WebGL + Experiment) — one layer per project
-- No `add-layer` command for existing projects (only `create` flow)
-- No version pinning UI — always clones latest `main`
-- No changes to the CMS integration system (`src/mergers/` for Sanity/BaseHub)
-- No changes to the hooks, plugins, or agent skills systems
-- No new merger functions for layers (layers use simple copy/replace, not smart merge)
-
-## Technical Considerations
-
-- **Reuse existing infrastructure:** `detectPathPrefix()`, `transformPath()`, and `formatMergeResults()` from `src/mergers/index.js` are already built for this pattern
-- **Layer files are local:** Unlike CMS integrations (cloned via tiged from a remote branch), layer files live in the CLI repo's `layers/` directory. No network request needed.
-- **Application order matters:** Layers run before CMS integration. Layers do NOT modify `layout.tsx`, so the Sanity layout merger continues to work on the unmodified base layout.
-- **Package.json format:** `next-starter` uses `package.json` (not `package.template.json`), simplifying hydration logic.
-
-### Files to Modify
-
-| File | Change Type |
-|------|-------------|
-| `src/mergers/config.js` | Add `LAYER_CONFIG`, `getLayerConfig()` |
-| `src/mergers/index.js` | Add `injectLayer()`, extend `formatMergeResults()` |
-| `src/commands/create.js` | Change tiged source, add layer step, config-driven deps |
-
-### Files to Create
-
-| File | Source |
-|------|--------|
-| `layers/webgl/app/page.tsx` | `template/webgl/app/page.tsx` |
-| `layers/webgl/components/webgl/canvas/dynamic.tsx` | `template/webgl/components/webgl/canvas/dynamic.tsx` |
-| `layers/webgl/components/webgl/canvas/index.tsx` | `template/webgl/components/webgl/canvas/index.tsx` |
-| `layers/webgl/components/webgl/components/scene/index.tsx` | `template/webgl/components/webgl/components/scene/index.tsx` |
-| `layers/experiment/components/layout/header/index.tsx` | `template/experiment/components/layout/header/index.tsx` |
-| `layers/experiment/components/layout/navigation-menu.tsx` | `template/experiment/components/layout/navigation-menu.tsx` |
-| `layers/experiment/lib/constats.ts` | `template/experiment/lib/constats.ts` |
-| `layers/experiment/lib/utils/cn.ts` | `template/experiment/lib/utils/cn.ts` |
-
-### Files/Directories to Delete
-
-| Path | Reason |
-|------|--------|
-| `template/default/` | Replaced by next-starter clone |
-| `template/webgl/` | Replaced by `layers/webgl/` |
-| `template/webgpu/` | Replaced by `layers/webgpu/` |
-| `template/experiment/` | Replaced by `layers/experiment/` |
-
-## Success Metrics
-
-- Template directory eliminated (0 duplicated files to maintain)
-- All 4 template types produce working projects with `bun dev`
-- CMS + layer combinations work correctly
-- CLI prompt flow unchanged (invisible to users)
-- Layer addition requires only: adding files to `layers/`, adding config to `LAYER_CONFIG`
-
-## Open Questions
-
-- Should we add a `--starter-ref` CLI flag in a future iteration for version pinning?
-- If next-starter changes its directory structure significantly, should the CLI validate expected paths before applying layers?
-- Should the `experiment` template's `constats.ts` typo be fixed to `constants.ts`?

package/tasks/prd-project-restructure.md

@@ -1,375 +0,0 @@
-# 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.