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

package/dist/server.js

@@ -1,13 +1,18 @@
 #!/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 { 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 { loadManifest, 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 +21,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 +30,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 {
+        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 = await readFile(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
+        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 +109,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 +127,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;
 }
 /**
@@ -176,12 +262,218 @@ function formatParam(p) {
         desc += ` — ${p.tooltip}`;
     return desc;
 }
+const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
+const CELL_EFFECTS = ["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 " +
@@ -195,16 +487,255 @@ const server = new McpServer({
         "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_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 +772,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 +800,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 +880,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 +898,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 +909,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 +1029,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 +1072,132 @@ 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 : {};
+    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,
+            },
+            synthEngine: state[`${prefix}synthEngine`] ?? 0,
+            enabledEffects: CELL_EFFECTS.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 +1211,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 +1293,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 +1559,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 +1632,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)
@@ -898,9 +1663,9 @@ server.registerTool("add_modulation", {
     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 +1681,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 +1759,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 +1795,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 +1824,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 +1912,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 +2074,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 +2103,56 @@ server.registerTool("save_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    const state = (await bridge.send("getState"));
+    // 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,6 +2166,8 @@ server.registerTool("save_preset", {
     }
     metadata.variations = existingVariations;
     const result = (await bridge.send("savePreset", metadata));
+    lastSavedPresetName = name;
+    lastSavedPresetPath = result?.path || readPath;
     return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}`);
 });
 server.registerTool("save_variation", {
@@ -1259,11 +2215,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,6 +2262,8 @@ 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` +
@@ -1419,30 +2381,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 +2547,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 +2764,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 +2790,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 +2818,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 () => {
@@ -1803,7 +2906,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: {
@@ -1834,15 +2946,25 @@ server.registerTool("add_video_layer", {
             .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 +3012,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 +3085,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 +3099,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 +3228,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 +3241,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 +3281,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 +3371,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 +3408,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 +3515,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 +3551,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 +3560,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}`] = [];
@@ -2352,6 +3595,10 @@ server.registerTool("update_effect_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)
@@ -2370,7 +3617,8 @@ 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,7 +3628,18 @@ 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."),
+        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.string().optional().describe("Scale name for pitch sequencer quantization (e.g. 'chromatic', 'major', 'minor')."),
         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."),
@@ -2401,6 +3660,10 @@ 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;
     const cellConfig = {};
     const flatDelta = {};
     for (const [key, value] of Object.entries(config)) {
@@ -2410,11 +3673,23 @@ server.registerTool("update_cell_config", {
     if (Object.keys(cellConfig).length === 0) {
         return error("At least one config property must be provided.");
     }
+    if (manifest && isMfxManifest(manifest)) {
+        const unsupported = Object.keys(cellConfig).filter((key) => !MFX_CELL_CONFIG_KEYS.has(key));
+        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(", ")}.`);
+        }
+    }
     // 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;
@@ -2426,11 +3701,50 @@ server.registerTool("update_cell_config", {
         .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(`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 +3752,7 @@ 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.",
+        "NOTE: the Tape requires a PAM build that ships it (flat state key masterTapeEnabled — master-chain keys are not manifest params). On older builds these keys are ignored.",
     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 +3767,46 @@ 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)."),
+        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 +3818,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,8 +3847,10 @@ 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(", ");
@@ -2520,7 +3889,7 @@ server.registerTool("set_drum_synth", {
         "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.",
+        "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,6 +3907,13 @@ 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}`);
@@ -2564,6 +3940,44 @@ server.registerTool("set_drum_synth", {
     const labels = engineId > 0 ? DRUM_SYNTH_ENGINES[engineId - 1].params.map((p) => p[0]).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 +4000,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 +4113,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 +4145,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 +4192,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 +4224,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 +4343,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
@@ -3186,6 +4642,86 @@ 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.
+// ============================================================
+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.
@@ -3797,11 +5333,27 @@ server.registerTool("update_modulation", {
 // ============================================================
 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). 'get' reads the arrangement back (nodes, compiled steps with the " +
+        "VX scene+slot each recalls, total bars); 'assignVx' re-pins one section's VX slot (and " +
+        "optional scene) after authoring.\n\n" +
+        "'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 +5363,62 @@ 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."),
+            bars: z.number().positive().optional().describe("Section length in bars (default: auto from longest pattern)."),
+            repeat: z.number().int().min(1).optional().describe("Times to play before advancing (default 1)."),
+            muted: z.boolean().optional().describe("Pass through without an audio trigger."),
+            probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
+            presetPath: z.string().optional().describe("Load this preset instead of switching variation."),
+            label: z.string().optional().describe("Section label shown on the grid node (e.g. 'Intro', 'Hook')."),
+            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%."),
+        }))
+            .optional()
+            .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section."),
+        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 +5432,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 +5457,65 @@ 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.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 +5555,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 +5585,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 +5981,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 +6034,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 +6050,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 +6106,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 +6133,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 +6145,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 +6165,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);
 });
@@ -4581,16 +6349,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 +6523,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)