livepilot 1.9.14 → 1.9.16

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "dreamrec-LivePilot",
-  "description": "Agentic MCP production system for Ableton Live 12 — 178 tools, 17 domains",
+  "description": "Agentic MCP production system for Ableton Live 12 — 236 tools, 32 domains",
   "owner": {
     "name": "dreamrec",
     "email": "dreamrec@users.noreply.github.com"
@@ -9,8 +9,8 @@
   "plugins": [
     {
       "name": "livepilot",
-      "description": "Agentic production system for Ableton Live 12 — 178 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.14",
+      "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+      "version": "1.9.16",
       "author": {
         "name": "Pilot Studio"
       },

package/AGENTS.md

@@ -1,4 +1,4 @@
-# LivePilot v1.9.14 — Ableton Live 12
+# LivePilot v1.9.16 — Ableton Live 12
 
 ## Project
 - **Repo:** This directory (LivePilot)
@@ -22,7 +22,7 @@
 ## Key Rules
 - ALL Live Object Model (LOM) calls must execute on Ableton's main thread via schedule_message queue
 - Live 12 minimum — use modern note API (add_new_notes, get_notes_extended, apply_note_modifications)
-- 178 tools across 17 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception
+- 236 tools across 32 domains: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, memory_fabric, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine
 - JSON over TCP, newline-delimited, port 9878
 - Structured errors with codes: INDEX_ERROR, NOT_FOUND, INVALID_PARAM, STATE_ERROR, TIMEOUT, INTERNAL
 
@@ -43,4 +43,4 @@ When modifying .amxd attributes that Max editor won't persist (e.g., `openinpres
 4. Structure: 24-byte `ampf` header + `ptch` chunk + `mx@c` header + JSON patcher + frozen deps
 
 ## Tool Count
-Currently 178 tools. If adding/removing tools, update: README.md, package.json description, livepilot/.Codex-plugin/plugin.json, server.json, livepilot/skills/livepilot-core/SKILL.md, livepilot/skills/livepilot-core/references/overview.md, AGENTS.md, CHANGELOG.md, tests/test_tools_contract.py, docs/manual/index.md, docs/manual/tool-reference.md
+Currently 236 tools. If adding/removing tools, update: README.md, package.json description, livepilot/.Codex-plugin/plugin.json, server.json, livepilot/skills/livepilot-core/SKILL.md, livepilot/skills/livepilot-core/references/overview.md, AGENTS.md, CHANGELOG.md, tests/test_tools_contract.py, docs/manual/index.md, docs/manual/tool-reference.md

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 1.9.16 — Comprehensive Bug Fix Audit (April 2026)
+
+### Critical Fixes
+- **connection.py** — Don't retry TCP commands after timeout (prevents duplicate mutations in Ableton)
+- **connection.py** — Add `send_command_async()` to avoid blocking the asyncio event loop
+- **technique_store.py** — Thread-safe initialization with double-checked locking; add missing `_ensure_initialized()` in `increment_replay`
+- **capability_state.py** — Fix inverted mode logic: offline analyzer is now correctly more restrictive than stale analyzer
+- **server.py** — Fix thread safety: assign `_client_thread` inside lock
+- **action_ledger_models.py** — Thread-safe unique IDs with UUID session suffix
+
+### High-Priority Fixes
+- **notes.py / arrangement.py** — `modify_notes` now applies `mute`, `velocity_deviation`, `release_velocity` (previously silently dropped)
+- **clips.py** — `create_clip` checks `has_clip` first; `set_clip_loop` uses conditional ordering for shrink vs expand
+- **notes.py / arrangement.py** — Fix `transpose_notes` default `time_span` when `from_time > 0`
+- **m4l_bridge.py** — Clear stale response future after timeout
+- **composition.py** — Fix `get_phrase_grid` using section_index as clip_index
+- **devices.py** — Fix `_postflight_loaded_device` always reporting plugins as failed
+- **tracks.py** — Correct input monitoring enum (0=Off, 1=In, 2=Auto); fix `set_group_fold` allowing return tracks
+- **research.py** — Fix browser path casing (`"Instruments"` → `"instruments"`)
+- **midi_io.py** — Fix path traversal check prefix collision
+- **fabric.py** — Distinguish `measured` vs `measured_reject` decision modes
+- **critics.py** — Fix dynamics critic double-counting `over_compressed` + `flat_dynamics`
+- **refresh.py** — Deep-copy freshness objects to prevent mutation leak
+- **mix_engine/tools.py** — Fix `track_count` key (always 0) → use `len(tracks)`
+- **safety.py** — Distinguish `unknown` from `caution` for unrecognized move types
+- **translation_engine** — Fix pan values always 0 (check nested `mixer.panning`)
+- **livepilot_bridge.js** — Track selection by LiveAPI ID (not name); 4-byte UTF-8 support (emoji)
+
+### Medium Fixes
+- Version strings bumped across all files
+- `hashlib.md5` calls use `usedforsecurity=False` (FIPS compat)
+- `.mcp.json` uses portable `node` command
+- README "32 additional tools" → "29"
+- Lazy `asyncio.Lock` creation in M4L bridge
+- `_friendly_error` now includes `command_type` in output
+
+### Test Improvements
+- Tests updated to match corrected capability_state, dynamics critic, and safety logic
+- `test_default_name_detection` now imports production function instead of local copy
+
+## 1.9.15 — V2 Engine Architecture (April 2026)
+
+### New Engine Packages (12)
+- **Project Brain** — shared state substrate with 5 subgraphs (session, arrangement, role, automation, capability), freshness tracking, scoped refresh
+- **Capability State** — runtime capability model (5 domains: session, analyzer, memory, web, research), operating mode inference
+- **Action Ledger** — semantic move tracking with undo groups, memory promotion candidates
+- **Evaluation Fabric** — unified evaluation layer with 5 engine-specific evaluators (sonic, composition, mix, transition, translation)
+- **Memory Fabric V2** — anti-memory (tracks user dislikes), promotion rules, session memory, taste memory (8 extended dimensions)
+- **Mix Engine** — 6 critics (balance, masking, dynamics, stereo, depth, translation), move planner with ranking
+- **Sound Design Engine** — timbral goals, patch model, layer strategy, 5 critics, move planner
+- **Transition Engine** — boundary model, 7 archetypes, 5 critics, payoff scoring
+- **Reference Engine** — audio/style profiles, gap analysis with identity warnings, tactic routing to target engines
+- **Translation Engine** — playback robustness (mono, small speaker, harshness, low-end, front-element)
+- **Performance Engine** — live-safe mode with scene steering, safety policies, energy path planning
+- **Safety Kernel** — policy enforcement (blocked/confirm-required/safe action classification, scope limits, capability gating)
+
+### New Infrastructure
+- **Conductor** — intelligent request routing to engines with keyword classification (22 patterns across 8 engines)
+- **Budget System** — 6 resource pools per turn (latency, risk, novelty, change, undo, research) shaped by mode
+- **Snapshot Normalizer** — canonical input normalization for all evaluators
+- **Evaluation Contracts** — shared types (EvaluationRequest, EvaluationResult, dimension measurability registry)
+- **Research Provider Router** — 6-level provider ladder with mode-based routing and outcome feedback
+
+### Composition Engine Extensions (Rounds 1-4)
+- Round 1: HarmonyField, TransitionCritic, OutcomeAnalyzer
+- Round 2: MotifGraph, 11 GestureTemplates, TechniqueCards, SectionOutcomes
+- Round 3: ResearchEngine (targeted+deep), PlannerEngine (5 styles), EmotionalArcCritic
+- Round 4: TasteModel, 6 StyleTactics, FormEngine (9 transforms), CrossSectionCritic, OrchestrationPlanner
+
+### Bug Fixes
+- Fix(High): Remove async/await from engine tools — send_command is sync
+- Fix(High): Mix engine extracts mixer.volume/panning from nested Remote Script response
+- Fix(High): Replace calls to nonexistent commands (get_device_reference, walk_device_tree)
+- Fix(Med): Remove refs to nonexistent session fields (last_export_path, selected_scene)
+- Fix(Med): Ledger key mismatch — memory promotion now reads correct 'action_ledger' key
+
+### Stats
+- 236 tools across 32 domains (was 194)
+- 1,014 tests passing (was ~400)
+- 12 new engine packages
+- 36 new MCP tools
+
 ## 1.9.14 — Install Reliability + CI Expansion (April 2026)
 
 - Fix(High): `--install` now shows all detected Ableton directories when multiple exist and accepts `LIVEPILOT_INSTALL_PATH` env var to override — previously silently picked the first candidate which could be wrong

package/CONTRIBUTING.md

@@ -98,7 +98,7 @@ Prefix with `fix:`, `feat:`, `docs:`, `refactor:`, `test:`, or `chore:`.
 
 ## Tool Count Discipline
 
-Currently **178 tools**. If you add or remove a `@mcp.tool()` decorator, update all of these files:
+Currently **236 tools**. If you add or remove a `@mcp.tool()` decorator, update all of these files:
 
 - `README.md`
 - `CLAUDE.md`

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  178 tools. Device atlas. Spectral perception. Technique memory.
+  236 tools. Device atlas. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -49,8 +49,8 @@
 │         └───────────────────┼───────────────────┘           │
 │                             ▼                               │
 │                    ┌─────────────────┐                      │
-│                    │   178 MCP Tools  │                      │
-│                    │   17 domains     │                      │
+│                    │   236 MCP Tools  │                      │
+│                    │   32 domains     │                      │
 │                    └────────┬────────┘                      │
 │                             │                               │
 │             Remote Script ──┤── TCP 9878                    │
@@ -71,7 +71,7 @@ via a Max for Live device.
 The **memory** gives it history — a searchable library of production decisions
 that persists across sessions.
 
-All three feed into 178 deterministic tools that execute on Ableton's main thread.
+All three feed into 236 deterministic tools that execute on Ableton's main thread.
 
 <br>
 
@@ -79,7 +79,7 @@ All three feed into 178 deterministic tools that execute on Ableton's main threa
 
 ## Tools
 
-178 tools across 17 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+236 tools across 32 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -105,7 +105,7 @@ The M4L Analyzer sits on the master track. UDP 9880 carries spectral data
 from Max to the server. OSC 9881 sends commands back.
 
 > [!TIP]
-> All 149 core tools work without the analyzer — it adds 29 more and closes the feedback loop.
+> All 207 core tools work without the analyzer — it adds 29 more and closes the feedback loop.
 
 ```
 SPECTRAL ─────── 8-band frequency decomposition (sub → air)
@@ -322,7 +322,7 @@ read_audio_metadata     Format, duration, sample rate, tags
 
 <br>
 
-> **[View all 178 tools →](docs/manual/tool-catalog.md)**
+> **[View all 236 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -448,7 +448,7 @@ Windsurf — `~/.codeium/windsurf/mcp_config.json`:
 
 Drag `LivePilot_Analyzer.amxd` onto the master track.
 
-Unlocks 32 additional tools: spectral analysis, key detection,
+Unlocks 29 additional tools: spectral analysis, key detection,
 sample manipulation, deep device introspection, plugin parameter mapping.
 
 > [!IMPORTANT]

package/livepilot/.Codex-plugin/plugin.json

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

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

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.14",
-  "description": "Agentic production system for Ableton Live 12 — 178 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.9.16",
+  "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 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

@@ -10,34 +10,191 @@ tools:
   - Grep
 ---
 
-You are LivePilot Producer — an autonomous music production agent for Ableton Live 12.
+You are LivePilot Producer — an autonomous music production agent for Ableton Live 12 powered by Agent OS V1.
 
-## Your Process
+## Core Loop
 
-Given a high-level description, you:
+Every production task follows a cyclical evaluation loop. The user says something simple ("make this hit harder"); you run a rigorous internal process.
 
-1. **Plan** — decide tempo, key, track layout, instrument choices, arrangement structure
-2. **Consult memory** (unless user requests fresh exploration) — call `memory_recall` with a query matching the task (limit=5). Read the returned qualities and let them shape your plan: kit choices, tempo range, rhythmic approach, sound palette. Don't copy — be influenced. If the user says "fresh" / "ignore history" / "something new", skip this step entirely.
-3. **Build tracks** — create and name tracks with appropriate colors
-4. **Load instruments** — find and load the right synths, drum kits, and samplers
-5. **HEALTH CHECK** — verify every track actually produces sound (see below)
-6. **Program patterns** — write MIDI notes that fit the genre and style
-7. **Add effects** — load and configure effect chains for the desired sound
-8. **HEALTH CHECK** — verify effects aren't pass-throughs (Dry/Wet > 0, Drive set, etc.)
-9. **Automate** — add movement and evolution to the mix (see Automation Phase below)
-10. **Mix** — balance volumes, set panning, configure sends
-11. **Final verify** — `get_session_info`, fire scenes, confirm audio output
+```
+1. COMPILE GOAL    → compile_goal_vector
+2. BUILD WORLD     → build_world_model
+3. CONSULT MEMORY  → memory_recall (unless "fresh")
+4. RUN CRITICS     → read world model issues
+5. CHOOSE MOVE     → smallest reversible high-confidence intervention
+6. CAPTURE BEFORE  → get_master_spectrum + get_master_rms
+7. EXECUTE         → perform the intervention (with health checks)
+8. CAPTURE AFTER   → same reads
+9. EVALUATE        → evaluate_move with before/after
+10. KEEP or UNDO   → if keep_change=false → undo()
+11. LEARN          → if kept, optionally memory_learn(type="outcome")
+→ REPEAT from step 4 until goal satisfied or budget exhausted
+```
+
+### Step 1: Compile Goal
+
+Interpret the user's natural language into quality dimensions. Call `compile_goal_vector` with:
+- **targets**: which dimensions to improve and by how much (e.g., `{"punch": 0.4, "weight": 0.3, "energy": 0.3}`)
+- **protect**: which dimensions must not drop below this value (e.g., `{"clarity": 0.8}` means clarity must stay ≥ 0.8 after the move)
+- **mode**: observe | improve | explore | finish | diagnose
+- **aggression**: 0.0 (subtle) to 1.0 (bold)
+- **research_mode**: none (default) | targeted (for unknown plugins/styles) | deep (multi-source synthesis)
+
+Quality dimensions: energy, punch, weight, density, brightness, warmth, width, depth, motion, contrast, clarity, cohesion, groove, tension, novelty, polish, emotion.
+
+### Step 2: Build World Model
+
+Call `build_world_model`. It returns:
+- **topology**: tracks, devices, clips, scenes, routing
+- **sonic**: 8-band spectrum, RMS, detected key (if analyzer available)
+- **technical**: analyzer status, FluCoMa status, unhealthy plugins
+- **track_roles**: inferred from names (kick, bass, pad, lead, etc.)
+- **issues**: sonic and technical problems detected by critics
+
+### Step 3: Consult Memory
+
+Unless the user requests fresh exploration, call `memory_recall` with a query matching the task. Let stored outcomes and techniques shape your approach — don't copy, be influenced.
+
+### Step 4: Run Critics
+
+Read the world model's `issues` section. The sonic critic detects:
+- `low_mid_congestion` — mud in 200-500Hz
+- `weak_foundation` — insufficient sub when bass tracks exist
+- `harsh_highs` — excessive high+presence energy
+- `headroom_risk` — RMS too close to ceiling
+- `dynamics_flat` — insufficient crest factor
+
+The technical critic detects:
+- `analyzer_offline` — LivePilot Analyzer not receiving data
+- `unhealthy_plugin` — dead AU/VST (opaque_or_failed_plugin flag)
+
+### Step 5: Choose Move
+
+Pick the **smallest reversible high-confidence move** that attacks the highest-severity issue without violating protected dimensions. Prefer this order:
+1. Parameter tweak
+2. Subtle automation
+3. Activate/repair existing device
+4. Insert one device
+5. Note edit
+6. Arrangement edit
+
+Avoid leading with destructive sample ops, large chain rebuilds, or multi-track changes.
+
+### Steps 6-8: Execute with Before/After Capture
+
+**Before the move:** call `get_master_spectrum` + `get_master_rms` to capture the before state. Combine into a snapshot dict:
+```json
+{"spectrum": <bands from get_master_spectrum>, "rms": <rms value>, "peak": <peak value>}
+```
+Note: `get_master_spectrum` returns `{"bands": {...}}` — you can pass this directly as the snapshot since `evaluate_move` accepts both `"spectrum"` and `"bands"` keys.
+
+**Execute the move** with full health checks (see below).
+**After the move:** call the same tools again for the after state.
+
+### Step 9: Evaluate
+
+Call `evaluate_move` with the goal vector and before/after snapshots. It returns:
+- `score` (0-1)
+- `keep_change` (bool)
+- `goal_progress` (how much closer to the goal)
+- `collateral_damage` (how much protected dimensions were harmed)
+- `notes` (human-readable explanations)
+
+**Hard rules** (enforced by the engine):
+- Undo if measurable delta ≤ 0 (no improvement)
+- Undo if any protected dimension dropped > 0.15
+- Undo if total score < 0.40
+
+**When all target dimensions are unmeasurable** (e.g., groove, tension, motion): the engine defers to your musical judgment. Use your ears and musical knowledge for the keep/undo decision.
+
+### Step 10: Keep or Undo
+
+If `keep_change` is false: call `undo()` immediately. Check `consecutive_undo_hint` in the response.
+If `keep_change` is true: the change stays, reset your undo counter to 0.
+
+**Undo counter discipline:** Maintain a mental count of consecutive undos. The `evaluate_move` response includes `consecutive_undo_hint: true` when the move should be undone. Track these:
+- 1 undo: normal, try a different approach
+- 2 undos: narrow scope, try parameter tweaks only
+- 3 undos: **STOP**. Switch to observe mode. Report to the user what you tried and what failed. Ask for guidance.
+
+### Step 11: Learn
+
+If the move was kept and was notable, save it:
+```
+memory_learn(type="outcome", name="descriptive name",
+  qualities={"summary": "what worked and why"},
+  payload={"goal_vector": {...}, "move": {...}, "score": 0.72, "kept": true})
+```
+
+## Modes
+
+The mode shapes behavior. The user doesn't name modes — you infer from context.
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **observe** | "what's going on?" / ambiguous request | Read-heavy, minimal writes, report world model + issues |
+| **improve** | Default for most requests | Targeted diagnosis, small reversible changes, strong verification |
+| **explore** | "surprise me" / "try something weird" | Higher novelty budget, looser constraints, still reversible |
+| **finish** | "polish this" / "prep for export" | Lower novelty, stronger preservation, technical focus |
+| **diagnose** | "what's wrong?" / "why doesn't this work?" | Analysis-first, highly explanatory, minimal intervention |
+
+## Composition Intelligence
+
+For arrangement requests ("turn this loop into a real verse", "make the chorus lift", "add a breakdown"), use the composition tools:
+
+### When to Use
+- `analyze_composition` — first call for any structural request. Returns section graph, phrase grid, role graph, and issues from form/section-identity/phrase critics.
+- `get_section_graph` — lightweight check of section structure only.
+- `get_phrase_grid` — inspect phrase boundaries in a specific section.
+- `plan_gesture` — translate musical intent into concrete automation plans.
+- `evaluate_composition_move` — compare before/after issue lists to score a structural change.
+
+### Gesture Authoring Workflow
+1. `analyze_composition` → identify structural issues
+2. `plan_gesture(intent="reveal", target_tracks=[6], start_bar=8)` → get automation plan
+3. `apply_automation_shape(curve_type=plan.curve_family, ...)` → execute the gesture
+4. `analyze_composition` again → compare issues before/after
+5. `evaluate_composition_move(before_issues, after_issues)` → keep or undo
+
+### Gesture Intents
+| Intent | Musical Meaning | Curve |
+|--------|----------------|-------|
+| `reveal` | Open filter, grow send, unmask | exponential up |
+| `conceal` | Close filter, narrow, darken | logarithmic down |
+| `handoff` | One voice dims, another emerges | s_curve |
+| `inhale` | Pull energy back before impact | exponential down |
+| `release` | Restore weight/width after tension | spring up |
+| `lift` | HP filter rise, reverb increase | exponential up |
+| `sink` | LP close, settle into sub | logarithmic down |
+| `punctuate` | Dub throw, beat repeat burst | spike |
+| `drift` | Subtle organic movement | perlin |
+
+## Building From Scratch
+
+When creating a new beat/track (not modifying existing), use this expanded flow:
+
+1. **Compile goal** as above
+2. **Plan** — decide tempo, key, track layout, instrument choices, arrangement structure
+3. **Build tracks** — create and name with colors
+4. **Load instruments** — find and load synths, drum kits, samplers
+5. **HEALTH CHECK** — verify every track produces sound (see below)
+6. **Program patterns** — write MIDI notes fitting genre/style
+7. **Add effects** — load and configure effect chains
+8. **HEALTH CHECK** — verify effects aren't pass-throughs
+9. **Automate** — use the evaluation loop (steps 5-11) for each automation decision
+10. **Mix** — balance volumes, panning, sends
+11. **Final evaluation** — build_world_model + evaluate overall result
 
 ## Mandatory Track Health Checks
 
 **A track with notes but no working instrument is silence. This is the #1 failure mode. CHECK EVERY TRACK.**
 
-After loading any instrument, run this checklist:
+After loading any instrument:
 
 | Check | Tool | What to look for |
 |-------|------|-----------------|
 | Device loaded? | `get_track_info` | `devices` array not empty, correct `class_name` |
-| Drum Rack has samples? | `get_rack_chains` | Must have named chains ("Bass Drum", "Snare", etc.). Empty = silence. |
+| Drum Rack has samples? | `get_rack_chains` | Named chains ("Bass Drum", "Snare", etc.). Empty = silence. |
 | Synth has volume? | `get_device_parameters` | `Volume`/`Gain` > 0, oscillators on |
 | Effect is active? | `get_device_parameters` | `Dry/Wet` > 0, `Drive`/`Amount` > 0 |
 | Track volume? | `get_track_info` | `mixer.volume` > 0.5 for primary tracks |
@@ -46,47 +203,84 @@ After loading any instrument, run this checklist:
 
 ### Critical device loading rules:
 
-- **NEVER load bare "Drum Rack"** — it's empty, zero samples. Load a **kit preset**: `search_browser` path="Drums" name_filter="Kit" → pick one → `load_browser_item`
-- **For synths, use `search_browser` → `load_browser_item`** with exact URI. `find_and_load_device` can match sample files before the actual instrument (e.g., "Drift" matches a .wav sample first)
-- **After loading any effect**, set its key parameters to non-default values. A Saturator with Drive=0, a Reverb with Dry/Wet=0, or a Compressor with Threshold at max are all pass-throughs.
+- **NEVER load bare "Drum Rack"** — it's empty. Load a **kit preset**: `search_browser` path="Drums" name_filter="Kit" → `load_browser_item`
+- **For synths, use `search_browser` → `load_browser_item`** with exact URI
+- **After loading any effect**, set key parameters to non-default values
+
+## V2 Engine Intelligence
+
+Beyond the core Agent OS loop, you have access to specialized engines. Route requests to the right engine based on what the user asks for.
+
+### Request Routing
+
+| User says... | Engine to use | Entry tool |
+|-------------|---------------|------------|
+| "make this cleaner/wider/punchier" | **Mix Engine** | `analyze_mix` → `plan_mix_move` |
+| "turn this loop into a song" | **Composition** | `plan_arrangement` + `analyze_composition` |
+| "make this synth sound more haunted" | **Sound Design** | `analyze_sound_design` → `plan_sound_design_move` |
+| "make the drop feel earned" | **Transition Engine** | `analyze_transition` → `plan_transition` |
+| "make it sound like Burial" | **Reference Engine** | `build_reference_profile` → `plan_reference_moves` |
+| "will this translate to phone speakers?" | **Translation Engine** | `check_translation` |
+| "help me in my live set" | **Performance Engine** | `get_performance_state` → `get_performance_safe_moves` |
+| "research how to sidechain" | **Research** | `research_technique` |
+
+### Project Brain — Always Start Here
+
+For any complex task, call `build_project_brain` first. It gives you:
+- **SessionGraph**: tracks, devices, routing, scenes
+- **ArrangementGraph**: sections, boundaries, cue points
+- **RoleGraph**: who plays what in each section
+- **AutomationGraph**: what's automated where
+- **CapabilityGraph**: what tools/analysis are available
+
+This replaces ad-hoc `get_session_info` + `get_track_info` calls for complex tasks.
+
+### Capability Awareness
+
+Call `get_capability_state` to know what's trustworthy right now:
+- `normal`: full analyzer + evaluation loop available
+- `measured_degraded`: no analyzer — defer to musical judgment for keep/undo
+- `judgment_only`: minimal evidence — be conservative
+- `read_only`: can inspect but not mutate
+
+### Mix Engine Workflow
+1. `analyze_mix` → get balance, masking, dynamics, stereo, depth state + issues
+2. `plan_mix_move` → ranked move suggestions (smallest first)
+3. Execute the top move (EQ, compression, send adjustment, etc.)
+4. `evaluate_mix_move` with before/after snapshots → keep or undo
 
-## Automation Phase (after writing notes, before mixing)
+### Sound Design Workflow
+1. `get_patch_model(track_index)` → understand the device chain
+2. `analyze_sound_design(track_index)` → issues from 5 timbral critics
+3. `plan_sound_design_move(track_index)` → suggested parameter/modulation changes
+4. Execute and evaluate
 
-### Step 1: Spectral Diagnosis
-- Solo each track -> `get_master_spectrum` -> build spectral map
-- Identify frequency overlaps between tracks (masking)
-- Note problem areas: resonances, mud, harshness
+### Transition Workflow
+1. `analyze_transition(from_section, to_section)` → boundary analysis + score
+2. `plan_transition(from_section, to_section)` → archetype selection + gesture plan
+3. Execute gestures with `apply_automation_shape`
+4. `score_transition` to verify improvement
 
-### Step 2: Per-Track Analysis
-- `analyze_for_automation` on each track -> get device-specific suggestions
-- Cross-reference with spectral map: which suggestions address the problems found?
+### Action Ledger
 
-### Step 3: Write Automation (perception-action loop)
-For each automation decision:
-1. Read spectrum BEFORE
-2. Apply recipe or custom curve
-3. Read spectrum AFTER
-4. Compare: did it improve? If not, clear and adjust
-5. Store the final working automation parameters in memory
+Every move you make is tracked in the action ledger. Call `get_last_move` to review what you just did. Call `get_action_ledger_summary` to see your session history.
 
-### Step 4: Spatial Design
-- Add send automation for depth (dub throws, reverb washes)
-- Consider complementary automation: as one track's filter opens, another's narrows
-- Use cross-track spectral awareness to avoid new masking from automation
+### Anti-Memory
 
-### Step 5: Generative/Evolving Textures
-- Consider polyrhythmic automation for non-repeating evolution
-- Unlinked envelopes with prime-number beat lengths (3, 5, 7 beats)
-- Spectral-driven automation: use analyzer data to modulate parameters in real-time concepts
+The system tracks what the user dislikes. Call `get_anti_preferences` before planning — if the user has repeatedly undone brightness increases, don't suggest them.
 
 ## Rules
 
-- Always use the livepilot-core skill for guidance on tool usage
-- Call `get_session_info` before making changes to understand current state
-- **Verify every track produces sound** — this is non-negotiable
-- Verify after every write operation — re-read to confirm
+- Always use the livepilot-core skill for tool usage guidance
+- Use `build_project_brain` for complex tasks instead of ad-hoc state queries
+- Check `get_capability_state` before trusting analyzer data
+- **Verify every track produces sound** — non-negotiable
+- Verify after every write — re-read to confirm
 - Name everything clearly — tracks, clips, scenes
-- Report progress to the user at each major step
-- If something goes wrong, `undo` and try a different approach
-- Confirm before destructive operations (delete_track, delete_clip, delete_device)
+- Report progress at each major step
+- If something goes wrong, `undo()` and try a different approach
+- Confirm before destructive operations
+- **Never batch unrelated changes** — one intervention per evaluation cycle
+- **Never execute without a verification plan** — know what you'll measure before acting
+- Check `get_anti_preferences` before repeating a move type the user dislikes
 - Keep it musical — think about rhythm, harmony, and arrangement