1 files changed, 67 insertions, 8 deletions

diff --git a/tools/mq_editor/README.md b/tools/mq_editor/README.md
index c1f2732..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
@@ -25,11 +25,62 @@ open tools/mq_editor/index.html
 
 ## Parameters
 
-- **Hop Size:** 64–1024 samples (default 256)
-- **Threshold:** dB floor for peak detection (default −60 dB)
-- **Prominence:** Min dB height of a peak above its surrounding "valley floor" (default 1.0 dB). Filters out insignificant local maxima.
-- **f·Power:** checkbox — weight spectrum by frequency (`f·FFT_Power(f)`) before peak detection, accentuating high-frequency peaks
-- **Keep %:** slider to limit how many partials are shown/synthesized
+Parameters are grouped into four sections in the toolbar.
+
+### STFT
+| Param | Default | Description |
+|-------|---------|-------------|
+| **Hop** | 256 | STFT hop size in samples. Smaller = finer time resolution, more frames, slower. |
+
+### Peak Detection
+| Param | Default | Description |
+|-------|---------|-------------|
+| **Threshold (dB)** | −20 | Minimum spectral peak amplitude. Peaks below this are ignored. |
+| **Prominence (dB)** | 1.0 | How much a peak must rise above its surrounding valley. Suppresses weak shoulders. |
+| **f·Power** | off | Weight spectrum by `f × Power(f)` before detection. Boosts high-frequency peaks relative to low-frequency ones. |
+
+### Tracking
+| Param | Default | Description |
+|-------|---------|-------------|
+| **Birth** | 3 | Frames a candidate must persist before becoming a partial. Higher = fewer spurious bursts. |
+| **Death** | 5 | Frames a partial can go unmatched before termination. Higher = bridges short gaps. |
+| **Phase Wt** | 2.0 | Weight of phase prediction error in the peak-matching cost function. Higher = stricter phase coherence. |
+| **Min Len** | 10 | Minimum frame count for a partial to survive after tracking. Discards very short partials. |
+
+### Filter
+| Param | Default | Description |
+|-------|---------|-------------|
+| **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
 
@@ -37,10 +88,16 @@ open tools/mq_editor/index.html
 |-----|--------|
 | `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 |
 
@@ -123,7 +180,7 @@ For a partial at 440 Hz with `spread = 0.02`: `BW ≈ 8.8 Hz`, `r ≈ exp(−πÂ
 
 1. **STFT:** Overlapping Hann windows, radix-2 FFT
 2. **Peak Detection:** Local maxima above threshold + parabolic interpolation. Includes **Prominence Filtering** (rejects peaks not significantly higher than surroundings). Optional `f·Power(f)` weighting.
-3. **Forward Tracking:** Birth/death/continuation with frequency-dependent tolerance. Includes **Predictive Kinematic Tracking** (uses velocity to track rapidly moving partials).
+3. **Forward Tracking:** Phase-coherent birth/death/continuation. Configurable `Birth`, `Death`, `Phase Wt`, and `Min Len`. Uses velocity prediction and phase advance to resolve ambiguous peak matches.
 4. **Backward Expansion:** Second pass extends each partial leftward to recover onset frames
 5. **Bezier Fitting:** Cubic curves optimized via **Least-Squares** (minimizes error across all points).
 
@@ -149,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