livepilot 1.23.6 → 1.25.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## v1.25.0 — 2026-05-02
+
+Hybrid Knowledge Surface — closes the gap between "compose runs successfully" and "compose makes thoughtful production decisions" by giving the agent three layers of atlas-corpus access during plan design instead of one-shot pre-resolution.
+
+### Added — three new MCP tools
+
+- **`atlas_explore(role, mood, genre, artists?, n=5, avoid_uris?, cohort_constraint?)`** — refined per-role candidate query callable mid-design. Wraps `AtlasResolver.resolve_for_role` with corpus-deep ranking signals: tag/genre match base, signature_techniques mood overlap (+0.20), curated `.adg` boost (+0.10), recent positive preference (+0.10), §1 banned-default penalty for melodic roles (−0.50), opaque-M4L pad penalty (−0.30), §7 #2 anti-repeat (−0.15), caller avoid-list (−0.30). Returns 3-5 ranked candidates with reasoning trails and a cohort_hint inferred from result frequency.
+- **`atlas_audition(uri)`** — full sidecar dump for a single URI: character_tags, signature_techniques (joined from `device_techniques_index.json`), producer-curated macro names (joined via `preset_resolver`), curated `.adg` paths, related demos placeholder. Use BEFORE committing to a candidate when its tags alone aren't enough.
+- **`atlas_substitute(current_uri, anti_tag, n=3)`** — anti-tag-driven swap for after analyze_sound_design or analyze_mix flags an issue. Substring-matches anti_tag against the 11-key map (bright/harsh/aggressive/sparse/thin/muddy/clean/dark/warm/static/generic) to derive (excluded_tags, preferred_tags), filters role-mate candidates that don't carry excluded character_tags, ranks the survivors with preferred_tags as mood boost.
+
+### Added — framework
+
+- **`mcp_server/composer/framework/atlas_resolver.py`** — `AtlasResolver` class with `resolve_anchors()` (Layer A: cohort + role-anchored URIs at brief-build time, wraps `atlas_pack_aware_compose` with coarse→fine role mapping) and `resolve_for_role()` (Layer B: per-role ranked candidates with cohort_constraint + excluded_uris). `AtlasCandidate` and `AtlasAnchors` dataclasses define the shared shape. Memory-rule constants `BANNED_DEFAULT_MELODIC` and `OPAQUE_M4L_FOR_PAD` are exported.
+- **`mcp_server/atlas/explore_tools.py`** — pure-Python implementations for the three new MCP tools, including `_ANTI_TAG_MAP` (11-key inversion table) and `_load_device_techniques_index()` lazy loader.
+
+### Changed — KnowledgePack + brief
+
+- `KnowledgePack.build()` accepts `atlas`, `ableton`, `ctx`, `brief_text` kwargs. When `mode="full"` AND `atlas` AND `brief_text` are provided, populates `atlas_anchors` (best-effort — silently `None` on any failure path).
+- `build_full_brief` now threads the atlas object through. The brief carries `atlas_anchors` alongside the existing fields.
+- `_DESIGN_TARGETS` text in `full/brief_builder.py` updated to teach the LLM about the three new tools and when to call each.
+
+### Tests
+
+- `tests/composer/framework/test_atlas_resolver.py` — 17 cases covering ranking math (8), `resolve_for_role` (6), candidate shape (1), `resolve_anchors` integration with mocked `pack_aware_compose` (2).
+- `tests/atlas/test_explore_tools.py` — 20 cases covering `atlas_explore` (6), `atlas_audition` (5), `_resolve_anti_tags` (3), `atlas_substitute` (6).
+- `tests/test_tools_contract.py` — count assertion updated 459 → 462; atlas tool registry expects the three new names.
+
+### Tool count
+
+- Net delta: **459 → 462** (+3: atlas_explore, atlas_audition, atlas_substitute).
+
+### Changed — `resolve_for_role` four-source union
+
+- **`AtlasResolver.resolve_for_role()`** previously queried only the bundled atlas tag index (`self._atlas._by_tag`). User-curated rack instruments and pack overlays were structurally invisible to the agent's design-time queries.
+- Two-pass overlay union added via new helper `_gather_from_overlays()`:
+  - **Pass A** — explicit `entity_type="demo_project"` query against the `packs` namespace. Demo-project entries (analyzed `.als` parses with `track_names` + `parent_pack` + `device_class_counts`) are the highest-confidence per-role anchors. Each survivor receives a **+0.15 score boost** with reasoning trail entry `"demo_project ground-truth (+0.15)"`.
+  - **Pass B** — full overlay search with no namespace filter. Captures `packs/pack`, `packs/cross_pack_workflow`, `m4l-devices/*`, `user.*`, `elektron/*` entries that share role tags.
+- New helper `_overlay_entry_to_device()` synthesizes `overlay://<namespace>/<entity_id>` URIs so overlay candidates render in the same shape as factory atlas candidates. Agents resolve to a loadable URI via `extension_atlas_get(namespace, entity_id)` afterward.
+- Best-effort: import or runtime failure of the overlay backend silently returns an empty list rather than raising — matches the existing `resolve_anchors` failure semantics.
+
+### Changed — `_DESIGN_TARGETS` four-source search mandate
+
+- Brief text in `mcp_server/composer/full/brief_builder.py::_DESIGN_TARGETS` rewritten to explicitly require the agent to UNION four sources before committing any role pick:
+  1. **Source 1 — Factory atlas** (already in `atlas_anchors`): `atlas_explore` / `atlas_audition` / `atlas_substitute`.
+  2. **Source 2 — User corpus** (mandatory): `extension_atlas_search(query=role)` and `extension_atlas_search(query=role, entity_type="demo_project")` for ground-truth role→URI mappings, plus `extension_atlas_get(namespace, entity_id)` for full-body inspection.
+  3. **Source 3 — Anthropic Ableton Knowledge MCP**: `mcp__Ableton_Knowledge__search_transcripts` / `search_live_manual` / `search_knowledge_base` / `search_videos` for tutorial-grade context.
+  4. **Five-step protocol** documented per role: read anchor → atlas_explore → extension_atlas_search (corpus + demo_project) → Ableton_Knowledge search → union, score, commit.
+- Production motivation: factory-atlas-only selection consistently missed canonical user-curated rack instruments (e.g., the `808 Trap Selector Rack.adg` from the Trap Drums by Sound Oracle pack lives in the packs overlay, not the factory tag index).
+
+### Fixed — `load_browser_item(role="drum")` post-load defaults
+
+Two compounding bugs in `mcp_server/tools/browser.py` made `role="drum"` a no-op since v1.20:
+
+- **Wrong parameter name** — `_SIMPLER_ROLE_DEFAULTS["drum"]` set `"Sample Pitch Coarse"` to 36, but that parameter does NOT exist on `OriginalSimpler`. The `set_device_parameter` call raised `Parameter 'Sample Pitch Coarse' not found`, was swallowed by the per-param try/except, and silently lost. Replaced with `("Transpose", 24)` (range −48..+48 semitones); +24 compensates for Simpler's default sample root C3 vs the drum-pad MIDI convention C1. Melodic and texture roles updated to `("Transpose", 0)` (no shift — C3 default matches their input range).
+- **Device-detection logic never triggered** — wrapper checked `result.get("device_index")` and `result.get("class_name")` from the load response, but the underlying TCP `load_browser_item` command returns only `{loaded, name, device_count}`. Both fields were always `None`/`""`, the `Simpler in device_class` check failed, and the entire role-defaults branch was skipped on every call. Fixed: post-load probe via `get_device_info(track_index, device_index=0)` to read class + name, treating chain-head as the canonical instrument slot Live places fresh instruments at.
+- Same broken parameter name was also patched in `mcp_server/tools/_analyzer_engine/sample.py::_simpler_post_load_hygiene`. Auto-detect-drum-root-note now translates `drum_root → Transpose = 60 − drum_root`, clamped to ±48 semitones.
+- Response now carries `role`, `role_defaults_applied: [{parameter, value|skipped}…]`, and `device_class` so callers can verify the four defaults landed.
+
+### Added — M4L instrument post-load hygiene
+
+- New `_M4L_INSTRUMENT_HYGIENE` dict in `mcp_server/tools/browser.py` maps a device-name substring to a list of `(parameter_name, value)` tames. Runs **unconditionally** (not gated on `role`) post-load, after Simpler role defaults.
+- Initial entry: `Harmonic Drone Generator` (Drone Lab pack) — sets `Latch=0` (off), `Volume=-40` (≈ −20 dB display, vs default ≈ −6 dB), `Density=40` (40 %, vs default 80 %). Without these tames every fresh HDG load slammed an 8-voice drone at full volume the moment any MIDI note hit it. The `Latch` issue compounded by keeping that note ringing forever even after the MIDI source released.
+- Response now carries `m4l_hygiene: {device_name, applied: [{parameter, value|skipped}…]}` when a hygiene entry matches. One match per load (`break` after first hit).
+
+### Tests
+
+- `tests/test_next_steps_2026_04_22.py::test_role_defaults_reasonable_for_drum_role` — assertion updated to `Transpose == 24`; regression guard `"Sample Pitch Coarse" not in drum` prevents the broken param name from ever reappearing.
+- `tests/test_next_steps_2026_04_22.py::test_role_defaults_reasonable_for_melodic_role` — assertion updated to `Transpose == 0` plus the same regression guard.
+- All four role-defaults tests pass against the new `_SIMPLER_ROLE_DEFAULTS` shape.
+
+## v1.24.0 — 2026-05-02
+
+Compose framework rebuild — fast / full / develop modes share an Applier substrate; full mode is a clean-room rewrite around an LLM-creative two-phase brief flow (LLM provides FORM, framework provides VOCABULARY).
+
+### Added — compose framework
+
+- **`mcp_server/composer/framework/applier.py`** — shared pre-flight + post-flight skeleton. `preflight()` loads analyzer, reconnects bridge, retries handshake up to 3× with 200ms gaps (fixes the M4L UDP-bind race that previously left "bridge not connected" failures on the first instrument-load call). `postflight()` sets monitoring=Auto on every newly-created track and calls `back_to_arranger`. Functions are dependency-injected so each mode's apply.py wires its own analyzer/bridge funcs.
+- **`mcp_server/composer/framework/knowledge_pack.py`** — `event_lexicon` (42 structural events across 7 categories: drum_density, harmonic, texture, vocal, rhythm_feel, tension, fx_gesture), `genre_context` loader (parses `livepilot/skills/livepilot-core/references/genre-vocabularies.md`, 15 genres), `artist_context` loader (parses `artist-vocabularies.md`, ~25 producers). `atlas_candidates_per_role` is scaffolded but **left as empty stub** — see v1.25 plan.
+- **`mcp_server/composer/full/apply.py::apply_full_plan_v2`** — full-mode rebuild. Takes an LLM-authored plan with `form` (sections), `tracks` (instruments + variants + arrangement_clips), `events`. Per-section variants prevent the BUG-FULL-MODE-18 flat tile. Native arrangement clip flow via `create_native_arrangement_clip` + `add_arrangement_notes` + `set_clip_loop` produces a single arrangement clip per section instead of 32 tiny tiles (BUG-FULL-MODE-23).
+- **`mcp_server/composer/develop/`** — develop mode (extend an existing 8-bar loop). `seed_introspector.py` classifies tracks by name + content; `brief_builder.py` pulls artist references from the user prompt + research hooks; `apply.py` writes per-track variants without disturbing the seed.
+- **`mcp_server/composer/fast/brief_builder.py`** — fast-mode brief authoring with tier classification (Tier-A curated > Tier-B audible default > Tier-C never). Hunt order: `search_browser(path="sounds")` first to surface curated `.adg` chains, then atlas, then bare instruments only as last resort. Bans bare-melodic Tier-B when curated alternatives exist (§1 violation prevention).
+
+### Fixed — live-test wave
+
+- **BUG-FULL-MODE-14: bridge UDP race** — `apply_full_plan` returned success on `bridge.connect()` but the M4L JS listener takes 100-500ms to bind the UDP socket; next bridge call ("UDP bridge is not connected"). Fixed in `Applier.preflight` with handshake retry loop.
+- **BUG-FULL-MODE-17: monitoring=In on all tracks** — Phase 4 Task 4 set monitoring `state=0` ("In", always passes input) instead of `state=1` ("Auto", default). Live screenshot showed every track armed-red. Fixed: state=1 in `Applier.postflight`.
+- **BUG-FULL-MODE-18: flat tiling instead of per-section variants** — full mode reused one MIDI variant for the whole arrangement. Fixed: per-section `variant_id` in plan + per-section variant resolution in apply.
+- **BUG-FULL-MODE-19: `track_index` vs `index` field** — `apply_full_plan_v2` read `result["track_index"]` from `create_midi_track`, but the Remote Script returns `result["index"]`. Same bug class as the v1.23.x `parameter_name` vs `name_or_index` fix.
+- **BUG-FULL-MODE-20: zombie/leftover tracks from previous sessions** — postflight only deleted default-named tracks (`1-MIDI`, `2-Audio`). Now also deletes tracks with no clips AND no instrument device (true-empty zombies) regardless of name.
+- **BUG-FULL-MODE-21: drum-pitch super-low** — Simpler default root C3=60, drum clips firing at MIDI 36 = 24 semitones below native pitch. Drum-role repair (Volume=0, Snap=Off, Transpose=+24) was already in fast mode; now ported to full mode for parity. (`composer/fast/apply._apply_drum_role_repair` is imported by full mode.)
+- **BUG-FULL-MODE-22: arrangement clip length wrong** — fixed alongside BUG-FULL-MODE-23.
+- **BUG-FULL-MODE-23: 32-tile arrangement** — `create_arrangement_clip` duplicated the session clip every `loop_length` beats, producing a tile-grid arrangement. Switched to `create_native_arrangement_clip` + `add_arrangement_notes` + `set_clip_loop` for native arrangement clip authoring; one clip per section, looped to fill section length.
+
+### Known gaps (deferred to v1.25)
+
+- **`KnowledgePack.atlas_candidates_per_role` is empty stub** — agent still falls through to `search_browser` filename matching instead of consulting the indexed atlas. Ranking + truncation per role needs careful design (1-2 days). Documented as **BUG-FULL-MODE-24** and is the headline feature of v1.25.
+- **Reasoning loop (Scope B)** — full mode currently does best-effort `analyze_mix`/`analyze_loudness`/`analyze_sound_design` calls but doesn't iterate on findings. v1.25 wires an analyze→adjust→re-analyze loop with a budget.
+- **Drum craft + bass craft sophistication passes** — full mode produces correct but generic drum/bass programming. v1.25 lifts these to "poweruser" depth (per-bar variation, sidechain wiring, ghost notes, swing curves, sub/mid/click frequency separation).
+- **`verify_track_audible` MCP tool** — Phase 4 Task 18c, deferred.
+
+### Tool count
+- Net delta: **453 → 459** (+6: compose framework expansion).
+
+### Tests
+- `tests/composer/` — 184 passing across fast / full / develop / framework subdirectories.
+- `tests/test_tools_contract.py` — 459 tools verified.
+
 ## v1.23.6 — 2026-04-30
 
 ### Fixed

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  453 tools. 54 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  462 tools. 55 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -29,6 +29,11 @@
 > Side effects that touch state outside the Live project — Splice downloads, memory/ledger writes,
 > installer actions, atlas scans, filesystem writes — persist beyond undo.
 
+> [!WARNING]
+> LivePilot is actively in development. Tools, behavior, and APIs change frequently between versions.
+> Pin to a specific version for stable work. Known gaps and in-progress features are documented in
+> each release's CHANGELOG entry.
+
 <br>
 
 ---
@@ -54,7 +59,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## Two Ways to Talk to LivePilot
 
-Pick whichever is faster for the idea in your head — both reach the same 453-tool surface.
+Pick whichever is faster for the idea in your head — both reach the same 462-tool surface.
 
 ### Route A — Artist / aesthetic shorthand
 
@@ -107,8 +112,8 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   453 MCP Tools  │                                  │
-│                  │   54 domains     │                                  │
+│                  │   462 MCP Tools  │                                  │
+│                  │   55 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -148,7 +153,7 @@ Most sessions do both. Lead with shorthand to anchor the aesthetic, then refine
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 453 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 462 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -200,7 +205,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-453 tools across 54 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+462 tools across 55 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -425,9 +430,9 @@ LivePilot reads Splice's local SQLite database to search your downloaded samples
 
 <br>
 
-### Composer — 3 tools
+### Composer — three modes (v1.25.0)
 
-Prompt-to-plan auto-composition engine.
+Prompt-to-plan auto-composition engine. Three modes share a common Applier substrate (preflight: bridge handshake retry + analyzer load; postflight: monitoring=Auto on new tracks + back_to_arranger). All modes return executable plans — the agent executes each step, it does not run autonomously.
 
 ```
 "dark minimal techno 128bpm with industrial textures and ghostly vocals"
@@ -451,10 +456,51 @@ Prompt-to-plan auto-composition engine.
 └─────────────────┘
 ```
 
-- 4 genre defaults: house, techno, trap, ambient (unknown genres fall back to a neutral plan)
-- Returns step-by-step plans — the agent executes each tool call in sequence
-- `compose` — plan a multi-layer composition from text prompt
-- `augment_with_samples` — plan sample-based layers for existing session
+#### fast mode — `compose_fast_apply`
+
+Quick loop sketch. Single scene in session view. Intended for roughing out ideas quickly.
+
+- Hunt order: curated `.adg` chains from the browser first, atlas devices second, bare instruments only as last resort
+- Drum-role pitch repair included (Simpler default root vs. MIDI 36 offset)
+- 4 genre defaults: house, techno, trap, ambient (unknown genres fall back to a neutral layer plan)
+- Invoke with: *"Make me a [genre] loop at [tempo] BPM"*
+
+#### full mode — `compose_full_apply`
+
+Full track with song form: intro, verse, hook, breakdown, outro. Uses a two-phase LLM-creative brief flow — the LLM authors the form (sections, track list, per-section variants); the framework supplies the vocabulary (device hunt order, MIDI generation rules, arrangement conventions).
+
+- Per-section MIDI variants prevent repeated tiles across the arrangement
+- Native arrangement clips via `create_native_arrangement_clip` (one clip per section, looped to fill section length)
+- Zombie-track cleanup in postflight (removes tracks with no clips and no instrument device)
+- Drum-role pitch repair ported from fast mode
+- **Known gap (v1.25):** `KnowledgePack.atlas_candidates_per_role` is an empty stub — the agent currently falls through to `search_browser` filename matching instead of consulting the indexed atlas. This is BUG-FULL-MODE-24 and is the headline feature of v1.25.
+- Invoke with: *"Write a full [genre] track at [tempo] BPM"* or *"Build a full arrangement"*
+
+#### develop mode — `develop_apply`
+
+Extends an existing 8-bar loop without disturbing the seed material.
+
+- Introspects the existing session (classifies tracks by name and content)
+- Pulls artist and stylistic references from the user prompt
+- Writes per-track variants and new supporting layers alongside the seed
+- Invoke with: *"Develop this loop"* or *"Extend what's here into a longer idea"*
+
+#### KnowledgePack scaffolding (v1.25.0)
+
+All three modes share a `KnowledgePack` that provides structured creative context at runtime:
+
+- `event_lexicon` — 42 structural events across 7 categories (drum density, harmonic, texture, vocal, rhythm feel, tension, fx gesture)
+- `genre_context` — parses the 15-genre `genre-vocabularies.md` at load time
+- `artist_context` — parses the ~25-producer `artist-vocabularies.md` at load time
+- `atlas_candidates_per_role` — **stubbed in v1.25.0**, will be populated in v1.25
+
+#### Core composer tools
+
+- `compose` — plan a multi-layer composition from text prompt (entry point, mode-agnostic)
+- `compose_fast_apply` — execute fast mode directly
+- `compose_full_apply` — execute full mode directly
+- `develop_apply` — execute develop mode directly
+- `augment_with_samples` — plan sample-based layers for an existing session
 - `get_composition_plan` — dry-run preview (see the plan without credit checks)
 
 <br>
@@ -494,7 +540,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 453 tools →](docs/manual/tool-catalog.md)**
+> **[View all 462 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -721,7 +767,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 453 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 462 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 5264 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

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.23.6";
+var VERSION = "1.25.0";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

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

package/mcp_server/atlas/__init__.py

@@ -57,9 +57,23 @@ class AtlasManager:
             if dev_category:
                 self._by_category.setdefault(dev_category, []).append(dev)
 
-            # Tag index
-            for tag in dev.get("tags", []):
-                self._by_tag.setdefault(tag.lower(), []).append(dev)
+            # Tag index — pull from BOTH legacy "tags" AND enriched
+            # "character_tags". BUG-P (caught 2026-05-01 live demo): the
+            # bundled factory atlas uses character_tags exclusively, so
+            # _by_tag was empty across the board, breaking every tag-based
+            # role picker. Reading both fields makes the index actually
+            # populated for normal user atlases.
+            seen_tags = set()
+            for tag in dev.get("tags", []) or []:
+                tag_lower = str(tag).lower()
+                if tag_lower not in seen_tags:
+                    seen_tags.add(tag_lower)
+                    self._by_tag.setdefault(tag_lower, []).append(dev)
+            for tag in dev.get("character_tags", []) or []:
+                tag_lower = str(tag).lower()
+                if tag_lower not in seen_tags:
+                    seen_tags.add(tag_lower)
+                    self._by_tag.setdefault(tag_lower, []).append(dev)
 
             # Genre index (primary + secondary)
             for genre in dev.get("genres", {}).get("primary", []):

package/mcp_server/atlas/explore_tools.py

@@ -0,0 +1,332 @@
+"""Three v1.25 atlas knowledge-surface tools — agent-callable mid-design.
+
+  atlas_explore     — refined per-role candidate query (wraps AtlasResolver)
+  atlas_audition    — full sidecar dump for one URI (signature_techniques +
+                      producer-curated macro values + related demos + curated ADGs)
+  atlas_substitute  — anti-tag-driven swap (used after analyze_sound_design or
+                      analyze_mix flags an issue with a chosen layer)
+
+Imported and registered via @mcp.tool() decorators in atlas/tools.py.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Anti-tag → character-tag inversion map ──────────────────────────
+#
+# Maps a free-text "anti" descriptor to (excluded_tags, preferred_tags).
+# Used by atlas_substitute. Keys are lowercased; matched as substring of the
+# caller's anti_tag string so "too bright" and "bright" both resolve.
+
+_ANTI_TAG_MAP: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
+    "bright":     (("bright", "high", "shimmer", "airy"), ("warm", "dark", "muted", "vintage")),
+    "harsh":      (("harsh", "aggressive", "distorted"), ("smooth", "soft", "clean")),
+    "aggressive": (("harsh", "aggressive", "punchy"),  ("soft", "warm", "subtle")),
+    "sparse":     (("minimal", "sparse", "thin"),     ("dense", "lush", "thick", "wide")),
+    "thin":       (("thin", "minimal"),               ("thick", "fat", "dense", "wide")),
+    "muddy":      (("muddy", "low_mid"),              ("clear", "open", "defined")),
+    "clean":      (("clean", "pristine"),             ("dirty", "saturated", "vintage", "lo-fi")),
+    "dark":       (("dark", "muted"),                 ("bright", "shimmer", "airy")),
+    "warm":       (("warm", "vintage"),               ("clean", "modern", "digital")),
+    "static":     (("static", "single_layer"),        ("evolving", "modulated", "movement")),
+    "generic":    (("generic", "default"),            ("character", "unique", "signature")),
+}
+
+
+def _resolve_anti_tags(anti_tag: str) -> tuple[list[str], list[str]]:
+    """Return (excluded_tags, preferred_tags) for an anti-tag string.
+
+    Substring-matches the caller's anti_tag string against keys in the map;
+    aggregates all hits. "too bright and harsh" → matches "bright" + "harsh".
+    Empty input returns ([], []) — caller should treat that as no-op.
+    """
+    excluded: list[str] = []
+    preferred: list[str] = []
+    s = (anti_tag or "").lower()
+    for key, (excl, pref) in _ANTI_TAG_MAP.items():
+        if key in s:
+            for t in excl:
+                if t not in excluded:
+                    excluded.append(t)
+            for t in pref:
+                if t not in preferred:
+                    preferred.append(t)
+    return excluded, preferred
+
+
+# ── Tech-index lookup ───────────────────────────────────────────────
+
+
+@lru_cache(maxsize=1)
+def _load_device_techniques_index() -> dict[str, list[dict]]:
+    """Lazy-load the device_techniques_index.json sidecar.
+
+    Returns the inner `devices` dict keyed by device id/slug, or {} on miss.
+    """
+    path = Path(__file__).parent / "device_techniques_index.json"
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data.get("devices") or {}
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.debug("device_techniques_index load failed: %s", exc)
+        return {}
+
+
+def _lookup_techniques(device: dict) -> list[dict]:
+    """Find signature_techniques entries for a device.
+
+    Tries device id first (matches the index key), then name slug.
+    Returns the list of {technique, description, aesthetic, kind} dicts;
+    empty list on miss.
+    """
+    if not device:
+        return []
+    index = _load_device_techniques_index()
+    if not index:
+        return []
+    dev_id = (device.get("id") or "").lower()
+    if dev_id and dev_id in index:
+        return list(index[dev_id])
+    name_slug = (device.get("name") or "").lower().replace(" ", "_")
+    if name_slug and name_slug in index:
+        return list(index[name_slug])
+    return []
+
+
+# ── Tool implementations ────────────────────────────────────────────
+
+
+def explore(
+    *,
+    atlas: Any,
+    role: str,
+    mood: str = "",
+    genre: str = "",
+    artists: Optional[list[str]] = None,
+    n: int = 5,
+    avoid_uris: Optional[list[str]] = None,
+    cohort_constraint: Optional[list[str]] = None,
+) -> dict:
+    """atlas_explore implementation — wraps AtlasResolver.resolve_for_role.
+
+    Returns a structured dict (not raw dataclass) so MCP serialization is clean.
+    Falls through gracefully when atlas is missing — empty `candidates` plus a
+    `reasoning` line that says why.
+    """
+    if atlas is None:
+        return {
+            "candidates": [],
+            "cohort_hint": None,
+            "reasoning": "atlas not loaded — no candidates available",
+        }
+
+    from ..composer.framework.atlas_resolver import AtlasResolver
+
+    resolver = AtlasResolver(atlas=atlas)
+    candidates = resolver.resolve_for_role(
+        role=role,
+        genre=genre,
+        mood=mood,
+        artist_refs=list(artists or []),
+        avoid=[],
+        cohort_constraint=list(cohort_constraint or []) or None,
+        excluded_uris=set(avoid_uris or []) or None,
+        n=n,
+    )
+
+    cohort_hint: Optional[str] = None
+    if cohort_constraint:
+        cohort_hint = cohort_constraint[0]
+    elif candidates:
+        # Most-frequent pack across top candidates
+        packs = [c.in_pack for c in candidates if c.in_pack]
+        if packs:
+            cohort_hint = max(set(packs), key=packs.count)
+
+    reasoning_bits: list[str] = []
+    if cohort_constraint:
+        reasoning_bits.append(f"cohort-constrained to: {', '.join(cohort_constraint)}")
+    if mood:
+        reasoning_bits.append(f"mood: {mood}")
+    if genre:
+        reasoning_bits.append(f"genre: {genre}")
+    if not candidates:
+        reasoning_bits.append(f"no candidates matched role '{role}'")
+
+    return {
+        "candidates": [asdict(c) for c in candidates],
+        "cohort_hint": cohort_hint,
+        "reasoning": "; ".join(reasoning_bits) or f"role '{role}' resolved",
+    }
+
+
+def audition(*, atlas: Any, uri: str) -> dict:
+    """atlas_audition implementation — full sidecar dump for a single URI.
+
+    Joins atlas device record + device_techniques_index entries +
+    preset_resolver curated macros (when pack is known and device user_name
+    matches a sidecar). Best-effort on every join — missing data returns
+    empty fields rather than failing the whole call.
+    """
+    if atlas is None:
+        return {"error": "atlas not loaded", "uri": uri}
+    if not uri:
+        return {"error": "uri is required", "uri": uri}
+
+    device = atlas.lookup(uri) if hasattr(atlas, "lookup") else None
+    if not device:
+        return {
+            "error": "device not found in atlas",
+            "uri": uri,
+            "hint": "URI may be a runtime browser URI (FileId-keyed). Try atlas_explore to find the canonical atlas URI.",
+        }
+
+    techniques = _lookup_techniques(device)
+    pack = device.get("pack")
+    user_name = device.get("name") or ""
+
+    producer_macros: list[dict] = []
+    curated_adg_paths: list[str] = []
+    if pack and user_name:
+        try:
+            from .preset_resolver import resolve_preset_for_device
+            preset_match = resolve_preset_for_device(
+                pack_slug=pack,
+                device_class=device.get("class") or "",
+                device_user_name=user_name,
+            )
+            if preset_match.get("found"):
+                # macro_names is {idx: name}; surface as a list ordered by index
+                names = preset_match.get("macro_names") or {}
+                for idx in sorted(names.keys()):
+                    producer_macros.append({
+                        "index": idx,
+                        "name": names[idx],
+                        "source_preset": preset_match.get("preset_name"),
+                    })
+                if preset_match.get("preset_file"):
+                    curated_adg_paths.append(preset_match["preset_file"])
+        except Exception as exc:
+            logger.debug("audition: preset_resolver failed: %s", exc)
+
+    return {
+        "uri": uri,
+        "name": user_name,
+        "id": device.get("id", ""),
+        "pack": pack,
+        "category": device.get("category", ""),
+        "character_tags": list(device.get("character_tags") or device.get("tags") or []),
+        "signature_techniques": techniques,
+        "producer_macros": producer_macros,
+        "curated_adg_paths": curated_adg_paths,
+        "enriched": bool(device.get("enriched")),
+        # Related demos: defer until v1.25.x reverse-index lands; explicit empty
+        # so callers can rely on the field's presence.
+        "related_demos": [],
+    }
+
+
+def substitute(
+    *,
+    atlas: Any,
+    current_uri: str,
+    anti_tag: str,
+    n: int = 3,
+) -> dict:
+    """atlas_substitute implementation — anti-tag-driven candidate swap.
+
+    Looks up the current device's role/category/tags, derives an excluded-tag
+    set from the anti_tag string, and returns N alternatives that:
+      - share role/category with the current pick
+      - do NOT carry any excluded character_tag
+      - are scored by AtlasResolver with the excluded names on the avoid list
+    """
+    if atlas is None:
+        return {"error": "atlas not loaded"}
+    if not current_uri:
+        return {"error": "current_uri is required"}
+
+    current = atlas.lookup(current_uri) if hasattr(atlas, "lookup") else None
+    if not current:
+        return {
+            "error": "current device not found in atlas",
+            "current_uri": current_uri,
+        }
+
+    excluded_tags, preferred_tags = _resolve_anti_tags(anti_tag)
+    if not excluded_tags:
+        return {
+            "error": f"unrecognized anti_tag '{anti_tag}'",
+            "supported_anti_tags": sorted(_ANTI_TAG_MAP.keys()),
+        }
+
+    # Derive a role tag from the current device's character_tags. Prefer the
+    # most-specific role term (kick/snare/hat/bass/pad/lead/atmos) over generic.
+    current_tags_lower = [
+        str(t).lower() for t in (current.get("character_tags") or current.get("tags") or [])
+    ]
+    role_priority = ("kick", "snare", "hihat", "hi-hat", "hat", "perc",
+                     "bass", "pad", "lead", "atmos", "vocal", "fx", "spectral")
+    role_tag = next((t for t in role_priority if t in current_tags_lower), "")
+    role = role_tag or current.get("category") or "unknown"
+
+    # Collect candidates from the same role tag, filter out any carrying an
+    # excluded character_tag.
+    by_tag = getattr(atlas, "_by_tag", {}) or {}
+    role_candidates: list[dict] = []
+    seen: set[str] = set()
+    for dev in by_tag.get(role_tag.lower(), []) if role_tag else []:
+        uri = dev.get("uri") or ""
+        if not uri or uri in seen or uri == current_uri:
+            continue
+        dev_tags = [str(t).lower() for t in (dev.get("character_tags") or dev.get("tags") or [])]
+        if any(excl in dev_tags for excl in excluded_tags):
+            continue
+        seen.add(uri)
+        role_candidates.append(dev)
+
+    # Score the survivors via AtlasResolver and pick top N
+    from ..composer.framework.atlas_resolver import AtlasResolver
+
+    resolver = AtlasResolver(atlas=atlas)
+    scored: list[tuple[float, dict]] = []
+    for dev in role_candidates:
+        score, reasoning = resolver._score(
+            dev,
+            role=role if role in {
+                "kick", "snare", "hat", "perc", "clap",
+                "bass", "pad", "lead", "atmos", "vocal_chop", "fx", "spectral",
+            } else "",
+            genre="",
+            mood=" ".join(preferred_tags),
+            artist_refs=[],
+            avoid=[],
+        )
+        scored.append((score, AtlasResolver._to_candidate(dev, score, reasoning, source="atlas").__dict__))
+
+    scored.sort(key=lambda x: -x[0])
+    alternatives = [c for _, c in scored[:n]]
+
+    return {
+        "current_uri": current_uri,
+        "current_name": current.get("name", ""),
+        "anti_tag": anti_tag,
+        "excluded_tags": excluded_tags,
+        "preferred_tags": preferred_tags,
+        "alternatives": alternatives,
+        "reasoning": (
+            f"Excluded tags {excluded_tags} from candidates sharing role '{role}'. "
+            f"Boosted candidates whose character_tags overlap preferred tags {preferred_tags}."
+        ),
+    }