docs(mq_editor): document Explore and Contour interactive modes

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

1 files changed, 40 insertions, 2 deletions

diff --git a/tools/mq_editor/README.md b/tools/mq_editor/README.md
index 83cd28d..d79a2f8 100644
--- a/tools/mq_editor/README.md
+++ b/tools/mq_editor/README.md
@@ -9,7 +9,7 @@ open tools/mq_editor/index.html
 ```
 
 1. Click **Open WAV** (or **âš— Test WAV** for a built-in 440+660 Hz test signal)
-2. Click **Extract Partials**
+2. Click **Extract Partials** (optional — Explore/Contour modes work immediately after load)
 3. Press **1** to play synthesized, **2** to play original
 
 ## UI
@@ -52,16 +52,52 @@ Parameters are grouped into four sections in the toolbar.
 |-------|---------|-------------|
 | **Keep %** | 100% | Retain only the strongest N% of extracted partials by peak amplitude. |
 
+## Interactive Partial Creation
+
+Three ways to add partials beyond automatic extraction:
+
+### ⊕ Explore — Peak Tracking (key: `X`)
+
+Hover the mouse over any spectral peak in the spectrogram. The tracker
+snaps to the nearest detected peak and runs MQ tracking forward and
+backward from the cursor position, showing an **orange dashed preview**.
+Click to commit the partial.
+
+- Works immediately after WAV load (no extraction required)
+- Uses **Birth / Death / Phase Wt** params from the toolbar
+- Good for: strong peaks missed by global extraction, fine-grained control
+
+### ≋ Contour — Iso-Energy Tracking (key: `C`)
+
+Hover over any region of the spectrogram. The tracker follows the
+iso-energy contour at the energy level under the cursor (`Eâ‚€ = mag(t, f)`),
+frame by frame, without requiring a spectral peak. Preview shown in **cyan**.
+Click to commit.
+
+- Designed for **broad, diffuse bass regions** where no peaks are detected
+- Search window: ±15% in frequency; declares a miss if nearest bin deviates >15 dB
+- Spread is auto-detected on commit (naturally comes out large for broad regions)
+- Good for: bass smear, noisy resonances, sub-threshold energy
+
+Both modes are mutually exclusive. `Escape` exits either mode.
+Committed partials are prepended to the partial list with full undo support.
+
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
 | `1` | Play synthesized audio |
 | `2` | Play original audio |
+| `3` | Play selected partial alone |
 | `E` | Extract Partials |
+| `N` | New partial (flat 440 Hz, full duration) |
+| `X` | Toggle ⊕ Explore mode (peak tracking) |
+| `C` | Toggle ≋ Contour mode (iso-energy tracking) |
 | `P` | Toggle raw peak overlay |
 | `A` | Toggle mini-spectrum: original ↔ synthesized |
-| `Esc` | Deselect partial |
+| `Esc` | Exit explore/contour mode · deselect partial |
+| `Ctrl+Z` | Undo |
+| `Ctrl+Y` / `Ctrl+Shift+Z` | Redo |
 | Shift+scroll | Zoom time axis |
 | Scroll | Pan time axis |
 
@@ -170,6 +206,8 @@ For a partial at 440 Hz with `spread = 0.02`: `BW ≈ 8.8 Hz`, `r ≈ exp(−πÂ
   - [x] Mute / delete partials
   - [x] Per-partial resonator synthesis mode (Synth tab toggle)
   - [x] Global LP/HP post-synthesis filter sliders with Hz display
+  - [x] Explore mode: interactive peak tracking from mouse position (`X`)
+  - [x] Contour mode: iso-energy tracking for bass/diffuse regions (`C`)
 - [ ] Phase 4: Export (.spec + C++ code generation)
 
 ## See Also