livepilot 1.20.3 → 1.21.1

package/CHANGELOG.md

@@ -1,5 +1,295 @@
 # Changelog
 
+## 1.21.1 — Audit-response patch: experiment-commit safety + doc hygiene + lockfile (April 24 2026)
+
+Small patch release responding to an external audit of v1.21.0 performed
+the same day it shipped. The audit surfaced one real safety bug
+(commit_experiment status allowlist was an exclusion list when the
+intent was an inclusion list) plus several doc-consistency drifts.
+No new features. No API changes beyond the tightened commit_experiment
+contract. v1.21.0 callers already doing the right thing
+(run_experiment → commit the ranked winner) continue to work unchanged.
+
+### P1 — commit_experiment only accepts `status='evaluated'`
+
+Pre-fix (v1.21.0 and all prior versions with commit_experiment), the
+status check was an EXCLUSION list:
+
+```python
+if target.status in ("rejected", "analytical", "failed"):
+    return {"error": ...}
+```
+
+Blocks 3 statuses; implicitly allows the other 6 — including `pending`,
+`running`, `discarded`, and `interesting_but_failed`. Those branches
+can't be ranked by `compare_experiments()`, but `commit_experiment`
+would accept them as long as a compiled plan was attached. The code's
+own inline comment already described the correct contract ("only
+status='evaluated' branches are ranking candidates"); the implementation
+had the wrong polarity. The fix flips it to an INCLUSION check:
+
+```python
+if target.status != "evaluated":
+    return {"error": ...}
+```
+
+Error message updated to enumerate all 9 possible statuses and explain
+which state each represents (pending/running = not yet evaluated;
+rejected/analytical/failed = classifier exclusions; committed =
+already committed; discarded = explicitly thrown out;
+interesting_but_failed = exploration-audit only).
+
+Why this matters: v1.21.0's `commit_experiment` ledger writer records
+every commit into `SessionLedger` where anti-repetition filters read
+it. Without the tighter status check, a caller bypassing the ranking
+layer could pollute the ledger with entries the system explicitly
+classified as non-winners — degrading anti-repetition signal quality.
+
+**Regression tests added (4)** in `tests/test_commit_experiment_ledger.py`:
+`test_commit_on_pending_branch_rejects`,
+`test_commit_on_running_branch_rejects`,
+`test_commit_on_discarded_branch_rejects`,
+`test_commit_on_interesting_but_failed_branch_rejects`. All FAILED
+pre-fix (reproducing the audit's finding), all PASS post-fix.
+
+### P1 — package-lock.json bumped 1.17.5 → 1.21.1
+
+Lockfile's root `.version` and `.packages[""].version` had been stale
+at 1.17.5 since before v1.18. `npm publish` doesn't read these fields
+(it reads package.json), so the npm registry was always correct — but
+the repo-local lockfile misled local `npm install` workflows and any
+release-check tooling that compared package.json vs lockfile. Fixed by
+surgical replace on the 2 stale strings; no dependency tree
+regeneration (keeps dep versions identical to v1.21.0).
+
+### P2 — Analyzer tool count: 32/33 → 38 (actual)
+
+README.md previously said "32 spectral/analyzer tools" in one place
+and "38 analyzer tools" in another — inconsistent within the same file.
+`docs/M4L_BRIDGE.md` said "33 MCP tools in the analyzer domain" in two
+places. Actual `@mcp.tool` count in `mcp_server/tools/analyzer.py` is
+**38** (grep-verified). All stale 32/33 refs corrected to 38.
+
+### P2 — Reversibility language hedge
+
+README's header NOTE block said "Everything is reversible with undo,"
+which is too strong. Live-session mutations (clips, devices, mixer,
+arrangement) do route through Ableton's undo stack and are reversible
+— but Splice downloads, memory/ledger writes, installer actions, atlas
+scans, and filesystem writes persist beyond undo. Hedged the language
+to reflect this.
+
+### Deferred to v1.22
+
+Audit-surfaced items that aren't patch-release material:
+
+- **Atlas statistics reconciliation.** Docs claim "1305 devices / 120
+  enriched / 641 pack-indexed" across 9 description fields, but the
+  shipped `device_atlas.json` has 5264 devices and 135 entries with
+  `.enriched` truthy. The "1305" number appears to be a long-stale
+  cargo-culted count. Requires deciding whether `.devices` contains
+  duplicates, what the canonical "enriched" definition is, and
+  whether to restructure atlas JSON or fix the readers that look for
+  `.meta.version`. v1.22 scope.
+- **`sync_metadata` expansion** to check package-lock.json project
+  version, semantic-move count via `registry.count()`, and
+  analyzer-tool count via grep on `analyzer.py`. Would convert this
+  entire class of drift into CI failures.
+- **Dev-install path** for local contributors hitting missing
+  `soundfile` / `scipy` / `pretty_midi` / `pytest_asyncio` deps during
+  bare-python local runs. CI has these installed via requirements.txt.
+
+### Credits
+
+External audit performed same day v1.21.0 shipped. Findings
+file-linked and reproducible. Response time: ~2 hours from audit
+receipt to v1.21.1 patch shipping.
+
+### Scope stats
+
+- 1 code fix (`mcp_server/experiment/tools.py` — commit_experiment status check)
+- 4 new regression tests (all initially FAILING pre-fix to reproduce
+  the audit, all PASSING post-fix)
+- 3 doc corrections (README.md × 2, docs/M4L_BRIDGE.md × 2, plus the
+  reversibility hedge)
+- 15 version-string sites + `.amxd` binary patch (2 bytes) +
+  package-lock.json (2 version fields)
+- Test suite: 3120 → 3124 pass (+4). Zero regressions.
+
+---
+
+## 1.21.0 — Consolidation: experiment ledger + preset library + record-readiness + reader audit (April 24 2026)
+
+Consolidation release closing five items from the v1.20 plan §12 non-goals
+that were tractable in a 2-session scope. Adds 1 new semantic move + 1
+major-tool auto-ledger-write + minimal preset-library infrastructure +
+a store-purpose audit that turns the v1.20 director-SKILL fix into a
+codebase-wide invariant, all gated behind a test-first wire-format
+parity extension that caught 1 pre-v1.20 drift bug and closed the
+audit window.
+
+Registry: 43 → 44 moves. Test suite: 3043 → 3118 pass (+75 across all
+chunks). Wire-format parity suite: 10 → 44 scenarios. Zero regressions.
+
+### New semantic moves (1)
+
+- **`configure_record_readiness`** (performance family, low risk, protects
+  `signal_integrity=0.7`)
+  - seed_args: `{track_index, armed, exclusive?}`
+  - Non-exclusive: single step `set_track_arm(track_index, arm=armed)` — note
+    the wire-format key is `arm`, not `armed` (the MCP tool accepts `armed`
+    as an ergonomic kwarg but renames to `arm` before send_command; the
+    remote_command backend bypasses that rename).
+  - Exclusive (`exclusive=True` + `armed=True`): N+1 step plan —
+    `set_track_arm(arm=False)` for every other regular track, then
+    `set_track_arm(target, arm=True)` for the target. Emulates Ableton's
+    exclusive-arm mode manually because `song.exclusive_arm` has no
+    Python setter in Live 12.4 (pre-existing v1.20.3 Remote Script bug
+    surfaced during v1.21 live-test pre-flight — see plan correction #6).
+    Requires `session_info.tracks` (automatically built by
+    `apply_semantic_move`).
+  - Rejects `exclusive=True + armed=False` (contradictory), missing `armed`
+    seed_arg, and negative `track_index` (return tracks can't be armed
+    per Ableton's handler at `remote_script/LivePilot/tracks.py:261`).
+  - Closes the one tech_debt entry seeded during v1.20 live test 6.
+
+### Experiment-engine ledger writer
+
+- **`commit_experiment`** now writes to `SessionLedger` after a successful
+  commit, mirroring v1.20's `apply_semantic_move` pattern (commit `0b3489b`).
+  Anti-repetition filters downstream now see experiment commits the same
+  way they see direct semantic-move applies.
+  - `engine` tag reflects branch SOURCE (not escalation success): `"composer"`
+    when `target.seed.source == "composer"`, else `"experiment"`. A composer-
+    sourced branch that fell back to scaffold execution is still
+    `engine=composer` — the escalation-success detail lives in
+    `target.evaluation["composer_escalation"]`.
+  - `move_class` via `_infer_move_family(target)`: `seed.family` when set,
+    else inspect first compiled_plan step's tool via `_TOOL_TO_FAMILY`
+    lookup, else default `"mix"`.
+  - `actions` = one entry per ok row in `commit_result["execution_log"]`
+    (the router's actual execution record — captures the post-escalation
+    plan when composer escalation fired).
+  - Response gains `ledger_entry_id` field (same pattern as
+    `apply_semantic_move`). Best-effort — a ledger-write exception is logged
+    and swallowed so the commit never fails on a bookkeeping path.
+
+### Minimal affordance preset library
+
+- New path `mcp_server/affordances/` with loader (`presets.py`), schema
+  validator (`_schema.py`), and 3 seed YAML files:
+  - `reverb.yaml` — preset `dub-cathedral` (Basic Channel-adjacent huge
+    space; Decay 0.85, Room 0.95, Dry/Wet 0.40, Predelay 0.45, Diffusion 0.80)
+  - `delay.yaml` — preset `ping-pong-dub` (dotted 8th, feedback 0.45,
+    HP+LP filtered)
+  - `auto-filter.yaml` — preset `slow-sweep` (LP type, bar-long LFO,
+    moderate resonance)
+- `configure_device` compiler gained optional `preset` + `device_slug`
+  seed_args (additive — v1.20 callers unaffected). Merge: preset resolves
+  first, explicit `param_overrides` win on per-key conflict (last-write-wins).
+  v1.21 requires explicit `device_slug` when `preset` is used; v1.22
+  adds class_name → slug auto-inference.
+- `livepilot-creative-director/references/phase-6-execution.md` §Affordance-
+  preset resolution rewritten to document the live import path and the
+  three dispatch patterns (preset reference, preset + explicit override,
+  fallback to Python resolve).
+
+### Wire-format parity retroactive gate
+
+- `tests/test_compiler_wire_format_parity.py` extended from 10 to 44
+  scenarios (10 v1.20 + 33 pre-v1.20 + 1 new `configure_record_readiness`).
+  Gate surfaced **1 pre-v1.20 drift pattern** affecting 7 moves:
+  `create_chaos_modulator`, `create_feedback_resonator`,
+  `create_wavefolder_effect`, `create_bitcrusher_effect`,
+  `create_karplus_string`, `create_stochastic_texture`, `create_fdn_reverb`
+  all shipped with a `find_and_load_device` plan_template emitting
+  `{"query": "Wonder X"}` but no `track_index`. The `remote_command`
+  backend bypasses MCP normalization, so Ableton's handler threw
+  `KeyError` on `params["track_index"]` — broken at runtime since
+  pre-v1.20, caught now.
+- Fix: `device_creation_compilers.py::_compile_device_creation` threads
+  `track_index` from `seed_args` into `find_and_load_device` steps.
+  Plan templates updated from `{"query": ...}` to `{"device_name": ...}`
+  across all 7 Device Forge moves.
+- Variant-B' consideration (>3 drift bugs → pause v1.21, ship patch):
+  all 7 failures were one pattern in one file, fixable in one commit.
+  Path B (inline fix as part of Task 1.1.5a) taken — single-pattern
+  single-file fixes are exactly what Task 1.1.5a was written for.
+  See `docs/plans/v1.21-impl-status.md` §3 for the decision log.
+
+### Store-purpose reader audit
+
+- Every file in `mcp_server/` that imports `SessionLedger` or calls
+  `memory_list` / `get_session_memory` now carries a
+  `# store_purpose: <purpose>` comment naming its intent.
+- Allowed purposes (closed set): `writer`, `anti_repetition`,
+  `audit_readonly`, `technique_library`, `session_observations`,
+  `escape_hatch_log`, `mcp_tool_definition`.
+- **`tests/test_ledger_readers.py`** new (5 test cases): enforces the
+  annotation contract at CI, AND guards against any file annotated
+  `anti_repetition` also calling `memory_list` — which would be the
+  latent v1.20 store-confusion bug (director SKILL originally pointed
+  at `memory_list` for recency; `memory_list` reads the persistent
+  technique library, not the action ledger).
+- Audit was clean across the entire `mcp_server` tree — no anti-repetition
+  caller was found reading the wrong store. The audit is purely
+  documentation contracts enforced at CI.
+
+### Plan corrections applied during execution (6, logged in impl-status doc)
+
+Documented for future release planners in `docs/plans/v1.21-impl-status.md`:
+
+1. **Baseline drift** — v1.20.2 and v1.20.3 shipped between plan-write and
+   execution; all version-string literals in the plan needed `1.20.1 →
+   1.20.3` remapping.
+2. **Wire-format drift in device_creation** — plan_templates emitted
+   `{"query": ...}`; handler requires `{"track_index", "device_name"}`.
+3. **`set_track_arm` wire format** — plan §3.1 used `{"armed": ...}`;
+   handler reads `params["arm"]`. MCP tool renames `armed → arm` before
+   send_command; remote_command backend bypasses the rename.
+4. **`set_exclusive_arm` shape** — plan §3.1 assumed a per-track signature
+   `(track_index=...)`; handler is a global mode toggle taking
+   `{"enabled": bool}`.
+5. **Return-track arm rejection** — plan's test expected negative
+   `track_index` to succeed; handler raises `ValueError: "Cannot arm a
+   return track"`. Corrected test pins compile-time rejection.
+6. **`set_exclusive_arm` is broken in Live 12.4 LOM** — live-test pre-flight
+   (2026-04-24) surfaced that `song.exclusive_arm` is a property WITHOUT a
+   Python setter in Live 12.4's Remote Script API. The v1.20.3 handler's
+   direct assignment `song.exclusive_arm = bool(...)` errors with
+   "property of 'Song' object has no setter". v1.21's
+   `configure_record_readiness` exclusive-mode now emulates the behavior
+   manually (disarm-all-others + arm-target loop) — correctness is
+   identical, works in any Live version. The broken v1.20.3
+   `set_exclusive_arm` handler is LEFT AS-IS for potential future fix
+   (when/if Ableton re-exposes the setter, or someone finds a LOM method
+   alternative); it's tracked as an independent bug in the Remote Script.
+
+### Non-goals (deferred)
+
+- **Hard cutover of the escape hatch.** v1.22+ target, conditional on
+  zero `tech_debt` log entries accumulating in one month of production.
+- **Standard / Deep preset catalog.** v1.22+. Minimal library from v1.21
+  proves the loader; catalog fills in after real-usage signal.
+- **class_name → slug auto-inference** for the preset library. v1.22+.
+- **Pre-v1.20 move compiler refactors** beyond the 1 drift fix. v1.22+.
+- **New move families beyond the canonical 7.** The performance family
+  already exists; `configure_record_readiness` joins it.
+- **Taste-graph integration for preset ranking.** v1.22+ once the catalog
+  exists.
+
+### Scope stats
+
+- 7 atomic commits on `v1.21.0-dev` (fix + gate + 4 feature + refactor + release)
+- 28 files changed, +1933 / -63 lines
+- 3 new test files (commit_experiment_ledger, performance_moves,
+  affordance_presets, ledger_readers) + 1 doc (impl-status)
+- 1 new package (`mcp_server/affordances/`) + 3 YAML seed files
+- 15 version-string sites bumped + `.amxd` binary patch (2 bytes)
+- 10 files annotated with `# store_purpose:`
+
+---
+
 ## 1.20.3 — Automated analyzer pre-flight (April 24 2026)
 
 Micro-release closing one class of operator error that broke the v1.20.1

package/README.md

@@ -25,7 +25,9 @@
 > [!NOTE]
 > LivePilot works with **any MCP client** — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf.
 > All tools execute on Ableton's main thread through the official Live Object Model API.
-> Everything is reversible with undo.
+> Live-session mutations (clips, devices, mixer, arrangement) route through Ableton's undo stack.
+> Side effects that touch state outside the Live project — Splice downloads, memory/ledger writes,
+> installer actions, atlas scans, filesystem writes — persist beyond undo.
 
 <br>
 
@@ -38,12 +40,12 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | Layer | What it provides |
 |-------|-----------------|
 | **Deterministic Tools** | Direct control: transport, tracks, clips, notes, devices, scenes, mixing, arrangement, browser, automation |
-| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed by name, URI, category, tag, genre, and pack (641 pack-indexed). 120 enriched with sonic intelligence (47 with aesthetic-tagged `signature_techniques`). 683 drum kits mapped. **Free-text `atlas_describe_chain`** ("a granular pad like Tim Hecker") and **reverse-lookup `atlas_techniques_for_device`** (what techniques reference this device?) added in v1.17 |
-| **Concept Surface** | **New in v1.17.** Two reference files let the LLM's training translate into LivePilot: `artist-vocabularies.md` maps ~25 producers (Villalobos, Hawtin, Basic Channel, Gas, Basinski, Hecker, Aphex, Autechre, Dilla, Burial, Henke, Daft Punk, …) to `reach_for` / `avoid` / `key_techniques`; `genre-vocabularies.md` maps 15 genres to tempo / kick / bass / percussion / harmonic / texture / devices. 146 cross-references between devices and techniques. The LLM reads "sound like Gas" and gets a concrete device chain, not guesswork |
-| **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 (v1.17)** |
-| **Spectral Perception** | Real-time ears via M4L — **9-band FFT (v1.17+, sub_low split at 20-60 Hz)**, RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Closes the feedback loop so the AI hears its own changes |
+| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed 7 ways (by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack — 641 pack-indexed). 120 enriched with sonic intelligence (47 with aesthetic-tagged `signature_techniques`). 683 drum kits mapped. Free-text `atlas_describe_chain` ("a granular pad like Tim Hecker") and reverse-lookup `atlas_techniques_for_device` cross-reference 146 techniques across 58 devices |
+| **Concept Surface** | Two reference files let the LLM's training translate into LivePilot: `artist-vocabularies.md` maps ~25 producers (Villalobos, Hawtin, Basic Channel, Gas, Basinski, Hecker, Aphex, Autechre, Dilla, Burial, Henke, Daft Punk, …) to `reach_for` / `avoid` / `key_techniques`; `genre-vocabularies.md` maps 15 genres to tempo / kick / bass / percussion / harmonic / texture / devices. The LLM reads "sound like Gas" and gets a concrete device chain, not guesswork |
+| **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** | A dozen engines that understand song identity, learn your taste, diagnose stuck sessions, generate creative options, and evaluate results before claiming success |
+| **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 |
 
 <br>
 
@@ -101,9 +103,9 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 **MCP Server** (`mcp_server/`) — Python FastMCP server. Validates inputs, routes commands to the Remote Script over TCP, manages the M4L bridge, runs the atlas, sample engine, composer, and all intelligence engines. This is what your AI client connects to.
 
-**M4L Bridge** (`m4l_device/`) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. The 32 spectral/analyzer tools strictly require the bridge; device and sample tools that call the bridge also have graceful fallbacks, so core functionality works without it. Backed by 31 bridge commands for hidden parameters, Simpler internals, warp markers, display values, and Simpler warp / Compressor sidechain writes that live on child objects Python can't reach.
+**M4L Bridge** (`m4l_device/`) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. The 38 spectral/analyzer tools strictly require the bridge; device and sample tools that call the bridge also have graceful fallbacks, so core functionality works without it. Backed by 31 bridge commands for hidden parameters, Simpler internals, warp markers, display values, and Simpler warp / Compressor sidechain writes that live on child objects Python can't reach.
 
-**Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre. The AI never hallucinates a device name or preset — it always resolves against the atlas first.
+**Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack (641 devices mapped to their source pack). Reverse-index `device_techniques_index.json` powers `atlas_techniques_for_device` (146 cross-references across 58 devices). The AI never hallucinates a device name or preset — it always resolves against the atlas first.
 
 **Sample Engine** (`mcp_server/sample_engine/`) — Searches three sources simultaneously: BrowserSource (Ableton's library), SpliceSource (local Splice catalog via SQLite), FilesystemSource (user directories). Every result passes through a 6-critic fitness battery (key, tempo, spectral, genre, mood, technical). 29 processing techniques (Surgeon precision vs. Alchemist experimentation). Builds complete sample processing plans with warp, slice, and effect recommendations.
 
@@ -133,7 +135,7 @@ Learns your production preferences across sessions. Tracks which move families y
 
 ### Semantic Moves — Musical Actions, Not Parameters
 
-26+ high-level intents ("add contrast," "tighten the low end," "build tension") that compile into tool sequences. Each move carries a risk level, target dimensions, and protection thresholds. The AI knows what it's risking with every action.
+**44 high-level intents** across 7 families (mix, arrangement, transition, sound_design, performance, device_creation, sample) — "add contrast," "tighten the low end," "make kick and bass lock," "sample vocal ghost," "destroy then rebuild." Each move compiles into a concrete tool sequence with risk level, target dimensions, and protection thresholds. Analyzer-gated moves (`tighten_low_end`, `make_kick_bass_lock`) mark their spectrum pre-reads as optional so the plan continues even when the analyzer isn't available. The AI knows what it's risking with every action.
 
 ### Wonder Mode — Stuck-Rescue Workflow
 
@@ -177,7 +179,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 <br>
 
-### Core (210 tools)
+### Core Ableton Control — highlights
 
 | Domain | # | What it covers |
 |--------|:-:|----------------|
@@ -200,12 +202,12 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 <br>
 
-### M4L Bridge — 30 tools `[optional]`
+### M4L Bridge — 38 analyzer tools `[optional]`, 31 bridge commands
 
-The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back.
+The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back. The `ensure_analyzer_on_master` pre-flight (v1.20.3) loads the analyzer idempotently on first use — call it once at session start and forget about it.
 
 > [!TIP]
-> Most tools work without the analyzer — it adds 32 spectral/analyzer tools (frequency, loudness, perception) and closes the feedback loop.
+> Most tools work without the analyzer — it adds 38 spectral/analyzer tools (frequency, loudness, perception, Simpler, warp) and closes the feedback loop.
 
 ```
 SPECTRAL ─────── 9-band frequency decomposition (sub_low → air)
@@ -228,36 +230,43 @@ WARP ─────────── get / add / move / remove markers
 
 <br>
 
-### Device Atlas — 6 tools
+### Device Atlas — 10 tools
 
 The atlas is an in-memory indexed database of Ableton's entire device library.
 
 ```
 1305 devices total
   120 enriched with sonic intelligence (mood, genre, texture, chains)
- 683 drum kits mapped with note assignments
-   6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre
+   47 with aesthetic-tagged signature_techniques
+  683 drum kits mapped with note assignments
+    7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack
+  146 technique cross-references across 58 devices (reverse-index)
 ```
 
 ```
-atlas_search           Search devices by name, category, or tag
-atlas_suggest          Suggest devices for a musical intent (e.g., "warm pad")
-atlas_chain            Build a device chain from a genre or purpose
-atlas_compare          Compare two devices side-by-side
-atlas_detail           Get full enriched profile for a device
-atlas_library_scan     Scan what's actually installed on this machine
+atlas_search                   Search devices by name, category, or tag
+atlas_device_info              Full enriched profile for a single device
+atlas_suggest                  Suggest devices for a musical intent (e.g., "warm pad")
+atlas_chain_suggest            Build a device chain from a genre, artist, or purpose
+atlas_compare                  Compare two devices side-by-side
+atlas_describe_chain           Free-text describe-a-chain ("granular pad like Tim Hecker")
+atlas_techniques_for_device    Reverse-lookup: what techniques reference this device?
+atlas_pack_info                Inspect a single Ableton pack — devices + enrichment coverage
+scan_full_library              Scan what's actually installed on this machine
+reload_atlas                   Hot-reload the atlas after adding enrichments
 ```
 
 <br>
 
-### Sample Engine — 6 tools
+### Sample Engine — 23 tools
 
-Three-source sample intelligence with critic-driven fitness scoring.
+Three-source sample intelligence with critic-driven fitness scoring, plus deep Splice integration (catalog search, preview, collections, preset downloads).
 
 ```
 SOURCES ─────────── BrowserSource  (Ableton's built-in library)
                     SpliceSource   (local Splice catalog via SQLite)
                     FilesystemSource (user-specified directories)
+                    Splice LIVE    (gRPC + GraphQL for the full catalog)
 
 CRITICS ─────────── key fitness · tempo fitness · spectral match
                     genre alignment · mood alignment · technical quality
@@ -265,15 +274,35 @@ CRITICS ─────────── key fitness · tempo fitness · spectr
 TECHNIQUES ─────── 29 processing recipes:
                     Surgeon (precise, transparent) vs.
                     Alchemist (experimental, transformative)
+
+PLAN-AWARE ─────── Ableton Live plan   100 samples/day (no credit drain)
+                    Sounds+/Creator     CREDIT_HARD_FLOOR=5 safety gate
+                    Free samples        bypass both gates
 ```
 
 ```
-analyze_sample         Build a complete SampleProfile (material, key, BPM, spectral)
-search_samples         Multi-source search with critic scoring
-suggest_sample_move    Recommend processing technique for a sample
-build_sample_plan      Full processing pipeline: warp + slice + effects
-list_sample_techniques Browse the 29-technique library
-get_sample_technique   Get detailed recipe for a specific technique
+Sample analysis & planning
+  analyze_sample            Build complete SampleProfile (material, key, BPM, spectral)
+  search_samples            Multi-source search with critic scoring
+  evaluate_sample_fit       Score a candidate sample against session context
+  suggest_sample_technique  Recommend processing technique for a sample
+  plan_sample_workflow      Full processing pipeline: warp + slice + effects
+  plan_slice_workflow       Slice-specific workflow for breaks / drum loops
+  get_sample_opportunities  Surface sample-friendly spots in the session
+
+Splice LIVE (catalog, collections, presets)
+  get_splice_credits        Plan + remaining credits + daily quota state
+  splice_catalog_hunt       Query the full Splice catalog (gRPC)
+  splice_download_sample    Plan-aware download (credit floor + quota check)
+  splice_preview_sample     Zero-cost audition via PreviewURL
+  splice_describe_sound     Natural-language search via Splice GraphQL
+  splice_generate_variation Find catalog samples similar to a given UUID
+  splice_list_collections   Enumerate user's Likes / bass / keys folders
+  splice_search_in_collection / add_to_collection / remove_from_collection / create_collection
+  splice_list_presets       Purchased instrument presets
+  splice_preset_info · splice_download_preset
+  splice_pack_info          Per-pack metadata
+  splice_http_diagnose      Debug the Splice HTTPS bridge
 ```
 
 <br>
@@ -461,12 +490,12 @@ livepilot --install
 </details>
 
 <details>
-<summary><strong>3. M4L Analyzer (optional — adds 27 tools)</strong></summary>
+<summary><strong>3. M4L Analyzer (optional — adds 38 tools)</strong></summary>
 
 Drag `LivePilot_Analyzer.amxd` onto the master track for real-time spectral analysis.
-The `--setup` wizard and Desktop Extension do this automatically.
+The `--setup` wizard and Desktop Extension do this automatically. From v1.20.3, your AI client can also call `ensure_analyzer_on_master` — an idempotent pre-flight that loads the device if missing and no-ops otherwise. The Creative Director skill does this on every session's Phase 1 ground read so you can't forget.
 
-> **Important:** The Analyzer must be the LAST device on the master track — after all effects (EQ, Compressor, Utility) so it reads the final output signal.
+> **Important:** The Analyzer must be the LAST device on the master track — after all effects (EQ, Compressor, Utility) so it reads the final output signal. The pre-flight tool reports `is_last_on_master: bool` and warns if the invariant is broken.
 
 </details>
 

package/m4l_device/livepilot_bridge.js

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.20.3";
+var VERSION = "1.21.1";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.20.3"
+__version__ = "1.21.1"

package/mcp_server/affordances/__init__.py

@@ -0,0 +1,31 @@
+"""Affordance-preset library — named presets per Ableton device class.
+
+v1.21 (minimal): infrastructure + 3 seed presets proving the resolver
+pattern:
+  - reverb.yaml       → preset: dub-cathedral
+  - delay.yaml        → preset: ping-pong-dub
+  - auto-filter.yaml  → preset: slow-sweep
+
+v1.22 (planned): full catalog coverage, class_name → slug inference,
+taste-graph integration for preset ranking.
+
+Public API (re-exported for ``from mcp_server.affordances import ...``):
+  resolve_preset(device_slug, preset_name) -> dict[str, number|bool] | None
+  list_devices() -> list[str]
+  list_presets(device_slug) -> list[str]
+  get_preset_metadata(device_slug, preset_name) -> dict | None
+"""
+
+from .presets import (
+    resolve_preset,
+    list_devices,
+    list_presets,
+    get_preset_metadata,
+)
+
+__all__ = [
+    "resolve_preset",
+    "list_devices",
+    "list_presets",
+    "get_preset_metadata",
+]