livepilot 1.26.0 → 1.26.2

package/livepilot/skills/livepilot-sample-engine/references/sample-critics.md

@@ -0,0 +1,87 @@
+# Sample Critics — Scoring Reference
+
+## Key Fit Critic
+
+Uses circle-of-fifths distance between sample key and song key.
+
+| Distance | Score | Relationship | Action |
+|----------|-------|-------------|--------|
+| 0 fifths | 1.0 | Same key | Load directly |
+| 1 fifth | 0.85 | Relative major/minor, dominant/subdominant | Layer with care |
+| 2 fifths | 0.7 | Closely related | Works for most intents |
+| 3 fifths | 0.55 | Moderately distant | Transpose or use as texture |
+| 4 fifths | 0.4 | Distant | Heavy filtering needed |
+| 5+ fifths | 0.25-0.3 | Chromatic clash | Intentional tension only |
+| Unknown | 0.0 | Key not detected | Verify by ear |
+
+**Weight adjustment:** For "texture" intent, key_fit weight drops 50% (pitch matters less).
+
+## Tempo Fit Critic
+
+Compares sample BPM against session tempo including half/double time relationships.
+
+| Deviation | Score | Action |
+|-----------|-------|--------|
+| <1% | 1.0 | Exact match, no warping |
+| <2% | 0.95 | Near-exact, minimal warp |
+| <5% | 0.8 | Light warp, quality preserved |
+| <10% | 0.6 | Moderate warp, choose mode carefully |
+| <15% | 0.4 | Significant — use Texture mode for ambient |
+| >15% | 0.2 | Extreme — texture use only |
+| Half time | 0.9 | Set warp to half-time |
+| Double time | 0.9 | Set warp to double-time |
+| Unknown | 0.0 | Estimate from onsets or verify |
+
+## Frequency Fit Critic
+
+Requires M4L bridge spectral data. Without it, returns neutral 0.5.
+
+| Situation | Score | Action |
+|-----------|-------|--------|
+| Fills empty frequency gap | 1.0 | Perfect complement |
+| Partial overlap, manageable | 0.7 | Suggest EQ carving |
+| Heavy masking | 0.3 | Aggressive filtering or texture use |
+| Full spectrum into dense mix | 0.1 | Transformation source only |
+
+## Role Fit Critic
+
+Cross-references material_type against existing track names/roles.
+
+| Situation | Score | Action |
+|-----------|-------|--------|
+| Fills missing role | 1.0 | "No percussion texture — this fills the gap" |
+| Complements existing | 0.7 | "Adds variety to palette" |
+| Redundant | 0.3 | "Already 3 synth layers — use as texture" |
+
+## Vibe Fit Critic
+
+Uses TasteGraph when evidence exists (>0 entries). Otherwise neutral 0.5.
+
+Compares brightness, density, complexity of sample against user's taste profile.
+
+## Intent Fit Critic
+
+Compatibility matrix — how well the material serves the stated intent:
+
+| Material \ Intent | rhythm | texture | layer | melody | vocal | atmosphere | transform |
+|-------------------|--------|---------|-------|--------|-------|------------|-----------|
+| vocal | 0.6 | 0.6 | 0.8 | 0.9 | 1.0 | 0.5 | 0.9 |
+| drum_loop | 1.0 | 0.5 | 0.6 | 0.2 | — | 0.3 | 0.9 |
+| instrument_loop | 0.5 | 0.6 | 1.0 | 1.0 | 0.3 | 0.5 | 0.9 |
+| one_shot | 0.9 | 0.4 | 0.3 | 0.5 | — | 0.3 | 0.8 |
+| texture | 0.2 | 1.0 | 0.7 | 0.3 | 0.2 | 1.0 | 0.8 |
+| foley | 0.5 | 0.8 | 0.4 | — | — | 0.9 | 0.8 |
+| fx | 0.3 | 0.7 | 0.3 | — | — | 0.8 | 0.7 |
+
+## Composite Score
+
+Default weights:
+```
+overall = key_fit(0.20) + tempo_fit(0.20) + frequency_fit(0.20)
+        + role_fit(0.15) + vibe_fit(0.10) + intent_fit(0.15)
+```
+
+Weights shift by intent:
+- **texture/atmosphere:** key_fit 0.10, tempo_fit 0.10, frequency_fit 0.25
+- **rhythm:** tempo_fit 0.25, key_fit 0.10
+- **melody:** key_fit 0.30, intent_fit 0.20

package/livepilot/skills/livepilot-sample-engine/references/sample-philosophy.md

@@ -0,0 +1,51 @@
+# Surgeon vs Alchemist — The Dual Philosophy
+
+## When to be a Surgeon
+
+The sample should serve the song without drawing attention to itself.
+
+- **Building a clean layer** — matching key, tempo, frequency
+- **Adding percussion variety** — break layering under existing drums
+- **Key-matched melodic layers** — transpose and blend
+- **Chord stab extraction** — isolate and retrigger cleanly
+- **User says:** "blend", "layer", "match", "fit", "complement"
+
+**Surgeon priorities:** Key accuracy > tempo precision > frequency carving > volume balance
+
+## When to be an Alchemist
+
+The sample is raw material for transformation. The result should surprise.
+
+- **Stuck on a boring section** — inject chaos via destruction
+- **Need organic texture** — reverse, stretch, scatter
+- **Vocal as instrument** — chop syllables into rhythm
+- **One-sample challenge** — constraint breeds creativity
+- **User says:** "flip", "destroy", "mangle", "transform", "surprise me"
+
+**Alchemist priorities:** Novelty > texture > emotion > originality
+
+## Auto Mode Decision Tree
+
+```
+User said "blend/layer/match/fit"?     -> Surgeon
+User said "flip/destroy/mangle/weird"? -> Alchemist
+Wonder Mode (stuck rescue)?            -> Alchemist
+Intent is "texture" or "atmosphere"?   -> Alchemist
+Intent is "layer" or "melody"?         -> Surgeon
+Intent is "rhythm"?                    -> Both available, lean Surgeon for drums, Alchemist for vocals
+Intent is "transform" or "challenge"?  -> Alchemist
+No clear signal?                       -> Present both, let user choose
+```
+
+## The Masters
+
+| Producer | Philosophy | Signature |
+|----------|-----------|-----------|
+| J Dilla | Both | Surgical chop points, alchemical timing/swing |
+| Burial | Alchemist | Ghostly vocal fragments, vinyl crackle as instrument |
+| Amon Tobin | Alchemist | 80+ samples per track, serial destruction |
+| Four Tet | Alchemist | Found-sound countermelody, collage composition |
+| DJ Premier | Surgeon | Perfect stab isolation, rhythmic precision |
+| Madlib | Alchemist | Blind crate digging, cross-genre flipping |
+| RZA | Both | Cinematic soul sampling with dialogue and detuning |
+| Bon Iver | Surgeon | Pitch-shifted vocal stacks, harmonic layering |

package/livepilot/skills/livepilot-sample-engine/references/sample-techniques.md

@@ -0,0 +1,131 @@
+# Sample Technique Catalog — 29 Recipes
+
+## Category 1: Rhythmic Sampling
+
+### slice_and_sequence (Surgeon)
+Classic MPC workflow: load loop, slice on transients, sequence with MIDI.
+**Material:** drum_loop, full_mix | **Steps:** load -> slice -> get slices -> create clip -> add notes
+
+### vocal_chop_rhythm (Alchemist)
+Chop vocal into syllable-length slices, trigger as staccato rhythm. Burial-inspired.
+**Material:** vocal | **Steps:** load -> slice by region -> MIDI staccato -> Auto Filter
+
+### micro_chop (Alchemist)
+1/32 slices, varied velocity, slight timing offsets. J Dilla micro-timing.
+**Material:** any loop | **Steps:** load -> manual slice -> dense 1/32 MIDI
+
+### stab_isolation (Surgeon)
+Isolate single chord stab, crop, retrigger rhythmically. DJ Premier style.
+**Material:** full_mix, instrument_loop | **Steps:** load -> classic mode -> crop -> MIDI
+
+### euclidean_slice_trigger (Alchemist)
+Map Simpler slices to Euclidean rhythm for polyrhythmic texture.
+**Material:** drum_loop, vocal, instrument_loop | **Steps:** load -> slice -> Euclidean pattern
+
+## Category 2: Textural Transformation
+
+### extreme_stretch (Alchemist)
+Paulstretch-style: Texture warp at 10-50x, reverb wash. Stars of the Lid territory.
+**Material:** any | **Steps:** load -> warp 64 beats -> Reverb 60-80% wet
+
+### drum_to_pad (Alchemist)
+Reverse + extreme stretch + reverb = drum hit becomes ambient pad.
+**Material:** drum_loop, one_shot | **Steps:** load -> reverse -> stretch -> Reverb
+
+### reverse_layer (Alchemist)
+Reversed sample as pre-echo swell or ghostly texture.
+**Material:** vocal, instrument_loop, one_shot | **Steps:** load -> reverse -> Delay
+
+### granular_scatter (Alchemist)
+Grain Delay as granular engine — scatter grains for cloud textures. Amon Tobin.
+**Material:** vocal, instrument_loop, texture | **Steps:** load -> Grain Delay -> Reverb
+
+### spectral_freeze (Alchemist)
+Crop to tiny region (50-200ms), extreme stretch = spectral freeze drone.
+**Material:** vocal, instrument_loop, full_mix | **Steps:** load -> crop -> stretch 64 beats
+
+### tail_harvest (Alchemist)
+Resample only the reverb/delay tail as independent texture.
+**Material:** any | **Steps:** load -> Reverb 100% wet -> level for subtle layer
+
+## Category 3: Melodic/Harmonic
+
+### key_matched_layer (Surgeon)
+Transpose to song key, EQ carve, blend behind existing elements.
+**Material:** instrument_loop | **Steps:** load -> transpose -> EQ -> volume -6 to -10dB
+
+### vocal_harmony_stack (Surgeon)
+Pitch-shifted vocal layers — Bon Iver Prismizer approach.
+**Material:** vocal | **Steps:** load -> duplicate -> transpose +3/+5/+7 -> blend
+
+### counterpoint_from_chops (Alchemist)
+Create countermelody from rearranged melodic fragments. Four Tet.
+**Material:** instrument_loop, vocal, full_mix | **Steps:** load -> slice by beat -> program melody
+
+### chord_stab_extraction (Surgeon)
+Isolate chord from full mix, crop, retrigger. Classic house/disco.
+**Material:** full_mix, instrument_loop | **Steps:** load -> slice -> crop -> rhythmic pattern
+
+## Category 4: Drum Enhancement
+
+### break_layering (Surgeon)
+Layer drum break under programmed drums. High-pass to avoid kick clash.
+**Material:** drum_loop | **Steps:** load -> warp 16 beats -> EQ HP 200-400Hz -> volume -10 to -15dB
+
+### ghost_note_texture (Alchemist)
+Heavy filter + low volume = barely audible ghost-note layer.
+**Material:** drum_loop | **Steps:** load -> Auto Filter BP 1-4kHz -> volume -18 to -24dB
+
+### transient_replacement (Surgeon)
+Layer one-shot transient over existing drums for punch.
+**Material:** one_shot | **Steps:** load -> classic mode -> MIDI on kick/snare hits
+
+### shuffle_extract (Alchemist)
+Extract groove timing from loop via slice positions, apply to MIDI.
+**Material:** drum_loop | **Steps:** load -> slice by transient -> read positions
+
+## Category 5: Vocal Processing
+
+### syllable_instrument (Alchemist)
+Each syllable = playable note. Vocal becomes a melodic instrument.
+**Material:** vocal | **Steps:** load -> slice by region -> program melody across slices
+
+### formant_shift_character (Alchemist)
+Shift formants for alien/robotic character. Transpose +/-12st.
+**Material:** vocal | **Steps:** load -> transpose -> Corpus for resonant body
+
+### vocal_freeze_drone (Alchemist)
+Sustain one vowel as ambient pad. Crop tiny region, extreme stretch.
+**Material:** vocal | **Steps:** load -> crop 100-300ms -> stretch 64 beats -> Chorus -> Reverb
+
+### phone_recording_texture (Alchemist)
+Burial signature: pitch down, lo-pass, ghost-level volume.
+**Material:** vocal, foley | **Steps:** load -> pitch -5 to -12 -> LP 800Hz -> volume -20 to -30dB
+
+## Category 6: Resampling Chains
+
+### serial_resample (Alchemist)
+Multi-pass destruction: Saturator + Grain Delay + Reverb, freeze, flatten, repeat.
+**Material:** any | **Steps:** load -> Saturator -> Grain Delay -> Reverb -> freeze -> flatten
+
+### parallel_resample (Alchemist)
+Duplicate, process one copy destructively, blend wet/dry.
+**Material:** any | **Steps:** load -> duplicate -> process duplicate -> blend -6 to -12dB
+
+### freeze_flatten_rechop (Alchemist)
+Freeze processed material, flatten to audio, re-slice the result. Recursive.
+**Material:** any | **Steps:** freeze -> flatten -> re-load into Simpler -> slice again
+
+## Category 7: Creative Constraints
+
+### one_sample_challenge (Alchemist)
+Build entire beat from one sample: kick, snare, hat, bass, pad all from slices.
+**Material:** any | **Steps:** load -> slice -> program full beat across slice pitches
+
+### found_sound_only (Alchemist)
+Non-musical field recordings as sole source material. Musique concrete.
+**Material:** foley | **Steps:** load -> slice -> EQ to isolate musical frequencies
+
+### reverse_engineering (Both)
+Recreate a reference track's texture by sampling and transforming similar elements.
+**Material:** full_mix | **Steps:** load -> slice by beat -> analyze structure

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

@@ -0,0 +1,247 @@
+---
+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.
+
+## Analyzer Character Is the Main Signal
+
+For broad quality requests, this skill is the primary route. "More punch", "warmer", "darker", "brighter", "less flat", "more alive", "more texture", and "more character" should become source/device/parameter decisions before they become volume moves.
+
+When the analyzer is available, read character, not just level:
+
+- `get_master_spectrum` for the 9-band contour
+- `get_spectral_shape` for centroid, flatness, crest, rolloff, and brightness/noise shape
+- `get_mel_spectrum` when EQ or source choice needs perceptual detail
+- `get_onsets` for transient/envelope decisions
+- `get_novelty` for movement/staticness decisions
+- `get_momentary_loudness` only for safety/headroom/loudness context
+
+Translate those measurements into musical moves:
+
+- Bright/harsh character → filter contour, softer source, de-harshing, saturation tone; do not merely lower volume.
+- Dark/dull character → oscillator/filter opening, excitation, air-band source, tasteful saturation; do not merely raise volume.
+- Static/low novelty → modulation, envelope drift, LFO, generative device, granular/vector source.
+- Weak punch → envelope/transient shaping, source layering, attack/release work; volume push is last.
+- Flat/noisy spectrum → source substitution, subtractive filtering, simpler spectral role.
+- Weak weight → instrument/register/source decision before master or track gain.
+
+## 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` plus the relevant character streams above — 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` plus the same character streams used before — 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 only when the user asked for a deep refinement pass. In normal mode, stop after one meaningful character-improving move and summarize what changed plus the next optional direction. Avoid long loops of small parameter nudges.
+
+## 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