From 70c64867baa30c83334559d3023153dfe3f9ff79 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 10:43:11 +0100
Subject: docs: Simplify all design docs (50% reduction, 1687 lines removed)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Consolidated and streamlined all documentation:

**Merged:**
- PROCEDURAL.md → deleted (content in ASSET_SYSTEM.md)
- FETCH_DEPS.md → BUILD.md (dependencies section)

**Simplified (line reductions):**
- HOWTO.md: 468→219 (53%)
- CONTRIBUTING.md: 453→173 (62%)
- SPECTRAL_BRUSH_EDITOR.md: 497→195 (61%)
- SEQUENCE.md: 355→197 (45%)
- CONTEXT_MAINTENANCE.md: 332→200 (40%)
- test_demo_README.md: 273→122 (55%)
- ASSET_SYSTEM.md: 271→108 (60%)
- MASKING_SYSTEM.md: 240→125 (48%)
- 3D.md: 196→118 (40%)
- TRACKER.md: 124→76 (39%)
- SCENE_FORMAT.md: 59→49 (17%)
- BUILD.md: 83→69 (17%)

**Total:** 3344→1657 lines (50.4% reduction)

**Changes:**
- Removed verbose examples, redundant explanations, unimplemented features
- Moved detailed task plans to TODO.md (single source of truth)
- Consolidated coding style rules
- Kept essential APIs, syntax references, technical details

**PROJECT_CONTEXT.md:**
- Added "Design Docs Quick Reference" with 2-3 line summaries
- Removed duplicate task entries
- All design docs now loaded on-demand via Read tool

Result: Context memory files reduced from 31.6k to ~15k tokens.
---
 doc/SEQUENCE.md | 286 +++++++++++++-------------------------------------------
 1 file changed, 64 insertions(+), 222 deletions(-)

(limited to 'doc/SEQUENCE.md')

diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md
index 7aa951d..954c816 100644
--- a/doc/SEQUENCE.md
+++ b/doc/SEQUENCE.md
@@ -4,45 +4,13 @@ This document describes the `.seq` file format used to define demo timelines.
 
 ## Overview
 
-Sequence files (`.seq`) define the timeline and layering of visual effects in the demo. They are compiled by `seq_compiler` into C++ code at build time.
-
-## File Location
+Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time.
 
+**Locations:**
 - Demo sequence: `assets/demo.seq`
 - Compiler: `tools/seq_compiler.cc`
 - Generated output: `src/generated/timeline.cc`
 
-## Command Line Usage
-
-### Basic Compilation
-```bash
-./build/seq_compiler assets/demo.seq src/generated/timeline.cc
-```
-
-### Validation Only
-```bash
-./build/seq_compiler assets/demo.seq
-```
-Validates syntax without generating code.
-
-### Gantt Chart Visualization
-
-**ASCII Gantt Chart:**
-```bash
-./build/seq_compiler assets/demo.seq --gantt=timeline.txt
-```
-
-**HTML/SVG Gantt Chart (Recommended):**
-```bash
-./build/seq_compiler assets/demo.seq --gantt-html=timeline.html
-```
-Open `timeline.html` in browser for interactive visualization with hover tooltips.
-
-**Combined Modes:**
-```bash
-./build/seq_compiler assets/demo.seq timeline.cc --gantt=t.txt --gantt-html=t.html
-```
-
 ---
 
 ## Syntax Reference
@@ -51,41 +19,32 @@ Open `timeline.html` in browser for interactive visualization with hover tooltip
 ```
 # BPM 120
 ```
-Specifies beats per minute for the demo. Used to convert beat notation to seconds.
+Specifies beats per minute. Used to convert beat notation to seconds.
 
 ### END_DEMO Directive
 ```
 END_DEMO <time>
 ```
-Specifies when the demo should automatically exit (optional).
-- If not specified, demo runs indefinitely until user closes window
-- Supports beat notation (e.g., `64b`) or seconds (e.g., `32.0`)
+Optional auto-exit time. Supports beat notation (`64b`) or seconds (`32.0`).
 
 ### SEQUENCE Declaration
 ```
 SEQUENCE <global_start> <priority> ["optional_name"] [optional_end]
-  EFFECT <EffectClassName> <local_start> <local_end> <priority> [constructor_args...]
+  EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
 ```
 
 **Parameters:**
-- `global_start`: When this sequence starts (beats or seconds)
-- `priority`: Render order between sequences (higher = rendered later/on top)
-  - Use 0-9 for scene effects
-  - Use 10+ for post-processing
-- `"optional_name"`: Optional human-readable name in quotes (e.g., `"Opening Scene"`)
-  - If specified, the name will be displayed in Gantt charts for better readability
-  - Helps identify sequences when visualizing complex timelines
-- `[optional_end]`: Optional end time in brackets (e.g., `[30.0]`)
-  - If specified, all effects in the sequence will be forcefully ended at this time
-  - Time is relative to the sequence start
-  - If omitted, effects run until their individual end times
+- `global_start`: Sequence start time (beats or seconds)
+- `priority`: Render order (0-9 for scenes, 10+ for post-processing)
+- `"optional_name"`: Optional display name for Gantt charts
+- `[optional_end]`: Optional sequence end time (forces effect termination)
 
 **Examples:**
 ```
-SEQUENCE 0 0                        # Basic sequence (no name, no explicit end)
+SEQUENCE 0 0                        # Basic sequence
 SEQUENCE 0 0 "Intro"                # Named sequence
-SEQUENCE 0 0 [5.0]                  # Sequence with explicit end time
-SEQUENCE 0 0 "Action Scene" [10.0]  # Named sequence with explicit end time
+SEQUENCE 0 0 [5.0]                  # Explicit end time
+SEQUENCE 0 0 "Action Scene" [10.0]  # Both name and end time
 ```
 
 ### EFFECT Declaration
@@ -93,29 +52,20 @@ SEQUENCE 0 0 "Action Scene" [10.0]  # Named sequence with explicit end time
 EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
 ```
 
+**Priority Modifiers:**
+- `+`: Increment priority (or start at 0 if first)
+- `=`: Keep same priority as previous
+- `-`: Decrement priority (or start at -1 if first, for backgrounds)
+
 **Parameters:**
-- Priority modifier (one of):
-  - `+`: Increment priority (or start at 0 if first effect)
-  - `=`: Keep same priority as previous effect
-  - `-`: Decrement priority (or start at -1 if first effect, for background layers)
-- `EffectClassName`: C++ class name (must be declared in `demo_effects.h`)
-- `local_start`: Start time relative to sequence start (beats or seconds)
-- `local_end`: End time relative to sequence start (beats or seconds)
-- `constructor_args`: Optional additional parameters (rarely used)
-
-**Priority System:**
-- Effects are assigned priorities based on their order in the file
-- First effect: `+` starts at 0, `-` starts at -1, `=` starts at 0
-- Subsequent effects: `+` increments, `=` keeps same, `-` decrements
-- Priorities determine render order (lower = drawn first/background)
-- Effects should be listed in desired priority order within each sequence
+- `EffectClassName`: C++ class from `demo_effects.h`
+- `local_start`, `local_end`: Time relative to sequence start
+- `constructor_args`: Optional (rarely used, most effects use standard params only)
 
 ---
 
 ## Time Notation
 
-The sequence file supports flexible time notation:
-
 | Notation | Example | Description |
 |----------|---------|-------------|
 | Integer beats | `0`, `64`, `128` | No decimal point = beats |
@@ -123,118 +73,33 @@ The sequence file supports flexible time notation:
 | Decimal seconds | `0.0`, `32.0`, `64.0` | Decimal point = seconds |
 | Explicit seconds | `32.0s`, `64.0s` | Suffix 's' = seconds |
 
-**Examples at 120 BPM:**
-- Beat 0 = 0.0 seconds
-- Beat 64 = 32.0 seconds
-- Beat 120 = 60.0 seconds
+**At 120 BPM:** Beat 64 = 32.0 seconds, Beat 120 = 60.0 seconds
 
 ---
 
-## Effect System
-
-### Constructor Parameters
-
-**Standard Parameters (ALL effects receive these automatically):**
-- `WGPUDevice device`: WebGPU device handle
-- `WGPUQueue queue`: Command queue for GPU operations
-- `WGPUTextureFormat format`: Surface texture format
-
-Most effects only use these standard parameters. If an effect needs custom initialization, parameters are specified after the priority field.
+## Runtime Parameters
 
-**Example (hypothetical custom effect):**
-```
-EFFECT CustomEffect 0 10 0 1.5 "param"
-```
-Translates to:
-```cpp
-std::make_shared<CustomEffect>(device, queue, format, 1.5, "param")
-```
-
-### Runtime Parameters
-
-All effects receive these dynamic parameters every frame in their `render()` method:
+All effects receive these parameters every frame in `render()`:
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `time` | float | Global time in seconds (from demo start) |
-| `beat` | float | Current beat fraction (0.0 to 1.0 within each beat) |
-| `intensity` | float | Audio peak intensity (0.0 to 1.0, for beat detection) |
-| `aspect_ratio` | float | Screen width/height ratio |
-
----
-
-## Available Effects
-
-### Scene Effects
-Render 3D geometry to the framebuffer with depth testing.
-
-#### HeptagonEffect
-Animated geometric heptagon shape.
-- **Uses:** `time` (animation), `beat` (rotation), `aspect_ratio` (projection)
-
-#### ParticlesEffect
-GPU-simulated particle system.
-- **Uses:** `time` (physics), `intensity` (emission rate)
-
-#### Hybrid3DEffect
-3D objects with camera movement.
-- **Uses:** `time` (camera paths), `beat` (object animation), `aspect_ratio`
-
-#### FlashCubeEffect
-Large background cube with Perlin noise texture.
-- **Uses:** `time` (rotation), `intensity` (flash trigger on beat hits)
-- **Note:** Typically used with priority -1 for background layer
-
-### Post-Process Effects
-Full-screen shaders applied in priority order after scene rendering.
-
-#### GaussianBlurEffect
-Gaussian blur with beat pulsation.
-- **Uses:** `intensity` (blur size pulsates 0.5x-2.5x based on audio peak)
-
-#### SolarizeEffect
-Color inversion with alternating red/blue tints.
-- **Uses:** `time` (alternates every 2 seconds between color schemes)
-
-#### ChromaAberrationEffect
-RGB channel separation effect.
-- **Uses:** `time` (animation), `intensity` (separation amount)
-
-#### ThemeModulationEffect
-Brightness cycling (bright/dark alternation).
-- **Uses:** `time` (cycles every 8 seconds: 1.0 bright to 0.35 dark)
-
-#### FadeEffect
-Fade to/from black.
-- **Uses:** `time` (fades in first 2s, fades out after 36s - hardcoded timing)
-
-#### FlashEffect
-White flash on strong beat hits.
-- **Uses:** `intensity` (triggers flash when > 0.7, exponential decay)
+| `time` | float | Global time in seconds |
+| `beat` | float | Current beat fraction (0.0-1.0) |
+| `intensity` | float | Audio peak (0.0-1.0, for beat sync) |
+| `aspect_ratio` | float | Screen width/height |
 
 ---
 
-## Tips & Best Practices
+## Priority System
 
-### Layering
-- Scene effects render to framebuffer with depth testing
-- Post-processing effects are full-screen shaders applied in sequence priority order
-- Use negative priority for background elements (skybox, far objects)
-- Higher sequence priority = later in post-process chain (rendered on top)
+**Scene Effects (0-9):**
+- `-1`: Background (skybox, far objects)
+- `0-5`: Midground (main geometry)
+- `6-9`: Foreground (overlays, particles)
 
-### Priority Guidelines
-- **Scene Effects:** priority 0-9
-  - Background: -1 (e.g., skybox, distant objects)
-  - Midground: 0-5 (main geometry)
-  - Foreground: 6-9 (overlays, particles)
-- **Post-Process:** priority 10+
-  - Apply in order: blur → distortion → color grading
-
-### Timing
-- Use beat notation for music-synchronized effects
-- Use seconds for absolute timing
-- Keep effect durations reasonable (avoid very short < 0.1s unless intentional)
-- Use sequence `[end_time]` to forcefully terminate long-running effects
+**Post-Process (10+):**
+- Applied in order: blur → distortion → color grading
+- Higher priority = rendered later (on top)
 
 ---
 
@@ -243,16 +108,16 @@ White flash on strong beat hits.
 ### Basic Sequence
 ```
 SEQUENCE 0 0
-  EFFECT + FlashEffect 0.0 0.5     # Priority 0 (first with +)
-  EFFECT + HeptagonEffect 0.2 10   # Priority 1 (increment)
+  EFFECT + FlashEffect 0.0 0.5     # Priority 0
+  EFFECT + HeptagonEffect 0.2 10   # Priority 1
 ```
 
-### Same Priority (Layered Effects)
+### Same Priority Layering
 ```
 SEQUENCE 0 0
   EFFECT + Flash 0.0 0.5           # Priority 0
-  EFFECT = Fade 0.1 0.3            # Priority 0 (same as Flash)
-  EFFECT + Other 0.2 3             # Priority 1 (increment)
+  EFFECT = Fade 0.1 0.3            # Priority 0 (same layer)
+  EFFECT + Other 0.2 3             # Priority 1
 ```
 
 ### Background Elements
@@ -263,93 +128,70 @@ SEQUENCE 0 0
   EFFECT + MainEffect 0 10         # Priority 0 (foreground)
 ```
 
-### Sequence with Explicit End Time
+### Sequence with Explicit End
 ```
 SEQUENCE 8b 0 [5.0]
-  EFFECT + Particles 0 120         # Would run 120s, but sequence ends at 5s
+  EFFECT + Particles 0 120         # Runs until 5s (sequence end)
 ```
 
 ### Post-Processing Chain
 ```
 SEQUENCE 0 10
-  EFFECT + GaussianBlur 0 60       # Priority 0 (applied first)
-  EFFECT + ChromaAberration 0 60   # Priority 1 (applied second)
-  EFFECT + Solarize 0 60           # Priority 2 (applied last)
+  EFFECT + GaussianBlur 0 60       # Applied first
+  EFFECT + ChromaAberration 0 60   # Applied second
+  EFFECT + Solarize 0 60           # Applied last
 ```
 
-### Music-Synchronized Effects
+### Music-Synchronized
 ```
 # BPM 120
-SEQUENCE 0b 0      # Start at beat 0 (0.0s)
-  EFFECT + Flash 0b 1b             # Flash from beat 0 to beat 1 (0-0.5s)
-  EFFECT + Heptagon 4b 8b          # Main effect from beat 4 to 8 (2-4s)
+SEQUENCE 0b 0
+  EFFECT + Flash 0b 1b             # Beat 0-1 (0-0.5s)
+  EFFECT + Heptagon 4b 8b          # Beat 4-8 (2-4s)
 ```
 
 ---
 
-## Debugging & Visualization
+## Visualization
 
 ### Gantt Charts
 
-Gantt charts help visualize the timeline structure:
-
-**ASCII Chart (Terminal-Friendly):**
-```
-Time (s): 0    5    10   15   20
-          |----|----|----|----|----|
-
-SEQ@0s [pri=0]
-          ████████████████████████  (0-20s)
-  FlashEffect [pri=1]
-          ▓▓··················  (0-1s)
-  HeptagonEffect [pri=0]
-          ▓▓▓▓▓▓▓▓▓▓▓▓········  (0-10s)
+**ASCII Chart (Terminal):**
+```bash
+./build/seq_compiler assets/demo.seq --gantt=timeline.txt
 ```
 
-**HTML/SVG Chart (Interactive):**
-- Color-coded sequences and effects
-- Hover tooltips with full details
-- Invalid time ranges highlighted in red
-- Professional dark theme
-- Zoom/pan support
-- Easy to share or present
-
-### Validation
+**HTML/SVG Chart (Recommended):**
+```bash
+./build/seq_compiler assets/demo.seq --gantt-html=timeline.html
+```
+Interactive visualization with hover tooltips, color coding, and zoom/pan.
 
-Run validation without code generation to catch syntax errors:
+### Validation Only
 ```bash
 ./build/seq_compiler assets/demo.seq
-# Output: "Validation successful: 14 sequences, explicit end time."
 ```
-
-### Common Issues Caught by Validation
-- Invalid time ranges (end < start)
-- Missing effect classes
-- Syntax errors
-- Malformed time notation
+Validates syntax without generating code.
 
 ---
 
-## Integration with Build System
+## Integration
 
-The sequence compiler is automatically invoked during build via CMake:
+CMake automatically invokes the compiler on `assets/demo.seq` changes:
 
 ```cmake
 add_custom_command(
   OUTPUT ${GENERATED_DIR}/timeline.cc
   COMMAND seq_compiler assets/demo.seq ${GENERATED_DIR}/timeline.cc
   DEPENDS assets/demo.seq
-  COMMENT "Compiling demo sequence..."
 )
 ```
 
-Editing `assets/demo.seq` triggers automatic recompilation and rebuilds affected targets.
-
 ---
 
 ## See Also
 
-- `doc/HOWTO.md` - Building and running the demo
-- `doc/CONTRIBUTING.md` - Coding guidelines
 - `assets/demo.seq` - Current demo timeline
 - `src/gpu/demo_effects.h` - Available effect classes
+- `doc/EFFECTS_CATALOG.md` - Detailed effect reference (if needed)
+- `doc/HOWTO.md` - Building and running
-- 
cgit v1.2.3