docs: document CLASS_TO_HEADER override in EFFECT_WORKFLOW

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/EFFECT_WORKFLOW.md b/doc/EFFECT_WORKFLOW.md
index 5d6f017..ab2d6c8 100644
--- a/doc/EFFECT_WORKFLOW.md
+++ b/doc/EFFECT_WORKFLOW.md
@@ -325,6 +325,16 @@ class My3DEffect : public Effect {
 - Pipeline format doesn't match framebuffer (use RGBA8Unorm)
 - Missing texture view or null resource
 
+**Build Error: generated `timeline.cc` includes wrong header (e.g. `ntsc_yiq_effect.h`)**
+- Occurs when multiple effect classes share one header file (e.g. `Ntsc` and `NtscYiq` both in `ntsc_effect.h`)
+- `seq_compiler.py` derives the header from the class name by default
+- Fix: add an entry to `CLASS_TO_HEADER` in `tools/seq_compiler.py`:
+  ```python
+  CLASS_TO_HEADER = {
+      'NtscYiq': 'ntsc',   # NtscYiq lives in ntsc_effect.h alongside Ntsc
+  }
+  ```
+
 ---
 
 ## See Also