docs: complete beat-based timing documentation

Updated all affected documentation files:
- UNIFORM_BUFFER_GUIDELINES.md: New CommonUniforms example
- ARCHITECTURE.md: Beat-based timing section
- EFFECT_WORKFLOW.md: Available uniforms reference
- CONTRIBUTING.md: Updated uniform buffer checklist

handoff(Claude): Beat-based timing system fully implemented and documented.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 19 insertions, 4 deletions

diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
index 97413de..4c36ec5 100644
--- a/doc/ARCHITECTURE.md
+++ b/doc/ARCHITECTURE.md
@@ -18,11 +18,26 @@ Detailed system architecture for the 64k demo project.
 
 **Effect**: Abstract base for visual elements. Supports `compute` and `render` phases.
 
-**Sequence**: Timeline of effects with start/end times.
+**Sequence**: Timeline of effects with start/end times defined in beats.
 
 **MainSequence**: Top-level coordinator and framebuffer manager.
 
-**seq_compiler**: Transpiles workspace `timeline.seq` into C++ `timeline.cc`.
+**seq_compiler**: Transpiles workspace `timeline.seq` (beat-based) into C++ `timeline.cc` (seconds).
+
+### Beat-Based Timing
+
+**Timeline Notation**: Sequences authored in musical beats (default) or explicit seconds (`s` suffix).
+
+**Runtime Conversion**: Beats → seconds at compile time using BPM. Effects activate at physical seconds.
+
+**Uniform Timing**: Effects receive both:
+- `time` - Physical seconds (constant, unaffected by tempo)
+- `beat_time` - Musical beats (from audio playback clock)
+- `beat_phase` - Fractional beat 0.0-1.0
+
+**Tempo Separation**: Variable tempo scales `music_time` for audio triggering only. Visual rendering uses constant physical time with optional beat synchronization.
+
+See `doc/BEAT_TIMING.md` for details.
 
 ---
 
@@ -42,10 +57,10 @@ Detailed system architecture for the 64k demo project.
 Real-time additive synthesis from spectrograms via FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method.
 
 ### Variable Tempo
-Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch.
+Music time abstraction with configurable `tempo_scale`. Tempo changes don't affect pitch. **Visual effects unaffected** - they use physical time, not tempo-scaled music time.
 
 ### Event-Based Tracker
-Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling.
+Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling. Triggers based on `music_time` (tempo-scaled).
 
 ### Backend Abstraction
 `AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering).