livepilot 1.9.21 → 1.9.23

package/livepilot/commands/beat.md

@@ -5,26 +5,73 @@ description: Guided beat creation — create a beat from scratch with genre, tem
 
 Guide the user through creating a beat from scratch. Follow these steps:
 
-1. **Ask about the vibe** — genre, tempo range, mood, reference tracks
-2. **Set up the session** — `set_tempo`, create tracks for drums/bass/harmony/melody with `create_midi_track`, name and color them
-3. **Load instruments** — use `find_and_load_device` for appropriate instruments per track
-4. **Verify device health** — after loading, run `get_device_info` on each loaded device. A `parameter_count` of 0 or 1 on AU/VST plugins means the plugin failed to initialize (dead plugin). If detected:
-   - Delete the dead plugin with `delete_device`
-   - Replace with a native Ableton alternative (e.g., Saturator instead of tape plugins, Operator instead of failed FM synths)
-   - Run `get_session_diagnostics` for any other issues (armed tracks, missing instruments)
-   - Inform the user which plugin failed and what replacement was used
-5. **Program drums first** — create a clip, add kick/snare/hat patterns with `add_notes`
-6. **Add bass** — create clip, program a bassline that locks with the kick
-7. **Add harmony** — chords or pads that set the mood
-8. **Add melody** — top-line or lead element
-9. **Mix** — balance levels with `set_track_volume` and `set_track_pan`
-10. **Pitch & tuning audit** — MANDATORY before firing. Run on every melodic track (skip drums):
-    - `identify_scale` on each track — verify all tracks agree on the same tonal center
-    - `analyze_harmony` on chordal tracks (pads, keys) — verify chord quality (no accidental augmented/diminished chords unless intentional)
-    - `detect_theory_issues` with `strict=true` on each track — check for out-of-key notes, parallel fifths, voice crossing
-    - **Interpret results against the intended scale**, not just C major. The analyzer only knows 7 standard modes — exotic scales (Hijaz, Hungarian minor, whole tone, etc.) will produce false "out of key" warnings. Cross-reference flagged notes against the intended scale manually.
-    - Report a clear tuning table to the user: which tracks are clean, which have issues, what the issues are
-    - Fix wrong notes with `modify_notes` before proceeding
-11. **Fire the scene** to listen, iterate based on feedback
+## Step 0: Session Prep (fresh projects only)
+
+If the user asks for a **fresh start** (new track, clean slate, start from scratch):
+
+1. **Read the session** — `get_session_info` to see what exists
+2. **Delete all existing tracks** — loop through all tracks with `delete_track`, starting from the highest index down to 0 (deleting from the top prevents index shifts)
+3. **Load the M4L Analyzer on master** — `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. This enables real-time spectral analysis, RMS metering, and key detection for the entire session. If it fails, try `search_browser(path="max_for_live", name_filter="LivePilot")` to find the URI and load manually.
+4. **Set up master chain** — load Glue Compressor + EQ Eight + Utility on master for bus processing
+5. **Verify analyzer** — wait 2 seconds, then call `get_master_spectrum`. If it returns data, the bridge is connected. If it errors with "UDP bridge not connected", call `reconnect_bridge` to rebind.
+
+If the user is adding to an **existing project**, skip step 0 — just call `get_session_info` and work with what's there.
+
+## Step 1: Ask about the vibe
+Genre, tempo range, mood, reference tracks.
+
+## Step 2: Set up the session
+`set_tempo`, create tracks for drums/bass/harmony/melody with `create_midi_track`, name and color them.
+
+## Step 3: Load instruments
+Use `search_browser` to find devices by name, `load_browser_item` or `find_and_load_device` to load them.
+
+## Step 4: Verify device health
+After loading, run `get_device_info` on each loaded device. A `parameter_count` of 0 or 1 on AU/VST plugins means the plugin failed to initialize (dead plugin). If detected:
+- Delete the dead plugin with `delete_device`
+- Replace with a native Ableton alternative (e.g., Saturator instead of tape plugins, Operator instead of failed FM synths)
+- Run `get_session_diagnostics` for any other issues (armed tracks, missing instruments)
+- Inform the user which plugin failed and what replacement was used
+
+## Step 5: Program drums first
+Create a clip, add kick/snare/hat patterns with `add_notes`.
+
+## Step 6: Add bass
+Create clip, program a bassline that locks with the kick.
+
+## Step 7: Add harmony
+Chords or pads that set the mood.
+
+## Step 8: Add melody
+Top-line or lead element.
+
+## Step 9: Mix + VERIFY
+Balance levels with `set_track_volume` and `set_track_pan`.
+
+**MANDATORY after every parameter change:**
+- Read `value_string` in the response to confirm the actual Hz/dB/% value makes sense
+- Call `get_track_meters(include_stereo=true)` and verify each track has non-zero output
+- If a track's stereo output drops to 0, the effect is killing the signal — check `get_device_parameters` for `value_string`, fix, re-verify
+- Parameter ranges are NOT always 0-1. Always read `value_string`.
+
+## Step 10: Pitch & tuning audit
+MANDATORY before firing. Run on every melodic track (skip drums):
+- `identify_scale` on each track — verify all tracks agree on the same tonal center
+- `analyze_harmony` on chordal tracks — verify chord quality
+- `detect_theory_issues` with `strict=true` on each track — check for out-of-key notes, parallel fifths, voice crossing
+- **Interpret results against the intended scale**, not just C major
+- Report a clear tuning table to the user: which tracks are clean, which have issues
+- Fix wrong notes with `modify_notes` before proceeding
+
+## Step 11: Perception check
+If the M4L Analyzer is connected:
+- `get_master_spectrum` — check spectral balance (sub should be present but not >60% for most genres)
+- `get_master_rms` — check levels aren't clipping
+- `get_detected_key` — verify the analyzer agrees with the intended key
+
+If not connected, use `capture_audio` + `analyze_loudness` + `analyze_spectrum_offline` for offline analysis.
+
+## Step 12: Fire the scene
+Fire to listen, iterate based on feedback.
 
 Use the livepilot-core skill for all tool calls. Verify after each step. Keep the user informed of what you're doing and why.

package/livepilot/commands/evaluate.md

@@ -11,28 +11,38 @@ Run the universal evaluation loop on recent production changes.
    - `judgment_only` — no analyzer, parameter-level heuristics only
    - `read_only` — session disconnected
 
-2. **Get the last move** — `get_last_move` to understand what was changed. If no recent move, `get_recent_actions` for history.
+2. **Ensure analyzer** — if mode is `judgment_only`, try to get full perception:
+   - `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`
+   - Wait 2s, then `get_master_spectrum` to test the bridge
+   - If bridge disconnected: `reconnect_bridge`
+   - If still unavailable: proceed with `judgment_only` but tell the user
 
-3. **Ask what the goal was** — what were they trying to achieve? More clarity? Wider stereo? Punchier drums?
+3. **Get the last move** — `get_last_move` to understand what was changed. If no recent move, `get_recent_actions` for history.
 
-4. **Compile the goal** — `compile_goal_vector(goal_description, mode="improve")`
+4. **Ask what the goal was** — what were they trying to achieve? More clarity? Wider stereo? Punchier drums?
 
-5. **Capture current state** — `get_master_spectrum` + `get_master_rms` + `get_mix_snapshot`
+5. **Compile the goal** — `compile_goal_vector(goal_description, mode="improve")`
 
-6. **Undo the change** — `undo()` to restore the before state
+6. **Capture current state** — full perception snapshot:
+   - `get_master_spectrum` + `get_master_rms` (if analyzer available)
+   - `get_track_meters(include_stereo=true)` — verify all tracks producing audio
+   - `get_mix_snapshot` — full volume/pan/send state
+   - Optionally: `capture_audio` + `analyze_loudness` + `analyze_spectrum_offline` for ground truth
 
-7. **Capture before state** — same reads as step 5
+7. **Undo the change** — `undo()` to restore the before state
 
-8. **Redo the change** — `redo()` to restore the after state
+8. **Capture before state** — same reads as step 6
 
-9. **Evaluate** — `evaluate_move(before_snapshot, after_snapshot, goal)` or use engine-specific:
-   - Mix changes: `evaluate_mix_move`
-   - Composition changes: `evaluate_composition_move`
-   - Multi-dimensional: `evaluate_with_fabric`
+9. **Redo the change** — `redo()` to restore the after state
 
-10. **Report results** — show: score (0-1), keep_change recommendation, goal_progress, collateral_damage, dimension changes
+10. **Evaluate** — `evaluate_move(before_snapshot, after_snapshot, goal)` or use engine-specific:
+    - Mix changes: `evaluate_mix_move`
+    - Composition changes: `evaluate_composition_move`
+    - Multi-dimensional: `evaluate_with_fabric`
 
-11. **Act on recommendation:**
+11. **Report results** — show: score (0-1), keep_change recommendation, goal_progress, collateral_damage, dimension changes
+
+12. **Act on recommendation:**
     - If `keep_change=true` — keep, suggest `memory_learn` if score > 0.7
     - If `keep_change=false` — `undo()`, explain why (collateral damage, goal regression)
 

package/livepilot/commands/mix.md

@@ -3,18 +3,42 @@ name: mix
 description: Mixing assistant — analyze and balance track levels, panning, and sends
 ---
 
-Help the user mix their session. Follow these steps:
+Help the user mix their session using the V2 orchestration pipeline.
 
-1. **Read the session** — `get_session_info` to see all tracks
-2. **Analyze each track** — `get_track_info` for clip and device details, check current volume/pan
-3. **Quick mix status** — `get_mix_summary` for a fast overview (track count, dynamics, stereo, issues)
-4. **Run critics** — `get_mix_issues` to detect problems (masking, dynamics, stereo width, headroom)
-5. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types, instruments, and detected issues
-6. **Apply with confirmation** — only change levels after the user approves each suggestion
-7. **Check return tracks** — `get_return_tracks` to see shared effects
-8. **Master chain** — `get_master_track` to review the master
-9. **Evaluate** — after changes, `evaluate_mix_move` with before/after snapshots to verify improvement
+## Orchestration Flow
 
-Present suggestions in a clear table format. Always explain the reasoning (e.g., "panning the hi-hats slightly right to create stereo width"). Use `undo` if the user doesn't like a change.
+1. **Session kernel** — `get_session_kernel(request_text=<user's request>, mode="improve")` for the full turn snapshot
+2. **Route** — `route_request(<user's request>)` to get engine routes + semantic move recommendations
+3. **Ensure analyzer** — if `get_master_spectrum` errors, load it: `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. If bridge disconnected, try `reconnect_bridge`.
+
+## Analysis Phase
+
+4. **Quick status** — `get_mix_summary` for track count, dynamics, stereo, issues
+5. **Run critics** — `get_mix_issues` for problems. `get_masking_report` for frequency collisions.
+6. **Spectral check** — `get_master_spectrum` for 8-band balance. Genre targets:
+   - Hip-hop: sub dominant, centroid 400-800 Hz
+   - Electronic: balanced, centroid 800-1500 Hz
+   - Ambient: mid-focused, low sub, centroid 500-1000 Hz
+7. **Musical intelligence** — `detect_role_conflicts` to find tracks competing for the same space. `detect_repetition_fatigue` if arrangement feels stale.
+
+## Decision Phase
+
+8. **Propose semantic moves** — `propose_next_best_move(request_text=<user's request>)` for ranked suggestions (e.g., `make_punchier`, `widen_stereo`, `tighten_low_end`)
+9. **Preview chosen move** — `preview_semantic_move(move_id)` to see the full compile plan before executing
+10. **Rank by taste** — if user has history, `rank_moves_by_taste(move_specs)` to personalize ordering
+
+## Execution Phase
+
+11. **Apply with approval** — `apply_semantic_move(move_id, mode="improve")` returns the compiled plan. Present it to the user: "I'd suggest: push Drums to 0.75, pull Pad to 0.25. Shall I do it?"
+12. **Verify after EVERY change** — read `value_string` in response, call `get_track_meters(include_stereo=true)`, check no track went silent
+13. **Capture + analyze** — `capture_audio` then `analyze_loudness` for LUFS/LRA, `analyze_spectrum_offline` for centroid/balance
+14. **Evaluate** — `evaluate_mix_move` with before/after snapshots. If `keep_change` is false, `undo` immediately.
+
+## Summary
+
+15. **Report** — "What I did / what improved / what I protected / what remains"
+16. **Session memory** — `add_session_memory` for notable decisions
+17. **Taste update** — successful moves update the TasteGraph automatically
 
 For deeper critic-driven iterative improvement, use the livepilot-mix-engine skill.
+For exploratory mode (try multiple ideas), use `create_experiment` + `run_experiment` + `compare_experiments`.

package/livepilot/commands/perform.md

@@ -3,28 +3,40 @@ name: perform
 description: Performance mode — enter a safety-constrained live performance context with energy tracking and safe moves
 ---
 
-Enter performance mode for live set support. All actions are constrained to safe and caution-level moves only.
+Enter performance mode with safety constraints and energy tracking.
 
-1. **Get performance state** — `get_performance_state` to see scene roles, energy levels, and current position
-2. **Show the dashboard** — present: current scene, energy level, energy direction (up/down/hold), available safe moves
-3. **Get safe moves** — `get_performance_safe_moves` for what can be done right now
-4. **Check before acting** — `check_safety(move_type)` before every action. Only execute safe or caution moves. Caution moves require user confirmation.
+## Orchestration Flow
 
-**BLOCKED during performance** (never execute, warn if requested):
-- Creating or deleting tracks, clips, or scenes
-- Editing notes or arrangement
-- Adding or removing devices (device chain surgery)
+1. **Session kernel** — `get_session_kernel(request_text="live performance", mode="improve")`
+2. **Route** — `route_request("live performance")` → workflow_mode should be `performance_safe`
+3. **Performance state** — `get_performance_state` for current scene, energy level, and safe moves
 
-**SAFE moves** (execute freely):
-- Scene launches, mute/unmute, volume nudges, send adjustments, macro tweaks, filter sweeps
+## Safety-First Rules
 
-**Scene transitions:**
-- `plan_scene_handoff(from_scene, to_scene)` — generates an energy path and gesture sequence
-- Follow the energy path: if going up, suggest high-energy scenes; if going down, suggest breakdowns
+- **NEVER** execute moves rated "high risk" during performance
+- **ALWAYS** use `get_performance_safe_moves` before ANY change
+- Only fire scenes, adjust volumes, and trigger safe effects
+- No device loading, track creation, or destructive operations
 
-**Always show:**
-- Current energy level and direction
-- What moves are available
-- What moves are blocked and why
+## Performance Tools
 
-Use the livepilot-performance-engine skill for safety classification and move suggestions.
+4. **Safe moves** — `get_performance_safe_moves` for available actions
+5. **Scene handoff** — `plan_scene_handoff` for safe transitions between scenes
+6. **Energy tracking** — monitor energy level across scene transitions
+7. **Semantic moves** — only performance-safe semantic moves:
+   - `smooth_scene_handoff` — safe transition between scenes
+   - Gesture templates: `pre_arrival_vacuum`, `re_entry_spotlight`
+
+## Live Dashboard
+
+8. **Monitor** — `get_track_meters(include_stereo=true)` for real-time levels
+9. **Spectrum** — `get_master_spectrum` for frequency balance during performance
+10. **Playing clips** — `get_playing_clips` to see what's active
+
+## Recovery
+
+11. **If something goes wrong** — `undo` immediately
+12. **Emergency** — `stop_all_clips` if audio goes haywire
+13. **Check safety** — `check_safety` to verify constraints are holding
+
+Keep the user informed of what's happening. Never make surprise changes during a live set.

package/livepilot/commands/sounddesign.md

@@ -3,20 +3,41 @@ name: sounddesign
 description: Sound design workflow — load instruments and effects, shape parameters for a target sound
 ---
 
-Guide the user through designing a sound. Follow these steps:
-
-1. **Ask about the target sound** — what character? (warm pad, aggressive bass, shimmering lead, atmospheric texture, etc.)
-2. **Choose an instrument** — pick the right synth for the job, load it with `search_browser` → `load_browser_item`
-3. **Verify device loaded** — `get_device_info` to confirm plugin initialized (AU/VST with `parameter_count` <= 1 = dead plugin — delete and replace with native alternative)
-4. **Get parameters** — `get_device_parameters` to see what's available
-5. **Shape the sound** — `set_device_parameter` or `batch_set_parameters` to dial in the character
-6. **Run critics** — `analyze_sound_design(track_index)` to check for static timbre, missing modulation, spectral imbalance
-7. **Address issues** — `plan_sound_design_move(track_index)` for suggested improvements
-8. **Add effects** — load effects (reverb, delay, chorus, distortion, etc.) and tweak their parameters
-9. **Create a test pattern** — `create_clip` + `add_notes` with a simple pattern to audition
-10. **Fire the clip** to listen, iterate based on feedback
-11. **Evaluate** — `evaluate_move(engine="sound_design")` with before/after to verify improvement
-
-Explain what each parameter does as you adjust it. Use `undo` liberally if something sounds wrong.
-
-For iterative critic-driven patch refinement, use the livepilot-sound-design-engine skill.
+Guide the user through designing a sound using the V2 orchestration pipeline.
+
+## Orchestration Flow
+
+1. **Session kernel** — `get_session_kernel(request_text=<user's request>, mode="improve")`
+2. **Route** — `route_request(<user's request>)` for engine routes + semantic moves
+
+## Design Phase
+
+3. **Ask about target** — what character? (warm pad, aggressive bass, shimmering lead, etc.)
+4. **Choose instrument** — `search_browser` to find devices, `load_browser_item` to load
+5. **Verify health** — `get_device_info` to confirm plugin initialized. Read `value_string` from `get_device_parameters` to understand actual units.
+6. **Shape sound** — `set_device_parameter` or `batch_set_parameters`. **ALWAYS read `value_string` in response** to confirm Hz/dB/% values make sense.
+7. **Verify after every change** — `get_track_meters(include_stereo=true)` — if stereo drops to 0, the effect killed the signal.
+
+## Critic Phase
+
+8. **Run critics** — `analyze_sound_design(track_index)` for static timbre, missing modulation, spectral imbalance
+9. **Plan improvements** — `plan_sound_design_move(track_index)` for suggested changes
+10. **Patch model** — `get_patch_model(track_index)` to see chain structure and controllable blocks
+
+## Effects & Automation
+
+11. **Add effects** — load with `find_and_load_device(track_index, device_name)`. Verify health.
+12. **Organic movement** — `apply_automation_shape(curve_type="perlin")` for filter/send drift
+13. **Automation recipes** — `apply_automation_recipe` for breathing, vinyl_crackle, auto_pan. Verify after applying.
+
+## Evaluation
+
+14. **Perception check** — `get_master_spectrum` or `capture_audio` + `analyze_spectrum_offline`
+15. **Evaluate** — `evaluate_move(goal_vector, before_snapshot, after_snapshot)` to score improvement
+
+## Summary
+
+16. **Report** — "What I changed / what improved / what I protected"
+17. **Memory** — if score > 0.7, suggest `memory_learn` to save the technique
+
+For critic-driven iterative refinement, use the livepilot-sound-design-engine skill.

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

@@ -134,4 +134,5 @@ For deeper compositional analysis beyond basic arrangement:
 
 ## Reference
 
-Consult `references/ableton-workflow-patterns.md` in the livepilot-core skill for session/arrangement workflow patterns, song structures by genre, follow action configurations, clip launch modes, and export settings.
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/ableton-workflow-patterns.md` — session/arrangement workflows, song structures by genre, follow actions, clip launch modes, export settings

package/livepilot/skills/livepilot-composition-engine/references/transition-archetypes.md

@@ -10,7 +10,7 @@ A filter or noise sweep that builds energy into the next section.
 - Duration: 2-8 bars
 - Implementation: ascending automation on filter cutoff (20% to 100%) plus optional white noise riser
 - Best for: verse-to-chorus, breakdown-to-drop
-- Tools: `set_clip_automation`, `apply_automation_shape(shape="exponential_rise")`
+- Tools: `set_clip_automation`, `apply_automation_shape(track_index, clip_index, parameter_type="device", curve_type="exponential", start=0, end=1)`
 
 ### drum_build
 Progressive addition of percussion layers leading to the downbeat.
@@ -52,7 +52,7 @@ Low-pass filter sweep closing down to muffle the sound.
 - Duration: 2-4 bars
 - Implementation: descending automation on master or bus filter cutoff (100% to 20-30%)
 - Best for: section endings, transitions to breakdowns
-- Tools: `set_clip_automation`, `apply_automation_shape(shape="exponential_fall")`
+- Tools: `set_clip_automation`, `apply_automation_shape(track_index, clip_index, parameter_type="device", curve_type="exponential", start=1, end=0)`
 
 ### reverb_wash
 Increase reverb wet level to blur the previous section into the next.

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

@@ -1,11 +1,11 @@
 ---
 name: livepilot-core
-description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 237 tools across 32 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
+description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 293 tools across 39 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
 ---
 
 # LivePilot Core — Ableton Live 12
 
-Agentic production system for Ableton Live 12. 237 tools across 32 domains, three layers:
+Agentic production system for Ableton Live 12. 293 tools across 39 domains, three layers:
 
 - **Device Atlas** — 280+ instruments, 139 drum kits, 350+ impulse responses. Consult `references/device-atlas/` before loading any device. Never guess a device name.
 - **M4L Analyzer** — Real-time audio analysis on the master bus (8-band spectrum, RMS/peak, key detection). Optional — all core tools work without it.
@@ -34,11 +34,12 @@ Agentic production system for Ableton Live 12. 237 tools across 32 domains, thre
     - If a track's stereo output drops to 0: the effect is killing the signal — check `get_device_parameters` for `value_string`, fix, re-verify
     - **Parameter ranges are NOT always 0-1.** Auto Filter Frequency is 20-135. Bit Depth is 1-16. Always read `value_string` to see actual units.
 16. **NEVER apply automation recipes without understanding the target parameter's range** — recipes generate 0-1 curves that get auto-scaled for device parameters, but always verify the result
+17. **LivePilot_Analyzer must be LAST on master chain** — always place after ALL effects (EQ, Compressor, Utility, etc.) so it measures the final post-processing output, not the raw signal. When loading effects on master, either load them before the analyzer or move the analyzer to end afterward
 
 ## Tool Speed Tiers
 
 ### Instant (<1s) — Use freely
-All 236 core tools plus M4L perception tools.
+All 293 tools plus M4L perception tools.
 
 ### Fast (1-5s) — Use freely
 `analyze_loudness` · `analyze_mix` · `analyze_sound_design`
@@ -63,6 +64,7 @@ Report ALL errors to the user immediately. Common failure modes:
 - **Connection timeout** — Ableton unresponsive → check if session is heavy
 - **Volume reset on scene fire** — Ableton restores mixer state when firing scenes. Always re-apply `set_track_volume`/`set_track_pan` after `fire_scene` if your mix settings differ from what was stored in the clips
 - **M4L Analyzer not connected** — if `get_master_spectrum` errors with "Analyzer not detected", auto-load it: `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. If it errors with "UDP bridge not connected", try `reconnect_bridge` first
+- **Another client connected** — Remote Script only accepts one TCP client on port 9878. If you see this error, the MCP server is already connected. Use MCP tools instead of raw TCP
 
 ## Technique Memory
 
@@ -71,6 +73,15 @@ Three modes:
 - **Fresh:** Skip memory when user wants something new ("ignore my history", "surprise me")
 - **Explicit recall:** `memory_recall` → `memory_get` → `memory_replay` when user references a saved technique
 
+## Wonder Mode — Stuck-Rescue Routing
+
+- Use Wonder (`enter_wonder_mode`) for creative ambiguity and session rescue
+- Do not fabricate three variants when only one real option exists
+- Do not describe a branch as previewable unless it has a valid `compiled_plan`
+- Prefer Wonder when `detect_stuckness` confidence > 0.5
+- Prefer Wonder when the user's request is emotionally-shaped, not parametric
+- Load `livepilot-wonder` skill for full workflow guidance
+
 ## Domain Skills
 
 For domain-specific workflows, load the appropriate skill:
@@ -100,7 +111,7 @@ Deep production knowledge in `references/`:
 
 | File | Content |
 |------|---------|
-| `references/overview.md` | All 237 tools with params and ranges |
+| `references/overview.md` | All 293 tools with params and ranges |
 | `references/device-atlas/` | 280+ device corpus with URIs and presets |
 | `references/midi-recipes.md` | Drum patterns, chord voicings, humanization |
 | `references/sound-design.md` | Synth recipes, device chain patterns |
@@ -109,3 +120,48 @@ Deep production knowledge in `references/`:
 | `references/ableton-workflow-patterns.md` | Session/arrangement workflows |
 | `references/memory-guide.md` | Technique memory usage and quality templates |
 | `references/m4l-devices.md` | M4L bridge command reference |
+
+## V2 Orchestration Layer
+
+For complex requests, use the V2 orchestration flow instead of ad-hoc tool calls:
+
+### Standard V2 Flow
+1. **`route_request`** — classify the request, get recommended engines and workflow mode
+2. **`get_session_kernel`** — build the unified turn snapshot (session, capabilities, taste, memory)
+3. **`propose_next_best_move`** — get ranked semantic move suggestions (taste-aware)
+4. **`preview_semantic_move`** — see what a move will do before committing
+5. **`apply_semantic_move`** — compile and execute the move (mode-dependent)
+6. **Evaluate** — use the appropriate evaluator to check the result
+
+### Semantic Moves
+High-level musical intents that compile to deterministic tool sequences. 5 families:
+- **mix** — `tighten_low_end`, `widen_stereo`, `make_punchier`, `darken_without_losing_width`, `reduce_repetition_fatigue`, `make_kick_bass_lock`, `reduce_foreground_competition`
+- **arrangement** — `create_buildup_tension`, `smooth_scene_handoff`, `increase_contrast_before_payoff`, `refresh_repeated_section`
+- **transition** — `increase_forward_motion`, `open_chorus`, `create_breakdown`, `bridge_sections`
+- **sound_design** — `add_warmth`, `add_texture`, `shape_transients`, `add_space`
+- **performance** — `recover_energy`, `decompress_tension`, `safe_spotlight`, `emergency_simplify`
+
+Use `list_semantic_moves(domain="mix")` to discover available moves.
+
+### Experiment Branching
+For creative exploration, use experiment branching to compare multiple approaches:
+1. `create_experiment(request_text="make it punchier")` — auto-proposes branches
+2. `run_experiment(experiment_id)` — trials each branch (apply → capture → undo)
+3. `compare_experiments(experiment_id)` — rank branches by score
+4. `commit_experiment(experiment_id, branch_id)` — apply winner permanently
+
+### Taste-Aware Ranking
+The system learns user preferences from kept/undone moves:
+- `get_taste_graph()` — current taste model
+- `explain_taste_inference()` — human-readable explanation
+- `rank_moves_by_taste(move_specs)` — sort options by preference fit
+- `propose_next_best_move` automatically applies taste ranking when evidence exists
+
+### Musical Intelligence
+Song-level analysis beyond parameters:
+- `detect_repetition_fatigue()` — clip overuse, section staleness
+- `detect_role_conflicts()` — tracks fighting for the same space
+- `infer_section_purposes()` — label sections as setup/tension/payoff/contrast/release
+- `score_emotional_arc()` — does the song have a satisfying build→climax→resolve?
+- `analyze_phrase_arc()` — capture and evaluate musical phrases
+- `compare_phrase_renders()` — compare phrase variants side by side

package/livepilot/skills/livepilot-core/references/device-atlas/distortion-and-character.md

@@ -11,7 +11,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Saturator
 
 - **Type:** Native (all editions)
-- **Load via:** `find_and_load_device("Saturator")`
+- **Load via:** `find_and_load_device(track_index, "Saturator")`
 - **What it does:** General-purpose waveshaping distortion. Pushes audio through a transfer curve that reshapes the waveform, adding harmonics. Ranges from imperceptible warmth to aggressive folding distortion depending on curve and drive. The most versatile single distortion device in Live.
 
 - **Signal flow:** Input -> Drive (gain stage) -> Waveshaper (selected curve) -> Color section (2-band post-EQ) -> Soft Clip (optional) -> Output gain -> Dry/Wet mix
@@ -50,7 +50,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Overdrive
 
 - **Type:** Native (all editions)
-- **Load via:** `find_and_load_device("Overdrive")`
+- **Load via:** `find_and_load_device(track_index, "Overdrive")`
 - **What it does:** Warm overdrive effect with a built-in bandpass filter that shapes the frequency range being distorted. Models the behavior of a guitar overdrive pedal: the bandpass focuses the distortion on the mids, preventing fizzy highs and muddy lows. Less versatile than Saturator but more immediately musical on guitars, bass, and keys.
 
 - **Signal flow:** Input -> Bandpass Filter (pre-distortion frequency focus) -> Distortion stage -> Tone control (post-distortion brightness) -> Dynamics control -> Output -> Dry/Wet
@@ -79,7 +79,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Erosion
 
 - **Type:** Native (all editions)
-- **Load via:** `find_and_load_device("Erosion")`
+- **Load via:** `find_and_load_device(track_index, "Erosion")`
 - **What it does:** Digital degradation effect. Modulates the audio signal with noise or a sine wave to create aliasing, digital artifacts, and high-frequency grit. Unlike analog-modeled distortion, Erosion sounds intentionally digital and broken. It creates artifacts that don't exist in the analog domain -- frequency-shifted noise clouds, aliasing products, digital "fuzz."
 
 - **Signal flow:** Input signal is ring-modulated/multiplied with a noise source or sine oscillator, creating sum-and-difference frequencies (aliasing artifacts). The result is mixed with the dry signal.
@@ -107,7 +107,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Redux
 
 - **Type:** Native (all editions, updated in Live 12)
-- **Load via:** `find_and_load_device("Redux")`
+- **Load via:** `find_and_load_device(track_index, "Redux")`
 - **What it does:** Bit crusher and sample rate reducer. Reduces the bit depth (fewer amplitude steps = quantization noise) and/or sample rate (fewer samples per second = aliasing) of the audio signal. The Live 12 update added new filter modes, jitter controls, and a modernized interface that makes it significantly more musical than the old version.
 
 - **Signal flow:** Input -> Downsample (sample rate reduction with selectable filter/interpolation) -> Bit Reduction (bit depth quantization) -> Output
@@ -138,7 +138,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Pedal
 
 - **Type:** Native (Standard/Suite, or as add-on)
-- **Load via:** `find_and_load_device("Pedal")`
+- **Load via:** `find_and_load_device(track_index, "Pedal")`
 - **What it does:** Guitar pedal emulation with three distinct distortion voicings. Designed to feel like stepping on a real stompbox. Each mode models a different class of guitar pedal circuit. More aggressive than Overdrive, more focused than Saturator, with a musical 3-band EQ.
 
 - **Signal flow:** Input -> Sub switch (optional low shelf boost) -> Gain stage (mode-dependent clipping circuit) -> 3-band EQ (Bass/Mid/Treble) -> Output gain -> Dry/Wet
@@ -172,7 +172,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Amp
 
 - **Type:** Native (Standard/Suite, or as add-on, developed with Softube)
-- **Load via:** `find_and_load_device("Amp")`
+- **Load via:** `find_and_load_device(track_index, "Amp")`
 - **What it does:** Physical modeling of seven classic guitar amplifier circuits. Each model captures the nonlinear behavior, EQ voicing, and breakup character of a real amp. Unlike Pedal (which is a pre-amp stompbox), Amp models the full amplifier including preamp gain stage, tone stack, and power amp saturation.
 
 - **Signal flow:** Input -> Gain (preamp drive) -> Tone Stack (Bass/Middle/Treble - interactive like real amps) -> Power Amp (Volume - controls power amp saturation) -> Presence (post-power-amp HF control) -> Output -> Dry/Wet
@@ -210,7 +210,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Cabinet
 
 - **Type:** Native (Standard/Suite, or as add-on, developed with Softube)
-- **Load via:** `find_and_load_device("Cabinet")`
+- **Load via:** `find_and_load_device(track_index, "Cabinet")`
 - **What it does:** Convolution-based speaker cabinet emulation. Models the frequency response and resonance of classic guitar/bass speaker cabinets with selectable virtual microphones and mic positions. Transforms the raw, harsh output of Amp into a natural, speaker-shaped tone. Essential companion to Amp.
 
 - **Signal flow:** Input -> Cabinet impulse response (convolution) -> Microphone model -> Mic Position -> Output -> Dry/Wet
@@ -241,7 +241,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Dynamic Tube
 
 - **Type:** Native (Standard/Suite)
-- **Load via:** `find_and_load_device("Dynamic Tube")`
+- **Load via:** `find_and_load_device(track_index, "Dynamic Tube")`
 - **What it does:** Tube saturation with an input-following envelope. The distortion amount responds dynamically to the signal level -- louder passages get more saturation, quiet passages stay cleaner. This mimics how real tube circuits behave: they saturate progressively as the signal increases. Three tube models offer different saturation colors.
 
 - **Signal flow:** Input -> Envelope Follower (detects input level) -> Tube saturation stage (model-dependent, amount modulated by envelope) -> Tone control -> Output -> Dry/Wet
@@ -274,7 +274,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Vinyl Distortion
 
 - **Type:** Native (Standard/Suite)
-- **Load via:** `find_and_load_device("Vinyl Distortion")`
+- **Load via:** `find_and_load_device(track_index, "Vinyl Distortion")`
 - **What it does:** Emulates the physical artifacts of vinyl record playback. Two independent distortion models (Tracing and Pinch) simulate different aspects of needle-on-groove behavior, plus a Crackle generator for surface noise. Creates that "sampled from vinyl" character heard in lo-fi hip-hop, downtempo, and sample-based production.
 
 - **Signal flow:** Input -> Tracing Model (simulates needle tracking distortion) + Pinch Effect (simulates pinch distortion) -> Crackle generator (added noise) -> Output -> Dry/Wet
@@ -306,7 +306,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Roar
 
 - **Type:** Native (Live 12 add-on, EUR 99)
-- **Load via:** `find_and_load_device("Roar")`
+- **Load via:** `find_and_load_device(track_index, "Roar")`
 - **What it does:** Live 12's flagship distortion -- a multi-stage distortion synthesizer with flexible routing, feedback loops, modulation, and compression. Three independent gain stages (each with its own shaper and filter), six routing topologies, four modulation sources, and a feedback section with delay. Roar can do everything from subtle tape warming to screaming feedback distortion to multi-band destruction. It is a distortion design environment, not just an effect.
 
 - **Signal flow:** Input -> Drive/Tone (global input shaping) -> Routing topology (distributes signal to gain stages) -> Gain Stage(s) (each: shaper + pre/post filter) -> Feedback section (delay with compressor) -> Global Compressor -> Output -> Dry/Wet
@@ -376,7 +376,7 @@ Complete sonic atlas for every distortion, saturation, and coloration device ava
 ### Drum Buss (Distortion Aspect)
 
 - **Type:** Native (Standard/Suite)
-- **Load via:** `find_and_load_device("Drum Buss")`
+- **Load via:** `find_and_load_device(track_index, "Drum Buss")`
 - **What it does:** All-in-one drum processing combining drive/distortion, transient shaping, bass enhancement, and damping. The distortion section specifically adds harmonic density and aggression to drum buses. While it's a multi-function device, the Drive section alone makes it worth including here.
 
 - **Signal flow:** Input -> Trim -> Drive section (distortion with 3 types) -> Crunch (compressive distortion) -> Transients -> Boom (resonant bass boost) -> Damping (HF control) -> Output -> Dry/Wet