Documentation: Update for file hierarchy reorganization

Updated docs to reflect February 13, 2026 changes:

- doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md: Complete summary
- doc/WORKSPACE_SYSTEM.md: Current structure, workspace.cfg format
- doc/SHADER_REUSE_INVESTIGATION.md: Implementation status
- PROJECT_CONTEXT.md: Workspace and shader system updates

Key changes documented:
- src/app/ application structure
- workspaces/{music,weights,obj,shaders}/ layout
- common/shaders/ shared shader system
- Eliminated 36 duplicate shaders
- Asset packer path normalization

handoff(Claude): Documentation updated for hierarchy cleanup

1 files changed, 202 insertions, 0 deletions

diff --git a/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md b/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md
new file mode 100644
index 0000000..8af5efd
--- /dev/null
+++ b/doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md
@@ -0,0 +1,202 @@
+# File Hierarchy Cleanup - February 13, 2026
+
+## Summary
+
+Comprehensive reorganization of project file structure for improved maintainability and code reuse.
+
+---
+
+## Changes Implemented
+
+### 1. Application Entry Points → `src/app/`
+
+**Before:**
+```
+src/
+  main.cc
+  stub_main.cc
+  test_demo.cc
+```
+
+**After:**
+```
+src/app/
+  main.cc
+  stub_main.cc
+  test_demo.cc
+```
+
+**Impact:** Cleaner src/ directory, separates application code from libraries.
+
+---
+
+### 2. Workspace Reorganization
+
+**Before:**
+```
+workspaces/main/
+  assets/music/*.spec
+  shaders/*.wgsl
+  obj/*.obj
+
+assets/
+  demo.seq
+  music.track
+  originals/
+  common/
+  final/
+```
+
+**After:**
+```
+workspaces/{main,test}/
+  music/        # Audio samples (.spec)
+  weights/      # CNN binary weights (.bin)
+  obj/          # 3D models (.obj)
+  shaders/      # Workspace-specific WGSL only
+
+common/
+  shaders/      # Shared WGSL utilities
+    math/
+    render/
+    compute/
+
+tools/
+  originals/    # Source audio files
+  test_demo.seq
+  test_demo.track
+```
+
+**Removed:**
+- `assets/` directory (legacy structure)
+- `assets/common/` (replaced by `common/`)
+- `assets/final/` (superseded by workspaces)
+- `assets/originals/` → `tools/originals/`
+
+---
+
+### 3. Shared Shader System
+
+**Problem:** 36 duplicate shader files across workspaces (byte-identical).
+
+**Solution:** Implemented Option 1 from `SHADER_REUSE_INVESTIGATION.md`.
+
+**Structure:**
+```
+common/shaders/
+  common_uniforms.wgsl
+  lighting.wgsl
+  passthrough.wgsl
+  ray_box.wgsl
+  ray_triangle.wgsl
+  sdf_primitives.wgsl
+  skybox.wgsl
+  math/
+    common_utils.wgsl
+    noise.wgsl
+    sdf_shapes.wgsl
+    sdf_utils.wgsl
+  render/
+    lighting_utils.wgsl
+    scene_query_bvh.wgsl
+    scene_query_linear.wgsl
+    shadows.wgsl
+  compute/
+    gen_blend.wgsl
+    gen_grid.wgsl
+    gen_mask.wgsl
+    gen_noise.wgsl
+    gen_perlin.wgsl
+```
+
+**Reference in assets.txt:**
+```
+SHADER_COMMON_UNIFORMS, NONE, ../../common/shaders/common_uniforms.wgsl
+SHADER_MATH_NOISE, NONE, ../../common/shaders/math/noise.wgsl
+```
+
+**Asset Packer Enhancement:**
+- Added `#include <filesystem>` for path normalization
+- Implemented `lexically_normal()` to resolve `../../common/` references
+- Cross-platform path handling for workspace-relative includes
+
+---
+
+## Updated Files
+
+### Configuration
+- `workspaces/main/workspace.cfg` - Updated asset_dirs and shader_dirs
+- `workspaces/test/workspace.cfg` - Updated asset_dirs and shader_dirs
+- `workspaces/main/assets.txt` - Common shader references
+- `workspaces/test/assets.txt` - Common shader references
+
+### Build System
+- `cmake/DemoExecutables.cmake` - src/app/ paths, test_demo paths
+- `cmake/DemoCodegen.cmake` - Removed legacy fallback paths
+- `cmake/Validation.cmake` - Workspace shader paths
+
+### Tools
+- `tools/asset_packer.cc` - Filesystem path normalization
+- `scripts/gen_spectrograms.sh` - tools/originals/ paths
+- `scripts/train_cnn_v2_full.sh` - workspaces/main/weights/ paths
+- `training/export_cnn_v2_weights.py` - workspaces/main/weights/ paths
+
+### Application
+- `src/app/main.cc` - Hot-reload workspace paths
+
+---
+
+## Metrics
+
+**File Reduction:**
+- Removed 36 duplicate shader files
+- Deleted legacy assets/ structure (~70 files)
+- Net: ~100 files eliminated
+
+**Disk Space:**
+- Common shaders: 20 files
+- Per-workspace shaders: ~30-35 files
+- Saved: ~36 shader duplicates
+
+**Workspace Structure:**
+```
+workspaces/main/: 31 shaders (workspace-specific)
+workspaces/test/: 19 shaders (workspace-specific)
+common/: 20 shaders (shared)
+Total unique: 70 shaders (vs 106 before)
+```
+
+---
+
+## Benefits
+
+1. **Single Source of Truth:** Common shaders in one location
+2. **No Duplication:** Bug fixes apply everywhere automatically
+3. **Clear Separation:** Common vs workspace-specific code
+4. **Size Optimization:** Important for 64k target
+5. **Maintainability:** Easier to understand and modify
+6. **Workspace Isolation:** Each workspace still self-contained for specific content
+
+---
+
+## Migration Notes
+
+**For New Workspaces:**
+1. Create `workspaces/new_workspace/` with subdirs: `music/`, `weights/`, `obj/`, `shaders/`
+2. Reference common shaders: `../../common/shaders/...`
+3. Add workspace-specific shaders to local `shaders/`
+4. Update `workspace.cfg`: `asset_dirs = ["music/", "weights/", "obj/"]`
+
+**For Common Shader Changes:**
+- Edit files in `common/shaders/`
+- Changes apply to all workspaces immediately
+- Run full build to verify all workspaces
+
+---
+
+## Documentation Updated
+
+- `doc/WORKSPACE_SYSTEM.md` - New structure reflected
+- `doc/SHADER_REUSE_INVESTIGATION.md` - Implementation status
+- `doc/PROJECT_CONTEXT.md` - Current project state
+- `doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md` - This document