docs: archive stale/completed docs, compact active refs (-1300 lines)

- Archive WORKSPACE_SYSTEM.md (completed); replace with 36-line operational ref
- Archive SHADER_REUSE_INVESTIGATION.md (implemented Feb 2026)
- Archive GPU_PROCEDURAL_PHASE4.md (completed feature)
- Archive GEOM_BUFFER.md (ideation only, never implemented)
- Archive SPECTRAL_BRUSH_EDITOR.md (v1 DCT approach, superseded by MQ v2)
- Update CLAUDE.md Tier 3 refs; point Audio to SPECTRAL_BRUSH_2.md
- Update TODO.md Task #5 design link to SPECTRAL_BRUSH_2.md
- Update COMPLETED.md archive index

handoff(Claude): doc cleanup done, 30 active docs (was 34), -1300 lines

9 files changed, 606 insertions, 565 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index e525708..5d4eb58 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,12 +17,12 @@
 # TIER 3: DESIGN DOCS (Load On-Demand by Subsystem)
 # ============================================
 #
-# Audio: @doc/SPECTRAL_BRUSH_EDITOR.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md
+# Audio: @doc/SPECTRAL_BRUSH_2.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md
 # CNN: @cnn_v1/docs/CNN_V1_EFFECT.md, @cnn_v2/docs/CNN_V2.md, @cnn_v2/docs/CNN_V2_BINARY_FORMAT.md
-# 3D/Graphics: @doc/3D.md, @doc/GPU_PROCEDURAL_PHASE4.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md
+# 3D/Graphics: @doc/3D.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md
 # Scene: @doc/SCENE_FORMAT.md, @doc/SEQUENCE.md, @doc/WORKSPACE_SYSTEM.md
 # Build: @doc/ASSET_SYSTEM.md, @doc/BUILD.md, @doc/CMAKE_MODULES.md, @doc/SIZE_MEASUREMENT.md
-# Rendering: @doc/GEOM_BUFFER.md, @doc/SHADER_REUSE_INVESTIGATION.md, @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md
+# Rendering: @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md
 # Tools: @doc/test_demo_README.md, @doc/HOT_RELOAD.md, @doc/HEADLESS_MODE.md, @doc/RECIPE.md, @doc/TOOLS_REFERENCE.md
 # Arch: @doc/ARCHITECTURE.md, @doc/CODING_STYLE.md, @doc/BACKLOG.md, @doc/CONTEXT_MAINTENANCE.md
 
diff --git a/TODO.md b/TODO.md
index b154926..aca1257 100644
--- a/TODO.md
+++ b/TODO.md
@@ -8,7 +8,7 @@
 
 Procedural spectrogram tool: 50-100× compression (5 KB .spec → ~100 bytes C++).
 
-**Design:** `doc/SPECTRAL_BRUSH_EDITOR.md`
+**Design:** `doc/SPECTRAL_BRUSH_2.md` (MQ-based v2)
 
 ---
 
diff --git a/doc/COMPLETED.md b/doc/COMPLETED.md
index 9299a93..42e4bc6 100644
--- a/doc/COMPLETED.md
+++ b/doc/COMPLETED.md
@@ -11,6 +11,11 @@ Completed task archive. See `doc/archive/` for detailed historical documents.
 - AUDIO_LIFECYCLE_REFACTOR.md, AUDIO_TIMING_ARCHITECTURE.md
 - BUILD_OPTIMIZATION_PROPOSAL.md, BUILD_OPTIMIZATION_PROPOSAL_V2.md
 - PLATFORM_ANALYSIS.md, SHADER_PARAMETRIZATION_PLAN.md
+- SHADER_REUSE_INVESTIGATION.md (shared `src/shaders/` approach implemented Feb 2026)
+- GPU_PROCEDURAL_PHASE4.md (multi-input composite shaders with sampler cache, ~830 bytes)
+- GEOM_BUFFER.md (G-buffer ideation, not yet implemented — see BACKLOG)
+- WORKSPACE_SYSTEM.md (full design; compacted to operational reference Feb 2026)
+- SPECTRAL_BRUSH_EDITOR.md (v1 DCT approach; superseded by MQ-based v2 in SPECTRAL_BRUSH_2.md)
 
 **Handoffs & Summaries:**
 - HANDOFF.md, HANDOFF_2026-02-04.md, HANDOFF_2026-02-08.md, HANDOFF_CLAUDE.md
diff --git a/doc/WORKSPACE_SYSTEM.md b/doc/WORKSPACE_SYSTEM.md
index 6b4319d..f0981fd 100644
--- a/doc/WORKSPACE_SYSTEM.md
+++ b/doc/WORKSPACE_SYSTEM.md
@@ -1,576 +1,36 @@
-# Workspace System (Task #77) [COMPLETED]
+# Workspace System
 
-## Status
+**Status:** ✅ Complete (Feb 9, 2026)
 
-**Implemented:** Feb 9, 2026
+Self-contained demo workspaces. Select with `cmake -B build -DDEMO_WORKSPACE=<name>`.
 
-Workspace system is now active. Use `cmake -B build -DDEMO_WORKSPACE=<name>` to select workspace.
+## Directory Layout
 
-## Overview
-
-Self-contained demo workspaces for parallel development and clean content separation.
-
-**Motivation:** Current structure scatters demo content across multiple locations:
-- `assets/demo.seq` - Timeline
-- `assets/music.track` - Audio
-- `assets/final/demo_assets.txt` - Asset list
-- `assets/final/music/*.spec` - Audio samples
-- `assets/shaders/*.wgsl` - Shaders (some demo-specific, some shared)
-
-This makes it hard to:
-- Work on multiple demos simultaneously
-- Understand what files belong to which demo
-- Share common resources cleanly
-- Onboard new developers
-
-## Problem Statement
-
-**Current structure (flat):**
 ```
-/assets/
-  demo.seq                    # Main demo timeline
-  music.track                 # Main demo music
-  test_demo.seq              # Test demo timeline
-  test_demo.track            # Test demo music
-  /final/
-    demo_assets.txt          # Main demo assets
-    /music/*.spec            # Audio samples (mixed usage)
-  /shaders/
-    *.wgsl                   # Mixed: common + demo-specific
-```
-
-**Issues:**
-1. No clear ownership of files
-2. Can't easily switch between demos
-3. Assets intermingled (demo vs test)
-4. Shaders hard to categorize (shared vs demo-specific)
-5. Adding new demos requires scattered changes
-
-## Current Structure (Implemented)
-
-### Workspace Directory Layout
-
-```
-/workspaces/
-  /main/                     # Main production demo
-    workspace.cfg            # Workspace metadata
-    timeline.seq             # Visual effects
-    music.track              # Audio patterns
-    assets.txt               # Asset list
-    /music/*.spec            # Audio samples
-    /weights/*.bin           # CNN binary weights
-    /obj/*.obj               # 3D models
-    /shaders/                # Workspace-specific shaders only
-      custom_effect.wgsl
-
-  /test/                     # Test/validation demo
-    workspace.cfg
-    timeline.seq
-    music.track
-    assets.txt
-    /music/
-    /weights/
-    /obj/
-    /shaders/
-
-/common/                     # Shared resources
-  /shaders/
-    /math/                   # Shared math utilities
-      common_utils.wgsl
-      noise.wgsl
-      sdf_shapes.wgsl
-      sdf_utils.wgsl
-    /render/                 # Shared rendering helpers
-      lighting_utils.wgsl
-      scene_query_bvh.wgsl
-      scene_query_linear.wgsl
-      shadows.wgsl
-    /compute/                # Shared compute shaders
-      gen_blend.wgsl
-      gen_grid.wgsl
-      gen_mask.wgsl
-      gen_noise.wgsl
-      gen_perlin.wgsl
-    common_uniforms.wgsl
-    lighting.wgsl
-    passthrough.wgsl
-    ray_box.wgsl
-    ray_triangle.wgsl
-    sdf_primitives.wgsl
-    skybox.wgsl
-
-/tools/
-  originals/                 # Source audio files (.wav, .aif)
-```
-
-### Workspace Configuration
-
-**`workspace.cfg` format:**
-```ini
-[workspace]
-name = "Main Demo"
-description = "Production 64k demo"
-version = "1.0"
+workspaces/
+  main/           # Main production demo
+    timeline.seq  # Visual effects
+    music.track   # Audio patterns
+    assets.txt    # Asset list
+    music/*.spec  # Audio samples
+    weights/*.bin # CNN weights
+    obj/*.obj     # 3D models
+    shaders/      # Workspace-specific shaders only
+  test/           # Test demo (same structure)
 
-[build]
-target = "demo64k"
-timeline = "timeline.seq"
-music = "music.track"
-assets = "assets.txt"
-asset_dirs = ["music/", "weights/", "obj/"]
-shader_dirs = ["shaders/"]
-
-[build]
-# Output binary name
-target = "demo64k"
-
-# Include paths (relative to workspace root)
-timeline = "timeline.seq"
-music = "music.track"
-assets = "assets.txt"
-
-# Asset directories
-asset_dirs = ["assets/", "../common/audio/"]
-
-# Shader directories (order matters: workspace-specific first)
-shader_dirs = ["shaders/", "../src/shaders/"]
-
-[options]
-# Default resolution
-width = 1280
-height = 720
-
-# Duration (seconds, -1 = auto-detect)
-duration = -1
-
-# BPM for timeline
-bpm = 120
+src/shaders/      # Shared common shaders (math/, render/, compute/)
 ```
 
-## Architecture
-
-### Build System Integration
-
-**CMakeLists.txt changes:**
-```cmake
-# Select active workspace (default: main)
-set(DEMO_WORKSPACE "main" CACHE STRING "Active workspace")
+## Usage
 
-# Parse workspace config
-set(WORKSPACE_DIR "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}")
-set(WORKSPACE_CFG "${WORKSPACE_DIR}/workspace.cfg")
-
-# Read config and set variables
-parse_workspace_config(${WORKSPACE_CFG}
-  TIMELINE_PATH
-  MUSIC_PATH
-  ASSETS_PATH
-  ASSET_DIRS
-  SHADER_DIRS
-  TARGET_NAME
-)
-
-# Generate assets from workspace
-add_custom_command(
-  OUTPUT ${GEN_ASSETS_H}
-  COMMAND asset_packer ${WORKSPACE_DIR}/${ASSETS_PATH} ...
-  DEPENDS ${WORKSPACE_DIR}/${ASSETS_PATH}
-)
-
-# Generate timeline from workspace
-add_custom_command(
-  OUTPUT ${GEN_TIMELINE_CC}
-  COMMAND seq_compiler ${WORKSPACE_DIR}/${TIMELINE_PATH} ...
-  DEPENDS ${WORKSPACE_DIR}/${TIMELINE_PATH}
-)
-
-# Add shader include paths from workspace
-foreach(SHADER_DIR ${SHADER_DIRS})
-  list(APPEND SHADER_INCLUDE_DIRS "${WORKSPACE_DIR}/${SHADER_DIR}")
-endforeach()
-```
-
-**Building specific workspace:**
 ```bash
-# Default (main workspace)
-cmake -S . -B build
-cmake --build build -j4
-
-# Specific workspace
-cmake -S . -B build_test -DDEMO_WORKSPACE=test
-cmake --build build_test -j4
-
-# Experimental workspace
-cmake -S . -B build_exp -DDEMO_WORKSPACE=experiments/demo2024_revision
-cmake --build build_exp -j4
-```
-
-### Asset Packer Changes
-
-**Support workspace-relative paths:**
-```cpp
-// asset_packer.cc
-void PackerContext::resolve_asset_path(const char* rel_path) {
-  // Try workspace-local first
-  std::string workspace_path = workspace_dir + "/" + rel_path;
-  if (file_exists(workspace_path)) {
-    return workspace_path;
-  }
-
-  // Try common assets
-  std::string common_path = "assets/common/" + rel_path;
-  if (file_exists(common_path)) {
-    return common_path;
-  }
-
-  error("Asset not found: %s", rel_path);
-}
-```
-
-### Shader Composer Changes
-
-**Support multiple include paths:**
-```cpp
-// shader_composer.cc
-class ShaderComposer {
-  std::vector<std::string> include_paths_;
-
-  void add_include_path(const char* path) {
-    include_paths_.push_back(path);
-  }
-
-  std::string resolve_include(const char* filename) {
-    for (const auto& base : include_paths_) {
-      std::string full = base + "/" + filename;
-      if (file_exists(full)) {
-        return full;
-      }
-    }
-    error("Shader include not found: %s", filename);
-  }
-};
-```
-
-**Shader includes with search paths:**
-```wgsl
-// workspace-specific shader
-#include "custom_uniforms.wgsl"      // From workspaces/main/shaders/
-#include "math/common_utils.wgsl"    // From src/shaders/
-```
-
-### CLI Tool
-
-**`scripts/workspace.sh` - Workspace management:**
-```bash
-#!/bin/bash
-# workspace.sh - Manage demo workspaces
-
-case "$1" in
-  list)
-    # List all workspaces
-    ls -1 workspaces/
-    ;;
-
-  create)
-    # Create new workspace from template
-    NAME=$2
-    mkdir -p workspaces/$NAME/{assets,shaders}
-    cp templates/workspace.cfg workspaces/$NAME/
-    echo "Created workspace: $NAME"
-    ;;
-
-  build)
-    # Build specific workspace
-    NAME=$2
-    cmake -S . -B build_$NAME -DDEMO_WORKSPACE=$NAME
-    cmake --build build_$NAME -j4
-    ;;
-
-  info)
-    # Show workspace details
-    NAME=$2
-    cat workspaces/$NAME/workspace.cfg
-    ;;
-esac
-```
-
-**Usage:**
-```bash
-./scripts/workspace.sh list
-./scripts/workspace.sh create my_demo
-./scripts/workspace.sh build main
-./scripts/workspace.sh info test
-```
-
-## Implementation Plan
-
-### Phase 1: Create Workspace Structure
-
-**1.1 Create directory tree:**
-```bash
-mkdir -p workspaces/{main,test}/assets
-mkdir -p workspaces/{main,test}/shaders
-mkdir -p assets/common/{shaders,audio}
-```
-
-**1.2 Move existing files:**
-```bash
-# Main demo
-mv assets/demo.seq workspaces/main/timeline.seq
-mv assets/music.track workspaces/main/music.track
-mv assets/final/demo_assets.txt workspaces/main/assets.txt
-mv assets/final/music workspaces/main/assets/
+# Main demo (default)
+cmake -S . -B build -DDEMO_WORKSPACE=main && cmake --build build -j4
 
 # Test demo
-mv assets/test_demo.seq workspaces/test/timeline.seq
-mv assets/test_demo.track workspaces/test/music.track
-cp assets/final/demo_assets.txt workspaces/test/assets.txt  # Or create minimal version
-
-# Common shaders
-mv assets/shaders/math assets/common/shaders/
-mv assets/shaders/common_uniforms assets/common/shaders/
-```
-
-**1.3 Create workspace configs:**
-```bash
-# Generate workspace.cfg for main and test
-# See format above
-```
-
-### Phase 2: Update Build System
-
-**2.1 Add workspace parsing:**
-- Create `cmake/ParseWorkspace.cmake`
-- Parse INI-style config
-- Set CMake variables
-
-**2.2 Update CMakeLists.txt:**
-- Add `DEMO_WORKSPACE` option
-- Use workspace paths for assets/timeline/music
-- Pass shader include paths to ShaderComposer
-
-**2.3 Update compiler tools:**
-- `asset_packer`: Accept workspace root dir
-- `seq_compiler`: Accept workspace root dir
-- `tracker_compiler`: Accept workspace root dir
-
-### Phase 3: Update Code
-
-**3.1 ShaderComposer:**
-- Add multi-path include resolution
-- Search workspace shaders first, then common
-
-**3.2 Asset loading:**
-- Update paths to match new structure
-- Ensure backward compatibility during transition
-
-**3.3 Generated code:**
-- Verify generated assets.h/timeline.cc still work
-- Update include paths if needed
-
-### Phase 4: Documentation & Tools
-
-**4.1 Update docs:**
-- README.md: Explain workspace structure
-- HOWTO.md: Document workspace build commands
-- CONTRIBUTING.md: Workspace best practices
-
-**4.2 Create helper scripts:**
-- `scripts/workspace.sh`: Workspace management CLI
-- `templates/workspace.cfg`: Template for new workspaces
-
-**4.3 Update CI:**
-- Build both main and test workspaces
-- Validate workspace isolation
-
-### Phase 5: Migration & Validation
-
-**5.1 Test builds:**
-```bash
-# Build both workspaces
-cmake -S . -B build_main -DDEMO_WORKSPACE=main
-cmake --build build_main -j4
-
-cmake -S . -B build_test -DDEMO_WORKSPACE=test
-cmake --build build_test -j4
-
-# Run tests
-cd build_main && ctest
-cd build_test && ctest
+cmake -S . -B build_test -DDEMO_WORKSPACE=test && cmake --build build_test -j4
 ```
 
-**5.2 Verify isolation:**
-- Modify workspace-specific shader → only that workspace affected
-- Modify common shader → both workspaces affected
-
-**5.3 Update .gitignore:**
-```
-/build_*/
-/workspaces/*/generated/
-```
-
-## Benefits
-
-### 1. Clear Ownership
-Each workspace is self-contained:
-```bash
-workspaces/main/
-├── workspace.cfg     # Configuration
-├── timeline.seq      # Timeline
-├── music.track       # Music
-├── assets.txt        # Assets
-├── assets/           # Local assets
-└── shaders/          # Local shaders
-```
-
-### 2. Parallel Development
-Multiple developers can work on different demos without conflicts:
-```bash
-# Developer A: Main demo
-cd workspaces/main
-vim timeline.seq
-
-# Developer B: Experimental demo
-cd workspaces/experiments/christmas_demo
-vim timeline.seq
-```
-
-### 3. Easy Switching
-```bash
-# Build main demo
-cmake -B build -DDEMO_WORKSPACE=main
-./build/demo64k
-
-# Build test demo
-cmake -B build -DDEMO_WORKSPACE=test
-./build/test_demo
-```
-
-### 4. Clean Sharing
-Common resources in one place:
-```
-assets/common/
-├── shaders/
-│   ├── math/          # Shared by all
-│   └── common_uniforms/
-└── audio/
-    └── standard_drums.spec
-```
-
-### 5. Scalability
-Easy to add new demos:
-```bash
-./scripts/workspace.sh create party2025
-cd workspaces/party2025
-# Start developing...
-```
-
-## Migration Path
-
-### Backward Compatibility
-
-During transition, support both structures:
-```cmake
-if(EXISTS "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}")
-  # New workspace structure
-  set(USING_WORKSPACES TRUE)
-else()
-  # Legacy flat structure
-  set(USING_WORKSPACES FALSE)
-endif()
-```
-
-### Gradual Migration
-
-1. **Phase 1:** Create workspace structure alongside existing
-2. **Phase 2:** Update build system to support both
-3. **Phase 3:** Move files to workspaces
-4. **Phase 4:** Remove legacy paths
-5. **Phase 5:** Update all documentation
-
-**Timeline:** 1-2 weeks for full migration
-
-## Trade-offs
-
-### Pros
-- Clear project organization
-- Parallel demo development
-- Clean resource sharing
-- Better onboarding for new devs
-- Scales to many demos
-
-### Cons
-- Initial migration effort
-- Build system complexity increases
-- More directories to navigate
-- Learning curve for contributors
-
-### Alternative Approaches
-
-**1. Monorepo with subprojects:**
-- Separate CMake projects per demo
-- More isolated but harder to share code
-
-**2. Configuration files only:**
-- Keep flat structure, use config to select files
-- Less clear, harder to understand ownership
-
-**3. Git branches per demo:**
-- Each demo is a branch
-- Conflicts when merging shared code
-
-**Chosen:** Workspace system (best balance)
-
-## Implementation Effort
-
-**Estimated time: 12-16 hours**
-
-- Phase 1: Create structure (2-3 hours)
-- Phase 2: Build system (4-5 hours)
-- Phase 3: Code updates (3-4 hours)
-- Phase 4: Documentation (2-3 hours)
-- Phase 5: Validation (1-2 hours)
-
-**Priority:** Medium (improves workflow, not blocking)
-
-## Success Criteria
-
-1. Both `main` and `test` workspaces build successfully
-2. Switching workspaces requires only CMake flag change
-3. Workspace-specific changes don't affect other workspaces
-4. Common shader changes affect all workspaces
-5. New workspace creation takes < 5 minutes
-6. All tests pass for both workspaces
-7. Documentation clear for new contributors
-
-## Related Files
-
-**New files:**
-- `workspaces/main/workspace.cfg` - Main demo config
-- `workspaces/test/workspace.cfg` - Test demo config
-- `cmake/ParseWorkspace.cmake` - Config parser
-- `scripts/workspace.sh` - Workspace CLI tool
-- `templates/workspace.cfg` - New workspace template
-
-**Modified files:**
-- `CMakeLists.txt` - Workspace support
-- `tools/asset_packer.cc` - Multi-path resolution
-- `src/gpu/shader_composer.cc` - Multi-path includes
-- `README.md` - Workspace documentation
-- `doc/HOWTO.md` - Build commands
-- `doc/CONTRIBUTING.md` - Workspace guidelines
-
-**Moved files:**
-- `assets/demo.seq` → `workspaces/main/timeline.seq`
-- `assets/music.track` → `workspaces/main/music.track`
-- `assets/final/demo_assets.txt` → `workspaces/main/assets.txt`
-- `assets/test_demo.*` → `workspaces/test/`
-- `assets/shaders/math/` → `assets/common/shaders/math/`
-
-## Notes
+Shared shaders in `src/shaders/` are referenced as `../../src/shaders/...` in `assets.txt`.
 
-- This is a **structural refactor**, not a feature
-- No runtime behavior changes
-- Enables future scalability
-- Makes project more professional
-- Good foundation for demoscene releases (multiple demos per repo)
+See `doc/archive/WORKSPACE_SYSTEM.md` for full design and implementation history.
diff --git a/doc/GEOM_BUFFER.md b/doc/archive/GEOM_BUFFER.md
index 0188125..0188125 100644
--- a/doc/GEOM_BUFFER.md
+++ b/doc/archive/GEOM_BUFFER.md
diff --git a/doc/GPU_PROCEDURAL_PHASE4.md b/doc/archive/GPU_PROCEDURAL_PHASE4.md
index 4cfc271..4cfc271 100644
--- a/doc/GPU_PROCEDURAL_PHASE4.md
+++ b/doc/archive/GPU_PROCEDURAL_PHASE4.md
diff --git a/doc/SHADER_REUSE_INVESTIGATION.md b/doc/archive/SHADER_REUSE_INVESTIGATION.md
index e840126..e840126 100644
--- a/doc/SHADER_REUSE_INVESTIGATION.md
+++ b/doc/archive/SHADER_REUSE_INVESTIGATION.md
diff --git a/doc/SPECTRAL_BRUSH_EDITOR.md b/doc/archive/SPECTRAL_BRUSH_EDITOR.md
index a7d0e3a..a7d0e3a 100644
--- a/doc/SPECTRAL_BRUSH_EDITOR.md
+++ b/doc/archive/SPECTRAL_BRUSH_EDITOR.md
diff --git a/doc/archive/WORKSPACE_SYSTEM.md b/doc/archive/WORKSPACE_SYSTEM.md
new file mode 100644
index 0000000..6b4319d
--- /dev/null
+++ b/doc/archive/WORKSPACE_SYSTEM.md
@@ -0,0 +1,576 @@
+# Workspace System (Task #77) [COMPLETED]
+
+## Status
+
+**Implemented:** Feb 9, 2026
+
+Workspace system is now active. Use `cmake -B build -DDEMO_WORKSPACE=<name>` to select workspace.
+
+## Overview
+
+Self-contained demo workspaces for parallel development and clean content separation.
+
+**Motivation:** Current structure scatters demo content across multiple locations:
+- `assets/demo.seq` - Timeline
+- `assets/music.track` - Audio
+- `assets/final/demo_assets.txt` - Asset list
+- `assets/final/music/*.spec` - Audio samples
+- `assets/shaders/*.wgsl` - Shaders (some demo-specific, some shared)
+
+This makes it hard to:
+- Work on multiple demos simultaneously
+- Understand what files belong to which demo
+- Share common resources cleanly
+- Onboard new developers
+
+## Problem Statement
+
+**Current structure (flat):**
+```
+/assets/
+  demo.seq                    # Main demo timeline
+  music.track                 # Main demo music
+  test_demo.seq              # Test demo timeline
+  test_demo.track            # Test demo music
+  /final/
+    demo_assets.txt          # Main demo assets
+    /music/*.spec            # Audio samples (mixed usage)
+  /shaders/
+    *.wgsl                   # Mixed: common + demo-specific
+```
+
+**Issues:**
+1. No clear ownership of files
+2. Can't easily switch between demos
+3. Assets intermingled (demo vs test)
+4. Shaders hard to categorize (shared vs demo-specific)
+5. Adding new demos requires scattered changes
+
+## Current Structure (Implemented)
+
+### Workspace Directory Layout
+
+```
+/workspaces/
+  /main/                     # Main production demo
+    workspace.cfg            # Workspace metadata
+    timeline.seq             # Visual effects
+    music.track              # Audio patterns
+    assets.txt               # Asset list
+    /music/*.spec            # Audio samples
+    /weights/*.bin           # CNN binary weights
+    /obj/*.obj               # 3D models
+    /shaders/                # Workspace-specific shaders only
+      custom_effect.wgsl
+
+  /test/                     # Test/validation demo
+    workspace.cfg
+    timeline.seq
+    music.track
+    assets.txt
+    /music/
+    /weights/
+    /obj/
+    /shaders/
+
+/common/                     # Shared resources
+  /shaders/
+    /math/                   # Shared math utilities
+      common_utils.wgsl
+      noise.wgsl
+      sdf_shapes.wgsl
+      sdf_utils.wgsl
+    /render/                 # Shared rendering helpers
+      lighting_utils.wgsl
+      scene_query_bvh.wgsl
+      scene_query_linear.wgsl
+      shadows.wgsl
+    /compute/                # Shared compute shaders
+      gen_blend.wgsl
+      gen_grid.wgsl
+      gen_mask.wgsl
+      gen_noise.wgsl
+      gen_perlin.wgsl
+    common_uniforms.wgsl
+    lighting.wgsl
+    passthrough.wgsl
+    ray_box.wgsl
+    ray_triangle.wgsl
+    sdf_primitives.wgsl
+    skybox.wgsl
+
+/tools/
+  originals/                 # Source audio files (.wav, .aif)
+```
+
+### Workspace Configuration
+
+**`workspace.cfg` format:**
+```ini
+[workspace]
+name = "Main Demo"
+description = "Production 64k demo"
+version = "1.0"
+
+[build]
+target = "demo64k"
+timeline = "timeline.seq"
+music = "music.track"
+assets = "assets.txt"
+asset_dirs = ["music/", "weights/", "obj/"]
+shader_dirs = ["shaders/"]
+
+[build]
+# Output binary name
+target = "demo64k"
+
+# Include paths (relative to workspace root)
+timeline = "timeline.seq"
+music = "music.track"
+assets = "assets.txt"
+
+# Asset directories
+asset_dirs = ["assets/", "../common/audio/"]
+
+# Shader directories (order matters: workspace-specific first)
+shader_dirs = ["shaders/", "../src/shaders/"]
+
+[options]
+# Default resolution
+width = 1280
+height = 720
+
+# Duration (seconds, -1 = auto-detect)
+duration = -1
+
+# BPM for timeline
+bpm = 120
+```
+
+## Architecture
+
+### Build System Integration
+
+**CMakeLists.txt changes:**
+```cmake
+# Select active workspace (default: main)
+set(DEMO_WORKSPACE "main" CACHE STRING "Active workspace")
+
+# Parse workspace config
+set(WORKSPACE_DIR "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}")
+set(WORKSPACE_CFG "${WORKSPACE_DIR}/workspace.cfg")
+
+# Read config and set variables
+parse_workspace_config(${WORKSPACE_CFG}
+  TIMELINE_PATH
+  MUSIC_PATH
+  ASSETS_PATH
+  ASSET_DIRS
+  SHADER_DIRS
+  TARGET_NAME
+)
+
+# Generate assets from workspace
+add_custom_command(
+  OUTPUT ${GEN_ASSETS_H}
+  COMMAND asset_packer ${WORKSPACE_DIR}/${ASSETS_PATH} ...
+  DEPENDS ${WORKSPACE_DIR}/${ASSETS_PATH}
+)
+
+# Generate timeline from workspace
+add_custom_command(
+  OUTPUT ${GEN_TIMELINE_CC}
+  COMMAND seq_compiler ${WORKSPACE_DIR}/${TIMELINE_PATH} ...
+  DEPENDS ${WORKSPACE_DIR}/${TIMELINE_PATH}
+)
+
+# Add shader include paths from workspace
+foreach(SHADER_DIR ${SHADER_DIRS})
+  list(APPEND SHADER_INCLUDE_DIRS "${WORKSPACE_DIR}/${SHADER_DIR}")
+endforeach()
+```
+
+**Building specific workspace:**
+```bash
+# Default (main workspace)
+cmake -S . -B build
+cmake --build build -j4
+
+# Specific workspace
+cmake -S . -B build_test -DDEMO_WORKSPACE=test
+cmake --build build_test -j4
+
+# Experimental workspace
+cmake -S . -B build_exp -DDEMO_WORKSPACE=experiments/demo2024_revision
+cmake --build build_exp -j4
+```
+
+### Asset Packer Changes
+
+**Support workspace-relative paths:**
+```cpp
+// asset_packer.cc
+void PackerContext::resolve_asset_path(const char* rel_path) {
+  // Try workspace-local first
+  std::string workspace_path = workspace_dir + "/" + rel_path;
+  if (file_exists(workspace_path)) {
+    return workspace_path;
+  }
+
+  // Try common assets
+  std::string common_path = "assets/common/" + rel_path;
+  if (file_exists(common_path)) {
+    return common_path;
+  }
+
+  error("Asset not found: %s", rel_path);
+}
+```
+
+### Shader Composer Changes
+
+**Support multiple include paths:**
+```cpp
+// shader_composer.cc
+class ShaderComposer {
+  std::vector<std::string> include_paths_;
+
+  void add_include_path(const char* path) {
+    include_paths_.push_back(path);
+  }
+
+  std::string resolve_include(const char* filename) {
+    for (const auto& base : include_paths_) {
+      std::string full = base + "/" + filename;
+      if (file_exists(full)) {
+        return full;
+      }
+    }
+    error("Shader include not found: %s", filename);
+  }
+};
+```
+
+**Shader includes with search paths:**
+```wgsl
+// workspace-specific shader
+#include "custom_uniforms.wgsl"      // From workspaces/main/shaders/
+#include "math/common_utils.wgsl"    // From src/shaders/
+```
+
+### CLI Tool
+
+**`scripts/workspace.sh` - Workspace management:**
+```bash
+#!/bin/bash
+# workspace.sh - Manage demo workspaces
+
+case "$1" in
+  list)
+    # List all workspaces
+    ls -1 workspaces/
+    ;;
+
+  create)
+    # Create new workspace from template
+    NAME=$2
+    mkdir -p workspaces/$NAME/{assets,shaders}
+    cp templates/workspace.cfg workspaces/$NAME/
+    echo "Created workspace: $NAME"
+    ;;
+
+  build)
+    # Build specific workspace
+    NAME=$2
+    cmake -S . -B build_$NAME -DDEMO_WORKSPACE=$NAME
+    cmake --build build_$NAME -j4
+    ;;
+
+  info)
+    # Show workspace details
+    NAME=$2
+    cat workspaces/$NAME/workspace.cfg
+    ;;
+esac
+```
+
+**Usage:**
+```bash
+./scripts/workspace.sh list
+./scripts/workspace.sh create my_demo
+./scripts/workspace.sh build main
+./scripts/workspace.sh info test
+```
+
+## Implementation Plan
+
+### Phase 1: Create Workspace Structure
+
+**1.1 Create directory tree:**
+```bash
+mkdir -p workspaces/{main,test}/assets
+mkdir -p workspaces/{main,test}/shaders
+mkdir -p assets/common/{shaders,audio}
+```
+
+**1.2 Move existing files:**
+```bash
+# Main demo
+mv assets/demo.seq workspaces/main/timeline.seq
+mv assets/music.track workspaces/main/music.track
+mv assets/final/demo_assets.txt workspaces/main/assets.txt
+mv assets/final/music workspaces/main/assets/
+
+# Test demo
+mv assets/test_demo.seq workspaces/test/timeline.seq
+mv assets/test_demo.track workspaces/test/music.track
+cp assets/final/demo_assets.txt workspaces/test/assets.txt  # Or create minimal version
+
+# Common shaders
+mv assets/shaders/math assets/common/shaders/
+mv assets/shaders/common_uniforms assets/common/shaders/
+```
+
+**1.3 Create workspace configs:**
+```bash
+# Generate workspace.cfg for main and test
+# See format above
+```
+
+### Phase 2: Update Build System
+
+**2.1 Add workspace parsing:**
+- Create `cmake/ParseWorkspace.cmake`
+- Parse INI-style config
+- Set CMake variables
+
+**2.2 Update CMakeLists.txt:**
+- Add `DEMO_WORKSPACE` option
+- Use workspace paths for assets/timeline/music
+- Pass shader include paths to ShaderComposer
+
+**2.3 Update compiler tools:**
+- `asset_packer`: Accept workspace root dir
+- `seq_compiler`: Accept workspace root dir
+- `tracker_compiler`: Accept workspace root dir
+
+### Phase 3: Update Code
+
+**3.1 ShaderComposer:**
+- Add multi-path include resolution
+- Search workspace shaders first, then common
+
+**3.2 Asset loading:**
+- Update paths to match new structure
+- Ensure backward compatibility during transition
+
+**3.3 Generated code:**
+- Verify generated assets.h/timeline.cc still work
+- Update include paths if needed
+
+### Phase 4: Documentation & Tools
+
+**4.1 Update docs:**
+- README.md: Explain workspace structure
+- HOWTO.md: Document workspace build commands
+- CONTRIBUTING.md: Workspace best practices
+
+**4.2 Create helper scripts:**
+- `scripts/workspace.sh`: Workspace management CLI
+- `templates/workspace.cfg`: Template for new workspaces
+
+**4.3 Update CI:**
+- Build both main and test workspaces
+- Validate workspace isolation
+
+### Phase 5: Migration & Validation
+
+**5.1 Test builds:**
+```bash
+# Build both workspaces
+cmake -S . -B build_main -DDEMO_WORKSPACE=main
+cmake --build build_main -j4
+
+cmake -S . -B build_test -DDEMO_WORKSPACE=test
+cmake --build build_test -j4
+
+# Run tests
+cd build_main && ctest
+cd build_test && ctest
+```
+
+**5.2 Verify isolation:**
+- Modify workspace-specific shader → only that workspace affected
+- Modify common shader → both workspaces affected
+
+**5.3 Update .gitignore:**
+```
+/build_*/
+/workspaces/*/generated/
+```
+
+## Benefits
+
+### 1. Clear Ownership
+Each workspace is self-contained:
+```bash
+workspaces/main/
+├── workspace.cfg     # Configuration
+├── timeline.seq      # Timeline
+├── music.track       # Music
+├── assets.txt        # Assets
+├── assets/           # Local assets
+└── shaders/          # Local shaders
+```
+
+### 2. Parallel Development
+Multiple developers can work on different demos without conflicts:
+```bash
+# Developer A: Main demo
+cd workspaces/main
+vim timeline.seq
+
+# Developer B: Experimental demo
+cd workspaces/experiments/christmas_demo
+vim timeline.seq
+```
+
+### 3. Easy Switching
+```bash
+# Build main demo
+cmake -B build -DDEMO_WORKSPACE=main
+./build/demo64k
+
+# Build test demo
+cmake -B build -DDEMO_WORKSPACE=test
+./build/test_demo
+```
+
+### 4. Clean Sharing
+Common resources in one place:
+```
+assets/common/
+├── shaders/
+│   ├── math/          # Shared by all
+│   └── common_uniforms/
+└── audio/
+    └── standard_drums.spec
+```
+
+### 5. Scalability
+Easy to add new demos:
+```bash
+./scripts/workspace.sh create party2025
+cd workspaces/party2025
+# Start developing...
+```
+
+## Migration Path
+
+### Backward Compatibility
+
+During transition, support both structures:
+```cmake
+if(EXISTS "${CMAKE_SOURCE_DIR}/workspaces/${DEMO_WORKSPACE}")
+  # New workspace structure
+  set(USING_WORKSPACES TRUE)
+else()
+  # Legacy flat structure
+  set(USING_WORKSPACES FALSE)
+endif()
+```
+
+### Gradual Migration
+
+1. **Phase 1:** Create workspace structure alongside existing
+2. **Phase 2:** Update build system to support both
+3. **Phase 3:** Move files to workspaces
+4. **Phase 4:** Remove legacy paths
+5. **Phase 5:** Update all documentation
+
+**Timeline:** 1-2 weeks for full migration
+
+## Trade-offs
+
+### Pros
+- Clear project organization
+- Parallel demo development
+- Clean resource sharing
+- Better onboarding for new devs
+- Scales to many demos
+
+### Cons
+- Initial migration effort
+- Build system complexity increases
+- More directories to navigate
+- Learning curve for contributors
+
+### Alternative Approaches
+
+**1. Monorepo with subprojects:**
+- Separate CMake projects per demo
+- More isolated but harder to share code
+
+**2. Configuration files only:**
+- Keep flat structure, use config to select files
+- Less clear, harder to understand ownership
+
+**3. Git branches per demo:**
+- Each demo is a branch
+- Conflicts when merging shared code
+
+**Chosen:** Workspace system (best balance)
+
+## Implementation Effort
+
+**Estimated time: 12-16 hours**
+
+- Phase 1: Create structure (2-3 hours)
+- Phase 2: Build system (4-5 hours)
+- Phase 3: Code updates (3-4 hours)
+- Phase 4: Documentation (2-3 hours)
+- Phase 5: Validation (1-2 hours)
+
+**Priority:** Medium (improves workflow, not blocking)
+
+## Success Criteria
+
+1. Both `main` and `test` workspaces build successfully
+2. Switching workspaces requires only CMake flag change
+3. Workspace-specific changes don't affect other workspaces
+4. Common shader changes affect all workspaces
+5. New workspace creation takes < 5 minutes
+6. All tests pass for both workspaces
+7. Documentation clear for new contributors
+
+## Related Files
+
+**New files:**
+- `workspaces/main/workspace.cfg` - Main demo config
+- `workspaces/test/workspace.cfg` - Test demo config
+- `cmake/ParseWorkspace.cmake` - Config parser
+- `scripts/workspace.sh` - Workspace CLI tool
+- `templates/workspace.cfg` - New workspace template
+
+**Modified files:**
+- `CMakeLists.txt` - Workspace support
+- `tools/asset_packer.cc` - Multi-path resolution
+- `src/gpu/shader_composer.cc` - Multi-path includes
+- `README.md` - Workspace documentation
+- `doc/HOWTO.md` - Build commands
+- `doc/CONTRIBUTING.md` - Workspace guidelines
+
+**Moved files:**
+- `assets/demo.seq` → `workspaces/main/timeline.seq`
+- `assets/music.track` → `workspaces/main/music.track`
+- `assets/final/demo_assets.txt` → `workspaces/main/assets.txt`
+- `assets/test_demo.*` → `workspaces/test/`
+- `assets/shaders/math/` → `assets/common/shaders/math/`
+
+## Notes
+
+- This is a **structural refactor**, not a feature
+- No runtime behavior changes
+- Enables future scalability
+- Makes project more professional
+- Good foundation for demoscene releases (multiple demos per repo)