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

package/dist/server.js

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { z } from "zod";
+import { buildVariationSnapshotBase } from "./generated/variationSnapshot.js";
 import { readFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import { inflateSync } from "node:zlib";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, walkPresets, } from "./manifest.js";
+import { createDrumSynthCatalog, } from "./drumSynth.js";
+import { loadManifest, cellEffectNames, 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";
 // --- State ---
 // Variation slot count. Must stay in sync with PRESET_VARIATION_SLOTS in
 // interface/src/stores/Preset.ts. Defined locally because the MCP package
@@ -16,6 +23,8 @@ const PRESET_VARIATION_SLOTS = 8;
 const bridge = new PluginBridge();
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const cellModeChangeSeq = {};
+let lastSavedPresetName;
+let lastSavedPresetPath;
 // --- Helpers ---
 function text(s) {
     return { content: [{ type: "text", text: s }] };
@@ -23,12 +32,78 @@ function text(s) {
 function json(obj) {
     return text(JSON.stringify(obj, null, 2));
 }
+/**
+ * Structured result: the same JSON in the text block (for text-only consumers,
+ * including ask_assistant's internal dispatch) plus structuredContent for
+ * clients that consume the tool's outputSchema. Only use from tools that
+ * declare an outputSchema — the SDK requires structuredContent on success then.
+ */
+function structured(obj) {
+    const record = isRecord(obj) ? obj : { value: obj };
+    return {
+        content: [{ type: "text", text: JSON.stringify(record, null, 2) }],
+        structuredContent: record,
+    };
+}
+/** structured() for bridge results that may arrive as a raw JSON string. */
+function structuredFromBridge(raw) {
+    if (typeof raw === "string") {
+        try {
+            return structured(JSON.parse(raw));
+        }
+        catch {
+            return structured({ value: raw });
+        }
+    }
+    return structured(raw);
+}
 function error(msg) {
     return { content: [{ type: "text", text: msg }], isError: true };
 }
-async function readPackageVersion() {
+function isMfxManifest(manifest) {
+    return (manifest.name?.toLowerCase() === "mfx" ||
+        manifest.bundleId?.toLowerCase() === "map.audio.mfx" ||
+        manifest.pluginCode?.toLowerCase() === "amfx");
+}
+const MFX_CELL_CONFIG_KEYS = new Set(["sidechainFrom"]);
+async function loadManifestForProductGuard() {
     try {
-        const raw = await readFile(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
+        return await loadManifest();
+    }
+    catch {
+        return null;
+    }
+}
+function manifestMaxCellId(manifest) {
+    if (!manifest)
+        return null;
+    const entries = [
+        ...(manifest.parameters ?? []),
+        ...(manifest.stateVariables ?? []),
+        ...(manifest.parameterInfos ?? []),
+    ];
+    const ids = new Set();
+    for (const entry of entries) {
+        const cellMatch = typeof entry.cell === "string" ? /^cell(\d+)$/.exec(entry.cell) : null;
+        const paramMatch = typeof entry.paramId === "string" ? /^cell(\d+)_/.exec(entry.paramId) : null;
+        const raw = cellMatch?.[1] ?? paramMatch?.[1];
+        if (raw)
+            ids.add(Number(raw));
+    }
+    return ids.size > 0 ? Math.max(...ids) : null;
+}
+function validateCellIdForManifest(cellId, manifest) {
+    const maxCellId = manifestMaxCellId(manifest);
+    if (maxCellId !== null && cellId > maxCellId) {
+        const productName = manifest?.name ?? "This product";
+        const noun = maxCellId === 1 ? "cell" : "cells";
+        return error(`${productName} exposes ${maxCellId} ${noun}; cell ${cellId} is not available in this product.`);
+    }
+    return true;
+}
+function readPackageVersion() {
+    try {
+        const raw = readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
         const pkg = JSON.parse(raw);
         return typeof pkg.version === "string" ? pkg.version : "unknown";
     }
@@ -36,14 +111,17 @@ async function readPackageVersion() {
         return "unknown";
     }
 }
+// Single source of truth for the server version: package.json. The MCP handshake,
+// --version, and --help must all report the same number.
+const SERVER_VERSION = readPackageVersion();
 async function handleCliArgs() {
     const args = new Set(process.argv.slice(2));
     if (args.has("--version") || args.has("-v")) {
-        console.log(await readPackageVersion());
+        console.log(SERVER_VERSION);
         return true;
     }
     if (args.has("--help") || args.has("-h")) {
-        const version = await readPackageVersion();
+        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.");
@@ -51,14 +129,24 @@ async function handleCliArgs() {
     }
     return false;
 }
+// Point offline tools (param validation, design_context) at the manifest of
+// the product we're actually connected to.
+function syncProductHint() {
+    setActiveProductHint(bridge.getConnectedInstance()?.product);
+}
 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.");
+            "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).`
+                : ""));
     }
+    syncProductHint();
     return true;
 }
 /**
@@ -121,42 +209,93 @@ 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() {
+    try {
+        const snap = await bridge.send("getSaveSnapshot");
+        if (snap && typeof snap === "object") {
+            return { state: snap, canonical: true };
+        }
+    }
+    catch {
+        // Older PAM: action not registered. Fall through.
+    }
+    const state = (await bridge.send("getState"));
+    return { state, canonical: false };
+}
+/** 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]));
     }
-    delete stateForVariation.activePresetPath;
-    return JSON.stringify(stateForVariation);
+    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}`;
@@ -176,35 +315,490 @@ function formatParam(p) {
         desc += ` — ${p.tooltip}`;
     return desc;
 }
+const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
+// Cell effects are derived per product from the manifest (`cellEffectNames`) —
+// this constant is only the fallback for a manifest that failed to load. The
+// hardcoded eight it used to be is why get_design_overview under-reported:
+// limiter, qverb, eq8, panner, gain, vocoder (and MFX's wavefold/resonator)
+// were enabled in state but absent from `enabledEffects`.
+const CELL_EFFECTS_FALLBACK = [
+    "filter", "delay", "crusher", "flanger", "eq", "fdn", "gate", "compressor",
+];
+const PATTERN_LANES = {
+    note: "midiSequence",
+    pitch: "pitchSequence",
+    slice: "sliceSequence",
+    stretch: "stretchSequence",
+};
+const LFO_DIVISIONS = [
+    "16 bar", "8 bar", "4 bar", "2 bar", "1 bar",
+    "1/2D", "1/2", "1/2T",
+    "1/4D", "1/4", "1/4T",
+    "1/8D", "1/8", "1/8T",
+    "1/16D", "1/16", "1/16T",
+    "1/32D", "1/32", "1/32T",
+    "1/64D", "1/64", "1/64T",
+];
+function levenshtein(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const curr = Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j];
+    }
+    return prev[b.length];
+}
+function similarity(a, b) {
+    if (a === b)
+        return 1;
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - levenshtein(a, b) / maxLen;
+}
+function paramSuffix(paramId) {
+    const m = paramId.match(/^(?:cell\d+|macro|lfo\d+)_?(.*)$/);
+    return m?.[1] || paramId;
+}
+function explicitParamAliases(paramId) {
+    const aliases = new Set();
+    const aliasSuffixes = {
+        delayTime: "delayDelayTime",
+        crusherBits: "crusherBitReduction",
+        crusherBitDepth: "crusherBitReduction",
+        crusherDownsample: "crusherRateReduction",
+        fdnDecay: "fdnFeedback",
+        filterResonance: "filterQ",
+    };
+    const lfo0 = paramId.match(/^lfo0_(.+)$/);
+    if (lfo0)
+        aliases.add(`lfo1_${lfo0[1]}`);
+    const cellMatch = paramId.match(/^(cell\d+_)(.+)$/);
+    const macroMatch = paramId.match(/^(macro_)(.+)$/);
+    const prefix = cellMatch?.[1] ?? macroMatch?.[1] ?? "";
+    const suffix = cellMatch?.[2] ?? macroMatch?.[2] ?? paramId;
+    const replacement = aliasSuffixes[suffix];
+    if (replacement)
+        aliases.add(`${prefix}${replacement}`);
+    return [...aliases];
+}
+function suggestParams(paramId, index, opts = {}) {
+    const explicit = explicitParamAliases(paramId).filter((id) => {
+        const p = index.get(id);
+        return p && (!opts.modulatableOnly || p.isModulatable);
+    });
+    const scored = [...index.values()]
+        .filter((p) => !opts.modulatableOnly || p.isModulatable)
+        .map((p) => {
+        const full = similarity(paramId.toLowerCase(), p.paramId.toLowerCase());
+        const suffix = similarity(paramSuffix(paramId).toLowerCase(), paramSuffix(p.paramId).toLowerCase());
+        const sameCell = paramId.match(/^cell\d+_/)?.[0] === p.paramId.match(/^cell\d+_/)?.[0] ? 0.12 : 0;
+        const sameFamily = paramId.startsWith("macro_") && p.paramId.startsWith("macro_") ? 0.08 :
+            paramId.startsWith("lfo") && p.paramId.startsWith("lfo") ? 0.08 :
+                0;
+        return { id: p.paramId, score: Math.max(full, suffix) + sameCell + sameFamily };
+    })
+        .filter((x) => x.score >= 0.52)
+        .sort((a, b) => b.score - a.score)
+        .map((x) => x.id);
+    return [...new Set([...explicit, ...scored])].slice(0, 5);
+}
+function formatUnknownParamError(paramId, index, opts = {}) {
+    const suggestions = suggestParams(paramId, index, opts);
+    const hint = paramId.startsWith("lfo0_")
+        ? " LFO parameter IDs are 1-based: use lfo1_... through lfo6_..."
+        : "";
+    const scope = opts.modulatableOnly ? " modulatable parameter" : " parameter";
+    return `Unknown${scope}: ${paramId}.${hint}${suggestions.length ? ` Did you mean ${suggestions.join(", ")}?` : ""}`;
+}
+function formatNotModulatableError(paramId, index) {
+    const suggestions = suggestParams(paramId, index, { modulatableOnly: true });
+    return `Parameter '${paramId}' is not modulatable.${suggestions.length ? ` Try modulatable target ${suggestions.join(", ")}.` : ""}`;
+}
+function formatRangeError(param, value) {
+    const unit = param.suffix ? param.suffix : "unitless";
+    const traits = [
+        param.bipolar ? "bipolar" : "unipolar",
+        unit,
+        param.strRepr && param.strRepr.length > 0
+            ? `values: ${param.strRepr.map((v, i) => `${i}=${v}`).join(", ")}`
+            : undefined,
+    ].filter(Boolean);
+    const panHint = param.paramId.endsWith("_pan") && Math.abs(value) > 1 && Math.abs(value) <= 100
+        ? `; ${value / 100} is approximately ${Math.abs(value)}% ${value < 0 ? "left" : "right"}`
+        : "";
+    return `${param.paramId}: ${value} out of range [${param.min}..${param.max}] (${traits.join("; ")}${panHint})`;
+}
+function jsonWithLimit(obj, tooLargeHint) {
+    const serialized = JSON.stringify(obj, null, 2);
+    if (serialized.length > FULL_STATE_RESPONSE_LIMIT_CHARS) {
+        return error(`Result is ${serialized.length.toLocaleString()} characters, above the ${FULL_STATE_RESPONSE_LIMIT_CHARS.toLocaleString()} character safety cap. ` +
+            tooLargeHint);
+    }
+    return text(serialized);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function cellPrefixSet(cellIds) {
+    return new Set((cellIds ?? []).map((id) => `cell${id}_`));
+}
+function paramTargetsCell(value, cells) {
+    if (!isRecord(value))
+        return false;
+    const paramId = typeof value.paramId === "string" ? value.paramId : undefined;
+    if (paramId && [...cells].some((prefix) => paramId.startsWith(prefix)))
+        return true;
+    const cellId = typeof value.cellId === "number" ? value.cellId : undefined;
+    return cellId !== undefined && cells.has(`cell${cellId}_`);
+}
+function filterState(state, opts) {
+    if (!isRecord(state))
+        return state;
+    const keySet = opts.keys?.length ? new Set(opts.keys) : null;
+    const prefixes = cellPrefixSet(opts.cellIds);
+    const filterByCell = prefixes.size > 0;
+    if (!keySet && !filterByCell)
+        return state;
+    const out = {};
+    for (const [key, value] of Object.entries(state)) {
+        if (keySet?.has(key)) {
+            out[key] = value;
+            continue;
+        }
+        if (!filterByCell)
+            continue;
+        if ([...prefixes].some((prefix) => key.startsWith(prefix))) {
+            out[key] = value;
+            continue;
+        }
+        if (key === "cells" && isRecord(value)) {
+            const cells = {};
+            for (const id of opts.cellIds ?? []) {
+                if (value[String(id)] !== undefined)
+                    cells[String(id)] = value[String(id)];
+            }
+            out.cells = cells;
+            continue;
+        }
+        if (["lfos", "envelopes", "vary", "paramSeqs"].includes(key) && Array.isArray(value)) {
+            out[key] = value.filter((entry) => paramTargetsCell(entry, prefixes));
+        }
+    }
+    return out;
+}
+function filterSectionResult(section, result, opts) {
+    const keySet = opts.keys?.length ? new Set(opts.keys) : null;
+    const prefixes = cellPrefixSet(opts.cellIds);
+    if (section === "cells" && isRecord(result) && prefixes.size > 0) {
+        const out = {};
+        for (const id of opts.cellIds ?? []) {
+            if (result[String(id)] !== undefined)
+                out[String(id)] = result[String(id)];
+        }
+        return out;
+    }
+    if (["lfos", "envelopes", "vary", "paramSeqs"].includes(section) && Array.isArray(result) && prefixes.size > 0) {
+        return result.filter((entry) => paramTargetsCell(entry, prefixes));
+    }
+    if (keySet && isRecord(result)) {
+        const out = {};
+        for (const key of keySet) {
+            if (result[key] !== undefined)
+                out[key] = result[key];
+        }
+        return out;
+    }
+    return result;
+}
+function countEvents(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+function stemName(path) {
+    if (typeof path !== "string" || path.length === 0)
+        return undefined;
+    return basename(path);
+}
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.8.0",
+    title: "PAM Audio Sampler",
+    version: SERVER_VERSION,
 }, {
-    instructions: "PAM is an audio sampler plugin. When browsing samples, ALWAYS call get_default_locations " +
+    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. " +
+        "The standard Drum Synth UI follows drumSynthEnabled (default true); this preference does not mute synth audio. " +
+        "set_mfx_routing is the MFX cable patchbay and errors on PAM/Cell1; set_audio_device is standalone-only. " +
         "Tools added in server version 1.7.0 — update_settings, configure_transport, " +
         "get_audio_device_setup, set_midi_io, set_midi_mapping, delete_preset, " +
         "set_preset_factory_status, get_sample_usage, repair_preset_samples, preview_sample, " +
         "set_plugin_params, skip_current_plugin_scan, remove_plugin_from_blocklist — require PAM ≥ 1.7.0. " +
         "VX video tools (get_video_state, video_command, add_video_layer, update_video_layer, " +
         "remove_video_layer, apply_video_layout, add_video_fx, set_video_fx, remove_video_fx, " +
-        "bind_video_param, set_video_settings) require PAM ≥ 1.8.0 AND PAM's window to be OPEN " +
-        "(the video engine renders in the WebView; there is no headless renderer). For " +
+        "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.4.50 / 1.5.0. " +
+        "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).",
-});
+        "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.",
+});
+// --- tool annotation policy ---------------------------------------------------
+// Single audit surface for MCP tool annotations. Every tool MUST have an entry;
+// the registerTool shim below merges it (inline annotations at the call site win
+// per key) and warns on stderr when a tool registers unclassified — and
+// scripts/check-tool-surface.mjs fails the release on a gap. openWorldHint is
+// false server-wide: every tool targets the local plugin instance.
+// Policy: readOnlyHint = no plugin/file mutation. destructiveHint = discards
+// user state that isn't trivially recoverable (delete/clear/reset/overwrite the
+// working state); slot-scoped saves follow the save_variation precedent (false).
+// idempotentHint = repeating the same args reaches the same end state.
+const RO = { readOnlyHint: true };
+const W = { destructiveHint: false }; // additive / one-shot write
+const WI = { destructiveHint: false, idempotentHint: true };
+const D = { destructiveHint: true };
+const DI = { destructiveHint: true, idempotentHint: true };
+const TOOL_ANNOTATIONS = {
+    // Reads (offline + live introspection)
+    get_parameter_info: RO,
+    list_presets: RO,
+    read_preset: RO,
+    get_manifest_summary: RO,
+    design_context: RO,
+    get_state: RO,
+    get_design_overview: RO,
+    get_transport: RO,
+    get_master_analysis: RO,
+    suggest_mix: RO, // pure function over cached analysis + current state
+    connection_status: RO,
+    list_samples: RO,
+    get_default_locations: RO,
+    get_audio_info: RO,
+    get_video_state: RO,
+    capture_ui: RO, // writes a screenshot file, mutates no plugin state
+    get_sample_peaks: RO,
+    get_audio_device_setup: RO,
+    get_sample_usage: RO,
+    get_model_status: RO,
+    list_models: RO,
+    workbench_get_state: RO,
+    workbench_list_takes: RO,
+    workbench_sidecar_status: RO,
+    list_visuals: RO,
+    get_visual_data_url: RO,
+    list_plugins: RO,
+    get_plugin_scan_status: RO,
+    list_loaded_plugins: RO,
+    get_mix_analysis: W, // refresh:true runs an offline analysis render
+    // Parameter / cell / modulation writes
+    set_parameters: WI,
+    load_sample: WI,
+    update_pattern: WI,
+    add_modulation: W,
+    update_modulation: WI,
+    clear_modulations: DI,
+    reset_patterns: DI,
+    update_effect_config: WI,
+    update_cell_config: WI,
+    set_cell_mute: WI,
+    set_master_effects: WI,
+    add_param_seq: W,
+    update_param_seq: WI,
+    remove_param_seq: DI,
+    set_drum_synth: WI,
+    set_drum_synth_wave: WI,
+    stop_cell: WI,
+    reset_cell: DI,
+    copy_cell: DI, // overwrites the destination cell
+    randomize: W,
+    randomize_samples: W,
+    randomize_patterns: W,
+    // Transport / MIDI
+    start_transport: WI,
+    stop_transport: WI,
+    full_stop_transport: WI,
+    set_bpm: WI,
+    set_metronome: WI,
+    configure_transport: WI,
+    trigger_midi: W,
+    trigger_midi_cc: W,
+    trigger_midi_program_change: W,
+    midi_recording: W,
+    // Presets / variations
+    load_preset: DI, // replaces the working state (unsaved edits are lost)
+    save_preset: WI,
+    new_preset: DI,
+    import_preset: WI,
+    export_preset: W,
+    update_preset_metadata: WI,
+    delete_preset: DI,
+    set_preset_factory_status: WI,
+    repair_preset_samples: WI,
+    load_variation: WI,
+    save_variation: WI,
+    queue_variation: WI,
+    cancel_queued_variation: WI,
+    update_variations: WI,
+    variation_hold: WI,
+    // Sample ops
+    preview_sample: WI, // audible only, no state change
+    preview_slice: WI,
+    trim_sample: W, // restore_original_sample recovers the pre-edit file
+    reverse_sample: W,
+    gain_sample: W,
+    normalize_sample: WI,
+    analyze_sample_tempo: WI, // dispatches results into state
+    resample_sample_to_bpm: WI,
+    restore_original_sample: DI, // discards all working edits on the sample
+    build_sample_chain: W,
+    export_slice: W,
+    // Looper
+    arm_looper_track: WI,
+    set_looper_track: WI,
+    clear_looper_track: DI, // looper state is global, not per-preset
+    set_looper_track_selection: WI,
+    start_looper_recording: W,
+    stop_looper_recording: WI,
+    capture_looper_now: W,
+    load_audio_to_looper_track: WI,
+    request_looper_warp: WI,
+    looper_settings: WI,
+    looper_variation: W,
+    looper_variation_sync: WI,
+    live_resample: W,
+    // 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_midi_io: WI,
+    set_midi_mapping: WI,
+    // Plugin host
+    scan_plugins: WI,
+    cancel_plugin_scan: WI,
+    skip_current_plugin_scan: W, // blocklists the currently scanning plugin
+    remove_plugin_from_blocklist: WI,
+    load_plugin: WI,
+    unload_plugin: DI, // discards the hosted plugin's state
+    set_plugin_param: WI,
+    set_plugin_params: WI,
+    set_plugin_bypass: WI,
+    // AI models / generation
+    download_model: WI,
+    load_model: WI,
+    unload_model: WI,
+    delete_model: DI,
+    generate_sample: W,
+    generate_kit: W,
+    // Workbench
+    workbench_set_state: WI,
+    workbench_render: W,
+    workbench_load_take: WI,
+    workbench_undo: W,
+    workbench_reset_chain: DI,
+    // Visuals / VX video
+    set_visual: WI,
+    delete_visual: DI,
+    import_visual_folder: WI,
+    video_command: D, // generic escape hatch — includes resetWorkspace
+    add_video_layer: W,
+    update_video_layer: WI,
+    set_video_layer_source: WI,
+    remove_video_layer: DI,
+    apply_video_layout: WI,
+    add_video_fx: W,
+    set_video_fx: WI,
+    remove_video_fx: DI,
+    bind_video_param: WI,
+    set_video_settings: WI,
+    vx_variation: W,
+    // Connection management
+    select_instance: WI,
+    // Dev-tree-only tools
+    set_view: WI,
+    ask_assistant: D, // executes arbitrary model-chosen tool calls
+};
+const internalTools = new Map();
+{
+    const origRegisterTool = server.registerTool.bind(server);
+    server.registerTool = ((name, config, handler) => {
+        internalTools.set(name, { shape: config.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;
+        if (!TOOL_ANNOTATIONS[name]) {
+            console.error(`[pam-mcp] 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);
+    });
+}
+async function callInternalTool(name, args) {
+    const tool = internalTools.get(name);
+    if (!tool)
+        return { text: `Unknown tool: ${name}.`, isError: true };
+    // Direct handler calls skip the SDK's zod layer — parse here so schema
+    // defaults apply and unknown keys strip, exactly like a real MCP call
+    // (list_samples without offset/limit would otherwise slice(undefined, NaN)
+    // to an empty page).
+    let parsed = args;
+    if (tool.shape) {
+        tool.parser ??= z.object(tool.shape);
+        const r = tool.parser.safeParse(args);
+        if (!r.success) {
+            const issues = r.error.issues.map((i) => `${i.path.join(".") || "(args)"}: ${i.message}`).join("; ");
+            return { text: `Invalid arguments for ${name} — ${issues}`, isError: true };
+        }
+        parsed = r.data;
+    }
+    try {
+        const result = await tool.handler(parsed);
+        const out = (result.content ?? [])
+            .filter((c) => c.type === "text")
+            .map((c) => c.text ?? "")
+            .join("\n");
+        return { text: out, isError: Boolean(result.isError) };
+    }
+    catch (e) {
+        return { text: `Tool error: ${e.message}`, isError: true };
+    }
+}
 // ============================================================
 // TOOLS — Offline (work without plugin running)
 // ============================================================
@@ -241,7 +835,7 @@ server.registerTool("get_parameter_info", {
     if (paramId) {
         const p = index.get(paramId);
         if (!p)
-            return error(`Unknown parameter: ${paramId}`);
+            return error(formatUnknownParamError(paramId, index));
         return json(p);
     }
     let params;
@@ -269,8 +863,10 @@ server.registerTool("get_parameter_info", {
     if (params.length === 0)
         return text("No parameters found matching criteria.");
     if (params.length > 50) {
-        return text(`${params.length} parameters found. Showing summary:\n\n` +
-            params.map(formatParam).join("\n"));
+        const shown = params.slice(0, 80);
+        return text(`${params.length} parameters found. Showing first ${shown.length}. ` +
+            "Use paramId, cell, effect, search, type, or design_context to narrow the response.\n\n" +
+            shown.map(formatParam).join("\n"));
     }
     return json(params);
 });
@@ -347,6 +943,16 @@ server.registerTool("get_manifest_summary", {
     description: "Get a high-level summary of PAM's capabilities: number of cells, effects, " +
         "modulators, and parameter counts.",
     inputSchema: {},
+    outputSchema: {
+        product: z.string().optional(),
+        company: z.string().optional(),
+        totalParameters: z.number().optional(),
+        cells: z.array(z.string()).optional(),
+        effects: z.array(z.string()).optional(),
+        globalParameters: z.number().optional(),
+        modulatableParameters: z.number().optional(),
+        pluginParameters: z.number().optional(),
+    },
     annotations: { readOnlyHint: true },
 }, async () => {
     const manifest = await loadManifest();
@@ -355,7 +961,7 @@ server.registerTool("get_manifest_summary", {
     const effects = new Set(params.filter((p) => p.effect).map((p) => p.effect));
     const global = params.filter((p) => !p.cell);
     const modulatable = params.filter((p) => p.isModulatable);
-    return json({
+    return structured({
         product: manifest.name,
         company: manifest.company,
         totalParameters: params.length,
@@ -366,6 +972,98 @@ server.registerTool("get_manifest_summary", {
         pluginParameters: params.filter((p) => p.isPluginParameter).length,
     });
 });
+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.",
+    inputSchema: {
+        cellId: z
+            .number()
+            .int()
+            .min(1)
+            .max(8)
+            .default(1)
+            .describe("Cell number to use for per-cell example param IDs. Defaults to cell 1."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ cellId }) => {
+    const manifest = await loadManifest();
+    const params = manifest.parameters;
+    const byId = new Map(params.map((p) => [p.paramId, p]));
+    const example = (suffix) => byId.get(`cell${cellId}_${suffix}`)?.paramId ?? `cell${cellId}_${suffix}`;
+    const macroTargetsByEffect = {};
+    for (const p of params.filter((param) => param.paramId.startsWith("macro_") && param.isModulatable)) {
+        const key = p.effect ?? "global";
+        if (!macroTargetsByEffect[key])
+            macroTargetsByEffect[key] = [];
+        macroTargetsByEffect[key].push(p.paramId);
+    }
+    for (const key of Object.keys(macroTargetsByEffect)) {
+        macroTargetsByEffect[key] = macroTargetsByEffect[key].sort();
+    }
+    const filterType = byId.get(example("filterType"));
+    const lfoQuick = [
+        ["16 bar", 0, 0.000],
+        ["4 bar", 2, 0.091],
+        ["2 bar", 3, 0.136],
+        ["1 bar", 4, 0.182],
+        ["1/2", 6, 0.273],
+        ["1/4", 9, 0.409],
+        ["1/8", 12, 0.545],
+        ["1/16", 15, 0.682],
+        ["1/32", 18, 0.818],
+        ["1/64", 21, 0.955],
+    ].map(([division, index, value]) => ({ division, index, lfoRate: value }));
+    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")],
+        },
+        unitNotes: {
+            pan: "cellN_pan is -1..1, so -0.15 is about 15% left; use cellN_pannerBalance for -100..100%.",
+            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.",
+            lfoRate: "LFO IDs are 1-based: lfo1_... through lfo6_.... Sync ON uses index/22.",
+        },
+        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",
+        },
+        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"],
+        },
+        delaySyncDivisions: [
+            "1/32T", "1/32", "1/32D", "1/16T", "1/16", "1/16D",
+            "1/8T", "1/8", "1/8D", "1/4T", "1/4", "1/4D",
+            "1/2T", "1/2", "1/2D", "1",
+        ],
+        filterTypes: filterType?.strRepr?.map((label, index) => `${index}=${label}`) ?? [
+            "0=Lowpass", "1=Highpass", "2=Bandpass", "3=Peak", "4=Notch",
+        ],
+        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.",
+    });
+});
 // Standard full update — graph dispatch + KV sync + parameter updates.
 const KV_OPTS_STANDARD = {
     shouldDispatch: true,
@@ -394,6 +1092,20 @@ const KV_OPTS_PATTERN = {
     updateParameters: false,
     broadcastFollowers: false,
 };
+// Master-chain config — KV + config-resource sync, NO graph dispatch. Every
+// master key (comp incl. the full promoted Punch surface, tape, iron, clipper,
+// limiter, EQ/width) is live-polled from master_config by its native node, so
+// a rebuild here is pure dropout risk (the plan's no-rebuild contract).
+// Mirrors interop.ts updateMasterConfig's options.
+const KV_OPTS_MASTER_CONFIG = {
+    shouldDispatch: false,
+    syncKVResources: true,
+    syncConfigResources: true,
+    skipFileLoadingIfUnchanged: true,
+    resyncKVAfterDispatch: false,
+    updateParameters: true,
+    broadcastFollowers: false,
+};
 // Effect config toggle — lighter KV path, no graph dispatch.
 const KV_OPTS_EFFECT_CONFIG = {
     shouldDispatch: false,
@@ -423,30 +1135,136 @@ async function applyKv(delta, options, directNodeOps) {
 }
 server.registerTool("get_state", {
     title: "Get Plugin State",
-    description: "Read the current full state of the running PAM plugin. " +
-        "Returns all parameter values, cell configs, modulation, and sequences.",
+    description: "Read the current state of the running PAM plugin. Prefer section, keys, cellIds, or get_design_overview " +
+        "over an unfiltered full-state read; large full-state payloads are capped to protect agent context.",
     inputSchema: {
         section: z
             .enum(["full", "cells", "lfos", "macros", "envelopes", "vary", "paramSeqs", "loopers", "songMode"])
             .optional()
             .describe("Return only a specific section of state. Defaults to 'full'. Use get_transport for transport data."),
+        keys: z
+            .array(z.string())
+            .optional()
+            .describe("Exact top-level state keys to return, e.g. ['cell1_filterCutoff','cell1_midiSequence']."),
+        cellIds: z
+            .array(z.number().int().min(1).max(8))
+            .optional()
+            .describe("Return only cell-scoped keys/config/modulation for these cells."),
+        allowLarge: z
+            .boolean()
+            .optional()
+            .describe("Set true to force an uncapped full-state response. Prefer filters unless you truly need everything."),
     },
     annotations: { readOnlyHint: true },
-}, async ({ section }) => {
+}, async ({ section, keys, cellIds, allowLarge }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const hasFilters = (keys?.length ?? 0) > 0 || (cellIds?.length ?? 0) > 0;
     if (section && section !== "full") {
         const result = await bridge.send("getState", section);
-        return json(result ?? `Section '${section}' not found in state.`);
+        const filtered = filterSectionResult(section, result, { keys, cellIds });
+        return jsonWithLimit(filtered ?? `Section '${section}' not found in state.`, "Use a narrower section, keys, or cellIds filter.");
     }
     const state = await bridge.send("getState");
-    return json(state);
+    const filtered = filterState(state, { keys, cellIds });
+    if (!hasFilters && !allowLarge) {
+        return jsonWithLimit(filtered, "Use get_design_overview for preset work, or get_state with section, keys, or cellIds. Pass allowLarge:true only for offline debugging.");
+    }
+    return json(filtered);
+});
+server.registerTool("get_design_overview", {
+    title: "Get Design Overview",
+    description: "Return a compact preset-design snapshot: cells, loaded samples/synth engines, enabled effects, pattern counts, " +
+        "modulation link counts, mixer values, BPM, and master FX. Use this instead of full get_state during preset design.",
+    inputSchema: {
+        cellIds: z
+            .array(z.number().int().min(1).max(8))
+            .optional()
+            .describe("Optional subset of cells to include. Defaults to all cells present in the selected manifest."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ cellIds }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const [stateRaw, transportRaw, manifest] = await Promise.all([
+        bridge.send("getState"),
+        bridge.send("getTransport").catch(() => undefined),
+        loadManifest(),
+    ]);
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const transport = isRecord(transportRaw) ? transportRaw : {};
+    // Product-aware: MFX carries wavefold/resonator, PAM/Cell1 do not.
+    const derivedEffects = cellEffectNames(manifest);
+    const effectNames = derivedEffects.length ? derivedEffects : CELL_EFFECTS_FALLBACK;
+    const manifestCellIds = [...new Set(manifest.parameters
+            .map((p) => p.cell)
+            .filter((cell) => typeof cell === "string" && /^cell\d+$/.test(cell))
+            .map((cell) => Number(cell.replace("cell", ""))))].sort((a, b) => a - b);
+    const ids = cellIds?.length ? cellIds : manifestCellIds;
+    const cellsObj = isRecord(state.cells) ? state.cells : {};
+    const modArrays = {
+        lfo: Array.isArray(state.lfos) ? state.lfos : [],
+        envelope: Array.isArray(state.envelopes) ? state.envelopes : [],
+        vary: Array.isArray(state.vary) ? state.vary : [],
+        paramSeq: Array.isArray(state.paramSeqs) ? state.paramSeqs : [],
+    };
+    const cells = ids.map((id) => {
+        const prefix = `cell${id}_`;
+        const rawCellState = cellsObj[String(id)];
+        const cellState = isRecord(rawCellState) ? rawCellState : {};
+        const samplePath = cellState.filePath ??
+            cellState.samplePath ??
+            state[`${prefix}filePath`] ??
+            state[`${prefix}samplePath`];
+        const modulation = Object.fromEntries(Object.entries(modArrays).map(([kind, arr]) => [
+            kind,
+            arr.filter((entry) => paramTargetsCell(entry, new Set([prefix]))).length,
+        ]));
+        return {
+            cellId: id,
+            sample: {
+                name: stemName(samplePath),
+                path: typeof samplePath === "string" ? samplePath : undefined,
+            },
+            // Both halves: the enum an agent writes back, and the name it reasons about.
+            synthEngine: describeSynthEngine(state[`${prefix}synthEngine`]),
+            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}`]),
+            ])),
+            modulation,
+            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,
+        masterFx: {
+            compressorEnabled: state.masterCompressorEnabled,
+            limiterEnabled: state.masterLimiterEnabled,
+            tapeEnabled: state.masterTapeEnabled,
+        },
+        totals: {
+            cellsWithSamples: cells.filter((c) => c.sample.path).length,
+            activePatternEvents: cells.reduce((sum, c) => sum + Object.values(c.patternEvents).reduce((a, b) => a + b, 0), 0),
+            modulationLinks: cells.reduce((sum, c) => sum + Object.values(c.modulation).reduce((a, b) => a + b, 0), 0),
+        },
+        cells,
+    });
 });
 server.registerTool("set_parameters", {
     title: "Set Parameters",
     description: "Set one or more PAM parameters. Values are validated against the manifest. " +
-        "Use get_parameter_info first to discover valid parameter IDs and ranges.",
+        "Effect enable flags such as cell1_filterEnabled are settable here too, so params + enables can land in one call " +
+        "when a graph dispatch is acceptable. Use get_parameter_info or design_context to discover valid IDs and ranges.",
     inputSchema: {
         parameters: z
             .record(z.string(), z.number())
@@ -460,11 +1278,11 @@ server.registerTool("set_parameters", {
     for (const [paramId, value] of Object.entries(parameters)) {
         const p = index.get(paramId);
         if (!p) {
-            errors.push(`Unknown parameter: ${paramId}`);
+            errors.push(formatUnknownParamError(paramId, index));
             continue;
         }
         if (value < p.min || value > p.max) {
-            errors.push(`${paramId}: ${value} out of range [${p.min}..${p.max}]`);
+            errors.push(formatRangeError(p, value));
         }
     }
     if (errors.length > 0)
@@ -542,11 +1360,21 @@ server.registerTool("get_model_status", {
     title: "Get AI Model Status",
     description: "Report downloaded / loaded / loading / download-in-flight + version + disk size + live download progress for an AI engine.",
     inputSchema: { engine: MODEL_ENGINE },
+    outputSchema: {
+        engine: z.string().optional(),
+        enabled: z.boolean().optional(),
+        downloaded: z.boolean().optional(),
+        loaded: z.boolean().optional(),
+        inFlight: z.boolean().optional(),
+        version: z.string().optional(),
+        state: z.string().optional(),
+        progress: z.number().optional(),
+    },
 }, async ({ engine }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    return json(await bridge.send("modelStatus", { engine }));
+    return structuredFromBridge(await bridge.send("modelStatus", { engine }));
 });
 server.registerTool("load_model", {
     title: "Load AI Model",
@@ -798,11 +1626,15 @@ server.registerTool("workbench_sidecar_status", {
     title: "Workbench: Sidecar Status",
     description: "Ping the SA3 render sidecar (127.0.0.1:8093). Returns { connected, loaded } — loaded means a pipeline is resident (first render after a cold start also pays the model load).",
     inputSchema: {},
+    outputSchema: {
+        connected: z.boolean().optional(),
+        loaded: z.boolean().optional(),
+    },
 }, async () => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    return json(await bridge.send("workbenchSidecarStatus"));
+    return structuredFromBridge(await bridge.send("workbenchSidecarStatus"));
 });
 server.registerTool("trigger_midi", {
     title: "Trigger MIDI",
@@ -867,13 +1699,13 @@ server.registerTool("add_modulation", {
             .min(1)
             .max(8)
             .optional()
-            .describe("Cell ID for envelope/vary sources (1-8)."),
+            .describe("Required for envelope/vary: source cell driving the follower (1-8). This is not the target cell; target is inferred from paramId."),
         lfoIndex: z
             .number()
             .min(0)
             .max(5)
             .optional()
-            .describe("LFO generator index (0-5). Required for LFO type."),
+            .describe("Required for LFO: generator index 0-5. Parameter IDs remain 1-based (lfo1_... through lfo6_...)."),
         strength: z
             .number()
             .min(0)
@@ -888,19 +1720,19 @@ 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();
     const param = index.get(paramId);
     if (!param)
-        return error(`Unknown parameter: ${paramId}`);
+        return error(formatUnknownParamError(paramId, index, { modulatableOnly: true }));
     if (!param.isModulatable)
-        return error(`Parameter '${paramId}' is not modulatable.`);
+        return error(formatNotModulatableError(paramId, index));
     const check = await requireBridge();
     if (check !== true)
         return check;
@@ -916,12 +1748,12 @@ server.registerTool("add_modulation", {
     }
     else if (type === "envelope") {
         if (!cellId)
-            return error("cellId is required for envelope modulation.");
+            return error("cellId is required for envelope modulation. It is the source cell driving the follower; the target cell is inferred from paramId.");
         await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams, pitch ?? false, pitchDuck ?? false);
     }
     else if (type === "vary") {
         if (!cellId)
-            return error("cellId is required for vary modulation.");
+            return error("cellId is required for vary modulation. It is the source cell driving the follower; the target cell is inferred from paramId.");
         await bridge.send("addVary", paramId, cellId, strength, bipolar, effectEnableParams);
     }
     return text(`Added ${type} modulation to ${paramId} (strength: ${strength}%).`);
@@ -994,12 +1826,17 @@ server.registerTool("update_pattern", {
 });
 server.registerTool("randomize", {
     title: "Randomize",
-    description: "Trigger PAM's randomization engine to generate random sounds and patterns.",
+    description: "Trigger PAM's randomization engine to generate random sounds and patterns. " +
+        "target:'synth' runs the musical, engine-aware drum-synth randomizer (picks an engine + " +
+        "shapes its params per cell) — it is routed through the WebView, so it requires PAM's window " +
+        "to be OPEN (samples/sequences/full run natively and do not). target:'synth' needs PAM ≥ 1.13.0.",
     inputSchema: {
+        // 'lfos'/'mods' added for the assistant surface (1.15.0) — WebView-routed
+        // like 'synth'. The describe() text is pinned (exported toolpack bytes).
         target: z
-            .enum(["full", "samples", "sequences"])
+            .enum(["full", "samples", "sequences", "synth", "lfos", "mods"])
             .default("full")
-            .describe("What to randomize."),
+            .describe("What to randomize. 'synth' = the built-in drum-synth machines (PAM window must be open)."),
         cellIds: z
             .array(z.number().min(1).max(8))
             .optional()
@@ -1025,6 +1862,21 @@ server.registerTool("randomize", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    if (target === "synth") {
+        // Routed to the canonical WebView randomizer (single source of truth) — needs the
+        // window open. Empty array → all non-excluded cells.
+        await bridge.send("randomizeDrumSynth", cellIds ?? []);
+        return text(`Randomized drum synths${cellIds ? ` for cells ${cellIds.join(", ")}` : " (all cells)"}. ` +
+            `(Drum-synth randomize runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+    }
+    if (target === "lfos" || target === "mods") {
+        // The data-driven modulation randomizer lives in WebView JS
+        // (interop.ts randomizeLfos/randomizeEnvelopes/randomizeVary) — routed
+        // like 'synth'. Needs PAM ≥ 1.15.0 and the window open.
+        await bridge.send("randomizeModulations", target, mutationAmount ?? -1);
+        return text(`Randomized ${target === "lfos" ? "LFO modulation links" : "all modulation (LFOs, envelopes, vary)"}. ` +
+            `(Runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+    }
     await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1);
     return text(`Randomized ${target}${cellIds ? ` for cells ${cellIds.join(", ")}` : ""}.`);
 });
@@ -1039,7 +1891,7 @@ server.registerTool("randomize_samples", {
         genreHint: z
             .string()
             .optional()
-            .describe("Genre hint to guide sample selection. Supported: techno, house, trap, boom_bap, drill, dnb, hip-hop, ambient, industrial, breaks."),
+            .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."),
         bpmHint: z
             .number()
             .min(20)
@@ -1127,13 +1979,148 @@ server.registerTool("get_transport", {
     title: "Get Transport",
     description: "Get current transport state (BPM, playing, position).",
     inputSchema: {},
+    outputSchema: {
+        bpm: z.number().optional(),
+        isPlaying: z.boolean().optional(),
+        ppqPosition: z.number().optional(),
+    },
     annotations: { readOnlyHint: true },
 }, async () => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const transport = await bridge.send("getTransport");
-    return json(transport);
+    return structuredFromBridge(transport);
+});
+server.registerTool("get_master_analysis", {
+    title: "Get Master Analysis",
+    description: "Read the master-bus loudness measurement (BS.1770-5 / EBU R128): momentary/short-term/integrated " +
+        "LUFS (m/s/i), rolling 30 s ungated loudness (roll), loudness range (lra, stable after 60 s — " +
+        "check lraStable), true peak dBTP (tp; tp3s = 3 s window), sample peak (sp), PSR/PLR crest " +
+        "metrics, stereo correlation (corr; corrLow = <120 Hz band), elapsed ms since reset, and ageMs " +
+        "(snapshot staleness). Absent field = no reading yet. Works headless (window can be closed); " +
+        "audio must be flowing — start the transport or play something first. Guard rails for " +
+        "mastering moves: keep tp <= -1 dBTP and PSR >= 8 in the loudest section.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const analysis = await bridge.send("getMasterAnalysis");
+    return json(analysis);
+});
+server.registerTool("get_mix_analysis", {
+    title: "Get Per-Cell Mix Analysis",
+    description: "Per-cell stem measurements from a faster-than-realtime offline bounce: LUFS (i/s/roll), LRA, " +
+        "true/sample peak (tp/sp), PSR/PLR crest, stereo correlation, onset density, and a 25-band Bark " +
+        "spectrum per cell, plus the full-mix master block. Pass refresh:true to run a new analysis " +
+        "(renders each sounding cell soloed from bar 0 — takes a few seconds; audio does NOT need to be " +
+        "playing). Cached result otherwise. Requires PAM ≥ 1.17.0. PAM only.",
+    inputSchema: {
+        refresh: z.boolean().optional().describe("Run a fresh analysis instead of returning the cached one."),
+        durationSeconds: z.number().min(5).max(30).optional().describe("Analysis render length (default 8 bars at the current BPM, clamped 5-30 s)."),
+        cellIds: z.array(z.number().int().min(1).max(8)).optional().describe("Cells to analyze (default: every cell with a sample or active drum synth)."),
+    },
+}, async ({ refresh, durationSeconds, cellIds }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (refresh) {
+        const started = (await bridge.send("analyzeMix", { durationSeconds, cellIds }));
+        if (started.status !== "started")
+            return error("Mix analysis is busy — an offline render already owns the engine. Retry when it finishes.");
+        const t0 = Date.now();
+        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);
+        }
+        return error("Mix analysis timed out after 120 s.");
+    }
+    const result = await bridge.send("getMixAnalysis");
+    return json(result);
+});
+// 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
+// suggest, which the refresh-first workflow tolerates.
+let lastAppliedMixEpoch = -1;
+server.registerTool("suggest_mix", {
+    title: "Suggest Mix Balance Moves",
+    description: "Runs the Mix Assist rule engine over the latest per-cell analysis (get_mix_analysis): " +
+        "partial-loudness fader balance, pan spread, bounded masking EQ cuts, and optional compressor " +
+        "settings. Returns absolute moves with per-move rationale and guard notes; apply:true lands them " +
+        "as one state update. Run get_mix_analysis with refresh:true first if the mix changed. " +
+        "Requires PAM ≥ 1.17.0. PAM only.",
+    inputSchema: {
+        scopes: z
+            .array(z.enum(["balance", "pan", "eq", "dynamics"]))
+            .optional()
+            .describe("Stages to run (default balance+pan+eq; dynamics is opt-in)."),
+        apply: z.boolean().optional().describe("Apply the suggested moves to the running plugin."),
+    },
+}, async ({ scopes, apply }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const r = (await bridge.send("getMixAnalysis"));
+    if (!r?.available)
+        return error("No mix analysis available — run get_mix_analysis with refresh:true first.");
+    const analysis = parseMixAnalysisPayload(r.analysis);
+    if (!analysis)
+        return error("Cached mix analysis is malformed — re-run get_mix_analysis with refresh:true.");
+    // 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.
+    if (!analysis.live && analysis.epoch === lastAppliedMixEpoch)
+        return error("This analysis was already applied — re-run get_mix_analysis with refresh:true to measure the new balance first.");
+    const state = (await bridge.send("getState"));
+    // Guard-rail parity with the in-app panel (context.ts contract): macros
+    // count as modulation, and cells whose source was removed after the
+    // analysis must not receive moves.
+    const mods = {
+        lfos: state.lfos,
+        envelopes: state.envelopes,
+        vary: state.vary,
+        paramSeqs: state.paramSeqs,
+        macros: state.macros,
+    };
+    const hasSource = (id) => {
+        const cells = state.cells;
+        if (cells?.[String(id)]?.filePath)
+            return true;
+        if (Number(state[`cell${id}_synthEngine`] ?? 0) > 0.5)
+            return true;
+        if (Number(state[`cell${id}_magentaEngine`] ?? 0) > 0.5)
+            return true;
+        const pluginPath = state[`cell${id}_pluginPath`];
+        return typeof pluginPath === "string" && pluginPath.length > 0;
+    };
+    const measurement = buildMixMeasurementFromState(analysis, state, mods, { hasSource });
+    const current = currentFlatFromState(analysis, state);
+    // Rider ownership (the panel's parked-bal rule): while Auto Mix AUTO runs,
+    // the cMixRide rider owns the balance — fader suggestions would
+    // double-drive it on top of the signed trims.
+    const riderOwnsBalance = Number(state.masterMixRideEnabled ?? 0) === 1 && Number(state.masterMixRideAuto ?? 0) === 1;
+    let resolvedScopes = scopes ?? ["balance", "pan", "eq"];
+    const balanceParked = riderOwnsBalance && resolvedScopes.includes("balance");
+    if (balanceParked)
+        resolvedScopes = resolvedScopes.filter((s) => s !== "balance");
+    if (resolvedScopes.length === 0)
+        return error("Auto Mix is running and owns the balance — request pan, eq, or dynamics scopes while it is on.");
+    const suggestion = suggestMix(measurement, { scopes: resolvedScopes }, current);
+    const parkedNote = balanceParked
+        ? { balanceParked: true, note: "Auto Mix AUTO owns the balance — balance scope was skipped." }
+        : {};
+    if (apply && suggestion.moves.length > 0) {
+        await applyKv(suggestion.flat, KV_OPTS_STANDARD);
+        if (!analysis.live)
+            lastAppliedMixEpoch = analysis.epoch;
+        return json({ ...suggestion, ...parkedNote, applied: true });
+    }
+    return json({ ...suggestion, ...parkedNote });
 });
 server.registerTool("new_preset", {
     title: "New Preset",
@@ -1154,7 +2141,11 @@ server.registerTool("save_preset", {
         "Writes to the user preset folder by default; pass `path` for a specific location. " +
         "Use `update_preset_metadata` to edit an existing preset without re-saving plugin state.",
     inputSchema: {
-        name: z.string().describe("Preset name (used for filename if `path` omitted)."),
+        // Optional since 1.15.0: omitted name = re-save the ACTIVE user preset in
+        // place (the UI Save button's semantics; the assistant's bare "save").
+        // The describe() text is pinned — the exported assistant toolpack keeps
+        // property descriptions, and the model is trained against those bytes.
+        name: z.string().optional().describe("Preset name (used for filename if `path` omitted)."),
         author: z.string().optional().describe("Author name."),
         category: z
             .string()
@@ -1179,26 +2170,56 @@ server.registerTool("save_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    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
+    // repair turns are trained on those shapes). Factory/Init need a name.
+    const extras = rest;
+    if (!name?.trim()) {
+        const activePath = typeof state.activePresetPath === "string" ? state.activePresetPath : "";
+        if (!activePath || activePath === "Init")
+            return error('No preset is active — give this one a name, e.g. save_preset({ name: "Night Drive" }).');
+        const readPath = normalizePresetLookupPath(activePath);
+        if (readPath.startsWith("Factory/"))
+            return error("The current preset is a factory patch — save a copy under a new name instead.");
+        name = (activePath.split("/").pop() || "").replace(/\.preset$/, "");
+        if (!name)
+            return error(`Could not derive a name from the active preset path (${activePath}) — pass name explicitly.`);
+        if (path === undefined)
+            path = activePath;
+        try {
+            const parsed = parsePresetFile(await readFile(await resolvePresetPath(readPath), "utf-8"));
+            for (const [k, v] of Object.entries(parsed.metadata)) {
+                // Structural keys are rebuilt below; everything else (author/tags/
+                // category/…) carries over unless the caller overrode it.
+                if (["name", "factory", "path", "variations", "currentVariation"].includes(k))
+                    continue;
+                if (extras[k] === undefined)
+                    extras[k] = v;
+            }
+        }
+        catch {
+            // unreadable/new — save fresh with whatever the caller passed
+        }
+    }
     const metadata = { name, factory: false };
     if (path !== undefined)
         metadata.path = path;
-    for (const [k, v] of Object.entries(rest)) {
+    for (const [k, v] of Object.entries(extras)) {
         if (v !== undefined)
             metadata[k] = v;
     }
     // Match UI behavior: auto-save current state to variation slot 0 if no variations exist,
     // otherwise update the current active variation slot.
-    const state = (await bridge.send("getState"));
     const variationString = buildVariationString(state);
     const presetRelPath = path || `User/${name}.preset`;
-    // Strip "Presets/" prefix if present — resolvePresetPath already prepends
-    // the presets base directory, so "Presets/User/X" would double up to
-    // ".../Presets/Presets/User/X" and silently fail to read back variations,
-    // wiping slots 1-7 on save. Mirrors save_variation's handling.
-    const readPath = presetRelPath.startsWith("Presets/")
-        ? presetRelPath.slice("Presets/".length)
-        : presetRelPath;
-    const existingVariations = await readExistingVariations(readPath);
+    const readPath = normalizePresetLookupPath(presetRelPath);
+    // Save As must copy the active preset's complete variation bank. Reading
+    // the new destination starts from eight empty slots because that file does
+    // not exist yet, which used to collapse every named save to one slot.
+    const variationSourcePath = selectSaveVariationSourcePath(state.activePresetPath, presetRelPath);
+    const existingVariations = await readExistingVariations(variationSourcePath);
     const hasVariations = existingVariations.some((v) => v !== null);
     if (!hasVariations) {
         existingVariations[0] = variationString;
@@ -1212,7 +2233,10 @@ server.registerTool("save_preset", {
     }
     metadata.variations = existingVariations;
     const result = (await bridge.send("savePreset", metadata));
-    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}`);
+    lastSavedPresetName = name;
+    lastSavedPresetPath = result?.path || readPath;
+    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}` +
+        hostedPluginSaveWarning(state, canonical));
 });
 server.registerTool("save_variation", {
     title: "Save Variation",
@@ -1245,8 +2269,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;
@@ -1259,11 +2283,15 @@ server.registerTool("save_variation", {
         // Strip "Presets/" prefix if present — resolvePresetPath already prepends
         // the presets base directory, so "Presets/User/X" would double up to
         // ".../Presets/Presets/User/X" and silently fail to read back variations.
-        diskPath = activePath.startsWith("Presets/") ? activePath.slice("Presets/".length) : activePath;
+        diskPath = normalizePresetLookupPath(activePath);
+    }
+    if (!presetName && lastSavedPresetName) {
+        presetName = lastSavedPresetName;
+        diskPath = lastSavedPresetPath;
     }
     if (!presetName) {
-        return text("Error: No preset name provided and no active preset loaded. " +
-            "Save the preset first with save_preset, or pass a name.");
+        return error("No preset name provided and no active preset loaded.\n" +
+            "Next call: save_preset({ name: 'Your Preset Name', ...metadata }) first, or call save_variation with name: 'Your Preset Name'.");
     }
     if (!diskPath) {
         diskPath = `User/${presetName}.preset`;
@@ -1302,10 +2330,13 @@ server.registerTool("save_variation", {
         resultSuffix = "\n(Note: active preset is a factory preset — saved as new user preset)";
     }
     const result = (await bridge.send("savePreset", metadata));
+    lastSavedPresetName = presetName;
+    lastSavedPresetPath = result?.path || diskPath;
     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",
@@ -1419,30 +2450,141 @@ server.registerTool("reverse_sample", {
     await bridge.send("reverseSampleForCell", cellId);
     return text(`Reversed sample in cell ${cellId}.`);
 });
+const BRIDGE_INSTANCE_SHAPE = z.object({
+    port: z.number().optional(),
+    instanceId: z.string().optional(),
+    product: z.string().optional(),
+    pid: z.number().optional(),
+});
 server.registerTool("connection_status", {
     title: "Connection Status",
     description: "Check if the MCP server can connect to a running PAM plugin instance. " +
         "Returns connection details or instructions for enabling the bridge.",
     inputSchema: {},
+    outputSchema: {
+        instances: z.array(BRIDGE_INSTANCE_SHAPE.passthrough()).optional(),
+        connected: z.boolean().optional(),
+        connectedTo: BRIDGE_INSTANCE_SHAPE.passthrough().nullable().optional(),
+        note: z.string().optional(),
+    },
     annotations: { readOnlyHint: true },
 }, async () => {
     const instances = await bridge.discover();
     if (instances.length === 0) {
-        return text("No running PAM instances found.\n\n" +
-            "To use live tools, PAM needs the MCP bridge enabled:\n" +
-            "1. Start PAM (standalone or in a DAW)\n" +
-            "2. The bridge will write its port to ~/.pam-mcp-bridge.json\n\n" +
-            "Offline tools (get_parameter_info, list_presets, read_preset) work without a connection.");
+        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. " +
+                "Offline tools (get_parameter_info, list_presets, read_preset) work without a connection.",
+        });
     }
     const connected = bridge.isConnected() || (await bridge.connect());
-    return json({
+    if (connected)
+        syncProductHint();
+    return structured({
         instances,
         connected,
+        connectedTo: bridge.getConnectedInstance(),
         note: connected
-            ? "Connected to PAM. All tools available."
+            ? instances.length > 1
+                ? "Connected. Multiple instances are running — use select_instance to drive a specific product."
+                : "Connected to PAM. All tools available."
             : "Found instances but could not connect. The plugin may have shut down.",
     });
 });
+server.registerTool("select_instance", {
+    title: "Select Plugin Instance",
+    description: "Choose which running plugin instance (PAM / CELL1 / MFX) the live tools drive when more than " +
+        "one is running. Match by product name, instanceId, or port — connection_status lists them. " +
+        "Reconnects if currently connected to a different instance, and points offline parameter " +
+        "validation at the selected product's manifest. The PAM_BRIDGE_PRODUCT env var pins the same " +
+        "choice at server launch.",
+    inputSchema: {
+        product: z.string().optional().describe("Product name: PAM, CELL1, or MFX (case-insensitive)."),
+        instanceId: z.string().optional().describe("Exact instanceId from connection_status."),
+        port: z.number().int().optional().describe("Exact TCP port from connection_status."),
+    },
+    outputSchema: {
+        connected: z.boolean().optional(),
+        connectedTo: BRIDGE_INSTANCE_SHAPE.passthrough().nullable().optional(),
+        note: z.string().optional(),
+    },
+}, async ({ product, instanceId, port }) => {
+    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 (!ok) {
+        const instances = await bridge.discover();
+        const listing = instances.length
+            ? ` Running instances: ${instances
+                .map((i) => `${i.product} (port ${i.port}, id ${i.instanceId})`)
+                .join("; ")}.`
+            : " No running instances found.";
+        return error(`No running instance matches that selector.${listing}`);
+    }
+    syncProductHint();
+    return structured({
+        connected: true,
+        connectedTo: bridge.getConnectedInstance(),
+        note: "Live tools now drive this instance.",
+    });
+});
+// Bounded recursive name search under a library root (BFS — shallow matches
+// first), over the bridge's listDirectory. Mirrors the in-plugin executor's
+// searchLibrary (assistantExecutor.ts) so the assistant's trained browse chain
+// (list_samples{path,search} → load_sample of a path-joined result) behaves
+// identically through the dev server. Returned names are relative to the
+// searched root; listDirectory accepts base-relative paths, so recursion can
+// use each entry's `path` verbatim.
+async function searchSampleLibrary(rootPath, term, audioOnly) {
+    const t = term.toLowerCase();
+    const matches = [];
+    const queue = [{ path: rootPath, prefix: "", depth: 0 }];
+    const options = JSON.stringify({ audioOnly, sort: "name" });
+    let dirReads = 0;
+    while (queue.length && dirReads < 40 && matches.length < 60) {
+        const { path, prefix, depth } = queue.shift();
+        dirReads++;
+        let entries = [];
+        try {
+            const res = await bridge.send("listDirectory", path, options);
+            if (Array.isArray(res))
+                entries = res;
+        }
+        catch {
+            continue; // unreadable subdir — keep sweeping the rest
+        }
+        for (const e of entries) {
+            const name = typeof e.name === "string" ? e.name : "";
+            if (!name)
+                continue;
+            if (e.isDir) {
+                if (depth < 3 && typeof e.path === "string")
+                    queue.push({ path: e.path, prefix: `${prefix}${name}/`, depth: depth + 1 });
+            }
+            else if (name.toLowerCase().includes(t)) {
+                matches.push(`${prefix}${name}`);
+                if (matches.length >= 60)
+                    break;
+            }
+        }
+    }
+    return matches;
+}
+// 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).
+function fitListing(base, itemsKey, items, moreKey, total) {
+    let page = items;
+    for (;;) {
+        const payload = { ...base, [itemsKey]: page, ...(total > page.length ? { [moreKey]: total - page.length } : {}) };
+        if (JSON.stringify(payload).length <= 380 || page.length <= 2)
+            return payload;
+        page = page.slice(0, Math.max(2, Math.floor(page.length / 2)));
+    }
+}
 server.registerTool("list_samples", {
     title: "List Samples",
     description: "Browse sample library directories. IMPORTANT: Do NOT guess paths — always call " +
@@ -1474,12 +2616,25 @@ server.registerTool("list_samples", {
             .max(200)
             .default(50)
             .describe("Maximum number of entries to return (1-200). Default: 50."),
+        // Declared LAST so the exported assistant toolpack keeps its property
+        // order byte-identical (export-toolpack.mjs overwrites this prop's text).
+        search: z
+            .string()
+            .optional()
+            .describe("Filter by file name, searched recursively under `path` (e.g. 'kick', '808')."),
     },
     annotations: { readOnlyHint: true },
-}, async ({ path: dirPath, audioOnly, sort, offset, limit }) => {
+}, async ({ path: dirPath, audioOnly, sort, offset, limit, search }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const term = search?.trim();
+    if (term) {
+        const matches = await searchSampleLibrary(dirPath, term, audioOnly);
+        // Executor-shaped payload; empty files:[] is a SUCCESS (the assistant
+        // reports the miss in text instead of repair-looping).
+        return json(fitListing({ path: dirPath }, "files", matches.slice(0, 10), "moreFiles", matches.length));
+    }
     const options = JSON.stringify({ audioOnly, sort });
     const result = await bridge.send("listDirectory", dirPath, options);
     if (!Array.isArray(result) || result.length === 0) {
@@ -1678,7 +2833,7 @@ const VIDEO_LAYER_FX = "hueRotate, glow, audioReact, vibration, chromaticAberrat
     "mirror, trails(drawing/text), beam(drawing/text), shake, rolls, barrelBlur, edge, " +
     "halftone, patches, brightnessContrast, lines, feedback, warp, datamosh, slicer, " +
     "polarSlitScan, cellVoronoi, spectralZones, paletteLut, asciiDither, pixelSort, " +
-    "cameraShake, blur";
+    "cameraShake, blur, cymatics, lineJitter, crt, vhs";
 // Output/global FX chain ids (videoStore, DEFAULT_VIDEO_FX_CONFIG).
 const VIDEO_OUTPUT_FX = "lines, barrelBlur, brightnessContrast, edge, glow, shake, rgbShift, halftone, mirror, " +
     "patches, pixelate, rolls, feedback, warp, datamosh, slicer, positionXY, speed, " +
@@ -1704,12 +2859,24 @@ async function getVideoStateRaw() {
     return (typeof r === "string" ? JSON.parse(r) : r) ?? {};
 }
 const sendVideoCommand = (command) => bridge.send("videoCommand", command);
-/** Create ops are fire-and-forget; resolve the minted id by diffing the snapshot. */
-async function resolveNewId(beforeIds, pick, timeoutMs = 2500) {
+let videoRequestCounter = 0;
+const mintVideoRequestId = () => `mcp-${process.pid}-${Date.now().toString(36)}-${++videoRequestCounter}`;
+/** Create ops are fire-and-forget. Ack-capable PAM builds record the command's
+ *  result in the snapshot as `lastCommandAck` keyed by our requestId — exact
+ *  under concurrent edits. Older builds never publish an ack, so the snapshot
+ *  id-set diff stays as the fallback. */
+async function resolveNewId(requestId, beforeIds, pick, ackIdKey, timeoutMs = 2500) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         await sleep(120);
         const s = await getVideoStateRaw();
+        const ack = s.lastCommandAck;
+        if (ack && ack.requestId === requestId) {
+            const minted = ack.result?.[ackIdKey];
+            if (typeof minted === "string" && minted.length > 0)
+                return minted;
+            return null; // acked but failed / no id — don't misattribute via the diff
+        }
         const found = pick(s).find((id) => !beforeIds.has(id));
         if (found)
             return found;
@@ -1720,9 +2887,14 @@ server.registerTool("get_video_state", {
     title: "Get Video State",
     description: "Read the full VX video scene: layers (in render order, top-first) with their " +
         "per-layer FX chains, the output/global FX chain, audio-reactive bindings, " +
-        "mod-matrix routes, the 3D model overlay, the active cell, and global render/sync " +
-        "settings. Layer/FX/binding ids returned here are what the other video tools " +
-        "address. If `available` is false, open PAM's window so the video UI mounts.",
+        "mod-matrix routes, the 3D model overlay, and global render/sync settings " +
+        "(incl. vxVariationFollowAudio + VX bar-sync). Also carries: vxVariations " +
+        "(8-slot occupancy booleans) + currentVxVariation; the songMode arrangement " +
+        "read-model (nodes with per-section VX slot assignments, compiled steps with " +
+        "the VX slot each recalls, arrangementBars); and the poll targets for " +
+        "long-running jobs — export (exportVideo), recording (start/stop/saveVideoRecording), " +
+        "songExport (exportSong). Layer/FX/binding ids returned here are what the other " +
+        "video tools address. If `available` is false, open PAM's window so the video UI mounts.",
     inputSchema: {},
     annotations: { readOnlyHint: true },
 }, async () => {
@@ -1793,6 +2965,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}, " +
@@ -1803,7 +2979,16 @@ server.registerTool("video_command", {
         "setOutputFxEnabled{instanceId,enabled}, setOutputFxStrength{instanceId,strength}; " +
         "addModRoute{route}, removeModRoute{id}, updateModRoute{id,updates}, clearModRoutes, " +
         "setModEnabled{enabled}; setModel{sourcePath?,visible?,blendMode?,audioReactive?,autoRotate?,transform?}, " +
-        "resetModel; setSettings{...}, setActiveCell{cellId}, resetWorkspace. " +
+        "resetModel; setSettings{...incl vxVariationFollowAudio,vxBarSyncEnabled,vxBarSyncIntervalBars}, " +
+        "setActiveCell{cellId} (deprecated no-op), resetWorkspace; " +
+        "VX variation slots: saveVxVariation{index 0-7}, loadVxVariation{index}, clearVxVariation{index}, " +
+        "fillVxVariationsRandomized (occupancy/current in get_video_state; or use the vx_variation tool); " +
+        "export/record: exportVideo{durationInSeconds,encoderId?,filename?,fps?,width?,height?,bitrate?,audioBitDepth?}, " +
+        "cancelVideoExport, startVideoRecording{encoderId?,saveMode?,fps?,barSync?,bars?,skipSilence?,normalize?}, " +
+        "stopVideoRecording, saveVideoRecording (poll get_video_state export/recording); " +
+        "song: setSongArrangement{sections:[{variationIndex,bars?,repeat?,muted?,probability?,presetPath?,label?,vxVariationIndex?,vxScenePath?}],connections?:[{from,to,probability?}],loop?,enabled?,crossfadeMs?}, " +
+        "setSongNodeVx{nodeId|stepIndex,index|null,vxScenePath?}, exportSong{name?,bars?,normalize?,includeVideo?,encoderId?,strategy?}, " +
+        "cancelSongExport (poll get_video_state songExport/songMode; or use the song_mode / export_song tools). " +
         "Layer fx target a per-layer chain; output fx target the global chain (ids differ). " +
         VIDEO_BIND_SOURCES,
     inputSchema: {
@@ -1826,23 +3011,33 @@ 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()
             .int()
             .optional()
             .describe("Data-index to insert at (default: top of stack)."),
+        sourcePath: z
+            .string()
+            .optional()
+            .describe("Absolute file path to image/video/model media to load into the new layer (no file picker). " +
+            "Bytes are read natively and handed to the WebView as a blob. Large videos are bounded by maxBytes."),
+        maxBytes: z
+            .number()
+            .optional()
+            .describe("Max bytes to read for sourcePath (default ~16MB; raise for video, e.g. 50000000)."),
     },
-}, async ({ kind, name, insertAt }) => {
+}, async ({ kind, name, insertAt, sourcePath, maxBytes }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const before = await getVideoStateRaw();
     const beforeIds = new Set((before.layers ?? []).map((l) => l.id));
-    await sendVideoCommand({ op: "addLayer", kind, name, insertAt });
-    const id = await resolveNewId(beforeIds, (s) => (s.layers ?? []).map((l) => l.id));
+    const requestId = mintVideoRequestId();
+    await sendVideoCommand({ op: "addLayer", kind, name, insertAt, sourcePath, maxBytes, requestId });
+    const id = await resolveNewId(requestId, beforeIds, (s) => (s.layers ?? []).map((l) => l.id), "layerId");
     return text(id
         ? `Added ${kind} layer: ${id}`
         : `Added ${kind} layer (window may be closed; call get_video_state to confirm).`);
@@ -1890,6 +3085,23 @@ server.registerTool("update_video_layer", {
     const result = await sendVideoCommand({ op: "updateLayer", layerId, patch });
     return json(result);
 });
+server.registerTool("set_video_layer_source", {
+    title: "Set Video Layer Source",
+    description: "Load image/video/model media into an existing VX layer from a file path — the headless " +
+        "equivalent of the file picker. Reads bytes natively and assigns a blob the layer renders. " +
+        "PAM's window must be open (VX renders in the WebView). Large videos: raise maxBytes.",
+    inputSchema: {
+        layerId: z.string().describe("Target layer id (from get_video_state / add_video_layer)."),
+        sourcePath: z.string().describe("Absolute path to the media file."),
+        maxBytes: z.number().optional().describe("Max bytes to read (default ~16MB; raise for video)."),
+    },
+}, async ({ layerId, sourcePath, maxBytes }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await sendVideoCommand({ op: "setLayerSource", layerId, sourcePath, maxBytes });
+    return { content: [{ type: "text", text: `Loading ${sourcePath} into layer ${layerId}.` }] };
+});
 server.registerTool("remove_video_layer", {
     title: "Remove Video Layer",
     description: "Remove a layer (and its FX + bindings). The master layer cannot be removed.",
@@ -1946,8 +3158,9 @@ server.registerTool("add_video_fx", {
     if (target === "output") {
         const before = await getVideoStateRaw();
         const beforeIds = new Set((before.outputFx ?? []).map((f) => f.instanceId));
-        await sendVideoCommand({ op: "addOutputFx", fxId: fxType });
-        const id = await resolveNewId(beforeIds, (s) => (s.outputFx ?? []).map((f) => f.instanceId));
+        const requestId = mintVideoRequestId();
+        await sendVideoCommand({ op: "addOutputFx", fxId: fxType, requestId });
+        const id = await resolveNewId(requestId, beforeIds, (s) => (s.outputFx ?? []).map((f) => f.instanceId), "instanceId");
         // Apply param overrides now that the instance exists.
         if (params && id)
             for (const [param, value] of Object.entries(params))
@@ -1959,11 +3172,12 @@ server.registerTool("add_video_fx", {
     const before = await getVideoStateRaw();
     const layer = (before.layers ?? []).find((l) => l.id === layerId);
     const beforeIds = new Set((layer?.fx ?? []).map((f) => f.id));
-    await sendVideoCommand({ op: "addLayerFx", layerId, fxType, params, beforeFxId });
-    const id = await resolveNewId(beforeIds, (s) => {
+    const requestId = mintVideoRequestId();
+    await sendVideoCommand({ op: "addLayerFx", layerId, fxType, params, beforeFxId, requestId });
+    const id = await resolveNewId(requestId, beforeIds, (s) => {
         const l = (s.layers ?? []).find((x) => x.id === layerId);
         return (l?.fx ?? []).map((f) => f.id);
-    });
+    }, "fxId");
     return text(id ? `Added ${fxType} to layer ${layerId}: ${id}` : `Added ${fxType} (confirm via get_video_state).`);
 });
 server.registerTool("set_video_fx", {
@@ -2087,8 +3301,9 @@ server.registerTool("set_video_settings", {
     title: "Set Video Settings",
     description: "Set global VX render/sync settings: syncMode (off|beat-sync|beat-match), loopBars, " +
         "aspectRatio (auto|16:9|4:3|1:1|stretch), renderQuality (low|medium|high), " +
-        "designAspect (w/h number or null), letterboxColor / canvasColor (#hex), the active " +
-        "video cell (cellId), and the mod-matrix master enable. resetWorkspace clears the " +
+        "designAspect (w/h number or null), letterboxColor / canvasColor (#hex), the " +
+        "mod-matrix master enable, VX-variation follow-audio, and VX bar-sync (queue slot " +
+        "loads on the next bar boundary while playing). resetWorkspace clears the " +
         "scene (preserves the master layer).",
     inputSchema: {
         syncMode: z.enum(["off", "beat-sync", "beat-match"]).optional(),
@@ -2099,10 +3314,22 @@ server.registerTool("set_video_settings", {
         letterboxColor: z.string().optional(),
         canvasColor: z.string().optional(),
         modEnabled: z.boolean().optional().describe("Mod-matrix master enable."),
-        activeCell: z.number().int().optional().describe("Switch the active per-cell video slice."),
+        vxVariationFollowAudio: z
+            .boolean()
+            .optional()
+            .describe("VX variation slots follow audio variation switches (default true)."),
+        vxBarSyncEnabled: z
+            .boolean()
+            .optional()
+            .describe("Queue VX-local slot loads on the next bar-sync boundary while the transport plays."),
+        vxBarSyncIntervalBars: z
+            .number()
+            .optional()
+            .describe("VX bar-sync interval in bars (-1 = longest-pattern sentinel)."),
+        activeCell: z.number().int().optional().describe("Deprecated/no-op: VX is a single global scene (no per-cell video)."),
         resetWorkspace: z.boolean().optional().describe("If true, clear the whole scene first."),
     },
-}, async ({ syncMode, loopBars, aspectRatio, renderQuality, designAspect, letterboxColor, canvasColor, modEnabled, activeCell, resetWorkspace }) => {
+}, async ({ syncMode, loopBars, aspectRatio, renderQuality, designAspect, letterboxColor, canvasColor, modEnabled, vxVariationFollowAudio, vxBarSyncEnabled, vxBarSyncIntervalBars, activeCell, resetWorkspace }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
@@ -2127,10 +3354,75 @@ server.registerTool("set_video_settings", {
         settings.letterboxColor = letterboxColor;
     if (canvasColor !== undefined)
         settings.canvasColor = canvasColor;
+    if (vxVariationFollowAudio !== undefined)
+        settings.vxVariationFollowAudio = vxVariationFollowAudio;
+    if (vxBarSyncEnabled !== undefined)
+        settings.vxBarSyncEnabled = vxBarSyncEnabled;
+    if (vxBarSyncIntervalBars !== undefined)
+        settings.vxBarSyncIntervalBars = vxBarSyncIntervalBars;
     if (Object.keys(settings).length > 0)
         await sendVideoCommand({ op: "setSettings", ...settings });
     return text("Video settings updated.");
 });
+server.registerTool("vx_variation", {
+    title: "VX Variation Slots",
+    description: "Manage the 8 VX (visual) variation slots — the visual siblings of the audio " +
+        "variation slots (save_variation / load_variation). 'save' snapshots the live VX " +
+        "scene into a slot; 'load' recalls one (an empty slot moves the index but keeps the " +
+        "current visuals); 'clear' empties a slot; 'fill' saves 8 randomized scene variations " +
+        "into all slots. With vxVariationFollowAudio on (default), audio variation switches — " +
+        "including Song Mode section changes — recall the matching VX slot automatically, so " +
+        "saving VX slots alongside audio slots gives every song section its own visuals " +
+        "(pin a different slot per section via song_mode assignVx). WebView-routed: PAM's " +
+        "window must be OPEN. Verify via get_video_state → vxVariations / currentVxVariation.",
+    inputSchema: {
+        op: z.enum(["save", "load", "clear", "fill"]).describe("Slot operation."),
+        index: z
+            .number()
+            .int()
+            .min(0)
+            .max(7)
+            .optional()
+            .describe("Slot index 0-7 (required for save/load/clear; ignored for fill)."),
+    },
+}, async ({ op, index }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (op !== "fill" && typeof index !== "number")
+        return error(`'${op}' requires index (0-7).`);
+    const opMap = {
+        save: "saveVxVariation",
+        load: "loadVxVariation",
+        clear: "clearVxVariation",
+        fill: "fillVxVariationsRandomized",
+    };
+    await sendVideoCommand(op === "fill" ? { op: opMap.fill } : { op: opMap[op], index });
+    // Fire-and-forget forward path — poll until the snapshot reflects the op
+    // (save→occupied, clear→empty, load→index moved [sticky-empty rule], fill→all occupied).
+    const expectMet = (s) => {
+        const slots = Array.isArray(s.vxVariations) ? s.vxVariations : [];
+        if (op === "save")
+            return slots[index] === true;
+        if (op === "clear")
+            return slots[index] === false;
+        if (op === "load")
+            return s.currentVxVariation === index;
+        return slots.length > 0 && slots.every(Boolean);
+    };
+    let state = await getVideoStateRaw();
+    const deadline = Date.now() + 2500;
+    while (state.available !== false && !expectMet(state) && Date.now() < deadline) {
+        await sleep(150);
+        state = await getVideoStateRaw();
+    }
+    if (state.available === false)
+        return error("VX unavailable — open PAM's window (the video engine renders in the WebView).");
+    const slots = Array.isArray(state.vxVariations) ? state.vxVariations : [];
+    return text(`vx_variation ${op}${op === "fill" ? "" : ` slot ${index}`} ${expectMet(state) ? "applied" : "sent (state not yet reflecting it — window open? rejected op?)"}. ` +
+        `Occupied slots: [${slots.map((o, i) => (o ? i : null)).filter((v) => v !== null).join(", ")}], ` +
+        `current: ${String(state.currentVxVariation ?? "?")}.`);
+});
 // ============================================================
 // Composite cell-operation tools
 // ============================================================
@@ -2152,6 +3444,10 @@ server.registerTool("reset_cell", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
     const [cellParams, envelopes] = await Promise.all([
         getParametersByCell(`cell${cellId}`),
         bridge.send("getState", "envelopes"),
@@ -2185,6 +3481,13 @@ server.registerTool("copy_cell", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const sourceCheck = validateCellIdForManifest(sourceCellId, manifest);
+    if (sourceCheck !== true)
+        return sourceCheck;
+    const targetCheck = validateCellIdForManifest(targetCellId, manifest);
+    if (targetCheck !== true)
+        return targetCheck;
     // Full state needed: cell params live as flat top-level cellN_* keys, no section.
     const state = (await bridge.send("getState"));
     const srcPrefix = `cell${sourceCellId}_`;
@@ -2285,6 +3588,10 @@ server.registerTool("clear_modulations", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
     const [lfosRaw, varyRaw, envsRaw] = await Promise.all([
         bridge.send("getState", "lfos"),
         bridge.send("getState", "vary"),
@@ -2317,7 +3624,7 @@ server.registerTool("clear_modulations", {
 });
 server.registerTool("reset_patterns", {
     title: "Reset Patterns",
-    description: "Clear all sequencer lanes (note, pitch, slice, stretch) for a single cell.",
+    description: "Clear all sequencer lanes (note, pitch, slice, stretch) for a single PAM/Cell1 sampler cell.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -2326,6 +3633,15 @@ server.registerTool("reset_patterns", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
+    const hasPatternLanes = (manifest?.stateVariables ?? []).some((entry) => entry.paramId === `cell${cellId}_midiSequence`);
+    if (manifest && !hasPatternLanes) {
+        const productName = manifest.name ?? "This product";
+        return error(`${productName} has no sampler MIDI/pitch/slice/stretch pattern lanes.`);
+    }
     const delta = { __forceRender__: true };
     for (const suffix of PATTERN_SUFFIXES) {
         delta[`cell${cellId}_${suffix}`] = [];
@@ -2335,7 +3651,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, eq, eq8, fdn, gate, compressor, panner, gain, vocoder, limiter, qverb, wavefold, resonator). " +
+        "wavefold and resonator exist on MFX only. " +
         "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)."),
@@ -2347,11 +3664,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(),
+        // The page-2 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(),
+        limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        qverbEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        // MFX-only page-2 signature effects; harmless no-ops on PAM/Cell1, whose
+        // manifests carry no cellN_wavefoldEnabled / cellN_resonatorEnabled key.
+        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();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
     const delta = {};
     for (const [key, value] of Object.entries(config)) {
         if (value !== undefined)
@@ -2366,11 +3701,94 @@ 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', or 'cellN'. 'output' is a destination only.";
+const MFX_ROUTING_SINK_HINT = "'output' or 'cellN'. 'input'/'sidechain' are sources only.";
+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" && !inRange(from)) {
+            return { ok: false, reason: `invalid source port '${from}' — expected ${MFX_ROUTING_SOURCE_HINT}` };
+        }
+        if (to !== "output" && !inRange(to)) {
+            return { ok: false, reason: `invalid destination port '${to}' — expected ${MFX_ROUTING_SINK_HINT}` };
+        }
+        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" +
+        "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("update_cell_config", {
     title: "Update Cell Config",
     description: "Update cell-level configuration properties like polyphony, MIDI settings, varispeed, and modulation latch. " +
         "These are KV-only properties that don't appear in the parameter manifest. " +
-        "Uses a lightweight KV path without graph rebuild.",
+        "Uses a lightweight KV path without graph rebuild. " +
+        "When bound to MFX, this tool only accepts sidechainFrom; sampler/MIDI/instrument config is PAM/Cell1-only.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         isPoly: z.union([z.literal(0), z.literal(1)]).optional().describe("Polyphonic mode (0=mono, 1=poly)."),
@@ -2380,8 +3798,36 @@ server.registerTool("update_cell_config", {
         modLatch: z.union([z.literal(0), z.literal(1)]).optional().describe("Latch slice/pitch/stretch modulation at trigger."),
         varispeed: z.union([z.literal(0), z.literal(1)]).optional().describe("Varispeed mode (pitch = speed) vs independent pitch shift."),
         armed: z.union([z.literal(0), z.literal(1)]).optional().describe("Whether cell accepts recorded MIDI."),
-        polyRootNote: z.number().min(0).max(127).optional().describe("Root note for poly pitch calculation."),
-        scaleName: z.string().optional().describe("Scale name for pitch sequencer quantization (e.g. 'chromatic', 'major', 'minor')."),
+        polyRootNote: z.number().min(0).max(127).optional().describe("Root note for poly pitch calculation. In Slice Keymap mode this is the key that triggers slice 1."),
+        sliceKeymapMode: z
+            .union([z.literal(0), z.literal(1)])
+            .optional()
+            .describe("Slice Keymap mode: incoming MIDI notes select slices by index instead of pitch (polyRootNote -> slice 1, +1 semitone -> slice 2, ...), each at its native pitch. Works in poly (polyphonic slice play) and mono (each new note chokes the previous slice). Requires the cell's sample to be sliced; notes outside the slice range are silent. The slice lane is ignored while this is on. 0=off, 1=on."),
+        sliceTriggerLength: z
+            .number()
+            .int()
+            .min(0)
+            .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
+            .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."),
@@ -2401,36 +3847,107 @@ server.registerTool("update_cell_config", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
+    // 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 = 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)
+        if (value === undefined)
+            continue;
+        if (PARAM_ROUTED_KEYS.has(key))
+            flatDelta[`cell${cellId}_${key}`] = value;
+        else
             cellConfig[key] = value;
     }
-    if (Object.keys(cellConfig).length === 0) {
-        return error("At least one config property must be provided.");
-    }
     // Auto-enable compressor when setting sidechain source
     if (cellConfig.sidechainFrom !== undefined && cellConfig.sidechainFrom !== null) {
         flatDelta[`cell${cellId}_compressorEnabled`] = 1;
     }
-    if (cellConfig.pitchMode !== undefined || cellConfig.stretchMode !== undefined) {
+    // Mirror interop.ts updateCellConfig: a pitch/stretch engine change OR a
+    // sliceKeymapMode flip (which changes pitch interpretation) bumps
+    // modeChangeSeq so the audio thread flushes its Signalsmith analysis state.
+    if (cellConfig.pitchMode !== undefined ||
+        cellConfig.stretchMode !== undefined ||
+        cellConfig.sliceKeymapMode !== undefined) {
         const next = (cellModeChangeSeq[cellId] ?? Date.now()) + 1;
         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)
+    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", {
+    title: "Mute / Solo Cell",
+    description: "Mute, unmute, solo, or unsolo a cell in the mixer — the real channel mute/solo, cutting the whole channel " +
+        "(source + all effect tails) rather than pulling the volume fader down. Soloing a cell silences every other " +
+        "non-soloed cell until unsoloed. cell{N}_mute / cell{N}_solo are live-polled state variables (no graph rebuild). " +
+        "Prefer this over set_parameter volume -60 when the user says mute, unmute, solo, unsolo, isolate, or 'just this cell'.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        mute: z.boolean().optional().describe("Mute (true) or unmute (false) the cell's channel."),
+        solo: z.boolean().optional().describe("Solo (true) or unsolo (false) the cell — solo silences all other non-soloed cells."),
+    },
+}, async ({ cellId, mute, solo }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
+    const delta = {};
+    if (typeof mute === "boolean")
+        delta[`cell${cellId}_mute`] = mute ? 1 : 0;
+    if (typeof solo === "boolean")
+        delta[`cell${cellId}_solo`] = solo ? 1 : 0;
+    if (Object.keys(delta).length === 0) {
+        return error("Provide mute and/or solo.");
+    }
+    // cell{N}_mute / cell{N}_solo are flat state vars projected to
+    // cell{N}_config.enabled by KVStateSyncManager — same options the UI's
+    // applyStateDelta uses (KV_OPTS_STANDARD); the projection needs
+    // syncConfigResources, no graph rebuild required but the standard path is
+    // the exact UI parity.
+    await applyKv(delta, KV_OPTS_STANDARD);
+    const summary = Object.entries(delta)
         .map(([k, v]) => `${k}=${v}`)
         .join(", ");
-    return text(`Updated cell ${cellId} config: ${summary}`);
+    return text(`Cell ${cellId}: ${summary}`);
 });
 server.registerTool("set_master_effects", {
     title: "Set Master Effects",
     description: "Configure the master bus Punch compressor, Limiter, and Tape colour. " +
         "The Punch compressor is a musical bus compressor — use it for glue and pump. " +
-        "The Limiter is a 3-stage brick-wall limiter with tanh saturation. " +
+        "The Limiter is a zero-latency brickwall safety stage (enable/disable only). " +
+        "Check results with get_master_analysis (keep tp <= -1 dBTP, PSR >= 8 in the loudest section). " +
         "The Tape is a vintage-tape coloration stage (ADAA tanh/asymmetric saturation + HF compression + wow/flutter), " +
         "the single biggest lever for lo-fi / dusty / 'pushed' master character (hip-hop, lo-fi, Memphis, dub). " +
         "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound. " +
@@ -2438,7 +3955,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 (manifest key masterTapeEnabled). 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)."),
@@ -2453,13 +3971,55 @@ server.registerTool("set_master_effects", {
         masterCompCeiling: z.number().min(-6).max(0).optional().describe("Output ceiling in dB (default -0.05)."),
         masterCompInputGain: z.number().min(-24).max(24).optional().describe("Input gain in dB (default 0)."),
         masterCompKnee: z.number().min(0).max(30).optional().describe("Knee width in dB (default 0)."),
+        masterCompOutTrim: z.number().min(-12).max(12).optional().describe("Output trim in dB (default 0) — the Punch panel's Makeup knob (post-compression level, separate from masterCompMakeupGain)."),
+        masterCompMix: z.number().min(0).max(1).optional().describe("Punch parallel dry/wet (0-1, default 1 = fully compressed)."),
         masterTapeDrive: z.number().min(0).max(1).optional().describe("Tape drive / saturation amount (0-1, default 0.5). Higher = more harmonic grit + HF compression ('push it harder → it gets duller')."),
         masterTapeTone: z.number().min(-1).max(1).optional().describe("Tape tone tilt (-1 dark .. 0 flat .. +1 bright, default 0). Go negative for dusty/lo-fi."),
         masterTapeMix: z.number().min(0).max(1).optional().describe("Tape dry/wet (0-1, default 1 = fully wet)."),
-        masterTapeMode: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional().describe("Tape character: 0=Clean (gentle tanh), 1=Lo-Fi (most degradation, dusty), 2=Amp (hard asymmetric drive). Default 0."),
+        masterTapeMode: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional().describe("Tape character: 0=Clean (gentle tanh), 1=Lo-Fi (most degradation, dusty), 2=Amp (hard asymmetric drive), 3=Studio (Jiles-Atherton magnetic hysteresis — the deep hi-fi machine, no wow/hiss). Default 0."),
         masterTapeWear: z.number().min(0).max(1).optional().describe("Tape wear: wow/flutter pitch drift + age (0-1, default 0.5). Raise for warble/sag."),
+        masterEqEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the master EQ (trim/tilt/shelves/bells)."),
+        masterWidthEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the stereo utility (width + elliptical bass-mono)."),
+        masterInputTrim: z.number().min(-24).max(24).optional().describe("Master input trim in dB (gain staging into the chain; default 0)."),
+        masterEqTilt: z.number().min(-6).max(6).optional().describe("Tilt in dB at the extremes around a 650 Hz pivot (+ = brighter; the coarse tonal-balance lever)."),
+        masterEqLsFreq: z.number().min(20).max(500).optional().describe("Low-shelf corner Hz (default 90)."),
+        masterEqLsGain: z.number().min(-12).max(12).optional().describe("Low-shelf gain dB (default 0)."),
+        masterEqHsFreq: z.number().min(1000).max(16000).optional().describe("High-shelf corner Hz (default 8000)."),
+        masterEqHsGain: z.number().min(-12).max(12).optional().describe("High-shelf gain dB (default 0)."),
+        masterWidth: z.number().min(0).max(2).optional().describe("Stereo width (0=mono, 1=unity, 2=double side; default 1). Check corr in get_master_analysis after widening."),
+        masterBassMonoFreq: z.number().min(0).max(300).optional().describe("Elliptical bass-mono corner Hz; < 20 = off. Engage (~100-120) when corrLow < +0.7."),
+        masterClipEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the oversampled soft clipper (post-Tape, pre-Limiter). Adds 23 samples of reported latency while on."),
+        masterClipDrive: z.number().min(0).max(12).optional().describe("Clipper drive dB (default 0). Staging guidance: the clipper shaves the sharpest 2-3 dB so the limiter works 1-2 dB."),
+        masterClipMix: z.number().min(0).max(1).optional().describe("Clipper parallel blend (1 = fully clipped)."),
+        masterClipMode: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional().describe("Clipper transfer: 0=Smooth (knee-tanh), 1=Silicon diode (hard knee), 2=Germanium diode (earlier, softer knee), 3=LED (higher knee). Diode modes are exact antiparallel-pair solves, ADAA at the 2x rate. Default 0."),
+        masterIronEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the console/transformer iron colour stage (post-Tape, pre-Clipper; zero latency)."),
+        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({
+            freq: z.number().min(30).max(16000).optional(),
+            gain: z.number().min(-12).max(12).optional(),
+            q: z.number().min(0.3).max(8).optional(),
+            dyn: z.union([z.literal(0), z.literal(1)]).optional().describe("Dynamic option: the band's gain rides the in-band level."),
+            dynThresh: z.number().min(-60).max(0).optional().describe("Dynamic threshold dB (default -24)."),
+            dynRange: z.number().min(-12).max(12).optional().describe("Dynamic range dB (negative ducks when loud — de-harsh; default -3)."),
+        }))
+            .max(4)
+            .optional()
+            .describe("The 4 parametric bells in order (defaults 200/700/2000/5000 Hz). Pass null-ish entries to skip a band."),
     },
-}, async ({ compressorEnabled, limiterEnabled, tapeEnabled, ...effectParams }) => {
+}, async ({ compressorEnabled, limiterEnabled, tapeEnabled, masterEqBells, ...effectParams }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
@@ -2471,8 +4031,28 @@ server.registerTool("set_master_effects", {
         delta.masterLimiterEnabled = limiterEnabled;
     if (tapeEnabled !== undefined)
         delta.masterTapeEnabled = tapeEnabled;
-    // Compressor + tape parameters are already the flat state keys read by the
-    // DSP graph / native master node (masterComp*, masterTape*). Pass through.
+    // Bell array → flat masterEqB{n}{Field} keys.
+    if (masterEqBells) {
+        masterEqBells.forEach((bell, i) => {
+            if (!bell)
+                return;
+            const base = `masterEqB${i + 1}`;
+            if (bell.freq !== undefined)
+                delta[`${base}Freq`] = bell.freq;
+            if (bell.gain !== undefined)
+                delta[`${base}Gain`] = bell.gain;
+            if (bell.q !== undefined)
+                delta[`${base}Q`] = bell.q;
+            if (bell.dyn !== undefined)
+                delta[`${base}Dyn`] = bell.dyn;
+            if (bell.dynThresh !== undefined)
+                delta[`${base}DynThresh`] = bell.dynThresh;
+            if (bell.dynRange !== undefined)
+                delta[`${base}DynRange`] = bell.dynRange;
+        });
+    }
+    // Compressor + tape + limiter + EQ parameters are already the flat state
+    // keys read by the DSP graph / native master nodes. Pass through.
     for (const [key, value] of Object.entries(effectParams)) {
         if (value !== undefined)
             delta[key] = value;
@@ -2480,47 +4060,61 @@ server.registerTool("set_master_effects", {
     if (Object.keys(delta).length === 0) {
         return error("At least one parameter must be provided.");
     }
-    // Use standard opts with graph dispatch so the DSP graph picks up new compressor params
-    await applyKv(delta, KV_OPTS_STANDARD);
+    // No-dispatch path: every master key is live-polled from master_config
+    // (the full Punch surface included), so a graph rebuild here would only
+    // risk dropouts during automated mastering.
+    await applyKv(delta, KV_OPTS_MASTER_CONFIG);
     const summary = Object.entries(delta)
         .map(([k, v]) => `${k}=${v}`)
         .join(", ");
     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. " +
-        "On builds without it, the cell{N}_synthEngine state key is ignored.",
+        "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)."),
         engine: z.enum(DRUM_SYNTH_ENGINE_NAMES).describe("Engine name. 'Off' disables the synth voice (sample-only cell)."),
@@ -2538,17 +4132,21 @@ server.registerTool("set_drum_synth", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
+    if (manifest && manifest.drumSynth?.enabled !== true) {
+        return error("set_drum_synth is PAM-only. This product manifest does not expose the built-in 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;
@@ -2561,9 +4159,47 @@ 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", {
+    title: "Set Drum Synth Wave Curve (Wave engine)",
+    description: "Set the custom single-cycle waveform for a cell's drum-synth WAVE engine (engine #16). " +
+        "Provide 2–16 breakpoints { t, v, tension } (t = phase 0..1, v = amplitude 0..1 with 0.5 the zero-crossing " +
+        "centre, tension −1..+1 with 0 = linear). PAM bakes them into a DC-removed, peak-normalized single cycle " +
+        "that the Wave engine's Draw param (p8) crossfades against the factory bank. Only the Wave engine reads it — " +
+        "select 'Wave' via set_drum_synth and raise Draw (p8) to hear it. Runs in the WebView (the curve transform " +
+        "is single-sourced there), so PAM's window must be OPEN. Needs PAM ≥ 1.13.0.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        points: z
+            .array(z.object({
+            t: z.number().min(0).max(1).describe("Phase position 0..1 (left→right)."),
+            v: z.number().min(0).max(1).describe("Amplitude 0..1 (0.5 = zero-crossing centre)."),
+            tension: z.number().min(-1).max(1).default(0).describe("Segment curve −1..+1 (0 = linear)."),
+        }))
+            .min(2)
+            .max(16)
+            .describe("2–16 breakpoints defining the single cycle, ordered left→right by t."),
+    },
+}, async ({ cellId, points }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    const cellCheck = validateCellIdForManifest(cellId, manifest);
+    if (cellCheck !== true)
+        return cellCheck;
+    if (manifest && manifest.drumSynth?.enabled !== true) {
+        return error("set_drum_synth_wave is PAM-only. This product manifest does not expose the built-in drum synth.");
+    }
+    await bridge.send("setDrumSynthWaveCurve", {
+        cellId,
+        points: points.map((p) => ({ t: p.t, v: p.v, tension: p.tension ?? 0 })),
+    });
+    return text(`Set cell ${cellId} Wave-engine custom waveform (${points.length} breakpoints). ` +
+        `Select the Wave engine and raise Draw (p8) to hear it. (Runs in the WebView — ensure PAM's window is open.)`);
+});
 server.registerTool("add_param_seq", {
     title: "Add Parameter Sequencer",
     description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
@@ -2586,8 +4222,11 @@ server.registerTool("add_param_seq", {
     if (check !== true)
         return check;
     const index = await getParameterIndex();
-    if (!index.get(paramId))
-        return error(`Unknown parameter: ${paramId}`);
+    const param = index.get(paramId);
+    if (!param)
+        return error(formatUnknownParamError(paramId, index, { modulatableOnly: true }));
+    if (!param.isModulatable)
+        return error(formatNotModulatableError(paramId, index));
     const existing = await bridge.send("getState", "paramSeqs");
     const paramSeqs = (Array.isArray(existing) ? existing : []).filter((seq) => seq?.paramId !== paramId);
     const newSeq = {
@@ -2696,11 +4335,30 @@ async function pollExportStatus(maxWaitMs = 180_000, pollMs = 500) {
     while (Date.now() - t0 < maxWaitMs) {
         await new Promise((r) => setTimeout(r, pollMs));
         const status = (await bridge.send("getExportStatus"));
-        if (status.complete)
+        if (status.complete) {
+            lastExportLoudness = status.loudness ?? null;
             return status.success ? "success" : "failed";
+        }
     }
     return "timeout";
 }
+// Loudness report of the last completed bounce (set by pollExportStatus).
+let lastExportLoudness = null;
+function loudnessReportLine() {
+    const l = lastExportLoudness;
+    if (!l || typeof l.i !== "number")
+        return "";
+    const parts = [`${l.i.toFixed(1)} LUFS-I`];
+    if (typeof l.lra === "number")
+        parts.push(`LRA ${l.lra.toFixed(1)}`);
+    if (typeof l.tp === "number")
+        parts.push(`TP ${l.tp.toFixed(1)} dBTP`);
+    if (typeof l.psr === "number")
+        parts.push(`PSR ${l.psr.toFixed(1)}`);
+    if (typeof l.plr === "number")
+        parts.push(`PLR ${l.plr.toFixed(1)}`);
+    return `\nLoudness: ${parts.join(" · ")}`;
+}
 server.registerTool("export_audio", {
     title: "Export Audio",
     description: "Render and export audio from the current preset to a WAV file in PAM's Exports folder. " +
@@ -2709,9 +4367,9 @@ server.registerTool("export_audio", {
         "Modes: 'main' (full mix, default) · 'individual' (one cell solo, needs cellId) · " +
         "'all-cells' / 'selected-cells' (per-cell stems, the latter needs selectedCellIds) · " +
         "'per-bus' (per output bus) · 'song-mode' (the Song Mode timeline).\n\n" +
-        "NOTE on 'song-mode': the OFFLINE bounce only renders the arrangement's FIRST section's live state — " +
-        "variation/preset switches are not applied offline (the message thread is blocked during render). " +
-        "For a true full track that captures every section change, use the `export_song` tool (live capture).",
+        "NOTE on 'song-mode': the offline bounce applies EVERY section on its anchor (PAM ≥ 1.5.7 with " +
+        "offline song export; older builds render only the first section). Wall-clock sources " +
+        "(Magenta/Notochord) render silent offline — use the `export_song` tool's live strategy for those.",
     inputSchema: {
         bars: z.number().min(1).max(128).default(4).describe("Bars to render (ignored for 'song-mode', which derives length from the timeline)."),
         cellId: z
@@ -2756,7 +4414,8 @@ server.registerTool("export_audio", {
         const outcome = await pollExportStatus();
         if (outcome === "success")
             return text(`Audio exported successfully.\nFile: ${outputPath}\n` +
-                `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)`);
+                `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)` +
+                loudnessReportLine());
         if (outcome === "failed")
             return error("Audio export failed.");
         return text(`Export timed out. The render may still be running.\nExpected output: ${outputPath}`);
@@ -2787,6 +4446,7 @@ server.registerTool("export_audio", {
     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."
@@ -2905,6 +4565,24 @@ Use \`update_pattern\` with \`type: "slice"\` to sequence slice changes over tim
 - Different patternSpeed creates rate variation: slice lane at 2x speed = double-time slice changes
 - Combine with \`prob\` field (0-1) on events for controlled randomness
 
+### Slice Keymap — Trigger Slices from MIDI
+Map incoming MIDI notes directly to slices (Octatrack / Geist style): the cell's Root note
+plays slice 1, root+1 semitone plays slice 2, and so on chromatically up. The slice
+sequencer lane above is ignored while this is on — the note picks the slice.
+
+\`\`\`
+update_cell_config: cellId=1, sliceKeymapMode=1, polyRootNote=60, sliceTriggerLength=0
+trigger_midi: cellId=1, note=60   # -> slice 1
+trigger_midi: cellId=1, note=62   # -> slice 3
+\`\`\`
+- Requires the cell's sample to be sliced first. Notes outside the slice range are silent.
+- \`polyRootNote\` = the key that triggers slice 1.
+- \`sliceTriggerLength\`: 0=Boundary (stop at next slice edge), 1=Sample End, 2=Note Off (needs cell mode=Gate).
+- Set \`isPoly=1\` for polyphonic slice play (held notes layer); leave poly off for monophonic
+  jamming (each new note chokes the previous slice). Slice Keymap works in both.
+- Each slice plays at its own per-slice pitch, so the keymap performs a chopped sample at
+  native rate. Played notes can be recorded into the cell's MIDI sequence and looped back.
+
 ## Sidechain Compression — The Pump
 
 ### Setup via MCP
@@ -3026,7 +4704,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)
 \`\`\`
@@ -3147,7 +4825,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)
@@ -3186,6 +4865,89 @@ 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,
     ],
 }));
 // ============================================================
+// 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.
+// ============================================================
+// Mirror of RANDOMIZER_GENRES (shared/randomizer/types.ts) — the published
+// package can't import repo-relative shared modules, so the copy is pinned by
+// interface/test/randomizerGenre.test.ts (source-text parity check).
+const GENRE_SUGGESTIONS = ["boom_bap", "trap", "drill", "house", "techno", "dnb"];
+const 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
+// optionals when DETECTING completable prompt args but not when RESOLVING the
+// 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);
+function promptText(text) {
+    return {
+        messages: [
+            { role: "user", content: { type: "text", 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.`));
+// ============================================================
 // TOOLS — Looper (state deltas)
 // ============================================================
 // applyStateDelta-equivalent options: full update, dispatch graph, sync KV.
@@ -3297,7 +5059,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)
@@ -3378,6 +5140,10 @@ server.registerTool("start_looper_recording", {
     const check = await requireBridge();
     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,
@@ -3593,7 +5359,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."),
@@ -3602,13 +5370,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",
@@ -3762,16 +5565,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();
@@ -3788,20 +5592,82 @@ 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 steps). Ops: 'setSequence', 'clear', " +
-        "'toggle', 'setLoopPoints', 'toggleLoop', 'setCrossfadeMs', 'setPlayhead'.",
+    description: "Control PAM's song mode (timeline of variation/preset sections). Ops: 'setArrangement', " +
+        "'get', 'assignVx', 'setSequence', 'clear', 'toggle', 'setLoopPoints', 'toggleLoop', " +
+        "'setCrossfadeMs', 'setPlayhead'.\n\n" +
+        "PREFER 'setArrangement' (PAM ≥ 1.5.7, window open): it authors real Song Mode grid nodes " +
+        "from a `sections` list, with an optional weighted `connections` graph. The result is " +
+        "visible/editable in the UI, and each section can pin a " +
+        "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). 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.",
     inputSchema: {
         op: z
             .enum([
+            "setArrangement",
+            "get",
+            "assignVx",
             "setSequence",
             "clear",
             "toggle",
@@ -3811,6 +5677,96 @@ server.registerTool("song_mode", {
             "setPlayhead",
         ])
             .describe("Operation."),
+        sections: z
+            .array(z.object({
+            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("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()
+                .min(0)
+                .max(7)
+                .optional()
+                .describe("VX variation slot recalled while this section plays (omit = follow the audio slot)."),
+            vxScenePath: z
+                .string()
+                .optional()
+                .describe("VX scene (.vxpreset path) whose slots vxVariationIndex indexes into — loaded before the " +
+                "section plays, so sections can pull visuals from different scenes. Requires vxVariationIndex; " +
+                "omit = the live scene's slots."),
+        }))
+            .min(1)
+            .optional()
+            .describe("For 'setArrangement': section list. Without `connections`, sections play in order."),
+        connections: z
+            .array(z.object({
+            from: z.number().int().min(0).describe("Source section index."),
+            to: z.number().int().min(0).describe("Destination section index."),
+            probability: z
+                .number()
+                .min(0)
+                .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. 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)."),
+        vxIndex: z
+            .number()
+            .int()
+            .min(0)
+            .max(7)
+            .nullable()
+            .optional()
+            .describe("For 'assignVx': VX slot 0-7, or null to clear (follow the audio slot)."),
+        vxScenePath: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("For 'assignVx': pin the scene (.vxpreset path) vxIndex indexes into (requires vxIndex; " +
+            "null/'' clears the pin → the live scene's slots; omit = keep the node's current pin)."),
         steps: z
             .array(z.object({
             variationIndex: z.number().min(0).max(7).describe("Variation slot 0-7."),
@@ -3824,8 +5780,8 @@ server.registerTool("song_mode", {
             probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
         }))
             .optional()
-            .describe("For 'setSequence': step list."),
-        enabled: z.boolean().optional().describe("For 'toggle' / 'toggleLoop': enabled state."),
+            .describe("For 'setSequence': raw step list (headless path; prefer 'setArrangement')."),
+        enabled: z.boolean().optional().describe("For 'toggle' / 'toggleLoop' / 'setArrangement': enabled state."),
         start: z
             .number()
             .nullable()
@@ -3849,6 +5805,66 @@ server.registerTool("song_mode", {
     if (check !== true)
         return check;
     switch (args.op) {
+        case "setArrangement": {
+            if (!args.sections || args.sections.length === 0)
+                return error("'setArrangement' requires sections");
+            await sendVideoCommand({
+                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 }),
+            });
+            // The forward path is fire-and-forget — poll until the WebView's apply
+            // republishes the snapshot (same pattern as resolveNewId).
+            const deadline = Date.now() + 3000;
+            let sm;
+            for (;;) {
+                const state = await getVideoStateRaw();
+                sm = state.songMode;
+                const landed = sm?.available === true &&
+                    Array.isArray(sm.nodes) &&
+                    sm.nodes.length === args.sections.length;
+                if (landed || Date.now() > deadline)
+                    break;
+                await sleep(150);
+            }
+            if (!sm || sm.available !== true)
+                return error("Arrangement command sent, but no song-mode read-model came back — this needs PAM ≥ 1.5.7 " +
+                    "with the window OPEN. On older builds fall back to op 'setSequence' (headless raw steps).");
+            const nodes = Array.isArray(sm.nodes) ? sm.nodes.length : 0;
+            if (nodes !== args.sections.length)
+                return error(`Arrangement did not land within 3s (${nodes} nodes vs ${args.sections.length} sections) — the ` +
+                    "command may have been rejected (variationIndex/vxVariationIndex must be 0-7; bars must be greater than 0).");
+            return text(`Song arrangement set: ${nodes} sections, ${Array.isArray(sm.steps) ? sm.steps.length : 0} steps, ` +
+                `${String(sm.arrangementBars)} bars${args.loop ? ", looped" : ""}${args.enabled ? ", song mode ON" : ""}. ` +
+                "Read it back with op 'get'.");
+        }
+        case "get": {
+            const state = await getVideoStateRaw();
+            if (state.available === false)
+                return error("VX/song read-model unavailable — open PAM's window (WebView-routed).");
+            const sm = state.songMode;
+            if (!sm)
+                return error("No songMode read-model in the snapshot — the connected PAM predates it (needs ≥ 1.5.7).");
+            return json(sm);
+        }
+        case "assignVx": {
+            if (args.nodeId === undefined && args.stepIndex === undefined)
+                return error("'assignVx' requires nodeId or stepIndex");
+            await sendVideoCommand({
+                op: "setSongNodeVx",
+                ...(args.nodeId !== undefined && { nodeId: args.nodeId }),
+                ...(args.stepIndex !== undefined && { stepIndex: args.stepIndex }),
+                index: args.vxIndex ?? null,
+                ...(args.vxScenePath !== undefined && { vxScenePath: args.vxScenePath }),
+            });
+            return text(`VX assignment sent (${args.nodeId ?? `step ${args.stepIndex}`} → ${args.vxIndex ?? "follow audio"}` +
+                `${args.vxIndex != null && args.vxScenePath ? ` in ${args.vxScenePath}` : ""}). ` +
+                "Verify with op 'get' (nodes[].vxVariationIndex / vxScenePath).");
+        }
         case "setSequence":
             if (!args.steps)
                 return error("'setSequence' requires steps");
@@ -3888,17 +5904,24 @@ server.registerTool("song_mode", {
 });
 server.registerTool("export_song", {
     title: "Export Song (Full Track)",
-    description: "Bounce the full Song Mode arrangement to a single WAV — the 'render my whole track' button. " +
-        "Set up the arrangement first with the `song_mode` tool (setSequence), then call this.\n\n" +
-        "Two strategies:\n" +
-        "• 'live' (DEFAULT, full fidelity): plays the arrangement in real time and captures the master mix, " +
-        "so EVERY section/variation/preset change and all modulation is rendered. Needs a free `cellId` to " +
-        "land the captured clip in (use an empty cell). Capture is capped at 64 bars; for longer songs bounce " +
-        "in sections or raise the cap. The captured WAV also lands in PAM's Resamples folder.\n" +
-        "• 'offline' (fast, LIMITED): renders via the offline song-mode bounce. Only the first section's state " +
-        "is rendered (variation/preset switches are NOT applied offline). Use only for single-section sketches.\n\n" +
-        "After a 'live' bounce, the captured file path is read back from the destination cell; run get_audio_info " +
-        "(resolve against the Resamples location from get_default_locations) to verify it.",
+    description: "Bounce the full Song Mode arrangement — the 'render my whole track' button. " +
+        "Set up the arrangement first with the `song_mode` tool (prefer op setArrangement), then call this.\n\n" +
+        "Strategies:\n" +
+        "• 'live' + includeVideo:true — full A/V render: plays the arrangement in real time, films the VX " +
+        "scene (VX variation follow runs live, so per-section visuals land exactly as assigned) and muxes " +
+        "the master mix into a video file. Needs PAM ≥ 1.5.7 with the window OPEN and at least one VX layer.\n" +
+        "• 'live' without cellId — bar-synced audio WAV via the same WebView Song Export (lands in " +
+        "VX/Resamples; window must be open, PAM ≥ 1.5.7). No destination cell consumed.\n" +
+        "• 'live' with cellId — legacy headless master-mix capture into an empty cell (works with the window " +
+        "closed on PAM ≥ 1.5.0). The captured WAV also lands in PAM's Resamples folder.\n" +
+        "• 'offline' — the DETERMINISTIC multi-section bounce (PAM ≥ 1.5.7 with offline song export): every " +
+        "variation section applies sample-accurately on its anchor; renders faster than realtime with no bar cap. " +
+        "Audio-only works headless (window closed); includeVideo runs the offline video pump with per-section VX " +
+        "recalls (window open, WebCodecs). Caveats: preset-path steps hold the previous section's sound (pending), " +
+        "and wall-clock sources (Magenta, Notochord, camera layers) cannot render offline — use 'live' for those.\n\n" +
+        "Live paths render in REAL TIME (a 90 s song takes ~90 s) and cap at 64 bars per capture. " +
+        "Verify audio results with get_audio_info (resolve cell captures against the Resamples location " +
+        "from get_default_locations).",
     inputSchema: {
         strategy: z.enum(["live", "offline"]).default("live").describe("Capture strategy."),
         bars: z
@@ -3911,41 +5934,113 @@ server.registerTool("export_song", {
             .min(1)
             .max(8)
             .optional()
-            .describe("For 'live': empty destination cell the bounced master clip is written into."),
-        bitDepth: z.number().default(24).describe("Bit depth (16 or 24)."),
+            .describe("For legacy headless 'live': empty destination cell for the bounced clip. Omit to use the WebView Song Export (window open)."),
+        includeVideo: z
+            .boolean()
+            .default(false)
+            .describe("Film the VX scene alongside the audio and mux to video (window open, VX layers required)."),
+        name: z.string().optional().describe("Output name for WebView Song Export renders (default 'Song')."),
+        normalize: z.boolean().optional().describe("Normalize the captured audio (WebView Song Export paths)."),
+        encoderId: z.string().optional().describe("Recording encoder preset for includeVideo (e.g. mp4-h264)."),
+        bitDepth: z.number().default(24).describe("Bit depth (16 or 24; legacy cell-capture + offline paths)."),
         tailBars: z
             .number()
             .min(0)
             .max(8)
             .default(1)
-            .describe("For 'live': extra bars captured after the arrangement end for reverb/release tails."),
+            .describe("For legacy cell-capture 'live': extra bars captured after the arrangement end for tails."),
     },
-}, async ({ strategy, bars, cellId, bitDepth, tailBars }) => {
+}, async ({ strategy, bars, cellId, includeVideo, name, normalize, encoderId, bitDepth, tailBars }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    // -------- Offline strategy: reuse the song-mode bounce (first-section only) --------
-    if (strategy === "offline") {
+    // -------- Offline audio-only: headless multi-section bounce --------
+    // (Offline WITH video routes through the WebView Song Export below — the
+    // pump needs the window; strategy rides the op.)
+    if (strategy === "offline" && !includeVideo) {
         const filename = `pam_song_${Date.now()}`;
         const transport = (await bridge.send("getTransport"));
         const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
         await bridge.send("exportAudio", {
             filename,
             mode: "song-mode",
+            // Estimate only — exportSongMode computes the real length from the arrangement.
             durationInSeconds: (bars * 4 * 60) / bpm,
             bitDepth,
         });
         const outcome = await pollExportStatus();
         if (outcome === "success")
-            return text(`Offline song bounce complete: ${filename}.wav (in PAM's Exports folder).\n` +
-                "Note: only the first section's state was rendered. Use strategy 'live' for the full track.");
+            return text(`Offline song bounce complete: ${filename}.wav (in PAM's Exports folder) — every variation section ` +
+                "applied on its anchor.\n" +
+                "Caveats: preset-path steps hold the previous section (pending); Magenta/Notochord render silent " +
+                "offline (use strategy 'live' for generative sources). Verify with get_audio_info.");
         if (outcome === "failed")
-            return error("Offline song bounce failed. Is Song Mode enabled with a non-empty sequence?");
+            return error("Offline song bounce failed (or was cancelled). Is Song Mode enabled with a non-empty sequence?");
         return text("Offline song bounce timed out. The render may still be running.");
     }
-    // -------- Live strategy: real-time master capture of the whole arrangement --------
-    if (typeof cellId !== "number")
-        return error("'live' strategy requires an empty destination cellId.");
+    // -------- VX-capture path (WebView Song Export): audio WAV or audio+video --------
+    // Chosen when the caller wants video, or asked for 'live' without a destination
+    // cell — runSongExport bar-syncs the capture, runs VX variation follow live, and
+    // needs no free cell. Fire-and-forget op + snapshot polling (songExport status).
+    if (includeVideo || typeof cellId !== "number") {
+        const pre = await getVideoStateRaw();
+        if (pre.available === false)
+            return error(includeVideo
+                ? "includeVideo needs PAM's window OPEN (the VX scene renders in the WebView)."
+                : "'live' without cellId uses the WebView Song Export (window must be OPEN). Open the window, or pass an empty destination cellId for the headless cell-capture path.");
+        if (!("songExport" in pre))
+            return error("The connected PAM predates the Song Export op (needs ≥ 1.5.7). " +
+                "Pass an empty destination cellId for the legacy live capture instead.");
+        const preJob = pre.songExport ?? {};
+        if (preJob.state === "running")
+            return error("A song export is already running — poll get_video_state songExport, or cancel it first.");
+        await sendVideoCommand({
+            op: "exportSong",
+            bars,
+            includeVideo,
+            strategy,
+            ...(name !== undefined && { name }),
+            ...(normalize !== undefined && { normalize }),
+            ...(encoderId !== undefined && { encoderId }),
+        });
+        // The op returns immediately; confirm OUR job actually started. A rejected
+        // op (sync guards: empty arrangement, busy capture, no VX layers) leaves
+        // the previous status — with its old startedAt stamp — in place.
+        let started = false;
+        for (let i = 0; i < 10; i++) {
+            await sleep(500);
+            const s = await getVideoStateRaw();
+            const job = s.songExport ?? {};
+            if (typeof job.startedAt === "number" && job.startedAt !== preJob.startedAt) {
+                started = true;
+                break;
+            }
+        }
+        if (!started)
+            return error("Song export did not start — likely a guard failure (empty arrangement, another capture " +
+                "running, or includeVideo with no VX layers). Check song_mode get / get_video_state.");
+        const transport = (await bridge.send("getTransport"));
+        const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
+        // Capture length + bar-sync start slack + save/mux margin.
+        const deadline = Date.now() + ((bars + 2) * 4 * 60 * 1000) / bpm + 120_000;
+        let last = {};
+        while (Date.now() < deadline) {
+            await sleep(2000);
+            const s = await getVideoStateRaw();
+            last = s.songExport ?? {};
+            if (last.state === "done")
+                return text(`Song export complete (${bars} bars, ${includeVideo ? "audio+video" : "audio WAV"}).\n` +
+                    `File: ${String(last.path ?? "(unknown — check VX/Resamples / Visuals)")}\n` +
+                    (includeVideo ? "" : "Verify with get_audio_info."));
+            if (last.state === "failed")
+                return error(`Song export failed: ${String(last.error ?? "unknown")}`);
+            if (last.state === "cancelled")
+                return error("Song export was cancelled.");
+        }
+        return error(`Song export timed out (last status: ${JSON.stringify(last)}). It may still be running — ` +
+            "poll get_video_state songExport, or cancel via video_command {op:'cancelSongExport'}.");
+    }
+    // -------- Legacy live strategy: headless master capture into a destination cell --------
     const transport = (await bridge.send("getTransport"));
     const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
     const totalBars = bars + (tailBars ?? 1);
@@ -4235,6 +6330,13 @@ function isPathUnderWhitelist(p) {
 // accepts entries observed here so an agent can't instantiate arbitrary
 // binaries.
 const knownPluginIdentifiers = new Set();
+// PAM's bridge returns some plugin-host results as a JSON OBJECT in `result`
+// (newer builds) and others as a pre-serialized string (older builds). The
+// handlers below must accept both — treating an object as a string made
+// text() emit a non-string (MCP result-validation error) and JSON.parse
+// throw, leaving knownPluginIdentifiers empty so load_plugin refused every
+// path.
+const bridgeResultText = (raw) => typeof raw === "string" ? raw : JSON.stringify(raw);
 // Hosted-plugin tools target PAM cells. Cap to the manifest's cell count
 // (falls back to 8 — PAM's shipping max) rather than the C++ slot
 // reservation of 32.
@@ -4281,12 +6383,12 @@ server.registerTool("list_plugins", {
         filter.isInstrument = args.isInstrument;
     if (args.nameContains)
         filter.nameContains = args.nameContains;
-    const raw = (await bridge.send("listPlugins", filter));
+    const raw = await bridge.send("listPlugins", filter);
     // Record every fileOrIdentifier so load_plugin can validate that the
     // caller-supplied path was discovered by PAM's own scanner.
     try {
-        const parsed = JSON.parse(raw);
-        if (Array.isArray(parsed.plugins)) {
+        const parsed = (typeof raw === "string" ? JSON.parse(raw) : raw);
+        if (Array.isArray(parsed?.plugins)) {
             for (const p of parsed.plugins) {
                 if (typeof p.fileOrIdentifier === "string") {
                     knownPluginIdentifiers.add(p.fileOrIdentifier);
@@ -4297,7 +6399,7 @@ server.registerTool("list_plugins", {
     catch {
         // C++ payload not JSON — fall through; load_plugin will reject unknowns.
     }
-    return text(raw);
+    return text(bridgeResultText(raw));
 });
 server.registerTool("scan_plugins", {
     title: "Scan Plugins",
@@ -4353,12 +6455,21 @@ server.registerTool("get_plugin_scan_status", {
         "`fraction` (0..1), `elapsedMs`, `isStall` (true when the in-flight plugin hasn't returned in 2s), " +
         "and `updatedAtMs`. Poll while a scan is running.",
     inputSchema: {},
+    outputSchema: {
+        isScanning: z.boolean().optional(),
+        format: z.string().optional(),
+        currentPath: z.string().optional(),
+        fraction: z.number().optional(),
+        elapsedMs: z.number().optional(),
+        isStall: z.boolean().optional(),
+        updatedAtMs: z.number().optional(),
+    },
 }, async () => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const raw = (await bridge.send("getPluginScanStatus"));
-    return text(raw);
+    const raw = await bridge.send("getPluginScanStatus");
+    return structuredFromBridge(raw);
 });
 server.registerTool("list_loaded_plugins", {
     title: "List Loaded Plugins",
@@ -4371,8 +6482,8 @@ server.registerTool("list_loaded_plugins", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const raw = (await bridge.send("listLoadedPlugins"));
-    return text(raw);
+    const raw = await bridge.send("listLoadedPlugins");
+    return text(bridgeResultText(raw));
 });
 server.registerTool("load_plugin", {
     title: "Load Plugin Into Cell",
@@ -4383,6 +6494,10 @@ server.registerTool("load_plugin", {
         cellId: z.number().int().min(1).describe("Target cell (1-based)."),
         path: z.string().describe("Plugin fileOrIdentifier from list_plugins."),
         format: PLUGIN_FORMAT.describe("Plugin format."),
+        uniqueId: z.number().int().optional().describe("Optional type disambiguator for multi-type bundles (one .vst3 exposing several plugin types, " +
+            "e.g. Serum2.vst3 = instrument + FX). Pass the uniqueId from the list_plugins entry you want. " +
+            "Absent → PAM prefers the instrument type at that path."),
+        name: z.string().optional().describe("Optional type name disambiguator (the list_plugins `name`), used when uniqueId is unavailable."),
     },
 }, async (args) => {
     const check = await requireBridge();
@@ -4399,6 +6514,8 @@ server.registerTool("load_plugin", {
         cellId: clamped,
         path: args.path,
         format: args.format,
+        ...(args.uniqueId ? { uniqueId: args.uniqueId } : {}),
+        ...(args.name ? { name: args.name } : {}),
     }));
     return text(raw);
 });
@@ -4471,7 +6588,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
@@ -4548,6 +6665,24 @@ server.registerTool("get_audio_device_setup", {
     const setup = await bridge.send("getAudioDeviceSetup");
     return json(setup);
 });
+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. " +
@@ -4581,16 +6716,16 @@ server.registerTool("set_midi_io", {
 server.registerTool("set_midi_mapping", {
     title: "Set MIDI Action Mapping",
     description: "Configure the global MIDI-controller mappings that trigger PAM actions: variation switch, preset change, " +
-        "looper record, live resample, and looper-variation switch. Set the enable flag, MIDI channel, CC number, " +
-        "preset source, or bar-sync for each target. One field per call.",
+        "looper record, live resample, VX video record toggle, and looper-variation switch. Set the enable flag, " +
+        "MIDI channel, CC number, preset source, or bar-sync for each target. One field per call.",
     inputSchema: {
         target: z
-            .enum(["variation", "preset", "looper", "resample", "looperVariation"])
-            .describe("Which action's mapping to configure."),
+            .enum(["variation", "preset", "looper", "resample", "vxRecord", "looperVariation"])
+            .describe("Which action's mapping to configure. 'vxRecord' toggles VX video recording — requires the PAM window open (VX renders in the WebView)."),
         field: z
             .enum(["enabled", "channel", "ccNumber", "source", "barSync"])
             .describe("Field to set. 'source' is preset-only; 'barSync' is variation/looperVariation-only; " +
-            "looper/resample have no source/barSync."),
+            "looper/resample/vxRecord have no source/barSync."),
         value: z
             .union([z.number(), z.boolean()])
             .describe("boolean for enabled/barSync; number for channel (1-16), ccNumber (0-127), or source."),
@@ -4755,13 +6890,309 @@ server.registerTool("remove_plugin_from_blocklist", {
     return text(`Removed ${fileOrIdentifier} from the plugin blocklist.`);
 });
 // ============================================================
+// TOOL — ask_assistant (drive the FunctionGemma assistant end-to-end)
+// ============================================================
+// The in-server twin of the ASK bar: renders the SAME FunctionGemma prompt
+// (shared fgemma-format module + live [ctx] line), generates against a local
+// OpenAI-compatible endpoint (llama-server serving the fine-tune), parses the
+// call blocks, and executes them through this server's own handlers. Lets an
+// MCP client (Claude Code) test the assistant model directly against a live
+// PAM. Stateless per call — thread follow-ups by passing back `modelTurn`
+// from the previous trace as `history`.
+//
+// Dev-tree only: registered only when the fgemma toolpack resolves (the
+// published npm package doesn't carry it — the tool would be dead weight).
+const ASSISTANT_TOOLPACK_PATH = resolve(PACKAGE_ROOT, "../fgemma-poc/out/toolpack.json");
+// The assistant's view vocabulary → MainViewTypes (stores/Interface.ts).
+// Pinned to the in-plugin executor's VIEW_MAP (assistantExecutor.ts) — one
+// vocabulary across tool arg, [ctx] view= field, and this dev twin. null =
+// the cell grid (selectMainView(null) semantics in the WebView).
+const SET_VIEW_MAIN_VIEW = {
+    cells: null,
+    pads: null,
+    grid: null,
+    mixer: "Mixer",
+    ctrl: "CtrlAll",
+    ctrlall: "CtrlAll",
+    looper: "Looper",
+    song: "SongMode",
+    lfo: "LFO",
+    envelope: "Envelope",
+    env: "Envelope",
+    vary: "Vary",
+    paramseq: "ParamSeq",
+    video: "Video",
+    vx: "Video",
+    visuals: "Video",
+    export: "Export",
+    presets: "PresetBrowser",
+    browser: "PresetBrowser",
+};
+// Dev-tree twin of the in-plugin assistant's set_view (toolpack-gated like
+// ask_assistant — the published server deliberately excludes window/view
+// chrome). Error strings mirror the executor exactly: the model's repair
+// turns are trained on those shapes.
+if (existsSync(ASSISTANT_TOOLPACK_PATH))
+    server.registerTool("set_view", {
+        title: "Set View (assistant surface)",
+        description: "Navigate PAM's UI: switch the main view, focus a cell, or set the pad-grid size. " +
+            "Dev-tree twin of the in-plugin assistant's set_view, routed through the WebView — " +
+            "PAM's window must be OPEN. On PAM builds without the setView bridge action it falls " +
+            "back to the capture_ui compose path (view + gridSize only; cell selection needs a " +
+            "rebuilt plugin).",
+        inputSchema: {
+            // Union: "8 cell view" phrasings make the model emit view:8 (a number) —
+            // accept it so the gridSize coercion below can run instead of a zod reject.
+            view: z
+                .union([z.string(), z.number()])
+                .optional()
+                .describe("Main view: cells, mixer, ctrl, looper, song, lfo, envelope, vary, paramseq, video, export, presets."),
+            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();
+        if (check !== true)
+            return check;
+        let view = viewArg === undefined ? undefined : String(viewArg);
+        // Numeric view token → gridSize (executor does the same coercion); an
+        // explicit gridSize wins and the numeric view is dropped either way.
+        if (view !== undefined && /^[148]$/.test(view.trim())) {
+            if (gridSize === undefined)
+                gridSize = Number(view.trim());
+            view = undefined;
+        }
+        const applied = {};
+        let token;
+        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.`);
+            applied.view = token;
+        }
+        if (gridSize !== undefined) {
+            if (gridSize !== 1 && gridSize !== 4 && gridSize !== 8)
+                return error("gridSize must be 1, 4, or 8.");
+            applied.gridSize = gridSize;
+        }
+        if (cellId !== undefined) {
+            if (!Number.isInteger(cellId) || cellId < 1 || cellId > 8)
+                return error("cellId must be 1-8.");
+            applied.cellId = cellId;
+        }
+        if (!Object.keys(applied).length)
+            return error("Provide view, cellId, and/or gridSize.");
+        try {
+            await bridge.send("setView", {
+                ...(token !== undefined ? { view: token } : {}),
+                ...(cellId !== undefined ? { cellId } : {}),
+                ...(gridSize !== undefined ? { gridSize } : {}),
+            });
+            return json(applied);
+        }
+        catch (e) {
+            const msg = e.message;
+            if (!/unknown action|does not support/i.test(msg))
+                return error(`set_view failed: ${msg}`);
+            // Pre-1.15.0 PAM build — compose via the shipped captureUi handler
+            // (applies mainView/gridSize in the WebView before its rasterize; the
+            // capture itself is discarded). No cell-selection fallback exists.
+            if (token === undefined && gridSize === undefined)
+                return error("Cell selection needs the setView bridge action — this PAM build predates it (rebuild PAM).");
+            const setup = { settleMs: 0 };
+            if (token !== undefined)
+                setup.mainView = SET_VIEW_MAIN_VIEW[token];
+            if (gridSize !== undefined)
+                setup.gridSize = gridSize;
+            try {
+                await bridge.send("captureUi", setup);
+            }
+            catch (e2) {
+                return error(`set_view failed: ${e2.message}`);
+            }
+            delete applied.cellId; // not applied on the fallback path — don't over-claim
+            return json(applied);
+        }
+    });
+if (existsSync(ASSISTANT_TOOLPACK_PATH))
+    server.registerTool("ask_assistant", {
+        title: "Ask Assistant (FunctionGemma e2e test)",
+        description: "Run one natural-language command through the on-device assistant model: render the " +
+            "FunctionGemma prompt (with the live [ctx] state line), generate via a local llama-server, " +
+            "parse the tool calls, execute them against PAM, and return the full trace. Requires " +
+            "llama-server running with the fine-tuned GGUF (--special). For multi-turn tests, pass the " +
+            "previous trace's modelTurn back via history.",
+        inputSchema: {
+            text: z.string().describe("The user command, e.g. 'mute the kick' or '174 bpm dnb kit'."),
+            endpoint: z
+                .string()
+                .optional()
+                .describe("OpenAI-compatible /v1 base URL (default env PAM_LLM_URL or http://127.0.0.1:8080/v1)."),
+            sel: z
+                .number()
+                .int()
+                .optional()
+                .describe("Selected-cell override for the [ctx] line (the bridge can't see UI selection)."),
+            noCtx: z.boolean().optional().describe("Skip the [ctx] line (test the no-context prompt shape)."),
+            history: z
+                .array(z.object({ user: z.string(), model: z.string() }))
+                .optional()
+                .describe("Prior exchanges to thread (user text + the modelTurn from that trace)."),
+            maxRounds: z.number().int().min(1).max(5).optional().describe("Continuation rounds (default 3)."),
+        },
+    }, async ({ text: userText, endpoint, sel, noCtx, history, maxRounds }) => {
+        // Toolpack: the model-facing surface (dev tree; regenerate with export-toolpack.mjs).
+        let pack;
+        try {
+            const doc = JSON.parse(readFileSync(ASSISTANT_TOOLPACK_PATH, "utf-8"));
+            pack = doc.tools;
+        }
+        catch {
+            return error("assistantToolpack not found — run `node scripts/export-toolpack.mjs` in packages/mcp-server first.");
+        }
+        const declared = new Set(pack.map((t) => t.name));
+        const llmUrl = (endpoint || process.env.PAM_LLM_URL || "http://127.0.0.1:8080/v1").replace(/\/$/, "");
+        // Live [ctx] line from this server's own read tools (sel is UI-only state
+        // the bridge can't see — honor the override, else none).
+        let ctx = null;
+        if (!noCtx) {
+            try {
+                const t = await callInternalTool("get_transport", {});
+                const o = await callInternalTool("get_design_overview", {});
+                if (!t.isError && !o.isError) {
+                    const transport = JSON.parse(t.text);
+                    const overview = JSON.parse(o.text);
+                    // preset= IS bridge-visible (state.activePresetPath) — only view/sel
+                    // are UI-only. Renders `none` for Init/Default, like the executor.
+                    let preset = null;
+                    try {
+                        const s = await callInternalTool("get_state", { keys: ["activePresetPath"] });
+                        const activePath = JSON.parse(s.text).activePresetPath;
+                        if (typeof activePath === "string" && activePath && activePath !== "Init") {
+                            const stem = (activePath.split("/").pop() ?? "").replace(/\.preset$/, "");
+                            preset = stem && stem !== "Default" ? stem : null;
+                        }
+                    }
+                    catch {
+                        preset = null;
+                    }
+                    ctx = {
+                        bpm: Number(transport.bpm ?? 120),
+                        playing: Boolean(transport.playing ?? transport.isPlaying),
+                        preset,
+                        sel: sel ?? null,
+                        cells: (overview.cells ?? [])
+                            .filter((c) => c.sample || c.synth)
+                            .map((c) => ({ id: c.id, name: c.sample ?? `${c.synth}(synth)` })),
+                    };
+                }
+            }
+            catch {
+                ctx = null; // no PAM — trained no-ctx prompt shape still works
+            }
+        }
+        let prompt = buildGenerationPrompt(pack, withContext(userText, ctx), {
+            bos: "none",
+            history,
+        });
+        const trace = { ctxLine: ctx ? renderContextLine(ctx) : null, rounds: [], executed: [], modelTurn: "" };
+        const rounds = maxRounds ?? 3;
+        // A repair round that re-emits the exact call that just errored will error
+        // identically forever — cut the loop (executor parity).
+        const failedCalls = new Set();
+        for (let round = 0; round < rounds; round++) {
+            const t0 = Date.now();
+            let raw;
+            try {
+                const resp = await fetch(`${llmUrl}/completions`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ prompt, max_tokens: 256, temperature: 0, stop: STOP_SEQUENCES, stream: false }),
+                });
+                if (!resp.ok)
+                    return error(`model endpoint ${resp.status}: ${(await resp.text()).slice(0, 200)}`);
+                raw = (await resp.json()).choices?.[0]?.text ?? "";
+            }
+            catch (e) {
+                return error(`cannot reach model endpoint ${llmUrl} — start llama-server with the fine-tuned GGUF and --special. (${e.message})`);
+            }
+            raw = truncateAtFabricatedResponse(raw);
+            const calls = parseFunctionCalls(raw);
+            trace.rounds.push({ raw, ms: Date.now() - t0, calls });
+            if (!calls.length) {
+                trace.text = raw.trim();
+                trace.modelTurn += trace.text;
+                return json(trace);
+            }
+            const unknown = calls.filter((c) => !declared.has(c.name));
+            if (unknown.length) {
+                trace.refused = `undeclared tool(s): ${unknown.map((c) => c.name).join(", ")}`;
+                return json(trace);
+            }
+            let continuation = raw.trimEnd();
+            let responses = "";
+            let wantContinue = false;
+            for (const call of calls) {
+                const signature = `${call.name} ${JSON.stringify(call.arguments)}`;
+                if (failedCalls.has(signature)) {
+                    trace.stopped = `model repeated a call that already failed (${call.name}) — loop cut`;
+                    return json(trace);
+                }
+                // The flat set_parameter alias maps onto the real object-map tool.
+                const real = pack.find((t) => t.name === call.name)?.aliasOf === "set_parameters"
+                    ? {
+                        name: "set_parameters",
+                        arguments: { parameters: { [String(call.arguments.paramId)]: call.arguments.value } },
+                    }
+                    : call;
+                const result = await callInternalTool(real.name, real.arguments);
+                if (result.isError)
+                    failedCalls.add(signature);
+                trace.executed.push({
+                    name: call.name,
+                    arguments: call.arguments,
+                    result: result.text.length > 400 ? `${result.text.slice(0, 400)}…` : result.text,
+                    isError: result.isError,
+                });
+                let payload;
+                if (result.isError)
+                    payload = { error: result.text.slice(0, 400) };
+                else {
+                    try {
+                        const parsed = JSON.parse(result.text);
+                        payload =
+                            parsed && typeof parsed === "object" && !Array.isArray(parsed) && result.text.length <= 400
+                                ? parsed
+                                : { result: result.text.slice(0, 400) };
+                    }
+                    catch {
+                        payload = { result: result.text.slice(0, 400) };
+                    }
+                }
+                const response = renderFunctionResponse(call.name, payload);
+                continuation += response;
+                responses += response;
+                if (result.isError || /^(get_|list_|connection_status)/.test(call.name))
+                    wantContinue = true;
+            }
+            trace.modelTurn += calls.map(renderFunctionCall).join("") + responses;
+            if (!wantContinue)
+                return json(trace);
+            prompt += continuation;
+        }
+        return json(trace);
+    });
+// ============================================================
 // Start
 // ============================================================
 async function main() {
     if (await handleCliArgs())
         return;
     // Try to connect to plugin on startup (non-blocking)
-    void bridge.connect();
+    void bridge.connect().then((ok) => {
+        if (ok)
+            syncProductHint();
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Log to stderr (stdout is the MCP JSON-RPC channel)