livepilot 1.26.0 → 1.26.2

package/livepilot/skills/livepilot-creative-director/references/the-four-move-rule.md

@@ -0,0 +1,192 @@
+# The Four-Move Rule
+
+A creative pass should touch four dimensions: **structural**,
+**rhythmic**, **timbral**, **spatial**. The three plans generated in
+Phase 3 distribute across these dimensions — they do not duplicate one.
+
+This is the complement to the move-family diversity rule. Family
+diversity enforces "different machinery"; four-move coverage enforces
+"different musical consequence."
+
+## The four dimensions
+
+Dimensions are orthogonal to `move.family`. A plan has ONE dominant
+dimension and ONE dominant family. Multiple dimensions can map to the
+same family (e.g. an `arrangement`-family plan can be structural OR
+rhythmic depending on what it does). See
+`move-family-diversity-rule.md` §"Family vs. dimension" for the split.
+
+| Dimension | What it is | Dominant family typically | Tag with | Also uses |
+|---|---|---|---|---|
+| **Structural** | Section-level form — adds, removes, reshapes sections or clip density | `arrangement` or `transition` | `dimension_hint` optional (family implies it) | `livepilot-arrangement`, `livepilot-composition-engine`, scene/arrangement tools |
+| **Rhythmic** | Timing, groove, swing, motif patterns, polyrhythm, per-hit velocity/probability | `arrangement` (clip pattern edits) OR `sound_design` (per-hit feel) | `dimension_hint: "rhythmic"` REQUIRED — there is no rhythmic family in the registry | `livepilot-notes`, `assign_clip_groove`, `modify_notes`, motif tools, Euclidean rhythm |
+| **Timbral** | Source character — instrument choice, patch, saturation, texture | `sound_design` or `device_creation` | `dimension_hint` optional | `livepilot-sound-design-engine`, `livepilot-devices`, atlas lookups |
+| **Spatial** | Space and stereo field — reverb, delay, pan, width, depth | `mix` (space-oriented moves) | `dimension_hint: "spatial"` recommended when family=mix (distinguishes from level/EQ mix plans) | `set_track_send`, `set_track_pan`, return-track routing, `add_space` |
+
+Note that `performance` family is orthogonal — it rarely applies on
+first-pass creative work; it's for live contexts.
+
+**The fudge is not a fudge:** earlier drafts of this rule described
+rhythmic plans as "fudged" because they borrow the `arrangement` or
+`sound_design` family. That framing was wrong. The family axis and the
+dimension axis are orthogonal by design — a rhythmic plan has an
+honest family tag AND an honest dimension tag, via `dimension_hint`.
+State both explicitly in the turn. No apology needed.
+
+## The rule
+
+For a creative pass of 3 plans, coverage should span at least 3 of the
+4 dimensions. Plans may overlap only after all four dimensions have
+been considered.
+
+```
+dimensions_touched = {dominant_dimension(p) for p in plans}
+len(dimensions_touched) >= 3      # default
+len(dimensions_touched) >= 4      # ideal
+```
+
+Falling below 3 distinct dimensions is the same failure mode as
+falling below 3 distinct families — the agent is clustering.
+
+## How to identify a plan's dominant dimension
+
+Use the move-family → dimension map, then confirm against the plan's
+audible consequence:
+
+1. If dominant move's family is `arrangement` or `transition` → **structural**
+2. If dominant move's family is `sound_design` or `device_creation` → **timbral**
+3. If dominant move's family is `mix` AND the move is space-oriented
+   (`add_space`, `widen_stereo`, reverb-related) → **spatial**
+4. If dominant move's family is `mix` AND the move is level / EQ /
+   dynamics → still **spatial** for this taxonomy (mix's audible
+   consequence is positional)
+5. If the plan is primarily MIDI-editing (notes, grooves, motif
+   transforms) → **rhythmic**, regardless of family tagging
+
+Ambiguous? Tag the seed explicitly in `seed.dimension_hint`.
+
+## Interaction with `locked_dimensions`
+
+If the brief's `locked_dimensions` includes a dimension, that dimension
+is off-limits. The remaining three must be covered across the three
+plans.
+
+| Locked | Must cover |
+|---|---|
+| (nothing) | any 3 of 4 (all 4 ideal) |
+| `structural` | rhythmic + timbral + spatial |
+| `timbral` | structural + rhythmic + spatial |
+| `rhythmic` | structural + timbral + spatial |
+| `spatial` | structural + rhythmic + timbral |
+| two locks | the remaining two — ship 2 plans, not 3 |
+
+Two locks on a 4-dimension space means the problem is narrow. Two
+plans is honest; faking a third by sneaking into a locked dimension
+violates both this rule AND the user's explicit constraint.
+
+## Example 1 — "Make it feel like Basic Channel if Dilla touched the swing"
+
+No locked dimensions. Ideal coverage = 4/4 but we only have 3 plans.
+Each plan tagged `family / dimension`:
+
+- Plan A (`arrangement` / **structural**): Add an 8-bar breakdown at bar 48 where kick drops out and only ghost hats + dub-chord tail remain.
+- Plan B (`arrangement` / **rhythmic**, dimension_hint="rhythmic"): Micro-shift hi-hat notes by −8 to +12 ticks, add ghost notes at 62% probability, assign a "Dilla-esque" groove.
+- Plan C (`sound_design` / **timbral**): Load Drift for the chord, route to a send with Ping Pong Delay + Auto Filter on the return, print 25% wet.
+
+Family-diversity note: Plans A and B are BOTH `arrangement` family —
+this is a rule violation unless corrected. Swap Plan B to tag
+`sound_design` family instead (per-hit velocity + micro-timing counts
+as feel-shaping sound_design per the family→dimension map), OR swap
+Plan A to `transition` family (create_breakdown semantic move). Either
+fix keeps all three dimensions covered. The point: rhythmic as a
+dimension does not exempt the plan from the three-distinct-families
+constraint — the director must still land family diversity, just via
+the appropriate tag.
+
+Corrected version:
+- Plan A (`transition` / **structural**): `create_breakdown` semantic move at bar 48.
+- Plan B (`arrangement` / **rhythmic**, dimension_hint="rhythmic"): groove + probability edits to clip.
+- Plan C (`sound_design` / **timbral**): Drift + send chain.
+
+Spatial dimension is not directly touched by a plan — but Plan C's
+send-chain IS spatial in consequence. Coverage is honest: 3 explicit
+dimensions, one implicit.
+
+## Example 2 — "Make the drums more interesting, don't touch the arrangement"
+
+Locked: `structural`. Must cover rhythmic + timbral + spatial.
+
+- Plan A (`arrangement` / **rhythmic**, dimension_hint="rhythmic"): Add probability 70-90% to the hat and clap clip; apply a 58% swing groove from `list_grooves`. Family is `arrangement` because the target is clip content; dimension is rhythmic because the audible consequence is feel. The `structural` lock concerns SECTION-level arrangement, not clip-level edits — locked_dimensions semantics resolve at the dimension level, not the family level.
+- Plan B (`sound_design` / **timbral**): Layer a parallel drum bus with Saturator + Drum Bus; per-hit velocity mod on snare.
+- Plan C (`mix` / **spatial**, dimension_hint="spatial"): Send hats and ghost snares to a short plate reverb at -14 dB; narrow the kick to mono under 80 Hz.
+
+All three dimensions hit. Section arrangement untouched. Three families
+distinct. Honest.
+
+## Example 3 — Narrow request: "the pad is too static"
+
+Ambiguous whether "static" means timbre or space. The agent should
+compile a brief that acknowledges this and generate plans across both:
+
+- Plan A (`sound_design` / **timbral**): Enable wavetable position LFO + macro
+  modulation on Drift.
+- Plan B (`mix` / **spatial**, dimension_hint="spatial"): Send the pad to a long convolution reverb on a
+  return with Auto Filter LFO.
+- Plan C (`arrangement` / **rhythmic**, dimension_hint="rhythmic"): Automate a slow 8-bar amplitude envelope so
+  the pad breathes with the section.
+
+This is an explicit case where the structural dimension is not
+relevant (it's one sound, not an arrangement decision). Three of four
+is the natural coverage. Shipping a structural plan would be
+fabricated.
+
+## When to drop below three dimensions
+
+Drop to 2 of 4 (or 1 of 4) ONLY in these situations. In all cases:
+ship fewer plans honestly. Do not fake coverage.
+
+1. **Two or more dimensions locked.** User explicitly locked two
+   dimensions → at most 2 dimensions remain → at most 2 honest plans.
+
+2. **Genuinely narrow task AND concept packet confirms no other
+   dimension is in scope.** Example: "make this one reverb return
+   less muddy" is spatial-only.
+
+3. **Low novelty_budget + narrow-idiom concept packet.** When the
+   user's request is reference-adjacent (`novelty_budget` ≤ 0.50) AND
+   the concept packet explicitly de-prioritizes certain dimensions,
+   dropping those dimensions is idiomatic, not fabricated. Examples:
+
+   - **Dub-techno packets** (Basic Channel / Rhythm & Sound) explicitly
+     de-emphasize the rhythmic dimension ("percussion implied not
+     stated"). Three plans may legitimately cluster in
+     timbral + spatial + (optional) structural. Rhythmic absent is
+     idiomatic honesty.
+   - **Ambient packets** (Gas / Basinski / Stars of the Lid) explicitly
+     de-emphasize rhythmic AND structural (static with very slow
+     evolution). Three plans clustering in timbral + spatial is
+     idiomatic.
+   - **Beat-focused packets** (Dilla / Premier) explicitly
+     de-emphasize the spatial dimension (dry intimacy is the aesthetic).
+     Three plans clustering in rhythmic + timbral + structural is
+     idiomatic.
+
+   When this rule fires, document the decision in the turn: *"The
+   packet's aesthetic de-prioritizes <dimension>; dropping it here is
+   idiomatic rather than coverage failure."* This prevents future
+   agents from mistaking the under-coverage for a skill bug.
+
+**Never-drop rule:** even when dropping dimensions, the family
+diversity rule still applies to whatever plans you DO ship. Two plans
+must have different families; three plans must have three different
+families. Narrow doesn't excuse fabricated distinctness.
+
+## Why this rule works
+
+"Layered and complex output" — what the user asks for when they say
+"more interesting" — is almost always a DISTRIBUTION problem, not a
+depth problem. A pass that touches rhythm + timbre + space feels
+three-dimensional even if each individual change is small. A pass that
+stacks three `mix` moves feels thin even when the changes are large.
+
+Force distribution. Depth emerges.

package/livepilot/skills/livepilot-devices/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: livepilot-devices
+description: This skill should be used when the user asks to "load a device", "add an effect", "find a plugin", "device chain", "rack", "preset", "sound design setup", "load instrument", "find a synth", or wants to browse, load, and configure devices in Ableton Live.
+---
+
+# Device Loading and Configuration
+
+Load instruments, effects, and plugins into Ableton Live tracks. Every device operation follows one discipline: search first, verify after.
+
+## Primary Workflow — Atlas-Driven
+
+The device atlas contains 1,305 devices with sonic descriptions, recipes, and recommendations. Always start here:
+
+1. **Discover:** `atlas_search(query)` — find devices by name, sound character, or genre
+2. **Learn:** `atlas_device_info(device_id)` — full parameters, recipes, gotchas, pairings
+3. **Suggest:** `atlas_suggest(intent, genre)` — "I need a warm pad" → ranked device+recipe combos
+4. **Chain:** `atlas_chain_suggest(role, genre)` — full device chain for a track role (instrument + effects)
+5. **Load:** Use the URI from atlas results → `load_browser_item(uri)` or `find_and_load_device(name)`
+6. **Recipe:** Apply starter recipe params → `batch_set_parameters(params)` from the atlas entry
+7. **Verify:** `get_device_info(track_index, device_index)` — check health flags
+
+If the atlas doesn't have a device (newly installed plugin, user sample), fall back to the browser workflow below.
+
+## Browser Workflow — The Fallback Path
+
+Use the browser workflow when the atlas doesn't have what you need:
+
+1. **Search:** `search_browser(path, name_filter)` — returns a list of matching items with exact URIs
+2. **Inspect:** Read the results. Confirm the item name, type, and path match what you need
+3. **Load:** `load_browser_item(uri)` — pass the exact URI string from search results
+
+Common search paths:
+- `path="Instruments"` — synths, samplers, instrument racks
+- `path="Drums"` — drum racks, drum kits, percussion
+- `path="Audio Effects"` — reverb, delay, compressor, EQ, saturator
+- `path="MIDI Effects"` — arpeggiator, chord, scale, random
+- `path="Sounds"` — preset sounds organized by category
+- `path="Samples"` — audio samples, one-shots, loops
+
+Combine path with `name_filter` to narrow results. Example: `search_browser(path="Drums", name_filter="808 Kit")`.
+
+NEVER invent device or preset names. A hallucinated name like "echomorph-hpf" or "Drift Pad Wonk" will crash the load. Always search first, then use the exact URI from results.
+
+For the full URI grammar reference (the three forms — FileId, bare-name, path-style — failure modes, and discovery recipe), see `references/load_browser_item-uri-grammar.md`.
+
+## find_and_load_device — The Shortcut
+
+Use `find_and_load_device(name)` ONLY for these simple built-in effects:
+- "Reverb"
+- "Delay"
+- "Compressor"
+- "EQ Eight"
+- "Saturator"
+- "Utility"
+
+For everything else — instruments, racks, presets, AU/VST plugins — use the browser workflow. The shortcut matches greedily and can load a sample file instead of a synth when names overlap (e.g., "Drift" matches "Synth Bass Drift Pad Wonk Bass.wav" before the Drift synthesizer).
+
+## Plugin Health Verification
+
+After loading any device, verify it actually works:
+
+1. Call `get_device_info(track_index, device_index)` on the newly loaded device
+2. Check `parameter_count` — if the device is an AU/VST plugin (`class_name` contains "PluginDevice") and `parameter_count` is 1 or less, the plugin is dead. The shell loaded but the DSP engine crashed.
+3. Check `health_flags` for `opaque_or_failed_plugin` (dead or untweakable AU/VST) or `sample_dependent` (needs source audio)
+4. Check `plugin_host_status` and `mcp_sound_design_ready`
+5. If `mcp_sound_design_ready` is `false`: delete the device with `delete_device`, replace it with a native Ableton alternative, and report the failure to the user
+
+Dead plugin recovery pattern:
+```
+get_device_info → parameter_count <= 1 on PluginDevice?
+  → delete_device(track_index, device_index)
+  → search_browser for native alternative
+  → load_browser_item with replacement URI
+  → report failure and substitution to user
+```
+
+## Rack Introspection
+
+Use `walk_device_tree(track_index)` to see the full nested structure of racks on a track — Instrument Racks, Audio Effect Racks, and Drum Racks with all their chains and sub-devices.
+
+Use `get_rack_chains(track_index, device_index)` to inspect individual rack chain contents. For Drum Racks, this reveals which pads have samples loaded and which chains exist. An empty Drum Rack (zero chains) produces silence.
+
+Set chain volumes with `set_chain_volume(track_index, device_index, chain_index, volume)` to balance rack layers.
+
+## Drum Rack Rule
+
+NEVER load a bare "Drum Rack" — it is an empty container with zero chains and produces silence. Always load a kit preset through the browser:
+
+```
+search_browser(path="Drums", name_filter="Kit")
+```
+
+Pick a real kit from results: "909 Core Kit", "808 Core Kit", "Boom Bap Kit", "Lo-Fi Kit", etc. These come pre-loaded with samples on their pads.
+
+After loading any Drum Rack preset, verify with `get_rack_chains` that chains exist and have named pads like "Bass Drum", "Snare", "Hi-Hat".
+
+## Custom Drum Rack Construction (build a kit from one-shots)
+
+When the user asks for a custom kit ("build me a minimal-techno kit", "make a Dilla-style boom-bap kit from these samples"), use `add_drum_rack_pad` — NOT repeated `load_browser_item` calls.
+
+**Why this matters (BUG-2026-04-22 #1):** Calling `load_browser_item` repeatedly on a track that contains a Drum Rack does NOT add new pads. The first call creates a chain at note 36; every subsequent call REPLACES the existing chain instead of appending to the next pad. After 7 sequential drops you end up with exactly 1 chain — only the last sample. This is a Live API limitation, not something to work around with retry loops.
+
+**The canonical workflow:**
+
+```
+# 1. Make sure a Drum Rack exists on the track. Either:
+#    - Load a preset kit and clear it, or
+#    - insert_device(track_index=N, device_name="Drum Rack") for an empty rack
+# 2. For each sample:
+add_drum_rack_pad(
+    track_index=N,
+    pad_note=36,                  # 36=Kick, 38=Snare, 42=Closed HH, 46=Open HH
+    file_path="/abs/path/to/sample.wav",
+)
+```
+
+`add_drum_rack_pad` does the full atomic build per pad: insert_rack_chain → set_drum_chain_note → insert empty Simpler into the chain → load sample via the native Live 12.4 replace_sample API with nested addressing. Returns `{ok, chain_index, pad_note, nested_device_index}` so you can verify and chain further calls.
+
+Requires Live 12.4+ (uses native nested-sample loading). On older versions returns an error directing the caller to the legacy separate-tracks workaround.
+
+For nested-Simpler operations on existing pads (e.g., adjust loop points after the kit is built), `replace_simpler_sample` and `load_sample_to_simpler` accept `chain_index` and `nested_device_index` for explicit deep addressing.
+
+## Sample-Dependent Devices
+
+These devices load "successfully" with many parameters but produce zero audio without source material. Since MCP tools cannot load samples into third-party plugin UIs, NEVER use these as standalone instruments:
+
+- **Granular synths:** iDensity, Tardigrain, Koala Sampler, Burns Audio Granular
+- **Bare samplers:** Simpler (empty), Sampler (empty) — always load a preset, never the empty shell
+- **Sample players:** AudioLayer, sEGments
+
+Use self-contained synthesizers instead — these produce sound immediately from MIDI input alone:
+- **Wavetable** — versatile wavetable synthesis
+- **Operator** — FM synthesis, 4 operators
+- **Drift** — analog-modeled, warm and organic
+- **Analog** — subtractive analog modeling
+- **Meld** — MPE-ready, two engines
+- **Collision** — physical modeling, mallet/resonator
+- **Tension** — physical modeling, string/exciter
+
+If granular textures are needed: use Wavetable with aggressive wavetable position modulation, Operator with FM feedback and short envelopes, or load a Simpler/Sampler **preset** (not the bare instrument) from the Sounds browser.
+
+## Simpler Operations
+
+For Simpler devices that already have samples loaded:
+
+- `load_sample_to_simpler(track_index, device_index, file_path)` — load audio into Simpler
+- `replace_simpler_sample(track_index, device_index, file_path)` — swap the current sample. Only works on Simplers that already have a sample loaded.
+- `crop_simpler(track_index, device_index)` — trim sample to current start/end points
+- `reverse_simpler(track_index, device_index)` — reverse the loaded sample
+- `get_simpler_slices(track_index, device_index)` — retrieve auto-detected slice points (Slice mode)
+- `set_simpler_playback_mode(track_index, device_index, playback_mode)` — switch modes: 0=Classic, 1=One-Shot, 2=Slice. Optional: `slice_by` (0=Transient, 1=Beat, 2=Region, 3=Manual), `sensitivity` (0.0-1.0, Transient only)
+- `warp_simpler(track_index, device_index, beats)` — warp sample to fit N beats
+
+### Slice Workflow
+
+For slice-based production, use `plan_slice_workflow`:
+1. `plan_slice_workflow(file_path=..., intent="rhythm")` — generates a complete workflow with Simpler setup, slice mapping, and MIDI notes
+2. Intents: `rhythm`, `hook`, `texture`, `percussion`, `melodic`
+3. The tool returns a step-by-step plan — execute each tool call in sequence
+
+Manual slice workflow: load sample → `set_simpler_playback_mode(playback_mode=2)` → `get_simpler_slices` → program MIDI notes targeting slice indices (C3 = slice 0, C#3 = slice 1, etc.)
+
+### New Device Operations (12.3+)
+
+- `insert_device(track_index, device_name)` — insert native device by name (10x faster than browser, 12.3+)
+- `insert_rack_chain(track_index, device_index)` — add chain to Instrument/Audio/Drum Rack
+- `set_drum_chain_note(track_index, device_index, chain_index, note)` — assign MIDI note to Drum Rack chain
+- `add_drum_rack_pad(track_index, pad_note, file_path)` — atomic single-pad build (chain + note + Simpler + sample). 12.4+. Use this for custom kit construction; see the "Custom Drum Rack Construction" section above.
+- `move_device(track_index, device_index, new_index)` — reorder devices on a track
+
+### Plugin Deep Control
+
+- `get_plugin_parameters(track_index, device_index)` — all AU/VST plugin parameters
+- `map_plugin_parameter(track_index, device_index, parameter_index)` — map for automation
+- `get_plugin_presets(track_index, device_index)` — list plugin presets
+
+## Parameter Name Quirks (BUG-2026-04-22 #10)
+
+Ableton's parameter names are inconsistent across devices. When `set_device_parameter` or `batch_set_parameters` errors with "Parameter 'X' not found," the response already lists the first 20 available names — read it and pick the right one. Common surprises:
+
+| You'd expect | Actual name | Where |
+|---|---|---|
+| `Width` | `Stereo Width` | Utility |
+| `Cutoff` | `Filter Freq` / `Frequency` | Various filters — check per-device |
+| `Resonance` | `Filter Resonance` / `Q` | Same |
+| `Drive` | `Drive` (Saturator) but `Drive Amount` (some racks) | Saturator vs racks |
+| `Mix` | `Dry/Wet` | Almost every native effect |
+| `Volume` | `Volume` (mixer) but `Sample Volume` / `Out Volume` | On certain devices |
+
+When in doubt, call `get_device_parameters(track_index, device_index)` first — it returns the exact `name` of every parameter and the `name` field is what `set_device_parameter` accepts.
+
+## Effect Chain Best Practices
+
+After loading any effect, verify its key parameters are not at pass-through defaults:
+- **Reverb:** `Dry/Wet` should be > 0 (typically 20-40% for subtle, 60-100% for creative)
+- **Delay:** `Dry/Wet` > 0, `Feedback` set appropriately
+- **Compressor:** `Threshold` below signal level, `Ratio` > 1:1
+- **EQ Eight:** At least one band with non-zero gain
+- **Saturator:** `Drive` > 0 dB
+- **Utility:** `Gain` at target value, `Width` as needed
+
+Use `get_device_parameters` to read current values, then `set_device_parameter` or `batch_set_parameters` to configure. Use `toggle_device` to bypass/enable devices for A/B comparison.
+
+## Device Presets
+
+- `get_device_presets(track_index, device_index)` — list available presets for the loaded device
+- `get_plugin_parameters(track_index, device_index)` — see all AU/VST plugin parameters
+- `get_plugin_presets(track_index, device_index)` — list presets for AU/VST plugins
+- `map_plugin_parameter(track_index, device_index, parameter_index)` — map a plugin parameter for automation
+
+## Device Atlas Reference
+
+Consult `references/device-atlas/` in the livepilot-core skill for the full corpus of 280+ instruments, 139 drum kits, and 350+ impulse responses. The atlas contains real browser URIs, preset names, and sonic descriptions. Use it as your lookup table before loading any device — never guess a name that is not in the atlas or in browser search results.

package/livepilot/skills/livepilot-devices/references/load_browser_item-uri-grammar.md

@@ -0,0 +1,82 @@
+# `load_browser_item` URI Grammar
+
+> Reference for the URI strings accepted by `load_browser_item(track_index, uri, ...)`.
+> Resolves the BUG-2026-04-22 #14 friction (URI format was undocumented and required reverse-engineering).
+
+## TL;DR
+
+URIs are produced by `search_browser` / `get_browser_items` / `get_browser_tree` — never invent them by hand. The format is `query:<Top-Level-Folder>#<Item-Identifier>`. Three known forms in the wild:
+
+| Form | Example | When you'll see it |
+|---|---|---|
+| **File ID** | `query:Drums#FileId_29738` | Browser items that resolve to a file in Live's installed packs (samples, presets, kits). The numeric FileId is stable across sessions on the same machine. |
+| **Bare name** | `query:Synths#Operator` | Native devices and effects whose name is unique within the folder. Most built-in instruments. |
+| **Path-like** | `query:UserLibrary#Samples:Splice:Filename.wav` | Items inside the User Library or other deep folder paths. The fragment uses `:` as a path separator within the URI's hash. |
+
+## Discovery recipe
+
+You almost never need to construct a URI from scratch. Always:
+
+1. **Search:** `search_browser(path="Drums", name_filter="909 Core")` — returns each match with its exact `uri` field.
+2. **Or browse:** `get_browser_tree()` for the top-level structure; `get_browser_items(path="Drums")` to drill down. Items include their URI.
+3. **Use the URI verbatim:** pass the exact string from the result to `load_browser_item(uri=...)`. Do not modify, normalize, or reconstruct it.
+
+## Why three forms exist
+
+Live's browser is backed by multiple resolvers under the hood:
+
+- **Pack content** is keyed by an internal FileId from a per-machine SQLite index — fast lookup, opaque names.
+- **Native devices** are addressed by their stable English class name within their folder.
+- **User Library / Samples** items use a path-style fragment because they're filesystem-rooted, not pack-indexed.
+
+The URI you receive from search/browse already has the correct form for that item — there is no "preferred" or "canonical" form, only "the one Live's browser knows."
+
+## What goes wrong if you guess
+
+- **Guessed FileId**: silently fails or loads the wrong sample.
+- **Guessed bare name** for a non-unique item: loads whatever Live's matcher hits first (e.g., `query:Synths#Drift` may match a `Drift Pad Wonk Bass.wav` sample before the `Drift` synth — see the `find_and_load_device` warning in `livepilot-devices` SKILL).
+- **Path with wrong separator** (using `/` instead of `:`): URI parses but resolves to nothing.
+- **Stale FileId** copied from a different machine: stale FileIds aren't portable.
+
+## Top-level folders (current Live 12.4)
+
+| Folder | Typical content |
+|---|---|
+| `Sounds` | Genre-organized presets across all native synths |
+| `Drums` | Drum Racks, drum kits, percussion one-shots |
+| `Instruments` | Synths, samplers, instrument racks (top-level entries) |
+| `Audio Effects` | Reverb, delay, compressor, EQ, saturator, etc. |
+| `MIDI Effects` | Arpeggiator, chord, scale, random, MPE Tools |
+| `Max for Live` | Native + installed M4L devices |
+| `Plug-ins` | Installed AU/VST plugins |
+| `Clips` | Sample loops + MIDI clips that ship with packs |
+| `Samples` | The big one — ~22,000 individual audio files |
+| `Packs` | Pack-level entries that resolve to internal preset/sample lists |
+| `User Library` | Your personal saved devices, racks, samples, sets |
+| `Current Project` | Items in the current Live set's project folder |
+
+## Behaviour after load (BUG-2026-04-22 #16)
+
+`load_browser_item` is context-dependent — same URI, different result:
+
+- **Empty track:** creates a Simpler with the sample loaded (instruments load directly).
+- **Track with an instrument already:** drops the new device after the existing one (Live's "load to selected" behavior).
+- **Track with a Drum Rack:** the FIRST `load_browser_item` of a sample creates a chain on note 36; **every subsequent call REPLACES that chain** instead of appending to the next pad. To build a kit pad-by-pad, use `add_drum_rack_pad(track_index, pad_note, file_path)` instead — it does the chain + note + Simpler + sample sequence atomically per pad.
+
+See the "Custom Drum Rack Construction" section in `livepilot-devices` SKILL for the canonical kit-build flow.
+
+## Role-aware defaults (BUG-2026-04-22 #17 + #18)
+
+`load_browser_item(role=...)` applies post-load Simpler defaults so the loaded sample plays correctly without per-bug-memory hand-tweaking:
+
+| Role | Snap | Volume | Trigger Mode | Root note |
+|---|---|---|---|---|
+| `"drum"` | 0 | 0 dB | 0 (Trigger / one-shot) | C1 (36) |
+| `"melodic"` | 1 | 0 dB | 1 (Gate / held) | C3 (60) |
+| `"texture"` | 0 | -6 dB | 1 (Gate) | C3 (60) |
+
+Omit `role` to keep Live's raw defaults (Volume=-12 dB, Snap=1, root=C3). Useful when loading a non-Simpler device or when you want the legacy behavior.
+
+## Trigger Mode polarity (BUG-2026-04-22 #9)
+
+Reverse from intuition: `Trigger Mode value=0` is **Trigger** (one-shot), `value=1` is **Gate** (held). The `role="drum"` default sets it to 0, the others to 1.