@engine-room/after-effects-mcp 0.2.1 → 0.3.0

package/bin/server.js

@@ -352,6 +352,7 @@ __export(schemas_exports, {
   CreateAdjustmentLayer: () => CreateAdjustmentLayer,
   CreateCameraLayer: () => CreateCameraLayer,
   CreateComp: () => CreateComp,
+  CreateFootageLayer: () => CreateFootageLayer,
   CreateLightLayer: () => CreateLightLayer,
   CreateNullLayer: () => CreateNullLayer,
   CreatePrecompLayer: () => CreatePrecompLayer,
@@ -361,6 +362,7 @@ __export(schemas_exports, {
   DeleteComp: () => DeleteComp,
   DeleteLayer: () => DeleteLayer,
   DuplicateLayer: () => DuplicateLayer,
+  ExportMogrt: () => ExportMogrt,
   FindLayers: () => FindLayers,
   GUIDE_TOPICS: () => GUIDE_TOPICS,
   GetComp: () => GetComp,
@@ -371,6 +373,7 @@ __export(schemas_exports, {
   GetKeyframes: () => GetKeyframes,
   GetLayerFull: () => GetLayerFull,
   GetProjectSummary: () => GetProjectSummary,
+  ImportFootage: () => ImportFootage,
   InitProject: () => InitProject,
   Interpolation: () => Interpolation,
   ListAvailableEffects: () => ListAvailableEffects,
@@ -427,7 +430,10 @@ var Interpolation = z2.object({
   easeIn: z2.object({ influence: z2.number(), speed: z2.number() }).optional(),
   easeOut: z2.object({ influence: z2.number(), speed: z2.number() }).optional()
 });
-var ListComps = z2.object({}).strict();
+var includeParam = (sections, hint) => z2.array(z2.enum(sections)).optional().describe(`Sections to return: ${sections.join(", ")}. Omit for all of them; [] for ${hint}.`);
+var ListComps = z2.object({
+  include: includeParam(["size", "timing", "bg", "counts"], "id + name only")
+}).strict();
 var GetComp = z2.object({ compId: z2.number() });
 var GetCompTree = z2.object({ compId: z2.number(), depth: z2.number().int().min(0).max(8).default(2).optional() });
 var CreateComp = z2.object({
@@ -452,8 +458,18 @@ var SetComp = z2.object({
 });
 var DeleteComp = z2.object({ compId: z2.number() });
 var SetActiveComp = z2.object({ compId: z2.number() });
-var ListLayers = z2.object({ compId: z2.number() });
-var GetLayerFull = z2.object({ compId: z2.number(), layerId: z2.number(), includeChildren: z2.boolean().default(false).optional() });
+var ListLayers = z2.object({
+  compId: z2.number(),
+  include: includeParam(["flags", "timing", "parent"], "the id/index/name/type map alone")
+});
+var GetLayerFull = z2.object({
+  compId: z2.number(),
+  layerId: z2.number(),
+  includeChildren: z2.boolean().default(false).optional(),
+  include: includeParam(["transform", "effects", "masks", "markers", "bounds", "text", "shape", "source"], "the layer header alone"),
+  maxKeyframes: z2.number().int().positive().optional().describe("Cap the keyframes serialized per property. Over the cap you get the first and last few plus a count of what was omitted \u2014 never a silent truncation. Omit for all of them."),
+  shapeDepth: z2.number().int().min(0).max(4).optional().describe("How deep to walk a shape layer's Contents tree. Default 4; drop to 1-2 on heavy shape layers.")
+});
 var CreateTextLayer = z2.object({
   compId: z2.number(),
   text: z2.string().default(""),
@@ -461,7 +477,8 @@ var CreateTextLayer = z2.object({
   size: z2.number().positive().optional(),
   color: Color.optional(),
   position: VecAny.optional(),
-  anchorAlign: z2.enum(["left", "center", "right", "none"]).default("left").optional().describe("Where the anchor point sits on the rendered text. Default 'left' makes `position` mean the visible left edge of the first character's baseline \u2014 the natural assumption. AE's addText() defaults to a centered anchor, which surprises agents; use 'none' to keep AE's raw default."),
+  tracking: z2.number().optional().describe("Letter-spacing. Omit it and the layer is created with tracking 0, because AE's addText() otherwise inherits whatever the user's Character panel was last left on (-20 is common) and the same call then renders differently on two machines. Not normalised when anchorAlign is 'none'."),
+  anchorAlign: z2.enum(["left", "center", "right", "none"]).default("left").optional().describe("How the text aligns to `position`, implemented as live paragraph justification with the anchor point left at [0,0]. Default 'left' makes `position` the start of the first baseline; 'center' and 'right' put it at the centre/end. Because it is justification rather than a measured anchor offset, the alignment stays correct when the Source Text changes later \u2014 retyped, driven by an expression, or edited through Essential Graphics. 'none' leaves AE's raw defaults alone: no justification, no anchor move, no tracking reset."),
   name: z2.string().optional()
 });
 var CreateShapeLayer = z2.object({
@@ -512,7 +529,12 @@ var SetLayer = z2.object({
   preserveTransparency: z2.boolean().optional(),
   trackMatte: z2.object({ type: z2.string(), layerId: z2.number().optional() }).optional()
 });
-var ParentLayer = z2.object({ compId: z2.number(), layerId: z2.number(), parentLayerId: z2.number().nullable() });
+var ParentLayer = z2.object({
+  compId: z2.number(),
+  layerId: z2.number(),
+  parentLayerId: z2.number().nullable(),
+  preserveTransform: z2.boolean().default(true).optional().describe("Keep the layer visually where it is (what AE's UI does). Leave on unless you want the layer to jump into the parent's coordinate space.")
+});
 var ReorderLayer = z2.object({ compId: z2.number(), layerId: z2.number(), toIndex: z2.number().int().positive() });
 var SetTransform = z2.object({
   compId: z2.number(),
@@ -592,7 +614,10 @@ var SetEffectParam = z2.object({
   keyframe: z2.boolean().default(false).optional()
 });
 var SetEffectEnabled = z2.object({ compId: z2.number(), layerId: z2.number(), effectIndex: z2.number().int().positive(), enabled: z2.boolean() });
-var ListAvailableEffects = z2.object({}).strict();
+var ListAvailableEffects = z2.object({
+  filter: z2.string().optional(),
+  refresh: z2.boolean().optional()
+}).strict();
 var SetText = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
@@ -707,7 +732,8 @@ var AddShapeContent = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
   parentGroupPath: PropertyPath.optional(),
-  content: ShapeContent
+  content: ShapeContent,
+  zOrder: z2.enum(["front", "back"]).optional().describe("Where the new node sits in its group's render stack. Index 1 renders in FRONT, and AE appends new content to the end \u2014 so the default, 'back', puts each node behind everything already there. 'front' moves it to index 1. Prefer ordering your calls front-to-back (details first, background rects last) over reaching for 'front': it needs an internal moveTo, which has been seen to disturb nested renders of the comp in AE 26.3.")
 });
 var SetShapeProperty = z2.object({
   compId: z2.number(),
@@ -758,16 +784,17 @@ var RemoveMarker = z2.object({
   layerId: z2.number().optional(),
   markerIndex: z2.number().int().positive()
 });
+var downsampleParam = z2.number().int().min(1).max(8).optional().describe("Render at 1/N resolution. Omit and one is chosen from the comp size (long edge ~1280px: 2 at 1080p, 3 at 4K). Pass 1 for a full-resolution frame.");
 var ScreenshotFrame = z2.object({
   compId: z2.number(),
   time: z2.number().optional(),
-  downsample: z2.number().int().min(1).max(8).default(1).optional()
+  downsample: downsampleParam
 });
 var ScreenshotLayer = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
   time: z2.number().optional(),
-  downsample: z2.number().int().min(1).max(8).default(1).optional()
+  downsample: downsampleParam
 });
 var RunBatch = z2.object({
   ops: z2.array(z2.object({ op: z2.string(), args: z2.unknown() })),
@@ -781,7 +808,31 @@ var FindLayers = z2.object({
   type: z2.string().optional(),
   hasEffectMatchName: z2.string().optional()
 });
-var RunJsx = z2.object({ code: z2.string() });
+var RunJsx = z2.object({
+  code: z2.string(),
+  undoGroup: z2.boolean().default(true).optional().describe("Wrap the script in one undo step. Set false only for the operations AE refuses while an undo group is open \u2014 copyToComp on a layer with a parent or a linked expression. The script's changes then land as whatever undo steps AE records on its own.")
+});
+var ImportFootage = z2.object({
+  path: z2.string().min(1).describe("Absolute path to the file to import."),
+  name: z2.string().optional().describe("Rename the project item after import. Omit to keep the filename."),
+  sequence: z2.boolean().default(false).optional().describe("Import a numbered still as an image sequence rather than a single frame."),
+  force: z2.boolean().default(false).optional().describe("Keep an item that failed validation instead of deleting it and throwing. The problem is still reported in `validation`. Only pass this when you know the dimensions are wrong and want the item anyway.")
+}).strict();
+var CreateFootageLayer = z2.object({
+  compId: z2.number(),
+  itemId: z2.number().describe("Project item id from import_footage or get_project_summary."),
+  name: z2.string().optional(),
+  position: VecAny.optional(),
+  startTime: z2.number().optional()
+});
+var ExportMogrt = z2.object({
+  compId: z2.number(),
+  destDir: z2.string().optional().describe("Folder to write the .mogrt into. Defaults to the folder holding the .aep."),
+  name: z2.string().optional().describe("Template name, which is also the output filename. Defaults to the comp name \u2014 AE's own default is the literal 'Untitled', so every scripted export would otherwise overwrite the same file."),
+  overwrite: z2.boolean().default(false).optional().describe("Required to replace an existing .mogrt at that path."),
+  posterTime: z2.number().optional().describe("Comp time to render as the template's still thumbnail, replacing the black one AE writes. Omit to leave AE's thumbnail alone."),
+  suppressDialogs: z2.boolean().default(true).optional().describe("Suppress the modal font warning during export. Leave true: an unsuppressed dialog freezes the bridge until someone clicks it in AE. Set false only to see the dialog deliberately.")
+}).strict();
 var GetHouseStyle = z2.object({}).strict();
 var SetHouseStyle = z2.object({
   content: z2.string().min(1).describe("The complete style guide as markdown. Replaces the file, so send the whole document."),
@@ -811,7 +862,10 @@ var LogIssue = z2.object({
 }).strict();
 var ListKnownIssues = z2.object({
   status: z2.enum(["all", "unreported", "reported"]).default("all").optional(),
-  tool: z2.string().optional().describe("Only entries about this tool, e.g. 'set_temporal_ease'. Omit for everything.")
+  tool: z2.string().optional().describe("Only entries about this tool, e.g. 'set_temporal_ease'. Omit for everything."),
+  query: z2.string().optional().describe("Free-text filter: every whitespace-separated term must appear in an entry's title, symptom or tools."),
+  id: z2.string().optional().describe("Read one entry in full \u2014 cause and workaround included \u2014 by the id from a previous listing. Ignores the filters."),
+  detail: z2.enum(["index", "full"]).default("index").optional().describe("'index' (default) is one line per entry: id, title, tools, counts and a one-line summary \u2014 read the one you need with `id`. 'full' returns every matching entry's whole body and costs thousands of tokens.")
 }).strict();
 var MarkIssueReported = z2.object({
   id: z2.string().describe("The entry id returned by log_issue or list_known_issues."),
@@ -888,6 +942,11 @@ var OpSchemas = {
   // explore
   get_project_summary: GetProjectSummary,
   find_layers: FindLayers,
+  // footage
+  import_footage: ImportFootage,
+  create_footage_layer: CreateFootageLayer,
+  // motion graphics templates
+  export_mogrt: ExportMogrt,
   // raw
   run_jsx: RunJsx,
   // house style
@@ -928,15 +987,69 @@ var BridgeUnreachableError = class _BridgeUnreachableError extends Error {
     ].filter(Boolean).join("\n");
   }
 };
+var BridgeTimeoutError = class _BridgeTimeoutError extends Error {
+  constructor(port, timeoutMs, opts = {}) {
+    super(_BridgeTimeoutError.message(port, timeoutMs, opts));
+    this.port = port;
+    this.timeoutMs = timeoutMs;
+    this.name = "BridgeTimeoutError";
+  }
+  port;
+  timeoutMs;
+  static message(port, timeoutMs, opts = {}) {
+    const secs = Math.round(timeoutMs / 1e3);
+    const what = opts.op ? `\`${opts.op}\`` : "the call";
+    return [
+      `The After Effects panel at http://127.0.0.1:${port} did not answer within ${secs}s for ${what}.`,
+      "",
+      "This is a timeout, not a lost connection \u2014 the panel is very probably still",
+      "there. ExtendScript is single-threaded, so while After Effects is busy running a",
+      "script it cannot answer the bridge at all, and a busy AE looks exactly like a",
+      "dead one from here. It usually recovers on its own.",
+      "",
+      "What to do, in order:",
+      "1. Do not restart After Effects, and do not run setup_panel. Do not re-send the",
+      "   call either \u2014 that would queue a second copy of the same work.",
+      "2. Call check_setup, and keep polling it for about a minute. The bridge normally",
+      "   comes back by itself once the script finishes.",
+      "3. Ask the user to look at After Effects. A modal dialog \u2014 an unsaved-project",
+      "   prompt, a missing-font warning \u2014 blocks it in the same way and may be hidden",
+      "   behind another window. Only they can click it.",
+      "4. On macOS, if they have switched to another desktop (Space), ask them to switch",
+      "   back to the one After Effects is on. Calls have been reported to stall until",
+      "   they return, then complete normally.",
+      "5. Only if check_setup still reports the bridge down after a minute should you",
+      "   treat this as a real disconnection and follow its nextSteps.",
+      opts.adjustable === false ? "" : `
+If this work legitimately takes longer than ${secs}s, the limit is settable: start the
+server with AE_MCP_OP_TIMEOUT_MS set to a larger number of milliseconds.`
+    ].filter(Boolean).join("\n");
+  }
+};
+function isTimeoutError(e, depth = 0) {
+  if (!e || typeof e !== "object" || depth > 4) return false;
+  const name = e.name;
+  if (name === "TimeoutError" || name === "AbortError") return true;
+  const cause = e.cause;
+  return cause === e ? false : isTimeoutError(cause, depth + 1);
+}
 var AeError = class extends Error {
-  constructor(message, stack_, line) {
+  /**
+   * `code` is set only when the panel diagnosed the failure itself rather than
+   * relaying one from ExtendScript — `STALE_FRAME` is the first. Those messages
+   * already read as complete instructions, so the caller uses this to decide
+   * whether an `AE:` prefix would help or just obscure them.
+   */
+  constructor(message, stack_, line, code) {
     super(message);
     this.stack_ = stack_;
     this.line = line;
+    this.code = code;
     this.name = "AeError";
   }
   stack_;
   line;
+  code;
 };
 
 // src/util/logger.ts
@@ -973,6 +1086,19 @@ function discoverPort() {
 }
 
 // src/bridge/httpClient.ts
+var DEFAULT_OP_TIMEOUT_MS = 12e4;
+var SLOW_OPS = /* @__PURE__ */ new Set(["run_batch", "run_jsx", "screenshot_frame", "screenshot_layer", "export_mogrt", "import_footage"]);
+var SLOW_OP_TIMEOUT_MS = 3e5;
+function opTimeoutMs(op) {
+  const raw = process.env.AE_MCP_OP_TIMEOUT_MS?.trim();
+  if (raw) {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+    logger.warn(`Ignoring AE_MCP_OP_TIMEOUT_MS=${raw} \u2014 expected a positive number of milliseconds.`);
+  }
+  return op && SLOW_OPS.has(op) ? SLOW_OP_TIMEOUT_MS : DEFAULT_OP_TIMEOUT_MS;
+}
+var HEALTH_TIMEOUT_MS = 2e3;
 var HttpClient = class {
   port;
   base;
@@ -984,23 +1110,28 @@ var HttpClient = class {
   // treat undefined as "too old to say" rather than as a mismatch.
   async health() {
     try {
-      const r = await fetch(`${this.base}/health`, { signal: AbortSignal.timeout(2e3) });
+      const r = await fetch(`${this.base}/health`, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
       if (!r.ok) throw new Error(`health HTTP ${r.status}`);
       return await r.json();
     } catch (e) {
+      if (isTimeoutError(e)) {
+        throw new BridgeTimeoutError(this.port, HEALTH_TIMEOUT_MS, { op: "health", adjustable: false });
+      }
       throw new BridgeUnreachableError(this.port, e);
     }
   }
   async runOp(op, args, progressToken) {
     let resp;
+    const timeoutMs = opTimeoutMs(op);
     try {
       resp = await fetch(`${this.base}/op`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ op, args: args ?? {}, progressToken }),
-        signal: AbortSignal.timeout(12e4)
+        signal: AbortSignal.timeout(timeoutMs)
       });
     } catch (e) {
+      if (isTimeoutError(e)) throw new BridgeTimeoutError(this.port, timeoutMs, { op });
       throw new BridgeUnreachableError(this.port, e);
     }
     let data;
@@ -1010,7 +1141,7 @@ var HttpClient = class {
       throw new AeError(`Bridge returned non-JSON (HTTP ${resp.status})`);
     }
     if (!data.ok) {
-      throw new AeError(data.error, data.stack, data.line);
+      throw new AeError(data.error, data.stack, data.line, data.code);
     }
     return data.result;
   }
@@ -1192,7 +1323,7 @@ var JobManager = class {
 // src/tools/descriptions.ts
 var descriptions = {
   // ---------- comps ----------
-  list_comps: "All comps: id, name, dims, duration, fps, layer count.",
+  list_comps: "All comps: id, name, dims, duration, fps, layer count. Pass `include` to trim it \u2014 `include: []` returns the id+name map alone, which is all orientation usually needs.",
   get_comp: "Single comp summary by id (no layers).",
   get_comp_tree: "Comp + nested layer tree, recursing pre-comps to `depth`.",
   create_comp: "Create a new comp. Returns id.",
@@ -1200,9 +1331,9 @@ var descriptions = {
   delete_comp: "Delete a comp. Reversible only via AE's Undo.",
   set_active_comp: "Focus a comp in the viewer/timeline.",
   // ---------- layers ----------
-  list_layers: "Layers in a comp, one-line each. Use get_layer_full for details.",
-  get_layer_full: "Full state of one layer: transform + keyframes + expressions, effects, masks, markers, parenting, text/shape/footage extras, and sourceRect (visible bounds). Always prefer over multiple smaller queries.",
-  create_text_layer: "Text layer with optional font/size/color/position. anchorAlign defaults to 'left' so position means the visible left edge.",
+  list_layers: "Layers in a comp, one-line each. Use get_layer_full for details. Pass `include` to trim it \u2014 `include: []` returns just id/index/name/type, the cheapest way to learn what is in a comp.",
+  get_layer_full: "Full state of one layer: transform + keyframes + expressions, effects, masks, markers, parenting, text/shape/footage extras, and sourceRect (visible bounds). Always prefer over multiple smaller queries. Bound the answer on a heavy layer: `include` picks the sections you need, `maxKeyframes` caps the keyframes per property, `shapeDepth` limits the Contents walk. Anything dropped is named and counted in the response, so a bounded read is never mistaken for a complete one.",
+  create_text_layer: "Text layer with optional font/size/color/position/tracking. anchorAlign (default 'left') aligns the text by setting paragraph justification and leaving the anchor at [0,0], so position means the start of the baseline AND stays right when the text is changed later. Tracking is set to 0 unless you pass one, because AE otherwise inherits the user's Character panel. anchorAlign 'none' keeps AE's raw defaults.",
   create_shape_layer: "Empty shape layer; fill via add_shape_content.",
   create_solid_layer: "Solid-color layer. color is RGB 0..1.",
   create_null_layer: "Null parent layer.",
@@ -1213,7 +1344,7 @@ var descriptions = {
   duplicate_layer: "Duplicate a layer N times; each has a fresh id.",
   delete_layer: "Remove a layer.",
   set_layer: "Update layer metadata (name/enabled/locked/shy/solo/3D/blend/label/in-out/stretch/trackMatte). Undefined fields unchanged.",
-  parent_layer: "Set/clear a layer's parent (parentLayerId=null to unparent).",
+  parent_layer: "Set/clear a layer's parent (parentLayerId=null to unparent). The layer stays visually put: AE's own compensation double-counts when the parent was itself re-parented in the same call, so this recomputes the world transform and corrects position/scale/rotation, reporting any correction in `correction`. Read `correction.notes` \u2014 3D layers, cameras and lights are not corrected, and with a keyframed ancestor the fix is only exact at the comp's current time. Pass preserveTransform:false to let the layer jump instead.",
   reorder_layer: "Move layer to 1-based stack index.",
   // ---------- transforms ----------
   set_transform: "Set any of position/scale/rotation/anchorPoint/opacity (+3D orientation/per-axis on 3D). keyframe:true + time sets keyframes.",
@@ -1231,17 +1362,17 @@ var descriptions = {
   clear_expression: "Remove an expression.",
   // ---------- effects ----------
   list_effects: "All effects on a layer with current param values + keyframes/expressions.",
-  add_effect: "Add effect by matchName (use list_available_effects \u2014 matchNames are stable across AE versions; display names aren't).",
+  add_effect: "Add effect by matchName (use list_available_effects \u2014 matchNames are stable across AE versions; display names aren't). A wrong matchName fails immediately and cheaply, so try the standard one (ADBE Gaussian Blur 2, ADBE Slider Control) before searching.",
   remove_effect: "Remove effect by 1-based index.",
   set_effect_param: "Set an effect param by name/matchName. keyframe:true+time for keyframed value.",
   set_effect_enabled: "Toggle an effect on/off without removing.",
-  list_available_effects: "All effects installed in this AE: displayName, matchName, category.",
+  list_available_effects: "Effects installed in this AE: displayName, matchName, category. **Always pass `filter`** to substring-search: the full list is 250-450+ entries and the cost is in returning them, not in reading them, so an unfiltered call takes seconds every time while a filtered one takes a fraction of one (measured on AE 26.3: 446 entries in 3.9s, 22 filtered in 0.17s). `refresh:true` re-reads after installing a plugin; the enumeration is cached per AE session, which is why refresh exists. Never loop over `app.effects` in run_jsx: it is slow enough to block the bridge past its timeout and looks like a crash.",
   // ---------- text ----------
   set_text: "Set text content + styling (font, size, fill/stroke, tracking, leading, justification). Undefined fields unchanged.",
   add_text_animator: "Add a text animator group (position/scale/rotation/opacity/tracking/skew/fillColor/strokeColor). Optional range selector.",
   // ---------- shapes ----------
   set_shape_path: "Replace a shape path with new vertices/tangents/closed.",
-  add_shape_content: "Add shape content under Contents or a sub-group. `content.type` picks the node (rect/ellipse/star/path/fill/stroke/trim/repeater/merge/group); the other keys set its properties by friendly name (e.g. rect: size/position/roundness; fill: color/opacity; stroke: color/width/lineCap; path: vertices/inTangents/outTangents/closed). Unknown or unsettable keys are NOT ignored \u2014 the whole node is rolled back and an error lists them, so trust a success result. Use get_layer_full to see exact property names.",
+  add_shape_content: "Add shape content under Contents or a sub-group. `content.type` picks the node (rect/ellipse/star/path/fill/stroke/trim/repeater/merge/group); the other keys set its properties by friendly name (e.g. rect: size/position/roundness; fill: color/opacity; stroke: color/width/lineCap; path: vertices/inTangents/outTangents/closed). Unknown or unsettable keys are NOT ignored \u2014 the whole node is rolled back and an error lists them, so trust a success result. Use get_layer_full to see exact property names. ORDER MATTERS: index 1 renders in FRONT and each call appends behind the last, so add front-to-back \u2014 details and dots first, big background rects last. `zOrder:'front'` can override that, but it needs an internal moveTo which has disturbed nested renders in AE 26.3, so prefer call order. A reference to one node goes stale once a sibling is added to the same group (add a Stroke and an earlier Fill reference throws 'Object is invalid'): add every node first, then address them by name.",
   set_shape_property: "Set a property on a shape content node. Optional keyframe at time.",
   // ---------- masks ----------
   add_mask: "Add a mask with vertices/tangents/closed/mode.",
@@ -1251,15 +1382,20 @@ var descriptions = {
   add_marker: "Add a marker on a layer (layerId) or on the comp. time + optional duration/comment/label/chapter/url/frameTarget.",
   remove_marker: "Remove a marker by 1-based index.",
   // ---------- vision ----------
-  screenshot_frame: "ONE-OFF visual check of a comp at a time. Base64 PNG. Use only at key moments \u2014 never per-frame or in a loop. For motion, 2-3 snapshots + get_layer_full property values. Set downsample:2 (or 3-4 on 4K comps) to keep the image small \u2014 full-res 4K frames are large enough to exhaust the context. The result reports the dimensions actually returned, and warns if a requested downsample could not be applied.",
-  screenshot_layer: "ONE-OFF visual check of a single layer (solo'd) at a time. Same one-off rule and same downsample guidance as screenshot_frame.",
+  screenshot_frame: "ONE-OFF visual check of a comp at a time. Base64 PNG. Use only at key moments \u2014 never per-frame or in a loop. For motion, 2-3 snapshots + get_layer_full property values. A downsample is chosen from the comp size unless you pass one \u2014 omit it, and pass downsample:1 only when you genuinely need full resolution. The result reports the dimensions actually returned, and warns if a requested downsample could not be applied. Not every result is an image: a 'Stale frame' error means AE re-served an earlier render \u2014 space calls a few seconds apart, retry with a higher downsample, and confirm motion by reading keyframes instead; `empty:true` means every pixel is transparent, so check the time, in/out points and enabled state. Never disable layers to make a frame render.",
+  screenshot_layer: "ONE-OFF visual check of a single layer (solo'd) at a time. Same one-off rule and same downsample guidance as screenshot_frame. The same 'Stale frame' and `empty:true` non-image results apply.",
   // ---------- batch ----------
   run_batch: "Many ops in one ExtendScript pass, one undo step. >500 ops returns a jobId + streams progress; use await_job. transactional:true (default) rolls back on first error.",
   // ---------- explore ----------
-  get_project_summary: "Project state: path, item count, active item, flat item list with type.",
+  get_project_summary: "Project state: path, item count, active item, flat item list with type (comp | footage | solid | folder | unknown \u2014 same vocabulary as a layer's sourceType).",
   find_layers: "Search across one or all comps for layers matching name/type/effect filters.",
   // ---------- raw ----------
-  run_jsx: "Escape hatch: arbitrary ExtendScript in an undo group. `comp`/`app`/`OPS`/helpers in scope. Use `return X` to send a value back; complex AE objects are coerced to plain props.",
+  run_jsx: 'Escape hatch: arbitrary ExtendScript in an undo group. `comp`/`app`/`OPS`/helpers in scope. `return X` sends a value back \u2014 arrays and nested objects come back whole. Anything that cannot be JSON is replaced in place by a marker string, never dropped: `"[function]"`, `"[undefined]"`, `"[circular]"`, `"[max depth]"`, `"[NaN]"`, and live AE objects as `"[CompItem \\"Main\\" #12]"` \u2014 a handle to pass to a real read tool, not a walk of the object. An empty result therefore means the script really returned nothing. AE refuses copyToComp for a layer with a parent or a linked expression while an undo group is open: call `withoutUndoGroup(function(){ \u2026 })` around just that part, or pass undoGroup:false for the whole script (its changes then land as whatever undo steps AE records on its own, not one). Keep loops short \u2014 ExtendScript is single-threaded and freezes the user\'s UI.',
+  // ---------- footage ----------
+  import_footage: "Import a file (video, image, audio, SVG, PSD/AI) into the project. Returns the item id \u2014 pass it to create_footage_layer to place it. Validates what AE actually produced: an SVG whose viewBox asks for one aspect ratio and imports at another is a known AE bug that renders as nothing with no error, so the item is deleted and the call throws with the workaround. `force:true` keeps it and reports the problem in `validation` instead.",
+  create_footage_layer: "Place an imported project item into a comp as a layer. Takes the itemId from import_footage or get_project_summary. For a comp use create_precomp_layer instead.",
+  // ---------- motion graphics templates ----------
+  export_mogrt: "Export a comp as a .mogrt for Premiere. Handles the three things that make a scripted export look like a hung connection: it saves the project first (removes AE's modal save prompt), suppresses the modal font warning that otherwise freezes this connection until someone clicks OK in AE, and runs outside the undo group. `name` defaults to the comp name \u2014 AE's own default is the literal 'Untitled', so every export would otherwise overwrite the same file. Pass `posterTime` to render that frame as the template's thumbnail, replacing the black one AE writes; the export still succeeds if only the thumbnail fails. Needs the project saved once by hand first. `fonts` in the result lists the fonts the template will require \u2014 tell the user, since non-Adobe ones make Premiere flag the template.",
   // ---------- house style ----------
   get_house_style: "The user's palette, type, motion and layout defaults for the project that is open, read from `house-style.md` beside the .aep. Call it once before building anything so your work matches the rest of theirs. `found:false` means none exists yet \u2014 build with sensible defaults and offer to capture one afterwards. Cheap; never a reason to skip.",
   set_house_style: "Write the project's style guide. Replaces the whole file, so read it first and send the merged document \u2014 `overwrite:true` is required to replace an existing one. The project must have been saved at least once, since the file lives beside the .aep. Use the style-guide topic of ae_guide for how to capture a style worth writing down.",
@@ -1274,7 +1410,7 @@ var descriptions = {
   setup_panel: "Install or refresh the After Effects panel and enable the Adobe preference AE needs to load it. Run this when check_setup reports the panel is missing, out of date, or older than what AE is running. It writes to the user's Adobe CEP extensions folder and sets a user-level Adobe preference \u2014 tell the user what it will do before calling it. Prefer running it while AE is CLOSED: the panel then loads when they open it, with no restart. If AE is already open they must quit and reopen it, and until they do, the old panel keeps answering. If the preference was newly enabled, a one-time Mac reboot may also be needed.",
   init_project: "Set up a working folder for one video, series or client: a project brief and a pointer to the house style, written in whichever layout this client reads. Run it when the user is starting out or asks to set up a project. It writes files to disk \u2014 say which folder before calling, and pass `dir` explicitly unless the client already told the server where it is working. It never overwrites anything and reports every path it wrote.",
   // ---------- issue journal ----------
-  list_known_issues: "Problems earlier sessions hit with these tools, with the workarounds that worked. Read it when a tool fails in a way you don't immediately understand \u2014 pass `tool` to narrow it to that one \u2014 and before nontrivial work. It can save you rediscovering a fix that already cost someone an hour. Also returns the repo and server version needed to report one.",
+  list_known_issues: "Problems earlier sessions hit with these tools, with the workarounds that worked. Read it when a tool fails in a way you don't immediately understand \u2014 pass `tool` or `query` to narrow it \u2014 and before nontrivial work. It can save you rediscovering a fix that already cost someone an hour. Returns a one-line index by default; the cause and the workaround are in the entry, so follow up with `id` on anything that looks like your problem. `detail:'full'` dumps every matching entry and is rarely worth it. Also returns the repo and server version needed to report one.",
   log_issue: "Record a problem you hit and the workaround that got past it, so the next session doesn't rediscover it. Log only what cost real effort and will recur: a tool failing for a non-obvious reason, an argument shape the schema didn't imply, AE behaving unlike the docs. Not your own typos, not one-off user mistakes. Call list_known_issues first and reuse the same title to extend an existing entry rather than duplicating it. If the result comes back with reported:false, then AFTER you have finished the actual work, close your reply by telling the user in plain language that something took much longer than it should have and offering to pass it to the people who maintain this tool \u2014 phrase it for a motion designer, in terms of what actually happened, and don't say 'GitHub issue' or 'bug report' unless they say it first.",
   mark_issue_reported: "Record that a journal entry has been sent to the maintainers, with the resulting URL. Call it only once the issue really exists, so later sessions don't ask the user to report the same thing twice."
 };
@@ -1537,6 +1673,8 @@ function debugModeLocation() {
 }
 
 // src/setup/check.ts
+var BRIDGE_PROBE_MS = 2e3;
+var BRIDGE_BUSY_FIX = "This is a timeout, not a refused connection \u2014 something is listening, it just did not answer in time. After Effects is most likely busy running a script, or waiting on a modal dialog nobody has clicked. Wait and run check_setup again, up to about a minute, before restarting anything; it usually clears on its own. On macOS, if the user has switched to another desktop, ask them to switch back to the one After Effects is on.";
 function sha256(file) {
   try {
     return crypto2.createHash("sha256").update(fs5.readFileSync(file)).digest("hex");
@@ -1546,11 +1684,20 @@ function sha256(file) {
 }
 async function bridgeReachable(port) {
   try {
-    const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2e3) });
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(BRIDGE_PROBE_MS)
+    });
     if (!res.ok) return { ok: false, detail: `port ${port} returned HTTP ${res.status}` };
     const body = await res.json().catch(() => ({}));
     return { ok: true, detail: `responding on port ${port}`, bundleHash: body.bundleHash };
   } catch (e) {
+    if (isTimeoutError(e)) {
+      return {
+        ok: false,
+        timedOut: true,
+        detail: `port ${port} accepted the connection but did not answer within ${BRIDGE_PROBE_MS / 1e3}s \u2014 After Effects is probably busy`
+      };
+    }
     return { ok: false, detail: `no response on port ${port} (${e.message})` };
   }
 }
@@ -1620,7 +1767,7 @@ async function checkSetup() {
     name: "bridgeReachable",
     ok: bridge.ok,
     detail: bridge.detail,
-    fix: bridge.ok ? void 0 : "If the other checks pass, restart After Effects so the panel reloads."
+    fix: bridge.ok ? void 0 : bridge.timedOut ? BRIDGE_BUSY_FIX : "If the other checks pass, restart After Effects so the panel reloads."
   });
   if (bridge.ok && source) {
     const assessment = assessPanel(bridge.bundleHash, sha256(path6.join(installed, "jsx", "bundle.jsx")), {
@@ -1643,14 +1790,24 @@ async function checkSetup() {
     });
   }
   const ready = checks.every((c) => c.ok);
-  return { ready, checks, nextSteps: buildNextSteps(checks, ready) };
+  return { ready, checks, nextSteps: buildNextSteps(checks, ready, bridge.timedOut === true) };
 }
-function buildNextSteps(checks, ready) {
+function buildNextSteps(checks, ready, bridgeTimedOut = false) {
   if (ready) return ["Everything is connected. After Effects is ready to drive."];
   const by = (name) => checks.find((c) => c.name === name);
   const steps = [];
   if (by("platform")?.ok === false) return [by("platform").fix];
   if (by("panelAssetsPresent")?.ok === false) return [by("panelAssetsPresent").fix];
+  const installSound = by("panelInstalled")?.ok !== false && by("panelUpToDate")?.ok !== false && by("panelDependencies")?.ok !== false && by("cepDebugMode")?.ok !== false;
+  if (bridgeTimedOut && installSound) {
+    return [
+      "Wait \u2014 do not restart anything yet. The panel is answering its port but is too busy to reply, which almost always means After Effects is still running a script.",
+      "Run check_setup again in about ten seconds, and keep checking for up to a minute. It usually clears on its own.",
+      "While waiting, ask the user to look at After Effects: a dialog it is waiting on (unsaved project, missing fonts) blocks it the same way and may be hidden behind another window.",
+      "On macOS, if they have moved to a different desktop, ask them to switch back to the one After Effects is on.",
+      "Only if it is still not answering after a minute should you treat it as disconnected and quit and reopen After Effects."
+    ];
+  }
   const brokenInstall = by("panelUpToDate")?.ok === false || by("panelDependencies")?.ok === false;
   const needsInstall = by("panelInstalled")?.ok === false || brokenInstall;
   const needsDebug = by("cepDebugMode")?.ok === false;
@@ -1772,12 +1929,12 @@ var GUIDES = [
   {
     name: "ae-setup",
     description: "Diagnose and repair the connection between the AE MCP tools and After Effects \u2014 panel not installed, AE not running, Adobe debug preference off, bridge not responding. Load when an After Effects tool reports it cannot reach AE, or when the user is setting this up for the first time.",
-    body: "# Getting After Effects connected\n\nThe tools talk to a small panel that runs **inside** After Effects. Three things must be true for that to work: the panel is installed, Adobe is willing to load it, and AE is open.\n\nAssume the person you are helping is a motion designer, not a developer. They should never need to open a terminal \u2014 you have tools for all of this.\n\n## Always start with check_setup\n\n`check_setup` is read-only and safe to call at any time. It returns a `checks` array and a `nextSteps` list already written in plain language.\n\n**Relay `nextSteps` to the user directly.** Do not paraphrase it into jargon, and do not invent steps it did not mention.\n\n## Install before they open After Effects, if you still can\n\nThe panel loads at launch and only at launch. So the order matters, and it is\nthe opposite of what people assume:\n\n- **After Effects is closed** \u2014 install now. When they open it, the panel is\n  simply there. No restart, nothing to ask for. This is the good path, and on a\n  first-time setup you can usually get it.\n- **After Effects is open** \u2014 install, then they have to quit and reopen it.\n  Unavoidable, but worth avoiding: if they have not opened AE yet in this\n  conversation, do the install *first* and tell them to open it after.\n\n`check_setup` reports `afterEffectsRunning`, so you always know which case you\nare in before you say anything.\n\n## The repair path\n\n1. **`check_setup`** \u2014 find out what is actually wrong.\n2. **`setup_panel`** \u2014 if the panel is missing or out of date. Tell the user what it will do *before* you call it: it copies the panel into their Adobe extensions folder and switches on the Adobe preference that permits unsigned panels. Both changes are user-level and reversible.\n3. **Get the panel loaded.** If AE was closed, ask them to open it. If it was already open, ask them to quit and reopen it. You cannot do either for them.\n4. **`check_setup`** again to confirm.\n\n## What the individual failures mean\n\n| Check | Meaning when it fails |\n|---|---|\n| `platform` | Not macOS or Windows. After Effects only runs on those two, so there is nothing to fix. |\n| `panelAssetsPresent` | The server package is incomplete \u2014 it needs reinstalling. |\n| `cepDebugMode` | Adobe refuses to load unsigned panels until this preference is on. `setup_panel` sets it. |\n| `panelInstalled` | The panel is not in the Adobe extensions folder yet. `setup_panel` installs it. |\n| `panelUpToDate` | The files on disk are older than this server. Run `setup_panel`. |\n| `panelRunningCurrent` | AE is *running* an older panel than these tools ship. This is the one that predicts whether calls will actually work \u2014 `panelUpToDate` can pass while this fails, for the whole window between installing an update and restarting AE. |\n| `afterEffectsRunning` | AE is closed. If the panel also needs installing, install it now and then ask them to open AE \u2014 that saves a restart. |\n| `bridgeReachable` | Everything is installed but the panel isn't answering \u2014 almost always fixed by restarting AE. |\n\n## The reboot case\n\n`cepDebugMode` is an Adobe preference that, on some macOS builds, only takes effect after a **restart of the Mac** \u2014 not just of After Effects. If `setup_panel` reports `rebootRecommended: true` and restarting AE alone did not fix it, ask the user to reboot once. This is a one-time cost, never needed again.\n\n## When a tool says the panel is out of date\n\nYou may get an error saying the panel is older than these tools, or that it does\nnot recognise an op. That is a version mismatch, not a broken tool, and the\nmessage tells you which of the two fixes applies:\n\n- **\"updated on disk \u2026 still running the previous version\"** \u2014 `setup_panel` has\n  already done its part. Only a restart of After Effects will help; running it\n  again will not.\n- **anything else** \u2014 run `setup_panel`, then get AE restarted.\n\nEither way, do not retry the failed call until the user confirms AE has\nrestarted. Say it as a version mismatch in plain language, not as a failure:\ntheir tools moved ahead of the panel, and it takes a restart to catch up.\n\n## If it still will not connect\n\nAsk the user to open **Window > Extensions > AE MCP Bridge** inside After Effects. That panel shows its own status and a log, and will say whether it started, which port it took, or what error it hit. Have them read it back to you.\n\nA common cause is a stale install: the panel loaded an older script bundle than the server expects. `check_setup`'s `panelUpToDate` catches that \u2014 the fix is `setup_panel` followed by an AE restart."
+    body: '# Getting After Effects connected\n\nThe tools talk to a small panel that runs **inside** After Effects. Three things must be true for that to work: the panel is installed, Adobe is willing to load it, and AE is open.\n\nAssume the person you are helping is a motion designer, not a developer. They should never need to open a terminal \u2014 you have tools for all of this.\n\n## Always start with check_setup\n\n`check_setup` is read-only and safe to call at any time. It returns a `checks` array and a `nextSteps` list already written in plain language.\n\n**Relay `nextSteps` to the user directly.** Do not paraphrase it into jargon, and do not invent steps it did not mention.\n\n## A timeout is not a disconnection\n\nBefore you start any repair, check which failure you actually have. "The panel did not answer within N seconds" and "cannot reach the panel" are opposite diagnoses:\n\n- **Did not answer** \u2014 something is listening; it is just too busy to reply. After Effects is single-threaded, so a long script or a modal dialog waiting for a click blocks it completely. Nothing is broken and nothing needs installing.\n- **Cannot reach** \u2014 nothing is listening. That is the case the repair path below is for.\n\nOn a timeout, `check_setup` says so itself: `bridgeReachable` reports that the port accepted the connection but did not answer in time, and `nextSteps` tells you to wait. Follow it. Re-running `setup_panel` or restarting After Effects here costs the user their work-in-progress for nothing, and both are the wrong move. Poll `check_setup` for about a minute; it usually clears on its own.\n\nTwo things to ask about while waiting: whether a dialog is sitting behind another window in After Effects, and \u2014 on macOS \u2014 whether they have switched to another desktop. Calls have been reported to stall while the user is on a different Space and to complete as soon as they come back.\n\n## Install before they open After Effects, if you still can\n\nThe panel loads at launch and only at launch. So the order matters, and it is\nthe opposite of what people assume:\n\n- **After Effects is closed** \u2014 install now. When they open it, the panel is\n  simply there. No restart, nothing to ask for. This is the good path, and on a\n  first-time setup you can usually get it.\n- **After Effects is open** \u2014 install, then they have to quit and reopen it.\n  Unavoidable, but worth avoiding: if they have not opened AE yet in this\n  conversation, do the install *first* and tell them to open it after.\n\n`check_setup` reports `afterEffectsRunning`, so you always know which case you\nare in before you say anything.\n\n## The repair path\n\n1. **`check_setup`** \u2014 find out what is actually wrong.\n2. **`setup_panel`** \u2014 if the panel is missing or out of date. Tell the user what it will do *before* you call it: it copies the panel into their Adobe extensions folder and switches on the Adobe preference that permits unsigned panels. Both changes are user-level and reversible.\n3. **Get the panel loaded.** If AE was closed, ask them to open it. If it was already open, ask them to quit and reopen it. You cannot do either for them.\n4. **`check_setup`** again to confirm.\n\n## What the individual failures mean\n\n| Check | Meaning when it fails |\n|---|---|\n| `platform` | Not macOS or Windows. After Effects only runs on those two, so there is nothing to fix. |\n| `panelAssetsPresent` | The server package is incomplete \u2014 it needs reinstalling. |\n| `cepDebugMode` | Adobe refuses to load unsigned panels until this preference is on. `setup_panel` sets it. |\n| `panelInstalled` | The panel is not in the Adobe extensions folder yet. `setup_panel` installs it. |\n| `panelUpToDate` | The files on disk are older than this server. Run `setup_panel`. |\n| `panelRunningCurrent` | AE is *running* an older panel than these tools ship. This is the one that predicts whether calls will actually work \u2014 `panelUpToDate` can pass while this fails, for the whole window between installing an update and restarting AE. |\n| `afterEffectsRunning` | AE is closed. If the panel also needs installing, install it now and then ask them to open AE \u2014 that saves a restart. |\n| `bridgeReachable` | Everything is installed but the panel isn\'t answering. Read the detail: if the port **timed out**, After Effects is busy and you should wait, not restart. If nothing is listening at all, restarting AE almost always fixes it. |\n\n## The reboot case\n\n`cepDebugMode` is an Adobe preference that, on some macOS builds, only takes effect after a **restart of the Mac** \u2014 not just of After Effects. If `setup_panel` reports `rebootRecommended: true` and restarting AE alone did not fix it, ask the user to reboot once. This is a one-time cost, never needed again.\n\n## When a tool says the panel is out of date\n\nYou may get an error saying the panel is older than these tools, or that it does\nnot recognise an op. That is a version mismatch, not a broken tool, and the\nmessage tells you which of the two fixes applies:\n\n- **"updated on disk \u2026 still running the previous version"** \u2014 `setup_panel` has\n  already done its part. Only a restart of After Effects will help; running it\n  again will not.\n- **anything else** \u2014 run `setup_panel`, then get AE restarted.\n\nEither way, do not retry the failed call until the user confirms AE has\nrestarted. Say it as a version mismatch in plain language, not as a failure:\ntheir tools moved ahead of the panel, and it takes a restart to catch up.\n\n## If it still will not connect\n\nAsk the user to open **Window > Extensions > AE MCP Bridge** inside After Effects. That panel shows its own status and a log, and will say whether it started, which port it took, or what error it hit. Have them read it back to you.\n\nA common cause is a stale install: the panel loaded an older script bundle than the server expects. `check_setup`\'s `panelUpToDate` catches that \u2014 the fix is `setup_panel` followed by an AE restart.'
   },
   {
     name: "after-effects",
     description: "How to drive Adobe After Effects well through the AE MCP tools \u2014 orienting in a project, building and animating layers, keyframes and easing, expressions, effects, text and shapes, and the gotchas that silently produce wrong output. Load whenever a task involves After Effects, motion graphics, comps, layers, or keyframes.",
-    body: '# Driving After Effects\n\nYou have direct control of a live After Effects session. The user sees every change immediately, and every tool call is a real undo step in their project. Work like a motion designer at the keyboard, not like a script that fires blind.\n\n## Read the house style first\n\n`get_house_style` returns the style guide for the project that is currently open\n\u2014 palette, type, motion defaults, layout rules \u2014 read from `house-style.md`\nsitting next to the `.aep` file. Call it once at the start of any build task and\nfollow what it says. It costs one cheap call and it is the difference between\nwork that matches everything else the user has made and work that does not.\n\nIf it reports `found: false`, build with sensible defaults and offer once, at the\nend, to capture a style guide from what you just made. Don\'t nag about it.\n\n## Orient before you touch anything\n\nNever guess at project state. Cheap reads exist for exactly this:\n\n| Question | Tool |\n|---|---|\n| What\'s in this project? | `get_project_summary` |\n| What comps exist? | `list_comps` |\n| What\'s in this comp? | `get_comp_tree` |\n| Everything about one layer | `get_layer_full` \u2B50 |\n| Where is a layer, by name/type/effect? | `find_layers` |\n\n`get_layer_full` is the one to reach for. It returns transforms **with their keyframes and expressions**, effects with every parameter, masks, markers, and `sourceRect` (the layer\'s visible bounds) in a single call. Prefer one `get_layer_full` over four narrow queries \u2014 it is faster and it shows you context you did not know to ask for.\n\n## Identify things by ID, never by index\n\nEvery comp and layer has a stable numeric `id`. Layer `index` is a 1-based position that **shifts whenever layers are added, deleted, or reordered**. Store `(compId, layerId)` and pass those. An index captured before a `create_*` call may point at a different layer by the time you use it.\n\n## Read, then write, then verify\n\n1. Read the current state (`get_layer_full`).\n2. Make the change.\n3. Verify by reading back the properties \u2014 not by screenshotting.\n\nProperty values are the ground truth. A screenshot tells you something *looks* wrong; `get_layer_full` tells you *why*.\n\n## Screenshots are a diagnostic, not a feedback loop\n\n`screenshot_frame` and `screenshot_layer` are **one-off checks**. Do not screenshot every frame, do not scrub through time, do not screenshot after every edit.\n\n- Take at most 2\u20133 across an animation \u2014 typically start, middle, end.\n- **Always pass `downsample`** on large comps: `2` for 1080p, `3`\u2013`4` for 4K. A full-resolution 4K frame is large enough to blow out your context in one call.\n- The result reports the dimensions actually returned and warns if the downsample could not be applied \u2014 trust those numbers rather than assuming.\n\nTo check motion, read the keyframe values. That is exact; a picture is not.\n\n## Bulk work goes through run_batch\n\nBuilding 40 layers with 40 separate calls is slow and produces 40 undo steps. `run_batch` runs many ops in one ExtendScript pass as a **single undo step**, which is also what the user expects when they ask to undo "that thing you just built".\n\n- `transactional: true` (the default) rolls back the whole batch on the first error.\n- Over 500 ops it returns a `jobId` and streams progress; call `await_job(jobId)` for the final result.\n\n## Keyframes and easing\n\n`add_keyframe` sets a value at a time. Interpolation is separate:\n\n- `set_interpolation` \u2014 linear / bezier / hold, per keyframe, in and out.\n- `set_temporal_ease` \u2014 influence and speed, the "easy ease" controls.\n- `set_spatial_tangents` \u2014 the shape of a motion path through a position keyframe.\n\n**The array-size trap.** `set_temporal_ease` wants one ease entry *per dimension* for ordinary multi-dimensional properties (Scale, Color), but exactly **one** entry for spatial properties (Position, Anchor Point) regardless of whether the layer is 2D or 3D \u2014 because the ease applies along the motion path, not per axis. If you see `Value array does not have 1 elements`, you fed a spatial property one entry per axis.\n\n## Expressions\n\n`set_expression` takes a `propertyPath` such as `["Transform","Position"]` or `["Effects","Gaussian Blur","Blurriness"]`. Expressions are ExtendScript-flavoured JavaScript evaluated by AE per frame.\n\nExpressions are usually a better answer than dense keyframes for anything procedural \u2014 wiggle, loops, counters, follow-through, time remapping. They stay editable by the user afterwards, where a wall of baked keyframes does not.\n\nUse `get_expression` to read one back and `toggle_expression` to disable without deleting.\n\n## Effects\n\nEffects are added by **matchName**, not display name: `add_effect({matchName: "ADBE Gaussian Blur 2"})`. If you do not know a matchName, call `list_available_effects` and search it \u2014 do not guess. `list_effects` shows what is already on a layer, with every parameter.\n\nSet parameters with `set_effect_param` by parameter name (e.g. `"Blurriness"`).\n\n## Text\n\n`create_text_layer` places **point text anchored at the bounding-box centre**, which is not where you would expect from the visible left edge. The tool defaults to `anchorAlign: "left"` so that `position` lines up with the left edge as a designer would read it. Pass `"center"` or `"right"` when you want those, `"none"` for AE\'s raw behaviour.\n\n`set_text` controls font, size, colour, tracking, leading and justification. To auto-fit a background to text, read `sourceRect` from `get_layer_full` and size the shape from its width and height plus padding.\n\n## Shapes\n\n`add_shape_content` builds one node at a time under `Contents` \u2014 `rect`, `ellipse`, `star`, `path`, `fill`, `stroke`, `trim`, `repeater`, `merge`, `group`. Properties are set with friendly names in the same call (`size`, `position`, `roundness`, `color`, `width`, `lineCap`, \u2026).\n\nThis tool is **all-or-nothing**: if a key cannot be applied, the whole node is removed and you get an error naming the bad key. A success result therefore means everything landed. Don\'t add defensive re-reads for it, but do read the error carefully \u2014 it usually means the property is named differently on that node type, and `get_layer_full` will show you the real name.\n\nFor a custom path, use `{type: "path", vertices: [[x,y], \u2026], closed: true}`. The key is `vertices`, not `points`.\n\n## The escape hatch\n\n`run_jsx` executes arbitrary ExtendScript with `app`, `comp`, `OPS` and the helper functions in scope. Reach for it when a needed operation has no tool \u2014 duplicating a comp, driving the render queue, batch-renaming.\n\nTwo warnings: ExtendScript is **single-threaded**, so a long synchronous loop freezes the user\'s AE UI; and returned objects are flattened, so return a string you have assembled yourself rather than a nested object.\n\n## When something costs you real time\n\nThese tools have rough edges, and the same ones catch every session. Two tools\nexist so that each one is only paid for once.\n\n**`list_known_issues`** \u2014 what earlier sessions hit and how they got past it.\nRead it when a tool fails in a way you do not immediately understand, before you\nstart guessing. The answer is often already there.\n\n**`log_issue`** \u2014 write down what you worked out, the moment you work it out.\n\nLog something when all three are true: it cost real effort, it was the tool\'s\nfault rather than yours, and the next session would hit it too. A schema that\naccepts an argument AE then rejects, an error message that names the wrong\nthing, a property whose real name is nothing like its display name. Not your own\ntypos. Not "I forgot the layer was 3D".\n\nWrite the entry for someone who has not seen the failure: the exact error text,\nthe call that produced it, and a workaround concrete enough to apply directly.\nReuse the existing title when you are extending an entry \u2014 that keeps one good\nrecord instead of five thin ones.\n\n### Then offer to pass it on\n\nIf `log_issue` comes back with `reported: false`, mention it to the user \u2014 but\nfinish the actual work first, and put it at the very end, after you have told\nthem what you built. It is a footnote, not the headline.\n\nSay it the way you would to a colleague who does not write code. What you were\ntrying to do, that it fought back, that you got there anyway, and that you can\nsend it to the people who maintain the tool so the next person does not lose the\nsame time. Something like:\n\n> Done \u2014 the lower third is in. One thing worth mentioning: getting the ease\n> onto that position keyframe took a lot longer than it should have, because the\n> tool kept rejecting a value it had just asked for. I found a way around it and\n> made a note. Want me to send it to the people who maintain this so they can\n> fix it properly?\n\nDo not say "GitHub issue", "file a bug" or "open a ticket" unless they say it\nfirst. If they say yes, use the **report-ae-issue** prompt this server provides\n(`/report-ae-issue` where your client exposes prompts as commands) \u2014 it handles\nthe rest. If they say no, drop it; the note stays and can be offered again\nanother time.\n\nNever claim you have reported something you have not.\n\n## When something is not connected\n\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay its `nextSteps` to the user in plain language. Do not try to diagnose CEP by hand.'
+    body: '# Driving After Effects\n\nYou have direct control of a live After Effects session. The user sees every change immediately, and every tool call is a real undo step in their project. Work like a motion designer at the keyboard, not like a script that fires blind.\n\n## Read the house style first\n\n`get_house_style` returns the style guide for the project that is currently open\n\u2014 palette, type, motion defaults, layout rules \u2014 read from `house-style.md`\nsitting next to the `.aep` file. Call it once at the start of any build task and\nfollow what it says. It costs one cheap call and it is the difference between\nwork that matches everything else the user has made and work that does not.\n\nIf it reports `found: false`, build with sensible defaults and offer once, at the\nend, to capture a style guide from what you just made. Don\'t nag about it.\n\n## Orient before you touch anything\n\nNever guess at project state. Cheap reads exist for exactly this:\n\n| Question | Tool |\n|---|---|\n| What\'s in this project? | `get_project_summary` |\n| What comps exist? | `list_comps` |\n| What\'s in this comp? | `get_comp_tree` |\n| Everything about one layer | `get_layer_full` \u2B50 |\n| Where is a layer, by name/type/effect? | `find_layers` |\n\n`get_layer_full` is the one to reach for. It returns transforms **with their keyframes and expressions**, effects with every parameter, masks, markers, and `sourceRect` (the layer\'s visible bounds) in a single call. Prefer one `get_layer_full` over four narrow queries \u2014 it is faster and it shows you context you did not know to ask for.\n\n### Ask for what you need\n\nA tool result stays in your context for the rest of the session, so a read you cannot bound is paid for on every later call. All of these reads take an `include` list:\n\n- `list_comps` / `list_layers` with `include: []` return the id-to-name map alone, which is what orientation actually needs.\n- `get_layer_full` takes `include` (`transform`, `effects`, `masks`, `markers`, `bounds`, `text`, `shape`, `source`), plus `maxKeyframes` to cap the keyframes per property and `shapeDepth` to limit the Contents walk on a heavy shape layer.\n\nOmit them all and you get everything, as before. Whatever they leave out is named and counted in the response \u2014 a bounded read never looks like a complete one.\n\n## Identify things by ID, never by index\n\nEvery comp and layer has a stable numeric `id`. Layer `index` is a 1-based position that **shifts whenever layers are added, deleted, or reordered**. Store `(compId, layerId)` and pass those. An index captured before a `create_*` call may point at a different layer by the time you use it.\n\nThe same trap bites inside `run_jsx`: a `comp.layer(1)` wrapper is index-bound, not a handle. After a `copyToComp` inserts the copy at index 1, a reference you took earlier silently resolves to the *new* layer \u2014 which is how a script ends up parenting a layer to itself. Re-resolve by id or name after anything that inserts a layer.\n\n## Read, then write, then verify\n\n1. Read the current state (`get_layer_full`).\n2. Make the change.\n3. Verify by reading back the properties \u2014 not by screenshotting.\n\nProperty values are the ground truth. A screenshot tells you something *looks* wrong; `get_layer_full` tells you *why*.\n\n## Screenshots are a diagnostic, not a feedback loop\n\n`screenshot_frame` and `screenshot_layer` are **one-off checks**. Do not screenshot every frame, do not scrub through time, do not screenshot after every edit.\n\n- Take at most 2\u20133 across an animation \u2014 typically start, middle, end.\n- **The `downsample` is picked from the comp size** unless you pass one \u2014 2 at 1080p, 3 at 4K, aiming at a long edge around 1280px. Pass `downsample: 1` only when you genuinely need full resolution: a full 4K frame is large enough to blow out your context in one call.\n- The result reports the dimensions actually returned and the factor actually applied \u2014 trust those numbers rather than assuming.\n- **Space them out.** Rapid back-to-back requests are far more likely to come back stale than requests a few seconds apart.\n\nTwo results are not images, and both are information rather than something to retry blindly:\n\n- **`Stale frame` (an error)** \u2014 After Effects returned the pixels it had already rendered for a *different* request, which the error names. Pause a few seconds and retry with a higher `downsample`; `6` has worked where `3`\u2013`4` stayed stale. If it repeats, read the keyframes instead.\n- **`empty: true`** \u2014 every pixel at that time is fully transparent, so no image was sent. That is a fact about the composition: usually the wrong time, a layer outside its in/out points, disabled, or at zero opacity.\n\n**Never disable layers to make a screenshot render.** A frame that will not render is a limit of the panel\'s render path, not project content that needs fixing \u2014 and it is very easy to leave someone\'s comp switched off afterwards.\n\nTo check motion, read the keyframe values. That is exact; a picture is not.\n\n## Bulk work goes through run_batch\n\nBuilding 40 layers with 40 separate calls is slow and produces 40 undo steps. `run_batch` runs many ops in one ExtendScript pass as a **single undo step**, which is also what the user expects when they ask to undo "that thing you just built".\n\n- `transactional: true` (the default) rolls back the whole batch on the first error.\n- Over 500 ops it returns a `jobId` and streams progress; call `await_job(jobId)` for the final result.\n\n## Keyframes and easing\n\n`add_keyframe` sets a value at a time. Interpolation is separate:\n\n- `set_interpolation` \u2014 linear / bezier / hold, per keyframe, in and out.\n- `set_temporal_ease` \u2014 influence and speed, the "easy ease" controls.\n- `set_spatial_tangents` \u2014 the shape of a motion path through a position keyframe.\n\n**The array-size trap.** `set_temporal_ease` wants one ease entry *per dimension* for ordinary multi-dimensional properties (Scale, Color), but exactly **one** entry for spatial properties (Position, Anchor Point) regardless of whether the layer is 2D or 3D \u2014 because the ease applies along the motion path, not per axis. If you see `Value array does not have 1 elements`, you fed a spatial property one entry per axis.\n\n## Expressions\n\n`set_expression` takes a `propertyPath` such as `["Transform","Position"]` or `["Effects","Gaussian Blur","Blurriness"]`. Expressions are ExtendScript-flavoured JavaScript evaluated by AE per frame.\n\nExpressions are usually a better answer than dense keyframes for anything procedural \u2014 wiggle, loops, counters, follow-through, time remapping. They stay editable by the user afterwards, where a wall of baked keyframes does not.\n\nUse `get_expression` to read one back and `toggle_expression` to disable without deleting.\n\n## Effects\n\nEffects are added by **matchName**, not display name: `add_effect({matchName: "ADBE Gaussian Blur 2"})`. If you do not know a matchName, call `list_available_effects({filter: "blur"})` \u2014 do not guess. `list_effects` shows what is already on a layer, with every parameter.\n\nSet parameters with `set_effect_param` by parameter name (e.g. `"Blurriness"`).\n\n**Never enumerate `app.effects` yourself in `run_jsx`.** There are around 250 of them and reading the table is slow enough to block the bridge past its timeout, which looks exactly like a crash and costs a minute of everyone\'s time. `list_available_effects` does the same enumeration once and caches it for the session, so `filter` searches are free after the first call. A wrong matchName also fails instantly and clearly, so trying `ADBE Slider Control` is cheaper than searching for it.\n\n## Text\n\n`create_text_layer` defaults to `anchorAlign: "left"`, which sets **paragraph justification** and leaves the anchor point at `[0,0]`, so `position` is the start of the first baseline. Pass `"center"` or `"right"` for those, `"none"` for AE\'s raw behaviour. Because the alignment is justification rather than a measured offset, it stays correct when the text changes later \u2014 retyped, driven by an expression, or edited through Essential Graphics in Premiere. Never "fix" alignment by writing an anchor point computed from `sourceRectAtTime()`: it is right once and wrong from the next edit onward.\n\nTracking is set to `0` unless you pass one, because AE\'s `addText()` otherwise inherits whatever the user\'s Character panel was last left on.\n\n`set_text` controls font, size, colour, tracking, leading and justification. To auto-fit a background to text, read `sourceRect` from `get_layer_full` and size the shape from its width and height plus padding.\n\n## Shapes\n\n`add_shape_content` builds one node at a time under `Contents` \u2014 `rect`, `ellipse`, `star`, `path`, `fill`, `stroke`, `trim`, `repeater`, `merge`, `group`. Properties are set with friendly names in the same call (`size`, `position`, `roundness`, `color`, `width`, `lineCap`, \u2026).\n\nThis tool is **all-or-nothing**: if a key cannot be applied, the whole node is removed and you get an error naming the bad key. A success result therefore means everything landed. Don\'t add defensive re-reads for it, but do read the error carefully \u2014 it usually means the property is named differently on that node type, and `get_layer_full` will show you the real name.\n\nFor a custom path, use `{type: "path", vertices: [[x,y], \u2026], closed: true}`. The key is `vertices`, not `points`.\n\n**Render order is the opposite of the layer stack.** Inside `Contents`, index 1 renders in *front*, and each `add_shape_content` call appends behind the previous one. So build **front-to-back**: details, text plates and traffic-light dots first, the big background rectangle last. Getting it backwards is silent \u2014 no error, just a solid slab where your artwork should be. `zOrder: "front"` will place a node at index 1 for you, but it needs an internal `moveTo`, which has been seen to disturb *nested* renders of the comp in AE 26.3; prefer ordering your calls. If an existing layer is already in the wrong order, rebuild it rather than reordering, and verify with a screenshot of a comp that **nests** it, not just the comp that owns it.\n\n**Node references go stale.** Adding a sibling to a group invalidates a reference you already hold to another node in it \u2014 add a Stroke and an earlier Fill reference starts throwing `Object is invalid`. Add every node first, then set values and expressions by addressing nodes by name.\n\n## The escape hatch\n\n`run_jsx` executes arbitrary ExtendScript with `app`, `comp`, `OPS` and the helper functions in scope. Reach for it when a needed operation has no tool \u2014 duplicating a comp, driving the render queue, batch-renaming.\n\nExtendScript is **single-threaded**, so a long synchronous loop freezes the user\'s AE UI. Keep the script short.\n\n`return X` sends the whole value back \u2014 arrays and nested objects included. Values that cannot be represented (functions, live AE objects, cycles) come back as a marker string in place, never dropped \u2014 a live object as `"[AVLayer \\"Hero\\" #616]"`, which is a handle to pass to `get_layer_full`, not a copy of the layer. So an empty result genuinely means the script returned nothing; never read one as "nothing happened".\n\nAE refuses `copyToComp` for a layer with a parent or a linked expression **while an undo group is open**, which is exactly the rig you wanted to copy. Wrap that one call in `withoutUndoGroup(function () { \u2026 })`, or pass `undoGroup: false` for the whole script. Nothing rolls back on error, so a script that fails halfway leaves its earlier changes applied \u2014 read the state back before re-running one that mutates.\n\nSet the parent first and the transform after, never the reverse. `parent_layer` keeps the layer where it is; raw `layer.parent = x` inside a script does not do so reliably two levels deep, so after scripted parenting audit scale and rotation as well as position.\n\n### Exporting a Motion Graphics template\n\nUse **`export_mogrt`**. Do not drive `comp.exportAsMotionGraphicsTemplate` from `run_jsx` \u2014 the tool exists because that call raises modal dialogs, and a modal dialog freezes this whole connection until someone clicks it in After Effects.\n\n`export_mogrt` handles all of it: it saves the project first (which is what removes AE\'s "the project needs to be saved" prompt, and it has to happen per export because exporting dirties the project again), it suppresses the font warning, and it runs outside the undo group so there is no "undo group mismatch" afterwards. Measured on 26.3: suppressed, an export of a comp using a non-Adobe font returns in about three seconds; unsuppressed, the same export sat past sixty and wrote nothing until the dialog was clicked.\n\nThree things worth knowing before you call it:\n\n- **The project must have been saved once, by hand.** There is no folder to save into otherwise, and the tool refuses rather than raising a dialog the user was not expecting.\n- **`name` is the filename.** It defaults to the comp name, because AE\'s own default is the literal `Untitled` \u2014 leave it to AE and every template in the project overwrites the same file.\n- **`fonts` in the result lists what the template will require.** Tell the user about any non-Adobe ones: Premiere flags the template as needing fonts it cannot supply, and that is worth hearing from you rather than discovering later.\n\n**The thumbnail.** AE writes the comp\'s *first frame* into the template, so anything that fades up from nothing gets a black one. Pass `posterTime` with a moment that actually shows the design and it is rendered and swapped in. If only the thumbnail fails the export still succeeds \u2014 check `thumbnail.patched` in the result.\n\nAlso note that `comp.setMotionGraphicsControllerName(index, \u2026)` numbers controllers in **reverse order of addition**: index 1 is the one you added last.\n\n**If any long call seems to have hung, assume a dialog before you assume a crash** \u2014 it may be behind another window. `comp.saveFrameToPng(...)` from `run_jsx` raises the save prompt the same way; use `screenshot_frame`, which does not.\n\n### Importing footage, and the SVG trap\n\nUse **`import_footage`**, then **`create_footage_layer`** to place the item in a comp. (For a comp as a layer, `create_precomp_layer`.)\n\n`import_footage` checks what AE actually produced, because one case fails silently: an SVG with a very large `viewBox` (say `0 0 278050 333334`) imports with **fabricated dimensions and renders as nothing**, no error at any stage. Verified on 26.3 \u2014 that viewBox yields a 15906x5654 item that will not even rasterize. The tool compares the aspect ratio the file asks for against the one AE produced, and on a mismatch it deletes the item and throws, rather than handing you an asset that looks healthy in the project panel and renders empty.\n\nIf you hit that, the workarounds are:\n\n- **Simple flat SVGs** \u2014 rebuild the path as a shape layer with the real vertices, scaled down to a sane coordinate space (divide by `333.334` for a 1000px version), set the fill from the SVG, and set `ADBE Vector Fill Rule` to `2` when the SVG says `fill-rule="evenodd"`. Done this way the result is pixel-accurate.\n- **Complex SVGs** \u2014 rasterise to PNG outside AE, or normalise the `viewBox` to a small coordinate space before importing.\n\n`force: true` keeps the item and reports the problem in `validation` instead of throwing. It is for when you know the dimensions are wrong and want it anyway \u2014 not a way past the error.\n\n## When something costs you real time\n\nThese tools have rough edges, and the same ones catch every session. Two tools\nexist so that each one is only paid for once.\n\n**`list_known_issues`** \u2014 what earlier sessions hit and how they got past it.\nRead it when a tool fails in a way you do not immediately understand, before you\nstart guessing. The answer is often already there. It comes back as a one-line\nindex, so open the entry that looks like your failure with\n`list_known_issues({id})` \u2014 the cause and the workaround are in the entry, not in\nthe index. `tool` and `query` narrow it further.\n\n**`log_issue`** \u2014 write down what you worked out, the moment you work it out.\n\nLog something when all three are true: it cost real effort, it was the tool\'s\nfault rather than yours, and the next session would hit it too. A schema that\naccepts an argument AE then rejects, an error message that names the wrong\nthing, a property whose real name is nothing like its display name. Not your own\ntypos. Not "I forgot the layer was 3D".\n\nWrite the entry for someone who has not seen the failure: the exact error text,\nthe call that produced it, and a workaround concrete enough to apply directly.\nReuse the existing title when you are extending an entry \u2014 that keeps one good\nrecord instead of five thin ones.\n\n### Then offer to pass it on\n\nIf `log_issue` comes back with `reported: false`, mention it to the user \u2014 but\nfinish the actual work first, and put it at the very end, after you have told\nthem what you built. It is a footnote, not the headline.\n\nSay it the way you would to a colleague who does not write code. What you were\ntrying to do, that it fought back, that you got there anyway, and that you can\nsend it to the people who maintain the tool so the next person does not lose the\nsame time. Something like:\n\n> Done \u2014 the lower third is in. One thing worth mentioning: getting the ease\n> onto that position keyframe took a lot longer than it should have, because the\n> tool kept rejecting a value it had just asked for. I found a way around it and\n> made a note. Want me to send it to the people who maintain this so they can\n> fix it properly?\n\nDo not say "GitHub issue", "file a bug" or "open a ticket" unless they say it\nfirst. If they say yes, use the **report-ae-issue** prompt this server provides\n(`/report-ae-issue` where your client exposes prompts as commands) \u2014 it handles\nthe rest. If they say no, drop it; the note stays and can be offered again\nanother time.\n\nNever claim you have reported something you have not.\n\n## When something is not connected\n\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay its `nextSteps` to the user in plain language. Do not try to diagnose CEP by hand.\n\n**A timeout is not proof the bridge is dead.** The error that says the panel did not answer in time is a different thing from the one that says the panel cannot be reached. Because ExtendScript is single-threaded, a busy After Effects cannot answer anything \u2014 so a long script, or a modal dialog nobody has clicked, is indistinguishable from a crash at this layer. It normally recovers on its own within a minute.\n\nSo when a call times out: do not re-send it (you would queue the same work twice), do not restart After Effects, and do not run `setup_panel`. Poll `check_setup` for about a minute first. Two causes worth asking about directly:\n\n- **A dialog is waiting.** Ask the user to check After Effects for a prompt hiding behind another window.\n- **They changed desktop.** On macOS, calls have been reported to stall while the user is on a different Space and to complete as soon as they return. If they have wandered off, ask them to switch back to the desktop After Effects is on before you diagnose anything else.\n\nIf a specific operation of yours legitimately needs longer than the limit, the user can raise it by setting `AE_MCP_OP_TIMEOUT_MS` in the server\'s environment.'
   },
   {
     name: "style-guide",
@@ -1802,7 +1959,7 @@ var PROMPTS = [
     name: "report-ae-issue",
     description: "Send a problem you hit with the After Effects tools to the people who maintain them",
     argumentHint: "[what went wrong, in your own words]",
-    body: '# Report a problem with the After Effects tools\n\nThe user wants to tell the maintainers about something that did not work. They are\nmost likely a motion designer, not a developer: they may never have seen GitHub,\nand they should not have to. Do the technical part yourself and only ask them\nthings they can actually answer.\n\n`$ARGUMENTS` is what they typed, if anything.\n\n## 1. Find out what to report\n\nCall `list_known_issues` with `status: "unreported"`. It returns entries earlier\nsessions wrote down, plus `repo`, `newIssueUrl`, `serverVersion` and `platform`.\n\n- **Entries exist** \u2014 show them as a short numbered list, one plain sentence each\n  ("Text layers ended up in the wrong place when a font was missing"), not the\n  raw titles. Ask which to send; offer "all of them" as an option.\n- **No entries, but `$ARGUMENTS` describes something** \u2014 work from that. Ask what\n  they were trying to do and what happened instead, then `log_issue` it so it is\n  recorded before you send it.\n- **Nothing either way** \u2014 say there is nothing recorded to send, and that you\n  will write things down as you hit them from now on. Stop there.\n\n## 2. Draft it\n\nShort. A maintainer should understand the problem in fifteen seconds.\n\n**Title:** one line, concrete. `set_temporal_ease fails on Position with "Value\narray does not have 1 elements"` \u2014 not `Keyframe bug`.\n\n**Body:** four short sections, a couple of sentences each.\n\n```markdown\n**What happens**\n<the failing call and the exact error, or the wrong result>\n\n**Why** (if known)\n<one line \u2014 omit this section entirely if unknown>\n\n**Workaround**\n<what got past it>\n\n**Environment**\nafter-effects-mcp <serverVersion> \xB7 <platform> \xB7 After Effects 2026\n```\n\nInclude the failing call and error text verbatim \u2014 that is the part that makes it\nfixable. Leave out the user\'s own content: comp and layer names from their\nproject, file paths, client names, anything about the video they are making. If a\ndetail like that is load-bearing, replace it with a placeholder.\n\n## 3. Show it and get a yes\n\nShow the finished title and body and ask whether to send it. This posts publicly\nto a repository under their name if `gh` is authenticated, so it needs a real\nanswer, not an assumption. If they want to change the wording, change it.\n\n## 4. Send it\n\nTry `gh` first:\n\n```bash\ngh issue create --repo <repo> --title "<title>" --body "<body>"\n```\n\nIf `gh` is missing or not authenticated, do not try to install or configure it.\nBuild a prefilled link instead \u2014 URL-encode the title and body onto\n`<newIssueUrl>` as `?title=\u2026&body=\u2026` \u2014 and give it to them with one line of\ninstruction: open this, it will already be filled in, press the green button. A\nGitHub account is needed to press it; if they do not have one, say so plainly and\noffer to write the text out for them to send another way.\n\n## 5. Close the loop\n\nOn success, call `mark_issue_reported` with the entry `id` and the URL, so no\nlater session asks them to report the same thing twice. Then tell them where it\nwent, in one sentence, with the link.\n\nIf they decline, leave the entry alone \u2014 it stays unreported and can be offered\nagain another day. Do not mark it.'
+    body: '# Report a problem with the After Effects tools\n\nThe user wants to tell the maintainers about something that did not work. They are\nmost likely a motion designer, not a developer: they may never have seen GitHub,\nand they should not have to. Do the technical part yourself and only ask them\nthings they can actually answer.\n\n`$ARGUMENTS` is what they typed, if anything.\n\n## 1. Find out what to report\n\nCall `list_known_issues` with `status: "unreported"`. It returns a one-line index\nof what earlier sessions wrote down, plus `repo`, `newIssueUrl`, `serverVersion`\nand `platform`. Once they have chosen, read each chosen entry in full with\n`list_known_issues({id})` \u2014 the draft below needs the symptom and workaround\ntext, which the index does not carry.\n\n- **Entries exist** \u2014 show them as a short numbered list, one plain sentence each\n  ("Text layers ended up in the wrong place when a font was missing"), not the\n  raw titles. Ask which to send; offer "all of them" as an option.\n- **No entries, but `$ARGUMENTS` describes something** \u2014 work from that. Ask what\n  they were trying to do and what happened instead, then `log_issue` it so it is\n  recorded before you send it.\n- **Nothing either way** \u2014 say there is nothing recorded to send, and that you\n  will write things down as you hit them from now on. Stop there.\n\n## 2. Draft it\n\nShort. A maintainer should understand the problem in fifteen seconds.\n\n**Title:** one line, concrete. `set_temporal_ease fails on Position with "Value\narray does not have 1 elements"` \u2014 not `Keyframe bug`.\n\n**Body:** four short sections, a couple of sentences each.\n\n```markdown\n**What happens**\n<the failing call and the exact error, or the wrong result>\n\n**Why** (if known)\n<one line \u2014 omit this section entirely if unknown>\n\n**Workaround**\n<what got past it>\n\n**Environment**\nafter-effects-mcp <serverVersion> \xB7 <platform> \xB7 After Effects 2026\n```\n\nInclude the failing call and error text verbatim \u2014 that is the part that makes it\nfixable. Leave out the user\'s own content: comp and layer names from their\nproject, file paths, client names, anything about the video they are making. If a\ndetail like that is load-bearing, replace it with a placeholder.\n\n## 3. Show it and get a yes\n\nShow the finished title and body and ask whether to send it. This posts publicly\nto a repository under their name if `gh` is authenticated, so it needs a real\nanswer, not an assumption. If they want to change the wording, change it.\n\n## 4. Send it\n\nTry `gh` first:\n\n```bash\ngh issue create --repo <repo> --title "<title>" --body "<body>"\n```\n\nIf `gh` is missing or not authenticated, do not try to install or configure it.\nBuild a prefilled link instead \u2014 URL-encode the title and body onto\n`<newIssueUrl>` as `?title=\u2026&body=\u2026` \u2014 and give it to them with one line of\ninstruction: open this, it will already be filled in, press the green button. A\nGitHub account is needed to press it; if they do not have one, say so plainly and\noffer to write the text out for them to send another way.\n\n## 5. Close the loop\n\nOn success, call `mark_issue_reported` with the entry `id` and the URL, so no\nlater session asks them to report the same thing twice. Then tell them where it\nwent, in one sentence, with the link.\n\nIf they decline, leave the entry alone \u2014 it stays unreported and can be offered\nagain another day. Do not mark it.'
   }
 ];
 var GUIDE_NAMES = GUIDES.map((g) => g.name);
@@ -1812,7 +1969,7 @@ function getGuide(name) {
 function getPrompt(name) {
   return PROMPTS.find((p) => p.name === name);
 }
-var SERVER_INSTRUCTIONS = "You are driving a live After Effects session through this server. The user sees\nevery change as it happens and every call is a real undo step in their project.\n\nSix things that are not obvious from the tool list:\n\n1. Read the house style before you build. `get_house_style` returns the user's\n   palette, type and motion defaults for the project that is open. One cheap call.\n2. Orient before you touch anything. `get_layer_full` returns a layer's\n   transforms with keyframes and expressions, every effect and parameter, masks,\n   markers and visible bounds in a single call \u2014 prefer it over several narrow reads.\n3. Identify by id, never by index. Layer `index` shifts whenever layers are\n   added, deleted or reordered. Carry `(compId, layerId)`.\n4. Verify by reading properties back, not by screenshotting. Screenshots are\n   one-off diagnostics: 2-3 across an animation, and always pass `downsample`\n   (2 for 1080p, 3-4 for 4K) or a single frame can fill your context.\n5. Bulk work goes through `run_batch` \u2014 one ExtendScript pass, one undo step.\n6. When a tool fails in a way you do not understand, call `list_known_issues`\n   before guessing; an earlier session may have solved it already. When you solve\n   a new one, `log_issue` it.\n\nCall `ae_guide` for the full guidance on any of this \u2014 topics: ae-setup, after-effects, style-guide.\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay\nits `nextSteps` verbatim; do not diagnose CEP by hand.";
+var SERVER_INSTRUCTIONS = "You are driving a live After Effects session through this server. The user sees\nevery change as it happens and every call is a real undo step in their project.\n\nSix things that are not obvious from the tool list:\n\n1. Read the house style before you build. `get_house_style` returns the user's\n   palette, type and motion defaults for the project that is open. One cheap call.\n2. Orient before you touch anything. `get_layer_full` returns a layer's\n   transforms with keyframes and expressions, every effect and parameter, masks,\n   markers and visible bounds in a single call \u2014 prefer it over several narrow reads.\n3. Identify by id, never by index. Layer `index` shifts whenever layers are\n   added, deleted or reordered. Carry `(compId, layerId)`.\n4. Verify by reading properties back, not by screenshotting. Screenshots are\n   one-off diagnostics: 2-3 across an animation, never per frame.\n5. Bulk work goes through `run_batch` \u2014 one ExtendScript pass, one undo step.\n6. When a tool fails in a way you do not understand, call `list_known_issues`\n   before guessing; an earlier session may have solved it already. When you solve\n   a new one, `log_issue` it.\n\nCall `ae_guide` for the full guidance on any of this \u2014 topics: ae-setup, after-effects, style-guide.\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay\nits `nextSteps` verbatim; do not diagnose CEP by hand.";
 
 // src/issues/journal.ts
 import fs7 from "node:fs";
@@ -1973,39 +2130,84 @@ function logIssue(input) {
     issueUrl: entry.issueUrl
   };
 }
-function listIssues(status = "all", tool) {
-  const { scope } = journalRoot();
+var SUMMARY_CHARS = 160;
+function summarize(entry) {
+  const text = oneLine(entry.symptom || entry.workaround || "");
+  return text.length > SUMMARY_CHARS ? `${text.slice(0, SUMMARY_CHARS).trimEnd()}\u2026` : text;
+}
+function toIndexEntry(e) {
+  return {
+    id: e.id,
+    title: e.title,
+    tools: e.tools,
+    lastSeen: e.lastSeen,
+    occurrences: e.occurrences,
+    reported: e.reported,
+    summary: summarize(e)
+  };
+}
+function readAllEntries() {
   const dir = journalDir();
-  let entries = [];
   try {
-    entries = fs7.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path8.join(dir, f))).filter((e) => e !== null);
+    return fs7.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path8.join(dir, f))).filter((e) => e !== null);
   } catch {
-    entries = [];
+    return [];
+  }
+}
+function matchesQuery(entry, terms) {
+  const haystack = `${entry.title} ${entry.symptom} ${entry.tools.join(" ")}`.toLowerCase();
+  return terms.every((t) => haystack.includes(t));
+}
+function listIssues(options = {}) {
+  const { scope } = journalRoot();
+  const dir = journalDir();
+  const entries = readAllEntries();
+  const envelope = {
+    dir,
+    scope,
+    repo: REPO,
+    newIssueUrl: NEW_ISSUE_URL,
+    serverVersion: packageVersion(),
+    platform: process.platform
+  };
+  const wantedId = options.id?.trim();
+  if (wantedId) {
+    const found = entries.find((e) => e.id === slugify(wantedId));
+    if (!found) {
+      throw new Error(
+        `No journal entry with id "${wantedId}".` + (entries.length > 0 ? ` Known ids: ${entries.map((e) => e.id).join(", ")}` : " The journal is empty.")
+      );
+    }
+    return { ...envelope, detail: "full", count: 1, issues: [found] };
   }
-  const wanted = tool?.trim().toLowerCase();
+  const status = options.status ?? "all";
+  const wanted = options.tool?.trim().toLowerCase();
+  const terms = (options.query ?? "").toLowerCase().split(/\s+/).filter((t) => t.length > 0);
   const filtered = entries.filter((e) => {
     const byStatus = status === "all" ? true : status === "reported" ? e.reported : !e.reported;
     if (!byStatus) return false;
+    if (terms.length > 0 && !matchesQuery(e, terms)) return false;
     if (!wanted) return true;
     return e.tools.some((t) => t.toLowerCase() === wanted) || e.title.toLowerCase().includes(wanted);
   });
   filtered.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences);
+  const detail = options.detail ?? "index";
   return {
-    dir,
-    scope,
-    repo: REPO,
-    newIssueUrl: NEW_ISSUE_URL,
-    serverVersion: packageVersion(),
-    platform: process.platform,
+    ...envelope,
+    detail,
     count: filtered.length,
-    issues: filtered
+    issues: detail === "full" ? filtered : filtered.map(toIndexEntry),
+    // The reason to read this journal is that something failed, so an index
+    // that stopped short of the workaround would be worse than useless. Say
+    // how to reach it, every time there is one to reach.
+    ...detail === "index" && filtered.length > 0 ? { next: 'list_known_issues({ id: "<id>" }) for the cause and the workaround.' } : {}
   };
 }
 function markReported(id, url) {
   const file = entryPath(slugify(id));
   const entry = fs7.existsSync(file) ? readEntry(file) : null;
   if (!entry) {
-    const known = listIssues("all").issues.map((e) => e.id);
+    const known = readAllEntries().map((e) => e.id);
     throw new Error(
       `No journal entry with id "${id}".` + (known.length > 0 ? ` Known ids: ${known.join(", ")}` : "")
     );
@@ -2049,7 +2251,7 @@ var GetJobSchema = schemas_exports.GetJob;
 var CancelJobSchema = schemas_exports.CancelJob;
 function createServer() {
   const server = new Server(
-    { name: "after-effects-mcp", version: "0.2.1" },
+    { name: "after-effects-mcp", version: "0.3.0" },
     {
       capabilities: { tools: {}, logging: {}, prompts: {}, resources: {} },
       // Clients that honour this fold it into the system prompt, which is the
@@ -2176,7 +2378,17 @@ function createServer() {
         }
         if (name === "list_known_issues") {
           const a = schemas_exports.ListKnownIssues.parse(rawArgs);
-          return textResult(listIssues(a.status ?? "all", a.tool));
+          return textResult(
+            listIssues({
+              status: a.status ?? "all",
+              tool: a.tool,
+              query: a.query,
+              id: a.id,
+              // Compact unless asked otherwise: the full corpus is thousands of
+              // tokens that stay in the transcript for the rest of the session.
+              detail: a.detail ?? "index"
+            })
+          );
         }
         if (name === "mark_issue_reported") {
           const a = schemas_exports.MarkIssueReported.parse(rawArgs);
@@ -2210,6 +2422,7 @@ function createServer() {
         }
         return textResult({ jobId: env.jobId, async: true, total: env.total });
       }
+      if (VISION_OPS.has(name) && isEmptyFrameResult(result)) return textResult(result);
       if (VISION_OPS.has(name) && isVisionResult(result)) {
         const v = result;
         return imageContent(
@@ -2223,6 +2436,10 @@ function createServer() {
             compId: v.compId,
             layerId: v.layerId,
             bytes: v.bytes,
+            // Present only when the project renders deeper than 8 bits per
+            // channel and the panel re-encoded the frame so it would decode.
+            converted: v.converted,
+            sourceBitDepth: v.sourceBitDepth,
             // Surfaced when a requested downsample could not be applied, so the
             // agent knows it is looking at a full-resolution frame.
             warning: v.warning
@@ -2232,8 +2449,10 @@ function createServer() {
       }
       return textResult(result);
     } catch (e) {
+      if (e instanceof BridgeTimeoutError) return errorResult(e.message);
       if (e instanceof BridgeUnreachableError) return errorResult(e.message);
       if (e instanceof AeError) {
+        if (e.code) return errorResult(e.message);
         if (/^Unknown op: /.test(e.message)) {
           panelGate.invalidate();
           return errorResult(unknownOpMessage(name));
@@ -2318,6 +2537,9 @@ function isAsyncEnvelope(v) {
 function isVisionResult(v) {
   return !!(v && typeof v === "object" && "base64" in v && "width" in v);
 }
+function isEmptyFrameResult(v) {
+  return !!(v && typeof v === "object" && v.empty === true && !("base64" in v));
+}
 
 // src/index.ts
 var USAGE = `@engine-room/after-effects-mcp \u2014 drive Adobe After Effects from an AI agent.
@@ -2359,7 +2581,7 @@ ${USAGE}`);
   await server.connect(transport);
   logger.info("MCP server running on stdio");
 }
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 main().catch((e) => {
   logger.error("fatal", e.message);
   process.exit(1);