From 2e492789582cd5cee46fa40c66f113469df69a0d Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sat, 31 Jan 2026 16:00:10 +0100
Subject: 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.
---
 HOWTO.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

(limited to 'HOWTO.md')

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:
 
-- 
cgit v1.2.3