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

package/dist/server.js

@@ -4,23 +4,29 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { z } from "zod";
 import { buildVariationSnapshotBase } from "./generated/variationSnapshot.js";
+import { CELL_CONFIG_KV_OPTIONS, EFFECT_CONFIG_KV_OPTIONS, MASTER_CONFIG_KV_OPTIONS, PATTERN_EDIT_KV_OPTIONS, STATE_UPDATE_KV_OPTIONS, } from "./generated/kvWriteOptions.js";
 import { CORPUS_META, CORPUS_RANGES } from "./corpusRanges.js";
 import { CORPUS_FINGERPRINTS, CORPUS_NOVELTY_BASELINE, CORPUS_VARIATION_BASELINE } from "./corpusFingerprints.js";
 import { buildFingerprint, scoreNovelty, similarity as fingerprintSimilarity } from "./fingerprint.js";
 import { analyzeMotion, decodeWav } from "./audioAnalysis.js";
-import { readFile } from "node:fs/promises";
-import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { inflateSync } from "node:zlib";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createDrumSynthCatalog, } from "./drumSynth.js";
 import { loadManifest, cellEffectNames, cellEffectOrder, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
 import { PluginBridge } from "./bridge.js";
+import { LANE_TARGET_FIELD, PATTERN_LANE_IDS, PATTERN_LANE_SUFFIX, CC_LANES, PARAM_LANES, ccLaneMayLand, ccLaneIndex, ccLaneSlotField, ccLaneSlotOf, CC_OUT_CONFIG_KEYS, CC_OUT_SLOTS, isCcLane, isCcOutValueSuffix, isParamLane, normalizeCcLaneEvents, normalizeTargetLaneEvents, productHasLane, resolveLaneTarget, } from "./patternLanes.js";
 import { buildMixMeasurementFromState, currentFlatFromState, parseMixAnalysisPayload, suggestMix, } from "./mixAssist.js";
-import { normalizePresetLookupPath, selectSaveVariationSourcePath, } from "./presetSave.js";
+import { isFactoryPresetPath, nativePresetPath, normalizePresetLookupPath, parsePresetFile, selectSaveVariationSourcePath, } from "./presetSave.js";
 import { STOP_SEQUENCES, buildGenerationPrompt, parseFunctionCalls, renderContextLine, renderFunctionCall, renderFunctionResponse, truncateAtFabricatedResponse, withContext, } from "./fgemma-format.js";
 import { mcpProductProfile } from "./productProfile.js";
 import { MFX_COMBO_COUNT, MFX_COMBO_MANUAL_STRENGTH, buildMfxComboTarget, isMfxComboTargetParameter, mfxComboTargetValueFromCurrent, parseMfxComboSlots, reanchorMfxComboTarget, resolveMfxCombos, setMfxComboTargetStop, } from "./mfxCombos.js";
+import { GENERATIVE_PLAYERS, LISTEN_MODES, MODULATABLE_PLAYER_FIELDS, NO_POLY_ARM, PATTERN_MODES, PLAYER_GENRES, PLAYER_NAMES, PLAYER_SLOT_FIELDS, cellPlayerType, describeCellPlayer, describePlayerSpec, getPlayerSpec, isMelodicPlayer, playerDefaultsFor, playerDensityDisplay, playerGenreConfig, playerMutateDisplay, playerPresetsFor, playerSlotDisplay, presetConfig, randomPlayerSeed, resolvePlayerPreset, resolvePlayerSpec, resolveSlotValue, rolePlayerConfigFor, roleSpreadSummary, snapPlayerValue, } from "./players.js";
+import { buildMidiFile, patternSpeedMultiplier, tilePatternEvents } from "./midiFile.js";
+import { MAX_SLICES, detectOnsetBoundaries, equalBoundaries, normalizeBoundaries } from "./sampleSlicing.js";
 // --- State ---
 // Variation slot count. Must stay in sync with PRESET_VARIATION_SLOTS in
 // interface/src/stores/Preset.ts. Defined locally because the MCP package
@@ -74,7 +80,56 @@ function isMfxManifest(manifest) {
         manifest.bundleId?.toLowerCase() === "map.audio.mfx" ||
         manifest.pluginCode?.toLowerCase() === "amfx");
 }
+// MSQ sequences MIDI only. These tools drive a part of PAM it does not have, so on an
+// MSQ instance they answer with the reason instead of writing state nothing reads.
+const MSQ_MISSING_BY_TOOL = new Map([
+    ...[
+        "load_sample", "randomize_samples", "trim_sample", "reverse_sample", "normalize_sample", "gain_sample",
+        "analyze_sample_pitch", "repitch_sample", "analyze_sample_tempo", "get_sample_peaks", "preview_slice",
+        "resample_sample_to_bpm", "restore_original_sample", "build_sample_chain", "export_slice", "set_slices",
+        "preview_sample", "get_sample_usage", "repair_preset_samples", "set_drum_synth", "set_drum_synth_wave",
+        "set_lane_target",
+    ].map((tool) => [tool, "sampler"]),
+    ...["update_effect_config", "set_effect_order"].map((tool) => [tool, "cell effects"]),
+    ...["set_master_effects", "get_master_analysis", "get_mix_analysis", "suggest_mix", "set_metronome"].map((tool) => [tool, "audio output"]),
+    ...["export_audio", "export_song", "song_mode", "live_resample"].map((tool) => [tool, "audio render or Song Mode"]),
+    ...[
+        "arm_looper_track", "set_looper_track", "clear_looper_track", "set_looper_track_selection",
+        "start_looper_recording", "stop_looper_recording", "capture_looper_now", "load_audio_to_looper_track",
+        "request_looper_warp", "looper_settings", "looper_variation", "looper_variation_sync",
+    ].map((tool) => [tool, "looper"]),
+    ...[
+        "set_visual", "list_visuals", "delete_visual", "get_visual_data_url", "import_visual_folder", "get_video_state",
+        "video_command", "add_video_layer", "update_video_layer", "set_video_layer_source", "remove_video_layer",
+        "apply_video_layout", "add_video_fx", "set_video_fx", "remove_video_fx", "bind_video_param", "set_video_settings",
+        "vx_variation", "analyze_motion",
+    ].map((tool) => [tool, "VX video engine"]),
+    ...[
+        "list_plugins", "scan_plugins", "cancel_plugin_scan", "get_plugin_scan_status", "list_loaded_plugins",
+        "load_plugin", "unload_plugin", "set_plugin_param", "set_plugin_params", "set_plugin_bypass",
+        "skip_current_plugin_scan", "remove_plugin_from_blocklist",
+    ].map((tool) => [tool, "plugin host"]),
+    ...[
+        "download_model", "get_model_status", "load_model", "unload_model", "delete_model", "list_models",
+        "generate_sample", "generate_kit", "workbench_get_state", "workbench_set_state", "workbench_render",
+        "workbench_list_takes", "workbench_load_take", "workbench_undo", "workbench_reset_chain",
+        "workbench_sidecar_status", "ask_assistant",
+    ].map((tool) => [tool, "AI stack"]),
+]);
 const MFX_CELL_CONFIG_KEYS = new Set(["sidechainFrom"]);
+// MSQ cells are MIDI tracks: their note, channel, scale and output wiring, never sampler config.
+const MSQ_CELL_CONFIG_KEYS = new Set([
+    "isPoly", "midiNote", "midiChannel", "midiIsolate", "armed", "polyRootNote", "scaleName", "scaleRoot",
+    "midiOutChannel", "sendToHost", "midiOutPort", ...CC_OUT_CONFIG_KEYS, ...CC_LANES.map(ccLaneSlotField),
+]);
+// A CC out slot's controller (cell config ccOutCc{K}); 120-127 are channel-mode messages.
+const ccOutControllerSchema = (slot) => z
+    .number()
+    .int()
+    .min(-1)
+    .max(119)
+    .optional()
+    .describe(`Controller number CC out slot ${slot} sends, -1=Off. Its value is the parameter cell{N}_ccOut${slot} (0-127).`);
 async function loadManifestForProductGuard() {
     try {
         return await loadManifest();
@@ -196,22 +251,6 @@ async function requireBridgeForCells(...cellIds) {
     }
     return true;
 }
-/**
- * Parse the PAM binary preset format: <metadataSize as text int><metadata JSON><data JSON>
- */
-function parsePresetFile(raw) {
-    const sizeMatch = raw.match(/^(\d+)/);
-    if (!sizeMatch)
-        throw new Error("invalid format (no metadata size prefix)");
-    const prefixLen = sizeMatch[1].length;
-    const metadataSize = parseInt(sizeMatch[1], 10);
-    if (metadataSize <= 0 || prefixLen + metadataSize > raw.length) {
-        throw new Error(`invalid format (metadata size ${metadataSize} out of bounds for file length ${raw.length})`);
-    }
-    const metadataStr = raw.slice(prefixLen, prefixLen + metadataSize);
-    const dataStr = raw.slice(prefixLen + metadataSize);
-    return { metadata: JSON.parse(metadataStr), data: JSON.parse(dataStr) };
-}
 // 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.
@@ -241,20 +280,17 @@ function variationsFromParsedPreset(parsed) {
         return Array(PRESET_VARIATION_SLOTS).fill(null);
     return src.map(decompressVariationEntry);
 }
-/**
- * Read existing variations array from a preset file on disk.
- * Returns Array(8) of plain-JSON strings or nulls.
- */
-async function readExistingVariations(presetPath) {
+async function readPresetForSave(presetPath, allowMissing = false) {
+    let fullPath;
     try {
-        const fullPath = await resolvePresetPath(presetPath);
-        const raw = await readFile(fullPath, "utf-8");
-        return variationsFromParsedPreset(parsePresetFile(raw));
+        fullPath = await resolvePresetPath(presetPath);
     }
-    catch {
-        // Preset doesn't exist yet or can't be read — start fresh
-        return Array(PRESET_VARIATION_SLOTS).fill(null);
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return null;
+        throw error;
     }
+    return parsePresetFile(await readFile(fullPath));
 }
 const VARIATION_CONTRACT = (() => {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -294,6 +330,7 @@ const VARIATION_EXCLUDED_PARAMS = [
 function buildVariationString(state) {
     return JSON.stringify(buildVariationSnapshotBase(state, {
         sessionKeys: VARIATION_EXCLUDED_PARAMS,
+        transientKeys: VARIATION_CONTRACT.transientDispatchKeys ?? [],
         visualParamIds: VARIATION_CONTRACT.visualParamIds ?? [],
         lfoGeneratorCount: VARIATION_CONTRACT.lfoGeneratorCount ?? 6,
     }));
@@ -372,12 +409,6 @@ const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
 // Preset listings grow with every installed pack; cap the unfiltered dump so it
 // can't crowd out the agent's context (`search` narrows it).
 const LIST_PRESETS_MAX = 400;
-const PATTERN_LANES = {
-    note: "midiSequence",
-    pitch: "pitchSequence",
-    slice: "sliceSequence",
-    stretch: "stretchSequence",
-};
 const LFO_DIVISIONS = [
     "16 bar", "8 bar", "4 bar", "2 bar", "1 bar",
     "1/2D", "1/2", "1/2T",
@@ -472,6 +503,44 @@ function formatNotModulatableError(paramId, index) {
     const suggestions = suggestParams(paramId, index, { modulatableOnly: true });
     return `Parameter '${paramId}' is not modulatable.${suggestions.length ? ` Try modulatable target ${suggestions.join(", ")}.` : ""}`;
 }
+// Hosted-plugin params exist only while a plugin is loaded, so they resolve against
+// the live instance; the id is the UI's `cell{N}_plugin_{slug(name)}_{index}`.
+const HOSTED_MOD_TARGET_RX = /^cell(\d+)_plugin(Fx)?_[a-z0-9][a-z0-9_]*_(\d+)$/;
+function hostedParamSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 32) || "p";
+}
+function hostedModTargetId(cellId, param, effect = false) {
+    return `cell${cellId}_${effect ? "pluginFx" : "plugin"}_${hostedParamSlug(param.name || param.label || `p${param.index}`)}_${param.index}`;
+}
+/** A manifest param, or a hosted-plugin param checked against the loaded instance; a string is the error. */
+async function resolveModulationTarget(paramId, index) {
+    const param = index.get(paramId);
+    if (param)
+        return param.isModulatable ? param : formatNotModulatableError(paramId, index);
+    const hosted = paramId.match(HOSTED_MOD_TARGET_RX);
+    if (!hosted)
+        return formatUnknownParamError(paramId, index, { modulatableOnly: true });
+    const cellId = Number(hosted[1]);
+    const hostedTarget = { paramId, name: paramId, displayName: paramId, min: 0, max: 1, defaultValue: 0, step: 0.001, skew: 1, isModulatable: true };
+    // list_loaded_plugins covers the instrument slot only; an FX id is taken as named.
+    if (hosted[2])
+        return hostedTarget;
+    let listed;
+    try {
+        listed = (await bridge.send("listLoadedPlugins"));
+    }
+    catch {
+        return `Hosted plugin parameters need a running PAM with the MCP bridge connected (${paramId}).`;
+    }
+    const plugin = listed?.loadedPlugins?.find((p) => Number(p.cellId) === cellId);
+    if (!plugin)
+        return `No hosted instrument plugin is loaded in cell ${cellId}; load one before targeting ${paramId}.`;
+    const entry = plugin.params?.find((p) => Number(p.index) === Number(hosted[3]));
+    if (!entry)
+        return `${plugin.name} in cell ${cellId} has no parameter at index ${hosted[3]}.`;
+    const expected = hostedModTargetId(cellId, { ...entry, index: Number(entry.index) });
+    return expected === paramId ? hostedTarget : `Unknown hosted parameter ${paramId}. Did you mean ${expected}?`;
+}
 function formatRangeError(param, value) {
     const unit = param.suffix ? param.suffix : "unitless";
     const traits = [
@@ -583,17 +652,16 @@ const server = new McpServer({
     version: SERVER_VERSION,
 }, {
     instructions: IS_MFX_SERVER
-        ? "MFX is a four-cell modular FX router. Start with design_context and get_design_overview; " +
-            "use set_mfx_routing for cables, set_effect_order for each chain, and set_parameters or " +
-            "update_effect_config to shape effects. Use cells 1-4 and save finished work with save_preset. " +
-            "Treat tool annotations as authoritative and use select_instance when several products are running."
-        : "PAM is an eight-cell sampler. Start read and design work with design_context and " +
-            "get_design_overview; filter get_state with section, keys, or cellIds. For samples, call " +
-            "get_default_locations before list_samples and load only returned paths; never guess library paths. " +
-            "Sequencer output requires a running transport. UI, video, and visual tools require the plugin " +
+        ? "MFX is a four-cell modular FX router: cells are patched with cables and each cell runs its own effect chain. " +
+            "Use cells 1-4. Treat tool annotations as authoritative and use select_instance when several products are running."
+        : "PAM is an eight-cell sampler. " +
+            "Sequencer notes require a running transport; a cell's CC out slots send whenever their value moves. " +
+            "UI, video, and visual tools require the plugin " +
             "window open; experimental plugin-host and AI tools require experimentalMode plus the matching " +
             "feature flag. Treat tool annotations as authoritative and use select_instance when several " +
-            "products are running. A 'build does not support' error means update the plugin, not only this server.",
+            "products are running. A 'build does not support' error means update the plugin, not only this server. " +
+            "An MSQ instance sequences MIDI only: its cells send notes and CC to the host MIDI out, so sample, effect, " +
+            "master, looper, video, plugin-host and AI tools refuse it.",
 });
 // --- tool annotation policy ---------------------------------------------------
 // Single audit surface for MCP tool annotations. Every tool MUST have an entry;
@@ -624,13 +692,14 @@ const TOOL_ANNOTATIONS = {
     get_design_overview: RO,
     get_transport: RO,
     get_master_analysis: RO,
-    suggest_mix: RO, // pure function over cached analysis + current state
+    suggest_mix: W,
     connection_status: RO,
+    situation: RO,
     list_samples: RO,
     get_default_locations: RO,
     get_audio_info: RO,
     get_video_state: RO,
-    capture_ui: RO, // writes a screenshot file, mutates no plugin state
+    capture_ui: WI,
     get_sample_peaks: RO,
     get_audio_device_setup: RO,
     get_memory_report: RO,
@@ -656,6 +725,7 @@ const TOOL_ANNOTATIONS = {
     reset_patterns: DI,
     update_effect_config: WI,
     update_cell_config: WI,
+    set_lane_target: WI,
     set_cell_mute: WI,
     set_master_effects: WI,
     add_param_seq: W,
@@ -663,6 +733,12 @@ const TOOL_ANNOTATIONS = {
     remove_param_seq: DI,
     set_drum_synth: WI,
     set_drum_synth_wave: WI,
+    list_players: RO,
+    set_player: WI,
+    keep_player: W,
+    set_slices: WI,
+    set_free_sequencer: WI,
+    export_midi: W,
     stop_cell: WI,
     reset_cell: DI,
     copy_cell: DI, // overwrites the destination cell
@@ -680,8 +756,10 @@ const TOOL_ANNOTATIONS = {
     trigger_midi_cc: W,
     trigger_midi_program_change: W,
     midi_recording: W,
+    session_take: W,
     // Presets / variations
     load_preset: DI, // replaces the working state (unsaved edits are lost)
+    get_preset_load_status: RO,
     save_preset: WI,
     new_preset: DI,
     import_preset: WI,
@@ -702,6 +780,8 @@ const TOOL_ANNOTATIONS = {
     trim_sample: W, // restore_original_sample recovers the pre-edit file
     reverse_sample: W,
     gain_sample: W,
+    repitch_sample: W,
+    analyze_sample_pitch: RO,
     normalize_sample: WI,
     analyze_sample_tempo: WI, // dispatches results into state
     resample_sample_to_bpm: WI,
@@ -772,7 +852,7 @@ const TOOL_ANNOTATIONS = {
     set_video_fx: WI,
     remove_video_fx: DI,
     bind_video_param: WI,
-    set_video_settings: WI,
+    set_video_settings: D, // resetWorkspace:true clears the scene
     vx_variation: W,
     // Connection management
     select_instance: WI,
@@ -797,6 +877,7 @@ const MFX_TOOL_NAMES = new Set([
     "get_design_overview",
     "get_transport",
     "connection_status",
+    "situation",
     "get_default_locations",
     "capture_ui",
     "get_memory_report",
@@ -811,6 +892,7 @@ const MFX_TOOL_NAMES = new Set([
     "add_param_seq",
     "update_param_seq",
     "remove_param_seq",
+    "set_free_sequencer",
     "stop_cell",
     "reset_cell",
     "copy_cell",
@@ -821,6 +903,7 @@ const MFX_TOOL_NAMES = new Set([
     "set_metronome",
     "configure_transport",
     "load_preset",
+    "get_preset_load_status",
     "save_preset",
     "new_preset",
     "import_preset",
@@ -834,8 +917,8 @@ const MFX_TOOL_NAMES = new Set([
     "cancel_queued_variation",
     "update_variations",
     "variation_hold",
-    "export_audio",
     "update_settings",
+    "get_audio_device_setup",
     "set_audio_device",
     "set_mfx_routing",
     "set_mfx_edge_gain",
@@ -847,27 +930,182 @@ const MFX_TOOL_NAMES = new Set([
 ]);
 function mfxSurfaceText(value) {
     return value
+        // MFX has its own version line, so a PAM version gate names a build MFX never reaches.
+        .replace(/PAM ?(?:≥|>=) ?\d+(?:\.\d+)*/g, "a current MFX build")
+        .replaceAll("a PAM build", "an MFX build")
+        .replaceAll(" saved via set_visual", "")
+        .replaceAll(" Check corr in get_master_analysis after widening.", "")
+        .replaceAll(" (same constraint as the video tools)", "")
+        .replaceAll("so the preset_novelty scale does", "so a whole-preset novelty scale does")
         .replaceAll("PAM/Cell1-only", "sampler-product-only")
         .replaceAll("PAM/Cell1", "sampler products")
         .replaceAll("PAM-only", "sampler-product-only")
         .replaceAll("PAM's", "MFX's")
         .replaceAll("PAM", "MFX");
 }
+const MFX_MAX_CELL = 4;
+// Copy of syncUtils::kValidBarSyncIntervals (SyncUtils.h); check-parity compares them.
+const LOOPER_BAR_SYNC_INTERVALS = [0.25, 0.5, 1, 2, 4, 8];
+// Zod wrappers are immutable, so narrowing a leaf means rebuilding the
+// optional/default/array/union chain around it and re-attaching the description.
+function rebuildSchema(schema, narrowLeaf) {
+    const def = schema._zod?.def;
+    const keepText = (next) => (schema.description ? next.describe(schema.description) : next);
+    const inner = () => rebuildSchema(def.innerType, narrowLeaf);
+    switch (def?.type) {
+        case "optional":
+            return keepText(inner().optional());
+        case "nullable":
+            return keepText(inner().nullable());
+        case "default":
+            return keepText(inner().default(def.defaultValue));
+        case "array":
+            return keepText(z.array(rebuildSchema(def.element, narrowLeaf)));
+        case "union":
+            return keepText(z.union(def.options.map((option) => rebuildSchema(option, narrowLeaf))));
+        default:
+            return keepText(narrowLeaf(schema));
+    }
+}
+function schemaKind(schema) {
+    return schema._zod?.def?.type;
+}
+const capCellId = (leaf) => schemaKind(leaf) === "number" ? leaf.max(MFX_MAX_CELL) : leaf;
+const dropEnumMembers = (drop) => (leaf) => {
+    if (schemaKind(leaf) !== "enum")
+        return leaf;
+    const entries = leaf._zod.def.entries;
+    const kept = Object.values(entries).filter((value) => !drop.includes(value));
+    return z.enum(kept);
+};
+// MFX ships four cells and the shared schemas advertise PAM's eight. The runtime
+// guard is manifest-driven; this is the advertised half of the same contract.
+const MFX_CELL_FIELDS = new Set([
+    "cellId",
+    "sourceCellId",
+    "targetCellId",
+    "cellIds",
+    "selectedCellIds",
+    "sidechainFrom",
+]);
+// Enum members MFX has no surface for: Vary is removed from its modulation stack,
+// neither song_mode nor a looper tool is registered on this launcher, and the MIDI
+// settings page hides the looper, resample and VX mappings.
+const MFX_ENUM_DROPS = {
+    add_modulation: { type: ["vary"] },
+    update_modulation: { type: ["vary"] },
+    get_state: { section: ["vary", "loopers", "songMode"] },
+    set_midi_mapping: { target: ["looper", "resample", "vxRecord", "looperVariation"] },
+};
+const MFX_KEPT_FIELDS = {
+    update_cell_config: ["cellId", "sidechainFrom"],
+};
+const MFX_DROPPED_FIELDS = {
+    select_instance: ["product"],
+    // MFX cells are effect slots — there is no synth/sampler tab to switch.
+    capture_ui: ["instrumentView"],
+    // MFX processes host input, which an offline render leaves silent.
+    analyze_motion: ["bars"],
+};
+const MFX_TOOL_DESCRIPTIONS = {
+    select_instance: "Choose which running MFX instance the live tools drive. Match by instanceId or port from connection_status. The launcher refuses non-MFX instances.",
+    update_cell_config: "Set one MFX cell's sidechain source. A non-null source also enables that cell's compressor.",
+    capture_ui: "Render MFX's plugin UI (#app_root) to a PNG via html2canvas and return the saved file path (read it to " +
+        "view the image). Optionally compose the view first: gridSize (1 or 4), mainView (CellGrid|MfxRouting|" +
+        "CtrlAll|Envelope|LFO|ParamSeq|Mixer|PresetBrowser; omit/null = cell grid). REQUIRES MFX's window OPEN — " +
+        "html2canvas needs the live DOM, there is no headless renderer. Beats screen-capture: deterministic, no " +
+        "cursor/screen control, exact UI bitmap. View arguments switch the live editor and the previous view is " +
+        "not restored.",
+    copy_cell: "Copy a cell's manifest parameters and remap its LFO and envelope links onto another cell, overwriting the " +
+        "target's. Not copied: parameter sequencers and the cell config block (sidechain source) — re-apply that with " +
+        "update_cell_config.",
+    set_midi_mapping: "Configure the global MIDI-controller mappings that trigger MFX actions: variation switch and preset change. " +
+        "Set the enable flag, MIDI channel, CC number, preset source, or bar-sync for each target. One field per call.",
+};
+const MFX_FIELD_DESCRIPTIONS = {
+    capture_ui: { gridSize: "Cell grid size to set before capture: 1 or 4." },
+    analyze_motion: {
+        wavPath: "Absolute path to a WAV of material processed through MFX, such as a DAW bounce. Required on MFX.",
+    },
+    set_midi_mapping: {
+        target: "Which action's mapping to configure.",
+        field: "Field to set. 'source' is preset-only; 'barSync' is variation-only.",
+    },
+    queue_variation: {
+        fadeMs: "Crossfade duration in ms. Omit all transition options to inherit the native Bar Sync settings.",
+    },
+    update_modulation: {
+        payload: "Update payload object, one property per call. lfo, envelope, macro and paramSeq all take " +
+            "{ index, property, value }, where index is the 0-based position in that state array (get_state " +
+            "section 'lfos' / 'envelopes' / 'macros' / 'paramSeqs') and property is the field name to overwrite. " +
+            "paramSeqSequence takes { index, sequence: number[] }. freeSeqSequence takes { sequence: number[] } — the " +
+            "master step contour every free-mode ParamSeq follows.",
+    },
+    add_modulation: {
+        cellId: "Required for envelope: source cell driving the follower (1-4). This is not the target cell; target is inferred from paramId.",
+    },
+};
+// Text whose subject is a tool this launcher does not register.
+function mfxDescriptionEdits(name, value) {
+    if (name === "analyze_motion")
+        return value
+            .replace("Fills the gap left by get_master_analysis (loudness) and get_mix_analysis (aggregate spectrum + onset " +
+            "density), neither of which can tell a modulated preset from a static one.", "No other tool on this surface can tell a modulated preset from a static one.")
+            .replace(/Pass wavPath to analyze an existing render[\s\S]*$/, "Pass wavPath to a WAV of material processed through MFX, such as a DAW bounce. MFX processes its " +
+            "host's input, so there is no offline render to fall back on.");
+    if (name === "reset_cell")
+        return value.replace("Untouched: envelopes targeting this cell from another source (clear_modulations), pattern lanes (reset_patterns), " +
+            "the cell config block (update_cell_config) and the loaded sample.", "Untouched: envelopes targeting this cell from another source (clear_modulations) and the cell config block " +
+            "(update_cell_config).");
+    if (name === "clear_modulations")
+        return value.replace("LFO, envelope, and vary modulation links", "LFO and envelope modulation links")
+            .replace("for envelopes/vary", "for envelopes");
+    if (name === "update_modulation")
+        return value.replace("LFO, Envelope, Vary, Macro", "LFO, Envelope, Macro");
+    if (name === "get_default_locations")
+        return value.replace(" Use these paths with list_samples to browse the sample library.", "");
+    if (name === "save_variation")
+        return value.replace("(load samples, set parameters, enable effects, add modulation)", "(set parameters, enable effects, patch cables, add modulation)");
+    if (name === "queue_variation")
+        return value.replace(" (song mode / an already-engaged queued-flip window only;", " (an already-engaged queued-flip window only;");
+    if (name === "get_design_overview")
+        return value.replace("cells, loaded samples/synth engines, enabled effects, pattern counts, modulation link counts, mixer values, " +
+            "BPM, and master FX.", "cells, enabled effects and order, sidechain sources, modulation link counts, mixer values, cables, cable " +
+            "levels, Combo assignments, band split, BPM, and transport state.");
+    if (name === "set_master_effects")
+        return value.replace("Check results with get_master_analysis (keep tp <= -1 dBTP, PSR >= 8 in the loudest section). ", "Aim for tp <= -1 dBTP and PSR >= 8 in the loudest section; no loudness analysis tool is registered on this surface. ");
+    if (name === "set_parameters")
+        return (value +
+            " Writing mfx_combo1, mfx_combo2 or mfx_combo3 also fans the value out to that combo's resolved target " +
+            "parameters, unless one of those targets is written in the same call.");
+    return value;
+}
 function mfxToolConfig(name, config) {
     const source = config;
-    const inputEntries = Object.entries(source.inputSchema ?? {}).filter(([key]) => (name !== "update_cell_config" || key === "cellId" || key === "sidechainFrom") &&
-        (name !== "select_instance" || key !== "product"));
+    const kept = MFX_KEPT_FIELDS[name];
+    const droppedFields = MFX_DROPPED_FIELDS[name] ?? [];
+    const enumDrops = MFX_ENUM_DROPS[name] ?? {};
+    const fieldText = MFX_FIELD_DESCRIPTIONS[name] ?? {};
     const inputSchema = source.inputSchema
-        ? Object.fromEntries(inputEntries.map(([key, schema]) => [
-            key,
-            schema.description ? schema.describe(mfxSurfaceText(schema.description)) : schema,
-        ]))
+        ? Object.fromEntries(Object.entries(source.inputSchema)
+            .filter(([key]) => (!kept || kept.includes(key)) && !droppedFields.includes(key))
+            .map(([key, schema]) => {
+            let narrowed = schema;
+            if (enumDrops[key])
+                narrowed = rebuildSchema(narrowed, dropEnumMembers(enumDrops[key]));
+            if (MFX_CELL_FIELDS.has(key))
+                narrowed = rebuildSchema(narrowed, capCellId);
+            const described = fieldText[key] ??
+                (narrowed.description
+                    ? mfxSurfaceText(MFX_CELL_FIELDS.has(key)
+                        ? narrowed.description.replaceAll("1-8", "1-4").replaceAll("1..8", "1..4")
+                        : narrowed.description)
+                    : undefined);
+            return [key, described ? narrowed.describe(described) : narrowed];
+        }))
         : undefined;
-    const description = name === "select_instance"
-        ? "Choose which running MFX instance the live tools drive. Match by instanceId or port from connection_status. The launcher refuses non-MFX instances."
-        : name === "update_cell_config"
-            ? "Set one MFX cell's sidechain source. A non-null source also enables that cell's compressor."
-            : source.description ? mfxSurfaceText(source.description) : undefined;
+    const description = MFX_TOOL_DESCRIPTIONS[name] ??
+        (source.description ? mfxSurfaceText(mfxDescriptionEdits(name, source.description)) : undefined);
     return {
         ...source,
         ...(description ? { description } : {}),
@@ -882,7 +1120,14 @@ function mfxToolConfig(name, config) {
         if (IS_MFX_SERVER && !MFX_TOOL_NAMES.has(name))
             return undefined;
         const productConfig = (IS_MFX_SERVER ? mfxToolConfig(name, config) : config);
-        internalTools.set(name, { shape: productConfig.inputSchema, handler });
+        const missing = MSQ_MISSING_BY_TOOL.get(name);
+        // Judged by the instance actually connected, not a manifest hint a previous session left behind.
+        const productHandler = missing
+            ? async (args) => (await requireBridge()) === true && bridge.getConnectedInstance()?.product?.toUpperCase() === "MSQ"
+                ? error(`${name} is not available in MSQ: it has no ${missing}.`)
+                : handler(args)
+            : handler;
+        internalTools.set(name, { shape: productConfig.inputSchema, handler: productHandler });
         // Merge the central annotation policy. Inline annotations at the call site
         // win per key; openWorldHint is false server-wide (local plugin only).
         const cfg = productConfig;
@@ -890,7 +1135,7 @@ function mfxToolConfig(name, config) {
             console.error(`[${SERVER_PRODUCT.command}] tool '${name}' has no TOOL_ANNOTATIONS entry — classify it (check-tool-surface fails on this)`);
         }
         cfg.annotations = { openWorldHint: false, ...TOOL_ANNOTATIONS[name], ...cfg.annotations };
-        return origRegisterTool(name, productConfig, handler);
+        return origRegisterTool(name, productConfig, productHandler);
     });
 }
 async function callInternalTool(name, args) {
@@ -996,7 +1241,7 @@ server.registerTool("get_parameter_info", {
 });
 server.registerTool("list_presets", {
     title: "List Presets",
-    description: "List available PAM presets (factory and user).",
+    description: "List available PAM presets (factory and user) as an array of {name, path}. Above 400 matches it returns {presets, total, truncated, hint} instead — narrow with `search` rather than paging.",
     inputSchema: {
         search: z.string().optional().describe("Filter presets by name."),
     },
@@ -1127,9 +1372,8 @@ server.registerTool("design_context", {
         groups: z
             .array(z.string())
             .optional()
-            .describe("Narrow keyPerCellParams to these groups (e.g. ['delay','vocoder']) on a follow-up call. " +
-            "Omit on the FIRST call — the full vocabulary is the point, and designing from a narrowed " +
-            "subset is what makes presets resemble each other."),
+            .describe("Narrow keyPerCellParams to these groups (e.g. ['delay','vocoder']). " +
+            "Omit it to get the full per-cell vocabulary."),
     },
     annotations: { readOnlyHint: true },
 }, async ({ cellId, groups: groupFilter }) => {
@@ -1278,7 +1522,7 @@ server.registerTool("design_context", {
             compressor: group("compressorThreshold", "compressorRatio", "compressorAttack", "compressorRelease"),
             panner: group("pannerBalance", "pannerWidth"),
             clip: group("gainClip", "gainClipMode"),
-            drumSynth: group("synthEngine", "synthVolume", "synthPitch", "synthAttack", "synth_p1", "synth_p2", "synth_p3"),
+            drumSynth: group("synthEngine", "synthVolume", "synthPitch", "synthAttack", "synthWaveFm", "synth_p1", "synth_p2", "synth_p3"),
             // Everything below is a real per-cell engine that no shipped factory
             // preset has ever touched. They are the least-explored territory in the
             // instrument, which makes them the first place to look when the brief
@@ -1360,6 +1604,9 @@ server.registerTool("design_context", {
             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.",
+        generativePlayers: "set_player turns a cell into a live generator (list_players for the roster: EUCLID, KIT, TURING, WALK, MARKOV, " +
+            "RATCHET, PHASE, RIFF, MASK). cell{N}_playerDensity/Mutate/P1..P5 are modulatable params with macro_player* twins; " +
+            "write them through set_player, never set_parameters alone, so the cell config stays in step.",
         modulationGuidance: "Primary movement should target per-cell params for distinct audible changes. Use macro_* for performance-level fan-out across cells. " +
             "Shipped presets that modulate at all carry a mean of 8.2 sources; the top third carry 8-46. Four sources is the corpus MEDIAN, i.e. the unremarkable middle — not a target.",
     });
@@ -1454,8 +1701,9 @@ server.registerTool("analyze_motion", {
         "a bar — the last one is what catches a bar-synced gate, tremolo or sidechain pump, whose bars are all " +
         "identical to each other.\n\n" +
         "Pass wavPath to analyze an existing render or live_resample capture. Otherwise the tool runs an offline " +
-        "export first. Digital silence is reported as a RENDER FAILURE with the workaround, not as 'no motion' — " +
-        "offline export is known to produce silence in the standalone build.",
+        "export first and leaves that render in PAM's Exports folder (its path is in the result). Digital silence is " +
+        "reported as a RENDER FAILURE with the workaround, not as 'no motion' — offline export is known to produce " +
+        "silence in the standalone build.",
     inputSchema: {
         wavPath: z
             .string()
@@ -1465,35 +1713,34 @@ server.registerTool("analyze_motion", {
         bpm: z
             .number()
             .optional()
-            .describe("Tempo for the per-bar windows. Read from the transport when omitted."),
+            .describe("wavPath only: tempo for the 4/4 per-bar windows (default: the transport's). A render uses its own tempo and meter."),
     },
     annotations: { readOnlyHint: false, destructiveHint: false },
 }, async ({ wavPath, bars, bpm }) => {
     let path = wavPath;
     let effectiveBpm = bpm;
+    if (!path && IS_MFX_SERVER) {
+        return error("Pass wavPath: MFX processes its host's input, so an offline render has no source to analyze.");
+    }
+    // Bar windows in seconds; a render reports its own, from the transport's tempo and meter.
+    let barSeconds;
     if (!path) {
         const check = await requireBridge();
         if (check !== true)
             return check;
-        const transport = (await bridge.send("getTransport"));
-        effectiveBpm ??= typeof transport?.bpm === "number" ? transport.bpm : 120;
-        const filename = `pam_motion_${Date.now()}`;
-        await bridge.send("exportAudio", {
-            filename,
-            mode: "main",
-            durationInSeconds: (bars * 4 * 60) / (effectiveBpm || 120),
-            bitDepth: 24,
-        });
+        // The bars form of exportAudio is the one that reports its output path.
+        const started = await bridge.send("exportAudio", { bars, bitDepth: 24 });
+        const outputPath = isRecord(started) && typeof started.outputPath === "string" ? started.outputPath : undefined;
+        if (!outputPath)
+            return error("This build did not report the render's output path. Re-run with an explicit wavPath.");
         const outcome = await pollExportStatus();
         if (outcome !== "success")
             return error(`Render failed before analysis could run (export ${outcome}).`);
-        const locations = (await bridge.send("getDefaultLocations"));
-        const exportDir = [locations?.exports, locations?.exportsLocation, locations?.Exports].find((v) => typeof v === "string" && v.length > 0);
-        if (!exportDir) {
-            return error(`Rendered ${filename}.wav but could not resolve PAM's Exports folder from get_default_locations. ` +
-                "Re-run with an explicit wavPath.");
-        }
-        path = resolve(exportDir, `${filename}.wav`);
+        path = outputPath;
+        const renderedSeconds = isRecord(started) ? Number(started.durationInSeconds) : NaN;
+        barSeconds = renderedSeconds > 0 ? renderedSeconds / bars : undefined;
+        if (isRecord(started) && typeof started.bpm === "number")
+            effectiveBpm = started.bpm;
     }
     else if (effectiveBpm === undefined) {
         const check = await requireBridge();
@@ -1505,7 +1752,7 @@ server.registerTool("analyze_motion", {
     }
     let metrics;
     try {
-        metrics = analyzeMotion(decodeWav(await readFile(path)), effectiveBpm);
+        metrics = analyzeMotion(decodeWav(await readFile(path)), barSeconds ?? (effectiveBpm ? (60 / effectiveBpm) * 4 : undefined));
     }
     catch (e) {
         return error(`Could not analyze ${path}: ${e.message}`);
@@ -1638,69 +1885,6 @@ server.registerTool("variation_distinctness", {
         corpusHabit: "Shipped variations mostly change modulation and groove; they almost never change samples or FX chain order. Those two are therefore the least-used lever available to you.",
     });
 });
-// Standard full update — graph dispatch + KV sync + parameter updates.
-const KV_OPTS_STANDARD = {
-    shouldDispatch: true,
-    syncKVResources: true,
-    syncConfigResources: true,
-    resyncKVAfterDispatch: true,
-    updateParameters: true,
-    broadcastFollowers: true,
-};
-// Modulation update — same as standard but no follower broadcast.
-const KV_OPTS_MOD = {
-    shouldDispatch: true,
-    syncKVResources: true,
-    syncConfigResources: true,
-    resyncKVAfterDispatch: true,
-    updateParameters: true,
-    broadcastFollowers: false,
-};
-// Pattern/sequencer update — KV-only, no graph rebuild, no param updates.
-const KV_OPTS_PATTERN = {
-    shouldDispatch: true,
-    syncKVResources: true,
-    syncConfigResources: false,
-    skipFileLoadingIfUnchanged: true,
-    resyncKVAfterDispatch: false,
-    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,
-    syncKVResources: true,
-    syncConfigResources: true,
-    skipFileLoadingIfUnchanged: true,
-    resyncKVAfterDispatch: false,
-    updateParameters: true,
-    broadcastFollowers: true,
-};
-// Cell config update — KV-only, syncs cell config resources, no graph dispatch.
-// Matches interop.ts updateCellConfig() options.
-const KV_OPTS_CELL_CONFIG = {
-    shouldDispatch: false,
-    syncKVResources: true,
-    syncConfigResources: true,
-    skipFileLoadingIfUnchanged: true,
-    resyncKVAfterDispatch: false,
-    updateParameters: true,
-    broadcastFollowers: false,
-};
 async function applyKv(delta, options, directNodeOps) {
     const payload = { delta, options };
     if (directNodeOps)
@@ -1810,7 +1994,7 @@ server.registerTool("get_design_overview", {
         return json({
             product: manifest.name,
             bpm: state.bpm ?? transport.bpm,
-            playing: transport.playing,
+            playing: transport.isPlaying,
             mix: state.mfx_mix,
             routing: state.mfx_routing,
             edgeGains: state.mfx_edge_gains,
@@ -1840,17 +2024,23 @@ server.registerTool("get_design_overview", {
         ]));
         return {
             cellId: id,
+            muted: state[`${prefix}mute`] === 1 || state[`${prefix}mute`] === true,
             sample: {
                 name: stemName(samplePath),
                 path: typeof samplePath === "string" ? samplePath : undefined,
             },
             // Both halves: the enum an agent writes back, and the name it reasons about.
             synthEngine: describeSynthEngine(state[`${prefix}synthEngine`]),
+            player: describeCellPlayer(id, cellState, state),
             enabledEffects: effectNames.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
-            patternEvents: Object.fromEntries(Object.entries(PATTERN_LANES).map(([lane, suffix]) => [
+            patternEvents: Object.fromEntries(Object.entries(PATTERN_LANE_SUFFIX).map(([lane, suffix]) => [
                 lane,
                 countEvents(state[`${prefix}${suffix}`]),
             ])),
+            laneTargets: Object.fromEntries(PARAM_LANES.flatMap((lane) => {
+                const target = cellState[LANE_TARGET_FIELD[lane]];
+                return typeof target === "string" && target ? [[lane, target]] : [];
+            })),
             modulation,
             mixer: {
                 volume: state[`${prefix}volume`],
@@ -1862,7 +2052,7 @@ server.registerTool("get_design_overview", {
     return json({
         product: manifest.name,
         bpm: state.bpm ?? transport.bpm,
-        playing: transport.playing,
+        playing: transport.isPlaying,
         masterFx: {
             compressorEnabled: state.masterCompressorEnabled,
             limiterEnabled: state.masterLimiterEnabled,
@@ -1870,6 +2060,7 @@ server.registerTool("get_design_overview", {
         },
         totals: {
             cellsWithSamples: cells.filter((c) => c.sample.path).length,
+            playersRunning: cells.filter((c) => c.player).length,
             activePatternEvents: cells.reduce((sum, c) => sum + Object.values(c.patternEvents).reduce((a, b) => a + b, 0), 0),
             modulationLinks: cells.reduce((sum, c) => sum + Object.values(c.modulation).reduce((a, b) => a + b, 0), 0),
         },
@@ -1880,7 +2071,8 @@ server.registerTool("set_parameters", {
     title: "Set Parameters",
     description: "Set one or more PAM parameters. Values are validated against the manifest. " +
         "Effect enable flags such as cell1_filterEnabled are settable here too, so params + enables can land in one call " +
-        "when a graph dispatch is acceptable. Use get_parameter_info or design_context to discover valid IDs and ranges.",
+        "when a graph dispatch is acceptable. Use get_parameter_info or design_context to discover valid IDs and ranges. " +
+        "Writing a macro_* id also enables that macro, matching the UI.",
     inputSchema: {
         parameters: z
             .record(z.string(), z.number())
@@ -1925,7 +2117,7 @@ server.registerTool("set_parameters", {
         delta.macros = macros;
     }
     let comboTargetCount = 0;
-    if (IS_MFX_SERVER) {
+    if (isMfxManifest(await loadManifest())) {
         const comboValues = new Map();
         for (let comboIndex = 1; comboIndex <= MFX_COMBO_COUNT; comboIndex++) {
             const value = parameters[`mfx_combo${comboIndex}`];
@@ -1956,21 +2148,14 @@ server.registerTool("set_parameters", {
     }
     await bridge.send("applyUnifiedStateKvUpdate", {
         delta,
-        options: {
-            shouldDispatch: true,
-            syncKVResources: true,
-            syncConfigResources: true,
-            resyncKVAfterDispatch: true,
-            updateParameters: true,
-            broadcastFollowers: true,
-        },
+        options: STATE_UPDATE_KV_OPTIONS,
     });
     return text(`Set ${Object.keys(parameters).length} parameter(s): ${Object.entries(parameters).map(([k, v]) => `${k}=${v}`).join(", ")}` +
         (comboTargetCount > 0 ? `; fanned out ${comboTargetCount} MFX combo target write(s)` : ""));
 });
 server.registerTool("load_sample", {
     title: "Load Sample",
-    description: "Load an audio file (wav, mp3, aif, flac) into a PAM cell.",
+    description: "Load an audio file (wav, mp3, aif, flac) into a PAM cell, replacing whatever the cell currently holds. Take filePath from list_samples or a get_default_locations root.",
     inputSchema: {
         filePath: z.string().describe("Path to the audio file (absolute, or relative as returned by list_samples)."),
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
@@ -2065,7 +2250,7 @@ server.registerTool("list_models", {
 });
 server.registerTool("generate_sample", {
     title: "Generate Sample (AI)",
-    description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, 2.71 GB). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
+    description: "Generate a new audio sample from a text prompt via the on-device AI engine (Stable Audio 3 Small SFX, 2.71 GB; text-to-audio only — audio-to-audio lives in the Workbench tools). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
     inputSchema: {
         category: z
             .enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"])
@@ -2074,13 +2259,8 @@ server.registerTool("generate_sample", {
         durationSeconds: z
             .number()
             .min(0.1)
-            .max(47)
-            .describe("Output length in seconds (Stable Audio 3 Small SFX engine cap ≈ 47 s). For loops, pass bar-converted duration: bars * beatsPerBar * 60 / bpm."),
-        mode: z
-            .enum(["text", "inpaint", "continuation"])
-            .optional()
-            .default("text")
-            .describe("Generation mode. text = unconditional, inpaint = audio-to-audio with mask, continuation = extend existing audio."),
+            .max(120)
+            .describe("Output length in seconds (the model's window is ~120 s). For loops, pass bar-converted duration: bars * beatsPerBar * 60 / bpm."),
         cellId: z
             .number()
             .int()
@@ -2089,11 +2269,6 @@ server.registerTool("generate_sample", {
             .optional()
             .describe("If provided, load result directly into this cell."),
         seed: z.number().int().optional().describe("Deterministic seed. Random if omitted."),
-        refAudioPath: z.string().optional().describe("Required for inpaint/continuation. Absolute path to a WAV."),
-        maskSpec: z
-            .string()
-            .optional()
-            .describe('Mask spec for inpaint mode: "tail:0.5" or "transient:0-0.05" or "full".'),
     },
 }, async (args) => {
     const ok = await requireBridge();
@@ -2109,7 +2284,7 @@ server.registerTool("generate_sample", {
 });
 server.registerTool("generate_kit", {
     title: "Generate Kit (AI)",
-    description: "Generate multiple AI samples in parallel (Stable Audio 3 Small SFX) and load them into a list of cells. Useful for building a coherent drum / instrument kit from a single high-level prompt. Requires the on-device model to be downloaded (Settings → Local models).",
+    description: "Generate multiple AI samples one after another (Stable Audio 3 Small SFX) and load them into a list of cells. Useful for building a coherent drum / instrument kit from a single high-level prompt. Requires the on-device model to be downloaded (Settings → Local models).",
     inputSchema: {
         prompt: z.string().describe('High-level kit description (e.g. "dark trap drum kit", "lofi house").'),
         cells: z
@@ -2149,6 +2324,7 @@ server.registerTool("generate_kit", {
 // curve / prompt / seed / sigma), sidecar renders, and the take shelf. Requires
 // experimentalMode + experimentalAIGen (update_settings) AND the SA3 Python
 // sidecar running on 127.0.0.1:8093 (packages/sa3-workbench-sidecar/README.md).
+const WORKBENCH_PREREQ = "Requires experimentalMode + experimentalAIGen (update_settings) and the SA3 sidecar on 127.0.0.1:8093; check workbench_sidecar_status first. ";
 const WORKBENCH_MASK_REGION = z.object({
     startSec: z.number().min(0).describe("Region start in seconds (source time)."),
     endSec: z.number().min(0).describe("Region end in seconds (must be > startSec)."),
@@ -2184,7 +2360,8 @@ const WORKBENCH_STATE_FIELDS = {
 };
 server.registerTool("workbench_get_state", {
     title: "Workbench: Get State",
-    description: "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
+    description: WORKBENCH_PREREQ +
+        "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -2194,7 +2371,8 @@ server.registerTool("workbench_get_state", {
 });
 server.registerTool("workbench_set_state", {
     title: "Workbench: Set State",
-    description: "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
+    description: WORKBENCH_PREREQ +
+        "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
     inputSchema: WORKBENCH_STATE_FIELDS,
 }, async (args) => {
     const check = await requireBridge();
@@ -2204,7 +2382,8 @@ server.registerTool("workbench_set_state", {
 });
 server.registerTool("workbench_render", {
     title: "Workbench: Render",
-    description: "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Blocks until done (up to ~3 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, durationSeconds, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file. A successful render ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain.",
+    description: WORKBENCH_PREREQ +
+        "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Waits until done (up to ~10 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, sourcePath, durationSeconds, activeSourcePath, chainAdvanced, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file (a sourceCellId override renders that cell's sample). A successful render of the canvas's own source ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain; renders with a sourcePath/sourceCellId override, or that finished after the chain moved, leave the head alone (chainAdvanced: false).",
     inputSchema: {
         ...WORKBENCH_STATE_FIELDS,
         sourcePath: z.string().optional()
@@ -2223,7 +2402,7 @@ server.registerTool("workbench_render", {
 });
 server.registerTool("workbench_list_takes", {
     title: "Workbench: List Takes",
-    description: "List all Workbench takes (renders) with full provenance, oldest first.",
+    description: WORKBENCH_PREREQ + "List all Workbench takes (renders) with full provenance, oldest first.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -2233,7 +2412,7 @@ server.registerTool("workbench_list_takes", {
 });
 server.registerTool("workbench_load_take", {
     title: "Workbench: Load Take",
-    description: "Load a rendered take's WAV into a cell (same native path as load_sample).",
+    description: WORKBENCH_PREREQ + "Load a rendered take's WAV into a cell (same native path as load_sample).",
     inputSchema: {
         takeId: z.string().describe("Take id from workbench_render / workbench_list_takes."),
         cellId: z.number().int().min(1).max(8).describe("Target cell."),
@@ -2251,7 +2430,8 @@ server.registerTool("workbench_load_take", {
 });
 server.registerTool("workbench_undo", {
     title: "Workbench: Undo (pop chain)",
-    description: "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
+    description: WORKBENCH_PREREQ +
+        "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -2261,7 +2441,8 @@ server.registerTool("workbench_undo", {
 });
 server.registerTool("workbench_reset_chain", {
     title: "Workbench: Reset Chain",
-    description: "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
+    description: WORKBENCH_PREREQ +
+        "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
@@ -2322,17 +2503,31 @@ server.registerTool("stop_cell", {
 });
 server.registerTool("load_preset", {
     title: "Load Preset",
-    description: "Load a preset into the running PAM plugin.",
+    description: "Queue a preset load through PAM's native load/morph lifecycle. Returns requestId and status:'queued'. " +
+        "Poll get_preset_load_status until status:'succeeded' before editing, randomizing, or saving; failure, cancellation, and supersession are explicit. " +
+        "Replaces working state and the variation bank; save_preset first if unsaved edits matter. Requires a plugin build with tracked preset loading.",
     inputSchema: {
         path: z.string().describe("Preset file path (absolute or relative to preset dirs)."),
+        immediate: z.boolean().optional().describe("true bypasses the preset morph; false/omitted follows the native preset morph settings."),
     },
-}, async ({ path: presetPath }) => {
+}, async ({ path: presetPath, immediate }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const fullPath = await resolvePresetPath(presetPath);
-    await bridge.send("loadPreset", fullPath);
-    return text(`Loaded preset: ${basename(fullPath, ".preset")}`);
+    return json(await bridge.send("loadPresetTracked", fullPath, immediate === true));
+});
+server.registerTool("get_preset_load_status", {
+    title: "Get Preset Load Status",
+    description: "Read the outcome of a load_preset request without requiring the plugin window. " +
+        "Statuses: queued, morphing, succeeded, failed, cancelled, superseded. Only succeeded confirms the world committed, including same-path reloads. " +
+        "PAM retains the latest 64 requests per instance; unknown/expired IDs return an error. Keep the same selected instance while polling.",
+    inputSchema: { requestId: z.string().min(1).describe("requestId returned by load_preset.") },
+}, async ({ requestId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("getPresetLoadStatus", requestId));
 });
 server.registerTool("add_modulation", {
     title: "Add Modulation",
@@ -2375,11 +2570,9 @@ server.registerTool("add_modulation", {
     },
 }, async ({ type, paramId, cellId, lfoIndex, strength, bipolar, pitch, pitchDuck }) => {
     const index = await getParameterIndex();
-    const param = index.get(paramId);
-    if (!param)
-        return error(formatUnknownParamError(paramId, index, { modulatableOnly: true }));
-    if (!param.isModulatable)
-        return error(formatNotModulatableError(paramId, index));
+    const param = await resolveModulationTarget(paramId, index);
+    if (typeof param === "string")
+        return error(param);
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
@@ -2405,34 +2598,42 @@ server.registerTool("add_modulation", {
     }
     return text(`Added ${type} modulation to ${paramId} (strength: ${strength}%).`);
 });
+/** The full parameter rows (ranges, isModulatable) a lane target is checked against. */
+async function laneTargetParameters() {
+    return loadManifest()
+        .then((manifest) => manifest.parameters)
+        .catch(() => []);
+}
+/** A cell's param-lane target suffix ("" = none). */
+async function laneTargetOf(cellId, lane) {
+    const cells = await bridge.send("getState", "cells").catch(() => undefined);
+    const cell = isRecord(cells) ? cells[String(cellId)] : undefined;
+    const target = isRecord(cell) ? cell[LANE_TARGET_FIELD[lane]] : undefined;
+    return typeof target === "string" ? target : "";
+}
 server.registerTool("update_pattern", {
     title: "Update Pattern",
-    description: "Write a note, pitch, slice, or stretch sequence to a cell's pattern sequencer.",
+    description: "Write one lane of a cell's pattern: the notes, a value lane (pitch, slice, stretch), a CC lane (ccOut1-ccOut4, " +
+        "the timeline of that CC out slot: each event sends its value on the slot's controller for its duration, then the " +
+        "slot returns to its knob) or a PAM param lane (paramLane1-paramLane4: each event sets the parameter the lane " +
+        "targets for its duration, in that parameter's units). MSQ has note and CC lanes; MFX has none.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
-        type: z
-            .enum(["note", "pitch", "slice", "stretch"])
-            .describe("Pattern lane type."),
+        type: z.enum(PATTERN_LANE_IDS).describe("Pattern lane."),
         sequence: z
             .array(z.any())
             .describe("Array of sequence events. For 'note': [{time, note, duration, velocity, prob}]. " +
-            "For 'pitch'/'slice'/'stretch': [{time, value, duration}]."),
+            "For value and CC lanes: [{time, value, duration, prob?}] (CC values 0-127; times and durations in beats)."),
     },
 }, async ({ cellId, type, sequence }) => {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
-    // Map pattern type to state key suffix
-    const keyMap = {
-        note: "midiSequence",
-        midi: "midiSequence",
-        pitch: "pitchSequence",
-        slice: "sliceSequence",
-        stretch: "stretchSequence",
-    };
-    const suffix = keyMap[type];
-    if (!suffix)
-        return error(`Unknown pattern type: ${type}`);
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && !productHasLane(cellId, type, manifest.stateVariables)) {
+        return error(`${manifest.name ?? "This product"} has no ${type} lane.`);
+    }
+    const suffix = PATTERN_LANE_SUFFIX[type];
     // For note sequences, fill in required defaults that PAM's sequencer expects
     let normalizedSequence = sequence;
     if (suffix === "midiSequence") {
@@ -2455,28 +2656,88 @@ server.registerTool("update_pattern", {
             value: evt.value ?? evt.velocity ?? 127,
         }));
     }
+    if (isCcLane(type))
+        normalizedSequence = normalizeCcLaneEvents(sequence);
+    if (isParamLane(type)) {
+        const target = await laneTargetOf(cellId, type);
+        if (!target)
+            return error(`Cell ${cellId}'s ${type} has no target parameter: pick one with set_lane_target first.`);
+        const resolved = resolveLaneTarget(cellId, target, await laneTargetParameters());
+        if ("reason" in resolved)
+            return error(`The ${type} lane targets ${target}: ${resolved.reason}.`);
+        normalizedSequence = normalizeTargetLaneEvents(sequence, resolved.param);
+    }
     const stateKey = `cell${cellId}_${suffix}`;
     await bridge.send("applyUnifiedStateKvUpdate", {
         delta: { [stateKey]: normalizedSequence, __forceRender__: true },
-        options: {
-            shouldDispatch: true,
-            syncKVResources: true,
-            syncConfigResources: false,
-            skipFileLoadingIfUnchanged: true,
-            resyncKVAfterDispatch: false,
-            updateParameters: false,
-            broadcastFollowers: false,
-        },
+        options: PATTERN_EDIT_KV_OPTIONS,
         directNodeOps: [{ key: stateKey, property: "sequence", value: normalizedSequence }],
     });
     return text(`Updated ${type} pattern for cell ${cellId} (${normalizedSequence.length} events).`);
 });
+server.registerTool("set_lane_target", {
+    title: "Set Lane Target",
+    description: "Point one of a PAM cell's four param lanes (paramLane1-paramLane4) at a modulatable parameter of the same cell " +
+        "(a suffix such as 'filterCutoff'), or clear it with null. Each lane event then sets that parameter for its " +
+        "duration; outside events the parameter follows its knob and modulation. Each param lane loops at its own " +
+        "clock, cell{N}_patternLengthParam{K} and cell{N}_patternSpeedParam{K} (set_parameters; 4 beats at 1x by default), " +
+        "while swing and direction follow the note lane; copy the note lane's length and speed to match it. The lane is cleared (its values meant the old target); another param lane already on that " +
+        "parameter is cleared too. Write the lane with update_pattern in the target's units. For a free-running step " +
+        "contour that adds to the knob, use a ParamSeq instead.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        lane: z.enum(PARAM_LANES).describe("Param lane to point."),
+        param: z.string().min(1).nullable().describe("Target parameter suffix (no cellN_ prefix), or null for none."),
+    },
+}, async ({ cellId, lane, param }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && !productHasLane(cellId, lane, manifest.stateVariables)) {
+        return error(`${manifest.name ?? "This product"} has no ${lane} lane.`);
+    }
+    let targetParam = null;
+    if (param !== null) {
+        const resolved = resolveLaneTarget(cellId, param, await laneTargetParameters());
+        if ("reason" in resolved)
+            return error(`Cannot target ${param}: ${resolved.reason}.`);
+        targetParam = resolved.param;
+    }
+    const cells = await bridge.send("getState", "cells").catch(() => undefined);
+    const cell = isRecord(cells) ? cells[String(cellId)] : undefined;
+    const target = param ?? "";
+    const current = isRecord(cell) && typeof cell[LANE_TARGET_FIELD[lane]] === "string" ? cell[LANE_TARGET_FIELD[lane]] : "";
+    if (current === target)
+        return text(`Cell ${cellId} ${lane} already ${target ? `→ ${target}` : "has no target"}; nothing changed.`);
+    const cellDelta = { [LANE_TARGET_FIELD[lane]]: target };
+    const delta = { [`cell${cellId}_${PATTERN_LANE_SUFFIX[lane]}`]: [] };
+    const reverted = [];
+    for (const sibling of PARAM_LANES) {
+        if (sibling === lane || !target || !isRecord(cell) || cell[LANE_TARGET_FIELD[sibling]] !== target)
+            continue;
+        cellDelta[LANE_TARGET_FIELD[sibling]] = "";
+        delta[`cell${cellId}_${PATTERN_LANE_SUFFIX[sibling]}`] = [];
+        reverted.push(sibling);
+    }
+    delta.cells = { [cellId]: cellDelta };
+    // Same as add_modulation: a lane on a bypassed effect's param turns the effect on.
+    if (targetParam?.effect && targetParam.cell)
+        delta[`${targetParam.cell}_${targetParam.effect}Enabled`] = 1;
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
+    const where = target ? `→ ${target}` : "target cleared";
+    const note = reverted.length ? ` ${reverted.join(", ")} lost that target and was cleared.` : "";
+    return text(`Cell ${cellId} ${lane} ${where}; lane cleared.${note}`);
+});
 server.registerTool("randomize", {
     title: "Randomize",
     description: "Trigger PAM's randomization engine to generate random sounds and patterns. " +
         "target:'synth' runs the musical, engine-aware drum-synth randomizer (picks an engine + " +
         "shapes its params per cell) — it is routed through the WebView, so it requires PAM's window " +
-        "to be OPEN (samples/sequences/full run natively and do not). target:'synth' needs PAM ≥ 1.13.0.",
+        "to be OPEN (samples/sequences/full run natively and do not). 'lfos'/'mods' are global and require an open window. " +
+        "Returns queued, not completed: poll get_state for the requested changes before another randomize, edit, or save. " +
+        "Concurrent requests can coalesce; a preset/variation load can discard pending work. " +
+        "Use target:'full' to chain sample selection and pattern generation in the native engine.",
     inputSchema: {
         // 'lfos'/'mods' added for the assistant surface (1.15.0) — WebView-routed
         // like 'synth'. The describe() text is pinned (exported toolpack bytes).
@@ -2487,7 +2748,7 @@ server.registerTool("randomize", {
         cellIds: z
             .array(z.number().min(1).max(8))
             .optional()
-            .describe("Specific cells to randomize. Omit for all."),
+            .describe("Specific cells to randomize. Omit for all. Not supported for global 'lfos'/'mods'."),
         genreHint: z
             .string()
             .optional()
@@ -2518,6 +2779,8 @@ server.registerTool("randomize", {
             .describe("Rhythmic placement for 'sequences'/'full' (-1 = strong beats, 0 = neutral, 1 = weaker offbeats). Omit for the genre and role default."),
     },
 }, async ({ target, cellIds, genreHint, bpmHint, mutationAmount, density, syncopation }) => {
+    if ((target === "lfos" || target === "mods") && cellIds !== undefined)
+        return error(`target:'${target}' randomizes global modulation; omit cellIds or edit individual links with update_modulation.`);
     const check = await requireBridgeForCells(cellIds);
     if (check !== true)
         return check;
@@ -2525,23 +2788,21 @@ server.registerTool("randomize", {
         // Routed to the canonical WebView randomizer (single source of truth) — needs the
         // window open. Empty array → all non-excluded cells.
         await bridge.send("randomizeDrumSynth", cellIds ?? []);
-        return text(`Randomized drum synths${cellIds ? ` for cells ${cellIds.join(", ")}` : " (all cells)"}. ` +
-            `(Drum-synth randomize runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+        return json({ status: "queued", target, cellIds, note: "Open PAM's window and poll get_design_overview for synth changes before editing or saving." });
     }
     if (target === "lfos" || target === "mods") {
-        // The data-driven modulation randomizer lives in WebView JS
-        // (interop.ts randomizeLfos/randomizeEnvelopes/randomizeVary) — routed
-        // like 'synth'. Needs PAM ≥ 1.15.0 and the window open.
         await bridge.send("randomizeModulations", target, mutationAmount ?? -1);
-        return text(`Randomized ${target === "lfos" ? "LFO modulation links" : "all modulation (LFOs, envelopes, vary)"}. ` +
-            `(Runs in the WebView — if nothing changed, ensure PAM's window is open.)`);
+        return json({ status: "queued", target, note: "Open PAM's window and poll get_state for modulation changes before editing or saving." });
     }
     await bridge.send("randomize", target, cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
-    return text(`Randomized ${target}${cellIds ? ` for cells ${cellIds.join(", ")}` : ""}.`);
+    return json({ status: "queued", target, cellIds, note: "Poll get_state for changed sample paths and/or sequences before another randomize, edit, or save. An acknowledgment does not prove the request applied." });
 });
 server.registerTool("randomize_samples", {
     title: "Randomize Samples",
-    description: "Use PAM's native sample randomization engine to pick coherent samples based on genre, BPM, and kit role. More musically coherent than manually browsing and loading samples. Supports folder filtering to constrain selection to specific sample packs.",
+    description: "Use PAM's native sample randomization engine to pick coherent samples based on genre, BPM, and kit role. Supports folder filtering. " +
+        "Returns queued: poll get_state section:'cells' for sample changes before generating patterns, editing, or saving. " +
+        "Serialize requests because concurrent requests can coalesce; a preset/variation load can discard pending work. " +
+        "For samples plus patterns, prefer randomize target:'full'.",
     inputSchema: {
         cellIds: z
             .array(z.number().min(1).max(8))
@@ -2573,8 +2834,8 @@ server.registerTool("randomize_samples", {
             .describe("Anti-centroid mode (0 = default behaviour, 1 = maximum spread). The native engine scores FOLDER " +
             "COHERENCE, which is correct for a kit-from-one-pack and is also why repeated randomizes keep landing " +
             "on the same few well-stocked folders. Above 0 this builds a cross-folder pool first and restricts the " +
-            "engine to it, keeping role assignment while removing its ability to converge. Use it for the DIVERGE " +
-            "step; ignored when allowedSamplePaths is given."),
+            "engine to it, keeping role assignment while removing its ability to converge. Ignored when " +
+            "allowedSamplePaths is given."),
         seed: z
             .number()
             .int()
@@ -2589,10 +2850,8 @@ server.registerTool("randomize_samples", {
     let pool = allowedSamplePaths;
     let diversifyNote = "";
     if (!pool && diversify && diversify > 0) {
-        const locations = (await bridge.send("getDefaultLocations"));
-        const roots = Object.entries(locations ?? {})
-            .filter(([k, v]) => typeof v === "string" && v.length > 0 && /sample/i.test(k))
-            .map(([, v]) => v);
+        const locations = await defaultLocationPaths();
+        const roots = ["User Samples", "Factory Samples"].flatMap((name) => locations.get(name) ?? []);
         if (roots.length) {
             const byFolder = await collectLibraryByFolder(roots);
             const spread = spreadAcrossFolders(byFolder, diversify, seed ?? 0);
@@ -2609,11 +2868,14 @@ server.registerTool("randomize_samples", {
         }
     }
     await bridge.send("randomizeSamples", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, excludedFolders ?? [], pool ?? []);
-    return text(`Randomized samples${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.${diversifyNote}`);
+    return json({ status: "queued", target: "samples", cellIds, genreHint,
+        note: "Poll get_state section:'cells' for changed sample paths before another randomize, patterns, edit, or save." + diversifyNote });
 });
 server.registerTool("randomize_patterns", {
     title: "Randomize Patterns",
-    description: "Use PAM's native pattern generation engine to create musically coherent note patterns based on genre and BPM. Analyzes loaded samples to determine roles (kick, snare, hat, etc.) and generates appropriate rhythms.",
+    description: "Use PAM's native pattern generation engine to create note patterns based on loaded sample roles, genre, and BPM. " +
+        "Identical to randomize target:'sequences'. Returns queued: poll get_state for changed cellN_midiSequence values " +
+        "before another randomize, edit, or save. Wait for sample loading/randomization first; concurrent requests can coalesce.",
     inputSchema: {
         cellIds: z
             .array(z.number().min(1).max(8))
@@ -2636,8 +2898,8 @@ server.registerTool("randomize_patterns", {
             .optional()
             .describe("How much to vary from typical patterns (0 = conventional, 1 = experimental). Default ~0.5. " +
             "This is the pattern-side divergence lever: the generator otherwise produces the genre's most typical " +
-            "rhythm, which is exactly what makes a batch of presets feel the same. Push it to 0.7-1.0 during the " +
-            "DIVERGE step, and keep it low only when the brief genuinely wants a stock groove."),
+            "rhythm, which is exactly what makes a batch of presets feel the same; 0.7-1.0 buys rhythmic " +
+            "distinctness, low values keep a stock groove."),
         density: z
             .number()
             .min(-1)
@@ -2656,11 +2918,12 @@ server.registerTool("randomize_patterns", {
     if (check !== true)
         return check;
     await bridge.send("randomize", "sequences", cellIds ?? [], genreHint ?? "", bpmHint ?? -1, mutationAmount ?? -1, density ?? null, syncopation ?? null);
-    return text(`Randomized patterns${cellIds ? ` for cells ${cellIds.join(", ")}` : " for all cells"}${genreHint ? ` (genre: ${genreHint})` : ""}.`);
+    return json({ status: "queued", target: "sequences", cellIds, genreHint,
+        note: "Poll get_state for changed cellN_midiSequence values before another randomize, edit, or save." });
 });
 server.registerTool("load_variation", {
     title: "Load Variation",
-    description: "Switch to a saved variation slot (0-7). Loads the stored state for that variation including parameters, effects, patterns, and modulation. The preset must have variations saved via save_variation first.",
+    description: "Request a switch to a saved variation slot (0-7), including parameters, effects, patterns, and modulation. Empty slots are rejected. Verify currentVariation and a slot-specific value with get_state before editing or saving.",
     inputSchema: {
         index: z
             .number()
@@ -2674,7 +2937,7 @@ server.registerTool("load_variation", {
     if (check !== true)
         return check;
     await bridge.send("loadVariation", index);
-    return text(`Loaded variation ${index} (UI slot ${index + 1}).`);
+    return text(`Requested variation ${index} (UI slot ${index + 1}); verify currentVariation and the intended state with get_state before editing or saving.`);
 });
 server.registerTool("full_stop_transport", {
     title: "Full Stop Transport",
@@ -2726,9 +2989,11 @@ 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.",
+        "spectrum per cell, plus the full-mix master block. Each cell also carries coact: {otherCellId: " +
+        "fraction of this cell's sounding time the other cell sounds too}. Pass refresh:true to run a new " +
+        "analysis (one in-context render from bar 0; each cell is measured at its post-fader output before " +
+        "the master chain, so muted cells read silent — takes a few seconds; audio does NOT need to be " +
+        "playing). Cached result otherwise. Requires a PAM build with Mix Assist support.",
     inputSchema: {
         refresh: z.boolean().optional().describe("Run a fresh analysis instead of returning the cached one."),
         durationSeconds: z.number().min(5).max(30).optional().describe("Analysis render length (default 8 bars at the current BPM, clamped 5-30 s)."),
@@ -2783,7 +3048,7 @@ server.registerTool("suggest_mix", {
         "partial-loudness fader balance, pan spread, bounded masking EQ cuts, and optional compressor " +
         "settings. Returns absolute moves with per-move rationale and guard notes; apply:true lands them " +
         "as one state update. Run get_mix_analysis with refresh:true first if the mix changed. " +
-        "Requires PAM ≥ 1.17.0. PAM only.",
+        "Requires a PAM build with Mix Assist support.",
     inputSchema: {
         scopes: z
             .array(z.enum(["balance", "pan", "eq", "dynamics"]))
@@ -2848,7 +3113,7 @@ server.registerTool("suggest_mix", {
         ? { 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);
+        await applyKv(suggestion.flat, STATE_UPDATE_KV_OPTIONS);
         if (!analysis.live)
             lastAppliedMixEpoch = analysis.epoch;
         return json({ ...suggestion, ...parkedNote, applied: true });
@@ -2870,7 +3135,8 @@ server.registerTool("new_preset", {
 });
 server.registerTool("save_preset", {
     title: "Save Preset",
-    description: "Save the current PAM state as a new preset file with metadata. " +
+    description: "Save the current PAM state as a preset file with metadata. Omit `name` to re-save the active user preset in place " +
+        "(factory presets are refused). Every save also snapshots the current state into variation slot 0 if the bank is empty, otherwise into the active slot. " +
         "Writes to the user preset folder by default; pass `path` for a specific location. " +
         "Use `update_preset_metadata` to edit an existing preset without re-saving plugin state.",
     inputSchema: {
@@ -2921,24 +3187,17 @@ server.registerTool("save_preset", {
             return error(`Could not derive a name from the active preset path (${activePath}) — pass name explicitly.`);
         if (path === undefined)
             path = activePath;
-        try {
-            const parsed = parsePresetFile(await readFile(await resolvePresetPath(readPath), "utf-8"));
-            for (const [k, v] of Object.entries(parsed.metadata)) {
-                // Structural keys are rebuilt below; everything else (author/tags/
-                // category/…) carries over unless the caller overrode it.
-                if (["name", "factory", "path", "variations", "currentVariation"].includes(k))
-                    continue;
-                if (extras[k] === undefined)
-                    extras[k] = v;
-            }
-        }
-        catch {
-            // unreadable/new — save fresh with whatever the caller passed
+        const parsed = await readPresetForSave(readPath);
+        for (const [k, v] of Object.entries(parsed.metadata)) {
+            if (["name", "factory", "path", "variations", "currentVariation"].includes(k))
+                continue;
+            if (extras[k] === undefined)
+                extras[k] = v;
         }
     }
     const metadata = { name, factory: false };
     if (path !== undefined)
-        metadata.path = path;
+        metadata.path = nativePresetPath(path);
     for (const [k, v] of Object.entries(extras)) {
         if (v !== undefined)
             metadata[k] = v;
@@ -2952,7 +3211,11 @@ server.registerTool("save_preset", {
     // the new destination starts from eight empty slots because that file does
     // not exist yet, which used to collapse every named save to one slot.
     const variationSourcePath = selectSaveVariationSourcePath(state.activePresetPath, presetRelPath);
-    const existingVariations = await readExistingVariations(variationSourcePath);
+    const hasActivePreset = typeof state.activePresetPath === "string"
+        && state.activePresetPath.length > 0 && state.activePresetPath !== "Init";
+    const source = await readPresetForSave(variationSourcePath, !hasActivePreset);
+    const existingVariations = source
+        ? variationsFromParsedPreset(source) : Array(PRESET_VARIATION_SLOTS).fill(null);
     const hasVariations = existingVariations.some((v) => v !== null);
     if (!hasVariations) {
         existingVariations[0] = variationString;
@@ -3002,49 +3265,25 @@ server.registerTool("save_variation", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    // 1. Canonical save snapshot (engine + hosted-plugin state), then shape it
     const { state, canonical } = await fetchSaveSnapshot();
     const variationString = buildVariationString(state);
-    // 2. Determine preset name and disk path — needed to read existing variations and metadata
-    let presetName = name;
-    let diskPath;
-    const activePath = state.activePresetPath;
-    if (!presetName && activePath) {
-        const filename = activePath.split("/").pop() || "";
-        presetName = filename.replace(/\.preset$/, "");
-        // Use active path for disk lookup (preserves subfolder structure).
-        // Strip "Presets/" prefix if present — resolvePresetPath already prepends
-        // the presets base directory, so "Presets/User/X" would double up to
-        // ".../Presets/Presets/User/X" and silently fail to read back variations.
-        diskPath = normalizePresetLookupPath(activePath);
-    }
-    if (!presetName && lastSavedPresetName) {
-        presetName = lastSavedPresetName;
-        diskPath = lastSavedPresetPath;
+    if (!name && state.activePresetPath === "Init") {
+        return error("No active preset. Call save_preset with a name first, or pass a name to save_variation.");
     }
+    const activePath = typeof state.activePresetPath === "string" && state.activePresetPath !== "Init"
+        ? normalizePresetLookupPath(state.activePresetPath) : "";
+    const presetName = name || (activePath.split("/").pop() || "").replace(/\.preset$/, "") || lastSavedPresetName;
     if (!presetName) {
-        return error("No preset name provided and no active preset loaded.\n" +
-            "Next call: save_preset({ name: 'Your Preset Name', ...metadata }) first, or call save_variation with name: 'Your Preset Name'.");
-    }
-    if (!diskPath) {
-        diskPath = `User/${presetName}.preset`;
-    }
-    // 3. Read existing preset metadata and variations from disk
-    let existingMeta = {};
-    let variations = Array(PRESET_VARIATION_SLOTS).fill(null);
-    try {
-        const fullPath = await resolvePresetPath(diskPath);
-        const raw = await readFile(fullPath, "utf-8");
-        const parsed = parsePresetFile(raw);
-        existingMeta = parsed.metadata;
-        variations = variationsFromParsedPreset(parsed);
-    }
-    catch {
-        // New preset or unreadable — start fresh
-    }
-    // 4. Update the target slot
+        return error("No active preset. Call save_preset with a name first, or pass a name to save_variation.");
+    }
+    const diskPath = name ? `User/${presetName}.preset`
+        : activePath || lastSavedPresetPath || `User/${presetName}.preset`;
+    const sourcePath = selectSaveVariationSourcePath(activePath, diskPath);
+    const parsed = await readPresetForSave(sourcePath, !!name && !activePath);
+    const existingMeta = parsed?.metadata ?? {};
+    const variations = parsed
+        ? variationsFromParsedPreset(parsed) : Array(PRESET_VARIATION_SLOTS).fill(null);
     variations[index] = variationString;
-    // 5. Build metadata: merge existing (preserves author/tags/etc.) then override with caller args
     const metadata = {
         ...existingMeta,
         name: presetName,
@@ -3053,12 +3292,13 @@ server.registerTool("save_variation", {
         currentVariation: index,
         ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),
     };
-    // Write to the correct subfolder path
+    delete metadata.path;
     let resultSuffix = "";
-    if (activePath && !activePath.startsWith("Factory/")) {
-        metadata.path = activePath;
+    const destinationPath = normalizePresetLookupPath(diskPath);
+    if (!name && !destinationPath.startsWith("Factory/")) {
+        metadata.path = nativePresetPath(destinationPath);
     }
-    else if (activePath?.startsWith("Factory/")) {
+    else if (sourcePath.startsWith("Factory/")) {
         // Cannot write back to factory location; savePreset will create User/{name}.preset
         resultSuffix = "\n(Note: active preset is a factory preset — saved as new user preset)";
     }
@@ -3159,7 +3399,7 @@ server.registerTool("set_bpm", {
 });
 server.registerTool("trim_sample", {
     title: "Trim Sample",
-    description: "Trim a cell's sample to its start/end markers (non-destructive crop).",
+    description: "Trim a cell's sample to its start/end markers: writes a new WAV into Samples/Resamples/Trimmed/ and points the cell at it. The original file is untouched, but a preset saved afterwards references the trimmed copy, and calling it again crops the trimmed file further.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -3167,12 +3407,15 @@ server.registerTool("trim_sample", {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
+    const loaded = await requireCellSample(cellId);
+    if (loaded !== true)
+        return loaded;
     await bridge.send("trimSampleForCell", cellId);
     return text(`Trimmed sample in cell ${cellId}.`);
 });
 server.registerTool("reverse_sample", {
     title: "Reverse Sample",
-    description: "Reverse a cell's loaded sample.",
+    description: "Reverse a cell's loaded sample. Writes <name>_reversed.<ext> next to the source file and points the cell at it; calling it again on an already-reversed sample restores the original instead of reversing twice.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -3180,6 +3423,9 @@ server.registerTool("reverse_sample", {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
+    const loaded = await requireCellSample(cellId);
+    if (loaded !== true)
+        return loaded;
     await bridge.send("reverseSampleForCell", cellId);
     return text(`Reversed sample in cell ${cellId}.`);
 });
@@ -3224,11 +3470,178 @@ server.registerTool("connection_status", {
         connectedTo: bridge.getConnectedInstance(),
         note: connected
             ? instances.length > 1
-                ? `Connected. Multiple ${SERVER_PRODUCT.name} instances are running; the launcher uses the first available instance.`
-                : `Connected to ${SERVER_PRODUCT.name}. All advertised tools are available.`
+                ? `Connected. Multiple ${SERVER_PRODUCT.name} instances are running; use select_instance to choose; reconnects stay pinned to that instance.`
+                : `Connected to ${SERVER_PRODUCT.name}. Tool availability also depends on this plugin build, open windows, and feature settings.`
             : "Found instances but could not connect. The plugin may have shut down.",
     });
 });
+// A plugin instance's pid is its DAW, so `ps` names the host; the plugin's own
+// binary is one of the host's mapped files (e.g. PAM.vst3/Contents/MacOS/PAM).
+function hostedPluginBinaries(pid, product) {
+    const pluginBinary = new RegExp(`/${product}\\.(?:vst3|component|clap)/Contents/MacOS/${product}$`, "i");
+    try {
+        const mapped = execFileSync("lsof", ["-a", "-p", String(pid), "-d", "txt", "-Fn"], {
+            encoding: "utf8",
+            timeout: 5000,
+        });
+        return [...new Set(mapped.split("\n").filter((line) => line.startsWith("n")).map((line) => line.slice(1)))]
+            .filter((path) => pluginBinary.test(path));
+    }
+    catch {
+        return [];
+    }
+}
+// build.js restages plugins with size and mtime intact, so an identical file in
+// the checkout's build tree identifies a development build.
+function matchesRepoBuild(binary, projectRoot) {
+    const entries = (path) => {
+        try {
+            return readdirSync(path);
+        }
+        catch {
+            return [];
+        }
+    };
+    try {
+        const target = statSync(binary);
+        const bundlePath = binary.split("/").slice(-4).join("/");
+        const darwin = join(resolve(projectRoot), "build", "Darwin");
+        for (const config of entries(darwin))
+            for (const artefacts of entries(join(darwin, config)).filter((name) => name.endsWith("_artefacts")))
+                for (const mode of entries(join(darwin, config, artefacts)))
+                    for (const format of entries(join(darwin, config, artefacts, mode))) {
+                        const candidate = join(darwin, config, artefacts, mode, format, bundlePath);
+                        if (!existsSync(candidate))
+                            continue;
+                        const stats = statSync(candidate);
+                        if (stats.size === target.size && Math.abs(stats.mtimeMs - target.mtimeMs) < 1000)
+                            return true;
+                    }
+    }
+    catch {
+        /* binary or build tree unreadable */
+    }
+    return false;
+}
+server.registerTool("situation", {
+    title: "Situation",
+    description: "One-call orientation snapshot: discovered instances, the connected instance's product/pid/executable " +
+        "(plus build mtime and a dev-build heuristic when resolvable), server and manifest identity, active preset, " +
+        "transport, and per-cell occupancy counts. Start a session here — it collapses the connection/product/build " +
+        "preflight and the first design reads into one round trip. Deeper reads: get_design_overview, design_context.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const instances = await bridge.discover().catch(() => []);
+    const connected = bridge.isConnected() || (await bridge.connect().catch(() => false)) === true;
+    if (connected)
+        syncProductHint();
+    const instance = connected ? bridge.getConnectedInstance() : null;
+    let build;
+    if (instance?.pid) {
+        try {
+            const processExecutable = execFileSync("ps", ["-o", "comm=", "-p", String(instance.pid)], {
+                encoding: "utf8",
+            }).trim();
+            if (processExecutable) {
+                const product = instance.product ?? SERVER_PRODUCT.name;
+                const projectRoot = process.env.PAM_PROJECT_ROOT;
+                const hosted = basename(processExecutable).toLowerCase() !== product.toLowerCase();
+                const pluginBinaries = hosted ? hostedPluginBinaries(instance.pid, product) : [];
+                const executable = hosted ? (pluginBinaries.length === 1 ? pluginBinaries[0] : undefined) : processExecutable;
+                build = hosted ? { host: processExecutable } : {};
+                if (pluginBinaries.length > 1)
+                    build.pluginBinaries = pluginBinaries;
+                if (executable) {
+                    build.executable = executable;
+                    if (!hosted) {
+                        build.looksLikeDevBuild = executable.includes("/build/") && !executable.startsWith("/Applications/");
+                    }
+                    else if (projectRoot) {
+                        build.looksLikeDevBuild = matchesRepoBuild(executable, projectRoot);
+                    }
+                }
+                try {
+                    if (executable)
+                        build.executableMtime = statSync(executable).mtime.toISOString();
+                }
+                catch {
+                    /* executable path unreadable from this process */
+                }
+                if (projectRoot && typeof build.executableMtime === "string") {
+                    try {
+                        const headIso = execFileSync("git", ["-C", resolve(projectRoot), "log", "-1", "--format=%cI"], { encoding: "utf8" }).trim();
+                        build.repoHeadCommitTime = headIso;
+                        build.binaryOlderThanHeadCommit =
+                            new Date(build.executableMtime).getTime() < new Date(headIso).getTime();
+                    }
+                    catch {
+                        /* PAM_PROJECT_ROOT is not a git checkout */
+                    }
+                }
+            }
+        }
+        catch {
+            /* ps unavailable (Windows) or pid already gone */
+        }
+    }
+    let live;
+    let manifestName;
+    if (connected) {
+        const [stateRaw, transportRaw, manifest] = await Promise.all([
+            bridge.send("getState").catch(() => undefined),
+            bridge.send("getTransport").catch(() => undefined),
+            loadManifest().catch(() => null),
+        ]);
+        manifestName = manifest?.name;
+        const state = isRecord(stateRaw) ? stateRaw : {};
+        const transport = isRecord(transportRaw) ? transportRaw : {};
+        if (manifest) {
+            const effectNames = cellEffectNames(manifest);
+            const ids = [...new Set(manifest.parameters
+                    .map((p) => p.cell)
+                    .filter((cell) => typeof cell === "string" && /^cell\d+$/.test(cell))
+                    .map((cell) => Number(cell.replace("cell", ""))))].sort((a, b) => a - b);
+            const cellsObj = isRecord(state.cells) ? state.cells : {};
+            const cells = ids.map((id) => {
+                const prefix = `cell${id}_`;
+                const rawCellState = cellsObj[String(id)];
+                const cellState = isRecord(rawCellState) ? rawCellState : {};
+                const samplePath = cellState.filePath ??
+                    cellState.samplePath ??
+                    state[`${prefix}filePath`] ??
+                    state[`${prefix}samplePath`];
+                const synth = IS_MFX_SERVER ? undefined : describeSynthEngine(state[`${prefix}synthEngine`]);
+                return {
+                    cellId: id,
+                    sample: stemName(samplePath),
+                    synthEngine: synth && synth.id > 0 ? synth.name : undefined,
+                    muted: state[`${prefix}mute`] === 1 || state[`${prefix}mute`] === true,
+                    enabledEffects: effectNames.filter((n) => state[`${prefix}${n}Enabled`] === 1 || state[`${prefix}${n}Enabled`] === true).length,
+                };
+            });
+            live = {
+                activePreset: state.activePresetPath,
+                bpm: state.bpm ?? transport.bpm,
+                playing: transport.isPlaying,
+                cells,
+                ...(IS_MFX_SERVER ? { mix: state.mfx_mix, routing: state.mfx_routing } : {}),
+            };
+        }
+    }
+    return json({
+        server: { name: SERVER_PRODUCT.name, version: SERVER_VERSION },
+        instances,
+        connected,
+        instance,
+        manifest: manifestName,
+        build,
+        live,
+        note: connected
+            ? undefined
+            : "Not connected. connection_status has enable instructions; offline tools still work.",
+    });
+});
 server.registerTool("select_instance", {
     title: "Select Plugin Instance",
     description: "Choose which running plugin instance (PAM / CELL1 / MFX) the live tools drive when more than " +
@@ -3318,6 +3731,30 @@ async function searchSampleLibrary(rootPath, term, audioOnly) {
 }
 // Walk the library and return audio files grouped by their parent folder.
 // Bounded like searchSampleLibrary — this runs inside a tool call, not a job.
+// The sample-edit actions answer "ok" before their async edit runs, even on an empty cell.
+async function requireCellSample(cellId, field = "filePath") {
+    const cells = await bridge.send("getState", "cells").catch(() => undefined);
+    if (!isRecord(cells))
+        return true;
+    const cell = cells[String(cellId)];
+    const path = isRecord(cell) ? cell[field] : undefined;
+    if (typeof path === "string" && path.length > 0)
+        return true;
+    return error(field === "filePath" ? `Cell ${cellId} has no sample loaded.` : `Cell ${cellId} has no original sample to restore.`);
+}
+// getDefaultLocations returns [{name, path, icon}]; the names are fixed in FileHandler.
+async function defaultLocationPaths() {
+    const locations = await bridge.send("getDefaultLocations").catch(() => undefined);
+    const entries = Array.isArray(locations) ? locations : [];
+    return new Map(entries
+        .filter((entry) => isRecord(entry) && typeof entry.name === "string" && typeof entry.path === "string")
+        .map((entry) => [entry.name, entry.path]));
+}
+// Native exports to <base>/Export beside <base>/Samples ("Plugin Samples"); check-parity pins both.
+async function exportsFolder() {
+    const pluginSamples = (await defaultLocationPaths()).get("Plugin Samples");
+    return pluginSamples ? join(dirname(pluginSamples), "Export") : undefined;
+}
 async function collectLibraryByFolder(roots, maxDirReads = 120) {
     const byFolder = new Map();
     const queue = roots.map((path) => ({ path, depth: 0 }));
@@ -3393,14 +3830,12 @@ function fitListing(base, itemsKey, items, moreKey, total) {
 }
 server.registerTool("list_samples", {
     title: "List Samples",
-    description: "Browse sample library directories. IMPORTANT: Do NOT guess paths — always call " +
-        "get_default_locations first to discover the actual library paths, then use those " +
-        "paths here. Paths vary per user and platform.",
+    description: "Browse sample library directories. Library paths vary per user and platform, so take them from " +
+        "get_default_locations rather than guessing.",
     inputSchema: {
         path: z
             .string()
-            .describe("Directory path to list. MUST be a path returned by get_default_locations " +
-            "or a subdirectory of one. Do not guess paths like ~/Music/PAM."),
+            .describe("Directory path to list: a path from get_default_locations, or a subdirectory of one."),
         audioOnly: z
             .boolean()
             .default(true)
@@ -3489,8 +3924,9 @@ server.registerTool("get_audio_info", {
 });
 server.registerTool("export_preset", {
     title: "Export Preset",
-    description: "Export a preset as a zip file bundled with all referenced samples. " +
-        "Creates a shareable preset package.",
+    description: "Export a preset as a zip file bundled with all referenced samples, written to PAM's Exports folder as " +
+        "<outputFolderName>.zip (get_default_locations resolves that folder). An existing folder or zip of that " +
+        "name is replaced, and presets belonging to a preset pack are refused.",
     inputSchema: {
         presetPath: z
             .string()
@@ -3503,12 +3939,18 @@ server.registerTool("export_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    await bridge.send("exportPresetWithSamples", presetPath, outputFolderName);
-    return text(`Exported preset to: ${outputFolderName}`);
+    const result = await bridge.send("exportPresetWithSamples", nativePresetPath(presetPath), outputFolderName);
+    if (result === false) {
+        return error(`Export refused for ${presetPath}: the preset is missing, belongs to a preset pack, or the folder name is invalid.`);
+    }
+    return text(`Exported preset to: ${outputFolderName}.zip in ${SERVER_PRODUCT.name}'s Exports folder`);
 });
 server.registerTool("import_preset", {
     title: "Import Preset",
-    description: "Import a preset from a zip file or folder into PAM's preset library.",
+    description: "Import a preset from a zip file or folder into PAM's preset library. Returns the relative path of the " +
+        "first imported preset, or an empty string on failure. Referenced samples are copied into the user sample " +
+        "folder and the preset's paths are rewritten. A name already in the library is never overwritten: the " +
+        "import lands as <name>_1, <name>_2 and so on.",
     inputSchema: {
         path: z.string().describe("Absolute path to the preset zip file or folder to import."),
     },
@@ -3680,14 +4122,15 @@ async function resolveNewId(requestId, beforeIds, pick, ackIdKey, timeoutMs = 25
         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
+                return { id: minted };
+            // An acked command never falls back to the diff, which could misattribute a concurrent edit.
+            return ack.ok === false ? { error: ack.error || "the command failed" } : {};
         }
         const found = pick(s).find((id) => !beforeIds.has(id));
         if (found)
-            return found;
+            return { id: found };
     }
-    return null;
+    return {};
 }
 server.registerTool("get_video_state", {
     title: "Get Video State",
@@ -3718,7 +4161,7 @@ server.registerTool("capture_ui", {
         "PresetBrowser; omit/null = cell grid), instrumentView ('synth'|'sampler', applied to " +
         "all cells). REQUIRES PAM's window OPEN — html2canvas needs the live DOM, there is no " +
         "headless renderer (same constraint as the video tools). Beats screen-capture: " +
-        "deterministic, no cursor/screen control, exact UI bitmap.",
+        "deterministic, no cursor/screen control, exact UI bitmap. View arguments switch the live editor and the previous view is not restored.",
     inputSchema: {
         gridSize: z.number().optional().describe("Cell grid size to set before capture: 1, 4, or 8."),
         mainView: z
@@ -3732,7 +4175,7 @@ server.registerTool("capture_ui", {
         settleMs: z.number().optional().describe("Delay (ms) after view changes before rasterizing. Default 350."),
         timeoutMs: z.number().optional().default(8000).describe("Max ms to wait for the WebView to return the image."),
     },
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 }, async ({ gridSize, mainView, instrumentView, settleMs, timeoutMs }) => {
     const check = await requireBridge();
     if (check !== true)
@@ -3843,7 +4286,9 @@ server.registerTool("add_video_layer", {
     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");
+    const { id, error: failure } = await resolveNewId(requestId, beforeIds, (s) => (s.layers ?? []).map((l) => l.id), "layerId");
+    if (failure)
+        return error(`add_video_layer failed: ${failure}`);
     return text(id
         ? `Added ${kind} layer: ${id}`
         : `Added ${kind} layer (window may be closed; call get_video_state to confirm).`);
@@ -3854,7 +4299,8 @@ server.registerTool("update_video_layer", {
         "(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}; " +
+        "{text,fontSize,fontWeight,color,align,lineHeight}; image/video/model3d {sourcePath (loads the file, as " +
+        "set_video_layer_source does),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.",
@@ -3877,7 +4323,11 @@ server.registerTool("update_video_layer", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const patch = { ...(fields ?? {}) };
+    // A sourcePath in the patch is only stored; setLayerSource is what loads the media.
+    const { sourcePath, ...kindFields } = fields ?? {};
+    if (sourcePath !== undefined && typeof sourcePath !== "string")
+        return error("fields.sourcePath must be a file path.");
+    const patch = { ...kindFields };
     if (opacity !== undefined)
         patch.opacity = opacity;
     if (blendMode !== undefined)
@@ -3888,6 +4338,10 @@ server.registerTool("update_video_layer", {
         patch.name = name;
     if (transform !== undefined)
         patch.transform = transform;
+    if (sourcePath !== undefined)
+        await sendVideoCommand({ op: "setLayerSource", layerId, sourcePath });
+    if (Object.keys(patch).length === 0)
+        return text(`Loading ${sourcePath} into layer ${layerId}.`);
     const result = await sendVideoCommand({ op: "updateLayer", layerId, patch });
     return json(result);
 });
@@ -3966,7 +4420,9 @@ server.registerTool("add_video_fx", {
         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");
+        const { id, error: failure } = await resolveNewId(requestId, beforeIds, (s) => (s.outputFx ?? []).map((f) => f.instanceId), "instanceId");
+        if (failure)
+            return error(`add_video_fx failed: ${failure}`);
         // Apply param overrides now that the instance exists.
         if (params && id)
             for (const [param, value] of Object.entries(params))
@@ -3980,10 +4436,12 @@ server.registerTool("add_video_fx", {
     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 { id, error: failure } = await resolveNewId(requestId, beforeIds, (s) => {
         const l = (s.layers ?? []).find((x) => x.id === layerId);
         return (l?.fx ?? []).map((f) => f.id);
     }, "fxId");
+    if (failure)
+        return error(`add_video_fx failed: ${failure}`);
     return text(id ? `Added ${fxType} to layer ${layerId}: ${id}` : `Added ${fxType} (confirm via get_video_state).`);
 });
 server.registerTool("set_video_fx", {
@@ -4024,10 +4482,18 @@ server.registerTool("set_video_fx", {
         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 }));
+        // A param write by fxId has just auto-created the FX, so resolve the instance after it.
+        let outputInstance = instanceId;
+        if (!outputInstance && fxId && (enabled !== undefined || strength !== undefined)) {
+            const current = await getVideoStateRaw();
+            outputInstance = (current.outputFx ?? []).find((fx) => fx.fxId === fxId)?.instanceId;
+            if (!outputInstance)
+                return error(`set_video_fx: no output ${fxId} to enable or scale; add_video_fx it first.`);
+        }
+        if (enabled !== undefined && outputInstance)
+            results.push(await sendVideoCommand({ op: "setOutputFxEnabled", instanceId: outputInstance, enabled }));
+        if (strength !== undefined && outputInstance)
+            results.push(await sendVideoCommand({ op: "setOutputFxStrength", instanceId: outputInstance, strength }));
     }
     if (results.length === 0)
         return error("set_video_fx: nothing to set (provide param/value, params, enabled, or strength).");
@@ -4112,13 +4578,23 @@ server.registerTool("set_video_settings", {
         "loads on the next bar boundary while playing). resetWorkspace clears the " +
         "scene (preserves the master layer).",
     inputSchema: {
-        syncMode: z.enum(["off", "beat-sync", "beat-match"]).optional(),
-        loopBars: z.number().optional(),
-        aspectRatio: z.enum(["auto", "16:9", "4:3", "1:1", "stretch"]).optional(),
-        renderQuality: z.enum(["low", "medium", "high"]).optional(),
-        designAspect: z.number().nullable().optional(),
-        letterboxColor: z.string().optional(),
-        canvasColor: z.string().optional(),
+        syncMode: z
+            .enum(["off", "beat-sync", "beat-match"])
+            .optional()
+            .describe("Clock source: 'off' free-runs, 'beat-sync' locks playback to the bar grid, 'beat-match' retimes clips to the transport."),
+        loopBars: z.number().min(0).optional().describe("Loop length in bars for the beat-sync and beat-match modes."),
+        aspectRatio: z
+            .enum(["auto", "16:9", "4:3", "1:1", "stretch"])
+            .optional()
+            .describe("How a layer is fitted to the canvas. 'auto' keeps the source ratio, 'stretch' fills it."),
+        renderQuality: z.enum(["low", "medium", "high"]).optional().describe("VX render resolution/effort tier."),
+        designAspect: z
+            .number()
+            .nullable()
+            .optional()
+            .describe("Canvas design ratio as width/height (e.g. 1.7777 for 16:9). null clears it and follows the window."),
+        letterboxColor: z.string().describe("#hex fill for the bars outside the design aspect.").optional(),
+        canvasColor: z.string().describe("#hex background behind every VX layer.").optional(),
         modEnabled: z.boolean().optional().describe("Mod-matrix master enable."),
         vxVariationFollowAudio: z
             .boolean()
@@ -4232,16 +4708,11 @@ server.registerTool("vx_variation", {
 // ============================================================
 // Composite cell-operation tools
 // ============================================================
-const PATTERN_SUFFIXES = [
-    "midiSequence",
-    "pitchSequence",
-    "sliceSequence",
-    "stretchSequence",
-];
 server.registerTool("reset_cell", {
     title: "Reset Cell",
-    description: "Reset all parameters of a single cell to their default values and remove " +
-        "any envelopes targeting this cell. Does not touch other cells.",
+    description: "Reset a single cell's manifest parameters to their defaults and remove the envelopes whose SOURCE is this cell. " +
+        "Untouched: envelopes targeting this cell from another source (clear_modulations), pattern lanes (reset_patterns), " +
+        "the cell config block (update_cell_config) and the loaded sample. Does not touch other cells.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -4260,6 +4731,8 @@ server.registerTool("reset_cell", {
     ]);
     const delta = {};
     for (const p of cellParams) {
+        if (isCcOutValueSuffix(p.paramId.replace(/^cell\d+_/, "")))
+            continue;
         if (p.defaultValue !== undefined)
             delta[p.paramId] = p.defaultValue;
     }
@@ -4269,13 +4742,16 @@ server.registerTool("reset_cell", {
     const removedEnvs = envArray.length - filteredEnvs.length;
     if (removedEnvs > 0)
         delta.envelopes = filteredEnvs;
-    await applyKv(delta, KV_OPTS_STANDARD);
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
     return text(`Reset cell ${cellId} to defaults (${paramCount} params, removed ${removedEnvs} envelopes).`);
 });
 server.registerTool("copy_cell", {
     title: "Copy Cell",
-    description: "Copy all parameters and modulation from one cell to another. " +
-        "Overwrites the target cell's settings.",
+    description: "Copy a cell's manifest parameters and remap its LFO, envelope and vary links onto another cell, overwriting the target's. " +
+        "Param-lane targets travel with their lanes. A CC lane lands only on a target slot that is Off or on the same " +
+        "controller; CC out values and controllers stay the target's. " +
+        "Not copied: the loaded sample, parameter sequencers, and the cell config block (polyphony, MIDI note/channel, scale, " +
+        "sidechain source, pitch/stretch engine, slice keymap) — re-apply those with load_sample and update_cell_config.",
     inputSchema: {
         sourceCellId: z.number().min(1).max(8).describe("Source cell (1-8)."),
         targetCellId: z.number().min(1).max(8).describe("Target cell (1-8)."),
@@ -4300,10 +4776,33 @@ server.registerTool("copy_cell", {
     const dstPrefix = `cell${targetCellId}_`;
     const delta = {};
     for (const [key, value] of Object.entries(state)) {
-        if (key.startsWith(srcPrefix)) {
+        if (key.startsWith(srcPrefix) && !isCcOutValueSuffix(key.slice(srcPrefix.length))) {
             delta[dstPrefix + key.slice(srcPrefix.length)] = value;
         }
     }
+    // Destination wiring: a CC lane lands only where the slot it locks is Off or on the same controller,
+    // and then brings that slot; one that stays out keeps the destination's.
+    const cellsState = isRecord(state.cells) ? state.cells : {};
+    const srcRaw = cellsState[String(sourceCellId)];
+    const dstRaw = cellsState[String(targetCellId)];
+    const srcCell = isRecord(srcRaw) ? srcRaw : {};
+    const dstCell = isRecord(dstRaw) ? dstRaw : {};
+    const targetDelta = {};
+    for (const lane of CC_LANES) {
+        const slot = ccLaneSlotOf(srcCell, lane);
+        if (slot === 0 || ccLaneMayLand(srcCell[`ccOutCc${slot}`], dstCell[`ccOutCc${slot}`])) {
+            targetDelta[ccLaneSlotField(lane)] = slot;
+        }
+        else {
+            delete delta[`${dstPrefix}${PATTERN_LANE_SUFFIX[lane]}`];
+            targetDelta[ccLaneSlotField(lane)] = ccLaneSlotOf(dstCell, lane);
+        }
+    }
+    for (const lane of PARAM_LANES) {
+        const target = srcCell[LANE_TARGET_FIELD[lane]];
+        targetDelta[LANE_TARGET_FIELD[lane]] = typeof target === "string" ? target : "";
+    }
+    delta.cells = { [targetCellId]: targetDelta };
     // Remap envelopes
     const envelopes = state.envelopes || [];
     if (envelopes.length > 0) {
@@ -4379,13 +4878,13 @@ server.registerTool("copy_cell", {
         if (remapped.length > 0)
             delta.paramSeqs = [...kept, ...remapped];
     }
-    await applyKv(delta, KV_OPTS_STANDARD);
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
     return text(`Copied cell ${sourceCellId} → cell ${targetCellId} (${Object.keys(delta).length} keys).`);
 });
 server.registerTool("clear_modulations", {
     title: "Clear Modulations",
     description: "Remove all LFO, envelope, and vary modulation links targeting a cell's parameters " +
-        "(or originating from that cell, for envelopes/vary). Useful for starting fresh on a cell.",
+        "(or originating from that cell, for envelopes/vary). Parameter sequencers survive — use remove_param_seq for those.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -4422,7 +4921,7 @@ server.registerTool("clear_modulations", {
     if (Object.keys(delta).length === 0) {
         return text(`No modulations found for cell ${cellId}.`);
     }
-    await applyKv(delta, KV_OPTS_MOD);
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
     const removed = (lfos.length - filteredLfos.length) +
         (vary.length - filteredVary.length) +
         (envelopes.length - filteredEnvs.length);
@@ -4430,7 +4929,8 @@ server.registerTool("clear_modulations", {
 });
 server.registerTool("reset_patterns", {
     title: "Reset Patterns",
-    description: "Clear all sequencer lanes (note, pitch, slice, stretch) for a single PAM/Cell1 sampler cell.",
+    description: "Clear every pattern lane of one cell (note, pitch, slice, stretch, the CC lanes and the param lanes, as the " +
+        "product has them) and clear the param lanes' targets. CC out controllers stay.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
@@ -4449,10 +4949,14 @@ server.registerTool("reset_patterns", {
         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}`] = [];
+    for (const lane of PATTERN_LANE_IDS) {
+        if (!manifest || productHasLane(cellId, lane, manifest.stateVariables))
+            delta[`cell${cellId}_${PATTERN_LANE_SUFFIX[lane]}`] = [];
     }
-    await applyKv(delta, KV_OPTS_PATTERN);
+    if (!manifest || productHasLane(cellId, "paramLane1", manifest.stateVariables)) {
+        delta.cells = { [cellId]: Object.fromEntries(PARAM_LANES.map((lane) => [LANE_TARGET_FIELD[lane], ""])) };
+    }
+    await applyKv(delta, PATTERN_EDIT_KV_OPTIONS);
     return text(`Cleared all patterns for cell ${cellId}.`);
 });
 server.registerTool("update_effect_config", {
@@ -4520,7 +5024,7 @@ server.registerTool("update_effect_config", {
     if (Object.keys(delta).length === 0) {
         return error("At least one effect flag must be provided.");
     }
-    await applyKv(delta, KV_OPTS_EFFECT_CONFIG);
+    await applyKv(delta, EFFECT_CONFIG_KV_OPTIONS);
     const summary = Object.entries(delta)
         .map(([k, v]) => `${k}=${v}`)
         .join(", ");
@@ -4530,7 +5034,7 @@ server.registerTool("update_effect_config", {
 // unreachable through set_parameters (numbers only) — an agent could shape an MFX
 // cell but never patch one to another, which is the whole product.
 //
-// Validation mirrors parseRoutingEdges (interface/src/dsp/mfxRouting.ts): the
+// Validation mirrors parseRoutingEdges (interface/src/utils/mfxRouting.ts): the
 // plugin re-validates on receipt, so this pass exists to fail loudly here rather
 // than have a typo silently drop a cable.
 const MFX_ROUTING_SOURCE_HINT = "'input', 'sidechain', 'split_lo' / 'split_mid' / 'split_hi', or 'cellN'. " +
@@ -4625,7 +5129,7 @@ server.registerTool("set_mfx_routing", {
         return error(`${validated.reason}. This product exposes cells 1..${maxCells}.`);
     }
     // mfx_routing is a GRAPH_RENDER state var — a re-patch must rebuild the graph.
-    await applyKv({ mfx_routing: validated.edges }, KV_OPTS_STANDARD);
+    await applyKv({ mfx_routing: validated.edges }, STATE_UPDATE_KV_OPTIONS);
     const summary = validated.edges.map((e) => `${e.from}→${e.to}`).join(", ");
     return text(`MFX routing set: ${validated.edges.length} cable(s)${summary ? ` — ${summary}` : " (patch cleared)"}.`);
 });
@@ -4634,7 +5138,7 @@ server.registerTool("set_mfx_edge_gain", {
     description: "Read or set the gain for one cable in the current MFX patch. Gain is linear: 0 is silent, 1 is unity, " +
         "and 1.5 is the maximum. The cable must already exist. Other cable gains are preserved.",
     inputSchema: {
-        op: z.enum(["get", "set"]),
+        op: z.enum(["get", "set"]).describe("'get' returns every cable gain; 'set' writes one."),
         from: z.string().optional().describe(`Cable source for 'set': ${MFX_ROUTING_SOURCE_HINT}`),
         to: z.string().optional().describe(`Cable destination for 'set': ${MFX_ROUTING_SINK_HINT}`),
         gain: z.number().min(0).max(1.5).optional().describe("Linear gain for 'set'."),
@@ -4662,7 +5166,8 @@ server.registerTool("set_mfx_edge_gain", {
         return error(`Cable ${from}→${to} is not in the current patch. Add it with set_mfx_routing first.`);
     const key = `${from}__${to}`;
     gains[key] = gain;
-    await applyKv({ mfx_edge_gains: gains }, KV_OPTS_EFFECT_CONFIG);
+    // Cable gains reach audio only through the graph's mounted refs, which a dispatch updates.
+    await applyKv({ mfx_edge_gains: gains }, STATE_UPDATE_KV_OPTIONS);
     return text(`MFX cable gain set: ${from}→${to} = ${gain}.`);
 });
 const MFX_COMBO_TARGET_INPUT = z.object({
@@ -4680,9 +5185,12 @@ server.registerTool("configure_mfx_combo", {
         op: z.enum([
             "get", "setValue", "rename", "lock", "unlock", "rescan", "setTargets", "addTarget",
             "removeTarget", "clearTargets", "invertTarget", "setTargetStop", "anchor",
-        ]),
+        ]).describe("get reads the combo; setValue writes its value and every resolved target; rename relabels it (blank restores the role label); " +
+            "lock freezes the current automatic assignment as manual; unlock and rescan return it to automatic; " +
+            "setTargets/addTarget/removeTarget/clearTargets edit the manual target list; invertTarget swaps a target's from/to stops; " +
+            "setTargetStop sets one target's stop value; anchor re-derives every target's stops from the current parameter values."),
         index: z.number().int().min(1).max(3).default(1),
-        value: z.number().min(-100).max(100).optional().describe("Combo value for setValue, or target value for setTargetStop."),
+        value: z.number().optional().describe("Combo value (−100 to 100) for setValue, or a value in the target parameter's units for setTargetStop."),
         name: z.string().max(24).optional().describe("New label for rename; blank restores the role label."),
         paramId: z.string().optional().describe("Target parameter for add/remove/invert/setTargetStop."),
         stop: z.enum(["from", "mid", "to"]).optional().describe("Target stop edited by setTargetStop."),
@@ -4707,6 +5215,8 @@ server.registerTool("configure_mfx_combo", {
     if (op === "setValue") {
         if (typeof value !== "number")
             return error("setValue requires value.");
+        if (value < -100 || value > 100)
+            return error("Combo value must be between -100 and 100.");
         const delta = { [`mfx_combo${index}`]: value };
         for (const target of combo.targets) {
             const info = parameterIndex.get(target.id);
@@ -4716,7 +5226,7 @@ server.registerTool("configure_mfx_combo", {
             const currentTargetValue = state[target.id];
             delta[target.id] = mfxComboTargetValueFromCurrent(target, typeof previousComboValue === "number" ? previousComboValue : 0, value, info, typeof currentTargetValue === "number" ? currentTargetValue : info.defaultValue);
         }
-        await applyKv(delta, KV_OPTS_STANDARD);
+        await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
         return json({ combo: index, value, targetsWritten: combo.targets.map((target) => target.id) });
     }
     const materialized = () => ({ ...stored, targets: [...combo.targets] });
@@ -4813,7 +5323,7 @@ server.registerTool("configure_mfx_combo", {
         locked: next?.locked === 1 ? 1 : 0,
         targets: Array.isArray(next?.targets) ? next.targets : null,
     };
-    await applyKv({ mfx_combos: { ...slots, [String(index)]: update } }, KV_OPTS_EFFECT_CONFIG);
+    await applyKv({ mfx_combos: { ...slots, [String(index)]: update } }, EFFECT_CONFIG_KV_OPTIONS);
     return json({ combo: index, slot: update });
 });
 server.registerTool("set_effect_order", {
@@ -4873,15 +5383,15 @@ server.registerTool("set_effect_order", {
             "To bypass a stage set its *Enabled flag via update_effect_config; leaving it out of the chain is not the same thing.");
     }
     // effectOrder rebuilds the cell's FX graph, like an MFX re-patch.
-    await applyKv({ [key]: order }, KV_OPTS_STANDARD);
+    await applyKv({ [key]: order }, STATE_UPDATE_KV_OPTIONS);
     return text(`Cell ${cellId} FX chain: ${order.join(" → ")}.`);
 });
 server.registerTool("update_cell_config", {
     title: "Update Cell Config",
-    description: "Update cell-level configuration properties like polyphony, MIDI settings, varispeed, and modulation latch. " +
+    description: "Update cell-level configuration properties like polyphony, MIDI settings, MIDI output (channel, Send, CC out controllers), 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. " +
-        "When bound to MFX, this tool only accepts sidechainFrom; sampler/MIDI/instrument config is PAM/Cell1-only.",
+        "When bound to MFX, this tool only accepts sidechainFrom; on MSQ it accepts the MIDI and output keys 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)."),
@@ -4923,8 +5433,8 @@ server.registerTool("update_cell_config", {
             "An out-of-vocabulary string would silently play as chromatic while junk persists into the preset, so the name is validated."),
         scaleRoot: z.number().min(0).max(11).optional().describe("Root note of the scale (0=C, 1=C#, ..., 11=B)."),
         pitchMode: z.number().int().min(0).max(3).optional().describe("Pitch engine: 0=Varispeed, 1=Formant, 2=Pitch Shift Quantize, 3=Varispeed Quantize."),
-        stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=OLA, 1=Cloud, 2=Phase Vocoder, 3=GrainRate."),
-        quantScale: z.number().int().min(0).max(9).optional().describe("Pitch quantize scale when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=Chromatic, 1=Major, 2=Minor, 3=Penta Maj, 4=Penta Min, 5=Dorian, 6=Mixolydian, 7=Blues, 8=Harm Min, 9=Phrygian. Order locked to QuantScale in modules/helpers/Scale.h."),
+        stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=Default (OLA), 1=Cloud, 2=Spectral, 3=Beats."),
+        quantScale: z.number().int().min(0).max(9).optional().describe("Pitch quantize scale when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=Chromatic, 1=Major, 2=Minor, 3=Penta Maj, 4=Penta Min, 5=Dorian, 6=Mixolydian, 7=Blues, 8=Harm Min, 9=Phrygian. Order locked to QuantScale in modules/dsp-core/Scale.h."),
         quantRoot: z.number().int().min(0).max(11).optional().describe("Pitch quantize root when pitchMode=2 (Pitch Shift Quantize) or 3 (Varispeed Quantize): 0=C, 1=C#, ..., 11=B."),
         grainDensity: z.number().int().min(1).max(24).optional().describe("Cloud stretch grain density when stretchMode=1."),
         grainWindow: z.number().int().min(0).max(4).optional().describe("Cloud stretch grain envelope when stretchMode=1: 0=Hann, 1=Tukey, 2=Welch, 3=Punch, 4=Swell."),
@@ -4935,6 +5445,20 @@ server.registerTool("update_cell_config", {
             .optional()
             .describe("Sidechain compressor source. null=no sidechain, 0=external audio input, 1-8=cell output. " +
             "Auto-enables the cell's compressor when set to a non-null value."),
+        midiOutChannel: z.number().int().min(0).max(16).optional().describe("MIDI out channel for the cell's CC out (and MSQ's notes): 0=Auto (the cell number), 1-16 explicit."),
+        sendToHost: z.union([z.literal(0), z.literal(1)]).optional().describe("0 keeps the cell's CC out (and MSQ's notes) off the MIDI out."),
+        midiOutPort: z.number().int().min(0).max(3).optional().describe("Standalone only: 0=Main MIDI Output, 1-3=Ports B-D set in Settings."),
+        ...Object.fromEntries(CC_OUT_SLOTS.map((slot) => [`ccOutCc${slot}`, ccOutControllerSchema(slot)])),
+        ...Object.fromEntries(CC_LANES.map((lane) => [
+            ccLaneSlotField(lane),
+            z
+                .number()
+                .int()
+                .min(0)
+                .max(CC_OUT_SLOTS.length)
+                .optional()
+                .describe(`CC out slot (1-${CC_OUT_SLOTS.length}) that CC lane ${ccLaneIndex(lane)} locks per event, 0=none. Lane L starts on slot L. The lane loops at its own cell{N}_patternLengthCc${ccLaneIndex(lane)} / patternSpeedCc${ccLaneIndex(lane)}.`),
+        ])),
     },
 }, async ({ cellId, ...config }) => {
     const check = await requireBridge();
@@ -4963,6 +5487,13 @@ server.registerTool("update_cell_config", {
                 `Sampler/MIDI/instrument config keys are PAM/Cell1-only: ${unsupported.join(", ")}.`);
         }
     }
+    if (bridge.getConnectedInstance()?.product?.toUpperCase() === "MSQ") {
+        const unsupported = providedKeys.filter((key) => !MSQ_CELL_CONFIG_KEYS.has(key));
+        if (unsupported.length > 0) {
+            return error(`update_cell_config in MSQ accepts MIDI keys only (${[...MSQ_CELL_CONFIG_KEYS].join(", ")}). ` +
+                `MSQ has no sampler: ${unsupported.join(", ")}.`);
+        }
+    }
     const cellConfig = {};
     const flatDelta = {};
     for (const [key, value] of Object.entries(config)) {
@@ -4990,7 +5521,8 @@ server.registerTool("update_cell_config", {
     const delta = { ...flatDelta };
     if (Object.keys(cellConfig).length > 0)
         delta.cells = { [cellId]: cellConfig };
-    await applyKv(delta, KV_OPTS_CELL_CONFIG);
+    // A sidechain source is wired at graph build, so it needs the dispatch the UI's setter makes.
+    await applyKv(delta, cellConfig.sidechainFrom !== undefined ? STATE_UPDATE_KV_OPTIONS : CELL_CONFIG_KV_OPTIONS);
     const summary = [
         ...Object.entries(cellConfig).map(([k, v]) => `${k}=${v}`),
         ...Object.entries(flatDelta).map(([k, v]) => `${k}=${v}`),
@@ -5002,7 +5534,7 @@ server.registerTool("set_cell_mute", {
     description: "Mute, unmute, solo, or unsolo a cell in the mixer — the real channel mute/solo, cutting the whole channel " +
         "(source + all effect tails) rather than pulling the volume fader down. Soloing a cell silences every other " +
         "non-soloed cell until unsoloed. cell{N}_mute / cell{N}_solo are live-polled state variables (no graph rebuild). " +
-        "Prefer this over set_parameter volume -60 when the user says mute, unmute, solo, unsolo, isolate, or 'just this cell'.",
+        "Prefer this over pulling cell{N}_volume down: a fader move leaves effect tails audible, a channel mute cuts them.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         mute: z.boolean().optional().describe("Mute (true) or unmute (false) the cell's channel."),
@@ -5026,10 +5558,10 @@ server.registerTool("set_cell_mute", {
     }
     // 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
+    // applyStateDelta uses (STATE_UPDATE_KV_OPTIONS); the projection needs
     // syncConfigResources, no graph rebuild required but the standard path is
     // the exact UI parity.
-    await applyKv(delta, KV_OPTS_STANDARD);
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
     const summary = Object.entries(delta)
         .map(([k, v]) => `${k}=${v}`)
         .join(", ");
@@ -5043,11 +5575,7 @@ server.registerTool("set_master_effects", {
         "Check results with get_master_analysis (keep tp <= -1 dBTP, PSR >= 8 in the loudest section). " +
         "The Tape is a vintage-tape coloration stage (ADAA tanh/asymmetric saturation + HF compression + wow/flutter), " +
         "the single biggest lever for lo-fi / dusty / 'pushed' master character (hip-hop, lo-fi, Memphis, dub). " +
-        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound. " +
-        "For pumpy beats: enable punch, set threshold around -18 to -12 dB, fast attack (0.1-0.5ms), " +
-        "medium release (80-200ms), ratio 4-8, autoMakeup true. " +
-        "For lo-fi/Memphis/dusty glue: tapeEnabled=1, tapeMode=1 (Lo-Fi), masterTapeDrive 0.55-0.7, " +
-        "masterTapeTone -0.4..-0.1 (darker), masterTapeWear 0.5-0.7 (wow/flutter). " +
+        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound; genre recipes live in the beat-making-guide resource. " +
         "Squeeze (masterSqueeze*) is the 3-band up/down density stage between Punch and Tape — for dense modern-electronic masters set masterSqueezeEnabled=1 with masterSqueezeDepth 0.2-0.4; it lifts quiet detail and limits loud bands per band (a character stage, not glue — Punch stays the glue). " +
         "NOTE: the Tape and Squeeze stages require a PAM build that ships them (flat state keys, not manifest params). On older builds these keys are ignored.",
     inputSchema: {
@@ -5081,10 +5609,18 @@ server.registerTool("set_master_effects", {
         masterEqHsGain: z.number().min(-12).max(12).optional().describe("High-shelf gain dB (default 0)."),
         masterWidth: z.number().min(0).max(2).optional().describe("Stereo width (0=mono, 1=unity, 2=double side; default 1). Check corr in get_master_analysis after widening."),
         masterBassMonoFreq: z.number().min(0).max(300).optional().describe("Elliptical bass-mono corner Hz; < 20 = off. Engage (~100-120) when corrLow < +0.7."),
-        masterClipEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the oversampled soft clipper (post-Tape, pre-Limiter). Adds 23 samples of reported latency while on."),
+        masterClipEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable the oversampled soft clipper (post-Tape, pre-Limiter). Its 23 samples of latency are reported whether it is on or off, so toggling it never moves the host's compensation."),
         masterClipDrive: z.number().min(0).max(12).optional().describe("Clipper drive dB (default 0). Staging guidance: the clipper shaves the sharpest 2-3 dB so the limiter works 1-2 dB."),
         masterClipMix: z.number().min(0).max(1).optional().describe("Clipper parallel blend (1 = fully clipped)."),
         masterClipMode: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional().describe("Clipper transfer: 0=Smooth (knee-tanh), 1=Silicon diode (hard knee), 2=Germanium diode (earlier, softer knee), 3=LED (higher knee). Diode modes are exact antiparallel-pair solves, ADAA at the 2x rate. Default 0."),
+        masterDenoiseEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master noise reduction before EQ and compression; off by default. Adds one FFT frame of latency while enabled; a DAW that is playing keeps that latency after a switch-off until its transport stops, and Fixed latency mode keeps it always."),
+        masterDenoiseLow: z.number().min(0).max(100).optional().describe("Low-band noise reduction strength, percent (default 50)."),
+        masterDenoiseMid: z.number().min(0).max(100).optional().describe("Mid-band noise reduction strength, percent (default 50)."),
+        masterDenoiseHigh: z.number().min(0).max(100).optional().describe("High-band noise reduction strength, percent (default 50)."),
+        masterDenoiseSplitLow: z.number().min(40).max(2000).optional().describe("Low/mid split in Hz (default 250)."),
+        masterDenoiseSplitHigh: z.number().min(500).max(12000).optional().describe("Mid/high split in Hz (default 4000)."),
+        masterDenoiseMix: z.number().min(0).max(1).optional().describe("Master Denoise dry/wet, 0..1 (default 1)."),
+        masterDenoisePrint: z.string().optional().describe("Learned noise print ('pdn1:<sampleRate>:<fftSize>:<base64>'), written by the Denoise panel's Learn button. Pass '' to forget it and return to adaptive tracking; copy a value read from get_state to reuse a print."),
         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)."),
@@ -5156,7 +5692,7 @@ server.registerTool("set_master_effects", {
     // 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);
+    await applyKv(delta, MASTER_CONFIG_KV_OPTIONS);
     const summary = Object.entries(delta)
         .map(([k, v]) => `${k}=${v}`)
         .join(", ");
@@ -5165,7 +5701,7 @@ server.registerTool("set_master_effects", {
 // Built-in per-cell drum synth ("machines"). Engine enum index = drumsynth::Engine
 // (Off = 0). The roster, the curated defaults and the engine-switch rule all come
 // from shared/drumSynthEngines.json — the registry build.js codegens the C++ cook
-// and the manifest from, and interface/src/dsp/modules/drumSynth.ts derives its
+// and the manifest from, and interface/src/utils/drumSynth.ts derives its
 // own tables from. The hand-copied table this replaced had drifted on Kick,
 // Cowbell and 808 (issue #999); the switch rule it shipped with carried knob
 // positions where the plugin carries engine units.
@@ -5250,8 +5786,8 @@ server.registerTool("set_drum_synth", {
     }
     if (volume !== undefined)
         delta[`cell${cellId}_synthVolume`] = volume;
-    // synthEngine is a graph-render key → needs a graph dispatch (KV_OPTS_STANDARD).
-    await applyKv(delta, KV_OPTS_STANDARD);
+    // synthEngine is a graph-render key → needs a graph dispatch (STATE_UPDATE_KV_OPTIONS).
+    await applyKv(delta, STATE_UPDATE_KV_OPTIONS);
     const labels = desc ? desc.params.map((p) => p.label).join(",") : "—";
     return text(`Cell ${cellId} drum synth → ${engine}${engineId > 0 ? ` (p1..pN = ${labels})` : ""}.`);
 });
@@ -5262,7 +5798,7 @@ server.registerTool("set_drum_synth_wave", {
         "centre, tension −1..+1 with 0 = linear). PAM bakes them into a DC-removed, peak-normalized single cycle " +
         "that the Wave engine's Draw param (p8) crossfades against the factory bank. Only the Wave engine reads it — " +
         "select 'Wave' via set_drum_synth and raise Draw (p8) to hear it. Runs in the WebView (the curve transform " +
-        "is single-sourced there), so PAM's window must be OPEN. Needs PAM ≥ 1.13.0.",
+        "is single-sourced there), so PAM's window must be OPEN with drum-synth wave editing support.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         points: z
@@ -5293,6 +5829,422 @@ server.registerTool("set_drum_synth_wave", {
     return text(`Set cell ${cellId} Wave-engine custom waveform (${points.length} breakpoints). ` +
         `Select the Wave engine and raise Draw (p8) to hear it. (Runs in the WebView — ensure PAM's window is open.)`);
 });
+// Generative Players (per-cell PLAYER mode). Arming semantics mirror
+// interface/src/interop.ts setCellPlayer; the registry is shared/generativePlayers.json.
+const PLAYER_REF_HELP = `one of ${PLAYER_NAMES.join(", ")} (or its id 1..${GENERATIVE_PLAYERS.length}), ` +
+    "'role' for the cell's role default, or 'off'";
+function playerProductError(manifest) {
+    if (manifest && manifest.generativePatterns?.enabled !== true) {
+        return error(`Generative players are PAM-only. ${manifest.name ?? "This product"}'s manifest exposes none.`);
+    }
+    return null;
+}
+const playerSlotArg = (n) => z
+    .union([z.number().min(0).max(1), z.string()])
+    .optional()
+    .describe(`P${n} slot: 0..1 (snapped to the slot's detents) or a position label such as 'Techno' or 'Triad'. ` +
+    "Its meaning is per player — list_players names it.");
+server.registerTool("list_players", {
+    title: "List Generative Players",
+    description: "Catalogue of PAM's generative Players — per-cell generators that replace a cell's drawn pattern with a " +
+        "seeded, transport-synced cycle (EUCLID, KIT, TURING, WALK, MARKOV, RATCHET, PHASE, RIFF, MASK). Returns each " +
+        "player's blurb, defaults, P-slot vocabulary (detented positions or 0..1 knobs) and curated preset names, plus " +
+        "the role spread (which player each cell arms by default). Offline — no bridge needed. Arm one with set_player.",
+    inputSchema: {
+        player: z.string().optional().describe("Return one player's full detail (name or id). Omit for the whole roster."),
+        presets: z
+            .boolean()
+            .optional()
+            .describe("Include each curated preset's values, not only its name. Default false."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ player, presets }) => {
+    const manifest = await loadManifestForProductGuard();
+    const available = manifest ? manifest.generativePatterns?.enabled === true : true;
+    const spec = player ? resolvePlayerSpec(player) : undefined;
+    if (player && !spec)
+        return error(`Unknown player '${player}' — ${PLAYER_REF_HELP}.`);
+    const specs = spec ? [spec] : GENERATIVE_PLAYERS;
+    return json({
+        available,
+        ...(available ? {} : { note: `${manifest?.name ?? "This product"} exposes no players; the catalogue is informational.` }),
+        players: specs.map((entry) => ({
+            ...describePlayerSpec(entry, true),
+            ...(presets ? { presetValues: playerPresetsFor(entry.id) } : {}),
+        })),
+        roleSpread: roleSpreadSummary(),
+        notes: [
+            "A player replaces what the cell PLAYS, never the drawn pattern: set_player 'off' restores the grid exactly.",
+            "Sequencer output needs the transport running (start_transport).",
+            "Melodic players arm the cell poly with the root on its trigger note; 'off' restores both.",
+            "KIT follows its Genre slot — pass genre to set_player so it matches the track.",
+            "patternMode 'keep' layers the player over the drawn pattern instead of masking it.",
+        ],
+    });
+});
+server.registerTool("set_player", {
+    title: "Set Generative Player",
+    description: "Arm, edit or switch off a cell's generative Player (PAM-only). Passing `player` arms that generator with the " +
+        "roster's own voicing (or a curated `preset`), the track genre on genre-aware players, and a reversible poly " +
+        "arm on melodic ones; omit `player` to edit the running player's values in place. Values land in both the cell " +
+        "config and the cell{N}_player* automation params, like the plugin UI. 'off' restores the drawn pattern and the " +
+        "cell's pre-arm polyphony. The player sounds only while the transport runs. The UI shows a running player " +
+        "unprompted; to arm from the UI as well, update_settings { experimentalMode: true, experimentalGenerativePatterns: true }.",
+    inputSchema: {
+        cellIds: z
+            .array(z.number().int().min(1).max(8))
+            .min(1)
+            .describe("Cells to write (1-8). Several cells take the same write, each snapped to its own player."),
+        player: z
+            .union([z.string(), z.number().int().min(0)])
+            .optional()
+            .describe(`Player to arm: ${PLAYER_REF_HELP}. Omit to edit the running player.`),
+        preset: z.string().optional().describe("Curated preset name for the armed or running player — list_players lists them."),
+        genre: z
+            .enum(PLAYER_GENRES)
+            .optional()
+            .describe("Genre for genre-aware players (KIT's Genre slot). Defaults to the roster default when arming."),
+        density: z.number().min(0).max(1).optional().describe("How much plays, 0..1. Audible from the next step."),
+        mutate: z.number().min(0).max(1).optional().describe("Cycle-to-cycle evolution, 0..1 (below 0.02 locks the loop)."),
+        p1: playerSlotArg(1),
+        p2: playerSlotArg(2),
+        p3: playerSlotArg(3),
+        p4: playerSlotArg(4),
+        p5: playerSlotArg(5),
+        seed: z
+            .union([z.number().int().min(0), z.literal("random")])
+            .optional()
+            .describe("Player seed (uint31) or 'random' to reroll — the DICE gesture."),
+        patternMode: z
+            .enum(PATTERN_MODES)
+            .optional()
+            .describe("'mask' (default, shown as Replace in the UI): the player replaces the drawn pattern. 'keep' (shown as Layer): the drawn pattern keeps sounding and the player layers over it."),
+        listenMode: z
+            .enum(LISTEN_MODES)
+            .optional()
+            .describe("Ensemble listening: react to another cell's last completed cycle — complement its gaps, answer it, or shade velocity harmonically."),
+        listenSource: z.number().int().min(0).max(8).optional().describe("Listening source: 0 = all other cells, 1-8 = one cell (never itself)."),
+        listenAmount: z.number().min(0).max(1).optional().describe("Listening strength 0..1."),
+        poly: z
+            .boolean()
+            .optional()
+            .describe("Override the automatic poly arm: true forces poly, false keeps the cell mono even for a melodic player."),
+    },
+}, async ({ cellIds, player, preset, genre, density, mutate, p1, p2, p3, p4, p5, seed, patternMode, listenMode, listenSource, listenAmount, poly }) => {
+    const check = await requireBridgeForCells(cellIds);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    const gate = playerProductError(manifest);
+    if (gate)
+        return gate;
+    const playerRef = typeof player === "string" ? player.trim().toLowerCase() : player;
+    const wantsOff = playerRef === "off" || playerRef === 0;
+    const wantsRole = playerRef === "role";
+    const explicitSpec = player !== undefined && !wantsOff && !wantsRole ? resolvePlayerSpec(player) : undefined;
+    if (player !== undefined && !wantsOff && !wantsRole && !explicitSpec) {
+        return error(`Unknown player '${player}' — ${PLAYER_REF_HELP}.`);
+    }
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const cellsObj = isRecord(state.cells) ? state.cells : {};
+    const slotInputs = [p1, p2, p3, p4, p5];
+    const flatDelta = {};
+    const cellsDelta = {};
+    const lines = [];
+    for (const cellId of new Set(cellIds)) {
+        const rawCell = cellsObj[String(cellId)];
+        const cell = isRecord(rawCell) ? rawCell : {};
+        const currentType = cellPlayerType(cell);
+        const recorded = (key) => {
+            const value = Number(cell[key]);
+            return Number.isFinite(value) && value !== NO_POLY_ARM ? Math.round(value) : undefined;
+        };
+        if (wantsOff) {
+            if (currentType <= 0) {
+                lines.push(`Cell ${cellId}: no player running.`);
+                continue;
+            }
+            const config = { playerType: 0, playerLastType: currentType };
+            const prePoly = recorded("playerPrePoly");
+            const preRoot = recorded("playerPreRoot");
+            if (prePoly !== undefined)
+                config.isPoly = prePoly;
+            if (preRoot !== undefined)
+                config.polyRootNote = preRoot;
+            config.playerPrePoly = NO_POLY_ARM;
+            config.playerPreRoot = NO_POLY_ARM;
+            cellsDelta[String(cellId)] = config;
+            lines.push(`Cell ${cellId}: ${getPlayerSpec(currentType)?.name ?? "player"} off — drawn pattern restored` +
+                `${prePoly !== undefined || preRoot !== undefined ? ", pre-arm polyphony restored" : ""}.`);
+            continue;
+        }
+        const roleConfig = wantsRole ? rolePlayerConfigFor(cellId) : undefined;
+        const spec = explicitSpec ?? (roleConfig ? getPlayerSpec(roleConfig.playerType) : getPlayerSpec(currentType));
+        if (!spec)
+            return error(`Cell ${cellId} runs no player. Pass player to arm one — ${PLAYER_REF_HELP}.`);
+        const arming = explicitSpec !== undefined || roleConfig !== undefined;
+        const config = {};
+        if (arming) {
+            Object.assign(config, playerDefaultsFor(spec.id), playerGenreConfig(spec, genre));
+            if (roleConfig?.playerP1 !== undefined)
+                config.playerP1 = roleConfig.playerP1;
+            if (roleConfig?.playerP5 !== undefined)
+                config.playerP5 = roleConfig.playerP5;
+            config.playerLastType = spec.id;
+        }
+        else if (genre) {
+            Object.assign(config, playerGenreConfig(spec, genre));
+        }
+        if (preset) {
+            const found = resolvePlayerPreset(spec, preset);
+            if (!found) {
+                const names = playerPresetsFor(spec.id).map((entry) => entry.name);
+                return error(`${spec.name} has no preset '${preset}' — one of: ${names.join(", ")}.`);
+            }
+            Object.assign(config, presetConfig(found));
+        }
+        if (density !== undefined)
+            config.playerDensity = density;
+        if (mutate !== undefined)
+            config.playerMutate = mutate;
+        for (let i = 0; i < slotInputs.length; i++) {
+            const input = slotInputs[i];
+            if (input === undefined)
+                continue;
+            const slot = spec.slots[i];
+            if (!slot)
+                return error(`${spec.name} has no P${i + 1} slot (it has ${spec.slots.length}).`);
+            const resolved = resolveSlotValue(slot, input);
+            if (typeof resolved === "string")
+                return error(`Cell ${cellId} ${spec.name} P${i + 1}: ${resolved}`);
+            config[PLAYER_SLOT_FIELDS[i]] = resolved;
+        }
+        PLAYER_SLOT_FIELDS.forEach((field, i) => {
+            if (config[field] !== undefined)
+                config[field] = snapPlayerValue(spec.slots[i]?.steps, config[field]);
+        });
+        if (seed !== undefined)
+            config.playerSeed = seed === "random" ? randomPlayerSeed() : Math.round(seed);
+        if (patternMode)
+            config.playerPatternMode = PATTERN_MODES.indexOf(patternMode);
+        if (listenMode)
+            config.playerListenMode = LISTEN_MODES.indexOf(listenMode);
+        if (listenSource !== undefined)
+            config.playerListenSource = listenSource;
+        if (listenAmount !== undefined)
+            config.playerListenAmount = listenAmount;
+        // Reversible poly arm: record the pre-arm values once, never the armed state.
+        const autoPoly = arming && poly !== false && (isMelodicPlayer(spec) || roleConfig?.isPoly === 1);
+        let polyNote = "";
+        if (autoPoly) {
+            if (recorded("playerPrePoly") === undefined && recorded("playerPreRoot") === undefined) {
+                config.playerPrePoly = Math.round(Number(cell.isPoly ?? 0)) || 0;
+                config.playerPreRoot = Math.round(Number(cell.polyRootNote ?? 48)) || 48;
+            }
+            config.isPoly = 1;
+            config.polyRootNote = Math.round(Number(cell.midiNote ?? 47 + cellId)) || 47 + cellId;
+            polyNote = `; poly armed (root ${config.polyRootNote})`;
+        }
+        else if (poly !== undefined) {
+            config.isPoly = poly ? 1 : 0;
+            polyNote = `; poly ${poly ? "on" : "off"}`;
+        }
+        if (arming)
+            config.playerType = spec.id;
+        if (Object.keys(config).length === 0)
+            return error("Nothing to write — pass player, preset, or at least one value.");
+        cellsDelta[String(cellId)] = config;
+        for (const field of MODULATABLE_PLAYER_FIELDS) {
+            if (typeof config[field] === "number")
+                flatDelta[`cell${cellId}_${field}`] = config[field];
+        }
+        const parts = [];
+        if (config.playerDensity !== undefined)
+            parts.push(`density ${playerDensityDisplay(config.playerDensity)}`);
+        if (config.playerMutate !== undefined)
+            parts.push(`mutate ${playerMutateDisplay(config.playerMutate)}`);
+        spec.slots.forEach((slot, i) => {
+            const value = config[PLAYER_SLOT_FIELDS[i]];
+            if (value !== undefined)
+                parts.push(`${slot.label}=${playerSlotDisplay(slot, value)}`);
+        });
+        if (config.playerSeed !== undefined)
+            parts.push(`seed ${config.playerSeed}`);
+        if (patternMode)
+            parts.push(`pattern ${patternMode}`);
+        if (listenMode)
+            parts.push(`listen ${listenMode}`);
+        lines.push(`Cell ${cellId}: ${spec.name} ${arming ? "armed" : "updated"} — ${parts.join(", ")}${polyNote}.`);
+    }
+    if (Object.keys(cellsDelta).length === 0)
+        return text(lines.join("\n"));
+    await applyKv({ ...flatDelta, cells: cellsDelta }, CELL_CONFIG_KV_OPTIONS);
+    return text(`${lines.join("\n")}\n` +
+        "Players sound only while the transport runs; get_design_overview reports each cell's player.");
+});
+server.registerTool("keep_player", {
+    title: "Keep a Player's Cycles",
+    description: "Commit what a cell's generative Player played into its drawn pattern (PAM-only), through the plugin UI so it is " +
+        "one undo step: 'cycle' merges the cycle playing now, 'previous' the one before it, 'last-two' both, and 'freeze' " +
+        "merges the cycle and switches the Player off. Merges are unions with the drawn notes. Needs the PAM window open " +
+        "and the transport having run a cycle; the commit is asynchronous, so read cell{N}_midiSequence with get_state after.",
+    inputSchema: {
+        cellId: z.number().int().min(1).max(8).describe("The Player cell (1-8)."),
+        keep: z.enum(["cycle", "previous", "last-two", "freeze"]).describe("Which cycles to commit; 'freeze' also switches the Player off."),
+    },
+}, async ({ cellId, keep }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const gate = playerProductError(await loadManifestForProductGuard());
+    if (gate)
+        return gate;
+    const cells = await bridge.send("getState", "cells").catch(() => undefined);
+    const cell = isRecord(cells) ? cells[String(cellId)] : undefined;
+    if (!(isRecord(cell) && Number(cell.playerType) > 0))
+        return error(`Cell ${cellId} runs no Player — nothing to keep.`);
+    await bridge.send("playerKeep", { cellId, keep });
+    return text(`Cell ${cellId}: ${keep === "freeze" ? "freeze" : `keep ${keep}`} sent to the plugin window. ` +
+        "Nothing lands if that cycle has not played yet; check cell" + cellId + "_midiSequence.");
+});
+/** A cell's sample as a readable file: absolute as given, else relative to a library root. */
+async function resolveCellSampleFile(filePath) {
+    const expanded = expandHome(filePath);
+    if (isAbsolute(expanded))
+        return existsSync(expanded) ? expanded : undefined;
+    const locations = await bridge.send("getDefaultLocations").catch(() => undefined);
+    const roots = Array.isArray(locations)
+        ? locations.filter((entry) => isRecord(entry) && typeof entry.path === "string")
+        : [];
+    const normalized = filePath.replaceAll("\\", "/");
+    const candidates = [];
+    for (const root of roots) {
+        const stripped = normalized.replace(/^Samples\/(User|Factory)\//, "");
+        if (/user/i.test(root.name) && /^Samples\/User\//.test(normalized))
+            candidates.push(join(root.path, stripped));
+        if (/factory/i.test(root.name) && /^Samples\/Factory\//.test(normalized))
+            candidates.push(join(root.path, stripped));
+        candidates.push(join(root.path, normalized), join(root.path, stripped));
+    }
+    return candidates.find((candidate) => existsSync(candidate));
+}
+server.registerTool("set_slices", {
+    title: "Set Sample Slices",
+    description: "Slice the sample loaded in a cell: explicit `boundaries` (0..1 of the file), `count` equal slices, or " +
+        "`transients` detected from the audio (WAV files, offline). Writes cell{N}_sliceBoundaries / _sliceCount — " +
+        "what the slice lane, Slice Keymap, preview_slice and export_slice all read — and switches the Slice knob on. " +
+        "`sequence:true` also chops the loop into the slice + note lanes so it plays back in order at native rate " +
+        "(the Slice → Sequence gesture: modLatch on, both lanes at 1× over the loop's length in beats).",
+    inputSchema: {
+        cellId: z.number().int().min(1).max(8).describe("Cell number (1-8); it must have a sample loaded."),
+        boundaries: z
+            .array(z.number().min(0).max(1))
+            .min(2)
+            .max(MAX_SLICES + 1)
+            .optional()
+            .describe("Slice boundaries as 0..1 positions in the file, ascending; 0 and 1 are added when missing."),
+        count: z.number().int().min(1).max(MAX_SLICES).optional().describe(`Equal slices, 1..${MAX_SLICES}.`),
+        transients: z.boolean().optional().describe("Detect onsets in the sample and slice there (WAV only)."),
+        sensitivity: z.number().min(0).max(1).optional().describe("Transient sensitivity 0..1 (default 0.5; higher finds more onsets)."),
+        maxSlices: z.number().int().min(2).max(MAX_SLICES).optional().describe("Cap on transient slices (default 32)."),
+        sequence: z.boolean().optional().describe("Also write the slice + note lanes so the slices play in order (loops)."),
+    },
+}, async ({ cellId, boundaries, count, transients, sensitivity, maxSlices, sequence }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && isMfxManifest(manifest))
+        return error("set_slices needs a sampler cell; MFX cells carry no sample.");
+    const modes = [boundaries !== undefined, count !== undefined, transients === true].filter(Boolean).length;
+    if (modes !== 1)
+        return error("Pass exactly one of boundaries, count, or transients:true.");
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const cellsObj = isRecord(state.cells) ? state.cells : {};
+    const cell = isRecord(cellsObj[String(cellId)]) ? cellsObj[String(cellId)] : {};
+    const filePath = [cell.filePath, cell.samplePath, state[`cell${cellId}_filePath`]].find((v) => typeof v === "string" && v.length > 0);
+    if (!filePath)
+        return error(`Cell ${cellId} has no sample loaded — load_sample first.`);
+    let resolved;
+    let wavDuration;
+    if (boundaries)
+        resolved = normalizeBoundaries(boundaries);
+    else if (count !== undefined)
+        resolved = equalBoundaries(count);
+    else {
+        const file = await resolveCellSampleFile(filePath);
+        if (!file)
+            return error(`Could not find '${filePath}' on disk to analyse — pass count or boundaries instead.`);
+        let wav;
+        try {
+            wav = decodeWav(await readFile(file));
+        }
+        catch (e) {
+            return error(`Transient slicing reads WAV files only (${e.message}) — pass count or boundaries for ${basename(file)}.`);
+        }
+        wavDuration = wav.durationSeconds;
+        resolved = detectOnsetBoundaries(wav, sensitivity ?? 0.5, maxSlices ?? 32);
+        if (resolved.length < 3)
+            return error("No transients found above the threshold — raise sensitivity or pass count.");
+    }
+    const sliceCount = resolved.length - 1;
+    const currentKnob = Number(state[`cell${cellId}_slice`]) || 0;
+    const delta = {
+        [`cell${cellId}_sliceBoundaries`]: resolved,
+        [`cell${cellId}_sliceCount`]: sliceCount,
+    };
+    if (currentKnob < 1 || currentKnob > sliceCount)
+        delta[`cell${cellId}_slice`] = 1;
+    await applyKv(delta, CELL_CONFIG_KV_OPTIONS);
+    let sequenceNote = "";
+    if (sequence) {
+        const transportRaw = await bridge.send("getTransport").catch(() => undefined);
+        const bpm = Number(isRecord(transportRaw) ? transportRaw.bpm : undefined) || Number(state.bpm) || 120;
+        let duration = wavDuration;
+        if (duration === undefined) {
+            const info = await bridge.send("getAudioFileInfo", filePath).catch(() => undefined);
+            const parsed = typeof info === "string" ? JSON.parse(info) : info;
+            duration = [parsed?.duration, parsed?.durationSeconds, parsed?.lengthSeconds, parsed?.length]
+                .map(Number)
+                .find((v) => Number.isFinite(v) && v > 0);
+        }
+        const loopBeats = duration ? (duration * bpm) / 60 : Number(state[`cell${cellId}_patternLengthSlice`]) || 16;
+        const patternLength = Math.max(1, Math.min(32, duration ? Math.ceil(loopBeats) : loopBeats));
+        const note = typeof cell.midiNote === "number" ? cell.midiNote : 48 + cellId - 1;
+        const channel = typeof cell.midiChannel === "number" ? cell.midiChannel : 1;
+        const sliceEvents = [];
+        const noteEvents = [];
+        for (let i = 0; i < sliceCount; i++) {
+            const time = resolved[i] * loopBeats;
+            const dur = (resolved[i + 1] - resolved[i]) * loopBeats;
+            if (dur <= 0)
+                continue;
+            sliceEvents.push({ note, channel, time, duration: dur, velocity: 100, value: i + 1 });
+            noteEvents.push({ note, channel, time, duration: dur, velocity: 100 });
+        }
+        await applyKv({
+            [`cell${cellId}_sliceSequence`]: sliceEvents,
+            [`cell${cellId}_midiSequence`]: noteEvents,
+            [`cell${cellId}_patternLengthSlice`]: patternLength,
+            [`cell${cellId}_patternLength`]: patternLength,
+            [`cell${cellId}_patternSpeedSlice`]: 9,
+            [`cell${cellId}_patternSpeed`]: 9,
+            [`cell${cellId}_patternDirection`]: 0,
+            [`cell${cellId}_slice`]: 1,
+            cells: { [cellId]: { modLatch: 1 } },
+            __forceRender__: true,
+        }, 
+        // Pattern lengths are DAW params and modLatch is cell config: interop's
+        // applySliceSequenceFromBoundaries syncs both, so this must too.
+        { ...PATTERN_EDIT_KV_OPTIONS, syncConfigResources: true, updateParameters: true });
+        sequenceNote = ` Chopped into the slice + note lanes over ${patternLength} beats at ${bpm} BPM; start_transport to hear it.`;
+    }
+    const positions = resolved.slice(1, -1).map((b) => `${Math.round(b * 1000) / 10}%`);
+    return text(`Cell ${cellId}: ${sliceCount} slice${sliceCount === 1 ? "" : "s"}` +
+        `${positions.length ? ` (cuts at ${positions.join(", ")})` : ""}.${sequenceNote}`);
+});
 server.registerTool("add_param_seq", {
     title: "Add Parameter Sequencer",
     description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
@@ -5309,17 +6261,23 @@ server.registerTool("add_param_seq", {
         bipolar: z.union([z.literal(0), z.literal(1)]).default(0).describe("0 = unipolar, 1 = bipolar."),
         length: z.number().min(0.0625).max(16).default(1).describe("Pattern length in bars."),
         speed: z.number().min(0.0625).max(16).default(1).describe("Pattern speed multiplier."),
+        freeMode: z
+            .union([z.literal(0), z.literal(1)])
+            .default(0)
+            .describe("0 = locked to the source cell's clock and its own steps; 1 = mapped to the Free Sequencer (its clock AND its master steps, set_free_sequencer)."),
+        stepMode: z
+            .union([z.literal(0), z.literal(1)])
+            .default(0)
+            .describe("0 = Clock; 1 = Gate: advance one step per trigger of the source cell (cell-locked only; MFX has no Gate)."),
     },
-}, async ({ paramId, cellId, sequence, strength, bipolar, length, speed }) => {
+}, async ({ paramId, cellId, sequence, strength, bipolar, length, speed, freeMode, stepMode }) => {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
     const index = await getParameterIndex();
-    const param = index.get(paramId);
-    if (!param)
-        return error(formatUnknownParamError(paramId, index, { modulatableOnly: true }));
-    if (!param.isModulatable)
-        return error(formatNotModulatableError(paramId, index));
+    const param = await resolveModulationTarget(paramId, index);
+    if (typeof param === "string")
+        return error(param);
     const existing = await bridge.send("getState", "paramSeqs");
     const paramSeqs = (Array.isArray(existing) ? existing : []).filter((seq) => seq?.paramId !== paramId);
     const newSeq = {
@@ -5333,10 +6291,11 @@ server.registerTool("add_param_seq", {
         bipolar,
         boost: 0,
         interpolate: 0,
-        freeMode: 0,
+        freeMode,
+        stepMode,
     };
     paramSeqs.push(newSeq);
-    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    await applyKv({ paramSeqs }, STATE_UPDATE_KV_OPTIONS);
     return text(`Added paramSeq for ${paramId} (${newSeq.sequence.length} steps, strength ${strength}).`);
 });
 server.registerTool("update_param_seq", {
@@ -5346,11 +6305,19 @@ server.registerTool("update_param_seq", {
     inputSchema: {
         paramId: z.string().describe("Target parameter ID."),
         sequence: z.array(z.number().min(0).max(1)).optional().describe("New step values (0-1)."),
-        strength: z.number().min(0).max(1).optional(),
-        length: z.number().min(0.0625).max(16).optional(),
-        speed: z.number().min(0.0625).max(16).optional(),
-        bipolar: z.union([z.literal(0), z.literal(1)]).optional(),
-        enabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        strength: z.number().min(0).max(1).optional().describe("Modulation depth (0-1)."),
+        length: z.number().min(0.0625).max(16).optional().describe("Pattern length in bars."),
+        speed: z.number().min(0.0625).max(16).optional().describe("Pattern speed multiplier."),
+        bipolar: z.union([z.literal(0), z.literal(1)]).optional().describe("0 = unipolar, 1 = bipolar."),
+        enabled: z.union([z.literal(0), z.literal(1)]).optional().describe("0 = bypass the sequencer, 1 = run it."),
+        freeMode: z
+            .union([z.literal(0), z.literal(1)])
+            .optional()
+            .describe("0 = cell-locked with its own steps; 1 = mapped to the Free Sequencer master contour (set_free_sequencer)."),
+        stepMode: z
+            .union([z.literal(0), z.literal(1)])
+            .optional()
+            .describe("0 = Clock; 1 = Gate (one step per source-cell trigger; falls back to Clock when free or on MFX)."),
     },
 }, async ({ paramId, ...updates }) => {
     const check = await requireBridge();
@@ -5371,9 +6338,150 @@ server.registerTool("update_param_seq", {
         return error(`No paramSeq found for ${paramId}. Use add_param_seq first.`);
     }
     paramSeqs[idx] = { ...paramSeqs[idx], ...cleanUpdates };
-    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    await applyKv({ paramSeqs }, STATE_UPDATE_KV_OPTIONS);
     return text(`Updated paramSeq ${paramId}: ${Object.keys(cleanUpdates).join(", ")}`);
 });
+server.registerTool("set_free_sequencer", {
+    title: "Set Free Sequencer",
+    description: "Write the Free Sequencer's master step contour (top-level `freeSeqSequence`, 2..64 steps of 0..1). Every " +
+        "parameter sequencer mapped to it (freeMode:1 via add_param_seq / update_param_seq) follows these steps AND its " +
+        "clock live, each with its own strength, polarity and smoothing; cell-locked and Gate-mode sequencers keep " +
+        "their own steps. An empty contour restores the legacy per-sequencer behaviour.",
+    inputSchema: {
+        sequence: z
+            .array(z.number().min(0).max(1))
+            .max(64)
+            .describe("Master step values, 0..1 each: 2..64 steps, or [] to clear the contour."),
+    },
+}, async ({ sequence }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (sequence.length === 1)
+        return error("A contour needs 2..64 steps; pass [] to clear it.");
+    await bridge.send("applyFreeSeqSequenceUpdate", { sequence });
+    if (sequence.length === 0)
+        return text("Free Sequencer contour cleared; mapped sequencers use their own steps.");
+    return text(`Free Sequencer: ${sequence.length} steps written. Map a paramSeq with freeMode:1 to follow it.`);
+});
+server.registerTool("export_midi", {
+    title: "Export MIDI",
+    description: "Write the cells' note patterns to a Standard MIDI File (type 1, 480 PPQ, tempo from the transport): " +
+        "one track per cell on MIDI channel = cell number, across `bars`. A Player cell exports the cycles it " +
+        "generates (density-gated, PATTERN Keep layered), rendered by PAM itself; Listen responses are left out. " +
+        "Grid timing from base values: swing, probability, CTRL macros and modulators are not applied. Nothing " +
+        "changes in PAM. Default location " +
+        "is PAM's Exports folder.",
+    inputSchema: {
+        filename: z.string().optional().describe("Base name without extension (default pam_midi_<epoch>)."),
+        cellIds: z.array(z.number().int().min(1).max(8)).optional().describe("Cells to include (default: every cell with notes)."),
+        bars: z.number().min(1).max(64).optional().describe("Length in 4/4 bars (default: the longest included pattern cycle, at least 1)."),
+        mode: z.enum(["combined", "stems"]).optional().describe("'combined' (default): one multi-track file. 'stems': one file per cell."),
+        outputDir: z.string().optional().describe("Directory to write into (default: PAM's Exports folder)."),
+    },
+}, async ({ filename, cellIds, bars, mode, outputDir }) => {
+    const check = await requireBridgeForCells(cellIds);
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && isMfxManifest(manifest))
+        return error("export_midi needs sampler cells with note patterns; MFX has none.");
+    const [stateRaw, transportRaw, exportsDir] = await Promise.all([
+        bridge.send("getState"),
+        bridge.send("getTransport").catch(() => undefined),
+        exportsFolder(),
+    ]);
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const bpm = Number(isRecord(transportRaw) ? transportRaw.bpm : undefined) || Number(state.bpm) || 120;
+    const dir = outputDir ? expandHome(outputDir) : exportsDir;
+    if (!dir)
+        return error("Could not resolve PAM's Exports folder from get_default_locations — pass outputDir.");
+    const maxCell = manifestMaxCellId(manifest) ?? 8;
+    const ids = (cellIds?.length ? cellIds : Array.from({ length: maxCell }, (_, i) => i + 1)).filter((id) => id <= maxCell);
+    const cellConfig = (id) => {
+        const cells = isRecord(state.cells) ? state.cells : {};
+        const config = cells[String(id)];
+        return isRecord(config) ? config : {};
+    };
+    const playerIds = ids.filter((id) => Number(cellConfig(id).playerType) > 0);
+    // A GRAB follower plays its source's notes, so an empty own grid does not rule it out.
+    const followerIds = ids.filter((id) => Number(cellConfig(id).seqFrom) > 0);
+    const cells = ids
+        .map((id) => ({
+        id,
+        sequence: state[`cell${id}_midiSequence`],
+        patternLength: state[`cell${id}_patternLength`],
+        speed: state[`cell${id}_patternSpeed`],
+    }))
+        .filter((cell) => (Array.isArray(cell.sequence) && cell.sequence.length > 0) || playerIds.includes(cell.id) || followerIds.includes(cell.id));
+    if (cells.length === 0)
+        return error("No note patterns to export — the selected cells carry no notes and run no Player.");
+    const cycleBars = cells.map((cell) => {
+        const length = Number(cell.patternLength);
+        const speedIndex = Math.round(Number(cell.speed));
+        const mul = Number.isFinite(speedIndex) ? patternSpeedMultiplier(speedIndex) : 1;
+        return (Number.isFinite(length) && length > 0 ? length : 4) / mul / 4;
+    });
+    const totalBars = bars ?? Math.max(1, Math.ceil(Math.max(...cycleBars)));
+    const totalBeats = totalBars * 4;
+    // PAM renders the notes itself (Player cycles included); a build without the route
+    // falls back to tiling the drawn grids here. Any other failure is reported, not tiled.
+    let native;
+    try {
+        native = await bridge.send("getMidiExportEvents", { beats: totalBeats, cellIds: cells.map((cell) => cell.id) });
+    }
+    catch (e) {
+        const msg = e.message;
+        if (!/unknown action|does not support/i.test(msg))
+            return error(`export_midi failed: ${msg}`);
+    }
+    const nativeCells = isRecord(native) && Array.isArray(native.cells) ? native.cells.filter(isRecord) : undefined;
+    const staleBuildNote = !nativeCells && playerIds.length > 0
+        ? `This PAM build predates Player-aware export: cell ${playerIds.join(", ")} exported its drawn grid, not the Player. Update PAM.`
+        : undefined;
+    const tracks = cells
+        .map((cell) => {
+        const rendered = nativeCells?.find((entry) => Number(entry.cellId) === cell.id);
+        const channel = Math.min(16, cell.id);
+        const events = rendered && Array.isArray(rendered.events)
+            ? rendered.events.filter(isRecord).map((e) => ({
+                channel,
+                note: Number(e.note),
+                velocity: Number(e.velocity),
+                startBeats: Number(e.startBeats),
+                durationBeats: Number(e.durationBeats),
+            }))
+            : tilePatternEvents(cell.sequence, cell.patternLength, cell.speed, totalBeats, channel);
+        return { name: `Cell ${cell.id}`, events };
+    })
+        .filter((track) => track.events.length > 0);
+    if (tracks.length === 0)
+        return error(staleBuildNote ?? "No notes to export — the selected cells rendered nothing over that length.");
+    const notes = [];
+    if (staleBuildNote)
+        notes.push(staleBuildNote);
+    const listening = playerIds.filter((id) => Number(cellConfig(id).playerListenMode) > 0 && cells.some((cell) => cell.id === id));
+    if (nativeCells && listening.length > 0)
+        notes.push(`Cell ${listening.join(", ")} listens to other cells; the file carries its cycles without that response.`);
+    const base = (filename?.trim() || `pam_midi_${Date.now()}`).replace(/\.mid$/i, "").replace(/[\\/:]/g, "_");
+    await mkdir(dir, { recursive: true });
+    const written = [];
+    if (mode === "stems") {
+        for (const track of tracks) {
+            const path = join(dir, `${base}_cell${track.name.slice(5)}.mid`);
+            await writeFile(path, buildMidiFile(bpm, [track], track.name));
+            written.push(path);
+        }
+    }
+    else {
+        const path = join(dir, `${base}.mid`);
+        await writeFile(path, buildMidiFile(bpm, tracks, base));
+        written.push(path);
+    }
+    const noteCount = tracks.reduce((sum, track) => sum + track.events.length, 0);
+    return text(`Exported ${noteCount} notes from ${tracks.length} cell${tracks.length === 1 ? "" : "s"} over ${totalBars} bar${totalBars === 1 ? "" : "s"} at ${bpm} BPM.\n` +
+        [...written.map((path) => `File: ${path}`), ...notes].join("\n"));
+});
 server.registerTool("remove_param_seq", {
     title: "Remove Parameter Sequencer",
     description: "Remove a parameter sequencer for the given paramId.",
@@ -5387,7 +6495,7 @@ server.registerTool("remove_param_seq", {
         return check;
     const existing = await bridge.send("getState", "paramSeqs");
     const paramSeqs = (Array.isArray(existing) ? existing : []).filter((seq) => seq?.paramId !== paramId);
-    await applyKv({ paramSeqs }, KV_OPTS_MOD);
+    await applyKv({ paramSeqs }, STATE_UPDATE_KV_OPTIONS);
     return text(`Removed paramSeq for ${paramId}.`);
 });
 server.registerTool("normalize_sample", {
@@ -5400,6 +6508,9 @@ server.registerTool("normalize_sample", {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
+    const loaded = await requireCellSample(cellId);
+    if (loaded !== true)
+        return loaded;
     await bridge.send("normalizeSampleForCell", cellId);
     return text(`Normalized sample in cell ${cellId}.`);
 });
@@ -5419,9 +6530,64 @@ server.registerTool("gain_sample", {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
+    const loaded = await requireCellSample(cellId);
+    if (loaded !== true)
+        return loaded;
     await bridge.send("gainSampleForCell", { cellId, gainDb });
     return text(`Applied ${gainDb > 0 ? "+" : ""}${gainDb} dB to the sample in cell ${cellId}.`);
 });
+// Mirrors pam::repitch::kMaxCoarseSemitones / kMaxFineCents (modules/sampler/SampleRepitch.h).
+const REPITCH_COARSE_RANGE = 24;
+const REPITCH_FINE_RANGE = 100;
+const PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+const pitchName = (midi) => {
+    const note = Math.round(midi);
+    const cents = Math.round((midi - note) * 100);
+    const name = `${PITCH_NAMES[((note % 12) + 12) % 12]}${Math.floor(note / 12) - 1}`;
+    return cents === 0 ? name : `${name} ${cents > 0 ? "+" : ""}${cents} cents`;
+};
+server.registerTool("analyze_sample_pitch", {
+    title: "Analyze Sample Pitch",
+    description: "Detect the fundamental of a cell's single-note sample and suggest the repitch_sample shift that centres it on the nearest C. " +
+        "The sampler's root note is a C, so a sample centred on C is the one the global tuning layer retunes correctly.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+    },
+}, async ({ cellId }) => {
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    const result = (await bridge.send("analyzeSamplePitch", cellId));
+    if (!result?.loaded)
+        return error(`Cell ${cellId} has no readable sample.`);
+    const hz = result.hz ?? 0;
+    if (hz <= 0)
+        return text(`No stable pitch in cell ${cellId}'s sample; tune it by ear with repitch_sample.`);
+    const midi = 69 + 12 * Math.log2(hz / 440);
+    const target = Math.round(midi / 12) * 12;
+    const semitones = Math.round(target - midi) || 0;
+    const cents = Math.round((target - midi - semitones) * 100) || 0;
+    return text(`Cell ${cellId} sounds ${pitchName(midi)} (${hz.toFixed(2)} Hz, confidence ${Math.round((result.confidence ?? 0) * 100)}%). ` +
+        `Nearest C is ${pitchName(target)}: repitch_sample with semitones ${semitones}, cents ${cents}.`);
+});
+server.registerTool("repitch_sample", {
+    title: "Repitch Sample",
+    description: "Varispeed a cell's sample by semitones plus cents and render it into a new file (offline, destructive): pitch and length change together, like tape. " +
+        "analyze_sample_pitch suggests the shift that centres a single-note sample on C. The original library file is left unchanged.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        semitones: z.number().int().min(-REPITCH_COARSE_RANGE).max(REPITCH_COARSE_RANGE).describe("Coarse shift in semitones."),
+        cents: z.number().min(-REPITCH_FINE_RANGE).max(REPITCH_FINE_RANGE).default(0).describe("Fine shift in cents."),
+    },
+}, async ({ cellId, semitones, cents }) => {
+    if (semitones === 0 && cents === 0)
+        return error("A zero shift leaves the sample unchanged.");
+    const check = await requireBridgeForCells(cellId);
+    if (check !== true)
+        return check;
+    await bridge.send("repitchSampleForCell", { cellId, semitones, cents });
+    return text(`Repitched the sample in cell ${cellId} by ${semitones} semitones ${cents} cents.`);
+});
 // 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();
@@ -5462,7 +6628,9 @@ server.registerTool("export_audio", {
         "'per-bus' (per output bus) · 'song-mode' (the Song Mode timeline).\n\n" +
         "NOTE on 'song-mode': the offline bounce applies EVERY section on its anchor (PAM ≥ 1.5.7 with " +
         "offline song export; older builds render only the first section). Wall-clock sources " +
-        "(Magenta/Notochord) render silent offline — use the `export_song` tool's live strategy for those.",
+        "(Magenta/Notochord) render silent offline — use the `export_song` tool's live strategy for those. " +
+        "It issues the same render as `export_song` with strategy 'offline'; prefer `export_song` for arrangements, " +
+        "which is the only route to the live and audio+video strategies.",
     inputSchema: {
         bars: z.number().min(1).max(128).default(4).describe("Bars to render (ignored for 'song-mode', which derives length from the timeline)."),
         cellId: z
@@ -5480,9 +6648,9 @@ server.registerTool("export_audio", {
             .optional()
             .describe("For mode 'selected-cells': cells to bounce as stems."),
         bitDepth: z
-            .number()
+            .union([z.literal(16), z.literal(24)])
             .default(24)
-            .describe("Bit depth (16 or 24)."),
+            .describe("Bit depth: 16 or 24."),
     },
 }, async ({ bars, cellId, mode, selectedCellIds, bitDepth }) => {
     const check = await requireBridgeForCells(cellId, selectedCellIds);
@@ -6033,10 +7201,10 @@ if (!IS_MFX_SERVER)
         },
     }, ({ 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` +
+        `2. ${bpm ? `set_bpm to ${bpm}` : "set_bpm to the genre's tempo"}.\n` +
+        `3. Build the kit and groove with randomize target:'full'${genre ? ` and genreHint '${genre}'` : " (pass a genreHint)"}; native chains samples before patterns. The reply is queued: poll get_state for changed cells and cellN_midiSequence before editing/saving. For specific sounds: get_default_locations → list_samples → load_sample, verify paths, then randomize_patterns and verify sequences.\n` +
         `4. start_transport — sequencer output needs the transport rolling.\n` +
-        `5. Refine: update_pattern for individual lanes, set_parameters for levels/filters (ranges via design_context), update_effect_config to switch FX on, add_modulation for movement.\n` +
+        `5. Refine: update_pattern for individual lanes, set_parameters for levels/filters (ranges via design_context), update_effect_config to switch FX on, add_modulation for movement. For a groove that evolves, set_player (player 'role' across the kit, or KIT / EUCLID / RIFF per cell — list_players first${genre ? `, genre '${genre}'` : ""}).\n` +
         `6. save_preset once it works, and update_preset_metadata with genre tags and BPM.`));
 if (!IS_MFX_SERVER)
     server.registerPrompt("make-a-song", {
@@ -6090,26 +7258,17 @@ if (!IS_MFX_SERVER)
 // ============================================================
 // TOOLS — Looper (state deltas)
 // ============================================================
-// applyStateDelta-equivalent options: full update, dispatch graph, sync KV.
-const KV_OPTS_LOOPER_STATE = {
-    shouldDispatch: true,
-    syncKVResources: true,
-    syncConfigResources: true,
-    resyncKVAfterDispatch: true,
-    updateParameters: true,
-    broadcastFollowers: true,
-};
 async function applyLoopersDelta(loopers, extra) {
     const delta = { loopers, ...(extra ?? {}) };
     await bridge.send("applyUnifiedStateKvUpdate", {
         delta,
-        options: KV_OPTS_LOOPER_STATE,
+        options: STATE_UPDATE_KV_OPTIONS,
     });
 }
 server.registerTool("arm_looper_track", {
     title: "Arm / Disarm Looper Track",
     description: "Arm or disarm a looper track for recording. Arming alone does not start " +
-        "recording — call start_looper_recording afterwards (or use arm_and_record).",
+        "recording — call start_looper_recording afterwards, or pass armedCellIds to start_looper_recording to arm and record in one call.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
         armed: z.boolean().describe("true to arm, false to disarm."),
@@ -6123,8 +7282,8 @@ server.registerTool("arm_looper_track", {
 });
 server.registerTool("set_looper_track", {
     title: "Set Looper Track State",
-    description: "Update one or more per-track looper fields (mute, overdub mode, reverse, " +
-        "pitch, warp, capture source, level). Pass only the fields you want to change.",
+    description: "Update one or more per-track looper fields (mute, solo, overdub mode, reverse, " +
+        "pitch, warp, capture source, level, auto-select and recorded BPM). Pass only the fields you want to change.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Looper track / cell (1-8)."),
         mute: z.boolean().optional().describe("Mute / unmute."),
@@ -6406,7 +7565,7 @@ server.registerTool("looper_settings", {
 server.registerTool("looper_variation", {
     title: "Looper Variation",
     description: "Manage looper variation slots (clip-set snapshots). Operations: 'apply' (immediate), 'queue' (bar-synced), " +
-        "'cancel', 'clear', 'setCurrent', 'save' (snapshot current looper state into the slot).",
+        "'cancel', 'clear', 'setCurrent', 'save' (write a snapshot object from the `data` field into the slot).",
     inputSchema: {
         op: z
             .enum(["apply", "queue", "cancel", "clear", "setCurrent", "save"])
@@ -6419,7 +7578,7 @@ server.registerTool("looper_variation", {
             .describe("Variation slot 0-7 (required for apply/queue/clear/setCurrent/save)."),
         intervalBars: z
             .number()
-            .min(0.125)
+            .min(0.25)
             .max(64)
             .optional()
             .describe("Bar interval for 'queue' (required for queue)."),
@@ -6427,7 +7586,7 @@ server.registerTool("looper_variation", {
         data: z
             .record(z.string(), z.unknown())
             .optional()
-            .describe("For 'save': the looper variation snapshot (object). Pass null to clear instead."),
+            .describe("For 'save' (required): the looper variation snapshot object. Use op 'clear' to empty a slot."),
     },
 }, async (args) => {
     const check = await requireBridge();
@@ -6464,10 +7623,10 @@ server.registerTool("looper_variation", {
         case "save":
             if (args.index === undefined)
                 return error("'save' requires index");
-            await bridge.send("saveLooperVariation", { index: args.index, data: args.data ?? null });
-            return text(args.data
-                ? `Saved looper variation slot ${args.index}.`
-                : `Cleared looper variation slot ${args.index} (no data).`);
+            if (!args.data)
+                return error("'save' requires data (a looper variation snapshot); use op 'clear' to empty a slot.");
+            await bridge.send("saveLooperVariation", { index: args.index, data: args.data });
+            return text(`Saved looper variation slot ${args.index}.`);
     }
     return text("No-op");
 });
@@ -6476,12 +7635,18 @@ server.registerTool("looper_variation_sync", {
     description: "Configure how looper variation switches synchronize to bar boundaries.",
     inputSchema: {
         barSyncEnabled: z.boolean().optional().describe("Toggle bar-sync mode."),
-        intervalBars: z.number().min(0.125).max(64).optional().describe("Sync interval in bars."),
+        intervalBars: z
+            .number()
+            .optional()
+            .describe(`Sync interval in bars: one of ${LOOPER_BAR_SYNC_INTERVALS.join(", ")}.`),
     },
 }, async ({ barSyncEnabled, intervalBars }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    if (intervalBars !== undefined && !LOOPER_BAR_SYNC_INTERVALS.includes(intervalBars)) {
+        return error(`intervalBars must be one of ${LOOPER_BAR_SYNC_INTERVALS.join(", ")}; native resets anything else to 1.`);
+    }
     const updates = [];
     if (typeof barSyncEnabled === "boolean") {
         await bridge.send("setLooperVariationBarSyncEnabled", barSyncEnabled);
@@ -6504,22 +7669,22 @@ server.registerTool("queue_variation", {
         "already-engaged queued-flip window only; a from-idle flip hard-switches).",
     inputSchema: {
         index: z.number().min(0).max(7).describe("Variation slot 0-7."),
-        intervalBars: z.number().min(0.125).max(64).describe("Bars before switching."),
-        fadeMs: z.number().min(0).max(2000).default(20).describe("Crossfade duration in ms."),
+        intervalBars: z.number().min(0.25).max(64).describe("Bars before switching."),
+        fadeMs: z.number().min(0).max(2000).optional().describe("Crossfade duration in ms. Omit all transition options to inherit the native Bar Sync/Song Mode settings."),
         resetPhase: z
             .boolean()
-            .default(true)
-            .describe("Reset pattern phase on switch."),
+            .optional()
+            .describe("Reset pattern phase on switch. Omit to inherit native settings."),
         morphBars: z
             .number()
             .min(0.25)
             .max(8)
             .optional()
-            .describe("Pre-anchor morph window in bars for this flip (PAM >= 1.19.3). Omit = hard switch."),
+            .describe("Pre-anchor morph window in bars for this flip. Omit all transition options to inherit native settings."),
         morphMode: z
             .enum(["auto", "param", "mix", "seq", "all"])
             .optional()
-            .describe("Morph style: 'param' glides continuous params (default); 'mix' equal-power blends the two sections; 'seq' adds a staged pattern dissolve to the glide (old notes lose trigger probability as new notes gain it); 'all' runs glide + dissolve + blend together; 'auto' lets the engine pick — mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; seq/all on older builds run param)."),
+            .describe("Morph style: 'param' glides continuous params (default); 'mix' equal-power blends the two sections; 'seq' adds a staged pattern dissolve to the glide (old notes lose trigger probability as new notes gain it); 'all' runs glide + dissolve + blend together; 'auto' lets the engine pick — mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise."),
         morphCurve: z
             .enum(["linear", "ease", "exp", "log"])
             .optional()
@@ -6532,7 +7697,7 @@ server.registerTool("queue_variation", {
             tailMaxBars: z.number().min(0.25).max(8).optional(),
         })
             .optional()
-            .describe("Advanced transition settings for this flip (PAM >= 1.20.0): pattern policy for a " +
+            .describe("Advanced transition settings for this flip: pattern policy for a " +
             "seq/all morph, blend gain law for a mix/all morph, and the outgoing section's " +
             "tail. Omitted fields keep the defaults (dissolve, equalPower, fade)."),
     },
@@ -6543,8 +7708,8 @@ server.registerTool("queue_variation", {
     await bridge.send("queueVariationOnBars", {
         index,
         intervalBars,
-        fadeMs,
-        resetPhase,
+        ...(fadeMs !== undefined && { fadeMs }),
+        ...(resetPhase !== undefined && { resetPhase }),
         ...(morphBars !== undefined && { morphBars }),
         ...(morphMode !== undefined && { morphMode }),
         ...(morphCurve !== undefined && { morphCurve }),
@@ -6585,7 +7750,7 @@ server.registerTool("update_variations", {
 server.registerTool("variation_hold", {
     title: "Variation Hold",
     description: "'Hold while note pressed' mode for variations. Use this to map MIDI notes to momentary " +
-        "variation switches that revert when the note releases.",
+        "variation switches. Hold mode reverts when the note releases; latch mode stays.",
     inputSchema: {
         enabled: z.boolean().optional().describe("Toggle hold mode on/off."),
         allNotesOff: z
@@ -6606,14 +7771,25 @@ server.registerTool("variation_hold", {
     if (check !== true)
         return check;
     const updates = [];
+    // The native router holds the live values; settings persist them the way the UI's
+    // setVariationHoldEnabled / syncVariationHoldBindings do.
+    const persisted = {};
     if (typeof enabled === "boolean") {
         await bridge.send("setVariationHoldEnabled", enabled);
+        persisted.variationHoldEnabled = enabled;
         updates.push(`enabled=${enabled}`);
     }
     if (bindings) {
-        await bridge.send("syncVariationHoldBindings", bindings);
+        const slots = Array.from({ length: PRESET_VARIATION_SLOTS }, (_, slot) => bindings[slot] ?? { triggerNote: -1, triggerChannel: 0 });
+        await bridge.send("syncVariationHoldBindings", slots);
+        persisted.variationHoldBindings = slots.map(({ triggerNote, triggerChannel }) => ({
+            triggerNote: triggerNote >= 0 ? triggerNote : null,
+            triggerChannel,
+        }));
         updates.push(`bindings=${bindings.length}`);
     }
+    if (Object.keys(persisted).length)
+        await bridge.send("applySettingsUpdate", persisted);
     if (allNotesOff) {
         await bridge.send("variationHoldAllNotesOff");
         updates.push("allNotesOff");
@@ -6700,6 +7876,21 @@ server.registerTool("midi_recording", {
     }
     return text("No-op");
 });
+server.registerTool("session_take", {
+    title: "Session Take",
+    description: "Record a session take: the master WAV plus a log of PAM's main window, rendered later to video by pam-render. " +
+        "PAM only; needs Settings > Experimental > Session Recorder. 'start' needs the window open. 'stop' saves in the " +
+        "background: poll 'status' until phase is 'idle' (saved to folder) or 'failed' (error). Returns the recorder status.",
+    inputSchema: {
+        op: z.enum(["start", "stop", "status"]).describe("Operation."),
+    },
+}, async ({ op }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const status = await bridge.send("sessionTake", op);
+    return text(typeof status === "string" ? status : JSON.stringify(status));
+});
 // ============================================================
 // TOOLS — Modulation updates (LFO/Env/Vary/Macro/ParamSeq)
 // ============================================================
@@ -6707,7 +7898,6 @@ server.registerTool("update_modulation", {
     title: "Update Modulation",
     description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, ParamSeq sequence data, " +
         "or the Free Sequencer master pattern. " +
-        "The payload is type-specific; see modulation update flows in interop.ts (applyLfoUpdate / updateEnvelope / etc.). " +
         "Use add_modulation to first attach a source to a target — then this tool to edit it.",
     inputSchema: {
         type: z
@@ -6715,7 +7905,11 @@ server.registerTool("update_modulation", {
             .describe("Which modulation system to update."),
         payload: z
             .record(z.string(), z.unknown())
-            .describe("Update payload object. Shape depends on type: lfo expects { index, rate?, depth?, shape?, customCurve?, target? }, envelope expects matrix entry edits, paramSeqSequence expects { id, steps[] }, freeSeqSequence expects { sequence: number[] } (the master step contour every free-mode ParamSeq follows), etc."),
+            .describe("Update payload object, one property per call. lfo, envelope, vary, macro and paramSeq all take " +
+            "{ index, property, value }, where index is the 0-based position in that state array (get_state " +
+            "section 'lfos' / 'envelopes' / 'vary' / 'macros' / 'paramSeqs') and property is the field name to " +
+            "overwrite. paramSeqSequence takes { index, sequence: number[] }. freeSeqSequence takes " +
+            "{ sequence: number[] } — the master step contour every free-mode ParamSeq follows."),
     },
 }, async ({ type, payload }) => {
     const check = await requireBridge();
@@ -6741,13 +7935,6 @@ server.registerTool("update_modulation", {
 // ============================================================
 // TOOLS — Song mode
 // ============================================================
-// Advanced transition spec (ADR-001, PAM >= 1.19.6; engine families live from
-// PAM >= 1.20.0). Honest contract: it persists, round-trips, and reads back
-// RESOLVED. Pattern policy (dissolve/wipe/cells), mix law (equal power / equal
-// gain / correlation), tail (cut/fade/ring) and phase run on song VARIATION
-// sections and queued bar-sync flips; preset destinations coerce to a param
-// glide, and offline bounces coerce ring→fade and blend→hard switch (each
-// reported, never silent). Wire enums are append-only.
 const morphCurveEnum = z.enum(["linear", "ease", "exp", "log"]);
 const transitionSpecSchema = z.object({
     mode: z.enum(["auto", "param", "mix", "seq", "all"]).optional(),
@@ -6757,6 +7944,10 @@ const transitionSpecSchema = z.object({
         paramCurve: morphCurveEnum.optional(),
         patternCurve: morphCurveEnum.optional(),
         mixCurve: morphCurveEnum.optional(),
+        staggerBy: z.enum(["off", "cell", "category"]).optional(),
+        staggerSpread: z.number().min(0).max(0.9).optional(),
+        staggerOrder: z.enum(["forward", "reverse"]).optional(),
+        relations: z.enum(["off", "stepped"]).optional(),
     })
         .optional(),
     pattern: z.object({ policy: z.enum(["dissolve", "wipe", "cells"]).optional() }).optional(),
@@ -6769,23 +7960,25 @@ const transitionSpecSchema = z.object({
         .optional(),
     phase: z.enum(["inherit", "reset", "continue"]).optional(),
 });
-const TRANSITION_SPEC_HONESTY = "Advanced transition spec (PAM >= 1.19.6; live engine from PAM >= 1.20.0): pattern.policy " +
+const TRANSITION_SPEC_HONESTY = "Advanced transition spec: pattern.policy " +
     "('dissolve' prob-morphs events, 'wipe' replaces them at a moving frontier, 'cells' hands " +
     "whole cells over in ascending order), audio.mixLaw ('equalPower' default, 'equalGain' for " +
     "correlated sections, 'correlation' auto-adapts), audio.tail ('fade' default, 'cut', 'ring' " +
     "lets voices/FX decay up to tailMaxBars), phase ('reset'/'continue' overrides the song's " +
     "Reset Phase per cable), window.patternCurve/mixCurve (per-domain easing; patternCurve " +
-    "defaults linear). Runs on variation sections + queued flips, and on preset destinations " +
-    "when the lanePresetSections setting is on (PAM >= 1.20.1 — the dual-lane preset section " +
+    "defaults linear). window.staggerBy (off/cell/category), staggerSpread (0..0.9), staggerOrder (forward/reverse), and relations (off/stepped) shape the parameter glide. Runs on variation sections + queued flips, and on preset destinations " +
+    "when the lanePresetSections setting is on (the dual-lane preset section " +
     "pipeline; with it off, preset destinations coerce to a param glide). Offline bounces " +
     "coerce ring→fade, blend→hard switch. 'get' reads back each cable's resolvedTransition " +
     "(effective values after inheritance and capability coercion) and lastMorphResolution " +
-    "(the engine's latest AUTO decision + reason).";
+    "(the engine's latest AUTO decision + reason; published only for an AUTO request, and " +
+    "one per song rather than one per cable).";
 server.registerTool("song_mode", {
     title: "Song Mode",
     description: "Control PAM's song mode (timeline of variation/preset sections). Ops: 'setArrangement', " +
         "'get', 'assignVx', 'setSequence', 'clear', 'toggle', 'setLoopPoints', 'toggleLoop', " +
-        "'setCrossfadeMs', 'setPlayhead'.\n\n" +
+        "'setCrossfadeMs', 'setPlayhead'. WebView-routed (window must be OPEN): setArrangement, get, assignVx. " +
+        "Headless: setSequence, clear, toggle, setLoopPoints, toggleLoop, setCrossfadeMs, setPlayhead.\n\n" +
         "PREFER 'setArrangement' (PAM ≥ 1.5.7, window open): it authors real Song Mode grid nodes " +
         "from a `sections` list, with an optional weighted `connections` graph. The result is " +
         "visible/editable in the UI, and each section can pin a " +
@@ -6793,8 +7986,11 @@ server.registerTool("song_mode", {
         "audio slot 1:1; see the vx_variation tool), optionally inside a specific VX scene via " +
         "`vxScenePath` (the .vxpreset loads before the section plays, so sections can pull visuals " +
         "from different scenes). A section can also carry `morphBars`/`morphCurve`/`morphMode` to glide the " +
-        "incoming variation's continuous params over the bars before its boundary (PAM >= 1.19.3), and an " +
-        "advanced `transition` spec (PAM >= 1.19.6 — authored metadata; see the field description). " +
+        "incoming variation's continuous params over the bars before its boundary, and an " +
+        "advanced `transition` spec (see the field description). " +
+        "A `transitionPreset` id (or `defaultTransitionPreset` at the top level) stamps a whole named " +
+        "transition in one field; op 'get' lists the available ids in `transitionPresets` and reports " +
+        "each cable's derived `transitionPreset`. " +
         "'get' reads the arrangement back (nodes, compiled steps with the " +
         "VX scene+slot each recalls, total bars, and each cable's `resolvedTransition` — the effective " +
         "transition after inheritance and capability coercion, e.g. preset destinations report param); " +
@@ -6820,18 +8016,18 @@ server.registerTool("song_mode", {
         sections: z
             .array(z.object({
             variationIndex: z.number().min(0).max(7).describe("Audio variation slot 0-7 this section plays. With presetPath set, this selects the variation INSIDE that preset's own bank — the two compose, they are not mutually exclusive."),
-            bars: z.number().positive().optional().describe("Section length in bars (default: auto from longest pattern)."),
+            bars: z.number().int().min(1).optional().describe("Section length in whole bars (default: auto from longest pattern)."),
             repeat: z.number().int().min(1).optional().describe("Times to play before advancing (default 1)."),
             muted: z.boolean().optional().describe("Pass through without an audio trigger."),
             probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
-            presetPath: z.string().optional().describe("Cross-preset section: at this section's boundary the song switches to THIS preset file, playing its variations[variationIndex] slot. With lanePresetSections on (PAM >= 1.20.1) it transitions exactly like a variation section (prepared off the audible path, full morph family); otherwise the legacy in-place load applies."),
+            presetPath: z.string().optional().describe("Cross-preset section: at this section's boundary the song switches to THIS preset file, playing its variations[variationIndex] slot. With lanePresetSections on it transitions exactly like a variation section (prepared off the audible path, full morph family); otherwise the legacy in-place load applies."),
             label: z.string().optional().describe("Section label shown on the grid node (e.g. 'Intro', 'Hook')."),
             morphBars: z
                 .number()
                 .min(0)
                 .max(8)
                 .optional()
-                .describe("Pre-anchor morph window in bars for the transition INTO this section — continuous params glide to the new values, landing at the boundary (PAM >= 1.19.3). 0 = explicit hard switch (never morph, ignores the song's default); omit to inherit the default. Values in (0, 0.25) clamp up to 0.25."),
+                .describe("Pre-anchor morph window in bars for the transition INTO this section — continuous params glide to the new values, landing at the boundary. 0 = explicit hard switch (never morph, ignores the song's default); omit to inherit the default. Values in (0, 0.25) clamp up to 0.25."),
             morphCurve: z
                 .enum(["linear", "ease", "exp", "log"])
                 .optional()
@@ -6839,8 +8035,12 @@ server.registerTool("song_mode", {
             morphMode: z
                 .enum(["auto", "param", "mix", "seq", "all"])
                 .optional()
-                .describe("Morph realization; default auto — the engine picks mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; older builds run param). 'param' glides continuous params; 'mix' DJ-blends stems; 'seq' adds a staged pattern dissolve to the glide; 'all' runs glide + dissolve + blend (seq/all on older builds run param). Ignored without morphBars."),
+                .describe("Morph realization; default auto — the engine picks mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise. 'param' glides continuous params; 'mix' DJ-blends stems; 'seq' adds a staged pattern dissolve to the glide; 'all' runs glide + dissolve + blend. Ignored without morphBars."),
             transition: transitionSpecSchema.optional().describe(TRANSITION_SPEC_HONESTY),
+            transitionPreset: z
+                .string()
+                .optional()
+                .describe("Named transition preset id — read the list from op 'get' (`transitionPresets`: the factory set plus the user's saved ones). Stamps every transition field onto the incoming cable; morphBars/morphCurve/morphMode/transition on the same object override the stamp field by field. Unknown ids fail with the known list."),
             vxVariationIndex: z
                 .number()
                 .int()
@@ -6883,6 +8083,10 @@ server.registerTool("song_mode", {
                 .optional()
                 .describe("Per-cable morph realization; overrides the destination section's morphMode. Same modes as the section field, incl. 'seq' (pattern dissolve) and 'all' (glide + dissolve + blend)."),
             transition: transitionSpecSchema.optional().describe("Per-cable " + TRANSITION_SPEC_HONESTY),
+            transitionPreset: z
+                .string()
+                .optional()
+                .describe("Named transition preset id — read the list from op 'get' (`transitionPresets`: the factory set plus the user's saved ones). Stamps every transition field onto the incoming cable; morphBars/morphCurve/morphMode/transition on the same object override the stamp field by field. Unknown ids fail with the known list."),
         }))
             .optional()
             .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section. Each cable may carry its own morphBars/morphCurve/morphMode/transition."),
@@ -6890,6 +8094,11 @@ server.registerTool("song_mode", {
             .nullable()
             .optional()
             .describe("For 'setArrangement': song-level advanced transition defaults inherited by cables without their own `transition`; null clears. " + TRANSITION_SPEC_HONESTY),
+        defaultTransitionPreset: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("For 'setArrangement': stamp a named preset as the song-level default transition (see transitionPreset)."),
         loop: z.boolean().optional().describe("For 'setArrangement': loop the whole arrangement."),
         nodeId: z.string().optional().describe("For 'assignVx': grid node id (from op 'get')."),
         stepIndex: z.number().int().min(0).optional().describe("For 'assignVx': compiled step index (alternative to nodeId)."),
@@ -6948,29 +8157,37 @@ server.registerTool("song_mode", {
         case "setArrangement": {
             if (!args.sections || args.sections.length === 0)
                 return error("'setArrangement' requires sections");
+            const requestId = mintVideoRequestId();
             await sendVideoCommand({
                 op: "setSongArrangement",
+                requestId,
                 sections: args.sections,
                 ...(args.connections !== undefined && { connections: args.connections }),
                 ...(args.defaultTransition !== undefined && { defaultTransition: args.defaultTransition }),
+                ...(args.defaultTransitionPreset !== undefined && { defaultTransitionPreset: args.defaultTransitionPreset }),
                 ...(args.loop !== undefined && { loop: args.loop }),
                 ...(args.enabled !== undefined && { enabled: args.enabled }),
                 ...(args.crossfadeMs !== undefined && { crossfadeMs: args.crossfadeMs }),
             });
-            // The forward path is fire-and-forget — poll until the WebView's apply
-            // republishes the snapshot (same pattern as resolveNewId).
             const deadline = Date.now() + 3000;
             let sm;
+            let acknowledged = false;
             for (;;) {
                 const state = await getVideoStateRaw();
-                sm = state.songMode;
-                const landed = sm?.available === true &&
-                    Array.isArray(sm.nodes) &&
-                    sm.nodes.length === args.sections.length;
-                if (landed || Date.now() > deadline)
+                const ack = state.lastCommandAck;
+                if (ack?.requestId === requestId) {
+                    if (ack.ok !== true)
+                        return error(ack.error ?? "Song arrangement was rejected.");
+                    sm = state.songMode;
+                    acknowledged = true;
+                    break;
+                }
+                if (Date.now() > deadline)
                     break;
                 await sleep(150);
             }
+            if (!acknowledged)
+                return error("Song arrangement was sent but its completion was not acknowledged. Open PAM's window and use a current plugin build; inspect song_mode op:'get' before retrying.");
             if (!sm || sm.available !== true)
                 return error("Arrangement command sent, but no song-mode read-model came back — this needs PAM ≥ 1.5.7 " +
                     "with the window OPEN. On older builds fall back to op 'setSequence' (headless raw steps).");
@@ -7055,11 +8272,13 @@ server.registerTool("export_song", {
         "• 'live' with cellId — legacy headless master-mix capture into an empty cell (works with the window " +
         "closed on PAM ≥ 1.5.0). The captured WAV also lands in PAM's Resamples folder.\n" +
         "• 'offline' — the DETERMINISTIC multi-section bounce (PAM ≥ 1.5.7 with offline song export): every " +
-        "variation section applies sample-accurately on its anchor; renders faster than realtime with no bar cap. " +
+        "variation section applies sample-accurately on its anchor and renders faster than realtime; `bars` is still required and capped at 64. " +
         "Audio-only works headless (window closed); includeVideo runs the offline video pump with per-section VX " +
         "recalls (window open, WebCodecs). Caveats: preset-path steps hold the previous section's sound (pending), " +
         "and wall-clock sources (Magenta, Notochord, camera layers) cannot render offline — use 'live' for those.\n\n" +
         "Live paths render in REAL TIME (a 90 s song takes ~90 s) and cap at 64 bars per capture. " +
+        "This is the entry point for arrangement bounces: strategy 'offline' issues the same render as " +
+        "`export_audio` with mode 'song-mode', and the live and audio+video strategies exist only here. " +
         "Verify audio results with get_audio_info (resolve cell captures against the Resamples location " +
         "from get_default_locations).",
     inputSchema: {
@@ -7068,7 +8287,7 @@ server.registerTool("export_song", {
             .number()
             .min(1)
             .max(64)
-            .describe("Total arrangement length in bars (the full timeline). Required for 'live'."),
+            .describe("Total arrangement length in bars (the full timeline), 1-64. Required for every strategy."),
         cellId: z
             .number()
             .min(1)
@@ -7082,7 +8301,10 @@ server.registerTool("export_song", {
         name: z.string().optional().describe("Output name for WebView Song Export renders (default 'Song')."),
         normalize: z.boolean().optional().describe("Normalize the captured audio (WebView Song Export paths)."),
         encoderId: z.string().optional().describe("Recording encoder preset for includeVideo (e.g. mp4-h264)."),
-        bitDepth: z.number().default(24).describe("Bit depth (16 or 24; legacy cell-capture + offline paths)."),
+        bitDepth: z
+            .union([z.literal(16), z.literal(24)])
+            .default(24)
+            .describe("Bit depth: 16 or 24 (legacy cell-capture + offline paths)."),
         tailBars: z
             .number()
             .min(0)
@@ -7235,9 +8457,10 @@ server.registerTool("set_metronome", {
 // ============================================================
 server.registerTool("analyze_sample_tempo", {
     title: "Analyze Sample Tempo",
-    description: "Run BPM detection and transient/slice analysis on an audio file. " +
-        "Result is dispatched asynchronously into PAM's state — fetch it via get_state after a short delay (~100-500ms). " +
-        "Use this before resample_sample_to_bpm if you don't already know the source BPM.",
+    description: "Run BPM detection and transient/slice analysis on an audio file. The result lands in the plugin's " +
+        "sample-metadata cache and the editor's sample library; the bridge does not capture it, so there is no " +
+        "get_state key that reads it back. Run it before resample_sample_to_bpm so the stretch has a source BPM, " +
+        "and use get_audio_info for a file's own format properties.",
     inputSchema: {
         filePath: z.string().describe("Path to the audio file."),
         transientSensitivity: z
@@ -7296,8 +8519,8 @@ server.registerTool("preview_slice", {
     title: "Preview Slice",
     description: "Audition a single slice of a cell's sample.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
-        sliceNumber: z.number().min(0).describe("Slice index."),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        sliceNumber: z.number().int().min(1).describe("Slice number, 1-based as in the UI (1 = first slice)."),
     },
 }, async ({ cellId, sliceNumber }) => {
     const check = await requireBridgeForCells(cellId);
@@ -7311,7 +8534,7 @@ server.registerTool("resample_sample_to_bpm", {
     description: "Time-stretch a cell's sample to the current project BPM (or a target BPM). " +
         "Non-destructive — use restore_original_sample to revert.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
         sourceBpm: z
             .number()
             .min(20)
@@ -7325,23 +8548,29 @@ server.registerTool("resample_sample_to_bpm", {
             .optional()
             .describe("Target BPM (defaults to current project BPM)."),
     },
-}, async (args) => {
+}, async ({ cellId, sourceBpm, targetBpm }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    await bridge.send("resampleSampleToBPM", args);
-    return text(`Resampled cell ${args.cellId} to BPM.`);
+    const loaded = await requireCellSample(cellId);
+    if (loaded !== true)
+        return loaded;
+    await bridge.send("resampleSampleToBPM", { cellId, sourceBPM: sourceBpm, targetBPM: targetBpm });
+    return text(`Resampled cell ${cellId} to ${targetBpm ?? "the project"} BPM.`);
 });
 server.registerTool("restore_original_sample", {
     title: "Restore Original Sample",
     description: "Revert a cell's sample to its un-edited source (undoes resample / trim / etc.).",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
     },
 }, async ({ cellId }) => {
     const check = await requireBridgeForCells(cellId);
     if (check !== true)
         return check;
+    const loaded = await requireCellSample(cellId, "originalFilePath");
+    if (loaded !== true)
+        return loaded;
     await bridge.send("restoreOriginalSample", { cellId });
     return text(`Restored original sample for cell ${cellId}.`);
 });
@@ -7363,8 +8592,8 @@ server.registerTool("export_slice", {
     title: "Export Slice",
     description: "Export a single slice of a cell's sample as a standalone WAV.",
     inputSchema: {
-        cellId: z.number().min(1).max(8),
-        sliceIndex: z.number().min(0),
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        sliceIndex: z.number().int().min(1).describe("Slice number, 1-based as in the UI (1 = first slice)."),
     },
 }, async ({ cellId, sliceIndex }) => {
     const check = await requireBridgeForCells(cellId);
@@ -7381,7 +8610,8 @@ server.registerTool("live_resample", {
     description: "Capture PAM's audio graph output into a cell as a new sample, in real time. Ops: 'start' / 'stop'. " +
         "Transport MUST be playing for the capture to produce audio. Because the capture runs live, " +
         "Song Mode section changes, modulation, and variation switches are all captured faithfully — " +
-        "this is the building block for full-track / Song Mode bounces (see export_song).\n\n" +
+        "this is the building block for full-track / Song Mode bounces (see export_song). On finalize the captured clip " +
+        "REPLACES whatever sample the destination cell held — use an empty cell, or reload the preset before saving anything afterwards.\n\n" +
         "`source` selects what to record: 'cell' (the destination cell's own output), 'input' (PAM's audio input), " +
         "or 'fullmix' (the whole master mix — use this to bounce the entire arrangement).",
     inputSchema: {
@@ -7394,10 +8624,11 @@ server.registerTool("live_resample", {
             .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)
+            .int()
+            .min(1)
             .max(64)
             .optional()
-            .describe("For 'start': capture length in bars (max 64; the capture also stops on the 'stop' op)."),
+            .describe("For 'start': whole bars to capture (max 64; the capture also stops on the 'stop' op)."),
         source: z
             .enum(["cell", "input", "fullmix"])
             .default("cell")
@@ -7660,15 +8891,20 @@ server.registerTool("list_loaded_plugins", {
     title: "List Loaded Plugins",
     description: "List plugins currently hosted in PAM cells (instrument slot only — FX-side hosting is not exposed). " +
         "Each entry: cellId, name, manufacturer, format, " +
-        "path, isInstrument, bypassed, and the plugin's full param list (index, name, label, value, defaultValue). " +
-        "Use the param `index` with `set_plugin_param`.",
+        "path, isInstrument, bypassed, and the plugin's param list (index, name, label, value, defaultValue, discrete, numSteps, and valueStrings for a discrete param; " +
+        "JUCE's MIDI CC proxy parameters are omitted). Use the param `index` with `set_plugin_param`, and its `modTarget` as the paramId for add_modulation / add_param_seq.",
     inputSchema: {},
 }, async () => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const raw = await bridge.send("listLoadedPlugins");
-    return text(bridgeResultText(raw));
+    const listed = typeof raw === "string" ? JSON.parse(raw) : raw;
+    for (const plugin of listed?.loadedPlugins ?? []) {
+        for (const p of plugin.params ?? [])
+            p.modTarget = hostedModTargetId(Number(plugin.cellId), p);
+    }
+    return text(bridgeResultText(listed));
 });
 server.registerTool("load_plugin", {
     title: "Load Plugin Into Cell",
@@ -7702,7 +8938,8 @@ server.registerTool("load_plugin", {
         ...(args.uniqueId ? { uniqueId: args.uniqueId } : {}),
         ...(args.name ? { name: args.name } : {}),
     }));
-    return text(raw);
+    // Native answers a success with an object (`{ok: true, …}`), a failure with a string.
+    return text(typeof raw === "string" ? raw : JSON.stringify(raw));
 });
 server.registerTool("unload_plugin", {
     title: "Unload Plugin From Cell",
@@ -7725,10 +8962,10 @@ server.registerTool("set_plugin_param", {
     description: "Set a parameter on a hosted plugin by cell + parameter index. Value is normalized 0..1. " +
         "Use `list_loaded_plugins` to find param indices and names. " +
         "This is the dedicated path for hosted plugin params — `set_parameters` won't reach them. " +
-        "Targets the cell's instrument-slot plugin only.",
+        "It exists for a single instrument-slot value; use `set_plugin_params` for a batch or for the FX slot.",
     inputSchema: {
-        cellId: z.number().int().min(1),
-        paramIndex: z.number().int().min(0),
+        cellId: z.number().int().min(1).describe("Cell hosting the plugin."),
+        paramIndex: z.number().int().min(0).describe("Parameter index from list_loaded_plugins."),
         value: z.number().min(0).max(1).describe("Normalized 0..1."),
     },
 }, async (args) => {
@@ -7750,8 +8987,8 @@ server.registerTool("set_plugin_bypass", {
     description: "Toggle bypass on the hosted plugin in a cell (instrument slot). Bypassed plugins are silenced; the cell sampler " +
         "still plays in parallel.",
     inputSchema: {
-        cellId: z.number().int().min(1),
-        bypassed: z.boolean(),
+        cellId: z.number().int().min(1).describe("Cell hosting the plugin."),
+        bypassed: z.boolean().describe("true silences the hosted plugin, false re-enables it."),
     },
 }, async (args) => {
     const check = await requireBridge();
@@ -7840,7 +9077,7 @@ server.registerTool("configure_transport", {
 server.registerTool("get_audio_device_setup", {
     title: "Get Audio Device Setup",
     description: "Get the standalone audio/MIDI device setup (sample rate, buffer size, available and active input/output devices). " +
-        "Returns null when running plugin-hosted (the DAW owns the device config). Use the device IDs/names from here with set_midi_io.",
+        "Returns {pluginHosted:true} inside a DAW, which owns the device config. Use the device IDs/names from here with set_midi_io.",
     inputSchema: {},
     annotations: { readOnlyHint: true },
 }, async () => {
@@ -7848,6 +9085,9 @@ server.registerTool("get_audio_device_setup", {
     if (check !== true)
         return check;
     const setup = await bridge.send("getAudioDeviceSetup");
+    if (setup === null || (isRecord(setup) && Object.keys(setup).length === 0)) {
+        return json({ pluginHosted: true, note: "The DAW owns the audio and MIDI device setup." });
+    }
     return json(setup);
 });
 server.registerTool("get_memory_report", {
@@ -7881,35 +9121,76 @@ server.registerTool("set_audio_device", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    await bridge.send("setAudioDevice", [deviceName]);
+    await bridge.send("setAudioDevice", deviceName);
     return text(`Audio output device set to '${deviceName}'.`);
 });
 server.registerTool("set_midi_io", {
     title: "Set MIDI I/O Devices",
-    description: "Select MIDI input/output devices (standalone). Use get_audio_device_setup to discover device IDs first. " +
-        "All fields optional.",
+    description: "Select MIDI input/output devices (standalone). get_audio_device_setup lists them under midiInputs / " +
+        "midiOutputs (and each port's device under midiOutputPorts); pass each device's identifier or exact name. " +
+        "Ports B-D are extra outputs a cell can pick with update_cell_config midiOutPort. All fields optional.",
     inputSchema: {
-        inputDeviceIds: z.array(z.string()).optional().describe("Enabled MIDI input device IDs (replaces the active set)."),
-        outputDeviceId: z.string().optional().describe("MIDI output device ID."),
+        inputDeviceIds: z
+            .array(z.string())
+            .optional()
+            .describe("MIDI inputs to enable, by identifier or name. Replaces the active set; [] disables all inputs."),
+        outputDeviceId: z.string().optional().describe("MIDI output device, by identifier or name; \"\" selects none."),
         outputEnabled: z.boolean().optional().describe("Enable/disable MIDI output."),
+        outputPortDeviceIds: z
+            .array(z.string())
+            .max(3)
+            .optional()
+            .describe("Devices for Ports B, C and D in order, by identifier or name; \"\" leaves a port with no device."),
     },
 }, async (args) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     const applied = [];
+    // Native enables only exact identifiers and disables every other input, so an
+    // unresolved name must fail here rather than silently switch MIDI off.
+    const devices = args.inputDeviceIds?.length || args.outputDeviceId || args.outputPortDeviceIds?.some(Boolean)
+        ? await bridge.send("getMidiDevices").catch(() => undefined)
+        : undefined;
+    const resolveDevices = (kind, requested) => {
+        // Builds without getMidiDevices take identifiers as given.
+        if (!isRecord(devices) || !Array.isArray(devices[kind]))
+            return { ids: requested };
+        const listed = devices[kind].filter((device) => isRecord(device) && typeof device.name === "string" && typeof device.identifier === "string");
+        const ids = [];
+        for (const wanted of requested) {
+            const match = listed.find((device) => device.identifier === wanted || device.name === wanted);
+            if (!match)
+                return { error: `Unknown MIDI device '${wanted}'. Available: ${listed.map((device) => device.name).join(", ") || "none"}.` };
+            ids.push(match.identifier);
+        }
+        return { ids };
+    };
+    const inputs = args.inputDeviceIds?.length ? resolveDevices("midiInputs", args.inputDeviceIds) : { ids: [] };
+    if ("error" in inputs)
+        return error(inputs.error);
+    const output = args.outputDeviceId ? resolveDevices("midiOutputs", [args.outputDeviceId]) : { ids: [""] };
+    if ("error" in output)
+        return error(output.error);
     if (args.inputDeviceIds !== undefined) {
-        await bridge.send("setMidiInputDevices", args.inputDeviceIds);
-        applied.push(`inputs=${args.inputDeviceIds.length}`);
+        await bridge.send("setMidiInputDevices", inputs.ids);
+        applied.push(`inputs=${inputs.ids.length}`);
     }
     if (args.outputDeviceId !== undefined) {
-        await bridge.send("setMidiOutputDevice", args.outputDeviceId);
-        applied.push(`output=${args.outputDeviceId}`);
+        await bridge.send("setMidiOutputDevice", output.ids[0]);
+        applied.push(`output=${args.outputDeviceId || "none"}`);
     }
     if (args.outputEnabled !== undefined) {
         await bridge.send("setMidiOutputEnabled", args.outputEnabled);
         applied.push(`outputEnabled=${args.outputEnabled}`);
     }
+    for (const [index, wanted] of (args.outputPortDeviceIds ?? []).entries()) {
+        const resolved = wanted ? resolveDevices("midiOutputs", [wanted]) : { ids: [""] };
+        if ("error" in resolved)
+            return error(resolved.error);
+        await bridge.send("setMidiOutputPortDevice", index + 1, resolved.ids[0]);
+        applied.push(`port${"BCD"[index]}=${wanted || "none"}`);
+    }
     if (applied.length === 0)
         return error("No MIDI I/O fields provided.");
     return text(`MIDI I/O set: ${applied.join(", ")}.`);
@@ -7950,7 +9231,11 @@ server.registerTool("delete_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = await bridge.send("removePreset", presetPath);
+    if (isFactoryPresetPath(presetPath))
+        return error("Factory presets are protected and cannot be deleted.");
+    const result = await bridge.send("removePreset", nativePresetPath(presetPath));
+    if (result !== true)
+        return error(`Preset not found or not deletable: ${presetPath}`);
     return json(result);
 });
 server.registerTool("set_preset_factory_status", {
@@ -7964,7 +9249,7 @@ server.registerTool("set_preset_factory_status", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const result = await bridge.send("togglePresetFactoryStatus", presetPath, makeFactory);
+    const result = await bridge.send("togglePresetFactoryStatus", nativePresetPath(presetPath), makeFactory);
     return json(result);
 });
 server.registerTool("get_sample_usage", {
@@ -7972,7 +9257,9 @@ server.registerTool("get_sample_usage", {
     description: "Cross-reference samples and presets. mode 'presetUsesSamples' lists the samples a preset references; " +
         "mode 'presetsUsingSample' lists presets that reference a given sample (or any sample under a folder).",
     inputSchema: {
-        mode: z.enum(["presetUsesSamples", "presetsUsingSample"]),
+        mode: z
+            .enum(["presetUsesSamples", "presetsUsingSample"])
+            .describe("Which direction to cross-reference: from a preset to its samples, or from a sample to the presets using it."),
         path: z
             .string()
             .describe("Relative preset path (presetUsesSamples) or relative sample path (presetsUsingSample)."),
@@ -7987,32 +9274,36 @@ server.registerTool("get_sample_usage", {
     if (check !== true)
         return check;
     const result = mode === "presetUsesSamples"
-        ? await bridge.send("getPresetSampleUsage", relPath)
+        ? await bridge.send("getPresetSampleUsage", nativePresetPath(relPath))
         : await bridge.send("getPresetsUsingSample", relPath, isFolder ?? false);
     return json(result);
 });
 server.registerTool("repair_preset_samples", {
     title: "Repair Preset Sample Paths",
     description: "Fix broken sample references in presets. mode 'fix' auto-relinks moved/renamed samples by searching the " +
-        "library (optionally scoped to one preset). mode 'rescan' re-audits a preset for still-missing samples and " +
+        "library (optionally scoped to one preset). mode 'rescan' re-audits the ACTIVE preset for still-missing samples and " +
         "reports them. Useful after moving a sample library or importing presets from another machine.",
     inputSchema: {
-        mode: z.enum(["fix", "rescan"]),
+        mode: z
+            .enum(["fix", "rescan"])
+            .describe("'fix' relinks moved samples by searching the library; 'rescan' only reports what is still missing."),
         presetPath: z
             .string()
             .optional()
-            .describe("Relative preset path. Omit for 'fix' to scan all presets; omit for 'rescan' to audit the active preset."),
+            .describe("'fix' only: relative preset path. Omit to scan all presets. 'rescan' always audits the active preset."),
     },
 }, async ({ mode, presetPath }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
     if (mode === "fix") {
-        const result = await bridge.send("fixPresetSamplePaths", presetPath ?? "");
+        const result = await bridge.send("fixPresetSamplePaths", presetPath ? nativePresetPath(presetPath) : "");
         return json(result);
     }
-    await bridge.send("rescanMissingSamples", presetPath ?? "");
-    return text(`Re-audited ${presetPath || "active preset"} for missing samples (results dispatched to UI state).`);
+    const missing = await bridge.send("rescanMissingSamples", "");
+    if (!Array.isArray(missing))
+        return text("Re-audited the active preset; this build reports the result only in its UI.");
+    return json({ missing, note: missing.length ? undefined : "The active preset has no missing samples." });
 });
 server.registerTool("preview_sample", {
     title: "Preview Sample",
@@ -8041,7 +9332,9 @@ server.registerTool("preview_sample", {
 server.registerTool("set_plugin_params", {
     title: "Set Hosted Plugin Params (batch)",
     description: "Set multiple hosted-plugin parameters in one call (more efficient than set_plugin_param per value). Values are " +
-        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'.",
+        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'. " +
+        "role:'effect' reaches the FX slot, but list_loaded_plugins reports instrument-slot plugins only, so " +
+        "effect-slot param indices are not discoverable through MCP.",
     inputSchema: {
         cellId: z.number().int().min(1).describe("Cell number."),
         role: z.enum(["instrument", "effect"]).optional().describe("Which hosted slot (default 'instrument')."),
@@ -8291,9 +9584,12 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
                         playing: Boolean(transport.playing ?? transport.isPlaying),
                         preset,
                         sel: sel ?? null,
-                        cells: (overview.cells ?? [])
-                            .filter((c) => c.sample || c.synth)
-                            .map((c) => ({ id: c.id, name: c.sample ?? `${c.synth}(synth)` })),
+                        muted: (overview.cells ?? []).filter((c) => c.muted).map((c) => c.cellId),
+                        cells: (overview.cells ?? []).flatMap((c) => {
+                            const name = c.sample?.path || c.sample?.name
+                                || (c.synthEngine && c.synthEngine.id > 0 ? `${c.synthEngine.name}(synth)` : undefined);
+                            return name ? [{ id: c.cellId, name }] : [];
+                        }),
                     };
                 }
             }
@@ -8364,16 +9660,23 @@ if (existsSync(ASSISTANT_TOOLPACK_PATH))
                     result: result.text.length > 400 ? `${result.text.slice(0, 400)}…` : result.text,
                     isError: result.isError,
                 });
+                // Same wrapping as the in-plugin executor's toResponsePayload, so a
+                // trace here shows the exact function responses the model sees there.
                 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) };
+                        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                            const obj = parsed;
+                            if (obj.ok === true)
+                                delete obj.ok;
+                            payload = result.text.length <= 400 ? obj : { result: result.text.slice(0, 400) };
+                        }
+                        else {
+                            payload = { result: parsed };
+                        }
                     }
                     catch {
                         payload = { result: result.text.slice(0, 400) };