livepilot 1.26.0 → 1.26.1

package/livepilot/skills/livepilot-performance-engine/references/performance-safety.md

@@ -0,0 +1,98 @@
+# Performance Safety Reference
+
+Complete classification of every LivePilot action for live performance contexts.
+
+## Safe Actions (No Confirmation Needed)
+
+| Action | Tool | Notes |
+|--------|------|-------|
+| Launch scene | `fire_scene` | Core performance action |
+| Launch clip | `fire_clip` | Individual clip triggering |
+| Stop clip | `stop_clip` | Individual clip stop |
+| Stop track clips | `stop_track_clips` | Clear a track |
+| Volume nudge (small) | `set_track_volume` | Delta <= 3 dB only |
+| Send nudge | `set_track_send` | Small adjustments to reverb/delay throws |
+| Macro nudge | `set_device_parameter` | On mapped macro controls only |
+| Filter sweep | `set_device_parameter` | On Auto Filter frequency parameter |
+| Mute toggle | `set_track_mute` | Non-destructive, reversible |
+| Solo toggle | `set_track_solo` | Non-destructive, reversible |
+| Pan nudge (small) | `set_track_pan` | Delta <= 0.2 only |
+| Master volume | `set_master_volume` | For overall level control |
+| Continue playback | `continue_playback` | Resume from pause |
+| Jump to cue | `jump_to_cue` | Navigate arrangement cue points |
+| Get state | `get_performance_state` | Read-only, always safe |
+| Get playing clips | `get_playing_clips` | Read-only |
+| Get scene matrix | `get_scene_matrix` | Read-only |
+| Any get_* tool | various | All read-only tools are safe |
+
+## Caution Actions (Require Confirmation)
+
+| Action | Tool | Risk |
+|--------|------|------|
+| Tempo nudge | `set_tempo` | May destabilize warped audio, synced plugins |
+| Device toggle | `toggle_device` | May cause audio pop, click, or silence |
+| Large pan move | `set_track_pan` | Disorienting for audience if sudden |
+| Large volume jump | `set_track_volume` | Jarring if delta > 3 dB |
+| Fire scene clips | `fire_scene_clips` | Selective scene launch, less predictable |
+| Set scene tempo | `set_scene_tempo` | Changes tempo on next scene fire |
+
+### Confirmation Protocol
+
+Present as: "[Action description]. Risk: [what could go wrong]. Confirm?"
+
+Keep confirmations short during performance. One line maximum.
+
+## Blocked Actions (Never During Performance)
+
+### Device Chain Surgery
+- `find_and_load_device` — loading causes audio thread hiccup
+- `delete_device` — removing active device causes dropout
+- `load_device_by_uri` — same as find_and_load
+- `load_browser_item` — browser loading is unpredictable latency
+
+### Track Structure
+- `create_midi_track` / `create_audio_track` / `create_return_track` — track creation pauses audio engine momentarily
+- `delete_track` — data loss, audio interruption
+- `duplicate_track` — CPU spike
+- `set_track_routing` — routing changes can cause feedback or silence
+
+### Clip Editing
+- `create_clip` / `delete_clip` / `duplicate_clip` — structural changes while playing
+- `set_clip_loop` / `set_clip_warp_mode` / `quantize_clip` — property changes on playing clips
+- `add_notes` / `modify_notes` / `remove_notes` — note editing mid-playback
+
+### Arrangement Editing
+- All `*_arrangement_*` tools — arrangement view editing during performance
+- `set_arrangement_automation` — automation lane changes
+
+### Heavy Operations
+- `freeze_track` / `flatten_track` — CPU-intensive, blocks audio thread
+- `start_recording` — may cause unexpected monitoring behavior
+- `capture_audio` / `capture_midi` — resource-intensive
+
+### Data Operations
+- `undo` / `redo` — unpredictable state reversion during live playback
+- `memory_learn` / `memory_delete` — non-urgent, save for after the show
+- `import_midi_to_clip` — file I/O during performance
+
+## Emergency Procedures
+
+### Audio Problem
+1. `set_track_mute(track_index, true)` on the problem track
+2. If problem persists: `set_master_volume(0.0)` for fade to silence
+3. Last resort: `stop_all_clips` for emergency silence
+
+### Feedback Loop
+1. `set_track_mute` on the suspected track immediately
+2. `set_track_send` to zero on all sends for that track
+3. Gradually unmute after identifying the routing issue
+
+### Wrong Scene Launched
+1. Immediately `fire_scene` on the correct scene
+2. Or `stop_all_clips` and restart from the correct point
+3. Do not use `undo` — it may revert more than intended
+
+### CPU Spike
+1. `set_track_mute` on the most CPU-heavy tracks (check `get_session_info` for device counts)
+2. `toggle_device` to bypass heavy effects (with caution confirmation skipped in emergency)
+3. If critical: `stop_all_clips` and restart with fewer active tracks

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

@@ -0,0 +1,151 @@
+---
+name: livepilot-release
+description: Release checklist for LivePilot — run before ANY push, publish, or "update everything" request. Covers every file, channel, and artifact that references version numbers, tool counts, or project state.
+---
+
+# LivePilot Release Checklist
+
+Run this checklist EVERY time the user says "update everything", "push", "release", "make sure everything is current", or similar.
+
+## 1. Version Strings (must ALL match)
+
+- [ ] `package.json` → `"version"`
+- [ ] `package-lock.json` → `"version"` (run `npm install --package-lock-only` if stale)
+- [ ] `server.json` → `"version"` (TWO locations: top-level and package)
+- [ ] `livepilot/.Codex-plugin/plugin.json` → `"version"` (primary Codex manifest)
+- [ ] `livepilot/.claude-plugin/plugin.json` → `"version"` (must match Codex plugin)
+- [ ] `.claude-plugin/marketplace.json` → `"version"` in plugins array
+- [ ] `mcp_server/__init__.py` → `__version__`
+- [ ] `remote_script/LivePilot/__init__.py` → `__version__` (log message auto-uses it)
+- [ ] `m4l_device/livepilot_bridge.js` → version in ping response
+- [ ] `CLAUDE.md` → header line
+- [ ] `livepilot/skills/livepilot-core/references/overview.md` → header line
+- [ ] `CHANGELOG.md` → latest version header
+- [ ] `docs/assets/banner-dark.svg` and `docs/assets/banner-light.svg` → current tool/domain display
+- [ ] `docs/M4L_BRIDGE.md` → ping response example
+
+**How to check:** `grep -rn "1\.[0-9]\.[0-9]" package.json server.json livepilot/.Codex-plugin/plugin.json livepilot/.claude-plugin/plugin.json .claude-plugin/marketplace.json mcp_server/__init__.py remote_script/LivePilot/__init__.py m4l_device/livepilot_bridge.js CHANGELOG.md CLAUDE.md livepilot/skills/livepilot-core/references/overview.md docs/M4L_BRIDGE.md`
+
+## 2. Tool Count (must ALL match)
+
+Current: **465 tools across 56 domains**.
+Spectral/analyzer (bridge-only): **38**. All others: **292** (work without bridge, some with graceful fallbacks). Backed by 32 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 ("465 tools. 56 domains"), bridge section ("38 spectral/analyzer tools require 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` → "465 tools across 56 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` — bridge copy (avoid hard numeric core/bridge split — use "38 spectral tools require bridge")
+- [ ] `docs/manual/tool-reference.md` — all domains present with correct counts
+- [ ] `docs/manual/tool-catalog.md` — auto-regenerated by `python3 scripts/sync_metadata.py --fix`
+      (raw generator is `python3 scripts/generate_tool_catalog.py > docs/manual/tool-catalog.md`,
+      but you should never need to call it directly — `--fix` invokes it at the end of the chain
+      after the count bumps so the catalog stays coherent with the live `mcp.list_tools()` registry)
+- [ ] `docs/M4L_BRIDGE.md` — bridge copy (avoid hard numeric core/bridge split — use "38 spectral tools require bridge")
+- [ ] `docs/assets/banner-dark.svg` and `docs/assets/banner-light.svg`
+- [ ] `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: **56 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, semantic_moves, diagnostics, follow_actions, grooves, scales, take_lanes, miditool, synthesis_brain, creative_director, user_corpus, audit, grader.
+
+- [ ] All files that mention domain count say "56 domains"
+- [ ] Domain lists include ALL 45 (especially newer domains — they're the most often omitted)
+
+## 4. npm Registry
+
+- [ ] `npm view livepilot version` matches local version
+- [ ] If not: `npm publish`
+
+## 5. GitHub
+
+- [ ] Repo description matches current tool count and features (`gh repo edit dreamrec/LivePilot --description "..."`)
+- [ ] Topics are current (should include: ai, mcp, ableton, livepilot, max-for-live, audio-analysis)
+- [ ] Latest release matches current version (`gh release list`)
+- [ ] Release notes are current
+- [ ] **NEW VERSION shows `Latest` flag in `gh release list`** — not just `Draft`. If a tag was deleted-then-recreated during release recovery (e.g., to move the tag to a fix commit), GitHub silently demotes the attached release to Draft AND clears its Latest flag. The release object survives (asset + body preserved) but the public-facing "what's the latest version" badge stays on the prior release. Fix in one call:
+      ```bash
+      gh release edit v${VERSION} --draft=false --latest
+      ```
+      This trap caught v1.18.0-era recovery and the v1.25.0 .amxd-freeze fix recovery. **Always re-verify after a tag-recreate flow.**
+
+## 6. Plugin Cache
+
+- [ ] `~/.claude/plugins/cache/dreamrec-LivePilot/livepilot/` has current version directory
+- [ ] Old version directories removed
+- [ ] `~/.claude/plugins/installed_plugins.json` → `livepilot@dreamrec-LivePilot` entry: update `version`, `installPath`, `gitCommitSha`, `lastUpdated`
+
+## 7. Social/Promotional Assets
+
+- [ ] `docs/assets/banner-dark.svg` and `docs/assets/banner-light.svg` — tool count and domain list
+- [ ] GitHub repo social preview image (Settings > Social preview)
+
+## 8. Documentation Content
+
+- [ ] `README.md` — features match current capabilities, "Coming" section is accurate
+- [ ] `docs/manual/getting-started.md` — install instructions current
+- [ ] `docs/manual/tool-reference.md` — all 56 domains listed, all 465 tools present
+- [ ] `docs/M4L_BRIDGE.md` — architecture accurate, core/bridge counts correct
+
+## 9. Derived Artifacts
+
+- [ ] `m4l_device/LivePilot_Analyzer.amxd` — frozen JS matches source? All commands present?
+- [ ] If `livepilot_bridge.js` changed → amxd needs rebuilding in Max editor
+- [ ] `dist/livepilot-${VERSION}.mcpb` — MCPB bundle for Claude Desktop one-click install.
+      **REQUIRED for every release** — the README's "Easiest: Claude Desktop Extension (1 click)"
+      path points at this asset. From v1.17 through v1.20.2 every release silently shipped
+      without it; v1.20.3+ MUST attach the bundle to the GitHub release.
+      ```bash
+      # Build (produces dist/livepilot-${VERSION}.mcpb — versioned, in dist/, ~4-5 MB)
+      bash scripts/build_mcpb.sh
+
+      # Attach to the release (run after `gh release create`)
+      VERSION=$(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")
+      gh release upload "v${VERSION}" "dist/livepilot-${VERSION}.mcpb" --clobber
+      ```
+      The script stages `manifest.json` + `bin/livepilot.js` + `mcp_server/` + `remote_script/`
+      + `m4l_device/` + `installer/` + `requirements.txt`, strips `__pycache__`/`*.pyc`/`.DS_Store`,
+      zips into `dist/`, and verifies the embedded manifest name+version+entry_point.
+
+## 10. Code Consistency
+
+- [ ] `@mcp.tool()` count matches documented tool count: `grep -r "@mcp.tool" mcp_server/tools/ | wc -l`
+- [ ] No dead imports or unused code in recently changed files
+- [ ] Remote script version matches MCP server version
+- [ ] All tests pass: `python3 -m pytest tests/ -v`
+
+## 11. Automated Checks
+
+- [ ] `python scripts/sync_metadata.py --check` — all metadata in sync
+- [ ] `python -m pytest tests/test_command_boundary_audit.py` — no invalid TCP targets
+- [ ] `python -m pytest tests/test_move_annotations.py` — all moves annotated
+- [ ] `python -m pytest tests/test_capability.py` — capability contract works
+- [ ] `python -m pytest tests/test_capability_probe.py` — doctor probe works
+
+## 12. Release Smoke Board
+
+- [ ] Run through `docs/archive/release-smoke-board-v1.10-era.md` scenarios
+      against a real Ableton session (archived — still a useful pre-flight
+      checklist even if written against v1.10 tool surface)
+- [ ] All preview modes correctly labeled (audible/metadata/analytical)
+- [ ] Persistence survives server restart
+
+## Quick Verify Command
+
+```bash
+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,117 @@
+---
+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?
+
+## Beyond Simpler — Sample-Adjacent Instruments in the Library
+
+Simpler is the default sample container, but the installed packs ship instruments that change the *physics* of what playback means. When the user reaches for "more texture" / "less recognizable" / "evolving" / "grain" / "drone bed", consider these before defaulting to Simpler + warp:
+
+- **Granulator III** (Live Suite, requires Live 12.0+ Max for Live) — Robert Henke's granular synth. Three modes: **Classic** (Granulator II engine), **Loop** (rhythmic playback), **Cloud** (up to 20 unsynced overlapping grains). MPE per-note control of grain size/shape/position. **Built-in real-time audio capture** — can grain whatever is currently playing in the session in one click. 59 presets. Reach for it when the user wants a sample to evolve, smear, or stop sounding like itself.
+- **PitchLoop89** (Live Suite) — Henke / Publison DHM 89 emulation. Two independent pitch-shifting delay voices, ±24 semitones, fine ±1 semitone, per-voice feedback / pan / reverse. The right tool when "shimmer", "detuned cloud", or "pitched echo" describes the goal.
+- **Drone Lab's Harmonic Drone Generator** — 8-voice M4L synth (Expert Math). Multiple tuning systems including just intonation, Pythagorean, Indonesian Pelog. The right tool when the source isn't a sample at all but a sustained tonal bed under whatever's already playing.
+- **Lost and Found multisamples** — music box, mid-century Capri fan organ, DIY plastic guitar, melodica, kazoo, metal xylophone, plus 7 Drum Racks built from everyday objects (steel water bottle, analog clock, submerged objects). When the user wants found-sound character without recording their own.
+
+These are awareness, not prescription — pick the one that fits the moment. Don't lock in a chain.
+
+## 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
+- `docs/research/2026-04-22-ableton-packs-deep-analysis.md` — Per-pack capabilities (44 installed packs scored against minimal/dub/cinematic aesthetic)

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