livepilot 1.26.0 → 1.26.2

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

@@ -0,0 +1,130 @@
+---
+name: livepilot-notes
+description: This skill should be used when the user asks to "write notes", "add a melody", "chord progression", "rhythm pattern", "MIDI notes", "transpose", "quantize", "Euclidean rhythm", "counterpoint", "scale", "key detection", "harmony", or wants to create, edit, or analyze MIDI content in Ableton Live.
+---
+
+# MIDI Notes — Create, Edit, and Analyze
+
+Write melodies, chords, rhythms, and generative patterns in Ableton Live clips. Every note operation follows the Live 12 API.
+
+## Note API Cycle
+
+Four operations form the core CRUD cycle for MIDI notes:
+
+1. **Create:** `add_notes(track_index, clip_index, notes)` — write new notes into a clip
+2. **Read:** `get_notes(track_index, clip_index)` — retrieve all notes with IDs, pitches, timings
+3. **Update:** `modify_notes(track_index, clip_index, modifications)` — change existing notes by `note_id`
+4. **Delete:** `remove_notes(track_index, clip_index, start_time, duration, pitch_start, pitch_end)` — clear a region, or `remove_notes_by_id(track_index, clip_index, note_ids)` — surgical deletion by ID
+
+Always create a clip first with `create_clip(track_index, clip_index, length)` before adding notes to it.
+
+## Note Format
+
+When calling `add_notes`, each note requires:
+
+```json
+{
+  "pitch": 60,
+  "start_time": 0.0,
+  "duration": 0.5,
+  "velocity": 100,
+  "mute": false
+}
+```
+
+When reading with `get_notes`, each note also returns Live 12 extended fields:
+- `note_id` — unique identifier for modify/remove operations
+- `probability` — 0.0 to 1.0, per-note trigger probability (Live 12 feature)
+- `velocity_deviation` — -127.0 to 127.0, randomizes velocity on each trigger
+- `release_velocity` — 0.0 to 127.0, note-off velocity
+
+Use `modify_notes` with `note_id` to update any field on existing notes — pitch, velocity, timing, probability, mute state.
+
+## Duplication and Transposition
+
+- `duplicate_notes(track_index, clip_index, time_offset)` — copy all notes forward by `time_offset` beats. Use for pattern repetition: a 4-beat pattern duplicated at offset 4.0 creates an 8-beat loop.
+- `transpose_notes(track_index, clip_index, semitones, start_time, duration)` — shift pitches in a region by semitones. Positive = up, negative = down.
+- `transpose_smart(track_index, clip_index, semitones, key)` — transpose with scale awareness. Notes stay within the target key, avoiding chromatic collisions.
+
+## Quantization
+
+`quantize_clip(track_index, clip_index, grid, amount)` snaps note start times to a rhythmic grid.
+
+Grid enum values:
+- 0 = None (no quantize)
+- 1 = 1/4 notes
+- 2 = 1/8 notes
+- 3 = 1/8 triplets
+- 4 = 1/8 + triplets (combined grid)
+- 5 = 1/16 notes
+- 6 = 1/16 triplets
+- 7 = 1/16 + triplets (combined grid)
+- 8 = 1/32 notes
+
+The `amount` parameter (0.0-1.0) controls how far notes move toward the grid. Use 1.0 for rigid quantize, 0.5-0.7 for humanized feel.
+
+## Theory Integration
+
+Run these checks before firing any clip with melodic content:
+
+1. `identify_scale(track_index, clip_index)` — detect the scale from existing notes (Krumhansl-Schmuckler algorithm). Returns key, mode, and confidence.
+2. `detect_theory_issues(track_index, clip_index, strict=true)` — check for out-of-key notes, parallel fifths, voice crossing, augmented/diminished accidents. The `strict` flag enables all checks.
+3. Fix problems with `modify_notes` — adjust offending pitches before the user hears them.
+
+The theory engine knows 7 standard modes. Exotic scales (Hijaz, Hungarian minor, whole tone) produce false "out of key" warnings. Cross-reference flagged pitches against the intended scale manually. Use `key="C hijaz"` for Hijaz/Phrygian Dominant keys.
+
+## Harmony Analysis and Suggestions
+
+- `analyze_harmony(track_index, clip_index)` — identify chords in a clip, returns chord names, qualities, root notes, and progression analysis
+- `suggest_next_chord(track_index, clip_index, key)` — given the current harmonic context, suggest the next chord with voice leading and functional reasoning
+- `harmonize_melody(track_index, clip_index, key, style)` — generate harmony notes for an existing melody. Returns a note array ready for `add_notes` on a separate track.
+- `generate_countermelody(track_index, clip_index, key, species)` — generate a counterpoint line against existing notes. Species 1-5 follow classical counterpoint rules. Returns notes for `add_notes`.
+
+Both `harmonize_melody` and `generate_countermelody` return note arrays — do not call them and discard the output. Place the results into a clip with `add_notes`.
+
+## Generative Algorithms
+
+### Euclidean Rhythms
+
+`generate_euclidean_rhythm(pulses, steps, pitch, velocity, duration)` — distribute `pulses` as evenly as possible across `steps` using the Bjorklund algorithm. Returns a note array. The tool identifies named rhythms automatically (e.g., 3 pulses in 8 steps = "tresillo", 5 in 8 = "cinquillo").
+
+`layer_euclidean_rhythms(layers)` — stack multiple Euclidean patterns for polyrhythmic textures. Each layer specifies pulses, steps, pitch, and velocity. Returns a combined note array spanning all layers, ready for a single `add_notes` call or split across tracks.
+
+### Minimalist Techniques
+
+`generate_tintinnabuli(melody_pitches, key, mode, position)` — implement Arvo Part's technique: a T-voice (triad arpeggio) against a M-voice (stepwise melody). Returns two-voice note data.
+
+`generate_phase_shift(pattern, shift_amount, repetitions)` — implement Steve Reich's phasing: two identical patterns drifting apart over time. One voice holds steady while the other shifts by `shift_amount` per repetition.
+
+`generate_additive_process(melody_pitches, iterations)` — implement Philip Glass's additive technique: melody expanded by adding one note per iteration, building complexity gradually.
+
+All generative tools return note arrays. Place them in clips with `add_notes`.
+
+## Neo-Riemannian Harmony
+
+- `navigate_tonnetz(chord, transform)` — apply PRL (Parallel, Relative, Leading-tone) transforms to a chord. Returns the neighbor chord and its relationship.
+- `find_voice_leading_path(start_chord, end_chord)` — find the shortest harmonic path between two chords through Tonnetz space. Returns intermediate chords.
+- `classify_progression(chords)` — identify the neo-Riemannian transform pattern in a chord sequence (e.g., PRL cycle, hexatonic, octatonic).
+- `suggest_chromatic_mediants(chord)` — return all chromatic mediant relations with film score usage notes. Useful for dramatic harmonic shifts.
+
+## MIDI File I/O
+
+- `export_clip_midi(track_index, clip_index, file_path)` — export a session clip's notes to a .mid file
+- `import_midi_to_clip(track_index, clip_index, file_path)` — load a .mid file into a clip, replacing existing notes
+- `analyze_midi_file(file_path)` — offline analysis of any .mid file (tempo, note count, structure). No Ableton connection needed.
+- `extract_piano_roll(file_path)` — return a 2D velocity matrix (pitch x time) from a .mid file for visualization
+
+## Pitch Audit — Mandatory Before Firing
+
+Before playing any clip with melodic or harmonic content:
+
+1. `identify_scale` on every melodic track — verify all tracks share the same tonal center
+2. `analyze_harmony` on chordal tracks — verify chord quality (no accidental augmented/diminished)
+3. `detect_theory_issues(strict=true)` — check all theory rules
+4. Report a clear tuning summary to the user before proceeding
+5. Fix wrong notes with `modify_notes` before firing
+
+## Reference
+
+Supporting references live in the `livepilot-core` skill's `references/` directory:
+- `livepilot-core/references/midi-recipes.md` — drum patterns by genre, chord voicings, scale tables, hi-hat articulations, humanization, polymetric layering

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

@@ -0,0 +1,122 @@
+---
+name: livepilot-performance-engine
+description: This skill should be used when the user asks to "perform live", "what's safe to do during a show", "scene handoff", "energy flow", "performance mode", "safe moves", or wants live performance support with safety constraints.
+---
+
+# Performance Engine — Safety-First Live Performance
+
+The performance engine enforces a strict safety model for live performance. Every action is classified before execution. Destructive operations are blocked. Risky operations require user confirmation. Only safe operations execute freely.
+
+## Safety Classification
+
+Every performance action falls into one of four tiers.
+
+### Safe — Execute Freely
+
+These actions are non-destructive and audience-invisible if they fail. Execute without asking.
+
+- `fire_scene` / `fire_clip` — launch scenes or clips (the core of live performance)
+- `set_track_send` with small delta — nudge send levels (reverb/delay throws)
+- `set_device_parameter` on mapped macros — macro knob adjustments
+- `set_track_mute` / `set_track_solo` — mute/solo toggles
+- `set_track_volume` with delta <= 3 dB — volume nudges
+- `set_track_pan` with delta <= 0.2 — subtle pan shifts
+- Filter sweeps via `set_device_parameter` on Auto Filter — smooth frequency movement
+
+### Caution — Require User Confirmation
+
+These actions are audible and may cause a noticeable glitch if wrong. Always ask before executing.
+
+- `set_tempo` with delta <= 5 BPM — tempo nudge (can destabilize synced elements)
+- `toggle_device` — enable/disable effects (may cause pops or silence)
+- `set_track_pan` with delta > 0.2 — large pan moves are disorienting live
+- `set_track_volume` with delta > 3 dB — large volume jumps
+
+Present the action to the user: "I will [action]. This may [risk]. Confirm?"
+
+### Blocked — Never Execute During Performance
+
+These actions risk audible disasters, data loss, or session corruption during a live show.
+
+- `delete_device` / `find_and_load_device` — device chain surgery causes audio interruption
+- `create_arrangement_clip` / `create_clip` / `delete_clip` — clip creation/deletion
+- `create_midi_track` / `create_audio_track` / `delete_track` — track structure changes
+- `add_notes` / `modify_notes` / `remove_notes` — note editing while playing
+- `set_clip_loop` / `set_clip_warp_mode` — clip property changes while playing
+- `flatten_track` / `freeze_track` — CPU-intensive operations
+- Any arrangement-view editing tools
+
+If the user requests a blocked action during performance mode, explain why it is blocked and suggest a safe alternative: "That requires editing the device chain, which can cause audio dropouts during a live show. Instead, try [safe alternative]."
+
+### Unknown — Treat as Blocked
+
+Any action not explicitly classified above defaults to blocked. Do not experiment with unclassified actions during a live performance.
+
+## Performance Loop
+
+### Step 1 — Get State
+
+Call `get_performance_state` to read the current session state:
+- Playing status, current tempo, time signature
+- Which scenes and clips are currently playing
+- Track arm states, solo/mute states
+- Current energy level estimate
+
+### Step 2 — Get Safe Moves
+
+Call `get_performance_safe_moves` to get a list of contextually appropriate safe actions based on the current state. The response is filtered by what makes musical sense right now — not just what is technically safe.
+
+### Step 3 — Check Safety
+
+Before executing any user request, call `check_safety(move_type)` to verify the classification. The response confirms: `safe`, `caution`, or `blocked` with an explanation.
+
+### Step 4 — Execute Safe/Caution Only
+
+- Safe: execute immediately
+- Caution: present to user, wait for confirmation, then execute
+- Blocked: refuse with explanation and alternative
+
+### Step 5 — Scene Handoff
+
+For transitioning between scenes (the primary live performance action), call `plan_scene_handoff(from_scene, to_scene)` to get a transition plan:
+
+- Which clips change between the scenes
+- Recommended launch timing (quantization)
+- Volume/send adjustments to smooth the handoff
+- Any tempo changes between scenes
+
+Execute the handoff plan using safe actions only.
+
+## Energy Flow
+
+During a live set, track the energy trajectory:
+
+1. `get_performance_state` includes an `energy_estimate` (0.0-1.0)
+2. Use scene ordering to build energy arcs: low-energy scenes for intros/breakdowns, high-energy for drops/peaks
+3. `plan_scene_handoff` accounts for energy delta — large energy jumps get transition suggestions
+
+## Performance Mode Entry
+
+When the user says "performance mode", "going live", or "starting the show":
+
+1. Call `get_performance_state` to verify the session is ready
+2. Confirm the safety model with the user: "Performance mode active. I will only execute safe actions freely and ask before caution-level moves. Destructive edits are blocked."
+3. Switch to a response style optimized for speed: short confirmations, no lengthy explanations mid-performance
+4. Prioritize scene launches and safe parameter nudges
+
+## Performance Mode Exit
+
+When the user says "done performing", "show's over", or "exit performance mode":
+
+1. Confirm: "Performance mode ended. Full editing capabilities restored."
+2. Resume normal operation with all tools available
+
+## Emergency Actions
+
+If something goes wrong during a live show:
+
+- `stop_all_clips` — emergency silence (use only if requested)
+- `set_master_volume(0.0)` — fade to silence
+- `set_track_mute` on the problem track — isolate the issue
+
+Never call `undo` during a live performance — it may revert a scene launch or clip state in unpredictable ways.

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**. The remaining tool surface works without the bridge or degrades gracefully. 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 56 (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)