livepilot 1.26.0 → 1.26.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v1.26.1 — 2026-05-24
+
+Patch release for installer/release hygiene and live execution correctness.
+
+### Fixed
+
+- Codex plugin installer now copies the full plugin payload into Codex's local plugin cache, writes the lowercase `.codex-plugin` manifest mirror, and prunes stale cache versions.
+- Full composer analysis now routes MCP-side analysis tools through the MCP dispatch registry instead of sending non-Remote-Script commands over TCP.
+- Remote Script write-command detection now classifies newer mutating handlers by prefix so they receive write timeouts and settle delays.
+- M4L bridge OSC builder now rejects unsupported argument types instead of silently emitting malformed OSC payloads.
+- `develop_apply` bridge ping call now passes timeout correctly instead of serializing a dict as an OSC argument.
+- Creative skills no longer route eclectic/rule-breaking requests to a private missing `livepilot-eclectic` skill.
+- Metadata/docs refreshed for 56 domains, 465 tools, and 44 semantic moves.
+- Social banner SVGs and release checklist paths now reference the current 465-tool / 56-domain project state.
+
+### Added
+
+- Public `CONTEXT.md` with repo vocabulary and architecture decisions.
+- Initial `LivePilot_Elektron` M4L SysEx bridge artifact and JS bridge scaffold.
+
+### Tests
+
+- Added contract coverage for Codex cache installation, MCP dispatch adapters, Remote Script command registry drift, write-command classification, OSC argument validation, and stale skill references.
+
 ## v1.26.0 — 2026-05-09
 
 Rubric grader system + atlas-aware load preflight + Drift factory-fingerprint detection. Closes a chronic-regression class: anti-pattern violations of CLAUDE.md §1/§2/§4/§5/§7.3 now have programmatic enforcement, and silent-instrument loads (Granulator III without a sample) are caught structurally at load time instead of much later via the verifier.

package/README.md

@@ -51,7 +51,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | **Sample Engine** | Three-source sample intelligence — Ableton's browser, your filesystem, and Splice's catalog (plan-aware: Ableton Live plan uses daily quota, Sounds+/Creator uses credits, free samples bypass both). 6 fitness critics. 29 processing techniques. Collections, presets, preview-URL audition, LIVE Describe-a-Sound + Variations via Splice GraphQL |
 | **Spectral Perception** | Real-time ears via M4L — 9-band FFT (with sub_low split at 20-60 Hz for kick fundamentals), RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Auto-loaded via `ensure_analyzer_on_master` (v1.20.3) — no more silently-degraded mix moves from forgotten analyzer |
 | **Technique Memory** | Persistent library of production decisions. Save a beat pattern, device chain, or mix template. Recall by mood, genre, or texture across sessions |
-| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **44 semantic moves** (v1.21) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
+| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **44 semantic moves** (v1.26) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
 
 <br>
 

package/installer/codex.js

@@ -6,9 +6,13 @@ const path = require("path");
 
 const ROOT = path.resolve(__dirname, "..");
 const SOURCE_DIR = path.join(ROOT, "livepilot");
-const SOURCE_MANIFEST = path.join(SOURCE_DIR, ".Codex-plugin", "plugin.json");
+const SOURCE_MANIFESTS = [
+  path.join(SOURCE_DIR, ".codex-plugin", "plugin.json"),
+  path.join(SOURCE_DIR, ".Codex-plugin", "plugin.json"),
+];
 const DEFAULT_PLUGIN_DIR = path.join(os.homedir(), "plugins", "livepilot");
 const DEFAULT_MARKETPLACE_PATH = path.join(os.homedir(), ".agents", "plugins", "marketplace.json");
+const DEFAULT_CODEX_CACHE_ROOT = path.join(os.homedir(), ".codex", "plugins", "cache", "local-plugins");
 
 const SKIP = new Set(["__pycache__", ".DS_Store"]);
 
@@ -31,15 +35,32 @@ function targetPluginDir() {
   return process.env.LIVEPILOT_CODEX_PLUGIN_PATH || DEFAULT_PLUGIN_DIR;
 }
 
+function codexCacheRoot() {
+  return process.env.LIVEPILOT_CODEX_CACHE_ROOT || DEFAULT_CODEX_CACHE_ROOT;
+}
+
+function targetCacheDir(pluginName, version) {
+  if (process.env.LIVEPILOT_CODEX_CACHE_PATH) {
+    return process.env.LIVEPILOT_CODEX_CACHE_PATH;
+  }
+  return path.join(codexCacheRoot(), pluginName, version);
+}
+
 function marketplacePath() {
   return process.env.LIVEPILOT_CODEX_MARKETPLACE_PATH || DEFAULT_MARKETPLACE_PATH;
 }
 
-function loadManifest() {
-  if (!fs.existsSync(SOURCE_MANIFEST)) {
-    throw new Error(`Codex plugin manifest not found at ${SOURCE_MANIFEST}`);
+function sourceManifestPath() {
+  for (const candidate of SOURCE_MANIFESTS) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
   }
-  return JSON.parse(fs.readFileSync(SOURCE_MANIFEST, "utf-8"));
+  throw new Error(`Codex plugin manifest not found at ${SOURCE_MANIFESTS.join(" or ")}`);
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(sourceManifestPath(), "utf-8"));
 }
 
 function writeLocalMcpConfig(destDir) {
@@ -55,6 +76,51 @@ function writeLocalMcpConfig(destDir) {
   fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
 }
 
+function ensureLowercaseCodexManifest(destDir) {
+  const canonicalDir = path.join(destDir, ".codex-plugin");
+  const canonicalManifest = path.join(canonicalDir, "plugin.json");
+  if (fs.existsSync(canonicalManifest)) {
+    return;
+  }
+
+  const legacyManifest = path.join(destDir, ".Codex-plugin", "plugin.json");
+  if (!fs.existsSync(legacyManifest)) {
+    return;
+  }
+
+  fs.mkdirSync(canonicalDir, { recursive: true });
+  fs.copyFileSync(legacyManifest, canonicalManifest);
+}
+
+function copyPluginTo(destDir) {
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
+  fs.rmSync(destDir, { recursive: true, force: true });
+  copyDirSync(SOURCE_DIR, destDir);
+  ensureLowercaseCodexManifest(destDir);
+  writeLocalMcpConfig(destDir);
+}
+
+function pruneStaleCacheVersions(pluginName, keepVersion) {
+  if (process.env.LIVEPILOT_CODEX_CACHE_PATH) {
+    return [];
+  }
+  const pluginCacheRoot = path.join(codexCacheRoot(), pluginName);
+  if (!fs.existsSync(pluginCacheRoot)) {
+    return [];
+  }
+
+  const removed = [];
+  for (const entry of fs.readdirSync(pluginCacheRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === keepVersion) {
+      continue;
+    }
+    const stalePath = path.join(pluginCacheRoot, entry.name);
+    fs.rmSync(stalePath, { recursive: true, force: true });
+    removed.push(stalePath);
+  }
+  return removed;
+}
+
 function ensureMarketplace(pluginName) {
   const file = marketplacePath();
   let marketplace = {
@@ -116,19 +182,24 @@ function removeMarketplaceEntry(pluginName) {
 function installCodexPlugin() {
   const manifest = loadManifest();
   const pluginName = manifest.name || "livepilot";
+  const pluginVersion = manifest.version || "unknown";
   const destDir = targetPluginDir();
+  const cacheDir = targetCacheDir(pluginName, pluginVersion);
   const marketFile = ensureMarketplace(pluginName);
 
   console.log("Installing LivePilot Codex plugin...");
   console.log("  Source: %s", SOURCE_DIR);
   console.log("  Target: %s", destDir);
+  console.log("  Codex cache: %s", cacheDir);
   console.log("  Marketplace: %s", marketFile);
   console.log("");
 
-  fs.mkdirSync(path.dirname(destDir), { recursive: true });
-  fs.rmSync(destDir, { recursive: true, force: true });
-  copyDirSync(SOURCE_DIR, destDir);
-  writeLocalMcpConfig(destDir);
+  copyPluginTo(destDir);
+  copyPluginTo(cacheDir);
+  const removedStaleCaches = pruneStaleCacheVersions(pluginName, pluginVersion);
+  for (const stalePath of removedStaleCaches) {
+    console.log("  Removed stale Codex cache: %s", stalePath);
+  }
 
   console.log("Done! Next steps:");
   console.log("  1. Open or refresh Codex");
@@ -139,7 +210,9 @@ function installCodexPlugin() {
 function uninstallCodexPlugin() {
   const manifest = loadManifest();
   const pluginName = manifest.name || "livepilot";
+  const pluginVersion = manifest.version || "unknown";
   const destDir = targetPluginDir();
+  const cacheDir = targetCacheDir(pluginName, pluginVersion);
   const marketFile = removeMarketplaceEntry(pluginName);
 
   if (fs.existsSync(destDir)) {
@@ -149,6 +222,11 @@ function uninstallCodexPlugin() {
     console.log("Codex plugin not found at %s", destDir);
   }
 
+  if (fs.existsSync(cacheDir)) {
+    console.log("Removing Codex plugin cache: %s", cacheDir);
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+  }
+
   if (marketFile) {
     console.log("Updated marketplace: %s", marketFile);
   }

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

@@ -0,0 +1,8 @@
+{
+  "name": "livepilot",
+  "version": "1.26.1",
+  "description": "Agentic production system for Ableton Live 12 \u2014 465 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "author": {
+    "name": "Pilot Studio"
+  }
+}

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

@@ -0,0 +1,8 @@
+{
+  "name": "livepilot",
+  "version": "1.26.1",
+  "description": "Agentic production system for Ableton Live 12 \u2014 465 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "author": {
+    "name": "Pilot Studio"
+  }
+}

package/livepilot/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "livepilot": {
+      "command": "npx",
+      "args": ["livepilot"]
+    }
+  }
+}

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

@@ -0,0 +1,314 @@
+---
+name: livepilot-producer
+description: Autonomous music production agent for Ableton Live 12. Handles complex multi-step tasks like creating beats, arranging songs, and designing sounds from high-level descriptions.
+when_to_use: When the user gives a high-level production request like "make a lo-fi hip hop beat", "create a drum pattern", "arrange an intro section", or any multi-step Ableton task that requires planning and execution.
+model: sonnet
+tools:
+  - mcp
+  - Read
+  - Glob
+  - Grep
+  - ToolSearch
+---
+
+You are LivePilot Producer — an autonomous music production agent for Ableton Live 12 powered by Agent OS V1.
+
+## Core Loop
+
+Every production task follows a cyclical evaluation loop. The user says something simple ("make this hit harder"); you run a rigorous internal process.
+
+```
+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**: 9-band spectrum (sub_low → air), 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:
+
+| 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` | 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 |
+| 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:
+
+- **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
+
+### 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
+
+### 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
+
+### Action Ledger
+
+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.
+
+### Anti-Memory
+
+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.
+
+## Skills Reference
+
+Load the appropriate skill for domain-specific guidance:
+- **livepilot-core** — golden rules, speed tiers, error handling (always relevant)
+- **livepilot-creative-director** — **load FIRST on open-ended creative intent** ("like X", "develop", "more interesting", reference/style asks); enforces 3-plan divergence across `move.family` before commit, then routes to the skills below
+- **livepilot-devices** — loading/browsing/configuring devices
+- **livepilot-notes** — MIDI content, theory, generative algorithms
+- **livepilot-mixing** — volume, pan, sends, routing, automation
+- **livepilot-arrangement** — song structure, scenes, arrangement view
+- **livepilot-mix-engine** — critic-driven mix analysis loop
+- **livepilot-sound-design-engine** — critic-driven patch refinement loop
+- **livepilot-composition-engine** — section analysis, transitions, form
+- **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
+- 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 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

package/livepilot/commands/arrange.md

@@ -0,0 +1,47 @@
+---
+name: arrange
+description: Guided arrangement — build song structure with sections, transitions, and energy flow
+---
+
+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 the branch-native experiment path (see livepilot-core SKILL.md, Flow B). Each section-ordering variant becomes one `composer`-source seed; attach pre-compiled plans via `compiled_plans`. When the user's request is vague or exploratory ("what would you do?", "surprise me with a structure"), bias `get_session_kernel(freshness=0.7-0.9)` to surface less-conservative branches.

package/livepilot/commands/beat.md

@@ -0,0 +1,81 @@
+---
+name: beat
+description: Guided beat creation — create a beat from scratch with genre, tempo, and instrumentation choices
+---
+
+Guide the user through creating a beat from scratch. Follow these steps:
+
+## 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.
+
+## Branch-Native Variations
+
+When the user wants options instead of a single committed beat ("try a few variants", "surprise me with the drum feel", "what else could this be?"), use the exploratory flow from livepilot-core SKILL.md (Flow B). Emit 2-3 seeds that differ in *how* they interpret the vibe — for example one `semantic_move` seed with `make_punchier`, one `freeform` seed describing a swung / pushed-beat variation with a pre-compiled plan, one `synthesis` seed that changes the kick's synthesis rather than its pattern. Set `get_session_kernel(freshness=0.6-0.8)` and `creativity_profile="alchemist"` when the user hasn't given concrete parameters.