livepilot 1.9.22 → 1.9.23

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 — 237 tools, 32 domains",
+  "description": "Agentic MCP production system for Ableton Live 12 — 293 tools, 39 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 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.22",
+      "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",
+      "version": "1.9.23",
       "author": {
         "name": "Pilot Studio"
       },

package/.mcpbignore

@@ -0,0 +1,40 @@
+# Development files
+.git
+.git-backup-full
+.github
+.claude
+.playwright-mcp
+.pytest_cache
+.venv
+__pycache__
+
+# Test and CI
+tests/
+scripts/
+.github/
+
+# Build artifacts
+*.pyc
+.DS_Store
+*.egg-info
+
+# Credentials and tokens
+.mcpregistry_*
+.env
+.npmrc
+
+# Docs and marketing (not needed at runtime)
+docs/specs/
+docs/social-banner.*
+docs/screenshots/
+
+# Large binary already in User Library after install
+# m4l_device/LivePilot_Analyzer.amxd
+
+# Dev config
+.mcp.json
+.npmignore
+.editorconfig
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+SECURITY.md

package/AGENTS.md

@@ -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)
-- 236 tools across 31 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, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine
+- 293 tools across 39 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, 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 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
+Currently 257 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,43 @@
 # Changelog
 
+## 1.9.23-wonder-v1.5 — Wonder Mode V1.5: Stuck-Rescue Workflow (April 2026)
+
+### Wonder Mode Redesign (292->293 tools)
+- **feat(wonder_mode):** Diagnosis-first workflow — stuckness detection drives variant generation
+- **feat(wonder_mode):** Honest variant labeling — `analytical_only: true` for non-executable variants
+- **feat(wonder_mode):** Real distinctness enforcement — variants must differ by move, family, or plan shape
+- **feat(wonder_mode):** WonderSession lifecycle — diagnosis -> variants -> preview -> commit/discard
+- **feat(wonder_mode):** `discard_wonder_session` tool — reject all variants, keep creative thread open
+- **feat(preview_studio):** Wonder-aware preview — accepts `wonder_session_id`, refuses analytical variants
+- **feat(preview_studio):** Commit lifecycle hooks — records outcome to continuity and taste
+- **feat(session_continuity):** No more premature turn recording — only commit/reject record turns
+- **feat(skills):** New `livepilot-wonder` skill with trigger conditions and honesty rules
+
+## 1.9.23 — Stage 2: The Magic Layer (April 2026)
+
+### Wonder Mode Rebuild
+- **feat(wonder_mode):** Full engine rebuild — variants now built from real semantic moves matched by keyword+taste scoring, not templates
+- **feat(wonder_mode):** Ranking uses bell-curve novelty centered on user's novelty_band, sacred element penalty, and coherence scoring
+- **feat(wonder_mode):** Taste fit uses full TasteGraph (family preference, dimension alignment, anti-preferences, risk alignment)
+- **feat(wonder_mode):** Each variant carries `targets_snapshot`, `compiled_plan`, and `score_breakdown` with all 4 component scores
+- **breaking(wonder_mode):** Removed `generate_wonder_variants` tool (redundant with `enter_wonder_mode`)
+
+### New Tools (10 new, -1 removed = net +9, 283→292)
+- **feat(preview_studio):** `render_preview_variant` — render a short preview of a variant using Ableton's undo system
+- **feat(hook_hunter):** `detect_hook_neglect` — check if a strong hook is underused across sections
+- **feat(hook_hunter):** `compare_phrase_impact` — compare emotional impact across multiple sections
+- **feat(stuckness_detector):** `start_rescue_workflow` — structured step-by-step rescue plan for a specific stuckness type
+- **feat(wonder_mode):** `rank_wonder_variants` — rank wonder variants by taste + identity + phrase impact
+- **feat(session_continuity):** `open_creative_thread` — open a new creative thread for exploration
+- **feat(session_continuity):** `list_open_creative_threads` — list all open non-stale creative threads
+- **feat(session_continuity):** `explain_preference_vs_identity` — explain taste vs identity tension for a candidate
+- **feat(creative_constraints):** `generate_constrained_variants` — generate triptych variants under active constraints
+- **feat(creative_constraints):** `generate_reference_inspired_variants` — generate variants inspired by distilled reference principles
+
+### Fixes
+- **fix(wonder_mode):** Fixed taste graph access to use session-scoped lifespan context instead of creating fresh stores
+- **fix(session_continuity):** Fixed taste graph access to match preview_studio pattern
+
 ## 1.9.22 — Skill & Command Overhaul (April 2026)
 
 ### Skill Updates

package/CONTRIBUTING.md

@@ -98,7 +98,7 @@ Prefix with `fix:`, `feat:`, `docs:`, `refactor:`, `test:`, or `chore:`.
 
 ## Tool Count Discipline
 
-Currently **236 tools**. If you add or remove a `@mcp.tool()` decorator, update all of these files:
+Currently **293 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>
-  236 tools. Device atlas. Spectral perception. Technique memory.
+  293 tools. Device atlas. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -49,8 +49,8 @@
 │         └───────────────────┼───────────────────┘           │
 │                             ▼                               │
 │                    ┌─────────────────┐                      │
-│                    │   236 MCP Tools  │                      │
-│                    │   31 domains     │                      │
+│                    │   293 MCP Tools  │                      │
+│                    │   39 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 236 deterministic tools that execute on Ableton's main thread.
+All three feed into 293 deterministic tools that execute on Ableton's main thread.
 
 <br>
 
@@ -79,7 +79,7 @@ All three feed into 236 deterministic tools that execute on Ableton's main threa
 
 ## Tools
 
-236 tools across 31 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+293 tools across 39 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -99,13 +99,13 @@ All three feed into 236 deterministic tools that execute on Ableton's main threa
 
 <br>
 
-### Perception — 29 tools `[M4L]`
+### Perception — 30 tools `[M4L]`
 
 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 207 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 30 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 236 tools →](docs/manual/tool-catalog.md)**
+> **[View all 293 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -330,123 +330,98 @@ read_audio_metadata     Format, duration, sample rate, tags
 
 ## Install
 
-### 1. Remote Script
+### Easiest: Claude Desktop Extension (1 click)
 
-```bash
-npx livepilot --install
-```
+Download [`livepilot.mcpb`](https://github.com/dreamrec/LivePilot/releases/latest) and double-click it.
+Claude Desktop installs everything automatically. Then:
 
-Restart Ableton → Preferences → Link, Tempo & MIDI → Control Surface → **LivePilot**
+1. Open Ableton Live 12
+2. Preferences → Link, Tempo & MIDI → Control Surface → **LivePilot**
+3. Start chatting
 
-### 2. MCP Client
+> [!TIP]
+> The Desktop Extension auto-installs the Remote Script and M4L Analyzer on first launch.
 
-<details open>
-<summary><strong>Claude Code</strong></summary>
+### Quick: One Command Setup
 
 ```bash
-claude mcp add LivePilot -- npx livepilot
+npx livepilot --setup
 ```
 
-Plugin (adds skills, slash commands, producer agent):
+This runs the full setup wizard: checks Python, installs the Remote Script, creates the Python environment, copies the M4L Analyzer, and tests the Ableton connection.
+
+### Manual: Step by Step
+
+<details>
+<summary><strong>1. Remote Script</strong></summary>
 
 ```bash
-claude plugin add github:dreamrec/LivePilot/plugin
+npx livepilot --install
 ```
 
+Restart Ableton → Preferences → Link, Tempo & MIDI → Control Surface → **LivePilot**
+
 </details>
 
 <details>
-<summary><strong>Claude Desktop (macOS)</strong></summary>
+<summary><strong>2. MCP Client</strong></summary>
 
-`~/Library/Application Support/Claude/claude_desktop_config.json`:
+**Claude Code:**
+```bash
+claude mcp add LivePilot -- npx livepilot
+claude plugin add github:dreamrec/LivePilot/plugin
+```
 
+**Claude Desktop (macOS)** — `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "LivePilot": {
-      "command": "npx",
-      "args": ["livepilot"]
-    }
+    "LivePilot": { "command": "npx", "args": ["livepilot"] }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><strong>Claude Desktop (Windows)</strong></summary>
-
+**Claude Desktop (Windows):**
 ```cmd
 npm install -g livepilot
 livepilot --install
 ```
-
 `%APPDATA%\Claude\claude_desktop_config.json`:
-
 ```json
 {
   "mcpServers": {
-    "LivePilot": {
-      "command": "livepilot"
-    }
+    "LivePilot": { "command": "livepilot" }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><strong>Cursor</strong></summary>
-
-`.cursor/mcp.json`:
-
+**Cursor** — `.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
-    "LivePilot": {
-      "command": "npx",
-      "args": ["livepilot"]
-    }
+    "LivePilot": { "command": "npx", "args": ["livepilot"] }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><strong>VS Code / Windsurf</strong></summary>
-
-VS Code — `.vscode/mcp.json`:
-
+**VS Code** — `.vscode/mcp.json`:
 ```json
 {
   "servers": {
-    "LivePilot": {
-      "command": "npx",
-      "args": ["livepilot"]
-    }
-  }
-}
-```
-
-Windsurf — `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "LivePilot": {
-      "command": "npx",
-      "args": ["livepilot"]
-    }
+    "LivePilot": { "command": "npx", "args": ["livepilot"] }
   }
 }
 ```
 
 </details>
 
-### 3. M4L Analyzer (optional)
+<details>
+<summary><strong>3. M4L Analyzer (optional)</strong></summary>
 
-Drag `LivePilot_Analyzer.amxd` onto the master track.
+Drag `LivePilot_Analyzer.amxd` onto the master track for real-time spectral analysis.
+The `--setup` wizard and Desktop Extension do this automatically.
+
+</details>
 
 Unlocks 29 additional tools: spectral analysis, key detection,
 sample manipulation, deep device introspection, plugin parameter mapping.

package/bin/livepilot.js

@@ -485,6 +485,109 @@ async function setupFlucoma() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Setup wizard — unified installer
+// ---------------------------------------------------------------------------
+
+async function setup() {
+  console.log("LivePilot Setup Wizard v%s", PKG.version);
+  console.log("═".repeat(50));
+  console.log("");
+
+  let ok = true;
+
+  // 1. Python
+  console.log("Step 1/5: Checking Python...");
+  const pyInfo = findPython();
+  if (pyInfo) {
+    console.log("  ✓ %s", pyInfo.version);
+  } else {
+    console.log("  ✗ Python >= 3.9 not found");
+    console.log("    Install: brew install python@3.12 (macOS) or python.org (Windows)");
+    ok = false;
+  }
+
+  // 2. Install Remote Script
+  console.log("");
+  console.log("Step 2/5: Installing Remote Script...");
+  try {
+    const { install } = require(path.join(ROOT, "installer", "install.js"));
+    install();
+    console.log("  ✓ Remote Script installed");
+  } catch (err) {
+    console.log("  ✗ Failed: %s", err.message);
+    ok = false;
+  }
+
+  // 3. Bootstrap Python venv
+  console.log("");
+  console.log("Step 3/5: Setting up Python environment...");
+  if (pyInfo) {
+    try {
+      ensureVenv(pyInfo.cmd, pyInfo.prefixArgs);
+      console.log("  ✓ Virtual environment ready");
+    } catch (err) {
+      console.log("  ✗ Failed: %s", err.message);
+      ok = false;
+    }
+  } else {
+    console.log("  ⊘ Skipped (no Python)");
+  }
+
+  // 4. Copy M4L Analyzer to User Library
+  console.log("");
+  console.log("Step 4/5: Installing M4L Analyzer...");
+  const analyzerSrc = path.join(ROOT, "m4l_device", "LivePilot_Analyzer.amxd");
+  if (fs.existsSync(analyzerSrc)) {
+    const home = require("os").homedir();
+    let dest;
+    if (process.platform === "darwin") {
+      dest = path.join(home, "Music", "Ableton", "User Library", "Presets",
+                        "Audio Effects", "Max Audio Effect");
+    } else {
+      dest = path.join(home, "Documents", "Ableton", "User Library", "Presets",
+                        "Audio Effects", "Max Audio Effect");
+    }
+    try {
+      fs.mkdirSync(dest, { recursive: true });
+      fs.copyFileSync(analyzerSrc, path.join(dest, "LivePilot_Analyzer.amxd"));
+      console.log("  ✓ Analyzer copied to %s", dest);
+    } catch (err) {
+      console.log("  ✗ Failed: %s", err.message);
+    }
+  } else {
+    console.log("  ⊘ Analyzer not found in package (optional)");
+  }
+
+  // 5. Connection test
+  console.log("");
+  console.log("Step 5/5: Testing Ableton connection...");
+  const reachable = await checkStatus();
+  if (reachable) {
+    console.log("  ✓ Ableton Live is running and reachable");
+  } else {
+    console.log("  ⊘ Ableton not running (start it and select LivePilot as Control Surface)");
+  }
+
+  // Summary
+  console.log("");
+  console.log("═".repeat(50));
+  if (ok) {
+    console.log("✓ Setup complete! Next steps:");
+    console.log("");
+    console.log("  1. Open Ableton Live 12");
+    console.log("  2. Go to Preferences → Link, Tempo & MIDI");
+    console.log("  3. Set Control Surface to 'LivePilot'");
+    console.log("  4. Start making music with AI!");
+    console.log("");
+    console.log("  Claude Code:    claude mcp add LivePilot -- npx livepilot");
+    console.log("  Claude Desktop: Already configured if using Desktop Extension");
+  } else {
+    console.log("⚠ Setup completed with issues. Run 'npx livepilot --doctor' for details.");
+  }
+}
+
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -507,6 +610,7 @@ async function main() {
     console.log("");
     console.log("Commands:");
     console.log("  (none)        Start the MCP server");
+    console.log("  --setup       Full setup wizard (install + configure + test)");
     console.log("  --install     Install Remote Script into Ableton Live");
     console.log("  --uninstall   Remove Remote Script from Ableton Live");
     console.log("  --status      Check if Ableton Live is reachable");
@@ -553,6 +657,37 @@ async function main() {
     process.exit(passed ? 0 : 1);
   }
 
+  // --setup (unified installer wizard)
+  if (flag === "--setup") {
+    await setup();
+    return;
+  }
+
+  // Auto-install Remote Script when launched from Desktop Extension
+  if (process.env.LIVEPILOT_AUTO_INSTALL === "true") {
+    try {
+      const { install } = require(path.join(ROOT, "installer", "install.js"));
+      const { findAbletonPaths } = require(path.join(ROOT, "installer", "paths.js"));
+      const candidates = findAbletonPaths();
+      if (candidates.length > 0) {
+        // Check if already installed
+        const target = path.join(candidates[0].path, "LivePilot");
+        if (!fs.existsSync(target)) {
+          console.error("LivePilot: auto-installing Remote Script to %s", candidates[0].path);
+          install();
+          console.error("LivePilot: Remote Script installed. Select 'LivePilot' in Ableton > Preferences > Link, Tempo & MIDI > Control Surface.");
+        }
+      }
+    } catch (err) {
+      console.error("LivePilot: auto-install skipped (%s)", err.message);
+    }
+  }
+
+  // Custom TCP port from Desktop Extension config
+  if (process.env.LIVEPILOT_TCP_PORT && process.env.LIVEPILOT_TCP_PORT !== "9878") {
+    process.env.LIVE_MCP_PORT = process.env.LIVEPILOT_TCP_PORT;
+  }
+
   // Default: start MCP server
   const pyInfo = findPython();
   if (!pyInfo) {

package/livepilot/.Codex-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.23",
+  "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/.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.23",
+  "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.