livepilot 1.27.2 → 1.27.3

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## v1.27.3 — 2026-07-10
+
+Deep-review remediation campaign (2026-07-09, on top of the 2026-06-24 fix batch): event-loop
+blocking eliminated tree-wide, release-pipeline gates hardened, atlas scan truncation fixed,
+Splice connection health, state-layer race/replay guards, docs drift automation, and +262 tests
+(4326 → 4597 passing). No change to the tool surface (467 tools / 56 domains).
+
+### Fixed — event loop (systemic)
+- Every remaining blocking call in async tool paths offloaded (~80 sites across 13 files):
+  the composer fast/full/develop apply executors, the shared plan-step executor
+  (`execution_router._execute_step_async`), preview/experiment paths, analyzer helper call
+  sites, automation session-record, agent_os iteration, device-forge/file I/O, and lifespan
+  subprocess probes. New canonical wrapper `AbletonConnection.send_command_async()`.
+- The AST regression guard now scans ALL of `mcp_server/` (was analyzer.py-only) with
+  one-hop transitive detection and file-I/O/subprocess patterns (`scripts/scan_async_blocking.py`).
+
+Live-verified on Ableton 12.4.2 (2026-07-10): per-track volume reporting, force_arrangement
+with return tracks, sidechain name resolution (both casings), analyzer bridge reconnect, and a
+full 40k-device library rescan with zero category truncation.
+
+### Fixed — correctness
+- Sidechain source matching gained a case-insensitive EXACT tier (found live: Live 12.4
+  routing menus can list bare unprefixed track names, where the "-name" suffix fallback
+  never fires); matching ladder extracted into a tested helper.
+- `audit_layer` §5.1 timbre check was a silent double no-op (wrong call signature + uppercase
+  band table vs lowercase producers) — now plumbs cached analyzer spectrum and case-folds.
+- Atlas scans no longer truncate alphabetically at 1000 entries/category (drum kits previously
+  cut off before reaching most of the alphabet); scans record per-category counts + truncation
+  flags, and atlas searches warn when a truncated category is queried. Rescan required to
+  rebuild an existing user atlas (`scan_full_library(force=True)`).
+- Semantic mix/sound-design/transition/performance moves now nudge track volume RELATIVE to the
+  current level (bounded, direction-safe) instead of writing absolute constants; the Remote
+  Script now reports per-track volume in `get_session_info`.
+- Splice client marks itself degraded on RPC failure and self-heals with a one-shot reconnect —
+  a Splice desktop restart no longer yields silent fake "0 results" for the session; quota
+  check-and-record is atomic; HTTP retry no longer sleeps after the final attempt.
+- Preview/wonder cached plans carry a session fingerprint and refuse commit with STATE_ERROR
+  when the session changed shape; shared caches are lock-guarded; persisted taste/project
+  stores back up before any version-mismatch reset; `song_brain` ids are content-aware.
+- `get_emotional_arc` harmonic-instability term computed (was structurally zero);
+  flucoma probe no longer reports empty dirs as installed; composer engine renumbers layers
+  after unresolved-sample drops on the experiment-escalation path.
+
+### Changed — release gates & CI
+- New CI jobs: MCPB bundle build (asset previously shipped missing for 4 releases),
+  Python 3.11 compatibility for `remote_script/` (compileall + vermin), content-level
+  .amxd freeze check (full bridge command set, not just the version string).
+- `bin/livepilot.js` venv staleness keyed on a requirements.txt content hash (hardcoded import
+  list had drifted — upgrading users silently never installed the Splice gRPC dependencies).
+- `sync_metadata.py` validates JSON manifests version-field-by-field (caught a live
+  server.json split-version); docs Domain Map is now generated from the live registry;
+  banner assets and README What's New are drift-guarded.
+
+### Changed — performance & analysis quality
+- Server import ~2.0s → ~0.9s (lazy overlay index + libyaml CSafeLoader); atlas duplicate
+  warnings throttled; test suite wall-clock ~41s → ~32s.
+- Mix-critic confidence values are data-derived (sample size, measured-vs-heuristic basis,
+  margin) instead of hardcoded literals; `analyze_mix`/`get_mix_issues` accept
+  `target_style="loud_master"` to suppress the over-compressed flag for intentionally loud
+  masters; Wonder Mode ranking surfaces a `boldest_executable` slot alongside the safe pick.
+- Security hardening: corpus plugin-id path validation, loopback-only UDP analyzer ingestion,
+  competing-TCP-client identification in eviction errors.
+
+### Changed — dependencies
+- **2026-06-25** — Raised the Python floor to 3.12: numpy>=2.5.0 and scipy>=1.18.0 declare `Requires-Python >=3.12`, so the prior 3.11 floor blocked both dependency bumps across the CI matrix. CI now tests only Python 3.12; the install-time Python-version diagnostic and manifest/docs floor references were updated to match. `remote_script/` stays 3.11-syntax-compatible for Ableton's embedded Python (Live 12.3) — the CI matrix change does not relax that constraint.
+
 ## v1.27.2 — 2026-06-23
 
 Maintenance release: M4L bridge response-correlation + chunk-reassembly hardening, plan-routing fixes, a Python 3.11 floor with clearer install diagnostics, and a Remote Script Group-track crash guard. No change to the tool surface (467 tools / 56 domains). Re-frozen LivePilot_Analyzer.amxd (analyzer reports 1.27.2).

package/README.md

@@ -38,14 +38,17 @@
 
 ---
 
-## What's New in v1.27.1
+## What's New in v1.27.3
 
-A maintenance release that fixes 35 issues from a deep audit and restores tools that had silently broken:
+A deep-review remediation release — ~150 fixes across two audit campaigns, no change to the tool surface (467 tools / 56 domains):
 
-- **Restored tools** — `augment_with_samples`, `get_composition_plan`, `propose_composer_branches`, `check_clip_key_consistency`, and `compare_phrase_renders` were crashing or returning empty results; they now work.
-- **Recursive plugin scanning (#44)** — the User Corpus scanner now finds plugins nested in vendor subfolders (e.g. `VST3/<Vendor>/Plugin.vst3`) instead of only the top level.
-- **Truer analysis** — reference-gap, hook-salience, dynamics, drop-detection, harmony-slot, and grader fixes that previously produced fabricated or empty results.
-- **Safer & faster** — Splice credit-gating fixed, blocking sample I/O moved off the event loop, unbounded tool responses capped, and the M4L bridge no longer loses responses on UDP reordering.
+- **Event-loop blocking eliminated tree-wide** — every remaining blocking call in async tool paths (composer apply executors, the shared plan-step executor, preview/experiment paths, ~80 sites in 13 files) now offloads to a worker thread; a repo-wide AST regression guard keeps it that way. Long composes no longer freeze concurrent tools or the analyzer bridge.
+- **Atlas scans no longer truncate** — library scans previously capped each category at 1,000 entries alphabetically (most drum one-shots were unreachable); the cap is now 25,000 with per-category truncation flags and rescan warnings. Run `scan_full_library(force=True)` once to rebuild your atlas.
+- **Splice self-heals** — a Splice desktop restart no longer silently turns every search into fake "0 results"; the client marks itself degraded and reconnects on the next call.
+- **Safer state** — cached preview/wonder plans carry a session fingerprint and refuse to replay against a session that changed shape; persisted taste/project stores back up before any reset.
+- **Stronger release gates** — the MCPB bundle, .amxd freeze content, and Python 3.11 Remote Script compatibility are now all CI-enforced.
+- **Python 3.12 floor** for the MCP server (numpy ≥2.5 / scipy ≥1.18); the Remote Script stays 3.11-compatible for Ableton's embedded Python.
+- **v1.27.1** fixed 35 issues from a deep audit and restored tools that had silently broken (`augment_with_samples`, `get_composition_plan`, `propose_composer_branches`, `check_clip_key_consistency`, `compare_phrase_renders`), plus recursive installed-plugin scanning.
 - **v1.27.0** added two read-only Live 12.4 capability-probe tools (`probe_link_audio`, `probe_stem_workflow`).
 
 Full details in the [CHANGELOG](CHANGELOG.md).
@@ -751,7 +754,7 @@ npx livepilot --version    # Show version
 | Requirement | Minimum |
 |-------------|---------|
 | Ableton Live | **12** (any edition). Suite required for Max for Live bridge and stock instruments |
-| Python | 3.11+ (numpy/scipy ship no wheels for 3.9/3.10) |
+| Python | 3.12+ (numpy>=2.5 / scipy>=1.18 require Python 3.12) |
 | Node.js | 18+ |
 | OS | macOS / Windows |
 | Splice | Desktop app with downloaded samples (optional — enables SQLite metadata search) |

package/bin/livepilot.js

@@ -15,12 +15,12 @@ const REQUIREMENTS = path.join(ROOT, "requirements.txt");
 // Python detection
 // ---------------------------------------------------------------------------
 
-// Minimum Python is 3.11, NOT 3.9: numpy>=2.4.6 and scipy>=1.17.1 (see
-// requirements.txt) publish no wheels and declare requires-python ">=3.11".
-// A 3.9/3.10 interpreter passes a looser gate, the venv is created, then
-// `pip install` aborts with a cryptic "no matching distribution" — the exact
-// install failure users hit. Gate here so we fail early with a clear message.
-const MIN_PY_MINOR = 11;
+// Minimum Python is 3.12: numpy>=2.5.0 and scipy>=1.18.0 (see requirements.txt)
+// declare requires-python ">=3.12". An older interpreter passes a looser gate,
+// the venv is created, then `pip install` aborts with a cryptic "no matching
+// distribution" — the exact install failure users hit. Gate here so we fail
+// early with a clear message.
+const MIN_PY_MINOR = 12;
 
 function findPython() {
   // On Windows, also try the "py -3" launcher which avoids the
@@ -47,7 +47,7 @@ function findPython() {
           const actualArgs = cmd === "py" ? ["-3"] : [];
           return { cmd: actualCmd, version: out, prefixArgs: actualArgs };
         }
-        // Found Python 3 but below 3.11 — remember the newest for diagnostics.
+        // Found Python 3 but below 3.12 — remember the newest for diagnostics.
         if (major === 3 && (!tooOld || minor > tooOld.minor)) {
           tooOld = { version: out, minor };
         }
@@ -122,8 +122,8 @@ function pipInstall(venvPy) {
     console.error("");
     console.error("LivePilot: dependency installation failed.");
     if (/No matching distribution|requires-python|Could not find a version/i.test(stderr)) {
-      console.error("  Most likely your Python is too old — LivePilot needs Python >= 3.11");
-      console.error("  (numpy/scipy ship no wheels for 3.9/3.10). Install 3.11+, delete the");
+      console.error("  Most likely your Python is too old — LivePilot needs Python >= 3.12");
+      console.error("  (numpy>=2.5 / scipy>=1.18 require Python 3.12). Install 3.12+, delete the");
       console.error("  .venv folder, and retry.");
     }
     const tail = stderr.split("\n").filter(Boolean).slice(-12);
@@ -136,6 +136,48 @@ function pipInstall(venvPy) {
   }
 }
 
+/**
+ * Content hash of requirements.txt — the venv staleness signal.
+ *
+ * The previous check was a hardcoded import list that silently drifted from
+ * requirements.txt (grpcio/protobuf were added for the Splice gRPC surface
+ * but never joined the list, so upgrading users kept a venv without them and
+ * the feature silently disabled itself). Hashing the file makes staleness
+ * detection automatically correct for every future dependency change.
+ */
+function requirementsHash() {
+  const crypto = require("crypto");
+  const reqs = fs.readFileSync(path.join(ROOT, "requirements.txt"));
+  return crypto.createHash("sha256").update(reqs).digest("hex");
+}
+
+function venvStampPath() {
+  return path.join(ROOT, VENV_DIR, ".requirements-sha256");
+}
+
+function writeVenvStamp() {
+  try {
+    fs.writeFileSync(venvStampPath(), requirementsHash() + "\n");
+  } catch {
+    // Non-fatal: worst case the next run reinstalls.
+  }
+}
+
+/**
+ * Pure decision function for venv staleness — extracted from ensureVenv so
+ * the reinstall/reuse/create branching can be unit-tested without touching
+ * the filesystem or spawning pip/venv. Behavior-identical to the inline
+ * logic it replaces:
+ *   - no venv on disk                       -> "create"
+ *   - venv exists, stamp matches hash       -> "reuse"
+ *   - venv exists, stamp missing/mismatched -> "update"
+ */
+function decideVenvAction(venvExists, storedStamp, currentHash) {
+  if (!venvExists) return "create";
+  if (storedStamp === currentHash) return "reuse";
+  return "update";
+}
+
 /**
  * Ensure a local .venv exists with dependencies installed.
  * Returns the path to the venv Python binary.
@@ -143,25 +185,31 @@ function pipInstall(venvPy) {
 function ensureVenv(systemPython, prefixArgs) {
   const prefix = prefixArgs || [];
   const venvPy = venvPython();
+  const venvExists = fs.existsSync(venvPy);
 
-  // Check if venv already exists and has our deps
-  if (fs.existsSync(venvPy)) {
+  let stamp = null;
+  if (venvExists) {
     try {
-      execFileSync(venvPy, ["-c", "import fastmcp; import midiutil; import pretty_midi; import numpy; import pyloudnorm; import soundfile; import scipy; import mutagen"], {
-        encoding: "utf-8",
-        timeout: 10000,
-        stdio: "pipe",
-      });
-      return venvPy; // venv exists and all deps importable
+      stamp = fs.readFileSync(venvStampPath(), "utf-8").trim();
     } catch {
-      // venv exists but deps missing — reinstall
-      console.error("LivePilot: reinstalling Python dependencies...");
-      pipInstall(venvPy);
-      return venvPy;
+      stamp = null; // pre-hash venv (or stamp deleted) — verify by reinstall
     }
   }
 
-  // Create venv from scratch
+  const action = decideVenvAction(venvExists, stamp, requirementsHash());
+
+  if (action === "reuse") {
+    return venvPy; // venv exists and was installed from this exact requirements.txt
+  }
+
+  if (action === "update") {
+    console.error("LivePilot: requirements changed — updating Python dependencies...");
+    pipInstall(venvPy);
+    writeVenvStamp();
+    return venvPy;
+  }
+
+  // action === "create"
   console.error("LivePilot: setting up Python environment (first run)...");
   execFileSync(systemPython, [...prefix, "-m", "venv", VENV_DIR], {
     cwd: ROOT,
@@ -171,6 +219,7 @@ function ensureVenv(systemPython, prefixArgs) {
 
   console.error("LivePilot: installing dependencies...");
   pipInstall(venvPython());
+  writeVenvStamp();
 
   return venvPython();
 }
@@ -309,12 +358,12 @@ async function doctor() {
   if (pyInfo && !pyInfo.tooOld) {
     console.log("  Python: %s (%s)", pyInfo.version, pyInfo.cmd);
   } else if (pyInfo && pyInfo.tooOld) {
-    console.log("  Python: %s found, but LivePilot needs >= 3.11", pyInfo.version);
-    console.log("    Fix: install Python 3.11+ (numpy/scipy ship no wheels for 3.9/3.10)");
+    console.log("  Python: %s found, but LivePilot needs >= 3.12", pyInfo.version);
+    console.log("    Fix: install Python 3.12+ (numpy>=2.5 / scipy>=1.18 require Python 3.12)");
     ok = false;
   } else {
-    console.log("  Python: NOT FOUND (need >= 3.11)");
-    console.log("    Fix: install Python 3.11+ and add to PATH");
+    console.log("  Python: NOT FOUND (need >= 3.12)");
+    console.log("    Fix: install Python 3.12+ and add to PATH");
     ok = false;
   }
 
@@ -737,12 +786,12 @@ async function setup() {
   if (pyInfo && !pyInfo.tooOld) {
     console.log("  ✓ %s", pyInfo.version);
   } else if (pyInfo && pyInfo.tooOld) {
-    console.log("  ✗ %s found, but LivePilot needs Python >= 3.11", pyInfo.version);
-    console.log("    (numpy/scipy ship no wheels for 3.9/3.10 — pip would fail)");
+    console.log("  ✗ %s found, but LivePilot needs Python >= 3.12", pyInfo.version);
+    console.log("    (numpy>=2.5 / scipy>=1.18 require Python 3.12 — pip would fail)");
     console.log("    Install: brew install python@3.12 (macOS) or python.org (Windows)");
     ok = false;
   } else {
-    console.log("  ✗ Python >= 3.11 not found");
+    console.log("  ✗ Python >= 3.12 not found");
     console.log("    Install: brew install python@3.12 (macOS) or python.org (Windows)");
     ok = false;
   }
@@ -784,7 +833,7 @@ async function setup() {
       ok = false;
     }
   } else if (pyInfo && pyInfo.tooOld) {
-    console.log("  ⊘ Skipped (%s found, need Python >= 3.11)", pyInfo.version);
+    console.log("  ⊘ Skipped (%s found, need Python >= 3.12)", pyInfo.version);
   } else {
     console.log("  ⊘ Skipped (no Python)");
   }
@@ -974,12 +1023,12 @@ async function main() {
   const pyInfo = findPython();
   if (!pyInfo || pyInfo.tooOld) {
     if (pyInfo && pyInfo.tooOld) {
-      console.error("Error: found %s, but LivePilot requires Python >= 3.11.", pyInfo.version);
-      console.error("  numpy>=2.4.6 and scipy>=1.17.1 publish no wheels for Python 3.9/3.10,");
-      console.error("  so dependency installation would fail. Install Python 3.11 or newer.");
+      console.error("Error: found %s, but LivePilot requires Python >= 3.12.", pyInfo.version);
+      console.error("  numpy>=2.5.0 and scipy>=1.18.0 require Python >= 3.12,");
+      console.error("  so dependency installation would fail. Install Python 3.12 or newer.");
     } else {
-      console.error("Error: Python >= 3.11 is required but was not found.");
-      console.error("  Install Python 3.11+ and ensure 'python3' or 'python' is on your PATH.");
+      console.error("Error: Python >= 3.12 is required but was not found.");
+      console.error("  Install Python 3.12+ and ensure 'python3' or 'python' is on your PATH.");
     }
     console.error("");
     console.error("  macOS:   brew install python@3.12");
@@ -1026,7 +1075,16 @@ async function main() {
   });
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Only auto-run the CLI when this file is executed directly (`node
+// bin/livepilot.js ...` or `npx livepilot ...`). When `require()`d as a
+// module — e.g. from tests exercising `decideVenvAction` in isolation —
+// skip the side-effecting entrypoint. Behavior-identical for real CLI
+// invocations; this guard only matters when the file is `require()`d.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { decideVenvAction, requirementsHash, venvStampPath };

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

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.27.2",
+  "version": "1.27.3",
   "description": "Agentic production system for Ableton Live 12 \u2014 467 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

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.27.2",
+  "version": "1.27.3",
   "description": "Agentic production system for Ableton Live 12 \u2014 467 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/skills/livepilot-core/SKILL.md

@@ -47,7 +47,7 @@ Agentic production system for Ableton Live 12. 467 tools across 56 domains, thre
     - **Parameter ranges are NOT always 0-1.** Auto Filter Frequency is 20-135. Bit Depth is 1-16. Always read `value_string` to see actual units.
 16. **NEVER apply automation recipes without understanding the target parameter's range** — recipes generate 0-1 curves that get auto-scaled for device parameters, but always verify the result
 17. **LivePilot_Analyzer must be LAST on master chain** — always place after ALL effects (EQ, Compressor, Utility, etc.) so it measures the final post-processing output, not the raw signal. When loading effects on master, either load them before the analyzer or move the analyzer to end afterward
-18. **Remote Script reload workflow** — after any edit to `remote_script/LivePilot/*.py`: run `npx livepilot --install` (NOT `node installer/install.js` — that raw file only module-exports the install function and silently no-ops as a script), then call `reload_handlers` (MCP tool, domain: diagnostics). NEVER instruct the user to toggle the Control Surface in Live Preferences. The tool uses pkgutil + importlib to re-fire `@register` decorators in-place in <1s while the TCP connection stays open. Standard procedure for every handler change — not just releases
+18. **Remote Script reload workflow** — after any edit to `remote_script/LivePilot/*.py`: install, then call `reload_handlers` (MCP tool, domain: diagnostics). From a LOCAL CHECKOUT the install command is `node bin/livepilot.js --install` — `npx livepilot --install` fetches the PUBLISHED npm package and overwrites local edits with stale code. Use `npx livepilot --install` only for the published package (end-user installs). Either way, NOT `node installer/install.js` — that raw file only module-exports the install function and silently no-ops as a script. NEVER instruct the user to toggle the Control Surface in Live Preferences. The tool uses pkgutil + importlib to re-fire `@register` decorators in-place in <1s while the TCP connection stays open. Standard procedure for every handler change — not just releases
 
 ## Tool Speed Tiers
 
@@ -79,6 +79,38 @@ Report ALL errors to the user immediately. Common failure modes:
 - **M4L Analyzer not connected** — if `get_master_spectrum` errors with "Analyzer not detected", call `ensure_analyzer_on_master`. If it returns `install_required`, call `install_m4l_device(source_path="<repo>/m4l_device/LivePilot_Analyzer.amxd")` and retry. If it errors with "UDP bridge not connected", try `reconnect_bridge` first
 - **Another client connected** — Remote Script only accepts one TCP client on port 9878. If you see this error, the MCP server is already connected. Use MCP tools instead of raw TCP
 
+## Response Fields You Must Check
+
+These fields were added to existing tool responses. They aren't optional
+extras — each one changes what you're allowed to claim to the user.
+
+- **`degraded_reason`** (`enter_wonder_mode` / Wonder Mode) — non-empty when
+  fewer than 3 of the returned variants are actually executable, or when no
+  matching moves were found and variants are cold-start fallbacks. Contract:
+  if `degraded_reason` is set, do NOT present the set as "three genuinely
+  different options" — disclose the degradation honestly. See
+  `livepilot-wonder`.
+- **`unenforced_constraints`** (`apply_creative_constraint_set` / Creative
+  Constraints) — lists constraint names that are advisory-only; the engine
+  cannot mechanically verify them against compiled steps. Contract: for every
+  name in this list, YOU must self-police that constraint manually — the
+  tool returning `valid: true` does not mean an advisory constraint wasn't
+  violated.
+- **`measured` / `severity_basis`** (`get_masking_report` / Mix Engine) — a
+  masking entry's `severity` is either a real per-track spectral-overlap
+  measurement (`measured=True`, `severity_basis="spectral_overlap"`) or a
+  role-pair heuristic constant (`measured=False`,
+  `severity_basis="role_heuristic"`). Contract: treat `measured=False`
+  entries as low-confidence priors, not verified problems — solo the tracks
+  and read `get_master_spectrum` before taking a mixing action based on them
+  (§3 Analysis Before Action). See `livepilot-mix-engine`.
+- **`load_via` / `browse_hint`** (Atlas — `atlas_search`, `atlas_suggest`,
+  `atlas_device_info`, etc.) — set when an atlas entry's `uri` is cleared
+  because it's a known-broken M4L pack-instrument reference. Contract: when
+  `load_via == "preset"`, do NOT call `load_browser_item` with the atlas
+  `uri` (it's empty/invalid) — call `search_browser` with `browse_hint`
+  instead to resolve a real URI first.
+
 ## Technique Memory
 
 Three modes:

package/livepilot/skills/livepilot-core/references/atlas-tool-notes.md

@@ -0,0 +1,69 @@
+# Atlas Tool Notes
+
+Implementation history and rationale for `mcp_server/atlas/tools.py`
+tools. The tool docstrings carry the operational contract (params,
+return shape, behavior); this file carries the bug history and
+step-by-step internals that explain *why* a tool behaves a certain way,
+for when that context is actually needed.
+
+## `scan_full_library` — scan cap history
+
+`max_per_category` defaults to 25000, matching the remote script's own
+default. The original hardcoded 1000 cap silently truncated large
+categories in browser-tree (alphabetical) order — e.g. `drum_kits`
+stopped at "Crash" (0 kicks, 2 hats), and the `samples` category alone
+has ~22,000 items per the browser tree, so a "1000 samples" count was
+wrong by a factor of 22 (BUG-2026-04-22#12). Raise the cap further for
+even bigger libraries; lower it for fast smoke scans.
+
+`truncated_categories` / `stats.category_truncated` are persisted into
+`device_atlas.json` so `AtlasManager` can warn future
+`atlas_search`/`atlas_suggest` calls that touch a truncated category
+without requiring a fresh scan first (P3-47).
+
+Scans always write to the user atlas path
+(`~/.livepilot/atlas/device_atlas.json`), never the bundled baseline —
+this keeps personal inventories (packs, user_library, plugins) out of
+the repo and surviving npm updates (v1.22.0). Enrichments are still
+read from the bundled package.
+
+## `atlas_describe_chain` — internals
+
+Free-text → chain proposal pipeline, mirroring `splice_describe_sound`
+for the device library (`atlas_chain_suggest` is the structured-input
+sibling — role + genre instead of a sentence):
+
+1. Parse role hints from the description (bass/lead/pad/keys/
+   percussion/drums/vocal/fx keyword buckets)
+2. Parse aesthetic hints — artist names map to genre/character tags
+   (cross-reference `artist-vocabularies.md`), plus explicit genre
+   names and character words (warm/cold/bright/dark/lush/...)
+3. Search the atlas (factory + user overlay namespaces) with those terms
+4. Propose the top devices per role with brief rationale, then take the
+   top suggestion per role as a simple ordered `chain_proposal`
+
+Does not autoload anything — the caller reviews/adjusts, then executes
+via `load_browser_item` + effects.
+
+## `atlas_techniques_for_device` — index
+
+Backed by the reverse-index file `device_techniques_index.json`
+(auto-generated from the knowledge base — regenerate via the
+post-v1.17 reverse-index builder script when adding new techniques;
+rare, since most additions happen through enrichment YAMLs that the
+index reads directly). `kind` values: `signature_technique` (from the
+device's own atlas entry), `sample_technique` (from
+`sample-techniques.md`), `sound_design_principle` (from
+`sound-design-deep.md`).
+
+## `atlas_search` — overlay budget split
+
+Searches both the bundled factory atlas (5,264 devices / 33 packs) and
+the user-local overlay corpus (`~/.livepilot/atlas-overlays/` — user-
+scanned Max devices, racks, plugin presets, AI-synthesized plugin
+identity YAMLs). When both sources have hits, `limit` splits roughly
+50/50 (factory gets the rounding-up extra slot); a source with zero
+hits doesn't consume budget. M4L pack instruments occasionally carry a
+bogus `query:Synths#` URI in the atlas — `atlas_search` clears it and
+surfaces a `browse_hint` so callers don't hit `INVALID_PARAM` from
+`load_browser_item` (LIVE#3).

package/livepilot/skills/livepilot-core/references/overview.md

@@ -1,4 +1,4 @@
-# LivePilot v1.27.2 — Architecture & Tool Reference
+# LivePilot v1.27.3 — Architecture & Tool Reference
 
 Agentic production system for Ableton Live 12. 467 tools across 56 domains. Device atlas (5264 devices, 120 enriched, 47 with aesthetic-tagged `signature_techniques`), spectral perception (M4L analyzer with 9-band FFT — sub_low / sub / low / low_mid / mid / high_mid / high / presence / air), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O, **LIVE Splice describe-a-sound + variations via captured GraphQL endpoints (v1.17)**, drum-rack pad-by-pad construction, live dead-device detection via meter sampling, role-aware Simpler defaults, session-record arrangement-automation workaround.
 
@@ -44,9 +44,16 @@ A flat tool list lets the AI press buttons. LivePilot's three layers give it con
 
 This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spectrum to confirm the mud is actually reduced."
 
-## The 467 Tools — What Each One Does
+## Core-Domain Reference (~228 tools, 13 of 56 domains)
 
-### Transport (12) — Playback, tempo, global state, diagnostics
+This section documents the 13 highest-traffic domains in prose (what each
+tool does, when to reach for it). It is intentionally NOT exhaustive — the
+remaining domains (sample_engine, atlas, agent_os, wonder_mode, and the rest
+of the Creative Intelligence layer) are covered by their own domain skills
+and by the auto-generated **[Tool Catalog](../../../../docs/manual/tool-catalog.md)**,
+which lists all 467 tools across all 56 domains.
+
+### Transport (showing 12 of 21) — Playback, tempo, global state, diagnostics
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -63,7 +70,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `get_recent_actions` | Returns log of recent commands sent to Ableton (newest first) | `limit` (1-50, default 20) |
 | `get_session_diagnostics` | Analyzes session for issues: armed tracks, solo leftovers, unnamed tracks, empty clips | — |
 
-### Tracks (14) — Create, delete, configure, group tracks
+### Tracks (showing 14 of 21) — Create, delete, configure, group tracks
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -82,7 +89,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `set_group_fold` | Folds/unfolds a group track | `track_index`, `folded` (bool) |
 | `set_track_input_monitoring` | Sets input monitoring state | `track_index`, `state` (0=In, 1=Auto, 2=Off) |
 
-### Clips (11) — Clip lifecycle, properties, warp
+### Clips (showing 11 of 16) — Clip lifecycle, properties, warp
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -122,7 +129,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 - `velocity_deviation` — -127.0 to 127.0
 - `release_velocity` — 0.0-127.0
 
-### Devices (15) — Instruments, effects, racks, 12.3+ device insertion
+### Devices (showing 15 of 42) — Instruments, effects, racks, 12.3+ device insertion
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -142,7 +149,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `set_chain_volume` | Sets volume of a rack chain | `track_index`, `device_index`, `chain_index`, `volume` |
 | `get_device_presets` | Lists presets for a device (audio effects, instruments, MIDI effects) | `device_name` |
 
-### Scenes (8) — Scene management
+### Scenes (showing 8 of 12) — Scene management
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -180,7 +187,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `search_browser` | Searches the browser | `query` |
 | `load_browser_item` | Loads a browser item onto a track — **`uri` MUST come from `search_browser` results, NEVER invented** | `track_index`, `uri` |
 
-### Arrangement (20) — Timeline, recording, cue points, arrangement notes
+### Arrangement (showing 20 of 21) — Timeline, recording, cue points, arrangement notes
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -205,7 +212,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `jump_to_cue` | Jumps to a cue point by index | `cue_index` |
 | `toggle_cue_point` | Creates/removes cue point at current position | — |
 
-### Memory (8) — Technique library persistence
+### Memory (showing 8 of 18) — Technique library persistence
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -218,7 +225,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `memory_update` | Updates name, tags, or qualities | `technique_id`, `name`, `tags`, `qualities` |
 | `memory_delete` | Removes technique (backs up first) | `technique_id` |
 
-### Analyzer (38) — Real-time DSP analysis (requires LivePilot Analyzer M4L device on master track)
+### Analyzer (showing 20 of 38) — Real-time DSP analysis (requires LivePilot Analyzer M4L device on master track)
 
 | Tool | What it does | Key params |
 |------|-------------|------------|
@@ -243,7 +250,7 @@ This turns "set EQ band 3 to -4 dB" into "cut 400 Hz by 4 dB, then read the spec
 | `stop_scrub` | Stop preview | `track_index`, `clip_index` |
 | `get_display_values` | Human-readable parameter values ("440 Hz", "-6 dB") | `track_index`, `device_index` |
 
-### Automation (8) — Clip automation CRUD + intelligent curve generation
+### Automation (showing 8 of 9) — Clip automation CRUD + intelligent curve generation
 
 | Tool | What it does | Key params |
 |------|-------------|------------|