## Project Rules
- Use existing patterns
- No refactors unless explicitly requested
- All changes must keep tests passing
- Prefer small, reviewable commits
- All `cmake --build` commands must use the `-j4` option for parallel building.
- 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`.

**Required steps (must complete ALL):**
1. Create effect files (.h, .cc, .wgsl)
2. Add shader to `workspaces/main/assets.txt`
3. Add `.cc` to CMakeLists.txt GPU_SOURCES (BOTH sections: headless and normal)
4. Include header in `src/gpu/demo_effects.h`
5. Add to timeline with `EFFECT +` (priority modifier is 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 only one CMakeLists.txt section (need BOTH headless and normal)
- Wrong asset ID (check assets.txt entry name → `ASSET_SHADER_<NAME>`)
- Forgetting to add to test file