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

package/dist/server.js

@@ -1,12 +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
@@ -15,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 }] };
@@ -22,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";
     }
@@ -35,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.");
@@ -50,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;
 }
 /**
@@ -76,23 +163,49 @@ function parsePresetFile(raw) {
     const dataStr = raw.slice(prefixLen + metadataSize);
     return { metadata: JSON.parse(metadataStr), data: JSON.parse(dataStr) };
 }
+// PAM ≥ 1.4.61 stores variations ONLY in the data block, zlib+base64-compressed with a
+// "PAMZ1:" marker (see helpers/VariationCodec.h). Decompress one entry to plain JSON;
+// plain (older-format) entries pass through unchanged.
+const VARIATION_MARKER = "PAMZ1:";
+function decompressVariationEntry(v) {
+    if (typeof v !== "string" || !v.startsWith(VARIATION_MARKER))
+        return v;
+    try {
+        return inflateSync(Buffer.from(v.slice(VARIATION_MARKER.length), "base64")).toString("utf8");
+    }
+    catch {
+        return v;
+    }
+}
+/**
+ * Canonical variations array for a parsed preset, as plain-JSON strings (or nulls).
+ * The data block is authoritative (current format); metadata.variations is the fallback
+ * for legacy presets that still carried the duplicate copy there.
+ */
+function variationsFromParsedPreset(parsed) {
+    const fromData = parsed.data?.variations;
+    const fromMeta = parsed.metadata?.variations;
+    const src = Array.isArray(fromData) && fromData.length === PRESET_VARIATION_SLOTS ? fromData
+        : Array.isArray(fromMeta) && fromMeta.length === PRESET_VARIATION_SLOTS ? fromMeta
+            : null;
+    if (!src)
+        return Array(PRESET_VARIATION_SLOTS).fill(null);
+    return src.map(decompressVariationEntry);
+}
 /**
  * Read existing variations array from a preset file on disk.
- * Returns Array(8) of strings or nulls.
+ * Returns Array(8) of plain-JSON strings or nulls.
  */
 async function readExistingVariations(presetPath) {
     try {
         const fullPath = await resolvePresetPath(presetPath);
         const raw = await readFile(fullPath, "utf-8");
-        const { metadata } = parsePresetFile(raw);
-        if (metadata.variations && Array.isArray(metadata.variations) && metadata.variations.length === PRESET_VARIATION_SLOTS) {
-            return [...metadata.variations];
-        }
+        return variationsFromParsedPreset(parsePresetFile(raw));
     }
     catch {
         // Preset doesn't exist yet or can't be read — start fresh
+        return Array(PRESET_VARIATION_SLOTS).fill(null);
     }
-    return Array(PRESET_VARIATION_SLOTS).fill(null);
 }
 // Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
 const VARIATION_EXCLUDED_PARAMS = [
@@ -149,27 +262,480 @@ 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.7.0",
+    title: "PAM Audio Sampler",
+    version: SERVER_VERSION,
 }, {
-    instructions: "PAM is an audio sampler plugin. When browsing samples, ALWAYS call get_default_locations " +
+    instructions: "PAM is an audio sampler plugin. Start design/read work with design_context (curated param " +
+        "cheat sheet) and get_design_overview (compact live snapshot) instead of full get_state or " +
+        "broad get_parameter_info; when you need detail, call get_state with section/keys/cellIds filters. " +
+        "When browsing samples, ALWAYS call get_default_locations " +
         "first to discover the user's actual library paths — never guess paths like ~/Music/PAM. " +
         "The sample library lives under ~/Library/Application Support/, NOT ~/Music/. " +
         "Use the returned paths with list_samples. When loading samples, use load_sample with " +
         "paths from list_samples. Transport must be playing for sequencer output. " +
-        "To enable experimental features (drum synth, plugin host) call update_settings with both " +
-        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true). " +
+        "To enable experimental features (plugin host, AI engines) call update_settings with both " +
+        "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true). " +
+        "The drum synth is a standard feature (PAM ≥ 1.5) — no settings flag needed. " +
         "Tools added in server version 1.7.0 — update_settings, configure_transport, " +
         "get_audio_device_setup, set_midi_io, set_midi_mapping, delete_preset, " +
         "set_preset_factory_status, get_sample_usage, repair_preset_samples, preview_sample, " +
         "set_plugin_params, skip_current_plugin_scan, remove_plugin_from_blocklist — require PAM ≥ 1.7.0. " +
+        "VX video tools (get_video_state, video_command, add_video_layer, update_video_layer, " +
+        "remove_video_layer, apply_video_layout, add_video_fx, set_video_fx, remove_video_fx, " +
+        "bind_video_param, set_video_settings, set_video_layer_source) require PAM ≥ 1.8.0 AND PAM's window to be OPEN " +
+        "(the video engine renders in the WebView; there is no headless renderer). " +
+        "capture_ui, set_visual, set_drum_synth_wave, and randomize with target 'synth' are " +
+        "WebView-routed too and need the window open for the same reason. For " +
+        "audio-reactive control, note the visual audio-react params (visualWaveDisplace, etc.) " +
+        "are regular plugin params — drive them with set_parameters; layers/FX/bindings go through " +
+        "the video tools. When building a scene, call get_video_state first to learn layer/fx ids. " +
+        "AI model lifecycle tools (download_model, get_model_status, load_model, unload_model, " +
+        "delete_model, list_models; engines aigen|magenta|notochord) require PAM ≥ 1.9.0 plus the " +
+        "matching experimental flags; load/unload/delete can block for seconds — poll " +
+        "get_model_status rather than tight-looping. " +
         "Earlier tool sets (looper, song mode, modulation edits, MIDI recording, sample analysis, " +
-        "live resample, variation scheduling, AI generation) require PAM ≥ 1.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)
 // ============================================================
@@ -206,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;
@@ -234,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);
 });
@@ -312,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();
@@ -320,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,
@@ -331,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,
@@ -359,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,
@@ -388,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())
@@ -425,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)
@@ -482,6 +1268,87 @@ server.registerTool("load_sample", {
     await bridge.send("loadSampleToCell", filePath, cellId);
     return text(`Loaded ${basename(filePath)} into cell ${cellId}.`);
 });
+// ---- Unified AI model management (notochord / aigen / magenta) ----
+// All six map to the C++ MCPBridge model* actions (helpers/MCPBridge.cpp::handleModelOp).
+// Each engine must have its experimental flags on (update_settings: experimentalMode
+// + experimental<Engine>) — the bridge returns a clear error otherwise.
+const MODEL_ENGINE = z
+    .enum(["notochord", "aigen", "magenta"])
+    .describe("Which AI engine. notochord = MIDI co-player (~18 MB blob); aigen = Stable Audio 3 sample generation (~3.2 GB ONNX); magenta = MagentaRT realtime audio (Apple Silicon, MLX).");
+const MODEL_VARIANT = z
+    .enum(["base", "small"])
+    .optional()
+    .describe("Magenta only: which variant (base = 2.4B, needs ~M2 Max/M3 Pro+; small = 230M, default). Ignored for notochord/aigen (single model).");
+server.registerTool("download_model", {
+    title: "Download AI Model",
+    description: "Start (or resume) downloading model weights for an AI engine. Async — returns immediately with download progress; poll get_model_status. aigen + notochord auto-load on completion; magenta needs a separate load_model. Requires the engine's experimental flags.",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelDownload", { engine, model }));
+});
+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 structuredFromBridge(await bridge.send("modelStatus", { engine }));
+});
+server.registerTool("load_model", {
+    title: "Load AI Model",
+    description: "Load a downloaded model into memory (async — poll get_model_status for loaded:true). Use after unload, or for magenta after download. magenta accepts an optional variant; omit to load whichever is on disk.",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelLoad", { engine, model }));
+});
+server.registerTool("unload_model", {
+    title: "Unload AI Model",
+    description: "Free the loaded model from memory (weights stay on disk). May briefly stall the plugin while an in-flight load finishes (non-interruptible ORT/MLX load).",
+    inputSchema: { engine: MODEL_ENGINE },
+}, async ({ engine }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelUnload", { engine }));
+});
+server.registerTool("delete_model", {
+    title: "Delete AI Model",
+    description: "Delete downloaded model weights from disk. Unloads first automatically. DESTRUCTIVE — re-download to restore. magenta delete is variant-agnostic (removes both variants + shared resources).",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelDelete", { engine, model }));
+});
+server.registerTool("list_models", {
+    title: "List AI Models",
+    description: "List available model variants per engine with downloaded / loaded state. Omit engine to list all engines (notochord, aigen, magenta base + small).",
+    inputSchema: { engine: MODEL_ENGINE.optional() },
+}, async ({ engine }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelList", { engine }));
+});
 server.registerTool("generate_sample", {
     title: "Generate Sample (AI)",
     description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, ~3.2 GB ONNX). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
@@ -563,6 +1430,145 @@ server.registerTool("generate_kit", {
         return error(`Kit generation failed: ${e.message}`);
     }
 });
+// --- AI Audio Workbench (Phase A, dev-gated) ---------------------------------
+// Drives the Transform canvas headlessly: canvas state (mask regions / strength
+// curve / prompt / seed / sigma), sidecar renders, and the take shelf. Requires
+// experimentalMode + experimentalAIGen (update_settings) AND the SA3 Python
+// sidecar running on 127.0.0.1:8093 (packages/sa3-workbench-sidecar/README.md).
+const WORKBENCH_MASK_REGION = z.object({
+    startSec: z.number().min(0).describe("Region start in seconds (source time)."),
+    endSec: z.number().min(0).describe("Region end in seconds (must be > startSec)."),
+    lowHz: z.number().min(0).optional()
+        .describe("Optional band low edge in Hz (canvas v2 2D mask). Omit BOTH lowHz/highHz for a full-band region (1D back-compat)."),
+    highHz: z.number().min(0).optional()
+        .describe("Optional band high edge in Hz (must be > lowHz). lowHz<=20 && highHz>=source nyquist is treated as full band by the sidecar."),
+});
+const WORKBENCH_CURVE_POINT = z.object({
+    t: z.number().describe("Normalized time 0..1."),
+    v: z.number().describe("Value 0..1 (σ at this point)."),
+    tension: z.number().optional().describe("Curve tension (CurveCanvas semantics, default 0)."),
+});
+const WORKBENCH_STATE_FIELDS = {
+    sourceCellId: z.number().int().min(1).max(8).nullable().optional()
+        .describe("Cell whose sample is the transform source (null to clear)."),
+    prompt: z.string().optional().describe("Text prompt for the render."),
+    seed: z.number().int().min(0).optional().describe("Render seed."),
+    seedLocked: z.boolean().optional().describe("Lock seed across renders (iterate at fixed identity)."),
+    sigma: z.number().min(0.02).max(1).optional()
+        .describe("Deviation σ / init noise level. a2a: 0.25-0.35 preserves melody, 0.45-0.5 variation; inpaint regime ~0.85."),
+    steps: z.number().int().min(1).max(32).optional().describe("Denoise steps (8 is the validated recipe)."),
+    maskRegions: z.array(WORKBENCH_MASK_REGION).optional()
+        .describe("Transform-lane mask. Empty = pure a2a re-render of the whole source; regions = inpaint (regenerate inside, keep outside). Regions may carry an optional lowHz/highHz band."),
+    strengthCurve: z.array(WORKBENCH_CURVE_POINT).optional()
+        .describe("Strength-lane breakpoints (stored with full provenance; per-region σ application is experimental)."),
+    activeSourcePath: z.string().optional()
+        .describe("Render-chain head: absolute WAV path used as the transform source ('' = the source cell's sample). Managed automatically — each successful render advances it to the new take's wavPath; set explicitly only to point the chain at a prior take. Walk it back with workbench_undo / workbench_reset_chain."),
+    sketchPath: z.string().optional()
+        .describe("SKETCH mode: absolute path to a painted-gesture WAV ('' = no sketch). Normally written by the UI (workbenchSaveSketch saves into ai-cache/workbench/); settable directly for headless tests. When non-empty, renders feed the model source + sketch*sketchGain as init audio AND use that MIX as the preservation reference for masks/paste-back — the gesture survives outside masked regions."),
+    sketchGain: z.number().min(0).max(1).optional()
+        .describe("SKETCH mix gain 0..1 (default 0.5) applied to the sketch before summing with the source. If the mix peaks above 0.99 the sidecar scales the whole mix down to 0.99."),
+};
+server.registerTool("workbench_get_state", {
+    title: "Workbench: Get State",
+    description: "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchGetState"));
+});
+server.registerTool("workbench_set_state", {
+    title: "Workbench: Set State",
+    description: "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
+    inputSchema: WORKBENCH_STATE_FIELDS,
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchSetState", args));
+});
+server.registerTool("workbench_render", {
+    title: "Workbench: Render",
+    description: "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Blocks until done (up to ~3 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, durationSeconds, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file. A successful render ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain.",
+    inputSchema: {
+        ...WORKBENCH_STATE_FIELDS,
+        sourcePath: z.string().optional()
+            .describe("Absolute path to a source WAV — bypasses sourceCellId resolution."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    try {
+        return json(await bridge.send("workbenchRender", args));
+    }
+    catch (e) {
+        return error(`Workbench render failed: ${e.message}`);
+    }
+});
+server.registerTool("workbench_list_takes", {
+    title: "Workbench: List Takes",
+    description: "List all Workbench takes (renders) with full provenance, oldest first.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchListTakes"));
+});
+server.registerTool("workbench_load_take", {
+    title: "Workbench: Load Take",
+    description: "Load a rendered take's WAV into a cell (same native path as load_sample).",
+    inputSchema: {
+        takeId: z.string().describe("Take id from workbench_render / workbench_list_takes."),
+        cellId: z.number().int().min(1).max(8).describe("Target cell."),
+    },
+}, async ({ takeId, cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    try {
+        return json(await bridge.send("workbenchLoadTake", { takeId, cellId }));
+    }
+    catch (e) {
+        return error(`Failed to load take: ${e.message}`);
+    }
+});
+server.registerTool("workbench_undo", {
+    title: "Workbench: Undo (pop chain)",
+    description: "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchUndo"));
+});
+server.registerTool("workbench_reset_chain", {
+    title: "Workbench: Reset Chain",
+    description: "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchResetChain"));
+});
+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 structuredFromBridge(await bridge.send("workbenchSidecarStatus"));
+});
 server.registerTool("trigger_midi", {
     title: "Trigger MIDI",
     description: "Send a MIDI note to a specific cell or globally. " +
@@ -626,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)
@@ -657,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;
@@ -675,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}%).`);
@@ -753,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()
@@ -784,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(", ")}` : ""}.`);
 });
@@ -798,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)
@@ -886,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",
@@ -913,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()
@@ -938,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;
@@ -971,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", {
@@ -1018,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`;
@@ -1033,11 +2234,9 @@ server.registerTool("save_variation", {
     try {
         const fullPath = await resolvePresetPath(diskPath);
         const raw = await readFile(fullPath, "utf-8");
-        const { metadata: m } = parsePresetFile(raw);
-        existingMeta = m;
-        if (m.variations && Array.isArray(m.variations) && m.variations.length === PRESET_VARIATION_SLOTS) {
-            variations = [...m.variations];
-        }
+        const parsed = parsePresetFile(raw);
+        existingMeta = parsed.metadata;
+        variations = variationsFromParsedPreset(parsed);
     }
     catch {
         // New preset or unreadable — start fresh
@@ -1063,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` +
@@ -1180,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 " +
@@ -1235,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) {
@@ -1344,86 +2669,686 @@ server.registerTool("set_visual", {
     if (typeof result === "object" && result.path) {
         return text(`Saved visual: ${result.path} (${result.mime}, ${result.size} bytes)`);
     }
-    return text("Visual saved.");
+    return text("Visual saved.");
+});
+server.registerTool("list_visuals", {
+    title: "List Visuals",
+    description: "List all visual/thumbnail files in PAM's media library. " +
+        "Returns name, relative path, MIME type, size, and modification time for each visual.",
+    inputSchema: {
+        scope: z
+            .enum(["user", "factory", "all"])
+            .optional()
+            .default("user")
+            .describe("Which library to list: 'user' (default), 'factory', or 'all'."),
+    },
+}, async ({ scope }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("listVisuals", scope);
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return text("No visuals found.");
+        const lines = result.map((v) => `- ${v.name} (${v.mime}, ${v.size} bytes) → ${v.path}`);
+        return text(`Found ${result.length} visual(s):\n${lines.join("\n")}`);
+    }
+    return json(result);
+});
+server.registerTool("delete_visual", {
+    title: "Delete Visual",
+    description: "Delete a visual file from PAM's user media library. " +
+        "Only files in the user media folder can be deleted (not factory visuals).",
+    inputSchema: {
+        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ path: relativePath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("deleteVisual", relativePath);
+    if (typeof result === "string" && result.includes("error"))
+        return error(`Failed to delete visual: ${relativePath}`);
+    return text(`Deleted visual: ${relativePath}`);
+});
+server.registerTool("get_visual_data_url", {
+    title: "Get Visual Data URL",
+    description: "Read a visual file from PAM's media library and return it as a base64 data URL. " +
+        "Useful for previewing or inspecting visual content.",
+    inputSchema: {
+        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
+        maxBytes: z
+            .number()
+            .optional()
+            .default(5242880)
+            .describe("Maximum file size in bytes (default 5MB). Files exceeding this are rejected."),
+    },
+}, async ({ path: relativePath, maxBytes }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = (await bridge.send("getVisualDataUrl", relativePath, maxBytes));
+    return text(`Visual: ${result.path} (${result.mime}, ${result.size} bytes)\nData URL: ${result.dataUrl}`);
+});
+server.registerTool("import_visual_folder", {
+    title: "Import Visual Folder",
+    description: "Bulk-import all valid visual files from a folder into PAM's user media library. " +
+        "The import runs asynchronously; this tool returns immediately once the import is queued.",
+    inputSchema: {
+        folderPath: z.string().describe("Absolute path to the folder containing visual files to import."),
+        operationId: z
+            .string()
+            .optional()
+            .describe("Optional operation ID for tracking import progress."),
+    },
+}, async ({ folderPath, operationId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = (await bridge.send("importVisualFolder", folderPath, operationId ?? ""));
+    return text(`Import queued for: ${result.folderPath}` +
+        (result.operationId ? ` (operationId: ${result.operationId})` : ""));
+});
+// ============================================================
+// VX video subsystem — layers, FX, audio-reactive bindings, settings
+// ============================================================
+//
+// The video scene lives in PAM's WebView (R3F/WebGL). These tools forward semantic
+// commands into the live video stores and read back a full-scene snapshot. PAM's
+// window must be OPEN for commands to apply (no headless renderer). Audio-reactive
+// *visual params* (visualWaveDisplace, etc.) are regular plugin params — drive those
+// with set_parameters; everything else (layers/FX/bindings/output FX) goes here.
+// Per-layer FX types (FxRegistry). Some only apply to drawing/text (trails, beam).
+const VIDEO_LAYER_FX = "hueRotate, glow, audioReact, vibration, chromaticAberration, pixelate, rgbShift, " +
+    "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, 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, " +
+    "cellVoronoi, polarSlitScan, spectralZones, audioReact";
+// Binding source vocabulary (sourceKey string form OR a ModSource object).
+const VIDEO_BIND_SOURCES = "Pass `source` as a sourceKey string: " +
+    "`g:<id>` global (level, bandLow, bandMid, bandHigh, transient, transientLow, " +
+    "transientMid, transientHigh, bpm, spectralCentroid, spectralFlux, stereoWidth, " +
+    "varyActivity, phraseLevel, phraseBass, looperBus, masterOnsetLow/Mid/High, " +
+    "masterStereoWidth, masterPanScalar, masterFullMix, masterCompressorGR, " +
+    "sidechainLevel, sidechainEnv); " +
+    "`t:<phase>` transport (beat, bar, phrase); " +
+    "`c:<cell>:<field>` per-cell (level, envFollow, pulse, onset, spectrumPeak, " +
+    "spectrumCentroid, pitch, postFaderL/R, samplerRMSL/R, synthRMS, beatPosition, " +
+    "activeRetriggers, grainActivity, grainPos, grainSpread, grainPitch, " +
+    "grainPitchSpread, grainReverseRatio); " +
+    "`l:<track>:level` looper; `lf:<lfo>:rate|phase` LFO; " +
+    "`p:<paramId>` any DAW param (e.g. p:macro_1). Or a structured object e.g. " +
+    "{kind:'cell',cellIndex:1,field:'onset'}.";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function getVideoStateRaw() {
+    const r = await bridge.send("getVideoState");
+    return (typeof r === "string" ? JSON.parse(r) : r) ?? {};
+}
+const sendVideoCommand = (command) => bridge.send("videoCommand", command);
+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;
+    }
+    return null;
+}
+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, 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 () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const state = await getVideoStateRaw();
+    return json(state);
+});
+server.registerTool("capture_ui", {
+    title: "Capture UI Screenshot",
+    description: "Render PAM's plugin UI (#app_root) to a PNG via html2canvas and return the saved " +
+        "file path (read it to view the image). Optionally compose the view first: " +
+        "gridSize (1|4|8), mainView (CellGrid|CtrlAll|Envelope|LFO|Vary|Mixer|SongMode|Video|" +
+        "PresetBrowser; omit/null = cell grid), instrumentView ('synth'|'sampler', applied to " +
+        "all cells). REQUIRES PAM's window OPEN — html2canvas needs the live DOM, there is no " +
+        "headless renderer (same constraint as the video tools). Beats screen-capture: " +
+        "deterministic, no cursor/screen control, exact UI bitmap.",
+    inputSchema: {
+        gridSize: z.number().optional().describe("Cell grid size to set before capture: 1, 4, or 8."),
+        mainView: z
+            .string()
+            .optional()
+            .describe("Main view to switch to before capture (CellGrid, Mixer, LFO, …). Omit for the cell grid."),
+        instrumentView: z
+            .enum(["synth", "sampler"])
+            .optional()
+            .describe("Switch all cells to the synth or sampler tab before capture."),
+        settleMs: z.number().optional().describe("Delay (ms) after view changes before rasterizing. Default 350."),
+        timeoutMs: z.number().optional().default(8000).describe("Max ms to wait for the WebView to return the image."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ gridSize, mainView, instrumentView, settleMs, timeoutMs }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const requestId = `ui-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+    const setup = { requestId };
+    if (typeof gridSize === "number")
+        setup.gridSize = gridSize;
+    if (mainView !== undefined)
+        setup.mainView = mainView;
+    if (instrumentView !== undefined)
+        setup.instrumentView = instrumentView;
+    if (typeof settleMs === "number")
+        setup.settleMs = settleMs;
+    // Forward is fire-and-forget; poll the C++ cache until the WebView posts the PNG back.
+    await bridge.send("captureUi", setup);
+    const deadline = Date.now() + (timeoutMs ?? 8000);
+    for (;;) {
+        const res = (await bridge.send("getUiCapture", { requestId }));
+        if (res.ready && res.requestId === requestId && res.path) {
+            return text(`Saved UI screenshot: ${res.path}`);
+        }
+        if (Date.now() > deadline) {
+            return error("capture_ui timed out waiting for the WebView to return the image. Is PAM's window " +
+                "open and active? html2canvas needs the live DOM — a closed/suspended editor cannot render.");
+        }
+        await new Promise((r) => setTimeout(r, 150));
+    }
+});
+server.registerTool("video_command", {
+    title: "Video Command (advanced)",
+    description: "Escape hatch to the full video command router — pass any { op, ...args } object. " +
+        "Use the dedicated tools (add_video_layer, set_video_fx, bind_video_param, …) when " +
+        "one fits; this reaches everything else. Ops: " +
+        "addLayer{kind,name?,insertAt?}, removeLayer{layerId}, updateLayer{layerId,patch}, " +
+        "moveLayer{layerId,toIndex}, duplicateLayer{layerId}, renameLayer{layerId,name}, " +
+        "setLayerEnabled{layerId,enabled?}, toggleSolo{layerId}, selectLayer{layerId}, " +
+        "resetLayer{layerId}, applyLayout{preset}, randomizeLayer{layerId}; " +
+        "addLayerFx{layerId,fxType,params?,beforeFxId?}, removeLayerFx{layerId,fxId}, " +
+        "removeAllLayerFx{layerId}, setLayerFxParam{layerId,fxId,param,value|params}, " +
+        "setLayerFxEnabled{layerId,fxId,enabled?}, reorderLayerFx{layerId,fxIds}, " +
+        "resetLayerFx{layerId,fxId}; bind{layerId,fxId?,paramKey,source,...}, " +
+        "unbind{layerId,fxId?,paramKey}, setBindingField{layerId,fxId?,paramKey,field,value}, " +
+        "fireImpulse{layerId,fxId?,paramKey}, removeBindingsForLayer{layerId}, clearBindings; " +
+        "addOutputFx{fxId}, removeOutputFx{instanceId}, setOutputFxParam{instanceId|fxId,param,value}, " +
+        "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{...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: {
+        command: z
+            .record(z.string(), z.any())
+            .describe("The command object. Must include a string `op` field."),
+    },
+}, async ({ command }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand(command);
+    return json(result);
+});
+server.registerTool("add_video_layer", {
+    title: "Add Video Layer",
+    description: "Add a layer to the VX scene and return its id. Kinds: video, image, camera, " +
+        "text, drawing, model3d, adjustment (adjustment = full-canvas FX only; master is a " +
+        "managed singleton and cannot be added). After adding, set its source/props with " +
+        "update_video_layer and stack FX with add_video_fx.",
+    inputSchema: {
+        kind: z
+            .enum(["video", "image", "camera", "text", "drawing", "model3d", "adjustment"])
+            .describe("Layer kind."),
+        name: z.string().optional().describe("Display name (auto-generated if omitted)."),
+        insertAt: z
+            .number()
+            .int()
+            .optional()
+            .describe("Data-index to insert at (default: top of stack)."),
+        sourcePath: z
+            .string()
+            .optional()
+            .describe("Absolute file path to image/video/model media to load into the new layer (no file picker). " +
+            "Bytes are read natively and handed to the WebView as a blob. Large videos are bounded by maxBytes."),
+        maxBytes: z
+            .number()
+            .optional()
+            .describe("Max bytes to read for sourcePath (default ~16MB; raise for video, e.g. 50000000)."),
+    },
+}, async ({ kind, name, insertAt, 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));
+    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).`);
+});
+server.registerTool("update_video_layer", {
+    title: "Update Video Layer",
+    description: "Update a layer's common props and/or kind-specific fields. transform is merged " +
+        "(partial) against the current transform; other fields replace. Common: opacity " +
+        "(0..1), blendMode (normal|add|multiply|screen), enabled, name, transform " +
+        "{x,y(0..1),scale,rotation(rad),anchor}. Kind-specific via `fields`: text layers " +
+        "{text,fontSize,fontWeight,color,align,lineHeight}; image/video/model3d {sourcePath,fit}; " +
+        "camera {deviceId,mirror,fit}; drawing {paintColor,paintWidth}; model3d " +
+        "{lightingMode,lightIntensity,rotateRateX/Y/Z,...}. Use get_video_state to see a " +
+        "layer's current fields.",
+    inputSchema: {
+        layerId: z.string().describe("Target layer id (from get_video_state)."),
+        opacity: z.number().min(0).max(1).optional(),
+        blendMode: z.enum(["normal", "add", "multiply", "screen"]).optional(),
+        enabled: z.boolean().optional(),
+        name: z.string().optional(),
+        transform: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Partial transform: {x?,y?,scale?,rotation?,anchor?}. Merged."),
+        fields: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Kind-specific fields (text, sourcePath, fit, fontSize, color, …)."),
+    },
+}, async ({ layerId, opacity, blendMode, enabled, name, transform, fields }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const patch = { ...(fields ?? {}) };
+    if (opacity !== undefined)
+        patch.opacity = opacity;
+    if (blendMode !== undefined)
+        patch.blendMode = blendMode;
+    if (enabled !== undefined)
+        patch.enabled = enabled;
+    if (name !== undefined)
+        patch.name = name;
+    if (transform !== undefined)
+        patch.transform = transform;
+    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.",
+    inputSchema: { layerId: z.string().describe("Layer id to remove.") },
+    annotations: { destructiveHint: true },
+}, async ({ layerId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand({ op: "removeLayer", layerId });
+    return json(result);
+});
+server.registerTool("apply_video_layout", {
+    title: "Apply Video Layout",
+    description: "Arrange the spatial layers with a layout preset: centered (stacked), grid, " +
+        "columns, rows, or focus (one large + thumbnail strip). adjustment and master " +
+        "layers are untouched.",
+    inputSchema: {
+        preset: z.enum(["centered", "grid", "columns", "rows", "focus"]).describe("Layout preset."),
+    },
+}, async ({ preset }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand({ op: "applyLayout", preset });
+    return json(result);
+});
+server.registerTool("add_video_fx", {
+    title: "Add Video FX",
+    description: "Append an FX to a layer's chain (target='layer', needs layerId) or to the output/" +
+        "global chain (target='output'), and return the new id. Per-layer FX: " +
+        VIDEO_LAYER_FX +
+        ". Output FX: " +
+        VIDEO_OUTPUT_FX +
+        ". FX params seed from registry defaults; override via `params`. Use set_video_fx " +
+        "to tweak afterwards.",
+    inputSchema: {
+        target: z.enum(["layer", "output"]).default("layer").describe("Which chain."),
+        layerId: z.string().optional().describe("Required when target='layer'."),
+        fxType: z.string().describe("FX id (see the per-layer / output id lists)."),
+        params: z
+            .record(z.string(), z.number())
+            .optional()
+            .describe("Optional initial param overrides {paramKey: value}."),
+        beforeFxId: z
+            .string()
+            .optional()
+            .describe("Insert before this fx id instead of appending (layer target only)."),
+    },
+}, async ({ target, layerId, fxType, params, beforeFxId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (target === "output") {
+        const before = await getVideoStateRaw();
+        const beforeIds = new Set((before.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))
+                await sendVideoCommand({ op: "setOutputFxParam", instanceId: id, param, value });
+        return text(id ? `Added output FX ${fxType}: ${id}` : `Added output FX ${fxType} (confirm via get_video_state).`);
+    }
+    if (!layerId)
+        return error("add_video_fx: layerId is required when target='layer'.");
+    const before = await getVideoStateRaw();
+    const layer = (before.layers ?? []).find((l) => l.id === layerId);
+    const beforeIds = new Set((layer?.fx ?? []).map((f) => f.id));
+    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", {
+    title: "Set Video FX",
+    description: "Set FX params / enabled / strength on a per-layer FX (target='layer', needs " +
+        "layerId + fxId) or an output FX (target='output', needs instanceId, or fxId to " +
+        "auto-create). Pass a single {param,value}, multiple {params}, `enabled`, and/or " +
+        "`strength` (output only). Get current ids/params from get_video_state.",
+    inputSchema: {
+        target: z.enum(["layer", "output"]).default("layer"),
+        layerId: z.string().optional().describe("target='layer': owning layer id."),
+        fxId: z.string().optional().describe("Layer fx id, or output fxId (auto-creates the output fx)."),
+        instanceId: z.string().optional().describe("target='output': the output fx instance id."),
+        param: z.string().optional().describe("Single param key to set."),
+        value: z.number().optional().describe("Value for `param`."),
+        params: z.record(z.string(), z.number()).optional().describe("Multiple params {key: value}."),
+        enabled: z.boolean().optional().describe("Enable/bypass this FX."),
+        strength: z.number().optional().describe("Output FX wet strength (output target only)."),
+    },
+}, async ({ target, layerId, fxId, instanceId, param, value, params, enabled, strength }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const results = [];
+    if (target === "layer") {
+        if (!layerId || !fxId)
+            return error("set_video_fx: layerId and fxId required for target='layer'.");
+        if (param !== undefined && value !== undefined)
+            results.push(await sendVideoCommand({ op: "setLayerFxParam", layerId, fxId, param, value }));
+        if (params)
+            results.push(await sendVideoCommand({ op: "setLayerFxParam", layerId, fxId, params }));
+        if (enabled !== undefined)
+            results.push(await sendVideoCommand({ op: "setLayerFxEnabled", layerId, fxId, enabled }));
+    }
+    else {
+        if (param !== undefined && value !== undefined)
+            results.push(await sendVideoCommand({ op: "setOutputFxParam", instanceId, fxId, param, value }));
+        if (params)
+            for (const [p, v] of Object.entries(params))
+                results.push(await sendVideoCommand({ op: "setOutputFxParam", instanceId, fxId, param: p, value: v }));
+        if (enabled !== undefined && instanceId)
+            results.push(await sendVideoCommand({ op: "setOutputFxEnabled", instanceId, enabled }));
+        if (strength !== undefined && instanceId)
+            results.push(await sendVideoCommand({ op: "setOutputFxStrength", instanceId, strength }));
+    }
+    if (results.length === 0)
+        return error("set_video_fx: nothing to set (provide param/value, params, enabled, or strength).");
+    return json({ applied: results.length });
 });
-server.registerTool("list_visuals", {
-    title: "List Visuals",
-    description: "List all visual/thumbnail files in PAM's media library. " +
-        "Returns name, relative path, MIME type, size, and modification time for each visual.",
+server.registerTool("remove_video_fx", {
+    title: "Remove Video FX",
+    description: "Remove an FX from a layer chain (target='layer' + layerId + fxId) or the output " +
+        "chain (target='output' + instanceId).",
     inputSchema: {
-        scope: z
-            .enum(["user", "factory", "all"])
-            .optional()
-            .default("user")
-            .describe("Which library to list: 'user' (default), 'factory', or 'all'."),
+        target: z.enum(["layer", "output"]).default("layer"),
+        layerId: z.string().optional(),
+        fxId: z.string().optional().describe("target='layer': fx id on the layer."),
+        instanceId: z.string().optional().describe("target='output': output fx instance id."),
     },
-}, async ({ scope }) => {
+    annotations: { destructiveHint: true },
+}, async ({ target, layerId, fxId, instanceId }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = await bridge.send("listVisuals", scope);
-    if (Array.isArray(result)) {
-        if (result.length === 0)
-            return text("No visuals found.");
-        const lines = result.map((v) => `- ${v.name} (${v.mime}, ${v.size} bytes) → ${v.path}`);
-        return text(`Found ${result.length} visual(s):\n${lines.join("\n")}`);
+    if (target === "layer") {
+        if (!layerId || !fxId)
+            return error("remove_video_fx: layerId and fxId required for target='layer'.");
+        return json(await sendVideoCommand({ op: "removeLayerFx", layerId, fxId }));
     }
-    return json(result);
+    if (!instanceId)
+        return error("remove_video_fx: instanceId required for target='output'.");
+    return json(await sendVideoCommand({ op: "removeOutputFx", instanceId }));
 });
-server.registerTool("delete_visual", {
-    title: "Delete Visual",
-    description: "Delete a visual file from PAM's user media library. " +
-        "Only files in the user media folder can be deleted (not factory visuals).",
+server.registerTool("bind_video_param", {
+    title: "Bind Video Param (audio-reactive)",
+    description: "Bind a per-layer FX param or layer field to an audio/transport source so it reacts " +
+        "to the music. Omit fxId (or pass '') to target a layer field: transform.x, " +
+        "transform.y, transform.scale, transform.rotation, opacity, hue, brightness, " +
+        "contrast, saturation, playbackRate, fontSize, pulseAmount, or model3d fields. " +
+        "Pass fxId to target an FX param (param key from that FX). " +
+        VIDEO_BIND_SOURCES +
+        " amount is -1..1; curve linear|exp|expInverse|bipolar; mode additive|replace|" +
+        "multiply|centered; impulse off|pulse|latch (one-shot on threshold crossing). " +
+        "attack/release default per-source if omitted.",
     inputSchema: {
-        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
+        layerId: z.string().describe("Target layer id."),
+        paramKey: z.string().describe("FX param key, or layer field (e.g. transform.scale, opacity)."),
+        source: z
+            .union([z.string(), z.record(z.string(), z.any())])
+            .describe("sourceKey string (e.g. 'g:bandLow', 'c:1:onset', 't:beat') or ModSource object."),
+        fxId: z.string().optional().describe("FX instance id; omit/'' for a layer-field target."),
+        amount: z.number().min(-1).max(1).optional().describe("Modulation depth (-1..1), default 1."),
+        curve: z.enum(["linear", "exp", "expInverse", "bipolar"]).optional(),
+        mode: z.enum(["additive", "replace", "multiply", "centered"]).optional(),
+        attackMs: z.number().min(0).optional(),
+        releaseMs: z.number().min(0).optional(),
+        threshold: z.number().min(0).max(1).optional().describe("Gate / impulse trigger level."),
+        impulse: z.enum(["off", "pulse", "latch"]).optional(),
     },
-    annotations: { destructiveHint: true },
-}, async ({ path: relativePath }) => {
+}, async ({ layerId, paramKey, source, fxId, amount, curve, mode, attackMs, releaseMs, threshold, impulse }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = await bridge.send("deleteVisual", relativePath);
-    if (typeof result === "string" && result.includes("error"))
-        return error(`Failed to delete visual: ${relativePath}`);
-    return text(`Deleted visual: ${relativePath}`);
+    const result = await sendVideoCommand({
+        op: "bind",
+        layerId,
+        fxId: fxId ?? "",
+        paramKey,
+        source,
+        amount,
+        curve,
+        mode,
+        attackMs,
+        releaseMs,
+        threshold,
+        impulse,
+    });
+    return json(result);
 });
-server.registerTool("get_visual_data_url", {
-    title: "Get Visual Data URL",
-    description: "Read a visual file from PAM's media library and return it as a base64 data URL. " +
-        "Useful for previewing or inspecting visual content.",
+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 " +
+        "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: {
-        path: z.string().describe("Relative path to the visual (as returned by list_visuals or set_visual)."),
-        maxBytes: z
+        syncMode: z.enum(["off", "beat-sync", "beat-match"]).optional(),
+        loopBars: z.number().optional(),
+        aspectRatio: z.enum(["auto", "16:9", "4:3", "1:1", "stretch"]).optional(),
+        renderQuality: z.enum(["low", "medium", "high"]).optional(),
+        designAspect: z.number().nullable().optional(),
+        letterboxColor: z.string().optional(),
+        canvasColor: z.string().optional(),
+        modEnabled: z.boolean().optional().describe("Mod-matrix master enable."),
+        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()
-            .default(5242880)
-            .describe("Maximum file size in bytes (default 5MB). Files exceeding this are rejected."),
+            .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 ({ path: relativePath, maxBytes }) => {
+}, async ({ syncMode, loopBars, aspectRatio, renderQuality, designAspect, letterboxColor, canvasColor, modEnabled, vxVariationFollowAudio, vxBarSyncEnabled, vxBarSyncIntervalBars, activeCell, resetWorkspace }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = (await bridge.send("getVisualDataUrl", relativePath, maxBytes));
-    return text(`Visual: ${result.path} (${result.mime}, ${result.size} bytes)\nData URL: ${result.dataUrl}`);
+    if (resetWorkspace)
+        await sendVideoCommand({ op: "resetWorkspace" });
+    if (activeCell !== undefined)
+        await sendVideoCommand({ op: "setActiveCell", cellId: activeCell });
+    if (modEnabled !== undefined)
+        await sendVideoCommand({ op: "setModEnabled", enabled: modEnabled });
+    const settings = {};
+    if (syncMode !== undefined)
+        settings.syncMode = syncMode;
+    if (loopBars !== undefined)
+        settings.loopBars = loopBars;
+    if (aspectRatio !== undefined)
+        settings.aspectRatio = aspectRatio;
+    if (renderQuality !== undefined)
+        settings.renderQuality = renderQuality;
+    if (designAspect !== undefined)
+        settings.designAspect = designAspect;
+    if (letterboxColor !== undefined)
+        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("import_visual_folder", {
-    title: "Import Visual Folder",
-    description: "Bulk-import all valid visual files from a folder into PAM's user media library. " +
-        "The import runs asynchronously; this tool returns immediately once the import is queued.",
+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: {
-        folderPath: z.string().describe("Absolute path to the folder containing visual files to import."),
-        operationId: z
-            .string()
+        op: z.enum(["save", "load", "clear", "fill"]).describe("Slot operation."),
+        index: z
+            .number()
+            .int()
+            .min(0)
+            .max(7)
             .optional()
-            .describe("Optional operation ID for tracking import progress."),
+            .describe("Slot index 0-7 (required for save/load/clear; ignored for fill)."),
     },
-}, async ({ folderPath, operationId }) => {
+}, async ({ op, index }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = (await bridge.send("importVisualFolder", folderPath, operationId ?? ""));
-    return text(`Import queued for: ${result.folderPath}` +
-        (result.operationId ? ` (operationId: ${result.operationId})` : ""));
+    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
@@ -1446,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"),
@@ -1479,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}_`;
@@ -1579,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"),
@@ -1611,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)."),
     },
@@ -1620,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}`] = [];
@@ -1646,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)
@@ -1664,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)."),
@@ -1674,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."),
@@ -1695,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)) {
@@ -1704,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;
@@ -1720,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. " +
@@ -1732,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)."),
@@ -1747,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;
@@ -1765,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;
@@ -1774,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(", ");
@@ -1813,8 +3888,8 @@ server.registerTool("set_drum_synth", {
         "sample for a pure synth voice, or layer over a sample. Each engine reinterprets the 8 generic params (p1..p8); pass " +
         "only the ones you want to nuance — unspecified params seed to the engine's musical default. Per-engine p-labels: " +
         DRUM_SYNTH_ENGINES.map((e) => `${e.name}=[${e.params.map((p) => p[0]).join(",")}]`).join("; ") + ". " +
-        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled) AND Settings → Experimental → Drum Synth ON. " +
-        "On builds without it, the cell{N}_synthEngine state key is ignored.",
+        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled) — a standard PAM feature, no settings flag. " +
+        "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)."),
@@ -1832,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}`);
@@ -1858,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. " +
@@ -1880,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 = {
@@ -1984,56 +4107,131 @@ server.registerTool("gain_sample", {
     await bridge.send("gainSampleForCell", { cellId, gainDb });
     return text(`Applied ${gainDb > 0 ? "+" : ""}${gainDb} dB to the sample in cell ${cellId}.`);
 });
+// Poll the offline-render status flag until the export completes or times out.
+async function pollExportStatus(maxWaitMs = 180_000, pollMs = 500) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < maxWaitMs) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        const status = (await bridge.send("getExportStatus"));
+        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. " +
-        "Uses the current BPM to calculate duration. Waits for completion and returns the output file path. " +
-        "Use get_audio_info afterwards to analyze the exported file.",
+    description: "Render and export audio from the current preset to a WAV file in PAM's Exports folder. " +
+        "Waits for completion. Default mode renders the looping preset for `bars` bars at the current BPM. " +
+        "Set `mode` to bounce stems or the whole Song Mode arrangement.\n\n" +
+        "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 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("Number of bars to render."),
+        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
             .number()
             .min(1)
             .max(8)
             .optional()
-            .describe("Render only a specific cell in solo. Omit for full mix."),
+            .describe("Render only a specific cell in solo (implies mode 'individual'). Omit for full mix."),
+        mode: z
+            .enum(["main", "individual", "all-cells", "selected-cells", "per-bus", "song-mode"])
+            .optional()
+            .describe("Export mode. Defaults to 'main' (or 'individual' when cellId is set)."),
+        selectedCellIds: z
+            .array(z.number().min(1).max(8))
+            .optional()
+            .describe("For mode 'selected-cells': cells to bounce as stems."),
         bitDepth: z
             .number()
             .default(24)
             .describe("Bit depth (16 or 24)."),
     },
-}, async ({ bars, cellId, bitDepth }) => {
+}, async ({ bars, cellId, mode, selectedCellIds, bitDepth }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const options = { bars, bitDepth };
-    if (cellId)
-        options.cellId = cellId;
-    const startResult = await bridge.send("exportAudio", options);
-    // If bridge returned old-style "ok", it was a pass-through with full options
-    if (typeof startResult === "string") {
-        return text(`Audio export started (${bars} bars, ${bitDepth}-bit).`);
-    }
-    const result = startResult;
-    const outputPath = result.outputPath;
-    const durationSecs = result.durationInSeconds;
-    const bpm = result.bpm;
-    // Poll for completion
-    const maxWaitMs = 120_000;
-    const pollMs = 500;
-    const t0 = Date.now();
-    while (Date.now() - t0 < maxWaitMs) {
-        await new Promise((r) => setTimeout(r, pollMs));
-        const status = (await bridge.send("getExportStatus"));
-        if (status.complete) {
-            if (status.success) {
-                return text(`Audio exported successfully.\nFile: ${outputPath}\n` +
-                    `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)`);
-            }
-            return error(`Audio export failed.`);
+    // Resolve the effective mode. A bare cellId means "individual".
+    const effectiveMode = mode ?? (cellId ? "individual" : "main");
+    // Fast path: main / individual go through the MCP-friendly bridge branch,
+    // which constructs options server-side and returns the output path + duration.
+    if (effectiveMode === "main" || (effectiveMode === "individual" && cellId)) {
+        const options = { bars, bitDepth };
+        if (cellId)
+            options.cellId = cellId;
+        const startResult = await bridge.send("exportAudio", options);
+        if (typeof startResult === "string") {
+            return text(`Audio export started (${bars} bars, ${bitDepth}-bit).`);
         }
+        const result = startResult;
+        const outputPath = result.outputPath;
+        const durationSecs = result.durationInSeconds;
+        const bpm = result.bpm;
+        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)` +
+                loudnessReportLine());
+        if (outcome === "failed")
+            return error("Audio export failed.");
+        return text(`Export timed out. The render may still be running.\nExpected output: ${outputPath}`);
     }
-    return text(`Export timed out after ${maxWaitMs / 1000}s. The render may still be running.\nExpected output: ${outputPath}`);
+    // Stem / song-mode modes: build full pass-through options (filename + mode +
+    // durationInSeconds) so the C++ export handler runs the requested mode directly.
+    if (effectiveMode === "selected-cells" && (!selectedCellIds || selectedCellIds.length === 0))
+        return error("mode 'selected-cells' requires selectedCellIds.");
+    if (effectiveMode === "individual" && !cellId)
+        return error("mode 'individual' requires cellId.");
+    const transport = (await bridge.send("getTransport"));
+    const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
+    // 4/4 assumption for the placeholder duration; 'song-mode' recomputes its own length from the timeline.
+    const durationInSeconds = (bars * 4 * 60) / bpm;
+    const filename = `pam_export_${effectiveMode.replace(/[^a-z0-9]/gi, "_")}_${Date.now()}`;
+    const options = {
+        filename,
+        mode: effectiveMode,
+        durationInSeconds,
+        bitDepth,
+    };
+    if (cellId)
+        options.selectedCellId = cellId;
+    if (selectedCellIds)
+        options.selectedCellIds = selectedCellIds;
+    await bridge.send("exportAudio", options);
+    const outcome = await pollExportStatus();
+    if (outcome === "success")
+        return text(`Export complete (mode '${effectiveMode}').\n` +
+            `File(s) written to PAM's Exports folder, base name: ${filename}.wav` +
+            loudnessReportLine() +
+            (effectiveMode === "song-mode"
+                ? "\n\nReminder: the offline song-mode bounce captures only the first section's state. " +
+                    "Use export_song for a full track with section changes."
+                : ""));
+    if (outcome === "failed")
+        return error(`Export failed (mode '${effectiveMode}').`);
+    return text(`Export timed out (mode '${effectiveMode}'). The render may still be running.`);
 });
 // ============================================================
 // RESOURCES
@@ -2145,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
@@ -2426,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.
@@ -3037,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",
@@ -3051,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."),
@@ -3064,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()
@@ -3089,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");
@@ -3126,6 +5553,178 @@ server.registerTool("song_mode", {
     }
     return text("No-op");
 });
+server.registerTool("export_song", {
+    title: "Export Song (Full Track)",
+    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
+            .number()
+            .min(1)
+            .max(64)
+            .describe("Total arrangement length in bars (the full timeline). Required for 'live'."),
+        cellId: z
+            .number()
+            .min(1)
+            .max(8)
+            .optional()
+            .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 legacy cell-capture 'live': extra bars captured after the arrangement end for tails."),
+    },
+}, async ({ strategy, bars, cellId, includeVideo, name, normalize, encoderId, bitDepth, tailBars }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // -------- 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) — 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 (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.");
+    }
+    // -------- 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);
+    if (totalBars > 64)
+        return error(`Total capture (${totalBars} bars incl. tail) exceeds the 64-bar live cap. Bounce in sections.`);
+    const captureSeconds = (totalBars * 4 * 60) / bpm;
+    // Reset playhead to the top so the arrangement starts at section 1, enable Song
+    // Mode, then roll the transport and capture the full master mix.
+    await bridge.send("fullStopTransport");
+    await bridge.send("toggleSongMode", true);
+    await bridge.send("setSongModePlayhead", 0);
+    await bridge.send("startTransport");
+    await bridge.send("resampleGraphToCell", JSON.stringify({ cellId, bars: totalBars, live: true, captureSource: 2, cellOnly: false }));
+    // Wait out the arrangement (plus a small safety margin), then stop + finalize.
+    await new Promise((r) => setTimeout(r, captureSeconds * 1000 + 1500));
+    await bridge.send("stopLiveResample", true);
+    await bridge.send("stopTransport");
+    // Read the captured clip path back off the destination cell.
+    let capturedPath = "(unknown — check PAM's Resamples folder)";
+    try {
+        const state = (await bridge.send("getState"));
+        const cells = state.cells;
+        const fp = cells?.[String(cellId)]?.filePath;
+        if (typeof fp === "string" && fp.length > 0)
+            capturedPath = fp;
+    }
+    catch {
+        // fall through with the placeholder
+    }
+    return text(`Live song bounce complete (${bars} bars + ${tailBars ?? 1} tail @ ${bpm} BPM, ${bitDepth}-bit).\n` +
+        `Captured into cell ${cellId}.\nClip: ${capturedPath}\n` +
+        "Resolve the absolute path against the Resamples location from get_default_locations, then verify with get_audio_info.");
+});
 // ============================================================
 // TOOLS — Metronome
 // ============================================================
@@ -3290,8 +5889,12 @@ server.registerTool("export_slice", {
 // ============================================================
 server.registerTool("live_resample", {
     title: "Live Resample",
-    description: "Capture PAM's audio graph output into a cell as a new sample. Ops: 'start' / 'stop'. " +
-        "Transport must be playing for the capture to produce audio.",
+    description: "Capture PAM's audio graph output into a cell as a new sample, in real time. Ops: 'start' / 'stop'. " +
+        "Transport MUST be playing for the capture to produce audio. Because the capture runs live, " +
+        "Song Mode section changes, modulation, and variation switches are all captured faithfully — " +
+        "this is the building block for full-track / Song Mode bounces (see export_song).\n\n" +
+        "`source` selects what to record: 'cell' (the destination cell's own output), 'input' (PAM's audio input), " +
+        "or 'fullmix' (the whole master mix — use this to bounce the entire arrangement).",
     inputSchema: {
         op: z.enum(["start", "stop"]).describe("Operation."),
         cellId: z
@@ -3299,13 +5902,21 @@ server.registerTool("live_resample", {
             .min(1)
             .max(8)
             .optional()
-            .describe("For 'start': destination cell."),
+            .describe("For 'start': destination cell the captured clip lands in. Use an empty/scratch cell for a full-mix bounce."),
         bars: z
             .number()
             .min(0.125)
             .max(64)
             .optional()
-            .describe("For 'start': capture length in bars."),
+            .describe("For 'start': capture length in bars (max 64; the capture also stops on the 'stop' op)."),
+        source: z
+            .enum(["cell", "input", "fullmix"])
+            .default("cell")
+            .describe("For 'start': capture source. 'fullmix' records the entire master output (the whole song)."),
+        normalize: z
+            .boolean()
+            .default(false)
+            .describe("For 'start': peak-normalize the captured clip after recording."),
         finalize: z
             .boolean()
             .default(true)
@@ -3318,8 +5929,19 @@ server.registerTool("live_resample", {
     if (args.op === "start") {
         if (typeof args.cellId !== "number" || typeof args.bars !== "number")
             return error("'start' requires cellId + bars");
-        await bridge.send("resampleGraphToCell", JSON.stringify({ cellId: args.cellId, bars: args.bars }));
-        return text(`Started live resample → cell ${args.cellId} (${args.bars} bars).`);
+        const source = args.source ?? "cell";
+        const captureSource = source === "fullmix" ? 2 : source === "input" ? 1 : 0;
+        await bridge.send("resampleGraphToCell", JSON.stringify({
+            cellId: args.cellId,
+            bars: args.bars,
+            live: true,
+            captureSource,
+            // For a full-mix / input bounce the destination cell must NOT be soloed,
+            // or we'd only capture that one (empty) cell.
+            cellOnly: source === "cell",
+            normalize: args.normalize ?? false,
+        }));
+        return text(`Started live resample → cell ${args.cellId} (${args.bars} bars, source '${source}').`);
     }
     await bridge.send("stopLiveResample", args.finalize ?? true);
     return text(`Stopped live resample (finalize=${args.finalize ?? true}).`);
@@ -3359,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.
@@ -3405,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);
@@ -3421,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",
@@ -3477,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",
@@ -3495,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",
@@ -3507,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();
@@ -3523,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);
 });
@@ -3592,14 +6236,15 @@ server.registerTool("update_settings", {
     title: "Update Plugin Settings",
     description: "Merge a partial settings delta into PAM's plugin settings (the Settings panel state) and apply it live. " +
         "Returns the full merged settings object so you can discover available keys. This is the only way to flip " +
-        "experimental-feature gates from an agent. Common boolean keys: experimentalMode, experimentalDrumSynth, " +
-        "experimentalPluginHost, experimentalMcpBridge. To enable the drum synth or plugin host, set BOTH " +
-        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true) in one call. Other keys " +
+        "experimental-feature gates from an agent. Common boolean keys: experimentalMode, " +
+        "experimentalPluginHost, experimentalMcpBridge. To enable the plugin host, set BOTH " +
+        "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true) in one call. " +
+        "The drum synth needs no flag — it is a standard feature on PAM. Other keys " +
         "include UI/library preferences — call get_state or inspect the returned object for the current set.",
     inputSchema: {
         settings: z
             .record(z.string(), z.any())
-            .describe("Partial settings object to merge. Example: { experimentalMode: true, experimentalDrumSynth: true }"),
+            .describe("Partial settings object to merge. Example: { experimentalMode: true, experimentalPluginHost: true }"),
     },
 }, async ({ settings }) => {
     const check = await requireBridge();
@@ -3704,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."),
@@ -3878,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)