livepilot 1.9.24 → 1.10.1

package/bin/livepilot.js

@@ -211,6 +211,45 @@ function checkStatus() {
   });
 }
 
+function probeAnalyzer(venvPy) {
+  const probeCode = `
+import asyncio
+import json
+import sys
+from types import SimpleNamespace
+
+sys.path.insert(0, ${JSON.stringify(ROOT)})
+
+from mcp_server.server import lifespan, _master_has_livepilot_analyzer
+from mcp_server.runtime.capability_probe import probe_capabilities
+
+async def main():
+    async with lifespan(None) as ctx:
+        loaded = _master_has_livepilot_analyzer(ctx["ableton"])
+        report = probe_capabilities(
+            ableton=ctx["ableton"],
+            ctx=SimpleNamespace(lifespan_context=ctx),
+        )
+        print(json.dumps({
+            "loaded_on_master": loaded,
+            "m4l_bridge": report["m4l_bridge"],
+            "tier": report["tier"]["active"],
+        }))
+
+asyncio.run(main())
+`;
+
+  const out = execFileSync(venvPy, ["-c", probeCode], {
+    cwd: ROOT,
+    encoding: "utf-8",
+    timeout: 15000,
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+
+  const lines = out.split(/\r?\n/).filter(Boolean);
+  return JSON.parse(lines[lines.length - 1]);
+}
+
 // ---------------------------------------------------------------------------
 // Doctor — comprehensive diagnostic
 // ---------------------------------------------------------------------------
@@ -312,6 +351,37 @@ async function doctor() {
     ok = false;
   }
 
+  // 9. Analyzer / bridge capability
+  if (connected && fs.existsSync(venvPy)) {
+    const HOST = process.env.LIVE_MCP_HOST || "127.0.0.1";
+    const PORT = parseInt(process.env.LIVE_MCP_PORT || "9878", 10);
+    const otherClient = findOtherLiveClient(HOST, PORT);
+
+    if (otherClient) {
+      console.log("  Analyzer: skipped (another LivePilot client is connected: %s)", otherClient);
+    } else {
+      try {
+        const analyzer = probeAnalyzer(venvPy);
+        if (analyzer.loaded_on_master) {
+          console.log(
+            "  Analyzer: %s",
+            analyzer.m4l_bridge.status === "ok"
+              ? "loaded on master and bridge is active"
+              : `loaded on master but bridge unavailable (${analyzer.m4l_bridge.detail})`,
+          );
+          if (analyzer.m4l_bridge.status !== "ok") {
+            ok = false;
+          }
+        } else {
+          console.log("  Analyzer: not detected on master track (optional)");
+        }
+      } catch (err) {
+        console.log("  Analyzer: could not probe (%s)", err.message || String(err));
+        ok = false;
+      }
+    }
+  }
+
   // Summary
   console.log("");
   console.log("─".repeat(50));
@@ -580,6 +650,7 @@ async function setup() {
     console.log("  3. Set Control Surface to 'LivePilot'");
     console.log("  4. Start making music with AI!");
     console.log("");
+    console.log("  Codex App:      npx livepilot --install-codex-plugin");
     console.log("  Claude Code:    claude mcp add LivePilot -- npx livepilot");
     console.log("  Claude Desktop: Already configured if using Desktop Extension");
   } else {
@@ -613,6 +684,8 @@ async function main() {
     console.log("  --setup       Full setup wizard (install + configure + test)");
     console.log("  --install     Install Remote Script into Ableton Live");
     console.log("  --uninstall   Remove Remote Script from Ableton Live");
+    console.log("  --install-codex-plugin   Install the bundled Codex plugin locally");
+    console.log("  --uninstall-codex-plugin Remove the locally installed Codex plugin");
     console.log("  --status      Check if Ableton Live is reachable");
     console.log("  --doctor      Run diagnostics (Python, deps, connection)");
     console.log("  --version     Show version");
@@ -639,6 +712,20 @@ async function main() {
     return;
   }
 
+  // --install-codex-plugin
+  if (flag === "--install-codex-plugin") {
+    const { installCodexPlugin } = require(path.join(ROOT, "installer", "codex.js"));
+    installCodexPlugin();
+    return;
+  }
+
+  // --uninstall-codex-plugin
+  if (flag === "--uninstall-codex-plugin") {
+    const { uninstallCodexPlugin } = require(path.join(ROOT, "installer", "codex.js"));
+    uninstallCodexPlugin();
+    return;
+  }
+
   // --status
   if (flag === "--status") {
     const reachable = await checkStatus();

package/installer/codex.js

@@ -0,0 +1,147 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const SOURCE_DIR = path.join(ROOT, "livepilot");
+const SOURCE_MANIFEST = path.join(SOURCE_DIR, ".Codex-plugin", "plugin.json");
+const DEFAULT_PLUGIN_DIR = path.join(os.homedir(), "plugins", "livepilot");
+const DEFAULT_MARKETPLACE_PATH = path.join(os.homedir(), ".agents", "plugins", "marketplace.json");
+
+const SKIP = new Set(["__pycache__", ".DS_Store"]);
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (SKIP.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function targetPluginDir() {
+  return process.env.LIVEPILOT_CODEX_PLUGIN_PATH || DEFAULT_PLUGIN_DIR;
+}
+
+function marketplacePath() {
+  return process.env.LIVEPILOT_CODEX_MARKETPLACE_PATH || DEFAULT_MARKETPLACE_PATH;
+}
+
+function loadManifest() {
+  if (!fs.existsSync(SOURCE_MANIFEST)) {
+    throw new Error(`Codex plugin manifest not found at ${SOURCE_MANIFEST}`);
+  }
+  return JSON.parse(fs.readFileSync(SOURCE_MANIFEST, "utf-8"));
+}
+
+function ensureMarketplace(pluginName) {
+  const file = marketplacePath();
+  let marketplace = {
+    name: "local-plugins",
+    interface: { displayName: "Local Plugins" },
+    plugins: [],
+  };
+
+  if (fs.existsSync(file)) {
+    const raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+    marketplace = {
+      name: raw.name || marketplace.name,
+      interface: raw.interface || marketplace.interface,
+      plugins: Array.isArray(raw.plugins) ? raw.plugins : [],
+    };
+  }
+
+  const entry = {
+    name: pluginName,
+    source: {
+      source: "local",
+      path: `./plugins/${pluginName}`,
+    },
+    policy: {
+      installation: "AVAILABLE",
+      authentication: "ON_INSTALL",
+    },
+    category: "Integration",
+  };
+
+  const idx = marketplace.plugins.findIndex((plugin) => plugin && plugin.name === pluginName);
+  if (idx >= 0) {
+    marketplace.plugins[idx] = entry;
+  } else {
+    marketplace.plugins.push(entry);
+  }
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(marketplace, null, 2) + "\n");
+  return file;
+}
+
+function removeMarketplaceEntry(pluginName) {
+  const file = marketplacePath();
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+
+  const raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+  const marketplace = {
+    name: raw.name || "local-plugins",
+    interface: raw.interface || { displayName: "Local Plugins" },
+    plugins: Array.isArray(raw.plugins) ? raw.plugins.filter((plugin) => plugin && plugin.name !== pluginName) : [],
+  };
+  fs.writeFileSync(file, JSON.stringify(marketplace, null, 2) + "\n");
+  return file;
+}
+
+function installCodexPlugin() {
+  const manifest = loadManifest();
+  const pluginName = manifest.name || "livepilot";
+  const destDir = targetPluginDir();
+  const marketFile = ensureMarketplace(pluginName);
+
+  console.log("Installing LivePilot Codex plugin...");
+  console.log("  Source: %s", SOURCE_DIR);
+  console.log("  Target: %s", destDir);
+  console.log("  Marketplace: %s", marketFile);
+  console.log("");
+
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
+  fs.rmSync(destDir, { recursive: true, force: true });
+  copyDirSync(SOURCE_DIR, destDir);
+
+  console.log("Done! Next steps:");
+  console.log("  1. Open or refresh Codex");
+  console.log("  2. Check that LivePilot appears in Local Plugins");
+  console.log("  3. Start a new thread or reload tools if Codex was already open");
+}
+
+function uninstallCodexPlugin() {
+  const manifest = loadManifest();
+  const pluginName = manifest.name || "livepilot";
+  const destDir = targetPluginDir();
+  const marketFile = removeMarketplaceEntry(pluginName);
+
+  if (fs.existsSync(destDir)) {
+    console.log("Removing Codex plugin: %s", destDir);
+    fs.rmSync(destDir, { recursive: true, force: true });
+  } else {
+    console.log("Codex plugin not found at %s", destDir);
+  }
+
+  if (marketFile) {
+    console.log("Updated marketplace: %s", marketFile);
+  }
+  console.log("Restart or refresh Codex to remove the plugin from the UI.");
+}
+
+module.exports = {
+  installCodexPlugin,
+  uninstallCodexPlugin,
+};

package/livepilot/.Codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.24",
-  "description": "Agentic production system for Ableton Live 12 — 293 tools, 39 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.10.1",
+  "description": "Agentic production system for Ableton Live 12 — 317 tools, 43 domains, device atlas, sample intelligence, auto-composition, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }

package/livepilot/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.24",
-  "description": "Agentic production system for Ableton Live 12 — 293 tools, 39 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.10.1",
+  "description": "Agentic production system for Ableton Live 12 — 317 tools, 43 domains, device atlas, sample intelligence, auto-composition, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }

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

@@ -47,8 +47,10 @@ Build linear song structures on the timeline.
 
 ### Creating Arrangement Clips
 
-- `create_arrangement_clip(track_index, start_time, length)` — place a new clip on the timeline at a specific beat position
+- `create_arrangement_clip(track_index, clip_slot_index, start_time, length)` — duplicate a session clip into Arrangement View at a specific beat position
+- `create_native_arrangement_clip(track_index, start_time, length)` — create arrangement clip with full automation envelope (12.1.10+)
 - `set_arrangement_clip_name(track_index, clip_index, name)` — name arrangement clips for clarity
+- `force_arrangement()` — force all tracks to play from arrangement (not session clips)
 
 ### Arrangement Notes
 
@@ -122,6 +124,21 @@ When building arrangements, use these as starting templates:
 
 Adapt these to the user's needs. Use `plan_arrangement` from the planner domain for algorithmic structure suggestions, and `transform_section` to create variations of existing sections.
 
+## Section-Aware Sample Roles
+
+`plan_arrangement` returns `sample_hints` per section — suggested roles for sample-based elements:
+
+| Section | Default Hints |
+|---------|--------------|
+| Intro | `texture_bed`, `fill_one_shot` |
+| Verse | `texture_bed`, `fill_one_shot` |
+| Build | `transition_fx`, `texture_bed` |
+| Chorus/Drop | `hook_sample`, `break_layer`, `fill_one_shot` |
+| Bridge/Breakdown | `texture_bed`, `transition_fx` |
+| Outro | `texture_bed`, `fill_one_shot` |
+
+Use `plan_sample_workflow(section_type=..., desired_role=...)` to generate concrete sample plans for each role. Use `plan_slice_workflow(intent=..., target_section=...)` for slice-based patterns.
+
 ## Composition Engine
 
 For deeper compositional analysis beyond basic arrangement:

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

@@ -1,13 +1,13 @@
 ---
 name: livepilot-core
-description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 293 tools across 39 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
+description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 317 tools across 43 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
 ---
 
 # LivePilot Core — Ableton Live 12
 
-Agentic production system for Ableton Live 12. 293 tools across 39 domains, three layers:
+Agentic production system for Ableton Live 12. 317 tools across 43 domains, three layers:
 
-- **Device Atlas** — 280+ instruments, 139 drum kits, 350+ impulse responses. Consult `references/device-atlas/` before loading any device. Never guess a device name.
+- **Device Atlas** — 1305 devices indexed (81 enriched with sonic intelligence, 683 drum kits). Consult `atlas_search` or `atlas_suggest` before loading any device. Never guess a device name.
 - **M4L Analyzer** — Real-time audio analysis on the master bus (8-band spectrum, RMS/peak, key detection). Optional — all core tools work without it.
 - **Technique Memory** — Persistent storage for production decisions. Consult `memory_recall` before creative tasks to understand user taste.
 
@@ -39,7 +39,7 @@ Agentic production system for Ableton Live 12. 293 tools across 39 domains, thre
 ## Tool Speed Tiers
 
 ### Instant (<1s) — Use freely
-All 293 tools plus M4L perception tools.
+All 317 tools plus M4L perception tools.
 
 ### Fast (1-5s) — Use freely
 `analyze_loudness` · `analyze_mix` · `analyze_sound_design`
@@ -82,6 +82,23 @@ Three modes:
 - Prefer Wonder when the user's request is emotionally-shaped, not parametric
 - Load `livepilot-wonder` skill for full workflow guidance
 
+## Creative Sound Design Knowledge
+
+Before setting device parameters, consult the knowledge corpus for informed creative choices. Read the relevant file BEFORE making changes:
+
+| User says | Read this file |
+|-----------|---------------|
+| "make it breathe" / "organic" / "alive" / "warm" / "cold" / "anxious" / "nostalgic" | `references/device-knowledge/creative-thinking.md` — emotional-to-technical mapping, physical world modeling |
+| "what effect chain for [genre]" / "dub techno" / "trap" / "SOPHIE" / "Arca" / "ambient" | `references/device-knowledge/chains-genre.md` — complete chains per genre |
+| "how to use Wavetable/Drift/Analog/Operator/Meld" | `references/device-knowledge/instruments-synths.md` — parameter-level recipes |
+| "distortion" / "saturation" / "Roar" / "Saturator" / "Redux" | `references/device-knowledge/effects-distortion.md` — every curve type, creative applications |
+| "reverb" / "delay" / "echo" / "space" / "dub" | `references/device-knowledge/effects-space.md` — dub recipes, shimmer chains |
+| "spectral" / "Resonators" / "Corpus" / "Vocoder" / "weird" / "experimental" | `references/device-knowledge/effects-spectral.md` — drum-to-melody, cross-synthesis |
+| "automate" / "evolve" / "arc" / "movement" / "filter sweep" | `references/device-knowledge/automation-as-music.md` — shapes, macro gestures, density mapping |
+| "sound design" / "make it interesting" / "more complex" | `references/sound-design-deep.md` — master techniques from Villalobos, SOPHIE, Basic Channel |
+
+**Rule:** Never set effect parameters from memory alone when the corpus has specific guidance. Read the file first, then apply the technique.
+
 ## Domain Skills
 
 For domain-specific workflows, load the appropriate skill:
@@ -111,7 +128,7 @@ Deep production knowledge in `references/`:
 
 | File | Content |
 |------|---------|
-| `references/overview.md` | All 293 tools with params and ranges |
+| `references/overview.md` | All 317 tools with params and ranges |
 | `references/device-atlas/` | 280+ device corpus with URIs and presets |
 | `references/midi-recipes.md` | Drum patterns, chord voicings, humanization |
 | `references/sound-design.md` | Synth recipes, device chain patterns |

package/livepilot/skills/livepilot-core/references/device-knowledge/00-index.md

@@ -0,0 +1,34 @@
+# Ableton Live 12 Device Knowledge Corpus
+
+Comprehensive reference for every built-in instrument and effect in Ableton Live 12. Written for an AI production assistant — parameter-level understanding, creative applications, and techniques from experimental electronic music producers.
+
+## How to Use This Corpus
+
+This is not a manual. It's a **creative knowledge base**. When the user asks to "design a sound" or "make it more interesting," consult these references to find specific parameters and techniques that achieve the goal. Don't just reach for obvious parameters — think about how SOPHIE, Arca, Villalobos, Aphex Twin, or Basic Channel would approach the same problem.
+
+## Files
+
+### Instruments
+- `instruments-synths.md` — Wavetable, Drift, Analog, Operator, Meld (synthesis engines)
+- `instruments-physical.md` — Collision, Tension, Electric (physical modeling)
+- `instruments-samplers.md` — Simpler, Sampler, Drum Rack, Drum Sampler
+
+### Effects — Processing
+- `effects-dynamics.md` — Compressor, Glue Compressor, Multiband Dynamics, Limiter, Gate, Color Limiter
+- `effects-eq-filter.md` — EQ Eight, EQ Three, Auto Filter, Channel EQ
+- `effects-distortion.md` — Saturator, Roar, Overdrive, Pedal, Amp, Cabinet, Erosion, Redux, Vinyl Distortion, Dynamic Tube, Drum Buss
+
+### Effects — Space & Time
+- `effects-reverb.md` — Reverb, Convolution Reverb, Hybrid Reverb
+- `effects-delay.md` — Delay, Echo, Grain Delay
+- `effects-modulation.md` — Chorus-Ensemble, Phaser-Flanger, Frequency Shifter, Shifter, Auto Pan-Tremolo
+
+### Effects — Spectral & Experimental
+- `effects-spectral.md` — Spectral Resonator, Spectral Time, Spectral Blur, Resonators, Corpus, Vocoder
+
+### Creative Chains
+- `chains-genre.md` — Effect chain blueprints by genre (dub techno, trap, SOPHIE-style, ambient, experimental)
+- `chains-technique.md` — Technique-specific chains (parallel processing, creative sidechain, feedback loops, resampling workflows)
+
+### Artist Techniques
+- `artist-techniques.md` — How specific artists use Ableton's built-in devices (researched from interviews, tutorials, and analysis)

package/livepilot/skills/livepilot-core/references/device-knowledge/automation-as-music.md

@@ -0,0 +1,204 @@
+# Automation as Music — The Art of Parameter Performance
+
+The greatest electronic musicians don't play notes — they play parameters. A filter cutoff automated over 64 bars IS the melody. A reverb send thrown open for one beat IS the harmony. The difference between a demo and a masterpiece is often not the sounds — it's the automation.
+
+## The Fundamental Principle
+
+**A static parameter is a dead parameter.** In acoustic music, every note is different — the player's breath, touch, and emotion create micro-variations. In electronic music, those variations must be created deliberately through automation. Every important parameter should move, even if only by 2-3%.
+
+---
+
+## Part 1: Automation Shapes and What They Mean Musically
+
+### Linear Ramps
+A straight line from value A to value B. The simplest shape. Use for:
+- **Build-ups:** Filter cutoff rising linearly over 16-32 bars before a drop
+- **Fade outs:** Volume decreasing to zero over 8-16 bars
+- **Limitation:** Linear ramps feel mechanical. Always prefer curves for musical expression.
+
+### Exponential Curves
+Slow start, accelerating change. Mimics how tension works in music — the last 4 bars contain more change than the first 12. Use for:
+- **Dramatic filter sweeps** — the ear perceives exponential change as "building"
+- **Reverb tail growth** — send level increasing exponentially creates "swelling space"
+- **Key insight:** Human perception of loudness is logarithmic, so exponential volume changes feel linear. Linear volume fades feel like they get quiet too fast at first.
+
+### S-Curves
+Slow start, fast middle, slow end. The most natural shape for transitions. Use for:
+- **Crossfades between elements** — one fades out as another fades in
+- **Filter sweeps that "settle"** — opens quickly in the middle, then gently arrives at target
+- **The Villalobos transition:** S-curve on multiple parameters simultaneously over 32 bars
+
+### Perlin Noise
+Smooth, organic randomness. Each value is related to the previous one (no sudden jumps) but the path is unpredictable. Use for:
+- **Filter cutoff drift** — sounds like a hand slowly exploring a knob
+- **Send level breathing** — reverb/delay amount fluctuates organically
+- **Oscillator detune wandering** — pitch instability that feels analog
+- **Key insight:** Perlin noise at 0.05-0.2 Hz is below conscious perception. The listener feels "alive" without knowing why.
+
+### Brownian Motion
+Random walk — each step is small but the cumulative drift can be large. More unpredictable than Perlin. Use for:
+- **Very slow parameter evolution** over minutes — the sound "wanders" like weather
+- **Stereo field drifting** — pan automation that meanders rather than oscillates
+- **Combined with manual override:** Set Brownian as a baseline, then make manual adjustments on top
+
+### Step Automation
+Discrete jumps between values. The opposite of smooth. Use for:
+- **Rhythmic gating** — volume steps creating on/off patterns (trance gate effect)
+- **Filter steps** — different cutoff per beat for rhythmic timbral changes
+- **The glitch technique:** Very fast steps (32nd or 64th note rate) on multiple parameters simultaneously = controlled chaos
+
+### Sawtooth / Triangle Automation
+Repeating rise-and-fall patterns. Use for:
+- **Pseudo-LFO on parameters that don't have built-in modulation** — draw a triangle on track volume for tremolo
+- **Rising sawtooth on filter** — creates repetitive filter sweeps that reset every bar (trance/acid)
+- **Asymmetric saw:** Fast rise, slow fall = different musical effect than slow rise, fast fall
+
+---
+
+## Part 2: What to Automate (Beyond the Obvious)
+
+Most producers only automate volume, pan, and filter cutoff. The masters automate everything.
+
+### Send Levels (The Dub Producer's Instrument)
+- **Reverb send throws** — 0→70% for half a beat, then back to 0. The element stabs into the reverb space and the tail fills the gap. King Tubby, Lee "Scratch" Perry, and Basic Channel all treat the send knob as a performance instrument.
+- **Delay send rhythmic patterns** — automate the send in a rhythmic pattern (not on every beat, but on specific accents). This creates a call-and-response between the dry and wet signals.
+- **Cross-send modulation** — automate Send A (reverb) going UP while Send B (delay) goes DOWN over 16 bars, then reverse. The spatial character morphs from "room" to "echo" and back.
+
+### Filter Resonance (Not Just Cutoff)
+- **Resonance alone** without moving cutoff — creates a subtle "emphasis" that brightens and thins the sound at the current cutoff point. Automate 15-40% range.
+- **Resonance spikes** — brief 0→80% resonance for 1 beat creates a "ring" or "ping" at the filter frequency. Musical accent.
+- **Counter-motion:** Cutoff goes down while resonance goes up — the sound gets darker but the filter "screams" more. Creates tension.
+
+### Distortion Parameters
+- **Saturator Drive automated with the beat** — drive increases on beats 2 and 4 = the mix gets grittier on the snare hits. Pull back on beats 1 and 3 for the kick to stay clean.
+- **Roar stage mix** — in Parallel mode, automate the balance between stages. Stage 1 (clean tube) dominant in verses, Stage 2 (aggressive) dominant in choruses.
+- **Erosion Amount as texture evolution** — slowly increase Erosion over a 64-bar section. The sound gradually degrades from pristine to lo-fi. The listener doesn't notice the transition — they just feel the vibe shift.
+
+### Reverb Internal Parameters
+- **Decay Time automation** — short decay (1s) during busy sections for clarity, long decay (5-8s) during breakdowns for depth. The room "breathes" with the arrangement.
+- **Reverb Freeze** — automate on/off. Freeze captures the current reverb tail as a drone. Use at section transitions: Freeze ON for 4 bars during breakdown, OFF when the beat returns.
+- **Diffusion** — low diffusion during rhythmic sections (you hear distinct echoes), high diffusion during ambient sections (smooth wash). The reverb character matches the musical energy.
+- **Pre-delay** — increase pre-delay during loud sections (separates reverb from source for clarity), decrease during quiet sections (source and reverb merge into one).
+
+### Delay Internal Parameters
+- **Feedback modulation** — push to 85% for 2 beats then pull to 50%. Creates a momentary feedback spiral that self-limits. The Dub Siren technique.
+- **Delay Time (in Repitch mode)** — changing delay time pitches the echoes. Automate a slow sweep (±10% over 8 bars) for warped, wow-and-flutter echoes. Basic Channel signature.
+- **Filter inside the delay** — automate the delay's internal filter cutoff. Each echo gets progressively darker (or brighter). Creates a natural "fading into distance" effect.
+- **Mod Freq + Dly < Mod** — automate the modulation amount. During sparse sections, increase modulation for wobbly, organic echoes. During dense sections, reduce for cleaner timing.
+
+### Synthesis Parameters You Might Not Think to Automate
+- **Wavetable Position** — LFO is obvious, but manually drawn automation tells a specific timbral story. Draw the position to follow the emotional arc: brighter wavetable positions during peaks, darker during valleys.
+- **FM Amount (Operator)** — automate the modulator level. Low during pads, spike during stabs, medium during leads. The harmonic complexity follows the musical tension.
+- **Oscillator feedback** — in Operator, automate feedback 10-40% range. Creates a sound that morphs from pure (low feedback) to gritty (high feedback) over time.
+- **Drift amount** — in Drift synth, automate the Drift parameter itself. Low Drift during precise sections, high Drift during loose, organic sections.
+- **Unison Amount** (Wavetable) — automate 0→50% over a build-up. The sound literally "widens and thickens" as the section grows. Return to 0 for a sudden "focused" impact.
+
+### Rack Chain Volumes
+- **Audio Effect Rack with multiple chains** — automate the chain selector or individual chain volumes to morph between completely different effect configurations. Chain 1: clean reverb. Chain 2: distorted delay. Chain 3: granular destruction. Crossfade between them = the sound evolves through processing states.
+- **Instrument Rack layers** — automate the chain volumes of a layered synth. Start with only the sub layer audible, gradually bring in the mid layer, then the bright layer. The sound "unfolds" from bottom to top.
+
+---
+
+## Part 3: Multi-Parameter Automation (The Macro Gesture)
+
+The most powerful automation isn't on single parameters — it's on coordinated groups that create a single musical gesture.
+
+### The "Open Up" Gesture
+Simultaneously automate over 8-16 bars:
+- Filter cutoff: 30% → 65%
+- Filter resonance: 15% → 30%
+- Reverb send: 25% → 45%
+- Stereo width (or pan spread): narrow → wide
+- **Musical meaning:** The sound "opens up" — goes from closed/intimate to wide/expansive. Use at the transition from verse to chorus, from build to drop.
+
+### The "Submerge" Gesture
+Simultaneously automate over 16-32 bars:
+- Filter cutoff: 65% → 25%
+- Reverb decay: 3s → 8s
+- Delay feedback: 40% → 70%
+- Volume: 0dB → -6dB
+- Erosion amount: 0% → 15%
+- **Musical meaning:** The sound "submerges" — sinks into depth and distance. Use at the transition into a breakdown or outro.
+
+### The "WTF" Gesture (2-4 beats only)
+Simultaneously snap:
+- Reverb send: 0% → 100% (everything washes out)
+- Delay feedback: 50% → 95% (echoes spiral)
+- Filter cutoff: current → fully open
+- Then ALL snap back to normal after 2-4 beats
+- **Musical meaning:** A moment of chaos that instantly resolves. The listener's brain says "what was THAT?" and re-engages attention.
+
+### The "Human Hand" Technique
+Record automation live (via mouse or MIDI controller) instead of drawing it. The tiny timing imperfections and non-mathematical curves create a fundamentally different feel than drawn automation. Then edit the recording — smooth the extreme mistakes but keep the organic character.
+
+This is how Villalobos works live: filter sweeps are performed, not drawn. The audience feels the human gesture even when they can't see the performer.
+
+---
+
+## Part 4: Automation Density by Section
+
+Different parts of a track need different automation density:
+
+### Intro (sparse automation)
+- 1-2 parameters moving slowly (filter, reverb send)
+- Very slow rates (0.05-0.1 Hz effective rate)
+- Purpose: establish mood, create anticipation
+
+### Build-Up (increasing density)
+- 3-5 parameters, all moving in the same "opening" direction
+- Exponential curves — change accelerates
+- Purpose: create tension and forward momentum
+
+### Peak/Drop (maximum density)
+- 5-8 parameters all active
+- Mix of slow sweeps and rhythmic modulation
+- Send throws, filter accents, distortion spikes
+- Purpose: maximum energy and interest
+
+### Breakdown (sudden reduction)
+- Drop to 1-2 parameters
+- Very slow, gentle movement
+- Purpose: contrast, breathing room, emotional reset
+
+### Outro (mirror of intro)
+- Gradually reduce automation density
+- Parameters return to starting values (or close)
+- The final automation move should be the filter closing to its lowest point
+- Purpose: the sound "returns to where it started" — cyclical, complete
+
+---
+
+## Part 5: Learning from the Masters
+
+### Villalobos: Filter as Melody
+Ricardo Villalobos automates a single lowpass filter on a pad for 8+ minutes. The filter IS the melody — it opens to reveal harmonics, closes to create tension, breathes with the groove. He never draws automation — he performs it live, which gives each performance unique character. The filter rarely moves by more than 5-10% at a time, but over 8 minutes it covers the full range.
+
+### Basic Channel: Space as Composition
+Mark Ernestus and Moritz von Oswald automate delay send levels, delay feedback, and reverb sends as their primary compositional tool. A chord stab enters the delay at 70% feedback — the echoes build up, creating a harmonic cloud. Then the feedback drops to 40% — the cloud thins and the next stab enters. The delay IS the arrangement.
+
+### Aphex Twin: Parameter Density
+Richard D. James automates dozens of parameters simultaneously at very high speed (32nd note and faster). Filter cutoffs, oscillator frequencies, effect parameters all changing independently at different rates create the "impossible complexity" that defines his sound. The key: each parameter has its own automation rate, and the rates are intentionally non-related (no multiples). This creates ever-evolving patterns that never exactly repeat.
+
+### SOPHIE: Extreme Parameter Snapshots
+SOPHIE's technique was to set up a sound, then rapidly switch between extreme parameter configurations — like snapshots. Filter fully open → fully closed in one beat. Distortion zero → maximum in one step. No smooth transitions — pure contrast. This creates the "hyperplastic" character: sounds that feel like they're being molded by an invisible force.
+
+### Boards of Canada: Decay as Atmosphere
+Marcus Eoin and Michael Sandison automate parameters to simulate degradation: filter slowly closing over minutes (tape getting worn), Vinyl Distortion amount slowly increasing (record deteriorating), subtle pitch detune growing (tape machine dying). The music doesn't just play — it deteriorates, creating the nostalgic feeling of listening to something from the past.
+
+### Amon Tobin: Micro-Edit as Expression
+Amon Tobin automates at the sample level — chopping, reordering, and processing tiny fragments of audio with rapidly changing effects. Each 16th note might have a different filter setting, different reverb amount, different distortion level. The automation IS the rhythm.
+
+---
+
+## Part 6: Wonder Mode Automation Intelligence
+
+When Wonder Mode generates variants, the automation layer is what separates "a clip arrangement" from "a musical journey." Every Wonder variant should include:
+
+1. **Filter arc** — at minimum, one element's filter should evolve over the full track length
+2. **Space arc** — reverb/delay sends should breathe with the arrangement density
+3. **Micro-modulation** — every sustained sound should have sub-perceptual LFO on at least one parameter
+4. **2-3 macro gestures** — coordinated multi-parameter moves at section transitions
+5. **1-2 WTF moments** — brief parameter disruptions that break and re-establish the hypnosis
+6. **Temporal density mapping** — automation density should follow the arrangement energy (sparse in intro/outro, dense at peaks)
+
+The automation is not optional garnish — it is the primary vehicle for musical expression in electronic music. A perfectly arranged track with no automation is a skeleton. The automation is the flesh, the breath, and the soul.