livepilot 1.9.22 → 1.9.24

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.24",
       "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

@@ -1,4 +1,4 @@
-# LivePilot v1.9.18 — Ableton Live 12
+# LivePilot v1.9.24 — 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)
-- 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 293 tools. If adding/removing tools, update: README.md, package.json description, livepilot/.Codex-plugin/plugin.json, livepilot/.claude-plugin/plugin.json, server.json, livepilot/skills/livepilot-core/SKILL.md, livepilot/skills/livepilot-core/references/overview.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, tests/test_tools_contract.py, docs/manual/index.md, docs/manual/tool-reference.md

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 1.9.24 — Stability & Intelligence Upgrade (April 2026)
+
+### Truth and Boundaries (Wave 1)
+- **feat(runtime):** Capability contract — every advanced tool reports `full/fallback/analytical_only/unavailable` with confidence scores
+- **feat(runtime):** Command boundary audit — CI catches any `send_command()` targeting a non-existent Remote Script command
+- **fix(song_brain):** `get_motif_graph` now uses pure-Python engine instead of invalid TCP call
+- **fix(hook_hunter):** Same motif routing fix
+- **fix(musical_intelligence):** Same motif routing fix + `analyze_phrase_arc` now calls perception engine directly
+- **fix(memory):** `record_positive_preference` actually updates taste dimensions (was a silent no-op due to key mismatch)
+- **fix(metadata):** AGENTS.md synced to v1.9.23/293 tools, test docstring corrected
+
+### Unified Execution Layer (Wave 2)
+- **feat(runtime):** Execution router — classifies steps as `remote_command/bridge_command/mcp_tool/unknown`, dispatches correctly
+- **feat(semantic_moves):** `apply_semantic_move` explore mode uses execution router
+- **feat(preview_studio):** `render_preview_variant` uses execution router
+
+### Persistent Memory (Waves 2-3)
+- **feat(persistence):** Base persistent JSON store (atomic write, corruption recovery, thread-safe)
+- **feat(persistence):** Taste store at `~/.livepilot/taste.json` — move outcomes, novelty band, device affinity, anti-preferences survive restart
+- **feat(persistence):** Project store at `~/.livepilot/projects/<hash>/state.json` — threads, turns, Wonder outcomes per song
+- **feat(memory):** TasteGraph.record_move_outcome writes to persistent backing
+- **feat(session_continuity):** tracker flushes threads and turns to project store on write
+
+### Move Annotations (Wave 3)
+- **feat(semantic_moves):** All 20 moves annotated with explicit `backend` per compile_plan step
+- **test:** Static audit verifies all annotations match the execution router classifier
+
+### Intelligence Upgrade (Waves 3-4)
+- **feat(services):** Shared motif service — one entry point consumed by SongBrain, HookHunter, musical_intelligence
+- **feat(song_brain):** Evidence-weighted identity confidence (motif=0.4, composition=0.2, roles=0.15, scenes=0.15, moves=0.1)
+- **feat(song_brain):** `evidence_breakdown` field shows per-source contributions
+- **feat(hook_hunter):** Hooks carry `evidence_sources` (motif_recurrence, track_name, clip_reuse)
+- **feat(hook_hunter):** Section-placement analysis boosts hooks recurring across sections
+- **feat(detectors):** Motif appearing in >60% of sections triggers fatigue signal
+
+### Preview and Doctor (Wave 4)
+- **feat(preview_studio):** Three explicit preview modes: `audible_preview` (M4L+spectrum), `metadata_only_preview`, `analytical_preview`
+- **feat(preview_studio):** `bars` parameter used for audible preview playback duration
+- **feat(preview_studio):** `preview_mode` field in response — no ambiguity about what was measured
+- **feat(runtime):** Capability probe — 6-area runtime detection (Ableton, Remote Script, M4L, numpy, persistence, tier)
+
+### Release Infrastructure (Wave 5)
+- **feat(scripts):** `sync_metadata.py` — single source of truth for version and tool count, CI-checkable
+- **docs:** README Intelligence Layer section with all 12 engines described
+- **docs:** Manual index rewritten with three-layer architecture and 39-domain map
+
+## 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,78 @@ 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>
+
+---
+
+## The Intelligence Layer
+
+Most MCP servers are tool collections — they execute commands. LivePilot is an **agentic production system** — it understands what a song is becoming, diagnoses when a session is stuck, generates real creative options, learns from your decisions, and tracks its own impact.
+
+This is the V2 intelligence layer: 12 engines that sit on top of the 293 tools and give the AI musical judgment, not just musical execution.
+
+### SongBrain — What the Song Is
+
+SongBrain builds a real-time model of the current session: what the defining idea is (identity core), what elements must not be casually damaged (sacred elements), what each section is trying to do emotionally (section purposes), and where the energy arc is heading. It answers the question every producer asks: *"What is this track?"*
+
+It detects when the song's identity is drifting — when recent edits are pulling the track away from what made it work. When identity confidence is high, the system makes bolder suggestions. When it's fragile, it protects what's there.
+
+### Taste Graph — What You Like
+
+The Taste Graph learns your production preferences across sessions. Not just "prefers reverb" — it tracks which move families you keep vs. undo (mix moves? arrangement moves?), which devices you gravitate toward, how experimental you want suggestions to be (your novelty band), and which dimensions you actively avoid.
+
+Every time you accept or reject a suggestion, the graph updates. Over time, it personalizes which creative options are offered and how they're ranked. Two producers using the same tools get different recommendations.
+
+### Semantic Moves — Musical Actions, Not Parameters
+
+A semantic move is a high-level musical intent — "add contrast," "tighten the low end," "build tension toward the chorus" — that compiles into a specific sequence of tool calls. The system has 20 moves across 4 families (mix, arrangement, transition, sound design), each with an executable plan.
+
+Moves carry risk levels, target dimensions, and protection thresholds. "Add a filter sweep build" targets energy and tension while protecting clarity. The AI doesn't just know what to do — it knows what it's risking.
+
+### Wonder Mode — Stuck-Rescue Workflow
+
+When a session is stuck — too many undos, polishing the same loop, no structural progress — Wonder Mode activates. It's not "surprise me." It's a structured diagnosis-and-rescue workflow:
+
+1. **Diagnose** — Why is the session stuck? Repeated undos? Overpolished loop? Missing contrast? Identity unclear? The stuckness detector analyzes the action history and classifies the problem.
+
+2. **Generate** — Based on the diagnosis, Wonder searches for semantic moves that address the specific problem. It enforces real distinctness — each variant must differ by move family or execution approach. If only one real option exists, it says so honestly instead of relabeling the same idea three times.
+
+3. **Preview** — Each executable variant can be applied, captured, and undone using Ableton's undo system. You hear what each option would actually sound like before committing.
+
+4. **Commit or Reject** — Choose one, and the system records it into taste and session continuity. Reject all, and the creative thread stays open for another attempt. No fake outcomes are recorded.
+
+### Creative Engines
+
+Six specialized engines handle different aspects of production intelligence:
+
+| Engine | What it does |
+|--------|-------------|
+| **Mix Engine** | Critic-driven mix analysis. Identifies masking, headroom issues, stereo problems. Plans corrective moves with before/after evaluation. |
+| **Sound Design Engine** | Analyzes patches for static timbre, missing modulation, weak transients. Suggests parameter moves and evaluates the result. |
+| **Transition Engine** | Classifies transition types (drop, build, breakdown). Scores transition quality and plans improvements using archetypes. |
+| **Composition Engine** | Analyzes song structure, detects motifs, infers section purposes, scores emotional arcs. Plans arrangement moves. |
+| **Performance Engine** | Safety-constrained suggestions for live performance. Knows which moves are safe during playback and which risk audio dropouts. |
+| **Reference Engine** | Distills principles from reference tracks. Maps those principles to your current session as concrete, actionable moves. |
+
+### Hook Hunter — Finding What Matters
+
+The Hook Hunter identifies the most salient musical idea in a session — the element listeners would remember. It ranks candidates by rhythmic distinctiveness, melodic contour, and repetition. Then it tracks whether hooks are being developed, neglected, or undermined by arrangement choices.
+
+When the hook is strong but underused, it flags it. When a transition fails to deliver the expected payoff, it diagnoses why.
+
+### Session Continuity — The Story of Your Session
+
+Session Continuity tracks what happened, what changed, and what's still unresolved. It maintains creative threads (open questions like "the chorus needs more lift") and records turn resolutions (what you tried, whether you kept it, how it affected identity).
+
+When you return to a project, the session story tells the AI: *"Last time, you were working on making the bridge darker. You tried three approaches and kept the filter sweep. The chorus lift thread is still open."*
+
+### Evaluation Loop — Verify Before Claiming Success
+
+Every creative engine follows the same discipline: **measure before, act, measure after, compare**. The evaluation system captures session state snapshots, runs the change, captures again, and scores the difference. If the change made things worse — more masking, lost headroom, identity drift — the system flags it before you move on.
+
+This closes the gap between "the AI did something" and "the AI did something that actually helped."
 
 <br>
 
@@ -79,7 +150,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 +170,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 +393,30 @@ read_audio_metadata     Format, duration, sample rate, tags
 
 <br>
 
-> **[View all 236 tools →](docs/manual/tool-catalog.md)**
+### Agentic Intelligence — 83 tools
+
+The V2 intelligence layer. These tools don't just execute commands — they analyze, diagnose, plan, evaluate, and learn.
+
+| Domain | # | What it does |
+|--------|:-:|-------------|
+| Agent OS | 8 | session kernel, action ledger, capability state, routing, turn budget |
+| Composition | 9 | section analysis, motif detection, emotional arc, form planning, section transforms |
+| Evaluation | 1 | before/after evaluation with structured scoring |
+| Mix Engine | 6 | critic-driven mix analysis, issue detection, move planning, masking reports |
+| Sound Design | 5 | patch analysis, modulation planning, timbre scoring |
+| Transition Engine | 5 | transition classification, scoring, archetype-based planning |
+| Reference Engine | 5 | reference profiling, principle distillation, gap analysis, move mapping |
+| Translation Engine | 3 | cross-domain translation, issue detection |
+| Performance Engine | 5 | safety-constrained suggestions, safe move lists, scene handoff planning |
+| Song Brain | 4 | identity inference, sacred element detection, drift monitoring, section purposes |
+| Hook Hunter | 9 | hook detection, salience scoring, development strategies, neglect detection, phrase impact |
+| Stuckness Detector | 3 | momentum analysis, rescue classification, structured rescue workflows |
+| Wonder Mode | 3 | diagnosis-driven variant generation, taste-aware ranking, session discard |
+| Session Continuity | 7 | creative threads, turn resolution, taste vs identity ranking, session story |
+| Creative Constraints | 5 | constraint activation, reference-inspired variants, constrained generation |
+| Preview Studio | 5 | variant creation, preview rendering, comparison, commit, discard |
+
+> **[View all 293 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -330,123 +424,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 for real-time spectral analysis.
+The `--setup` wizard and Desktop Extension do this automatically.
 
-Drag `LivePilot_Analyzer.amxd` onto the master track.
+</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.24",
+  "description": "Agentic production system for Ableton Live 12 — 293 tools, 39 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }