@map-audio/pam-mcp-server 1.18.1 → 1.22.0

package/dist/server.js

@@ -3,26 +3,37 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 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 { 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 { readFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 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 { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
+import { createDrumSynthCatalog, } from "./drumSynth.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 { 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";
 // --- 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 }] };
@@ -100,6 +111,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);
@@ -120,9 +134,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;
@@ -132,21 +146,56 @@ 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;
 }
+/**
+ * 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.
+ */
+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;
+}
 /**
  * Parse the PAM binary preset format: <metadataSize as text int><metadata JSON><data JSON>
  */
@@ -207,42 +256,99 @@ async function readExistingVariations(presetPath) {
         return Array(PRESET_VARIATION_SLOTS).fill(null);
     }
 }
-// Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
+const VARIATION_CONTRACT = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "..", "shared", "variationSessionKeys.json"), // repo checkout
+        resolve(here, "variationSessionKeys.json"), // published dist/
+    ];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        const contract = JSON.parse(readFileSync(file, "utf8"));
+        if (Array.isArray(contract.all) && contract.all.length > 0)
+            return contract;
+    }
+    throw new Error("pam-mcp: variationSessionKeys.json not found. Run `node scripts/generate-variation-session-keys.mjs` " +
+        "(repo) or rebuild the package — saving a variation without it would bake session state into the slot.");
+})();
+// `transport` is live host position, reported in state but never variation content.
 const VARIATION_EXCLUDED_PARAMS = [
-    "variations",
-    "interfaceCache",
-    "songMode",
-    "volume",
-    "hqMode",
-    "previewSamplePath",
-    "previewCellId",
-    "transport",
-    "snapshotRateHz",
-    "looperCrossfade",
-    "looperLength",
-    "looperVolume",
-    "looperFilter",
-    "loopers",
-    "looperPlaybackBars",
-    "looperTrack1Level",
-    "looperTrack2Level",
-    "looperTrack3Level",
-    "looperTrack4Level",
-    "looperTrack5Level",
-    "looperTrack6Level",
-    "looperTrack7Level",
-    "looperTrack8Level",
+    ...new Set([...(VARIATION_CONTRACT.all ?? []), "transport"]),
 ];
 /**
- * Build a variation snapshot string from plugin state (matching interop.ts logic).
+ * Build a variation snapshot string from plugin state.
+ *
+ * The exclusion set comes from the generated contract, so this matches what a
+ * UI save strips. It does NOT match a UI save in one respect: interop.ts awaits
+ * `refreshLoadedPluginStateBlobs()` first and stamps each hosted plugin's
+ * identity and bypass from `pluginHostStore` — data that lives in the WebView,
+ * not in the headless bridge's state. `hostedPluginCells` reports the cells
+ * where that difference bites so callers are told rather than silently handed a
+ * lossy slot.
+ *
+ * This path is the FALLBACK. A PAM build carrying the `getSaveSnapshot` action
+ * hands back the native canonical snapshot (hosted-plugin state included) and
+ * never reaches here.
  */
 function buildVariationString(state) {
-    const stateForVariation = { ...state };
-    for (const param of VARIATION_EXCLUDED_PARAMS) {
-        delete stateForVariation[param];
+    return JSON.stringify(buildVariationSnapshotBase(state, {
+        sessionKeys: VARIATION_EXCLUDED_PARAMS,
+        visualParamIds: VARIATION_CONTRACT.visualParamIds ?? [],
+        lfoGeneratorCount: VARIATION_CONTRACT.lfoGeneratorCount ?? 6,
+    }));
+}
+/**
+ * The canonical save-time state — engine state PLUS every live hosted plugin's
+ * identity, bypass and state blob (PluginProcessor::buildCanonicalSaveSnapshot).
+ *
+ * `getState` returns the live map, which carries no hosted-plugin blob, so a
+ * variation built from it silently dropped the hosted patch (A1). Falls back to
+ * `getState` on a PAM build that predates the action, and reports the fallback
+ * 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") {
+            state = snap;
+            canonical = true;
+        }
+        else {
+            state = (await bridge.send("getState"));
+        }
+    }
+    catch {
+        // Older PAM: action not registered. Fall through.
+        state = (await bridge.send("getState"));
     }
-    delete stateForVariation.activePresetPath;
-    return JSON.stringify(stateForVariation);
+    return { state, canonical };
+}
+/** Cells whose hosted plugin this snapshot cannot fully capture. */
+function hostedPluginCells(state) {
+    const cells = new Set();
+    for (const key of Object.keys(state)) {
+        const m = /^cell(\d+)_plugin(?:Fx)?Path$/.exec(key);
+        if (m && state[key])
+            cells.add(Number(m[1]));
+    }
+    return [...cells].sort((a, b) => a - b);
+}
+/** Appended to a save result when the snapshot is known to be lossy. */
+function hostedPluginSaveWarning(state, canonical = false) {
+    // The canonical snapshot stamps hosted-plugin state on the message thread, so
+    // there is nothing to warn about.
+    if (canonical)
+        return "";
+    const cells = hostedPluginCells(state);
+    if (!cells.length)
+        return "";
+    return (`\n\n⚠️  Cell${cells.length > 1 ? "s" : ""} ${cells.join(", ")} host${cells.length > 1 ? "" : "s"} a plugin. ` +
+        "This save captured the plugin's last-known state, not its live one — the bridge cannot refresh a " +
+        "hosted plugin's state blob (that runs in the plugin UI). Re-save from the PAM window to capture " +
+        "current hosted-plugin settings.");
 }
 function formatParam(p) {
     let desc = `${p.paramId}: ${p.displayName}`;
@@ -263,7 +369,9 @@ function formatParam(p) {
     return desc;
 }
 const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
-const CELL_EFFECTS = ["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",
@@ -279,6 +387,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);
@@ -466,54 +578,22 @@ 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 drum synth is a standard feature (PAM ≥ 1.5) — no settings flag needed. " +
-        "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. Start with design_context and get_design_overview; " +
+            "use set_mfx_routing for cables, set_effect_order for each chain, and set_parameters or " +
+            "update_effect_config to shape effects. Use cells 1-4 and save finished work with save_preset. " +
+            "Treat tool annotations as authoritative and use select_instance when several products are running."
+        : "PAM is an eight-cell sampler. Start read and design work with design_context and " +
+            "get_design_overview; filter get_state with section, keys, or cellIds. For samples, call " +
+            "get_default_locations before list_samples and load only returned paths; never guess library paths. " +
+            "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;
@@ -537,6 +617,9 @@ 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,
@@ -550,6 +633,7 @@ const TOOL_ANNOTATIONS = {
     capture_ui: RO, // writes a screenshot file, mutates no plugin state
     get_sample_peaks: RO,
     get_audio_device_setup: RO,
+    get_memory_report: RO,
     get_sample_usage: RO,
     get_model_status: RO,
     list_models: RO,
@@ -637,13 +721,18 @@ 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,
     export_audio: W,
     // Settings / devices
     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
@@ -692,18 +781,116 @@ 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",
+    "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",
+    "stop_cell",
+    "reset_cell",
+    "copy_cell",
+    "start_transport",
+    "stop_transport",
+    "full_stop_transport",
+    "set_bpm",
+    "set_metronome",
+    "configure_transport",
+    "load_preset",
+    "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",
+    "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
+        .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");
+}
+function mfxToolConfig(name, config) {
+    const source = config;
+    const inputEntries = Object.entries(source.inputSchema ?? {}).filter(([key]) => (name !== "update_cell_config" || key === "cellId" || key === "sidechainFrom") &&
+        (name !== "select_instance" || key !== "product"));
+    const inputSchema = source.inputSchema
+        ? Object.fromEntries(inputEntries.map(([key, schema]) => [
+            key,
+            schema.description ? schema.describe(mfxSurfaceText(schema.description)) : schema,
+        ]))
+        : undefined;
+    const description = name === "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."
+        : name === "update_cell_config"
+            ? "Set one MFX cell's sidechain source. A non-null source also enables that cell's compressor."
+            : source.description ? mfxSurfaceText(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) {
@@ -829,7 +1016,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",
@@ -911,8 +1111,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()
@@ -921,13 +1124,74 @@ 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']) on a follow-up call. " +
+            "Omit on the FIRST call — the full vocabulary is the point, and designing from a narrowed " +
+            "subset is what makes presets resemble each other."),
     },
     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";
@@ -951,39 +1215,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", "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",
@@ -993,12 +1349,293 @@ 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.",
+        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. 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.
@@ -1132,6 +1769,8 @@ server.registerTool("get_design_overview", {
     ]);
     const state = isRecord(stateRaw) ? stateRaw : {};
     const transport = isRecord(transportRaw) ? transportRaw : {};
+    // 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))
@@ -1144,6 +1783,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)];
@@ -1162,8 +1844,9 @@ server.registerTool("get_design_overview", {
                 name: stemName(samplePath),
                 path: typeof samplePath === "string" ? samplePath : undefined,
             },
-            synthEngine: state[`${prefix}synthEngine`] ?? 0,
-            enabledEffects: CELL_EFFECTS.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
+            // Both halves: the enum an agent writes back, and the name it reasons about.
+            synthEngine: describeSynthEngine(state[`${prefix}synthEngine`]),
+            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,
                 countEvents(state[`${prefix}${suffix}`]),
@@ -1241,6 +1924,36 @@ server.registerTool("set_parameters", {
         }
         delta.macros = macros;
     }
+    let comboTargetCount = 0;
+    if (IS_MFX_SERVER) {
+        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: {
@@ -1252,7 +1965,8 @@ 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",
@@ -1262,7 +1976,7 @@ server.registerTool("load_sample", {
         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);
@@ -1274,7 +1988,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()
@@ -1351,7 +2065,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"])
@@ -1525,7 +2239,7 @@ server.registerTool("workbench_load_take", {
         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 {
@@ -1582,7 +2296,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) {
@@ -1600,7 +2314,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);
@@ -1653,11 +2367,11 @@ server.registerTool("add_modulation", {
             .boolean()
             .optional()
             .describe("Envelope only: route from the cell's pitch-tracked source instead of amp. " +
-            "false (default) = AMP; true & pitchDuck=false = BOOST; true & pitchDuck=true = DUCK."),
+            "false (default) = AMP; true & pitchDuck=false = PITCH (comb); true & pitchDuck=true = DUCK."),
         pitchDuck: z
             .boolean()
             .optional()
-            .describe("Envelope only: when pitch=true, switch from BOOST to DUCK semantics (notch). Ignored if pitch=false."),
+            .describe("Envelope only: when pitch=true, switch from PITCH (comb) to DUCK semantics (notch). Ignored if pitch=false."),
     },
 }, async ({ type, paramId, cellId, lfoIndex, strength, bipolar, pitch, pitchDuck }) => {
     const index = await getParameterIndex();
@@ -1666,7 +2380,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)
@@ -1705,7 +2419,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
@@ -1790,9 +2504,21 @@ 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 }) => {
+    const check = await requireBridgeForCells(cellIds);
     if (check !== true)
         return check;
     if (target === "synth") {
@@ -1810,7 +2536,7 @@ server.registerTool("randomize", {
         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.)`);
     }
-    await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
+    await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
     return text(`Randomized ${target}${cellIds ? ` for cells ${cellIds.join(", ")}` : ""}.`);
 });
 server.registerTool("randomize_samples", {
@@ -1824,7 +2550,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)
@@ -1839,13 +2565,51 @@ 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. Use it for the DIVERGE " +
+            "step; 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 text(`Randomized samples${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.${diversifyNote}`);
 });
 server.registerTool("randomize_patterns", {
     title: "Randomize Patterns",
@@ -1870,13 +2634,28 @@ 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. Push it to 0.7-1.0 during the " +
+            "DIVERGE step, and keep it low only when the brief genuinely wants 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);
+    await bridge.send("randomize", "sequences", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
     return text(`Randomized patterns${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
 });
 server.registerTool("load_variation", {
@@ -1967,14 +2746,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
@@ -2004,6 +2801,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.
@@ -2103,7 +2903,7 @@ server.registerTool("save_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const state = (await bridge.send("getState"));
+    const { state, canonical } = await fetchSaveSnapshot();
     // Bare save (no name): the UI Save button's semantics — overwrite the
     // ACTIVE user preset in place, preserving its on-disk metadata. Mirrors
     // the in-plugin assistant executor (error strings included — the model's
@@ -2168,7 +2968,8 @@ server.registerTool("save_preset", {
     const result = (await bridge.send("savePreset", metadata));
     lastSavedPresetName = name;
     lastSavedPresetPath = result?.path || readPath;
-    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}`);
+    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}` +
+        hostedPluginSaveWarning(state, canonical));
 });
 server.registerTool("save_variation", {
     title: "Save Variation",
@@ -2201,8 +3002,8 @@ server.registerTool("save_variation", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    // 1. Get current full state and build variation snapshot
-    const state = (await bridge.send("getState"));
+    // 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;
@@ -2267,7 +3068,8 @@ server.registerTool("save_variation", {
     return text(`Saved variation ${index} for "${presetName}"\n` +
         `Path: ${result?.path || "(unknown path)"}\n` +
         `Filled slots: ${variations.filter((v) => v !== null).length}/8` +
-        resultSuffix);
+        resultSuffix +
+        hostedPluginSaveWarning(state, canonical));
 });
 server.registerTool("update_preset_metadata", {
     title: "Update Preset Metadata",
@@ -2362,7 +3164,7 @@ server.registerTool("trim_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("trimSampleForCell", cellId);
@@ -2375,7 +3177,7 @@ server.registerTool("reverse_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("reverseSampleForCell", cellId);
@@ -2400,13 +3202,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.",
         });
     }
@@ -2419,8 +3224,8 @@ 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; the launcher uses the first available instance.`
+                : `Connected to ${SERVER_PRODUCT.name}. All advertised tools are available.`
             : "Found instances but could not connect. The plugin may have shut down.",
     });
 });
@@ -2445,9 +3250,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})`)
@@ -2504,6 +3316,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).
@@ -2896,6 +3771,10 @@ server.registerTool("video_command", {
         "moveLayer{layerId,toIndex}, duplicateLayer{layerId}, renameLayer{layerId,name}, " +
         "setLayerEnabled{layerId,enabled?}, toggleSolo{layerId}, selectLayer{layerId}, " +
         "resetLayer{layerId}, applyLayout{preset}, randomizeLayer{layerId}; " +
+        "setShaderSource{layerId,source} (GLSL fragment for a 'shader' layer; auto-parses " +
+        "'// @param uP_x 0..1 = 0.5 \"Label\"' rows into sliders/bind targets; read " +
+        "layers[].shaderCompile in get_video_state for the compile ok/infoLog and repair), " +
+        "setShaderParam{layerId,paramKey,value}; " +
         "addLayerFx{layerId,fxType,params?,beforeFxId?}, removeLayerFx{layerId,fxId}, " +
         "removeAllLayerFx{layerId}, setLayerFxParam{layerId,fxId,param,value|params}, " +
         "setLayerFxEnabled{layerId,fxId,enabled?}, reorderLayerFx{layerId,fxIds}, " +
@@ -2938,8 +3817,8 @@ server.registerTool("add_video_layer", {
         "update_video_layer and stack FX with add_video_fx.",
     inputSchema: {
         kind: z
-            .enum(["video", "image", "camera", "text", "drawing", "model3d", "adjustment"])
-            .describe("Layer kind."),
+            .enum(["video", "image", "camera", "text", "drawing", "model3d", "shader", "adjustment"])
+            .describe("Layer kind. 'shader' is a user-GLSL fragment layer — write its source with video_command {op:'setShaderSource'}."),
         name: z.string().optional().describe("Display name (auto-generated if omitted)."),
         insertAt: z
             .number()
@@ -3578,7 +4457,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, fdn, gate, compressor). " +
+    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)."),
@@ -3590,6 +4470,29 @@ 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(),
+        // 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.
+        eq8Enabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        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(),
+        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(),
     },
 }, async ({ cellId, ...config }) => {
     const check = await requireBridge();
@@ -3599,10 +4502,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.");
@@ -3613,6 +4526,356 @@ server.registerTool("update_effect_config", {
         .join(", ");
     return text(`Updated effect config for cell ${cellId}: ${summary}`);
 });
+// MFX cable patchbay. `mfx_routing` is a non-numeric state variable, so it was
+// 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
+// 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', '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;
+}
+function validateMfxEdges(edges, maxCells) {
+    const seen = new Set();
+    const out = [];
+    const inRange = (port) => {
+        const c = mfxPortCell(port);
+        return c !== null && c >= 1 && c <= maxCells;
+    };
+    for (const { from, to } of edges) {
+        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" && 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
+        seen.add(key);
+        out.push({ from, to });
+    }
+    return { ok: true, edges: out };
+}
+server.registerTool("set_mfx_routing", {
+    title: "Set MFX Cable Routing",
+    description: "Read or replace the MFX cable patch — the graph that decides which cell feeds which. MFX-only; on PAM/Cell1 " +
+        "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 " +
+        "left alone; a new cable takes the graph's own default (unity forward, 0.5 on a back or self edge). " +
+        "Re-patching rebuilds the audio graph, like reordering FX.",
+    inputSchema: {
+        op: z.enum(["get", "set"]).describe("'get' reads the current cables; 'set' replaces them."),
+        edges: z
+            .array(z.object({
+            from: z.string().describe(`Source port: ${MFX_ROUTING_SOURCE_HINT}`),
+            to: z.string().describe(`Destination port: ${MFX_ROUTING_SINK_HINT}`),
+        }))
+            .optional()
+            .describe("Full cable list for 'set'. An empty array clears the patch (silence)."),
+    },
+    annotations: { destructiveHint: false, idempotentHint: true },
+}, async ({ op, edges }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && !isMfxManifest(manifest)) {
+        return error(`set_mfx_routing is MFX-only. ${manifest.name ?? "This product"} has no cable patchbay — ` +
+            "its cells run in a fixed per-cell chain.");
+    }
+    if (op === "get") {
+        const raw = await bridge.send("getState", "mfx_routing");
+        return json(isRecord(raw) ? raw.mfx_routing ?? raw : raw);
+    }
+    if (!edges)
+        return error("op 'set' requires an `edges` array (pass [] to clear the patch).");
+    const maxCells = manifestMaxCellId(manifest) ?? 4;
+    const validated = validateMfxEdges(edges, maxCells);
+    if (!validated.ok) {
+        return error(`${validated.reason}. This product exposes cells 1..${maxCells}.`);
+    }
+    // mfx_routing is a GRAPH_RENDER state var — a re-patch must rebuild the graph.
+    await applyKv({ mfx_routing: validated.edges }, KV_OPTS_STANDARD);
+    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"]),
+        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",
+        ]),
+        index: z.number().int().min(1).max(3).default(1),
+        value: z.number().min(-100).max(100).optional().describe("Combo value for setValue, or target value 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.");
+        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. " +
@@ -3640,7 +4903,24 @@ server.registerTool("update_cell_config", {
             .max(2)
             .optional()
             .describe("Slice playback length when sliceKeymapMode=1: 0=Boundary (stop at the next slice edge), 1=Sample End (play to end of sample), 2=Note Off (sustain until key release; requires the cell to be in Gate mode)."),
-        scaleName: z.string().optional().describe("Scale name for pitch sequencer quantization (e.g. 'chromatic', 'major', 'minor')."),
+        scaleName: z
+            .enum([
+            "chromatic",
+            "major",
+            "minor",
+            "pentatonicMajor",
+            "pentatonicMinor",
+            "dorian",
+            "mixolydian",
+            "blues",
+            "harmonicMinor",
+            "phrygian",
+            "lydian",
+            "locrian",
+        ])
+            .optional()
+            .describe("Scale name for pitch sequencer / note quantization ('chromatic' = no filter). " +
+            "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."),
@@ -3664,22 +4944,35 @@ server.registerTool("update_cell_config", {
     const cellCheck = validateCellIdForManifest(cellId, manifest);
     if (cellCheck !== true)
         return cellCheck;
-    const cellConfig = {};
-    const flatDelta = {};
-    for (const [key, value] of Object.entries(config)) {
-        if (value !== undefined)
-            cellConfig[key] = value;
-    }
-    if (Object.keys(cellConfig).length === 0) {
+    // These four are DAW params (cell{N}_quantScale, …), not cell-config keys —
+    // nothing consumes them on the cells{} config channel (the sampler reads
+    // the param signal inputs), so a cells{} write was a silent no-op that
+    // also persisted junk keys into the preset. Route them to flat param keys,
+    // which applyKv maps onto the JUCE params (updateParameters: true).
+    const PARAM_ROUTED_KEYS = new Set(["quantScale", "quantRoot", "spread", "chaos"]);
+    const providedKeys = Object.entries(config)
+        .filter(([, value]) => value !== undefined)
+        .map(([key]) => key);
+    if (providedKeys.length === 0) {
         return error("At least one config property must be provided.");
     }
     if (manifest && isMfxManifest(manifest)) {
-        const unsupported = Object.keys(cellConfig).filter((key) => !MFX_CELL_CONFIG_KEYS.has(key));
+        const unsupported = providedKeys.filter((key) => !MFX_CELL_CONFIG_KEYS.has(key));
         if (unsupported.length > 0) {
             return error("update_cell_config in MFX only accepts sidechainFrom. " +
                 `Sampler/MIDI/instrument config keys are PAM/Cell1-only: ${unsupported.join(", ")}.`);
         }
     }
+    const cellConfig = {};
+    const flatDelta = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (value === undefined)
+            continue;
+        if (PARAM_ROUTED_KEYS.has(key))
+            flatDelta[`cell${cellId}_${key}`] = value;
+        else
+            cellConfig[key] = value;
+    }
     // Auto-enable compressor when setting sidechain source
     if (cellConfig.sidechainFrom !== undefined && cellConfig.sidechainFrom !== null) {
         flatDelta[`cell${cellId}_compressorEnabled`] = 1;
@@ -3694,11 +4987,14 @@ server.registerTool("update_cell_config", {
         cellModeChangeSeq[cellId] = next;
         cellConfig.modeChangeSeq = next;
     }
-    const delta = { cells: { [cellId]: cellConfig }, ...flatDelta };
+    const delta = { ...flatDelta };
+    if (Object.keys(cellConfig).length > 0)
+        delta.cells = { [cellId]: cellConfig };
     await applyKv(delta, KV_OPTS_CELL_CONFIG);
-    const summary = Object.entries(cellConfig)
-        .map(([k, v]) => `${k}=${v}`)
-        .join(", ");
+    const summary = [
+        ...Object.entries(cellConfig).map(([k, v]) => `${k}=${v}`),
+        ...Object.entries(flatDelta).map(([k, v]) => `${k}=${v}`),
+    ].join(", ");
     return text(`Updated cell ${cellId} config: ${summary}`);
 });
 server.registerTool("set_cell_mute", {
@@ -3752,7 +5048,8 @@ server.registerTool("set_master_effects", {
         "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). " +
-        "NOTE: the Tape requires a PAM build that ships it (flat state key masterTapeEnabled — master-chain keys are not manifest params). On older builds these keys are ignored.",
+        "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: {
         compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable Punch compressor (0=off, 1=on)."),
         limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master Limiter (0=off, 1=on)."),
@@ -3792,6 +5089,15 @@ server.registerTool("set_master_effects", {
         masterIronDrive: z.number().min(0).max(12).optional().describe("Iron drive dB (default 0). Level-compensated — drive adds colour, not loudness."),
         masterIronAmount: z.number().min(0).max(1).optional().describe("Transformer (magnetizing-branch) depth 0..1 — LF-concentrated saturation, the 'iron' signature (default 0.5)."),
         masterIronMode: z.union([z.literal(0), z.literal(1)]).optional().describe("0=Console (amp-forward, subtle), 1=Transformer (heavier LF iron)."),
+        masterSqueezeEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable Squeeze — a 3-band upward+downward compressor (post-Punch, pre-Tape; zero latency). The character (88/2500 Hz splits, thresholds, ratios) is baked; Depth is the main lever."),
+        masterSqueezeDepth: z.number().min(0).max(1).optional().describe("Squeeze depth 0..1 (default 0.3): scales the applied per-band gain toward the full character — a density control, NOT a dry/wet. 0.15-0.3 densifies a master; 0.6+ is the aggressive pumped sound."),
+        masterSqueezeTime: z.number().min(0.1).max(10).optional().describe("Squeeze time multiplier on all band attack+release (0.1 fast .. 10 slow, default 1)."),
+        masterSqueezeTone: z.number().min(-1).max(1).optional().describe("Squeeze tone: bipolar low<->high band tilt, ±6 dB at the extremes (default 0)."),
+        masterSqueezeInGain: z.number().min(-12).max(12).optional().describe("Squeeze input gain dB (default 0) — drives program into the fixed thresholds (more In = more of everything)."),
+        masterSqueezeOutTrim: z.number().min(-12).max(12).optional().describe("Squeeze output trim dB (default 0)."),
+        masterSqueezeUpAmount: z.number().min(0).max(1.5).optional().describe("Squeeze upward-branch trim 0..1.5 (default 1). 0 disables the upward lift (downward-only multiband)."),
+        masterSqueezeDownAmount: z.number().min(0).max(1.5).optional().describe("Squeeze downward-branch trim 0..1.5 (default 1). 0 disables the downward limiting (pure upward lift)."),
+        masterSqueezeUpCapDb: z.number().min(0).max(24).optional().describe("Squeeze upward max-boost clamp dB (default 12) — bounds how far quiet material (tails, noise floor) is lifted."),
         masterLoudnessAutoReset: z.union([z.literal(0), z.literal(1)]).optional().describe("Loudness meter auto-reset on host transport start (default 1). 0 keeps measurements running across transport stops."),
         masterEqBells: z
             .array(z.object({
@@ -3857,38 +5163,50 @@ server.registerTool("set_master_effects", {
     return text(`Updated master effects: ${summary}`);
 });
 // Built-in per-cell drum synth ("machines"). Engine enum index = drumsynth::Engine
-// (Off = 0). Per-engine param labels + musical defaults mirror DRUM_SYNTH_ENGINES
-// in interface/src/dsp/modules/drumSynth.ts — keep in lockstep (append-only).
-const DRUM_SYNTH_ENGINES = [
-    { name: "Kick", params: [["Tune", 0.25], ["Pitch", 0.5], ["P.Decay", 0.35], ["Decay", 0.5], ["Click", 0.3], ["Drive", 0.35], ["Tone", 0.6]] },
-    { name: "Snare", params: [["Tune", 0.4], ["Snap", 0.45], ["Body", 0.35], ["N.Decay", 0.45], ["N.Tone", 0.5], ["Detune", 0.3], ["Drive", 0.25]] },
-    { name: "HiHat", params: [["Tune", 0.5], ["Decay", 0.3], ["Tone", 0.5], ["Metal", 0.6], ["Noise", 0.2]] },
-    { name: "Clap", params: [["Tune", 0.45], ["Spread", 0.4], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.2]] },
-    { name: "Tom", params: [["Tune", 0.4], ["Pitch", 0.4], ["Decay", 0.45], ["Tone", 0.55], ["Noise", 0.2], ["Drive", 0.2]] },
-    { name: "FM", params: [["Tune", 0.4], ["Ratio", 0.45], ["FM Amt", 0.4], ["Decay", 0.4], ["FM Dcy", 0.4], ["F.Back", 0.1], ["Drive", 0.2]] },
-    { name: "Cymbal", params: [["Tune", 0.5], ["Decay", 0.5], ["Tone", 0.6], ["Metal", 0.7], ["Sizzle", 0.4]] },
-    { name: "Cowbell", params: [["Tune", 0.5], ["Decay", 0.4], ["Ratio", 0.45], ["Tone", 0.5], ["Drive", 0.2]] },
-    { name: "808", params: [["Tune", 0.35], ["Glide", 0.25], ["P.Decay", 0.4], ["Decay", 0.55], ["Saturate", 0.2], ["Click", 0.25], ["Tone", 0.5]] },
-    { name: "Shaker", params: [["Tune", 0.5], ["Color", 0.3], ["Decay", 0.3], ["Attack", 0.4], ["Rattle", 0.0], ["Tone", 0.4]] },
-    { name: "Rim", params: [["Tune", 0.4], ["Ring", 0.5], ["Decay", 0.3], ["Mode", 0.4], ["Snap", 0.6], ["Drive", 0.2]] },
-    { name: "Conga", params: [["Tune", 0.45], ["Slap", 0.4], ["Decay", 0.4], ["Mode", 0.3], ["Tone", 0.55], ["Skin", 0.25], ["Drive", 0.2]] },
-    { name: "Bell", params: [["Tune", 0.5], ["Ratio", 0.4], ["FM Amt", 0.4], ["Decay", 0.5], ["Inharm", 0.3], ["Strike", 0.3], ["Tone", 0.3]] },
-    { name: "Pluck", params: [["Tune", 0.4], ["Sustain", 0.6], ["Damp", 0.5], ["Excite", 0.4], ["Tone", 0.6], ["Drive", 0.15], ["Decay", 0.5]] },
-    { name: "Zap", params: [["Tune", 0.3], ["Sweep", 0.7], ["S.Time", 0.35], ["Decay", 0.4], ["Timbre", 0.3], ["Noise", 0.1], ["Drive", 0.25], ["Tone", 0.6]] },
-    { name: "Wave", params: [["Tune", 0.35], ["Position", 0.2], ["P.Env", 0.4], ["Decay", 0.4], ["Bright", 0.6], ["Morph", 0.0], ["Drive", 0.2]] },
-    { name: "Chaos", params: [["Tune", 0.4], ["Chaos", 0.6], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.3], ["Noise", 0.1]] },
-];
-const DRUM_SYNTH_ENGINE_NAMES = ["Off", ...DRUM_SYNTH_ENGINES.map((e) => e.name)];
+// (Off = 0). The roster, the curated defaults and the engine-switch rule all come
+// from shared/drumSynthEngines.json — the registry build.js codegens the C++ cook
+// and the manifest from, and interface/src/dsp/modules/drumSynth.ts derives its
+// own tables from. The hand-copied table this replaced had drifted on Kick,
+// Cowbell and 808 (issue #999); the switch rule it shipped with carried knob
+// positions where the plugin carries engine units.
+const DRUM_SYNTH_REGISTRY = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "..", "shared", "drumSynthEngines.json"), // repo checkout
+        resolve(here, "drumSynthEngines.json"), // published dist/
+    ];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.engines && Object.keys(parsed.engines).length > 0)
+            return parsed;
+    }
+    throw new Error("pam-mcp: drumSynthEngines.json not found. Rebuild the package (scripts/build-postprocess.mjs " +
+        "vendors it into dist/) — seeding a drum engine without it would write defaults that disagree " +
+        "with the plugin.");
+})();
+const drumSynth = createDrumSynthCatalog(DRUM_SYNTH_REGISTRY);
+const DRUM_SYNTH_ENGINE_NAMES = drumSynth.engineNames;
+/** State carries the bare enum; agents reason about the name. Report both. */
+function describeSynthEngine(raw) {
+    const id = Math.round(Number(raw ?? 0));
+    return { id, name: DRUM_SYNTH_ENGINE_NAMES[id] ?? "Off" };
+}
 server.registerTool("set_drum_synth", {
     title: "Set Drum Synth (built-in machine)",
     description: "Select and shape a cell's built-in drum-synth 'machine' — a real-time synthesized voice that sums into the cell " +
-        "alongside (or instead of) its sample. 18 engines: Off, Kick, Snare, HiHat, Clap, Tom, FM, Cymbal, Cowbell, 808, " +
-        "Shaker, Rim, Conga, Bell, Pluck, Zap, Wave, Chaos. The 808 engine is a tuned long-glide sub that plays as a chromatic " +
+        `alongside (or instead of) its sample. ${DRUM_SYNTH_ENGINE_NAMES.length} engines: ${DRUM_SYNTH_ENGINE_NAMES.join(", ")}. ` +
+        "The 808 engine is a tuned long-glide sub that plays as a chromatic " +
         "bassline (drive it with a pitch lane + pitch-quantize) — ideal for 808 sub-bass, trap, Memphis. Use a cell with NO " +
         "sample for a pure synth voice, or layer over a sample. Each engine reinterprets the 8 generic params (p1..p8); pass " +
-        "only the ones you want to nuance — unspecified params seed to the engine's musical default. Per-engine p-labels: " +
-        DRUM_SYNTH_ENGINES.map((e) => `${e.name}=[${e.params.map((p) => p[0]).join(",")}]`).join("; ") + ". " +
-        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled) — a standard PAM feature, no settings flag. " +
+        "only the ones you want to nuance. First activation seeds every slot from the engine's musical defaults. On a switch " +
+        "between two active engines, only slots you had moved off their default travel, and they carry the engine VALUE " +
+        "(re-mapped through the destination's own range), so Kick Decay 0.41 becomes Stab Decay 0.336 — the same 198 ms. " +
+        "Untouched slots, and slots whose label or unit has no counterpart, take the destination's default. Per-engine p-labels: " +
+        drumSynth.engines.map((e) => `${e.name}=[${e.params.map((p) => p.label).join(",")}]`).join("; ") + ". " +
+        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled). This headless tool is product-gated, " +
+        "not gated by the UI-only drumSynthEnabled preference. " +
         "On products without it, this tool returns a product error instead of writing inert synth keys.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
@@ -3917,14 +5235,11 @@ server.registerTool("set_drum_synth", {
     const engineId = DRUM_SYNTH_ENGINE_NAMES.indexOf(engine);
     if (engineId < 0)
         return error(`Unknown drum synth engine: ${engine}`);
-    const delta = { [`cell${cellId}_synthEngine`]: engineId };
-    if (engineId > 0) {
-        // Seed the engine's musical defaults so the voice sounds good immediately,
-        // then apply explicit p-overrides on top (nuance only what you mean to).
-        const desc = DRUM_SYNTH_ENGINES[engineId - 1];
-        desc.params.forEach(([, def], i) => {
-            delta[`cell${cellId}_synth_p${i + 1}`] = def;
-        });
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const delta = drumSynth.buildEngineSwitchDelta(cellId, engineId, state);
+    const desc = drumSynth.getEngine(engineId);
+    if (desc) {
         for (const [key, value] of Object.entries(overrides)) {
             if (value === undefined)
                 continue;
@@ -3937,7 +5252,7 @@ server.registerTool("set_drum_synth", {
         delta[`cell${cellId}_synthVolume`] = volume;
     // synthEngine is a graph-render key → needs a graph dispatch (KV_OPTS_STANDARD).
     await applyKv(delta, KV_OPTS_STANDARD);
-    const labels = engineId > 0 ? DRUM_SYNTH_ENGINES[engineId - 1].params.map((p) => p[0]).join(",") : "—";
+    const labels = desc ? desc.params.map((p) => p.label).join(",") : "—";
     return text(`Cell ${cellId} drum synth → ${engine}${engineId > 0 ? ` (p1..pN = ${labels})` : ""}.`);
 });
 server.registerTool("set_drum_synth_wave", {
@@ -3996,7 +5311,7 @@ server.registerTool("add_param_seq", {
         speed: z.number().min(0.0625).max(16).default(1).describe("Pattern speed multiplier."),
     },
 }, async ({ paramId, cellId, sequence, strength, bipolar, length, speed }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     const index = await getParameterIndex();
@@ -4082,7 +5397,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);
@@ -4101,7 +5416,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 });
@@ -4170,7 +5485,7 @@ server.registerTool("export_audio", {
             .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".
@@ -4208,7 +5523,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,
@@ -4223,12 +5538,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.`);
@@ -4236,8 +5547,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) => {
@@ -4251,8 +5562,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) => {
@@ -4262,10 +5573,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`,
         })),
     }),
@@ -4280,7 +5591,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",
@@ -4290,16 +5601,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
 
@@ -4482,7 +5815,7 @@ Variations exclude: global volume, looper state.
 
 ## Master Effects — The Final Stage
 
-Signal chain: Cell outputs → Bus Mix → **Punch Compressor** → **Limiter** → Volume Fader → Output
+Signal chain: Cell outputs → Bus Mix → **EQ** → **Punch Compressor** → **Squeeze** (3-band up/down) → **Tape** → **Iron** → **Clipper** → **Limiter** → Volume Fader → Output
 
 ### Punch Compressor (Musical Bus Comp)
 \`\`\`
@@ -4603,7 +5936,8 @@ update_cell_config: cellId=5, scaleName="pentatonicMinor", scaleRoot=0
 \`\`\`
 \`scaleRoot\`: 0=C, 1=C#, 2=D, 3=D#, 4=E, 5=F, 6=F#, 7=G, 8=G#, 9=A, 10=A#, 11=B
 
-Available scales: \`chromatic\` (default/none), \`major\`, \`minor\`, \`pentatonicMajor\`, \`pentatonicMinor\`, \`dorian\`, \`mixolydian\`, \`blues\`, \`harmonicMinor\`, \`phrygian\`
+Available scales: \`chromatic\` (default/none), \`major\`, \`minor\`, \`pentatonicMajor\`, \`pentatonicMinor\`, \`dorian\`, \`mixolydian\`, \`blues\`, \`harmonicMinor\`, \`phrygian\`, \`lydian\`, \`locrian\`
+(The sampler pitch-quantize lane \`cell{N}_quantScale\` is a separate, deliberately frozen 10-scale DAW param — no lydian/locrian there.)
 
 ### Playback Modes
 \`cell{N}_mode\`: 0=Trigger (one-shot), 1=Gate (plays while held, default), 2=Loop (continuous)
@@ -4638,15 +5972,19 @@ 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
 // README and tool descriptions teach, with exact tool names.
 // ============================================================
-const GENRE_SUGGESTIONS = ["boom_bap", "trap", "drill", "house", "techno", "dnb"];
+// 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", "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
@@ -4654,7 +5992,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: [
@@ -4662,65 +6000,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. 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.`));
+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)
 // ============================================================
@@ -4749,7 +6115,7 @@ server.registerTool("arm_looper_track", {
         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 } });
@@ -4833,7 +6199,7 @@ server.registerTool("set_looper_track", {
     if (typeof rest.sourceCell === "number")
         trackDelta.sourceCell = rest.sourceCell;
     if (typeof rest.autoSelect === "boolean")
-        trackDelta.autoSelect = rest.autoSelect ? 1 : 0;
+        trackDelta.autoSelect = rest.autoSelect;
     if (typeof rest.recordedBpm === "number")
         trackDelta.recordedBpm = rest.recordedBpm;
     if (Object.keys(trackDelta).length === 0)
@@ -4849,7 +6215,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({
@@ -4877,7 +6243,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({
@@ -4911,9 +6277,13 @@ 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
+    // mount off loopers[id].armed, so a bridge-only record left the timeline
+    // blank while recording ran fine underneath.
+    await applyLoopersDelta(Object.fromEntries(armedCellIds.map((cellId) => [cellId, { armed: 1 }])));
     const meta = trackMetadata ??
         armedCellIds.map((cellId) => ({
             cellId,
@@ -4981,7 +6351,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);
@@ -5129,7 +6499,9 @@ server.registerTool("looper_variation_sync", {
 server.registerTool("queue_variation", {
     title: "Queue Variation Switch",
     description: "Schedule a global variation switch on the next bar boundary. " +
-        "For an immediate switch, use load_variation instead.",
+        "For an immediate switch, use load_variation instead. Optionally morph " +
+        "into the new section over the bars before the boundary (song mode / an " +
+        "already-engaged queued-flip window only; a from-idle flip hard-switches).",
     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."),
@@ -5138,13 +6510,48 @@ server.registerTool("queue_variation", {
             .boolean()
             .default(true)
             .describe("Reset pattern phase on switch."),
+        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."),
+        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)."),
+        morphCurve: z
+            .enum(["linear", "ease", "exp", "log"])
+            .optional()
+            .describe("Morph easing; default ease."),
+        transition: z
+            .object({
+            patternPolicy: z.enum(["dissolve", "wipe", "cells"]).optional(),
+            mixLaw: z.enum(["equalPower", "equalGain", "correlation"]).optional(),
+            tail: z.enum(["cut", "fade", "ring"]).optional(),
+            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 " +
+            "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)."),
     },
-}, async ({ index, intervalBars, fadeMs, resetPhase }) => {
+}, async ({ index, intervalBars, fadeMs, resetPhase, morphBars, morphMode, morphCurve, transition }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    await bridge.send("queueVariationOnBars", { index, intervalBars, fadeMs, resetPhase });
-    return text(`Queued variation ${index} on next ${intervalBars}-bar boundary.`);
+    await bridge.send("queueVariationOnBars", {
+        index,
+        intervalBars,
+        fadeMs,
+        resetPhase,
+        ...(morphBars !== undefined && { morphBars }),
+        ...(morphMode !== undefined && { morphMode }),
+        ...(morphCurve !== undefined && { morphCurve }),
+        ...(transition !== undefined && { transition }),
+    });
+    const morphNote = morphBars !== undefined ? ` (morph ${morphBars} bars, ${morphMode ?? "param"})` : "";
+    return text(`Queued variation ${index} on next ${intervalBars}-bar boundary${morphNote}.`);
 });
 server.registerTool("cancel_queued_variation", {
     title: "Cancel Queued Variation",
@@ -5298,16 +6705,17 @@ server.registerTool("midi_recording", {
 // ============================================================
 server.registerTool("update_modulation", {
     title: "Update Modulation",
-    description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, or ParamSeq sequence data. " +
+    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
-            .enum(["lfo", "envelope", "vary", "macro", "paramSeq", "paramSeqSequence"])
+            .enum(["lfo", "envelope", "vary", "macro", "paramSeq", "paramSeqSequence", "freeSeqSequence"])
             .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[] }, etc."),
+            .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."),
     },
 }, async ({ type, payload }) => {
     const check = await requireBridge();
@@ -5324,13 +6732,55 @@ server.registerTool("update_modulation", {
                     ? "applyMacroUpdate"
                     : type === "paramSeq"
                         ? "applyParamSeqUpdate"
-                        : "applyParamSeqSequenceUpdate";
+                        : type === "paramSeqSequence"
+                            ? "applyParamSeqSequenceUpdate"
+                            : "applyFreeSeqSequenceUpdate";
     await bridge.send(action, data);
     return text(`Applied ${type} update.`);
 });
 // ============================================================
 // 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(),
+    window: z
+        .object({
+        bars: z.number().min(0).max(8).optional(),
+        paramCurve: morphCurveEnum.optional(),
+        patternCurve: morphCurveEnum.optional(),
+        mixCurve: morphCurveEnum.optional(),
+    })
+        .optional(),
+    pattern: z.object({ policy: z.enum(["dissolve", "wipe", "cells"]).optional() }).optional(),
+    audio: z
+        .object({
+        mixLaw: z.enum(["equalPower", "equalGain", "correlation"]).optional(),
+        tail: z.enum(["cut", "fade", "ring"]).optional(),
+        tailMaxBars: z.number().min(0.25).max(8).optional(),
+    })
+        .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 " +
+    "('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 " +
+    "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).";
 server.registerTool("song_mode", {
     title: "Song Mode",
     description: "Control PAM's song mode (timeline of variation/preset sections). Ops: 'setArrangement', " +
@@ -5342,9 +6792,13 @@ server.registerTool("song_mode", {
         "VX (visual) variation slot via `vxVariationIndex` (omit = visuals follow the section's " +
         "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). 'get' reads the arrangement back (nodes, compiled steps with the " +
-        "VX scene+slot each recalls, total bars); 'assignVx' re-pins one section's VX slot (and " +
-        "optional scene) after authoring.\n\n" +
+        "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). " +
+        "'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); " +
+        "'assignVx' re-pins one section's VX slot (and optional scene) after authoring.\n\n" +
         "'setSequence' is the older HEADLESS raw-step path (works with the window closed): steps " +
         "land in the C++ player but carry no grid nodes, so the UI can't edit them and VX can only " +
         "follow 1:1 by audio slot.",
@@ -5365,13 +6819,28 @@ server.registerTool("song_mode", {
             .describe("Operation."),
         sections: z
             .array(z.object({
-            variationIndex: z.number().min(0).max(7).describe("Audio variation slot 0-7 this section plays."),
+            variationIndex: z.number().min(0).max(7).describe("Audio variation slot 0-7 this section plays. With presetPath set, this selects the variation INSIDE that preset's own bank — the two compose, they are not mutually exclusive."),
             bars: z.number().positive().optional().describe("Section length in bars (default: auto from longest pattern)."),
             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("Load this preset instead of switching variation."),
+            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."),
             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."),
+            morphCurve: z
+                .enum(["linear", "ease", "exp", "log"])
+                .optional()
+                .describe("Morph glide easing; default ease. Ignored without morphBars."),
+            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."),
+            transition: transitionSpecSchema.optional().describe(TRANSITION_SPEC_HONESTY),
             vxVariationIndex: z
                 .number()
                 .int()
@@ -5399,9 +6868,28 @@ server.registerTool("song_mode", {
                 .max(1)
                 .optional()
                 .describe("Branch probability (0-1). Sibling routes normalize to 100%."),
+            morphBars: z
+                .number()
+                .min(0)
+                .max(8)
+                .optional()
+                .describe("Per-cable morph window in bars — overrides the destination section's morphBars for THIS cable only (branching arrangements can give each incoming cable its own window). 0 = hard switch; omit to use the section value / song default."),
+            morphCurve: z
+                .enum(["linear", "ease", "exp", "log"])
+                .optional()
+                .describe("Per-cable morph easing; overrides the destination section's morphCurve."),
+            morphMode: z
+                .enum(["auto", "param", "mix", "seq", "all"])
+                .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),
         }))
             .optional()
-            .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section."),
+            .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section. Each cable may carry its own morphBars/morphCurve/morphMode/transition."),
+        defaultTransition: transitionSpecSchema
+            .nullable()
+            .optional()
+            .describe("For 'setArrangement': song-level advanced transition defaults inherited by cables without their own `transition`; null clears. " + TRANSITION_SPEC_HONESTY),
         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)."),
@@ -5464,6 +6952,7 @@ server.registerTool("song_mode", {
                 op: "setSongArrangement",
                 sections: args.sections,
                 ...(args.connections !== undefined && { connections: args.connections }),
+                ...(args.defaultTransition !== undefined && { defaultTransition: args.defaultTransition }),
                 ...(args.loop !== undefined && { loop: args.loop }),
                 ...(args.enabled !== undefined && { enabled: args.enabled }),
                 ...(args.crossfadeMs !== undefined && { crossfadeMs: args.crossfadeMs }),
@@ -5602,7 +7091,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 --------
@@ -5811,7 +7300,7 @@ server.registerTool("preview_slice", {
         sliceNumber: z.number().min(0).describe("Slice index."),
     },
 }, async ({ cellId, sliceNumber }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("previewSlice", cellId, sliceNumber);
@@ -5850,7 +7339,7 @@ server.registerTool("restore_original_sample", {
         cellId: z.number().min(1).max(8),
     },
 }, async ({ cellId }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("restoreOriginalSample", { cellId });
@@ -5864,7 +7353,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);
@@ -5878,7 +7367,7 @@ server.registerTool("export_slice", {
         sliceIndex: z.number().min(0),
     },
 }, async ({ cellId, sliceIndex }) => {
-    const check = await requireBridge();
+    const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     await bridge.send("exportSliceForCell", { cellId, sliceIndex });
@@ -5923,14 +7412,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,
@@ -5941,10 +7437,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)
@@ -6239,7 +7773,7 @@ server.registerTool("update_settings", {
         "experimental-feature gates from an agent. Common boolean keys: experimentalMode, " +
         "experimentalPluginHost, experimentalMcpBridge. To enable the plugin host, set BOTH " +
         "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true) in one call. " +
-        "The drum synth needs no flag — it is a standard feature on PAM. Other keys " +
+        "Set drumSynthEnabled:false to hide its UI without muting loaded synths. Other keys " +
         "include UI/library preferences — call get_state or inspect the returned object for the current set.",
     inputSchema: {
         settings: z
@@ -6316,6 +7850,40 @@ 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 " +
+        "device, and the call errors there). Use the exact name from get_audio_device_setup's device list. " +
+        "The usual reason to call this headlessly is routing PAM into a loopback device (BlackHole, Soundflower) " +
+        "so a capture run records audio. MIDI devices go through set_midi_io.",
+    inputSchema: {
+        deviceName: z
+            .string()
+            .describe("Output device name exactly as listed by get_audio_device_setup."),
+    },
+}, async ({ deviceName }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("setAudioDevice", [deviceName]);
+    return text(`Audio output device set to '${deviceName}'.`);
+});
 server.registerTool("set_midi_io", {
     title: "Set MIDI I/O Devices",
     description: "Select MIDI input/output devices (standalone). Use get_audio_device_setup to discover device IDs first. " +
@@ -6560,6 +8128,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
@@ -6579,12 +8150,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);
@@ -6600,7 +8172,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) {
@@ -6818,13 +8395,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);
@@ -6835,9 +8454,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