livepilot 1.26.0 → 1.26.1

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,157 @@
+---
+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.
+
+## 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.
+
+## 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 + levels. Answers 80% of mix questions.
+2. **Fast (1-5s):** `analyze_loudness` + `analyze_mix` — LUFS, true peak, and full mix analysis. For mastering prep.
+3. **Slow (5-15s):** `compare_to_reference` + `analyze_spectrum_offline` — reference matching, offline spectral analysis. Ask the user first.
+
+Never skip levels. Start at the lowest appropriate level and offer to go deeper.
+
+## 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

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

@@ -0,0 +1,130 @@
+---
+name: livepilot-notes
+description: This skill should be used when the user asks to "write notes", "add a melody", "chord progression", "rhythm pattern", "MIDI notes", "transpose", "quantize", "Euclidean rhythm", "counterpoint", "scale", "key detection", "harmony", or wants to create, edit, or analyze MIDI content in Ableton Live.
+---
+
+# MIDI Notes — Create, Edit, and Analyze
+
+Write melodies, chords, rhythms, and generative patterns in Ableton Live clips. Every note operation follows the Live 12 API.
+
+## Note API Cycle
+
+Four operations form the core CRUD cycle for MIDI notes:
+
+1. **Create:** `add_notes(track_index, clip_index, notes)` — write new notes into a clip
+2. **Read:** `get_notes(track_index, clip_index)` — retrieve all notes with IDs, pitches, timings
+3. **Update:** `modify_notes(track_index, clip_index, modifications)` — change existing notes by `note_id`
+4. **Delete:** `remove_notes(track_index, clip_index, start_time, duration, pitch_start, pitch_end)` — clear a region, or `remove_notes_by_id(track_index, clip_index, note_ids)` — surgical deletion by ID
+
+Always create a clip first with `create_clip(track_index, clip_index, length)` before adding notes to it.
+
+## Note Format
+
+When calling `add_notes`, each note requires:
+
+```json
+{
+  "pitch": 60,
+  "start_time": 0.0,
+  "duration": 0.5,
+  "velocity": 100,
+  "mute": false
+}
+```
+
+When reading with `get_notes`, each note also returns Live 12 extended fields:
+- `note_id` — unique identifier for modify/remove operations
+- `probability` — 0.0 to 1.0, per-note trigger probability (Live 12 feature)
+- `velocity_deviation` — -127.0 to 127.0, randomizes velocity on each trigger
+- `release_velocity` — 0.0 to 127.0, note-off velocity
+
+Use `modify_notes` with `note_id` to update any field on existing notes — pitch, velocity, timing, probability, mute state.
+
+## Duplication and Transposition
+
+- `duplicate_notes(track_index, clip_index, time_offset)` — copy all notes forward by `time_offset` beats. Use for pattern repetition: a 4-beat pattern duplicated at offset 4.0 creates an 8-beat loop.
+- `transpose_notes(track_index, clip_index, semitones, start_time, duration)` — shift pitches in a region by semitones. Positive = up, negative = down.
+- `transpose_smart(track_index, clip_index, semitones, key)` — transpose with scale awareness. Notes stay within the target key, avoiding chromatic collisions.
+
+## Quantization
+
+`quantize_clip(track_index, clip_index, grid, amount)` snaps note start times to a rhythmic grid.
+
+Grid enum values:
+- 0 = None (no quantize)
+- 1 = 1/4 notes
+- 2 = 1/8 notes
+- 3 = 1/8 triplets
+- 4 = 1/8 + triplets (combined grid)
+- 5 = 1/16 notes
+- 6 = 1/16 triplets
+- 7 = 1/16 + triplets (combined grid)
+- 8 = 1/32 notes
+
+The `amount` parameter (0.0-1.0) controls how far notes move toward the grid. Use 1.0 for rigid quantize, 0.5-0.7 for humanized feel.
+
+## Theory Integration
+
+Run these checks before firing any clip with melodic content:
+
+1. `identify_scale(track_index, clip_index)` — detect the scale from existing notes (Krumhansl-Schmuckler algorithm). Returns key, mode, and confidence.
+2. `detect_theory_issues(track_index, clip_index, strict=true)` — check for out-of-key notes, parallel fifths, voice crossing, augmented/diminished accidents. The `strict` flag enables all checks.
+3. Fix problems with `modify_notes` — adjust offending pitches before the user hears them.
+
+The theory engine knows 7 standard modes. Exotic scales (Hijaz, Hungarian minor, whole tone) produce false "out of key" warnings. Cross-reference flagged pitches against the intended scale manually. Use `key="C hijaz"` for Hijaz/Phrygian Dominant keys.
+
+## Harmony Analysis and Suggestions
+
+- `analyze_harmony(track_index, clip_index)` — identify chords in a clip, returns chord names, qualities, root notes, and progression analysis
+- `suggest_next_chord(track_index, clip_index, key)` — given the current harmonic context, suggest the next chord with voice leading and functional reasoning
+- `harmonize_melody(track_index, clip_index, key, style)` — generate harmony notes for an existing melody. Returns a note array ready for `add_notes` on a separate track.
+- `generate_countermelody(track_index, clip_index, key, species)` — generate a counterpoint line against existing notes. Species 1-5 follow classical counterpoint rules. Returns notes for `add_notes`.
+
+Both `harmonize_melody` and `generate_countermelody` return note arrays — do not call them and discard the output. Place the results into a clip with `add_notes`.
+
+## Generative Algorithms
+
+### Euclidean Rhythms
+
+`generate_euclidean_rhythm(pulses, steps, pitch, velocity, duration)` — distribute `pulses` as evenly as possible across `steps` using the Bjorklund algorithm. Returns a note array. The tool identifies named rhythms automatically (e.g., 3 pulses in 8 steps = "tresillo", 5 in 8 = "cinquillo").
+
+`layer_euclidean_rhythms(layers)` — stack multiple Euclidean patterns for polyrhythmic textures. Each layer specifies pulses, steps, pitch, and velocity. Returns a combined note array spanning all layers, ready for a single `add_notes` call or split across tracks.
+
+### Minimalist Techniques
+
+`generate_tintinnabuli(melody_pitches, key, mode, position)` — implement Arvo Part's technique: a T-voice (triad arpeggio) against a M-voice (stepwise melody). Returns two-voice note data.
+
+`generate_phase_shift(pattern, shift_amount, repetitions)` — implement Steve Reich's phasing: two identical patterns drifting apart over time. One voice holds steady while the other shifts by `shift_amount` per repetition.
+
+`generate_additive_process(melody_pitches, iterations)` — implement Philip Glass's additive technique: melody expanded by adding one note per iteration, building complexity gradually.
+
+All generative tools return note arrays. Place them in clips with `add_notes`.
+
+## Neo-Riemannian Harmony
+
+- `navigate_tonnetz(chord, transform)` — apply PRL (Parallel, Relative, Leading-tone) transforms to a chord. Returns the neighbor chord and its relationship.
+- `find_voice_leading_path(start_chord, end_chord)` — find the shortest harmonic path between two chords through Tonnetz space. Returns intermediate chords.
+- `classify_progression(chords)` — identify the neo-Riemannian transform pattern in a chord sequence (e.g., PRL cycle, hexatonic, octatonic).
+- `suggest_chromatic_mediants(chord)` — return all chromatic mediant relations with film score usage notes. Useful for dramatic harmonic shifts.
+
+## MIDI File I/O
+
+- `export_clip_midi(track_index, clip_index, file_path)` — export a session clip's notes to a .mid file
+- `import_midi_to_clip(track_index, clip_index, file_path)` — load a .mid file into a clip, replacing existing notes
+- `analyze_midi_file(file_path)` — offline analysis of any .mid file (tempo, note count, structure). No Ableton connection needed.
+- `extract_piano_roll(file_path)` — return a 2D velocity matrix (pitch x time) from a .mid file for visualization
+
+## Pitch Audit — Mandatory Before Firing
+
+Before playing any clip with melodic or harmonic content:
+
+1. `identify_scale` on every melodic track — verify all tracks share the same tonal center
+2. `analyze_harmony` on chordal tracks — verify chord quality (no accidental augmented/diminished)
+3. `detect_theory_issues(strict=true)` — check all theory rules
+4. Report a clear tuning summary to the user before proceeding
+5. Fix wrong notes with `modify_notes` before firing
+
+## Reference
+
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/midi-recipes.md` — drum patterns by genre, chord voicings, scale tables, hi-hat articulations, humanization, polymetric layering

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

@@ -0,0 +1,122 @@
+---
+name: livepilot-performance-engine
+description: This skill should be used when the user asks to "perform live", "what's safe to do during a show", "scene handoff", "energy flow", "performance mode", "safe moves", or wants live performance support with safety constraints.
+---
+
+# Performance Engine — Safety-First Live Performance
+
+The performance engine enforces a strict safety model for live performance. Every action is classified before execution. Destructive operations are blocked. Risky operations require user confirmation. Only safe operations execute freely.
+
+## Safety Classification
+
+Every performance action falls into one of four tiers.
+
+### Safe — Execute Freely
+
+These actions are non-destructive and audience-invisible if they fail. Execute without asking.
+
+- `fire_scene` / `fire_clip` — launch scenes or clips (the core of live performance)
+- `set_track_send` with small delta — nudge send levels (reverb/delay throws)
+- `set_device_parameter` on mapped macros — macro knob adjustments
+- `set_track_mute` / `set_track_solo` — mute/solo toggles
+- `set_track_volume` with delta <= 3 dB — volume nudges
+- `set_track_pan` with delta <= 0.2 — subtle pan shifts
+- Filter sweeps via `set_device_parameter` on Auto Filter — smooth frequency movement
+
+### Caution — Require User Confirmation
+
+These actions are audible and may cause a noticeable glitch if wrong. Always ask before executing.
+
+- `set_tempo` with delta <= 5 BPM — tempo nudge (can destabilize synced elements)
+- `toggle_device` — enable/disable effects (may cause pops or silence)
+- `set_track_pan` with delta > 0.2 — large pan moves are disorienting live
+- `set_track_volume` with delta > 3 dB — large volume jumps
+
+Present the action to the user: "I will [action]. This may [risk]. Confirm?"
+
+### Blocked — Never Execute During Performance
+
+These actions risk audible disasters, data loss, or session corruption during a live show.
+
+- `delete_device` / `find_and_load_device` — device chain surgery causes audio interruption
+- `create_arrangement_clip` / `create_clip` / `delete_clip` — clip creation/deletion
+- `create_midi_track` / `create_audio_track` / `delete_track` — track structure changes
+- `add_notes` / `modify_notes` / `remove_notes` — note editing while playing
+- `set_clip_loop` / `set_clip_warp_mode` — clip property changes while playing
+- `flatten_track` / `freeze_track` — CPU-intensive operations
+- Any arrangement-view editing tools
+
+If the user requests a blocked action during performance mode, explain why it is blocked and suggest a safe alternative: "That requires editing the device chain, which can cause audio dropouts during a live show. Instead, try [safe alternative]."
+
+### Unknown — Treat as Blocked
+
+Any action not explicitly classified above defaults to blocked. Do not experiment with unclassified actions during a live performance.
+
+## Performance Loop
+
+### Step 1 — Get State
+
+Call `get_performance_state` to read the current session state:
+- Playing status, current tempo, time signature
+- Which scenes and clips are currently playing
+- Track arm states, solo/mute states
+- Current energy level estimate
+
+### Step 2 — Get Safe Moves
+
+Call `get_performance_safe_moves` to get a list of contextually appropriate safe actions based on the current state. The response is filtered by what makes musical sense right now — not just what is technically safe.
+
+### Step 3 — Check Safety
+
+Before executing any user request, call `check_safety(move_type)` to verify the classification. The response confirms: `safe`, `caution`, or `blocked` with an explanation.
+
+### Step 4 — Execute Safe/Caution Only
+
+- Safe: execute immediately
+- Caution: present to user, wait for confirmation, then execute
+- Blocked: refuse with explanation and alternative
+
+### Step 5 — Scene Handoff
+
+For transitioning between scenes (the primary live performance action), call `plan_scene_handoff(from_scene, to_scene)` to get a transition plan:
+
+- Which clips change between the scenes
+- Recommended launch timing (quantization)
+- Volume/send adjustments to smooth the handoff
+- Any tempo changes between scenes
+
+Execute the handoff plan using safe actions only.
+
+## Energy Flow
+
+During a live set, track the energy trajectory:
+
+1. `get_performance_state` includes an `energy_estimate` (0.0-1.0)
+2. Use scene ordering to build energy arcs: low-energy scenes for intros/breakdowns, high-energy for drops/peaks
+3. `plan_scene_handoff` accounts for energy delta — large energy jumps get transition suggestions
+
+## Performance Mode Entry
+
+When the user says "performance mode", "going live", or "starting the show":
+
+1. Call `get_performance_state` to verify the session is ready
+2. Confirm the safety model with the user: "Performance mode active. I will only execute safe actions freely and ask before caution-level moves. Destructive edits are blocked."
+3. Switch to a response style optimized for speed: short confirmations, no lengthy explanations mid-performance
+4. Prioritize scene launches and safe parameter nudges
+
+## Performance Mode Exit
+
+When the user says "done performing", "show's over", or "exit performance mode":
+
+1. Confirm: "Performance mode ended. Full editing capabilities restored."
+2. Resume normal operation with all tools available
+
+## Emergency Actions
+
+If something goes wrong during a live show:
+
+- `stop_all_clips` — emergency silence (use only if requested)
+- `set_master_volume(0.0)` — fade to silence
+- `set_track_mute` on the problem track — isolate the issue
+
+Never call `undo` during a live performance — it may revert a scene launch or clip state in unpredictable ways.