livepilot 1.9.24 → 1.10.1

package/livepilot/skills/livepilot-core/references/sound-design-deep.md

@@ -0,0 +1,140 @@
+# Deep Sound Design — Techniques from the Masters
+
+This is a reference for creative sound design thinking, not a recipe book. These are principles and techniques drawn from deep minimal, dub techno, and experimental electronic production. Use them as inspiration — adapt, combine, subvert.
+
+## Philosophy: Sound Design IS Composition
+
+In minimal and experimental electronic music, sound design and composition are the same thing. A filter sweep IS the melody. A reverb tail IS the harmony. Modulation IS the arrangement. The producer's job is not to write notes — it's to sculpt evolving textures.
+
+**Villalobos principle:** A single sound source, properly modulated, IS a complete piece. The trick is making one thing do the work of ten.
+
+**Basic Channel principle:** Space is an instrument. Delay and reverb are not effects — they are the composition itself.
+
+**Richie Hawtin principle:** Subtraction is more powerful than addition. Remove one thing and the remaining elements become louder without touching a fader.
+
+---
+
+## Technique Library
+
+### 1. Micro-Modulation (Making Things Breathe)
+
+The difference between "sounds like a computer" and "sounds alive" is modulation that operates below conscious perception.
+
+**Filter breathing:** Assign an LFO at 0.1-0.5 Hz to a lowpass filter cutoff with a depth of 5-15%. The filter opens and closes like breathing. The listener doesn't hear "filter modulation" — they feel "organic movement."
+
+**Oscillator drift:** Detune oscillators by 1-3 cents with slow LFO modulation (0.05-0.2 Hz). This creates the warmth of analog — tiny pitch instabilities that prevent digital sterility.
+
+**Amplitude micro-variation:** Automate track volume with perlin/brownian noise at very low depth (±1-3 dB). Every bar sounds slightly different even with identical notes.
+
+**Key insight:** If the listener can consciously hear the modulation, it's too much. The best modulation is felt, not heard.
+
+### 2. Space as Composition (Dub Techniques)
+
+In dub techno, reverb and delay are not decorations — they generate the harmonic and melodic content.
+
+**The dub chord:** A short, dry chord stab fed into long delay (70-80% feedback) with a filter on the delay return. The delay tail becomes the pad. The filter on the return shapes the "melody" — slowly opening the filter on the delay return makes the chord brighten over time while the source stays dark.
+
+**Reverb as harmony:** A single note hit fed into a reverb with 5-10s decay. The reverb tail becomes a drone that carries harmonic information. Modulating the reverb's pre-delay and diffusion creates the impression of harmonic movement.
+
+**Delay throws:** Normally sends are set to a fixed level. A "throw" is a momentary spike — send level goes from 0 to 60-80% for half a beat, then back to 0. The element echoes into space and the echo fills the gap. Use this on snare, hats, vocal fragments. The throw IS the composition — it creates rhythmic space events.
+
+**Feedback modulation:** Set delay feedback to 75-85% (near self-oscillation). Then modulate the delay time by ±5-10%. The pitch shifts create eerie, warped echoes — the signature Basic Channel sound.
+
+### 3. Creative Sidechain (Beyond Pump)
+
+Sidechain compression is not just for the kick-bass pump. It's a modulation source.
+
+**Sidechain reverb from drums:** Route the dry drum signal to trigger sidechain compression on the reverb return. When drums hit, the reverb ducks. When drums are silent, the reverb fills the space. This creates rhythmic breathing in the entire reverb field — the room "pulses" with the groove.
+
+**Sidechain everything from a ghost kick:** Create a muted kick track (no audio output). Use it as a sidechain source for pads, textures, atmospheres. This creates rhythmic ducking on elements that have no rhythmic content — they pulse with a phantom groove.
+
+**Sidechain filter instead of volume:** Instead of ducking volume, use an envelope follower (from the kick) to modulate a filter cutoff on the pad. When the kick hits, the pad filter closes. When the kick releases, the pad opens. Subtler than volume ducking — the pad "brightens" between kicks instead of getting quieter.
+
+**Multiband sidechain:** Only duck the low frequencies of a pad from the kick. The high frequencies stay constant — shimmer remains while the sub clears for the kick. Use Multiband Dynamics or an EQ before the compressor.
+
+### 4. Textural Layering (Villalobos Method)
+
+Villalobos builds textures by layering tiny, filtered, processed fragments — each one barely audible alone, together they create a living fabric.
+
+**Grain technique:** Take a single percussion hit. Duplicate it 3-4 times. Process each copy differently — one through bit reduction, one through heavy reverb, one through a bandpass filter, one pitch-shifted. Pan them across the stereo field. Mix each at 15-25% of the original. The result: one "hit" that has depth, width, and organic irregularity.
+
+**Noise sculpting:** White noise through a tight bandpass filter with slow LFO on the center frequency creates a "breathing" texture. Add this at -20dB under your main elements. It's the "air" in the room. Modulate the filter Q for moments of focus.
+
+**Sample mangling:** Take a melodic sample. Time-stretch it to 200-400% length. This reveals the granular structure — artifacts become texture. Filter the result aggressively. Use what remains as an atmospheric layer.
+
+### 5. Frequency Domain Thinking
+
+Don't think about tracks — think about frequency bands. Each band is a voice in the mix.
+
+**Sub (20-60 Hz):** One element only. Kick or bass, never both at the same time. Sidechain or frequency split to ensure they alternate.
+
+**Low (60-200 Hz):** Bass body and kick impact. Keep this mono. This is where groove lives.
+
+**Low-mid (200-500 Hz):** The "warmth" zone but also the "mud" zone. Be selective — only one or two elements should occupy this space at any time.
+
+**Mid (500-2kHz):** Where most melodic/harmonic content sits. Filter pads to stay below 2kHz for depth. Bright melodic elements (leads) sit above 1kHz.
+
+**High-mid (2-6kHz):** Presence and attack. Hi-hats, percussion transients, vocal presence. This is what makes things "cut through."
+
+**High/Air (6-20kHz):** Shimmer and sparkle. Reverb tails, noise textures, cymbal sustain. Subtle modulation here creates "life."
+
+**The frequency dance:** At any given moment, each frequency band should have one primary element. When the chord opens its filter into the highs, pull the hi-hat back. When the bass drops, the kick shortens. This is mix engineering as composition.
+
+### 6. Organic Automation Shapes
+
+Real producers don't draw straight lines or perfect curves. Their automation reflects human movement.
+
+**Perlin noise:** Smooth, natural-looking randomness. Perfect for filter cutoff drift, send level breathing, oscillator detune. Sounds like "a hand on a knob."
+
+**Brownian motion:** Random walk — each value is close to the previous one. Good for very slow parameter drift over 16-32 bars. Creates the feeling of gradual transformation.
+
+**Exponential curves:** For build-ups and filter sweeps. Energy accumulates slowly at first, then accelerates. This is how tension works in music — the last 4 bars contain more change than the first 12.
+
+**Asymmetric envelopes:** Fast attack, slow release on send throws. The element stabs into the reverb quickly, but the tail fades slowly. This is more musical than symmetric curves.
+
+**Anti-quantize:** After drawing automation, add tiny random offsets (±0.05 beats) to the breakpoints. This prevents the automation from sounding "gridded."
+
+### 7. The WTF Moment
+
+Every great minimal track has 2-3 moments where something unexpected happens — a sound that doesn't belong, a brief disruption that breaks the hypnosis just enough to deepen it.
+
+**Techniques:**
+- Reverse a percussion hit for 1 bar before a section change
+- Pitch-shift the entire master bus by ±2 semitones for 2 beats
+- Suddenly remove ALL reverb for 4 beats — the room "dries up"
+- Send one element to 100% delay feedback for 1 beat, creating a momentary pitch spiral
+- Drop the tempo by 0.5 BPM for 16 bars, then return — subconscious tension
+- Insert 1 bar of silence (mute master) — the most powerful "effect"
+
+**Rules:**
+- Maximum 3 WTF moments per 8-minute track
+- Never repeat the same trick
+- The WTF moment should last 2-8 beats — any longer and it becomes a section, not a moment
+- After the WTF, return to exactly where you were — the contrast is what makes it powerful
+
+### 8. Effects as Instruments
+
+In experimental electronic music, effects chains ARE instruments.
+
+**Self-oscillating filter:** Push a filter's resonance to the point where it starts ringing. Play notes by changing the cutoff frequency. The filter becomes a sine oscillator with natural overtones.
+
+**Feedback loop instrument:** Route a track's output back to its own input through effects. Add a compressor to prevent runaway feedback. What you get is a living, evolving texture that responds to its own output. Add a gate to control when it speaks.
+
+**Granular reverb:** Very short reverb (0.1-0.3s) with high diffusion on percussive sounds. The reverb doesn't add "space" — it smears the transient into a tonal cloud. The pitch of the cloud is determined by the reverb size.
+
+**Convolution as synthesis:** Load a non-impulse-response file into a convolution reverb — a speech recording, a drum break, a synth pad. The "reverb" imprints the spectral character of that source onto whatever passes through it. A kick drum through a vocal convolution gains speech-like formants.
+
+---
+
+## Application Principles
+
+When working on any track, think about these layers:
+
+1. **Foundation:** What is the one element that defines this track? Protect it.
+2. **Modulation:** What is moving? If nothing is moving, the track is dead.
+3. **Space:** Where are things in the stereo field? What reverb/delay creates the "room"?
+4. **Frequency balance:** At any moment, is every frequency band occupied by exactly one primary element?
+5. **Surprise:** Where are the 2-3 WTF moments that break the hypnosis?
+6. **Evolution:** Over 8 minutes, what changes? Not clip changes — parameter changes. The filter that opened 5% in the first minute is at 70% by minute 6.
+
+**The test:** Mute any single track. If the track sounds empty, that element is doing too much. If the track sounds the same, that element isn't doing enough. Each element should be missed when removed but not dominant when present.

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

@@ -7,9 +7,23 @@ description: This skill should be used when the user asks to "load a device", "a
 
 Load instruments, effects, and plugins into Ableton Live tracks. Every device operation follows one discipline: search first, verify after.
 
-## Browser Workflow — The Safe Path
+## Primary Workflow — Atlas-Driven
 
-Always use the two-step browser workflow for loading devices:
+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
@@ -106,9 +120,30 @@ For Simpler devices that already have samples 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, mode)` — switch between Classic, One-Shot, and Slice modes
+- `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
+- `move_device(track_index, device_index, new_index)` — reorder devices on a track
+
+### Plugin Deep Control
 
-Slice mode workflow: load sample, set playback mode to Slice, call `get_simpler_slices` to see slice points, then program MIDI notes targeting slice indices.
+- `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
 
 ## Effect Chain Best Practices
 

package/livepilot/skills/livepilot-evaluation/references/capability-modes.md

@@ -104,7 +104,7 @@ Call `get_capability_state` at the start of any evaluation session. The response
 {
   "mode": "normal",
   "analyzer_connected": true,
-  "bridge_version": "1.9.18",
+  "bridge_version": "1.10.1",
   "spectral_cache_age_ms": 1200,
   "flucoma_available": false,
   "session_connected": true

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

@@ -28,38 +28,42 @@ Run this checklist EVERY time the user says "update everything", "push", "releas
 
 ## 2. Tool Count (must ALL match)
 
-Current: **293 tools across 39 domains**.
-Core (no M4L): **149**. Analyzer (M4L): **29**. Perception (offline): **4**. V2 engines: **86+**.
+Current: **317 tools across 43 domains**.
+Core (no M4L): **286**. Bridge (M4L): **30** (backed by 28 bridge commands).
 
 Verify: `grep -rc "@mcp.tool" mcp_server/tools/ | grep -v ":0" | awk -F: '{sum+=$2} END{print sum}'`
 
 Files that reference tool count:
-- [ ] `README.md` — header, PERCEPTION section ("207 core...30 analyzer"), Analyzer table header "(29)", Perception table header "(4)"
-- [ ] `package.json` → `"description"` (293 tools, 39 domains)
+- [ ] `README.md` — header ("317 tools. 43 domains"), bridge section ("286 core...30 bridge")
+- [ ] `package.json` → `"description"`
 - [ ] `server.json` → `"description"`
+- [ ] `manifest.json` → `"description"`
 - [ ] `livepilot/.Codex-plugin/plugin.json` → `"description"` (primary Codex manifest)
 - [ ] `livepilot/.claude-plugin/plugin.json` → `"description"` (must match Codex plugin)
 - [ ] `.claude-plugin/marketplace.json` → `"description"`
-- [ ] `CLAUDE.md` → "293 tools across 39 domains"
-- [ ] `livepilot/skills/livepilot-core/SKILL.md` — "293 tools across 39 domains", Analyzer (30), Perception (4)
-- [ ] `livepilot/skills/livepilot-core/references/overview.md` — "293 tools across 39 domains"
-- [ ] `docs/manual/index.md` — domain table: Analyzer (30), Perception (4)
-- [ ] `docs/manual/getting-started.md` — "207 core tools...30 analyzer"
+- [ ] `CLAUDE.md` → "317 tools across 43 domains"
+- [ ] `CONTRIBUTING.md` → tool count in intro
+- [ ] `livepilot/skills/livepilot-core/SKILL.md` — tool/domain count
+- [ ] `livepilot/skills/livepilot-core/references/overview.md` — tool/domain count
+- [ ] `docs/manual/index.md` — domain table with correct per-domain counts
+- [ ] `docs/manual/getting-started.md` — "286 core tools...30 bridge"
 - [ ] `docs/manual/tool-reference.md` — all domains present with correct counts
-- [ ] `docs/TOOL_REFERENCE.md` — all domains present
-- [ ] `docs/M4L_BRIDGE.md` — "207 core tools...30 analyzer"
+- [ ] `docs/manual/tool-catalog.md` — all tools present (CI-tested)
+- [ ] `docs/manual/tool-catalog-generated.md` — regenerated from source
+- [ ] `docs/TOOL_REFERENCE.md` — all domains present with correct counts
+- [ ] `docs/M4L_BRIDGE.md` — "286 core tools...30 bridge"
 - [ ] `docs/social-banner.html`
-- [ ] `mcp_server/tools/analyzer.py` → module docstring
 - [ ] `tests/test_tools_contract.py` → expected total count
+- [ ] `tests/test_skill_contracts.py` → catalog sync test passes
 
 **How to check:** `grep -rn "168\|139\|135\|127\|115\|107" --include="*.md" --include="*.json" --include="*.py" --include="*.html" . | grep -v node_modules | grep -v .git | grep -v __pycache__ | grep -v CHANGELOG`
 
 ## 3. Domain Count
 
-Current: **39 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine, song_brain, preview_studio, hook_hunter, stuckness_detector, wonder_mode, session_continuity, creative_constraints.
+Current: **43 domains**: transport, tracks, clips, notes, devices, scenes, mixing, browser, arrangement, memory, analyzer, automation, theory, generative, harmony, midi_io, perception, agent_os, composition, motif, research, planner, project_brain, runtime, evaluation, mix_engine, sound_design, transition_engine, reference_engine, translation_engine, performance_engine, song_brain, preview_studio, hook_hunter, stuckness_detector, wonder_mode, session_continuity, creative_constraints, device_forge, sample_engine, atlas, composer, experiment, musical_intelligence.
 
-- [ ] All files that mention domain count say "39 domains"
-- [ ] Domain lists include ALL 39 (especially newer domains — they're the most often omitted)
+- [ ] All files that mention domain count say "43 domains"
+- [ ] Domain lists include ALL 43 (especially newer domains — they're the most often omitted)
 
 ## 4. npm Registry
 
@@ -89,9 +93,9 @@ Current: **39 domains**: transport, tracks, clips, notes, devices, scenes, mixin
 
 - [ ] `README.md` — features match current capabilities, "Coming" section is accurate
 - [ ] `docs/manual/getting-started.md` — install instructions current
-- [ ] `docs/manual/tool-reference.md` — all 39 domains listed, all 293 tools present
-- [ ] `docs/TOOL_REFERENCE.md` — all 39 domains present
-- [ ] `docs/M4L_BRIDGE.md` — architecture accurate, core tool count correct
+- [ ] `docs/manual/tool-reference.md` — all 43 domains listed, all 317 tools present
+- [ ] `docs/TOOL_REFERENCE.md` — all 43 domains present with correct counts
+- [ ] `docs/M4L_BRIDGE.md` — architecture accurate, core/bridge counts correct
 
 ## 9. Derived Artifacts
 
@@ -122,5 +126,5 @@ Current: **39 domains**: transport, tracks, clips, notes, devices, scenes, mixin
 ## Quick Verify Command
 
 ```bash
-echo "=== Versions ===" && grep -h '"version"' package.json server.json livepilot/.Codex-plugin/plugin.json livepilot/.claude-plugin/plugin.json .claude-plugin/marketplace.json | head -7 && grep __version__ mcp_server/__init__.py remote_script/LivePilot/__init__.py && echo "=== Tool count ===" && grep -rc "@mcp.tool" mcp_server/tools/ | grep -v ":0" | awk -F: '{sum+=$2} END{print "Total:", sum}' && echo "=== Tests ===" && python3 -m pytest tests/ -q 2>&1 | tail -1
+echo "=== Versions ===" && grep -h '"version"' package.json server.json manifest.json livepilot/.Codex-plugin/plugin.json livepilot/.claude-plugin/plugin.json .claude-plugin/marketplace.json | head -8 && grep __version__ mcp_server/__init__.py remote_script/LivePilot/__init__.py && echo "=== Tool count ===" && grep -rc "@mcp.tool" mcp_server/ | grep -v ":0" | awk -F: '{sum+=$2} END{print "Total:", sum}' && echo "=== Tests ===" && python3 -m pytest tests/ -q 2>&1 | tail -1
 ```

package/livepilot/skills/livepilot-sample-engine/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: livepilot-sample-engine
+description: >
+  This skill should be used when the user asks to "sample", "chop",
+  "slice a loop", "find me a sample", "load a sample", "flip this",
+  "resample", "vocal chop", "found sound", "texture from", "turn this into",
+  "break", "one-shot", "load into Simpler", or when get_sample_opportunities
+  finds gaps in the song's sample usage.
+---
+
+# Sample Engine — AI Sample Manipulation for Ableton Live
+
+The Sample Engine is LivePilot's intelligence layer for sample discovery,
+analysis, critique, and creative manipulation. It turns raw samples into
+musical elements through 29 techniques drawn from Dilla, Burial, Amon Tobin,
+Four Tet, and DJ Premier.
+
+## Philosophy: Surgeon vs Alchemist
+
+Every sample workflow is guided by one of two philosophies:
+
+- **Surgeon** — Precision. Match key, align tempo, carve frequencies, blend
+  seamlessly. The sample should sound like it was always part of the track.
+- **Alchemist** — Transformation. Reverse, stretch, destroy, rebuild.
+  The original creator shouldn't recognize their sample.
+- **Auto** (default) — Context decides. Building a clean layer? Surgeon.
+  Stuck and need surprise? Alchemist. The critics and intent determine which.
+
+## 6 MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `analyze_sample` | Build SampleProfile — material type, key, BPM, recommendations |
+| `evaluate_sample_fit` | 6-critic battery — key, tempo, frequency, role, vibe, intent fit |
+| `search_samples` | Search Splice library, Ableton browser, and local filesystem |
+| `suggest_sample_technique` | Recommend techniques from the 29-recipe library |
+| `plan_sample_workflow` | End-to-end plan: analyze + critique + technique + compiled steps |
+| `get_sample_opportunities` | Analyze song for where samples could improve it |
+
+## Workflow Modes
+
+### Direct Request
+User asks to do something specific with a sample:
+```
+"Chop this vocal into a rhythm"
+ -> analyze_sample -> evaluate_sample_fit(intent="rhythm")
+ -> suggest_sample_technique -> execute
+```
+
+### Discovery Mode
+User wants to find and use a sample:
+```
+"Find me a dark vocal for this track"
+ -> search_samples(query="dark vocal") -> present candidates
+ -> user picks -> analyze -> critique -> plan -> execute
+```
+
+### Wonder Mode Integration
+When stuck, Wonder Mode can suggest sample-based variants:
+- 6 sample-domain semantic moves in the registry
+- Compiled plans require agent to supply `file_path` from prior `search_samples` results
+- Diagnosis detects: no_organic_texture, stale_drums, dense_but_static
+- Note: Wonder does not yet auto-call `search_samples` — the agent must chain the calls
+
+## Golden Rules
+
+1. **Always analyze before loading** — `analyze_sample` tells you what
+   the material is before you commit to a technique
+2. **Always critique before executing** — `evaluate_sample_fit` catches
+   key clashes, tempo mismatches, and frequency masking before they happen
+3. **Respect the intent** — "rhythm" and "texture" need different approaches
+   even for the same sample
+4. **Start from the nearest technique** — don't improvise a workflow when
+   a proven recipe exists in the library
+5. **Present both plans** — surgeon and alchemist. Let the user choose.
+
+## Material Types
+
+| Type | Detection | Best Simpler Mode | Best Warp Mode |
+|------|-----------|-------------------|----------------|
+| vocal | "vocal", "vox", "voice" in name | Slice (Region) | Complex Pro |
+| drum_loop | "drum", "break", "beat" in name | Slice (Transient) | Beats |
+| instrument_loop | "guitar", "piano", "synth" | Slice (Beat) | Complex Pro |
+| one_shot | "kick", "snare", "clap", short | Classic | Complex |
+| texture | "ambient", "pad", "drone" | Classic | Texture |
+| foley | "foley", "field", "recording" | Classic | Texture |
+| fx | "fx", "riser", "sweep" | Classic | Complex |
+| full_mix | full mix, long duration | Slice (Beat) | Complex Pro |
+
+## 6 Sample Critics
+
+Each scores 0.0-1.0 on one dimension of fitness:
+
+1. **Key Fit** — Circle-of-fifths distance from song key
+2. **Tempo Fit** — BPM match including half/double time
+3. **Frequency Fit** — Spectral overlap with existing mix
+4. **Role Fit** — Does this fill a missing role in the song?
+5. **Vibe Fit** — Taste graph alignment (if evidence exists)
+6. **Intent Fit** — Does the material serve the stated goal?
+
+## Reference Docs
+
+- `references/sample-techniques.md` — Full 29-technique catalog
+- `references/sample-critics.md` — Critic scoring details
+- `references/sample-philosophy.md` — Surgeon vs Alchemist guide

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 |