bsmnt 0.0.2 → 0.1.0

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,26 @@
 # @basementstudio/cli
 
+## 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

@@ -10,8 +10,8 @@ This is **basement**, a CLI tool that scaffolds Next.js projects with AI agent i
 
 ### 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,46 @@ 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
+│       │   └── basehub/                  # BaseHub files, 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 +138,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 +151,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,basehub}/
+    ├── 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

package/biome.json

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

package/bun.lock

@@ -2,7 +2,7 @@
   "lockfileVersion": 1,
   "workspaces": {
     "": {
-      "name": "@basementstudio/cli",
+      "name": "bsmnt",
       "dependencies": {
         "chalk": "^5.6.2",
         "dotenv": "^17.2.3",

package/docs/architecture.drawio

@@ -0,0 +1,266 @@
+<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>
+
+        <!-- BaseHub -->
+        <mxCell id="basehub" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#6b2020;strokeColor=#ff4d4d;arcSize=8;" vertex="1" parent="1">
+          <mxGeometry x="1350" y="240" width="175" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="basehub_label" value="&lt;b&gt;basehub/&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="1360" y="245" width="80" height="22" as="geometry" />
+        </mxCell>
+
+        <mxCell id="b_config" value="&lt;b&gt;config.js&lt;/b&gt;&#xa;basehub: ^3.0.0&#xa;(minimal)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7a2a2a;strokeColor=#ff8a8a;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1360" y="275" width="100" height="50" as="geometry" />
+        </mxCell>
+
+        <mxCell id="b_files" value="&lt;b&gt;files/&lt;/b&gt;&#xa;README.md" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7a2a2a;strokeColor=#ff8a8a;fontColor=#fff;fontSize=9;align=center;" vertex="1" parent="1">
+          <mxGeometry x="1468" y="275" width="50" height="50" 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,91 @@
+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
+            subgraph BASEHUB["basehub/"]
+                B_CONFIG["config.js<br/><i>basehub ^3.0.0</i>"]
+                B_FILES["files/<br/><i>README.md</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 --> B_CONFIG
+    CLI_CREATE --> H_CONFIG
+    CLI_ADD --> CBA_INDEX
+    CLI_ADD --> S_CONFIG
+    CLI_ADD --> B_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,BASEHUB integration
+    class HOOKS hook