# 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