livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-sound-design-engine/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: livepilot-sound-design-engine
+description: This skill should be used when the user asks to "design a sound", "analyze a patch", "fix a static sound", "add modulation", "check my timbre", "improve a synth patch", or wants critic-driven sound design feedback and iterative patch refinement.
+---
+
+# Sound Design Engine — Critic-Driven Patch Refinement
+
+The sound design engine analyzes synth patches, identifies timbral weaknesses, and iteratively refines them through a measured critic loop. Every change is evaluated against the before state.
+
+## Atlas-first reflex (v1.23.x+, MANDATORY before any creative move)
+
+Before producing ANY creative response, query the user's atlas overlays. The corpus contains 337 entries across 3 namespaces, plus 3,917 parameter-level JSON sidecars — far richer than anything inferable from training data alone.
+
+**Query order:**
+
+1. **`extension_atlas_search(namespace="packs", query=<intent>)`** — pack identity, signature workflows, hidden gems, anti-patterns, notable presets with macro deep-data, demo projects
+2. **`extension_atlas_search(namespace="packs", query=<intent>, entity_type="cross_pack_workflow")`** — multi-pack signature recipes (15 entries: dub-techno spectral drone bed, BoC decayed pad, Mica Levi orchestral dread, etc.)
+3. **`extension_atlas_search(namespace="m4l-devices", query=<sonic descriptor>)`** — M4L instrument/effect/midi-effect device catalog (155 entries)
+4. **`atlas_search(...)`** — bundled atlas (Core Library, fallback)
+
+**Multi-grain traversal:**
+
+When an aesthetic-level query lands a pack-level result, AUTO-DRILL: pack → its `notable_presets` → those preset macro states → load via `load_browser_item`. Don't stop at "I found a relevant pack" — drill to the actual preset/parameter level the user can immediately use.
+
+```python
+# Example — agent received "design a BoC pad — sublime, decayed, harmonic warmth"
+hit = extension_atlas_search(namespace="packs", query="BoC sublime decayed pad harmonic warmth")
+# → boc_decayed_pad cross-pack-workflow + inspired_by_nature pack
+
+workflow = extension_atlas_get("packs", "boc_decayed_pad")
+# → reveals signal flow + which notable_presets to start from
+
+drone_lab = extension_atlas_get("packs", "drone_lab")
+# → notable_presets reveals Razor Wire Drone with macros Filter Control=108, Movement=53...
+
+# Now propose the patch with concrete preset names + macro starting values, not vague descriptions
+```
+
+**When the user mentions a producer or pack by name:**
+
+- "BoC sublime pad" → atlas hit: `boc_decayed_pad` cross-pack-workflow + `inspired_by_nature` pack
+- "Henke spectral chain" → atlas hit: `pitchloop89` + `granulator_iii` + 2 Henke cross-pack workflows
+- "Mica Levi orchestral dread" → atlas hit: `mica_levi_orchestral_dread` workflow + the orchestral suite packs
+- "Drone Lab" → atlas hit: `drone_lab` pack + 4 Drone Lab demo_project entries
+
+The atlas knows the user's installed library at parameter depth. **Producer-anchor queries land specific moves, not vague descriptions.**
+
+**Anti-pattern surfacing:**
+
+Every pack entry has an `anti_patterns` body field listing "don't reach for this when X." Surface the relevant anti-pattern when proposing a move so the user knows the move's domain. (E.g. "Drone Lab is sustain-only — don't use for percussive content.")
+
+**For deliberately rule-breaking creative requests** ("eclectic", "ignore the limits", "weird combo", "mix incompatible aesthetics"): enter **Eclectic Mode** inside this sound-design loop. Anti-patterns become prompt tension rather than guardrails: keep hard safety and protected-user constraints, then pair one normally-avoided source or processor with one identity-preserving anchor. Do not route to a private or missing skill.
+
+## The Sound Design Critic Loop
+
+### Step 1 — Build Patch Model
+
+Call `get_patch_model(track_index)` to build a PatchModel for the target track. The PatchModel maps every device on the track into typed blocks (oscillator, filter, envelope, lfo, saturation, spatial, effect) and classifies each as `controllable` or `opaque`.
+
+Read the response carefully:
+- `blocks`: ordered list of processing blocks with types and parameter names
+- `controllable_params`: parameters you can modify via `set_device_parameter`
+- `opaque_blocks`: third-party plugins where parameters may not map cleanly
+- `modulation_sources`: detected LFOs, envelopes, and macro mappings
+- `signal_flow`: how blocks connect (serial, parallel, or rack chains)
+
+See `references/patch-model.md` for the full PatchModel structure and native device block map.
+
+### Step 2 — Analyze
+
+Call `analyze_sound_design(track_index)` to run all sound design critics against the patch. The response contains an `issues` array with `critic`, `severity`, `block`, and `evidence`.
+
+Five critics run during analysis. See `references/sound-design-critics.md` for thresholds:
+
+- **static_timbre** — sound does not evolve over time, no movement
+- **no_modulation_sources** — no LFOs, envelopes, or automation detected
+- **modulation_flatness** — modulation exists but ranges are too narrow to hear
+- **missing_filter** — raw oscillator output with no spectral shaping
+- **spectral_imbalance** — too much energy in one frequency region, or gaps
+
+### Step 3 — Plan
+
+Pick the highest-severity issue. Call `plan_sound_design_move(track_index)` with the issue. The planner returns a single intervention:
+
+- `move_type`: one of the move vocabulary entries
+- `target_device`: device index on the track
+- `target_parameter`: parameter name or index
+- `target_value`: the new value
+- `rationale`: why this move addresses the issue
+
+Move vocabulary:
+- **modulation_injection** — add or increase LFO/envelope depth on a parameter
+- **filter_shaping** — adjust cutoff, resonance, or filter type
+- **parameter_automation** — create clip automation for time-varying timbral change
+- **oscillator_tuning** — adjust pitch, detune, waveform, or unison settings
+
+### Step 4 — Capture Before
+
+1. Call `get_device_parameters(track_index, device_index)` — save current parameter state
+2. Call `get_master_spectrum` — save spectral snapshot (if analyzer available)
+
+### Step 5 — Execute
+
+Apply the planned move using the appropriate tool:
+
+- `set_device_parameter` for direct parameter changes (filter cutoff, LFO rate, oscillator shape)
+- `toggle_device` for enabling/disabling processing blocks
+- `batch_set_parameters` when the move requires coordinated changes (e.g., LFO depth + rate together)
+- `set_clip_automation` for parameter automation moves
+- `find_and_load_device` when the fix requires adding a new device (e.g., adding an Auto Filter)
+
+Execute one move at a time. Verify before continuing.
+
+### Step 6 — Capture After
+
+Repeat the same measurements:
+
+1. Call `get_device_parameters(track_index, device_index)` — confirm the change took effect
+2. Call `get_master_spectrum` — save post-change spectral snapshot
+
+### Step 7 — Evaluate
+
+Call `evaluate_move(goal_vector, before_snapshot, after_snapshot)` where `goal_vector` is the compiled goal from Step 1 and snapshots contain `{spectrum: {...}, rms: float, peak: float}`. Read:
+
+- `keep_change` (bool): whether the change improved the sound
+- `score` (0.0-1.0): quality improvement magnitude
+- `timbral_delta`: what changed spectrally
+- `explanation`: human-readable summary
+
+### Step 8 — Keep or Undo
+
+If `keep_change` is `false`, call `undo()`. Explain what was tried and why it did not improve the sound.
+
+If `keep_change` is `true`, report the improvement. If score > 0.7, consider calling `memory_learn(name="...", type="device_chain", qualities={"summary": "..."}, payload={...})` to save the technique.
+
+### Step 9 — Repeat
+
+Return to Step 2. Re-analyze after each kept change. The critic list updates as issues are resolved. Continue until the user is satisfied or no high-severity issues remain.
+
+## Working with Opaque Plugins
+
+Third-party AU/VST plugins may report as `opaque` in the PatchModel:
+
+1. Check `get_plugin_parameters(track_index, device_index)` — some plugins expose parameters through the host
+2. If `parameter_count <= 1`, the plugin is dead or unresponsive. Call `delete_device` and suggest a native alternative
+3. If parameters are available but unnamed (Parameter 1, Parameter 2...), try `map_plugin_parameter` to identify them by ear
+4. Report opaque status to the user — sound design critics cannot fully analyze what they cannot inspect
+
+## Quick Sound Design Checks
+
+- **"What's wrong with this sound?"** — Call `get_sound_design_issues(track_index)` for a diagnostic without executing fixes
+- **"Show me the patch"** — Call `get_patch_model(track_index)` then `walk_device_tree(track_index)` for full device chain visibility
+- **"What can I automate?"** — Read the `controllable_params` list from the PatchModel response
+
+## Native Device Strengths
+
+When adding processing blocks, prefer native Ableton devices for controllability:
+
+- **Wavetable** — complex oscillator section with built-in modulation matrix
+- **Operator** — FM synthesis with per-operator envelopes and LFO
+- **Analog** — subtractive with two filters and two LFOs
+- **Auto Filter** — standalone filter with envelope follower and LFO
+- **Corpus** — resonant body modeling for physical character
+- **Erosion** — high-frequency noise and distortion artifacts
+- **Saturator** — waveshaping with multiple curve types
+
+Always `search_browser` before loading — never guess device names.
+
+## M4L Instruments in the Library — When the Standard Synths Are the Wrong Aesthetic
+
+Wavetable / Operator / Analog cover most subtractive and FM work, but several installed packs ship M4L instruments that produce sounds those three architecturally cannot. Reach for them when the standard list is the wrong starting point:
+
+- **Granulator III** (Live Suite + Max for Live) — granular synthesis as a first-class instrument. Loop / Cloud / Classic modes, MPE per-note grain control, built-in audio capture. Use when the source needs to *be* a sample but evolve as a sustained voice.
+- **Harmonic Drone Generator** (Drone Lab pack) — 8-voice M4L drone synth by Expert Math. Just intonation, Pythagorean, Pelog, equal temperament. Use when the patch is a sustained tonal bed and standard equal-tempered subtractive sounds wrong (microtonal beating is the point).
+- **Bouncy Notes** (Inspired by Nature, Dillon Bastan) — gravity-based MIDI sequencer. Drop a ball, it bounces on a piano roll producing asymmetric never-repeating note cascades. Use as a generative source instead of writing notes by hand.
+- **Tree Tone** (Inspired by Nature) — fractal-plant-growth resonator. Each branch is a tunable resonator (frequency / decay / amplitude). Use when you want resonance/body that evolves under itself, instead of static Corpus.
+- **Vector FM / Vector Grain / Vector Map** (Inspired by Nature) — particle-physics modulation systems. Vector Map can route one particle to multiple parameters at once — useful when the patch needs *coupled* modulation that LFOs cannot produce.
+- **PitchLoop89** (Live Suite) — Henke pitch-shift delay (Publison DHM 89 emulation). Use as the spatial/pitched-echo block on any sustained voice when standard delay + Auto Pan is too rigid.
+
+These do not replace the modulation_injection / filter_shaping / parameter_automation move vocabulary. They change what "the source" can be — which is upstream of the critic loop.
+
+## Deep Sound Design Reference
+
+Consult `references/sound-design-deep.md` for advanced techniques when working on creative requests. Key principles:
+
+### Making Sounds Breathe
+Every static sound can become alive with modulation below conscious perception:
+- **Filter breathing:** LFO at 0.1-0.5 Hz on filter cutoff, 5-15% depth
+- **Oscillator drift:** ±1-3 cent detune with very slow LFO (0.05-0.2 Hz)
+- **Amplitude micro-variation:** Perlin/brownian noise on volume, ±1-3 dB
+- **Rule:** If the listener can hear the modulation, it's too much. The best modulation is felt, not heard.
+
+### Space as Composition
+Reverb and delay are not decorations — in dub/minimal they ARE the composition:
+- **Dub chord:** Short stab → long delay (70-80% feedback) + filter on the delay return
+- **Delay throws:** Momentary send spikes (0→70% for half a beat) — the echo IS the event
+- **Sidechain reverb:** Dry drums trigger sidechain compression on reverb returns — the room pulses
+- **Feedback modulation:** Delay feedback at 75-85% + modulate delay time ±5-10% for warped echoes
+
+### Creative Sidechain (Beyond Pump)
+Sidechain compression is a modulation source, not just a mix tool:
+- **Sidechain filter:** Envelope follower from kick modulates pad filter cutoff — pad brightens between kicks
+- **Ghost sidechain:** Muted kick as sidechain source for textures — phantom groove on non-rhythmic elements
+- **Multiband sidechain:** Only duck sub frequencies from pad — shimmer stays, sub clears for kick
+
+### Effects as Instruments
+- **Self-oscillating filter:** Push resonance until it rings, play notes by changing cutoff
+- **Feedback loops:** Route output back to input through effects + compressor to control
+- **Convolution as synthesis:** Load non-IR files (speech, drum break) into convolution reverb — imprints spectral character
+- **Granular reverb:** Very short reverb (0.1-0.3s) high diffusion on percussion — smears transient into tonal cloud
+
+### The Frequency Dance
+At any moment, each frequency band should have one primary element. When one opens up, another pulls back:
+- Chord filter opens into highs → pull hi-hat back
+- Bass drops → kick shortens
+- Reverb tail fills → dry elements duck
+This is mix engineering as composition.
+
+### When to Apply These
+- User says "make it breathe" or "it sounds static" → micro-modulation
+- User says "more space" or "deeper" → dub techniques (delay throws, reverb composition)
+- User says "more groove" or "make it pump" → creative sidechain
+- User says "more texture" or "more complex" → textural layering
+- User says "surprise me" or "WTF moment" → brief textural disruption (2-8 beats max)
+- User says "warmer" or "more analog" → oscillator drift + subtle saturation + filter breathing

package/livepilot/skills/livepilot-sound-design-engine/references/patch-model.md

@@ -0,0 +1,119 @@
+# Patch Model Reference
+
+The PatchModel is returned by `get_patch_model(track_index)` and represents the complete signal processing structure of a track's device chain.
+
+## PatchModel Structure
+
+```json
+{
+  "track_index": 0,
+  "track_name": "Lead Synth",
+  "blocks": [
+    {
+      "device_index": 0,
+      "device_name": "Wavetable",
+      "block_type": "oscillator",
+      "controllable": true,
+      "parameters": ["Osc 1 Pos", "Osc 1 Gain", "Sub Gain", ...],
+      "sub_blocks": [
+        { "block_type": "filter", "parameters": ["Filter Freq", "Filter Res", ...] },
+        { "block_type": "lfo", "parameters": ["LFO 1 Rate", "LFO 1 Amount", ...] },
+        { "block_type": "envelope", "parameters": ["Amp Attack", "Amp Decay", ...] }
+      ]
+    },
+    {
+      "device_index": 1,
+      "device_name": "Auto Filter",
+      "block_type": "filter",
+      "controllable": true,
+      "parameters": ["Frequency", "Resonance", "Env. Modulation", ...]
+    }
+  ],
+  "controllable_params": [...],
+  "opaque_blocks": [],
+  "modulation_sources": [
+    { "type": "lfo", "device_index": 0, "rate": "0.5 Hz", "targets": ["Filter Freq"] }
+  ],
+  "signal_flow": "serial"
+}
+```
+
+## Block Types
+
+### oscillator
+Sound source generators. Found in synth instruments (Wavetable, Operator, Analog, Drift, Simpler, Sampler).
+
+Key parameters: waveform/position, pitch/tune/detune, unison voices/spread, sub oscillator level, FM amount/ratio.
+
+### filter
+Spectral shaping. Found as sub-blocks inside instruments or as standalone devices (Auto Filter, EQ Eight).
+
+Key parameters: cutoff frequency, resonance, filter type (LP/HP/BP/Notch), slope (12/24 dB), envelope modulation amount, drive.
+
+### envelope
+Time-shaping contour generators. Usually ADSR controlling amplitude or filter cutoff.
+
+Key parameters: attack, decay, sustain, release. Some instruments offer additional envelopes with arbitrary targets.
+
+### lfo
+Low-frequency oscillators for cyclic modulation.
+
+Key parameters: rate (Hz or synced), waveform (sine, triangle, square, saw, random), amount/depth, target parameter, phase, offset.
+
+### saturation
+Waveshaping, distortion, and harmonic generation.
+
+Devices: Saturator, Overdrive, Pedal, Amp, Erosion, Dynamic Tube. Key parameters: drive, tone, type/curve, dry/wet.
+
+### spatial
+Stereo field and space processing.
+
+Devices: Reverb, Delay, Chorus, Phaser, Flanger, Echo, Hybrid Reverb. Key parameters: decay/time, pre-delay, size, damping, dry/wet, feedback.
+
+### effect
+Catch-all for utility and dynamics processing.
+
+Devices: Compressor, Glue Compressor, Limiter, Gate, Utility, Tuner, Spectrum. Key parameters vary by device.
+
+## Controllable vs Opaque
+
+- **Controllable**: native Ableton devices and well-behaved plugins where `get_device_parameters` returns named, ranged parameters. All LivePilot set/get parameter tools work reliably.
+- **Opaque**: third-party AU/VST plugins where parameter inspection fails or returns generic names (Parameter 1, Parameter 2). The sound design engine can detect the block exists but cannot reason about individual parameters.
+
+Check `parameter_count` on opaque blocks. If <= 1, the plugin failed to load — delete it and replace with a native alternative.
+
+## Native Device Block Map
+
+Quick reference for which block types each native device provides:
+
+| Device | Primary Block | Sub-blocks |
+|--------|--------------|------------|
+| Wavetable | oscillator | filter, lfo, envelope |
+| Operator | oscillator | filter, lfo, envelope |
+| Analog | oscillator | filter, lfo, envelope |
+| Drift | oscillator | filter, lfo, envelope |
+| Simpler | oscillator | filter, lfo, envelope |
+| Sampler | oscillator | filter, lfo, envelope |
+| Auto Filter | filter | lfo, envelope |
+| EQ Eight | filter | — |
+| Compressor | effect | envelope (sidechain) |
+| Glue Compressor | effect | — |
+| Saturator | saturation | — |
+| Overdrive | saturation | — |
+| Pedal | saturation | — |
+| Reverb | spatial | — |
+| Delay | spatial | filter |
+| Echo | spatial | filter, lfo |
+| Chorus-Ensemble | spatial | — |
+| Phaser-Flanger | spatial | lfo |
+| Hybrid Reverb | spatial | — |
+| Corpus | spatial | — |
+| Utility | effect | — |
+
+## Rack Detection
+
+If a track contains an Instrument Rack or Audio Effect Rack, the PatchModel reports:
+
+- `signal_flow`: "parallel" (rack chains run in parallel)
+- Each chain appears as a nested block list
+- Use `get_rack_chains(track_index, device_index)` for per-chain detail

package/livepilot/skills/livepilot-sound-design-engine/references/sound-design-critics.md

@@ -0,0 +1,118 @@
+# Sound Design Critics Reference
+
+Each critic runs during `analyze_sound_design(track_index)` and produces an issue object with `critic`, `severity` (0.0-1.0), `block`, and `evidence`.
+
+## static_timbre
+
+Detects sounds that do not evolve over time. A static timbre lacks movement, making it sound flat and lifeless in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No detectable spectral change over a 4-bar window. Crest factor of spectral flux < 0.5 dB
+- severity >= 0.4: Minimal change (spectral flux < 1.5 dB). Some subtle movement present
+- severity < 0.4: Adequate movement detected, likely intentional sustain character
+
+**Evidence format:**
+```json
+{
+  "spectral_flux_db": 0.3,
+  "analysis_window_bars": 4,
+  "brightest_moment_db": -8.2,
+  "dullest_moment_db": -8.5
+}
+```
+
+**Typical fix:** modulation_injection — add LFO to filter cutoff (rate 0.1-2 Hz, depth 20-40%).
+
+## no_modulation_sources
+
+Detects patches with zero modulation sources: no LFOs, no envelopes beyond amp/filter ADSR, no automation, no macro mappings.
+
+**Thresholds:**
+- severity >= 0.7: Zero modulation sources on a melodic/pad/lead instrument
+- severity >= 0.4: No modulation on a bass or rhythmic element (some genres keep bass static intentionally)
+- severity < 0.4: Drum hits and one-shots (modulation not expected)
+
+**Evidence format:**
+```json
+{
+  "lfo_count": 0,
+  "envelope_count": 1,
+  "automation_lanes": 0,
+  "macro_mappings": 0,
+  "instrument_type": "pad"
+}
+```
+
+**Typical fix:** modulation_injection — enable device LFO if available, or add Auto Filter with LFO. For pads, map LFO to filter cutoff and/or oscillator pitch (subtle detune).
+
+## modulation_flatness
+
+Detects modulation sources that exist but operate with such narrow ranges they produce no audible effect.
+
+**Thresholds:**
+- severity >= 0.7: Modulation depth < 5% of parameter range on all targets
+- severity >= 0.4: Modulation depth 5-15% — present but barely perceptible
+- severity < 0.4: Depth > 15%, audible modulation
+
+**Evidence format:**
+```json
+{
+  "modulation_source": "LFO 1",
+  "target_parameter": "Filter Cutoff",
+  "depth_percent": 3.2,
+  "parameter_range": [20, 20000],
+  "effective_range": [850, 920]
+}
+```
+
+**Typical fix:** Increase modulation depth to 20-40% for filter targets, 5-15% for pitch targets, 10-30% for amplitude targets.
+
+## missing_filter
+
+Detects raw oscillator output with no filter or spectral shaping in the signal path. Unfiltered signals often sound harsh and sit poorly in a mix.
+
+**Thresholds:**
+- severity >= 0.7: No filter device in the signal chain, and the source is a harmonically rich waveform (saw, square, FM)
+- severity >= 0.4: Filter present but fully open (cutoff at maximum, no resonance)
+- severity < 0.4: Filter active and shaping the spectrum
+
+**Evidence format:**
+```json
+{
+  "has_filter": false,
+  "source_waveform": "sawtooth",
+  "harmonic_content": "rich",
+  "device_chain": ["Wavetable"]
+}
+```
+
+**Typical fix:** filter_shaping — add Auto Filter (low-pass, cutoff around 2-5 kHz, resonance 20-40%) or enable the instrument's built-in filter.
+
+## spectral_imbalance
+
+Detects patches with too much energy concentrated in one frequency region, or significant spectral gaps.
+
+**Thresholds:**
+- severity >= 0.7: Single band > 12 dB above the mean, or a gap > 12 dB below
+- severity >= 0.4: Imbalance 6-12 dB in one or more regions
+- severity < 0.4: Balanced spectrum appropriate for the instrument role
+
+**Evidence format:**
+```json
+{
+  "peak_band": "high_mid",
+  "peak_deviation_db": 14.2,
+  "gap_band": "low_mid",
+  "gap_deviation_db": -8.5,
+  "band_levels_db": {
+    "sub": -22.0,
+    "low": -14.5,
+    "low_mid": -20.1,
+    "mid": -11.6,
+    "high_mid": -2.4,
+    "high": -8.9
+  }
+}
+```
+
+**Typical fix:** filter_shaping to tame the peak (EQ cut or filter sweep), or oscillator_tuning to fill the gap (add sub oscillator, adjust waveform).

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

@@ -0,0 +1,143 @@
+---
+name: livepilot-wonder
+description: >
+  This skill should be used when the user asks to "surprise me",
+  "make it magical", "I'm stuck", "give me options", "take it somewhere",
+  or when stuckness confidence is high. Provides the Wonder Mode
+  stuck-rescue workflow with honest variant labeling and preview-first UX.
+---
+
+# Wonder Mode — Stuck-Rescue Workflow
+
+Wonder Mode is a **preview-first stuck-rescue workflow**. It diagnoses
+why a session is stuck, generates genuinely distinct executable options,
+and lets the user preview, compare, and commit.
+
+## Atlas-first reflex (v1.23.x+, MANDATORY before any creative move)
+
+Before producing ANY creative response, query the user's atlas overlays. The corpus contains 337 entries across 3 namespaces, plus 3,917 parameter-level JSON sidecars — far richer than anything inferable from training data alone.
+
+**Query order:**
+
+1. **`extension_atlas_search(namespace="packs", query=<intent>)`** — pack identity, signature workflows, hidden gems, anti-patterns, notable presets with macro deep-data, demo projects
+2. **`extension_atlas_search(namespace="packs", query=<intent>, entity_type="cross_pack_workflow")`** — multi-pack signature recipes (15 entries: dub-techno spectral drone bed, BoC decayed pad, Mica Levi orchestral dread, etc.)
+3. **`extension_atlas_search(namespace="m4l-devices", query=<sonic descriptor>)`** — M4L instrument/effect/midi-effect device catalog (155 entries)
+4. **`atlas_search(...)`** — bundled atlas (Core Library, fallback)
+
+**Multi-grain traversal:**
+
+When an aesthetic-level query lands a pack-level result, AUTO-DRILL: pack → its `notable_presets` → those preset macro states → load via `load_browser_item`. Don't stop at "I found a relevant pack" — drill to the actual preset/parameter level the user can immediately use.
+
+```python
+# Example — agent received "take it somewhere unexpected, surprise me"
+hit = extension_atlas_search(namespace="packs", query="take it somewhere unexpected hidden gem")
+# → cross-pack workflows + packs with hidden_gems body fields surface
+
+workflow = extension_atlas_get("packs", "dub_techno_spectral_drone_bed")
+# → reveals signal_flow: HDG → PitchLoop89 cross-feedback → Convolution Reverb
+
+drone_lab = extension_atlas_get("packs", "drone_lab")
+# → notable_presets reveals Razor Wire Drone with macros Filter Control=108, Movement=53...
+
+# Now propose variants with concrete preset names + macro values, not vague descriptions
+```
+
+**When the user mentions a producer or pack by name:**
+
+- "BoC sublime pad" → atlas hit: `boc_decayed_pad` cross-pack-workflow + `inspired_by_nature` pack
+- "Henke spectral chain" → atlas hit: `pitchloop89` + `granulator_iii` + 2 Henke cross-pack workflows
+- "Mica Levi orchestral dread" → atlas hit: `mica_levi_orchestral_dread` workflow + the orchestral suite packs
+- "Drone Lab" → atlas hit: `drone_lab` pack + 4 Drone Lab demo_project entries
+
+The atlas knows the user's installed library at parameter depth. **Producer-anchor queries land specific moves, not vague descriptions.**
+
+**Anti-pattern surfacing:**
+
+Every pack entry has an `anti_patterns` body field listing "don't reach for this when X." Surface the relevant anti-pattern when proposing a move so the user knows the move's domain. (E.g. "Drone Lab is sustain-only — don't use for percussive content.")
+
+**For deliberately rule-breaking creative requests** ("eclectic", "ignore the limits", "weird combo", "mix incompatible aesthetics"): enter **Eclectic Mode** inside Wonder. Anti-patterns become prompt tension rather than guardrails: keep hard safety and protected-user constraints, then generate variants that intentionally combine one normally-avoided source with one identity-preserving source. Do not route to a private or missing skill.
+
+## When to Trigger
+
+- User says "I'm stuck", "surprise me", "make it magical", "give me options"
+- `detect_stuckness` confidence > 0.5
+- 3+ consecutive undos in action ledger
+- Multiple plausible next moves with no clear winner
+- **`livepilot-creative-director` delegates divergence to Wonder** (first-pass creative intent, not only rescue)
+
+## Two contexts — Stuck-Rescue vs Creative-Director Divergence
+
+Wonder Mode now serves two callers:
+
+1. **Stuck-rescue** (original): a specific session is stuck and needs
+   rescue. The "fewer than 3 variants is correct" honesty rule applies —
+   you are not obligated to fabricate options that don't exist.
+
+2. **Creative-director first-pass**: the director is running standard
+   divergence before any commit. Here, actively WIDEN across `move.family`
+   before accepting fewer than 3 variants. Only fall back after honestly
+   re-reading concept packets, anti-preferences, and recent memory. The
+   context comes in via the `wonder_session_id` metadata or the caller's
+   explicit framing.
+
+## When NOT to Trigger
+
+- Exact operational requests ("set track 3 volume to -6dB")
+- Narrow deterministic edits ("quantize this clip")
+- Performance-safe-only context (unless explicitly requested)
+
+## The Workflow
+
+1. `enter_wonder_mode` — get diagnosis + 1-3 variants
+2. Explain the diagnosis in **musical language**, not tool language
+3. Present variants honestly:
+   - Executable variants: can be previewed and committed
+   - Analytical variants (`analytical_only: true`): directional ideas only
+4. `create_preview_set` with `wonder_session_id` for executable variants
+5. `render_preview_variant` for each executable variant
+6. `compare_preview_variants` — present recommendation with reasons
+7. User chooses:
+   - `commit_preview_variant` — applies the variant, records outcome
+   - `discard_wonder_session` — rejects all, keeps creative thread open
+
+## Honesty Rules
+
+- **Never describe an analytical variant as previewable**
+- **Never fabricate distinctness** by relabeling the same move — and
+  specifically, two variants with the same `move.family` are not distinct
+- **Fewer than 3 variants is correct** when fewer distinct moves exist —
+  but on creative-director first-pass, widen across `move.family` values
+  FIRST before accepting that conclusion (see `livepilot-creative-director`
+  references/move-family-diversity-rule.md)
+- 1 executable + 2 analytical is an honest, useful result
+- The `variant_count_actual` field tells you how many are real
+
+## Presenting Results
+
+For each variant, explain:
+- What it changes (in musical terms)
+- What it preserves (sacred elements)
+- Why it matters for this specific session
+- Whether it's executable or analytical-only
+
+For the recommendation, explain:
+- Why this one over the others
+- What risk it introduces
+- What sacred elements it preserves
+
+## Creative Intelligence (consult before generating variants)
+
+Wonder Mode should produce musically interesting results, not just technically correct ones. Before generating or applying any variant, read the shared device-knowledge references (they live in the `livepilot-core` skill, not in this one):
+
+1. `livepilot-core/references/device-knowledge/automation-as-music.md` — automation shapes and macro gestures
+2. `livepilot-core/references/device-knowledge/creative-thinking.md` — emotional-to-technical mapping
+3. `livepilot-core/references/device-knowledge/chains-genre.md` — if the session has a genre identity
+
+When reviewing Wonder variants, aim for musical depth:
+- **Filter arcs** — evolving filter across sections adds movement
+- **Space arcs** — reverb/delay sends breathing with density
+- **Micro-modulation** — subtle LFOs on sustained sounds
+- **Macro gestures** — coordinated multi-parameter moves at transitions
+
+Note: these are agent-level guidelines, not enforced by the Wonder engine.
+The engine generates variants from semantic moves; the agent adds musical polish.