@dpantani/tdmcp 0.5.0 → 0.6.1

package/dist/cli/agent.js

@@ -7,7 +7,7 @@ import { resolve as resolve6 } from "path";
 import { createInterface } from "readline";
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
-import { z as z155 } from "zod";
+import { z as z159 } from "zod";
 
 // src/td-client/types.ts
 var TdError = class extends Error {
@@ -45,6 +45,11 @@ function friendlyTdError(err) {
   if (err instanceof Error) return err.message;
   return String(err);
 }
+function isMissingEndpoint(err) {
+  if (!(err instanceof TdApiError)) return false;
+  if (err.status === 404) return true;
+  return /^Unsupported (GET|POST|PUT|PATCH|DELETE) /.test(err.message);
+}
 
 // src/feedback/previewCapture.ts
 async function capturePreview(client, path2, width = 640, height = 360) {
@@ -1042,12 +1047,35 @@ var NodeRefSchema = z3.object({
   /** Parameters that could not be applied at create time (unknown name or bad value). */
   parameter_warnings: z3.array(z3.string()).optional()
 });
+var NodeFlagsSchema = z3.object({
+  bypass: z3.boolean().optional(),
+  render: z3.boolean().optional(),
+  display: z3.boolean().optional(),
+  lock: z3.boolean().optional(),
+  allowCooking: z3.boolean().optional(),
+  cloneImmune: z3.boolean().optional(),
+  is_clone: z3.boolean().optional(),
+  clone: z3.string().nullable().optional()
+});
+var NodeWireSchema = z3.object({
+  in_index: z3.number().int().nullable(),
+  from: z3.string(),
+  out_index: z3.number().int()
+});
 var NodeDetailSchema = NodeRefSchema.extend({
   parameters: z3.record(z3.string(), z3.unknown()).default({}),
   inputs: z3.array(z3.string()).optional(),
   outputs: z3.array(z3.string()).optional(),
   family: z3.string().optional(),
-  errors: z3.array(z3.string()).optional()
+  errors: z3.array(z3.string()).optional(),
+  // --- NEW (node_flags_in_detail): cosmetic + behavioral signals for a faithful round-trip ---
+  flags: NodeFlagsSchema.optional(),
+  wires_in: z3.array(NodeWireSchema).optional(),
+  nodeX: z3.number().optional(),
+  nodeY: z3.number().optional(),
+  comment: z3.string().optional(),
+  color: z3.array(z3.number()).optional(),
+  tags: z3.array(z3.string()).optional()
 });
 var NodeListSchema = z3.object({ nodes: z3.array(NodeRefSchema).default([]) });
 var InfoSchema = z3.object({
@@ -1134,6 +1162,70 @@ var BatchOperationSchema = z3.discriminatedUnion("action", [
     target_input: z3.number().int().default(0)
   })
 ]);
+var ConnectResultSchema = z3.object({
+  source_path: z3.string(),
+  target_path: z3.string(),
+  requested_input: z3.number().int().optional(),
+  actual_input: z3.number().int().optional(),
+  source_output: z3.number().int().default(0),
+  connected: z3.boolean().default(true)
+});
+var DisconnectResultSchema = z3.object({
+  to_path: z3.string(),
+  from_path: z3.string().nullable().optional(),
+  to_input: z3.number().int().nullable().optional(),
+  removed: z3.array(z3.object({ input: z3.number().int(), from: z3.string() })).default([]),
+  warnings: z3.array(z3.string()).default([])
+});
+var ParamModeEntrySchema = z3.object({
+  name: z3.string(),
+  mode: z3.string(),
+  value: z3.unknown().optional(),
+  expr: z3.string().optional(),
+  bind_expr: z3.string().optional(),
+  export_op: z3.string().optional()
+});
+var ParamModesSchema = z3.object({
+  path: z3.string(),
+  type: z3.string().default(""),
+  name: z3.string().default(""),
+  parameters: z3.array(ParamModeEntrySchema).default([]),
+  warnings: z3.array(z3.string()).default([])
+});
+var SetParamModeResultSchema = z3.object({
+  path: z3.string(),
+  param: z3.string(),
+  mode: z3.string(),
+  readback_mode: z3.string().default(""),
+  readback_expr: z3.string().default("")
+});
+var DatTextSchema = z3.object({
+  path: z3.string(),
+  text: z3.string().default(""),
+  is_table: z3.boolean().default(false),
+  num_rows: z3.number().int().default(0),
+  num_cols: z3.number().int().default(0)
+});
+var DatTextWriteSchema = z3.object({
+  path: z3.string(),
+  old_length: z3.number().int().default(0),
+  new_length: z3.number().int().default(0)
+});
+var BridgeLogLineSchema = z3.object({
+  source: z3.string().default(""),
+  message: z3.string().default(""),
+  absframe: z3.number().int().optional(),
+  frame: z3.number().int().optional(),
+  severity: z3.string().default(""),
+  type: z3.string().default("")
+});
+var BridgeLogsSchema = z3.object({
+  lines: z3.array(BridgeLogLineSchema).default([]),
+  count: z3.number().int().default(0),
+  error_dat: z3.string().optional(),
+  available: z3.boolean().default(true),
+  warnings: z3.array(z3.string()).default([])
+});
 
 // src/td-client/touchDesignerClient.ts
 var sleep = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
@@ -1324,6 +1416,52 @@ var TouchDesignerClient = class {
       recursive ? { recursive: true } : void 0
     );
   }
+  // --- First-class wiring (survives TDMCP_BRIDGE_ALLOW_EXEC=0) ---
+  connectNodes(sourcePath, targetPath, sourceOutput = 0, targetInput = 0) {
+    return this.request("POST", "/api/connect", ConnectResultSchema, {
+      source_path: sourcePath,
+      target_path: targetPath,
+      source_output: sourceOutput,
+      target_input: targetInput
+    });
+  }
+  disconnectNodes(toPath, fromPath, toInput) {
+    return this.request("POST", "/api/disconnect", DisconnectResultSchema, {
+      to_path: toPath,
+      from_path: fromPath ?? null,
+      to_input: toInput ?? null
+    });
+  }
+  // --- Param-mode + DAT-text endpoints (survive ALLOW_EXEC=0) ---
+  readParameterModes(path2, keys, nonDefaultOnly = false) {
+    return this.request("GET", `/api/nodes/${segment(path2)}/params`, ParamModesSchema, void 0, {
+      modes: true,
+      keys: keys?.join(","),
+      non_default_only: nonDefaultOnly || void 0
+    });
+  }
+  setParameterMode(path2, param, mode, expr, value) {
+    return this.request(
+      "PATCH",
+      `/api/nodes/${segment(path2)}/params/${encodeURIComponent(param)}/mode`,
+      SetParamModeResultSchema,
+      { mode, expr, value }
+    );
+  }
+  getDatText(path2) {
+    return this.request("GET", `/api/nodes/${segment(path2)}/text`, DatTextSchema);
+  }
+  putDatText(path2, text) {
+    return this.request("PUT", `/api/nodes/${segment(path2)}/text`, DatTextWriteSchema, { text });
+  }
+  // --- Structured bridge logs (Error DAT reader) ---
+  getLogs(severity = "all", maxLines = 200, scope) {
+    return this.request("GET", "/api/logs", BridgeLogsSchema, void 0, {
+      severity,
+      max_lines: maxLines,
+      scope
+    });
+  }
 };
 
 // src/utils/config.ts
@@ -1599,6 +1737,13 @@ async function checkErrors(client, path2, recursive = true) {
 
 // src/tools/layer2/connectHelper.ts
 async function connectNodesViaBridge(client, sourcePath, targetPath, sourceOutput = 0, targetInput = 0) {
+  try {
+    const r2 = await client.connectNodes(sourcePath, targetPath, sourceOutput, targetInput);
+    return { method: "endpoint", actualInput: r2.actual_input };
+  } catch (err) {
+    if (!isMissingEndpoint(err)) throw err;
+  }
+  let batchError;
   try {
     const result = await client.batch([
       {
@@ -1609,7 +1754,9 @@ async function connectNodesViaBridge(client, sourcePath, targetPath, sourceOutpu
         target_input: targetInput
       }
     ]);
-    if (result.results[0]?.ok) return { method: "batch" };
+    const op = result.results[0];
+    if (op?.ok) return { method: "batch" };
+    batchError = op?.error;
   } catch (err) {
     if (!(err instanceof TdApiError)) throw err;
   }
@@ -1621,8 +1768,17 @@ async function connectNodesViaBridge(client, sourcePath, targetPath, sourceOutpu
     `if __s.parent() is None or __d.parent() is None or __s.parent().path != __d.parent().path: raise ValueError('connect: cannot wire across containers (%s -> %s); use a Select/In OP to bring an operator across networks' % (${src}, ${dst}))`,
     `__d.inputConnectors[${targetInput}].connect(__s.outputConnectors[${sourceOutput}])`
   ].join("\n");
-  await client.executePythonScript(python, false);
-  return { method: "python" };
+  try {
+    await client.executePythonScript(python, false);
+  } catch (err) {
+    if (batchError) {
+      throw new TdApiError(`${friendlyTdError(err)} (batch connect also failed: ${batchError})`, {
+        cause: err
+      });
+    }
+    throw err;
+  }
+  return batchError ? { method: "python", batchError } : { method: "python" };
 }
 
 // src/tools/layout.ts
@@ -3402,7 +3558,7 @@ var createDatamoshSchema = z15.object({
     "How slowly the trail fades (0\u20131). Higher values = longer smear / more persistent ghost. Applied via levelTOP brightness1. Default 0.9."
   ),
   displace: z15.coerce.number().min(0).default(0).describe(
-    "Pixel displacement of the fed-back frame each cycle (the 'mosh wobble'). Applied via displaceTOP displaceweight. 0 = no wobble. Default 0.0."
+    "Pixel displacement of the fed-back frame each cycle (the 'mosh wobble'). Applied via displaceTOP displaceweight1 (falls back to displaceweight on older builds). 0 = no wobble. Default 0.0."
   ),
   resolution: z15.tuple([z15.number(), z15.number()]).default([1280, 720]).describe(
     "Output resolution [width, height] in pixels. Forced on the feedback loop to prevent flickering. Default [1280, 720]."
@@ -3434,11 +3590,23 @@ async function buildFeedbackEcho(builder, args) {
   const decay = await builder.add("levelTOP", "decay1");
   await builder.setParams(decay, { brightness1: args.decay });
   let last = comp;
+  let dispPath = null;
   if (args.displace > 0) {
     const disp = await builder.add("displaceTOP", "displace1");
-    await builder.setParams(disp, { displaceweight: args.displace });
+    await builder.python(
+      `_d = op(${q10(disp)})
+_set = False
+for _pn in ['displaceweight1', 'displaceweight']:
+    try:
+        setattr(_d.par, _pn, ${args.displace})
+        _set = True
+        break
+    except Exception:
+        pass`
+    );
     await builder.connect(last, disp, 0, 0);
     await builder.connect(src, disp, 0, 1);
+    dispPath = disp;
     last = disp;
   }
   await builder.connect(last, decay);
@@ -3460,14 +3628,14 @@ async function buildFeedbackEcho(builder, args) {
       default: args.decay,
       bind_to: [`${decay}.brightness1`]
     },
-    ...args.displace > 0 ? [
+    ...dispPath !== null ? [
       {
         name: "Displace",
         type: "float",
         min: 0,
         max: 1,
         default: args.displace,
-        bind_to: [`${decay}.displaceweight`]
+        bind_to: [`${dispPath}.displaceweight1`, `${dispPath}.displaceweight`]
       }
     ] : []
   ];
@@ -3497,7 +3665,17 @@ async function buildFrameBlend(builder, args) {
   let last = comp;
   if (args.displace > 0) {
     const disp = await builder.add("displaceTOP", "displace1");
-    await builder.setParams(disp, { displaceweight: args.displace });
+    await builder.python(
+      `_d = op(${q10(disp)})
+_set = False
+for _pn in ['displaceweight1', 'displaceweight']:
+    try:
+        setattr(_d.par, _pn, ${args.displace})
+        _set = True
+        break
+    except Exception:
+        pass`
+    );
     await builder.connect(last, disp, 0, 0);
     await builder.connect(src, disp, 0, 1);
     last = disp;
@@ -3549,7 +3727,17 @@ async function buildTimeEcho(builder, args) {
   let last = timeMachine;
   if (args.displace > 0) {
     const disp = await builder.add("displaceTOP", "displace1");
-    await builder.setParams(disp, { displaceweight: args.displace });
+    await builder.python(
+      `_d = op(${q10(disp)})
+_set = False
+for _pn in ['displaceweight1', 'displaceweight']:
+    try:
+        setattr(_d.par, _pn, ${args.displace})
+        _set = True
+        break
+    except Exception:
+        pass`
+    );
     await builder.connect(last, disp, 0, 0);
     await builder.connect(noiseMap, disp, 0, 1);
     last = disp;
@@ -5346,7 +5534,7 @@ import { z as z27 } from "zod";
 var q21 = (value) => JSON.stringify(value);
 var HALFTONE_SHADER = `out vec4 fragColor;
 
-uniform int   uStyle;
+uniform float uStyle;
 uniform float uDotSize;
 uniform float uAngle;
 uniform float uMix;
@@ -5361,8 +5549,8 @@ vec2 rotateUV(vec2 uv, float angle) {
 
 // Dot-grid halftone: returns 0 (dot) or 1 (paper) for a single channel value
 float dotCell(vec2 uv, float val, float cellPx, float angle) {
-    // pixel size from TD built-in (no manual binding needed)
-    vec2 px = uTD2DInfos[0].res.zw;
+    // res.xy = (1/width, 1/height) per TDTexInfo layout \u2014 already texel size
+    vec2 px = uTDOutputInfo.res.xy;
     vec2 uvr = rotateUV(uv, angle);
     vec2 cell = fract(uvr / (cellPx * px)) - 0.5;
     float dist = length(cell);
@@ -5386,17 +5574,18 @@ float bayer4(vec2 pos) {
 void main() {
     vec2 uv = vUV.st;
     vec4 orig = texture(sTD2DInputs[0], uv);
+    int style = int(uStyle);
 
     vec4 styled;
 
-    if (uStyle == 0) {
+    if (style == 0) {
         // ---- DOTS: monochrome halftone ----
         float lum = dot(orig.rgb, vec3(0.299, 0.587, 0.114));
         float angleRad = uAngle * 3.14159265 / 180.0;
         float paper = dotCell(uv, lum, uDotSize, angleRad);
         styled = vec4(vec3(paper), orig.a);
 
-    } else if (uStyle == 1) {
+    } else if (style == 1) {
         // ---- CMYK: 4-colour halftone separation ----
         // Convert RGB \u2192 CMY; K = min component
         float k = 1.0 - max(max(orig.r, orig.g), orig.b);
@@ -5416,9 +5605,9 @@ void main() {
         col -= (1.0 - kDot) * vec3(1.0, 1.0, 1.0);  // black ink
         styled = vec4(clamp(col, 0.0, 1.0), orig.a);
 
-    } else if (uStyle == 2) {
+    } else if (style == 2) {
         // ---- DITHER: 4\xD74 Bayer ordered dither ----
-        vec2 px = uTD2DInfos[0].res.zw;
+        vec2 px = uTDOutputInfo.res.xy;
         vec2 screenPos = uv / px;
         float thresh = bayer4(screenPos);
         // Quantise each channel against the dither threshold
@@ -5434,7 +5623,7 @@ void main() {
         float levels = 6.0;
         vec3 post = floor(orig.rgb * levels) / levels;
         // Edge detect via luminance gradient (centre-difference, 1-pixel step)
-        vec2 px = uTD2DInfos[0].res.zw;
+        vec2 px = uTDOutputInfo.res.xy;
         float lc = dot(orig.rgb,                                    vec3(0.299, 0.587, 0.114));
         float lr = dot(texture(sTD2DInputs[0], uv + vec2(px.x, 0.0)).rgb, vec3(0.299, 0.587, 0.114));
         float lu = dot(texture(sTD2DInputs[0], uv + vec2(0.0, px.y)).rgb, vec3(0.299, 0.587, 0.114));
@@ -13645,13 +13834,23 @@ async function connectNodesImpl(ctx, args) {
       args.source_output,
       args.target_input
     ),
-    (result) => jsonResult(`Connected ${args.source_path} \u2192 ${args.target_path} (via ${result.method}).`, {
-      source: args.source_path,
-      target: args.target_path,
-      source_output: args.source_output,
-      target_input: args.target_input,
-      method: result.method
-    })
+    (result) => {
+      const actualInput = result.actualInput ?? args.target_input;
+      const packed = result.actualInput !== void 0 && result.actualInput !== args.target_input;
+      const note = (result.batchError ? ` Batch connect first failed (${result.batchError}); used the Python fallback.` : "") + (packed ? ` Requested input ${args.target_input} packed to live slot ${actualInput}.` : "");
+      return jsonResult(
+        `Connected ${args.source_path} \u2192 ${args.target_path} (via ${result.method}).${note}`,
+        {
+          source: args.source_path,
+          target: args.target_path,
+          source_output: args.source_output,
+          target_input: args.target_input,
+          actual_input: actualInput,
+          method: result.method,
+          ...result.batchError ? { batch_error: result.batchError } : {}
+        }
+      );
+    }
   );
 }
 
@@ -16022,19 +16221,478 @@ async function createLedMapperImpl(ctx, args) {
   );
 }
 
-// src/tools/layer2/createMacro.ts
+// src/tools/layer2/createLookBank.ts
 import { z as z98 } from "zod";
-var macroTargetSchema = z98.object({
-  param: z98.string().describe("Parameter to drive, written as 'nodePath.parName'."),
-  min: z98.coerce.number().describe("Value this target takes when the macro is at 0."),
-  max: z98.coerce.number().describe("Value this target takes when the macro is at 1."),
-  curve: z98.coerce.number().positive().default(1).describe("Response curve exponent: 1 = linear, >1 = ease-in, <1 = ease-out.")
+var createLookBankSchema = z98.object({
+  action: z98.enum(["build", "store", "recall", "set_ab", "list", "delete"]).default("build").describe(
+    "build: create the look-bank container (Table DAT + A\u2194B morph knob + recall button row) on a control COMP. store: snapshot the COMP's current numeric look into a named slot. recall: jump or crossfade to a slot. set_ab: assign which two slots the A\u2194B knob blends, and optionally set the knob. list / delete slots."
+  ),
+  comp_path: z98.string().default("/project1").describe(
+    "Control COMP whose custom-parameter values the looks capture (a control-panel container, e.g. from create_control_panel). The look-bank widgets are built inside it; recall drives this COMP's params."
+  ),
+  name: z98.string().default("look_bank").describe("Name of the look-bank panel container built inside comp_path."),
+  slot: z98.string().optional().describe("Slot name (required for store / recall / delete)."),
+  morph_seconds: z98.coerce.number().min(0).default(0).describe(
+    "(recall) 0 = snap instantly; >0 = crossfade to the slot over this many seconds (eased), via the cue morph engine."
+  ),
+  quantize: z98.enum(["off", "beat", "bar"]).default("off").describe(
+    "(recall) Defer the snap/crossfade to the next musical boundary (project tempo), so look changes land on the downbeat. Mirrors manage_cue."
+  ),
+  slot_a: z98.string().optional().describe("(set_ab) Slot the A\u2194B knob reads at value 0."),
+  slot_b: z98.string().optional().describe("(set_ab) Slot the A\u2194B knob reads at value 1."),
+  ab: z98.coerce.number().min(0).max(1).optional().describe(
+    "(set_ab) Optionally set the A\u2194B knob position now (0 = slot A, 1 = slot B, 0.5 = halfway). Omit to just (re)assign the slots."
+  ),
+  include: z98.array(z98.string()).optional().describe(
+    "(store) Restrict the snapshot to these custom-parameter names. Omit to capture every numeric/toggle/menu parameter (pulses and strings are always skipped)."
+  )
+});
+var AB_BLEND_CB = `import td
+
+def _lookbank_blend():
+    bank = me.parent()
+    comp = bank.parent()
+    st = bank.fetch('tdmcp_lookbank_ab', {})
+    sa = st.get('slot_a'); sb = st.get('slot_b')
+    if not sa or not sb:
+        return
+    tbl = bank.op('looks')
+    if tbl is None or tbl.numRows < 1:
+        return
+    header = [tbl[0, c].val for c in range(tbl.numCols)]
+    if sa not in header or sb not in header:
+        return
+    ca = header.index(sa); cb = header.index(sb)
+    abpar = getattr(bank.par, 'Ab', None)
+    ab = float(abpar.eval()) if abpar is not None else 0.0
+    for r in range(1, tbl.numRows):
+        k = tbl[r, 0].val
+        par = getattr(comp.par, k, None)
+        if par is None or par.readOnly or not getattr(par, 'isNumber', False):
+            continue
+        try:
+            a = float(tbl[r, ca].val); b = float(tbl[r, cb].val)
+        except Exception:
+            continue
+        val = a + (b - a) * ab
+        try:
+            par.val = int(round(val)) if getattr(par, 'style', '') == 'Int' else val
+        except Exception:
+            pass
+    return
+
+def onValueChange(par, prev):
+    if par.name == 'Ab':
+        _lookbank_blend()
+    return
+
+def onPulse(par):
+    return
+`;
+var LOOKBANK_SCRIPT = `
+import ast, json, base64, traceback
+import td
+_p = json.loads(base64.b64decode("__PAYLOAD_B64__").decode("utf-8"))
+report = {"action": _p["action"], "comp": _p["comp"], "warnings": []}
+_c = op(_p["comp"])
+
+def _next_boundary_delay(quant):
+    # Seconds from now (absTime) to the next beat/bar boundary, from the project tempo + signature.
+    # Returns 0.0 for 'off' or on any failure, degrading to an immediate change.
+    if quant not in ("beat", "bar"):
+        return 0.0
+    try:
+        _t = op('/').time
+        _tempo = float(getattr(_t, 'tempo', 0.0) or 0.0)
+        if _tempo <= 0.0:
+            return 0.0
+        _spb = 60.0 / _tempo
+        _beat = getattr(_t, 'beat', None)
+        if _beat is None:
+            _secs = float(getattr(_t, 'seconds', 0.0) or 0.0)
+            _beat = _secs / _spb
+        _beat = float(_beat)
+        if quant == "beat":
+            _period = 1.0
+        else:
+            _bpb = int(round(float(getattr(_t, 'signature1', 4) or 4)))
+            if _bpb < 1:
+                _bpb = 4
+            _period = float(_bpb)
+        _phase = _beat % _period
+        _remaining = _period - _phase
+        if _remaining <= 1e-6:
+            _remaining = _period
+        return _remaining * _spb
+    except Exception:
+        return 0.0
+
+def _table(bank):
+    return bank.op('looks') or bank.create(td.tableDAT, 'looks')
+
+def _header(tbl):
+    if tbl.numRows < 1:
+        tbl.appendRow(['param'])
+    return [tbl[0, c].val for c in range(tbl.numCols)]
+
+def _slots(tbl):
+    return _header(tbl)[1:] if tbl.numRows >= 1 else []
+
+def _col_dict(tbl, slot):
+    # Read a slot column into {param: typed value}. Values are stored as repr() so bools/ints/
+    # floats round-trip; fall back to a float, then the raw string.
+    hdr = _header(tbl)
+    if slot not in hdr:
+        return {}
+    ci = hdr.index(slot)
+    out = {}
+    for r in range(1, tbl.numRows):
+        k = tbl[r, 0].val
+        raw = tbl[r, ci].val
+        if raw == '':
+            continue
+        v = raw
+        try:
+            # literal_eval safely round-trips the repr() values written by store
+            # (numbers, strings, bool, None, tuples/lists) and REJECTS code, so a
+            # hand-edited look slot cannot execute arbitrary expressions in TD.
+            v = ast.literal_eval(raw)
+        except Exception:
+            try:
+                v = float(raw)
+            except Exception:
+                v = raw
+        out[k] = v
+    return out
+
+def _ensure_morph(comp, text):
+    h = comp.op('cue_morph') or comp.create(td.executeDAT, 'cue_morph')
+    h.text = text
+    if hasattr(h.par, 'framestart'):
+        h.par.framestart = True
+    h.par.active = True
+    return h
+
+def _btn_name(s):
+    # Deterministic, INJECTIVE op name: ASCII-alnum chars pass through, every other
+    # char (including '_' and non-ASCII) is escaped as _<HEX>_, so distinct slot
+    # labels can NEVER collide to the same buttonCOMP (e.g. 'intro/drop' vs
+    # 'intro_drop'). Pure function of the label, so create and delete agree; the
+    # displayed label (par.label) and the cue key keep the raw slot string.
+    _out = []
+    for _ch in str(s):
+        if _ch.isascii() and _ch.isalnum():
+            _out.append(_ch)
+        else:
+            _out.append('_%X_' % ord(_ch))
+    return 'recall_' + (''.join(_out) or 'slot')
+
+def _rebuild_buttons(bank, comp, btn_cb):
+    # One momentary buttonCOMP per slot + one Panel Execute DAT dispatching them via the shared
+    # tdmcp_surface_cues map (same shape create_control_surface uses), so SURFACE_BUTTON_CB fires
+    # the mirrored cue. morph_seconds per button defaults to 0 (snap) on (re)build.
+    tbl = _table(bank)
+    slots = _slots(tbl)
+    cmap = {}
+    paths = []
+    for s in slots:
+        _nm = _btn_name(s)
+        bt = bank.op(_nm) or bank.create(td.buttonCOMP, _nm)
+        try:
+            bt.par.w = 110; bt.par.h = 60
+            bt.par.label = s
+            if hasattr(bt.par, 'buttontype'):
+                bt.par.buttontype = 'momentary'
+        except Exception:
+            pass
+        cmap[bt.path] = {"comp": comp.path, "cue": s, "dur": 0}
+        paths.append(bt.path)
+    if paths:
+        bank.store('tdmcp_surface_cues', cmap)
+        pe = bank.op('recall_exec') or bank.create(td.panelexecuteDAT, 'recall_exec')
+        pe.text = btn_cb
+        try:
+            pe.par.panels = " ".join(paths)
+            if hasattr(pe.par, 'offtoon'):
+                pe.par.offtoon = True
+            pe.par.active = True
+        except Exception:
+            pass
+    return paths
+
+try:
+    if _c is None:
+        report["fatal"] = "COMP not found: " + _p["comp"]
+    elif not hasattr(_c, "customPars"):
+        report["fatal"] = _p["comp"] + " is not a COMP, so it has no custom parameters to snapshot."
+    else:
+        _action = _p["action"]
+        _bank = _c.op(_p["name"]) or _c.create(td.containerCOMP, _p["name"])
+        report["bank"] = _bank.path
+        _tbl = _table(_bank)
+        report["table"] = _tbl.path
+        _ensure_morph(_c, _p["morph_text"])
+        # Ensure the Ab knob + its watcher exist on every action so the panel is always live.
+        if getattr(_bank.par, "Ab", None) is None:
+            _pg = None
+            for _g in _bank.customPages:
+                if _g.name == "LookBank":
+                    _pg = _g; break
+            if _pg is None:
+                _pg = _bank.appendCustomPage("LookBank")
+            _abp = _pg.appendFloat("Ab")[0]
+            _abp.normMin = 0; _abp.normMax = 1; _abp.default = 0; _abp.val = 0
+        _abx = _bank.op("ab_exec") or _bank.create(td.parameterexecuteDAT, "ab_exec")
+        _abx.text = _p["ab_cb"]
+        try:
+            _abx.par.op = _bank.path
+            if hasattr(_abx.par, "valuechange"):
+                _abx.par.valuechange = True
+            if hasattr(_abx.par, "pars"):
+                _abx.par.pars = "Ab"
+            _abx.par.active = True
+        except Exception:
+            report["warnings"].append("Could not fully wire the A/B watcher.")
+
+        if _action == "build":
+            report["buttons"] = _rebuild_buttons(_bank, _c, _p["button_cb"])
+            report["slots"] = _slots(_tbl)
+        elif _action == "list":
+            report["slots"] = _slots(_tbl)
+        elif _action == "store":
+            _slot = _p.get("slot")
+            _include = _p.get("include")
+            _captured = []; _skipped = []
+            _vals = {}
+            for _pr in _c.customPars:
+                _name = _pr.name
+                if _include and _name not in _include:
+                    continue
+                _keep = ((_pr.isNumber or _pr.isToggle or _pr.isMenu)
+                         and not _pr.readOnly
+                         and not (_pr.isPulse or _pr.isMomentary)
+                         and not _pr.isString)
+                if not _keep:
+                    _skipped.append(_name); continue
+                try:
+                    _vals[_name] = _pr.eval()
+                    _captured.append(_name)
+                except Exception:
+                    _skipped.append(_name)
+            # Write the slot column into the looks table (append the column if new).
+            _hdr = _header(_tbl)
+            if _slot not in _hdr:
+                _tbl.appendCol([_slot])
+                _hdr = _header(_tbl)
+            _ci = _hdr.index(_slot)
+            # Clear the column first: a re-store capturing FEWER params must not leave
+            # stale cells behind (recall reads the Table column, skipping blank cells).
+            for _r in range(1, _tbl.numRows):
+                _tbl[_r, _ci] = ''
+            # Ensure a row exists for each captured param, then write repr() into the slot cell.
+            _rows = {_tbl[_r, 0].val: _r for _r in range(1, _tbl.numRows)}
+            for _k, _v in _vals.items():
+                if _k not in _rows:
+                    _newrow = [''] * _tbl.numCols
+                    _newrow[0] = _k
+                    _tbl.appendRow(_newrow)
+                    _rows[_k] = _tbl.numRows - 1
+                _tbl[_rows[_k], _ci] = repr(_v)
+            # Mirror into comp_path's tdmcp_cues so the slot is interoperable + recall-able.
+            _cues = dict(_c.fetch("tdmcp_cues", {}))
+            _cues[_slot] = _vals
+            _c.store("tdmcp_cues", _cues)
+            report["slot"] = _slot
+            report["captured"] = sorted(_captured)
+            report["skipped"] = sorted(_skipped)
+            report["slots"] = _slots(_tbl)
+            report["buttons"] = _rebuild_buttons(_bank, _c, _p["button_cb"])
+        elif _action == "recall":
+            _slot = _p.get("slot")
+            _to = _col_dict(_tbl, _slot)
+            if not _to and _slot not in _slots(_tbl):
+                report["fatal"] = "Slot not found: '%s' (available: %s)" % (_slot, ", ".join(_slots(_tbl)) or "none")
+            else:
+                _quant = _p.get("quantize") or "off"
+                _delay = _next_boundary_delay(_quant)
+                _dur = float(_p.get("morph_seconds") or 0)
+                if _dur <= 0 and _delay <= 0.0:
+                    _restored = []
+                    for _k, _v in _to.items():
+                        _pr = getattr(_c.par, _k, None)
+                        if _pr is None or _pr.readOnly:
+                            report["warnings"].append("skipped " + _k); continue
+                        try:
+                            _pr.val = _v; _restored.append(_k)
+                        except Exception:
+                            report["warnings"].append("could not set " + _k)
+                    report["restored"] = sorted(_restored)
+                else:
+                    _from = {}
+                    for _k in _to.keys():
+                        _pr = getattr(_c.par, _k, None)
+                        if _pr is not None:
+                            try:
+                                _from[_k] = _pr.eval()
+                            except Exception:
+                                pass
+                    _tdur = _dur if _dur > 0 else 0.0001
+                    _start = td.absTime.seconds + _delay
+                    _c.store("tdmcp_cue_transition", {"active": True, "from": _from, "to": _to, "start": _start, "duration": _tdur})
+                    _ensure_morph(_c, _p["morph_text"])
+                    report["restored"] = sorted(_from.keys())
+                    if _dur > 0:
+                        report["morph_seconds"] = _dur
+                    if _delay > 0.0:
+                        report["quantize"] = _quant; report["scheduled_in"] = round(_delay, 4)
+                report["slot"] = _slot
+        elif _action == "set_ab":
+            _sa = _p.get("slot_a"); _sb = _p.get("slot_b")
+            _st = dict(_bank.fetch("tdmcp_lookbank_ab", {}))
+            _st["slot_a"] = _sa; _st["slot_b"] = _sb
+            _ab = _p.get("ab")
+            if _ab is not None:
+                _st["ab"] = float(_ab)
+            _bank.store("tdmcp_lookbank_ab", _st)
+            report["slot_a"] = _sa; report["slot_b"] = _sb
+            if _ab is not None:
+                _abp = getattr(_bank.par, "Ab", None)
+                if _abp is not None and not _abp.readOnly:
+                    try:
+                        _abp.val = float(_ab)
+                    except Exception:
+                        pass
+                report["ab"] = float(_ab)
+                # Run the blend once so the knob preview is live immediately.
+                _hdr = _header(_tbl)
+                if _sa in _hdr and _sb in _hdr:
+                    _da = _col_dict(_tbl, _sa); _dbb = _col_dict(_tbl, _sb)
+                    for _k, _av in _da.items():
+                        _pr = getattr(_c.par, _k, None)
+                        if _pr is None or _pr.readOnly or not getattr(_pr, "isNumber", False):
+                            continue
+                        _bv = _dbb.get(_k, _av)
+                        try:
+                            _val = float(_av) + (float(_bv) - float(_av)) * float(_ab)
+                            _pr.val = int(round(_val)) if getattr(_pr, "style", "") == "Int" else _val
+                        except Exception:
+                            pass
+            report["slots"] = _slots(_tbl)
+        elif _action == "delete":
+            _slot = _p.get("slot")
+            _hdr = _header(_tbl)
+            if _slot in _hdr:
+                _tbl.deleteCol(_hdr.index(_slot))
+                _bt = _bank.op(_btn_name(_slot))
+                if _bt is not None:
+                    _bt.destroy()
+                _cues = dict(_c.fetch("tdmcp_cues", {}))
+                if _slot in _cues:
+                    _cues.pop(_slot, None); _c.store("tdmcp_cues", _cues)
+                report["deleted"] = _slot
+                report["buttons"] = _rebuild_buttons(_bank, _c, _p["button_cb"])
+            else:
+                report["warnings"].append("Slot not found: " + str(_slot))
+            report["slots"] = _slots(_tbl)
+        else:
+            report["fatal"] = "Unknown action: " + str(_action)
+except Exception:
+    report["fatal"] = traceback.format_exc().splitlines()[-1]
+print(json.dumps(report))
+`;
+function buildLookBankScript(payload) {
+  return buildPayloadScript(LOOKBANK_SCRIPT, payload);
+}
+async function createLookBankImpl(ctx, args) {
+  if ((args.action === "store" || args.action === "recall" || args.action === "delete") && !args.slot) {
+    return errorResult(`A slot name is required for the '${args.action}' action.`);
+  }
+  if (args.action === "set_ab" && (!args.slot_a || !args.slot_b)) {
+    return errorResult("set_ab needs both slot_a and slot_b (the two looks the A\u2194B knob blends).");
+  }
+  const RESERVED_SLOT = "param";
+  if ([args.slot, args.slot_a, args.slot_b].includes(RESERVED_SLOT)) {
+    return errorResult(
+      `'${RESERVED_SLOT}' is a reserved slot name (the look table's parameter-key column). Choose a different slot name.`
+    );
+  }
+  return guardTd(
+    async () => {
+      const script = buildLookBankScript({
+        action: args.action,
+        comp: args.comp_path,
+        name: args.name,
+        slot: args.slot,
+        morph_seconds: args.morph_seconds,
+        quantize: args.quantize,
+        slot_a: args.slot_a,
+        slot_b: args.slot_b,
+        ab: args.ab,
+        include: args.include,
+        morph_text: MORPH_HOOK,
+        ab_cb: AB_BLEND_CB,
+        // SURFACE_BUTTON_CB is exported by the integrator (reuse decision A). Coalesce to "" so
+        // this file is runtime-safe before that one-line export lands; an empty dispatcher simply
+        // means no recall buttons fire until the export is applied (build still succeeds).
+        button_cb: SURFACE_BUTTON_CB ?? ""
+      });
+      const exec = await ctx.client.executePythonScript(script, true);
+      return parsePythonReport(exec.stdout);
+    },
+    (report) => {
+      if (report.fatal) {
+        return errorResult(`Look bank ${report.action} failed: ${report.fatal}`, report);
+      }
+      let summary;
+      switch (report.action) {
+        case "build":
+          summary = `Built look bank ${report.bank} on ${report.comp} (${report.slots?.length ?? 0} slot(s), A\u2194B morph knob ready).`;
+          break;
+        case "store": {
+          const cap = report.captured?.length ?? 0;
+          const skip = report.skipped?.length ?? 0;
+          summary = `Stored look "${report.slot}" (${cap} control(s) captured${skip ? `, ${skip} skipped` : ""}) on ${report.comp}.`;
+          break;
+        }
+        case "recall": {
+          const n = report.restored?.length ?? 0;
+          if (report.quantize) {
+            summary = `Look "${report.slot}" (${n} control(s)) ${report.morph_seconds ? `crossfades over ${report.morph_seconds}s` : "snaps"} on the next ${report.quantize} (~${report.scheduled_in}s) on ${report.comp}.`;
+          } else if (report.morph_seconds) {
+            summary = `Crossfading to look "${report.slot}" over ${report.morph_seconds}s (${n} control(s)) on ${report.comp}.`;
+          } else {
+            summary = `Recalled look "${report.slot}" (${n} control(s)) \u2014 jumped on ${report.comp}.`;
+          }
+          break;
+        }
+        case "set_ab":
+          summary = report.ab === void 0 ? `A\u2194B knob (re)assigned: A="${report.slot_a}" \u2192 B="${report.slot_b}" on ${report.comp} (knob not moved).` : `A\u2194B knob set to ${report.ab} blending A="${report.slot_a}" \u2192 B="${report.slot_b}" on ${report.comp}.`;
+          break;
+        case "delete":
+          summary = report.deleted ? `Deleted look "${report.deleted}" on ${report.comp}.` : `No look to delete on ${report.comp}.`;
+          break;
+        default:
+          summary = `${report.slots?.length ?? 0} look(s) on ${report.comp}: ${report.slots?.join(", ") || "no slots"}.`;
+      }
+      if (report.warnings.length) summary += ` ${report.warnings.length} warning(s).`;
+      return jsonResult(summary, report);
+    }
+  );
+}
+
+// src/tools/layer2/createMacro.ts
+import { z as z99 } from "zod";
+var macroTargetSchema = z99.object({
+  param: z99.string().describe("Parameter to drive, written as 'nodePath.parName'."),
+  min: z99.coerce.number().describe("Value this target takes when the macro is at 0."),
+  max: z99.coerce.number().describe("Value this target takes when the macro is at 1."),
+  curve: z99.coerce.number().positive().default(1).describe("Response curve exponent: 1 = linear, >1 = ease-in, <1 = ease-out.")
 });
-var createMacroSchema = z98.object({
-  comp_path: z98.string().default("/project1").describe("COMP that will hold the macro knob (usually a control-panel container)."),
-  name: z98.string().describe("Macro control name, e.g. 'Energy' or 'Intensity'."),
-  default: z98.coerce.number().min(0).max(1).default(0).describe("Initial macro value (0\u20131)."),
-  targets: z98.array(macroTargetSchema).min(1).describe("Parameters this macro drives, each remapped from the macro's 0\u20131 into [min,max].")
+var createMacroSchema = z99.object({
+  comp_path: z99.string().default("/project1").describe("COMP that will hold the macro knob (usually a control-panel container)."),
+  name: z99.string().describe("Macro control name, e.g. 'Energy' or 'Intensity'."),
+  default: z99.coerce.number().min(0).max(1).default(0).describe("Initial macro value (0\u20131)."),
+  targets: z99.array(macroTargetSchema).min(1).describe("Parameters this macro drives, each remapped from the macro's 0\u20131 into [min,max].")
 });
 var MACRO_SCRIPT = `
 import json, base64, traceback
@@ -16112,7 +16770,7 @@ async function createMacroImpl(ctx, args) {
 }
 
 // src/tools/layer2/createMidiMap.ts
-import { z as z99 } from "zod";
+import { z as z100 } from "zod";
 var DEVICE_PRESETS = {
   // Akai APC Mini Mk1 — UNVERIFIED
   // Faders: CC 48-55 on ch1; pads: note-on on ch1 (rows 0-7, cols 0-7)
@@ -16237,23 +16895,23 @@ var DEVICE_PRESETS = {
   // generic: bare MIDI In + empty template table — no preset bindings
   generic: []
 };
-var bindingSchema = z99.object({
-  control: z99.string().describe(
+var bindingSchema = z100.object({
+  control: z100.string().describe(
     "Control id from the device preset map, e.g. 'fader1', 'knob3', 'pad5'. For 'generic' device, use any label you choose."
   ),
-  target_param: z99.string().optional().describe("'nodePath.parName' to drive (for continuous controls)."),
-  cue: z99.string().optional().describe("Cue name to recall when this pad is triggered.")
+  target_param: z100.string().optional().describe("'nodePath.parName' to drive (for continuous controls)."),
+  cue: z100.string().optional().describe("Cue name to recall when this pad is triggered.")
 });
-var createMidiMapSchema = z99.object({
-  parent_path: z99.string().default("/project1").describe("COMP to create the MIDI map inside."),
-  name: z99.string().default("midi_map").describe("Name for the MIDI In CHOP node created under parent_path."),
-  device: z99.enum(["apc_mini", "launchpad", "midi_mix", "nanokontrol", "generic"]).default("nanokontrol").describe(
+var createMidiMapSchema = z100.object({
+  parent_path: z100.string().default("/project1").describe("COMP to create the MIDI map inside."),
+  name: z100.string().default("midi_map").describe("Name for the MIDI In CHOP node created under parent_path."),
+  device: z100.enum(["apc_mini", "launchpad", "midi_mix", "nanokontrol", "generic"]).default("nanokontrol").describe(
     "Controller preset. Each preset embeds a best-effort CC/note map for that device (UNVERIFIED \u2014 real numbers depend on firmware; validate with hardware). 'generic' builds a bare MIDI In + a template bind table with no preset."
   ),
-  target: z99.string().optional().describe(
+  target: z100.string().optional().describe(
     "COMP whose custom numeric params/cues the preset auto-binds faders/knobs onto. Faders bind to the first N float/int custom pars; pads look for matching cues. Auto-binding is best-effort and hardware-gated."
   ),
-  bindings: z99.array(bindingSchema).default([]).describe(
+  bindings: z100.array(bindingSchema).default([]).describe(
     "Explicit control\u2192param/cue overrides. Applied after the preset auto-map. Omit to rely entirely on the device preset's default map."
   )
 });
@@ -16417,17 +17075,277 @@ async function createMidiMapImpl(ctx, args) {
   );
 }
 
-// src/tools/layer2/createNodeChain.ts
-import { z as z100 } from "zod";
-var ChainNodeSchema = z100.object({
-  type: z100.string().describe("Operator type, e.g. 'noiseTOP'."),
-  name: z100.string().optional().describe("Name for this node; auto-generated when omitted."),
-  parameters: z100.record(z100.string(), z100.unknown()).optional().describe("Initial parameter values for this node, as a { parName: value } map.")
+// src/tools/layer2/createModulators.ts
+import { z as z101 } from "zod";
+var modulatorSchema = z101.object({
+  name: z101.string().optional().describe(
+    "Output channel name for this modulator (e.g. 'breathe', 'sweep'). Sanitized to a valid channel name; defaults to mod1, mod2, \u2026"
+  ),
+  shape: z101.enum(["sine", "triangle", "saw", "square", "random"]).default("sine").describe(
+    "Oscillator shape. 'saw' is a rising ramp; 'random' is a sample-&-hold (a new random value held each cycle) built from a Noise CHOP. Every shape sweeps the full depth range."
+  ),
+  rate_beats: z101.coerce.number().positive().default(4).describe(
+    "Cycle length in BEATS \u2014 how many beats one full cycle takes. 4 = one cycle per bar (slow breathe), 1 = one cycle per beat, 0.5 = twice per beat (eighths). Locked to the tempo source so it tracks BPM."
+  ),
+  depth_min: z101.coerce.number().default(0).describe("Low end of this modulator's output range."),
+  depth_max: z101.coerce.number().default(1).describe("High end of this modulator's output range."),
+  phase: z101.coerce.number().min(0).max(1).default(0).describe(
+    "Phase offset 0\u20131 (fraction of a cycle). Use to fan a bank out of step (e.g. 0, 0.25, 0.5, 0.75)."
+  )
 });
-var createNodeChainSchema = z100.object({
-  parent_path: z100.string().describe("Parent COMP to create the chain inside."),
-  nodes: z100.array(ChainNodeSchema).min(1).describe("Ordered list of nodes to create."),
-  connect_sequentially: z100.boolean().default(true).describe("Wire output[0] \u2192 input[0] for each consecutive pair.")
+var createModulatorsSchema = z101.object({
+  name: z101.string().default("modulators").describe("Name of the self-contained modulator-bank container."),
+  parent_path: z101.string().default("/project1").describe("Parent COMP the 'modulators' container is created inside."),
+  modulators: z101.array(modulatorSchema).min(1).max(32).describe(
+    "The modulators (LFOs) to build. Each becomes one named output channel on the bank's Null."
+  ),
+  tempo_source: z101.string().optional().describe(
+    "Path to an existing tempo Null/Beat CHOP carrying a 'bpm' channel (e.g. the Null from create_tempo_sync, '/project1/tempo_sync/tempo'). Omit to create a fresh Beat CHOP locked to TouchDesigner's global tempo inside the bank."
+  ),
+  bpm_channel: z101.string().default("bpm").describe("Name of the BPM channel on the tempo source to lock rates to."),
+  expose_controls: z101.boolean().default(true).describe(
+    "Expose a live custom-parameter page on the bank: a master Rate multiplier and a master Depth (amplitude) scale, so you can speed up or flatten the whole bank from one knob during a show."
+  )
+});
+var WAVE_MAP3 = {
+  sine: "sin",
+  triangle: "tri",
+  saw: "ramp",
+  square: "square"
+};
+var BIPOLAR_SHAPES = /* @__PURE__ */ new Set(["sine", "triangle", "square"]);
+function toChannelName(value, index) {
+  let name = value.replace(/[^a-zA-Z0-9_]/g, "");
+  if (!name) name = `mod${index + 1}`;
+  if (!/^[a-zA-Z]/.test(name)) name = `m${name}`;
+  return name;
+}
+function pyStr(value) {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+var MODULATORS_SCRIPT = `
+import json, base64, traceback
+_p = json.loads(base64.b64decode("__PAYLOAD_B64__").decode("utf-8"))
+report = {
+    "comp": "", "out_chop": "", "channels": [], "tempo_source": "",
+    "beat_created": False, "modulators": [], "time_playing": False,
+    "warnings": [],
+}
+try:
+    report["time_playing"] = bool(op('/').time.play)
+    _parent = op(_p["parent_path"])
+    if _parent is None:
+        report["fatal"] = "Parent not found: " + _p["parent_path"]
+    elif not hasattr(_parent, "create"):
+        report["fatal"] = _p["parent_path"] + " cannot contain operators."
+    else:
+        # Reuse-or-create the named container so it is NEVER auto-renamed on a
+        # collision: a bare create() would yield e.g. "modulators1" while the
+        # pre-built freq/rate expressions still point at parent_path/name, binding
+        # the bank to the wrong/missing tempo control. Clear children so a re-run
+        # rebuilds cleanly at deterministic child paths (beat / lfo_* / mod_out).
+        _comp = _parent.op(_p["name"])
+        if _comp is not None and not hasattr(_comp, "create"):
+            raise TypeError("%s exists and is not a container; pass a different name." % _comp.path)
+        _comp = _comp or _parent.create(containerCOMP, _p["name"])
+        for _old in list(_comp.children):
+            _old.destroy()
+        report["comp"] = _comp.path
+
+        # Resolve the tempo source: an external Null/Beat CHOP, or a fresh internal Beat CHOP.
+        _tempo_path = _p.get("tempo_source")
+        if _tempo_path:
+            if op(_tempo_path) is None:
+                report["warnings"].append("Tempo source not found: %s (rates will read 0 until it exists)." % _tempo_path)
+        else:
+            _beat = _comp.create(beatCHOP, "beat")
+            try:
+                _beat.par.bpm = 1
+            except Exception:
+                pass
+            _tempo_path = _beat.path
+            report["beat_created"] = True
+        report["tempo_source"] = _tempo_path
+
+        _merge = _comp.create(mergeCHOP, "merge")
+        _src_ops = []
+        for _m in _p["modulators"]:
+            try:
+                if _m["kind"] == "noise":
+                    _o = _comp.create(noiseCHOP, "noise_" + _m["channel"])
+                    _o.par.type = "random"
+                    try:
+                        _o.par.periodunit = "seconds"
+                    except Exception:
+                        pass
+                    _pp = _o.par.period
+                    _PM = type(_pp.mode)
+                    _pp.expr = _m["period_expr"]
+                    _pp.mode = _PM.EXPRESSION
+                else:
+                    _o = _comp.create(lfoCHOP, "lfo_" + _m["channel"])
+                    _o.par.wavetype = _m["wavetype"]
+                    _o.par.phase = _m["phase"]
+                    _fp = _o.par.frequency
+                    _PM = type(_fp.mode)
+                    _fp.expr = _m["freq_expr"]
+                    _fp.mode = _PM.EXPRESSION
+                _o.par.amp = _m["amp"]
+                _o.par.offset = _m["offset"]
+                _o.par.channelname = _m["channel"]
+                _src_ops.append(_o)
+                report["modulators"].append({"op": _o.path, "channel": _m["channel"], "shape": _m["shape"], "rate_beats": _m["rate_beats"]})
+                report["channels"].append(_m["channel"])
+            except Exception:
+                report["warnings"].append("Failed to build modulator '%s': %s" % (_m.get("channel", "?"), traceback.format_exc().splitlines()[-1]))
+
+        for _i, _o in enumerate(_src_ops):
+            try:
+                _merge.inputConnectors[_i].connect(_o)
+            except Exception:
+                report["warnings"].append("Failed to wire %s into merge." % _o.path)
+
+        _tail = _merge
+        _controls = []
+        if _p["expose_controls"]:
+            _depth = _comp.op("depth") or _comp.create(mathCHOP, "depth")
+            _depth.inputConnectors[0].connect(_merge)
+            # Reuse existing Rate/Depth controls on a re-run: children were cleared,
+            # but the container's custom page/params persist \u2014 re-appending would make
+            # Rate1/Depth1 while the expressions still bind .par.Rate/.par.Depth.
+            _rate_par = getattr(_comp.par, "Rate", None)
+            _depth_par = getattr(_comp.par, "Depth", None)
+            if _rate_par is None or _depth_par is None:
+                _page = _comp.appendCustomPage("Modulators")
+                if _rate_par is None:
+                    _rate_par = _page.appendFloat("Rate", label="Rate")[0]
+                if _depth_par is None:
+                    _depth_par = _page.appendFloat("Depth", label="Depth")[0]
+            _rate_par.normMin = 0.0; _rate_par.normMax = 4.0
+            _rate_par.default = 1.0; _rate_par.val = 1.0
+            _depth_par.normMin = 0.0; _depth_par.normMax = 2.0
+            _depth_par.default = 1.0; _depth_par.val = 1.0
+            # Master Depth scales the whole bank's amplitude via the Math CHOP gain.
+            try:
+                _gp = _depth.par.gain
+                _PM = type(_gp.mode)
+                _gp.expr = "op(%s).par.Depth" % repr(_comp.path)
+                _gp.mode = _PM.EXPRESSION
+            except Exception:
+                report["warnings"].append("Could not bind master Depth to the Math CHOP gain.")
+            _tail = _depth
+            _controls = ["Rate", "Depth"]
+            report["controls"] = _controls
+
+        _out = _comp.create(nullCHOP, "mod_out")
+        _out.inputConnectors[0].connect(_tail)
+        report["out_chop"] = _out.path
+
+        # Warn on any duplicate channel names that survived TS de-duplication (defensive).
+        _seen = {}
+        for _c in report["channels"]:
+            _seen[_c] = _seen.get(_c, 0) + 1
+        for _c, _n in _seen.items():
+            if _n > 1:
+                report["warnings"].append("Duplicate channel name '%s' (x%d) \u2014 Merge keeps only one." % (_c, _n))
+except Exception:
+    report["fatal"] = traceback.format_exc().splitlines()[-1]
+print(json.dumps(report))
+`;
+function buildModulatorsScript(payload) {
+  return buildPayloadScript(MODULATORS_SCRIPT, payload);
+}
+function buildModulatorSpecs(args, tempoOp) {
+  const dupeWarnings = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  const masterRate = args.expose_controls ? ` * op(${pyStr(`${args.parent_path}/${args.name}`)}).par.Rate` : "";
+  const masterRateDiv = args.expose_controls ? ` / max(op(${pyStr(`${args.parent_path}/${args.name}`)}).par.Rate, 1e-6)` : "";
+  const specs = args.modulators.map((m, i) => {
+    const base = toChannelName(m.name ?? `mod${i + 1}`, i);
+    let channel = base;
+    if (usedNames.has(channel)) {
+      let n = 2;
+      while (usedNames.has(`${base}_${n}`)) n++;
+      channel = `${base}_${n}`;
+      dupeWarnings.push(
+        `Duplicate channel name '${base}' renamed to '${channel}' so both modulators survive the Merge.`
+      );
+    }
+    usedNames.add(channel);
+    const span = m.depth_max - m.depth_min;
+    const bipolar = BIPOLAR_SHAPES.has(m.shape);
+    const amp = bipolar ? span / 2 : span;
+    const offset = bipolar ? (m.depth_max + m.depth_min) / 2 : m.depth_min;
+    const cpb = 1 / m.rate_beats;
+    const beatsPerCycle = m.rate_beats;
+    const isNoise = m.shape === "random";
+    const tempoExpr = `op(${pyStr(tempoOp)})`;
+    const tempoRef = `(${tempoExpr}[${pyStr(args.bpm_channel)}] if ${tempoExpr} else 0.0)`;
+    return {
+      channel,
+      shape: m.shape,
+      kind: isNoise ? "noise" : "lfo",
+      wavetype: isNoise ? void 0 : WAVE_MAP3[m.shape],
+      amp,
+      offset,
+      phase: m.phase,
+      cpb,
+      beats_per_cycle: beatsPerCycle,
+      rate_beats: m.rate_beats,
+      freq_expr: isNoise ? void 0 : `${tempoRef} / 60.0 * ${cpb}${masterRate}`,
+      period_expr: isNoise ? args.expose_controls ? `(60.0 / max(${tempoRef}, 1e-6) * ${beatsPerCycle})${masterRateDiv}` : `60.0 / max(${tempoRef}, 1e-6) * ${beatsPerCycle}` : void 0
+    };
+  });
+  return { specs, dupeWarnings };
+}
+async function createModulatorsImpl(ctx, args) {
+  const tempoOp = args.tempo_source ?? `${args.parent_path}/${args.name}/beat`;
+  const { specs, dupeWarnings } = buildModulatorSpecs(args, tempoOp);
+  return guardTd(
+    async () => {
+      const script = buildModulatorsScript({
+        name: args.name,
+        parent_path: args.parent_path,
+        tempo_source: args.tempo_source ?? null,
+        bpm_channel: args.bpm_channel,
+        expose_controls: args.expose_controls,
+        modulators: specs
+      });
+      const exec = await ctx.client.executePythonScript(script, true);
+      return parsePythonReport(exec.stdout);
+    },
+    (report) => {
+      if (report.fatal) {
+        return errorResult(`Could not build modulators: ${report.fatal}`, report);
+      }
+      const warnings = [...dupeWarnings, ...report.warnings];
+      const tempoLabel = report.beat_created ? "TD global tempo" : report.tempo_source;
+      let summary = `Built a bank of ${report.channels.length} BPM-synced modulator(s) at ${report.out_chop} (channels: ${report.channels.join(", ")}), locked to ${tempoLabel}. Bind with bind_to_channel(source_chop="${report.out_chop}", channel="${report.channels[0] ?? "mod1"}").`;
+      if (report.controls?.length) {
+        summary += ` Master controls exposed: ${report.controls.join(", ")}.`;
+      }
+      if (!report.time_playing) {
+        summary += " \u26A0 The timeline is paused \u2014 modulators are frozen until you press Play (they're timeline-driven).";
+      }
+      if (warnings.length) {
+        summary += ` ${warnings.length} warning(s).`;
+      }
+      return jsonResult(summary, { ...report, warnings });
+    }
+  );
+}
+
+// src/tools/layer2/createNodeChain.ts
+import { z as z102 } from "zod";
+var ChainNodeSchema = z102.object({
+  type: z102.string().describe("Operator type, e.g. 'noiseTOP'."),
+  name: z102.string().optional().describe("Name for this node; auto-generated when omitted."),
+  parameters: z102.record(z102.string(), z102.unknown()).optional().describe("Initial parameter values for this node, as a { parName: value } map.")
+});
+var createNodeChainSchema = z102.object({
+  parent_path: z102.string().describe("Parent COMP to create the chain inside."),
+  nodes: z102.array(ChainNodeSchema).min(1).describe("Ordered list of nodes to create."),
+  connect_sequentially: z102.boolean().default(true).describe("Wire output[0] \u2192 input[0] for each consecutive pair.")
 });
 async function createNodeChainImpl(ctx, args) {
   const created = [];
@@ -16496,31 +17414,31 @@ async function createNodeChainImpl(ctx, args) {
 }
 
 // src/tools/layer2/createPalette.ts
-import { z as z101 } from "zod";
+import { z as z103 } from "zod";
 var MAX_SWATCHES = 13;
 var PALETTE_RULES = ["complementary", "analogous", "triad", "tetrad", "monochrome"];
-var createPaletteSchema = z101.object({
-  mode: z101.enum(["harmony", "from_source"]).default("harmony").describe(
+var createPaletteSchema = z103.object({
+  mode: z103.enum(["harmony", "from_source"]).default("harmony").describe(
     "How swatches are derived: 'harmony' computes them from a base hue + a colour-theory rule (pure maths); 'from_source' samples dominant colours from a source TOP."
   ),
-  base_hue: z101.coerce.number().min(0).max(1).default(0).describe(
+  base_hue: z103.coerce.number().min(0).max(1).default(0).describe(
     "(harmony) Base hue on the colour wheel, 0..1 (0 = red, 0.333 = green, 0.666 = blue)."
   ),
-  saturation: z101.coerce.number().min(0).max(1).default(0.7).describe("(harmony) Base saturation 0..1 (0 = grey, 1 = vivid)."),
-  value: z101.coerce.number().min(0).max(1).default(0.9).describe("(harmony) Base value / brightness 0..1."),
-  rule: z101.enum(PALETTE_RULES).default("triad").describe(
+  saturation: z103.coerce.number().min(0).max(1).default(0.7).describe("(harmony) Base saturation 0..1 (0 = grey, 1 = vivid)."),
+  value: z103.coerce.number().min(0).max(1).default(0.9).describe("(harmony) Base value / brightness 0..1."),
+  rule: z103.enum(PALETTE_RULES).default("triad").describe(
     "(harmony) Colour-theory spread: complementary (base + opposite), analogous (neighbours), triad (3 evenly spaced), tetrad (4 evenly spaced), monochrome (one hue, varied brightness)."
   ),
-  count: z101.coerce.number().int().min(1).max(MAX_SWATCHES).default(5).describe(
+  count: z103.coerce.number().int().min(1).max(MAX_SWATCHES).default(5).describe(
     `Number of swatches to produce (1..${MAX_SWATCHES}; capped because the swatch Constant CHOP holds 40 channels = 13 RGB swatches).`
   ),
-  analogous_spread: z101.coerce.number().min(0).max(0.5).default(0.083).describe("(harmony, analogous rule) Hue step between neighbours, 0..0.5 (0.083 \u2248 30\xB0)."),
-  source: z101.string().optional().describe(
+  analogous_spread: z103.coerce.number().min(0).max(0.5).default(0.083).describe("(harmony, analogous rule) Hue step between neighbours, 0..0.5 (0.083 \u2248 30\xB0)."),
+  source: z103.string().optional().describe(
     "(from_source) Absolute path of a TOP to sample dominant colours from. It is down-res'd to a tiny image and its pixels are read back; if missing/unreadable the palette falls back to a neutral greyscale ramp."
   ),
-  parent_path: z101.string().default("/project1").describe("COMP to build the Ramp TOP + swatch CHOP inside."),
-  name: z101.string().default("palette").describe("Base name for the created nodes."),
-  expose_controls: z101.boolean().default(true).describe("Add BaseHue / Saturation / Value / Rule / Count custom parameters to parent_path.")
+  parent_path: z103.string().default("/project1").describe("COMP to build the Ramp TOP + swatch CHOP inside."),
+  name: z103.string().default("palette").describe("Base name for the created nodes."),
+  expose_controls: z103.boolean().default(true).describe("Add BaseHue / Saturation / Value / Rule / Count custom parameters to parent_path.")
 });
 function wrapHue(h) {
   const x = h % 1;
@@ -16746,22 +17664,22 @@ async function createPaletteImpl(ctx, args) {
 }
 
 // src/tools/layer2/createPanic.ts
-import { z as z102 } from "zod";
+import { z as z104 } from "zod";
 var q57 = (value) => JSON.stringify(value);
-var createPanicSchema = z102.object({
-  input_path: z102.string().optional().describe(
+var createPanicSchema = z104.object({
+  input_path: z104.string().optional().describe(
     "Optional absolute path of the live source TOP to protect. Pulled in via a Select TOP (TD wires can't cross containers, so it's referenced by path). If omitted, a built-in test source (Ramp TOP) is used so the panic COMP still builds and previews on its own."
   ),
-  blackout: z102.boolean().default(false).describe(
+  blackout: z104.boolean().default(false).describe(
     "Initial Blackout state. When on, the output is forced to black (Level TOP brightness1 = 0) \u2014 the instant kill switch."
   ),
-  freeze: z102.boolean().default(false).describe(
+  freeze: z104.boolean().default(false).describe(
     "Initial Freeze state. When on, the last frame is held instead of passing the live input (Cache TOP stops capturing \u2014 active = 0)."
   ),
-  expose_controls: z102.boolean().default(true).describe(
+  expose_controls: z104.boolean().default(true).describe(
     "Expose big Blackout and Freeze toggle buttons on the container so a performer can hit them instantly."
   ),
-  parent_path: z102.string().default("/project1").describe("Parent COMP the panic container is built inside (default '/project1').")
+  parent_path: z104.string().default("/project1").describe("Parent COMP the panic container is built inside (default '/project1').")
 });
 async function createPanicImpl(ctx, args) {
   return runBuild(async () => {
@@ -16840,10 +17758,10 @@ _p.mode = type(_p.mode).EXPRESSION`
 }
 
 // src/tools/layer2/createPhoneRemote.ts
-import { z as z103 } from "zod";
-var createPhoneRemoteSchema = z103.object({
-  comp_path: z103.string().default("/project1").describe("Control COMP whose numeric custom parameters the phone page exposes."),
-  port: z103.coerce.number().int().positive().max(65535).default(9981).describe("TCP port for the remote web server (keep it distinct from the bridge's 9980).")
+import { z as z105 } from "zod";
+var createPhoneRemoteSchema = z105.object({
+  comp_path: z105.string().default("/project1").describe("Control COMP whose numeric custom parameters the phone page exposes."),
+  port: z105.coerce.number().int().positive().max(65535).default(9981).describe("TCP port for the remote web server (keep it distinct from the bridge's 9980).")
 });
 var REMOTE_CALLBACKS = `from urllib.parse import urlparse, parse_qs
 
@@ -16969,17 +17887,17 @@ async function createPhoneRemoteImpl(ctx, args) {
 }
 
 // src/tools/layer2/createPythonScript.ts
-import { z as z104 } from "zod";
+import { z as z106 } from "zod";
 var TYPE_MAP = {
   text: "textDAT",
   execute: "executeDAT",
   script: "scriptDAT"
 };
-var createPythonScriptSchema = z104.object({
-  parent_path: z104.string().describe("Parent COMP to create the DAT inside."),
-  name: z104.string().optional().describe("Name for the new DAT; auto-generated when omitted."),
-  code: z104.string().min(1).describe("Python source to place in the DAT."),
-  dat_type: z104.enum(["text", "execute", "script"]).default("text").describe("Kind of DAT: 'text' (plain), 'execute' (event hooks), or 'script' (table builder).")
+var createPythonScriptSchema = z106.object({
+  parent_path: z106.string().describe("Parent COMP to create the DAT inside."),
+  name: z106.string().optional().describe("Name for the new DAT; auto-generated when omitted."),
+  code: z106.string().min(1).describe("Python source to place in the DAT."),
+  dat_type: z106.enum(["text", "execute", "script"]).default("text").describe("Kind of DAT: 'text' (plain), 'execute' (event hooks), or 'script' (table builder).")
 });
 async function createPythonScriptImpl(ctx, args) {
   return guardTd(
@@ -17010,16 +17928,16 @@ async function createPythonScriptImpl(ctx, args) {
 }
 
 // src/tools/layer2/createReplicator.ts
-import { z as z105 } from "zod";
-var createReplicatorSchema = z105.object({
-  parent_path: z105.string().default("/project1").describe("COMP to build the replicator inside."),
-  name: z105.string().default("replicator1").describe("Name for the Replicator COMP."),
-  template_path: z105.string().optional().describe(
+import { z as z107 } from "zod";
+var createReplicatorSchema = z107.object({
+  parent_path: z107.string().default("/project1").describe("COMP to build the replicator inside."),
+  name: z107.string().default("replicator1").describe("Name for the Replicator COMP."),
+  template_path: z107.string().optional().describe(
     "Existing COMP to clone per row. Omit \u2192 create a minimal template COMP (a container with a Text)."
   ),
-  table_path: z105.string().optional().describe("Table DAT whose rows drive the clones. Omit \u2192 create a small example Table DAT."),
-  rows: z105.number().int().min(0).max(64).default(0).describe("When creating an example table, how many example rows (0 = a 3-row demo)."),
-  callback_stub: z105.boolean().default(true).describe("Generate an onReplicate callback DAT stub (per-clone setup hook).")
+  table_path: z107.string().optional().describe("Table DAT whose rows drive the clones. Omit \u2192 create a small example Table DAT."),
+  rows: z107.number().int().min(0).max(64).default(0).describe("When creating an example table, how many example rows (0 = a 3-row demo)."),
+  callback_stub: z107.boolean().default(true).describe("Generate an onReplicate callback DAT stub (per-clone setup hook).")
 });
 var REPLICATOR_SCRIPT = `
 import json, base64, traceback
@@ -17161,30 +18079,30 @@ async function createReplicatorImpl(ctx, args) {
 }
 
 // src/tools/layer2/createStageDashboard.ts
-import { z as z106 } from "zod";
-var faderSpecSchema = z106.object({
-  label: z106.string().describe("Fader label shown on the page."),
-  par_path: z106.string().describe(
+import { z as z108 } from "zod";
+var faderSpecSchema = z108.object({
+  label: z108.string().describe("Fader label shown on the page."),
+  par_path: z108.string().describe(
     "Absolute parameter path the fader drives, e.g. '/project1/level1/brightness1' or '/project1/comp1/Intensity'. Written live as a float."
   )
 });
-var createStageDashboardSchema = z106.object({
-  target: z106.string().default("/project1").describe(
+var createStageDashboardSchema = z108.object({
+  target: z108.string().default("/project1").describe(
     "Control COMP the dashboard is built inside. It holds the cues (manage_cue) and the Blackout/Freeze toggles (create_panic); cue buttons fire that COMP's cues and the panic button toggles its safety pars."
   ),
-  port: z106.coerce.number().int().positive().max(65535).default(9990).describe(
+  port: z108.coerce.number().int().positive().max(65535).default(9990).describe(
     "TCP port for the dashboard web server (keep it distinct from the bridge's 9980 and phone_remote's 9981)."
   ),
-  cues: z106.array(z106.string()).default([]).describe(
+  cues: z108.array(z108.string()).default([]).describe(
     "Cue names (stored with manage_cue) to expose as launch buttons, in order. Each becomes a button that instantly recalls its cue on the target COMP. Empty omits the cue grid."
   ),
-  faders: z106.array(faderSpecSchema).default([]).describe(
+  faders: z108.array(faderSpecSchema).default([]).describe(
     "Master faders, each a { label, par_path } that becomes a slider writing the parameter live. Empty omits the fader bank."
   ),
-  audio_features: z106.string().optional().describe(
+  audio_features: z108.string().optional().describe(
     "Optional audio-features Null CHOP path for the readout strip's VU bar (first channel). When omitted the readout still renders (beat from the timeline, VU flat)."
   ),
-  name: z106.string().default("stage_dashboard").describe("Name of the Web Server DAT (and its callbacks DAT) built inside the target COMP.")
+  name: z108.string().default("stage_dashboard").describe("Name of the Web Server DAT (and its callbacks DAT) built inside the target COMP.")
 });
 var DASHBOARD_CALLBACKS = `import json
 from urllib.parse import urlparse, parse_qs
@@ -17427,12 +18345,12 @@ async function createStageDashboardImpl(ctx, args) {
 }
 
 // src/tools/layer2/duplicateNetwork.ts
-import { z as z107 } from "zod";
+import { z as z109 } from "zod";
 var q58 = (value) => JSON.stringify(value);
-var duplicateNetworkSchema = z107.object({
-  source_path: z107.string().describe("Path of the node/COMP to duplicate."),
-  name: z107.string().optional().describe("Name for the copy (auto-generated if omitted)."),
-  parent_path: z107.string().optional().describe("Where to place the copy (defaults to the source's parent).")
+var duplicateNetworkSchema = z109.object({
+  source_path: z109.string().describe("Path of the node/COMP to duplicate."),
+  name: z109.string().optional().describe("Name for the copy (auto-generated if omitted)."),
+  parent_path: z109.string().optional().describe("Where to place the copy (defaults to the source's parent).")
 });
 async function duplicateNetworkImpl(ctx, args) {
   const script = [
@@ -17453,23 +18371,23 @@ async function duplicateNetworkImpl(ctx, args) {
 }
 
 // src/tools/layer2/learnControl.ts
-import { z as z108 } from "zod";
-var learnControlSchema = z108.object({
-  mode: z108.enum(["snapshot", "bind"]).describe(
+import { z as z110 } from "zod";
+var learnControlSchema = z110.object({
+  mode: z110.enum(["snapshot", "bind"]).describe(
     "snapshot: record the current value of every channel of source_chop. bind: re-read source_chop, find the channel that moved the most since the snapshot, and bind target to it. Call snapshot first (controls at rest), wiggle one hardware control, then call bind."
   ),
-  source_chop: z108.string().describe(
+  source_chop: z110.string().describe(
     "Absolute path of the input CHOP carrying the hardware controls (e.g. a midiin/oscin CHOP or a Null fed by one)."
   ),
-  target: z108.string().optional().describe(
+  target: z110.string().optional().describe(
     "Parameter to drive, written as 'nodePath.parName' (e.g. '/project1/sys/transform1.scale'). Required for mode:'bind'; switched to expression mode so it tracks the matched channel live."
   ),
-  scale: z108.coerce.number().default(1).describe("Multiply the matched channel value (mapping gain)."),
-  offset: z108.coerce.number().default(0).describe("Add to the scaled value (mapping offset)."),
-  min_delta: z108.coerce.number().optional().describe(
+  scale: z110.coerce.number().default(1).describe("Multiply the matched channel value (mapping gain)."),
+  offset: z110.coerce.number().default(0).describe("Add to the scaled value (mapping offset)."),
+  min_delta: z110.coerce.number().optional().describe(
     "mode:'bind' minimum NORMALIZED movement (default 0.05). The winning channel's delta is normalized by max(|old|, |new|, epsilon) \u2014 a unit-free relative change \u2014 so a 0\u2013127 MIDI CC and a 0\u20131 OSC float compare fairly. If the top channel moved less than this, nothing is bound and you're told to wiggle the control harder. Raise it to reject controller jitter; lower it for very small/slow knobs."
   ),
-  parent_path: z108.string().default("/project1").describe(
+  parent_path: z110.string().default("/project1").describe(
     "COMP whose storage persists the snapshot between the snapshot and bind calls (defaults to /project1)."
   )
 });
@@ -17620,21 +18538,21 @@ async function learnControlImpl(ctx, args) {
 }
 
 // src/tools/layer2/manageAnnotation.ts
-import { z as z109 } from "zod";
-var manageAnnotationSchema = z109.object({
-  action: z109.enum(["create", "comment", "list", "enclosed"]).describe(
+import { z as z111 } from "zod";
+var manageAnnotationSchema = z111.object({
+  action: z111.enum(["create", "comment", "list", "enclosed"]).describe(
     "'create' a titled annotation box, 'comment' to set an op's comment, 'list' the annotations in a network, or 'enclosed' to list the ops a box geometrically encloses."
   ),
-  parent_path: z109.string().default("/project1").describe("(create/list) The network (COMP) to act in."),
-  text: z109.string().optional().describe("(create) The title/text shown on the box; (comment) the comment string to set."),
-  name: z109.string().optional().describe("(create) Name for the annotation COMP (defaults to 'anno')."),
-  node_path: z109.string().optional().describe(
+  parent_path: z111.string().default("/project1").describe("(create/list) The network (COMP) to act in."),
+  text: z111.string().optional().describe("(create) The title/text shown on the box; (comment) the comment string to set."),
+  name: z111.string().optional().describe("(create) Name for the annotation COMP (defaults to 'anno')."),
+  node_path: z111.string().optional().describe(
     "(comment) The op to comment on; (enclosed) the annotation box whose enclosed ops to list."
   ),
-  x: z109.coerce.number().optional().describe("(create) Node-space X position for the box's left edge."),
-  y: z109.coerce.number().optional().describe("(create) Node-space Y position for the box's top edge."),
-  w: z109.coerce.number().optional().describe("(create) Node-space width of the box."),
-  h: z109.coerce.number().optional().describe("(create) Node-space height of the box.")
+  x: z111.coerce.number().optional().describe("(create) Node-space X position for the box's left edge."),
+  y: z111.coerce.number().optional().describe("(create) Node-space Y position for the box's top edge."),
+  w: z111.coerce.number().optional().describe("(create) Node-space width of the box."),
+  h: z111.coerce.number().optional().describe("(create) Node-space height of the box.")
 });
 var ANNOTATION_SCRIPT = `
 import json, base64, traceback
@@ -17879,15 +18797,15 @@ async function manageAnnotationImpl(ctx, args) {
 }
 
 // src/tools/layer2/manageCheckpoint.ts
-import { z as z110 } from "zod";
-var manageCheckpointSchema = z110.object({
-  action: z110.enum(["store", "restore", "list", "delete"]).describe(
+import { z as z112 } from "zod";
+var manageCheckpointSchema = z112.object({
+  action: z112.enum(["store", "restore", "list", "delete"]).describe(
     "store a full snapshot of a sub-network, restore one, list all, or delete one. A checkpoint is an 'undo point' before risky live edits."
   ),
-  comp_path: z110.string().default("/project1").describe("Root COMP whose whole sub-network the checkpoint captures."),
-  name: z110.string().optional().describe("Checkpoint name (required for store/restore/delete)."),
-  prune_created: z110.boolean().default(true).describe("(restore) Destroy nodes that were created after the checkpoint was stored."),
-  recreate_deleted: z110.boolean().default(true).describe(
+  comp_path: z112.string().default("/project1").describe("Root COMP whose whole sub-network the checkpoint captures."),
+  name: z112.string().optional().describe("Checkpoint name (required for store/restore/delete)."),
+  prune_created: z112.boolean().default(true).describe("(restore) Destroy nodes that were created after the checkpoint was stored."),
+  recreate_deleted: z112.boolean().default(true).describe(
     "(restore) Recreate nodes that were deleted after the checkpoint (type + params + wiring, best-effort)."
   )
 });
@@ -18090,17 +19008,17 @@ async function manageCheckpointImpl(ctx, args) {
 }
 
 // src/tools/layer2/manageComponent.ts
-import { z as z111 } from "zod";
-var manageComponentSchema = z111.object({
-  action: z111.enum(["save", "load"]).describe("save a COMP to a .tox file, or load a .tox into the project."),
-  file_path: z111.string().describe("Absolute path to the .tox file (e.g. '/Users/me/components/widget.tox')."),
-  comp_path: z111.string().optional().describe("(save) The COMP to save as a reusable .tox component."),
-  parent_path: z111.string().default("/project1").describe("(load) COMP to place the loaded component inside."),
-  linked: z111.boolean().default(false).describe(
+import { z as z113 } from "zod";
+var manageComponentSchema = z113.object({
+  action: z113.enum(["save", "load"]).describe("save a COMP to a .tox file, or load a .tox into the project."),
+  file_path: z113.string().describe("Absolute path to the .tox file (e.g. '/Users/me/components/widget.tox')."),
+  comp_path: z113.string().optional().describe("(save) The COMP to save as a reusable .tox component."),
+  parent_path: z113.string().default("/project1").describe("(load) COMP to place the loaded component inside."),
+  linked: z113.boolean().default(false).describe(
     "(load) Create a live-linked instance (externaltox) that re-reads the file on change, instead of an independent copy."
   ),
-  name: z111.string().optional().describe("(load, linked) Name for the linked COMP; defaults to the file name."),
-  create_folders: z111.boolean().default(false).describe("(save) Create the parent folders if they do not exist.")
+  name: z113.string().optional().describe("(load, linked) Name for the linked COMP; defaults to the file name."),
+  create_folders: z113.boolean().default(false).describe("(save) Create the parent folders if they do not exist.")
 });
 var COMPONENT_SCRIPT = `
 import json, base64, traceback, os
@@ -18191,14 +19109,14 @@ async function manageComponentImpl(ctx, args) {
 }
 
 // src/tools/layer2/managePresets.ts
-import { z as z112 } from "zod";
-var managePresetsSchema = z112.object({
-  action: z112.enum(["store", "recall", "list", "delete"]).describe("store a snapshot, recall one, list all, or delete one."),
-  comp_path: z112.string().default("/project1").describe(
+import { z as z114 } from "zod";
+var managePresetsSchema = z114.object({
+  action: z114.enum(["store", "recall", "list", "delete"]).describe("store a snapshot, recall one, list all, or delete one."),
+  comp_path: z114.string().default("/project1").describe(
     "COMP whose parameter values the preset captures \u2014 usually a control-panel container."
   ),
-  name: z112.string().optional().describe("Preset name (required for store/recall/delete)."),
-  params: z112.array(z112.string()).optional().describe(
+  name: z114.string().optional().describe("Preset name (required for store/recall/delete)."),
+  params: z114.array(z114.string()).optional().describe(
     "Specific custom-parameter names to capture/restore. Defaults to every custom parameter on the COMP."
   )
 });
@@ -18299,14 +19217,14 @@ async function managePresetsImpl(ctx, args) {
 }
 
 // src/tools/layer2/randomizeControls.ts
-import { z as z113 } from "zod";
-var randomizeControlsSchema = z113.object({
-  comp_path: z113.string().default("/project1").describe("COMP whose custom parameters to randomize (usually a control-panel container)."),
-  params: z113.array(z113.string()).optional().describe("Specific custom-parameter names to randomize. Defaults to every numeric one."),
-  amount: z113.coerce.number().min(0).max(1).default(1).describe(
+import { z as z115 } from "zod";
+var randomizeControlsSchema = z115.object({
+  comp_path: z115.string().default("/project1").describe("COMP whose custom parameters to randomize (usually a control-panel container)."),
+  params: z115.array(z115.string()).optional().describe("Specific custom-parameter names to randomize. Defaults to every numeric one."),
+  amount: z115.coerce.number().min(0).max(1).default(1).describe(
     "How far to move toward a random value in range: 1 = fully random, 0.2 = a gentle nudge from the current value. Lets you improvise without losing the current look."
   ),
-  seed: z113.coerce.number().int().optional().describe("Optional RNG seed for repeatable results.")
+  seed: z115.coerce.number().int().optional().describe("Optional RNG seed for repeatable results.")
 });
 var RANDOMIZE_SCRIPT = `
 import json, base64, traceback, random
@@ -18375,37 +19293,37 @@ async function randomizeControlsImpl(ctx, args) {
 }
 
 // src/tools/layer2/rebuildNetwork.ts
-import { z as z114 } from "zod";
-var ParamSpec = z114.object({
-  value: z114.unknown().optional().describe("Constant value for the parameter (used when mode is constant or omitted)."),
-  mode: z114.string().optional().describe(
+import { z as z116 } from "zod";
+var ParamSpec = z116.object({
+  value: z116.unknown().optional().describe("Constant value for the parameter (used when mode is constant or omitted)."),
+  mode: z116.string().optional().describe(
     "Parameter mode: 'EXPRESSION', 'BIND', or 'CONSTANT' (case-insensitive). Omit for a plain constant."
   ),
-  expr: z114.string().optional().describe(
+  expr: z116.string().optional().describe(
     "Expression or bind string, required when mode is EXPRESSION or BIND, e.g. 'me.time.seconds'."
   )
 });
-var NodeSpec = z114.object({
-  name: z114.string().describe("Name for the node inside the parent (TD may adjust it to avoid collisions)."),
-  type: z114.string().describe("Operator type to create, e.g. 'noiseTOP', 'levelTOP'."),
-  params: z114.record(z114.string(), ParamSpec).default({}).describe("Map of parameter name \u2192 { value | mode | expr } to apply after creation."),
-  inputs: z114.array(
-    z114.object({
-      from: z114.string().describe("Name of an earlier node in this spec to wire from."),
-      out_index: z114.number().int().default(0).describe("Output connector index on the source node (default 0)."),
-      in_index: z114.number().int().default(0).describe("Input connector index on this node (default 0).")
+var NodeSpec = z116.object({
+  name: z116.string().describe("Name for the node inside the parent (TD may adjust it to avoid collisions)."),
+  type: z116.string().describe("Operator type to create, e.g. 'noiseTOP', 'levelTOP'."),
+  params: z116.record(z116.string(), ParamSpec).default({}).describe("Map of parameter name \u2192 { value | mode | expr } to apply after creation."),
+  inputs: z116.array(
+    z116.object({
+      from: z116.string().describe("Name of an earlier node in this spec to wire from."),
+      out_index: z116.number().int().default(0).describe("Output connector index on the source node (default 0)."),
+      in_index: z116.number().int().default(0).describe("Input connector index on this node (default 0).")
     })
   ).default([]).describe("Inbound wires for this node, each referencing another node by `from` name."),
-  x: z114.number().optional().describe("Optional node X position (nodeX) in the network editor."),
-  y: z114.number().optional().describe("Optional node Y position (nodeY) in the network editor.")
+  x: z116.number().optional().describe("Optional node X position (nodeX) in the network editor."),
+  y: z116.number().optional().describe("Optional node Y position (nodeY) in the network editor.")
 });
-var rebuildNetworkSchema = z114.object({
-  parent_path: z114.string().describe("COMP to rebuild the network inside."),
-  spec: z114.object({
-    root: z114.string().optional().describe("Original root path the spec was serialized from (informational only)."),
-    nodes: z114.array(NodeSpec).describe("Nodes to create, parameterize, and wire, in order.")
+var rebuildNetworkSchema = z116.object({
+  parent_path: z116.string().describe("COMP to rebuild the network inside."),
+  spec: z116.object({
+    root: z116.string().optional().describe("Original root path the spec was serialized from (informational only)."),
+    nodes: z116.array(NodeSpec).describe("Nodes to create, parameterize, and wire, in order.")
   }).describe("A serialize_network spec to reconstruct."),
-  clear_existing: z114.boolean().default(false).describe("Delete existing children of parent_path first (destructive).")
+  clear_existing: z116.boolean().default(false).describe("Delete existing children of parent_path first (destructive).")
 });
 var REBUILD_SCRIPT = `
 import json, base64, traceback
@@ -18551,26 +19469,26 @@ async function rebuildNetworkImpl(ctx, args) {
 }
 
 // src/tools/layer2/scaffoldExtension.ts
-import { z as z115 } from "zod";
+import { z as z117 } from "zod";
 var PY_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var scaffoldExtensionSchema = z115.object({
-  comp_path: z115.string().describe("The COMP to give a Python extension class."),
-  class_name: z115.string().regex(
+var scaffoldExtensionSchema = z117.object({
+  comp_path: z117.string().describe("The COMP to give a Python extension class."),
+  class_name: z117.string().regex(
     PY_IDENTIFIER,
     "class_name must be a valid Python identifier (a letter or underscore, then letters/digits/underscores)."
   ).describe(
     "Extension class name, e.g. 'WidgetExt' (capitalized to a valid identifier; must already be identifier-safe)."
   ),
-  methods: z115.array(
-    z115.string().regex(
+  methods: z117.array(
+    z117.string().regex(
       PY_IDENTIFIER,
       "each method name must be a valid Python identifier (a letter or underscore, then letters/digits/underscores)."
     )
   ).optional().describe("Optional method-name stubs to add to the class (each takes only `self`)."),
-  promote: z115.boolean().default(true).describe(
+  promote: z117.boolean().default(true).describe(
     "Promote the extension so its members are callable directly on the COMP (op.Method())."
   ),
-  slot: z115.coerce.number().int().min(1).max(8).default(1).describe("Extension slot (1\u20138) \u2014 a COMP can hold several extensions.")
+  slot: z117.coerce.number().int().min(1).max(8).default(1).describe("Extension slot (1\u20138) \u2014 a COMP can hold several extensions.")
 });
 var PY_KEYWORDS = /* @__PURE__ */ new Set([
   "False",
@@ -18762,13 +19680,13 @@ async function scaffoldExtensionImpl(ctx, args) {
 }
 
 // src/tools/layer2/setParametersBatch.ts
-import { z as z116 } from "zod";
-var UpdateSchema = z116.object({
-  path: z116.string().describe("Path of the node whose parameters to update."),
-  parameters: z116.record(z116.string(), z116.unknown()).describe("Parameter values to set on that node, as a { parName: value } map.")
+import { z as z118 } from "zod";
+var UpdateSchema = z118.object({
+  path: z118.string().describe("Path of the node whose parameters to update."),
+  parameters: z118.record(z118.string(), z118.unknown()).describe("Parameter values to set on that node, as a { parName: value } map.")
 });
-var setParametersBatchSchema = z116.object({
-  updates: z116.array(UpdateSchema).min(1).describe(
+var setParametersBatchSchema = z118.object({
+  updates: z118.array(UpdateSchema).min(1).describe(
     "List of { path, parameters } updates sent in one batch request (per-update results; not transactional \u2014 a failed update does not roll back the others)."
   )
 });
@@ -18791,9 +19709,9 @@ async function setParametersBatchImpl(ctx, args) {
 }
 
 // src/tools/layer2/setPerformMode.ts
-import { z as z117 } from "zod";
-var setPerformModeSchema = z117.object({
-  enabled: z117.boolean().describe(
+import { z as z119 } from "zod";
+var setPerformModeSchema = z119.object({
+  enabled: z119.boolean().describe(
     "true to enter perform mode before a live show, false to leave it afterward. While perform mode is ON, tools that honor the advisory flag skip nonessential compute. The built-in guard currently suppresses auto preview captures; future tools can opt in by checking op('/').fetch('tdmcp_perform_mode', False) before doing expensive work. It does NOT stop the TD timeline or kill audio/video processing."
   )
 });
@@ -18846,42 +19764,42 @@ async function setPerformModeImpl(ctx, args) {
 }
 
 // src/tools/layer3/analyzeProject.ts
-import { z as z118 } from "zod";
-var analyzeProjectSchema = z118.object({
-  path: z118.string().default("/project1").describe("Network root to analyze (the COMP whose descendants are scanned)."),
-  recursive: z118.boolean().default(true).describe(
+import { z as z120 } from "zod";
+var analyzeProjectSchema = z120.object({
+  path: z120.string().default("/project1").describe("Network root to analyze (the COMP whose descendants are scanned)."),
+  recursive: z120.boolean().default(true).describe(
     "Recurse into child COMPs (true) or only inspect the root's direct children (false)."
   )
 });
-var analyzeProjectOutputSchema = z118.object({
-  path: z118.string(),
-  recursive: z118.boolean(),
-  counts: z118.object({
-    nodes: z118.number(),
-    by_family: z118.record(z118.string(), z118.number())
+var analyzeProjectOutputSchema = z120.object({
+  path: z120.string(),
+  recursive: z120.boolean(),
+  counts: z120.object({
+    nodes: z120.number(),
+    by_family: z120.record(z120.string(), z120.number())
   }),
-  unused: z118.array(
-    z118.object({
-      path: z118.string(),
-      type: z118.string(),
-      reason: z118.string()
+  unused: z120.array(
+    z120.object({
+      path: z120.string(),
+      type: z120.string(),
+      reason: z120.string()
     })
   ),
-  broken_file_deps: z118.array(
-    z118.object({
-      path: z118.string(),
-      par: z118.string(),
-      file: z118.string()
+  broken_file_deps: z120.array(
+    z120.object({
+      path: z120.string(),
+      par: z120.string(),
+      file: z120.string()
     })
   ),
-  orphan_comps: z118.array(
-    z118.object({
-      path: z118.string(),
-      reason: z118.string()
+  orphan_comps: z120.array(
+    z120.object({
+      path: z120.string(),
+      reason: z120.string()
     })
   ),
-  dependency_map: z118.record(z118.string(), z118.array(z118.string())),
-  warnings: z118.array(z118.string())
+  dependency_map: z120.record(z120.string(), z120.array(z120.string())),
+  warnings: z120.array(z120.string())
 });
 var ANALYZE_SCRIPT = `
 import json, base64, traceback, os, re
@@ -19130,28 +20048,28 @@ async function analyzeProjectImpl(ctx, args) {
 }
 
 // src/tools/layer3/compareTdNodes.ts
-import { z as z119 } from "zod";
-var compareTdNodesSchema = z119.object({
-  path_a: z119.string().describe("First node path."),
-  path_b: z119.string().describe("Second node path."),
-  only_diff: z119.boolean().default(true).describe("Return only the parameters that differ (true) or also list the identical ones.")
+import { z as z121 } from "zod";
+var compareTdNodesSchema = z121.object({
+  path_a: z121.string().describe("First node path."),
+  path_b: z121.string().describe("Second node path."),
+  only_diff: z121.boolean().default(true).describe("Return only the parameters that differ (true) or also list the identical ones.")
 });
-var compareTdNodesOutputSchema = z119.object({
-  a: z119.string().describe("Path of the first node compared."),
-  b: z119.string().describe("Path of the second node compared."),
-  type_a: z119.string().describe("Operator type of the first node."),
-  type_b: z119.string().describe("Operator type of the second node."),
-  type_match: z119.boolean().describe("True if both nodes are the same operator type."),
-  differing_count: z119.number().describe("Number of parameters whose values differ."),
-  same_count: z119.number().describe("Number of parameters that are identical on both nodes."),
-  differing: z119.array(
-    z119.object({
-      param: z119.string().describe("Name of the differing parameter."),
-      a: z119.unknown().describe("Its value on the first node."),
-      b: z119.unknown().describe("Its value on the second node.")
+var compareTdNodesOutputSchema = z121.object({
+  a: z121.string().describe("Path of the first node compared."),
+  b: z121.string().describe("Path of the second node compared."),
+  type_a: z121.string().describe("Operator type of the first node."),
+  type_b: z121.string().describe("Operator type of the second node."),
+  type_match: z121.boolean().describe("True if both nodes are the same operator type."),
+  differing_count: z121.number().describe("Number of parameters whose values differ."),
+  same_count: z121.number().describe("Number of parameters that are identical on both nodes."),
+  differing: z121.array(
+    z121.object({
+      param: z121.string().describe("Name of the differing parameter."),
+      a: z121.unknown().describe("Its value on the first node."),
+      b: z121.unknown().describe("Its value on the second node.")
     })
   ).describe("Every parameter that differs, with each node's value."),
-  identical: z119.array(z119.string()).optional().describe("Names of identical parameters; present only when only_diff is false.")
+  identical: z121.array(z121.string()).optional().describe("Names of identical parameters; present only when only_diff is false.")
 });
 async function compareTdNodesImpl(ctx, args) {
   return guardTd(
@@ -19192,12 +20110,12 @@ async function compareTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/createTdNode.ts
-import { z as z120 } from "zod";
-var createTdNodeSchema = z120.object({
-  parent_path: z120.string().default("/project1").describe("Parent COMP path to create the node inside."),
-  type: z120.string().describe("Operator type string, e.g. 'noiseTOP', 'feedbackTOP', 'nullTOP', 'constantCHOP'."),
-  name: z120.string().optional().describe("Optional node name (auto-generated if omitted)."),
-  parameters: z120.record(z120.string(), z120.unknown()).optional().describe("Optional initial parameter overrides as key\u2192value pairs.")
+import { z as z122 } from "zod";
+var createTdNodeSchema = z122.object({
+  parent_path: z122.string().default("/project1").describe("Parent COMP path to create the node inside."),
+  type: z122.string().describe("Operator type string, e.g. 'noiseTOP', 'feedbackTOP', 'nullTOP', 'constantCHOP'."),
+  name: z122.string().optional().describe("Optional node name (auto-generated if omitted)."),
+  parameters: z122.record(z122.string(), z122.unknown()).optional().describe("Optional initial parameter overrides as key\u2192value pairs.")
 });
 async function createTdNodeImpl(ctx, args) {
   const warnings = [];
@@ -19230,9 +20148,9 @@ async function createTdNodeImpl(ctx, args) {
 }
 
 // src/tools/layer3/deleteTdNode.ts
-import { z as z121 } from "zod";
-var deleteTdNodeSchema = z121.object({
-  path: z121.string().describe("Full path of the node to delete, e.g. '/project1/noise1'.")
+import { z as z123 } from "zod";
+var deleteTdNodeSchema = z123.object({
+  path: z123.string().describe("Full path of the node to delete, e.g. '/project1/noise1'.")
 });
 async function deleteTdNodeImpl(ctx, args) {
   return guardTd(
@@ -19242,23 +20160,23 @@ async function deleteTdNodeImpl(ctx, args) {
 }
 
 // src/tools/layer3/diffSnapshots.ts
-import { z as z122 } from "zod";
-var snapshotNodeSchema = z122.object({
-  path: z122.string(),
-  type: z122.string().optional(),
-  parameters: z122.record(z122.string(), z122.unknown()).optional()
+import { z as z124 } from "zod";
+var snapshotNodeSchema = z124.object({
+  path: z124.string(),
+  type: z124.string().optional(),
+  parameters: z124.record(z124.string(), z124.unknown()).optional()
 });
-var snapshotConnSchema = z122.object({
-  source_path: z122.string(),
-  source_output: z122.number().optional(),
-  target_path: z122.string(),
-  target_input: z122.number().optional()
+var snapshotConnSchema = z124.object({
+  source_path: z124.string(),
+  source_output: z124.number().optional(),
+  target_path: z124.string(),
+  target_input: z124.number().optional()
 });
-var snapshotSchema = z122.object({
-  nodes: z122.array(snapshotNodeSchema).default([]),
-  connections: z122.array(snapshotConnSchema).default([])
+var snapshotSchema = z124.object({
+  nodes: z124.array(snapshotNodeSchema).default([]),
+  connections: z124.array(snapshotConnSchema).default([])
 });
-var diffSnapshotsSchema = z122.object({
+var diffSnapshotsSchema = z124.object({
   before: snapshotSchema.describe(
     "Earlier snapshot (from snapshot_td_graph, include_params for param diffs)."
   ),
@@ -19302,13 +20220,13 @@ function diffSnapshotsImpl(_ctx, args) {
 }
 
 // src/tools/layer3/disconnectNodes.ts
-import { z as z123 } from "zod";
-var disconnectNodesSchema = z123.object({
-  to_path: z123.string().describe("The downstream node to remove input wire(s) from."),
-  from_path: z123.string().optional().describe(
+import { z as z125 } from "zod";
+var disconnectNodesSchema = z125.object({
+  to_path: z125.string().describe("The downstream node to remove input wire(s) from."),
+  from_path: z125.string().optional().describe(
     "Only remove wires coming from this upstream node. Omit to remove ALL input wires into to_path (scoped by to_input if given)."
   ),
-  to_input: z123.number().int().min(0).optional().describe("Only clear this input index on to_path (0-based). Omit to clear all inputs.")
+  to_input: z125.number().int().min(0).optional().describe("Only clear this input index on to_path (0-based). Omit to clear all inputs.")
 });
 var DISCONNECT_SCRIPT = `
 import json, base64, traceback
@@ -19401,6 +20319,12 @@ function buildDisconnectScript(payload) {
 async function disconnectNodesImpl(ctx, args) {
   return guardTd(
     async () => {
+      try {
+        const r2 = await ctx.client.disconnectNodes(args.to_path, args.from_path, args.to_input);
+        return { ...r2, probe: null };
+      } catch (err) {
+        if (!isMissingEndpoint(err)) throw err;
+      }
       const script = buildDisconnectScript({
         to_path: args.to_path,
         from_path: args.from_path ?? null,
@@ -19423,11 +20347,11 @@ async function disconnectNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/documentNetwork.ts
-import { z as z124 } from "zod";
+import { z as z126 } from "zod";
 var MAX_NODES = 150;
-var documentNetworkSchema = z124.object({
-  path: z124.string().default("/project1").describe("Network root to document."),
-  recursive: z124.boolean().default(false).describe("Include all descendants (otherwise just the direct children).")
+var documentNetworkSchema = z126.object({
+  path: z126.string().default("/project1").describe("Network root to document."),
+  recursive: z126.boolean().default(false).describe("Include all descendants (otherwise just the direct children).")
 });
 function family(type) {
   const m = /(TOP|CHOP|SOP|COMP|DAT|MAT|POP)$/.exec(type);
@@ -19480,12 +20404,71 @@ async function documentNetworkImpl(ctx, args) {
 }
 
 // src/tools/layer3/editDatContent.ts
-import { z as z125 } from "zod";
-var editDatContentSchema = z125.object({
-  dat_path: z125.string().describe("Absolute path to the Text or Table DAT to edit (e.g. '/project1/mytext1')."),
-  old_string: z125.string().min(1).describe("Exact substring to find. Must match at least once. Empty strings are rejected."),
-  new_string: z125.string().describe("Replacement text. May be empty to delete the matched substring."),
-  replace_all: z125.boolean().default(false).describe(
+import { z as z127 } from "zod";
+
+// src/tools/layer3/datTextReplace.ts
+function computeDatTextReplace(text, oldString, newString, replaceAll) {
+  if (oldString.length === 0) {
+    return {
+      occurrences: 0,
+      replacements: 0,
+      replaceAll,
+      error: "old_string must not be empty."
+    };
+  }
+  const occurrences = countOccurrences(text, oldString);
+  if (occurrences === 0) {
+    return {
+      occurrences,
+      replacements: 0,
+      replaceAll,
+      error: "old_string not found."
+    };
+  }
+  if (occurrences > 1 && !replaceAll) {
+    return {
+      occurrences,
+      replacements: 0,
+      replaceAll,
+      error: `old_string matches ${occurrences} times; pass replace_all:true to replace all, or add surrounding context for a unique match.`
+    };
+  }
+  if (replaceAll) {
+    return {
+      text: text.split(oldString).join(newString),
+      occurrences,
+      replacements: occurrences,
+      replaceAll
+    };
+  }
+  return {
+    text: replaceFirst(text, oldString, newString),
+    occurrences,
+    replacements: 1,
+    replaceAll
+  };
+}
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    count += 1;
+    index = haystack.indexOf(needle, index + needle.length);
+  }
+  return count;
+}
+function replaceFirst(haystack, needle, replacement) {
+  const index = haystack.indexOf(needle);
+  if (index === -1) return haystack;
+  return haystack.slice(0, index) + replacement + haystack.slice(index + needle.length);
+}
+
+// src/tools/layer3/editDatContent.ts
+var editDatContentSchema = z127.object({
+  dat_path: z127.string().describe("Absolute path to the Text or Table DAT to edit (e.g. '/project1/mytext1')."),
+  old_string: z127.string().min(1).describe("Exact substring to find. Must match at least once. Empty strings are rejected."),
+  new_string: z127.string().describe("Replacement text. May be empty to delete the matched substring."),
+  replace_all: z127.boolean().default(false).describe(
     "When false (default), requires exactly one match \u2014 0 or >1 occurrences is an error. Set true to replace every occurrence."
   )
 });
@@ -19527,6 +20510,35 @@ function buildEditDatContentScript(payload) {
 async function editDatContentImpl(ctx, args) {
   return guardTd(
     async () => {
+      try {
+        const cur = await ctx.client.getDatText(args.dat_path);
+        const res = computeDatTextReplace(
+          cur.text,
+          args.old_string,
+          args.new_string,
+          args.replace_all
+        );
+        if (res.error || res.text === void 0) {
+          return {
+            dat: args.dat_path,
+            occurrences: res.occurrences,
+            replacements: res.replacements,
+            replace_all: args.replace_all,
+            warnings: [],
+            fatal: res.error ?? "edit_dat_content: nothing to replace."
+          };
+        }
+        await ctx.client.putDatText(args.dat_path, res.text);
+        return {
+          dat: args.dat_path,
+          occurrences: res.occurrences,
+          replacements: res.replacements,
+          replace_all: args.replace_all,
+          warnings: []
+        };
+      } catch (err) {
+        if (!isMissingEndpoint(err)) throw err;
+      }
       const script = buildEditDatContentScript({
         dat: args.dat_path,
         old: args.old_string,
@@ -19547,12 +20559,12 @@ async function editDatContentImpl(ctx, args) {
 }
 
 // src/tools/layer3/execNodeMethod.ts
-import { z as z126 } from "zod";
-var execNodeMethodSchema = z126.object({
-  path: z126.string().describe("Full path of the node to call the method on."),
-  method: z126.string().describe("Method name to call, e.g. 'cook', 'par', 'destroy', 'copy'."),
-  args: z126.array(z126.unknown()).default([]).describe("Positional arguments."),
-  kwargs: z126.record(z126.string(), z126.unknown()).default({}).describe("Keyword arguments.")
+import { z as z128 } from "zod";
+var execNodeMethodSchema = z128.object({
+  path: z128.string().describe("Full path of the node to call the method on."),
+  method: z128.string().describe("Method name to call, e.g. 'cook', 'par', 'destroy', 'copy'."),
+  args: z128.array(z128.unknown()).default([]).describe("Positional arguments."),
+  kwargs: z128.record(z128.string(), z128.unknown()).default({}).describe("Keyword arguments.")
 });
 async function execNodeMethodImpl(ctx, args) {
   return guardTd(
@@ -19562,12 +20574,12 @@ async function execNodeMethodImpl(ctx, args) {
 }
 
 // src/tools/layer3/executePythonScript.ts
-import { z as z127 } from "zod";
-var executePythonScriptSchema = z127.object({
-  script: z127.string().min(1).describe(
+import { z as z129 } from "zod";
+var executePythonScriptSchema = z129.object({
+  script: z129.string().min(1).describe(
     "Python source to execute inside TouchDesigner (runs in the TD process, not locally)."
   ),
-  return_output: z127.boolean().default(true).describe("Capture stdout / the value of the last expression and return it.")
+  return_output: z129.boolean().default(true).describe("Capture stdout / the value of the last expression and return it.")
 });
 async function executePythonScriptImpl(ctx, args) {
   return guardTd(
@@ -19577,7 +20589,7 @@ async function executePythonScriptImpl(ctx, args) {
 }
 
 // src/tools/layer3/findTdNodes.ts
-import { z as z128 } from "zod";
+import { z as z130 } from "zod";
 
 // src/tools/layer3/nodeMatch.ts
 function globToRegExp(pattern) {
@@ -19590,21 +20602,21 @@ function parentOf2(path2) {
 }
 
 // src/tools/layer3/findTdNodes.ts
-var findTdNodesSchema = z128.object({
-  parent_path: z128.string().default("/project1").describe("Where to search from."),
-  pattern: z128.string().optional().describe("Case-insensitive name/path filter with '*' wildcards (e.g. 'text*', '*noise*')."),
-  type: z128.string().optional().describe("Case-insensitive operator-type substring (e.g. 'TOP', 'noise')."),
-  recursive: z128.boolean().default(true).describe("Search the whole sub-network (true) or only direct children (false)."),
-  path_only: z128.boolean().default(false).describe("Return only matching paths."),
-  limit: z128.number().int().positive().default(50).describe("Max matches to return.")
+var findTdNodesSchema = z130.object({
+  parent_path: z130.string().default("/project1").describe("Where to search from."),
+  pattern: z130.string().optional().describe("Case-insensitive name/path filter with '*' wildcards (e.g. 'text*', '*noise*')."),
+  type: z130.string().optional().describe("Case-insensitive operator-type substring (e.g. 'TOP', 'noise')."),
+  recursive: z130.boolean().default(true).describe("Search the whole sub-network (true) or only direct children (false)."),
+  path_only: z130.boolean().default(false).describe("Return only matching paths."),
+  limit: z130.number().int().positive().default(50).describe("Max matches to return.")
 });
-var findTdNodesOutputSchema = z128.object({
-  parent_path: z128.string().describe("The network root the search ran under."),
-  recursive: z128.boolean().describe("Whether descendants were searched, echoing the request."),
-  count: z128.number().describe("Total nodes matched before `limit` truncation."),
-  truncated: z128.boolean().describe("True if more nodes matched than `limit` returned."),
-  paths: z128.array(z128.string()).optional().describe("path_only mode: the matched node paths and nothing else."),
-  matches: z128.array(NodeRefSchema).optional().describe("Default mode: each matched node as {path, name, type}.")
+var findTdNodesOutputSchema = z130.object({
+  parent_path: z130.string().describe("The network root the search ran under."),
+  recursive: z130.boolean().describe("Whether descendants were searched, echoing the request."),
+  count: z130.number().describe("Total nodes matched before `limit` truncation."),
+  truncated: z130.boolean().describe("True if more nodes matched than `limit` returned."),
+  paths: z130.array(z130.string()).optional().describe("path_only mode: the matched node paths and nothing else."),
+  matches: z130.array(NodeRefSchema).optional().describe("Default mode: each matched node as {path, name, type}.")
 });
 async function findTdNodesImpl(ctx, args) {
   const fetch2 = args.recursive ? async () => (await ctx.client.getNetworkTopology(args.parent_path, true)).nodes : async () => (await ctx.client.getNodes(args.parent_path)).nodes;
@@ -19628,17 +20640,17 @@ async function findTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/generateReadme.ts
-import { z as z129 } from "zod";
-var generateReadmeOutputSchema = z129.object({
-  markdown: z129.string().describe("Full Markdown document."),
-  node_count: z129.number().describe("Total child nodes inspected."),
-  families: z129.record(z129.string(), z129.number()).describe("Node counts by operator family."),
-  has_preview: z129.boolean().describe("Whether a preview thumbnail was successfully embedded.")
+import { z as z131 } from "zod";
+var generateReadmeOutputSchema = z131.object({
+  markdown: z131.string().describe("Full Markdown document."),
+  node_count: z131.number().describe("Total child nodes inspected."),
+  families: z131.record(z131.string(), z131.number()).describe("Node counts by operator family."),
+  has_preview: z131.boolean().describe("Whether a preview thumbnail was successfully embedded.")
 });
-var generateReadmeSchema = z129.object({
-  path: z129.string().default("/project1").describe("Path of the project or COMP to document (e.g. /project1 or /project1/myComp)."),
-  title: z129.string().optional().describe("Document title. Defaults to the COMP name when omitted."),
-  include_preview: z129.boolean().default(true).describe("Capture and embed a preview thumbnail of the output TOP as a base64 inline image.")
+var generateReadmeSchema = z131.object({
+  path: z131.string().default("/project1").describe("Path of the project or COMP to document (e.g. /project1 or /project1/myComp)."),
+  title: z131.string().optional().describe("Document title. Defaults to the COMP name when omitted."),
+  include_preview: z131.boolean().default(true).describe("Capture and embed a preview thumbnail of the output TOP as a base64 inline image.")
 });
 var README_SCRIPT = `
 import json, base64, traceback
@@ -19883,29 +20895,29 @@ _Preview capture failed for \`${report.output_top}\`._
 }
 
 // src/tools/layer3/getBridgeLogs.ts
-import { z as z130 } from "zod";
-var getBridgeLogsSchema = z130.object({
-  scope: z130.string().default("/").describe(
+import { z as z132 } from "zod";
+var getBridgeLogsSchema = z132.object({
+  scope: z132.string().default("/").describe(
     "Network path to collect cook errors/warnings from (default whole project). Must be an existing operator path."
   ),
-  max_lines: z130.number().int().min(1).max(500).default(100).describe("Cap how many log lines to return (1\u2013500)."),
-  include_cook_errors: z130.boolean().default(true).describe("Include current operator cook errors/warnings across the scope.")
+  max_lines: z132.number().int().min(1).max(500).default(100).describe("Cap how many log lines to return (1\u2013500)."),
+  include_cook_errors: z132.boolean().default(true).describe("Include current operator cook errors/warnings across the scope.")
 });
-var getBridgeLogsOutputSchema = z130.object({
-  scope: z130.string().describe("The network path that was scanned, echoing the request."),
-  lines: z130.array(
-    z130.object({
-      source: z130.string().describe("Log source: 'cook' for cook errors/warnings, 'textport' for textport lines."),
-      level: z130.string().describe("Severity level: 'error' or 'warning'."),
-      text: z130.string().describe("The log message text."),
-      op: z130.string().optional().describe("Full operator path that produced this line (for cook sources).")
+var getBridgeLogsOutputSchema = z132.object({
+  scope: z132.string().describe("The network path that was scanned, echoing the request."),
+  lines: z132.array(
+    z132.object({
+      source: z132.string().describe("Log source: 'cook' for cook errors/warnings, 'textport' for textport lines."),
+      level: z132.string().describe("Severity level: 'error' or 'warning'."),
+      text: z132.string().describe("The log message text."),
+      op: z132.string().optional().describe("Full operator path that produced this line (for cook sources).")
     })
   ).describe("Collected log lines, newest-first within each source."),
-  count: z130.number().describe("Total number of lines returned (after capping at max_lines)."),
-  probe: z130.record(z130.string(), z130.unknown()).optional().describe(
+  count: z132.number().describe("Total number of lines returned (after capping at max_lines)."),
+  probe: z132.record(z132.string(), z132.unknown()).optional().describe(
     "Diagnostic info about which log sources were reachable in this TD build (cook_errors always present; textport availability varies by build)."
   ),
-  warnings: z130.array(z130.string()).describe("Non-fatal issues during collection (e.g. truncation notes).")
+  warnings: z132.array(z132.string()).describe("Non-fatal issues during collection (e.g. truncation notes).")
 });
 var GET_BRIDGE_LOGS_SCRIPT = `
 import json, base64, traceback
@@ -19935,14 +20947,20 @@ try:
                 )
             for _o in _all_ops:
                 try:
-                    for _msg in (_o.errors(recurse=False) or []):
+                    # op.errors()/op.warnings() return a STRING, not a list. Wrap
+                    # each in a single-element list so a (possibly multi-line)
+                    # message becomes exactly ONE log line \u2014 iterating the string
+                    # directly would emit one bogus line per character.
+                    _err = _o.errors(recurse=False)
+                    for _msg in ([str(_err)] if _err else []):
                         report["lines"].append({
                             "source": "cook",
                             "level": "error",
                             "text": str(_msg),
                             "op": _o.path,
                         })
-                    for _msg in (_o.warnings(recurse=False) or []):
+                    _warn = _o.warnings(recurse=False)
+                    for _msg in ([str(_warn)] if _warn else []):
                         report["lines"].append({
                             "source": "cook",
                             "level": "warning",
@@ -20016,6 +21034,30 @@ function buildGetBridgeLogsScript(payload) {
 async function getBridgeLogsImpl(ctx, args) {
   return guardTd(
     async () => {
+      if (args.include_cook_errors) {
+        try {
+          const logs = await ctx.client.getLogs("all", args.max_lines, args.scope);
+          if (logs.available) {
+            const lines = logs.lines.map((l) => ({
+              source: "cook",
+              level: (l.severity || "error").toLowerCase(),
+              text: l.message,
+              // Omit op when the Error-DAT row has a blank source — the schema makes
+              // it optional, and op:"" would force callers to special-case an empty path.
+              ...l.source ? { op: l.source } : {}
+            }));
+            return {
+              scope: args.scope,
+              lines,
+              count: lines.length,
+              probe: { endpoint: true, error_dat: logs.error_dat },
+              warnings: logs.warnings
+            };
+          }
+        } catch (err) {
+          if (!isMissingEndpoint(err)) throw err;
+        }
+      }
       const script = buildGetBridgeLogsScript({
         scope: args.scope,
         max_lines: args.max_lines,
@@ -20043,9 +21085,9 @@ async function getBridgeLogsImpl(ctx, args) {
 }
 
 // src/tools/layer3/getModuleHelp.ts
-import { z as z131 } from "zod";
-var getModuleHelpSchema = z131.object({
-  name: z131.string().describe("Class or module name to get help for, e.g. 'OP', 'App', 'Project'.")
+import { z as z133 } from "zod";
+var getModuleHelpSchema = z133.object({
+  name: z133.string().describe("Class or module name to get help for, e.g. 'OP', 'App', 'Project'.")
 });
 function getModuleHelpImpl(ctx, args) {
   const cls = ctx.knowledge.getPythonClass(args.name);
@@ -20074,26 +21116,26 @@ function getModuleHelpImpl(ctx, args) {
 }
 
 // src/tools/layer3/getNodeStateRuntime.ts
-import { z as z132 } from "zod";
-var getNodeStateRuntimeSchema = z132.object({
-  path: z132.string().describe("Full path of the operator to inspect (e.g. '/project1/noise1').")
+import { z as z134 } from "zod";
+var getNodeStateRuntimeSchema = z134.object({
+  path: z134.string().describe("Full path of the operator to inspect (e.g. '/project1/noise1').")
 });
-var getNodeStateRuntimeOutputSchema = z132.object({
-  path: z132.string().describe("Echoed operator path."),
-  type: z132.string().describe("Operator type string (e.g. 'noiseTOP')."),
-  family: z132.string().optional().describe("Operator family: TOP, CHOP, SOP, DAT, COMP, MAT, etc."),
-  cook_time_ms: z132.number().optional().describe("Last cook duration in milliseconds (op.cookTime * 1000). UNVERIFIED attr name."),
-  cook_count: z132.number().optional().describe(
+var getNodeStateRuntimeOutputSchema = z134.object({
+  path: z134.string().describe("Echoed operator path."),
+  type: z134.string().describe("Operator type string (e.g. 'noiseTOP')."),
+  family: z134.string().optional().describe("Operator family: TOP, CHOP, SOP, DAT, COMP, MAT, etc."),
+  cook_time_ms: z134.number().optional().describe("Last cook duration in milliseconds (op.cookTime * 1000). UNVERIFIED attr name."),
+  cook_count: z134.number().optional().describe(
     "Total number of times the op has cooked (op.totalCooks / op.cookCount). UNVERIFIED."
   ),
-  last_cook_frame: z132.number().optional().describe("Absolute frame number of the last cook (op.cookAbsFrame). UNVERIFIED attr name."),
-  resolution: z132.array(z132.number()).optional().describe("[width, height] for TOPs (op.width, op.height). UNVERIFIED."),
-  num_chans: z132.number().optional().describe("Number of channels for CHOPs (op.numChans). UNVERIFIED."),
-  num_samples: z132.number().optional().describe("Number of samples per channel for CHOPs (op.numSamples). UNVERIFIED."),
-  gpu_memory: z132.number().optional().describe("GPU memory used in bytes for TOPs (op.gpuMemory). UNVERIFIED attr name."),
-  errors: z132.array(z132.string()).describe("Cook errors from op.errors(recurse=False)."),
-  warnings: z132.array(z132.string()).describe("Bridge-level warnings about unreadable attributes."),
-  extra: z132.record(z132.string(), z132.unknown()).optional().describe(
+  last_cook_frame: z134.number().optional().describe("Absolute frame number of the last cook (op.cookAbsFrame). UNVERIFIED attr name."),
+  resolution: z134.array(z134.number()).optional().describe("[width, height] for TOPs (op.width, op.height). UNVERIFIED."),
+  num_chans: z134.number().optional().describe("Number of channels for CHOPs (op.numChans). UNVERIFIED."),
+  num_samples: z134.number().optional().describe("Number of samples per channel for CHOPs (op.numSamples). UNVERIFIED."),
+  gpu_memory: z134.number().optional().describe("GPU memory used in bytes for TOPs (op.gpuMemory). UNVERIFIED attr name."),
+  errors: z134.array(z134.string()).describe("Cook errors from op.errors(recurse=False)."),
+  warnings: z134.array(z134.string()).describe("Bridge-level warnings about unreadable attributes."),
+  extra: z134.record(z134.string(), z134.unknown()).optional().describe(
     "Additional Info attributes found via getattr probing \u2014 allows live-validation to confirm real attr names."
   )
 });
@@ -20267,9 +21309,9 @@ async function getNodeStateRuntimeImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdClassDetails.ts
-import { z as z133 } from "zod";
-var getTdClassDetailsSchema = z133.object({
-  class_name: z133.string().describe("Python class name, e.g. 'OP', 'TOP', 'App', 'CHOP'.")
+import { z as z135 } from "zod";
+var getTdClassDetailsSchema = z135.object({
+  class_name: z135.string().describe("Python class name, e.g. 'OP', 'TOP', 'App', 'CHOP'.")
 });
 function getTdClassDetailsImpl(ctx, args) {
   const cls = ctx.knowledge.getPythonClass(args.class_name);
@@ -20287,9 +21329,9 @@ function getTdClassDetailsImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdClasses.ts
-import { z as z134 } from "zod";
-var getTdClassesSchema = z134.object({
-  filter: z134.string().optional().describe("Optional case-insensitive substring to filter class names by.")
+import { z as z136 } from "zod";
+var getTdClassesSchema = z136.object({
+  filter: z136.string().optional().describe("Optional case-insensitive substring to filter class names by.")
 });
 function getTdClassesImpl(ctx, args) {
   let classes = ctx.knowledge.listPythonClasses();
@@ -20305,7 +21347,7 @@ function getTdClassesImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdInfo.ts
-var EXPECTED_BRIDGE_VERSION = "0.5.0";
+var EXPECTED_BRIDGE_VERSION = "0.6.1";
 async function getTdInfoImpl(ctx) {
   const knowledge = ctx.knowledge.stats();
   try {
@@ -20337,17 +21379,17 @@ async function getTdInfoImpl(ctx) {
 }
 
 // src/tools/layer3/getTdNodeErrors.ts
-import { z as z135 } from "zod";
-var getTdNodeErrorsSchema = z135.object({
-  path: z135.string().describe("Full path of the node (or network root) to check for errors."),
-  recursive: z135.boolean().default(false).describe("If true, check the whole network under `path`; otherwise just that node."),
-  summary: z135.boolean().default(false).describe("Return only counts grouped by error type instead of the full error list.")
+import { z as z137 } from "zod";
+var getTdNodeErrorsSchema = z137.object({
+  path: z137.string().describe("Full path of the node (or network root) to check for errors."),
+  recursive: z137.boolean().default(false).describe("If true, check the whole network under `path`; otherwise just that node."),
+  summary: z137.boolean().default(false).describe("Return only counts grouped by error type instead of the full error list.")
 });
-var getTdNodeErrorsOutputSchema = z135.object({
-  path: z135.string().describe("The node or network root that was checked, echoing the request."),
-  total: z135.number().describe("Total number of errors/warnings found (0 means clean)."),
-  errors: z135.array(NodeErrorSchema).optional().describe("Full mode: each error/warning with its node path, type and message."),
-  by_type: z135.record(z135.string(), z135.number()).optional().describe("summary mode: count of errors grouped by error type.")
+var getTdNodeErrorsOutputSchema = z137.object({
+  path: z137.string().describe("The node or network root that was checked, echoing the request."),
+  total: z137.number().describe("Total number of errors/warnings found (0 means clean)."),
+  errors: z137.array(NodeErrorSchema).optional().describe("Full mode: each error/warning with its node path, type and message."),
+  by_type: z137.record(z137.string(), z137.number()).optional().describe("summary mode: count of errors grouped by error type.")
 });
 async function getTdNodeErrorsImpl(ctx, args) {
   return guardTd(
@@ -20375,12 +21417,300 @@ async function getTdNodeErrorsImpl(ctx, args) {
   );
 }
 
+// src/tools/layer3/getTdNodeFlags.ts
+import { z as z138 } from "zod";
+var getTdNodeFlagsSchema = z138.object({
+  path: z138.string().describe(
+    "Full path of the node to inspect, or the COMP whose children to scan when recursive is set."
+  ),
+  recursive: z138.boolean().default(false).describe(
+    "Also scan the immediate children (depth 1) of path. Use this on a container to diagnose its whole network in one round-trip."
+  ),
+  only_problems: z138.boolean().default(false).describe(
+    "Return only nodes whose flags or cook errors would suppress output: bypass on, allowCooking off, or a cook error present. Conservative \u2014 display/render are reported but never used to filter (they default off on many visible ops)."
+  ),
+  max_nodes: z138.number().int().min(1).max(500).default(200).describe("Cap the number of nodes scanned during a recursive subtree walk.")
+});
+var nodeFlagsSchema = z138.object({
+  bypass: z138.boolean().optional(),
+  render: z138.boolean().optional(),
+  display: z138.boolean().optional(),
+  lock: z138.boolean().optional(),
+  allowCooking: z138.boolean().optional(),
+  cloneImmune: z138.boolean().optional(),
+  is_clone: z138.boolean().optional(),
+  clone: z138.string().nullable().optional()
+});
+var nodeWireSchema = z138.object({
+  in_index: z138.number().int().nullable(),
+  from: z138.string(),
+  out_index: z138.number().int()
+});
+var nodeFlagsEntrySchema = z138.object({
+  path: z138.string(),
+  type: z138.string(),
+  name: z138.string(),
+  flags: nodeFlagsSchema,
+  wires_in: z138.array(nodeWireSchema),
+  nodeX: z138.number().optional(),
+  nodeY: z138.number().optional(),
+  color: z138.array(z138.number()).optional(),
+  comment: z138.string().optional(),
+  errors: z138.array(z138.string()),
+  suspect_reason: z138.string().optional()
+});
+var getTdNodeFlagsOutputSchema = z138.object({
+  path: z138.string(),
+  scanned: z138.number().int(),
+  nodes: z138.array(nodeFlagsEntrySchema),
+  probe: z138.record(z138.string(), z138.unknown()).optional(),
+  warnings: z138.array(z138.string())
+});
+var GET_FLAGS_SCRIPT = `
+import json, base64, traceback
+_p = json.loads(base64.b64decode("__PAYLOAD_B64__").decode("utf-8"))
+report = {"path": _p["path"], "scanned": 0, "nodes": [], "warnings": []}
+
+def _flags(_o):
+    out = {}
+    for _attr in ("bypass", "render", "display", "lock", "allowCooking", "cloneImmune"):
+        try:
+            _v = getattr(_o, _attr)
+            if isinstance(_v, bool):
+                out[_attr] = _v
+        except Exception:
+            pass
+    # clone is COMP-only and lives on .par.clone (path to master), NOT op.clone.
+    try:
+        if hasattr(_o, "isClone"):
+            out["is_clone"] = bool(_o.isClone)
+    except Exception:
+        pass
+    try:
+        _cp = getattr(_o.par, "clone", None)
+        if _cp is not None:
+            _cv = _cp.eval()
+            out["clone"] = str(_cv) if _cv else None
+    except Exception:
+        pass
+    return out
+
+def _wires_in(_o):
+    # Faithful, index-aware: iterate inputConnectors (NOT _o.inputs, which omits
+    # empty slots). Each wire => {in_index, from, out_index}.
+    _wires = []
+    try:
+        for _ic in _o.inputConnectors:
+            try:
+                _in_index = _ic.index
+            except Exception:
+                _in_index = None
+            try:
+                _conns = list(_ic.connections)
+            except Exception:
+                _conns = []
+            for _oc in _conns:
+                try:
+                    _wires.append({"in_index": _in_index, "from": _oc.owner.path, "out_index": _oc.index})
+                except Exception:
+                    pass
+    except Exception:
+        pass
+    return _wires
+
+def _errors(_o):
+    # op.errors() returns a STRING, not a list \u2014 wrap it, never iterate it.
+    try:
+        _s = _o.errors(recurse=False)
+        if _s:
+            return [str(_s)]
+    except Exception:
+        pass
+    return []
+
+def _entry(_o, _only_problems):
+    _e = {
+        "path": _o.path,
+        "type": _o.type,
+        "name": _o.name,
+        "flags": _flags(_o),
+        "wires_in": _wires_in(_o),
+        "errors": _errors(_o),
+    }
+    try:
+        _e["nodeX"] = _o.nodeX
+        _e["nodeY"] = _o.nodeY
+    except Exception:
+        pass
+    try:
+        _e["color"] = list(_o.color)
+    except Exception:
+        pass
+    try:
+        if _o.comment:
+            _e["comment"] = _o.comment
+    except Exception:
+        pass
+    # Conservative suspect classification: only the unambiguous, high-signal cases.
+    _reasons = []
+    if _e["flags"].get("bypass") is True:
+        _reasons.append("bypass on")
+    if _e["flags"].get("allowCooking") is False:
+        _reasons.append("cooking disabled")
+    if _e["errors"]:
+        _reasons.append("cook error")
+    if _reasons:
+        _e["suspect_reason"] = ", ".join(_reasons)
+    return _e, bool(_reasons)
+
+try:
+    _root = op(_p["path"])
+    if _root is None:
+        report["fatal"] = "Node not found: " + str(_p["path"])
+    else:
+        _only = bool(_p.get("only_problems", False))
+        _recursive = bool(_p.get("recursive", False))
+        _max = int(_p.get("max_nodes", 200))
+        _targets = [_root]
+        if _recursive:
+            try:
+                _targets += list(_root.findChildren(depth=1))
+            except Exception as _fe:
+                report["warnings"].append("findChildren failed: " + str(_fe))
+        _first = True
+        for _o in _targets:
+            if report["scanned"] >= _max:
+                report["warnings"].append("max_nodes (" + str(_max) + ") reached; subtree scan truncated.")
+                break
+            report["scanned"] += 1
+            try:
+                # Probe the first node's available flags to confirm the real TD API.
+                if _first:
+                    _first = False
+                    try:
+                        report["probe"] = {
+                            "flags_present": sorted(_flags(_o).keys()),
+                            "has_inputConnectors": hasattr(_o, "inputConnectors"),
+                            "errors_is_str": isinstance(_o.errors(recurse=False), str),
+                        }
+                    except Exception:
+                        report["probe"] = {"error": traceback.format_exc().splitlines()[-1]}
+                _ent, _is_problem = _entry(_o, _only)
+                if _only and not _is_problem:
+                    continue
+                report["nodes"].append(_ent)
+            except Exception:
+                try:
+                    report["warnings"].append("Error reading " + str(_o.path) + ": " + traceback.format_exc().splitlines()[-1])
+                except Exception:
+                    report["warnings"].append("Error reading node: " + traceback.format_exc().splitlines()[-1])
+except Exception:
+    report["fatal"] = traceback.format_exc().splitlines()[-1]
+print(json.dumps(report))
+`;
+function buildGetFlagsScript(payload) {
+  return buildPayloadScript(GET_FLAGS_SCRIPT, payload);
+}
+function detailToFlagsEntry(d) {
+  const errors = d.errors ?? [];
+  const flags = d.flags ?? {};
+  const entry = {
+    path: d.path,
+    type: d.type,
+    name: d.name,
+    flags,
+    wires_in: d.wires_in ?? [],
+    errors
+  };
+  if (d.nodeX !== void 0) entry.nodeX = d.nodeX;
+  if (d.nodeY !== void 0) entry.nodeY = d.nodeY;
+  if (d.color !== void 0) entry.color = d.color;
+  if (d.comment) entry.comment = d.comment;
+  const reasons = [];
+  if (flags.bypass === true) reasons.push("bypass on");
+  if (flags.allowCooking === false) reasons.push("cooking disabled");
+  if (errors.length > 0) reasons.push("cook error");
+  if (reasons.length > 0) entry.suspect_reason = reasons.join(", ");
+  return entry;
+}
+async function getTdNodeFlagsImpl(ctx, args) {
+  return guardTd(
+    async () => {
+      try {
+        const root = await ctx.client.getNode(args.path);
+        if (root.flags !== void 0) {
+          const report = {
+            path: args.path,
+            scanned: 0,
+            nodes: [],
+            warnings: []
+          };
+          const details = [root];
+          if (args.recursive) {
+            try {
+              const list = await ctx.client.getNodes(args.path);
+              for (const child of list.nodes) {
+                if (details.length >= args.max_nodes) {
+                  report.warnings.push(
+                    `max_nodes (${args.max_nodes}) reached; subtree scan truncated.`
+                  );
+                  break;
+                }
+                try {
+                  details.push(await ctx.client.getNode(child.path));
+                } catch (childErr) {
+                  report.warnings.push(`Error reading ${child.path}: ${friendlyTdError(childErr)}`);
+                }
+              }
+            } catch (listErr) {
+              report.warnings.push(`findChildren failed: ${friendlyTdError(listErr)}`);
+            }
+          }
+          for (const d of details) {
+            report.scanned += 1;
+            const entry = detailToFlagsEntry(d);
+            if (args.only_problems && !entry.suspect_reason) continue;
+            report.nodes.push(entry);
+          }
+          report.probe = { endpoint: "node_detail", flags_present: Object.keys(root.flags).sort() };
+          return report;
+        }
+      } catch (err) {
+        if (!isMissingEndpoint(err)) throw err;
+      }
+      const script = buildGetFlagsScript({
+        path: args.path,
+        recursive: args.recursive,
+        only_problems: args.only_problems,
+        max_nodes: args.max_nodes
+      });
+      const exec = await ctx.client.executePythonScript(script, true);
+      return parsePythonReport(exec.stdout);
+    },
+    (report) => {
+      if (report.fatal) {
+        return errorResult(`get_td_node_flags failed: ${report.fatal}`, report);
+      }
+      const suspects = report.nodes.filter((n) => n.suspect_reason).length;
+      const scope = args.recursive ? " (subtree)" : "";
+      const summary = `Inspected ${report.scanned} node(s) under ${report.path}${scope} \u2014 ${report.nodes.length} reported, ${suspects} suspect.`;
+      return structuredResult(summary, {
+        path: report.path,
+        scanned: report.scanned,
+        nodes: report.nodes,
+        probe: report.probe,
+        warnings: report.warnings
+      });
+    }
+  );
+}
+
 // src/tools/layer3/getTdNodeParameters.ts
-import { z as z136 } from "zod";
-var getTdNodeParametersSchema = z136.object({
-  path: z136.string().describe("Full path of the node to inspect."),
-  keys: z136.array(z136.string()).optional().describe("Only return these parameter names (case-sensitive). Omit to return all parameters."),
-  omit_io: z136.boolean().default(false).describe("Drop the inputs/outputs lists from the result to save context.")
+import { z as z139 } from "zod";
+var getTdNodeParametersSchema = z139.object({
+  path: z139.string().describe("Full path of the node to inspect."),
+  keys: z139.array(z139.string()).optional().describe("Only return these parameter names (case-sensitive). Omit to return all parameters."),
+  omit_io: z139.boolean().default(false).describe("Drop the inputs/outputs lists from the result to save context.")
 });
 async function getTdNodeParametersImpl(ctx, args) {
   return guardTd(
@@ -20410,29 +21740,29 @@ async function getTdNodeParametersImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdNodes.ts
-import { z as z137 } from "zod";
-var getTdNodesSchema = z137.object({
-  parent_path: z137.string().default("/project1").describe("Parent COMP whose direct children should be listed."),
-  pattern: z137.string().optional().describe(
+import { z as z140 } from "zod";
+var getTdNodesSchema = z140.object({
+  parent_path: z140.string().default("/project1").describe("Parent COMP whose direct children should be listed."),
+  pattern: z140.string().optional().describe(
     "Case-insensitive filter on node name/path. Supports '*' wildcards (e.g. 'text*', '*noise*')."
   ),
-  path_only: z137.boolean().default(false).describe("Return only the list of node paths, dropping type/name."),
-  limit: z137.number().int().positive().optional().describe("Cap the number of nodes returned."),
-  detail_level: z137.enum(["summary", "full"]).default("summary").describe(
+  path_only: z140.boolean().default(false).describe("Return only the list of node paths, dropping type/name."),
+  limit: z140.number().int().positive().optional().describe("Cap the number of nodes returned."),
+  detail_level: z140.enum(["summary", "full"]).default("summary").describe(
     "'summary' (default) returns a count, a type breakdown and the first few paths; 'full' returns every node. Use 'full' (or path_only) when you need the complete list."
   )
 });
 var SAMPLE_SIZE = 10;
-var getTdNodesOutputSchema = z137.object({
-  parent_path: z137.string().describe("The parent COMP whose children were listed."),
-  count: z137.number().describe("Number of children matched (before any limit truncation)."),
-  detail_level: z137.enum(["summary", "full"]).describe("Which detail level produced this result, echoing the request."),
-  truncated: z137.boolean().describe("True if `limit` cut the list short of the full match count."),
-  by_type: z137.record(z137.string(), z137.number()).optional().describe("Summary mode: count of matched nodes per operator type."),
-  sample: z137.array(z137.string()).optional().describe("Summary mode: paths of the first few matched nodes."),
-  paths: z137.array(z137.string()).optional().describe("path_only mode: the matched node paths and nothing else."),
-  nodes: z137.array(NodeRefSchema).optional().describe("Full mode: every matched node as {path, name, type}."),
-  hint: z137.string().optional().describe("Summary mode: note that the list was sampled, with how to get all of it.")
+var getTdNodesOutputSchema = z140.object({
+  parent_path: z140.string().describe("The parent COMP whose children were listed."),
+  count: z140.number().describe("Number of children matched (before any limit truncation)."),
+  detail_level: z140.enum(["summary", "full"]).describe("Which detail level produced this result, echoing the request."),
+  truncated: z140.boolean().describe("True if `limit` cut the list short of the full match count."),
+  by_type: z140.record(z140.string(), z140.number()).optional().describe("Summary mode: count of matched nodes per operator type."),
+  sample: z140.array(z140.string()).optional().describe("Summary mode: paths of the first few matched nodes."),
+  paths: z140.array(z140.string()).optional().describe("path_only mode: the matched node paths and nothing else."),
+  nodes: z140.array(NodeRefSchema).optional().describe("Full mode: every matched node as {path, name, type}."),
+  hint: z140.string().optional().describe("Summary mode: note that the list was sampled, with how to get all of it.")
 });
 async function getTdNodesImpl(ctx, args) {
   return guardTd(
@@ -20487,7 +21817,7 @@ async function getTdNodesImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdPerformance.ts
-import { z as z138 } from "zod";
+import { z as z141 } from "zod";
 
 // src/feedback/performanceMonitor.ts
 async function checkPerformance(client, path2, targetFps = 60, recursive = true) {
@@ -20512,26 +21842,26 @@ async function checkPerformance(client, path2, targetFps = 60, recursive = true)
 }
 
 // src/tools/layer3/getTdPerformance.ts
-var getTdPerformanceSchema = z138.object({
-  root_path: z138.string().default("/project1").describe("Network root to measure cook times under."),
-  target_fps: z138.number().positive().default(60).describe("Frame-rate target used to flag slow nodes."),
-  recursive: z138.boolean().default(true).describe(
+var getTdPerformanceSchema = z141.object({
+  root_path: z141.string().default("/project1").describe("Network root to measure cook times under."),
+  target_fps: z141.number().positive().default(60).describe("Frame-rate target used to flag slow nodes."),
+  recursive: z141.boolean().default(true).describe(
     "Measure every descendant (true, default) so cook time inside generated containers is counted, not just the root's direct children."
   )
 });
-var getTdPerformanceOutputSchema = z138.object({
-  path: z138.string().describe("The network root that was measured, echoing the request."),
-  targetFps: z138.number().describe("The frame-rate target used to derive the per-frame budget."),
-  frameBudgetMs: z138.number().describe("Milliseconds available per frame at the target FPS (1000 / targetFps)."),
-  totalCookMs: z138.number().describe("Sum of the measured nodes' last cook times, in milliseconds."),
-  nodes: z138.array(
-    z138.object({
-      path: z138.string().describe("Path of the measured node."),
-      cook_time_ms: z138.number().describe("That node's last cook time in milliseconds."),
-      cook_count: z138.number().optional().describe("How many times the node has cooked, when reported by TD.")
+var getTdPerformanceOutputSchema = z141.object({
+  path: z141.string().describe("The network root that was measured, echoing the request."),
+  targetFps: z141.number().describe("The frame-rate target used to derive the per-frame budget."),
+  frameBudgetMs: z141.number().describe("Milliseconds available per frame at the target FPS (1000 / targetFps)."),
+  totalCookMs: z141.number().describe("Sum of the measured nodes' last cook times, in milliseconds."),
+  nodes: z141.array(
+    z141.object({
+      path: z141.string().describe("Path of the measured node."),
+      cook_time_ms: z141.number().describe("That node's last cook time in milliseconds."),
+      cook_count: z141.number().optional().describe("How many times the node has cooked, when reported by TD.")
     })
   ).describe("Per-node cook times, slowest first."),
-  warnings: z138.array(z138.string()).describe(
+  warnings: z141.array(z141.string()).describe(
     "Budget warnings: one line per node whose cook time exceeds the frame budget, plus a final aggregate line when the summed total cook time exceeds the budget. Empty when everything is within budget."
   )
 });
@@ -20546,7 +21876,7 @@ async function getTdPerformanceImpl(ctx, args) {
 }
 
 // src/tools/layer3/getTdTopology.ts
-import { z as z139 } from "zod";
+import { z as z142 } from "zod";
 
 // src/feedback/networkVerifier.ts
 async function verifyNetwork(client, path2) {
@@ -20567,14 +21897,14 @@ async function verifyNetwork(client, path2) {
 }
 
 // src/tools/layer3/getTdTopology.ts
-var getTdTopologySchema = z139.object({
-  root_path: z139.string().default("/project1").describe("Network root to map.")
+var getTdTopologySchema = z142.object({
+  root_path: z142.string().default("/project1").describe("Network root to map.")
 });
-var getTdTopologyOutputSchema = z139.object({
-  path: z139.string().describe("The network root that was mapped, echoing the request."),
-  nodeCount: z139.number().describe("Total number of nodes found under the root."),
-  connectionCount: z139.number().describe("Total number of wires (connections) between those nodes."),
-  issues: z139.array(z139.string()).describe("Plain-language structural problems detected, e.g. dangling or orphaned nodes."),
+var getTdTopologyOutputSchema = z142.object({
+  path: z142.string().describe("The network root that was mapped, echoing the request."),
+  nodeCount: z142.number().describe("Total number of nodes found under the root."),
+  connectionCount: z142.number().describe("Total number of wires (connections) between those nodes."),
+  issues: z142.array(z142.string()).describe("Plain-language structural problems detected, e.g. dangling or orphaned nodes."),
   topology: TopologySchema.describe("The full graph: the node list and the connection list.")
 });
 async function getTdTopologyImpl(ctx, args) {
@@ -20588,38 +21918,38 @@ async function getTdTopologyImpl(ctx, args) {
 }
 
 // src/tools/layer3/inspectComponent.ts
-import { z as z140 } from "zod";
-var inspectComponentSchema = z140.object({
-  path: z140.string().describe("COMP to inspect."),
-  include_storage: z140.boolean().default(true).describe("Include the COMP's Python storage dict (keys + JSON-able values)."),
-  include_extensions: z140.boolean().default(true).describe("Include extension classes + promoted members."),
-  include_custom_pars: z140.boolean().default(true).describe("Include custom-parameter definitions (page/name/style/default).")
+import { z as z143 } from "zod";
+var inspectComponentSchema = z143.object({
+  path: z143.string().describe("COMP to inspect."),
+  include_storage: z143.boolean().default(true).describe("Include the COMP's Python storage dict (keys + JSON-able values)."),
+  include_extensions: z143.boolean().default(true).describe("Include extension classes + promoted members."),
+  include_custom_pars: z143.boolean().default(true).describe("Include custom-parameter definitions (page/name/style/default).")
 });
-var inspectComponentOutputSchema = z140.object({
-  path: z140.string().describe("Full path of the inspected COMP."),
-  type: z140.string().describe("Operator type of the COMP (e.g. 'baseCOMP')."),
-  storage: z140.record(z140.string(), z140.unknown()).optional().describe(
+var inspectComponentOutputSchema = z143.object({
+  path: z143.string().describe("Full path of the inspected COMP."),
+  type: z143.string().describe("Operator type of the COMP (e.g. 'baseCOMP')."),
+  storage: z143.record(z143.string(), z143.unknown()).optional().describe(
     "Python storage dict \u2014 keys and their JSON-serializable values (non-serializable values are stringified)."
   ),
-  extensions: z140.array(
-    z140.object({
-      name: z140.string().describe("Extension class name as registered on the COMP."),
-      promoted: z140.boolean().describe("Whether the extension's members are promoted onto the COMP."),
-      members: z140.array(z140.string()).describe("Public (non-dunder) member names on the extension object (capped at 50).")
+  extensions: z143.array(
+    z143.object({
+      name: z143.string().describe("Extension class name as registered on the COMP."),
+      promoted: z143.boolean().describe("Whether the extension's members are promoted onto the COMP."),
+      members: z143.array(z143.string()).describe("Public (non-dunder) member names on the extension object (capped at 50).")
     })
   ).optional().describe("Extension class descriptors attached to the COMP."),
-  custom_pars: z140.array(
-    z140.object({
-      page: z140.string().describe("Custom-parameter page name."),
-      name: z140.string().describe("Parameter name."),
-      style: z140.string().describe("Parameter style / widget type (e.g. 'Float', 'Toggle', 'Menu')."),
-      default: z140.unknown().optional().describe("Default value, if readable.")
+  custom_pars: z143.array(
+    z143.object({
+      page: z143.string().describe("Custom-parameter page name."),
+      name: z143.string().describe("Parameter name."),
+      style: z143.string().describe("Parameter style / widget type (e.g. 'Float', 'Toggle', 'Menu')."),
+      default: z143.unknown().optional().describe("Default value, if readable.")
     })
   ).optional().describe("Custom-parameter definitions on the COMP, across all custom pages."),
-  probe: z140.record(z140.string(), z140.unknown()).optional().describe(
+  probe: z143.record(z143.string(), z143.unknown()).optional().describe(
     "API-reachability map from the bridge \u2014 records which storage/extension/custom-par APIs were available on this TD build. UNVERIFIED: exact attribute names vary by build."
   ),
-  warnings: z140.array(z140.string()).describe("Per-item problems that did not abort the inspection.")
+  warnings: z143.array(z143.string()).describe("Per-item problems that did not abort the inspection.")
 });
 var INSPECT_SCRIPT = `
 import json, base64, traceback
@@ -20845,14 +22175,14 @@ async function inspectComponentImpl(ctx, args) {
 }
 
 // src/tools/layer3/optimizePerformance.ts
-import { z as z141 } from "zod";
-var optimizePerformanceSchema = z141.object({
-  path: z141.string().default("/project1").describe("Network to analyze (recursively)."),
-  threshold_ms: z141.coerce.number().positive().default(2).describe("Flag nodes whose last cook took at least this many milliseconds."),
-  apply: z141.boolean().default(false).describe(
+import { z as z144 } from "zod";
+var optimizePerformanceSchema = z144.object({
+  path: z144.string().default("/project1").describe("Network to analyze (recursively)."),
+  threshold_ms: z144.coerce.number().positive().default(2).describe("Flag nodes whose last cook took at least this many milliseconds."),
+  apply: z144.boolean().default(false).describe(
     "If true, actually lower the resolution of the flagged TOPs by `scale`. Default false = just report the bottlenecks and suggestions."
   ),
-  scale: z141.coerce.number().min(0.1).max(1).default(0.5).describe("(apply) Resolution multiplier for flagged TOPs (0.5 = half on each axis).")
+  scale: z144.coerce.number().min(0.1).max(1).default(0.5).describe("(apply) Resolution multiplier for flagged TOPs (0.5 = half on each axis).")
 });
 var OPTIMIZE_SCRIPT = `
 import json, base64, traceback
@@ -20932,32 +22262,32 @@ async function optimizePerformanceImpl(ctx, args) {
 }
 
 // src/tools/layer3/readParameterModes.ts
-import { z as z142 } from "zod";
-var readParameterModesSchema = z142.object({
-  path: z142.string().describe("Full path of the node whose parameters to inspect."),
-  keys: z142.array(z142.string()).optional().describe("Only report these parameter names (case-sensitive). Omit for all parameters."),
-  non_default_only: z142.boolean().default(false).describe(
+import { z as z145 } from "zod";
+var readParameterModesSchema = z145.object({
+  path: z145.string().describe("Full path of the node whose parameters to inspect."),
+  keys: z145.array(z145.string()).optional().describe("Only report these parameter names (case-sensitive). Omit for all parameters."),
+  non_default_only: z145.boolean().default(false).describe(
     "Only return parameters whose mode is not plain constant (i.e. expression/export/bind) \u2014 the ones that matter for a faithful round-trip."
   )
 });
-var parameterModeInfoSchema = z142.object({
-  name: z142.string(),
-  value: z142.unknown().optional(),
-  mode: z142.string(),
-  expr: z142.string().optional(),
-  bind_expr: z142.string().optional(),
-  export_op: z142.string().optional(),
-  expression: z142.string().optional(),
-  bind_expression: z142.string().optional(),
-  export_source: z142.string().optional()
+var parameterModeInfoSchema = z145.object({
+  name: z145.string(),
+  value: z145.unknown().optional(),
+  mode: z145.string(),
+  expr: z145.string().optional(),
+  bind_expr: z145.string().optional(),
+  export_op: z145.string().optional(),
+  expression: z145.string().optional(),
+  bind_expression: z145.string().optional(),
+  export_source: z145.string().optional()
 });
-var readParameterModesOutputSchema = z142.object({
-  path: z142.string(),
-  type: z142.string(),
-  name: z142.string(),
-  parameters: z142.array(parameterModeInfoSchema),
-  probe: z142.record(z142.string(), z142.unknown()).optional(),
-  warnings: z142.array(z142.string())
+var readParameterModesOutputSchema = z145.object({
+  path: z145.string(),
+  type: z145.string(),
+  name: z145.string(),
+  parameters: z145.array(parameterModeInfoSchema),
+  probe: z145.record(z145.string(), z145.unknown()).optional(),
+  warnings: z145.array(z145.string())
 });
 var READ_PARAMETER_MODES_SCRIPT = `
 import json, base64, math, traceback
@@ -21068,6 +22398,18 @@ function buildReadParameterModesScript(payload) {
 async function readParameterModesImpl(ctx, args) {
   return guardTd(
     async () => {
+      try {
+        const r2 = await ctx.client.readParameterModes(args.path, args.keys, args.non_default_only);
+        return {
+          path: r2.path,
+          type: r2.type,
+          name: r2.name,
+          parameters: r2.parameters,
+          warnings: r2.warnings
+        };
+      } catch (err) {
+        if (!isMissingEndpoint(err)) throw err;
+      }
       const script = buildReadParameterModesScript({
         path: args.path,
         keys: args.keys ?? null,
@@ -21095,15 +22437,15 @@ async function readParameterModesImpl(ctx, args) {
 }
 
 // src/tools/layer3/recordMovie.ts
-import { z as z143 } from "zod";
-var recordMovieSchema = z143.object({
-  action: z143.enum(["start", "stop"]).default("start").describe("start recording the TOP to a file, or stop the current recording."),
-  node_path: z143.string().describe("Path of the TOP to record."),
-  file: z143.string().optional().describe(
+import { z as z146 } from "zod";
+var recordMovieSchema = z146.object({
+  action: z146.enum(["start", "stop"]).default("start").describe("start recording the TOP to a file, or stop the current recording."),
+  node_path: z146.string().describe("Path of the TOP to record."),
+  file: z146.string().optional().describe(
     "(start) Output movie path on the TD machine, with a .mov or .mp4 extension. Absolute path recommended."
   ),
-  fps: z143.coerce.number().positive().default(30).describe("(start) Frames per second."),
-  seconds: z143.coerce.number().positive().optional().describe(
+  fps: z146.coerce.number().positive().default(30).describe("(start) Frames per second."),
+  seconds: z146.coerce.number().positive().optional().describe(
     "(start) If set, auto-stop after this many seconds (records a fixed-length loop); otherwise record until you call stop."
   )
 });
@@ -21211,8 +22553,8 @@ async function recordMovieImpl(ctx, args) {
 }
 
 // src/tools/layer3/reloadBridge.ts
-import { z as z144 } from "zod";
-var reloadBridgeSchema = z144.object({});
+import { z as z147 } from "zod";
+var reloadBridgeSchema = z147.object({});
 var RELOAD_SCRIPT = `
 import json
 from mcp import dev
@@ -21233,10 +22575,10 @@ async function reloadBridgeImpl(ctx) {
 }
 
 // src/tools/layer3/renderOutput.ts
-import { z as z145 } from "zod";
-var renderOutputSchema = z145.object({
-  node_path: z145.string().describe("Path of the TOP to render to a file."),
-  file: z145.string().describe(
+import { z as z148 } from "zod";
+var renderOutputSchema = z148.object({
+  node_path: z148.string().describe("Path of the TOP to render to a file."),
+  file: z148.string().describe(
     "Output file path (written by TouchDesigner, so on the TD machine). Extension picks the format: .png/.jpg/.exr/.tiff. Use an absolute path."
   )
 });
@@ -21276,7 +22618,7 @@ async function renderOutputImpl(ctx, args) {
 }
 
 // src/tools/layer3/searchOperators.ts
-import { z as z146 } from "zod";
+import { z as z149 } from "zod";
 
 // src/knowledge/embeddings.ts
 async function embedTexts(texts, config, timeoutMs = 2e4) {
@@ -21360,12 +22702,12 @@ function cosineSimilarity(a, b) {
 }
 
 // src/tools/layer3/searchOperators.ts
-var searchOperatorsSchema = z146.object({
-  query: z146.string().min(1).describe(
+var searchOperatorsSchema = z149.object({
+  query: z149.string().min(1).describe(
     "What you're looking for \u2014 words from a name, family, or description (e.g. 'blur edge', 'audio spectrum', 'instance geometry')."
   ),
-  limit: z146.coerce.number().int().positive().max(100).default(20).describe("Max results to return."),
-  semantic: z146.boolean().default(false).describe(
+  limit: z149.coerce.number().int().positive().max(100).default(20).describe("Max results to return."),
+  semantic: z149.boolean().default(false).describe(
     "Opt-in: re-rank keyword candidates by embedding similarity via the configured LLM endpoint (TDMCP_LLM_BASE_URL / _MODEL, Ollama by default). Better for fuzzy/conceptual queries. Falls back to keyword ranking if the endpoint is unavailable \u2014 the default (false) needs nothing."
   )
 });
@@ -21401,44 +22743,49 @@ async function searchOperatorsImpl(ctx, args) {
 }
 
 // src/tools/layer3/serializeNetwork.ts
-import { z as z147 } from "zod";
-var serializeNetworkSchema = z147.object({
-  path: z147.string().describe("Root COMP whose children to serialize into a diffable spec."),
-  max_nodes: z147.number().int().min(1).max(500).default(200).describe("Cap nodes serialized."),
-  include_custom_params: z147.boolean().default(true).describe("Include custom-parameter definitions (best-effort).")
+import { z as z150 } from "zod";
+var serializeNetworkSchema = z150.object({
+  path: z150.string().describe("Root COMP whose children to serialize into a diffable spec."),
+  max_nodes: z150.number().int().min(1).max(500).default(200).describe("Cap nodes serialized."),
+  include_custom_params: z150.boolean().default(true).describe("Include custom-parameter definitions (best-effort).")
 });
-var SerializedParamSchema = z147.object({
-  value: z147.unknown().optional().describe("Evaluated parameter value."),
-  mode: z147.string().optional().describe("Parameter mode (CONSTANT / EXPRESSION / EXPORT / BIND), normalized."),
-  expr: z147.string().optional().describe("Raw expression string when the mode is EXPRESSION.")
+var SerializedParamSchema = z150.object({
+  value: z150.unknown().optional().describe("Evaluated parameter value."),
+  mode: z150.string().optional().describe("Parameter mode (CONSTANT / EXPRESSION / EXPORT / BIND), normalized."),
+  expr: z150.string().optional().describe("Raw expression string when the mode is EXPRESSION.")
 });
-var SerializedInputSchema = z147.object({
-  from: z147.string().describe("Source node NAME (within root) feeding this input."),
-  out_index: z147.number().describe("Output connector index on the source node."),
-  in_index: z147.number().describe("Input connector index on this node.")
+var SerializedInputSchema = z150.object({
+  from: z150.string().describe("Source node NAME (within root) feeding this input."),
+  out_index: z150.number().describe("Output connector index on the source node."),
+  in_index: z150.number().describe("Input connector index on this node.")
 });
-var SerializedCustomParSchema = z147.object({
-  name: z147.string().describe("Custom parameter name."),
-  page: z147.string().optional().describe("Parameter page the knob lives on."),
-  style: z147.string().optional().describe("Parameter style (Float, Int, Toggle, Menu, \u2026)."),
-  default: z147.unknown().optional().describe("Default value, best-effort (UNVERIFIED shape).")
+var SerializedCustomParSchema = z150.object({
+  name: z150.string().describe("Custom parameter name."),
+  page: z150.string().optional().describe("Parameter page the knob lives on."),
+  style: z150.string().optional().describe("Parameter style (Float, Int, Toggle, Menu, \u2026)."),
+  default: z150.unknown().optional().describe("Default value, best-effort (UNVERIFIED shape).")
 });
-var SerializedNodeSchema = z147.object({
-  name: z147.string().describe("Node name (unique within root)."),
-  type: z147.string().describe('TD op type, e.g. "noiseTOP".'),
-  params: z147.record(z147.string(), SerializedParamSchema).describe("Non-default / interesting params keyed by parameter name."),
-  inputs: z147.array(SerializedInputSchema).describe("Input wires, by source node NAME."),
-  x: z147.number().optional().describe("Node X position (cosmetic)."),
-  y: z147.number().optional().describe("Node Y position (cosmetic)."),
-  custom_params: z147.array(SerializedCustomParSchema).optional().describe(
+var SerializedNodeSchema = z150.object({
+  name: z150.string().describe("Node name (unique within root)."),
+  type: z150.string().describe('TD op type, e.g. "noiseTOP".'),
+  params: z150.record(z150.string(), SerializedParamSchema).describe("Non-default / interesting params keyed by parameter name."),
+  inputs: z150.array(SerializedInputSchema).describe("Input wires, by source node NAME."),
+  x: z150.number().optional().describe("Node X position (cosmetic)."),
+  y: z150.number().optional().describe("Node Y position (cosmetic)."),
+  flags: z150.record(z150.string(), z150.boolean()).optional().describe(
+    "Operator flags (bypass/render/display/lock/allowCooking) \u2014 inspection/diff metadata; rebuild_network does not restore these."
+  ),
+  comment: z150.string().optional().describe("Node comment (cosmetic)."),
+  color: z150.array(z150.number()).optional().describe("Node color RGB (cosmetic)."),
+  custom_params: z150.array(SerializedCustomParSchema).optional().describe(
     "Custom-parameter definitions so rebuild can recreate knobs (best-effort, UNVERIFIED)."
   )
 });
-var serializeNetworkOutputSchema = z147.object({
-  root: z147.string().describe("The serialized root path."),
-  nodes: z147.array(SerializedNodeSchema).describe("Every serialized child node of the root."),
-  truncated: z147.boolean().optional().describe("True when the child count exceeded max_nodes and the spec was capped."),
-  warnings: z147.array(z147.string()).describe("Per-item problems collected without failing the read.")
+var serializeNetworkOutputSchema = z150.object({
+  root: z150.string().describe("The serialized root path."),
+  nodes: z150.array(SerializedNodeSchema).describe("Every serialized child node of the root."),
+  truncated: z150.boolean().optional().describe("True when the child count exceeded max_nodes and the spec was capped."),
+  warnings: z150.array(z150.string()).describe("Per-item problems collected without failing the read.")
 });
 var SERIALIZE_NETWORK_SCRIPT = `
 import json, base64, traceback
@@ -21491,6 +22838,26 @@ try:
                 _node["y"] = _o.nodeY
             except Exception:
                 pass
+            # Flags (cosmetic + behavioral) \u2014 inspection/diff metadata; rebuild_network does not restore these.
+            _flags = {}
+            for _fa in ("bypass", "render", "display", "lock", "allowCooking"):
+                try:
+                    _fv = getattr(_o, _fa)
+                    if isinstance(_fv, bool):
+                        _flags[_fa] = _fv
+                except Exception:
+                    pass
+            if _flags:
+                _node["flags"] = _flags
+            try:
+                if _o.comment:
+                    _node["comment"] = _o.comment
+            except Exception:
+                pass
+            try:
+                _node["color"] = list(_o.color)
+            except Exception:
+                pass
             # Parameters: value + normalized mode + raw expression, defensively per attribute.
             try:
                 _pars = _o.pars()
@@ -21628,15 +22995,15 @@ async function serializeNetworkImpl(ctx, args) {
 }
 
 // src/tools/layer3/setDatContent.ts
-import { z as z148 } from "zod";
-var setDatContentSchema = z148.object({
-  dat_path: z148.string().describe(
+import { z as z151 } from "zod";
+var setDatContentSchema = z151.object({
+  dat_path: z151.string().describe(
     "Absolute path to the Text or Table DAT whose content will be fully replaced (e.g. '/project1/mytext1')."
   ),
-  text: z148.string().describe(
+  text: z151.string().describe(
     "The full new contents of the DAT. Every existing character will be discarded; this string becomes the entire `.text` value."
   ),
-  confirm_wipe: z148.boolean().default(false).describe(
+  confirm_wipe: z151.boolean().default(false).describe(
     "Set true to allow writing empty or whitespace-only text, which clears the DAT. When false (default), the tool refuses to write blank content to prevent silent data loss."
   )
 });
@@ -21670,6 +23037,18 @@ async function setDatContentImpl(ctx, args) {
   }
   return guardTd(
     async () => {
+      try {
+        const w = await ctx.client.putDatText(args.dat_path, args.text);
+        return {
+          dat: args.dat_path,
+          old_length: w.old_length,
+          new_length: w.new_length,
+          wiped: args.text.trim() === "",
+          warnings: []
+        };
+      } catch (err) {
+        if (!isMissingEndpoint(err)) throw err;
+      }
       const script = buildSetDatContentScript({ dat: args.dat_path, text: args.text });
       const exec = await ctx.client.executePythonScript(script, true);
       return parsePythonReport(exec.stdout);
@@ -21686,19 +23065,19 @@ async function setDatContentImpl(ctx, args) {
 }
 
 // src/tools/layer3/setParameterExpression.ts
-import { z as z149 } from "zod";
-var setParameterExpressionSchema = z149.object({
-  path: z149.string().describe("Full path of the node whose parameters to set."),
-  assignments: z149.array(
-    z149.object({
-      param: z149.string().describe("Parameter name (case-sensitive), e.g. 'tx'."),
-      mode: z149.enum(["expression", "bind", "constant"]).default("expression").describe(
+import { z as z152 } from "zod";
+var setParameterExpressionSchema = z152.object({
+  path: z152.string().describe("Full path of the node whose parameters to set."),
+  assignments: z152.array(
+    z152.object({
+      param: z152.string().describe("Parameter name (case-sensitive), e.g. 'tx'."),
+      mode: z152.enum(["expression", "bind", "constant"]).default("expression").describe(
         "expression: set par.expr; bind: set par.bindExpr; constant: set par.val from `value`."
       ),
-      expr: z149.string().optional().describe(
+      expr: z152.string().optional().describe(
         `The expression or bind string (required for mode expression/bind), e.g. 'me.time.seconds' or 'op("audio")["level"]'.`
       ),
-      value: z149.union([z149.number(), z149.string(), z149.boolean()]).optional().describe("Constant value (for mode 'constant').")
+      value: z152.union([z152.number(), z152.string(), z152.boolean()]).optional().describe("Constant value (for mode 'constant').")
     })
   ).min(1).describe("One or more parameter assignments.")
 });
@@ -21738,9 +23117,9 @@ try:
                         continue
                     _par.expr = _e
                     try:
-                        _par.mode = ParMode.EXPRESSION
+                        _par.mode = type(_par.mode).EXPRESSION
                     except Exception:
-                        report["warnings"].append("ParMode enum unavailable; set raw attribute only")
+                        report["warnings"].append("param '" + str(_a["param"]) + "': could not flip to Expression mode")
                 elif _m == "bind":
                     _e = _a.get("expr")
                     if not _e:
@@ -21748,9 +23127,9 @@ try:
                         continue
                     _par.bindExpr = _e
                     try:
-                        _par.mode = ParMode.BIND
+                        _par.mode = type(_par.mode).BIND
                     except Exception:
-                        report["warnings"].append("ParMode enum unavailable; set raw attribute only")
+                        report["warnings"].append("param '" + str(_a["param"]) + "': could not flip to Bind mode")
                 else:
                     _v = _a.get("value")
                     if _v is None:
@@ -21758,7 +23137,7 @@ try:
                         continue
                     _par.val = _v
                     try:
-                        _par.mode = ParMode.CONSTANT
+                        _par.mode = type(_par.mode).CONSTANT
                     except Exception:
                         pass
                 report["applied"].append({
@@ -21779,6 +23158,46 @@ function buildSetExprScript(payload) {
 async function setParameterExpressionImpl(ctx, args) {
   return guardTd(
     async () => {
+      const applied = [];
+      const warnings = [];
+      let endpointUsable = true;
+      let endpointProven = false;
+      for (let i = 0; i < args.assignments.length; i++) {
+        const a = args.assignments[i];
+        if (!a) continue;
+        if ((a.mode === "expression" || a.mode === "bind") && !a.expr) {
+          warnings.push(`param '${a.param}': expr required for mode '${a.mode}'`);
+          continue;
+        }
+        if (a.mode === "constant" && a.value === void 0) {
+          warnings.push(`param '${a.param}': value required for mode 'constant'`);
+          continue;
+        }
+        try {
+          const r2 = await ctx.client.setParameterMode(args.path, a.param, a.mode, a.expr, a.value);
+          endpointProven = true;
+          applied.push({
+            param: r2.param,
+            mode: a.mode,
+            readback_mode: r2.readback_mode,
+            readback_expr: r2.readback_expr
+          });
+        } catch (err) {
+          if (!endpointProven && isMissingEndpoint(err)) {
+            endpointUsable = false;
+            break;
+          }
+          if (err instanceof TdApiError) {
+            endpointProven = true;
+            warnings.push(`param '${a.param}': ${err.message}`);
+            continue;
+          }
+          throw err;
+        }
+      }
+      if (endpointUsable) {
+        return { path: args.path, applied, warnings };
+      }
       const script = buildSetExprScript({
         path: args.path,
         assignments: args.assignments
@@ -21802,53 +23221,53 @@ async function setParameterExpressionImpl(ctx, args) {
 }
 
 // src/tools/layer3/snapshotTdGraph.ts
-import { z as z150 } from "zod";
+import { z as z153 } from "zod";
 var MAX_PARAM_NODES = 60;
-var snapshotTdGraphSchema = z150.object({
-  path: z150.string().default("/project1").describe("Network root to snapshot."),
-  include_params: z150.boolean().default(false).describe("Also fetch each node's parameters (one request per node; capped for large graphs)."),
-  compact: z150.boolean().default(false).describe(
+var snapshotTdGraphSchema = z153.object({
+  path: z153.string().default("/project1").describe("Network root to snapshot."),
+  include_params: z153.boolean().default(false).describe("Also fetch each node's parameters (one request per node; capped for large graphs)."),
+  compact: z153.boolean().default(false).describe(
     "Token-cheap whole-COMP read: hoist each operator type's most-common parameter values into a shared `typeDefaults` map and store only each node's *deltas* from them (Embody-style read_tdn). Implies fetching parameters. Use for feeding a large network to an agent without paying for repeated identical values."
   ),
-  include_parameter_modes: z150.boolean().default(false).describe(
+  include_parameter_modes: z153.boolean().default(false).describe(
     "Also preserve TouchDesigner parameter modes/expressions/binds where available. Compact mode implies this so reactive expressions are not flattened to their current value."
   )
 });
-var snapshotTdGraphOutputSchema = z150.object({
-  path: z150.string().describe("The network root that was snapshotted, echoing the request."),
-  nodeCount: z150.number().describe("Total number of nodes captured."),
-  connectionCount: z150.number().describe("Total number of connections captured."),
-  issues: z150.array(z150.string()).describe("Plain-language structural problems detected in the graph."),
-  params_truncated: z150.boolean().describe(
+var snapshotTdGraphOutputSchema = z153.object({
+  path: z153.string().describe("The network root that was snapshotted, echoing the request."),
+  nodeCount: z153.number().describe("Total number of nodes captured."),
+  connectionCount: z153.number().describe("Total number of connections captured."),
+  issues: z153.array(z153.string()).describe("Plain-language structural problems detected in the graph."),
+  params_truncated: z153.boolean().describe(
     "True if params were requested (`include_params` or `compact`) but the graph exceeded the per-node fetch cap."
   ),
-  parameter_modes_truncated: z150.boolean().optional().describe(
+  parameter_modes_truncated: z153.boolean().optional().describe(
     "True if parameter modes were requested (`include_parameter_modes` or `compact`) but the graph exceeded the per-node fetch cap."
   ),
-  compact: z150.boolean().optional().describe(
+  compact: z153.boolean().optional().describe(
     "True when compact mode hoisted per-type default parameters and delta-encoded nodes."
   ),
-  typeDefaults: z150.record(z150.string(), z150.record(z150.string(), z150.unknown())).optional().describe(
+  typeDefaults: z153.record(z153.string(), z153.record(z153.string(), z153.unknown())).optional().describe(
     "Compact mode only: each operator type's hoisted default parameter values; nodes store only their deltas from these."
   ),
-  nodes: z150.array(
-    z150.object({
-      path: z150.string().describe("Full path of the node."),
-      type: z150.string().describe("Operator type of the node."),
-      name: z150.string().describe("Short name of the node."),
-      parameters: z150.record(z150.string(), z150.unknown()).optional().describe(
+  nodes: z153.array(
+    z153.object({
+      path: z153.string().describe("Full path of the node."),
+      type: z153.string().describe("Operator type of the node."),
+      name: z153.string().describe("Short name of the node."),
+      parameters: z153.record(z153.string(), z153.unknown()).optional().describe(
         "The node's parameters as key\u2192value; present when `include_params` or `compact` is set (compact implies fetching). In compact mode, only the deltas from the type default."
       ),
-      params_unfetched: z150.boolean().optional().describe(
+      params_unfetched: z153.boolean().optional().describe(
         "True when parameters were requested (`include_params` or `compact`) but not fetched for this node (past the per-node cap or a failed read), so a missing `parameters` field isn't mistaken for matching the type default."
       ),
-      parameter_modes: z150.record(z150.string(), parameterModeInfoSchema).optional().describe(
+      parameter_modes: z153.record(z153.string(), parameterModeInfoSchema).optional().describe(
         "Parameter state keyed by par name. Present when `include_parameter_modes` is true, and in compact mode only for expression/bind/export-like non-constant state."
       ),
-      parameter_modes_unfetched: z150.boolean().optional().describe("True when parameter modes were requested but not fetched for this node.")
+      parameter_modes_unfetched: z153.boolean().optional().describe("True when parameter modes were requested but not fetched for this node.")
     })
   ).describe("Every captured node, optionally with its parameters."),
-  connections: z150.array(ConnectionSchema).describe("Every wire as {source_path, target_path, \u2026}, suitable for diffing.")
+  connections: z153.array(ConnectionSchema).describe("Every wire as {source_path, target_path, \u2026}, suitable for diffing.")
 });
 function computeTypeDefaults(nodes) {
   const byType = /* @__PURE__ */ new Map();
@@ -22028,28 +23447,28 @@ async function snapshotTdGraphImpl(ctx, args) {
 }
 
 // src/tools/layer3/summarizeTdErrors.ts
-import { z as z151 } from "zod";
-var summarizeTdErrorsSchema = z151.object({
-  path: z151.string().default("/project1").describe("Network root to collect errors under."),
-  group_by: z151.enum(["message", "type", "parent"]).default("message").describe(
+import { z as z154 } from "zod";
+var summarizeTdErrorsSchema = z154.object({
+  path: z154.string().default("/project1").describe("Network root to collect errors under."),
+  group_by: z154.enum(["message", "type", "parent"]).default("message").describe(
     "How to cluster errors: by exact message, by error type, or by parent container (to find a common upstream cause)."
   )
 });
-var summarizeTdErrorsOutputSchema = z151.object({
-  path: z151.string().describe("The network root errors were collected under, echoing the request."),
-  total: z151.number().describe("Total number of errors found across the network (0 means clean)."),
-  group_by: z151.enum(["message", "type", "parent"]).describe("How the errors were clustered, echoing the request."),
-  groups: z151.array(
-    z151.object({
-      key: z151.string().describe("The shared message, type, or parent path for this cluster."),
-      count: z151.number().describe("How many errors fall into this cluster."),
-      sample: z151.object({
-        path: z151.string().describe("Path of one representative node in this cluster."),
-        message: z151.string().describe("That node's error message, as a concrete example.")
+var summarizeTdErrorsOutputSchema = z154.object({
+  path: z154.string().describe("The network root errors were collected under, echoing the request."),
+  total: z154.number().describe("Total number of errors found across the network (0 means clean)."),
+  group_by: z154.enum(["message", "type", "parent"]).describe("How the errors were clustered, echoing the request."),
+  groups: z154.array(
+    z154.object({
+      key: z154.string().describe("The shared message, type, or parent path for this cluster."),
+      count: z154.number().describe("How many errors fall into this cluster."),
+      sample: z154.object({
+        path: z154.string().describe("Path of one representative node in this cluster."),
+        message: z154.string().describe("That node's error message, as a concrete example.")
       }).describe("One representative error from the cluster.")
     })
   ).describe("Error clusters, largest first; fixing a big cluster's cause clears it at once."),
-  suggestions: z151.array(z151.string()).describe("Plain-language next steps, e.g. the common cause and which nodes to check first.")
+  suggestions: z154.array(z154.string()).describe("Plain-language next steps, e.g. the common cause and which nodes to check first.")
 });
 async function summarizeTdErrorsImpl(ctx, args) {
   return guardTd(
@@ -22096,10 +23515,10 @@ async function summarizeTdErrorsImpl(ctx, args) {
 }
 
 // src/tools/layer3/updateTdNodeParameters.ts
-import { z as z152 } from "zod";
-var updateTdNodeParametersSchema = z152.object({
-  path: z152.string().describe("Full path of the node whose parameters to update."),
-  parameters: z152.record(z152.string(), z152.unknown()).describe("Parameter overrides as key\u2192value pairs, e.g. { period: 4, amplitude: 0.5 }.")
+import { z as z155 } from "zod";
+var updateTdNodeParametersSchema = z155.object({
+  path: z155.string().describe("Full path of the node whose parameters to update."),
+  parameters: z155.record(z155.string(), z155.unknown()).describe("Parameter overrides as key\u2192value pairs, e.g. { period: 4, amplitude: 0.5 }.")
 });
 async function updateTdNodeParametersImpl(ctx, args) {
   return guardTd(
@@ -22111,15 +23530,15 @@ async function updateTdNodeParametersImpl(ctx, args) {
 }
 
 // src/tools/layer3/writeAgentGuide.ts
-import { z as z153 } from "zod";
-var writeAgentGuideSchema = z153.object({
-  filename: z153.string().default("CLAUDE.md").describe(
+import { z as z156 } from "zod";
+var writeAgentGuideSchema = z156.object({
+  filename: z156.string().default("CLAUDE.md").describe(
     "Name of the guide file to emit, e.g. CLAUDE.md or AGENTS.md. Defaults to CLAUDE.md."
   ),
-  output_dir: z153.string().optional().describe(
+  output_dir: z156.string().optional().describe(
     "Absolute path on the machine running TouchDesigner where the guide file should be written. If omitted the guide is returned in the result but not written to disk."
   ),
-  path: z153.string().default("/project1").describe(
+  path: z156.string().default("/project1").describe(
     "TouchDesigner project/COMP path to summarise in the guide header, e.g. /project1. A one-line dynamic summary (node count + top families) is prepended to the static body."
   )
 });
@@ -22292,11 +23711,11 @@ ${lookupTable}
 *End of guide \u2014 re-run ${BT}write_agent_guide${BT} any time to refresh the project summary.*
 `;
 }
-var writeAgentGuideOutputSchema = z153.object({
-  filename: z153.string().describe("Name of the guide file."),
-  written: z153.boolean().describe("Whether the file was written to disk."),
-  path: z153.string().optional().describe("Absolute path the file was written to (if written)."),
-  guide: z153.string().describe("The full guide markdown text.")
+var writeAgentGuideOutputSchema = z156.object({
+  filename: z156.string().describe("Name of the guide file."),
+  written: z156.boolean().describe("Whether the file was written to disk."),
+  path: z156.string().optional().describe("Absolute path the file was written to (if written)."),
+  guide: z156.string().describe("The full guide markdown text.")
 });
 async function tryBridgeReport(ctx, payload) {
   try {
@@ -22364,7 +23783,7 @@ import {
   writeFileSync as writeFileSync3
 } from "fs";
 import { basename as basename2, dirname as dirname4, extname, join as join7, parse, resolve as resolve4, sep as sep2 } from "path";
-import { z as z154 } from "zod";
+import { z as z157 } from "zod";
 
 // src/packages/archive.ts
 import { execFileSync } from "child_process";
@@ -22468,16 +23887,16 @@ function listZipEntryInfo(zipPath) {
 }
 
 // src/tools/library/index.ts
-var ComponentManifestSchema = z154.object({
-  id: z154.string().optional(),
-  name: z154.string().optional(),
-  version: z154.string().optional(),
-  description: z154.string().optional(),
-  type: z154.string().optional(),
-  tox: z154.string().optional(),
-  assets: z154.array(z154.string()).default([]),
-  docs: z154.array(z154.string()).default([]),
-  recipes: z154.array(z154.string()).default([])
+var ComponentManifestSchema = z157.object({
+  id: z157.string().optional(),
+  name: z157.string().optional(),
+  version: z157.string().optional(),
+  description: z157.string().optional(),
+  type: z157.string().optional(),
+  tox: z157.string().optional(),
+  assets: z157.array(z157.string()).default([]),
+  docs: z157.array(z157.string()).default([]),
+  recipes: z157.array(z157.string()).default([])
 }).passthrough();
 function manifestCandidates(path2) {
   const full = resolve4(path2);
@@ -22603,12 +24022,12 @@ function extractZip(zipPath, destDir, exec = execFileSync2, listEntries = listZi
   const { command, args } = zipExtractCommand(zipPath, destDir);
   exec(command, args, { stdio: "pipe" });
 }
-var browseLibrarySchema = z154.object({
-  query: z154.string().optional(),
-  tags: z154.array(z154.string()).default([]),
-  package_dir: z154.string().optional(),
-  include_recipes: z154.boolean().default(true),
-  include_packages: z154.boolean().default(true)
+var browseLibrarySchema = z157.object({
+  query: z157.string().optional(),
+  tags: z157.array(z157.string()).default([]),
+  package_dir: z157.string().optional(),
+  include_recipes: z157.boolean().default(true),
+  include_packages: z157.boolean().default(true)
 });
 async function browseLibraryImpl(ctx, args) {
   const query = args.query?.toLowerCase();
@@ -22638,7 +24057,7 @@ async function browseLibraryImpl(ctx, args) {
     packages
   });
 }
-var inspectComponentManifestSchema = z154.object({ path: z154.string() });
+var inspectComponentManifestSchema = z157.object({ path: z157.string() });
 async function inspectComponentManifestImpl(_ctx, args) {
   try {
     const { path: path2, manifest } = readManifest(args.path);
@@ -22655,11 +24074,11 @@ async function inspectComponentManifestImpl(_ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var makePortableToxSchema = z154.object({
-  comp_path: z154.string(),
-  out_dir: z154.string(),
-  name: z154.string().optional(),
-  docs: z154.array(z154.string()).default([])
+var makePortableToxSchema = z157.object({
+  comp_path: z157.string(),
+  out_dir: z157.string(),
+  name: z157.string().optional(),
+  docs: z157.array(z157.string()).default([])
 });
 var SAVE_TOX_SCRIPT = `
 import json, base64, os, traceback
@@ -22718,10 +24137,10 @@ async function makePortableToxImpl(ctx, args) {
     }
   );
 }
-var exportRecipeBundleSchema = z154.object({
-  out_file: z154.string(),
-  recipe_ids: z154.array(z154.string()).default([]),
-  include_all: z154.boolean().default(false)
+var exportRecipeBundleSchema = z157.object({
+  out_file: z157.string(),
+  recipe_ids: z157.array(z157.string()).default([]),
+  include_all: z157.boolean().default(false)
 });
 async function exportRecipeBundleImpl(ctx, args) {
   try {
@@ -22740,15 +24159,15 @@ async function exportRecipeBundleImpl(ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var importRecipeBundleSchema = z154.object({
-  bundle_file: z154.string(),
-  out_dir: z154.string(),
-  overwrite: z154.boolean().default(false)
+var importRecipeBundleSchema = z157.object({
+  bundle_file: z157.string(),
+  out_dir: z157.string(),
+  overwrite: z157.boolean().default(false)
 });
 async function importRecipeBundleImpl(_ctx, args) {
   try {
     const raw = JSON.parse(readFileSync6(args.bundle_file, "utf8"));
-    const recipes = z154.array(RecipeSchema).parse(raw.recipes ?? []);
+    const recipes = z157.array(RecipeSchema).parse(raw.recipes ?? []);
     const targets = recipes.map((recipe) => ({
       recipe,
       out: join7(args.out_dir, recipeFileName(recipe))
@@ -22780,9 +24199,9 @@ async function importRecipeBundleImpl(_ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var validateLibraryAssetSchema = z154.object({
-  path: z154.string(),
-  manifest_path: z154.string().optional()
+var validateLibraryAssetSchema = z157.object({
+  path: z157.string(),
+  manifest_path: z157.string().optional()
 });
 async function validateLibraryAssetImpl(_ctx, args) {
   const issues = [];
@@ -22821,11 +24240,11 @@ async function validateLibraryAssetImpl(_ctx, args) {
     }
   );
 }
-var scaffoldRecipeTemplateSchema = z154.object({
-  out_file: z154.string(),
-  id: z154.string(),
-  name: z154.string(),
-  overwrite: z154.boolean().default(false)
+var scaffoldRecipeTemplateSchema = z157.object({
+  out_file: z157.string(),
+  id: z157.string(),
+  name: z157.string(),
+  overwrite: z157.boolean().default(false)
 });
 async function scaffoldRecipeTemplateImpl(_ctx, args) {
   try {
@@ -22858,10 +24277,10 @@ async function scaffoldRecipeTemplateImpl(_ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var attachDocsAsAssetsSchema = z154.object({
-  manifest_path: z154.string(),
-  docs: z154.array(z154.string()).min(1),
-  asset_dir: z154.string().default("docs")
+var attachDocsAsAssetsSchema = z157.object({
+  manifest_path: z157.string(),
+  docs: z157.array(z157.string()).min(1),
+  asset_dir: z157.string().default("docs")
 });
 async function attachDocsAsAssetsImpl(_ctx, args) {
   try {
@@ -22887,9 +24306,9 @@ async function attachDocsAsAssetsImpl(_ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var localMarketplaceIndexSchema = z154.object({
-  package_dir: z154.string(),
-  out_file: z154.string().optional()
+var localMarketplaceIndexSchema = z157.object({
+  package_dir: z157.string(),
+  out_file: z157.string().optional()
 });
 async function localMarketplaceIndexImpl(_ctx, args) {
   try {
@@ -22923,9 +24342,9 @@ async function localMarketplaceIndexImpl(_ctx, args) {
     return errorResult(err instanceof Error ? err.message : String(err));
   }
 }
-var componentLinkHealthSchema = z154.object({
-  paths: z154.array(z154.string()).default([]),
-  parent_path: z154.string().default("/project1")
+var componentLinkHealthSchema = z157.object({
+  paths: z157.array(z157.string()).default([]),
+  parent_path: z157.string().default("/project1")
 });
 var LINK_HEALTH_SCRIPT = `
 import json, base64, os, traceback
@@ -22979,10 +24398,10 @@ async function componentLinkHealthImpl(ctx, args) {
     }
   );
 }
-var refreshAssetPreviewsSchema = z154.object({
-  targets: z154.array(z154.object({ node_path: z154.string(), file_path: z154.string() })).min(1),
-  width: z154.coerce.number().int().positive().default(640),
-  height: z154.coerce.number().int().positive().default(360)
+var refreshAssetPreviewsSchema = z157.object({
+  targets: z157.array(z157.object({ node_path: z157.string(), file_path: z157.string() })).min(1),
+  width: z157.coerce.number().int().positive().default(640),
+  height: z157.coerce.number().int().positive().default(360)
 });
 async function refreshAssetPreviewsImpl(ctx, args) {
   const written = [];
@@ -23010,10 +24429,10 @@ async function refreshAssetPreviewsImpl(ctx, args) {
   if (written.length === 0) return errorResult(summary, report);
   return jsonResult(summary, report);
 }
-var installLibraryPackageSchema = z154.object({
-  source: z154.string().describe("Local package folder, .zip, .tox, or manifest file."),
-  dest_dir: z154.string(),
-  overwrite: z154.boolean().default(false)
+var installLibraryPackageSchema = z157.object({
+  source: z157.string().describe("Local package folder, .zip, .tox, or manifest file."),
+  dest_dir: z157.string(),
+  overwrite: z157.boolean().default(false)
 });
 async function installLibraryPackageImpl(_ctx, args) {
   try {
@@ -23042,6 +24461,192 @@ async function installLibraryPackageImpl(_ctx, args) {
   }
 }
 
+// src/tools/vault/generateLibraryIndex.ts
+import { basename as basename3, extname as extname2 } from "path";
+import { z as z158 } from "zod";
+
+// src/tools/vault/shared.ts
+var NO_VAULT = "No Obsidian vault is configured. Set TDMCP_VAULT_PATH to your vault folder (e.g. ~/Documents/MyVault) and restart the server, then try again.";
+function requireVault(ctx) {
+  if (!ctx.vault) return { error: errorResult(NO_VAULT) };
+  return { vault: ctx.vault };
+}
+function readNoteSafe(vault, relPath) {
+  try {
+    return vault.readNote(relPath);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return {
+      error: errorResult(
+        `Could not read vault note "${relPath}": ${reason}. Check the file is readable and its YAML frontmatter is valid.`
+      )
+    };
+  }
+}
+
+// src/tools/vault/generateLibraryIndex.ts
+var generateLibraryIndexSchema = z158.object({
+  kinds: z158.array(z158.enum(["recipes", "shaders", "presets", "components", "setlists", "all"])).default(["all"]).describe("Which library categories to include. 'all' = every category."),
+  output: z158.string().default("Library Index.md").describe("Vault-relative path of the contact-sheet note to write."),
+  include_thumbnails: z158.boolean().default(true).describe("Embed each asset's <stem>.png sibling when present; false = text-only."),
+  columns: z158.coerce.number().int().min(1).max(6).default(3).describe("Cards per row in the contact-sheet grid."),
+  query: z158.string().optional().describe("Case-insensitive substring filter on title/tags."),
+  overwrite: z158.boolean().default(true).describe("When false, refuse to overwrite an existing index note.")
+});
+var CATEGORY_FOLDERS = {
+  recipes: "Recipes",
+  shaders: "Shaders",
+  presets: "Presets",
+  components: "Components",
+  setlists: "Setlists"
+};
+var ALL_KINDS = Object.keys(CATEGORY_FOLDERS);
+function fmString(data, key) {
+  const v = data[key];
+  return typeof v === "string" ? v : void 0;
+}
+function fmTags(data) {
+  const v = data.tags;
+  if (Array.isArray(v)) return v.map((t) => String(t)).filter(Boolean);
+  if (typeof v === "string")
+    return v.split(",").map((t) => t.trim()).filter(Boolean);
+  return [];
+}
+function matchesQuery(title, tags, query) {
+  const q59 = query.toLowerCase();
+  if (title.toLowerCase().includes(q59)) return true;
+  return tags.some((t) => t.toLowerCase().includes(q59));
+}
+var CATEGORY_TITLES = {
+  recipes: "Recipes",
+  shaders: "Shaders",
+  presets: "Presets",
+  components: "Components",
+  setlists: "Setlists"
+};
+function loadSnippet(kind, stem, relPath, data) {
+  switch (kind) {
+    case "recipes": {
+      const id = fmString(data, "id") ?? stem;
+      return `\`apply_recipe id=${id}\``;
+    }
+    case "components": {
+      const tox = fmString(data, "tox") ?? `Components/${stem}.tox`;
+      return `\`manage_component action=load file_path=<vault>/${tox}\``;
+    }
+    case "shaders":
+      return `\`apply_shader_from_vault note=${relPath}\``;
+    case "setlists":
+      return `\`import_setlist note=${relPath}\``;
+    default:
+      return `[[${stem}]]`;
+  }
+}
+function mdCell(s) {
+  return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function renderCell(card) {
+  const thumb = card.png ? `![[${basename3(card.png)}]]` : "_(no preview)_";
+  const tags = mdCell(card.tags.join(", "));
+  return `${thumb}<br>**${mdCell(card.title)}**<br><small>${tags}</small><br>${mdCell(card.snippet)}`;
+}
+function renderSection(title, cards, columns) {
+  const lines = [`## ${title} (${cards.length})`, ""];
+  lines.push(`|${" |".repeat(columns)}`);
+  lines.push(`|${"---|".repeat(columns)}`);
+  for (let i = 0; i < cards.length; i += columns) {
+    const row = cards.slice(i, i + columns).map(renderCell);
+    while (row.length < columns) row.push("");
+    lines.push(`| ${row.join(" | ")} |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function generateLibraryIndexImpl(ctx, args) {
+  const v = requireVault(ctx);
+  if ("error" in v) return v.error;
+  const { vault } = v;
+  let outResolveError;
+  try {
+    vault.resolve(args.output);
+  } catch (err) {
+    outResolveError = err instanceof Error ? err.message : String(err);
+  }
+  if (outResolveError) {
+    return errorResult(`Cannot write the index note: ${outResolveError}`);
+  }
+  if (!args.overwrite && vault.exists(args.output)) {
+    return errorResult(
+      `An index note already exists at "${args.output}". Re-run with overwrite:true to replace it.`
+    );
+  }
+  const requested = args.kinds.includes("all") ? ALL_KINDS : [...new Set(args.kinds)];
+  const counts = {};
+  const warnings = [];
+  const sections = [];
+  let withThumbnails = 0;
+  let withoutThumbnails = 0;
+  for (const kind of requested) {
+    const folder = CATEGORY_FOLDERS[kind];
+    if (!folder) continue;
+    const files = vault.list(folder, ".md");
+    const cards = [];
+    for (const filename of files) {
+      const relPath = `${folder}/${filename}`;
+      const note = readNoteSafe(vault, relPath);
+      if ("error" in note) {
+        warnings.push(`Could not read ${relPath}: skipped.`);
+        continue;
+      }
+      const { data } = note;
+      const stem = basename3(filename, extname2(filename));
+      const title = fmString(data, "title") ?? fmString(data, "name") ?? stem;
+      const tags = fmTags(data);
+      if (args.query && !matchesQuery(title, tags, args.query)) continue;
+      const pngRel = `${folder}/${stem}.png`;
+      const png = args.include_thumbnails && vault.exists(pngRel) ? pngRel : null;
+      if (png) withThumbnails += 1;
+      else withoutThumbnails += 1;
+      cards.push({
+        title,
+        tags,
+        png,
+        snippet: loadSnippet(kind, stem, relPath, data)
+      });
+    }
+    counts[kind] = cards.length;
+    if (cards.length > 0) sections.push({ kind, cards });
+  }
+  const total = sections.reduce((n, s) => n + s.cards.length, 0);
+  const categoryCount = sections.length;
+  const generated = (/* @__PURE__ */ new Date()).toISOString();
+  const bodyParts = ["# Library Index", ""];
+  if (total === 0) {
+    bodyParts.push(
+      `_No library assets found${args.query ? ` matching "${args.query}"` : ""}. Save recipes/components to the vault, then regenerate with \`generate_library_index\`._`
+    );
+  } else {
+    bodyParts.push(
+      `_${total} asset(s) across ${categoryCount} categor${categoryCount === 1 ? "y" : "ies"}. Regenerate with \`generate_library_index\`._`,
+      ""
+    );
+    for (const { kind, cards } of sections) {
+      bodyParts.push(renderSection(CATEGORY_TITLES[kind] ?? kind, cards, args.columns));
+    }
+  }
+  const body = bodyParts.join("\n").trimEnd();
+  vault.writeNote(args.output, { type: "library-index", generated, kinds: requested }, body);
+  const summary = total === 0 ? `Wrote ${args.output} \u2014 no library assets found.` : `Wrote ${args.output} \u2014 ${total} asset(s) across ${categoryCount} categor${categoryCount === 1 ? "y" : "ies"} (${withThumbnails} with thumbnails).`;
+  return structuredResult(summary, {
+    index_path: args.output,
+    total,
+    counts,
+    with_thumbnails: withThumbnails,
+    without_thumbnails: withoutThumbnails,
+    warnings
+  });
+}
+
 // src/cli/doctor.ts
 import { existsSync as existsSync8, statSync as statSync2 } from "fs";
 import { homedir as homedir5 } from "os";
@@ -23427,7 +25032,7 @@ async function runDoctor(opts = {}) {
 // src/cli/agent.ts
 var r = (schema, run, summary, opts = {}) => ({ schema, run, summary, mutates: !!opts.mutates, unsafe: !!opts.unsafe });
 var COMMANDS = {
-  info: r(z155.object({}), (ctx) => getTdInfoImpl(ctx), "Health check + TD/bridge info."),
+  info: r(z159.object({}), (ctx) => getTdInfoImpl(ctx), "Health check + TD/bridge info."),
   reload: r(
     reloadBridgeSchema,
     reloadBridgeImpl,
@@ -23441,6 +25046,11 @@ var COMMANDS = {
   "nodes find": r(findTdNodesSchema, findTdNodesImpl, "Search nodes by name pattern and/or type."),
   "nodes get": r(getTdNodeParametersSchema, getTdNodeParametersImpl, "Read a node's parameters."),
   "nodes errors": r(getTdNodeErrorsSchema, getTdNodeErrorsImpl, "Check a node/network for errors."),
+  "nodes flags": r(
+    getTdNodeFlagsSchema,
+    getTdNodeFlagsImpl,
+    "Inspect node flags + wiring (why-is-it-black)."
+  ),
   "nodes compare": r(compareTdNodesSchema, compareTdNodesImpl, "Diff two nodes' parameters."),
   "nodes snapshot": r(snapshotTdGraphSchema, snapshotTdGraphImpl, "Capture a network snapshot."),
   "nodes topology": r(getTdTopologySchema, getTdTopologyImpl, "Map nodes + connections."),
@@ -23756,6 +25366,18 @@ var COMMANDS = {
   macro: r(createMacroSchema, createMacroImpl, "Add one knob that drives many parameters.", {
     mutates: true
   }),
+  modulators: r(
+    createModulatorsSchema,
+    createModulatorsImpl,
+    "Build a bank of BPM-synced LFOs on one Null (the 'everything breathes' lever).",
+    { mutates: true }
+  ),
+  "look-bank": r(
+    createLookBankSchema,
+    createLookBankImpl,
+    "Snapshot/morph look bank: store, recall, A\u2194B blend named looks on a control COMP.",
+    { mutates: true }
+  ),
   randomize: r(
     randomizeControlsSchema,
     randomizeControlsImpl,
@@ -24265,6 +25887,12 @@ var COMMANDS = {
     installLibraryPackageImpl,
     "Install a local package folder, zip, tox, or manifest into a package directory.",
     { mutates: true }
+  ),
+  "library-index": r(
+    generateLibraryIndexSchema,
+    generateLibraryIndexImpl,
+    "Write a Markdown contact-sheet of the whole vault library (thumbnails + load snippets).",
+    { mutates: true }
   )
 };
 function textOf(result) {
@@ -24485,18 +26113,18 @@ function assembleParams(values) {
   }
   return { raw };
 }
-var runStepSchema = z155.object({
-  command: z155.union([z155.string(), z155.array(z155.string()).min(1)]),
-  params: z155.record(z155.string(), z155.unknown()).optional(),
-  json: z155.record(z155.string(), z155.unknown()).optional(),
-  output: z155.enum(["json", "ndjson", "text"]).optional(),
-  dry_run: z155.boolean().optional(),
-  allow_unsafe: z155.boolean().optional(),
-  quiet: z155.boolean().optional()
+var runStepSchema = z159.object({
+  command: z159.union([z159.string(), z159.array(z159.string()).min(1)]),
+  params: z159.record(z159.string(), z159.unknown()).optional(),
+  json: z159.record(z159.string(), z159.unknown()).optional(),
+  output: z159.enum(["json", "ndjson", "text"]).optional(),
+  dry_run: z159.boolean().optional(),
+  allow_unsafe: z159.boolean().optional(),
+  quiet: z159.boolean().optional()
 }).passthrough();
-var runFileSchema = z155.union([
-  z155.array(runStepSchema),
-  z155.object({ steps: z155.array(runStepSchema) })
+var runFileSchema = z159.union([
+  z159.array(runStepSchema),
+  z159.object({ steps: z159.array(runStepSchema) })
 ]);
 function runStepArgv(step) {
   const argv = Array.isArray(step.command) ? [...step.command] : tokenizeLine(step.command);
@@ -24611,7 +26239,7 @@ async function runCli(argv, opts = {}) {
       summary: cmd2.summary,
       mutates: cmd2.mutates,
       unsafe: cmd2.unsafe,
-      input: z155.toJSONSchema(cmd2.schema)
+      input: z159.toJSONSchema(cmd2.schema)
     };
     return { stdout: `${JSON.stringify(doc, null, 2)}
 `, stderr: "", code: 0 };