livepilot 1.9.22 → 1.9.24

package/livepilot/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.22",
-  "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.9.24",
+  "description": "Agentic production system for Ableton Live 12 — 293 tools, 39 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }

package/livepilot/agents/livepilot-producer/AGENT.md

@@ -8,6 +8,7 @@ tools:
   - Read
   - Glob
   - Grep
+  - ToolSearch
 ---
 
 You are LivePilot Producer — an autonomous music production agent for Ableton Live 12 powered by Agent OS V1.
@@ -200,6 +201,7 @@ After loading any instrument:
 | Track volume? | `get_track_info` | `mixer.volume` > 0.5 for primary tracks |
 | Track not muted? | `get_track_info` | `mute: false` |
 | Master audible? | `get_master_track` | `volume` > 0.5 |
+| Analyzer at end? | `get_master_track` | LivePilot_Analyzer is LAST device (after all effects) |
 
 ### Critical device loading rules:
 
@@ -283,6 +285,17 @@ Load the appropriate skill for domain-specific guidance:
 - **livepilot-performance-engine** — live performance safety constraints
 - **livepilot-evaluation** — universal before/after evaluation loop
 
+## Tool Access
+
+MCP tools (all `mcp__livepilot__*` tools) should be available to you. If they are NOT in your tool namespace:
+
+1. Try using `ToolSearch` with query `"livepilot"` to discover and load them
+2. If that fails, **tell the user immediately**: "MCP tools not available in this subagent session"
+3. Do NOT fall back to reading code and planning — that wastes tokens
+4. Suggest running the task in the main conversation instead
+
+**NEVER just read files and describe what you would do. You must call MCP tools to control Ableton.**
+
 ## Rules
 
 - Load relevant skills before starting domain-specific work

package/livepilot/commands/arrange.md

@@ -3,26 +3,45 @@ name: arrange
 description: Guided arrangement — build song structure with sections, transitions, and energy flow
 ---
 
-Guide the user through arranging their session into a full song structure.
-
-1. **Read the session** — `get_session_info` to see all tracks and clips. `get_scene_matrix` for the full clip grid.
-2. **Analyze current structure** — `get_section_graph` to see inferred sections from scene names. `get_emotional_arc` to understand current energy flow.
-3. **Detect motifs** — `get_motif_graph` to find recurring patterns, fatigue risk, and suggested developments (inversion, augmentation, fragmentation).
-4. **Ask about the target structure** — what form? (verse-chorus, AABA, build-drop, through-composed). What energy arc? (gradual build, peaks and valleys, flat)
-5. **Plan the arrangement** — `plan_arrangement` with the target bar count and style. Review the proposed section order, transitions, and gesture templates.
-6. **Build sections** — for each section, create or duplicate scenes, set scene names and colors. Use `duplicate_scene` for variations. Use `transform_motif` for melodic development (inversion, retrograde, diminution, augmentation).
-7. **Apply gesture templates** — for each transition, use `apply_gesture_template` with the planned template:
-   - `pre_arrival_vacuum` — pull energy back before a drop
-   - `harmonic_tint_rise` — gradually open filters for intro/build sections
-   - `re_entry_spotlight` — darken then snap back to highlight returning elements
-   - `tension_ratchet` — stepped build in 4-bar stages
-   - `outro_decay_dissolve` — gradual dissolution for endings
-   - `phrase_end_throw` — reverb/delay throw at section boundaries
-   Then execute each gesture plan using `apply_automation_shape` with the suggested curve_family.
-8. **Add organic movement** — use `apply_automation_shape` with `curve_type="perlin"` on filter/send/effect parameters so nothing repeats exactly the same each cycle.
-9. **Check emotional arc** — `get_emotional_arc` to verify the energy flow matches the target. Address any issues flagged (no_clear_build, peak_too_early, no_resolution).
-10. **Verify with perception** — `get_master_spectrum` during each section to confirm spectral differentiation. `capture_audio` + `analyze_loudness` to check LRA (should be >2 LU for dynamic arrangements).
-11. **Translation check** — `check_translation` to verify mono compatibility and spectral consistency across sections.
-12. **Record to arrangement** — when satisfied, use `create_arrangement_clip` to lay out clips on the timeline, or guide the user through `back_to_arranger` and recording the session performance.
-
-Use the livepilot-composition-engine skill for section analysis and transition planning. Present the arrangement as a visual timeline to the user.
+Guide the user through arranging their session 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
+
+## Analysis Phase
+
+3. **Scene matrix** — `get_scene_matrix` for the full clip grid
+4. **Section purposes** — `infer_section_purposes` to understand what each scene is doing
+5. **Emotional arc** — `score_emotional_arc` — does the song have build → climax → resolve?
+6. **Repetition check** — `detect_repetition_fatigue` — are patterns overused?
+7. **Motif analysis** — `get_motif_graph` for recurring patterns and fatigue risk
+8. **Role conflicts** — `detect_role_conflicts` to find competing tracks
+
+## Planning Phase
+
+9. **Ask about target** — what form? (verse-chorus, build-drop, through-composed). What energy arc?
+10. **Plan arrangement** — `plan_arrangement(target_bars, style)` for section blueprint
+11. **Propose moves** — `propose_next_best_move(request_text)` for arrangement semantic moves (e.g., `create_buildup_tension`, `smooth_scene_handoff`)
+12. **Preview** — `preview_semantic_move(move_id)` to see the gesture plan
+
+## Execution Phase
+
+13. **Build sections** — duplicate scenes, set names/colors, use `transform_motif` for melodic development
+14. **Apply gestures** — `apply_gesture_template` for transitions:
+    - `pre_arrival_vacuum` — energy suck before drops
+    - `harmonic_tint_rise` — filter opening for intros
+    - `re_entry_spotlight` — highlight returning elements
+    - `tension_ratchet` — stepped energy build
+    - `outro_decay_dissolve` — gradual dissolution
+15. **Add organic movement** — `apply_automation_shape(curve_type="perlin")` on filters/sends
+16. **Verify arc** — `score_emotional_arc` again to confirm improvement
+17. **Perception check** — `capture_audio` + `analyze_loudness` to verify LRA > 2 LU
+
+## Summary
+
+18. **Report** — "What I did / what improved / what I protected / what remains"
+19. **Session memory** — `add_session_memory` for arrangement decisions
+
+For exploratory arrangement, use `create_experiment` to try multiple section orderings.

package/livepilot/commands/mix.md

@@ -3,27 +3,42 @@ name: mix
 description: Mixing assistant — analyze and balance track levels, panning, and sends
 ---
 
-Help the user mix their session. Follow these steps:
-
-1. **Read the session** — `get_session_info` to see all tracks
-2. **Ensure analyzer** — check if M4L Analyzer is on master. If `get_master_spectrum` errors, load it: `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. If bridge disconnected, try `reconnect_bridge`.
-3. **Analyze each track** — `get_track_info` for clip and device details, `get_track_meters(include_stereo=true)` for actual output levels
-4. **Quick mix status** — `get_mix_summary` for a fast overview (track count, dynamics, stereo, issues)
-5. **Run critics** — `get_mix_issues` to detect problems (masking, dynamics, stereo width, headroom). For frequency collisions: `get_masking_report`
-6. **Spectral check** — `get_master_spectrum` for 8-band frequency balance. Typical targets:
+Help the user mix their session using the V2 orchestration pipeline.
+
+## Orchestration Flow
+
+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. **Suggest a mix** — propose volume levels, panning positions, and send amounts based on the track types, instruments, and detected issues
-8. **Apply with verification** — after EVERY volume/pan/send change:
-   - Read `value_string` in the response
-   - Call `get_track_meters(include_stereo=true)` to verify no track went silent
-   - Check master spectrum to verify the balance improved
-9. **Check return tracks** — `get_return_tracks` to see shared effects
-10. **Master chain** — `get_master_track` to review the master. Typical chain: Glue Compressor → EQ Eight → Utility → LivePilot_Analyzer
-11. **Capture + analyze** — `capture_audio` then `analyze_loudness` for LUFS/peak/LRA, `analyze_spectrum_offline` for centroid/rolloff/balance
-12. **Evaluate** — `evaluate_mix_move` with before/after snapshots to verify improvement. If `keep_change` is false, `undo` immediately.
-
-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.
+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,28 +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. **Read `value_string`** to understand actual units (Hz, dB, %, ms) — raw values are often NOT in human units.
-5. **Shape the sound** — `set_device_parameter` or `batch_set_parameters` to dial in the character
-   - **ALWAYS read `value_string` in the response** to confirm the actual value makes sense
-   - **ALWAYS call `get_track_meters(include_stereo=true)` after filter/effect changes** — verify the track still produces audio
-   - If stereo output drops to 0, the effect is killing the signal. Check `value_string`, fix, re-verify.
-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, `get_patch_model` to see chain structure
-8. **Add effects** — load effects and tweak. For automation, use `apply_automation_shape` with musically appropriate curve types:
-   - Filter sweeps → exponential (perceptually even)
-   - Volume fades → logarithmic (matches ear's response)
-   - Organic movement → perlin (never repeats exactly)
-   - If using `apply_automation_recipe`, verify the recipe didn't push parameters to extremes
-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. **Perception check** — `get_master_spectrum` or `capture_audio` + `analyze_spectrum_offline` to verify the sound sits correctly in the frequency spectrum
-12. **Evaluate** — `evaluate_move` with before/after snapshots 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