docs: Capture Sequence system and debugging protocols

Updates HOWTO.md with instructions for the --seek flag and assets/demo.seq editing. Updates CONTRIBUTING.md with the protocol for adding and registering new visual effects.

2 files changed, 36 insertions, 1 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index eb18786..3c78f18 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -146,3 +146,14 @@ types.
 
 don't.
 
+## Development Protocols
+
+### Adding a New Visual Effect
+
+1.  **Implement**: Create or update a class in `src/gpu/demo_effects.cc` (and declare in `demo_effects.h`) that inherits from `Effect`.
+    -   Implement `init()` for one-time resource setup (e.g., using the asset system).
+    -   Implement `compute()` if you need GPU-side physics or state updates.
+    -   Implement `render()` to record WebGPU draw commands.
+2.  **Register**: Add an `EFFECT` entry to `assets/demo.seq` specifying the class name, start/end times, and any constructor arguments.
+3.  **Verify**: Build with `DEMO_ALL_OPTIONS=ON` and use `--seek` to test your effect at its specific timestamp.
+
diff --git a/HOWTO.md b/HOWTO.md
index f9cce91..afb8459 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -49,7 +49,31 @@ cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
 cmake --build build
 ```
 
-### Windows (Wine)
+## Debugging
+
+### Seeking / Fast-Forward
+In non-stripped builds, you can jump to any timestamp in the demo. This will simulate all audio logic and GPU physics (compute shaders) frame-by-frame from the start until the target time, then begin real-time playback.
+
+```bash
+./build/demo64k --seek 15.5
+```
+
+## Demo Choreography
+
+### Sequence Compiler
+The demo timeline is managed via a textual description in `assets/demo.seq`. This file is transpiled into C++ code during the build process.
+
+**Format:**
+```text
+# Starts a new sequence layer (global_start, priority)
+SEQUENCE 0.0 0
+  # Adds an effect to the sequence (ClassName, local_start, local_end, priority, [constructor_args...])
+  EFFECT HeptagonEffect 0.0 60.0 0
+```
+
+To update the demo's timing or layering, simply edit `assets/demo.seq` and rebuild.
+
+## Tools
 
 If you are on macOS and want to test the Windows build: