livepilot 1.26.0 → 1.26.2

package/livepilot/skills/livepilot-mix-engine/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: livepilot-mix-engine
+description: This skill should be used when the user asks to "analyze my mix", "find mix issues", "fix masking", "check frequency clashes", "improve dynamics", "check stereo width", "check headroom", or wants critic-driven mix analysis and evaluation. Provides the mix critic loop for iterative mix improvement.
+---
+
+# Mix Engine — Critic-Driven Mix Improvement
+
+The mix engine runs an iterative critic loop: analyze, plan, execute, measure, evaluate, keep or undo. Every mix change is measured before and after. Nothing stays unless it scores better than the original.
+
+## Character-First Default
+
+Do not treat the full loop as the default for vague requests like "make it better", "more character", "more alive", "punchier", "warmer", or "more interesting". Those are usually sound-design or creative-direction requests. Start from analyzer character (`sonic_character`, `get_spectral_shape`, `get_novelty`, `get_onsets`, `get_mel_spectrum`) and prefer source, instrument, device-chain, envelope, filter, saturation, modulation, and transient-shape decisions before generic level changes.
+
+Use `set_track_volume`, `set_track_pan`, and broad send-level balancing only when the user explicitly asks for balance/level/pan/send work, or when analyzer evidence shows a safety/translation problem such as clipping, headroom collapse, mono collapse, or a severe masking issue. Producers can adjust simple loudness by ear quickly; LivePilot's value is in hearing spectral character and choosing a smarter musical intervention.
+
+For normal work, cap mix-engine action to one high-value move plus a short verdict. Enter the repeated full loop only for explicit requests like "deep mix pass", "mastering prep", "fix all mix issues", or an exact target such as LUFS/headroom/mono compatibility.
+
+## The Mix Critic Loop
+
+Follow these steps in order. Do not skip the evaluation step.
+
+### Step 1 — Analyze
+
+Call `analyze_mix` or `get_mix_issues` to build a MixState and run all critics against the current session. The response contains an `issues` array, each with a `critic`, `severity`, `track_index`, and `evidence` dict.
+
+If the M4L analyzer bridge is absent, critics fall back to role-based heuristics only (track names, device chains, volume/pan positions). Inform the user that spectral analysis is unavailable and recommendations are less precise.
+
+For detailed frequency collision data, call `get_masking_report`. For a quick status overview without the full critic pass, call `get_mix_summary`.
+
+### Step 2 — Plan
+
+Pick the highest-severity issue from the `issues` array. Call `plan_mix_move` with the issue data. The planner returns the smallest intervention that addresses the problem — a single parameter change, not a chain of edits.
+
+Read the `move` object: it contains `move_type`, `target_track`, `target_device`, `target_parameter`, `target_value`, and `rationale`. Consult the move vocabulary in `references/mix-moves.md` for parameter ranges.
+
+### Step 3 — Capture Before
+
+Take a measurement snapshot before executing anything:
+
+1. Call `get_master_spectrum` — save the 9-band spectral data (sub_low → air)
+2. Call `get_master_rms` — save the RMS and peak values
+
+Optionally call `get_mix_snapshot` if you need per-track volume/pan/send state for the evaluation.
+
+### Step 4 — Execute
+
+Execute the planned move. Use the appropriate tool for the move type:
+
+- `set_device_parameter` for EQ cuts/boosts, compressor thresholds, saturation drives
+- `set_track_volume` for gain staging
+- `set_track_pan` for stereo placement
+- `set_track_send` for bus routing levels
+- `toggle_device` for bypassing/enabling processors
+- `batch_set_parameters` when the move requires multiple related parameter changes on the same device
+
+Execute exactly one move. Do not chain multiple interventions before measuring.
+
+### Step 5 — Capture After
+
+Repeat the same measurements from Step 3:
+
+1. Call `get_master_spectrum` — save the post-change spectral data
+2. Call `get_master_rms` — save the post-change RMS and peak values
+
+### Step 6 — Evaluate
+
+Call `evaluate_mix_move` with the before and after snapshots:
+
+```
+evaluate_mix_move(
+  before_snapshot: { spectrum: [...], rms: float, peak: float },
+  after_snapshot:  { spectrum: [...], rms: float, peak: float },
+  targets: { ... },     # what the move aimed to improve
+  protect: { ... }      # what must not get worse
+)
+```
+
+Read the response: `keep_change` (bool), `score` (0.0-1.0), `improvements` (list), `regressions` (list), `explanation` (string).
+
+### Step 7 — Keep or Undo
+
+If `keep_change` is `false`, call `undo()` immediately. Tell the user what was tried and why it was reverted, citing the `regressions` list.
+
+If `keep_change` is `true`, report the improvement to the user with the score and explanation.
+
+### Step 8 — Learn (Optional)
+
+If the move scored above 0.7 and the user confirms satisfaction, call `memory_learn(name="...", type="mix_template", qualities={"summary": "..."}, payload={...})` to save the technique for future recall.
+
+### Step 9 — Repeat
+
+Return to Step 1 and re-analyze only when the user requested a deep/full mix pass. Otherwise stop after the first measured high-value intervention and report the remaining optional issues as suggestions. Avoid spending a turn on small volume-balancing loops unless they are the requested task.
+
+## Quick Mix Checks
+
+Not every request needs the full loop:
+
+- **"How's my mix?"** — Call `get_mix_summary` for a one-shot status report with no changes
+- **"What's clashing?"** — Call `get_masking_report` for detailed per-pair frequency collision data
+- **"What are the issues?"** — Call `get_mix_issues` for the critic list without executing any fixes
+
+## Critic Types
+
+Six critics run during analysis. See `references/mix-critics.md` for thresholds and evidence format:
+
+- **masking** — frequency collisions between overlapping tracks
+- **over_compressed** — excessive compression reducing dynamic range
+- **flat_dynamics** — insufficient volume variation across sections
+- **low_headroom** — master peak too close to 0 dBFS
+- **stereo_width** — mono collapse or excessive width on specific elements
+- **spectral_balance** — overall tonal balance skew (too bright, too dark, mid-heavy)
+
+## Move Vocabulary
+
+The planner draws from six move types. See `references/mix-moves.md` for parameter ranges:
+
+- **gain_staging** — volume adjustments to establish proper level hierarchy
+- **bus_compression** — glue compression on groups or master
+- **transient_shaping** — attack/sustain manipulation for punch or smoothness
+- **eq_cut** — subtractive EQ to clear masking or remove resonances
+- **eq_boost** — additive EQ to bring out character (use sparingly)
+- **pan_spread** — stereo placement adjustments for width and separation
+
+## Analyzer Dependency
+
+The mix engine works in two modes:
+
+- **Full mode** (M4L analyzer connected): spectral data, RMS, key detection available. Critics use measured evidence.
+- **Heuristic mode** (no analyzer): critics infer from track names, device chains, and parameter positions. Always inform the user: "Spectral analysis unavailable — recommendations are based on track structure and device settings only."
+
+Call `get_capability_state` to check which mode is active before starting the loop.
+
+## Extended Perception Toolkit
+
+Beyond `get_master_spectrum` / `get_master_rms` / `get_detected_key`, the analyzer domain exposes six more measurements that give finer evidence than the 9-band spectrum alone. Use them when the standard snapshot is too coarse for the move you are evaluating:
+
+- **`get_spectral_shape`** — centroid, spread, skewness, kurtosis, rolloff, flatness, crest. Use for *tonal balance* judgments ("is this bright?", "is the energy concentrated or spread?") that 9 discrete bands cannot describe.
+- **`get_mel_spectrum`** — perceptual mel-band energies. Use when an EQ move needs to be evaluated against how the change is *heard*, not against linear-frequency bin energies.
+- **`get_chroma`** — 12-bin pitch-class energy. Use to detect harmonic clashes or to confirm a key without trusting `get_detected_key` alone.
+- **`get_onsets`** — transient detection. Use for groove / rhythm evaluations where you need to know *when* hits land, not just how loud the average is.
+- **`get_novelty`** — spectral change score with boundary flag. Use to confirm an arrangement boundary actually creates a perceived event, or to detect static sections that need disruption.
+- **`get_momentary_loudness`** — momentary LUFS + true-peak dBTP. Use during mastering moves where peak/RMS is insufficient and EBU R128 is the gauge.
+
+All six are bridge-dependent — they return helpful errors if the analyzer is not on master. They do not replace the before/after snapshot pattern; they enrich what "snapshot" means when the move warrants it.

package/livepilot/skills/livepilot-mix-engine/references/mix-critics.md

@@ -0,0 +1,143 @@
+# Mix Critics Reference
+
+Each critic runs during `analyze_mix` or `get_mix_issues` and produces an issue object with `critic`, `severity` (0.0-1.0), `track_index`, and `evidence`.
+
+## masking
+
+Detects frequency collisions between tracks that occupy the same spectral range.
+
+**Thresholds:**
+- severity >= 0.7: Two tracks share > 60% spectral overlap in the same frequency band with both > -12 dB in that range
+- severity >= 0.4: Partial overlap (30-60%) or one track is significantly quieter
+- severity < 0.4: Minor overlap, likely intentional layering
+
+**Evidence format:**
+```json
+{
+  "track_a": 0,
+  "track_b": 2,
+  "collision_band": "low_mid",
+  "frequency_range": [200, 500],
+  "overlap_percent": 72.5,
+  "a_level_db": -8.2,
+  "b_level_db": -10.1
+}
+```
+
+**Typical fix:** eq_cut on the less important track in the collision band, or pan_spread to separate spatially.
+
+## over_compressed
+
+Detects tracks or the master bus with excessive compression, indicated by very low crest factor (peak-to-RMS ratio).
+
+**Thresholds:**
+- severity >= 0.7: Crest factor < 3 dB on a dynamic source (vocals, drums, full mix)
+- severity >= 0.4: Crest factor 3-6 dB on sources that should be more dynamic
+- severity < 0.4: Mild compression, may be intentional for genre
+
+**Evidence format:**
+```json
+{
+  "track_index": 1,
+  "crest_factor_db": 2.4,
+  "rms_db": -12.3,
+  "peak_db": -9.9,
+  "compressor_device": "Compressor",
+  "compressor_ratio": 8.0,
+  "compressor_threshold_db": -20.0
+}
+```
+
+**Typical fix:** Raise compressor threshold, reduce ratio, or increase attack time.
+
+## flat_dynamics
+
+Detects tracks or sections with insufficient volume variation, making the mix feel static across song sections.
+
+**Thresholds:**
+- severity >= 0.7: Volume variation < 2 dB across all sections
+- severity >= 0.4: Volume variation 2-4 dB where genre expects more contrast
+- severity < 0.4: Minimal variation but may suit the genre (EDM drops, ambient)
+
+**Evidence format:**
+```json
+{
+  "track_index": 3,
+  "section_volumes_db": [-10.2, -10.5, -10.1, -10.4],
+  "volume_range_db": 0.4,
+  "expected_range_db": 6.0
+}
+```
+
+**Typical fix:** Automation on track volume or device parameters between sections.
+
+## low_headroom
+
+Detects when the master bus peak is dangerously close to 0 dBFS, risking clipping.
+
+**Thresholds:**
+- severity >= 0.7: Master peak > -1 dBFS
+- severity >= 0.4: Master peak between -3 and -1 dBFS
+- severity < 0.4: Master peak between -6 and -3 dBFS (acceptable for mastered content)
+
+**Evidence format:**
+```json
+{
+  "master_peak_db": -0.3,
+  "master_rms_db": -8.2,
+  "headroom_db": 0.3,
+  "clipping": false
+}
+```
+
+**Typical fix:** gain_staging — reduce the loudest tracks by 1-3 dB, or apply a limiter on the master.
+
+## stereo_width
+
+Detects stereo problems: mono collapse (too narrow), excessive width (phase issues), or elements placed inappropriately in the stereo field.
+
+**Thresholds:**
+- severity >= 0.7: Correlation coefficient < 0.1 (phase issues) or > 0.95 (essentially mono)
+- severity >= 0.4: Bass content with significant stereo width, or lead vocal panned away from center
+- severity < 0.4: Minor width imbalance
+
+**Evidence format:**
+```json
+{
+  "track_index": 5,
+  "correlation": 0.05,
+  "width_estimate": 0.95,
+  "issue_type": "phase_cancellation",
+  "frequency_range": [100, 300]
+}
+```
+
+**Typical fix:** Narrow bass to mono below 150 Hz (Utility mid/side), widen or narrow specific elements with pan_spread.
+
+## spectral_balance
+
+Detects overall tonal balance skew across the full mix — too bright, too dark, or mid-heavy compared to reference targets.
+
+**Thresholds:**
+- severity >= 0.7: Any band deviates > 6 dB from genre target curve
+- severity >= 0.4: Deviation 3-6 dB in one or more bands
+- severity < 0.4: Minor skew, within normal range
+
+**Evidence format:**
+```json
+{
+  "balance_type": "too_bright",
+  "band_deviations_db": {
+    "sub": -1.2,
+    "low": 0.5,
+    "low_mid": -0.8,
+    "mid": -2.1,
+    "high_mid": 4.2,
+    "high": 7.1,
+    "air": 5.8
+  },
+  "reference_curve": "electronic_modern"
+}
+```
+
+**Typical fix:** eq_cut on the protruding bands, or eq_boost on deficient bands. Prefer cuts over boosts.

package/livepilot/skills/livepilot-mix-engine/references/mix-moves.md

@@ -0,0 +1,105 @@
+# Mix Moves Reference
+
+The move vocabulary used by `plan_mix_move`. Each move type has defined parameter ranges and constraints.
+
+## gain_staging
+
+Adjust track or bus volume to establish proper level hierarchy.
+
+**Parameters:**
+- `target_track`: track index (0-based)
+- `target_value`: normalized volume 0.0-1.0 (0.85 = unity / 0 dB)
+- `delta_db`: typical adjustment range -6 to +3 dB per move
+
+**Constraints:**
+- Never boost more than +3 dB in a single move
+- Prefer cutting the louder track over boosting the quieter one
+- Check master headroom after any gain change
+- Group tracks (drums, synths, vocals) should be staged relative to each other first
+
+**Tools:** `set_track_volume`, `set_master_volume`
+
+## bus_compression
+
+Apply or adjust glue compression on groups, return tracks, or master bus.
+
+**Parameters:**
+- `threshold_db`: -30 to 0 dB (start conservative at -15)
+- `ratio`: 1.5:1 to 4:1 for glue, up to 8:1 for limiting
+- `attack_ms`: 0.1 to 100 ms (10-30 ms for glue, <1 ms for limiting)
+- `release_ms`: 50 to 500 ms (auto release preferred for master bus)
+- `makeup_gain_db`: 0 to +6 dB
+
+**Constraints:**
+- Gain reduction should stay under 3-4 dB for glue compression
+- Always capture before/after RMS to verify loudness is maintained
+- On master bus, prefer ratio <= 2:1 and attack >= 10 ms
+
+**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "Compressor")`
+
+## transient_shaping
+
+Adjust attack and sustain characteristics to control punch and body.
+
+**Parameters:**
+- `attack`: -100% to +100% (negative softens, positive sharpens)
+- `sustain`: -100% to +100% (negative tightens, positive lengthens)
+
+**Constraints:**
+- Apply to individual drum hits or drum bus, not full mix
+- Check that transient shaping doesn't push peaks above headroom
+- Often more effective than compression for punch problems
+
+**Tools:** `set_device_parameter` on a transient shaper device
+
+## eq_cut
+
+Subtractive EQ to clear masking, remove resonances, or fix spectral balance.
+
+**Parameters:**
+- `frequency_hz`: 20 to 20000 Hz
+- `gain_db`: -12 to 0 dB (never cut more than 12 dB in one move)
+- `q`: 0.5 to 8.0 (narrow cuts 4-8 for resonances, wide cuts 0.5-2 for balance)
+- `filter_type`: low_cut, high_cut, bell, notch
+
+**Constraints:**
+- Prefer EQ Eight for surgical work (8 bands available)
+- For low cuts on non-bass tracks, use 18 or 24 dB/oct high-pass
+- Cut on the less important track in a masking pair
+- Verify after cut that the track still sounds full — over-cutting kills body
+
+**Tools:** `set_device_parameter`, `find_and_load_device(track_index, "EQ Eight")`
+
+## eq_boost
+
+Additive EQ to bring out character frequencies. Use sparingly.
+
+**Parameters:**
+- `frequency_hz`: 20 to 20000 Hz
+- `gain_db`: 0 to +4 dB (never boost more than 4 dB in one move)
+- `q`: 0.5 to 4.0 (wide boosts sound more natural)
+
+**Constraints:**
+- Always try a cut on competing tracks before boosting
+- Boosts above +4 dB usually indicate a source problem, not a mix problem
+- Check master headroom after any boost — boosts add energy
+- Wide Q (0.5-1.5) for tonal shaping, narrow Q (2-4) for emphasis
+
+**Tools:** `set_device_parameter` on EQ device
+
+## pan_spread
+
+Stereo placement adjustments for width and separation.
+
+**Parameters:**
+- `pan`: -1.0 (full left) to 1.0 (full right), 0.0 = center
+- `width`: 0.0 (mono) to 2.0 (extra wide) on Utility device
+
+**Constraints:**
+- Bass and kick stay centered (pan 0.0)
+- Lead vocal stays centered or very slightly off-center (within -0.1 to 0.1)
+- Stereo pairs (L/R guitars, synth layers) mirror symmetrically
+- Check mono compatibility after spreading — call `check_translation` if available
+- Never pan return tracks (reverb/delay should remain stereo)
+
+**Tools:** `set_track_pan`, `set_device_parameter` on Utility for mid/side width

package/livepilot/skills/livepilot-mixing/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: livepilot-mixing
+description: This skill should be used when the user asks to "mix", "balance levels", "set volume", "pan a track", "EQ", "compress", "sends", "routing", "master volume", "gain staging", "sidechain", or wants to perform mixing operations in Ableton Live.
+---
+
+# Mixing — Levels, Panning, Routing, and Analysis
+
+Balance track levels, configure routing, apply mix effects, and analyze frequency content in Ableton Live.
+
+## Default Value Filter
+
+For broad musical requests, do not spend the turn on manual-feeling volume balancing. Levels, pan, and sends are useful when the user asks for them, when clipping/headroom/translation is objectively unsafe, or when a routing architecture is part of the style. Otherwise, treat meters as context and use analyzer character to make higher-value choices: source selection, filter/envelope shape, saturation, modulation, transient design, or a better device/preset.
+
+When a request says "more punch", "more warmth", "more character", "less flat", "more alive", or similar, route through sound-design/creative-director first and use mix tools only as safety checks.
+
+## Read Before Write
+
+Always understand the current state before changing anything:
+
+1. `get_session_info` — see all tracks, their types, and current configuration
+2. `get_track_info(track_index)` — detailed info on a single track: devices, clips, mixer state
+3. `get_mix_snapshot` — one-call overview of all levels, panning, routing, mute/solo state across the entire session
+4. `get_device_parameters(track_index, device_index)` — read current parameter values before tweaking
+
+Never set levels blindly. Read the current state, make informed adjustments, then verify the result.
+
+## Volume and Pan
+
+- `set_track_volume(track_index, value)` — value is normalized 0.0 to 1.0 (not dB). 0.85 is roughly unity gain. 0.0 is silence, 1.0 is max.
+- `set_track_pan(track_index, value)` — value is -1.0 (hard left) to 1.0 (hard right). 0.0 is center.
+- `set_master_volume(value)` — master output level, same 0.0-1.0 range.
+
+Gain staging principle: keep individual tracks at moderate levels (0.5-0.85) and use the master for final output. Avoid pushing tracks to 1.0 — it leaves no headroom for summing.
+
+## Sends and Return Tracks
+
+Sends route signal from any track to a return track for shared processing (reverb bus, delay bus, parallel compression).
+
+- `set_track_send(track_index, send_index, value)` — set send level (0.0-1.0). Send index 0 = Send A, 1 = Send B, etc.
+- `get_return_tracks` — list all return tracks with their names, devices, and routing
+- `create_return_track` — add a new return track to the session
+- `get_master_track` — inspect the master track configuration
+
+Return track workflow:
+1. `create_return_track` — creates a new return (automatically assigned next letter: A, B, C...)
+2. Load an effect on the return track (e.g., Reverb with Dry/Wet at 100%)
+3. `set_track_send(track_index, send_index, value)` on each track that needs the effect
+4. Adjust send levels per track for different amounts of the shared effect
+
+## Routing
+
+- `get_track_routing(track_index)` — see current input/output routing for a track
+- `set_track_routing(track_index, input_routing, output_routing)` — configure where audio comes from and goes to
+
+Common routing patterns:
+- **Resampling:** set input routing to "Resampling" on an audio track to capture the master output
+- **Sidechain:** route a track's output to another track's sidechain input for ducking compression
+- **Sub-groups:** route multiple tracks to a group track for bus processing
+
+## Metering
+
+- `get_track_meters(track_index)` — read real-time output level of a specific track (left/right channels)
+- `get_master_meters` — read the master output level in real-time
+
+Use metering to verify your level adjustments. After setting volumes, check meters to confirm nothing is clipping and the balance sounds right.
+
+## Mix Snapshot
+
+`get_mix_snapshot` returns a complete picture of the session mix in one call:
+- All track volumes and pan positions
+- Mute and solo states
+- Send levels
+- Routing configuration
+- Return track setup
+
+Use this as your starting point for any mixing task. It shows the full picture without needing to query each track individually.
+
+## Automation
+
+### Clip Automation
+
+- `get_clip_automation(track_index, clip_index, parameter_name)` — read existing automation for a parameter
+- `set_clip_automation(track_index, clip_index, parameter_name, points)` — write automation points as `[{time, value}, ...]`
+- `clear_clip_automation(track_index, clip_index, parameter_name)` — remove automation before rewriting
+
+### Intelligent Curves
+
+- `generate_automation_curve(shape, start_value, end_value, num_points)` — generate automation points using 16 curve types: linear, exponential, logarithmic, sine, cosine, s_curve, ease_in, ease_out, bounce, random_walk, step, triangle, sawtooth, reverse_sawtooth, pulse, and smooth_random
+- `apply_automation_shape(track_index, clip_index, parameter_name, shape, start_value, end_value)` — generate and apply a curve in one call
+
+### Recipes
+
+`apply_automation_recipe(track_index, clip_index, recipe_name)` — apply a pre-built automation pattern. Available recipes:
+
+- `filter_sweep_up` — low-pass filter opens over time, classic build
+- `filter_sweep_down` — filter closes, darkening effect
+- `sidechain_pump` — rhythmic volume ducking on each beat
+- `dub_throw` — delay feedback spikes on specific beats
+- `tremolo` — rhythmic volume oscillation
+- `autopan` — stereo movement back and forth
+- `fade_in` / `fade_out` — gradual volume transitions
+- `stutter` — rapid volume gates for glitch effects
+- `vinyl_crackle` — subtle noise modulation
+- `tape_wow` — pitch/speed micro-variations
+- `bit_crush_sweep` — sample rate reduction over time
+- `resonance_peak` — filter resonance spike for emphasis
+- `stereo_width_grow` — mono to wide stereo expansion
+- `grain_scatter` — granular parameter randomization
+
+### Automation Feedback Loop
+
+Follow this cycle for all automation work:
+
+1. **Perceive:** `get_master_spectrum` + `get_track_meters` to understand current state
+2. **Diagnose:** identify what needs to change based on spectral data
+3. **Act:** `apply_automation_shape` or `apply_automation_recipe`
+4. **Verify:** `get_master_spectrum` again to confirm the change worked
+5. **Adjust:** if not right, `clear_clip_automation` and try different parameters
+
+Never write automation without reading spectrum before and after.
+
+## Spectrum Analysis (Requires M4L Bridge)
+
+When the LivePilot Analyzer M4L device is on the master track:
+
+- `get_master_spectrum` — 9-band frequency analysis: sub_low (20-60 Hz), sub (60-120 Hz), low (120-250 Hz), low_mid (250-500 Hz), mid (500-1k Hz), high_mid (1-2k Hz), high (2-4k Hz), presence (4-8k Hz), air (8-20k Hz)
+- `get_master_rms` — true RMS and peak levels for loudness assessment
+- `get_detected_key` — detect musical key from audio content
+
+Use spectrum data to make informed EQ decisions. If the low_mid band is 6 dB hotter than everything else, there is mud to clean up. If the air band is absent, the mix may sound dull. When FluCoMa streams are active, prefer `get_spectral_shape`, `get_mel_spectrum`, `get_onsets`, and `get_novelty` for character decisions; those descriptors tell you whether the sound is bright/dark, flat/peaked, static/moving, or transient/soft in a way simple level meters cannot.
+
+## Mix Engine — Critic-Driven Analysis
+
+For deeper mix analysis beyond basic levels and spectrum:
+
+- `analyze_mix` — full spectral mix analysis with per-track breakdown
+- `get_mix_issues` — identify specific problems (masking, imbalance, phase)
+- `plan_mix_move` — get a suggested action to fix a detected issue
+- `evaluate_mix_move` — score a proposed change before applying it
+- `get_masking_report` — detect frequency masking between tracks
+- `get_mix_summary` — quick overall mix health status
+
+Use the mix engine when the user wants a critical evaluation of their mix, not just level adjustments. Start with `get_mix_summary` for a quick overview, escalate to `analyze_mix` for full detail.
+
+## Quick Mix Status
+
+`get_mix_summary` from the mix engine provides an overall health score, top issues, and priority recommendations in a single call. Use it as a fast check before diving into detailed analysis.
+
+## Escalation Ladder
+
+Follow this progression — start fast, go deeper only when needed:
+
+1. **Instant:** `get_master_spectrum` + `get_track_meters` — frequency balance + safety context.
+2. **Fast character:** `get_spectral_shape` + `get_novelty` + `get_onsets` when available — decide whether the next move belongs to sound design, arrangement, or mix.
+3. **Fast mix (1-5s):** `analyze_loudness` + `analyze_mix` — LUFS, true peak, and full mix analysis. For mastering prep or explicit mix critique.
+4. **Slow (5-15s):** `compare_to_reference` + `analyze_spectrum_offline` — reference matching, offline spectral analysis. Ask the user first.
+
+Never skip safety context. Do not let safety context become a long volume-tweaking session unless the user asked for that.
+
+## Reference
+
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/mixing-patterns.md` — gain staging, parallel compression, sidechain, EQ by instrument, bus processing, stereo width
+- `livepilot-core/references/automation-atlas.md` — curve theory, genre-specific recipes, diagnostic filter, cross-track spectral mapping