bsmnt 0.0.2 → 0.1.1

package/.github/workflows/release.yml

@@ -52,3 +52,5 @@ jobs:
           createGithubReleases: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @basementstudio/cli
 
+## 0.1.1
+
+### Patch Changes
+
+- [#39](https://github.com/basementstudio/basement-cli/pull/39) [`43a5857`](https://github.com/basementstudio/basement-cli/commit/43a5857a33350e344494d85c70a2400ac038695c) Thanks [@BertovDev](https://github.com/BertovDev)! - Add WebGPU template support
+
+- [#33](https://github.com/basementstudio/basement-cli/pull/33) [`9bef7ca`](https://github.com/basementstudio/basement-cli/commit/9bef7ca91ba7fa5928263c76adcc9f6bf77c3143) Thanks [@BertovDev](https://github.com/BertovDev)! - Remove BaseHub CMS integration. BaseHub was a stub that was never fully implemented. Sanity remains as the only CMS option.
+
+- [#36](https://github.com/basementstudio/basement-cli/pull/36) [`ffa1407`](https://github.com/basementstudio/basement-cli/commit/ffa1407c299a50dbf27c4472e3e8d89bf66ed4fa) Thanks [@mustache-dev](https://github.com/mustache-dev)! - One r3f canvas for webgl-webgpu avoids redundancy
+
+## 0.1.0
+
+### Minor Changes
+
+- [#29](https://github.com/basementstudio/basement-cli/pull/29) [`e30588e`](https://github.com/basementstudio/basement-cli/commit/e30588e8609835add7314cbbfc4453ca6d47c195) Thanks [@BertovDev](https://github.com/BertovDev)! - Restructure project into a bun workspaces monorepo with two packages: @basementstudio/cli and @basementstudio/create-basement-app.
+
+  Split CLI entry point and commands into packages/cli
+
+  Move template scaffolding, mergers, integrations, hooks, and plugins into packages/create-basement-app
+
+  Replace remote tiged template downloads with local standalone templates (default, webgl, webgpu, experiment)
+
+  Move Sanity and BaseHub integration files locally with declarative config manifests (config.js)
+
+  Centralize animation and hook dependency configs in create-basement-app/src/configs/
+
+  Update CI workflow and changeset config for workspace publishing
+
+  Remove old root-level bin/, src/, layers/, and dead
+  code
+
 ## 0.0.2
 
 ### Patch Changes

package/CLAUDE.md

@@ -4,14 +4,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is **basement**, a CLI tool that scaffolds Next.js projects with AI agent integration. It creates projects from templates (Default, WebGL, WebGPU, Experiment) and optionally injects CMS integrations (Sanity, BaseHub) and animation libraries (GSAP, Framer Motion).
+This is **basement**, a CLI tool that scaffolds Next.js projects with AI agent integration. It creates projects from templates (Default, WebGL, WebGPU, Experiment) and optionally injects CMS integrations (Sanity) and animation libraries (GSAP, Framer Motion).
 
 ## Commands
 
 ### CLI Development
 ```bash
-npm link              # Install CLI locally for testing
-basement      # Run the CLI
+cd packages/cli && npm link   # Install CLI locally for testing
+basement                      # Run the CLI
 ```
 
 ### Generated Project Commands
@@ -34,28 +34,45 @@ bun sanity:typegen    # Generate TS types from Sanity schema
 
 ## Architecture
 
+This project is a **bun workspaces monorepo** with two packages:
+
 ```
 basement-starter-cli/
-├── bin/index.js              # CLI entry point (basement command)
-├── src/commands/create.js    # Main project creation logic
-├── layers/                   # Technology layer overlays (applied on top of next-starter)
-│   ├── webgl/               # Three.js WebGL components (page, canvas, scene)
-│   ├── webgpu/              # WebGPU (deps-only, .gitkeep)
-│   └── experiment/          # Creative coding (header, navigation, utils)
-├── integrations/             # CMS integrations (injected on top of templates)
-│   └── sanity/              # Sanity CMS files
-├── template-hooks/           # Reusable React hooks (selected during setup)
-└── plugins/                  # Biome linting rules (Grit patterns)
+├── packages/
+│   ├── cli/                              # @basementstudio/cli
+│   │   ├── bin/index.js                  # CLI entry point (basement command)
+│   │   └── src/commands/
+│   │       ├── create.js                 # Main project creation logic
+│   │       ├── add-integration.js        # Add CMS to existing projects
+│   │       ├── worktree.js               # Git worktree management
+│   │       └── setup-sanity.js           # Sanity project provisioning
+│   └── create-basement-app/              # @basementstudio/create-basement-app
+│       ├── src/
+│       │   ├── index.js                  # Barrel exports (public API)
+│       │   ├── mergers/                  # File merge logic (layout, sitemap, config)
+│       │   └── configs/animations.js     # Animation dependency configs
+│       ├── templates/                    # Standalone project templates
+│       │   ├── default/                  # Next.js 16 + React 19 + Tailwind v4
+│       │   ├── webgl/                    # + React Three Fiber + Three.js
+│       │   ├── webgpu/                   # + R3F WebGPU renderer (alpha)
+│       │   └── experiment/               # + Creative coding navigation UI
+│       ├── integrations/                 # CMS integration files + config manifests
+│       │   └── sanity/                   # Sanity files, mergers, config.js
+│       ├── template-hooks/               # Reusable React hooks + config.js
+│       └── plugins/                      # Biome linting rules (Grit patterns)
+├── .changeset/                           # Changeset config for versioning
+├── .github/workflows/release.yml         # CI: publish both packages to npm
+├── biome.json                            # Shared Biome config (root-level)
+└── package.json                          # Workspace root (private, no runtime deps)
 ```
 
-### CLI Flow (src/commands/create.js)
+### CLI Flow (packages/cli/src/commands/create.js)
 1. **Prompts**: Collect project name, template type, CMS, animation library, agent preference, hooks
-2. **Template Download**: Clone from `basementstudio/next-starter#main`
-3. **Layer Injection**: Overlay technology layer files from local `layers/{type}/` directory
-4. **Integration Injection**: Overlay CMS files from `basementstudio/basement/integrations/{cms}#sanity-integration`
-5. **Package Hydration**: Inject layer deps (from LAYER_CONFIG), CMS deps, animation deps, and scripts
-6. **Agent Skills**: Install AI agent skills via `bunx skills add`
-7. **Hooks**: Copy selected hooks from `template-hooks/`
+2. **Template Copy**: Copy standalone template from `create-basement-app/templates/{type}/` (instant, no network)
+3. **Integration Injection**: Merge CMS files from local `create-basement-app/integrations/{cms}/files/`
+4. **Package Hydration**: Inject CMS deps, animation deps, hook deps, and scripts (all from config manifests)
+5. **Agent Skills**: Install AI agent skills via `bunx skills add`
+6. **Hooks**: Copy selected hooks from `create-basement-app/template-hooks/`
 
 ## Generated Project Stack
 
@@ -120,9 +137,10 @@ import { cn } from '@/styles/cn'
 - Root layouts should have ZERO dynamic function calls — encapsulate all dynamic behavior in child components with proper Suspense boundaries
 
 ### Integration File Sources
-- **Technology layers** (`layers/`) are LOCAL files in this CLI repo
-- **CMS integrations** (`integrations/`) are downloaded from REMOTE GitHub branches via `tiged` — the local `integrations/` directory is only a reference copy
-- Files that need to exist in generated projects but aren't on the remote branch must be **generated inline by the merger** (e.g., `SanityStudioGuard` component is written by `layout-merger.js`)
+- **Templates** (`packages/create-basement-app/templates/`) are standalone, complete Next.js projects (no layer overlay needed)
+- **CMS integrations** (`packages/create-basement-app/integrations/`) are LOCAL files with config manifests — no remote GitHub cloning
+- **Config manifests** (`config.js` in each integration) declare deps, scripts, additivePaths, and mergeFiles
+- Files that need to exist in generated projects but aren't in the integration directory must be **generated inline by the merger** (e.g., `SanityStudioGuard` component is written by `layout-merger.js`)
 
 ### Debug Components
 Always gate debug UI (not auto-removed in production):
@@ -132,7 +150,7 @@ Always gate debug UI (not auto-removed in production):
 
 ## Biome Plugins
 
-Custom linting rules in `plugins/`:
+Custom linting rules in `packages/create-basement-app/plugins/`:
 - `no-anchor-element.grit` - Enforce Next.js `<Link>` over `<a>`
 - `no-unnecessary-forwardref.grit` - Prevent forwardRef with React 19
 - `no-relative-parent-imports.grit` - Enforce `@/` alias imports

package/README.md

@@ -1,9 +1,9 @@
-# basement `1.0.0`
+# bsmnt `1.0.0`
 
 Your project starts here. One command to go from zero to a fully configured Next.js project with our stack, CMS, agent skills, and everything wired up.
 
 ```bash
-basement
+bsmnt
 ```
 
 ## What's in 1.0
@@ -40,7 +40,7 @@ Already have a project running? The `--add` command injects Sanity into it. It d
 Real-world validated — this is how we integrated Sanity into the ROX project.
 
 ```bash
-basement --add
+bsmnt --add
 ```
 
 ### Agent skills out of the box
@@ -60,23 +60,45 @@ For Claude Code + Sanity, it also registers the Sanity MCP server automatically.
 Run multiple Claude Code instances on separate branches without conflicts. The CLI manages worktree creation, switching, and cleanup.
 
 ```bash
-basement -wc -b=feature/auth,feature/dashboard,fix/bug-123
+bsmnt -wc -b=feature/auth,feature/dashboard,fix/bug-123
 ```
 
 Creates three isolated worktrees with dependencies auto-installed. Each one is a full working copy your agent can run in independently.
 
 ---
 
+## Project Structure
+
+This is a **bun workspaces monorepo** with two publishable packages:
+
+| Package | npm | Description |
+|---------|-----|-------------|
+| `packages/cli` | `@basementstudio/cli` | CLI binary — prompts, argument parsing, command routing |
+| `packages/create-basement-app` | `@basementstudio/create-basement-app` | Templates, integrations, mergers, hooks, plugins |
+
+```
+packages/
+├── cli/                          # CLI entry point and commands
+│   ├── bin/index.js
+│   └── src/commands/
+└── create-basement-app/          # Scaffolding assets and merge logic
+    ├── templates/{default,webgl,webgpu,experiment}/
+    ├── integrations/{sanity}/
+    ├── template-hooks/
+    └── plugins/
+```
+
 ## (SOON) Installation
 
 ```bash
-npm install -g basement
+npm install -g @basementstudio/cli
 ```
 
 For local development — clone the repo and run:
 
 ```bash
-npm link
+bun install
+cd packages/cli && npm link
 ```
 
 ## Usage
@@ -84,31 +106,31 @@ npm link
 Interactive mode — answer prompts step by step:
 
 ```bash
-basement
+bsmnt
 ```
 
 Skip everything with flags:
 
 ```bash
-basement --create my-app --webgpu --sanity --gsap --claude
+bsmnt --create my-app --webgpu --sanity --gsap --claude
 ```
 
 Add Sanity to an existing project:
 
 ```bash
-basement --add
+bsmnt --add
 ```
 
 Manage worktrees:
 
 ```bash
-basement --worktree
+bsmnt --worktree
 ```
 
 ## All Flags
 
 ```
-basement [mode] [project-name] [flags]
+bsmnt [mode] [project-name] [flags]
 
 Modes:
   -c, --create              Setup a new project
@@ -123,7 +145,6 @@ Templates:
 
 CMS:
   --sanity                  Sanity CMS
-  --basehub                 BaseHub CMS
   --no-cms                  No CMS
 
 Animation:

package/biome.json

@@ -14,6 +14,7 @@
 			"layers/**",
 			"template-hooks/**",
 			"plugins/**",
+			"packages/**",
 			"biome.json",
 			"package.json"
 		]

package/bun.lock

@@ -1,8 +1,9 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
-      "name": "@basementstudio/cli",
+      "name": "bsmnt",
       "dependencies": {
         "chalk": "^5.6.2",
         "dotenv": "^17.2.3",

package/docs/architecture.drawio

@@ -0,0 +1,250 @@
+<mxfile host="app.diagrams.net" modified="2026-02-12T00:00:00.000Z" agent="Claude Code" version="24.0.0" type="device">
+  <diagram id="architecture" name="Project Structure">
+    <mxGraphModel dx="1422" dy="794" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1600" pageHeight="1200" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+
+        <!-- ROOT -->
+        <mxCell id="root" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1a1a2e;strokeColor=#e94560;arcSize=8;" vertex="1" parent="1">
+          <mxGeometry x="20" y="20" width="1560" height="1160" as="geometry" />
+        </mxCell>
+        <mxCell id="root_label" value="&lt;b&gt;basement-starter-cli&lt;/b&gt; (root)" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#e94560;fontSize=16;" vertex="1" parent="1">
+          <mxGeometry x="40" y="30" width="250" height="30" as="geometry" />
+        </mxCell>
+
+        <!-- Root files -->
+        <mxCell id="root_pkg" value="package.json&#xa;workspaces: [packages/*]" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2d2d44;strokeColor=#e94560;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="40" y="70" width="160" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="root_biome" value="biome.json&#xa;shared linting" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2d2d44;strokeColor=#e94560;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="210" y="70" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="root_changeset" value=".changeset/&#xa;versioning" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2d2d44;strokeColor=#e94560;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="340" y="70" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="root_ci" value=".github/workflows/&#xa;release pipeline" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2d2d44;strokeColor=#e94560;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="470" y="70" width="140" height="40" as="geometry" />
+        </mxCell>
+
+        <!-- CLI PACKAGE -->
+        <mxCell id="cli" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#16213e;strokeColor=#0f3460;arcSize=6;" vertex="1" parent="1">
+          <mxGeometry x="40" y="140" width="360" height="420" as="geometry" />
+        </mxCell>
+        <mxCell id="cli_label" value="&lt;b&gt;packages/cli&lt;/b&gt;&#xa;@basementstudio/cli" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#4da6ff;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="55" y="150" width="200" height="40" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_bin" value="&lt;b&gt;bin/index.js&lt;/b&gt;&#xa;CLI entry point&#xa;&#x27;basement&#x27; command&#xa;arg parsing + routing" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="60" y="200" width="150" height="70" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_create" value="&lt;b&gt;src/commands/create.js&lt;/b&gt;&#xa;Orchestrates scaffolding&#xa;Calls create-basement-app" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="60" y="285" width="160" height="60" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_add" value="&lt;b&gt;src/commands/&#xa;add-integration.js&lt;/b&gt;&#xa;Add CMS to existing project" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="230" y="285" width="155" height="60" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_worktree" value="&lt;b&gt;src/commands/&#xa;worktree.js&lt;/b&gt;&#xa;Git worktree mgmt" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="60" y="360" width="130" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_sanity" value="&lt;b&gt;src/commands/&#xa;setup-sanity.js&lt;/b&gt;&#xa;Sanity project setup" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="200" y="360" width="140" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_pkg" value="&lt;b&gt;package.json&lt;/b&gt;&#xa;deps: fs-extra, ora, picocolors,&#xa;prompts, dotenv" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e3a5f;strokeColor=#4da6ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="60" y="430" width="200" height="50" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cli_dep_label" value="depends on&#xa;create-basement-app&#xa;(workspace:*)" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff6b6b;fontSize=10;fontStyle=2;" vertex="1" parent="1">
+          <mxGeometry x="60" y="490" width="130" height="50" as="geometry" />
+        </mxCell>
+
+        <!-- CREATE-BASEMENT-APP PACKAGE -->
+        <mxCell id="cba" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#0f3460;strokeColor=#533483;arcSize=4;" vertex="1" parent="1">
+          <mxGeometry x="420" y="140" width="1140" height="1020" as="geometry" />
+        </mxCell>
+        <mxCell id="cba_label" value="&lt;b&gt;packages/create-basement-app&lt;/b&gt;&#xa;@basementstudio/create-basement-app" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#b388ff;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="440" y="150" width="350" height="40" as="geometry" />
+        </mxCell>
+
+        <!-- SRC -->
+        <mxCell id="cba_src" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1a2744;strokeColor=#533483;arcSize=6;" vertex="1" parent="1">
+          <mxGeometry x="440" y="200" width="520" height="200" as="geometry" />
+        </mxCell>
+        <mxCell id="cba_src_label" value="&lt;b&gt;src/&lt;/b&gt; — scaffolding logic" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#b388ff;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="450" y="205" width="180" height="25" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cba_index" value="&lt;b&gt;index.js&lt;/b&gt;&#xa;Public API&#xa;barrel export" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2a3f5f;strokeColor=#b388ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="455" y="235" width="100" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cba_mergers" value="&lt;b&gt;mergers/&lt;/b&gt;&#xa;index.js — injectLayer, injectIntegration&#xa;config.js — CMS_CONFIG, LAYER_CONFIG" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2a3f5f;strokeColor=#b388ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="570" y="235" width="250" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cba_configs" value="&lt;b&gt;configs/&lt;/b&gt;&#xa;animations.js&#xa;GSAP + Motion deps" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2a3f5f;strokeColor=#b388ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="835" y="235" width="110" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="cba_pkg" value="&lt;b&gt;package.json&lt;/b&gt; — deps: fs-extra, picocolors" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2a3f5f;strokeColor=#b388ff;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="455" y="310" width="280" height="30" as="geometry" />
+        </mxCell>
+
+        <!-- TEMPLATES -->
+        <mxCell id="templates" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#3d1f6d;strokeColor=#e94560;arcSize=6;" vertex="1" parent="1">
+          <mxGeometry x="440" y="420" width="520" height="280" as="geometry" />
+        </mxCell>
+        <mxCell id="templates_label" value="&lt;b&gt;templates/&lt;/b&gt; — full standalone Next.js projects" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff6b9d;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="450" y="425" width="330" height="25" as="geometry" />
+        </mxCell>
+
+        <mxCell id="t_default" value="&lt;b&gt;default/&lt;/b&gt;&#xa;84 files&#xa;Base next-starter&#xa;&#xa;next 16.1.4&#xa;react 19.2.4&#xa;tailwindcss v4&#xa;zustand&#xa;biome" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#4a2080;strokeColor=#ff6b9d;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="455" y="460" width="110" height="130" as="geometry" />
+        </mxCell>
+
+        <mxCell id="t_webgl" value="&lt;b&gt;webgl/&lt;/b&gt;&#xa;87 files&#xa;default + R3F&#xa;&#xa;@react-three/fiber&#xa;@react-three/drei&#xa;three ^0.182.0&#xa;+ canvas/scene" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#4a2080;strokeColor=#ff6b9d;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="580" y="460" width="115" height="130" as="geometry" />
+        </mxCell>
+
+        <mxCell id="t_webgpu" value="&lt;b&gt;webgpu/&lt;/b&gt;&#xa;84 files&#xa;default + alpha R3F&#xa;&#xa;fiber 10.0.0-alpha&#xa;drei ^11.0.0-alpha&#xa;(deps only,&#xa;no extra files)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#4a2080;strokeColor=#ff6b9d;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="710" y="460" width="115" height="130" as="geometry" />
+        </mxCell>
+
+        <mxCell id="t_experiment" value="&lt;b&gt;experiment/&lt;/b&gt;&#xa;86 files&#xa;default + nav&#xa;&#xa;Radix NavMenu&#xa;CVA styling&#xa;+ header/nav&#xa;+ constants.ts" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#4a2080;strokeColor=#ff6b9d;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="840" y="460" width="110" height="130" as="geometry" />
+        </mxCell>
+
+        <mxCell id="t_note" value="Each template is independently runnable:&#xa;cd templates/webgl &amp;&amp; bun install &amp;&amp; bun dev" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff6b9d;fontSize=10;fontStyle=2;" vertex="1" parent="1">
+          <mxGeometry x="455" y="605" width="280" height="35" as="geometry" />
+        </mxCell>
+
+        <!-- INTEGRATIONS -->
+        <mxCell id="integrations" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#5c1a1a;strokeColor=#ff4d4d;arcSize=6;" vertex="1" parent="1">
+          <mxGeometry x="980" y="200" width="560" height="310" as="geometry" />
+        </mxCell>
+        <mxCell id="int_label" value="&lt;b&gt;integrations/&lt;/b&gt; — CMS overlays (applied on top of any template)" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff6b6b;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="990" y="205" width="400" height="25" as="geometry" />
+        </mxCell>
+
+        <!-- Sanity -->
+        <mxCell id="sanity" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#6b2020;strokeColor=#ff4d4d;arcSize=8;" vertex="1" parent="1">
+          <mxGeometry x="995" y="240" width="340" height="250" as="geometry" />
+        </mxCell>
+        <mxCell id="sanity_label" value="&lt;b&gt;sanity/&lt;/b&gt;" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff8a8a;fontSize=11;" vertex="1" parent="1">
+          <mxGeometry x="1005" y="245" width="70" height="22" as="geometry" />
+        </mxCell>
+
+        <mxCell id="s_config" value="&lt;b&gt;config.js&lt;/b&gt;&#xa;Single source of truth&#xa;deps: @sanity/*, next-sanity&#xa;devDeps: sanity&#xa;scripts: extract, typegen&#xa;additivePaths: 9&#xa;mergeFiles: 3" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7a2a2a;strokeColor=#ff8a8a;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1010" y="270" width="150" height="100" as="geometry" />
+        </mxCell>
+
+        <mxCell id="s_files" value="&lt;b&gt;files/&lt;/b&gt;&#xa;35 Sanity files&#xa;app/ components/&#xa;lib/integrations/sanity/" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7a2a2a;strokeColor=#ff8a8a;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1175" y="270" width="145" height="70" as="geometry" />
+        </mxCell>
+
+        <mxCell id="s_mergers" value="&lt;b&gt;mergers/&lt;/b&gt;&#xa;layout-merger.js&#xa;sitemap-merger.js&#xa;check-integration-merger.js" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7a2a2a;strokeColor=#ff8a8a;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1175" y="355" width="145" height="70" as="geometry" />
+        </mxCell>
+
+        <!-- HOOKS -->
+        <mxCell id="hooks" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1a3a4a;strokeColor=#4ecdc4;arcSize=6;" vertex="1" parent="1">
+          <mxGeometry x="980" y="530" width="560" height="170" as="geometry" />
+        </mxCell>
+        <mxCell id="hooks_label" value="&lt;b&gt;template-hooks/&lt;/b&gt; — optional hooks copied during scaffolding" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#4ecdc4;fontSize=12;" vertex="1" parent="1">
+          <mxGeometry x="990" y="535" width="380" height="25" as="geometry" />
+        </mxCell>
+
+        <mxCell id="h_config" value="&lt;b&gt;config.js&lt;/b&gt;&#xa;Hook metadata&#xa;+ npm deps per hook" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e4a5a;strokeColor=#4ecdc4;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1000" y="570" width="120" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="h_battery" value="use-battery.ts&#xa;deps: lodash-es" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e4a5a;strokeColor=#4ecdc4;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1135" y="570" width="100" height="40" as="geometry" />
+        </mxCell>
+
+        <mxCell id="h_perf" value="use-device-perf.ts&#xa;deps: detect-gpu,&#xa;react-device-detect, zustand" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e4a5a;strokeColor=#4ecdc4;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1250" y="570" width="130" height="55" as="geometry" />
+        </mxCell>
+
+        <mxCell id="h_observer" value="use-intersection-&#xa;observer.ts&#xa;(no deps)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e4a5a;strokeColor=#4ecdc4;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1395" y="570" width="100" height="50" as="geometry" />
+        </mxCell>
+
+        <mxCell id="h_media" value="use-media.ts&#xa;(no deps)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1e4a5a;strokeColor=#4ecdc4;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1135" y="625" width="100" height="35" as="geometry" />
+        </mxCell>
+
+        <!-- PLUGINS -->
+        <mxCell id="plugins" value="&lt;b&gt;plugins/&lt;/b&gt;&#xa;no-anchor-element.grit&#xa;no-unnecessary-forwardref.grit&#xa;no-relative-parent-imports.grit" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#2a3a2a;strokeColor=#66bb6a;fontColor=#fff;fontSize=10;align=center;" vertex="1" parent="1">
+          <mxGeometry x="980" y="720" width="220" height="70" as="geometry" />
+        </mxCell>
+
+        <!-- ARROWS: CLI -> CBA -->
+        <mxCell id="arrow1" value="" style="endArrow=block;endFill=1;html=1;strokeColor=#ff6b6b;strokeWidth=2;entryX=0;entryY=0.5;exitX=1;exitY=0.5;" edge="1" parent="1" source="cli_create" target="cba_index">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow1_label" value="imports" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontColor=#ff6b6b;fontSize=10;" vertex="1" connectable="0" parent="arrow1">
+          <mxGeometry x="-0.2" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+
+        <!-- ARROW: CLI create -> templates -->
+        <mxCell id="arrow2" value="" style="endArrow=block;endFill=1;html=1;strokeColor=#ff6b9d;strokeWidth=2;dashed=1;exitX=1;exitY=1;entryX=0;entryY=0;" edge="1" parent="1" source="cli_create" target="templates">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow2_label" value="fs.copy" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontColor=#ff6b9d;fontSize=10;" vertex="1" connectable="0" parent="arrow2">
+          <mxGeometry x="-0.2" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+
+        <!-- ARROW: CLI create -> integrations -->
+        <mxCell id="arrow3" value="" style="endArrow=block;endFill=1;html=1;strokeColor=#ff4d4d;strokeWidth=2;dashed=1;exitX=1;exitY=0.3;entryX=0;entryY=0.5;" edge="1" parent="1" source="cli" target="integrations">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow3_label" value="merge + copy" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontColor=#ff4d4d;fontSize=10;" vertex="1" connectable="0" parent="arrow3">
+          <mxGeometry x="-0.3" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+
+        <!-- ARROW: mergers -> sanity mergers -->
+        <mxCell id="arrow4" value="" style="endArrow=block;endFill=1;html=1;strokeColor=#ff8a8a;strokeWidth=1;dashed=1;" edge="1" parent="1" source="cba_mergers" target="s_mergers">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="arrow4_label" value="imports" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontColor=#ff8a8a;fontSize=9;" vertex="1" connectable="0" parent="arrow4">
+          <mxGeometry x="-0.2" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+
+        <!-- DATA FLOW LEGEND -->
+        <mxCell id="legend" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1a1a2e;strokeColor=#555;arcSize=8;" vertex="1" parent="1">
+          <mxGeometry x="440" y="730" width="500" height="110" as="geometry" />
+        </mxCell>
+        <mxCell id="legend_title" value="&lt;b&gt;Data Flow&lt;/b&gt;" style="text;html=1;align=left;verticalAlign=top;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#fff;fontSize=11;" vertex="1" parent="1">
+          <mxGeometry x="455" y="735" width="80" height="22" as="geometry" />
+        </mxCell>
+        <mxCell id="legend1" value="1. User runs &lt;b&gt;basement&lt;/b&gt; → CLI parses args, prompts for choices" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#4da6ff;fontSize=10;" vertex="1" parent="1">
+          <mxGeometry x="455" y="758" width="340" height="22" as="geometry" />
+        </mxCell>
+        <mxCell id="legend2" value="2. CLI copies selected &lt;b&gt;template&lt;/b&gt; to target dir (instant, no network)" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff6b9d;fontSize=10;" vertex="1" parent="1">
+          <mxGeometry x="455" y="778" width="380" height="22" as="geometry" />
+        </mxCell>
+        <mxCell id="legend3" value="3. CLI applies CMS &lt;b&gt;integration&lt;/b&gt; via merge + copy (if selected)" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#ff4d4d;fontSize=10;" vertex="1" parent="1">
+          <mxGeometry x="455" y="798" width="350" height="22" as="geometry" />
+        </mxCell>
+        <mxCell id="legend4" value="4. CLI hydrates package.json from &lt;b&gt;config manifests&lt;/b&gt; (zero hardcoded deps)" style="text;html=1;align=left;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontColor=#b388ff;fontSize=10;" vertex="1" parent="1">
+          <mxGeometry x="455" y="818" width="420" height="22" as="geometry" />
+        </mxCell>
+
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

package/docs/architecture.mermaid

@@ -0,0 +1,85 @@
+graph TD
+    subgraph ROOT["basement-starter-cli (root)"]
+        PKG_ROOT["package.json<br/><i>workspaces: packages/*</i>"]
+        BIOME["biome.json<br/><i>shared linting</i>"]
+        CHANGESET[".changeset/<br/><i>versioning</i>"]
+        CI[".github/workflows/<br/><i>release pipeline</i>"]
+    end
+
+    subgraph CLI["packages/cli — @basementstudio/cli"]
+        CLI_BIN["bin/index.js<br/><i>CLI entry point</i><br/><i>basement command</i>"]
+        CLI_CREATE["src/commands/create.js<br/><i>orchestrates scaffolding</i>"]
+        CLI_ADD["src/commands/add-integration.js<br/><i>add CMS to existing project</i>"]
+        CLI_WORKTREE["src/commands/worktree.js<br/><i>git worktree management</i>"]
+        CLI_SANITY["src/commands/setup-sanity.js<br/><i>automated Sanity setup</i>"]
+        CLI_PKG["package.json<br/><i>depends on create-basement-app</i>"]
+    end
+
+    subgraph CBA["packages/create-basement-app — @basementstudio/create-basement-app"]
+        CBA_INDEX["src/index.js<br/><i>public API barrel export</i>"]
+
+        subgraph MERGERS["src/mergers/"]
+            MERGER_INDEX["index.js<br/><i>injectLayer, injectIntegration</i>"]
+            MERGER_CONFIG["config.js<br/><i>CMS_CONFIG, LAYER_CONFIG</i>"]
+        end
+
+        subgraph CONFIGS["src/configs/"]
+            ANIM_CONFIG["animations.js<br/><i>GSAP, Motion deps</i>"]
+        end
+
+        subgraph TEMPLATES["templates/ — standalone Next.js projects"]
+            T_DEFAULT["default/<br/><i>84 files, base starter</i>"]
+            T_WEBGL["webgl/<br/><i>87 files, R3F + canvas</i>"]
+            T_WEBGPU["webgpu/<br/><i>84 files, alpha R3F deps</i>"]
+            T_EXPERIMENT["experiment/<br/><i>86 files, nav components</i>"]
+        end
+
+        subgraph INTEGRATIONS["integrations/ — CMS overlays"]
+            subgraph SANITY["sanity/"]
+                S_CONFIG["config.js<br/><i>deps, scripts, paths</i>"]
+                S_FILES["files/<br/><i>35 Sanity files</i>"]
+                S_MERGERS["mergers/<br/><i>layout, sitemap, check</i>"]
+            end
+        end
+
+        subgraph HOOKS["template-hooks/"]
+            H_CONFIG["config.js<br/><i>hook metadata + deps</i>"]
+            H_BATTERY["use-battery.ts"]
+            H_PERF["use-device-perf.ts"]
+            H_OBSERVER["use-intersection-observer.ts"]
+            H_MEDIA["use-media.ts"]
+        end
+
+        PLUGINS["plugins/<br/><i>3 Biome Grit rules</i>"]
+    end
+
+    %% Dependencies
+    CLI_BIN --> CLI_CREATE
+    CLI_BIN --> CLI_ADD
+    CLI_BIN --> CLI_WORKTREE
+    CLI_CREATE --> CBA_INDEX
+    CLI_CREATE --> S_CONFIG
+    CLI_CREATE --> H_CONFIG
+    CLI_ADD --> CBA_INDEX
+    CLI_ADD --> S_CONFIG
+    CBA_INDEX --> MERGER_INDEX
+    CBA_INDEX --> ANIM_CONFIG
+    MERGER_INDEX --> MERGER_CONFIG
+    MERGER_INDEX --> S_MERGERS
+    CLI_CREATE --> TEMPLATES
+    CLI_CREATE --> CLI_SANITY
+
+    %% Styling
+    classDef root fill:#1a1a2e,stroke:#e94560,color:#fff
+    classDef cli fill:#16213e,stroke:#0f3460,color:#fff
+    classDef cba fill:#0f3460,stroke:#533483,color:#fff
+    classDef template fill:#533483,stroke:#e94560,color:#fff
+    classDef integration fill:#e94560,stroke:#fff,color:#fff
+    classDef hook fill:#0f3460,stroke:#e94560,color:#fff
+
+    class ROOT root
+    class CLI cli
+    class CBA cba
+    class TEMPLATES,T_DEFAULT,T_WEBGL,T_WEBGPU,T_EXPERIMENT template
+    class INTEGRATIONS,SANITY integration
+    class HOOKS hook