@map-audio/pam-mcp-server 1.21.0 → 1.25.0

package/dist/server.js

@@ -4,27 +4,40 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { z } from "zod";
 import { buildVariationSnapshotBase } from "./generated/variationSnapshot.js";
-import { readFile } from "node:fs/promises";
-import { existsSync, readFileSync } from "node:fs";
+import { CORPUS_META, CORPUS_RANGES } from "./corpusRanges.js";
+import { CORPUS_FINGERPRINTS, CORPUS_NOVELTY_BASELINE, CORPUS_VARIATION_BASELINE } from "./corpusFingerprints.js";
+import { buildFingerprint, scoreNovelty, similarity as fingerprintSimilarity } from "./fingerprint.js";
+import { analyzeMotion, decodeWav } from "./audioAnalysis.js";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { inflateSync } from "node:zlib";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createDrumSynthCatalog, } from "./drumSynth.js";
-import { loadManifest, cellEffectNames, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
+import { loadManifest, cellEffectNames, cellEffectOrder, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
 import { PluginBridge } from "./bridge.js";
 import { buildMixMeasurementFromState, currentFlatFromState, parseMixAnalysisPayload, suggestMix, } from "./mixAssist.js";
-import { normalizePresetLookupPath, selectSaveVariationSourcePath, } from "./presetSave.js";
+import { normalizePresetLookupPath, parsePresetFile, selectSaveVariationSourcePath, } from "./presetSave.js";
 import { STOP_SEQUENCES, buildGenerationPrompt, parseFunctionCalls, renderContextLine, renderFunctionCall, renderFunctionResponse, truncateAtFabricatedResponse, withContext, } from "./fgemma-format.js";
+import { mcpProductProfile } from "./productProfile.js";
+import { MFX_COMBO_COUNT, MFX_COMBO_MANUAL_STRENGTH, buildMfxComboTarget, isMfxComboTargetParameter, mfxComboTargetValueFromCurrent, parseMfxComboSlots, reanchorMfxComboTarget, resolveMfxCombos, setMfxComboTargetStop, } from "./mfxCombos.js";
+import { GENERATIVE_PLAYERS, LISTEN_MODES, MODULATABLE_PLAYER_FIELDS, NO_POLY_ARM, PATTERN_MODES, PLAYER_GENRES, PLAYER_NAMES, PLAYER_SLOT_FIELDS, cellPlayerType, describeCellPlayer, describePlayerSpec, getPlayerSpec, isMelodicPlayer, playerDefaultsFor, playerDensityDisplay, playerGenreConfig, playerMutateDisplay, playerPresetsFor, playerSlotDisplay, presetConfig, randomPlayerSeed, resolvePlayerPreset, resolvePlayerSpec, resolveSlotValue, rolePlayerConfigFor, roleSpreadSummary, snapPlayerValue, } from "./players.js";
+import { buildMidiFile, patternSpeedMultiplier, tilePatternEvents } from "./midiFile.js";
+import { MAX_SLICES, detectOnsetBoundaries, equalBoundaries, normalizeBoundaries } from "./sampleSlicing.js";
 // --- State ---
 // Variation slot count. Must stay in sync with PRESET_VARIATION_SLOTS in
 // interface/src/stores/Preset.ts. Defined locally because the MCP package
 // can't import from the interface workspace without infra changes.
 const PRESET_VARIATION_SLOTS = 8;
+const SERVER_PRODUCT = mcpProductProfile();
+const IS_MFX_SERVER = SERVER_PRODUCT.id === "mfx";
 const bridge = new PluginBridge();
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const cellModeChangeSeq = {};
 let lastSavedPresetName;
 let lastSavedPresetPath;
+let activeLiveResample;
 // --- Helpers ---
 function text(s) {
     return { content: [{ type: "text", text: s }] };
@@ -102,6 +115,9 @@ function validateCellIdForManifest(cellId, manifest) {
     return true;
 }
 function readPackageVersion() {
+    const override = IS_MFX_SERVER ? process.env.MFX_MCP_SERVER_VERSION?.trim() : undefined;
+    if (override)
+        return override;
     try {
         const raw = readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
         const pkg = JSON.parse(raw);
@@ -122,9 +138,9 @@ async function handleCliArgs() {
     }
     if (args.has("--help") || args.has("-h")) {
         const version = SERVER_VERSION;
-        console.log(`pam-mcp ${version}\n\n` +
-            "MCP stdio server for PAM. Configure your MCP client to launch this command; " +
-            "it reads ~/.pam-mcp-bridge.json to find a running PAM instance.");
+        console.log(`${SERVER_PRODUCT.command} ${version}\n\n` +
+            `MCP stdio server for ${SERVER_PRODUCT.name}. Configure your MCP client to launch this command; ` +
+            `it reads the local bridge registry to find a running ${SERVER_PRODUCT.name} instance.`);
         return true;
     }
     return false;
@@ -134,36 +150,55 @@ async function handleCliArgs() {
 function syncProductHint() {
     setActiveProductHint(bridge.getConnectedInstance()?.product);
 }
+function resolveServerMfxCombos(state, manifest) {
+    const instance = bridge.getConnectedInstance();
+    const cacheKey = instance?.instanceId ?? (instance ? `${instance.product}:${instance.port}` : manifest.bundleId);
+    return resolveMfxCombos(state, manifest, cacheKey);
+}
 async function requireBridge() {
     if (bridge.isConnected())
         return true;
     const ok = await bridge.connect();
     if (!ok) {
         const pin = process.env.PAM_BRIDGE_PRODUCT;
-        return error("Not connected to PAM plugin. Start PAM (standalone or in a DAW) with MCP bridge enabled. " +
-            "The bridge writes its port to ~/.pam-mcp-bridge.json on startup." +
+        return error(`Not connected to ${SERVER_PRODUCT.name}. Start ${SERVER_PRODUCT.name} (standalone or in a DAW) with MCP bridge enabled. ` +
+            (IS_MFX_SERVER
+                ? "The launcher finds MFX through the local bridge registry; the plugin records its actual port on startup."
+                : "The bridge writes its port to ~/.pam-mcp-bridge.json on startup.") +
             (pin
-                ? ` Note: PAM_BRIDGE_PRODUCT pins this server to '${pin}' — no matching instance was found (connection_status lists what is running).`
+                ? IS_MFX_SERVER
+                    ? " The MFX launcher is product-pinned, but no matching instance was found."
+                    : ` Note: PAM_BRIDGE_PRODUCT pins this server to '${pin}' — no matching instance was found (connection_status lists what is running).`
                 : ""));
     }
     syncProductHint();
     return true;
 }
 /**
- * Parse the PAM binary preset format: <metadataSize as text int><metadata JSON><data JSON>
+ * requireBridge() plus product-aware cell bounds, for tools that ADDRESS a cell.
+ *
+ * The zod schemas cap cellId at 8 because they are built before we know which
+ * product is on the other end. Cell1 has 1 cell and MFX has 4, so without this
+ * an agent aims at cell 7 and gets a bridge-level failure or a silent no-op
+ * instead of being told the cell does not exist. Read filters (get_state,
+ * get_design_overview) deliberately stay unguarded — returning only the cells
+ * that exist is the right answer there. Manifests are cached, so this is
+ * effectively free after the first call.
  */
-function parsePresetFile(raw) {
-    const sizeMatch = raw.match(/^(\d+)/);
-    if (!sizeMatch)
-        throw new Error("invalid format (no metadata size prefix)");
-    const prefixLen = sizeMatch[1].length;
-    const metadataSize = parseInt(sizeMatch[1], 10);
-    if (metadataSize <= 0 || prefixLen + metadataSize > raw.length) {
-        throw new Error(`invalid format (metadata size ${metadataSize} out of bounds for file length ${raw.length})`);
-    }
-    const metadataStr = raw.slice(prefixLen, prefixLen + metadataSize);
-    const dataStr = raw.slice(prefixLen + metadataSize);
-    return { metadata: JSON.parse(metadataStr), data: JSON.parse(dataStr) };
+async function requireBridgeForCells(...cellIds) {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const ids = cellIds.flat().filter((c) => typeof c === "number");
+    if (ids.length === 0)
+        return true;
+    const manifest = await loadManifestForProductGuard();
+    for (const id of new Set(ids)) {
+        const cellCheck = validateCellIdForManifest(id, manifest);
+        if (cellCheck !== true)
+            return cellCheck;
+    }
+    return true;
 }
 // PAM ≥ 1.4.61 stores variations ONLY in the data block, zlib+base64-compressed with a
 // "PAMZ1:" marker (see helpers/VariationCodec.h). Decompress one entry to plain JSON;
@@ -194,20 +229,17 @@ function variationsFromParsedPreset(parsed) {
         return Array(PRESET_VARIATION_SLOTS).fill(null);
     return src.map(decompressVariationEntry);
 }
-/**
- * Read existing variations array from a preset file on disk.
- * Returns Array(8) of plain-JSON strings or nulls.
- */
-async function readExistingVariations(presetPath) {
+async function readPresetForSave(presetPath, allowMissing = false) {
+    let fullPath;
     try {
-        const fullPath = await resolvePresetPath(presetPath);
-        const raw = await readFile(fullPath, "utf-8");
-        return variationsFromParsedPreset(parsePresetFile(raw));
+        fullPath = await resolvePresetPath(presetPath);
     }
-    catch {
-        // Preset doesn't exist yet or can't be read — start fresh
-        return Array(PRESET_VARIATION_SLOTS).fill(null);
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return null;
+        throw error;
     }
+    return parsePresetFile(await readFile(fullPath));
 }
 const VARIATION_CONTRACT = (() => {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -247,6 +279,7 @@ const VARIATION_EXCLUDED_PARAMS = [
 function buildVariationString(state) {
     return JSON.stringify(buildVariationSnapshotBase(state, {
         sessionKeys: VARIATION_EXCLUDED_PARAMS,
+        transientKeys: VARIATION_CONTRACT.transientDispatchKeys ?? [],
         visualParamIds: VARIATION_CONTRACT.visualParamIds ?? [],
         lfoGeneratorCount: VARIATION_CONTRACT.lfoGeneratorCount ?? 6,
     }));
@@ -261,17 +294,23 @@ function buildVariationString(state) {
  * so the save result can say the snapshot is lossy.
  */
 async function fetchSaveSnapshot() {
+    let state;
+    let canonical = false;
     try {
         const snap = await bridge.send("getSaveSnapshot");
         if (snap && typeof snap === "object") {
-            return { state: snap, canonical: true };
+            state = snap;
+            canonical = true;
+        }
+        else {
+            state = (await bridge.send("getState"));
         }
     }
     catch {
         // Older PAM: action not registered. Fall through.
+        state = (await bridge.send("getState"));
     }
-    const state = (await bridge.send("getState"));
-    return { state, canonical: false };
+    return { state, canonical };
 }
 /** Cells whose hosted plugin this snapshot cannot fully capture. */
 function hostedPluginCells(state) {
@@ -316,14 +355,9 @@ function formatParam(p) {
     return desc;
 }
 const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
-// Cell effects are derived per product from the manifest (`cellEffectNames`) —
-// this constant is only the fallback for a manifest that failed to load. The
-// hardcoded eight it used to be is why get_design_overview under-reported:
-// limiter, qverb, eq8, panner, gain, vocoder (and MFX's wavefold/resonator)
-// were enabled in state but absent from `enabledEffects`.
-const CELL_EFFECTS_FALLBACK = [
-    "filter", "delay", "crusher", "flanger", "eq", "fdn", "gate", "compressor",
-];
+// Preset listings grow with every installed pack; cap the unfiltered dump so it
+// can't crowd out the agent's context (`search` narrows it).
+const LIST_PRESETS_MAX = 400;
 const PATTERN_LANES = {
     note: "midiSequence",
     pitch: "pitchSequence",
@@ -339,6 +373,10 @@ const LFO_DIVISIONS = [
     "1/32D", "1/32", "1/32T",
     "1/64D", "1/64", "1/64T",
 ];
+// Index/enum params. derive-corpus-ranges.mjs skips them (a percentile over an
+// index means nothing), so design_context must not read their missing corpus
+// row as "no preset ever used this". Keep in sync with ENUMISH in that script.
+const CORPUS_ENUM_PARAMS = /^(mode|filterType|arpegMode|gateProgram|synthEngine|outputMode|outputIndex|crossfadeAssign|grainWindow|grainArp|fmSource|fmPolarity|gainClipMode|patternDirection|quantRoot|quantScale|.*SyncEnabled|.*Enabled)$/;
 function levenshtein(a, b) {
     const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
     const curr = Array(b.length + 1).fill(0);
@@ -526,55 +564,18 @@ function stemName(path) {
 }
 // --- Server ---
 const server = new McpServer({
-    name: "pam",
-    title: "PAM Audio Sampler",
+    name: SERVER_PRODUCT.id,
+    title: SERVER_PRODUCT.serverTitle,
     version: SERVER_VERSION,
 }, {
-    instructions: "PAM is an audio sampler plugin. Start design/read work with design_context (curated param " +
-        "cheat sheet) and get_design_overview (compact live snapshot) instead of full get_state or " +
-        "broad get_parameter_info; when you need detail, call get_state with section/keys/cellIds filters. " +
-        "When browsing samples, ALWAYS call get_default_locations " +
-        "first to discover the user's actual library paths — never guess paths like ~/Music/PAM. " +
-        "The sample library lives under ~/Library/Application Support/, NOT ~/Music/. " +
-        "Use the returned paths with list_samples. When loading samples, use load_sample with " +
-        "paths from list_samples. Transport must be playing for sequencer output. " +
-        "To enable experimental features (plugin host, AI engines) call update_settings with both " +
-        "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true). " +
-        "The standard Drum Synth UI follows drumSynthEnabled (default true); this preference does not mute synth audio. " +
-        "set_mfx_routing is the MFX cable patchbay and errors on PAM/Cell1; set_audio_device is standalone-only. " +
-        "Tools added in server version 1.7.0 — update_settings, configure_transport, " +
-        "get_audio_device_setup, set_midi_io, set_midi_mapping, delete_preset, " +
-        "set_preset_factory_status, get_sample_usage, repair_preset_samples, preview_sample, " +
-        "set_plugin_params, skip_current_plugin_scan, remove_plugin_from_blocklist — require PAM ≥ 1.7.0. " +
-        "VX video tools (get_video_state, video_command, add_video_layer, update_video_layer, " +
-        "remove_video_layer, apply_video_layout, add_video_fx, set_video_fx, remove_video_fx, " +
-        "bind_video_param, set_video_settings, set_video_layer_source) require PAM ≥ 1.8.0 AND PAM's window to be OPEN " +
-        "(the video engine renders in the WebView; there is no headless renderer). " +
-        "capture_ui, set_visual, set_drum_synth_wave, and randomize with target 'synth' are " +
-        "WebView-routed too and need the window open for the same reason. For " +
-        "audio-reactive control, note the visual audio-react params (visualWaveDisplace, etc.) " +
-        "are regular plugin params — drive them with set_parameters; layers/FX/bindings go through " +
-        "the video tools. When building a scene, call get_video_state first to learn layer/fx ids. " +
-        "AI model lifecycle tools (download_model, get_model_status, load_model, unload_model, " +
-        "delete_model, list_models; engines aigen|magenta|notochord) require PAM ≥ 1.9.0 plus the " +
-        "matching experimental flags; load/unload/delete can block for seconds — poll " +
-        "get_model_status rather than tight-looping. " +
-        "Earlier tool sets (looper, song mode, modulation edits, MIDI recording, sample analysis, " +
-        "live resample, variation scheduling, AI generation) require PAM ≥ 1.5.0. " +
-        "SONG WORKFLOW: author sections as variation slots (save_variation), arrange them with " +
-        "song_mode (op setArrangement authors real Song Mode grid nodes and can pin a VX variation " +
-        "slot per section via vxVariationIndex; op setSequence is the older headless raw-step path), " +
-        "manage visual variation slots with vx_variation (save/load/clear/fill — the VX siblings of " +
-        "save_variation), then bounce with export_song (includeVideo:true films the VX scene with " +
-        "variation follow live). song_mode setArrangement/get/assignVx, vx_variation, and " +
-        "export_song includeVideo are WebView-routed (window open, PAM ≥ 1.5.7). " +
-        "If a tool fails with \"PAM build does not support 'X'\", the connected plugin is older than " +
-        "this MCP server; the user must update PAM (updating the npm package alone is not enough). " +
-        "Tool annotations are accurate: readOnlyHint tools never mutate the plugin, destructiveHint " +
-        "tools discard user state (confirm intent before calling them). When several product " +
-        "instances run at once (PAM + MFX), select_instance chooses which one the live tools drive " +
-        "(PAM_BRIDGE_PRODUCT pins it at launch). Guided workflow prompts are available: build-a-beat, " +
-        "make-a-song, design-a-preset, mix-and-master, troubleshoot-bridge.",
+    instructions: IS_MFX_SERVER
+        ? "MFX is a four-cell modular FX router: cells are patched with cables and each cell runs its own effect chain. " +
+            "Use cells 1-4. Treat tool annotations as authoritative and use select_instance when several products are running."
+        : "PAM is an eight-cell sampler. " +
+            "Sequencer output requires a running transport. UI, video, and visual tools require the plugin " +
+            "window open; experimental plugin-host and AI tools require experimentalMode plus the matching " +
+            "feature flag. Treat tool annotations as authoritative and use select_instance when several " +
+            "products are running. A 'build does not support' error means update the plugin, not only this server.",
 });
 // --- tool annotation policy ---------------------------------------------------
 // Single audit surface for MCP tool annotations. Every tool MUST have an entry;
@@ -598,19 +599,24 @@ const TOOL_ANNOTATIONS = {
     read_preset: RO,
     get_manifest_summary: RO,
     design_context: RO,
+    preset_novelty: RO,
+    variation_distinctness: RO,
+    analyze_motion: W,
     get_state: RO,
     get_design_overview: RO,
     get_transport: RO,
     get_master_analysis: RO,
-    suggest_mix: RO, // pure function over cached analysis + current state
+    suggest_mix: W,
     connection_status: RO,
+    situation: RO,
     list_samples: RO,
     get_default_locations: RO,
     get_audio_info: RO,
     get_video_state: RO,
-    capture_ui: RO, // writes a screenshot file, mutates no plugin state
+    capture_ui: WI,
     get_sample_peaks: RO,
     get_audio_device_setup: RO,
+    get_memory_report: RO,
     get_sample_usage: RO,
     get_model_status: RO,
     list_models: RO,
@@ -640,6 +646,11 @@ const TOOL_ANNOTATIONS = {
     remove_param_seq: DI,
     set_drum_synth: WI,
     set_drum_synth_wave: WI,
+    list_players: RO,
+    set_player: WI,
+    set_slices: WI,
+    set_free_sequencer: WI,
+    export_midi: W,
     stop_cell: WI,
     reset_cell: DI,
     copy_cell: DI, // overwrites the destination cell
@@ -659,6 +670,7 @@ const TOOL_ANNOTATIONS = {
     midi_recording: W,
     // Presets / variations
     load_preset: DI, // replaces the working state (unsaved edits are lost)
+    get_preset_load_status: RO,
     save_preset: WI,
     new_preset: DI,
     import_preset: WI,
@@ -698,7 +710,7 @@ const TOOL_ANNOTATIONS = {
     looper_settings: WI,
     looper_variation: W,
     looper_variation_sync: WI,
-    live_resample: W,
+    live_resample: D, // finalize replaces the destination cell; finalize:false discards the take
     // Song mode / export
     song_mode: W,
     export_song: W,
@@ -707,6 +719,9 @@ const TOOL_ANNOTATIONS = {
     update_settings: WI,
     set_audio_device: WI,
     set_mfx_routing: WI,
+    set_mfx_edge_gain: WI,
+    configure_mfx_combo: WI,
+    set_effect_order: WI,
     set_midi_io: WI,
     set_midi_mapping: WI,
     // Plugin host
@@ -746,7 +761,7 @@ const TOOL_ANNOTATIONS = {
     set_video_fx: WI,
     remove_video_fx: DI,
     bind_video_param: WI,
-    set_video_settings: WI,
+    set_video_settings: D, // resetWorkspace:true clears the scene
     vx_variation: W,
     // Connection management
     select_instance: WI,
@@ -755,18 +770,231 @@ const TOOL_ANNOTATIONS = {
     ask_assistant: D, // executes arbitrary model-chosen tool calls
 };
 const internalTools = new Map();
+// The shared implementation contains sampler, song, video, AI, hosted-
+// instrument, and MFX operations. A dedicated MFX launcher must not advertise
+// sampler workflows merely because their handlers live in this file: tool
+// discovery is part of the product contract, not an implementation inventory.
+const MFX_TOOL_NAMES = new Set([
+    "get_parameter_info",
+    "list_presets",
+    "read_preset",
+    "get_manifest_summary",
+    "design_context",
+    "variation_distinctness",
+    "analyze_motion",
+    "get_state",
+    "get_design_overview",
+    "get_transport",
+    "connection_status",
+    "situation",
+    "get_default_locations",
+    "capture_ui",
+    "get_memory_report",
+    "set_parameters",
+    "add_modulation",
+    "update_modulation",
+    "clear_modulations",
+    "update_effect_config",
+    "update_cell_config",
+    "set_cell_mute",
+    "set_master_effects",
+    "add_param_seq",
+    "update_param_seq",
+    "remove_param_seq",
+    "set_free_sequencer",
+    "stop_cell",
+    "reset_cell",
+    "copy_cell",
+    "start_transport",
+    "stop_transport",
+    "full_stop_transport",
+    "set_bpm",
+    "set_metronome",
+    "configure_transport",
+    "load_preset",
+    "get_preset_load_status",
+    "save_preset",
+    "new_preset",
+    "import_preset",
+    "export_preset",
+    "update_preset_metadata",
+    "delete_preset",
+    "set_preset_factory_status",
+    "load_variation",
+    "save_variation",
+    "queue_variation",
+    "cancel_queued_variation",
+    "update_variations",
+    "variation_hold",
+    "export_audio",
+    "update_settings",
+    "get_audio_device_setup",
+    "set_audio_device",
+    "set_mfx_routing",
+    "set_mfx_edge_gain",
+    "configure_mfx_combo",
+    "set_effect_order",
+    "set_midi_io",
+    "set_midi_mapping",
+    "select_instance",
+]);
+function mfxSurfaceText(value) {
+    return value
+        // MFX has its own version line, so a PAM version gate names a build MFX never reaches.
+        .replace(/PAM ?(?:≥|>=) ?\d+(?:\.\d+)*/g, "a current MFX build")
+        .replaceAll("a PAM build", "an MFX build")
+        .replaceAll(" saved via set_visual", "")
+        .replaceAll(" Check corr in get_master_analysis after widening.", "")
+        .replaceAll(" (same constraint as the video tools)", "")
+        .replaceAll("so the preset_novelty scale does", "so a whole-preset novelty scale does")
+        .replaceAll("PAM/Cell1-only", "sampler-product-only")
+        .replaceAll("PAM/Cell1", "sampler products")
+        .replaceAll("PAM-only", "sampler-product-only")
+        .replaceAll("PAM's", "MFX's")
+        .replaceAll("PAM", "MFX");
+}
+const MFX_MAX_CELL = 4;
+// Zod wrappers are immutable, so narrowing a leaf means rebuilding the
+// optional/default/array/union chain around it and re-attaching the description.
+function rebuildSchema(schema, narrowLeaf) {
+    const def = schema._zod?.def;
+    const keepText = (next) => (schema.description ? next.describe(schema.description) : next);
+    const inner = () => rebuildSchema(def.innerType, narrowLeaf);
+    switch (def?.type) {
+        case "optional":
+            return keepText(inner().optional());
+        case "nullable":
+            return keepText(inner().nullable());
+        case "default":
+            return keepText(inner().default(def.defaultValue));
+        case "array":
+            return keepText(z.array(rebuildSchema(def.element, narrowLeaf)));
+        case "union":
+            return keepText(z.union(def.options.map((option) => rebuildSchema(option, narrowLeaf))));
+        default:
+            return keepText(narrowLeaf(schema));
+    }
+}
+function schemaKind(schema) {
+    return schema._zod?.def?.type;
+}
+const capCellId = (leaf) => schemaKind(leaf) === "number" ? leaf.max(MFX_MAX_CELL) : leaf;
+const dropEnumMembers = (drop) => (leaf) => {
+    if (schemaKind(leaf) !== "enum")
+        return leaf;
+    const entries = leaf._zod.def.entries;
+    const kept = Object.values(entries).filter((value) => !drop.includes(value));
+    return z.enum(kept);
+};
+// MFX ships four cells and the shared schemas advertise PAM's eight. The runtime
+// guard is manifest-driven; this is the advertised half of the same contract.
+const MFX_CELL_FIELDS = new Set([
+    "cellId",
+    "sourceCellId",
+    "targetCellId",
+    "cellIds",
+    "selectedCellIds",
+    "sidechainFrom",
+]);
+// Enum members MFX has no surface for: Vary is removed from its modulation stack,
+// and neither song_mode nor a looper tool is registered on this launcher.
+const MFX_ENUM_DROPS = {
+    add_modulation: { type: ["vary"] },
+    get_state: { section: ["vary", "loopers", "songMode"] },
+    export_audio: { mode: ["song-mode"] },
+};
+const MFX_KEPT_FIELDS = {
+    update_cell_config: ["cellId", "sidechainFrom"],
+};
+const MFX_DROPPED_FIELDS = {
+    select_instance: ["product"],
+    // MFX cells are effect slots — there is no synth/sampler tab to switch.
+    capture_ui: ["instrumentView"],
+};
+const MFX_TOOL_DESCRIPTIONS = {
+    select_instance: "Choose which running MFX instance the live tools drive. Match by instanceId or port from connection_status. The launcher refuses non-MFX instances.",
+    update_cell_config: "Set one MFX cell's sidechain source. A non-null source also enables that cell's compressor.",
+    capture_ui: "Render MFX's plugin UI (#app_root) to a PNG via html2canvas and return the saved file path (read it to " +
+        "view the image). Optionally compose the view first: gridSize (1 or 4), mainView (CellGrid|MfxRouting|" +
+        "CtrlAll|Envelope|LFO|ParamSeq|Mixer|PresetBrowser; omit/null = cell grid). REQUIRES MFX's window OPEN — " +
+        "html2canvas needs the live DOM, there is no headless renderer. Beats screen-capture: deterministic, no " +
+        "cursor/screen control, exact UI bitmap. View arguments switch the live editor and the previous view is " +
+        "not restored.",
+};
+const MFX_FIELD_DESCRIPTIONS = {
+    capture_ui: { gridSize: "Cell grid size to set before capture: 1 or 4." },
+    export_audio: { bars: "Bars to render." },
+    add_modulation: {
+        cellId: "Required for envelope: source cell driving the follower (1-4). This is not the target cell; target is inferred from paramId.",
+    },
+};
+// Text whose subject is a tool this launcher does not register.
+function mfxDescriptionEdits(name, value) {
+    if (name === "export_audio")
+        return value
+            .replace("Set `mode` to bounce stems or the whole Song Mode arrangement.", "Set `mode` to bounce per-cell or per-bus stems.")
+            .replace(" · 'song-mode' (the Song Mode timeline)", "")
+            .replace(/\n\nNOTE on 'song-mode':[\s\S]*$/, "");
+    if (name === "analyze_motion")
+        return value.replace("Fills the gap left by get_master_analysis (loudness) and get_mix_analysis (aggregate spectrum + onset " +
+            "density), neither of which can tell a modulated preset from a static one.", "No other tool on this surface can tell a modulated preset from a static one.");
+    if (name === "set_master_effects")
+        return value.replace("Check results with get_master_analysis (keep tp <= -1 dBTP, PSR >= 8 in the loudest section). ", "Aim for tp <= -1 dBTP and PSR >= 8 in the loudest section; no loudness analysis tool is registered on this surface. ");
+    if (name === "set_parameters")
+        return (value +
+            " Writing mfx_combo1, mfx_combo2 or mfx_combo3 also fans the value out to that combo's resolved target " +
+            "parameters, unless one of those targets is written in the same call.");
+    return value;
+}
+function mfxToolConfig(name, config) {
+    const source = config;
+    const kept = MFX_KEPT_FIELDS[name];
+    const droppedFields = MFX_DROPPED_FIELDS[name] ?? [];
+    const enumDrops = MFX_ENUM_DROPS[name] ?? {};
+    const fieldText = MFX_FIELD_DESCRIPTIONS[name] ?? {};
+    const inputSchema = source.inputSchema
+        ? Object.fromEntries(Object.entries(source.inputSchema)
+            .filter(([key]) => (!kept || kept.includes(key)) && !droppedFields.includes(key))
+            .map(([key, schema]) => {
+            let narrowed = schema;
+            if (enumDrops[key])
+                narrowed = rebuildSchema(narrowed, dropEnumMembers(enumDrops[key]));
+            if (MFX_CELL_FIELDS.has(key))
+                narrowed = rebuildSchema(narrowed, capCellId);
+            const described = fieldText[key] ??
+                (narrowed.description
+                    ? mfxSurfaceText(MFX_CELL_FIELDS.has(key)
+                        ? narrowed.description.replaceAll("1-8", "1-4").replaceAll("1..8", "1..4")
+                        : narrowed.description)
+                    : undefined);
+            return [key, described ? narrowed.describe(described) : narrowed];
+        }))
+        : undefined;
+    const description = MFX_TOOL_DESCRIPTIONS[name] ??
+        (source.description ? mfxSurfaceText(mfxDescriptionEdits(name, source.description)) : undefined);
+    return {
+        ...source,
+        ...(description ? { description } : {}),
+        ...(inputSchema ? { inputSchema } : {}),
+    };
+}
 {
     const origRegisterTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, handler) => {
-        internalTools.set(name, { shape: config.inputSchema, handler });
+        // Registration handles are never retained by this module; omitted product
+        // tools therefore have no runtime handle to return.
+        if (IS_MFX_SERVER && !MFX_TOOL_NAMES.has(name))
+            return undefined;
+        const productConfig = (IS_MFX_SERVER ? mfxToolConfig(name, config) : config);
+        internalTools.set(name, { shape: productConfig.inputSchema, handler });
         // Merge the central annotation policy. Inline annotations at the call site
         // win per key; openWorldHint is false server-wide (local plugin only).
-        const cfg = config;
+        const cfg = productConfig;
         if (!TOOL_ANNOTATIONS[name]) {
-            console.error(`[pam-mcp] tool '${name}' has no TOOL_ANNOTATIONS entry — classify it (check-tool-surface fails on this)`);
+            console.error(`[${SERVER_PRODUCT.command}] tool '${name}' has no TOOL_ANNOTATIONS entry — classify it (check-tool-surface fails on this)`);
         }
         cfg.annotations = { openWorldHint: false, ...TOOL_ANNOTATIONS[name], ...cfg.annotations };
-        return origRegisterTool(name, config, handler);
+        return origRegisterTool(name, productConfig, handler);
     });
 }
 async function callInternalTool(name, args) {
@@ -872,7 +1100,7 @@ server.registerTool("get_parameter_info", {
 });
 server.registerTool("list_presets", {
     title: "List Presets",
-    description: "List available PAM presets (factory and user).",
+    description: "List available PAM presets (factory and user) as an array of {name, path}. Above 400 matches it returns {presets, total, truncated, hint} instead — narrow with `search` rather than paging.",
     inputSchema: {
         search: z.string().optional().describe("Filter presets by name."),
     },
@@ -892,7 +1120,20 @@ server.registerTool("list_presets", {
     }
     if (allPresets.length === 0)
         return text("No presets found.");
-    return json(allPresets.map((p) => ({ name: p.name, path: p.relativePath })));
+    // A pack-heavy library runs to thousands of entries and would swamp the
+    // agent's context. `search` is the narrowing control — it is already in the
+    // FunctionGemma toolpack schema, so this stays an output-side cap and the
+    // inputSchema does not drift. The plain array shape is preserved unless the
+    // cap actually bites, so normal libraries see exactly what they saw before.
+    const entries = allPresets.map((p) => ({ name: p.name, path: p.relativePath }));
+    if (entries.length <= LIST_PRESETS_MAX)
+        return json(entries);
+    return json({
+        presets: entries.slice(0, LIST_PRESETS_MAX),
+        total: entries.length,
+        truncated: entries.length - LIST_PRESETS_MAX,
+        hint: "Pass `search` to narrow the list — only the first entries are shown.",
+    });
 });
 server.registerTool("read_preset", {
     title: "Read Preset",
@@ -974,8 +1215,11 @@ server.registerTool("get_manifest_summary", {
 });
 server.registerTool("design_context", {
     title: "Design Context",
-    description: "Compact parameter-design cheat sheet for agents: macro targets, per-effect key params, musical ranges, " +
-        "unit notes, LFO/delay division hints, MIDI cell note map, and variation slot semantics.",
+    description: "Compact parameter-design cheat sheet for agents: the product's global controls and full per-cell effect vocabulary, " +
+        "value bands measured from the " +
+        "shipped factory presets, an underexplored-parameter list, macro targets, unit traps, LFO/delay division " +
+        "tables, FX chain order, MIDI cell note map, and variation slot semantics. The bands describe where " +
+        "shipped presets sit — they are not limits, and the distinctive end of a range is usually outside them.",
     inputSchema: {
         cellId: z
             .number()
@@ -984,13 +1228,73 @@ server.registerTool("design_context", {
             .max(8)
             .default(1)
             .describe("Cell number to use for per-cell example param IDs. Defaults to cell 1."),
+        groups: z
+            .array(z.string())
+            .optional()
+            .describe("Narrow keyPerCellParams to these groups (e.g. ['delay','vocoder']). " +
+            "Omit it to get the full per-cell vocabulary."),
     },
     annotations: { readOnlyHint: true },
-}, async ({ cellId }) => {
+}, async ({ cellId, groups: groupFilter }) => {
     const manifest = await loadManifest();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
     const params = manifest.parameters;
+    const defaultEffectOrder = cellEffectOrder(manifest);
     const byId = new Map(params.map((p) => [p.paramId, p]));
     const example = (suffix) => byId.get(`cell${cellId}_${suffix}`)?.paramId ?? `cell${cellId}_${suffix}`;
+    if (IS_MFX_SERVER) {
+        const requestedGroups = groupFilter?.length ? new Set(groupFilter) : null;
+        const effectGroups = Object.fromEntries(cellEffectNames(manifest).filter((effect) => !requestedGroups || requestedGroups.has(effect)).map((effect) => [
+            effect,
+            params
+                .filter((parameter) => parameter.cell === `cell${cellId}` && parameter.effect === effect)
+                .map((parameter) => parameter.paramId),
+        ]));
+        return json({
+            product: manifest.name,
+            architecture: "Four effect cells connected by a replaceable cable graph.",
+            cells: [1, 2, 3, 4],
+            routing: {
+                tool: "set_mfx_routing",
+                gainTool: "set_mfx_edge_gain",
+                ports: {
+                    sources: ["input", "sidechain", "cell1..cell4", "split_lo", "split_mid", "split_hi"],
+                    destinations: ["cell1..cell4", "split", "output"],
+                },
+                serialExample: [
+                    { from: "input", to: "cell1" },
+                    { from: "cell1", to: "cell2" },
+                    { from: "cell2", to: "cell3" },
+                    { from: "cell3", to: "cell4" },
+                    { from: "cell4", to: "output" },
+                ],
+                splitParameters: ["mfx_split_lo_hz", "mfx_split_hi_hz"],
+            },
+            combos: {
+                tool: "configure_mfx_combo",
+                parameters: ["mfx_combo1", "mfx_combo2", "mfx_combo3"],
+                roles: ["Morph", "Color", "Motion"],
+                note: "The tool resolves automatic assignments, edits targets and labels, locks assignments, and fans combo values out while the MFX window is closed.",
+            },
+            globalParameters: params
+                .filter((parameter) => !parameter.cell && parameter.paramId.startsWith("mfx_"))
+                .map((parameter) => parameter.paramId),
+            effectOrder: {
+                tool: "set_effect_order",
+                paramId: `cell${cellId}_effectOrder`,
+                defaultOrder: defaultEffectOrder,
+            },
+            keyPerCellParams: effectGroups,
+            parameterRanges: "Call get_parameter_info with a paramId above for its exact range, default, unit, and enum labels.",
+            modulation: {
+                tools: ["add_modulation", "update_modulation", "clear_modulations", "add_param_seq"],
+                note: "Target the cell effect parameters above or the three combo parameters.",
+            },
+            variationSlots: "API indices are 0..7.",
+        });
+    }
     const macroTargetsByEffect = {};
     for (const p of params.filter((param) => param.paramId.startsWith("macro_") && param.isModulatable)) {
         const key = p.effect ?? "global";
@@ -1014,39 +1318,131 @@ server.registerTool("design_context", {
         ["1/32", 18, 0.818],
         ["1/64", 21, 0.955],
     ].map(([division, index, value]) => ({ division, index, lfoRate: value }));
+    // Terse corpus band for one param suffix. Reports where the shipped
+    // presets actually sit AND how much of the legal span they leave unused —
+    // the second number is the one that matters when the brief is "make it
+    // sound like nothing we've shipped".
+    const band = (suffix) => {
+        const r = CORPUS_RANGES[suffix];
+        if (!r)
+            return undefined;
+        const headroom = r.spanUsedPct < 60 ? ` — corpus only visits ${r.spanUsedPct}% of the legal span` : "";
+        return `typical ${r.p10}..${r.p90} (median ${r.p50}); corpus ${r.lo}..${r.hi}; legal ${r.legal[0]}..${r.legal[1]}; default ${r.def}${headroom}`;
+    };
+    // Attach bands to a group's param IDs so one lookup answers both "what is
+    // the ID" and "what value is musical".
+    const group = (...suffixes) => Object.fromEntries(suffixes.map((s) => [example(s), band(s) ?? "no corpus data — use get_parameter_info for the legal range"]));
+    const wanted = groupFilter?.length ? new Set(groupFilter) : null;
+    const pick = (all) => wanted ? Object.fromEntries(Object.entries(all).filter(([k]) => wanted.has(k))) : all;
+    // Params the corpus barely explores. Presented as opportunity, not as a
+    // warning: an agent that only ever writes values inside the dense part of
+    // the distribution reproduces the average shipped preset by construction.
+    const underexplored = Object.entries(CORPUS_RANGES)
+        .filter(([, r]) => r.spanUsedPct < 55 || r.distinct <= 8)
+        .sort((a, b) => a[1].spanUsedPct - b[1].spanUsedPct)
+        .map(([k, r]) => `${k}: corpus uses ${r.lo}..${r.hi} of ${r.legal[0]}..${r.legal[1]} (${r.distinct} distinct values)`);
+    // Params with no corpus row at all — no shipped preset has ever moved them.
+    // Enable flags, sync toggles and the per-band EQ8 grid are excluded because
+    // they are switches and a 49-row template, not sound-design dials.
+    const neverUsed = params
+        .filter((p) => p.paramId.startsWith(`cell${cellId}_`))
+        .map((p) => p.paramId.slice(`cell${cellId}_`.length))
+        .filter((s) => !CORPUS_RANGES[s] &&
+        // Enum/index params carry no corpus row because a percentile over an
+        // index is meaningless — their absence is not evidence of disuse.
+        !CORPUS_ENUM_PARAMS.test(s) &&
+        !s.startsWith("eq8_") &&
+        !s.startsWith("magenta") &&
+        !/^synth_p[4-8]$/.test(s))
+        .sort();
     return json({
         product: manifest.name,
         exampleCell: cellId,
         macroTargetsByEffect,
-        keyPerCellParams: {
-            mixer: [example("volume"), example("pan"), example("gainGain")],
-            filter: [example("filterCutoff"), example("filterQ"), example("filterType")],
-            delay: [example("delayDelayTime"), example("delayFeedback"), example("delayTilt"), example("delayMix")],
-            crusher: [example("crusherBitReduction"), example("crusherRateReduction"), example("crusherDrive"), example("crusherMix")],
-            fdn: [example("fdnSize"), example("fdnFeedback"), example("fdnModDepth"), example("fdnMix")],
-            gate: [example("gateTime"), example("gateProgram"), example("gateMix")],
-            compressor: [example("compressorThreshold"), example("compressorRatio"), example("compressorAttack"), example("compressorRelease")],
-            drumSynth: [example("synthEngine"), example("synthVolume"), example("synth_p1"), example("synth_p2"), example("synth_p3")],
-        },
+        // Ordered roughly by how much each group changes the character of a
+        // sound. The sampler group is first because startPos/endPos/pitchShift
+        // are the three most actively-designed params in the whole factory
+        // corpus — chopping and re-tuning the source moves a preset further than
+        // any amount of downstream FX.
+        keyPerCellParams: pick({
+            sampler: group("startPos", "endPos", "cutFrom", "fadeIn", "fadeOut", "mode"),
+            pitch: group("pitchShift", "stretch", "arpeg", "arpegMode"),
+            envelope: group("envAttack", "envGain", "envRelease"),
+            retrigger: group("retrigger", "retriggerDelay"),
+            groove: group("patternSwing"),
+            mixer: group("volume", "pan", "gainGain"),
+            filter: group("filterCutoff", "filterQ", "filterType"),
+            eq: group("eqLowGain", "eqLowMidFreq", "eqMidGain", "eqMidHighFreq", "eqHighGain"),
+            delay: group("delayDelayTime", "delayFeedback", "delayTilt", "delayMix"),
+            flanger: group("flangerMix", "flangerTime", "flangerFeedback", "flangerFreq", "flangerSyncEnabled"),
+            crusher: group("crusherBitReduction", "crusherRateReduction", "crusherDrive", "crusherMix"),
+            fdn: group("fdnSize", "fdnFeedback", "fdnModDepth", "fdnMix"),
+            gate: group("gateTime", "gateProgram", "gateMix"),
+            compressor: group("compressorThreshold", "compressorRatio", "compressorAttack", "compressorRelease"),
+            panner: group("pannerBalance", "pannerWidth"),
+            clip: group("gainClip", "gainClipMode"),
+            drumSynth: group("synthEngine", "synthVolume", "synthPitch", "synthAttack", "synthWaveFm", "synth_p1", "synth_p2", "synth_p3"),
+            // Everything below is a real per-cell engine that no shipped factory
+            // preset has ever touched. They are the least-explored territory in the
+            // instrument, which makes them the first place to look when the brief
+            // is "something we haven't heard".
+            granular: group("stretchGrainMs", "stretchCrossfadeFrac", "stretchSyncEnabled", "grainDensity", "grainWindow", "grainArp", "grainScan", "grainFeedback", "grainTone"),
+            vocoder: group("vocoderMix", "vocoderWave", "vocoderNote", "vocoderFormant", "vocoderSpeed", "vocoderWidth"),
+            resonator: group("envResonatorMix", "envResonatorResonance", "envResonatorDampHz", "envResonatorDetune", "envResonatorGlideMs"),
+            crossModulation: group("fmSource", "fmAmount", "fmPolarity", "spread", "chaos", "formantShift", "vcaDepth"),
+            patternShape: group("patternDirection", "patternLength", "patternSpeed"),
+            pitchQuantize: group("quantRoot", "quantScale", "quantStrength"),
+            retriggerShape: group("retriggerSyncEnabled", "retriggerDecayDb", "retriggerRamp"),
+            slicing: group("slice"),
+        }),
         unitNotes: {
-            pan: "cellN_pan is -1..1, so -0.15 is about 15% left; use cellN_pannerBalance for -100..100%.",
+            sampleWindow: "cellN_startPos / cellN_endPos are 0..100 percent of the sample (defaults 0 and 100). Trimming endPos is how the corpus builds chops — a quarter of shipped sounding cells end below 69%. cellN_cutFrom (0..8) picks the slice source.",
+            pitchShift: "cellN_pitchShift is -24..24 SEMITONES, not a ratio. Pair with update_cell_config quantRoot/quantScale to keep a pitched cell in key.",
+            stretch: "cellN_stretch is 0..1 with 0.25 = unstretched. Below 0.25 smears toward granular freeze, above plays faster. This is PAM's signature control — a value away from 0.25 is audible immediately.",
+            envelope: "cellN_envAttack 1..100 and cellN_envRelease 1..5000 are ms; cellN_envGain is -24..24 dB. A long envRelease on a short one-shot is how a tail is built without reverb.",
+            retrigger: "cellN_retrigger is a repeat COUNT (0..10); cellN_retriggerDelay is a normalized 0..1 division, not seconds.",
+            arpeg: "cellN_arpeg is a -24..24 semitone step and cellN_arpegMode selects the pattern (0=Up 1=Down 2=Up/Down 3=Random 4=Triad 5=Major 6=Minor 7=Penta Maj ...). Non-zero arpeg turns a one-shot cell into a melodic line.",
+            pan: "cellN_pan is -1..1, so -0.15 is about 15% left; use cellN_pannerBalance for -100..100% (needs pannerEnabled).",
             percentages: "Most mix/feedback/depth controls are 0..100 percent.",
             filterCutoff: "Use real Hz values; move at least 1.5 octaves for obviously audible modulation.",
             delayDelayTime: "With delaySyncEnabled=1, normalized 0..1 maps to musical divisions; do not use cellN_delayTime.",
+            flanger: "cellN_flangerTime and cellN_flangerFreq are normalized 0..1, not ms/Hz. flangerFeedback is where the character lives — the corpus median is 70 and the top quartile is at 95+.",
+            eqGains: "cellN_eq{Low,Mid,High}Gain are -60..12 dB. The -60 floor makes the EQ a band KILL, not just a tilt.",
             lfoRate: "LFO IDs are 1-based: lfo1_... through lfo6_.... Sync ON uses index/22.",
+            lfoFeel: "lfoN_jitter and lfoN_offset (both 0..100, both default 0) are what stop an LFO sounding like a metronome — jitter randomizes the period, offset moves the starting phase so two LFOs at the same rate stop moving in lockstep. Only 8% and 6% of shipped LFOs set them.",
+            granular: "The granular engine runs under cellN_stretch. cellN_stretchGrainMs (1..2000) is grain size — small values buzz, 200+ smears into a pad; cellN_grainDensity (1..32) is grains in flight; cellN_grainScan (-100..100) moves the read head independently of playback, so a negative scan plays a sample backwards through itself; cellN_grainFeedback (0..100) recirculates grains; cellN_grainTone (-100..100) tilts them; cellN_grainWindow (0..4) is the grain envelope shape.",
+            vocoder: "Per-cell vocoder: cellN_vocoderMix (0..100) blends it in, cellN_vocoderNote (24..96) is the carrier MIDI note, cellN_vocoderWave (0..100) morphs the carrier, cellN_vocoderFormant (-12..12) shifts formants against pitch, cellN_vocoderSpeed (0.25..4) is band tracking rate. Any cell can vocode any source — it does not need a voice sample.",
+            resonator: "cellN_envResonator* is the tuned comb resonator: mix (0..100), resonance (0..100), dampHz (200..20000), detune (-24..24 semitones), glideMs (0..500). High resonance turns a percussive hit into a pitched tone that follows the cell — see rules/tunedcomb.md for PRE/POST routing.",
+            crossModulation: "cellN_fmSource (0..8) picks ANOTHER cell as an FM modulator and cellN_fmAmount (0..100) sets depth, so cells can modulate each other rather than each sitting in its own lane. cellN_chaos (0..100) and cellN_spread (0..100) add instability and stereo scatter; cellN_formantShift (-12..12) moves formants without pitch; cellN_vcaDepth (0..100) sets how hard the amp envelope bites.",
+            patternShape: "cellN_patternDirection (0..4), cellN_patternLength (1..32) and cellN_patternSpeed (0..19) reshape a lane without rewriting a single note. Odd lengths against a 16-step grid (7, 11, 13) produce phasing polymeter, and the pitch/slice/stretch lanes have their own patternLength*/patternSpeed* variants so lanes can run at different lengths against each other.",
+            pitchQuantize: "cellN_quantRoot (0..11), cellN_quantScale (0..9) and cellN_quantStrength (0..100) force a pitched cell into key. Set these before writing a pitch lane so transposition stays musical.",
+            clip: "cellN_gainClip (0..12 dB) with cellN_gainClipMode (0..3) is a per-cell clipper — a different distortion character from the crusher's drive.",
+            slice: "cellN_slice (0..64) selects the active slice; drive it from a slice lane for stutter edits without touching the sample.",
+        },
+        // Derived from the shipped factory presets, not hand-written. Regenerate
+        // with `node scripts/derive-corpus-ranges.mjs` after changing the corpus.
+        corpusBands: {
+            source: `${CORPUS_META.presets} factory presets, ${CORPUS_META.soundingCells} sounding cells (${CORPUS_META.source})`,
+            reading: "'typical' is p10..p90 — where the shipped presets sit. It is a description of the house average, NOT a limit. The interesting end of a range is usually outside it, and 'corpus' shows how far the shipped presets actually went.",
+            underexplored,
+            neverUsed: {
+                note: "No shipped factory preset has ever moved these. That makes them the cheapest route to a sound the library does not already contain — reach here before adding another filter sweep.",
+                params: neverUsed,
+            },
         },
-        musicalRanges: {
-            filterCutoff: "dark 300-900 Hz, mid 900-3500 Hz, open 3500-12000 Hz",
-            delayFeedback: "10-35% controlled, 35-60% dubby, >70% runaway risk",
-            wetMix: "10-25% subtle, 25-45% audible, >60% wash/destroy",
-            crusherBitReduction: "7-16 bits musical grit, 1-4 bits brutal",
-            volumeDb: "Layer cells with -12..0 dB staging before master processing",
+        eq8: {
+            note: "Every cell also has a full 8-band parametric EQ, separate from the 3-band eq group above. It is a per-band grid rather than a fixed param list.",
+            template: `cell${cellId}_eq8_b{1..8}_{freq,gain,q,type,slope,enabled}`,
+            bandRanges: "freq 10..30000 Hz, gain -30..30 dB, q 0.025..40, type 0..5, slope 0..2, enabled 0/1",
+            outputGain: example("eq8_outputGain"),
+            idea: "A q of 40 at a chosen freq is a resonant whistle, not an EQ move — eight of them tuned to a chord turn any noise source into a pitched pad.",
         },
         lfoSyncTable: {
             formula: "set lfoN_lfoSyncEnabled=1 and lfoN_lfoRate=index/22",
             quick: lfoQuick,
             fullDivisions: LFO_DIVISIONS,
             shapes: ["0=Sine", "1=Saw", "2=Tri", "3=Square", "4=Random", "5=Wander", "6=Custom"],
+            shapeNote: "Shapes 4 (Random) and 5 (Wander) are stepped/drifting rather than periodic — they read as performance rather than automation. Half of shipped LFOs are shape 0 (Sine).",
         },
         delaySyncDivisions: [
             "1/32T", "1/32", "1/32D", "1/16T", "1/16", "1/16D",
@@ -1056,12 +1452,297 @@ server.registerTool("design_context", {
         filterTypes: filterType?.strRepr?.map((label, index) => `${index}=${label}`) ?? [
             "0=Lowpass", "1=Highpass", "2=Bandpass", "3=Peak", "4=Notch",
         ],
+        effectOrder: {
+            paramId: `cell${cellId}_effectOrder`,
+            tool: "set_effect_order",
+            note: "Per-cell FX chain order is a JSON string array, NOT a numeric param — set_parameters cannot reach it. Order is audible: filter-into-delay smears the resonance, delay-into-filter darkens the repeats.",
+            defaultOrder: defaultEffectOrder,
+        },
         midiNoteMap: Object.fromEntries(Array.from({ length: 8 }, (_, i) => {
             const id = i + 1;
             return [`cell${id}`, 47 + id];
         })),
         variationSlots: "API is 0-based (0..7); PAM UI labels slots 1..8. Save/load variation index 0 = UI slot 1.",
-        modulationGuidance: "Primary movement should target per-cell params for distinct audible changes. Use macro_* for performance-level fan-out across cells.",
+        generativePlayers: "set_player turns a cell into a live generator (list_players for the roster: EUCLID, KIT, TURING, WALK, MARKOV, " +
+            "RATCHET, PHASE, RIFF, MASK). cell{N}_playerDensity/Mutate/P1..P5 are modulatable params with macro_player* twins; " +
+            "write them through set_player, never set_parameters alone, so the cell config stays in step.",
+        modulationGuidance: "Primary movement should target per-cell params for distinct audible changes. Use macro_* for performance-level fan-out across cells. " +
+            "Shipped presets that modulate at all carry a mean of 8.2 sources; the top third carry 8-46. Four sources is the corpus MEDIAN, i.e. the unremarkable middle — not a target.",
+    });
+});
+server.registerTool("preset_novelty", {
+    title: "Score Preset Novelty",
+    description: "Score a preset against the shipped factory corpus and name what it duplicates. Answers the question " +
+        "nothing else in the pipeline could: 'does this already exist?'\n\n" +
+        "Compares structure, not audio — which params are off their defaults, the FX set and chain orders, the " +
+        "modulation topology, per-cell onset patterns, transpositions, and sample sources. No render, no audio, " +
+        "and (for source 'file') no plugin connection needed.\n\n" +
+        "novelty is 1 - (closest match). Read it against percentileVsCorpus, NOT as an absolute: every PAM preset " +
+        "shares an instrument, so a perfectly good one still scores around " +
+        `${CORPUS_NOVELTY_BASELINE.p50}. The closest pair that actually shipped scores ${CORPUS_NOVELTY_BASELINE.floor} — ` +
+        "below that, a preset is more derivative than anything in the library.\n\n" +
+        "duplicatedDimensions is the actionable part: it names which dimensions to change.",
+    inputSchema: {
+        source: z
+            .enum(["live", "file"])
+            .default("live")
+            .describe("'live' fingerprints the running plugin's current state; 'file' reads a .preset from disk."),
+        path: z.string().optional().describe("Preset path for source 'file' (absolute or relative to the preset dirs)."),
+        topN: z.number().int().min(1).max(20).default(5).describe("How many nearest neighbours to return."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ source, path: presetPath, topN }) => {
+    const manifest = await loadManifest();
+    const defaults = {};
+    for (const p of manifest.parameters) {
+        const m = /^cell1_(.+)$/.exec(p.paramId);
+        if (m)
+            defaults[m[1]] = p.defaultValue;
+    }
+    const effectNames = cellEffectNames(manifest);
+    let state;
+    let label = "live state";
+    if (source === "file") {
+        if (!presetPath)
+            return error("source 'file' requires a `path`.");
+        try {
+            const full = await resolvePresetPath(presetPath);
+            const { metadata, data } = parsePresetFile(await readFile(full, "utf-8"));
+            state = data;
+            label = metadata.name || basename(full, ".preset");
+        }
+        catch (e) {
+            return error(`Failed to read preset: ${e.message}`);
+        }
+    }
+    else {
+        const check = await requireBridge();
+        if (check !== true)
+            return check;
+        state = (await bridge.send("getState"));
+    }
+    const candidate = buildFingerprint(state, defaults, effectNames, label);
+    if (candidate.cells === 0) {
+        return error("No cell carries any notes, so there is nothing to fingerprint. Write note patterns first (update_pattern), then re-score.");
+    }
+    // Re-scoring a preset that already shipped would otherwise match itself at
+    // 1.0 and report "more derivative than anything in the library", which is
+    // true but useless. Drop the identity match and say so.
+    const selfIndex = CORPUS_FINGERPRINTS.findIndex((f) => f.name === candidate.name && fingerprintSimilarity(candidate, f).overall > 0.999);
+    const corpus = selfIndex >= 0 ? CORPUS_FINGERPRINTS.filter((_, i) => i !== selfIndex) : CORPUS_FINGERPRINTS;
+    const report = scoreNovelty(candidate, corpus, topN, CORPUS_NOVELTY_BASELINE);
+    return json({
+        subject: label,
+        alreadyInCorpus: selfIndex >= 0 || undefined,
+        ...report,
+        corpusBaseline: {
+            ...CORPUS_NOVELTY_BASELINE,
+            note: `Leave-one-out novelty of the ${CORPUS_FINGERPRINTS.length} shipped presets against each other. p50 is a typical preset; below floor is more derivative than any shipped pair.`,
+        },
+        candidateProfile: {
+            soundingCells: candidate.cells,
+            paramsMoved: candidate.params.length,
+            fx: candidate.fx,
+            distinctChainOrders: candidate.chains.length,
+            modulationSources: candidate.mod.lfo + candidate.mod.env + candidate.mod.vary + candidate.mod.seq,
+            modulationTargets: candidate.mod.targets.length,
+            transpositions: candidate.pitch.length,
+            sampleSources: candidate.sources.length,
+        },
+    });
+});
+server.registerTool("analyze_motion", {
+    title: "Analyze Preset Motion",
+    description: "Measure whether a preset actually MOVES over time, rather than whether it is mixed. Fills the gap left by " +
+        "get_master_analysis (loudness) and get_mix_analysis (aggregate spectrum + onset density), neither of which " +
+        "can tell a modulated preset from a static one.\n\n" +
+        "Reports spectral flux, brightness wander, per-bar level and brightness variation, and level movement WITHIN " +
+        "a bar — the last one is what catches a bar-synced gate, tremolo or sidechain pump, whose bars are all " +
+        "identical to each other.\n\n" +
+        "Pass wavPath to analyze an existing render or live_resample capture. Otherwise the tool runs an offline " +
+        "export first and leaves that render in PAM's Exports folder as pam_motion_<epoch>.wav. Digital silence is " +
+        "reported as a RENDER FAILURE with the workaround, not as 'no motion' — offline export is known to produce " +
+        "silence in the standalone build.",
+    inputSchema: {
+        wavPath: z
+            .string()
+            .optional()
+            .describe("Absolute path to an existing WAV. Skips rendering — use this for a live_resample capture."),
+        bars: z.number().int().min(1).max(32).default(4).describe("Bars to render when no wavPath is given."),
+        bpm: z
+            .number()
+            .optional()
+            .describe("Tempo for the per-bar windows. Read from the transport when omitted."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+}, async ({ wavPath, bars, bpm }) => {
+    let path = wavPath;
+    let effectiveBpm = bpm;
+    if (!path) {
+        const check = await requireBridge();
+        if (check !== true)
+            return check;
+        const transport = (await bridge.send("getTransport"));
+        effectiveBpm ??= typeof transport?.bpm === "number" ? transport.bpm : 120;
+        const filename = `pam_motion_${Date.now()}`;
+        await bridge.send("exportAudio", {
+            filename,
+            mode: "main",
+            durationInSeconds: (bars * 4 * 60) / (effectiveBpm || 120),
+            bitDepth: 24,
+        });
+        const outcome = await pollExportStatus();
+        if (outcome !== "success")
+            return error(`Render failed before analysis could run (export ${outcome}).`);
+        const locations = (await bridge.send("getDefaultLocations"));
+        const exportDir = [locations?.exports, locations?.exportsLocation, locations?.Exports].find((v) => typeof v === "string" && v.length > 0);
+        if (!exportDir) {
+            return error(`Rendered ${filename}.wav but could not resolve PAM's Exports folder from get_default_locations. ` +
+                "Re-run with an explicit wavPath.");
+        }
+        path = resolve(exportDir, `${filename}.wav`);
+    }
+    else if (effectiveBpm === undefined) {
+        const check = await requireBridge();
+        if (check === true) {
+            const transport = (await bridge.send("getTransport"));
+            if (typeof transport?.bpm === "number")
+                effectiveBpm = transport.bpm;
+        }
+    }
+    let metrics;
+    try {
+        metrics = analyzeMotion(decodeWav(await readFile(path)), effectiveBpm);
+    }
+    catch (e) {
+        return error(`Could not analyze ${path}: ${e.message}`);
+    }
+    return json({
+        file: path,
+        bpm: effectiveBpm ?? null,
+        ...metrics,
+        reading: "static:true means nothing measurably changes — brightness, per-bar level and within-bar level are all flat. " +
+            "centroidVariability and perBarCentroidVariability catch slow filter/timbre motion; intraBarRmsVariability " +
+            "catches per-hit and per-beat movers (gate, tremolo, sidechain duck). A preset can pass the modulation-count " +
+            "check and still fail here when depths are too small to hear.",
+    });
+});
+// What to change when a pair of variations is identical on a given dimension.
+// The dimension name alone is not actionable; this maps it to a move.
+const VARIATION_FIX_HINTS = {
+    groove: "rewrite the note patterns — different onsets, not just different density",
+    params: "change the sound, not the mix: filter type, chop window (startPos/endPos), stretch, or a different FX",
+    mod: "change what MOVES — retarget the front modulator or swap the mover type",
+    pitch: "transpose or re-voice the melodic parts",
+    fx: "enable or bypass a different effect on at least one cell",
+    chains: "reorder one cell's FX chain (set_effect_order)",
+    sources: "swap a sample on at least one cell",
+};
+server.registerTool("variation_distinctness", {
+    title: "Check Variation Distinctness",
+    description: "Measure whether a preset's variation slots are actually different, and name what is identical about the " +
+        "pairs that are not. Structural comparison of the saved slot snapshots — no render, no transport, no " +
+        "audition loop, and no risk of the load_variation race.\n\n" +
+        `Read scores against the shipped corpus, where sibling variation pairs sit at a median of ` +
+        `${CORPUS_VARIATION_BASELINE.p50} similarity (p75 ${CORPUS_VARIATION_BASELINE.p75}, p90 ${CORPUS_VARIATION_BASELINE.p90}). ` +
+        `Siblings are far more alike than two different presets by construction, so the preset_novelty scale does ` +
+        `not apply. ${CORPUS_VARIATION_BASELINE.nearIdenticalShare}% of shipped pairs are already near-identical — ` +
+        "this gate exists to stop adding to that number.\n\n" +
+        "Each failing pair reports the dimensions it duplicates plus the move that would fix it.",
+    inputSchema: {
+        source: z
+            .enum(["live", "file"])
+            .default("live")
+            .describe("'live' reads the running plugin's variation slots; 'file' reads them from a .preset."),
+        path: z.string().optional().describe("Preset path for source 'file'."),
+        threshold: z
+            .number()
+            .min(0.5)
+            .max(1)
+            .default(0.9)
+            .describe(`Similarity above which a pair fails. Default 0.9 — worse than 75% of shipped sibling pairs (p75 ${CORPUS_VARIATION_BASELINE.p75}).`),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ source, path: presetPath, threshold }) => {
+    const manifest = await loadManifest();
+    const defaults = {};
+    for (const p of manifest.parameters) {
+        const m = /^cell1_(.+)$/.exec(p.paramId);
+        if (m)
+            defaults[m[1]] = p.defaultValue;
+    }
+    const effectNames = cellEffectNames(manifest);
+    let slots;
+    let label;
+    if (source === "file") {
+        if (!presetPath)
+            return error("source 'file' requires a `path`.");
+        try {
+            const full = await resolvePresetPath(presetPath);
+            const parsed = parsePresetFile(await readFile(full, "utf-8"));
+            slots = variationsFromParsedPreset(parsed);
+            label = parsed.metadata.name || basename(full, ".preset");
+        }
+        catch (e) {
+            return error(`Failed to read preset: ${e.message}`);
+        }
+    }
+    else {
+        const check = await requireBridge();
+        if (check !== true)
+            return check;
+        const state = (await bridge.send("getState"));
+        const raw = Array.isArray(state.variations) ? state.variations : [];
+        slots = Array.from({ length: PRESET_VARIATION_SLOTS }, (_, i) => typeof raw[i] === "string" ? decompressVariationEntry(raw[i]) : null);
+        label = "live state";
+    }
+    const filled = [];
+    for (const [i, slot] of slots.entries()) {
+        if (typeof slot !== "string" || slot.length < 10)
+            continue;
+        try {
+            filled.push({ slot: i, fp: buildFingerprint(JSON.parse(slot), defaults, effectNames, `slot ${i}`) });
+        }
+        catch {
+            /* unreadable slot — reported via the occupancy count below */
+        }
+    }
+    if (filled.length < 2) {
+        return error(`Only ${filled.length} readable variation slot(s) — need at least 2 to compare. ` +
+            "Save more slots with save_variation (API indices are 0-based; UI labels them 1-8).");
+    }
+    const pairs = [];
+    for (let i = 0; i < filled.length; i += 1) {
+        for (let j = i + 1; j < filled.length; j += 1) {
+            const sim = fingerprintSimilarity(filled[i].fp, filled[j].fp);
+            const identical = Object.entries(sim.byDimension)
+                .filter(([, v]) => v >= 0.95)
+                .sort((a, b) => b[1] - a[1])
+                .map(([k]) => k);
+            pairs.push({
+                pair: `slot ${filled[i].slot} vs slot ${filled[j].slot}`,
+                similarity: Math.round(sim.overall * 1000) / 1000,
+                pass: sim.overall < threshold,
+                identicalDimensions: identical,
+                fix: sim.overall < threshold ? undefined : identical.map((d) => VARIATION_FIX_HINTS[d] ?? d),
+            });
+        }
+    }
+    const failing = pairs.filter((p) => !p.pass).sort((a, b) => b.similarity - a.similarity);
+    return json({
+        subject: label,
+        filledSlots: filled.map((f) => f.slot),
+        threshold,
+        pass: failing.length === 0,
+        verdict: failing.length === 0
+            ? `All ${pairs.length} slot pairs differ by more than the ${threshold} threshold.`
+            : `${failing.length} of ${pairs.length} slot pairs are too similar. Give one slot in each a real change — density alone is not a variation.`,
+        failingPairs: failing,
+        allPairs: pairs,
+        corpusBaseline: CORPUS_VARIATION_BASELINE,
+        // Shipped variations move these dimensions and leave those alone — useful
+        // when deciding WHICH dimension to change.
+        corpusHabit: "Shipped variations mostly change modulation and groove; they almost never change samples or FX chain order. Those two are therefore the least-used lever available to you.",
     });
 });
 // Standard full update — graph dispatch + KV sync + parameter updates.
@@ -1195,9 +1876,8 @@ server.registerTool("get_design_overview", {
     ]);
     const state = isRecord(stateRaw) ? stateRaw : {};
     const transport = isRecord(transportRaw) ? transportRaw : {};
-    // Product-aware: MFX carries wavefold/resonator, PAM/Cell1 do not.
-    const derivedEffects = cellEffectNames(manifest);
-    const effectNames = derivedEffects.length ? derivedEffects : CELL_EFFECTS_FALLBACK;
+    // The manifest is authoritative; every current product carries both character effects.
+    const effectNames = cellEffectNames(manifest);
     const manifestCellIds = [...new Set(manifest.parameters
             .map((p) => p.cell)
             .filter((cell) => typeof cell === "string" && /^cell\d+$/.test(cell))
@@ -1210,6 +1890,49 @@ server.registerTool("get_design_overview", {
         vary: Array.isArray(state.vary) ? state.vary : [],
         paramSeq: Array.isArray(state.paramSeqs) ? state.paramSeqs : [],
     };
+    if (IS_MFX_SERVER) {
+        const cells = ids.map((id) => {
+            const prefix = `cell${id}_`;
+            const targetPrefix = new Set([prefix]);
+            const storedOrder = state[`${prefix}effectOrder`];
+            const rawCell = cellsObj[String(id)];
+            const cellConfig = isRecord(rawCell) ? rawCell : {};
+            return {
+                cellId: id,
+                muted: state[`${prefix}mute`] === 1 || state[`${prefix}mute`] === true,
+                sidechainFrom: cellConfig.sidechainFrom ?? state[`${prefix}sidechainFrom`],
+                effectOrder: Array.isArray(storedOrder) ? storedOrder : cellEffectOrder(manifest),
+                enabledEffects: effectNames.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
+                modulation: Object.fromEntries(Object.entries(modArrays).map(([kind, arr]) => [
+                    kind,
+                    arr.filter((entry) => paramTargetsCell(entry, targetPrefix)).length,
+                ])),
+                mixer: {
+                    volume: state[`${prefix}volume`],
+                    pan: state[`${prefix}pan`],
+                    gain: state[`${prefix}gainGain`],
+                },
+            };
+        });
+        return json({
+            product: manifest.name,
+            bpm: state.bpm ?? transport.bpm,
+            playing: transport.playing,
+            mix: state.mfx_mix,
+            routing: state.mfx_routing,
+            edgeGains: state.mfx_edge_gains,
+            split: { lowHz: state.mfx_split_lo_hz, highHz: state.mfx_split_hi_hz },
+            combos: resolveServerMfxCombos(state, manifest).map((combo) => ({
+                ...combo,
+                value: state[`mfx_combo${combo.index}`],
+            })),
+            totals: {
+                enabledEffects: cells.reduce((sum, cell) => sum + cell.enabledEffects.length, 0),
+                modulationLinks: cells.reduce((sum, cell) => sum + Object.values(cell.modulation).reduce((subtotal, count) => subtotal + count, 0), 0),
+            },
+            cells,
+        });
+    }
     const cells = ids.map((id) => {
         const prefix = `cell${id}_`;
         const rawCellState = cellsObj[String(id)];
@@ -1224,12 +1947,14 @@ server.registerTool("get_design_overview", {
         ]));
         return {
             cellId: id,
+            muted: state[`${prefix}mute`] === 1 || state[`${prefix}mute`] === true,
             sample: {
                 name: stemName(samplePath),
                 path: typeof samplePath === "string" ? samplePath : undefined,
             },
             // Both halves: the enum an agent writes back, and the name it reasons about.
             synthEngine: describeSynthEngine(state[`${prefix}synthEngine`]),
+            player: describeCellPlayer(id, cellState, state),
             enabledEffects: effectNames.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
             patternEvents: Object.fromEntries(Object.entries(PATTERN_LANES).map(([lane, suffix]) => [
                 lane,
@@ -1254,6 +1979,7 @@ server.registerTool("get_design_overview", {
         },
         totals: {
             cellsWithSamples: cells.filter((c) => c.sample.path).length,
+            playersRunning: cells.filter((c) => c.player).length,
             activePatternEvents: cells.reduce((sum, c) => sum + Object.values(c.patternEvents).reduce((a, b) => a + b, 0), 0),
             modulationLinks: cells.reduce((sum, c) => sum + Object.values(c.modulation).reduce((a, b) => a + b, 0), 0),
         },
@@ -1264,7 +1990,8 @@ server.registerTool("set_parameters", {
     title: "Set Parameters",
     description: "Set one or more PAM parameters. Values are validated against the manifest. " +
         "Effect enable flags such as cell1_filterEnabled are settable here too, so params + enables can land in one call " +
-        "when a graph dispatch is acceptable. Use get_parameter_info or design_context to discover valid IDs and ranges.",
+        "when a graph dispatch is acceptable. Use get_parameter_info or design_context to discover valid IDs and ranges. " +
+        "Writing a macro_* id also enables that macro, matching the UI.",
     inputSchema: {
         parameters: z
             .record(z.string(), z.number())
@@ -1308,6 +2035,36 @@ server.registerTool("set_parameters", {
         }
         delta.macros = macros;
     }
+    let comboTargetCount = 0;
+    if (isMfxManifest(await loadManifest())) {
+        const comboValues = new Map();
+        for (let comboIndex = 1; comboIndex <= MFX_COMBO_COUNT; comboIndex++) {
+            const value = parameters[`mfx_combo${comboIndex}`];
+            if (typeof value === "number")
+                comboValues.set(comboIndex, value);
+        }
+        if (comboValues.size > 0) {
+            const stateRaw = await bridge.send("getState");
+            const state = isRecord(stateRaw) ? stateRaw : {};
+            const manifest = await loadManifest();
+            for (const combo of resolveServerMfxCombos(state, manifest)) {
+                const value = comboValues.get(combo.index);
+                if (value === undefined)
+                    continue;
+                if (combo.targets.some((target) => Object.hasOwn(parameters, target.id)))
+                    continue;
+                for (const target of combo.targets) {
+                    const info = index.get(target.id);
+                    if (!info)
+                        continue;
+                    const previousComboValue = state[`mfx_combo${combo.index}`];
+                    const currentTargetValue = state[target.id];
+                    delta[target.id] = mfxComboTargetValueFromCurrent(target, typeof previousComboValue === "number" ? previousComboValue : 0, value, info, typeof currentTargetValue === "number" ? currentTargetValue : info.defaultValue);
+                    comboTargetCount++;
+                }
+            }
+        }
+    }
     await bridge.send("applyUnifiedStateKvUpdate", {
         delta,
         options: {
@@ -1319,17 +2076,18 @@ server.registerTool("set_parameters", {
             broadcastFollowers: true,
         },
     });
-    return text(`Set ${Object.keys(parameters).length} parameter(s): ${Object.entries(parameters).map(([k, v]) => `${k}=${v}`).join(", ")}`);
+    return text(`Set ${Object.keys(parameters).length} parameter(s): ${Object.entries(parameters).map(([k, v]) => `${k}=${v}`).join(", ")}` +
+        (comboTargetCount > 0 ? `; fanned out ${comboTargetCount} MFX combo target write(s)` : ""));
 });
 server.registerTool("load_sample", {
     title: "Load Sample",
-    description: "Load an audio file (wav, mp3, aif, flac) into a PAM cell.",
+    description: "Load an audio file (wav, mp3, aif, flac) into a PAM cell, replacing whatever the cell currently holds. Take filePath from list_samples or a get_default_locations root.",
     inputSchema: {
         filePath: z.string().describe("Path to the audio file (absolute, or relative as returned by list_samples)."),
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ filePath, cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("loadSampleToCell", filePath, cellId);
@@ -1341,7 +2099,7 @@ server.registerTool("load_sample", {
 // + experimental<Engine>) — the bridge returns a clear error otherwise.
 const MODEL_ENGINE = z
     .enum(["notochord", "aigen", "magenta"])
-    .describe("Which AI engine. notochord = MIDI co-player (~18 MB blob); aigen = Stable Audio 3 sample generation (~3.2 GB ONNX); magenta = MagentaRT realtime audio (Apple Silicon, MLX).");
+    .describe("Which AI engine. notochord = MIDI co-player (~18 MB blob); aigen = Stable Audio 3 sample generation (2.71 GB); magenta = MagentaRT realtime audio (Apple Silicon, MLX).");
 const MODEL_VARIANT = z
     .enum(["base", "small"])
     .optional()
@@ -1418,7 +2176,7 @@ server.registerTool("list_models", {
 });
 server.registerTool("generate_sample", {
     title: "Generate Sample (AI)",
-    description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, ~3.2 GB ONNX). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
+    description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, 2.71 GB). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
     inputSchema: {
         category: z
             .enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"])
@@ -1502,6 +2260,7 @@ server.registerTool("generate_kit", {
 // curve / prompt / seed / sigma), sidecar renders, and the take shelf. Requires
 // experimentalMode + experimentalAIGen (update_settings) AND the SA3 Python
 // sidecar running on 127.0.0.1:8093 (packages/sa3-workbench-sidecar/README.md).
+const WORKBENCH_PREREQ = "Requires experimentalMode + experimentalAIGen (update_settings) and the SA3 sidecar on 127.0.0.1:8093; check workbench_sidecar_status first. ";
 const WORKBENCH_MASK_REGION = z.object({
     startSec: z.number().min(0).describe("Region start in seconds (source time)."),
     endSec: z.number().min(0).describe("Region end in seconds (must be > startSec)."),
@@ -1537,7 +2296,8 @@ const WORKBENCH_STATE_FIELDS = {
 };
 server.registerTool("workbench_get_state", {
     title: "Workbench: Get State",
-    description: "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
+    description: WORKBENCH_PREREQ +
+        "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -1547,7 +2307,8 @@ server.registerTool("workbench_get_state", {
 });
 server.registerTool("workbench_set_state", {
     title: "Workbench: Set State",
-    description: "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
+    description: WORKBENCH_PREREQ +
+        "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
     inputSchema: WORKBENCH_STATE_FIELDS,
 }, async (args) => {
     const check = await requireBridge();
@@ -1557,7 +2318,8 @@ server.registerTool("workbench_set_state", {
 });
 server.registerTool("workbench_render", {
     title: "Workbench: Render",
-    description: "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Blocks until done (up to ~3 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, durationSeconds, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file. A successful render ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain.",
+    description: WORKBENCH_PREREQ +
+        "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Blocks until done (up to ~3 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, durationSeconds, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file. A successful render ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain.",
     inputSchema: {
         ...WORKBENCH_STATE_FIELDS,
         sourcePath: z.string().optional()
@@ -1576,7 +2338,7 @@ server.registerTool("workbench_render", {
 });
 server.registerTool("workbench_list_takes", {
     title: "Workbench: List Takes",
-    description: "List all Workbench takes (renders) with full provenance, oldest first.",
+    description: WORKBENCH_PREREQ + "List all Workbench takes (renders) with full provenance, oldest first.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -1586,13 +2348,13 @@ server.registerTool("workbench_list_takes", {
 });
 server.registerTool("workbench_load_take", {
     title: "Workbench: Load Take",
-    description: "Load a rendered take's WAV into a cell (same native path as load_sample).",
+    description: WORKBENCH_PREREQ + "Load a rendered take's WAV into a cell (same native path as load_sample).",
     inputSchema: {
         takeId: z.string().describe("Take id from workbench_render / workbench_list_takes."),
         cellId: z.number().int().min(1).max(8).describe("Target cell."),
     },
 }, async ({ takeId, cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     try {
@@ -1604,7 +2366,8 @@ server.registerTool("workbench_load_take", {
 });
 server.registerTool("workbench_undo", {
     title: "Workbench: Undo (pop chain)",
-    description: "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
+    description: WORKBENCH_PREREQ +
+        "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -1614,7 +2377,8 @@ server.registerTool("workbench_undo", {
 });
 server.registerTool("workbench_reset_chain", {
     title: "Workbench: Reset Chain",
-    description: "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
+    description: WORKBENCH_PREREQ +
+        "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -1649,7 +2413,7 @@ server.registerTool("trigger_midi", {
         channel: z.number().min(1).max(16).default(1).describe("MIDI channel (1-16)."),
     },
 }, async ({ cellId, note, noteOn, channel }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     if (cellId) {
@@ -1667,7 +2431,7 @@ server.registerTool("stop_cell", {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("stopCell", cellId);
@@ -1675,17 +2439,31 @@ server.registerTool("stop_cell", {
 });
 server.registerTool("load_preset", {
     title: "Load Preset",
-    description: "Load a preset into the running PAM plugin.",
+    description: "Queue a preset load through PAM's native load/morph lifecycle. Returns requestId and status:'queued'. " +
+        "Poll get_preset_load_status until status:'succeeded' before editing, randomizing, or saving; failure, cancellation, and supersession are explicit. " +
+        "Replaces working state and the variation bank; save_preset first if unsaved edits matter. Requires a plugin build with tracked preset loading.",
     inputSchema: {
         path: z.string().describe("Preset file path (absolute or relative to preset dirs)."),
+        immediate: z.boolean().optional().describe("true bypasses the preset morph; false/omitted follows the native preset morph settings."),
     },
-}, async ({ path: presetPath }) => {
+}, async ({ path: presetPath, immediate }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const fullPath = await resolvePresetPath(presetPath);
-    await bridge.send("loadPreset", fullPath);
-    return text(`Loaded preset: ${basename(fullPath, ".preset")}`);
+    return json(await bridge.send("loadPresetTracked", fullPath, immediate === true));
+});
+server.registerTool("get_preset_load_status", {
+    title: "Get Preset Load Status",
+    description: "Read the outcome of a load_preset request without requiring the plugin window. " +
+        "Statuses: queued, morphing, succeeded, failed, cancelled, superseded. Only succeeded confirms the world committed, including same-path reloads. " +
+        "PAM retains the latest 64 requests per instance; unknown/expired IDs return an error. Keep the same selected instance while polling.",
+    inputSchema: { requestId: z.string().min(1).describe("requestId returned by load_preset.") },
+}, async ({ requestId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("getPresetLoadStatus", requestId));
 });
 server.registerTool("add_modulation", {
     title: "Add Modulation",
@@ -1733,7 +2511,7 @@ server.registerTool("add_modulation", {
         return error(formatUnknownParamError(paramId, index, { modulatableOnly: true }));
     if (!param.isModulatable)
         return error(formatNotModulatableError(paramId, index));
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     // Compute effect-enabled params to auto-enable disabled effects (mirrors UI behavior)
@@ -1772,7 +2550,7 @@ server.registerTool("update_pattern", {
             "For 'pitch'/'slice'/'stretch': [{time, value, duration}]."),
     },
 }, async ({ cellId, type, sequence }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     // Map pattern type to state key suffix
@@ -1829,7 +2607,10 @@ server.registerTool("randomize", {
     description: "Trigger PAM's randomization engine to generate random sounds and patterns. " +
         "target:'synth' runs the musical, engine-aware drum-synth randomizer (picks an engine + " +
         "shapes its params per cell) — it is routed through the WebView, so it requires PAM's window " +
-        "to be OPEN (samples/sequences/full run natively and do not). target:'synth' needs PAM ≥ 1.13.0.",
+        "to be OPEN (samples/sequences/full run natively and do not). 'lfos'/'mods' are global and require an open window. " +
+        "Returns queued, not completed: poll get_state for the requested changes before another randomize, edit, or save. " +
+        "Concurrent requests can coalesce; a preset/variation load can discard pending work. " +
+        "Use target:'full' to chain sample selection and pattern generation in the native engine.",
     inputSchema: {
         // 'lfos'/'mods' added for the assistant surface (1.15.0) — WebView-routed
         // like 'synth'. The describe() text is pinned (exported toolpack bytes).
@@ -1840,7 +2621,7 @@ server.registerTool("randomize", {
         cellIds: z
             .array(z.number().min(1).max(8))
             .optional()
-            .describe("Specific cells to randomize. Omit for all."),
+            .describe("Specific cells to randomize. Omit for all. Not supported for global 'lfos'/'mods'."),
         genreHint: z
             .string()
             .optional()
@@ -1857,32 +2638,44 @@ server.registerTool("randomize", {
             .max(1)
             .optional()
             .describe("Mutation amount for pattern randomization (0-1). Lower = subtler changes."),
+        density: z
+            .number()
+            .min(-1)
+            .max(1)
+            .optional()
+            .describe("Pattern density for 'sequences'/'full' (-1 = sparse, 0 = neutral, 1 = dense). Omit for the genre and role default."),
+        syncopation: z
+            .number()
+            .min(-1)
+            .max(1)
+            .optional()
+            .describe("Rhythmic placement for 'sequences'/'full' (-1 = strong beats, 0 = neutral, 1 = weaker offbeats). Omit for the genre and role default."),
     },
-}, async ({ target, cellIds, genreHint, bpmHint, mutationAmount }) => {
-    const check = await requireBridge();
+}, async ({ target, cellIds, genreHint, bpmHint, mutationAmount, density, syncopation }) => {
+    if ((target === "lfos" || target === "mods") && cellIds !== undefined)
+        return error(`target:'${target}' randomizes global modulation; omit cellIds or edit individual links with update_modulation.`);
+    const check = await requireBridgeForCells(cellIds);
     if (check !== true)
         return check;
     if (target === "synth") {
         // Routed to the canonical WebView randomizer (single source of truth) — needs the
         // window open. Empty array → all non-excluded cells.
         await bridge.send("randomizeDrumSynth", cellIds ?? []);
-        return text(`Randomized drum synths${cellIds ? ` for cells ${cellIds.join(", ")}` : " (all cells)"}. ` +
-            `(Drum-synth randomize runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+        return json({ status: "queued", target, cellIds, note: "Open PAM's window and poll get_design_overview for synth changes before editing or saving." });
     }
     if (target === "lfos" || target === "mods") {
-        // The data-driven modulation randomizer lives in WebView JS
-        // (interop.ts randomizeLfos/randomizeEnvelopes/randomizeVary) — routed
-        // like 'synth'. Needs PAM ≥ 1.15.0 and the window open.
         await bridge.send("randomizeModulations", target, mutationAmount ?? -1);
-        return text(`Randomized ${target === "lfos" ? "LFO modulation links" : "all modulation (LFOs, envelopes, vary)"}. ` +
-            `(Runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+        return json({ status: "queued", target, note: "Open PAM's window and poll get_state for modulation changes before editing or saving." });
     }
-    await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
-    return text(`Randomized ${target}${cellIds ? ` for cells ${cellIds.join(", ")}` : ""}.`);
+    await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
+    return json({ status: "queued", target, cellIds, note: "Poll get_state for changed sample paths and/or sequences before another randomize, edit, or save. An acknowledgment does not prove the request applied." });
 });
 server.registerTool("randomize_samples", {
     title: "Randomize Samples",
-    description: "Use PAM's native sample randomization engine to pick coherent samples based on genre, BPM, and kit role. More musically coherent than manually browsing and loading samples. Supports folder filtering to constrain selection to specific sample packs.",
+    description: "Use PAM's native sample randomization engine to pick coherent samples based on genre, BPM, and kit role. Supports folder filtering. " +
+        "Returns queued: poll get_state section:'cells' for sample changes before generating patterns, editing, or saving. " +
+        "Serialize requests because concurrent requests can coalesce; a preset/variation load can discard pending work. " +
+        "For samples plus patterns, prefer randomize target:'full'.",
     inputSchema: {
         cellIds: z
             .array(z.number().min(1).max(8))
@@ -1891,7 +2684,7 @@ server.registerTool("randomize_samples", {
         genreHint: z
             .string()
             .optional()
-            .describe("Genre hint to guide sample selection. Supported: boom_bap (aliases hip-hop, lofi), trap, drill, house, techno, dnb (aliases jungle, breakbeat, breaks). Other values fall back to neutral role-based selection; omit to auto-detect from the library."),
+            .describe("Genre hint to guide sample selection. Supported: boom_bap (aliases hip-hop, lofi), trap, drill, house, techno, dnb (aliases jungle, breakbeat, breaks), idm (aliases braindance, electronica, breakcore). Other values fall back to neutral role-based selection; omit to auto-detect from the library."),
         bpmHint: z
             .number()
             .min(20)
@@ -1906,17 +2699,58 @@ server.registerTool("randomize_samples", {
             .array(z.string())
             .optional()
             .describe("If provided, only pick samples from these paths. Overrides default library scan."),
+        diversify: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Anti-centroid mode (0 = default behaviour, 1 = maximum spread). The native engine scores FOLDER " +
+            "COHERENCE, which is correct for a kit-from-one-pack and is also why repeated randomizes keep landing " +
+            "on the same few well-stocked folders. Above 0 this builds a cross-folder pool first and restricts the " +
+            "engine to it, keeping role assignment while removing its ability to converge. Ignored when " +
+            "allowedSamplePaths is given."),
+        seed: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Seed for diversify, so a diverged kit can be reproduced. Defaults to 0."),
     },
-}, async ({ cellIds, genreHint, bpmHint, excludedFolders, allowedSamplePaths }) => {
-    const check = await requireBridge();
-    if (check !== true)
-        return check;
-    await bridge.send("randomizeSamples", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, excludedFolders ?? [], allowedSamplePaths ?? []);
-    return text(`Randomized samples${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
+}, async ({ cellIds, genreHint, bpmHint, excludedFolders, allowedSamplePaths, diversify, seed }) => {
+    const check = await requireBridgeForCells(cellIds);
+    if (check !== true)
+        return check;
+    let pool = allowedSamplePaths;
+    let diversifyNote = "";
+    if (!pool && diversify && diversify > 0) {
+        const locations = (await bridge.send("getDefaultLocations"));
+        const roots = Object.entries(locations ?? {})
+            .filter(([k, v]) => typeof v === "string" && v.length > 0 && /sample/i.test(k))
+            .map(([, v]) => v);
+        if (roots.length) {
+            const byFolder = await collectLibraryByFolder(roots);
+            const spread = spreadAcrossFolders(byFolder, diversify, seed ?? 0);
+            if (spread.length >= 4) {
+                pool = spread;
+                diversifyNote = ` Diversified: ${spread.length} samples drawn across ${byFolder.size} folders (diversify ${diversify}, seed ${seed ?? 0}).`;
+            }
+            else {
+                diversifyNote = " Diversify found too few samples to build a pool; fell back to the normal library scan.";
+            }
+        }
+        else {
+            diversifyNote = " Diversify could not resolve a sample library root; fell back to the normal library scan.";
+        }
+    }
+    await bridge.send("randomizeSamples", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, excludedFolders ?? [], pool ?? []);
+    return json({ status: "queued", target: "samples", cellIds, genreHint,
+        note: "Poll get_state section:'cells' for changed sample paths before another randomize, patterns, edit, or save." + diversifyNote });
 });
 server.registerTool("randomize_patterns", {
     title: "Randomize Patterns",
-    description: "Use PAM's native pattern generation engine to create musically coherent note patterns based on genre and BPM. Analyzes loaded samples to determine roles (kick, snare, hat, etc.) and generates appropriate rhythms.",
+    description: "Use PAM's native pattern generation engine to create note patterns based on loaded sample roles, genre, and BPM. " +
+        "Identical to randomize target:'sequences'. Returns queued: poll get_state for changed cellN_midiSequence values " +
+        "before another randomize, edit, or save. Wait for sample loading/randomization first; concurrent requests can coalesce.",
     inputSchema: {
         cellIds: z
             .array(z.number().min(1).max(8))
@@ -1937,18 +2771,34 @@ server.registerTool("randomize_patterns", {
             .min(0)
             .max(1)
             .optional()
-            .describe("How much to vary from typical patterns (0 = conventional, 1 = experimental). Default ~0.5."),
+            .describe("How much to vary from typical patterns (0 = conventional, 1 = experimental). Default ~0.5. " +
+            "This is the pattern-side divergence lever: the generator otherwise produces the genre's most typical " +
+            "rhythm, which is exactly what makes a batch of presets feel the same; 0.7-1.0 buys rhythmic " +
+            "distinctness, low values keep a stock groove."),
+        density: z
+            .number()
+            .min(-1)
+            .max(1)
+            .optional()
+            .describe("Pattern density (-1 = sparse, 0 = neutral, 1 = dense). Omit for the genre and role default."),
+        syncopation: z
+            .number()
+            .min(-1)
+            .max(1)
+            .optional()
+            .describe("Rhythmic placement (-1 = strong beats, 0 = neutral, 1 = weaker offbeats). Omit for the genre and role default."),
     },
-}, async ({ cellIds, genreHint, bpmHint, mutationAmount }) => {
-    const check = await requireBridge();
+}, async ({ cellIds, genreHint, bpmHint, mutationAmount, density, syncopation }) => {
+    const check = await requireBridgeForCells(cellIds);
     if (check !== true)
         return check;
-    await bridge.send("randomize", "sequences", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
-    return text(`Randomized patterns${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
+    await bridge.send("randomize", "sequences", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
+    return json({ status: "queued", target: "sequences", cellIds, genreHint,
+        note: "Poll get_state for changed cellN_midiSequence values before another randomize, edit, or save." });
 });
 server.registerTool("load_variation", {
     title: "Load Variation",
-    description: "Switch to a saved variation slot (0-7). Loads the stored state for that variation including parameters, effects, patterns, and modulation. The preset must have variations saved via save_variation first.",
+    description: "Request a switch to a saved variation slot (0-7), including parameters, effects, patterns, and modulation. Empty slots are rejected. Verify currentVariation and a slot-specific value with get_state before editing or saving.",
     inputSchema: {
         index: z
             .number()
@@ -1962,7 +2812,7 @@ server.registerTool("load_variation", {
     if (check !== true)
         return check;
     await bridge.send("loadVariation", index);
-    return text(`Loaded variation ${index} (UI slot ${index + 1}).`);
+    return text(`Requested variation ${index} (UI slot ${index + 1}); verify currentVariation and the intended state with get_state before editing or saving.`);
 });
 server.registerTool("full_stop_transport", {
     title: "Full Stop Transport",
@@ -2016,7 +2866,7 @@ server.registerTool("get_mix_analysis", {
         "true/sample peak (tp/sp), PSR/PLR crest, stereo correlation, onset density, and a 25-band Bark " +
         "spectrum per cell, plus the full-mix master block. Pass refresh:true to run a new analysis " +
         "(renders each sounding cell soloed from bar 0 — takes a few seconds; audio does NOT need to be " +
-        "playing). Cached result otherwise. Requires PAM ≥ 1.17.0. PAM only.",
+        "playing). Cached result otherwise. Requires a PAM build with Mix Assist support.",
     inputSchema: {
         refresh: z.boolean().optional().describe("Run a fresh analysis instead of returning the cached one."),
         durationSeconds: z.number().min(5).max(30).optional().describe("Analysis render length (default 8 bars at the current BPM, clamped 5-30 s)."),
@@ -2034,14 +2884,32 @@ server.registerTool("get_mix_analysis", {
         while (Date.now() - t0 < 120_000) {
             await new Promise((r) => setTimeout(r, 500));
             const status = (await bridge.send("getMixAnalysis"));
-            if (status.status !== "running")
-                return json(status);
+            if (status.status !== "running") {
+                const silent = silentMixAnalysisMessage(status);
+                return silent ? error(silent) : json(status);
+            }
         }
         return error("Mix analysis timed out after 120 s.");
     }
     const result = await bridge.send("getMixAnalysis");
-    return json(result);
+    const silent = silentMixAnalysisMessage(result);
+    return silent ? error(silent) : json(result);
 });
+function silentMixAnalysisMessage(raw) {
+    if (!isRecord(raw))
+        return null;
+    const analysis = parseMixAnalysisPayload(raw.analysis);
+    if (!analysis || analysis.cells.length === 0)
+        return null;
+    const stems = [...analysis.cells, analysis.master];
+    const silent = stems.every((stem) => stem.barkDb.length > 0 &&
+        stem.onsets === 0 &&
+        (stem.lufsI === undefined || stem.lufsI <= -119) &&
+        stem.barkDb.every((band) => band <= -119));
+    return silent
+        ? "Mix analysis rendered digital silence. No balance or EQ inference is safe from this result; use live playback measurement or retry in a plugin host."
+        : null;
+}
 // Epoch of the last OFFLINE analysis suggest_mix applied moves from — the
 // stacking guard's memory (live payloads refresh their epoch, so they never
 // stay consumed). Session-scoped by design: a server restart just re-allows a
@@ -2053,7 +2921,7 @@ server.registerTool("suggest_mix", {
         "partial-loudness fader balance, pan spread, bounded masking EQ cuts, and optional compressor " +
         "settings. Returns absolute moves with per-move rationale and guard notes; apply:true lands them " +
         "as one state update. Run get_mix_analysis with refresh:true first if the mix changed. " +
-        "Requires PAM ≥ 1.17.0. PAM only.",
+        "Requires a PAM build with Mix Assist support.",
     inputSchema: {
         scopes: z
             .array(z.enum(["balance", "pan", "eq", "dynamics"]))
@@ -2071,6 +2939,9 @@ server.registerTool("suggest_mix", {
     const analysis = parseMixAnalysisPayload(r.analysis);
     if (!analysis)
         return error("Cached mix analysis is malformed — re-run get_mix_analysis with refresh:true.");
+    const silent = silentMixAnalysisMessage(r);
+    if (silent)
+        return error(silent);
     // Stacking guard (mirrors the panel's consumed-epoch gate): the engine's
     // deltas come from the analysis but land on the LIVE params, so suggesting
     // again from an analysis that was already applied doubles the correction.
@@ -2137,7 +3008,8 @@ server.registerTool("new_preset", {
 });
 server.registerTool("save_preset", {
     title: "Save Preset",
-    description: "Save the current PAM state as a new preset file with metadata. " +
+    description: "Save the current PAM state as a preset file with metadata. Omit `name` to re-save the active user preset in place " +
+        "(factory presets are refused). Every save also snapshots the current state into variation slot 0 if the bank is empty, otherwise into the active slot. " +
         "Writes to the user preset folder by default; pass `path` for a specific location. " +
         "Use `update_preset_metadata` to edit an existing preset without re-saving plugin state.",
     inputSchema: {
@@ -2188,19 +3060,12 @@ server.registerTool("save_preset", {
             return error(`Could not derive a name from the active preset path (${activePath}) — pass name explicitly.`);
         if (path === undefined)
             path = activePath;
-        try {
-            const parsed = parsePresetFile(await readFile(await resolvePresetPath(readPath), "utf-8"));
-            for (const [k, v] of Object.entries(parsed.metadata)) {
-                // Structural keys are rebuilt below; everything else (author/tags/
-                // category/…) carries over unless the caller overrode it.
-                if (["name", "factory", "path", "variations", "currentVariation"].includes(k))
-                    continue;
-                if (extras[k] === undefined)
-                    extras[k] = v;
-            }
-        }
-        catch {
-            // unreadable/new — save fresh with whatever the caller passed
+        const parsed = await readPresetForSave(readPath);
+        for (const [k, v] of Object.entries(parsed.metadata)) {
+            if (["name", "factory", "path", "variations", "currentVariation"].includes(k))
+                continue;
+            if (extras[k] === undefined)
+                extras[k] = v;
         }
     }
     const metadata = { name, factory: false };
@@ -2219,7 +3084,11 @@ server.registerTool("save_preset", {
     // the new destination starts from eight empty slots because that file does
     // not exist yet, which used to collapse every named save to one slot.
     const variationSourcePath = selectSaveVariationSourcePath(state.activePresetPath, presetRelPath);
-    const existingVariations = await readExistingVariations(variationSourcePath);
+    const hasActivePreset = typeof state.activePresetPath === "string"
+        && state.activePresetPath.length > 0 && state.activePresetPath !== "Init";
+    const source = await readPresetForSave(variationSourcePath, !hasActivePreset);
+    const existingVariations = source
+        ? variationsFromParsedPreset(source) : Array(PRESET_VARIATION_SLOTS).fill(null);
     const hasVariations = existingVariations.some((v) => v !== null);
     if (!hasVariations) {
         existingVariations[0] = variationString;
@@ -2269,49 +3138,25 @@ server.registerTool("save_variation", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    // 1. Canonical save snapshot (engine + hosted-plugin state), then shape it
     const { state, canonical } = await fetchSaveSnapshot();
     const variationString = buildVariationString(state);
-    // 2. Determine preset name and disk path — needed to read existing variations and metadata
-    let presetName = name;
-    let diskPath;
-    const activePath = state.activePresetPath;
-    if (!presetName && activePath) {
-        const filename = activePath.split("/").pop() || "";
-        presetName = filename.replace(/\.preset$/, "");
-        // Use active path for disk lookup (preserves subfolder structure).
-        // Strip "Presets/" prefix if present — resolvePresetPath already prepends
-        // the presets base directory, so "Presets/User/X" would double up to
-        // ".../Presets/Presets/User/X" and silently fail to read back variations.
-        diskPath = normalizePresetLookupPath(activePath);
-    }
-    if (!presetName && lastSavedPresetName) {
-        presetName = lastSavedPresetName;
-        diskPath = lastSavedPresetPath;
+    if (!name && state.activePresetPath === "Init") {
+        return error("No active preset. Call save_preset with a name first, or pass a name to save_variation.");
     }
+    const activePath = typeof state.activePresetPath === "string" && state.activePresetPath !== "Init"
+        ? normalizePresetLookupPath(state.activePresetPath) : "";
+    const presetName = name || (activePath.split("/").pop() || "").replace(/\.preset$/, "") || lastSavedPresetName;
     if (!presetName) {
-        return error("No preset name provided and no active preset loaded.\n" +
-            "Next call: save_preset({ name: 'Your Preset Name', ...metadata }) first, or call save_variation with name: 'Your Preset Name'.");
-    }
-    if (!diskPath) {
-        diskPath = `User/${presetName}.preset`;
-    }
-    // 3. Read existing preset metadata and variations from disk
-    let existingMeta = {};
-    let variations = Array(PRESET_VARIATION_SLOTS).fill(null);
-    try {
-        const fullPath = await resolvePresetPath(diskPath);
-        const raw = await readFile(fullPath, "utf-8");
-        const parsed = parsePresetFile(raw);
-        existingMeta = parsed.metadata;
-        variations = variationsFromParsedPreset(parsed);
-    }
-    catch {
-        // New preset or unreadable — start fresh
-    }
-    // 4. Update the target slot
+        return error("No active preset. Call save_preset with a name first, or pass a name to save_variation.");
+    }
+    const diskPath = name ? `User/${presetName}.preset`
+        : activePath || lastSavedPresetPath || `User/${presetName}.preset`;
+    const sourcePath = selectSaveVariationSourcePath(activePath, diskPath);
+    const parsed = await readPresetForSave(sourcePath, !!name && !activePath);
+    const existingMeta = parsed?.metadata ?? {};
+    const variations = parsed
+        ? variationsFromParsedPreset(parsed) : Array(PRESET_VARIATION_SLOTS).fill(null);
     variations[index] = variationString;
-    // 5. Build metadata: merge existing (preserves author/tags/etc.) then override with caller args
     const metadata = {
         ...existingMeta,
         name: presetName,
@@ -2320,12 +3165,13 @@ server.registerTool("save_variation", {
         currentVariation: index,
         ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),
     };
-    // Write to the correct subfolder path
+    delete metadata.path;
     let resultSuffix = "";
-    if (activePath && !activePath.startsWith("Factory/")) {
-        metadata.path = activePath;
+    const destinationPath = normalizePresetLookupPath(diskPath);
+    if (!name && !destinationPath.startsWith("Factory/")) {
+        metadata.path = destinationPath;
     }
-    else if (activePath?.startsWith("Factory/")) {
+    else if (sourcePath.startsWith("Factory/")) {
         // Cannot write back to factory location; savePreset will create User/{name}.preset
         resultSuffix = "\n(Note: active preset is a factory preset — saved as new user preset)";
     }
@@ -2426,12 +3272,12 @@ server.registerTool("set_bpm", {
 });
 server.registerTool("trim_sample", {
     title: "Trim Sample",
-    description: "Trim a cell's sample to its start/end markers (non-destructive crop).",
+    description: "Trim a cell's sample to its start/end markers: writes a new WAV into Samples/Resamples/Trimmed/ and points the cell at it. The original file is untouched, but a preset saved afterwards references the trimmed copy, and calling it again crops the trimmed file further.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("trimSampleForCell", cellId);
@@ -2439,12 +3285,12 @@ server.registerTool("trim_sample", {
 });
 server.registerTool("reverse_sample", {
     title: "Reverse Sample",
-    description: "Reverse a cell's loaded sample.",
+    description: "Reverse a cell's loaded sample. Writes <name>_reversed.<ext> next to the source file and points the cell at it; calling it again on an already-reversed sample restores the original instead of reversing twice.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("reverseSampleForCell", cellId);
@@ -2469,13 +3315,16 @@ server.registerTool("connection_status", {
     },
     annotations: { readOnlyHint: true },
 }, async () => {
-    const instances = await bridge.discover();
+    const discoveredInstances = await bridge.discover();
+    const instances = IS_MFX_SERVER
+        ? discoveredInstances.filter((instance) => instance.product?.trim().toLowerCase() === "mfx")
+        : discoveredInstances;
     if (instances.length === 0) {
         return structured({
             instances: [],
             connected: false,
-            note: "No running PAM instances found. To use live tools, PAM needs the MCP bridge enabled: " +
-                "start PAM (standalone or in a DAW) and the bridge will write its port to ~/.pam-mcp-bridge.json. " +
+            note: `No running ${SERVER_PRODUCT.name} instances found. To use live tools, ${SERVER_PRODUCT.name} needs the MCP bridge enabled: ` +
+                `start ${SERVER_PRODUCT.name} (standalone or in a DAW) and enable it in Settings → Experimental. ` +
                 "Offline tools (get_parameter_info, list_presets, read_preset) work without a connection.",
         });
     }
@@ -2488,11 +3337,117 @@ server.registerTool("connection_status", {
         connectedTo: bridge.getConnectedInstance(),
         note: connected
             ? instances.length > 1
-                ? "Connected. Multiple instances are running — use select_instance to drive a specific product."
-                : "Connected to PAM. All tools available."
+                ? `Connected. Multiple ${SERVER_PRODUCT.name} instances are running; use select_instance to choose; reconnects stay pinned to that instance.`
+                : `Connected to ${SERVER_PRODUCT.name}. Tool availability also depends on this plugin build, open windows, and feature settings.`
             : "Found instances but could not connect. The plugin may have shut down.",
     });
 });
+server.registerTool("situation", {
+    title: "Situation",
+    description: "One-call orientation snapshot: discovered instances, the connected instance's product/pid/executable " +
+        "(plus build mtime and a dev-build heuristic when resolvable), server and manifest identity, active preset, " +
+        "transport, and per-cell occupancy counts. Start a session here — it collapses the connection/product/build " +
+        "preflight and the first design reads into one round trip. Deeper reads: get_design_overview, design_context.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const instances = await bridge.discover().catch(() => []);
+    const connected = bridge.isConnected() || (await bridge.connect().catch(() => false)) === true;
+    if (connected)
+        syncProductHint();
+    const instance = connected ? bridge.getConnectedInstance() : null;
+    let build;
+    if (instance?.pid) {
+        try {
+            const executable = execFileSync("ps", ["-o", "comm=", "-p", String(instance.pid)], {
+                encoding: "utf8",
+            }).trim();
+            if (executable) {
+                build = {
+                    executable,
+                    looksLikeDevBuild: executable.includes("/build/") && !executable.startsWith("/Applications/"),
+                };
+                try {
+                    build.executableMtime = statSync(executable).mtime.toISOString();
+                }
+                catch {
+                    /* executable path unreadable from this process */
+                }
+                const projectRoot = process.env.PAM_PROJECT_ROOT;
+                if (projectRoot && typeof build.executableMtime === "string") {
+                    try {
+                        const headIso = execFileSync("git", ["-C", resolve(projectRoot), "log", "-1", "--format=%cI"], { encoding: "utf8" }).trim();
+                        build.repoHeadCommitTime = headIso;
+                        build.binaryOlderThanHeadCommit =
+                            new Date(build.executableMtime).getTime() < new Date(headIso).getTime();
+                    }
+                    catch {
+                        /* PAM_PROJECT_ROOT is not a git checkout */
+                    }
+                }
+            }
+        }
+        catch {
+            /* ps unavailable (Windows) or pid already gone */
+        }
+    }
+    let live;
+    let manifestName;
+    if (connected) {
+        const [stateRaw, transportRaw, manifest] = await Promise.all([
+            bridge.send("getState").catch(() => undefined),
+            bridge.send("getTransport").catch(() => undefined),
+            loadManifest().catch(() => null),
+        ]);
+        manifestName = manifest?.name;
+        const state = isRecord(stateRaw) ? stateRaw : {};
+        const transport = isRecord(transportRaw) ? transportRaw : {};
+        if (manifest) {
+            const effectNames = cellEffectNames(manifest);
+            const ids = [...new Set(manifest.parameters
+                    .map((p) => p.cell)
+                    .filter((cell) => typeof cell === "string" && /^cell\d+$/.test(cell))
+                    .map((cell) => Number(cell.replace("cell", ""))))].sort((a, b) => a - b);
+            const cellsObj = isRecord(state.cells) ? state.cells : {};
+            const cells = ids.map((id) => {
+                const prefix = `cell${id}_`;
+                const rawCellState = cellsObj[String(id)];
+                const cellState = isRecord(rawCellState) ? rawCellState : {};
+                const samplePath = cellState.filePath ??
+                    cellState.samplePath ??
+                    state[`${prefix}filePath`] ??
+                    state[`${prefix}samplePath`];
+                const synth = IS_MFX_SERVER ? undefined : describeSynthEngine(state[`${prefix}synthEngine`]);
+                return {
+                    cellId: id,
+                    sample: stemName(samplePath),
+                    synthEngine: synth && synth.id > 0 ? synth.name : undefined,
+                    muted: state[`${prefix}mute`] === 1 || state[`${prefix}mute`] === true,
+                    enabledEffects: effectNames.filter((n) => state[`${prefix}${n}Enabled`] === 1 || state[`${prefix}${n}Enabled`] === true).length,
+                };
+            });
+            live = {
+                activePreset: state.activePresetPath,
+                bpm: state.bpm ?? transport.bpm,
+                playing: transport.playing,
+                cells,
+                ...(IS_MFX_SERVER ? { mix: state.mfx_mix, routing: state.mfx_routing } : {}),
+            };
+        }
+    }
+    return json({
+        server: { name: SERVER_PRODUCT.name, version: SERVER_VERSION },
+        instances,
+        connected,
+        instance,
+        manifest: manifestName,
+        build,
+        live,
+        note: connected
+            ? undefined
+            : "Not connected. connection_status has enable instructions; offline tools still work.",
+    });
+});
 server.registerTool("select_instance", {
     title: "Select Plugin Instance",
     description: "Choose which running plugin instance (PAM / CELL1 / MFX) the live tools drive when more than " +
@@ -2514,9 +3469,16 @@ server.registerTool("select_instance", {
     if (!product && !instanceId && port === undefined) {
         return error("Pass at least one of product, instanceId, or port. Call connection_status to list running instances.");
     }
-    const ok = await bridge.connect({ product, instanceId, port });
+    if (IS_MFX_SERVER && product && product.trim().toLowerCase() !== "mfx") {
+        return error("The mfx-mcp launcher can select MFX instances only.");
+    }
+    const targetProduct = IS_MFX_SERVER ? "MFX" : product;
+    const ok = await bridge.connect({ product: targetProduct, instanceId, port });
     if (!ok) {
-        const instances = await bridge.discover();
+        const discovered = await bridge.discover();
+        const instances = IS_MFX_SERVER
+            ? discovered.filter((instance) => instance.product?.trim().toLowerCase() === "mfx")
+            : discovered;
         const listing = instances.length
             ? ` Running instances: ${instances
                 .map((i) => `${i.product} (port ${i.port}, id ${i.instanceId})`)
@@ -2573,6 +3535,69 @@ async function searchSampleLibrary(rootPath, term, audioOnly) {
     }
     return matches;
 }
+// Walk the library and return audio files grouped by their parent folder.
+// Bounded like searchSampleLibrary — this runs inside a tool call, not a job.
+async function collectLibraryByFolder(roots, maxDirReads = 120) {
+    const byFolder = new Map();
+    const queue = roots.map((path) => ({ path, depth: 0 }));
+    const options = JSON.stringify({ audioOnly: true, sort: "name" });
+    let dirReads = 0;
+    while (queue.length && dirReads < maxDirReads) {
+        const { path, depth } = queue.shift();
+        dirReads += 1;
+        let entries = [];
+        try {
+            const res = await bridge.send("listDirectory", path, options);
+            if (Array.isArray(res))
+                entries = res;
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (typeof e.path !== "string")
+                continue;
+            if (e.isDir) {
+                if (depth < 3)
+                    queue.push({ path: e.path, depth: depth + 1 });
+            }
+            else {
+                const list = byFolder.get(path) ?? [];
+                list.push(e.path);
+                byFolder.set(path, list);
+            }
+        }
+    }
+    return byFolder;
+}
+// Build a sample pool that deliberately SPANS folders instead of collapsing
+// into one pack.
+//
+// WHY: randomize_samples' native engine scores folder coherence, which is the
+// right default (a kit from one pack sounds like a kit) and the wrong one when
+// the brief is "something we haven't heard" — coherence pulls every result
+// toward the same few well-stocked folders. Restricting the engine to a
+// cross-folder pool keeps its role assignment while removing its ability to
+// converge. Deterministic given the same seed, so a diverged kit can be
+// reproduced.
+function spreadAcrossFolders(byFolder, diversify, seed) {
+    const folders = [...byFolder.keys()].sort();
+    if (!folders.length)
+        return [];
+    // At diversify 1 every folder contributes a single file (maximum spread); at
+    // low values a few folders contribute many (close to normal behaviour).
+    const perFolder = Math.max(1, Math.round(12 - 11 * diversify));
+    const folderCount = Math.max(1, Math.min(folders.length, Math.round(2 + (folders.length - 2) * diversify)));
+    const start = folders.length ? seed % folders.length : 0;
+    const pool = [];
+    for (let i = 0; i < folderCount; i += 1) {
+        const files = byFolder.get(folders[(start + i) % folders.length]) ?? [];
+        for (let j = 0; j < Math.min(perFolder, files.length); j += 1) {
+            pool.push(files[(seed + j * 7) % files.length]);
+        }
+    }
+    return [...new Set(pool)];
+}
 // Search-result payloads feed the assistant's 256-token continuation round —
 // trim to that budget instead of letting the listing collapse to an opaque
 // truncation string (executor parity: assistantExecutor.ts fitListing).
@@ -2587,14 +3612,12 @@ function fitListing(base, itemsKey, items, moreKey, total) {
 }
 server.registerTool("list_samples", {
     title: "List Samples",
-    description: "Browse sample library directories. IMPORTANT: Do NOT guess paths — always call " +
-        "get_default_locations first to discover the actual library paths, then use those " +
-        "paths here. Paths vary per user and platform.",
+    description: "Browse sample library directories. Library paths vary per user and platform, so take them from " +
+        "get_default_locations rather than guessing.",
     inputSchema: {
         path: z
             .string()
-            .describe("Directory path to list. MUST be a path returned by get_default_locations " +
-            "or a subdirectory of one. Do not guess paths like ~/Music/PAM."),
+            .describe("Directory path to list: a path from get_default_locations, or a subdirectory of one."),
         audioOnly: z
             .boolean()
             .default(true)
@@ -2683,8 +3706,9 @@ server.registerTool("get_audio_info", {
 });
 server.registerTool("export_preset", {
     title: "Export Preset",
-    description: "Export a preset as a zip file bundled with all referenced samples. " +
-        "Creates a shareable preset package.",
+    description: "Export a preset as a zip file bundled with all referenced samples, written to PAM's Exports folder as " +
+        "<outputFolderName>.zip (get_default_locations resolves that folder). An existing folder or zip of that " +
+        "name is replaced, and presets belonging to a preset pack are refused.",
     inputSchema: {
         presetPath: z
             .string()
@@ -2702,7 +3726,10 @@ server.registerTool("export_preset", {
 });
 server.registerTool("import_preset", {
     title: "Import Preset",
-    description: "Import a preset from a zip file or folder into PAM's preset library.",
+    description: "Import a preset from a zip file or folder into PAM's preset library. Returns the relative path of the " +
+        "first imported preset, or an empty string on failure. Referenced samples are copied into the user sample " +
+        "folder and the preset's paths are rewritten. A name already in the library is never overwritten: the " +
+        "import lands as <name>_1, <name>_2 and so on.",
     inputSchema: {
         path: z.string().describe("Absolute path to the preset zip file or folder to import."),
     },
@@ -2912,7 +3939,7 @@ server.registerTool("capture_ui", {
         "PresetBrowser; omit/null = cell grid), instrumentView ('synth'|'sampler', applied to " +
         "all cells). REQUIRES PAM's window OPEN — html2canvas needs the live DOM, there is no " +
         "headless renderer (same constraint as the video tools). Beats screen-capture: " +
-        "deterministic, no cursor/screen control, exact UI bitmap.",
+        "deterministic, no cursor/screen control, exact UI bitmap. View arguments switch the live editor and the previous view is not restored.",
     inputSchema: {
         gridSize: z.number().optional().describe("Cell grid size to set before capture: 1, 4, or 8."),
         mainView: z
@@ -2926,7 +3953,7 @@ server.registerTool("capture_ui", {
         settleMs: z.number().optional().describe("Delay (ms) after view changes before rasterizing. Default 350."),
         timeoutMs: z.number().optional().default(8000).describe("Max ms to wait for the WebView to return the image."),
     },
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 }, async ({ gridSize, mainView, instrumentView, settleMs, timeoutMs }) => {
     const check = await requireBridge();
     if (check !== true)
@@ -3306,13 +4333,23 @@ server.registerTool("set_video_settings", {
         "loads on the next bar boundary while playing). resetWorkspace clears the " +
         "scene (preserves the master layer).",
     inputSchema: {
-        syncMode: z.enum(["off", "beat-sync", "beat-match"]).optional(),
-        loopBars: z.number().optional(),
-        aspectRatio: z.enum(["auto", "16:9", "4:3", "1:1", "stretch"]).optional(),
-        renderQuality: z.enum(["low", "medium", "high"]).optional(),
-        designAspect: z.number().nullable().optional(),
-        letterboxColor: z.string().optional(),
-        canvasColor: z.string().optional(),
+        syncMode: z
+            .enum(["off", "beat-sync", "beat-match"])
+            .optional()
+            .describe("Clock source: 'off' free-runs, 'beat-sync' locks playback to the bar grid, 'beat-match' retimes clips to the transport."),
+        loopBars: z.number().min(0).optional().describe("Loop length in bars for the beat-sync and beat-match modes."),
+        aspectRatio: z
+            .enum(["auto", "16:9", "4:3", "1:1", "stretch"])
+            .optional()
+            .describe("How a layer is fitted to the canvas. 'auto' keeps the source ratio, 'stretch' fills it."),
+        renderQuality: z.enum(["low", "medium", "high"]).optional().describe("VX render resolution/effort tier."),
+        designAspect: z
+            .number()
+            .nullable()
+            .optional()
+            .describe("Canvas design ratio as width/height (e.g. 1.7777 for 16:9). null clears it and follows the window."),
+        letterboxColor: z.string().describe("#hex fill for the bars outside the design aspect.").optional(),
+        canvasColor: z.string().describe("#hex background behind every VX layer.").optional(),
         modEnabled: z.boolean().optional().describe("Mod-matrix master enable."),
         vxVariationFollowAudio: z
             .boolean()
@@ -3434,8 +4471,9 @@ const PATTERN_SUFFIXES = [
 ];
 server.registerTool("reset_cell", {
     title: "Reset Cell",
-    description: "Reset all parameters of a single cell to their default values and remove " +
-        "any envelopes targeting this cell. Does not touch other cells.",
+    description: "Reset a single cell's manifest parameters to their defaults and remove the envelopes whose SOURCE is this cell. " +
+        "Untouched: envelopes targeting this cell from another source (clear_modulations), pattern lanes (reset_patterns), " +
+        "the cell config block (update_cell_config) and the loaded sample. Does not touch other cells.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -3468,8 +4506,9 @@ server.registerTool("reset_cell", {
 });
 server.registerTool("copy_cell", {
     title: "Copy Cell",
-    description: "Copy all parameters and modulation from one cell to another. " +
-        "Overwrites the target cell's settings.",
+    description: "Copy a cell's manifest parameters and remap its LFO, envelope and vary links onto another cell, overwriting the target's. " +
+        "Not copied: the loaded sample, parameter sequencers, and the cell config block (polyphony, MIDI note/channel, scale, " +
+        "sidechain source, pitch/stretch engine, slice keymap) — re-apply those with load_sample and update_cell_config.",
     inputSchema: {
         sourceCellId: z.number().min(1).max(8).describe("Source cell (1-8)."),
         targetCellId: z.number().min(1).max(8).describe("Target cell (1-8)."),
@@ -3579,7 +4618,7 @@ server.registerTool("copy_cell", {
 server.registerTool("clear_modulations", {
     title: "Clear Modulations",
     description: "Remove all LFO, envelope, and vary modulation links targeting a cell's parameters " +
-        "(or originating from that cell, for envelopes/vary). Useful for starting fresh on a cell.",
+        "(or originating from that cell, for envelopes/vary). Parameter sequencers survive — use remove_param_seq for those.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -3651,8 +4690,8 @@ server.registerTool("reset_patterns", {
 });
 server.registerTool("update_effect_config", {
     title: "Update Effect Config",
-    description: "Toggle cell effects on/off (filter, delay, crusher, flanger, eq, eq8, fdn, gate, compressor, panner, gain, vocoder, limiter, qverb, wavefold, resonator). " +
-        "wavefold and resonator exist on MFX only. " +
+    description: "Toggle cell effects on/off (filter, delay, crusher, flanger, chorus, phaser, eq, eq8, tablefilter, fdn, gate, compressor, panner, gain, vocoder, ringmod, vinylbrake, transient, repeat, pitchshift, limiter, qverb, shimmer, wavefold, resonator). " +
+        "Wavefold and Resonator ship in every product. Exact availability comes from the selected product manifest. " +
         "Uses the lighter KV path that does not rebuild the audio graph. Pass 1 to enable, 0 to disable.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
@@ -3664,7 +4703,7 @@ server.registerTool("update_effect_config", {
         fdnEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         gateEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
-        // The page-2 effects. These ship on PAM/Cell1 too, so leaving them out of the
+        // Shared extended effects. These ship on PAM/Cell1 too, so leaving them out of the
         // schema made them unreachable over the bridge even though the handler is
         // generic (it just builds `cell{N}_{key}`) and the state vars exist in
         // build.js alongside the eight above.
@@ -3672,10 +4711,19 @@ server.registerTool("update_effect_config", {
         pannerEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         gainEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         vocoderEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        ringmodEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        vinylbrakeEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        transientEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        repeatEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        pitchshiftEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         qverbEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
-        // MFX-only page-2 signature effects; harmless no-ops on PAM/Cell1, whose
-        // manifests carry no cellN_wavefoldEnabled / cellN_resonatorEnabled key.
+        chorusEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        phaserEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        shimmerEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        tablefilterEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        // Product-specific extended effects. The handler rejects flags absent from
+        // the connected product instead of relying on the bridge to ignore them.
         wavefoldEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         resonatorEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
     },
@@ -3687,10 +4735,20 @@ server.registerTool("update_effect_config", {
     const cellCheck = validateCellIdForManifest(cellId, manifest);
     if (cellCheck !== true)
         return cellCheck;
+    if (!manifest) {
+        return error("The selected product manifest is unavailable; effect availability cannot be validated safely.");
+    }
+    const availableEffects = new Set(cellEffectNames(manifest));
     const delta = {};
     for (const [key, value] of Object.entries(config)) {
-        if (value !== undefined)
-            delta[`cell${cellId}_${key}`] = value;
+        if (value === undefined)
+            continue;
+        const effect = key.endsWith("Enabled") ? key.slice(0, -"Enabled".length) : key;
+        if (!availableEffects.has(effect)) {
+            return error(`${effect} is not available in ${manifest.name ?? "the selected product"}. ` +
+                `Available effects: ${[...availableEffects].join(", ")}.`);
+        }
+        delta[`cell${cellId}_${key}`] = value;
     }
     if (Object.keys(delta).length === 0) {
         return error("At least one effect flag must be provided.");
@@ -3705,11 +4763,16 @@ server.registerTool("update_effect_config", {
 // unreachable through set_parameters (numbers only) — an agent could shape an MFX
 // cell but never patch one to another, which is the whole product.
 //
-// Validation mirrors parseRoutingEdges (interface/src/dsp/mfxRouting.ts): the
+// Validation mirrors parseRoutingEdges (interface/src/dsp/products/mfx/mfxRouting.ts): the
 // plugin re-validates on receipt, so this pass exists to fail loudly here rather
 // than have a typo silently drop a cable.
-const MFX_ROUTING_SOURCE_HINT = "'input', 'sidechain', or 'cellN'. 'output' is a destination only.";
-const MFX_ROUTING_SINK_HINT = "'output' or 'cellN'. 'input'/'sidechain' are sources only.";
+const MFX_ROUTING_SOURCE_HINT = "'input', 'sidechain', 'split_lo' / 'split_mid' / 'split_hi', or 'cellN'. " +
+    "'output' and 'split' are destinations only.";
+const MFX_ROUTING_SINK_HINT = "'output', 'split', or 'cellN'. 'input', 'sidechain' and the three split bands are sources only.";
+// SPLIT — the three-band crossover patch node. One sink, three band sources.
+const MFX_SPLIT_SINK = "split";
+const MFX_SPLIT_BANDS = ["split_lo", "split_mid", "split_hi"];
+const isMfxSplitBand = (port) => MFX_SPLIT_BANDS.includes(port);
 function mfxPortCell(port) {
     const m = /^cell([1-9]\d*)$/.exec(port); // canonical form only — 'cell01' is not a port
     return m ? Number(m[1]) : null;
@@ -3722,12 +4785,23 @@ function validateMfxEdges(edges, maxCells) {
         return c !== null && c >= 1 && c <= maxCells;
     };
     for (const { from, to } of edges) {
-        if (from !== "input" && from !== "sidechain" && !inRange(from)) {
+        if (from !== "input" && from !== "sidechain" && !isMfxSplitBand(from) && !inRange(from)) {
             return { ok: false, reason: `invalid source port '${from}' — expected ${MFX_ROUTING_SOURCE_HINT}` };
         }
-        if (to !== "output" && !inRange(to)) {
+        if (to !== "output" && to !== MFX_SPLIT_SINK && !inRange(to)) {
             return { ok: false, reason: `invalid destination port '${to}' — expected ${MFX_ROUTING_SINK_HINT}` };
         }
+        // Only a source ENDPOINT may feed the crossover. Mirrors parseRoutingEdges: SPLIT sits
+        // outside the cell evaluation order, so a cell→split cable would put it inside a cycle
+        // the plugin's resolver cannot see. The plugin drops such a cable silently; failing here
+        // is what tells the agent why its patch came back short.
+        if (to === MFX_SPLIT_SINK && from !== "input" && from !== "sidechain") {
+            return {
+                ok: false,
+                reason: `'${from}' cannot feed '${MFX_SPLIT_SINK}' — only 'input' and 'sidechain' can. ` +
+                    "Split what arrives, then patch the bands.",
+            };
+        }
         const key = `${from}->${to}`;
         if (seen.has(key))
             continue; // dedupe, matching the plugin
@@ -3742,6 +4816,11 @@ server.registerTool("set_mfx_routing", {
         "this returns a product error.\n\n" +
         "Ports: 'input' (the host's audio in) and 'sidechain' are sources; 'output' is the destination; 'cellN' is both. " +
         "A self-edge cellN→cellN is a feedback loop, and input→output is a direct dry path. Duplicate cables are dropped.\n\n" +
+        "SPLIT is a three-band crossover node: cable 'input' (or 'sidechain') to 'split', then patch 'split_lo', " +
+        "'split_mid' and 'split_hi' to different cells. Each band then has its own full FX rack, its own modulation " +
+        "and its own sidechain key — which is how you build a multiband gate or a multiband distortion here. Only " +
+        "'input' and 'sidechain' may feed 'split'; the bands are sources only. Its two corner frequencies are the " +
+        "ordinary parameters mfx_split_lo_hz and mfx_split_hi_hz (set_parameters).\n\n" +
         "A plain serial chain on 4 cells is input→cell1, cell1→cell2, cell2→cell3, cell3→cell4, cell4→output. " +
         "Parallel is input→each cell plus each cell→output.\n\n" +
         "'set' REPLACES the whole patch, so send the full cable list. Per-cable levels live in mfx_edge_gains and are " +
@@ -3783,6 +4862,258 @@ server.registerTool("set_mfx_routing", {
     const summary = validated.edges.map((e) => `${e.from}→${e.to}`).join(", ");
     return text(`MFX routing set: ${validated.edges.length} cable(s)${summary ? ` — ${summary}` : " (patch cleared)"}.`);
 });
+server.registerTool("set_mfx_edge_gain", {
+    title: "Set MFX Cable Gain",
+    description: "Read or set the gain for one cable in the current MFX patch. Gain is linear: 0 is silent, 1 is unity, " +
+        "and 1.5 is the maximum. The cable must already exist. Other cable gains are preserved.",
+    inputSchema: {
+        op: z.enum(["get", "set"]).describe("'get' returns every cable gain; 'set' writes one."),
+        from: z.string().optional().describe(`Cable source for 'set': ${MFX_ROUTING_SOURCE_HINT}`),
+        to: z.string().optional().describe(`Cable destination for 'set': ${MFX_ROUTING_SINK_HINT}`),
+        gain: z.number().min(0).max(1.5).optional().describe("Linear gain for 'set'."),
+    },
+}, async ({ op, from, to, gain }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (!manifest || !isMfxManifest(manifest))
+        return error("set_mfx_edge_gain is MFX-only.");
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const gains = isRecord(state.mfx_edge_gains) ? { ...state.mfx_edge_gains } : {};
+    if (op === "get")
+        return json(gains);
+    if (!from || !to || typeof gain !== "number")
+        return error("op 'set' requires from, to, and gain.");
+    const validated = validateMfxEdges([{ from, to }], manifestMaxCellId(manifest) ?? 4);
+    if (!validated.ok)
+        return error(validated.reason);
+    const edges = Array.isArray(state.mfx_routing) ? state.mfx_routing : [];
+    const exists = edges.some((edge) => isRecord(edge) && edge.from === from && edge.to === to);
+    if (!exists)
+        return error(`Cable ${from}→${to} is not in the current patch. Add it with set_mfx_routing first.`);
+    const key = `${from}__${to}`;
+    gains[key] = gain;
+    await applyKv({ mfx_edge_gains: gains }, KV_OPTS_EFFECT_CONFIG);
+    return text(`MFX cable gain set: ${from}→${to} = ${gain}.`);
+});
+const MFX_COMBO_TARGET_INPUT = z.object({
+    paramId: z.string(),
+    from: z.number().optional(),
+    mid: z.number().optional(),
+    to: z.number().optional(),
+});
+server.registerTool("configure_mfx_combo", {
+    title: "Configure MFX Combo",
+    description: "Read, edit, or move one of MFX's three performance combos. Automatic assignments follow the audible patch. " +
+        "Manual target edits materialize and lock the assignment. setValue writes the combo parameter and its real targets " +
+        "in one native state update, so it works with the MFX window closed.",
+    inputSchema: {
+        op: z.enum([
+            "get", "setValue", "rename", "lock", "unlock", "rescan", "setTargets", "addTarget",
+            "removeTarget", "clearTargets", "invertTarget", "setTargetStop", "anchor",
+        ]).describe("get reads the combo; setValue writes its value and every resolved target; rename relabels it (blank restores the role label); " +
+            "lock freezes the current automatic assignment as manual; unlock and rescan return it to automatic; " +
+            "setTargets/addTarget/removeTarget/clearTargets edit the manual target list; invertTarget swaps a target's from/to stops; " +
+            "setTargetStop sets one target's stop value; anchor re-derives every target's stops from the current parameter values."),
+        index: z.number().int().min(1).max(3).default(1),
+        value: z.number().optional().describe("Combo value (−100 to 100) for setValue, or a value in the target parameter's units for setTargetStop."),
+        name: z.string().max(24).optional().describe("New label for rename; blank restores the role label."),
+        paramId: z.string().optional().describe("Target parameter for add/remove/invert/setTargetStop."),
+        stop: z.enum(["from", "mid", "to"]).optional().describe("Target stop edited by setTargetStop."),
+        targets: z.array(MFX_COMBO_TARGET_INPUT).max(6).optional().describe("Complete target list for setTargets."),
+    },
+}, async ({ op, index, value, name, paramId, stop, targets }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifest();
+    if (!isMfxManifest(manifest))
+        return error("configure_mfx_combo is MFX-only.");
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const resolved = resolveServerMfxCombos(state, manifest);
+    const combo = resolved[index - 1];
+    const slots = parseMfxComboSlots(state.mfx_combos);
+    const stored = slots[String(index)] ?? {};
+    const parameterIndex = new Map(manifest.parameters.map((parameter) => [parameter.paramId, parameter]));
+    if (op === "get")
+        return json({ combos: resolved.map((entry) => ({ ...entry, value: state[`mfx_combo${entry.index}`] })) });
+    if (op === "setValue") {
+        if (typeof value !== "number")
+            return error("setValue requires value.");
+        if (value < -100 || value > 100)
+            return error("Combo value must be between -100 and 100.");
+        const delta = { [`mfx_combo${index}`]: value };
+        for (const target of combo.targets) {
+            const info = parameterIndex.get(target.id);
+            if (!info)
+                continue;
+            const previousComboValue = state[`mfx_combo${index}`];
+            const currentTargetValue = state[target.id];
+            delta[target.id] = mfxComboTargetValueFromCurrent(target, typeof previousComboValue === "number" ? previousComboValue : 0, value, info, typeof currentTargetValue === "number" ? currentTargetValue : info.defaultValue);
+        }
+        await applyKv(delta, KV_OPTS_STANDARD);
+        return json({ combo: index, value, targetsWritten: combo.targets.map((target) => target.id) });
+    }
+    const materialized = () => ({ ...stored, targets: [...combo.targets] });
+    let next = stored;
+    if (op === "rename") {
+        if (name === undefined)
+            return error("rename requires name.");
+        next = { ...stored };
+        const trimmed = name.trim().slice(0, 24);
+        if (trimmed)
+            next.name = trimmed;
+        else
+            delete next.name;
+    }
+    else if (op === "lock") {
+        next = { ...materialized(), locked: 1 };
+    }
+    else if (op === "unlock" || op === "rescan") {
+        next = stored.name ? { name: stored.name } : null;
+    }
+    else {
+        let edited = materialized();
+        if (op === "setTargets") {
+            if (!targets)
+                return error("setTargets requires targets.");
+            const built = [];
+            for (const target of targets) {
+                const info = parameterIndex.get(target.paramId);
+                if (!info || !isMfxComboTargetParameter(info)) {
+                    return error(`'${target.paramId}' is not an available MFX combo target.`);
+                }
+                if (built.some((candidate) => candidate.id === target.paramId)) {
+                    return error(`'${target.paramId}' appears more than once in targets.`);
+                }
+                const current = state[target.paramId];
+                let builtTarget = buildMfxComboTarget(target.paramId, info, MFX_COMBO_MANUAL_STRENGTH, 1, typeof current === "number" ? current : info.defaultValue);
+                for (const targetStop of ["from", "mid", "to"]) {
+                    const targetValue = target[targetStop];
+                    if (typeof targetValue === "number")
+                        builtTarget = setMfxComboTargetStop(builtTarget, info, targetStop, targetValue);
+                }
+                built.push(builtTarget);
+            }
+            edited.targets = built;
+        }
+        else if (op === "clearTargets") {
+            edited.targets = [];
+        }
+        else if (op === "anchor") {
+            edited.targets = edited.targets.map((target) => {
+                const info = parameterIndex.get(target.id);
+                const current = state[target.id];
+                return info && typeof current === "number" ? reanchorMfxComboTarget(target, info, current) : target;
+            });
+        }
+        else {
+            if (!paramId)
+                return error(`${op} requires paramId.`);
+            const info = parameterIndex.get(paramId);
+            if (!info || !isMfxComboTargetParameter(info)) {
+                return error(`'${paramId}' is not an available MFX combo target.`);
+            }
+            if (op === "addTarget") {
+                if (!edited.targets.some((target) => target.id === paramId)) {
+                    if (edited.targets.length >= 6)
+                        return error("A combo can drive at most 6 targets.");
+                    const current = state[paramId];
+                    edited.targets.push(buildMfxComboTarget(paramId, info, MFX_COMBO_MANUAL_STRENGTH, 1, typeof current === "number" ? current : info.defaultValue));
+                }
+            }
+            else if (op === "removeTarget") {
+                edited.targets = edited.targets.filter((target) => target.id !== paramId);
+            }
+            else if (op === "invertTarget") {
+                edited.targets = edited.targets.map((target) => target.id === paramId
+                    ? { id: target.id, from: target.to, mid: target.mid, to: target.from }
+                    : target);
+            }
+            else if (op === "setTargetStop") {
+                if (!stop || typeof value !== "number")
+                    return error("setTargetStop requires paramId, stop, and value.");
+                if (!edited.targets.some((target) => target.id === paramId)) {
+                    return error(`'${paramId}' is not assigned to combo ${index}.`);
+                }
+                edited.targets = edited.targets.map((target) => target.id === paramId
+                    ? setMfxComboTargetStop(target, info, stop, value)
+                    : target);
+            }
+        }
+        next = { ...edited, locked: 1 };
+    }
+    const update = {
+        name: next?.name ?? null,
+        locked: next?.locked === 1 ? 1 : 0,
+        targets: Array.isArray(next?.targets) ? next.targets : null,
+    };
+    await applyKv({ mfx_combos: { ...slots, [String(index)]: update } }, KV_OPTS_EFFECT_CONFIG);
+    return json({ combo: index, slot: update });
+});
+server.registerTool("set_effect_order", {
+    title: "Set Cell FX Chain Order",
+    description: "Read or replace one cell's FX chain order. cellN_effectOrder is a JSON string array, not a numeric " +
+        "parameter, so set_parameters cannot reach it — this tool owns it (the set_mfx_routing precedent).\n\n" +
+        "The available stages and their fresh-cell order are product-specific and come from the selected manifest; " +
+        "design_context reports that default order. 'set' REPLACES the chain, so send every listed stage " +
+        "in the order you want it to process; the array must be a permutation, not a subset (use the per-effect " +
+        "*Enabled flags via update_effect_config to switch stages off).\n\n" +
+        "Order is audible and is a cheap way to make two otherwise identical patches sound different: filter before " +
+        "delay smears the resonance into the repeats, delay before filter darkens the repeats instead. Crusher " +
+        "before filter grinds then tames; filter before crusher grinds only what survived. Reordering rebuilds the " +
+        "cell's graph.",
+    inputSchema: {
+        cellId: z.number().int().min(1).max(8).describe("Cell to read or reorder."),
+        op: z.enum(["get", "set"]).default("set").describe("'get' reads the current chain; 'set' replaces it."),
+        order: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Full product-specific chain order for 'set' — a permutation of every stage reported by design_context."),
+    },
+    annotations: { destructiveHint: false, idempotentHint: true },
+}, async ({ cellId, op, order }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const key = `cell${cellId}_effectOrder`;
+    if (op === "get") {
+        const raw = await bridge.send("getState", key);
+        return json(isRecord(raw) ? raw[key] ?? raw : raw);
+    }
+    if (!order)
+        return error("op 'set' requires an `order` array.");
+    const manifest = await loadManifestForProductGuard();
+    if (!manifest) {
+        return error("The selected product manifest is unavailable; its complete FX chain cannot be validated safely.");
+    }
+    const expectedOrder = cellEffectOrder(manifest);
+    if (expectedOrder.length === 0) {
+        return error(`${manifest.name ?? "The selected product"} manifest has no valid cell1_effectOrder default.`);
+    }
+    const seen = new Set(order);
+    if (seen.size !== order.length) {
+        const dupes = order.filter((s, i) => order.indexOf(s) !== i);
+        return error(`Duplicate stage(s) in order: ${[...new Set(dupes)].join(", ")}.`);
+    }
+    // A subset would silently drop stages from the chain rather than bypass
+    // them, so it is rejected here instead of at the plugin.
+    const expected = new Set(expectedOrder);
+    const unknown = order.filter((stage) => !expected.has(stage));
+    const missing = expectedOrder.filter((stage) => !seen.has(stage));
+    if (unknown.length || missing.length) {
+        return error(`order must be a full ${manifest.name ?? "product"} permutation` +
+            `${unknown.length ? ` — unknown: ${[...new Set(unknown)].join(", ")}` : ""}` +
+            `${missing.length ? ` — missing: ${missing.join(", ")}` : ""}. ` +
+            "To bypass a stage set its *Enabled flag via update_effect_config; leaving it out of the chain is not the same thing.");
+    }
+    // effectOrder rebuilds the cell's FX graph, like an MFX re-patch.
+    await applyKv({ [key]: order }, KV_OPTS_STANDARD);
+    return text(`Cell ${cellId} FX chain: ${order.join(" → ")}.`);
+});
 server.registerTool("update_cell_config", {
     title: "Update Cell Config",
     description: "Update cell-level configuration properties like polyphony, MIDI settings, varispeed, and modulation latch. " +
@@ -3830,8 +5161,8 @@ server.registerTool("update_cell_config", {
             "An out-of-vocabulary string would silently play as chromatic while junk persists into the preset, so the name is validated."),
         scaleRoot: z.number().min(0).max(11).optional().describe("Root note of the scale (0=C, 1=C#, ..., 11=B)."),
         pitchMode: z.number().int().min(0).max(3).optional().describe("Pitch engine: 0=Varispeed, 1=Formant, 2=Pitch Shift Quantize, 3=Varispeed Quantize."),
-        stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=OLA, 1=Cloud, 2=Phase Vocoder, 3=GrainRate."),
-        quantScale: z.number().int().min(0).max(9).optional().describe("Pitch quantize scale when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=Chromatic, 1=Major, 2=Minor, 3=Penta Maj, 4=Penta Min, 5=Dorian, 6=Mixolydian, 7=Blues, 8=Harm Min, 9=Phrygian. Order locked to QuantScale in modules/helpers/Scale.h."),
+        stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=Default (OLA), 1=Cloud, 2=Spectral, 3=Beats."),
+        quantScale: z.number().int().min(0).max(9).optional().describe("Pitch quantize scale when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=Chromatic, 1=Major, 2=Minor, 3=Penta Maj, 4=Penta Min, 5=Dorian, 6=Mixolydian, 7=Blues, 8=Harm Min, 9=Phrygian. Order locked to QuantScale in modules/dsp-core/Scale.h."),
         quantRoot: z.number().int().min(0).max(11).optional().describe("Pitch quantize root when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=C, 1=C#, ..., 11=B."),
         grainDensity: z.number().int().min(1).max(24).optional().describe("Cloud stretch grain density when stretchMode=1."),
         grainWindow: z.number().int().min(0).max(4).optional().describe("Cloud stretch grain envelope when stretchMode=1: 0=Hann, 1=Tukey, 2=Welch, 3=Punch, 4=Swell."),
@@ -3909,7 +5240,7 @@ server.registerTool("set_cell_mute", {
     description: "Mute, unmute, solo, or unsolo a cell in the mixer — the real channel mute/solo, cutting the whole channel " +
         "(source + all effect tails) rather than pulling the volume fader down. Soloing a cell silences every other " +
         "non-soloed cell until unsoloed. cell{N}_mute / cell{N}_solo are live-polled state variables (no graph rebuild). " +
-        "Prefer this over set_parameter volume -60 when the user says mute, unmute, solo, unsolo, isolate, or 'just this cell'.",
+        "Prefer this over pulling cell{N}_volume down: a fader move leaves effect tails audible, a channel mute cuts them.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         mute: z.boolean().optional().describe("Mute (true) or unmute (false) the cell's channel."),
@@ -3950,11 +5281,7 @@ server.registerTool("set_master_effects", {
         "Check results with get_master_analysis (keep tp <= -1 dBTP, PSR >= 8 in the loudest section). " +
         "The Tape is a vintage-tape coloration stage (ADAA tanh/asymmetric saturation + HF compression + wow/flutter), " +
         "the single biggest lever for lo-fi / dusty / 'pushed' master character (hip-hop, lo-fi, Memphis, dub). " +
-        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound. " +
-        "For pumpy beats: enable punch, set threshold around -18 to -12 dB, fast attack (0.1-0.5ms), " +
-        "medium release (80-200ms), ratio 4-8, autoMakeup true. " +
-        "For lo-fi/Memphis/dusty glue: tapeEnabled=1, tapeMode=1 (Lo-Fi), masterTapeDrive 0.55-0.7, " +
-        "masterTapeTone -0.4..-0.1 (darker), masterTapeWear 0.5-0.7 (wow/flutter). " +
+        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound; genre recipes live in the beat-making-guide resource. " +
         "Squeeze (masterSqueeze*) is the 3-band up/down density stage between Punch and Tape — for dense modern-electronic masters set masterSqueezeEnabled=1 with masterSqueezeDepth 0.2-0.4; it lifts quiet detail and limits loud bands per band (a character stage, not glue — Punch stays the glue). " +
         "NOTE: the Tape and Squeeze stages require a PAM build that ships them (flat state keys, not manifest params). On older builds these keys are ignored.",
     inputSchema: {
@@ -3988,7 +5315,7 @@ server.registerTool("set_master_effects", {
         masterEqHsGain: z.number().min(-12).max(12).optional().describe("High-shelf gain dB (default 0)."),
         masterWidth: z.number().min(0).max(2).optional().describe("Stereo width (0=mono, 1=unity, 2=double side; default 1). Check corr in get_master_analysis after widening."),
         masterBassMonoFreq: z.number().min(0).max(300).optional().describe("Elliptical bass-mono corner Hz; < 20 = off. Engage (~100-120) when corrLow < +0.7."),
-        masterClipEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the oversampled soft clipper (post-Tape, pre-Limiter). Adds 23 samples of reported latency while on."),
+        masterClipEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the oversampled soft clipper (post-Tape, pre-Limiter). Its 23 samples of latency are reported whether it is on or off, so toggling it never moves the host's compensation."),
         masterClipDrive: z.number().min(0).max(12).optional().describe("Clipper drive dB (default 0). Staging guidance: the clipper shaves the sharpest 2-3 dB so the limiter works 1-2 dB."),
         masterClipMix: z.number().min(0).max(1).optional().describe("Clipper parallel blend (1 = fully clipped)."),
         masterClipMode: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional().describe("Clipper transfer: 0=Smooth (knee-tanh), 1=Silicon diode (hard knee), 2=Germanium diode (earlier, softer knee), 3=LED (higher knee). Diode modes are exact antiparallel-pair solves, ADAA at the 2x rate. Default 0."),
@@ -4169,7 +5496,7 @@ server.registerTool("set_drum_synth_wave", {
         "centre, tension −1..+1 with 0 = linear). PAM bakes them into a DC-removed, peak-normalized single cycle " +
         "that the Wave engine's Draw param (p8) crossfades against the factory bank. Only the Wave engine reads it — " +
         "select 'Wave' via set_drum_synth and raise Draw (p8) to hear it. Runs in the WebView (the curve transform " +
-        "is single-sourced there), so PAM's window must be OPEN. Needs PAM ≥ 1.13.0.",
+        "is single-sourced there), so PAM's window must be OPEN with drum-synth wave editing support.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         points: z
@@ -4200,6 +5527,394 @@ server.registerTool("set_drum_synth_wave", {
     return text(`Set cell ${cellId} Wave-engine custom waveform (${points.length} breakpoints). ` +
         `Select the Wave engine and raise Draw (p8) to hear it. (Runs in the WebView — ensure PAM's window is open.)`);
 });
+// Generative Players (per-cell PLAYER mode). Arming semantics mirror
+// interface/src/interop.ts setCellPlayer; the registry is shared/generativePlayers.json.
+const PLAYER_REF_HELP = `one of ${PLAYER_NAMES.join(", ")} (or its id 1..${GENERATIVE_PLAYERS.length}), ` +
+    "'role' for the cell's role default, or 'off'";
+function playerProductError(manifest) {
+    if (manifest && manifest.generativePatterns?.enabled !== true) {
+        return error(`Generative players are PAM-only. ${manifest.name ?? "This product"}'s manifest exposes none.`);
+    }
+    return null;
+}
+const playerSlotArg = (n) => z
+    .union([z.number().min(0).max(1), z.string()])
+    .optional()
+    .describe(`P${n} slot: 0..1 (snapped to the slot's detents) or a position label such as 'Techno' or 'Triad'. ` +
+    "Its meaning is per player — list_players names it.");
+server.registerTool("list_players", {
+    title: "List Generative Players",
+    description: "Catalogue of PAM's generative Players — per-cell generators that replace a cell's drawn pattern with a " +
+        "seeded, transport-synced cycle (EUCLID, KIT, TURING, WALK, MARKOV, RATCHET, PHASE, RIFF, MASK). Returns each " +
+        "player's blurb, defaults, P-slot vocabulary (detented positions or 0..1 knobs) and curated preset names, plus " +
+        "the role spread (which player each cell arms by default). Offline — no bridge needed. Arm one with set_player.",
+    inputSchema: {
+        player: z.string().optional().describe("Return one player's full detail (name or id). Omit for the whole roster."),
+        presets: z
+            .boolean()
+            .optional()
+            .describe("Include each curated preset's values, not only its name. Default false."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ player, presets }) => {
+    const manifest = await loadManifestForProductGuard();
+    const available = manifest ? manifest.generativePatterns?.enabled === true : true;
+    const spec = player ? resolvePlayerSpec(player) : undefined;
+    if (player && !spec)
+        return error(`Unknown player '${player}' — ${PLAYER_REF_HELP}.`);
+    const specs = spec ? [spec] : GENERATIVE_PLAYERS;
+    return json({
+        available,
+        ...(available ? {} : { note: `${manifest?.name ?? "This product"} exposes no players; the catalogue is informational.` }),
+        players: specs.map((entry) => ({
+            ...describePlayerSpec(entry, true),
+            ...(presets ? { presetValues: playerPresetsFor(entry.id) } : {}),
+        })),
+        roleSpread: roleSpreadSummary(),
+        notes: [
+            "A player replaces what the cell PLAYS, never the drawn pattern: set_player 'off' restores the grid exactly.",
+            "Sequencer output needs the transport running (start_transport).",
+            "Melodic players arm the cell poly with the root on its trigger note; 'off' restores both.",
+            "KIT follows its Genre slot — pass genre to set_player so it matches the track.",
+            "patternMode 'keep' layers the player over the drawn pattern instead of masking it.",
+        ],
+    });
+});
+server.registerTool("set_player", {
+    title: "Set Generative Player",
+    description: "Arm, edit or switch off a cell's generative Player (PAM-only). Passing `player` arms that generator with the " +
+        "roster's own voicing (or a curated `preset`), the track genre on genre-aware players, and a reversible poly " +
+        "arm on melodic ones; omit `player` to edit the running player's values in place. Values land in both the cell " +
+        "config and the cell{N}_player* automation params, like the plugin UI. 'off' restores the drawn pattern and the " +
+        "cell's pre-arm polyphony. The player sounds only while the transport runs. The UI shows a running player " +
+        "unprompted; to arm from the UI as well, update_settings { experimentalMode: true, experimentalGenerativePatterns: true }.",
+    inputSchema: {
+        cellIds: z
+            .array(z.number().int().min(1).max(8))
+            .min(1)
+            .describe("Cells to write (1-8). Several cells take the same write, each snapped to its own player."),
+        player: z
+            .union([z.string(), z.number().int().min(0)])
+            .optional()
+            .describe(`Player to arm: ${PLAYER_REF_HELP}. Omit to edit the running player.`),
+        preset: z.string().optional().describe("Curated preset name for the armed or running player — list_players lists them."),
+        genre: z
+            .enum(PLAYER_GENRES)
+            .optional()
+            .describe("Genre for genre-aware players (KIT's Genre slot). Defaults to the roster default when arming."),
+        density: z.number().min(0).max(1).optional().describe("How much plays, 0..1. Audible from the next step."),
+        mutate: z.number().min(0).max(1).optional().describe("Cycle-to-cycle evolution, 0..1 (below 0.02 locks the loop)."),
+        p1: playerSlotArg(1),
+        p2: playerSlotArg(2),
+        p3: playerSlotArg(3),
+        p4: playerSlotArg(4),
+        p5: playerSlotArg(5),
+        seed: z
+            .union([z.number().int().min(0), z.literal("random")])
+            .optional()
+            .describe("Player seed (uint31) or 'random' to reroll — the DICE gesture."),
+        patternMode: z
+            .enum(PATTERN_MODES)
+            .optional()
+            .describe("'mask' (default): the player replaces the drawn pattern. 'keep': the drawn pattern keeps sounding and the player layers over it."),
+        listenMode: z
+            .enum(LISTEN_MODES)
+            .optional()
+            .describe("Ensemble listening: react to another cell's last completed cycle — complement its gaps, answer it, or shade velocity harmonically."),
+        listenSource: z.number().int().min(0).max(8).optional().describe("Listening source: 0 = all other cells, 1-8 = one cell (never itself)."),
+        listenAmount: z.number().min(0).max(1).optional().describe("Listening strength 0..1."),
+        poly: z
+            .boolean()
+            .optional()
+            .describe("Override the automatic poly arm: true forces poly, false keeps the cell mono even for a melodic player."),
+    },
+}, async ({ cellIds, player, preset, genre, density, mutate, p1, p2, p3, p4, p5, seed, patternMode, listenMode, listenSource, listenAmount, poly }) => {
+    const check = await requireBridgeForCells(cellIds);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    const gate = playerProductError(manifest);
+    if (gate)
+        return gate;
+    const playerRef = typeof player === "string" ? player.trim().toLowerCase() : player;
+    const wantsOff = playerRef === "off" || playerRef === 0;
+    const wantsRole = playerRef === "role";
+    const explicitSpec = player !== undefined && !wantsOff && !wantsRole ? resolvePlayerSpec(player) : undefined;
+    if (player !== undefined && !wantsOff && !wantsRole && !explicitSpec) {
+        return error(`Unknown player '${player}' — ${PLAYER_REF_HELP}.`);
+    }
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const cellsObj = isRecord(state.cells) ? state.cells : {};
+    const slotInputs = [p1, p2, p3, p4, p5];
+    const flatDelta = {};
+    const cellsDelta = {};
+    const lines = [];
+    for (const cellId of new Set(cellIds)) {
+        const rawCell = cellsObj[String(cellId)];
+        const cell = isRecord(rawCell) ? rawCell : {};
+        const currentType = cellPlayerType(cell);
+        const recorded = (key) => {
+            const value = Number(cell[key]);
+            return Number.isFinite(value) && value !== NO_POLY_ARM ? Math.round(value) : undefined;
+        };
+        if (wantsOff) {
+            if (currentType <= 0) {
+                lines.push(`Cell ${cellId}: no player running.`);
+                continue;
+            }
+            const config = { playerType: 0, playerLastType: currentType };
+            const prePoly = recorded("playerPrePoly");
+            const preRoot = recorded("playerPreRoot");
+            if (prePoly !== undefined)
+                config.isPoly = prePoly;
+            if (preRoot !== undefined)
+                config.polyRootNote = preRoot;
+            config.playerPrePoly = NO_POLY_ARM;
+            config.playerPreRoot = NO_POLY_ARM;
+            cellsDelta[String(cellId)] = config;
+            lines.push(`Cell ${cellId}: ${getPlayerSpec(currentType)?.name ?? "player"} off — drawn pattern restored` +
+                `${prePoly !== undefined || preRoot !== undefined ? ", pre-arm polyphony restored" : ""}.`);
+            continue;
+        }
+        const roleConfig = wantsRole ? rolePlayerConfigFor(cellId) : undefined;
+        const spec = explicitSpec ?? (roleConfig ? getPlayerSpec(roleConfig.playerType) : getPlayerSpec(currentType));
+        if (!spec)
+            return error(`Cell ${cellId} runs no player. Pass player to arm one — ${PLAYER_REF_HELP}.`);
+        const arming = explicitSpec !== undefined || roleConfig !== undefined;
+        const config = {};
+        if (arming) {
+            Object.assign(config, playerDefaultsFor(spec.id), playerGenreConfig(spec, genre));
+            if (roleConfig?.playerP1 !== undefined)
+                config.playerP1 = roleConfig.playerP1;
+            if (roleConfig?.playerP5 !== undefined)
+                config.playerP5 = roleConfig.playerP5;
+            config.playerLastType = spec.id;
+        }
+        else if (genre) {
+            Object.assign(config, playerGenreConfig(spec, genre));
+        }
+        if (preset) {
+            const found = resolvePlayerPreset(spec, preset);
+            if (!found) {
+                const names = playerPresetsFor(spec.id).map((entry) => entry.name);
+                return error(`${spec.name} has no preset '${preset}' — one of: ${names.join(", ")}.`);
+            }
+            Object.assign(config, presetConfig(found));
+        }
+        if (density !== undefined)
+            config.playerDensity = density;
+        if (mutate !== undefined)
+            config.playerMutate = mutate;
+        for (let i = 0; i < slotInputs.length; i++) {
+            const input = slotInputs[i];
+            if (input === undefined)
+                continue;
+            const slot = spec.slots[i];
+            if (!slot)
+                return error(`${spec.name} has no P${i + 1} slot (it has ${spec.slots.length}).`);
+            const resolved = resolveSlotValue(slot, input);
+            if (typeof resolved === "string")
+                return error(`Cell ${cellId} ${spec.name} P${i + 1}: ${resolved}`);
+            config[PLAYER_SLOT_FIELDS[i]] = resolved;
+        }
+        PLAYER_SLOT_FIELDS.forEach((field, i) => {
+            if (config[field] !== undefined)
+                config[field] = snapPlayerValue(spec.slots[i]?.steps, config[field]);
+        });
+        if (seed !== undefined)
+            config.playerSeed = seed === "random" ? randomPlayerSeed() : Math.round(seed);
+        if (patternMode)
+            config.playerPatternMode = PATTERN_MODES.indexOf(patternMode);
+        if (listenMode)
+            config.playerListenMode = LISTEN_MODES.indexOf(listenMode);
+        if (listenSource !== undefined)
+            config.playerListenSource = listenSource;
+        if (listenAmount !== undefined)
+            config.playerListenAmount = listenAmount;
+        // Reversible poly arm: record the pre-arm values once, never the armed state.
+        const autoPoly = arming && poly !== false && (isMelodicPlayer(spec) || roleConfig?.isPoly === 1);
+        let polyNote = "";
+        if (autoPoly) {
+            if (recorded("playerPrePoly") === undefined && recorded("playerPreRoot") === undefined) {
+                config.playerPrePoly = Math.round(Number(cell.isPoly ?? 0)) || 0;
+                config.playerPreRoot = Math.round(Number(cell.polyRootNote ?? 48)) || 48;
+            }
+            config.isPoly = 1;
+            config.polyRootNote = Math.round(Number(cell.midiNote ?? 47 + cellId)) || 47 + cellId;
+            polyNote = `; poly armed (root ${config.polyRootNote})`;
+        }
+        else if (poly !== undefined) {
+            config.isPoly = poly ? 1 : 0;
+            polyNote = `; poly ${poly ? "on" : "off"}`;
+        }
+        if (arming)
+            config.playerType = spec.id;
+        if (Object.keys(config).length === 0)
+            return error("Nothing to write — pass player, preset, or at least one value.");
+        cellsDelta[String(cellId)] = config;
+        for (const field of MODULATABLE_PLAYER_FIELDS) {
+            if (typeof config[field] === "number")
+                flatDelta[`cell${cellId}_${field}`] = config[field];
+        }
+        const parts = [];
+        if (config.playerDensity !== undefined)
+            parts.push(`density ${playerDensityDisplay(config.playerDensity)}`);
+        if (config.playerMutate !== undefined)
+            parts.push(`mutate ${playerMutateDisplay(config.playerMutate)}`);
+        spec.slots.forEach((slot, i) => {
+            const value = config[PLAYER_SLOT_FIELDS[i]];
+            if (value !== undefined)
+                parts.push(`${slot.label}=${playerSlotDisplay(slot, value)}`);
+        });
+        if (config.playerSeed !== undefined)
+            parts.push(`seed ${config.playerSeed}`);
+        if (patternMode)
+            parts.push(`pattern ${patternMode}`);
+        if (listenMode)
+            parts.push(`listen ${listenMode}`);
+        lines.push(`Cell ${cellId}: ${spec.name} ${arming ? "armed" : "updated"} — ${parts.join(", ")}${polyNote}.`);
+    }
+    if (Object.keys(cellsDelta).length === 0)
+        return text(lines.join("\n"));
+    await applyKv({ ...flatDelta, cells: cellsDelta }, KV_OPTS_CELL_CONFIG);
+    return text(`${lines.join("\n")}\n` +
+        "Players sound only while the transport runs; get_design_overview reports each cell's player.");
+});
+/** A cell's sample as a readable file: absolute as given, else relative to a library root. */
+async function resolveCellSampleFile(filePath) {
+    const expanded = expandHome(filePath);
+    if (isAbsolute(expanded))
+        return existsSync(expanded) ? expanded : undefined;
+    const locations = await bridge.send("getDefaultLocations").catch(() => undefined);
+    const roots = Array.isArray(locations)
+        ? locations.filter((entry) => isRecord(entry) && typeof entry.path === "string")
+        : [];
+    const normalized = filePath.replaceAll("\\", "/");
+    const candidates = [];
+    for (const root of roots) {
+        const stripped = normalized.replace(/^Samples\/(User|Factory)\//, "");
+        if (/user/i.test(root.name) && /^Samples\/User\//.test(normalized))
+            candidates.push(join(root.path, stripped));
+        if (/factory/i.test(root.name) && /^Samples\/Factory\//.test(normalized))
+            candidates.push(join(root.path, stripped));
+        candidates.push(join(root.path, normalized), join(root.path, stripped));
+    }
+    return candidates.find((candidate) => existsSync(candidate));
+}
+server.registerTool("set_slices", {
+    title: "Set Sample Slices",
+    description: "Slice the sample loaded in a cell: explicit `boundaries` (0..1 of the file), `count` equal slices, or " +
+        "`transients` detected from the audio (WAV files, offline). Writes cell{N}_sliceBoundaries / _sliceCount — " +
+        "what the slice lane, Slice Keymap, preview_slice and export_slice all read — and switches the Slice knob on. " +
+        "`sequence:true` also chops the loop into the slice + note lanes so it plays back in order at native rate " +
+        "(the Slice → Sequence gesture: modLatch on, both lanes at 1× over the loop's length in beats).",
+    inputSchema: {
+        cellId: z.number().int().min(1).max(8).describe("Cell number (1-8); it must have a sample loaded."),
+        boundaries: z
+            .array(z.number().min(0).max(1))
+            .min(2)
+            .max(MAX_SLICES + 1)
+            .optional()
+            .describe("Slice boundaries as 0..1 positions in the file, ascending; 0 and 1 are added when missing."),
+        count: z.number().int().min(1).max(MAX_SLICES).optional().describe(`Equal slices, 1..${MAX_SLICES}.`),
+        transients: z.boolean().optional().describe("Detect onsets in the sample and slice there (WAV only)."),
+        sensitivity: z.number().min(0).max(1).optional().describe("Transient sensitivity 0..1 (default 0.5; higher finds more onsets)."),
+        maxSlices: z.number().int().min(2).max(MAX_SLICES).optional().describe("Cap on transient slices (default 32)."),
+        sequence: z.boolean().optional().describe("Also write the slice + note lanes so the slices play in order (loops)."),
+    },
+}, async ({ cellId, boundaries, count, transients, sensitivity, maxSlices, sequence }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && isMfxManifest(manifest))
+        return error("set_slices needs a sampler cell; MFX cells carry no sample.");
+    const modes = [boundaries !== undefined, count !== undefined, transients === true].filter(Boolean).length;
+    if (modes !== 1)
+        return error("Pass exactly one of boundaries, count, or transients:true.");
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const cellsObj = isRecord(state.cells) ? state.cells : {};
+    const cell = isRecord(cellsObj[String(cellId)]) ? cellsObj[String(cellId)] : {};
+    const filePath = [cell.filePath, cell.samplePath, state[`cell${cellId}_filePath`]].find((v) => typeof v === "string" && v.length > 0);
+    if (!filePath)
+        return error(`Cell ${cellId} has no sample loaded — load_sample first.`);
+    let resolved;
+    let wavDuration;
+    if (boundaries)
+        resolved = normalizeBoundaries(boundaries);
+    else if (count !== undefined)
+        resolved = equalBoundaries(count);
+    else {
+        const file = await resolveCellSampleFile(filePath);
+        if (!file)
+            return error(`Could not find '${filePath}' on disk to analyse — pass count or boundaries instead.`);
+        let wav;
+        try {
+            wav = decodeWav(await readFile(file));
+        }
+        catch (e) {
+            return error(`Transient slicing reads WAV files only (${e.message}) — pass count or boundaries for ${basename(file)}.`);
+        }
+        wavDuration = wav.durationSeconds;
+        resolved = detectOnsetBoundaries(wav, sensitivity ?? 0.5, maxSlices ?? 32);
+        if (resolved.length < 3)
+            return error("No transients found above the threshold — raise sensitivity or pass count.");
+    }
+    const sliceCount = resolved.length - 1;
+    const currentKnob = Number(state[`cell${cellId}_slice`]) || 0;
+    const delta = {
+        [`cell${cellId}_sliceBoundaries`]: resolved,
+        [`cell${cellId}_sliceCount`]: sliceCount,
+    };
+    if (currentKnob < 1 || currentKnob > sliceCount)
+        delta[`cell${cellId}_slice`] = 1;
+    await applyKv(delta, KV_OPTS_CELL_CONFIG);
+    let sequenceNote = "";
+    if (sequence) {
+        const transportRaw = await bridge.send("getTransport").catch(() => undefined);
+        const bpm = Number(isRecord(transportRaw) ? transportRaw.bpm : undefined) || Number(state.bpm) || 120;
+        let duration = wavDuration;
+        if (duration === undefined) {
+            const info = await bridge.send("getAudioFileInfo", filePath).catch(() => undefined);
+            const parsed = typeof info === "string" ? JSON.parse(info) : info;
+            duration = [parsed?.duration, parsed?.durationSeconds, parsed?.lengthSeconds, parsed?.length]
+                .map(Number)
+                .find((v) => Number.isFinite(v) && v > 0);
+        }
+        const loopBeats = duration ? (duration * bpm) / 60 : Number(state[`cell${cellId}_patternLengthSlice`]) || 16;
+        const patternLength = Math.max(1, Math.min(32, duration ? Math.ceil(loopBeats) : loopBeats));
+        const note = typeof cell.midiNote === "number" ? cell.midiNote : 48 + cellId - 1;
+        const channel = typeof cell.midiChannel === "number" ? cell.midiChannel : 1;
+        const sliceEvents = [];
+        const noteEvents = [];
+        for (let i = 0; i < sliceCount; i++) {
+            const time = resolved[i] * loopBeats;
+            const dur = (resolved[i + 1] - resolved[i]) * loopBeats;
+            if (dur <= 0)
+                continue;
+            sliceEvents.push({ note, channel, time, duration: dur, velocity: 100, value: i + 1 });
+            noteEvents.push({ note, channel, time, duration: dur, velocity: 100 });
+        }
+        await applyKv({
+            [`cell${cellId}_sliceSequence`]: sliceEvents,
+            [`cell${cellId}_midiSequence`]: noteEvents,
+            [`cell${cellId}_patternLengthSlice`]: patternLength,
+            [`cell${cellId}_patternLength`]: patternLength,
+            [`cell${cellId}_patternSpeedSlice`]: 9,
+            [`cell${cellId}_patternSpeed`]: 9,
+            [`cell${cellId}_patternDirection`]: 0,
+            [`cell${cellId}_slice`]: 1,
+            cells: { [cellId]: { modLatch: 1 } },
+            __forceRender__: true,
+        }, KV_OPTS_PATTERN);
+        sequenceNote = ` Chopped into the slice + note lanes over ${patternLength} beats at ${bpm} BPM; start_transport to hear it.`;
+    }
+    const positions = resolved.slice(1, -1).map((b) => `${Math.round(b * 1000) / 10}%`);
+    return text(`Cell ${cellId}: ${sliceCount} slice${sliceCount === 1 ? "" : "s"}` +
+        `${positions.length ? ` (cuts at ${positions.join(", ")})` : ""}.${sequenceNote}`);
+});
 server.registerTool("add_param_seq", {
     title: "Add Parameter Sequencer",
     description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
@@ -4216,9 +5931,17 @@ server.registerTool("add_param_seq", {
         bipolar: z.union([z.literal(0), z.literal(1)]).default(0).describe("0 = unipolar, 1 = bipolar."),
         length: z.number().min(0.0625).max(16).default(1).describe("Pattern length in bars."),
         speed: z.number().min(0.0625).max(16).default(1).describe("Pattern speed multiplier."),
+        freeMode: z
+            .union([z.literal(0), z.literal(1)])
+            .default(0)
+            .describe("0 = locked to the source cell's clock and its own steps; 1 = mapped to the Free Sequencer (its clock AND its master steps, set_free_sequencer)."),
+        stepMode: z
+            .union([z.literal(0), z.literal(1)])
+            .default(0)
+            .describe("0 = Clock; 1 = Gate: advance one step per trigger of the source cell (cell-locked only; MFX has no Gate)."),
     },
-}, async ({ paramId, cellId, sequence, strength, bipolar, length, speed }) => {
-    const check = await requireBridge();
+}, async ({ paramId, cellId, sequence, strength, bipolar, length, speed, freeMode, stepMode }) => {
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     const index = await getParameterIndex();
@@ -4240,7 +5963,8 @@ server.registerTool("add_param_seq", {
         bipolar,
         boost: 0,
         interpolate: 0,
-        freeMode: 0,
+        freeMode,
+        stepMode,
     };
     paramSeqs.push(newSeq);
     await applyKv({ paramSeqs }, KV_OPTS_MOD);
@@ -4253,11 +5977,19 @@ server.registerTool("update_param_seq", {
     inputSchema: {
         paramId: z.string().describe("Target parameter ID."),
         sequence: z.array(z.number().min(0).max(1)).optional().describe("New step values (0-1)."),
-        strength: z.number().min(0).max(1).optional(),
-        length: z.number().min(0.0625).max(16).optional(),
-        speed: z.number().min(0.0625).max(16).optional(),
-        bipolar: z.union([z.literal(0), z.literal(1)]).optional(),
-        enabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        strength: z.number().min(0).max(1).optional().describe("Modulation depth (0-1)."),
+        length: z.number().min(0.0625).max(16).optional().describe("Pattern length in bars."),
+        speed: z.number().min(0.0625).max(16).optional().describe("Pattern speed multiplier."),
+        bipolar: z.union([z.literal(0), z.literal(1)]).optional().describe("0 = unipolar, 1 = bipolar."),
+        enabled: z.union([z.literal(0), z.literal(1)]).optional().describe("0 = bypass the sequencer, 1 = run it."),
+        freeMode: z
+            .union([z.literal(0), z.literal(1)])
+            .optional()
+            .describe("0 = cell-locked with its own steps; 1 = mapped to the Free Sequencer master contour (set_free_sequencer)."),
+        stepMode: z
+            .union([z.literal(0), z.literal(1)])
+            .optional()
+            .describe("0 = Clock; 1 = Gate (one step per source-cell trigger; falls back to Clock when free or on MFX)."),
     },
 }, async ({ paramId, ...updates }) => {
     const check = await requireBridge();
@@ -4281,6 +6013,105 @@ server.registerTool("update_param_seq", {
     await applyKv({ paramSeqs }, KV_OPTS_MOD);
     return text(`Updated paramSeq ${paramId}: ${Object.keys(cleanUpdates).join(", ")}`);
 });
+server.registerTool("set_free_sequencer", {
+    title: "Set Free Sequencer",
+    description: "Write the Free Sequencer's master step contour (top-level `freeSeqSequence`, 2..64 steps of 0..1). Every " +
+        "parameter sequencer mapped to it (freeMode:1 via add_param_seq / update_param_seq) follows these steps AND its " +
+        "clock live, each with its own strength, polarity and smoothing; cell-locked and Gate-mode sequencers keep " +
+        "their own steps. An empty contour restores the legacy per-sequencer behaviour.",
+    inputSchema: {
+        sequence: z.array(z.number().min(0).max(1)).min(2).max(64).describe("Master step values, 0..1 each."),
+    },
+}, async ({ sequence }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("applyFreeSeqSequenceUpdate", { sequence });
+    return text(`Free Sequencer: ${sequence.length} steps written. Map a paramSeq with freeMode:1 to follow it.`);
+});
+server.registerTool("export_midi", {
+    title: "Export MIDI",
+    description: "Write the cells' drawn note patterns to a Standard MIDI File (type 1, 480 PPQ, tempo from the transport): " +
+        "one track per cell on MIDI channel = cell number, each pattern tiled across `bars`. Pure file write — no " +
+        "render, nothing changes in PAM. Generated Player cycles are not drawn patterns; FREEZE them first (in the UI) " +
+        "to export what a player is playing. Default location is PAM's Exports folder.",
+    inputSchema: {
+        filename: z.string().optional().describe("Base name without extension (default pam_midi_<epoch>)."),
+        cellIds: z.array(z.number().int().min(1).max(8)).optional().describe("Cells to include (default: every cell with notes)."),
+        bars: z.number().min(1).max(64).optional().describe("Length in 4/4 bars (default: the longest included pattern cycle, at least 1)."),
+        mode: z.enum(["combined", "stems"]).optional().describe("'combined' (default): one multi-track file. 'stems': one file per cell."),
+        outputDir: z.string().optional().describe("Directory to write into (default: the Exports location from get_default_locations)."),
+    },
+}, async ({ filename, cellIds, bars, mode, outputDir }) => {
+    const check = await requireBridgeForCells(cellIds);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && isMfxManifest(manifest))
+        return error("export_midi needs sampler cells with note patterns; MFX has none.");
+    const [stateRaw, transportRaw, locations] = await Promise.all([
+        bridge.send("getState"),
+        bridge.send("getTransport").catch(() => undefined),
+        bridge.send("getDefaultLocations").catch(() => undefined),
+    ]);
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const bpm = Number(isRecord(transportRaw) ? transportRaw.bpm : undefined) || Number(state.bpm) || 120;
+    let dir = outputDir ? expandHome(outputDir) : undefined;
+    if (!dir) {
+        if (Array.isArray(locations)) {
+            const exportsEntry = locations.find((entry) => isRecord(entry) && /export/i.test(String(entry.name)));
+            if (isRecord(exportsEntry) && typeof exportsEntry.path === "string")
+                dir = exportsEntry.path;
+        }
+        else if (isRecord(locations)) {
+            dir = [locations.exports, locations.exportsLocation, locations.Exports].find((v) => typeof v === "string" && v.length > 0);
+        }
+    }
+    if (!dir)
+        return error("Could not resolve PAM's Exports folder from get_default_locations — pass outputDir.");
+    const maxCell = manifestMaxCellId(manifest) ?? 8;
+    const ids = (cellIds?.length ? cellIds : Array.from({ length: maxCell }, (_, i) => i + 1)).filter((id) => id <= maxCell);
+    const cells = ids
+        .map((id) => ({
+        id,
+        sequence: state[`cell${id}_midiSequence`],
+        patternLength: state[`cell${id}_patternLength`],
+        speed: state[`cell${id}_patternSpeed`],
+    }))
+        .filter((cell) => Array.isArray(cell.sequence) && cell.sequence.length > 0);
+    if (cells.length === 0)
+        return error("No note patterns to export — the selected cells carry no notes.");
+    const cycleBars = cells.map((cell) => {
+        const length = Number(cell.patternLength);
+        const speedIndex = Math.round(Number(cell.speed));
+        const mul = Number.isFinite(speedIndex) ? patternSpeedMultiplier(speedIndex) : 1;
+        return (Number.isFinite(length) && length > 0 ? length : 4) / mul / 4;
+    });
+    const totalBars = bars ?? Math.max(1, Math.ceil(Math.max(...cycleBars)));
+    const totalBeats = totalBars * 4;
+    const tracks = cells.map((cell) => ({
+        name: `Cell ${cell.id}`,
+        events: tilePatternEvents(cell.sequence, cell.patternLength, cell.speed, totalBeats, Math.min(16, cell.id)),
+    }));
+    const base = (filename?.trim() || `pam_midi_${Date.now()}`).replace(/\.mid$/i, "").replace(/[\\/:]/g, "_");
+    await mkdir(dir, { recursive: true });
+    const written = [];
+    if (mode === "stems") {
+        for (const track of tracks) {
+            const path = join(dir, `${base}_cell${track.name.slice(5)}.mid`);
+            await writeFile(path, buildMidiFile(bpm, [track], track.name));
+            written.push(path);
+        }
+    }
+    else {
+        const path = join(dir, `${base}.mid`);
+        await writeFile(path, buildMidiFile(bpm, tracks, base));
+        written.push(path);
+    }
+    const noteCount = tracks.reduce((sum, track) => sum + track.events.length, 0);
+    return text(`Exported ${noteCount} notes from ${tracks.length} cell${tracks.length === 1 ? "" : "s"} over ${totalBars} bar${totalBars === 1 ? "" : "s"} at ${bpm} BPM.\n` +
+        written.map((path) => `File: ${path}`).join("\n"));
+});
 server.registerTool("remove_param_seq", {
     title: "Remove Parameter Sequencer",
     description: "Remove a parameter sequencer for the given paramId.",
@@ -4304,7 +6135,7 @@ server.registerTool("normalize_sample", {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("normalizeSampleForCell", cellId);
@@ -4323,7 +6154,7 @@ server.registerTool("gain_sample", {
             .describe("Gain in decibels (e.g. 3 = +3 dB louder, -6 = 6 dB quieter)."),
     },
 }, async ({ cellId, gainDb }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("gainSampleForCell", { cellId, gainDb });
@@ -4369,7 +6200,9 @@ server.registerTool("export_audio", {
         "'per-bus' (per output bus) · 'song-mode' (the Song Mode timeline).\n\n" +
         "NOTE on 'song-mode': the offline bounce applies EVERY section on its anchor (PAM ≥ 1.5.7 with " +
         "offline song export; older builds render only the first section). Wall-clock sources " +
-        "(Magenta/Notochord) render silent offline — use the `export_song` tool's live strategy for those.",
+        "(Magenta/Notochord) render silent offline — use the `export_song` tool's live strategy for those. " +
+        "It issues the same render as `export_song` with strategy 'offline'; prefer `export_song` for arrangements, " +
+        "which is the only route to the live and audio+video strategies.",
     inputSchema: {
         bars: z.number().min(1).max(128).default(4).describe("Bars to render (ignored for 'song-mode', which derives length from the timeline)."),
         cellId: z
@@ -4387,12 +6220,12 @@ server.registerTool("export_audio", {
             .optional()
             .describe("For mode 'selected-cells': cells to bounce as stems."),
         bitDepth: z
-            .number()
+            .union([z.literal(16), z.literal(24)])
             .default(24)
-            .describe("Bit depth (16 or 24)."),
+            .describe("Bit depth: 16 or 24."),
     },
 }, async ({ bars, cellId, mode, selectedCellIds, bitDepth }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId, selectedCellIds);
     if (check !== true)
         return check;
     // Resolve the effective mode. A bare cellId means "individual".
@@ -4430,7 +6263,7 @@ server.registerTool("export_audio", {
     const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
     // 4/4 assumption for the placeholder duration; 'song-mode' recomputes its own length from the timeline.
     const durationInSeconds = (bars * 4 * 60) / bpm;
-    const filename = `pam_export_${effectiveMode.replace(/[^a-z0-9]/gi, "_")}_${Date.now()}`;
+    const filename = `${SERVER_PRODUCT.id}_export_${effectiveMode.replace(/[^a-z0-9]/gi, "_")}_${Date.now()}`;
     const options = {
         filename,
         mode: effectiveMode,
@@ -4445,12 +6278,8 @@ server.registerTool("export_audio", {
     const outcome = await pollExportStatus();
     if (outcome === "success")
         return text(`Export complete (mode '${effectiveMode}').\n` +
-            `File(s) written to PAM's Exports folder, base name: ${filename}.wav` +
-            loudnessReportLine() +
-            (effectiveMode === "song-mode"
-                ? "\n\nReminder: the offline song-mode bounce captures only the first section's state. " +
-                    "Use export_song for a full track with section changes."
-                : ""));
+            `File(s) written to ${SERVER_PRODUCT.name}'s Exports folder, base name: ${filename}.wav` +
+            loudnessReportLine());
     if (outcome === "failed")
         return error(`Export failed (mode '${effectiveMode}').`);
     return text(`Export timed out (mode '${effectiveMode}'). The render may still be running.`);
@@ -4458,8 +6287,8 @@ server.registerTool("export_audio", {
 // ============================================================
 // RESOURCES
 // ============================================================
-server.registerResource("parameter-manifest", "pam://parameters", {
-    title: "PAM Parameter Manifest",
+server.registerResource("parameter-manifest", `${SERVER_PRODUCT.resourceScheme}://parameters`, {
+    title: `${SERVER_PRODUCT.name} Parameter Manifest`,
     description: "Complete parameter definitions with ranges, defaults, and metadata.",
     mimeType: "application/json",
 }, async (uri) => {
@@ -4473,8 +6302,8 @@ server.registerResource("parameter-manifest", "pam://parameters", {
         ],
     };
 });
-server.registerResource("parameter-summary", "pam://parameters/summary", {
-    title: "PAM Parameter Summary",
+server.registerResource("parameter-summary", `${SERVER_PRODUCT.resourceScheme}://parameters/summary`, {
+    title: `${SERVER_PRODUCT.name} Parameter Summary`,
     description: "Human-readable parameter list with ranges and descriptions.",
     mimeType: "text/plain",
 }, async (uri) => {
@@ -4484,10 +6313,10 @@ server.registerResource("parameter-summary", "pam://parameters/summary", {
         contents: [{ uri: uri.href, text: lines.join("\n") }],
     };
 });
-server.registerResource("cell-parameters", new ResourceTemplate("pam://cell/{cellId}/parameters", {
+server.registerResource("cell-parameters", new ResourceTemplate(`${SERVER_PRODUCT.resourceScheme}://cell/{cellId}/parameters`, {
     list: async () => ({
-        resources: Array.from({ length: 8 }, (_, i) => ({
-            uri: `pam://cell/cell${i + 1}/parameters`,
+        resources: Array.from({ length: SERVER_PRODUCT.cellCount }, (_, i) => ({
+            uri: `${SERVER_PRODUCT.resourceScheme}://cell/cell${i + 1}/parameters`,
             name: `Cell ${i + 1} Parameters`,
         })),
     }),
@@ -4502,7 +6331,7 @@ server.registerResource("cell-parameters", new ResourceTemplate("pam://cell/{cel
         contents: [{ uri: uri.href, text: JSON.stringify(params, null, 2) }],
     };
 });
-server.registerResource("global-parameters", "pam://parameters/global", {
+server.registerResource("global-parameters", `${SERVER_PRODUCT.resourceScheme}://parameters/global`, {
     title: "Global Parameters",
     description: "Non-cell-specific parameters (volume, crossfade, looper, etc.).",
     mimeType: "application/json",
@@ -4512,16 +6341,38 @@ server.registerResource("global-parameters", "pam://parameters/global", {
         contents: [{ uri: uri.href, text: JSON.stringify(params, null, 2) }],
     };
 });
-server.registerResource("beat-making-guide", "pam://guide/beat-making", {
-    title: "PAM Beat-Making Guide",
-    description: "Comprehensive guide for creating beats with PAM. Covers cell roles, slicer for loops, " +
-        "sidechain pumping, poly/arp patterns, macros, variations, gain staging, and master effects.",
-    mimeType: "text/markdown",
-}, async () => ({
-    contents: [
-        {
-            uri: "pam://guide/beat-making",
-            text: `# PAM Beat-Making Guide
+if (IS_MFX_SERVER) {
+    server.registerResource("mfx-routing-guide", "mfx://guide/routing", {
+        title: "MFX Routing Guide",
+        description: "A concise workflow for cabling, ordering, shaping, and modulating an MFX patch.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [{
+                uri: "mfx://guide/routing",
+                text: `# MFX Routing Guide
+
+MFX has four effects cells. Audio reaches a cell only when the cable patch routes a source into it.
+
+1. Call \`set_mfx_routing\` with \`op: "get"\` before changing the patch.
+2. Use \`design_context\` to inspect the available effects, parameters, and default effect order.
+3. Replace the complete cable list with \`set_mfx_routing\` and \`op: "set"\`. A serial patch is input → cell1 → cell2 → cell3 → cell4 → output.
+4. Use \`set_effect_order\`, \`update_effect_config\`, and \`set_parameters\` to shape each cell.
+5. Add movement with the modulation tools, audition the result, and save it with \`save_preset\`.
+`,
+            }],
+    }));
+}
+else {
+    server.registerResource("beat-making-guide", "pam://guide/beat-making", {
+        title: "PAM Beat-Making Guide",
+        description: "Comprehensive guide for creating beats with PAM. Covers cell roles, slicer for loops, " +
+            "sidechain pumping, poly/arp patterns, macros, variations, gain staging, and master effects.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "pam://guide/beat-making",
+                text: `# PAM Beat-Making Guide
 
 ## Cell Architecture — 8 Cells, Each a Full Instrument
 
@@ -4861,9 +6712,10 @@ Index → multiplier: 0=1/32, 1=1/16, 2=1/12, 3=1/8, 4=1/6, 5=1/5, 6=1/4, 7=1/3,
 ### Pattern Direction
 \`cell{N}_patternDirection\`: 0=Forward, 1=Backward, 2=Ping-Pong, 3=Random Cycle (shuffle each loop), 4=Random Step (each step independent)
 `,
-        },
-    ],
-}));
+            },
+        ],
+    }));
+}
 // ============================================================
 // PROMPTS — guided workflows (client-invokable, e.g. slash
 // commands in Claude Code). Each stages the same flows the
@@ -4872,7 +6724,7 @@ Index → multiplier: 0=1/32, 1=1/16, 2=1/12, 3=1/8, 4=1/6, 5=1/5, 6=1/4, 7=1/3,
 // Mirror of RANDOMIZER_GENRES (shared/randomizer/types.ts) — the published
 // package can't import repo-relative shared modules, so the copy is pinned by
 // interface/test/randomizerGenre.test.ts (source-text parity check).
-const GENRE_SUGGESTIONS = ["boom_bap", "trap", "drill", "house", "techno", "dnb"];
+const GENRE_SUGGESTIONS = ["boom_bap", "trap", "drill", "house", "techno", "dnb", "idm"];
 const completeGenre = (value) => GENRE_SUGGESTIONS.filter((g) => g.startsWith((value ?? "").toLowerCase()));
 // completable() tags the schema OBJECT with a symbol, so ordering is delicate:
 // .describe()/.optional() clone schemas and drop the tag, SDK 1.29 unwraps
@@ -4880,7 +6732,7 @@ const completeGenre = (value) => GENRE_SUGGESTIONS.filter((g) => g.startsWith((v
 // completer at request time — the tag must sit on both the inner type and the
 // outer optional. Covered by the completion assertion in check-tool-surface's
 // sibling smoke; revisit when the SDK unifies the two lookups.
-const genreArg = completable(completable(z.string().describe("Genre hint, e.g. techno, house, dnb, trap, boom_bap, drill."), completeGenre).optional(), completeGenre);
+const genreArg = completable(completable(z.string().describe("Genre hint, e.g. techno, house, dnb, trap, boom_bap, drill, idm."), completeGenre).optional(), completeGenre);
 function promptText(text) {
     return {
         messages: [
@@ -4888,65 +6740,93 @@ function promptText(text) {
         ],
     };
 }
-server.registerPrompt("build-a-beat", {
-    title: "Build a Beat",
-    description: "Guided kit-building + pattern workflow: coherent samples, genre patterns, transport, refinement, save.",
-    argsSchema: {
-        genre: genreArg,
-        bpm: z.string().optional().describe("Target tempo in BPM."),
-    },
-}, ({ genre, bpm }) => promptText(`Build a beat in PAM${genre ? ` in the style of ${genre}` : ""}${bpm ? ` at ${bpm} BPM` : ""}. Work in stages, listening between them:\n\n` +
-    `1. connection_status to confirm the bridge, then get_design_overview for the current state.\n` +
-    `2. Load a kit: randomize_samples${genre ? ` with genreHint '${genre}'` : " (pass a genreHint)"} — the native engine picks role-coherent samples; prefer it over manual browsing. For specific sounds: get_default_locations → list_samples → load_sample.\n` +
-    `3. ${bpm ? `set_bpm to ${bpm}` : "set_bpm to the genre's tempo"}, then randomize_patterns to generate genre-appropriate patterns from the loaded sample roles.\n` +
-    `4. start_transport — sequencer output needs the transport rolling.\n` +
-    `5. Refine: update_pattern for individual lanes, set_parameters for levels/filters (ranges via design_context), update_effect_config to switch FX on, add_modulation for movement.\n` +
-    `6. save_preset once it works, and update_preset_metadata with genre tags and BPM.`));
-server.registerPrompt("make-a-song", {
-    title: "Make a Song",
-    description: "Arrange the current preset into sections with variations + Song Mode, then bounce a full track.",
-    argsSchema: {
-        bars: z.string().optional().describe("Approximate song length in bars."),
-    },
-}, ({ bars }) => promptText(`Turn the current PAM preset into an arranged song${bars ? ` of roughly ${bars} bars` : ""}:\n\n` +
-    `1. Design 2-4 contrasting sections (intro / groove / peak / outro): shape the state for each, then save_variation into slots 0-7.\n` +
-    `2. Arrange with song_mode op 'setArrangement' — an ordered sections list ({variationIndex, bars, repeat}, minimum 2 sections). Read it back with op 'get'.\n` +
-    `3. Audition: start_transport with Song Mode driving the timeline; queue_variation switches sections live.\n` +
-    `4. Bounce with export_song — strategy 'live' captures the ground-truth master mix (required for Magenta/Notochord/automation), strategy 'offline' is the deterministic multi-section bounce with no bar cap. includeVideo:true films the VX scene (window must be open).\n` +
-    `5. The rendered file lands in PAM's Exports/Resamples locations — get_default_locations resolves them.`));
-server.registerPrompt("design-a-preset", {
-    title: "Design a Preset",
-    description: "Sound-design workflow from a creative brief to a saved preset.",
-    argsSchema: {
-        brief: z.string().describe("Creative brief, e.g. 'dusty lo-fi kit with a wobbly sub'."),
-    },
-}, ({ brief }) => promptText(`Design a PAM preset from this brief: "${brief}"\n\n` +
-    `1. Read design_context (curated parameter cheat sheet) and get_design_overview first — avoid full get_state dumps.\n` +
-    `2. Source sounds: randomize_samples with a genre hint, or get_default_locations → list_samples → load_sample. generate_sample creates bespoke hits (AI engines need update_settings experimental flags + a downloaded model).\n` +
-    `3. Shape each cell: set_parameters (design_context teaches ranges and units), update_effect_config for FX chains, set_drum_synth for synthesized drum layers.\n` +
-    `4. Add movement: add_modulation (LFO / envelope / vary), add_param_seq for stepped motion.\n` +
-    `5. Write patterns with update_pattern, then start_transport to audition.\n` +
-    `6. save_preset with a fitting name and update_preset_metadata (category, tags, BPM).`));
-server.registerPrompt("mix-and-master", {
-    title: "Mix and Master",
-    description: "Balance the cells and shape the master bus using the analysis + suggestion tools.",
-    argsSchema: {},
-}, () => promptText(`Balance and master the current PAM project:\n\n` +
-    `1. get_mix_analysis with refresh:true (offline per-cell stem measurements — takes a few seconds) and get_master_analysis (live loudness snapshot).\n` +
-    `2. suggest_mix for rule-based balance / pan / EQ / dynamics moves; apply the returned parameter moves with set_parameters and enable keys with update_effect_config.\n` +
-    `3. Shape the master bus with set_master_effects (compressor, tape, limiter — design_context lists the keys).\n` +
-    `4. Re-check get_master_analysis and iterate toward the loudness target.\n` +
-    `5. Render with export_audio (mode 'main'; 'all-cells' for stems).`));
-server.registerPrompt("troubleshoot-bridge", {
-    title: "Troubleshoot the PAM Bridge",
-    description: "Diagnose why live tools can't reach the plugin.",
-    argsSchema: {},
-}, () => promptText(`Diagnose the PAM MCP connection:\n\n` +
-    `1. connection_status. No instances → PAM isn't running or the bridge is off (PAM Settings → Experimental Mode → MCP Bridge, default port 9847). Multiple instances → select_instance picks which product the live tools drive.\n` +
-    `2. Instances found but not connected → the plugin may have shut down, or its message thread is busy (heavy render); retry once.\n` +
-    `3. Timeouts on WebView-routed tools (video tools, capture_ui, set_drum_synth_wave, randomize target 'synth') → the plugin window must be OPEN.\n` +
-    `4. "PAM build does not support 'X'" errors → the plugin is older than this server; the user must update PAM (updating the npm package alone is not enough).\n` +
-    `5. Offline tools always work without a plugin: get_parameter_info, design_context, list_presets, read_preset, get_manifest_summary.`));
+if (IS_MFX_SERVER) {
+    server.registerPrompt("design-a-preset", {
+        title: "Design an MFX Preset",
+        description: "Turn a creative effects brief into a routed, modulated, saved MFX preset.",
+        argsSchema: {
+            brief: z.string().describe("Creative brief, e.g. 'wide rhythmic distortion with a filtered parallel tail'."),
+        },
+    }, ({ brief }) => promptText(`Design an MFX preset from this brief: "${brief}"\n\n` +
+        `1. Call connection_status, design_context, and get_design_overview.\n` +
+        `2. Read the current cable patch with set_mfx_routing op 'get', then replace the full patch only if the routing needs to change.\n` +
+        `3. Shape cells 1-4 with set_effect_order, update_effect_config, and set_parameters.\n` +
+        `4. Add movement with add_modulation or add_param_seq, then audition and refine.\n` +
+        `5. Save the result with save_preset and useful metadata.`));
+    server.registerPrompt("troubleshoot-bridge", {
+        title: "Troubleshoot the MFX Bridge",
+        description: "Diagnose why live tools cannot reach MFX.",
+        argsSchema: {},
+    }, () => promptText(`Diagnose the MFX MCP connection:\n\n` +
+        `1. Run connection_status. If no instance appears, start MFX and enable Settings → Experimental → MCP Bridge.\n` +
+        `2. MFX starts at the configured port and automatically takes the next available port when needed; do not assign a second fixed product port.\n` +
+        `3. If an instance appears but cannot connect, it may have closed or be busy with a render; retry once.\n` +
+        `4. If a live tool is unavailable, update the MFX plugin as well as the mfx-mcp package.`));
+}
+if (!IS_MFX_SERVER)
+    server.registerPrompt("build-a-beat", {
+        title: "Build a Beat",
+        description: "Guided kit-building + pattern workflow: coherent samples, genre patterns, transport, refinement, save.",
+        argsSchema: {
+            genre: genreArg,
+            bpm: z.string().optional().describe("Target tempo in BPM."),
+        },
+    }, ({ genre, bpm }) => promptText(`Build a beat in PAM${genre ? ` in the style of ${genre}` : ""}${bpm ? ` at ${bpm} BPM` : ""}. Work in stages, listening between them:\n\n` +
+        `1. connection_status to confirm the bridge, then get_design_overview for the current state.\n` +
+        `2. ${bpm ? `set_bpm to ${bpm}` : "set_bpm to the genre's tempo"}.\n` +
+        `3. Build the kit and groove with randomize target:'full'${genre ? ` and genreHint '${genre}'` : " (pass a genreHint)"}; native chains samples before patterns. The reply is queued: poll get_state for changed cells and cellN_midiSequence before editing/saving. For specific sounds: get_default_locations → list_samples → load_sample, verify paths, then randomize_patterns and verify sequences.\n` +
+        `4. start_transport — sequencer output needs the transport rolling.\n` +
+        `5. Refine: update_pattern for individual lanes, set_parameters for levels/filters (ranges via design_context), update_effect_config to switch FX on, add_modulation for movement. For a groove that evolves, set_player (player 'role' across the kit, or KIT / EUCLID / RIFF per cell — list_players first${genre ? `, genre '${genre}'` : ""}).\n` +
+        `6. save_preset once it works, and update_preset_metadata with genre tags and BPM.`));
+if (!IS_MFX_SERVER)
+    server.registerPrompt("make-a-song", {
+        title: "Make a Song",
+        description: "Arrange the current preset into sections with variations + Song Mode, then bounce a full track.",
+        argsSchema: {
+            bars: z.string().optional().describe("Approximate song length in bars."),
+        },
+    }, ({ bars }) => promptText(`Turn the current PAM preset into an arranged song${bars ? ` of roughly ${bars} bars` : ""}:\n\n` +
+        `1. Design 2-4 contrasting sections (intro / groove / peak / outro): shape the state for each, then save_variation into slots 0-7.\n` +
+        `2. Arrange with song_mode op 'setArrangement' — an ordered sections list ({variationIndex, bars, repeat}, minimum 2 sections). Read it back with op 'get'.\n` +
+        `3. Audition: start_transport with Song Mode driving the timeline; queue_variation switches sections live.\n` +
+        `4. Bounce with export_song — strategy 'live' captures the ground-truth master mix (required for Magenta/Notochord/automation), strategy 'offline' is the deterministic multi-section bounce with no bar cap. includeVideo:true films the VX scene (window must be open).\n` +
+        `5. The rendered file lands in PAM's Exports/Resamples locations — get_default_locations resolves them.`));
+if (!IS_MFX_SERVER)
+    server.registerPrompt("design-a-preset", {
+        title: "Design a Preset",
+        description: "Sound-design workflow from a creative brief to a saved preset.",
+        argsSchema: {
+            brief: z.string().describe("Creative brief, e.g. 'dusty lo-fi kit with a wobbly sub'."),
+        },
+    }, ({ brief }) => promptText(`Design a PAM preset from this brief: "${brief}"\n\n` +
+        `1. Read design_context (curated parameter cheat sheet) and get_design_overview first — avoid full get_state dumps.\n` +
+        `2. Source sounds: randomize_samples with a genre hint, or get_default_locations → list_samples → load_sample. generate_sample creates bespoke hits (AI engines need update_settings experimental flags + a downloaded model).\n` +
+        `3. Shape each cell: set_parameters (design_context teaches ranges and units), update_effect_config for FX chains, set_drum_synth for synthesized drum layers.\n` +
+        `4. Add movement: add_modulation (LFO / envelope / vary), add_param_seq for stepped motion.\n` +
+        `5. Write patterns with update_pattern, then start_transport to audition.\n` +
+        `6. save_preset with a fitting name and update_preset_metadata (category, tags, BPM).`));
+if (!IS_MFX_SERVER)
+    server.registerPrompt("mix-and-master", {
+        title: "Mix and Master",
+        description: "Balance the cells and shape the master bus using the analysis + suggestion tools.",
+        argsSchema: {},
+    }, () => promptText(`Balance and master the current PAM project:\n\n` +
+        `1. get_mix_analysis with refresh:true (offline per-cell stem measurements — takes a few seconds) and get_master_analysis (live loudness snapshot).\n` +
+        `2. suggest_mix for rule-based balance / pan / EQ / dynamics moves; apply the returned parameter moves with set_parameters and enable keys with update_effect_config.\n` +
+        `3. Shape the master bus with set_master_effects (compressor, tape, limiter — design_context lists the keys).\n` +
+        `4. Re-check get_master_analysis and iterate toward the loudness target.\n` +
+        `5. Render with export_audio (mode 'main'; 'all-cells' for stems).`));
+if (!IS_MFX_SERVER)
+    server.registerPrompt("troubleshoot-bridge", {
+        title: "Troubleshoot the PAM Bridge",
+        description: "Diagnose why live tools can't reach the plugin.",
+        argsSchema: {},
+    }, () => promptText(`Diagnose the PAM MCP connection:\n\n` +
+        `1. connection_status. No instances → PAM isn't running or the bridge is off (PAM Settings → Experimental Mode → MCP Bridge, default port 9847). Multiple instances → select_instance picks which product the live tools drive.\n` +
+        `2. Instances found but not connected → the plugin may have shut down, or its message thread is busy (heavy render); retry once.\n` +
+        `3. Timeouts on WebView-routed tools (video tools, capture_ui, set_drum_synth_wave, randomize target 'synth') → the plugin window must be OPEN.\n` +
+        `4. "PAM build does not support 'X'" errors → the plugin is older than this server; the user must update PAM (updating the npm package alone is not enough).\n` +
+        `5. Offline tools always work without a plugin: get_parameter_info, design_context, list_presets, read_preset, get_manifest_summary.`));
 // ============================================================
 // TOOLS — Looper (state deltas)
 // ============================================================
@@ -4969,13 +6849,13 @@ async function applyLoopersDelta(loopers, extra) {
 server.registerTool("arm_looper_track", {
     title: "Arm / Disarm Looper Track",
     description: "Arm or disarm a looper track for recording. Arming alone does not start " +
-        "recording — call start_looper_recording afterwards (or use arm_and_record).",
+        "recording — call start_looper_recording afterwards, or pass armedCellIds to start_looper_recording to arm and record in one call.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
         armed: z.boolean().describe("true to arm, false to disarm."),
     },
 }, async ({ cellId, armed }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await applyLoopersDelta({ [cellId]: { armed: armed ? 1 : 0 } });
@@ -4983,8 +6863,8 @@ server.registerTool("arm_looper_track", {
 });
 server.registerTool("set_looper_track", {
     title: "Set Looper Track State",
-    description: "Update one or more per-track looper fields (mute, overdub mode, reverse, " +
-        "pitch, warp, capture source, level). Pass only the fields you want to change.",
+    description: "Update one or more per-track looper fields (mute, solo, overdub mode, reverse, " +
+        "pitch, warp, capture source, level, auto-select and recorded BPM). Pass only the fields you want to change.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
         mute: z.boolean().optional().describe("Mute / unmute."),
@@ -5075,7 +6955,7 @@ server.registerTool("clear_looper_track", {
         cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await applyLoopersDelta({
@@ -5103,7 +6983,7 @@ server.registerTool("set_looper_track_selection", {
 }, async ({ cellId, start, end }) => {
     if (end <= start)
         return error("end must be > start");
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await applyLoopersDelta({
@@ -5137,7 +7017,7 @@ server.registerTool("start_looper_recording", {
             .describe("Per-track metadata. Defaults: replace mode, cell-output source. Pass existingClipPaths to enable overdub on a prior layer."),
     },
 }, async ({ loopBars, armedCellIds, trackMetadata }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(armedCellIds);
     if (check !== true)
         return check;
     // Arm in UI state too — the plugin's live recording overlay and progress
@@ -5211,7 +7091,7 @@ server.registerTool("request_looper_warp", {
         cellId: z.number().min(1).max(8).describe("Looper track (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("requestLooperWarp", cellId);
@@ -5287,7 +7167,7 @@ server.registerTool("looper_variation", {
         data: z
             .record(z.string(), z.unknown())
             .optional()
-            .describe("For 'save': the looper variation snapshot (object). Pass null to clear instead."),
+            .describe("For 'save': the looper variation snapshot (object). Omit this field to clear the slot instead."),
     },
 }, async (args) => {
     const check = await requireBridge();
@@ -5365,21 +7245,21 @@ server.registerTool("queue_variation", {
     inputSchema: {
         index: z.number().min(0).max(7).describe("Variation slot 0-7."),
         intervalBars: z.number().min(0.125).max(64).describe("Bars before switching."),
-        fadeMs: z.number().min(0).max(2000).default(20).describe("Crossfade duration in ms."),
+        fadeMs: z.number().min(0).max(2000).optional().describe("Crossfade duration in ms. Omit all transition options to inherit the native Bar Sync/Song Mode settings."),
         resetPhase: z
             .boolean()
-            .default(true)
-            .describe("Reset pattern phase on switch."),
+            .optional()
+            .describe("Reset pattern phase on switch. Omit to inherit native settings."),
         morphBars: z
             .number()
             .min(0.25)
             .max(8)
             .optional()
-            .describe("Pre-anchor morph window in bars for this flip (PAM >= 1.19.3). Omit = hard switch."),
+            .describe("Pre-anchor morph window in bars for this flip. Omit all transition options to inherit native settings."),
         morphMode: z
             .enum(["auto", "param", "mix", "seq", "all"])
             .optional()
-            .describe("Morph style: 'param' glides continuous params (default); 'mix' equal-power blends the two sections; 'seq' adds a staged pattern dissolve to the glide (old notes lose trigger probability as new notes gain it); 'all' runs glide + dissolve + blend together; 'auto' lets the engine pick — mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; seq/all on older builds run param)."),
+            .describe("Morph style: 'param' glides continuous params (default); 'mix' equal-power blends the two sections; 'seq' adds a staged pattern dissolve to the glide (old notes lose trigger probability as new notes gain it); 'all' runs glide + dissolve + blend together; 'auto' lets the engine pick — mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise."),
         morphCurve: z
             .enum(["linear", "ease", "exp", "log"])
             .optional()
@@ -5392,7 +7272,7 @@ server.registerTool("queue_variation", {
             tailMaxBars: z.number().min(0.25).max(8).optional(),
         })
             .optional()
-            .describe("Advanced transition settings for this flip (PAM >= 1.20.0): pattern policy for a " +
+            .describe("Advanced transition settings for this flip: pattern policy for a " +
             "seq/all morph, blend gain law for a mix/all morph, and the outgoing section's " +
             "tail. Omitted fields keep the defaults (dissolve, equalPower, fade)."),
     },
@@ -5403,8 +7283,8 @@ server.registerTool("queue_variation", {
     await bridge.send("queueVariationOnBars", {
         index,
         intervalBars,
-        fadeMs,
-        resetPhase,
+        ...(fadeMs !== undefined && { fadeMs }),
+        ...(resetPhase !== undefined && { resetPhase }),
         ...(morphBars !== undefined && { morphBars }),
         ...(morphMode !== undefined && { morphMode }),
         ...(morphCurve !== undefined && { morphCurve }),
@@ -5445,7 +7325,7 @@ server.registerTool("update_variations", {
 server.registerTool("variation_hold", {
     title: "Variation Hold",
     description: "'Hold while note pressed' mode for variations. Use this to map MIDI notes to momentary " +
-        "variation switches that revert when the note releases.",
+        "variation switches. Hold mode reverts when the note releases; latch mode stays.",
     inputSchema: {
         enabled: z.boolean().optional().describe("Toggle hold mode on/off."),
         allNotesOff: z
@@ -5567,7 +7447,6 @@ server.registerTool("update_modulation", {
     title: "Update Modulation",
     description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, ParamSeq sequence data, " +
         "or the Free Sequencer master pattern. " +
-        "The payload is type-specific; see modulation update flows in interop.ts (applyLfoUpdate / updateEnvelope / etc.). " +
         "Use add_modulation to first attach a source to a target — then this tool to edit it.",
     inputSchema: {
         type: z
@@ -5575,7 +7454,11 @@ server.registerTool("update_modulation", {
             .describe("Which modulation system to update."),
         payload: z
             .record(z.string(), z.unknown())
-            .describe("Update payload object. Shape depends on type: lfo expects { index, rate?, depth?, shape?, customCurve?, target? }, envelope expects matrix entry edits, paramSeqSequence expects { id, steps[] }, freeSeqSequence expects { sequence: number[] } (the master step contour every free-mode ParamSeq follows), etc."),
+            .describe("Update payload object, one property per call. lfo, envelope, vary, macro and paramSeq all take " +
+            "{ index, property, value }, where index is the 0-based position in that state array (get_state " +
+            "section 'lfos' / 'envelopes' / 'vary' / 'macros' / 'paramSeqs') and property is the field name to " +
+            "overwrite. paramSeqSequence takes { index, sequence: number[] }. freeSeqSequence takes " +
+            "{ sequence: number[] } — the master step contour every free-mode ParamSeq follows."),
     },
 }, async ({ type, payload }) => {
     const check = await requireBridge();
@@ -5601,13 +7484,6 @@ server.registerTool("update_modulation", {
 // ============================================================
 // TOOLS — Song mode
 // ============================================================
-// Advanced transition spec (ADR-001, PAM >= 1.19.6; engine families live from
-// PAM >= 1.20.0). Honest contract: it persists, round-trips, and reads back
-// RESOLVED. Pattern policy (dissolve/wipe/cells), mix law (equal power / equal
-// gain / correlation), tail (cut/fade/ring) and phase run on song VARIATION
-// sections and queued bar-sync flips; preset destinations coerce to a param
-// glide, and offline bounces coerce ring→fade and blend→hard switch (each
-// reported, never silent). Wire enums are append-only.
 const morphCurveEnum = z.enum(["linear", "ease", "exp", "log"]);
 const transitionSpecSchema = z.object({
     mode: z.enum(["auto", "param", "mix", "seq", "all"]).optional(),
@@ -5617,6 +7493,10 @@ const transitionSpecSchema = z.object({
         paramCurve: morphCurveEnum.optional(),
         patternCurve: morphCurveEnum.optional(),
         mixCurve: morphCurveEnum.optional(),
+        staggerBy: z.enum(["off", "cell", "category"]).optional(),
+        staggerSpread: z.number().min(0).max(0.9).optional(),
+        staggerOrder: z.enum(["forward", "reverse"]).optional(),
+        relations: z.enum(["off", "stepped"]).optional(),
     })
         .optional(),
     pattern: z.object({ policy: z.enum(["dissolve", "wipe", "cells"]).optional() }).optional(),
@@ -5629,23 +7509,25 @@ const transitionSpecSchema = z.object({
         .optional(),
     phase: z.enum(["inherit", "reset", "continue"]).optional(),
 });
-const TRANSITION_SPEC_HONESTY = "Advanced transition spec (PAM >= 1.19.6; live engine from PAM >= 1.20.0): pattern.policy " +
+const TRANSITION_SPEC_HONESTY = "Advanced transition spec: pattern.policy " +
     "('dissolve' prob-morphs events, 'wipe' replaces them at a moving frontier, 'cells' hands " +
     "whole cells over in ascending order), audio.mixLaw ('equalPower' default, 'equalGain' for " +
     "correlated sections, 'correlation' auto-adapts), audio.tail ('fade' default, 'cut', 'ring' " +
     "lets voices/FX decay up to tailMaxBars), phase ('reset'/'continue' overrides the song's " +
     "Reset Phase per cable), window.patternCurve/mixCurve (per-domain easing; patternCurve " +
-    "defaults linear). Runs on variation sections + queued flips, and on preset destinations " +
-    "when the lanePresetSections setting is on (PAM >= 1.20.1 — the dual-lane preset section " +
+    "defaults linear). window.staggerBy (off/cell/category), staggerSpread (0..0.9), staggerOrder (forward/reverse), and relations (off/stepped) shape the parameter glide. Runs on variation sections + queued flips, and on preset destinations " +
+    "when the lanePresetSections setting is on (the dual-lane preset section " +
     "pipeline; with it off, preset destinations coerce to a param glide). Offline bounces " +
     "coerce ring→fade, blend→hard switch. 'get' reads back each cable's resolvedTransition " +
     "(effective values after inheritance and capability coercion) and lastMorphResolution " +
-    "(the engine's latest AUTO decision + reason).";
+    "(the engine's latest AUTO decision + reason; published only for an AUTO request, and " +
+    "one per song rather than one per cable).";
 server.registerTool("song_mode", {
     title: "Song Mode",
     description: "Control PAM's song mode (timeline of variation/preset sections). Ops: 'setArrangement', " +
         "'get', 'assignVx', 'setSequence', 'clear', 'toggle', 'setLoopPoints', 'toggleLoop', " +
-        "'setCrossfadeMs', 'setPlayhead'.\n\n" +
+        "'setCrossfadeMs', 'setPlayhead'. WebView-routed (window must be OPEN): setArrangement, get, assignVx. " +
+        "Headless: setSequence, clear, toggle, setLoopPoints, toggleLoop, setCrossfadeMs, setPlayhead.\n\n" +
         "PREFER 'setArrangement' (PAM ≥ 1.5.7, window open): it authors real Song Mode grid nodes " +
         "from a `sections` list, with an optional weighted `connections` graph. The result is " +
         "visible/editable in the UI, and each section can pin a " +
@@ -5653,8 +7535,11 @@ server.registerTool("song_mode", {
         "audio slot 1:1; see the vx_variation tool), optionally inside a specific VX scene via " +
         "`vxScenePath` (the .vxpreset loads before the section plays, so sections can pull visuals " +
         "from different scenes). A section can also carry `morphBars`/`morphCurve`/`morphMode` to glide the " +
-        "incoming variation's continuous params over the bars before its boundary (PAM >= 1.19.3), and an " +
-        "advanced `transition` spec (PAM >= 1.19.6 — authored metadata; see the field description). " +
+        "incoming variation's continuous params over the bars before its boundary, and an " +
+        "advanced `transition` spec (see the field description). " +
+        "A `transitionPreset` id (or `defaultTransitionPreset` at the top level) stamps a whole named " +
+        "transition in one field; op 'get' lists the available ids in `transitionPresets` and reports " +
+        "each cable's derived `transitionPreset`. " +
         "'get' reads the arrangement back (nodes, compiled steps with the " +
         "VX scene+slot each recalls, total bars, and each cable's `resolvedTransition` — the effective " +
         "transition after inheritance and capability coercion, e.g. preset destinations report param); " +
@@ -5684,14 +7569,14 @@ server.registerTool("song_mode", {
             repeat: z.number().int().min(1).optional().describe("Times to play before advancing (default 1)."),
             muted: z.boolean().optional().describe("Pass through without an audio trigger."),
             probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
-            presetPath: z.string().optional().describe("Cross-preset section: at this section's boundary the song switches to THIS preset file, playing its variations[variationIndex] slot. With lanePresetSections on (PAM >= 1.20.1) it transitions exactly like a variation section (prepared off the audible path, full morph family); otherwise the legacy in-place load applies."),
+            presetPath: z.string().optional().describe("Cross-preset section: at this section's boundary the song switches to THIS preset file, playing its variations[variationIndex] slot. With lanePresetSections on it transitions exactly like a variation section (prepared off the audible path, full morph family); otherwise the legacy in-place load applies."),
             label: z.string().optional().describe("Section label shown on the grid node (e.g. 'Intro', 'Hook')."),
             morphBars: z
                 .number()
                 .min(0)
                 .max(8)
                 .optional()
-                .describe("Pre-anchor morph window in bars for the transition INTO this section — continuous params glide to the new values, landing at the boundary (PAM >= 1.19.3). 0 = explicit hard switch (never morph, ignores the song's default); omit to inherit the default. Values in (0, 0.25) clamp up to 0.25."),
+                .describe("Pre-anchor morph window in bars for the transition INTO this section — continuous params glide to the new values, landing at the boundary. 0 = explicit hard switch (never morph, ignores the song's default); omit to inherit the default. Values in (0, 0.25) clamp up to 0.25."),
             morphCurve: z
                 .enum(["linear", "ease", "exp", "log"])
                 .optional()
@@ -5699,8 +7584,12 @@ server.registerTool("song_mode", {
             morphMode: z
                 .enum(["auto", "param", "mix", "seq", "all"])
                 .optional()
-                .describe("Morph realization; default auto — the engine picks mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; older builds run param). 'param' glides continuous params; 'mix' DJ-blends stems; 'seq' adds a staged pattern dissolve to the glide; 'all' runs glide + dissolve + blend (seq/all on older builds run param). Ignored without morphBars."),
+                .describe("Morph realization; default auto — the engine picks mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise. 'param' glides continuous params; 'mix' DJ-blends stems; 'seq' adds a staged pattern dissolve to the glide; 'all' runs glide + dissolve + blend. Ignored without morphBars."),
             transition: transitionSpecSchema.optional().describe(TRANSITION_SPEC_HONESTY),
+            transitionPreset: z
+                .string()
+                .optional()
+                .describe("Named transition preset id — read the list from op 'get' (`transitionPresets`: the factory set plus the user's saved ones). Stamps every transition field onto the incoming cable; morphBars/morphCurve/morphMode/transition on the same object override the stamp field by field. Unknown ids fail with the known list."),
             vxVariationIndex: z
                 .number()
                 .int()
@@ -5743,6 +7632,10 @@ server.registerTool("song_mode", {
                 .optional()
                 .describe("Per-cable morph realization; overrides the destination section's morphMode. Same modes as the section field, incl. 'seq' (pattern dissolve) and 'all' (glide + dissolve + blend)."),
             transition: transitionSpecSchema.optional().describe("Per-cable " + TRANSITION_SPEC_HONESTY),
+            transitionPreset: z
+                .string()
+                .optional()
+                .describe("Named transition preset id — read the list from op 'get' (`transitionPresets`: the factory set plus the user's saved ones). Stamps every transition field onto the incoming cable; morphBars/morphCurve/morphMode/transition on the same object override the stamp field by field. Unknown ids fail with the known list."),
         }))
             .optional()
             .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section. Each cable may carry its own morphBars/morphCurve/morphMode/transition."),
@@ -5750,6 +7643,11 @@ server.registerTool("song_mode", {
             .nullable()
             .optional()
             .describe("For 'setArrangement': song-level advanced transition defaults inherited by cables without their own `transition`; null clears. " + TRANSITION_SPEC_HONESTY),
+        defaultTransitionPreset: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("For 'setArrangement': stamp a named preset as the song-level default transition (see transitionPreset)."),
         loop: z.boolean().optional().describe("For 'setArrangement': loop the whole arrangement."),
         nodeId: z.string().optional().describe("For 'assignVx': grid node id (from op 'get')."),
         stepIndex: z.number().int().min(0).optional().describe("For 'assignVx': compiled step index (alternative to nodeId)."),
@@ -5808,29 +7706,37 @@ server.registerTool("song_mode", {
         case "setArrangement": {
             if (!args.sections || args.sections.length === 0)
                 return error("'setArrangement' requires sections");
+            const requestId = mintVideoRequestId();
             await sendVideoCommand({
                 op: "setSongArrangement",
+                requestId,
                 sections: args.sections,
                 ...(args.connections !== undefined && { connections: args.connections }),
                 ...(args.defaultTransition !== undefined && { defaultTransition: args.defaultTransition }),
+                ...(args.defaultTransitionPreset !== undefined && { defaultTransitionPreset: args.defaultTransitionPreset }),
                 ...(args.loop !== undefined && { loop: args.loop }),
                 ...(args.enabled !== undefined && { enabled: args.enabled }),
                 ...(args.crossfadeMs !== undefined && { crossfadeMs: args.crossfadeMs }),
             });
-            // The forward path is fire-and-forget — poll until the WebView's apply
-            // republishes the snapshot (same pattern as resolveNewId).
             const deadline = Date.now() + 3000;
             let sm;
+            let acknowledged = false;
             for (;;) {
                 const state = await getVideoStateRaw();
-                sm = state.songMode;
-                const landed = sm?.available === true &&
-                    Array.isArray(sm.nodes) &&
-                    sm.nodes.length === args.sections.length;
-                if (landed || Date.now() > deadline)
+                const ack = state.lastCommandAck;
+                if (ack?.requestId === requestId) {
+                    if (ack.ok !== true)
+                        return error(ack.error ?? "Song arrangement was rejected.");
+                    sm = state.songMode;
+                    acknowledged = true;
+                    break;
+                }
+                if (Date.now() > deadline)
                     break;
                 await sleep(150);
             }
+            if (!acknowledged)
+                return error("Song arrangement was sent but its completion was not acknowledged. Open PAM's window and use a current plugin build; inspect song_mode op:'get' before retrying.");
             if (!sm || sm.available !== true)
                 return error("Arrangement command sent, but no song-mode read-model came back — this needs PAM ≥ 1.5.7 " +
                     "with the window OPEN. On older builds fall back to op 'setSequence' (headless raw steps).");
@@ -5915,11 +7821,13 @@ server.registerTool("export_song", {
         "• 'live' with cellId — legacy headless master-mix capture into an empty cell (works with the window " +
         "closed on PAM ≥ 1.5.0). The captured WAV also lands in PAM's Resamples folder.\n" +
         "• 'offline' — the DETERMINISTIC multi-section bounce (PAM ≥ 1.5.7 with offline song export): every " +
-        "variation section applies sample-accurately on its anchor; renders faster than realtime with no bar cap. " +
+        "variation section applies sample-accurately on its anchor and renders faster than realtime; `bars` is still required and capped at 64. " +
         "Audio-only works headless (window closed); includeVideo runs the offline video pump with per-section VX " +
         "recalls (window open, WebCodecs). Caveats: preset-path steps hold the previous section's sound (pending), " +
         "and wall-clock sources (Magenta, Notochord, camera layers) cannot render offline — use 'live' for those.\n\n" +
         "Live paths render in REAL TIME (a 90 s song takes ~90 s) and cap at 64 bars per capture. " +
+        "This is the entry point for arrangement bounces: strategy 'offline' issues the same render as " +
+        "`export_audio` with mode 'song-mode', and the live and audio+video strategies exist only here. " +
         "Verify audio results with get_audio_info (resolve cell captures against the Resamples location " +
         "from get_default_locations).",
     inputSchema: {
@@ -5928,7 +7836,7 @@ server.registerTool("export_song", {
             .number()
             .min(1)
             .max(64)
-            .describe("Total arrangement length in bars (the full timeline). Required for 'live'."),
+            .describe("Total arrangement length in bars (the full timeline), 1-64. Required for every strategy."),
         cellId: z
             .number()
             .min(1)
@@ -5942,7 +7850,10 @@ server.registerTool("export_song", {
         name: z.string().optional().describe("Output name for WebView Song Export renders (default 'Song')."),
         normalize: z.boolean().optional().describe("Normalize the captured audio (WebView Song Export paths)."),
         encoderId: z.string().optional().describe("Recording encoder preset for includeVideo (e.g. mp4-h264)."),
-        bitDepth: z.number().default(24).describe("Bit depth (16 or 24; legacy cell-capture + offline paths)."),
+        bitDepth: z
+            .union([z.literal(16), z.literal(24)])
+            .default(24)
+            .describe("Bit depth: 16 or 24 (legacy cell-capture + offline paths)."),
         tailBars: z
             .number()
             .min(0)
@@ -5951,7 +7862,7 @@ server.registerTool("export_song", {
             .describe("For legacy cell-capture 'live': extra bars captured after the arrangement end for tails."),
     },
 }, async ({ strategy, bars, cellId, includeVideo, name, normalize, encoderId, bitDepth, tailBars }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     // -------- Offline audio-only: headless multi-section bounce --------
@@ -6095,9 +8006,10 @@ server.registerTool("set_metronome", {
 // ============================================================
 server.registerTool("analyze_sample_tempo", {
     title: "Analyze Sample Tempo",
-    description: "Run BPM detection and transient/slice analysis on an audio file. " +
-        "Result is dispatched asynchronously into PAM's state — fetch it via get_state after a short delay (~100-500ms). " +
-        "Use this before resample_sample_to_bpm if you don't already know the source BPM.",
+    description: "Run BPM detection and transient/slice analysis on an audio file. The result lands in the plugin's " +
+        "sample-metadata cache and the editor's sample library; the bridge does not capture it, so there is no " +
+        "get_state key that reads it back. Run it before resample_sample_to_bpm so the stretch has a source BPM, " +
+        "and use get_audio_info for a file's own format properties.",
     inputSchema: {
         filePath: z.string().describe("Path to the audio file."),
         transientSensitivity: z
@@ -6156,11 +8068,11 @@ server.registerTool("preview_slice", {
     title: "Preview Slice",
     description: "Audition a single slice of a cell's sample.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
-        sliceNumber: z.number().min(0).describe("Slice index."),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        sliceNumber: z.number().min(0).describe("Slice index (0-based)."),
     },
 }, async ({ cellId, sliceNumber }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("previewSlice", cellId, sliceNumber);
@@ -6171,7 +8083,7 @@ server.registerTool("resample_sample_to_bpm", {
     description: "Time-stretch a cell's sample to the current project BPM (or a target BPM). " +
         "Non-destructive — use restore_original_sample to revert.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         sourceBpm: z
             .number()
             .min(20)
@@ -6196,10 +8108,10 @@ server.registerTool("restore_original_sample", {
     title: "Restore Original Sample",
     description: "Revert a cell's sample to its un-edited source (undoes resample / trim / etc.).",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("restoreOriginalSample", { cellId });
@@ -6213,7 +8125,7 @@ server.registerTool("build_sample_chain", {
         cellId: z.number().min(1).max(8).describe("Destination cell."),
     },
 }, async ({ filePaths, cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     const result = await bridge.send("buildSampleChain", filePaths, cellId);
@@ -6223,11 +8135,11 @@ server.registerTool("export_slice", {
     title: "Export Slice",
     description: "Export a single slice of a cell's sample as a standalone WAV.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
-        sliceIndex: z.number().min(0),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        sliceIndex: z.number().min(0).describe("Slice index (0-based)."),
     },
 }, async ({ cellId, sliceIndex }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("exportSliceForCell", { cellId, sliceIndex });
@@ -6241,7 +8153,8 @@ server.registerTool("live_resample", {
     description: "Capture PAM's audio graph output into a cell as a new sample, in real time. Ops: 'start' / 'stop'. " +
         "Transport MUST be playing for the capture to produce audio. Because the capture runs live, " +
         "Song Mode section changes, modulation, and variation switches are all captured faithfully — " +
-        "this is the building block for full-track / Song Mode bounces (see export_song).\n\n" +
+        "this is the building block for full-track / Song Mode bounces (see export_song). On finalize the captured clip " +
+        "REPLACES whatever sample the destination cell held — use an empty cell, or reload the preset before saving anything afterwards.\n\n" +
         "`source` selects what to record: 'cell' (the destination cell's own output), 'input' (PAM's audio input), " +
         "or 'fullmix' (the whole master mix — use this to bounce the entire arrangement).",
     inputSchema: {
@@ -6272,14 +8185,21 @@ server.registerTool("live_resample", {
             .describe("For 'stop': finalize the captured clip (false discards)."),
     },
 }, async (args) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(args.op === "start" ? args.cellId : undefined);
     if (check !== true)
         return check;
     if (args.op === "start") {
+        if (activeLiveResample) {
+            return error(`A live resample started by this server is already targeting cell ${activeLiveResample.cellId}. Stop it first.`);
+        }
         if (typeof args.cellId !== "number" || typeof args.bars !== "number")
             return error("'start' requires cellId + bars");
         const source = args.source ?? "cell";
         const captureSource = source === "fullmix" ? 2 : source === "input" ? 1 : 0;
+        const beforeRaw = await bridge.send("getState");
+        const beforeCells = isRecord(beforeRaw) && isRecord(beforeRaw.cells) ? beforeRaw.cells : {};
+        const beforeCell = beforeCells[String(args.cellId)];
+        const before = isRecord(beforeCell) ? beforeCell : {};
         await bridge.send("resampleGraphToCell", JSON.stringify({
             cellId: args.cellId,
             bars: args.bars,
@@ -6290,10 +8210,48 @@ server.registerTool("live_resample", {
             cellOnly: source === "cell",
             normalize: args.normalize ?? false,
         }));
+        activeLiveResample = {
+            cellId: args.cellId,
+            previousPath: typeof before.filePath === "string" ? before.filePath : undefined,
+        };
         return text(`Started live resample → cell ${args.cellId} (${args.bars} bars, source '${source}').`);
     }
-    await bridge.send("stopLiveResample", args.finalize ?? true);
-    return text(`Stopped live resample (finalize=${args.finalize ?? true}).`);
+    const finalize = args.finalize ?? true;
+    await bridge.send("stopLiveResample", finalize);
+    const capture = activeLiveResample;
+    activeLiveResample = undefined;
+    if (!finalize)
+        return text("Stopped live resample and discarded the capture.");
+    if (!capture)
+        return error("Stopped live resample, but this server did not start it and cannot identify the destination cell.");
+    let capturedPath;
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const stateRaw = await bridge.send("getState");
+        const state = isRecord(stateRaw) ? stateRaw : {};
+        const stateCells = isRecord(state.cells) ? state.cells : {};
+        const rawCell = stateCells[String(capture.cellId)];
+        const cell = isRecord(rawCell) ? rawCell : {};
+        if (typeof cell.filePath === "string" && cell.filePath && cell.filePath !== capture.previousPath) {
+            capturedPath = cell.filePath;
+            break;
+        }
+        await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+    }
+    if (!capturedPath) {
+        return error(`Capture finalized into cell ${capture.cellId}, but its new file path was not available after 5 seconds.`);
+    }
+    if (!isAbsolute(capturedPath)) {
+        const locations = await bridge.send("getDefaultLocations");
+        const userSamples = Array.isArray(locations)
+            ? locations.find((location) => isRecord(location) && location.name === "User Samples")
+            : undefined;
+        if (isRecord(userSamples) && typeof userSamples.path === "string") {
+            const normalized = capturedPath.replaceAll("\\", "/");
+            const userRelative = normalized.replace(/^Samples\/User\//, "");
+            capturedPath = join(userSamples.path, userRelative);
+        }
+    }
+    return text(`Stopped live resample and finalized cell ${capture.cellId}.\nFile: ${capturedPath}`);
 });
 // ============================================================
 // TOOLS — Plugin host (scan/load/unload/param/bypass on hosted VST3/AU/CLAP)
@@ -6475,7 +8433,7 @@ server.registerTool("list_loaded_plugins", {
     title: "List Loaded Plugins",
     description: "List plugins currently hosted in PAM cells (instrument slot only — FX-side hosting is not exposed). " +
         "Each entry: cellId, name, manufacturer, format, " +
-        "path, isInstrument, bypassed, and the plugin's full param list (index, name, label, value, defaultValue). " +
+        "path, isInstrument, bypassed, and the plugin's full param list (index, name, label, value, defaultValue, discrete, numSteps, and valueStrings for a discrete param). " +
         "Use the param `index` with `set_plugin_param`.",
     inputSchema: {},
 }, async () => {
@@ -6517,7 +8475,8 @@ server.registerTool("load_plugin", {
         ...(args.uniqueId ? { uniqueId: args.uniqueId } : {}),
         ...(args.name ? { name: args.name } : {}),
     }));
-    return text(raw);
+    // Native answers a success with an object (`{ok: true, …}`), a failure with a string.
+    return text(typeof raw === "string" ? raw : JSON.stringify(raw));
 });
 server.registerTool("unload_plugin", {
     title: "Unload Plugin From Cell",
@@ -6540,10 +8499,10 @@ server.registerTool("set_plugin_param", {
     description: "Set a parameter on a hosted plugin by cell + parameter index. Value is normalized 0..1. " +
         "Use `list_loaded_plugins` to find param indices and names. " +
         "This is the dedicated path for hosted plugin params — `set_parameters` won't reach them. " +
-        "Targets the cell's instrument-slot plugin only.",
+        "It exists for a single instrument-slot value; use `set_plugin_params` for a batch or for the FX slot.",
     inputSchema: {
-        cellId: z.number().int().min(1),
-        paramIndex: z.number().int().min(0),
+        cellId: z.number().int().min(1).describe("Cell hosting the plugin."),
+        paramIndex: z.number().int().min(0).describe("Parameter index from list_loaded_plugins."),
         value: z.number().min(0).max(1).describe("Normalized 0..1."),
     },
 }, async (args) => {
@@ -6565,8 +8524,8 @@ server.registerTool("set_plugin_bypass", {
     description: "Toggle bypass on the hosted plugin in a cell (instrument slot). Bypassed plugins are silenced; the cell sampler " +
         "still plays in parallel.",
     inputSchema: {
-        cellId: z.number().int().min(1),
-        bypassed: z.boolean(),
+        cellId: z.number().int().min(1).describe("Cell hosting the plugin."),
+        bypassed: z.boolean().describe("true silences the hosted plugin, false re-enables it."),
     },
 }, async (args) => {
     const check = await requireBridge();
@@ -6665,6 +8624,22 @@ server.registerTool("get_audio_device_setup", {
     const setup = await bridge.send("getAudioDeviceSetup");
     return json(setup);
 });
+server.registerTool("get_memory_report", {
+    title: "Get Memory Report",
+    description: "Report the instance's audio memory: vfsBytes (decoded samples resident in the engine's virtual file system), " +
+        "vfsRetiredBytes (superseded buffers not yet reclaimed), vfsEntryCount, looperRingBytes (allocated looper " +
+        "capture rings), and residentBytes (whole-process RSS; residentBytesAvailable is false when the platform " +
+        "could not answer, in which case residentBytes is 0 rather than empty). Use it to check whether loading, " +
+        "replacing or auditioning samples leaves memory flat or growing.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const report = await bridge.send("getMemoryReport");
+    return json(report);
+});
 server.registerTool("set_audio_device", {
     title: "Set Audio Output Device",
     description: "Switch the active audio OUTPUT device by name (standalone only — plugin-hosted builds let the DAW own the " +
@@ -6771,7 +8746,9 @@ server.registerTool("get_sample_usage", {
     description: "Cross-reference samples and presets. mode 'presetUsesSamples' lists the samples a preset references; " +
         "mode 'presetsUsingSample' lists presets that reference a given sample (or any sample under a folder).",
     inputSchema: {
-        mode: z.enum(["presetUsesSamples", "presetsUsingSample"]),
+        mode: z
+            .enum(["presetUsesSamples", "presetsUsingSample"])
+            .describe("Which direction to cross-reference: from a preset to its samples, or from a sample to the presets using it."),
         path: z
             .string()
             .describe("Relative preset path (presetUsesSamples) or relative sample path (presetsUsingSample)."),
@@ -6796,7 +8773,9 @@ server.registerTool("repair_preset_samples", {
         "library (optionally scoped to one preset). mode 'rescan' re-audits a preset for still-missing samples and " +
         "reports them. Useful after moving a sample library or importing presets from another machine.",
     inputSchema: {
-        mode: z.enum(["fix", "rescan"]),
+        mode: z
+            .enum(["fix", "rescan"])
+            .describe("'fix' relinks moved samples by searching the library; 'rescan' only reports what is still missing."),
         presetPath: z
             .string()
             .optional()
@@ -6840,7 +8819,9 @@ server.registerTool("preview_sample", {
 server.registerTool("set_plugin_params", {
     title: "Set Hosted Plugin Params (batch)",
     description: "Set multiple hosted-plugin parameters in one call (more efficient than set_plugin_param per value). Values are " +
-        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'.",
+        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'. " +
+        "role:'effect' reaches the FX slot, but list_loaded_plugins reports instrument-slot plugins only, so " +
+        "effect-slot param indices are not discoverable through MCP.",
     inputSchema: {
         cellId: z.number().int().min(1).describe("Cell number."),
         role: z.enum(["instrument", "effect"]).optional().describe("Which hosted slot (default 'instrument')."),
@@ -6927,6 +8908,9 @@ const SET_VIEW_MAIN_VIEW = {
     export: "Export",
     presets: "PresetBrowser",
     browser: "PresetBrowser",
+    // MFX-only surfaces. The handler rejects them for other products.
+    patch: "MfxRouting",
+    patchbay: "MfxRouting",
 };
 // Dev-tree twin of the in-plugin assistant's set_view (toolpack-gated like
 // ask_assistant — the published server deliberately excludes window/view
@@ -6946,12 +8930,13 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
             view: z
                 .union([z.string(), z.number()])
                 .optional()
-                .describe("Main view: cells, mixer, ctrl, looper, song, lfo, envelope, vary, paramseq, video, export, presets."),
+                .describe("Main view: cells, mixer, ctrl, looper, song, lfo, envelope, vary, paramseq, video, export, presets. " +
+                "MFX also takes patch (the cable patchbay)."),
             cellId: z.number().int().optional().describe("Cell to select/focus (1-8)."),
             gridSize: z.number().optional().describe("How many pads the grid shows: 1, 4, or 8."),
         },
     }, async ({ view: viewArg, cellId, gridSize }) => {
-        const check = await requireBridge();
+        const check = await requireBridgeForCells(cellId);
         if (check !== true)
             return check;
         let view = viewArg === undefined ? undefined : String(viewArg);
@@ -6967,7 +8952,12 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
         if (typeof view === "string" && view.trim()) {
             token = view.trim().toLowerCase();
             if (!(token in SET_VIEW_MAIN_VIEW))
-                return error(`Unknown view: ${view}. Views: cells, mixer, ctrl, looper, song, lfo, envelope, vary, paramseq, video, export, presets.`);
+                return error(`Unknown view: ${view}. Views: cells, mixer, ctrl, looper, song, lfo, envelope, vary, paramseq, video, export, presets, patch.`);
+            if (token === "patch" || token === "patchbay") {
+                const manifest = await loadManifestForProductGuard();
+                if (manifest && !isMfxManifest(manifest))
+                    return error(`${token} is available in MFX only.`);
+            }
             applied.view = token;
         }
         if (gridSize !== undefined) {
@@ -7081,9 +9071,12 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
                         playing: Boolean(transport.playing ?? transport.isPlaying),
                         preset,
                         sel: sel ?? null,
-                        cells: (overview.cells ?? [])
-                            .filter((c) => c.sample || c.synth)
-                            .map((c) => ({ id: c.id, name: c.sample ?? `${c.synth}(synth)` })),
+                        muted: (overview.cells ?? []).filter((c) => c.muted).map((c) => c.cellId),
+                        cells: (overview.cells ?? []).flatMap((c) => {
+                            const name = c.sample?.path || c.sample?.name
+                                || (c.synthEngine && c.synthEngine.id > 0 ? `${c.synthEngine.name}(synth)` : undefined);
+                            return name ? [{ id: c.cellId, name }] : [];
+                        }),
                     };
                 }
             }
@@ -7185,13 +9178,55 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
 // ============================================================
 // Start
 // ============================================================
+// A stdio server that dies takes its whole tool surface with it, and the client
+// only ever reports "Connection closed". Nothing short of an explicit exit is
+// worth that, so stray async faults are logged to stderr and the server lives.
+// The rule must stay BOUNDED: a fault that repeats every tick turns "the server
+// lives" into a permanent 100% CPU spin, and each report re-formats a tsx
+// source-mapped stack. Five orphaned servers burned a core each for over a week.
+const FAULT_WINDOW_MS = 10_000;
+const FAULT_LIMIT = 100;
+let faultTimes = [];
+function surviveFault(label, value) {
+    const now = Date.now();
+    faultTimes = faultTimes.filter((t) => now - t < FAULT_WINDOW_MS);
+    faultTimes.push(now);
+    if (faultTimes.length > FAULT_LIMIT)
+        process.exit(1);
+    try {
+        console.error(label, value);
+    }
+    catch {
+        process.exit(1);
+    }
+}
+// EPIPE on our own stdio is the dead-client signal, not a stray fault: the SDK
+// writes JSON-RPC to stdout unguarded, and routing that through the handler
+// below made the logger re-raise the fault it was reporting. Exit at the source.
+for (const s of [process.stdout, process.stderr]) {
+    s.on("error", (e) => {
+        if (e?.code === "EPIPE")
+            process.exit(0);
+    });
+}
+process.on("unhandledRejection", (reason) => {
+    surviveFault("[pam-mcp] unhandled rejection (server continuing):", reason);
+});
+process.on("uncaughtException", (err) => {
+    surviveFault("[pam-mcp] uncaught exception (server continuing):", err);
+});
 async function main() {
     if (await handleCliArgs())
         return;
     // Try to connect to plugin on startup (non-blocking)
-    void bridge.connect().then((ok) => {
+    void bridge
+        .connect()
+        .then((ok) => {
         if (ok)
             syncProductHint();
+    })
+        .catch((e) => {
+        console.error("[pam-mcp] startup bridge connect failed:", e);
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
@@ -7202,9 +9237,27 @@ main().catch((e) => {
     console.error("Fatal:", e);
     process.exit(1);
 });
-process.on("SIGINT", async () => {
+// MCP clients terminate stdio servers with SIGTERM as often as SIGINT; without
+// both, the bridge socket is left for the OS to reap.
+let shuttingDown = false;
+const shutdown = async () => {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
     bridge.disconnect();
-    await server.close();
+    try {
+        await server.close();
+    }
+    catch {
+        // Already torn down — exiting anyway.
+    }
     process.exit(0);
-});
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+// A client that dies without signalling leaves no signal at all — the process is
+// reparented to launchd and only stdin EOF says the session is gone. Without this
+// the server outlives every crashed client; ten-day-old orphans were measured.
+process.stdin.on("end", () => void shutdown());
+process.stdin.on("close", () => void shutdown());
 //# sourceMappingURL=server.js.map