## Project Rules
- Use existing patterns
- No refactors unless explicitly requested
- All changes must keep tests passing
- Prefer small, reviewable commits. Don't sign commits with "Co-Authored-By: Claude..."
- All `cmake --build` commands must use the `-j4` option for parallel building.
- Medium/large sub-system changes require top-level doc update (summarize, streamline, archive).
- after a task, a 'big' final commit should contain a short handoff tag like "handoff(Gemini):..." if you're gemini-cli, or "handoff(Claude): ..." if you're claude-code.

## Adding Visual Effects

**IMPORTANT:** When adding new visual effects, follow the complete workflow in `doc/EFFECT_WORKFLOW.md`.

**Simple post-process (WgslEffect path — no .cc, no CMake):**
1. Create `src/effects/<name>.wgsl`
2. Add shader to `workspaces/main/assets.txt`
3. Create `src/effects/<name>_effect.h` as thin wrapper over `WgslEffect`
4. Add extern to `shaders.h` / `shaders.cc`
5. Include header in `src/gpu/demo_effects.h`
6. Add to test list in `src/tests/gpu/test_demo_effects.cc`
7. Add to timeline with `EFFECT +` (priority modifier REQUIRED)
8. Build and verify: `cmake --build build -j4 && cd build && ./test_demo_effects`

**Complex effects (custom uniforms / 3D / compute — full class):**
1. Create effect files (.h, .cc, .wgsl)
2. Add shader to `workspaces/main/assets.txt`
3. Add `.cc` to `cmake/DemoSourceLists.cmake` COMMON_GPU_EFFECTS
4. Include header in `src/gpu/demo_effects.h`
5. Add to timeline with `EFFECT +` (priority modifier REQUIRED)
6. Add to test list in `src/tests/gpu/test_demo_effects.cc`
7. Build and verify: `cmake --build build -j4 && cd build && ./test_demo_effects`

**Common mistakes to avoid:**
- Missing priority modifier in timeline (`EFFECT` must be `EFFECT +`, `EFFECT =`, or `EFFECT -`)
- Adding `.cc` to CMake for WgslEffect thin wrappers (not needed)
- Wrong asset ID (check assets.txt entry name → `ASSET_SHADER_<NAME>`)
- Forgetting to add to test file