1 files changed, 58 insertions, 0 deletions
diff --git a/doc/HEADLESS_MODE.md b/doc/HEADLESS_MODE.md
new file mode 100644
index 0000000..35098b1
--- /dev/null
+++ b/doc/HEADLESS_MODE.md
@@ -0,0 +1,58 @@
+// Headless Mode Documentation
+// Workspace: demo (shared across all workspaces)
+
+# Headless Mode
+
+Minimal GPU/platform stubs for testing without graphics.
+
+## Use Cases
+
+- CI/CD without GPU
+- Audio/tracker iteration
+- Timeline validation
+- Fast testing cycles
+
+## Build
+
+```bash
+cmake -B build_headless -DDEMO_HEADLESS=ON
+cmake --build build_headless -j4
+```
+
+Or use the test script:
+```bash
+./scripts/test_headless.sh
+```
+
+## Usage
+
+```bash
+# 30s simulation (default)
+./build_headless/demo64k --headless
+
+# Custom duration
+./build_headless/demo64k --headless --duration 60
+
+# Audio validation
+./build_headless/demo64k --dump_wav test.wav
+```
+
+Progress printed every 5s.
+
+## Implementation
+
+- **GPU stub:** Validates lifecycle, maintains MainSequence
+- **Platform stub:** Simulates 60Hz time progression
+- **Main loop:** Audio updates without rendering
+
+## vs STRIP_EXTERNAL_LIBS
+
+| Feature | HEADLESS | STRIP_EXTERNAL_LIBS |
+|---------|----------|---------------------|
+| Compiles | Yes | Yes |
+| Runs | Yes | No |
+| Audio | Full | No-op |
+| Timeline | Full | No |
+| Tests | Pass | Fail |
+
+See `src/gpu/headless_gpu.cc` and `src/platform/headless_platform.cc` for details.