2 files changed, 26 insertions, 12 deletions
diff --git a/tools/shadertoy/README.md b/tools/shadertoy/README.md
index e734684..d12865f 100644
--- a/tools/shadertoy/README.md
+++ b/tools/shadertoy/README.md
@@ -2,6 +2,8 @@
 
 Quick guide to convert ShaderToy shaders to demo effects.
 
+**For complete workflow:** See `doc/EFFECT_WORKFLOW.md` for full integration checklist.
+
 ## Quick Start (Automated)
 
 ```bash
@@ -95,16 +97,24 @@ In `src/gpu/demo_effects.h`:
 In `workspaces/main/timeline.seq`:
 ```
 SEQUENCE 0.0 0
-  EFFECT MyEffectEffect 0.0 10.0 0
+  EFFECT + MyEffectEffect 0.0 10.0
+```
+
+### 7. Update CMakeLists.txt
+
+Add effect source to `CMakeLists.txt` GPU_SOURCES (both headless and normal mode sections):
+```cmake
+src/gpu/effects/myeffect_effect.cc
 ```
 
-### 7. Update Tests
+### 8. Update Tests
 
-In `tests/test_demo_effects.cc`:
-- Add `"MyEffectEffect"` to test list
-- Increment `EXPECTED_*_COUNT`
+In `src/tests/gpu/test_demo_effects.cc`:
+- Add to `post_process_effects` list (lines 80-93) if it's a post-process effect
+- OR add to `scene_effects` list (lines 125-137) if it's a scene effect
+- Example: `{"MyEffectEffect", std::make_shared<MyEffectEffect>(fixture.ctx())},`
 
-### 8. Build & Test
+### 9. Build & Test
 
 ```bash
 cmake --build build -j4
diff --git a/tools/shadertoy/convert_shadertoy.py b/tools/shadertoy/convert_shadertoy.py
index 4956cfd..29eca1d 100755
--- a/tools/shadertoy/convert_shadertoy.py
+++ b/tools/shadertoy/convert_shadertoy.py
@@ -383,7 +383,7 @@ def main():
 
     print("✓ Files generated")
     print()
-    print("Next steps:")
+    print("Next steps (see doc/EFFECT_WORKFLOW.md for details):")
     print()
     print("1. Add shader to workspaces/main/assets.txt:")
     print(f"   shaders/{snake_name}.wgsl")
@@ -392,13 +392,17 @@ def main():
     print(f'   #include "gpu/effects/{snake_name}_effect.h"')
     print()
     print("3. Add to timeline in workspaces/main/timeline.seq:")
-    print(f"   EFFECT {effect_name}Effect 0.0 10.0 0")
+    print(f"   EFFECT + {effect_name}Effect 0.0 10.0")
     print()
-    print("4. Update tests/test_demo_effects.cc:")
-    print(f'   - Add "{effect_name}Effect" to test list')
-    print("   - Increment EXPECTED_*_COUNT")
+    print("4. Add to CMakeLists.txt GPU_SOURCES (both headless and normal mode):")
+    print(f"   src/gpu/effects/{snake_name}_effect.cc")
     print()
-    print("5. Build and test:")
+    print("5. Update src/tests/gpu/test_demo_effects.cc:")
+    print(f'   - Add "{{{effect_name}Effect", std::make_shared<{effect_name}Effect>(fixture.ctx())}}" to appropriate list')
+    print("   - Use post_process_effects (lines 80-93) for post-process effects")
+    print("   - Use scene_effects (lines 125-137) for scene effects")
+    print()
+    print("6. Build and test:")
     print("   cmake --build build -j4")
     print("   ./build/demo64k")
     print()