@engine-room/after-effects-mcp 0.3.1 → 0.5.0

package/bin/server.js

@@ -9,12 +9,138 @@ var __export = (target, all) => {
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/cli/init.ts
-import path2 from "node:path";
+import path3 from "node:path";
 
 // src/setup/scaffold.ts
+import fs2 from "node:fs";
+import os2 from "node:os";
+import path2 from "node:path";
+
+// src/setup/paths.ts
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+var BUNDLE_ID = "games.engine-room.ae-mcp";
+function isSupportedPlatform() {
+  return process.platform === "darwin" || process.platform === "win32";
+}
+function packageRoot() {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.dirname(fileURLToPath(import.meta.url));
+}
+function executableDir() {
+  return path.dirname(process.execPath);
+}
+function packageVersion() {
+  for (const dir of [packageRoot(), executableDir()]) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+      if (typeof pkg.version === "string") return pkg.version;
+    } catch {
+    }
+  }
+  return "unknown";
+}
+function panelSourceDir() {
+  const candidates = [
+    // The live workspace copy comes first so a git checkout always installs
+    // what the developer is editing, never a stale vendored copy left behind by
+    // a previous `npm pack`. Only the second path exists in the tarball.
+    path.resolve(packageRoot(), "..", "ae-panel"),
+    path.join(packageRoot(), "panel"),
+    // Compiled single-file build: the panel ships beside the executable.
+    path.join(executableDir(), "panel")
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, "CSXS", "manifest.xml"))) return dir;
+  }
+  return null;
+}
+function cepExtensionsDir() {
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appData, "Adobe", "CEP", "extensions");
+  }
+  return path.join(os.homedir(), "Library", "Application Support", "Adobe", "CEP", "extensions");
+}
+function installedPanelDir() {
+  return path.join(cepExtensionsDir(), BUNDLE_ID);
+}
+function signedInstallPresent(dir) {
+  return fs.existsSync(path.join(dir, "META-INF", "signatures.xml")) || fs.existsSync(path.join(dir, "META-INF")) || fs.existsSync(path.join(dir, "mimetype"));
+}
+function isWsModuleDir(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    if (pkg.name !== "ws") return false;
+    return fs.existsSync(path.join(dir, "index.js")) && fs.existsSync(path.join(dir, "lib", "websocket.js"));
+  } catch {
+    return false;
+  }
+}
+function wsModuleDir() {
+  const candidates = [];
+  try {
+    const require2 = createRequire(import.meta.url);
+    const entry = require2.resolve("ws");
+    if (path.isAbsolute(entry)) {
+      const marker = `${path.sep}node_modules${path.sep}ws${path.sep}`;
+      const idx = entry.lastIndexOf(marker);
+      candidates.push(idx >= 0 ? entry.slice(0, idx + marker.length - 1) : path.dirname(entry));
+    }
+  } catch {
+  }
+  candidates.push(path.join(executableDir(), "node_modules", "ws"));
+  candidates.push(path.join(packageRoot(), "node_modules", "ws"));
+  for (const dir of candidates) {
+    if (isWsModuleDir(dir)) return dir;
+  }
+  return null;
+}
+function listPanelFiles(dir, prefix = "") {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".DS_Store") continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listPanelFiles(path.join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+function sameContents(a, b) {
+  try {
+    if (fs.statSync(a).size !== fs.statSync(b).size) return false;
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch {
+    return false;
+  }
+}
+function panelInstallDiff(source, installed) {
+  return listPanelFiles(source).filter((rel) => !sameContents(path.join(source, rel), path.join(installed, rel))).sort();
+}
+function copyRecursive(src, dst) {
+  const stat = fs.lstatSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dst, entry));
+    }
+  } else if (stat.isSymbolicLink()) {
+    fs.symlinkSync(fs.readlinkSync(src), dst);
+  } else {
+    fs.copyFileSync(src, dst);
+  }
+}
+
+// src/setup/scaffold.ts
 var ScaffoldError = class extends Error {
 };
 function detectClient(clientName) {
@@ -38,10 +164,10 @@ function mcpConfigFor(client) {
     case "claude-code":
       return { rel: ".mcp.json", json: standard };
     case "cursor":
-      return { rel: path.join(".cursor", "mcp.json"), json: standard };
+      return { rel: path2.join(".cursor", "mcp.json"), json: standard };
     case "vscode":
       return {
-        rel: path.join(".vscode", "mcp.json"),
+        rel: path2.join(".vscode", "mcp.json"),
         json: JSON.stringify({ servers: { "after-effects": { type: "stdio", ...MCP_SERVER_ENTRY } } }, null, 2) + "\n"
       };
     default:
@@ -50,25 +176,30 @@ function mcpConfigFor(client) {
 }
 function globalConfigHint(client) {
   const standard = JSON.stringify({ mcpServers: { "after-effects": MCP_SERVER_ENTRY } }, null, 2) + "\n";
-  const home = os.homedir();
+  const home = os2.homedir();
   switch (client) {
     case "claude-desktop":
       return {
-        path: process.platform === "darwin" ? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : path.join(process.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json"),
+        path: process.platform === "darwin" ? path2.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : path2.join(process.env.APPDATA ?? path2.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json"),
         json: standard
       };
     case "windsurf":
-      return { path: path.join(home, ".codeium", "windsurf", "mcp_config.json"), json: standard };
+      return { path: path2.join(home, ".codeium", "windsurf", "mcp_config.json"), json: standard };
     case "codex":
       return {
-        path: path.join(home, ".codex", "config.toml"),
+        path: path2.join(home, ".codex", "config.toml"),
         json: '[mcp_servers.after-effects]\ncommand = "npx"\nargs = ["-y", "@engine-room/after-effects-mcp"]\n'
       };
     default:
       return void 0;
   }
 }
-var AGENTS_MD = (name) => `# ${name}
+var ABSORBED_MARKER_PREFIX = "Tools version last absorbed:";
+var ABSORBED_MARKER = new RegExp(`^\\s*${ABSORBED_MARKER_PREFIX}\\s*v?(\\d+\\.\\d+\\.\\d+)\\s*$`, "m");
+function absorbedMarkerLine(version) {
+  return `${ABSORBED_MARKER_PREFIX} ${version}`;
+}
+var AGENTS_MD = (name, version) => `# ${name}
 
 An After Effects project folder. The AE tools drive After Effects directly from
 here \u2014 describe what you want and it gets built in the open project.
@@ -94,6 +225,14 @@ Check \`list_known_issues\` before guessing \u2014 an earlier session may alread
 solved it. Anything newly worked out goes in with \`log_issue\`, and the
 report-ae-issue prompt sends it to the maintainers.
 
+## Tool updates
+
+${absorbedMarkerLine(version)}
+
+When the After Effects tools update, the absorb-release prompt reads what
+changed since the version above, fixes any rule in this folder the update made
+stale, and moves the version on. Leave the line where it is.
+
 ## Conventions for this project
 
 <!-- Anything specific to this project rather than to your general style: naming
@@ -123,48 +262,51 @@ function pointerFiles(client) {
     case "claude-code":
       return ["CLAUDE.md"];
     case "cursor":
-      return [path.join(".cursor", "rules", "after-effects.mdc")];
+      return [path2.join(".cursor", "rules", "after-effects.mdc")];
     case "windsurf":
       return [".windsurfrules"];
     case "vscode":
-      return [path.join(".github", "copilot-instructions.md")];
+      return [path2.join(".github", "copilot-instructions.md")];
     default:
       return [];
   }
 }
 function resolveTarget(dir, roots) {
   if (dir && dir.trim().length > 0) {
-    return { dir: path.resolve(dir.trim()), resolvedFrom: "argument" };
+    return refuseUnscoped({ dir: path2.resolve(dir.trim()), resolvedFrom: "argument" });
   }
   const root = roots?.find((r) => r && r.trim().length > 0);
-  if (root) return { dir: path.resolve(root), resolvedFrom: "client-root" };
+  if (root) return refuseUnscoped({ dir: path2.resolve(root), resolvedFrom: "client-root" });
   const cwd = process.cwd();
-  const isFilesystemRoot = cwd === path.parse(cwd).root;
-  if (isFilesystemRoot || cwd === os.homedir()) {
-    throw new ScaffoldError(
-      `No project folder to write to. This client did not say which folder it is working in, and the server was started in ${cwd}, which is not somewhere a project should be created. Ask the user which folder they want the project in \u2014 a new one is fine \u2014 and pass it as \`dir\`.`
-    );
-  }
-  return { dir: cwd, resolvedFrom: "working-directory" };
+  return refuseUnscoped({ dir: cwd, resolvedFrom: "working-directory" });
+}
+function refuseUnscoped(target) {
+  const { dir, resolvedFrom } = target;
+  const isFilesystemRoot = dir === path2.parse(dir).root;
+  if (!isFilesystemRoot && dir !== os2.homedir()) return target;
+  const how = resolvedFrom === "argument" ? `\`dir\` is ${dir}` : resolvedFrom === "client-root" ? `the client says it is working in ${dir}` : `this client did not say which folder it is working in, and the server was started in ${dir}`;
+  throw new ScaffoldError(
+    `No project folder to write to: ${how}, which is not somewhere a project should be created. Ask the user which folder they want the project in \u2014 a new one is fine \u2014 and pass it as \`dir\`.`
+  );
 }
 function scaffold(opts) {
   const { dir, resolvedFrom } = resolveTarget(opts.dir, opts.roots);
-  const name = opts.name?.trim() || path.basename(dir);
-  const files = [["AGENTS.md", AGENTS_MD(name)]];
+  const name = opts.name?.trim() || path2.basename(dir);
+  const files = [["AGENTS.md", AGENTS_MD(name, packageVersion())]];
   for (const rel of pointerFiles(opts.client)) files.push([rel, pointerContent(rel)]);
-  files.push([path.join("renders", ".gitkeep"), ""]);
+  files.push([path2.join("renders", ".gitkeep"), ""]);
   const projectConfig = opts.withMcpConfig ? mcpConfigFor(opts.client) : void 0;
   if (projectConfig) files.push([projectConfig.rel, projectConfig.json]);
-  const existing = files.map(([rel]) => rel).filter((rel) => fs.existsSync(path.join(dir, rel)));
+  const existing = files.map(([rel]) => rel).filter((rel) => fs2.existsSync(path2.join(dir, rel)));
   if (existing.length > 0) {
     throw new ScaffoldError(
       `${dir} already has ${existing.join(", ")}. Nothing was written. This folder is already set up \u2014 or pick a different one.`
     );
   }
   for (const [rel, content] of files) {
-    const full = path.join(dir, rel);
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, content, "utf8");
+    const full = path2.join(dir, rel);
+    fs2.mkdirSync(path2.dirname(full), { recursive: true });
+    fs2.writeFileSync(full, content, "utf8");
   }
   const hint = opts.withMcpConfig && !projectConfig ? globalConfigHint(opts.client) : void 0;
   const nextSteps = [
@@ -246,7 +388,7 @@ Usage: npx @engine-room/after-effects-mcp init <directory> [--no-mcp] [--client
   }
   const lines = [`Created ${result.dir}`, ``];
   for (const rel of result.written) {
-    if (rel.endsWith(".gitkeep")) lines.push(`  ${pad(path2.dirname(rel) + "/")} exports land here`);
+    if (rel.endsWith(".gitkeep")) lines.push(`  ${pad(path3.dirname(rel) + "/")} exports land here`);
     else if (rel === "AGENTS.md") lines.push(`  ${pad(rel)} what this project is`);
     else if (rel.endsWith("mcp.json")) lines.push(`  ${pad(rel)} connects your client to After Effects`);
     else lines.push(`  ${pad(rel)} points your client at AGENTS.md`);
@@ -273,6 +415,290 @@ function pad(s) {
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+// src/bridge/discovery.ts
+import fs3 from "node:fs";
+import os3 from "node:os";
+import path4 from "node:path";
+
+// src/util/errors.ts
+var BridgeUnreachableError = class _BridgeUnreachableError extends Error {
+  constructor(port, cause) {
+    super(_BridgeUnreachableError.message(port, cause));
+    this.port = port;
+    this.name = "BridgeUnreachableError";
+  }
+  port;
+  static message(port, cause) {
+    return [
+      `Cannot reach the After Effects panel at http://127.0.0.1:${port}.`,
+      cause ? `Underlying error: ${cause.message}` : "",
+      "",
+      "Call the check_setup tool to find out why, then relay its nextSteps to the user.",
+      "In most cases the fix is either running setup_panel (installs the panel) or",
+      "simply opening After Effects."
+    ].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 {
+  /**
+   * `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, source) {
+    super(message);
+    this.stack_ = stack_;
+    this.line = line;
+    this.code = code;
+    this.source = source;
+    this.name = "AeError";
+  }
+  stack_;
+  line;
+  code;
+  source;
+};
+function aeErrorText(e) {
+  const head = `AE: ${e.message}`;
+  const s = e.source;
+  if (!s) return e.line ? `${head} (line ${e.line})` : head;
+  const where = s.sourceName ?? "the script you submitted";
+  const total = s.lineCount ? `, ${s.lineCount} lines` : "";
+  const lines = [head];
+  if (s.sourceLine) {
+    lines.push(`  at line ${s.sourceLine} of ${where}${total}:`);
+    if (s.sourceText) lines.push(`    ${s.sourceText}`);
+    if (s.rawLine != null && s.rawLine !== s.sourceLine) {
+      lines.push(`  (After Effects reported line ${s.rawLine}.)`);
+    }
+  } else if (s.rawLine != null) {
+    lines.push(
+      `  After Effects reported line ${s.rawLine}, which does not fall inside ${where}${total} \u2014 trust the message, not the number.`
+    );
+  }
+  lines.push(
+    "  Everything before the failure already ran and nothing rolls back: read the state back rather than re-running the script."
+  );
+  return lines.join("\n");
+}
+var WriteQueueWaitError = class _WriteQueueWaitError extends Error {
+  constructor(op, waitedMs, behind) {
+    super(_WriteQueueWaitError.message(op, waitedMs, behind));
+    this.op = op;
+    this.waitedMs = waitedMs;
+    this.behind = behind;
+    this.name = "WriteQueueWaitError";
+  }
+  op;
+  waitedMs;
+  behind;
+  static message(op, waitedMs, behind) {
+    const secs = Math.round(waitedMs / 1e3);
+    return [
+      `\`${op}\` waited ${secs}s behind \`${behind}\` for the After Effects write queue and was dropped without running.`,
+      "",
+      "This is neither a lost connection nor a busy bridge. The panel is fine and this",
+      "call never reached After Effects, so nothing in the project was changed.",
+      "",
+      "Writes are serialized because After Effects runs one script at a time and applies",
+      "changes in the order it receives them; two in flight block each other and land in",
+      "an order nobody chose. Something in front of this call is taking a very long time",
+      "\u2014 most often a long run_batch, occasionally a modal dialog in After Effects",
+      "blocking the script in front.",
+      "",
+      "What to do, in order:",
+      "1. Nothing was written, so re-sending this call is safe \u2014 unlike a bridge timeout.",
+      "   Wait for the work in front to finish first, or it will just queue again.",
+      "2. Find out what is in front: get_job or await_job for a batch. Reads are not",
+      "   queued, so list_/get_ calls still work and will tell you the current state.",
+      "3. Ask the user to look at After Effects for a dialog nobody has clicked.",
+      `4. If the work in front is legitimately this long, raise the limit: start the`,
+      "   server with AE_MCP_WRITE_QUEUE_WAIT_MS set to a larger number of milliseconds."
+    ].join("\n");
+  }
+};
+var WriteQueueFullError = class _WriteQueueFullError extends Error {
+  constructor(op, maxDepth, behind) {
+    super(_WriteQueueFullError.message(op, maxDepth, behind));
+    this.op = op;
+    this.maxDepth = maxDepth;
+    this.behind = behind;
+    this.name = "WriteQueueFullError";
+  }
+  op;
+  maxDepth;
+  behind;
+  static message(op, maxDepth, behind) {
+    return [
+      `The After Effects write queue is full \u2014 ${maxDepth} calls are already waiting, so \`${op}\` was refused.`,
+      "",
+      `Nothing was written. Writes are serialized so they land in the order you sent them,`,
+      `and \`${behind}\` is holding the queue up.`,
+      "",
+      "Stop issuing writes and let it drain \u2014 reads are not queued, so list_/get_ calls",
+      "still work. If you have this much independent work to do, send it as one",
+      "run_batch instead of as many calls: that is one ExtendScript pass and one place in",
+      "the queue, and its result reports how many undo steps it actually made.",
+      "AE_MCP_WRITE_QUEUE_DEPTH raises the limit if you really need it raised."
+    ].join("\n");
+  }
+};
+var WriteQueueCancelledError = class extends Error {
+  constructor(op) {
+    super(`\`${op}\` was cancelled while waiting for the After Effects write queue. It never ran, and nothing was changed.`);
+    this.op = op;
+    this.name = "WriteQueueCancelledError";
+  }
+  op;
+};
+function invalidArgsText(op, e) {
+  const issues = e?.issues;
+  if (!Array.isArray(issues) || issues.length === 0) {
+    return `Invalid arguments for ${op}: ${e.message}`;
+  }
+  const lines = issues.map((raw) => {
+    const issue = raw;
+    const where = Array.isArray(issue.path) && issue.path.length ? issue.path.join(".") : null;
+    let text = issue.message ?? "invalid";
+    if (issue.code === "invalid_type" && issue.received === "undefined") {
+      text = "required, and was not passed";
+    } else if (issue.code === "invalid_type" && issue.expected) {
+      text = `expected ${issue.expected}, got ${issue.received ?? "something else"}`;
+    }
+    return where ? `  - ${where}: ${text}` : `  - ${text}`;
+  });
+  const head = issues.length === 1 ? `Invalid arguments for ${op}:` : `Invalid arguments for ${op} (${issues.length} problems):`;
+  return [head, ...lines].join("\n");
+}
+
+// src/bridge/discovery.ts
+var DEFAULT_PORT = 7777;
+function portFilePath() {
+  return path4.join(os3.homedir(), ".engineroom-ae-mcp", "port");
+}
+function pinnedPort() {
+  const envPort = process.env.AE_MCP_PORT;
+  if (!envPort) return null;
+  const n = parseInt(envPort, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+function portFilePort() {
+  try {
+    const f = portFilePath();
+    if (fs3.existsSync(f)) {
+      const txt = fs3.readFileSync(f, "utf8").trim();
+      const n = parseInt(txt, 10);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+  } catch {
+  }
+  return null;
+}
+function discoverPort() {
+  return pinnedPort() ?? portFilePort() ?? DEFAULT_PORT;
+}
+function portCandidates() {
+  const pinned = pinnedPort();
+  if (pinned !== null) return [pinned];
+  const out = [DEFAULT_PORT];
+  const fromFile = portFilePort();
+  if (fromFile !== null && fromFile !== DEFAULT_PORT) out.push(fromFile);
+  return out;
+}
+function diagnosticPortCandidates() {
+  const out = [...portCandidates()];
+  for (const p of [DEFAULT_PORT, portFilePort()]) {
+    if (p !== null && !out.includes(p)) out.push(p);
+  }
+  return out;
+}
+function isPanelHealth(body) {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  return b.ok === true && ("bundleHash" in b || "bundleLoaded" in b);
+}
+var PROBE_TIMEOUT_MS = 2e3;
+async function probePanel(port, timeoutMs = PROBE_TIMEOUT_MS) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) {
+      return { port, status: "other", detail: `port ${port} answered HTTP ${res.status}, which is not the panel` };
+    }
+    const body = await res.json().catch(() => null);
+    if (isPanelHealth(body)) {
+      return { port, status: "panel", health: body, detail: `the panel is answering on port ${port}` };
+    }
+    return { port, status: "other", detail: `port ${port} answered, but not as the After Effects panel` };
+  } catch (e) {
+    if (isTimeoutError(e)) {
+      return {
+        port,
+        status: "busy",
+        detail: `port ${port} accepted the connection but had not answered after ${Math.round(timeoutMs / 1e3)}s \u2014 a panel may be there and busy`
+      };
+    }
+    return { port, status: "none", detail: `nothing is listening on port ${port} (${e.message})` };
+  }
+}
+async function locatePanel(candidates = portCandidates()) {
+  const probed = [];
+  for (const port of candidates) {
+    const r = await probePanel(port);
+    probed.push(r);
+    if (r.status === "panel") return { found: r, probed };
+  }
+  return { found: null, probed };
+}
+
+// src/server.ts
 import {
   CallToolRequestSchema,
   GetPromptRequestSchema,
@@ -336,6 +762,7 @@ var WsEvent = z.discriminatedUnion("type", [
 // ../shared/dist/schemas.js
 var schemas_exports = {};
 __export(schemas_exports, {
+  ARRAY_ELEMENT: () => ARRAY_ELEMENT,
   AddEffect: () => AddEffect,
   AddKeyframe: () => AddKeyframe,
   AddMarker: () => AddMarker,
@@ -343,7 +770,10 @@ __export(schemas_exports, {
   AddShapeContent: () => AddShapeContent,
   AddTextAnimator: () => AddTextAnimator,
   AeGuide: () => AeGuide,
+  ArchiveIssue: () => ArchiveIssue,
+  AudioCue: () => AudioCue,
   AwaitJob: () => AwaitJob,
+  CROSS_FIELD_RULE: () => CROSS_FIELD_RULE,
   CancelJob: () => CancelJob,
   CheckSetup: () => CheckSetup,
   ClearExpression: () => ClearExpression,
@@ -361,6 +791,8 @@ __export(schemas_exports, {
   CreateTextLayer: () => CreateTextLayer,
   DeleteComp: () => DeleteComp,
   DeleteLayer: () => DeleteLayer,
+  DiffComp: () => DiffComp,
+  DuplicateComp: () => DuplicateComp,
   DuplicateLayer: () => DuplicateLayer,
   ExportMogrt: () => ExportMogrt,
   FindLayers: () => FindLayers,
@@ -376,6 +808,7 @@ __export(schemas_exports, {
   ImportFootage: () => ImportFootage,
   InitProject: () => InitProject,
   Interpolation: () => Interpolation,
+  LAYER_SUMMARY_SECTIONS: () => LAYER_SUMMARY_SECTIONS,
   ListAvailableEffects: () => ListAvailableEffects,
   ListComps: () => ListComps,
   ListEffects: () => ListEffects,
@@ -383,9 +816,12 @@ __export(schemas_exports, {
   ListLayers: () => ListLayers,
   LogIssue: () => LogIssue,
   MarkIssueReported: () => MarkIssueReported,
+  OpMutation: () => OpMutation,
   OpSchemas: () => OpSchemas,
   ParentLayer: () => ParentLayer,
+  PlaceAudioCues: () => PlaceAudioCues,
   PropertyPath: () => PropertyPath,
+  PurgeUnusedFootage: () => PurgeUnusedFootage,
   RemoveEffect: () => RemoveEffect,
   RemoveKeyframe: () => RemoveKeyframe,
   RemoveMarker: () => RemoveMarker,
@@ -412,10 +848,18 @@ __export(schemas_exports, {
   SetTransform: () => SetTransform,
   SetupPanel: () => SetupPanel,
   ShapeContent: () => ShapeContent,
+  SnapshotComp: () => SnapshotComp,
   ToggleExpression: () => ToggleExpression,
   Vec2: () => Vec2,
   Vec3: () => Vec3,
-  VecAny: () => VecAny
+  VecAny: () => VecAny,
+  crossFieldJsonSchema: () => crossFieldJsonSchema,
+  crossFieldMessage: () => crossFieldMessage,
+  crossFieldPresent: () => crossFieldPresent,
+  crossFieldRuleOf: () => crossFieldRuleOf,
+  crossFieldRulesIn: () => crossFieldRulesIn,
+  crossFieldSatisfied: () => crossFieldSatisfied,
+  objectShapeOf: () => objectShapeOf
 });
 import { z as z2 } from "zod";
 var Color = z2.tuple([z2.number(), z2.number(), z2.number()]).describe("RGB 0..1");
@@ -431,6 +875,117 @@ var Interpolation = z2.object({
   easeOut: z2.object({ influence: z2.number(), speed: z2.number() }).optional()
 });
 var includeParam = (sections, hint) => z2.array(z2.enum(sections)).optional().describe(`Sections to return: ${sections.join(", ")}. Omit for all of them; [] for ${hint}.`);
+var CROSS_FIELD_RULE = /* @__PURE__ */ Symbol.for("engineRoom.aeMcp.crossFieldRule");
+var backticked = (fields) => fields.map((f) => "`" + f + "`");
+var joinWith = (parts, conjunction) => {
+  if (parts.length <= 1)
+    return parts.join("");
+  if (parts.length === 2)
+    return `${parts[0]} ${conjunction} ${parts[1]}`;
+  return `${parts.slice(0, -1).join(", ")} ${conjunction} ${parts[parts.length - 1]}`;
+};
+function crossFieldMessage(rule, present) {
+  const want = joinWith(backticked(rule.fields), "or");
+  const got = joinWith(backticked(present), "and");
+  const head = rule.kind === "exactlyOne" ? `Pass exactly one of ${want}` : rule.kind === "atLeastOne" ? `Pass at least one of ${want}` : `Pass at most one of ${want}`;
+  const body = present.length === 0 ? rule.fields.length === 2 ? " \u2014 neither was passed." : " \u2014 none of them was passed." : ` \u2014 got ${got}. Keep the one you meant and drop ${present.length === 2 ? "the other" : "the others"}.`;
+  return head + body + (rule.then ? " " + rule.then : "");
+}
+function crossFieldPresent(rule, value) {
+  if (!value || typeof value !== "object")
+    return [];
+  const obj = value;
+  return rule.fields.filter((f) => obj[f] !== void 0);
+}
+function crossFieldSatisfied(rule, value) {
+  const n = crossFieldPresent(rule, value).length;
+  if (rule.kind === "exactlyOne")
+    return n === 1;
+  if (rule.kind === "atLeastOne")
+    return n >= 1;
+  return n <= 1;
+}
+function crossFieldJsonSchema(rule) {
+  const each = rule.fields.map((f) => ({ required: [f] }));
+  if (rule.kind === "exactlyOne")
+    return { oneOf: each };
+  if (rule.kind === "atLeastOne")
+    return { anyOf: each };
+  const pairs = [];
+  for (let i = 0; i < rule.fields.length; i++) {
+    for (let j = i + 1; j < rule.fields.length; j++) {
+      pairs.push({ required: [rule.fields[i], rule.fields[j]] });
+    }
+  }
+  return { not: pairs.length === 1 ? pairs[0] : { anyOf: pairs } };
+}
+function crossField(schema, rule) {
+  const refined = schema.superRefine((value, ctx) => {
+    if (crossFieldSatisfied(rule, value))
+      return;
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: crossFieldMessage(rule, crossFieldPresent(rule, value)),
+      // The first field of the rule, so the issue has somewhere to point. The
+      // message names all of them, which is the part that matters.
+      path: [rule.fields[0]]
+    });
+  });
+  Object.defineProperty(refined, CROSS_FIELD_RULE, { value: rule, enumerable: false });
+  return refined;
+}
+function crossFieldRuleOf(node) {
+  if (!node || typeof node !== "object")
+    return void 0;
+  return node[CROSS_FIELD_RULE];
+}
+var ARRAY_ELEMENT = "[]";
+function crossFieldRulesIn(schema) {
+  const found = [];
+  const walk = (node, path12, depth) => {
+    const def = node?._def;
+    if (!def || depth > 16)
+      return;
+    switch (def.typeName) {
+      case "ZodEffects":
+        found.push({ path: [...path12], rule: crossFieldRuleOf(node) });
+        return walk(def.schema, path12, depth + 1);
+      case "ZodOptional":
+      case "ZodDefault":
+      case "ZodNullable":
+      case "ZodReadonly":
+        return walk(def.innerType, path12, depth + 1);
+      case "ZodObject": {
+        const shape = def.shape();
+        for (const key of Object.keys(shape))
+          walk(shape[key], [...path12, key], depth + 1);
+        return;
+      }
+      case "ZodArray":
+        return walk(def.type, [...path12, ARRAY_ELEMENT], depth + 1);
+      case "ZodUnion":
+      case "ZodDiscriminatedUnion": {
+        const options = def.options;
+        const list = Array.isArray(options) ? options : [...options.values()];
+        for (const opt of list)
+          walk(opt, path12, depth + 1);
+        return;
+      }
+      default:
+        return;
+    }
+  };
+  walk(schema, [], 0);
+  return found;
+}
+function objectShapeOf(schema) {
+  let cur = schema;
+  for (let i = 0; i < 16 && cur?._def?.typeName === "ZodEffects"; i++) {
+    cur = cur._def.schema;
+  }
+  const shape = cur?.shape;
+  return shape;
+}
 var ListComps = z2.object({
   include: includeParam(["size", "timing", "bg", "counts"], "id + name only")
 }).strict();
@@ -456,11 +1011,31 @@ var SetComp = z2.object({
   workAreaDuration: z2.number().positive().optional(),
   bgColor: Color.optional()
 });
-var DeleteComp = z2.object({ compId: z2.number() });
+var DeleteComp = z2.object({
+  compId: z2.number(),
+  purgeUnusedSolids: z2.boolean().default(false).optional().describe("Also remove the solid footage items this comp's own layers used, once nothing else uses them. Off by default because a solid can be shared: one another comp still uses is kept and reported with the comps using it.")
+}).strict();
 var SetActiveComp = z2.object({ compId: z2.number() });
+var DuplicateComp = z2.object({
+  compId: z2.number(),
+  name: z2.string().optional().describe("Name for the copy. Omit to take AE's own ('<name> 2')."),
+  folderId: z2.number().optional().describe("Project folder to put the copy in. Must be a folder item id from get_project_summary."),
+  deep: z2.boolean().default(false).optional().describe("Also duplicate the nested precomps and re-point the copy's layers at them. Off by default, which matches AE's own Duplicate: a shallow copy shares its nested comps with the original, so editing one edits both."),
+  nameSuffix: z2.string().optional().describe("With deep:true, name each duplicated nested comp '<original><nameSuffix>'. Omit to let AE name them.")
+}).strict();
+var SnapshotComp = z2.object({
+  compId: z2.number(),
+  includeFingerprint: z2.boolean().default(false).optional().describe("Return the fingerprint itself as well as its id. Off by default \u2014 returning it reintroduces exactly the context cost a snapshot exists to avoid.")
+}).strict();
+var DiffComp = z2.object({
+  since: z2.string().describe("A snapshotId from an earlier snapshot_comp or diff_comp."),
+  compId: z2.number().optional().describe("Defaults to the comp the snapshot was taken of; pass it only to assert which comp you mean."),
+  includeFingerprint: z2.boolean().default(false).optional().describe("Return the new fingerprint as well as the diff. Off by default.")
+}).strict();
+var LAYER_SUMMARY_SECTIONS = ["flags", "timing", "parent"];
 var ListLayers = z2.object({
   compId: z2.number(),
-  include: includeParam(["flags", "timing", "parent"], "the id/index/name/type map alone")
+  include: includeParam(LAYER_SUMMARY_SECTIONS, "the id/index/name/type map alone")
 });
 var GetLayerFull = z2.object({
   compId: z2.number(),
@@ -491,7 +1066,8 @@ var CreateShapeLayer = z2.object({
   shapes: z2.array(z2.record(z2.string(), z2.unknown())).default([]),
   fill: Color.optional(),
   stroke: Color.optional(),
-  strokeWidth: z2.number().nonnegative().optional()
+  strokeWidth: z2.number().nonnegative().optional(),
+  position: z2.union([Vec2, Vec3, z2.literal("center")]).optional().describe("Where the layer's origin goes. Defaults to [0,0], which makes the layer's coordinate space the comp's \u2014 so vertices and shape positions you write afterwards are in comp pixels. 'center' is After Effects' own spawn point (the comp centre), which offsets every path you add by half a frame. The Anchor Point stays at [0,0] either way. A new shape layer is 2D, so use [x,y]; a three-component position needs set_layer threeDLayer:true first.")
 });
 var CreateSolidLayer = z2.object({
   compId: z2.number(),
@@ -524,14 +1100,22 @@ var SetLayer = z2.object({
   shy: z2.boolean().optional(),
   solo: z2.boolean().optional(),
   threeDLayer: z2.boolean().optional(),
-  blendingMode: z2.string().optional(),
+  // These two are keys into After Effects' own `BlendingMode` and
+  // `TrackMatteType` enumerations, looked up by name in `layers.jsx`. A name
+  // that is not in the enumeration is **ignored**, and the call still reports
+  // success — so the accepted spelling has to be visible here, and a value you
+  // are unsure of has to be read back off the layer rather than assumed.
+  blendingMode: z2.string().optional().describe("After Effects' BlendingMode constant name, upper case with underscores: NORMAL, MULTIPLY, SCREEN, OVERLAY, ADD, SUBTRACT, DIFFERENCE, DARKEN, LIGHTEN, COLOR_DODGE, COLOR_BURN, LINEAR_DODGE, LINEAR_BURN, SOFT_LIGHT, HARD_LIGHT, VIVID_LIGHT, LINEAR_LIGHT, PIN_LIGHT, HUE, SATURATION, COLOR, LUMINOSITY, STENCIL_ALPHA, STENCIL_LUMA, ALPHA_ADD, DISSOLVE. A name After Effects does not recognise leaves the mode unchanged without erroring, so read it back with get_layer_full if you are guessing."),
   label: z2.number().int().min(0).max(16).optional(),
   inPoint: z2.number().optional(),
   outPoint: z2.number().optional(),
   startTime: z2.number().optional(),
   stretch: z2.number().optional(),
   preserveTransparency: z2.boolean().optional(),
-  trackMatte: z2.object({ type: z2.string(), layerId: z2.number().optional() }).optional()
+  trackMatte: z2.object({
+    type: z2.string().describe("NO_TRACK_MATTE, ALPHA, ALPHA_INVERTED, LUMA or LUMA_INVERTED. Anything else leaves the matte unchanged without erroring."),
+    layerId: z2.number().optional()
+  }).optional()
 });
 var ParentLayer = z2.object({
   compId: z2.number(),
@@ -539,7 +1123,22 @@ var ParentLayer = z2.object({
   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 ReorderLayer = crossField(
+  z2.object({
+    compId: z2.number(),
+    layerId: z2.number(),
+    toIndex: z2.number().int().positive().optional().describe("Where the layer ENDS UP: its 1-based index after the move, counting from the front (1 renders in front of everything, numLayers is the back). Clamped to the stack. Prefer beforeLayerId/afterLayerId when you are placing this layer relative to another one \u2014 an index you read earlier may already be stale."),
+    beforeLayerId: z2.number().optional().describe("Put this layer directly IN FRONT OF (above) the layer with this id."),
+    afterLayerId: z2.number().optional().describe("Put this layer directly BEHIND (below) the layer with this id.")
+  }),
+  // One destination, resolved before it can reach ExtendScript — two readings of
+  // "where does it go" are a contract the schema should never let through.
+  {
+    kind: "exactlyOne",
+    fields: ["toIndex", "beforeLayerId", "afterLayerId"],
+    then: "`beforeLayerId`/`afterLayerId` are the safer two: this is the op that shifts every index below it, so an index read before the move may already be stale."
+  }
+);
 var SetTransform = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
@@ -584,14 +1183,24 @@ var SetInterpolation = z2.object({
   in: z2.enum(["linear", "bezier", "hold"]).optional(),
   out: z2.enum(["linear", "bezier", "hold"]).optional()
 });
-var SetTemporalEase = z2.object({
-  compId: z2.number(),
-  layerId: z2.number(),
-  propertyPath: PropertyPath,
-  keyIndex: z2.number().int().positive(),
-  easeIn: z2.object({ influence: z2.number(), speed: z2.number() }).optional(),
-  easeOut: z2.object({ influence: z2.number(), speed: z2.number() }).optional()
-});
+var SetTemporalEase = crossField(
+  z2.object({
+    compId: z2.number(),
+    layerId: z2.number(),
+    propertyPath: PropertyPath,
+    keyIndex: z2.number().int().positive(),
+    easeIn: z2.object({ influence: z2.number(), speed: z2.number() }).optional().describe("One influence/speed pair, applied to every dimension of the property. At least one of easeIn/easeOut is required."),
+    easeOut: z2.object({ influence: z2.number(), speed: z2.number() }).optional().describe("One influence/speed pair, applied to every dimension of the property.")
+  }),
+  // `keyframes.jsx` has always refused this, and still does — but it refused
+  // from inside After Effects, which meant a round trip and a write lease spent
+  // on a call that was never going to change anything.
+  {
+    kind: "atLeastOne",
+    fields: ["easeIn", "easeOut"],
+    then: "Each is one {influence, speed} pair; this tool sizes the ease array for the property itself."
+  }
+);
 var SetSpatialTangents = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
@@ -607,16 +1216,27 @@ var ClearExpression = z2.object({ compId: z2.number(), layerId: z2.number(), pro
 var ListEffects = z2.object({ compId: z2.number(), layerId: z2.number() });
 var AddEffect = z2.object({ compId: z2.number(), layerId: z2.number(), matchName: z2.string() });
 var RemoveEffect = z2.object({ compId: z2.number(), layerId: z2.number(), effectIndex: z2.number().int().positive() });
-var SetEffectParam = z2.object({
-  compId: z2.number(),
-  layerId: z2.number(),
-  effectIndex: z2.number().int().positive(),
-  paramName: z2.string().optional(),
-  paramMatchName: z2.string().optional(),
-  value: VecAny,
-  time: z2.number().optional(),
-  keyframe: z2.boolean().default(false).optional()
-});
+var SetEffectParam = crossField(
+  z2.object({
+    compId: z2.number(),
+    layerId: z2.number(),
+    effectIndex: z2.number().int().positive(),
+    paramName: z2.string().optional().describe("The parameter's display name as list_effects reports it, e.g. 'Blurriness'."),
+    paramMatchName: z2.string().optional().describe("The parameter's matchName, e.g. 'ADBE Gaussian Blur 2-0001'. Tried before paramName when both are given, so it is the one to use when a display name is ambiguous or localised."),
+    value: VecAny,
+    time: z2.number().optional(),
+    keyframe: z2.boolean().default(false).optional()
+  }),
+  // Neither one is not a call with a default — it is a call that resolves no
+  // property at all, and `effects.jsx` answers it with a bare "Effect param not
+  // found", which reads like the *name* was wrong rather than absent.
+  // Both together is legal and useful: matchName wins, name is the fallback.
+  {
+    kind: "atLeastOne",
+    fields: ["paramName", "paramMatchName"],
+    then: "list_effects on the layer reports both for every parameter of every effect."
+  }
+);
 var SetEffectEnabled = z2.object({ compId: z2.number(), layerId: z2.number(), effectIndex: z2.number().int().positive(), enabled: z2.boolean() });
 var ListAvailableEffects = z2.object({
   filter: z2.string().optional(),
@@ -755,7 +1375,9 @@ var AddMask = z2.object({
   inTangents: z2.array(Vec2).optional(),
   outTangents: z2.array(Vec2).optional(),
   closed: z2.boolean().default(true).optional(),
-  mode: z2.string().default("ADD").optional()
+  // A key into AE's `MaskMode`, looked up by name in `masks.jsx`; an
+  // unrecognised one leaves the mode alone rather than erroring.
+  mode: z2.string().default("ADD").optional().describe("Mask blend mode: ADD (default), NONE, SUBTRACT, INTERSECT, LIGHTEN, DARKEN or DIFFERENCE. Anything else leaves the mode unchanged without erroring.")
 });
 var SetMask = z2.object({
   compId: z2.number(),
@@ -765,7 +1387,7 @@ var SetMask = z2.object({
   inTangents: z2.array(Vec2).optional(),
   outTangents: z2.array(Vec2).optional(),
   closed: z2.boolean().optional(),
-  mode: z2.string().optional(),
+  mode: z2.string().optional().describe("Mask blend mode: ADD, NONE, SUBTRACT, INTERSECT, LIGHTEN, DARKEN or DIFFERENCE. Anything else leaves the mode unchanged without erroring."),
   inverted: z2.boolean().optional(),
   expansion: z2.number().optional(),
   feather: Vec2.optional(),
@@ -788,34 +1410,81 @@ 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: downsampleParam
-});
+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. The factor is always exactly what you asked for: the render sets the comp's resolution and puts it back, so a viewer left on Quarter or Third does not change the size of the frame you get.");
+var ScreenshotFrame = crossField(
+  z2.object({
+    compId: z2.number(),
+    time: z2.number().optional(),
+    /**
+     * Several times in one call, returned as one tiled sheet.
+     *
+     * Judging motion is a single visual question, and answering it used to cost
+     * one call per frame — three image blocks resident for the rest of the
+     * session, and three chances for After Effects to re-serve a stale buffer.
+     * Capped at six because past that each tile is too small to read at the
+     * pixel budget of one frame.
+     */
+    times: z2.array(z2.number()).min(2).max(6).optional().describe("2-6 times to render into one tiled contact sheet, in order, with the time burned into each tile. Cheaper than one call per frame and the whole point of it is judging motion. Mutually exclusive with `time`."),
+    downsample: downsampleParam
+  }),
+  // Enforced here rather than in the panel: two readings of "which frame did
+  // you want" reaching ExtendScript at all is a contract the schema should
+  // never have let through. `atMostOne` and not `exactlyOne` — neither is a
+  // legal call, and means the comp's current time.
+  {
+    kind: "atMostOne",
+    fields: ["time", "times"],
+    then: "`time` is one frame, `times` is a contact sheet of 2-6 of them; omit both for the comp's current time."
+  }
+);
 var ScreenshotLayer = z2.object({
   compId: z2.number(),
   layerId: z2.number(),
   time: z2.number().optional(),
   downsample: downsampleParam
 });
+var diffParam = z2.boolean().default(false).optional().describe("Fingerprint the comp before and after this call and append only what changed (layers added/removed/renamed/retimed/re-parented, keyframe counts, expression and effect counts). A few dozen tokens instead of reading the comp back. If the call fails, the diff of what landed before it stopped is appended to the error.");
+var diffCompIdParam = z2.number().optional().describe("Which comp `diff` should fingerprint. Defaults to the comps this call names, else the comp open in the viewer.");
 var RunBatch = z2.object({
   ops: z2.array(z2.object({ op: z2.string(), args: z2.unknown() })),
-  transactional: z2.boolean().default(true).optional(),
-  undoGroupName: z2.string().default("AE MCP Batch").optional()
+  transactional: z2.boolean().default(true).optional().describe("Stop at the first failing op instead of running the rest. Nothing rolls back either way \u2014 the ops before the failure stay applied, and the error says where it stopped."),
+  undoGroupName: z2.string().default("AE MCP Batch").optional().describe(`What the user sees in After Effects' Edit > Undo menu. A chunked batch numbers its steps from this, e.g. "AE MCP Batch (3)".`),
+  singleUndo: z2.boolean().default(false).optional().describe("Force the whole batch into ONE undo step, whatever its size, by running it in a single blocking ExtendScript call. Up to 2000 ops. The cost is real: After Effects' interface is frozen for the entire batch and no progress is reported, so the user sees nothing until it finishes. Without it a batch over 500 ops is chunked and lands as one undo step per chunk of 25 \u2014 the result reports the exact count. Reach for this only when the user has to be able to undo the work with a single Cmd-Z."),
+  diff: diffParam,
+  diffCompId: diffCompIdParam
 });
 var GetProjectSummary = z2.object({}).strict();
 var FindLayers = z2.object({
   compId: z2.number().optional(),
   namePattern: z2.string().optional(),
   type: z2.string().optional(),
-  hasEffectMatchName: z2.string().optional()
-});
-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.")
+  hasEffectMatchName: z2.string().optional(),
+  // Same section names as list_layers, opposite default: a search is for
+  // learning which layers exist and what to address them by, so omitting this
+  // means the core alone rather than everything (issue #87). `includeParam`
+  // is not reused because its sentence says "omit for all of them".
+  include: z2.array(z2.enum(LAYER_SUMMARY_SECTIONS)).optional().describe(`Sections to add to each match: ${LAYER_SUMMARY_SECTIONS.join(", ")} \u2014 the same names as list_layers. Omit it (or pass []) for id/index/name/sourceType plus compId/compName only; unlike list_layers, omitting it here does NOT return every section. The result echoes what was included.`)
 });
+var RunJsx = crossField(
+  z2.object({
+    code: z2.string().optional().describe("The ExtendScript to run. Exactly one of `code` or `scriptPath`."),
+    scriptPath: z2.string().optional().describe("Absolute path to a .jsx file to run instead of `code`. The server reads it, so a long script never enters the conversation. Exactly one of `code` or `scriptPath`."),
+    libraries: z2.array(z2.string()).optional().describe("Absolute paths to .jsx files inlined ahead of the script, sharing its scope, so their functions are callable from it. The server reads them, so their text never enters the conversation. They are re-evaluated on every call \u2014 keep them to declarations, not to work. Put shared helpers here rather than pasting them into every script."),
+    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."),
+    diff: diffParam,
+    diffCompId: diffCompIdParam
+  }),
+  // `resolveRunJsxSource` refuses both and neither too, and keeps doing so —
+  // it is reachable from `run_batch`, whose steps are never zod-validated. What
+  // the rule buys here is the half that runs *before* the call: declared, it
+  // reaches the emitted JSON Schema, so the model sees the choice rather than
+  // discovering it.
+  {
+    kind: "exactlyOne",
+    fields: ["code", "scriptPath"],
+    then: "Prefer `scriptPath` for anything long \u2014 the server reads the file, so the script never enters the conversation."
+  }
+);
 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."),
@@ -829,6 +1498,32 @@ var CreateFootageLayer = z2.object({
   position: VecAny.optional(),
   startTime: z2.number().optional()
 });
+var PurgeUnusedFootage = z2.object({
+  solidsOnly: z2.boolean().default(true).optional().describe("Only remove solids \u2014 the items behind solid and adjustment layers. Pass false to remove every footage item no comp uses, imported files and placeholders included, which is what AE's own Remove Unused Footage does. Comps and folders are never removed either way."),
+  dryRun: z2.boolean().default(false).optional().describe("List what would be removed without removing anything \u2014 not even an undo step."),
+  folderId: z2.number().optional().describe("Restrict the sweep to one project folder and everything nested under it. A folder id from get_project_summary; omit for the whole project.")
+}).strict();
+var AudioCue = z2.object({
+  footageId: z2.number().optional().describe("Project item id of an already-imported sound. Give this or `path`, not both."),
+  path: z2.string().min(1).optional().describe("Absolute path to a sound file. Imported once per call however many cues name it, and an item already in the project from that path is reused rather than imported again."),
+  time: z2.number().describe("Comp time in seconds where the cue starts."),
+  levelDb: z2.number().optional().describe("Level in decibels, the same unit After Effects shows. 0 is the file untouched, -6 is roughly half as loud, negative is quieter. Defaults to 0, written explicitly so the result is the same on every machine."),
+  name: z2.string().optional().describe("Layer name. Defaults to namePrefix + the file's basename without its extension."),
+  inPoint: z2.number().optional().describe("Trim the layer's in point to this COMP time. Must not be earlier than `time`. Omit to play from the start of the file."),
+  outPoint: z2.number().optional().describe("Trim the layer's out point to this COMP time. Omit to play to the end of the file."),
+  label: z2.union([z2.number().int().min(0).max(16), z2.string()]).optional().describe("AE label colour, as an index 0-16 or a name (red, yellow, aqua, pink, lavender, peach, seafoam, blue, green, purple, orange, brown, fuchsia, cyan, sandstone, darkgreen)."),
+  loop: z2.boolean().optional().describe("Loop the sound until `outPoint`, or until the end of the comp when no outPoint is given \u2014 for beds and ambiences. Enables time remapping with a wrap-around expression on Time Remap; the layer's in point still trims the front of the file the way it does on any layer. Default false: the file plays once."),
+  fadeIn: z2.number().min(0).optional().describe("Seconds to fade in from `fadeFloorDb` up to `levelDb`, as keyframes on Audio Levels starting at the layer's in point. Default 0 (no fade). fadeIn + fadeOut must fit inside the cue's placed length or the cue is refused by index."),
+  fadeOut: z2.number().min(0).optional().describe("Seconds to fade out from `levelDb` down to `fadeFloorDb`, ending at the layer's out point. Default 0 (no fade). fadeIn + fadeOut must fit inside the cue's placed length or the cue is refused by index."),
+  stretch: z2.number().positive().optional().describe("Time stretch as a percentage: 100 is unchanged, 200 plays at half speed (lower pitch, twice as long), 50 at double speed. Must be greater than 0. The layer's start time and any trim are re-asserted after it, since After Effects moves them when stretch changes. Default 100.")
+}).strict();
+var PlaceAudioCues = z2.object({
+  compId: z2.number(),
+  cues: z2.array(AudioCue).min(1).max(200),
+  namePrefix: z2.string().default("SFX_").optional().describe('Prefix for cues that do not name themselves. Pass "" for no prefix.'),
+  fadeFloorDb: z2.number().optional().describe("The level in decibels that every fadeIn starts from and every fadeOut ends at. Default -48, the bottom of After Effects' own Audio Levels slider and 1/256 of the recorded amplitude \u2014 near-silence. Must be below each faded cue's levelDb. One floor for the whole list."),
+  dryRun: z2.boolean().default(false).optional().describe("Resolve and check the whole list without importing, creating or changing anything \u2014 not even an undo step. Returns counts, the files it would import, the items it would reuse and the failing cues by index \u2014 never the whole resolved list.")
+}).strict();
 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."),
@@ -837,19 +1532,35 @@ var ExportMogrt = z2.object({
   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 GetHouseStyle = z2.object({
+  detail: z2.enum(["summary", "full"]).default("summary").optional().describe("'summary' (default) is a few hundred tokens: palette as named hexes, type, motion defaults, layout rules, and what it could not summarise. 'full' returns the whole document \u2014 use it before editing the guide with set_house_style, or when the summary is not enough.")
+}).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."),
   overwrite: z2.boolean().default(false).optional().describe("Required to replace an existing guide. Read it with get_house_style and merge first \u2014 this is not a patch.")
 }).strict();
 var CheckSetup = z2.object({}).strict();
 var SetupPanel = z2.object({
-  enableDebugMode: z2.boolean().default(true).optional().describe("Also enable Adobe's PlayerDebugMode preference, which AE requires to load this unsigned panel. Default true."),
+  enableDebugMode: z2.boolean().default(true).optional().describe("Also set Adobe's PlayerDebugMode preference, which AE requires to load this unsigned panel, and CEP's LogLevel where it was never set, so CEP's own log records why a panel failed to load (issue #91). Default true."),
   force: z2.boolean().default(false).optional().describe("Replace an existing symlinked (development) install with a copy. Default false.")
 }).strict();
-var GUIDE_TOPICS = ["ae-setup", "after-effects", "style-guide"];
+var GUIDE_TOPICS = [
+  "ae-setup",
+  "after-effects",
+  "animation",
+  "assembly",
+  "extendscript-gotchas",
+  "issue-journal",
+  "mogrt-and-footage",
+  "shapes",
+  "sound",
+  "style-guide",
+  "text",
+  "whats-new"
+];
 var AeGuide = z2.object({
-  topic: z2.enum(GUIDE_TOPICS).describe("after-effects: building, animating, easing, expressions, the traps. style-guide: capturing the user's look. ae-setup: connecting to AE when a tool cannot reach it.")
+  topic: z2.enum(GUIDE_TOPICS).describe("after-effects: the core \u2014 orienting, bounded reads, verifying a write, screenshots, the bridge failures \u2014 start here; it points at one topic per subject. animation: keyframes, easing, rigging, expressions. shapes: shape layers and their Contents. text: text layers. assembly: shots placed into a master comp, markers, retiming. extendscript-gotchas: read before writing raw ExtendScript for run_jsx. sound: sound effects and levels. mogrt-and-footage: exporting a .mogrt, importing footage. issue-journal: when a tool fought back. whats-new: what changed, one section per release, when a call behaves differently from what you expected or a project is being brought up to date after an upgrade. style-guide: capturing the user's look. ae-setup: connecting to AE when a tool cannot reach it."),
+  since: z2.string().regex(/^v?\d+\.\d+\.\d+$/, "must be a version like 0.4.0").optional().describe("whats-new only: return just the releases newer than this version \u2014 the version named is the one already absorbed and is excluded \u2014 behind the guide's preamble, or one line saying nothing is newer. Use the version a project's docs record as last absorbed. The answer opens with the server's own version. Rejected on any other topic, since there is nothing there to filter.")
 }).strict();
 var InitProject = z2.object({
   dir: z2.string().optional().describe("Folder to create or fill, absolute or relative to the server's working directory. Ask the user if you do not know; do not invent one."),
@@ -862,19 +1573,29 @@ var LogIssue = z2.object({
   symptom: z2.string().min(3).describe("What went wrong, including the exact error text and the call that produced it."),
   workaround: z2.string().min(3).describe("What actually worked \u2014 concrete enough for the next session to apply without rediscovering it."),
   cause: z2.string().optional().describe("Why it happens, if you worked it out."),
-  tools: z2.array(z2.string()).optional().describe("Tool names involved, e.g. ['set_temporal_ease'].")
+  tools: z2.array(z2.string()).optional().describe("Tool names involved, e.g. ['set_temporal_ease']. With errorText, this is what a later failure is matched on."),
+  errorText: z2.string().optional().describe("The exact error text the failing call returned, verbatim. The next time a call to one of `tools` fails with matching text, its error names this entry \u2014 and a later log_issue with the same tool and error text extends this entry instead of creating a second one under a different title."),
+  kind: z2.enum(["tool-bug", "ae-quirk"]).default("tool-bug").optional().describe("'tool-bug' (default): something these tools get wrong, which a later release may fix \u2014 so the entry is archived once it was last seen on an older server than the one running. 'ae-quirk': After Effects itself behaving unlike its documentation; no release changes that, so it is never archived by version."),
+  scope: z2.enum(["project", "user"]).default("project").optional().describe("'project' (default) for this project's footage, comps or files. 'user' for how these tools or After Effects behave \u2014 that journal travels with the person, so every future project starts knowing it. Reported back as 'home' when there is no project folder to write into.")
 }).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."),
   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.")
+  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. Ids are unique only within a journal, so prefix with the entry's scope ('user:my-entry') when the listing shows one in each."),
+  detail: z2.enum(["index", "full"]).default("index").optional().describe("'index' (default) is one line per entry: id, title, tools, kind, when and on which version it was last seen, counts \u2014 read the one you need with `id`. 'full' returns every matching entry's whole body and costs thousands of tokens."),
+  scope: z2.enum(["all", "project", "user"]).default("all").optional().describe("Which journal to read. 'all' (default) merges this project's with the user's cross-project one and tags every entry with the scope it came from."),
+  limit: z2.number().int().positive().max(500).default(50).optional().describe("Most entries to return. Anything held back is counted in `omitted`."),
+  includeArchived: z2.boolean().default(false).optional().describe("Also list archived entries \u2014 not seen for 30 days, last seen on an older server than this one, or retired with archive_issue \u2014 each flagged with its reason. Default false: they are hidden and only counted in `archivedCount`. An `id` read always returns the entry, archived or not.")
 }).strict();
 var MarkIssueReported = z2.object({
-  id: z2.string().describe("The entry id returned by log_issue or list_known_issues."),
+  id: z2.string().describe("The entry id returned by log_issue or list_known_issues. Prefix with its scope ('user:my-entry') when the same id exists in both journals."),
   url: z2.string().optional().describe("Link to the issue that was opened.")
 }).strict();
+var ArchiveIssue = z2.object({
+  id: z2.string().describe("The entry id from log_issue or list_known_issues. Prefix with its scope ('user:my-entry') when the same id exists in both journals \u2014 only the one named moves."),
+  reason: z2.string().min(3).describe("Why it is being retired, one line \u2014 the URL of the report that already covers it, the release that fixed it, or where the lesson was moved to.")
+}).strict();
 var AwaitJob = z2.object({ jobId: z2.string(), timeoutMs: z2.number().int().positive().default(6e5).optional() });
 var GetJob = z2.object({ jobId: z2.string() });
 var CancelJob = z2.object({ jobId: z2.string() });
@@ -887,6 +1608,9 @@ var OpSchemas = {
   set_comp: SetComp,
   delete_comp: DeleteComp,
   set_active_comp: SetActiveComp,
+  duplicate_comp: DuplicateComp,
+  snapshot_comp: SnapshotComp,
+  diff_comp: DiffComp,
   // layers
   list_layers: ListLayers,
   get_layer_full: GetLayerFull,
@@ -949,6 +1673,9 @@ var OpSchemas = {
   // footage
   import_footage: ImportFootage,
   create_footage_layer: CreateFootageLayer,
+  purge_unused_footage: PurgeUnusedFootage,
+  // audio
+  place_audio_cues: PlaceAudioCues,
   // motion graphics templates
   export_mogrt: ExportMogrt,
   // raw
@@ -969,91 +1696,116 @@ var OpSchemas = {
   // issue journal
   log_issue: LogIssue,
   list_known_issues: ListKnownIssues,
-  mark_issue_reported: MarkIssueReported
+  mark_issue_reported: MarkIssueReported,
+  archive_issue: ArchiveIssue
 };
-
-// src/util/errors.ts
-var BridgeUnreachableError = class _BridgeUnreachableError extends Error {
-  constructor(port, cause) {
-    super(_BridgeUnreachableError.message(port, cause));
-    this.port = port;
-    this.name = "BridgeUnreachableError";
-  }
-  port;
-  static message(port, cause) {
-    return [
-      `Cannot reach the After Effects panel at http://127.0.0.1:${port}.`,
-      cause ? `Underlying error: ${cause.message}` : "",
-      "",
-      "Call the check_setup tool to find out why, then relay its nextSteps to the user.",
-      "In most cases the fix is either running setup_panel (installs the panel) or",
-      "simply opening After Effects."
-    ].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 {
-  /**
-   * `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;
+var OpMutation = {
+  // comps
+  list_comps: "read",
+  get_comp: "read",
+  get_comp_tree: "read",
+  create_comp: "write",
+  set_comp: "write",
+  delete_comp: "write",
+  set_active_comp: "write",
+  duplicate_comp: "write",
+  // Fingerprints: they forward a read to the panel and keep the answer in the
+  // server. Nothing is written to the project or the undo stack, so they must
+  // not queue — the point of a diff is checking on a write that is in flight.
+  snapshot_comp: "read",
+  diff_comp: "read",
+  // layers
+  list_layers: "read",
+  get_layer_full: "read",
+  create_text_layer: "write",
+  create_shape_layer: "write",
+  create_solid_layer: "write",
+  create_null_layer: "write",
+  create_adjustment_layer: "write",
+  create_precomp_layer: "write",
+  create_camera_layer: "write",
+  create_light_layer: "write",
+  duplicate_layer: "write",
+  delete_layer: "write",
+  set_layer: "write",
+  parent_layer: "write",
+  reorder_layer: "write",
+  // transforms
+  set_transform: "write",
+  // keyframes
+  add_keyframe: "write",
+  remove_keyframe: "write",
+  get_keyframes: "read",
+  set_interpolation: "write",
+  set_temporal_ease: "write",
+  set_spatial_tangents: "write",
+  // expressions
+  get_expression: "read",
+  set_expression: "write",
+  toggle_expression: "write",
+  clear_expression: "write",
+  // effects
+  list_effects: "read",
+  add_effect: "write",
+  remove_effect: "write",
+  set_effect_param: "write",
+  set_effect_enabled: "write",
+  list_available_effects: "read",
+  // text
+  set_text: "write",
+  add_text_animator: "write",
+  // shapes
+  set_shape_path: "write",
+  add_shape_content: "write",
+  set_shape_property: "write",
+  // masks
+  add_mask: "write",
+  set_mask: "write",
+  remove_mask: "write",
+  // markers
+  add_marker: "write",
+  remove_marker: "write",
+  // vision — read-only despite being the slowest thing here. `screenshot_*`
+  // borrows the comp's resolutionFactor and restores it in a `finally`;
+  // nothing in the project changes.
+  screenshot_frame: "read",
+  screenshot_layer: "read",
+  // batch
+  run_batch: "write",
+  // explore
+  get_project_summary: "read",
+  find_layers: "read",
+  // footage
+  import_footage: "write",
+  create_footage_layer: "write",
+  // Removes project items. A dryRun changes nothing, but the table is per op,
+  // not per call — a dry run waiting behind a batch costs a little time and a
+  // real one interleaving with it costs the batch's undo step.
+  purge_unused_footage: "write",
+  // audio cues — imports footage and adds layers.
+  place_audio_cues: "write",
+  // motion graphics templates — saves the project before exporting.
+  export_mogrt: "write",
+  // raw — the script is the caller's and may do anything. Assume the worst.
+  run_jsx: "write",
+  // house style — written over the bridge into a file beside the .aep.
+  get_house_style: "read",
+  set_house_style: "write",
+  // jobs
+  await_job: "server",
+  get_job: "server",
+  cancel_job: "server",
+  // setup
+  check_setup: "server",
+  setup_panel: "server",
+  init_project: "server",
+  // guidance
+  ae_guide: "server",
+  // issue journal
+  log_issue: "server",
+  list_known_issues: "server",
+  mark_issue_reported: "server",
+  archive_issue: "server"
 };
 
 // src/util/logger.ts
@@ -1066,32 +1818,18 @@ var logger = {
   }
 };
 
-// src/bridge/discovery.ts
-import fs2 from "node:fs";
-import os2 from "node:os";
-import path3 from "node:path";
-var DEFAULT_PORT = 7777;
-function discoverPort() {
-  const envPort = process.env.AE_MCP_PORT;
-  if (envPort) {
-    const n = parseInt(envPort, 10);
-    if (Number.isFinite(n)) return n;
-  }
-  try {
-    const f = path3.join(os2.homedir(), ".engineroom-ae-mcp", "port");
-    if (fs2.existsSync(f)) {
-      const txt = fs2.readFileSync(f, "utf8").trim();
-      const n = parseInt(txt, 10);
-      if (Number.isFinite(n)) return n;
-    }
-  } catch {
-  }
-  return DEFAULT_PORT;
-}
-
 // 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_OPS = /* @__PURE__ */ new Set([
+  "run_batch",
+  "run_jsx",
+  "screenshot_frame",
+  "screenshot_layer",
+  "export_mogrt",
+  "import_footage",
+  "place_audio_cues",
+  "purge_unused_footage"
+]);
 var SLOW_OP_TIMEOUT_MS = 3e5;
 function opTimeoutMs(op) {
   const raw = process.env.AE_MCP_OP_TIMEOUT_MS?.trim();
@@ -1103,12 +1841,61 @@ function opTimeoutMs(op) {
   return op && SLOW_OPS.has(op) ? SLOW_OP_TIMEOUT_MS : DEFAULT_OP_TIMEOUT_MS;
 }
 var HEALTH_TIMEOUT_MS = 2e3;
+var LISTENER_SETTLE_MS = 750;
+function probeSummary(located) {
+  if (located.probed.length === 0) return "";
+  const busy = located.probed.find((p) => p.status === "busy");
+  const parts = located.probed.map((p) => p.detail);
+  const head = `Also looked for the panel on port${located.probed.length > 1 ? "s" : ""} ${located.probed.map((p) => p.port).join(", ")}: ${parts.join("; ")}.`;
+  const pinned = pinnedPort();
+  const pin = pinned !== null ? ` AE_MCP_PORT pins this server to port ${pinned}, so no other port was tried; unset it (or point it at the port check_setup reports) to let the server look at ${DEFAULT_PORT} and the port file.` : "";
+  return busy ? `${head} A listener on port ${busy.port} may be the panel with After Effects busy; the next call looks again.${pin}` : `${head}${pin}`;
+}
 var HttpClient = class {
   port;
   base;
-  constructor(port) {
+  /** The port this client started on — what a later drift is measured against. */
+  initialPort;
+  listeners = [];
+  candidatesFn;
+  constructor(port, opts = {}) {
     this.port = port ?? discoverPort();
+    this.initialPort = this.port;
     this.base = `http://127.0.0.1:${this.port}`;
+    this.candidatesFn = opts.candidates ?? portCandidates;
+  }
+  /** The ports a rediscovery will ask, in order. Exposed so `check_setup` asks the same ones. */
+  candidates() {
+    return this.candidatesFn();
+  }
+  onPortChange(listener) {
+    this.listeners.push(listener);
+  }
+  /**
+   * Move to another port and let the dependants follow before anything else
+   * is sent there. The wait is bounded: a listener that never settles must not
+   * turn a port switch into a hang.
+   */
+  async switchPort(next) {
+    const previous = this.port;
+    if (next === previous) return;
+    this.port = next;
+    this.base = `http://127.0.0.1:${next}`;
+    logger.warn(`Bridge port changed: ${previous} -> ${next}`);
+    await Promise.race([
+      Promise.all(this.listeners.map((l) => Promise.resolve().then(() => l(next, previous)).catch((e) => {
+        logger.warn(`port-change listener failed: ${e.message}`);
+      }))),
+      new Promise((r) => setTimeout(r, LISTENER_SETTLE_MS).unref?.())
+    ]);
+  }
+  /**
+   * Ask the candidate ports where the panel is now. Returns the probe that
+   * answered as the panel, or null — and the whole list of what was asked, so
+   * a failure can say what it looked at.
+   */
+  async rediscover() {
+    return locatePanel(this.candidates());
   }
   // `bundleHash` is absent on panels installed before it was added; callers must
   // treat undefined as "too old to say" rather than as a mismatch.
@@ -1124,7 +1911,12 @@ var HttpClient = class {
       throw new BridgeUnreachableError(this.port, e);
     }
   }
-  async runOp(op, args, progressToken) {
+  /**
+   * One POST to /op on the current port. Its own `AbortSignal.timeout`, created
+   * here, so a retry after a port switch gets the full budget rather than the
+   * remainder of a clock that started before the refusal.
+   */
+  async postOp(op, args, progressToken) {
     let resp;
     const timeoutMs = opTimeoutMs(op);
     try {
@@ -1145,10 +1937,47 @@ 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, data.code);
+      throw new AeError(data.error, data.stack, data.line, data.code, data.source);
     }
     return data.result;
   }
+  /**
+   * Forward an op, following the panel if it has moved.
+   *
+   * The port is discovered once, at construction, and every op posts there —
+   * which is how `check_setup` could report the panel healthy on 7777 while
+   * every op failed on 7778 for a week (issue #92): the panel had moved after
+   * this server read the port file. So a *refused* connection is taken as a
+   * cue to look again. Only a refusal, and this is the whole safety argument:
+   * refused means the request never reached a panel, so sending it again
+   * cannot run anything twice. A timeout is the opposite case — the call did
+   * reach After Effects and may still be running — and must never be retried
+   * (issue #43 is what a duplicated `run_jsx` costs).
+   *
+   * The retry happens only when the search turns up a *different* port that
+   * answers as the panel. The same port answering again means the refusal was
+   * something else, and that is the original error's story to tell.
+   */
+  async runOp(op, args, progressToken) {
+    try {
+      return await this.postOp(op, args, progressToken);
+    } catch (e) {
+      if (!(e instanceof BridgeUnreachableError)) throw e;
+      const refusedPort = this.port;
+      const located = await this.rediscover();
+      if (located.found && located.found.port !== refusedPort) {
+        logger.warn(
+          `\`${op}\` was refused on port ${refusedPort}; the panel is answering on port ${located.found.port}. Switching and re-sending once.`
+        );
+        await this.switchPort(located.found.port);
+        return await this.postOp(op, args, progressToken);
+      }
+      const summary = probeSummary(located);
+      if (summary) e.message += `
+${summary}`;
+      throw e;
+    }
+  }
   async cancel(jobId) {
     try {
       await fetch(`${this.base}/cancel`, {
@@ -1165,11 +1994,12 @@ var HttpClient = class {
 // src/bridge/wsClient.ts
 import WebSocket from "ws";
 var WsClient = class {
-  constructor(port, jobs) {
-    this.port = port;
+  constructor(bridge, jobs) {
+    this.bridge = bridge;
     this.jobs = jobs;
+    bridge.onPortChange(() => this.reconnect());
   }
-  port;
+  bridge;
   jobs;
   ws;
   reconnectTimer;
@@ -1185,26 +2015,46 @@ var WsClient = class {
     } catch {
     }
   }
+  /** Drop the current socket and connect to wherever the bridge is now. Resolves on open, or on failure. */
+  reconnect() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    const old = this.ws;
+    this.ws = void 0;
+    try {
+      old?.removeAllListeners();
+      old?.on("error", () => {
+      });
+      old?.close();
+    } catch {
+    }
+    return this.connect();
+  }
   connect() {
-    if (this.stopped) return;
-    const url = `ws://127.0.0.1:${this.port}/events`;
+    if (this.stopped) return Promise.resolve();
+    const url = `ws://127.0.0.1:${this.bridge.port}/events`;
     const ws = new WebSocket(url);
     this.ws = ws;
-    ws.on("open", () => logger.debug("WS connected", url));
-    ws.on("message", (data) => {
-      let evt;
-      try {
-        evt = JSON.parse(data.toString());
-      } catch {
-        return;
-      }
-      this.handleEvent(evt);
-    });
-    ws.on("close", () => {
-      if (this.stopped) return;
-      this.reconnectTimer = setTimeout(() => this.connect(), 1500);
-    });
-    ws.on("error", () => {
+    return new Promise((resolve) => {
+      ws.on("open", () => {
+        logger.debug("WS connected", url);
+        resolve();
+      });
+      ws.on("message", (data) => {
+        let evt;
+        try {
+          evt = JSON.parse(data.toString());
+        } catch {
+          return;
+        }
+        this.handleEvent(evt);
+      });
+      ws.on("close", () => {
+        resolve();
+        if (this.stopped || this.ws !== ws) return;
+        this.reconnectTimer = setTimeout(() => this.connect(), 1500);
+      });
+      ws.on("error", () => {
+      });
     });
   }
   handleEvent(evt) {
@@ -1225,6 +2075,168 @@ var WsClient = class {
   }
 };
 
+// src/bridge/writeQueue.ts
+var DEFAULT_MAX_WAIT_MS = 6e5;
+var DEFAULT_MAX_DEPTH = 64;
+function queueWaitMs() {
+  return envNumber("AE_MCP_WRITE_QUEUE_WAIT_MS", DEFAULT_MAX_WAIT_MS);
+}
+function queueMaxDepth() {
+  return envNumber("AE_MCP_WRITE_QUEUE_DEPTH", DEFAULT_MAX_DEPTH);
+}
+function envNumber(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (Number.isFinite(n) && n > 0) return n;
+  logger.warn(`Ignoring ${name}=${raw} \u2014 expected a positive number.`);
+  return fallback;
+}
+var WriteQueue = class {
+  holder = null;
+  waiting = [];
+  maxWaitMs;
+  maxDepth;
+  constructor(opts = {}) {
+    this.maxWaitMs = opts.maxWaitMs ?? queueWaitMs();
+    this.maxDepth = opts.maxDepth ?? queueMaxDepth();
+  }
+  /** For tests and diagnostics. */
+  get depth() {
+    return this.waiting.filter((w) => !w.done).length;
+  }
+  get held() {
+    return this.holder;
+  }
+  /**
+   * The longest a lease may be held past its call by `extendUntil` — a leak
+   * guard for a job that never reports completion (a dropped WS, say).
+   *
+   * Twice the wait ceiling on purpose. Anything already queued behind that job
+   * has hit its own deadline and gone by then, so expiring the hold can never
+   * hand the lock to a writer while the batch is still going.
+   */
+  get holdCeilingMs() {
+    return this.maxWaitMs * 2;
+  }
+  /**
+   * Wait for the lock, then return the lease.
+   *
+   * Rejects rather than resolving late when the request was cancelled, when the
+   * wait ran past `maxWaitMs`, or when the queue is full. In every one of those
+   * cases the caller must not go on to hit the bridge — nothing was written,
+   * and the error says so, which is what makes re-sending safe there and unsafe
+   * after a bridge timeout.
+   */
+  acquire(op, signal) {
+    if (signal?.aborted) {
+      return Promise.reject(new WriteQueueCancelledError(op));
+    }
+    if (this.holder === null && this.depth === 0) {
+      this.holder = op;
+      return Promise.resolve(this.makeLease(null));
+    }
+    if (this.depth >= this.maxDepth) {
+      return Promise.reject(new WriteQueueFullError(op, this.maxDepth, this.holder ?? "another write"));
+    }
+    const behind = this.holder ?? this.waiting.find((w) => !w.done)?.op ?? "another write";
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        op,
+        enqueuedAt: Date.now(),
+        behind,
+        done: false,
+        settle: resolve,
+        fail: reject,
+        cleanup: () => {
+        }
+      };
+      const timer = setTimeout(() => {
+        if (waiter.done) return;
+        waiter.done = true;
+        waiter.cleanup();
+        reject(new WriteQueueWaitError(op, this.maxWaitMs, waiter.behind));
+        this.pump();
+      }, this.maxWaitMs);
+      timer.unref?.();
+      const onAbort = () => {
+        if (waiter.done) return;
+        waiter.done = true;
+        waiter.cleanup();
+        reject(new WriteQueueCancelledError(op));
+        this.pump();
+      };
+      waiter.cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.waiting.push(waiter);
+    });
+  }
+  makeLease(wait) {
+    let released = false;
+    let hold = null;
+    const queue = this;
+    return {
+      wait,
+      extendUntil(p) {
+        hold = p;
+        if (released) settleHold();
+      },
+      release() {
+        if (released) return;
+        released = true;
+        if (hold) settleHold();
+        else queue.handOff();
+      }
+    };
+    function settleHold() {
+      const p = hold;
+      hold = null;
+      if (!p) return;
+      const ceiling = queue.holdCeilingMs;
+      let fired = false;
+      const done = () => {
+        if (fired) return;
+        fired = true;
+        queue.handOff();
+      };
+      const t = setTimeout(() => {
+        if (fired) return;
+        logger.warn(
+          `A write held the After Effects queue for over ${Math.round(ceiling / 1e3)}s without its job reporting completion; releasing it.`
+        );
+        done();
+      }, ceiling);
+      t.unref?.();
+      p.then(done, done).finally(() => clearTimeout(t));
+    }
+  }
+  handOff() {
+    this.holder = null;
+    this.pump();
+  }
+  pump() {
+    if (this.holder !== null) return;
+    while (this.waiting.length > 0) {
+      const next = this.waiting.shift();
+      if (next.done) continue;
+      next.done = true;
+      next.cleanup();
+      this.holder = next.op;
+      next.settle(this.makeLease({ queuedBehind: next.behind, waitedMs: Date.now() - next.enqueuedAt }));
+      return;
+    }
+  }
+};
+function mergeWait(value, wait) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const obj = value;
+  if ("queuedBehind" in obj || "waitedMs" in obj) return null;
+  return { ...obj, ...wait };
+}
+
 // src/jobs/manager.ts
 var JobManager = class {
   jobs = /* @__PURE__ */ new Map();
@@ -1241,10 +2253,34 @@ var JobManager = class {
     this.jobs.set(jobId, s);
     return s;
   }
+  /**
+   * Forward this job's progress to `fn` until the job settles or the returned
+   * function is called.
+   *
+   * The caller owns the lifetime, and the returned unbind is not optional: an
+   * emitter is bound for the span of one MCP request — `await_job` — and one
+   * left behind would keep sending `notifications/progress` on that request's
+   * token after its response, which is exactly what a spec-compliant client
+   * stops listening for the moment the response arrives (issue #82). `flush`
+   * drops every emitter when the job finishes, so unbinding after that is a
+   * no-op rather than an error.
+   */
   bindProgressEmitter(jobId, fn) {
     const arr = this.progressEmitters.get(jobId) ?? [];
     arr.push(fn);
     this.progressEmitters.set(jobId, arr);
+    return () => this.unbindProgressEmitter(jobId, fn);
+  }
+  unbindProgressEmitter(jobId, fn) {
+    const arr = this.progressEmitters.get(jobId);
+    if (!arr) return;
+    const i = arr.indexOf(fn);
+    if (i >= 0) arr.splice(i, 1);
+    if (arr.length === 0) this.progressEmitters.delete(jobId);
+  }
+  /** How many emitters a job currently has. Exists for the tests. */
+  progressEmitterCount(jobId) {
+    return this.progressEmitters.get(jobId)?.length ?? 0;
   }
   reportProgress(jobId, progress, total, message) {
     const s = this.jobs.get(jobId);
@@ -1324,6 +2360,54 @@ var JobManager = class {
   }
 };
 
+// src/snapshots/store.ts
+var DEFAULT_MAX = 32;
+var SnapshotStore = class {
+  constructor(max = DEFAULT_MAX) {
+    this.max = max;
+  }
+  max;
+  snapshots = /* @__PURE__ */ new Map();
+  seq = 0;
+  store(fingerprint) {
+    this.seq += 1;
+    const snapshot = {
+      id: `snap_${this.seq}`,
+      compId: fingerprint.compId,
+      compName: fingerprint.name,
+      layerCount: Array.isArray(fingerprint.layers) ? fingerprint.layers.length : 0,
+      takenAt: Date.now(),
+      fingerprint
+    };
+    this.snapshots.set(snapshot.id, snapshot);
+    while (this.snapshots.size > this.max) {
+      const oldest = this.snapshots.keys().next();
+      if (oldest.done) break;
+      this.snapshots.delete(oldest.value);
+    }
+    return snapshot;
+  }
+  get(id) {
+    return this.snapshots.get(id);
+  }
+  size() {
+    return this.snapshots.size;
+  }
+  ids() {
+    return [...this.snapshots.keys()];
+  }
+  /**
+   * Why an id is not here, and what to do instead. An agent hitting this has
+   * already done the work it wanted to verify, so "unknown snapshot" on its own
+   * would strand it.
+   */
+  missingMessage(id) {
+    const held = this.ids();
+    const listing = held.length === 0 ? "No snapshots are held in this session yet." : `Held right now: ${held.join(", ")}.`;
+    return `No snapshot "${id}". Snapshots live in this server's memory for the length of the session: they are gone when the MCP server restarts, and the oldest is dropped once ${this.max} are held. ${listing} Take a fresh one with snapshot_comp, do the work, then diff against that id. To verify a write you have already made, read the comp back with list_layers instead \u2014 a diff can only compare against a snapshot taken beforehand.`;
+  }
+};
+
 // src/tools/descriptions.ts
 var descriptions = {
   // ---------- comps ----------
@@ -1332,13 +2416,16 @@ var descriptions = {
   get_comp_tree: "Comp + nested layer tree, recursing pre-comps to `depth`.",
   create_comp: "Create a new comp. Returns id.",
   set_comp: "Modify a comp (name, dims, fps, duration, work area, bg). Undefined fields unchanged.",
-  delete_comp: "Delete a comp. Reversible only via AE's Undo.",
+  delete_comp: "Delete a comp. Reversible only via AE's Undo. The solids its layers used are project items, not part of the comp, and After Effects leaves them behind in the Solids folder \u2014 the result counts them in `unusedSolidsLeft`. Pass `purgeUnusedSolids:true` to remove, in the same undo step, the ones nothing else uses; a solid another comp still uses is kept and reported in `keptSolids` with that comp's id. Only this comp's own solids are ever considered \u2014 for the whole project's orphans use purge_unused_footage.",
   set_active_comp: "Focus a comp in the viewer/timeline.",
+  duplicate_comp: "Copy a comp. Returns the new comp id, so you never have to find it by name. Use this instead of run_jsx + CompItem.duplicate(). By default the copy is SHALLOW, exactly like AE's own Duplicate: its precomp layers point at the same nested comps as the original, so editing one of those edits both. `deep:true` duplicates the nested comps too and re-points the copy at them \u2014 that is what 'a variant of this rig' means. A nested comp used by several layers is duplicated once and reused. `folderId` files the copy in a project folder; `nameSuffix` names the nested copies '<original><suffix>'.",
+  snapshot_comp: "Take a cheap structural fingerprint of a comp and keep it in this server's memory. Returns a snapshotId and nothing else worth tokens \u2014 call it BEFORE a write, then diff_comp afterwards to learn what the write actually did, instead of reading the comp back and comparing by eye. It records per layer: id, name, index, type, in/out/start, parent, enabled, keyframe counts, expression count, effect count; per comp: size, duration, frame rate, work area, markers. It does NOT record property values, expression text, effect parameters, masks or shape contents. Nothing is written into the AE project, and snapshots are gone when the session ends.",
+  diff_comp: "What changed in a comp since a snapshot: layers added, removed, renamed, retimed, re-parented, keyframe counts that moved, expressions and effects gained or lost \u2014 and nothing at all for unchanged layers, which are only counted. A few dozen tokens where list_layers + get_layer_full is thousands, and it answers the three questions worth asking after a write: which layer is the new one, where did a failed script stop, and did the assembly land. Only the recorded fields are compared, so 'no differences' means none of THOSE moved, not that the comp is identical. Returns a fresh snapshotId so you can keep diffing forward.",
   // ---------- layers ----------
   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. On a shape layer, `shapeDetail: 'compact'` returns one indented line per group \u2014 `name  matchName  prop=value prop=value`, with `[3 keys]`/`[expr]` marking animated properties and `(at defaults)` a group Transform nobody has touched \u2014 which is a fraction of the size and still names every node the write tools address. Material Options (48 3D-extrusion properties per group, inert on a 2D shape layer) is left out of both forms and counted in `materialsOmitted`; pass `shapeMaterials:true` for the extruded-3D case.",
-  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_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. The justification is read back after the write (AE 26.3 has been seen to store a different alignment from the one set \u2014 issues #93/#94): the result carries `justification` as read and `justificationReasserted` when a second write was needed, and if it still disagrees the layer is removed and the call throws, so a success result is a layer aligned the way it says.",
+  create_shape_layer: "Empty shape layer; fill via add_shape_content. Position defaults to [0,0] with Anchor Point [0,0], so the layer's coordinate space IS the comp's and every vertex, rect/ellipse position and path you add afterwards is in comp pixels. (After Effects' own default is the comp centre, which silently offsets a drawing authored in comp coordinates by half a frame \u2014 pass position:'center' if you want that, or any [x,y] to place the origin yourself.) The result echoes the position and anchor point it ended up with.",
   create_solid_layer: "Solid-color layer. color is RGB 0..1.",
   create_null_layer: "Null parent layer.",
   create_adjustment_layer: "Adjustment layer \u2014 effects on it apply to layers below.",
@@ -1349,30 +2436,30 @@ var descriptions = {
   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). 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.",
+  reorder_layer: "Move a layer in the render stack. Pass exactly one destination: `beforeLayerId` puts it directly in front of (above) that layer, `afterLayerId` directly behind it, `toIndex` at an absolute 1-based position where 1 is the front and numLayers the back. `toIndex` is where the layer ENDS UP, not the slot it displaces \u2014 the two differ by one when moving down the stack. Prefer the id forms: this is the op that shifts every index below it, so an index you read earlier may already be stale. The result carries `movedFrom` and the landed `index`, read back off the layer; equal values mean it was already there.",
   // ---------- transforms ----------
   set_transform: "Set any of position/scale/rotation/anchorPoint/opacity (+3D orientation/per-axis on 3D). keyframe:true + time sets keyframes.",
   // ---------- keyframes ----------
-  add_keyframe: "Keyframe at `time` on propertyPath (e.g. ['Transform','Position']). Optional in/out interpolation + ease.",
+  add_keyframe: "Keyframe at `time` on propertyPath (e.g. ['Transform','Position']). Optional in/out interpolation + ease \u2014 one influence/speed pair, expanded to however many entries the property needs (see set_temporal_ease). The count used comes back as `easeDimensions`.",
   remove_keyframe: "Remove keyframe at `time`.",
   get_keyframes: "All keyframes on a property: time, value, interpolation, ease, spatial tangents.",
   set_interpolation: "Set in/out interpolation type of a specific keyframe.",
-  set_temporal_ease: "Set influence+speed for in/out ease of a keyframe.",
+  set_temporal_ease: "Set influence+speed for the in/out ease of one keyframe. Pass at least one of `easeIn`/`easeOut` \u2014 neither is refused, since it would change nothing. Pass ONE {influence, speed} pair per side and it is applied to every dimension of the property \u2014 you never size the ease array yourself. That matters because AE's own setTemporalEaseAtKey wants a per-property number of entries that is not derivable from the value (2D Scale takes 2, a shape Ellipse Size takes 3, Opacity and sliders take 1, and spatial Position takes 1 whether the layer is 2D or 3D), and the wrong count throws a bare 'parameter 2'. This derives the count, retries the alternatives, and reports what worked as `easeDimensions` \u2014 worth reading if you are also easing that property from run_jsx.",
   set_spatial_tangents: "Set in/out spatial tangents for a position-style keyframe.",
   // ---------- expressions ----------
-  get_expression: "Expression text + enabled state on a property.",
-  set_expression: "Set + enable an expression on a property.",
-  toggle_expression: "Enable/disable an expression without clearing.",
+  get_expression: "Expression text, enabled state and `expressionError` on a property. `expressionError` is After Effects' own message when the expression cannot be compiled or evaluated \u2014 the text of the warning banner in the AE UI \u2014 or an empty string when it runs clean. A non-empty one means the property is not being driven by that expression, whatever `enabled` says.",
+  set_expression: "Set + enable an expression on a property, and verify it: after the write the property is evaluated and, if After Effects reports an error on it, the call THROWS with that message and the property path. So a success result means the expression compiles and runs; a failure means the text was written but AE cannot evaluate it \u2014 fix it and call set_expression again, or clear_expression to remove it. A broken expression never comes back as ok.",
+  toggle_expression: "Enable/disable an expression without clearing. Enabling verifies the same way set_expression does: if AE reports an error on the expression once it is enabled, the call throws with the message rather than returning ok.",
   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). 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_param: "Set one parameter of one effect. Pass at least one of `paramName` (the display name, e.g. 'Blurriness') or `paramMatchName` (e.g. 'ADBE Gaussian Blur 2-0001'); list_effects reports both for every parameter on the layer. Give both and the matchName wins, with the name as fallback \u2014 worth doing when a display name is ambiguous or the user's After Effects is localised. `keyframe:true` plus `time` writes a keyframed value instead of a static one.",
   set_effect_enabled: "Toggle an effect on/off without removing.",
   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.",
+  set_text: "Set text content + styling (font, size, fill/stroke, tracking, leading, justification). Undefined fields unchanged \u2014 and for justification that is verified, not assumed: on AE 26.3 the Source Text round trip has been seen to reset a left-aligned layer to centre when only `text` was changed (issue #93), so after writing, the justification is read back and compared with what should be there (the one you passed, or the one the layer had). If it moved it is written again on its own; if it still disagrees the call throws naming expected and actual rather than reporting a success the layer does not show. The result carries `justification` (the name read back) and `justificationReasserted` (true when the second write was needed).",
   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.",
@@ -1386,182 +2473,147 @@ 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. 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.",
+  screenshot_frame: "ONE-OFF visual check of a comp. Base64 PNG. Use only at key moments \u2014 never per-frame or in a loop. To judge MOTION, pass `times` (2-6 values) and get one tiled contact sheet with the time burned into each tile: one call, one image, about the pixel cost of a single frame \u2014 always cheaper and safer than several separate calls. `time` and `times` are mutually exclusive. Confirm the numbers with get_layer_full / get_keyframes; a picture is not exact. A downsample is chosen from the comp size (per tile, for a sheet) unless you pass one \u2014 omit it, and pass downsample:1 only when you genuinely need full resolution. Not every result is an image: 'Stale frame' means AE re-served an earlier render, 'Corrupt frame' means the file AE wrote is not a whole PNG (retry at downsample 6-8, or screenshot the precomps separately), 'Render timed out' means it is still rendering (wait, don't retry immediately), and `empty:true` means every pixel is transparent \u2014 check the time, in/out points and enabled state. On a sheet, a bad tile is drawn as a marked block and named in `warning`; the rest of the sheet is still good. 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', 'Corrupt frame', 'Render timed out' and `empty:true` non-image results apply. No `times` here \u2014 contact sheets are screenshot_frame only.",
   // ---------- 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.",
+  run_batch: 'Many ops in one ExtendScript pass \u2014 far faster than the same ops as separate calls, and far fewer undo steps. **Up to 500 ops it is exactly one undo step.** Over 500 it is chunked into a background job \u2014 this call returns a jobId at once, before the first chunk runs; finish with await_job, which blocks for the job and is where its progress is delivered (pass a progressToken on THAT call, not on this one; get_job polls without one) \u2014 and lands as **one undo step per chunk of 25** \u2014 around 24 steps for 600 ops \u2014 because After Effects discards an undo group that spans two script calls. Every result reports the measured count in `undoSteps` with a `note`: read it before you tell anyone how to undo the work, and never say "one Cmd-Z" for a chunked batch. `singleUndo:true` forces one undo step at any size up to 2000 ops, by running the whole batch in one blocking call \u2014 After Effects\' interface is frozen for the duration and no progress is reported, so use it only when a single Cmd-Z actually matters to the user. Over 2000 it is refused rather than freezing AE. transactional:true (default) stops at the first error; nothing rolls back either way \u2014 the ops before it stay applied, so read the state back rather than re-running. `diff:true` appends a structural diff of the comps the batch touched \u2014 what it added, retimed, re-parented and keyframed \u2014 and on a failure that diff rides on the error, which is the cheapest way to find where a half-applied batch stopped.',
   // ---------- explore ----------
   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.",
+  find_layers: "Search one comp (`compId`) or every comp for layers matching name (regex, case-insensitive), type and/or effect matchName filters. Returns `{matches, count, compsSearched, included}`; each match is id/index/name/sourceType plus compId/compName \u2014 enough to address the layer with any other tool. That is the whole record by default: pass `include` (flags, timing, parent \u2014 the same names as list_layers) to add sections to every match, and note that unlike list_layers an omitted `include` here means the bounded form, not everything. For one layer's details use get_layer_full on the id it gives you.",
   // ---------- raw ----------
-  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. A script with no explicit `return` \u2014 including one ending in a bare expression, which does NOT return its value \u2014 comes back as `{ok:true, returned:null, undoGroup, note}`. That means it ran to completion; it did **not** fail, so do not re-run it. Nothing rolls back, so re-running a mutating script applies it twice. 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.',
+  run_jsx: 'Escape hatch: arbitrary ExtendScript in an undo group. Pass exactly one of `code` (inline) or `scriptPath` (absolute) to run a .jsx file the server reads \u2014 use the path for anything long, so the script never enters the conversation. `libraries` (absolute .jsx paths) are read by the server too and inlined ahead of the script in the same scope, so their functions are callable from it; they are re-evaluated on every call, so keep them to declarations rather than to work. Keep shared helpers there instead of pasting them into every script. In scope: `app`, the full `OPS` table (every tool on this server, e.g. `OPS.set_transform({compId, layerId, position:[0,0]})`), and these helpers \u2014 `compById(id)`, `getCompById(id)`, `layerById(compOrId, layerId)`, `getLayerById(comp, layerId)`, `walkProperty(layer, ["Transform","Position"])`, `addKeys(prop, [[t, v], \u2026])` \u2192 key indices, `ease(prop, keyIndex, easeIn, easeOut)` which sizes the KeyframeEase array itself (a bare number means influence; omit easeOut for the same both sides), `shape(comp, {name, position})` which lands the layer at [0,0] rather than the comp centre, and `withoutUndoGroup(fn)`. `app.executeCommand()` menu commands silently no-op here \u2014 they depend on host focus and the active selection, neither of which this bridge has \u2014 so use the API equivalents (`CompItem.duplicate()`, `layer.duplicate()`). `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. A script with no explicit `return` \u2014 including one ending in a bare expression, which does NOT return its value \u2014 comes back as `{ok:true, returned:null, undoGroup, note}`. That means it ran to completion; it did **not** fail, so do not re-run it. Nothing rolls back, so re-running a mutating script applies it twice. A failure names the line of YOUR script and prints its text; when the number cannot be mapped it says so rather than guessing. Everything before that line already ran and nothing rolls back, so read the state back \u2014 never re-run the script to see if it fails again. 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. `diff:true` fingerprints the comp before and after the script and appends only what changed, so the script reports what it actually did instead of you reading the comp back; with it the answer is always `{ok, returned, diff}`. If the script throws, that diff is appended to the error \u2014 which is how you find where a half-applied script stopped, since nothing rolls back.',
   // ---------- 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.",
+  purge_unused_footage: "Remove footage items no comp uses. By default only solids \u2014 the items behind solid and adjustment layers, which delete_comp and delete_layer leave behind in the Solids folder, so a session that builds and discards comps can leave hundreds. `solidsOnly:false` removes every unused footage item, imported files and placeholders too, which is what AE's own Remove Unused Footage does. Comps and folders are never touched: a nested comp nothing uses is not footage. `dryRun:true` lists what would go (`wouldRemove`) without removing anything or adding an undo step \u2014 use it first on a project you did not build. `folderId` limits the sweep to one folder and its subfolders. Reports `scanned`, `inUse` and `removed` (id, name, kind); a real run is one undo step. If one removal fails, the error names it, what was already removed and what was not attempted, since nothing rolls back.",
+  // ---------- audio ----------
+  place_audio_cues: "Score a scene in one call: a list of cues, each a sound at a comp time with a level in dB, becomes one audio layer each \u2014 imported if needed, named, trimmed, labelled \u2014 in a single undo step. Reach for it whenever you are placing more than two or three sound effects; the alternative is dozens of round trips or a run_jsx loop that has to know that `layer.property('ADBE Audio Levels')` returns null on an audio layer. Every cue names its sound with **exactly one** of `path` (a file to use \u2014 imported once however many cues name it, and an item already in the project from that path is reused) or `footageId` (one already imported); both together, or neither, is reported against that cue's index with nothing placed. `time` is when the cue starts; `levelDb` is decibels (0 = the file as recorded, negative = quieter), defaulting to 0. `inPoint`/`outPoint` trim in COMP time, not file time. Three per-cue options cover what scoring passes otherwise redo in run_jsx: `loop:true` repeats the sound to `outPoint` or the comp's end (time remapping plus a wrap-around expression on Time Remap; AE's own remap keyframes are kept, since removing them breaks the property); `fadeIn`/`fadeOut` in seconds put Audio Levels keyframes at the layer's real in/out, fading between `fadeFloorDb` (call-level, default -48) and `levelDb`; `stretch` is a percentage (100 unchanged, 200 half speed and lower pitch) and the start time and trims are re-asserted after it. A loop that is also stretched has the factor baked into its expression, so changing stretch by hand later leaves the loop at the old rate. A fade longer than the cue's placed length, a stretch of 0 or below, or a floor at or above the cue's level is refused by cue index with nothing placed; for a file not yet imported the fade is checked right after the import, before any layer exists. It is all-or-nothing: every cue is validated \u2014 file exists, item has audio, time inside the comp, options sane \u2014 before a single layer is made, and if a later one still fails, everything this call created is removed and the error names the cue. The result carries one small entry per cue (layerId, name, time, plus `looped`/`stretch`/`fadeIn`/`fadeOut` and read-back in/out only where an option set them) and `sources` naming what was imported or reused \u2014 not an echo of the request. Use `dryRun:true` to check a cue list against the project without touching anything, including the undo stack; it answers with counts, `wouldImport`, `wouldReuse` and the failing cues by index, never the whole resolved list. Max 200 cues per call.",
   // ---------- 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.",
+  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. **The comp needs at least one property in its Essential Graphics panel** \u2014 After Effects will not build a template from an empty one, and it refuses silently, so this tool checks the controller count first and refuses before exporting rather than reporting a cause it cannot know. Fix it in AE: Window > Essential Graphics, pick the comp, drag a layer property in. `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. If an export still fails, read the message before acting: it lists what was checked, and it only names a modal dialog when dialogs were left unsuppressed. Under the default suppression a dialog is impossible, the cause is genuinely unknown, and the way to see AE's own reason is for the user to run the same export by hand from the Essential Graphics panel.",
   // ---------- 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.",
+  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. Returns a few-hundred-token summary by default \u2014 palette as named hexes, type, motion, layout, and a note naming anything it could not summarise; pass `detail:'full'` for the whole document, which you need before editing the guide with set_house_style. `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.",
   // ---------- guidance ----------
-  ae_guide: "The full working guidance for these tools, by topic. Read `after-effects` before a first substantial build in a session, `style-guide` when capturing or editing the user's look, `ae-setup` when a tool cannot reach After Effects. Covers the traps that silently produce wrong output and are not visible from any single tool's schema.",
+  ae_guide: "The full working guidance for these tools, by topic. Read `after-effects` before a first substantial build in a session, `style-guide` when capturing or editing the user's look, `ae-setup` when a tool cannot reach After Effects, `whats-new` when a call behaves differently from what you expected. Covers the traps that silently produce wrong output and are not visible from any single tool's schema. `whats-new` is one section per release, newest first, each entry leading with the rule as it now stands and a `supersedes:` line quoting the old rule a project's notes may still carry; pass `since` (a version, e.g. '0.4.0') to get only the releases after it, or one line saying nothing is newer \u2014 that is how the absorb-release prompt brings a project's docs up to date once per upgrade. The whats-new answer always opens with this server's own version. `since` is rejected on any other topic.",
   // ---------- jobs ----------
-  await_job: "Block until job is done. Default 10min timeout. Returns the same payload the tool would have.",
-  get_job: "Non-blocking job status: progress/total/state/error.",
+  await_job: "Block until a chunked run_batch job is done. Default 10min timeout. Returns the same payload the tool would have, `undoSteps` included. **This is the call that carries progress**: send it with a progressToken and notifications/progress arrive while it waits, every one before its response. run_batch's own response is back before the first chunk runs, so no progress can ride on that call \u2014 a token there is ignored.",
+  get_job: "Non-blocking job status: progress/total/state/error. Poll this when you cannot keep an await_job open. It never sends notifications/progress \u2014 that is await_job's job.",
   cancel_job: "Set cancel flag; chunked loop stops at next boundary.",
   // ---------- setup ----------
-  check_setup: "Diagnose the After Effects connection: panel installed, up to date, the version AE is actually running, Adobe debug preference on, AE running, bridge answering. Read-only and safe to call any time. Call this FIRST whenever another tool reports it cannot reach After Effects or says the panel is out of date, then relay `nextSteps` to the user in plain language. `panelRunningCurrent` is the one that predicts whether calls will work \u2014 it can fail while `panelUpToDate` passes, which means an update is installed but AE has not been restarted.",
-  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.",
+  check_setup: "Diagnose the After Effects connection: panel installed, up to date, the version AE is actually running, Adobe debug preference on, AE running, bridge answering \u2014 on whichever port it answers, since the port file is only a hint \u2014 plus `portAgreement` (do tool calls go to the port the panel answers on?) and, when nothing answers at all, `panelSignature` (did CEP's own log say it refused to load the panel?). Read-only and safe to call any time. Call this FIRST whenever another tool reports it cannot reach After Effects or says the panel is out of date, then relay `nextSteps` to the user in plain language. `panelRunningCurrent` is the one that predicts whether calls will work \u2014 it can fail while `panelUpToDate` passes, which means an update is installed but AE has not been restarted. A failing `portAgreement` means the server's port went stale, not the panel: retry the call (the server re-discovers the port whenever a call is refused) or reconnect the MCP server \u2014 never restart After Effects for it, a panel is listening. A failing `panelSignature` means no restart and no reinstall will help; `nextSteps` carries the self-signing fix.",
+  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 two user-level Adobe preferences \u2014 PlayerDebugMode, and CEP's LogLevel where it was never set, so that if AE ever refuses to load the panel its CEP log says why \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. If the existing install had been self-signed (check_setup's `panelInstalled` says so), the fresh copy is unsigned and the result says the signing has to be redone \u2014 on a machine that needed signing, tell the user before calling this.",
+  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. AGENTS.md carries a `Tools version last absorbed: <version>` line stamped with this server's version; the absorb-release prompt reads it after an upgrade to apply only what changed since, then moves it on \u2014 leave the line in place.",
   // ---------- 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` 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."
+  list_known_issues: "Problems earlier sessions hit with these tools, with the workarounds that worked. You do not need to read this ahead of time: a failed call names the entries that match its tool and error text in the error itself, under `Known from earlier sessions:`. Call this when you are planning something that has bitten before (pass `tool` or `query`), when a failure's pointer names an entry you want to open, or when the user asks what is known. Merges two journals and tags every entry with the one it came from: `project` (or `home`, the fallback when there is no project folder) for this project's own notes, `user` for tool and After Effects behaviour carried across every project. Returns a one-line index by default, entries naming `tool` first and then most recently seen first; the cause and the workaround are in the entry, so follow up with `id` on anything that looks like your problem \u2014 ids are unique only within a journal, so use the `scope:id` form the `next` pointer shows. Archived entries (not seen for 30 days, last seen on an older server, or retired with archive_issue) are hidden and counted in `archivedCount`; `includeArchived:true` lists them, and an `id` read always works. `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. Pass `tools` and the exact `errorText`: that is what lets a later failure be answered with this entry, and it is what merges a re-log into the existing entry even under a different title (the result says `mergedBy` and keeps the existing title). Reusing an existing title extends it too. Pass `kind:'ae-quirk'` for a permanent After Effects behaviour, so a new release does not archive it as fixed; the default `tool-bug` is presumed fixed once it was last seen on an older server than the one running. Choose the scope by what the entry is *about*: leave it at the default `project` for this project's footage, comps or files, and pass `scope:'user'` when it is about how these tools or After Effects behave, so the next project starts already knowing it. If the result says `reopened:true`, an entry that had been retired is back \u2014 tell the user the problem was supposed to be gone. 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.",
+  archive_issue: "Retire a journal entry for good: it leaves the index (and the pointers a failed call shows still name it, marked archived with this reason) but the file stays, hand-editable, with `reason` in its frontmatter. Use it when a report already covers the problem (pass that URL as the reason), when a release fixed it, or when the lesson has been moved into the project's own notes. Entries that merely go quiet archive themselves \u2014 30 days unseen, or last seen on an older server \u2014 so this is for a decision, not for tidying. Use the scope-qualified id (`user:my-entry`) when both journals hold the slug; only the one named moves. A later log_issue with the same title or the same tool and error text brings it back and says so."
 };
 
-// src/setup/check.ts
-import crypto2 from "node:crypto";
-import fs5 from "node:fs";
-import path6 from "node:path";
-
-// src/setup/paths.ts
-import fs3 from "node:fs";
-import os3 from "node:os";
-import path4 from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-var BUNDLE_ID = "games.engine-room.ae-mcp";
-function isSupportedPlatform() {
-  return process.platform === "darwin" || process.platform === "win32";
-}
-function packageRoot() {
-  let dir = path4.dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 8; i++) {
-    if (fs3.existsSync(path4.join(dir, "package.json"))) return dir;
-    const parent = path4.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return path4.dirname(fileURLToPath(import.meta.url));
-}
-function executableDir() {
-  return path4.dirname(process.execPath);
-}
-function packageVersion() {
-  for (const dir of [packageRoot(), executableDir()]) {
-    try {
-      const pkg = JSON.parse(fs3.readFileSync(path4.join(dir, "package.json"), "utf8"));
-      if (typeof pkg.version === "string") return pkg.version;
-    } catch {
-    }
+// src/tools/runJsxSource.ts
+import fs4 from "node:fs";
+import path5 from "node:path";
+var MAX_SCRIPT_BYTES = 512 * 1024;
+var MAX_LIBRARIES = 16;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+function readScriptFile(p, what) {
+  if (!path5.isAbsolute(p)) {
+    throw new Error(
+      `${what} must be an absolute path \u2014 got "${p}". Relative paths have no meaning here: the server resolves them against its own working directory, which is not the user's project folder (Claude Desktop starts it at "/").`
+    );
   }
-  return "unknown";
-}
-function panelSourceDir() {
-  const candidates = [
-    // The live workspace copy comes first so a git checkout always installs
-    // what the developer is editing, never a stale vendored copy left behind by
-    // a previous `npm pack`. Only the second path exists in the tarball.
-    path4.resolve(packageRoot(), "..", "ae-panel"),
-    path4.join(packageRoot(), "panel"),
-    // Compiled single-file build: the panel ships beside the executable.
-    path4.join(executableDir(), "panel")
-  ];
-  for (const dir of candidates) {
-    if (fs3.existsSync(path4.join(dir, "CSXS", "manifest.xml"))) return dir;
+  let stat;
+  try {
+    stat = fs4.statSync(p);
+  } catch (e) {
+    throw new Error(`${what} could not be read: ${p} (${e.code ?? e.message}).`);
   }
-  return null;
-}
-function cepExtensionsDir() {
-  if (process.platform === "win32") {
-    const appData = process.env.APPDATA ?? path4.join(os3.homedir(), "AppData", "Roaming");
-    return path4.join(appData, "Adobe", "CEP", "extensions");
+  if (stat.isDirectory()) throw new Error(`${what} is a directory, not a file: ${p}`);
+  if (!stat.isFile()) throw new Error(`${what} is not a regular file: ${p}`);
+  if (stat.size > MAX_SCRIPT_BYTES) {
+    throw new Error(
+      `${what} is ${stat.size} bytes, over the ${MAX_SCRIPT_BYTES}-byte limit: ${p}. Split it into smaller scripts and run them in sequence. Moving the bulk into a \`libraries\` file does not help: libraries are inlined ahead of the script on every call, so they count against the same budget.`
+    );
   }
-  return path4.join(os3.homedir(), "Library", "Application Support", "Adobe", "CEP", "extensions");
-}
-function installedPanelDir() {
-  return path4.join(cepExtensionsDir(), BUNDLE_ID);
-}
-function isWsModuleDir(dir) {
+  let text;
   try {
-    const pkg = JSON.parse(fs3.readFileSync(path4.join(dir, "package.json"), "utf8"));
-    if (pkg.name !== "ws") return false;
-    return fs3.existsSync(path4.join(dir, "index.js")) && fs3.existsSync(path4.join(dir, "lib", "websocket.js"));
-  } catch {
-    return false;
+    text = fs4.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new Error(`${what} could not be read: ${p} (${e.message}).`);
   }
+  if (text.trim() === "") throw new Error(`${what} is empty: ${p}`);
+  return { text, bytes: stat.size };
 }
-function wsModuleDir() {
-  const candidates = [];
-  try {
-    const require2 = createRequire(import.meta.url);
-    const entry = require2.resolve("ws");
-    if (path4.isAbsolute(entry)) {
-      const marker = `${path4.sep}node_modules${path4.sep}ws${path4.sep}`;
-      const idx = entry.lastIndexOf(marker);
-      candidates.push(idx >= 0 ? entry.slice(0, idx + marker.length - 1) : path4.dirname(entry));
-    }
-  } catch {
-  }
-  candidates.push(path4.join(executableDir(), "node_modules", "ws"));
-  candidates.push(path4.join(packageRoot(), "node_modules", "ws"));
-  for (const dir of candidates) {
-    if (isWsModuleDir(dir)) return dir;
+function resolveRunJsxSource(args) {
+  const hasCode = typeof args.code === "string" && args.code.length > 0;
+  const hasPath = typeof args.scriptPath === "string" && args.scriptPath.length > 0;
+  if (hasCode && hasPath) {
+    throw new Error(
+      "run_jsx takes either `code` or `scriptPath`, not both. Pass the path on its own \u2014 the file is read here, so its text never has to enter the conversation."
+    );
   }
-  return null;
-}
-function listPanelFiles(dir, prefix = "") {
-  const out = [];
-  for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name === "node_modules" || entry.name === ".DS_Store") continue;
-    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) out.push(...listPanelFiles(path4.join(dir, entry.name), rel));
-    else out.push(rel);
+  if (!hasCode && !hasPath) {
+    throw new Error(
+      "run_jsx needs either `code` (ExtendScript inline) or `scriptPath` (an absolute path to a .jsx file)."
+    );
   }
-  return out;
-}
-function sameContents(a, b) {
-  try {
-    if (fs3.statSync(a).size !== fs3.statSync(b).size) return false;
-    return fs3.readFileSync(a).equals(fs3.readFileSync(b));
-  } catch {
-    return false;
+  const { libraries: requestedLibraries, ...passthrough } = args;
+  const out = { ...passthrough, code: "" };
+  if (hasPath) {
+    const p = args.scriptPath;
+    out.code = readScriptFile(p, "run_jsx `scriptPath`").text;
+    out.scriptPath = p;
+  } else {
+    out.code = args.code;
+    delete out.scriptPath;
   }
-}
-function panelInstallDiff(source, installed) {
-  return listPanelFiles(source).filter((rel) => !sameContents(path4.join(source, rel), path4.join(installed, rel))).sort();
-}
-function copyRecursive(src, dst) {
-  const stat = fs3.lstatSync(src);
-  if (stat.isDirectory()) {
-    fs3.mkdirSync(dst, { recursive: true });
-    for (const entry of fs3.readdirSync(src)) {
-      copyRecursive(path4.join(src, entry), path4.join(dst, entry));
+  if (requestedLibraries && requestedLibraries.length > 0) {
+    if (requestedLibraries.length > MAX_LIBRARIES) {
+      throw new Error(
+        `run_jsx takes at most ${MAX_LIBRARIES} libraries, got ${requestedLibraries.length}.`
+      );
     }
-  } else if (stat.isSymbolicLink()) {
-    fs3.symlinkSync(fs3.readlinkSync(src), dst);
-  } else {
-    fs3.copyFileSync(src, dst);
+    const libs = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of requestedLibraries) {
+      if (seen.has(raw)) continue;
+      seen.add(raw);
+      const { text, bytes } = readScriptFile(raw, `run_jsx library "${raw}"`);
+      libs.push({ path: raw, text, bytes });
+    }
+    out.libraries = libs;
+  }
+  const total = Buffer.byteLength(out.code, "utf8") + (out.libraries ?? []).reduce((n, l) => n + l.bytes, 0);
+  if (total > MAX_TOTAL_BYTES) {
+    throw new Error(
+      `run_jsx would send ${total} bytes of source (script plus ${out.libraries?.length ?? 0} libraries), over the ${MAX_TOTAL_BYTES}-byte limit for one call. Libraries are inlined ahead of the script \u2014 they have to be, or their functions are not in its scope \u2014 so every byte travels on every call. Pass only the libraries this script actually uses.`
+    );
   }
+  return out;
 }
 
+// src/setup/check.ts
+import crypto2 from "node:crypto";
+import fs7 from "node:fs";
+import path8 from "node:path";
+
 // src/setup/panelVersion.ts
 import crypto from "node:crypto";
-import fs4 from "node:fs";
-import path5 from "node:path";
+import fs5 from "node:fs";
+import path6 from "node:path";
 var cachedSourceHash;
 function sourceBundleHash() {
   if (cachedSourceHash !== void 0) return cachedSourceHash;
   const source = panelSourceDir();
-  cachedSourceHash = source ? hashFile(path5.join(source, "jsx", "bundle.jsx")) : null;
+  cachedSourceHash = source ? hashFile(path6.join(source, "jsx", "bundle.jsx")) : null;
   return cachedSourceHash;
 }
 function installedBundleHash(installedPanel) {
-  return hashFile(path5.join(installedPanel, "jsx", "bundle.jsx"));
+  return hashFile(path6.join(installedPanel, "jsx", "bundle.jsx"));
 }
 function hashFile(file) {
   try {
-    return crypto.createHash("sha256").update(fs4.readFileSync(file)).digest("hex");
+    return crypto.createHash("sha256").update(fs5.readFileSync(file)).digest("hex");
   } catch {
     return null;
   }
@@ -1601,6 +2653,9 @@ function unknownOpMessage(op) {
 
 // src/setup/platform.ts
 import { execFile } from "node:child_process";
+import fs6 from "node:fs";
+import os4 from "node:os";
+import path7 from "node:path";
 import { promisify } from "node:util";
 var exec = promisify(execFile);
 var CSXS_VERSIONS = [12, 11, 10, 9];
@@ -1675,37 +2730,153 @@ async function isAfterEffectsRunning() {
 function debugModeLocation() {
   return process.platform === "win32" ? "the PlayerDebugMode value under HKEY_CURRENT_USER\\Software\\Adobe\\CSXS.*" : "Adobe's PlayerDebugMode preference";
 }
+function cepLogDir() {
+  if (process.platform === "win32") {
+    return process.env.TEMP ?? process.env.TMP ?? os4.tmpdir();
+  }
+  return path7.join(os4.homedir(), "Library", "Logs", "CSXS");
+}
+var CEP_LOG_NAME = /^(?:cep|csxs)(\d+)-AEFT\.log$/i;
+function cepLogPaths(dir = cepLogDir()) {
+  let names;
+  try {
+    names = fs6.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names.filter((n) => CEP_LOG_NAME.test(n)).map((n) => {
+    const file = path7.join(dir, n);
+    let mtime = 0;
+    try {
+      mtime = fs6.statSync(file).mtimeMs;
+    } catch {
+    }
+    return { file, mtime };
+  }).sort((a, b) => b.mtime - a.mtime).map((e) => e.file);
+}
+async function cepLogLevel(version) {
+  try {
+    if (process.platform === "win32") {
+      const { stdout: stdout2 } = await exec("reg", ["query", `HKCU\\Software\\Adobe\\CSXS.${version}`, "/v", "LogLevel"]);
+      const m = /LogLevel\s+REG_\w+\s+(\d+)/.exec(stdout2);
+      return m ? Number(m[1]) : null;
+    }
+    const { stdout } = await exec("defaults", ["read", `com.adobe.CSXS.${version}`, "LogLevel"]);
+    const n = Number(stdout.trim());
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+var CEP_LOG_LEVEL = 6;
+async function ensureCepLogging() {
+  const set = [];
+  const kept = [];
+  for (const v of CSXS_VERSIONS) {
+    const current = await cepLogLevel(v);
+    if (current !== null) {
+      kept.push({ version: v, level: current });
+      continue;
+    }
+    try {
+      if (process.platform === "win32") {
+        await exec("reg", [
+          "add",
+          `HKCU\\Software\\Adobe\\CSXS.${v}`,
+          "/v",
+          "LogLevel",
+          "/t",
+          "REG_SZ",
+          "/d",
+          String(CEP_LOG_LEVEL),
+          "/f"
+        ]);
+      } else {
+        await exec("defaults", ["write", `com.adobe.CSXS.${v}`, "LogLevel", String(CEP_LOG_LEVEL)]);
+      }
+      set.push(v);
+    } catch {
+    }
+  }
+  return { set, kept };
+}
+function cepLogLevelCommand(version = CSXS_VERSIONS[0]) {
+  return process.platform === "win32" ? `reg add HKCU\\Software\\Adobe\\CSXS.${version} /v LogLevel /t REG_SZ /d ${CEP_LOG_LEVEL} /f` : `defaults write com.adobe.CSXS.${version} LogLevel ${CEP_LOG_LEVEL}`;
+}
 
 // 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");
+    return crypto2.createHash("sha256").update(fs7.readFileSync(file)).digest("hex");
   } catch {
     return null;
   }
 }
-async function bridgeReachable(port) {
+async function probeBridge(candidates = diagnosticPortCandidates(), opPort) {
+  const order = [];
+  const push = (p) => {
+    if (p !== void 0 && !order.includes(p)) order.push(p);
+  };
+  push(opPort);
+  for (const c of candidates) push(c);
+  const probed = [];
+  let answering = null;
+  let busy = null;
+  for (const port of order) {
+    const r = await probePanel(port, BRIDGE_PROBE_MS);
+    probed.push(r);
+    if (r.status === "panel" && !answering) answering = r;
+    if (r.status === "busy" && !busy) busy = r;
+    if (answering) break;
+  }
+  const atOpPort = opPort === void 0 ? null : probed.find((p) => p.port === opPort) ?? null;
+  return { answering, busy, atOpPort, probed };
+}
+var CEP_LOG_TAIL_BYTES = 256 * 1024;
+function readTail(file, bytes) {
+  const fd = fs7.openSync(file, "r");
   try {
-    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`
-      };
+    const size = fs7.fstatSync(fd).size;
+    const start = Math.max(0, size - bytes);
+    const buf = Buffer.alloc(size - start);
+    fs7.readSync(fd, buf, 0, buf.length, start);
+    return buf.toString("utf8");
+  } finally {
+    fs7.closeSync(fd);
+  }
+}
+function findSignatureFailure(logs, bundleId = BUNDLE_ID) {
+  const needle = `Signature verification failed for extension ${bundleId}`;
+  for (const file of logs) {
+    let text;
+    let mtime;
+    try {
+      text = readTail(file, CEP_LOG_TAIL_BYTES);
+      mtime = fs7.statSync(file).mtime;
+    } catch {
+      continue;
+    }
+    const lines = text.split(/\r?\n/).filter((l) => l.includes(needle));
+    if (lines.length > 0) {
+      return { file, line: lines[lines.length - 1].trim().slice(0, 240), mtime };
     }
-    return { ok: false, detail: `no response on port ${port} (${e.message})` };
   }
+  return null;
+}
+function signatureWorkaroundSteps(installed) {
+  return [
+    "After Effects is refusing to load the panel because CEP's signature check is running even though PlayerDebugMode is on. That is an Adobe CEP 12 bug, not a broken install \u2014 nothing here needs reinstalling, and restarting After Effects again will not change it. The fix is to sign the installed panel folder yourself, with Adobe's own tool, so it passes the check.",
+    "1. Download ZXPSignCmd from Adobe's CEP-Resources repository on GitHub (folder `ZXPSignCMD/4.1.3`, the build for this platform). It is a single command-line program.",
+    '2. Make a self-signed certificate: `ZXPSignCmd -selfSignedCert US CA "AE MCP" "AE MCP Bridge" password cert.p12` (the country, state and names are free text; keep the password).',
+    `3. Sign the installed panel folder into a zip: \`ZXPSignCmd -sign "${installed}" signed.zxp cert.p12 password -tsa http://timestamp.digicert.com\``,
+    `4. Unzip signed.zxp back into that same folder, overwriting in place. That adds \`META-INF/signatures.xml\` and a \`mimetype\` file next to the panel's own files and changes nothing else. check_setup keeps reporting the panel as up to date with those extra files present.`,
+    "5. Then restart After Effects \u2014 the signed panel loads on launch. Run check_setup to confirm.",
+    "Caveat: setup_panel installs a fresh, unsigned copy. After any reinstall on this machine, steps 3-5 have to be done again."
+  ];
 }
-async function checkSetup() {
+async function checkSetup(opts = {}) {
   const checks = [];
   const supported = isSupportedPlatform();
   checks.push({
@@ -1729,11 +2900,12 @@ async function checkSetup() {
     fix: debugMode.on ? void 0 : `Run the setup_panel tool. After Effects only loads unsigned panels when ${debugModeLocation()} is set.`
   });
   const installed = installedPanelDir();
-  const isInstalled = fs5.existsSync(path6.join(installed, "CSXS", "manifest.xml"));
+  const isInstalled = fs7.existsSync(path8.join(installed, "CSXS", "manifest.xml"));
+  const signed = isInstalled && signedInstallPresent(installed);
   checks.push({
     name: "panelInstalled",
     ok: isInstalled,
-    detail: isInstalled ? installed : `not present at ${installed}`,
+    detail: isInstalled ? `${installed}${signed ? " (self-signed: META-INF present)" : ""}` : `not present at ${installed}`,
     fix: isInstalled ? void 0 : "Run the setup_panel tool to install it."
   });
   let installComplete = true;
@@ -1749,7 +2921,7 @@ async function checkSetup() {
     });
   }
   if (isInstalled) {
-    const panelWs = path6.join(installed, "node_modules", "ws");
+    const panelWs = path8.join(installed, "node_modules", "ws");
     const wsOk = isWsModuleDir(panelWs);
     checks.push({
       name: "panelDependencies",
@@ -1765,16 +2937,47 @@ async function checkSetup() {
     detail: running ? "running" : "not running",
     fix: running ? void 0 : "Launch After Effects. The panel starts automatically with it."
   });
-  const port = discoverPort();
-  const bridge = await bridgeReachable(port);
+  const bridge = await probeBridge(opts.candidates, opts.opPort);
+  const fromFile = portFilePort();
+  const bridgeTimedOut = !bridge.answering && bridge.busy !== null;
+  let bridgeDetail;
+  if (bridge.answering) {
+    bridgeDetail = `responding on port ${bridge.answering.port}`;
+    if (fromFile !== null && fromFile !== bridge.answering.port) {
+      bridgeDetail += ` (the port file says ${fromFile}, which is stale \u2014 the socket is the authority)`;
+    }
+  } else if (bridge.busy) {
+    bridgeDetail = `port ${bridge.busy.port} accepted the connection but did not answer within ${BRIDGE_PROBE_MS / 1e3}s \u2014 After Effects is probably busy`;
+  } else {
+    const ports = bridge.probed.map((p) => p.port).join(", ");
+    const reasons = bridge.probed.map((p) => p.detail).join("; ");
+    bridgeDetail = `no response on port${bridge.probed.length > 1 ? "s" : ""} ${ports} (${reasons})`;
+  }
   checks.push({
     name: "bridgeReachable",
-    ok: bridge.ok,
-    detail: bridge.detail,
-    fix: bridge.ok ? void 0 : bridge.timedOut ? BRIDGE_BUSY_FIX : "If the other checks pass, restart After Effects so the panel reloads."
+    ok: bridge.answering !== null,
+    detail: bridgeDetail,
+    fix: bridge.answering ? void 0 : bridgeTimedOut ? 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")), {
+  if (opts.opPort !== void 0 && (bridge.answering || bridge.busy)) {
+    const opPort = opts.opPort;
+    const agrees = bridge.answering !== null && bridge.answering.port === opPort;
+    let detail;
+    let fix;
+    if (agrees) {
+      detail = `tool calls go to port ${opPort} and the panel answers there`;
+    } else if (bridge.answering) {
+      const pinned = pinnedPort() === opPort;
+      detail = pinned ? `tool calls are pinned to port ${opPort} by AE_MCP_PORT (${bridge.atOpPort?.detail ?? "not probed"}), but the panel is answering on port ${bridge.answering.port}` : `tool calls are being sent to port ${opPort} (${bridge.atOpPort?.detail ?? "not probed"}), but the panel is answering on port ${bridge.answering.port}`;
+      fix = pinned ? `AE_MCP_PORT pins tool calls to port ${opPort}, and a pin is never walked past, so retrying changes nothing. Set AE_MCP_PORT to ${bridge.answering.port}, or unset it, then reconnect the MCP server (restart the client's connection to it). Do NOT restart After Effects for this: a panel is listening, and a restart would cost the user their work in progress for nothing.` : `The server's port is stale; the panel is fine. Retry the failed call \u2014 the server re-checks the port whenever a call is refused and switches to ${bridge.answering.port} by itself. If it still fails, reconnect the MCP server (restart the client's connection to it) so it starts on the right port. Do NOT restart After Effects for this: a panel is listening, and a restart would cost the user their work in progress for nothing.`;
+    } else {
+      detail = `tool calls are being sent to port ${opPort} (${bridge.atOpPort?.detail ?? "not probed"}); port ${bridge.busy.port} accepted a connection but is busy and could not be confirmed as the panel`;
+      fix = `Wait for After Effects to finish what it is doing, then retry the call \u2014 once port ${bridge.busy.port} answers, the server switches to it on the next refused call. Do not restart After Effects: something is listening there.`;
+    }
+    checks.push({ name: "portAgreement", ok: agrees, detail, fix });
+  }
+  if (bridge.answering && source) {
+    const assessment = assessPanel(bridge.answering.health?.bundleHash, sha256(path8.join(installed, "jsx", "bundle.jsx")), {
       installComplete
     });
     const ok = assessment.state === "current";
@@ -1785,16 +2988,44 @@ async function checkSetup() {
       fix: ok ? void 0 : assessment.message
     });
   }
-  if (bridge.ok && !isInstalled) {
+  if (bridge.answering && !isInstalled) {
     checks.push({
       name: "panelIdentity",
       ok: false,
-      detail: `a panel is answering on port ${port}, but not the one at ${installed}`,
+      detail: `a panel is answering on port ${bridge.answering.port}, but not the one at ${installed}`,
       fix: `An older install is serving the bridge. Look in ${cepExtensionsDir()} for a differently named folder, remove it, then run setup_panel and restart After Effects.`
     });
   }
+  if (running && isInstalled && !bridge.answering && !bridgeTimedOut) {
+    const logs = cepLogPaths();
+    const finding = findSignatureFailure(logs);
+    if (finding) {
+      checks.push({
+        name: "panelSignature",
+        ok: false,
+        evidence: "failure-logged",
+        detail: `the CEP log ${finding.file} (last written ${finding.mtime.toISOString()}) records: "${finding.line}" \u2014 CEP is enforcing signature verification on this panel even though PlayerDebugMode is on`,
+        fix: "CEP is refusing the unsigned panel's signature despite PlayerDebugMode \u2014 an Adobe CEP 12 bug, not a broken install. No reinstall and no restart changes that; the panel folder has to be self-signed with Adobe's ZXPSignCmd. nextSteps carries the exact steps."
+      });
+    } else if (logs.length > 0) {
+      const level = await cepLogLevel(CSXS_VERSIONS[0]);
+      checks.push({
+        name: "panelSignature",
+        ok: true,
+        evidence: "log-clean",
+        detail: `no signature failure recorded in ${logs[0]}` + (level === null ? " (CEP LogLevel is not set, so the log may predate this launch)" : ` (CEP LogLevel ${level})`)
+      });
+    } else {
+      checks.push({
+        name: "panelSignature",
+        ok: true,
+        evidence: "no-log",
+        detail: `no CEP log found in ${cepLogDir()} \u2014 CEP is not logging, so a signature refusal cannot be ruled out; nextSteps says how to turn the log on`
+      });
+    }
+  }
   const ready = checks.every((c) => c.ok);
-  return { ready, checks, nextSteps: buildNextSteps(checks, ready, bridge.timedOut === true) };
+  return { ready, checks, nextSteps: buildNextSteps(checks, ready, bridgeTimedOut) };
 }
 function buildNextSteps(checks, ready, bridgeTimedOut = false) {
   if (ready) return ["Everything is connected. After Effects is ready to drive."];
@@ -1802,15 +3033,39 @@ function buildNextSteps(checks, ready, bridgeTimedOut = false) {
   const steps = [];
   if (by("platform")?.ok === false) return [by("platform").fix];
   if (by("panelAssetsPresent")?.ok === false) return [by("panelAssetsPresent").fix];
+  const agreement = by("portAgreement");
+  if (agreement && agreement.ok === false && by("bridgeReachable")?.ok === true && /pinned to port/.test(agreement.detail)) {
+    return [
+      `Do not restart After Effects \u2014 the panel is running and answering. ${agreement.detail}.`,
+      "AE_MCP_PORT pins the server to that port and a pin is never walked past, so retrying will not help: set AE_MCP_PORT to the port the panel answers on, or unset it, then reconnect the MCP server \u2014 restart the client's connection to it, not After Effects.",
+      "Nothing about the install is wrong; setup_panel would change nothing here."
+    ];
+  }
+  if (agreement && agreement.ok === false && by("bridgeReachable")?.ok === true) {
+    return [
+      `Do not restart After Effects \u2014 the panel is running and answering. ${agreement.detail}.`,
+      "Retry the call that failed. The server re-checks the port whenever a call is refused and switches to the port that answers, so the retry normally succeeds on its own.",
+      "If it still fails, reconnect the MCP server \u2014 restart the client's connection to it, not After Effects \u2014 so it starts on the right port.",
+      "Nothing about the install is wrong; setup_panel would change nothing here."
+    ];
+  }
   const installSound = by("panelInstalled")?.ok !== false && by("panelUpToDate")?.ok !== false && by("panelDependencies")?.ok !== false && by("cepDebugMode")?.ok !== false;
   if (bridgeTimedOut && installSound) {
-    return [
+    const out = [
       "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."
+      "On macOS, if they have moved to a different desktop, ask them to switch back to the one After Effects is on."
     ];
+    if (agreement && agreement.ok === false) {
+      out.push(`${agreement.detail}. Once it answers, the server switches to it on the next refused call \u2014 no reconnect needed.`);
+    }
+    out.push("Only if it is still not answering after a minute should you treat it as disconnected and quit and reopen After Effects.");
+    return out;
+  }
+  const signature = by("panelSignature");
+  if (signature && signature.ok === false) {
+    return signatureWorkaroundSteps(installedPanelDir());
   }
   const brokenInstall = by("panelUpToDate")?.ok === false || by("panelDependencies")?.ok === false;
   const needsInstall = by("panelInstalled")?.ok === false || brokenInstall;
@@ -1837,15 +3092,30 @@ function buildNextSteps(checks, ready, bridgeTimedOut = false) {
     );
   }
   if (steps.length === 0 && by("bridgeReachable")?.ok === false) {
-    steps.push("Everything is installed but the panel is not answering. Quit and reopen After Effects.");
-    steps.push("If it still fails, open Window > Extensions > AE MCP Bridge in AE to see the panel's own status log.");
+    steps.push(
+      "Everything is installed but the panel is not answering. If After Effects has not been restarted since the panel was installed, quit and reopen After Effects once \u2014 the panel loads only at launch."
+    );
+    if (signature?.evidence === "log-clean") {
+      steps.push(
+        `If it has already been restarted, the CEP log shows no signature refusal (${signature.detail}), so that is not the cause. Ask the user to open Window > Extensions > AE MCP Bridge in After Effects and read back what the panel says; if nothing opens at all, report it with log_issue.`
+      );
+    } else {
+      steps.push(
+        "If it has already been restarted and still does not answer, the likely cause is CEP refusing the unsigned panel's signature even though PlayerDebugMode is on \u2014 an Adobe CEP 12 bug, seen on Windows (issue #91). Nothing about the install is wrong, and restarting again will not help."
+      );
+      steps.push(
+        `To confirm it, turn CEP's own logging up so it records why the panel did not load: run \`${cepLogLevelCommand()}\` (After Effects 2026 uses CSXS.${CSXS_VERSIONS[0]}; setup_panel sets this for new installs). Then relaunch After Effects and run check_setup again \u2014 it reads the CEP log, and if the signature check is what is failing it reports panelSignature with the exact fix.`
+      );
+      steps.push("Also ask the user to open Window > Extensions > AE MCP Bridge in AE: if nothing appears at all, that is the same symptom.");
+    }
   }
   return steps;
 }
 
 // src/setup/install.ts
-import fs6 from "node:fs";
-import path7 from "node:path";
+import fs8 from "node:fs";
+import path9 from "node:path";
+var SIGNED_INSTALL_OVERWRITTEN_NOTE = "The previous install had been self-signed (META-INF/signatures.xml was present). This fresh copy is NOT signed. On a machine where CEP refuses unsigned panels despite PlayerDebugMode \u2014 the issue #91 case, seen on Windows \u2014 After Effects will not load it until it is signed again: repeat the ZXPSignCmd steps from check_setup's panelSignature nextSteps on the newly installed folder, then restart After Effects.";
 async function installPanel(opts = {}) {
   const actions = [];
   const notes = [];
@@ -1858,7 +3128,7 @@ async function installPanel(opts = {}) {
   if (!source) {
     throw new Error("Could not find the CEP panel assets that ship with this server. Reinstall the package.");
   }
-  if (!fs6.existsSync(path7.join(source, "jsx", "bundle.jsx"))) {
+  if (!fs8.existsSync(path9.join(source, "jsx", "bundle.jsx"))) {
     throw new Error(`The panel at ${source} has no jsx/bundle.jsx. In a git checkout, run \`npm run build:jsx\` first.`);
   }
   const ws = wsModuleDir();
@@ -1868,9 +3138,9 @@ async function installPanel(opts = {}) {
     );
   }
   const target = installedPanelDir();
-  const existing = fs6.lstatSync(target, { throwIfNoEntry: false });
+  const existing = fs8.lstatSync(target, { throwIfNoEntry: false });
   if (existing?.isSymbolicLink() && !opts.force) {
-    const linkTarget = fs6.readlinkSync(target);
+    const linkTarget = fs8.readlinkSync(target);
     return {
       ok: true,
       panelPath: target,
@@ -1883,16 +3153,17 @@ async function installPanel(opts = {}) {
       ]
     };
   }
+  const wasSigned = existing ? signedInstallPresent(target) : false;
   if (existing) {
-    fs6.rmSync(target, { recursive: true, force: true });
-    actions.push("Removed the previously installed panel.");
+    fs8.rmSync(target, { recursive: true, force: true });
+    actions.push(wasSigned ? "Removed the previously installed (self-signed) panel." : "Removed the previously installed panel.");
   }
-  fs6.mkdirSync(path7.dirname(target), { recursive: true });
+  fs8.mkdirSync(path9.dirname(target), { recursive: true });
   copyRecursive(source, target);
   actions.push(`Installed the panel to ${target}.`);
-  const dest = path7.join(target, "node_modules", "ws");
-  fs6.mkdirSync(path7.dirname(dest), { recursive: true });
-  fs6.rmSync(dest, { recursive: true, force: true });
+  const dest = path9.join(target, "node_modules", "ws");
+  fs8.mkdirSync(path9.dirname(dest), { recursive: true });
+  fs8.rmSync(dest, { recursive: true, force: true });
   copyRecursive(ws, dest);
   if (!isWsModuleDir(dest)) {
     throw new Error(
@@ -1915,6 +3186,15 @@ async function installPanel(opts = {}) {
       }
     }
   }
+  if (opts.enableDebugMode !== false) {
+    const logging = await ensureCepLogging();
+    if (logging.set.length > 0) {
+      actions.push(
+        `Set CEP's LogLevel to ${CEP_LOG_LEVEL} for CSXS ${logging.set.join(", ")} so that, if After Effects ever refuses to load the panel, its CEP log says why.`
+      );
+    }
+  }
+  if (wasSigned) notes.push(SIGNED_INSTALL_OVERWRITTEN_NOTE);
   if (rebootRecommended) {
     notes.push("PlayerDebugMode was just turned on. Quit and reopen After Effects; if the panel still does not connect, restart the Mac once \u2014 on some macOS builds the preference only applies after a reboot.");
   }
@@ -1924,29 +3204,146 @@ async function installPanel(opts = {}) {
     actions,
     restartAfterEffects: true,
     rebootRecommended,
-    notes
+    notes,
+    signedInstallOverwritten: wasSigned || void 0
   };
 }
 
+// src/tools/whatsNew.ts
+var RELEASE_HEADING = /^## v?(\d+\.\d+\.\d+)\s*$/;
+function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa) throw new Error(`Not a version: ${JSON.stringify(a)}`);
+  if (!pb) throw new Error(`Not a version: ${JSON.stringify(b)}`);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+function splitReleases(body) {
+  const lines = body.replace(/\r\n/g, "\n").split("\n");
+  const preamble = [];
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const m = RELEASE_HEADING.exec(line);
+    if (m) {
+      if (current) sections.push({ version: current.version, text: current.lines.join("\n").trimEnd() });
+      current = { version: m[1], lines: [line] };
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+  if (current) sections.push({ version: current.version, text: current.lines.join("\n").trimEnd() });
+  return { preamble: preamble.join("\n").trimEnd(), sections };
+}
+function renderWhatsNew(body, opts) {
+  const { preamble, sections } = splitReleases(body);
+  const newest = sections.length > 0 ? sections[0].version : null;
+  const server = `This server is after-effects-mcp ${opts.serverVersion}.`;
+  if (opts.since === void 0) {
+    return {
+      text: `${server} Pass \`since\` to see only the releases after a version.
+
+${body.trim()}`,
+      versions: sections.map((s) => s.version),
+      newest
+    };
+  }
+  const since = opts.since.replace(/^v/, "");
+  const newer = sections.filter((s) => compareSemver(s.version, since) > 0);
+  if (newer.length === 0) {
+    const described = newest ? `the newest release described here is ${newest}` : "this guide describes no releases";
+    return {
+      text: `${server} Nothing newer than ${since}: ${described}.`,
+      versions: [],
+      newest
+    };
+  }
+  const versions = newer.map((s) => s.version);
+  const header = `${server} Showing releases after ${since}: ${versions.join(", ")}.`;
+  const parts = [header, preamble, ...newer.map((s) => s.text)].filter((p) => p.length > 0);
+  return { text: parts.join("\n\n"), versions, newest };
+}
+
 // src/generated/content.ts
 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## 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.'
+    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, bridge on the wrong port, CEP refusing the panel's signature. 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## A timeout is not a disconnection\n\nBefore you start any repair, work out which of **four** failures you have. They\nread alike and their remedies contradict each other:\n\n- **Did not answer in time** \u2014 something is listening; it is just too busy to\n  reply. After Effects is single-threaded, so a long script or a modal dialog\n  waiting for a click blocks it completely. Nothing is broken and nothing needs\n  installing. The call **did** reach After Effects and may still be running, so\n  do not re-send it.\n- **Cannot reach** \u2014 nothing is listening on the port the server tried. That\n  is the case the repair path below is for \u2014 *unless* the next case applies,\n  so read the message to the end: it now says which other ports it looked at\n  and what it found there.\n- **Cannot reach on port X, while `check_setup` reports the panel on port Y**\n  \u2014 the server\'s idea of the port went stale, not the panel. The panel is\n  running and answering; the server was started from a port file that no\n  longer described it. `check_setup` reports this as its own check,\n  `portAgreement`, with both numbers. Retry the failed call: the server\n  re-checks the port whenever a call is refused and switches to the port that\n  answers by itself. If it still fails, reconnect the MCP server (restart the\n  client\'s connection to it, not After Effects). **Never restart After Effects\n  for this** \u2014 something is listening, and a restart costs the user their work\n  in progress for nothing.\n- **Waited behind another op for the write queue and was dropped** \u2014 the panel\n  is fine and this call never left the server, so nothing in the project was\n  changed. Writes are serialized so that they land in the order the agent issued\n  them and nothing drops into the middle of work the user asked for as one\n  thing; something in front is taking a very long time, usually a long\n  `run_batch`. Re-sending **is** safe here, once the work in\n  front has finished; this is the one of the four where it is. Find out what is\n  in front with `get_job` or `await_job` \u2014 reads are never queued, so `list_`\n  and `get_` calls still answer.\n\nThe message itself tells you which one you have; the queue error says in as many\nwords that nothing was written. Never collapse them into "the bridge is playing\nup", because "re-send it", "do not re-send it" and "do not restart it" are three\ndifferent answers.\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\nA **full** write queue is a fifth message and a different instruction again:\ntoo many calls are already waiting, so stop issuing writes and let it drain. If\nyou have that much independent work, send it as one `run_batch` \u2014 one\nExtendScript pass and one place in the queue, instead of dozens of each.\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 two Adobe preferences \u2014 the one that permits unsigned panels, and CEP\'s own log (only where it was never set), so that if AE ever refuses to load the panel the reason is recorded. All of it is user-level and reversible. One caution: if `check_setup` showed the install as **self-signed**, `setup_panel` replaces it with an unsigned copy and the signing has to be done again \u2014 say so before calling it.\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. When it passes, the detail also says whether the install is **self-signed** \u2014 see the last section. |\n| `panelUpToDate` | The files on disk are older than this server. Run `setup_panel`. A self-signed install\'s extra files (`META-INF/`, `mimetype`) do not count as differences. |\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 **on any port** \u2014 it asks the default port and the port file\'s port both, and reports whichever answers. Read the detail: if a port **timed out**, After Effects is busy and you should wait, not restart. If nothing is listening anywhere, one restart of AE is reasonable, because the panel loads only at launch; if that has already been tried, read `panelSignature` and `nextSteps` before suggesting a second. |\n| `portAgreement` | The panel answers, but on a different port from the one tool calls go to. The server is stale, the panel is fine. Retry the call, or reconnect the MCP server. Never restart After Effects for this. |\n| `panelSignature` | CEP\'s own log says it refused to load the panel because its signature failed verification \u2014 even with `cepDebugMode` on. An Adobe CEP 12 bug, seen on Windows. No restart and no reinstall helps; `nextSteps` carries the self-signing fix. When it *passes* on a silent bridge, its `evidence` says whether the log was clean or there was no log to read. |\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## The port, and why it is not the port file\n\nThe panel binds port 7777. On one machine nothing else ever uses it, so if\nthe port is taken when the panel starts, the holder is a previous copy of the\npanel itself \u2014 a leftover from a relaunch, or a second panel window. The panel\ndoes not move to another port in that case: it says so in its own status\n("waiting \u2014 port 7777 is held by another AE MCP panel"), and retries until the\nold one exits, then takes over with no restart. If a user reports that status\nand it does not clear, the leftover process is still running; quitting After\nEffects fully and reopening it clears it.\n\nThe panel moves only when something that is *not* an AE MCP panel holds the\nport, and it logs which port it chose and why. People who really run two\nAfter Effects instances at once can opt back into moving past their own panel\nwith a small file the panel reads at launch,\n`~/.engineroom-ae-mcp/config.json` (`%USERPROFILE%\\.engineroom-ae-mcp\\config.json`\non Windows): `{ "port": 7777, "allowPortWalk": true }`. The server is told\nwhich port to use with `AE_MCP_PORT`, and with that set it never looks\nelsewhere.\n\nWhatever the panel bound goes in the port file beside that config. The server\nreads it once at startup as a hint and no more: the socket is the authority,\nand when a call is refused the server asks 7777 and the file\'s port which one\nactually answers.\n\n## The panel is installed, AE is open, and nothing is listening\n\nIf every check passes except `bridgeReachable`, After Effects has already been\nrestarted once since the install, and nothing appears when the user opens\n**Window > Extensions > AE MCP Bridge** \u2014 no window, no error \u2014 then the\nlikely cause is CEP refusing the panel\'s signature despite `cepDebugMode`\nbeing on. It is an Adobe CEP 12 bug, seen on Windows with After Effects 2026,\nand nothing about the install is wrong. Do not send the user round a third\nrestart.\n\n`check_setup` reads CEP\'s own log and reports `panelSignature` when it finds\nthe refusal. If there is no log to read, `nextSteps` says how to turn CEP\nlogging on (one command, which it spells out; `setup_panel` sets it on new\ninstalls), after which one relaunch of AE and one more `check_setup` gives\na definite answer.\n\nThe fix is to sign the installed panel folder with Adobe\'s own `ZXPSignCmd`\nand unzip the result back over the folder in place. `nextSteps` carries the\nexact commands. Two things to tell the user: the signing survives updates to\nthe server but **not** a reinstall \u2014 `setup_panel` puts an unsigned copy back\nand warns when it does \u2014 and `check_setup` keeps reporting a signed install as\nup to date, so the extra files it adds are nothing to worry about.\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, whether it is waiting for a port another panel holds, 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### 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**Reading a shape layer, use `shapeDetail: "compact"`.** It returns one indented line per group \u2014 the group\'s name, its matchName, then its own properties as `name=value`, with `[3 keys]` or `[expr]` on the animated ones and `(at defaults)` for a group Transform nobody has touched. Every name the write tools address a node by is still on the line, and it costs a fraction of the full JSON form. Reach for `"full"` when you need exact values, keyframe detail or indices.\n\nOne thing is left out of both forms: **Material Options**, the 48-property 3D extrusion block AE hangs off every vector group. It only means anything for an extruded shape under the Cinema 4D renderer, and on the 2D shape layers that are nearly all of them it was most of the weight of the read \u2014 a single 68px circle cost 4,400 tokens, of which the geometry was about 40. `materialsOmitted` counts what was skipped; `shapeMaterials: true` brings it back.\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\n**A bare expression is not a return.** `"ping";` as the last line yields nothing, and so does any script that just does its work. That case comes back as `{ok: true, returned: null, undoGroup, note}` \u2014 an envelope that says *the script ran to completion*. Do not re-run it. Nothing rolls back, so a second run of a script that duplicated a layer, reordered content or wrote keyframes applies all of it twice; read the state back instead, and add an explicit `return` if you want a value.\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.'
+    description: "How to drive Adobe After Effects well through the AE MCP tools \u2014 orienting in a project, bounding every read, verifying a write with a diff, screenshots as a one-off diagnostic with their cost in tokens, write ordering, and the three bridge failures whose remedies contradict each other. Load whenever a task involves After Effects, motion graphics, comps, layers, or keyframes; it points at one reference per subject for everything else.",
+    body: '# Driving After Effects\n\nYou have direct control of a live After Effects session. The user sees every\nchange immediately, and every tool call is a real undo step in their project.\nWork like a motion designer at the keyboard, not like a script that fires blind.\n\nThis file holds only what silently produces wrong output on *any* task. Each\nsubject sits behind it in a reference, loaded when a task reaches that subject\nand never otherwise. From any client, `ae_guide({topic: \u2026})`; loaded as a\nskill, the file beside this one:\n\n| When the task reaches\u2026 | Topic | File |\n|---|---|---|\n| keyframes, easing, rigging, expressions | `animation` | `references/animation.md` |\n| a shape layer and its Contents | `shapes` | `references/shapes.md` |\n| a text layer | `text` | `references/text.md` |\n| shots placed into a master comp, markers, retiming a shot | `assembly` | `references/assembly.md` |\n| any raw ExtendScript for `run_jsx` \u2014 read it **before** writing the script | `extendscript-gotchas` | `references/extendscript-gotchas.md` |\n| sound effects and beds | `sound` | `references/sound.md` |\n| a `.mogrt` export, importing footage, or the solids a deleted comp leaves behind | `mogrt-and-footage` | `references/mogrt-and-footage.md` |\n| a tool that fought back, and what to do with what you learned | `issue-journal` | `references/issue-journal.md` |\n| a call that behaves differently from what you remember | `whats-new` | `references/whats-new.md` |\n\nTwo topics are siblings rather than references: `style-guide`, for capturing the\nuser\'s look, and `ae-setup`, for a connection that is not working.\n\n## Read the house style first\n\n`get_house_style` returns the project\'s style guide \u2014 palette, type, motion\ndefaults, layout rules \u2014 read from `house-style.md` beside the `.aep`. Call it\nonce at the start of any build task and follow it; it is the difference between\nwork that matches everything else the user has made and work that does not.\n\nWhat comes back is a **digest** of a few hundred tokens, which is what you build\nfrom. Pass `detail: "full"` only when you need the guide\'s own wording \u2014 and\nalways before `set_house_style`, which replaces the whole file, so you send the\nmerged document rather than a patch. `structured: false` means the guide could\nnot be read as a spec and its opening text is returned instead; `found: false`\nmeans there is none \u2014 build with sensible defaults and offer once, at the end,\nto capture one from what you made. Do not nag about it.\n\n## Orient before you touch anything\n\nNever guess at project state. Cheap reads exist for exactly this, and the\nbounded form is the one to reach for:\n\n| Question | Call |\n|---|---|\n| What is in this project? | `get_project_summary` |\n| What comps exist? | `list_comps({include: []})` \u2014 ids and names |\n| What is in this comp? | `list_layers({compId, include: []})` \u2014 id, index, name, type; `get_comp_tree` for the nesting |\n| Where is a layer, by name, type or effect? | `find_layers` \u2014 `{matches, count, compsSearched, included}`; a match is id, index, name, sourceType, compId and compName, and `include` (`flags`, `timing`, `parent` \u2014 the `list_layers` names) widens it. Unlike `list_layers`, omitting `include` here does **not** return everything |\n| One layer, in depth | `get_layer_full({compId, layerId, include: [\u2026]})` \u2B50 |\n| What did my last change actually do? | `snapshot_comp` \u2192 `diff_comp` \u2B50 |\n\n**Bound every read.** A tool result is re-sent to you on every later request\nfor the rest of the session, so an unbounded read is paid for once when you\nmake it and again on every request until the session ends. `include: []` on the\nlist calls; on `get_layer_full`, `include` names the sections you want\n(`transform`, `effects`, `masks`, `markers`, `bounds`, `text`, `shape`,\n`source`), `maxKeyframes` caps the keyframes per property, `shapeDepth` limits\nthe Contents walk, and `shapeDetail: "compact"` reads a shape layer as one line\nper group. Omit them all and you get everything. Whatever a bound leaves out is\nnamed and counted in the response, so a bounded read never passes for a\ncomplete one.\n\n**One bounded `get_layer_full` beats several narrow calls.** It returns\ntransforms with their keyframes and expressions, effects with every parameter,\nmasks, markers and `sourceRect` (the layer\'s visible bounds) in one answer, so\nwhen you need three of those, name the three in `include` rather than making\nthree calls. The bound is the `include` list, not the number of calls.\n\n**Making a variant of something** is `duplicate_comp`, which returns the new id\nso you never look for the copy by name. Its default is a **shallow** copy, the\nsame as AE\'s own Duplicate: the copy\'s precomp layers point at the *same* nested\ncomps, so editing one edits both. That is right for "another version of this\nshot" and wrong for "a variant of this rig" \u2014 for that pass `deep: true`, which\nduplicates the nested comps and re-points the copy at them.\n\n**Effects are added by matchName**, not display name:\n`add_effect({matchName: "ADBE Gaussian Blur 2"})`, then `set_effect_param` by\nparameter name. If you do not know a matchName, `list_available_effects({filter:\n"blur"})` \u2014 always with a `filter`, since the unfiltered list is several hundred\nentries and takes seconds every time. `list_effects` shows what is already on a\nlayer with every parameter.\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\nposition that **shifts whenever layers are added, deleted or reordered**. Store\n`(compId, layerId)` and pass those; an index captured before a `create_*` call\nmay point at a different layer by the time you use it.\n\n`reorder_layer` is the op that shifts every index below it, so it takes\n**exactly one** destination and the id forms are the ones to use:\n`beforeLayerId` puts the layer directly in front of (above) that layer,\n`afterLayerId` directly behind it. `toIndex` is absolute \u2014 1 is the front,\n`numLayers` the back \u2014 and means the index the layer **ends up at**, not the\nslot it displaces. Reach for it only when you genuinely mean "on top" or "at the\nback". The result carries `movedFrom` beside the landed `index`.\n\n## Read, then write, then verify\n\n1. Read the current state (a bounded `get_layer_full`).\n2. Make the change.\n3. Verify by reading back \u2014 property values are the ground truth. A screenshot\n   tells you something *looks* wrong; the property tells you *why*.\n\n**Verify with a diff, not a second full read.** Re-reading a comp to see what\nchanged makes you compare two large answers by eye, and you pay for both for the\nrest of the session. `snapshot_comp({compId})` before the write returns a\n`snapshotId` and almost nothing else; `diff_comp({since})` afterwards returns\nonly what moved \u2014 layers added, removed, renamed, retimed, re-parented, keyframe\ncounts, expressions and effects gained or lost \u2014 and a count of the layers that\ndid not. `run_jsx` and `run_batch` take `diff: true`, which does the same\n*inside* the call, so there is no window between the write and the fingerprint.\n\nA fingerprint records no property values, expression text, effect parameters,\nmasks or shape contents, so `changeCount: 0` means none of the recorded fields\nmoved \u2014 not that the comp is unchanged. For "is this value right", read the\nproperty.\n\n**A failed write is a partial write.** Nothing rolls back, on any tool: a\n`run_jsx` that throws on its fourth line has done the first three, and a\n`run_batch` that stops at op 30 has done 29. So find out what landed \u2014 on a\nfailure the `diff: true` result rides on the error, which is the cheapest way \u2014\nand never re-send the same call to see whether it fails again: the half that\nworked is applied a second time.\n\n## Screenshots are a diagnostic, not a feedback loop\n\n`screenshot_frame` and `screenshot_layer` are **one-off checks**. Do not\nscreenshot every frame, do not scrub through time, do not screenshot after every\nedit.\n\n**An image is the most expensive result this server returns, and it stays in\nyour context for the rest of the session.** Measured at 4K on 26.3: a frame at\n`downsample: 3` \u2014 the factor picked for a 4K comp when you pass none, a\n1280\xD7720 image \u2014 costs about 1,230 tokens; `downsample: 2` about 2,765; a full\n4K frame at `downsample: 1` can blow out your context in one call. Budget a\nbuild in a handful of sheets, not in frames.\n\n**To judge motion, ask for a contact sheet \u2014 one call, not three.**\n`screenshot_frame({compId, times: [0, 1, 2]})` takes two to six times and\nreturns a *single* tiled image with the time burned into each tile, held to\nroughly the pixel budget of one frame. `time` and `times` are mutually\nexclusive; there is no `times` on `screenshot_layer`.\n\nThe `downsample` is picked from the comp size unless you pass one \u2014 2 at 1080p,\n3 at 4K, aiming at a long edge near 1280px, per tile on a sheet. `downsample: 1`\nis genuinely full resolution: the render sets the comp\'s resolution explicitly\nand restores it afterwards, whatever the viewer\'s Resolution dropdown says. The\nresult reports the dimensions and the factor actually applied \u2014 trust those.\nSpace single frames out; rapid back-to-back requests are the pattern most likely\nto come back stale, and a sheet does the spacing for you.\n\nFour results are not a picture, and their remedies point in different\ndirections, so read which one you got before you retry anything:\n\n- **`Stale frame`** \u2014 After Effects re-served pixels it rendered for a\n  *different* request, which the error names. Wait a few seconds and retry at a\n  higher `downsample`; if two frames of a genuinely static comp really are\n  identical, a different factor renders a different number of pixels and proves\n  it.\n- **`Corrupt frame`** \u2014 the render stopped writing and the file is not a whole\n  PNG, so nothing was sent. **Not a timeout.** It tracks how heavy the comp is:\n  retry at `downsample` 6\u20138, or screenshot the shot precomps one at a time\n  instead of the assembly.\n- **`Render timed out`** \u2014 After Effects was still working when the panel gave\n  up, and probably still is. Wait a few seconds before doing anything else; a\n  retry issued now queues behind it.\n- **`empty: true`** \u2014 every pixel at that time is fully transparent. That is a\n  fact about the composition: the wrong time, a layer outside its in/out points,\n  disabled, or at zero opacity.\n\nOn a sheet a single bad tile is drawn as a marked block and named in `warning`;\nthe rest of the sheet is still good, so read it rather than re-requesting.\n\n**Never disable layers to make a screenshot render.** A frame that will not\nrender is a limit of the render path, not project content that needs fixing \u2014\nand it is very easy to leave someone\'s comp switched off afterwards.\n\n## Bulk work, and the order writes land in\n\n`run_batch` runs many ops in one ExtendScript pass \u2014 far faster than the same\nops as separate calls, and far fewer undo steps. **Up to 500 ops it is one undo\nstep.** Over 500 it returns a `jobId` at once, before the first chunk runs, and\nlands as **one undo step per chunk of 25** \u2014 about 24 for 600 ops \u2014 because\nAfter Effects discards an undo group that spans two script calls.\n`await_job(jobId)` finishes it, and is the call that carries progress: send it\nwith a progress token and `notifications/progress` arrive while it waits. None\ncan ride on `run_batch` itself, whose response is already back; `get_job` polls\nthe same state without a token. `singleUndo: true` forces one step at any size\nup to 2000 by running the whole batch in one blocking call, with AE\'s interface\nfrozen for the duration. Every result carries the *measured* `undoSteps`: read\nit before you tell anyone how many Cmd-Z the work takes. `transactional: true`\n(the default) stops at the first failing op; `false` runs the rest and collects\nthe errors.\nNeither rolls anything back \u2014 `diff: true` shows what landed.\n\n**You do not have to issue writes one at a time.** The server runs one write at\na time for the whole session, in the order you issued them, and a long\n`run_batch` holds that lock until its last chunk lands \u2014 so nothing drops into\nthe middle of work the user asked for as one thing. A call that had to wait says\nso with `queuedBehind` and `waitedMs`. Reads are never queued: `list_*`,\n`get_*`, the screenshots and `await_job` answer while a batch runs.\n\n## Three failures that read alike, with remedies that contradict\n\n- **Did not answer in time.** The call reached After Effects, which is\n  single-threaded, so a long script or a modal dialog nobody has clicked blocks\n  every reply. It may still be running: do **not** re-send it, do not restart\n  After Effects, do not run `setup_panel`. Poll `check_setup` for about a\n  minute, and ask the user whether a dialog is hiding behind another window. A\n  call that legitimately needs longer gets it from `AE_MCP_OP_TIMEOUT_MS` in the\n  server\'s environment.\n- **Cannot reach After Effects.** The connection was refused, so nothing\n  reached After Effects and nothing changed. The server looks again on its own\n  first \u2014 7777, then the port file \u2014 and follows a panel that has moved, so a\n  refusal that reaches you is one that search did not resolve. Call\n  `check_setup` and relay its `nextSteps` to the user in plain language; the\n  repair path is the `ae-setup` topic. If it reports the panel answering on a\n  port other than the one the call named, retry the call or reconnect the MCP\n  server and never restart After Effects for it: something *is* listening, and\n  a restart costs the user their work in progress. Do not diagnose CEP by hand.\n- **Waited behind another op for the write queue and was dropped.** Nothing\n  reached After Effects and nothing changed. Something in front is slow \u2014 usually\n  a long `run_batch`; find it with `get_job` or `await_job` \u2014 then re-send once\n  it has finished. That is the one of the three where re-sending is right.'
+  },
+  {
+    name: "animation",
+    description: "Keyframes, easing, rigging and expressions through the AE MCP tools \u2014 what each keyframe tool controls, the one ease pair per side that the tools size for you, a held pose as a hold key and a waypoint that must not stop, the parenting facts that cost review rounds (at rest, before the pop, in the parent's space, a mirrored parent), building expression text from numbers, a shake as an expression over keys, and why an expression's `time` does not follow a retimed layer. Load when a task animates, parents or drives anything with an expression.",
+    body: '# Keyframes, rigging and expressions\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- `get_keyframes` reads them all back, with the ease on each key \u2014 the exact\n  answer to "does it move right", where a screenshot is an impression.\n\n**Pass one `{influence, speed}` pair per side and nothing else.**\n`set_temporal_ease` and `add_keyframe` size the ease array for the property\nthemselves and report the count that worked as `easeDimensions`. That number is\nnot derivable from the value\'s dimension \u2014 After Effects wants a different count\nper property, and the measured table is in the `extendscript-gotchas` topic for\nthe day you script an ease by hand. Through the tools you never need it; from a\nscript, use the `ease()` helper, which is the same sizing code and not a second\ncopy of it.\n\n**A held pose is a hold keyframe, not two equal keys.** Between two\nequal-valued bezier keys the value still moves \u2014 the tangents are shaped by the\nneighbouring keys, so a pose drifts and a motion path bows through the hold.\nGive the key that starts the hold `set_interpolation({keyIndex, out: "hold"})`,\nor `interpolation` on the `add_keyframe` that makes it, and the value stays put\nuntil the next key.\n\n**A waypoint with speed zero is a stop.** Easing every key in a run brings the\nspeed to zero at each one, and the move visibly halts there. One move is one\nease \u2014 `set_temporal_ease` on the first and last key \u2014 with the keys between\nthem left linear (`set_interpolation({in: "linear", out: "linear"})`), so\nspeed passes through them instead of stopping.\n\nExpressions are usually a better answer than dense keyframes for anything\nprocedural \u2014 wiggle, loops, counters, follow-through, time remapping. They stay\neditable by the user afterwards, where a wall of baked keyframes does not.\n\n## Rigging\n\nNulls, parents and retimed layers. Parenting carries less than people expect,\nand each rule below has cost a review round more than once.\n\n**Opacity does not propagate through parenting.** Scale, rotation and position\nride the parent; opacity never does. Every text or child layer under a shape\nthat pops or stamps in needs its own matching opacity keys, or it sits there on\nscreen before its parent has revealed anything.\n\n**Parent world layers to a camera null *before* you key the null, at a time\nwhere it is still at identity** \u2014 anchor and position at the comp centre, scale\n100. Parenting compensation is a no-op there, so the children keep plain world\ncoordinates and the keyframes they already had. To look at a world target `T`\nat zoom `s`: key the null\'s scale to `s` and its position to `C + (C \u2212 T)\xB7s/100`,\nwith `C` the comp centre. Children of a precomp layer get parented while that\nparent is at rest, and AE rewrites their position and divides their scale for\nyou. `parent_layer` with `preserveTransform` does the arithmetic.\n\n**The same rule for any parent: parent while it is at rest, and before it is\nkeyed.** Keeping a child where it is means writing the inverse of the parent\'s\ntransform *at that moment* into the child, so a child parented under a tilt,\nmid-pop or at a scale other than 100 carries that inverse for good and reads\nwrong afterwards \u2014 and a parent whose first scale key is `0` has no inverse at\nall; a child parented there is divided by zero. Build, parent, then pop. Key a\nchild before parenting, while the parent is at identity, and its keys stay\nplain world values; a child keyed *after* parenting is keyed in the parent\'s\nspace \u2014 `world \u2212 parentPosition + parentAnchor`, and that difference divided by\nthe parent\'s scale when the parent is a scaled precomp. Either way, read the\nchild\'s position, scale and rotation back before trusting them; the result\'s\n`correction` says what was rewritten.\n\n**A parent mirrored with a negative scale mirrors its children, text included.**\nA rig flipped with scale `[\u2212100, 100]` shows every label backwards. Flip a text\nchild back with its own negative x scale about its own anchor \u2014 centre-justified,\nso the flip is about its centre \u2014 and when the parent flips mid-scene, do it by\nan expression on the child\'s scale that reads the sign of\n`parent.transform.scale[0]`, so the child follows every flip.\n\n**Anything flown out of frame is still there when the camera moves.** A layer\nparked at y = \u2212900 comes straight back into shot on a whip-up. Cut its opacity\nonce it is clear rather than trusting the frame edge to hide it.\n\n**Expressions run on comp time, not layer time.** Retiming a layer with\n`startTime` moves its keyframes and leaves its expressions exactly where they\nwere, so a freeze written against `time` \u2014 `Math.min(time, 0.75)` \u2014 replays\nfrom zero in the shifted layer. Offset `time` inside the expression\n(`time \u2212 startTime`, or rewrite `\\btime\\b` to `(time + offset)` in every\nexpression on a layer you retime), or key the value instead. A shot built in\nits own comp does not have this problem, which is the reason the `assembly`\ntopic builds shots in local time.\n\n## Expressions\n\n`set_expression` takes a `propertyPath` such as `["Transform", "Position"]` or\n`["Effects", "Gaussian Blur", "Blurriness"]`. Expressions are\nExtendScript-flavoured JavaScript evaluated by AE per frame.\n\n**`set_expression` throws when After Effects cannot evaluate what it wrote.**\nAssigning an expression succeeds whatever the text says; AE\'s only report is a\nwarning banner on the property in the interface, which you cannot see. So the\ntool evaluates the property after the write and, if AE reports an error on it,\nfails with AE\'s own message and the property path \u2014 a success result means the\nexpression compiles and runs. The expression is still on the property after\nsuch a failure: fix it and call `set_expression` again, or `clear_expression`\nto remove it. Do not add a second one on top. `toggle_expression({enabled:\ntrue})` verifies the same way, because enabling can surface an error that has\nsat on the property since it was disabled.\n\n`get_expression` reads one back as `expression`, `enabled` and\n`expressionError` \u2014 AE\'s message, or an empty string when it runs clean. A\nnon-empty `expressionError` means the property is not being driven by that\nexpression, whatever `enabled` says. `toggle_expression` disables one without\ndeleting it, and `clear_expression` removes it.\n\n**Build expression text from numbers explicitly.** A negative offset\nconcatenated after `time-` produces `time--2`, and an array concatenated bare\nloses its brackets (`960,540`). Write an offset as `"time-(" + t + ")"` and a\nvector as `"[" + v[0] + ", " + v[1] + "]"`. `set_expression` reports what does\nnot evaluate, with AE\'s own message, so a slip here is a failed call rather\nthan a property that quietly stops moving.\n\n**A shake on a keyed move is an expression over the keys, never more keys.**\nExtra keys fight the ease and cannot be moved with it; `value + \u2026` leaves the\nmove as keyed and adds the hit on top \u2014 a decaying sine per impact,\n`amplitude \xB7 sin(rate \xB7 d) \xB7 e^(\u2212decay \xB7 d)` with `d = time \u2212 hitTime`, summed\nover the hit times \u2014 and the null that carries the move keeps its keys\neditable.'
+  },
+  {
+    name: "assembly",
+    description: "Assembling shots into a master comp \u2014 each shot built in its own comp in local time and placed at its offset, comp markers at the beats, retiming, reversing or trimming a shot without touching its contents, the precomp that renders nothing before its startTime or past its source, what a nesting shares (controls, a resize, collapse transformations, motion blur), replacing a nested comp without losing the layers that nest it, and how an assembly, a small detail, a doubtful tile and a cut are verified. Load when a task has more than one scene, a narration to cut to, or a shot to move in time.",
+    body: "# Assembling shots into a master\n\nEvery narrated job has this shape: several shots, each a few seconds, cut to\nbeats in a voice track, in one deliverable. Build it as **one comp per shot,\nplaced into a master**, and the three questions that otherwise cost a session \u2014\nwhere does this shot start, how do I move it, why is the frame black \u2014 stop\narising.\n\n## Build each shot in local time\n\nMake each shot its own comp (`create_comp`, sized and timed like the master)\nand animate it **from zero** \u2014 its first keyframe at `0`, its expressions\nwritten against the comp's own `time`. A shot comp has its own clock: when it\nis placed into the master, every keyframe and every expression inside it keeps\nworking wherever it lands, because nothing inside it ever knew about the\nmaster's timeline. That is the whole reason to build this way; a shot animated\nin the master's absolute time cannot be moved without re-keying it, and its\nexpressions do not follow \u2014 see the `animation` topic on comp time versus layer\ntime.\n\n## Place it at its offset\n\n`create_precomp_layer({compId: master, sourceCompId: shot})` places the shot as\na layer, then `set_layer({\u2026, startTime: offset})` puts its local zero at the\nbeat. `inPoint` and `outPoint` trim it in master time; `stretch` changes its\nspeed. All four leave the shot comp untouched, which is what \"retime a shot\"\nshould mean: move the layer, never the contents. To make a shot longer or\nshorter, change its content in the shot comp and then re-trim the layer.\n\n**A precomp layer cannot run past its source.** `outPoint` clamps to the shot\ncomp's duration without a word, and a layer trimmed past it \u2014 in a rig as much\nas in the master \u2014 simply ends there. Extend the shot comp's `duration` with\n`set_comp` first, then the layer's `outPoint`, and read the out point back\nfrom the result. To play a shot backwards, time-remap the layer from the\nshot's end to its start \u2014 `run_jsx`: `timeRemapEnabled = true`, then swap the\nvalues of the two default keys with `setValueAtKey` \u2014 and nothing inside the\nshot is touched.\n\n**A precomp layer renders nothing before its `startTime`.** So you cannot hold\na rigged shot at its pre-animation state by pushing `startTime` later than the\nmoment it appears \u2014 you get an empty frame until the layer starts. Freeze the\nstart by duplicating the shot comp and stripping the keys (`duplicate_comp`,\nwhich is a shallow copy by default \u2014 pass `deep: true` when the shot nests\ncomps of its own), or start the layer at the moment it should first be visible\nand let the shot's own opening hold. Freeze the *end* past the source duration\nwith time remap and `Math.min(time + off, dur \u2212 0.1)` on the layer, not by\nextending the shot comp.\n\n**Nothing on the master's timeline hides a shot that has run past its cut.**\nTrim `outPoint` at the cut, or the next shot renders on top of a tail that is\nstill animating.\n\n## What a nesting shares, and what it clips\n\n**A control inside a shot comp is shared by every layer that nests it.** Key a\nslider in the shot and every instance of the shot changes with it. A shot that\nmust differ per placement is its own comp \u2014 `duplicate_comp`, with `deep:\ntrue` when the shot nests comps of its own \u2014 keyed on its own control.\n\n**Changing a shot comp's size moves everything that nests it by half the\nchange.** A precomp layer's anchor sits at its source's centre, and after\n`set_comp` changes the width or height the anchor and the position of each\nnesting layer no longer agree, so the nested world jumps by half the\ndifference. Read every nesting layer's anchor point and position back and\nre-place it.\n\n**A precomp is clipped at its own bounds unless collapse transformations is\non.** A blur or a glow at a shot's edge is cut off at the frame, and a camera\nbelow 100 % shows the cut edge; a shot flown through at scale goes soft at 4\xD7.\nThe layer's collapse switch fixes both \u2014 vector contents render at the final\nresolution and past the bounds \u2014 and every instance of the shot needs it, not\njust one. It costs two things: an adjustment layer inside a collapsed shot acts\non the frame *behind* the shot rather than on the shot alone, and the shot\nlayer's own blending mode is ignored. Where either matters, leave collapse off\nand oversize the shot comp instead. No tool sets the switch; from `run_jsx`,\n`layerById(compId, layerId).collapseTransformation = true`.\n\n**Motion blur is a per-comp switch and a per-layer switch, and the layer\nswitch inside the shot is the one a build forgets.** The master's comp switch,\nthe precomp layer's switch and each moving layer's switch inside the shot all\nhave to be on before anything in the shot blurs; switch the shot comp's own on\ntoo, so the shot previews the same way opened alone. From `run_jsx`:\n`comp.motionBlur = true` on a comp, `layer.motionBlur = true` on a layer.\n\n**`delete_comp` on a shot takes every layer that nests it with it**, in the\nmaster and anywhere else, silently. To replace a shot with a rebuilt one, build\nthe new comp under a working name, point each nesting layer at it \u2014 `run_jsx`:\n`layer.replaceSource(newComp, false)`, then `startTime`, `inPoint` and\n`outPoint` written again, because the swap keeps the old timing \u2014 and delete\nthe old comp only once nothing nests it (`return compById(oldId).usedIn.length`\nreads `0`); then rename.\n\n## Markers at the beats\n\n`add_marker({compId, time, comment})` with no `layerId` puts a **comp marker**\non the master; with a `layerId` it marks the layer. Put one at every beat you\ncut to, with the beat's words in `comment`, before you place a single shot \u2014 the\noffsets then have a name, the user sees the structure in the timeline, and a\nlater session reads the plan off the comp instead of re-deriving it. `duration`\nturns a marker into a span, which suits a shot's whole run.\n\n## Checking an assembly\n\n**Verify the master by reading it back; screenshot the shots.**\n`get_comp_tree({compId: master})` shows the nesting, `list_layers({compId,\ninclude: [\"timing\"]})` shows where each shot starts and ends, and\n`snapshot_comp` \u2192 `diff_comp` confirms a placement moved only the layer you\nmeant. A master is the heaviest thing you can render and the first to come back\n`Corrupt frame`; a shot comp screenshots cheaply and shows the same picture. A\ncamera move across the master is a null parented while at identity \u2014 the\n`animation` topic has the arithmetic.\n\nFour rules for the screenshots you do take:\n\n- **A shot comp with no background renders its empty areas transparent, and\n  what a transparent area looks like is the viewer, not the set** \u2014 white,\n  often, or a sheet's dark gutter. Judge sky, ground and anything that reads\n  against the background on the assembled comp over its real background, or\n  put a temporary solid behind the shot.\n- **Detail under about 40 px is judged at `downsample: 1`, never from a\n  downsampled frame** \u2014 a stroke, a label, a small icon blur or vanish at the\n  default factor. `screenshot_layer` isolates the layer but is still a whole\n  frame; for a detail in a heavy comp, a small temporary comp of a few hundred\n  pixels that nests the shot scaled up around the detail is what makes full\n  resolution affordable.\n- **A contact-sheet tile that contradicts a property read-back is re-rendered\n  as a single frame before anything is changed.** A tile can be stale \u2014 the\n  sheet names it when it can tell \u2014 and a read-back cannot, so the\n  disagreement is a question about the picture, not about the property.\n- **A cut is verified with a Difference render.** In a temporary comp, the\n  outgoing shot at its last frame under the incoming shot at its first\n  (`create_precomp_layer` twice, `set_layer` with `startTime` so those two\n  frames fall on the same comp time), the top layer at\n  `set_layer({blendingMode: \"DIFFERENCE\"})`, both over one solid so both sides\n  are opaque, collapse off on both \u2014 a collapsed layer ignores its blending\n  mode. `screenshot_frame` at that time: anything not black is where the two\n  frames disagree."
+  },
+  {
+    name: "extendscript-gotchas",
+    description: "The run_jsx reference \u2014 when to script instead of calling a tool, how much one call can do before the timeout, scriptPath and libraries as the normal way to build, the helpers already in scope, and the ExtendScript facts that abort a script while naming something else (property lookups that return null, a `.value` read at the playhead rather than at a time, effects addressed by a name that is not unique, a track matte that switches its matte's video off, ease arrays sized per property, a TextDocument that stores the wrong justification, output-module settings that are read-only, the reserved words that stop a script before its first line). Read it before writing raw ExtendScript, not after it fails.",
+    body: '# Scripting After Effects with run_jsx\n\n`run_jsx` executes arbitrary ExtendScript inside After Effects. Reach for it\nwhen a needed operation has no tool \u2014 the render queue, a bulk edit no single op\nexpresses, a rig that is easier to describe as a loop than as forty calls. Check\nthe tool list first: duplicating a comp, easing a keyframe, reordering a layer,\nplacing a shape layer at a sane origin and scoring a scene all have tools, and\neach wraps a trap on this page. The whole `OPS` table is in scope, so a script\ncan call any tool as a function and keep to the DOM for the part no tool covers.\n\n## How much one call can do\n\n- **Timeouts.** A call gets 120 s by default; `run_jsx`, `run_batch`, the two\n  screenshot ops, `export_mogrt`, `import_footage` and `place_audio_cues` get\n  300 s. `AE_MCP_OP_TIMEOUT_MS` in the server\'s environment raises every one of\n  them. ExtendScript is single-threaded, so After Effects\' interface is frozen\n  for as long as the script runs, and a script that outlives its limit looks to\n  the server exactly like a dead bridge \u2014 the "did not answer in time" failure \u2014\n  while it carries on running to the end.\n- **In practice, about 60 layers\' worth of creation and keying per call** is\n  where a scene build stays well inside the limit (reported from a\n  fourteen-scene, thousand-layer build). Split a big build by scene, not by op;\n  the same op repeated hundreds of times is `run_batch`, which chunks itself.\n- **Source size** \u2014 the script plus every library it names \u2014 is capped at 1 MB\n  per call, because libraries are inlined into the call, so every byte travels\n  every time.\n\n## Build from files, not from the conversation\n\nInline `code` is for a probe or a one-liner. A build is written as files:\n\n- **`scriptPath`** runs an absolute `.jsx` path. The server reads it, so the\n  script is paid for once, on disk, rather than once per call in the\n  conversation and again on every later request.\n- **`libraries`** takes absolute `.jsx` paths and inlines them ahead of the\n  script, in the same scope, so their functions are callable from it. A library\n  is re-read and re-evaluated on every call, so keep it to declarations rather\n  than to work; it is parse-checked on its own before the script runs, and a\n  failure inside one is reported against that file, by name and line.\n\nThe rule: a script file is paid for once; a helper shared by two scripts belongs\nin a library, never pasted into both. `code` and `scriptPath` are exclusive.\n\nPass **`diff: true`** on any script that writes. It fingerprints the comp\naround the call and appends only what changed \u2014 layers added, renamed, retimed,\nkeyframe counts \u2014 so the script reports what it did instead of you reading the\ncomp back, and on a throw the diff rides on the error, which is how you find\nwhere a half-applied script stopped.\n\n## What you already have\n\nBefore you write a helper, check it is not in scope. Each of these wraps a trap\non this page, and a version you write yourself re-derives the bug.\n\n- **`OPS`** \u2014 the whole tool table:\n  `OPS.set_transform({compId, layerId, position: [0, 0]})`. Anything a tool\n  already does well, do this way rather than reaching into the DOM.\n- **`compById(id)` / `layerById(compOrId, layerId)`** \u2014 the pair every tool\n  returns, resolved. No index arithmetic.\n- **`walkProperty(layer, ["Transform", "Position"])`** \u2014 a property path,\n  resolved the way the tools resolve it.\n- **`addKeys(prop, [[t, v], \u2026])`** \u2014 returns the key index of each, in order, so\n  the next call can ease them without searching.\n- **`ease(prop, keyIndex, easeIn, easeOut)`** \u2014 sizes the KeyframeEase array\n  itself; see "Keyframes and easing" below for why that is not optional.\n- **`shape(comp, {name, position})`** \u2014 a shape layer whose origin is `[0,0]`.\n- **`withoutUndoGroup(fn)`** \u2014 closes the undo group around one statement, which\n  is what `copyToComp` needs.\n\n## Adobe\'s documentation describes an ExtendScript After Effects 2026 does not implement\n\nEvery item here is measured on 26.3, and several contradict Adobe\'s reference:\n`$.evalFile` evaluates into the calling function\'s scope, not the global one;\n`Error.start` and `Error.end` are `0` on every error, however far in the throw\nwas; an undo group opened in one script call and closed in another is\ndiscarded; `CompItem.posterTime` does not exist; `exportAsMotionGraphicsTemplate`\ninvalidates `app.project` itself, not only the comp passed to it. None of them\nraise \u2014 each returns exactly what success returns. When this page and Adobe\'s\nreference disagree, this page was measured; and before you build on a\ndocumented behaviour nothing here mentions, write the three-line probe that\nproves it.\n\n## Property names that return null\n\n`layer.property(matchName)` returns **null** for a name that does not exist on\nthat layer. It does not throw, so the failure lands later, somewhere else, as\n`null is not an object`. When a lookup might miss, check for null on the line\nthat does it.\n\n- **2D rotation is `ADBE Rotate Z`.** `layer.property("ADBE Rotation")` is\n  null; `layer.transform.rotation` is the safe form.\n- **Audio levels are `layer.audioLevels`.** `layer.property("ADBE Audio\n  Levels")` is null on an audio layer \u2014 the level is never set, on every layer,\n  silently. *The tool already does:* `place_audio_cues`.\n- **Time remap is `layer.timeRemap`.** `layer.property("ADBE Time Remap")` is\n  null on audio layers and on precomp layers, even after\n  `timeRemapEnabled = true`.\n- **`instanceof` is unreliable on host objects.** Probe instead: a shape layer\n  is one where `property("ADBE Root Vectors Group")` is non-null, and a\n  project item\'s kind is `item.typeName` \u2014 `"Composition"`, `"Footage"`,\n  `"Folder"` \u2014 a string compare that needs no class.\n\n## Reading and writing values\n\n- **`.value` is the value at the comp\'s current time** \u2014 wherever the user\n  left the playhead, not time zero \u2014 so on a keyed or expression-driven\n  property it is one sample from a moment you did not choose. Read at the\n  time you mean with `valueAtTime(t, false)`, the post-expression value\n  (`true` is pre-expression). To bake a driven property, sample every time\n  you need first, then remove the expression, then the keys: each of those\n  changes what the next read returns.\n- **`setValue` on a comp that is not open in a viewer can throw with the\n  value already applied.** Open the comp first \u2014 `comp.openInViewer()`, or\n  `set_active_comp` from outside \u2014 and on such a throw read the property back\n  before retrying: the write may already be there.\n\n## Layers and comps\n\n- **A `comp.layer(n)` reference is index-bound, not a handle.** Once a\n  `copyToComp` or a `duplicate()` has shifted the destination\'s indices, a\n  reference taken earlier resolves to a *different* layer \u2014 which is how a script\n  parents a layer to itself. Re-resolve by id or name after anything that\n  inserts a layer.\n- **`copyToComp` does not put the copy at index 1.** The first copy lands on\n  top; each later copy lands *below the previous copy*, so `dest.layer(1)` keeps\n  handing back the same layer. Identify a copy by diffing the set of layer ids\n  before and after the call, or pass `diff: true`.\n- **`copyToComp` needs the undo group closed.** AE refuses to copy a layer that\n  has a parent or a linked expression while an undo group is open \u2014 exactly the\n  rig worth copying. Wrap that one call in `withoutUndoGroup(function () { \u2026 })`,\n  or pass `undoGroup: false` for the whole script and accept whatever undo steps\n  AE records on its own.\n- **A copied layer carries parent-relative values.** Parented to a null that\n  was not at identity, it renders offset in the destination. Check the first\n  frame against the source; fix it with an intermediate null carrying the\n  inverse offset, re-parenting while the new parent is at identity.\n- **Set the parent first, the transform second.** Raw `layer.parent = x` does\n  not reliably preserve where a layer sits two levels deep, so after scripted\n  parenting audit scale and rotation as well as position. *The tool already\n  does:* `parent_layer` with `preserveTransform`.\n- **`app.executeCommand(id)` silently no-ops** through this bridge. Menu\n  commands depend on host focus and the active selection, and the bridge has\n  neither; the call returns without complaint and nothing happens. Use the API\n  equivalents \u2014 `CompItem.duplicate()`, `layer.duplicate()`. *The tool already\n  does:* `duplicate_comp`, whose `deep: true` also duplicates the nested comps,\n  which `CompItem.duplicate()` alone does not.\n- **`moveTo` is a shape-node method, not a layer method.** `layer.moveTo(n)`\n  throws `parent is not an INDEXED_GROUP`, naming a concept the caller never\n  mentioned. Layers move with `moveBefore` / `moveAfter` / `moveToBeginning` /\n  `moveToEnd` \u2014 the first two take a **layer**, never an index, and the two\n  directions need different primitives: moving up, `moveBefore` lands on the\n  target; moving down the target shifts up as the layer leaves, so `moveAfter`\n  is the one that lands on it. *The tool already does:* `reorder_layer`.\n- **Assigning a track matte switches the matte layer\'s video off.** That is\n  After Effects\' own default, and `setTrackMatte` and `trackMatteType` both\n  do it. A layer that is both a matte and visible art gets `enabled = true`\n  again after every call that points a matte at it; read the switch back\n  rather than assuming.\n- **`replaceSource` keeps the layer\'s old timing.** `startTime`, `inPoint`\n  and `outPoint` stay where the previous source put them, so a longer or\n  shorter file arrives trimmed to the old one. After the swap write\n  `startTime`, then `inPoint`, then `outPoint`, and read them back; on a\n  time-remapped layer turn `timeRemapEnabled` off before the swap and on\n  again after it, so the default keys are rebuilt for the new duration.\n- **Removing a comp removes every layer that nests it**, in every comp,\n  without a word. The `assembly` topic has the replacement flow.\n- The layer stack builds back-to-front \u2014 every `layers.add*()` lands at\n  index 1, on top \u2014 which the `shapes` topic states beside the `Contents`\n  order it is the opposite of.\n\n## Effects\n\n- **Effects are addressed by display name, and the name is not unique.**\n  `effects.property("Slider Control")` returns the *first* effect with that\n  name, so a second slider added under the default name is unreachable by\n  name and a write meant for it silently drives the first. Name each control\n  as you add it (`fx.name = "Zoom"`), or remove a same-named one first; from\n  outside, `list_effects` reports every effect\'s name and index and\n  `set_effect_param` takes the index.\n- **Adding an effect invalidates every effect reference held on that layer**,\n  a second Slider Control included: the group re-indexes and an earlier\n  handle throws `Object is invalid`, the way a shape node reference goes\n  stale when a sibling is added. Add every effect first, then resolve each by\n  name and set its parameters.\n\n## Shapes\n\nRender order inside `Contents`, references that go stale when a sibling is\nadded, and the coordinate space of a new shape layer bite the tool path as much\nas a script, so they are in the `shapes` topic. The raw-scripting traps:\n\n- **`comp.layers.addShape()` spawns at the comp centre** with the anchor at\n  `(0,0)`, so contents authored in comp coordinates land offset by half a frame.\n  Zero the position before adding anything to `Contents` \u2014 the `shape()` helper\n  does.\n- **Polystar type is `1 = Star`, `2 = Polygon`** on `ADBE Vector Star Type`.\n  Type 2 *hides* Inner Radius, so setting it after choosing polygon throws\n  `property is hidden`. A gear is type 1.\n- **Stroke dashes do not take.** `addProperty("ADBE Vector Stroke Dash 1")`\n  followed by `setValue` throws the same hidden-property error. A dashed band\n  that does work: a small square plus a Repeater (`ADBE Vector Repeater\n  Transform` \u2192 `ADBE Vector Repeater Position` set to `[2 * side, 0]`) in a\n  group in front, over a plain rect in a group behind.\n\n## Text\n\n- **Do not write `justification` into a `TextDocument` from a script.** On\n  26.3, `d.justification = ParagraphJustification.CENTER_JUSTIFY;\n  prop.setValue(d)` on a layer made with `addText()` lands as RIGHT (`7414`):\n  the enum reads correctly in that scope (`CENTER_JUSTIFY` is `7415`, LEFT\n  `7413`), the setter stores the wrong value, and LEFT only appears to work\n  because it is `addText()`\'s default. Set font, size, colour and tracking\n  through the `TextDocument` if you like, then set justification through the\n  tool \u2014 `OPS.set_text({compId, layerId, justification: "center"})` inside the\n  script, or `set_text` / `create_text_layer`\'s `anchorAlign` from outside \u2014\n  and verify with `get_layer_full({\u2026, include: ["bounds"]})`: a centred layer\'s\n  `sourceRect.left` is about `-width / 2`, a left-justified one\'s about `0`.\n  The tool path gets a check a script does not: `set_text` and\n  `create_text_layer` read the justification back after the write, re-assert it\n  once if it moved, and throw naming expected and actual if it still disagrees,\n  so the `justification` they return is what the layer shows.\n\n## Keyframes and easing\n\n- **`setTemporalEaseAtKey` wants one `KeyframeEase` per ease dimension, and\n  that count belongs to the property, not to its value.** Measured on 26.3:\n  Opacity and sliders take 1; a 2D layer\'s **Scale takes 3** while its value\n  reads `[x, y]`; a shape\'s **Ellipse Size takes 2** while its value reads\n  `[w, h]`; Position and Anchor Point take 1 whether the layer is 2D or 3D,\n  because the ease runs along the motion path. Each of those is the opposite of\n  the sensible guess \u2014 and one session on 26.3 had a 2D layer\'s Position\n  accept only **3** through raw `setTemporalEaseAtKey`, a single observation\n  not yet reproduced. The point is that the count is not derivable, from the\n  value\'s length or from this list. The wrong one throws `Value array does not\n  have N elements` about `parameter 2` and aborts the script there. So never\n  size it by hand: `ease(prop, keyIndex, easeIn, easeOut)` is in scope and is\n  the same code `set_temporal_ease` runs \u2014 it walks 1, 2, 3, 4 until one takes\n  and returns the count that worked; the tools report the same number as\n  `easeDimensions`. A bare number means influence; omitting `easeOut` uses the\n  same ease both sides. And **put eases after every geometry and key write in\n  the script**, so an ease that still fails loses nothing above it.\n- **The key lookup is `nearestKeyIndex(t)`**, not `nearestKeyAtTime`.\n- **Removing the last Time Remap key hides the property.** After\n  `while (tr.numKeys) tr.removeKey(1)` the next `setValueAtTime` (or\n  `addKeys`) throws `Can not "set value at time" with this property, because\n  the property or a parent property is hidden`, the script dies there, and the\n  layer is left remap-enabled with no keys. Setting `timeRemapEnabled = true`\n  already creates the two keys a loop needs \u2014 `[inPoint, 0]` and\n  `[inPoint + source duration, source duration]` \u2014 so there is no reason to\n  clear them: edit those keys in place, or put an expression over them \u2014\n  `(time - startTime) % thisLayer.source.duration` loops \u2014 which overrides\n  them without touching them. If your keys must sit at other times, add them\n  **before** removing the two defaults: only a property with no keys at all\n  hides. And re-assert `outPoint` after `timeRemapEnabled = true`, because\n  enabling it resets the layer\'s end \u2014 on a remapped layer set `outPoint`\n  before `inPoint` and read both back, since an in point past the source\'s\n  natural end moves the layer instead of trimming it until the out point has\n  let it extend. If the keys are already gone, toggle `timeRemapEnabled` off\n  and on to get the defaults back. *The tool already does:* `place_audio_cues`\n  with `loop: true`.\n\n## Render queue and output modules\n\n- **`OutputModule.setSettings` rejects Format, Channels, Depth and Color as\n  read-only** \u2014 `Invalid Value for key: <Depth>. Property is read-only`, and\n  likewise `<Channels>`, `<Format>`, `<Color>` \u2014 although\n  `getSettings(GetSettingsFormat.SPEC)` lists full enum tables for all four.\n  SPEC reports a setting\'s domain, not whether it is writable;\n  `GetSettingsFormat.STRING_SETTABLE` is the honest list, and it omits all four.\n  Measured on 26.3 from four starting states (after `applyTemplate` of a ProRes\n  template, after the stock alpha templates, after a TIFF sequence, and on a\n  fresh output module setting Format alone), so it is not codec gating. "Video\n  Codec" is not in SPEC at all; it lives behind the QuickTime Format Options\n  dialog, which has no scripting surface.\n- **So codec, bit depth and alpha cannot be set from a script.** A person builds\n  the output module once in the UI \u2014 Edit > Templates > Output Module > New, or\n  Make Template from the Render Queue\'s Output Module menu \u2014 under a known name,\n  and scripts (`om.applyTemplate(name)`) and `aerender -OMtemplate "<name>"`\n  apply it by name. Templates live in AE\'s preferences, so one creation covers\n  every project on the machine. Before trusting a template, apply it and read\n  `getSettings(GetSettingsFormat.STRING)` back: an alpha-incapable codec such as\n  ProRes 422 HQ reports Channels `RGB` and will not be talked out of it.\n- **A failed `setSettings` throws before any cleanup line runs**, so a temporary\n  render-queue item added earlier in the script stays in the user\'s queue. Add\n  temporary items inside `try { \u2026 } finally { item.remove(); }`, or sweep the\n  queue at the top of the next call.\n\n## Undo groups\n\n- **An undo group does not survive a script boundary.** `beginUndoGroup` in one\n  `evalScript` call and `endUndoGroup` in another produces no group at all \u2014\n  After Effects discards it, `endUndoGroup()` returns exactly as it does on\n  success, and the only place the truth is visible is AE\'s Edit menu. Anything\n  spanning calls opens and closes its own group per call. *The tool already\n  does:* `run_batch` reports the measured `undoSteps`.\n- **`copyToComp` needs the group closed**, which is the opposite problem \u2014 see\n  "Layers and comps".\n\n## The language itself\n\nExtendScript reserves words JavaScript does not: **`short`, `int`, `char`,\n`byte`, `long`, `float`, `double`, `boolean`**. `var short = \u2026` fails with\n`Illegal use of reserved word` and **nothing in the script runs** \u2014 every side\neffect you expected is simply absent, which reads exactly like a bridge failure.\n`s`, `n`, `count`, `flag` cost nothing.\n\nThe rest of the dialect is ES3: no `let`/`const`, no arrow functions, no\ntemplate literals, no `Object.keys`, no destructuring, no trailing commas.\n\n## Reading the result, and a failure\n\n`return X` sends the whole value back \u2014 arrays and nested objects included.\nValues that cannot be represented come back as a marker string in place, never\ndropped: a live AE object as `"[AVLayer \\"Hero\\" #616]"`, which is a handle to\npass to `get_layer_full`, not a copy of the layer. An empty result therefore\nmeans the script returned nothing.\n\n**A bare expression is not a return.** `"ping";` as the last line yields\nnothing, and so does any script that just does its work. That case comes back\nas `{ok: true, returned: null, undoGroup, note}` \u2014 an envelope that says *the\nscript ran to completion*. Do not re-run it; add an explicit `return` if you\nwant a value.\n\n**On a failure, read the error before you touch anything.** It names the line\nof *your* script and prints that line\'s text; a line inside a library is\nattributed to that file; and when the number cannot be mapped it says so rather\nthan guessing. Everything above that line already ran and nothing rolls back,\nso find out what landed \u2014 `diff: true` appends it to the error; otherwise\n`diff_comp`, `get_comp_tree` or `find_layers` \u2014 and never re-run the script to\nsee whether it fails again: the lines above the failure apply a second time.'
+  },
+  {
+    name: "issue-journal",
+    description: 'What to do when a tool fights back \u2014 the journal entries a failed call brings you, when a workaround is worth writing down with log_issue and which scope it belongs in, retiring an entry that is no longer true, and how to offer the user the chance to pass a problem on without ever saying "GitHub issue". Load when a call has failed in a way you had to work around.',
+    body: '# When something costs you real time\n\nThese tools have rough edges, and the same ones catch every session. The\njournal exists so that each one is only paid for once \u2014 and it comes to you,\nrather than you going to it.\n\n## A failure brings its own history\n\n**You do not have to read the journal before you start.** When a call fails,\nthe error itself ends with `Known from earlier sessions: <scope:id> \u2014 <title>`\nfor anything that matches its tool and its error text \u2014 up to three, most\nrecently seen first, the overflow counted \u2014 and names the\n`list_known_issues({id})` call that opens the first. The cause and the\nworkaround are in the entry, not in the index. A match is also a sighting: the\nentry\'s `lastSeen` and `lastVersion` move, so an entry that keeps biting stays\nlive.\n\nReach for the listing when you are planning something that has bitten before\n(`tool` or `query` narrows it) or when the user asks what is known. It is an\nindex \u2014 id, scope, title, tools, `kind`, `lastSeen`, `lastVersion`, counts \u2014\nwith the entries naming the tool first and then the most recently seen first,\nand a `next` pointer spelling out the call that opens the top one. Archived\nentries \u2014 unseen for 30 days, a `tool-bug` last seen on an older server than\nthe one running, or retired with `archive_issue` \u2014 are hidden and counted in\n`archivedCount`; `includeArchived: true` shows them, and a read by `id` always\nworks, archived or not, because a failure\'s pointer can name one (marked\narchived, with the reason).\n\nThere are two journals and every entry says which it came from. `project` is\nthis project\'s own notes; `user` travels with the person across every project.\nIds are only unique within a journal, so open an entry with the qualified form\nthe listing\'s `next` pointer shows you \u2014 `list_known_issues({id: "user:\u2026"})`.\n\n## Write it down the moment you work it out\n\n**`log_issue`** records what you learned. Log something when all three are\ntrue: it cost real effort, it was the tool\'s fault rather than yours, and the\nnext session would hit it too. A schema that accepts an argument AE then\nrejects, an error message that names the wrong thing, a property whose real\nname is nothing like its display name. Not your own typos. Not "I forgot the\nlayer was 3D".\n\nWrite the entry for someone who has not seen the failure: the call that\nproduced it, the exact error text, and a workaround concrete enough to apply\ndirectly. **Pass `tools` and the exact `errorText`.** That is what lets the\nnext failure be answered with your entry, and it is what folds a re-log of the\nsame error into the existing entry even if you gave it a different title \u2014 the\nresult says `mergedBy: "errorText"` and keeps the existing title. Logging under\nan existing title extends that entry too, so if the failure brought you an\nentry, extend it rather than writing a twin. Use `kind: "ae-quirk"` for a\npermanent After Effects behaviour, so a new release does not archive it as\nfixed; the default `tool-bug` is presumed fixed once it was last seen on an\nolder server than the one running. Every entry records the server version it\nwas first and last seen on. If the result says `reopened: true`, a problem\nthat was supposed to be gone is back \u2014 tell the user.\n\n**Pick the scope by what the entry is about, not by where you are.** Leave it\nat the default `project` for this project\'s footage, comps or files. Pass\n`scope: "user"` when it is about how these tools or After Effects behave \u2014 that\nis nearly everything worth logging, and it is the difference between the next\nproject starting out knowing it and re-learning it.\n\n## Retire what is no longer true\n\nAn entry has to be able to leave, and most leave on their own: one unseen for\n30 days, or a `tool-bug` last seen on an older server than the one running, is\narchived without anyone deciding \u2014 and comes back the moment a failure matches\nit or a `log_issue` lands on it. `archive_issue({id, reason})` is for a\ndecision: a report already covers the problem (pass its URL as the reason), a\nrelease fixed it, or the lesson has been promoted into the\n`extendscript-gotchas` topic or the project\'s own docs. An archived entry stays\non disk, leaves the index, and is still named by a matching failure \u2014 marked\narchived, with the reason \u2014 so the pointer leads somewhere; only a deliberate\n`log_issue` reopens it. A journal that only grows is one nobody reads.\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 checks\nthe tracker for a report that already covers the problem before drafting one,\narchiving the entry when that report is closed and marking it reported when it\nis open, and handles the rest.\nIf they say no, drop it; the note stays and can be offered again another time.\n\nNever claim you have reported something you have not.'
+  },
+  {
+    name: "mogrt-and-footage",
+    description: "Exporting a Motion Graphics template, importing footage and keeping the project bin clean through the AE MCP tools \u2014 export_mogrt and the preconditions it checks before touching the project, the thumbnail, the modal dialogs that freeze this connection, the SVG whose viewBox makes After Effects fabricate dimensions and render nothing, and the solids a deleted comp leaves behind. Load when a task exports a .mogrt, imports a file, or deletes comps.",
+    body: "# Motion Graphics templates and footage\n\n## Exporting a Motion Graphics template\n\nUse **`export_mogrt`**. Do not drive `comp.exportAsMotionGraphicsTemplate`\nfrom `run_jsx`: that call raises modal dialogs, and a modal dialog freezes this\nwhole connection until someone clicks it in After Effects \u2014 but suppressing\nthem, which is what you have to do, costs you the only channel AE has for saying\nwhy an export failed. It answers with a bare boolean and nothing else. So the\ntool checks every precondition it can *before* exporting, which is the half of\nthe job a script cannot do.\n\n`export_mogrt` saves the project first (which removes AE's \"the project needs to\nbe saved\" prompt, and has to happen per export because exporting dirties the\nproject again), suppresses the font warning, and runs outside the undo group so\nthere is no \"undo group mismatch\" afterwards. Measured on 26.3: suppressed, an\nexport of a comp using a non-Adobe font returns in about three seconds;\nunsuppressed, the same export blocks past sixty and writes nothing until the\ndialog is clicked.\n\nFour things to know before you call it. The first is the one that actually\nstops exports:\n\n- **The comp needs at least one property in its Essential Graphics panel.**\n  After Effects will not build a template from an empty one, and it refuses\n  silently \u2014 no file, no dialog, not a word. The tool checks the controller\n  count first and refuses before touching anything. The fix is in AE and the\n  user has to do it: Window > Essential Graphics, pick the comp, drag a layer\n  property in.\n- **The project must have been saved once, by hand.** There is no folder to\n  save into otherwise, and the tool refuses rather than raising a dialog the\n  user was not expecting.\n- **`name` is the filename.** It defaults to the comp name, because AE's own\n  default is the literal `Untitled` \u2014 leave it to AE and every template in the\n  project overwrites the same file. `overwrite: true` is required to replace an\n  existing one.\n- **`fonts` in the result lists what the template will require.** Tell the user\n  about any non-Adobe ones: Premiere flags the template as needing fonts it\n  cannot supply, and that is worth hearing from you rather than discovering\n  later.\n\n**If an export fails anyway, read the message rather than guessing.** It lists\nwhat was checked and ruled out, and it only names a modal dialog when dialogs\nwere left *unsuppressed*. Under the default suppression a dialog is impossible\nby construction, so the cause is genuinely unknown \u2014 say so, and tell the user\nthe one place AE's own reason exists: exporting the same comp by hand from the\nEssential Graphics panel, where AE shows its error in the interface. Do not\nsend them looking for a dialog that cannot be there.\n\n**The thumbnail.** AE writes the comp's *first frame* into the template, so\nanything that fades up from nothing gets a black one. Pass `posterTime` with a\nmoment that actually shows the design and it is rendered and swapped in. If\nonly the thumbnail fails the export still succeeds \u2014 check `thumbnail.patched`\nin the result.\n\n`comp.setMotionGraphicsControllerName(index, \u2026)` numbers controllers in\n**reverse order of addition**: index 1 is the one added last.\n\n**If any long call seems to have hung, assume a dialog before you assume a\ncrash** \u2014 it may be behind another window. `comp.saveFrameToPng(...)` from\n`run_jsx` raises the save prompt the same way; use `screenshot_frame`, which\ndoes not.\n\n## Importing footage, and the SVG trap\n\nUse **`import_footage`**, then **`create_footage_layer`** to place the item in\na comp. (For a comp as a layer, `create_precomp_layer`.)\n\n`import_footage` checks what AE actually produced, because one case fails\nsilently: an SVG with a very large `viewBox` (say `0 0 278050 333334`) imports\nwith **fabricated dimensions and renders as nothing**, no error at any stage.\nMeasured on 26.3: that viewBox yields a 15906\xD75654 item that will not even\nrasterize, and the numbers depend only on the viewBox. The tool compares the\naspect ratio the file asks for against the one AE produced, and on a mismatch it\ndeletes the item and throws, rather than handing you an asset that looks healthy\nin 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\n  vertices, scaled down to a sane coordinate space (divide by `333.334` for a\n  1000px version), set the fill from the SVG, and set `ADBE Vector Fill Rule`\n  to `2` when the SVG says `fill-rule=\"evenodd\"`. Done this way the result is\n  pixel-accurate.\n- **Complex SVGs** \u2014 rasterise to PNG outside AE, or normalise the `viewBox` to\n  a small coordinate space before importing.\n\n`force: true` keeps the item and reports the problem in `validation` instead of\nthrowing. It is for when you know the dimensions are wrong and want it anyway \u2014\nnot a way past the error.\n\n## Solids outlive their comps\n\nA solid or adjustment layer's source is a footage item in the project's Solids\nfolder, and `delete_comp` and `delete_layer` remove the layer, not the item \u2014\nso iterating on a rig by building and deleting comps silently fills the bin.\n`delete_comp` counts what it left in `unusedSolidsLeft`, with a note when that\nis not zero. Pass `purgeUnusedSolids: true` to take the comp's own now-unused\nsolids with it in the same undo step, reported as `removedSolids` and\n`keptSolids` \u2014 a solid another comp still uses is kept, with that comp named\nunder `usedIn`. Only the deleted comp's own solids are ever considered there;\n`purge_unused_footage` sweeps the whole project: solids only by default,\n`solidsOnly: false` for every unused footage item (what AE's own Remove Unused\nFootage does), `folderId` to scope it to one folder, and `dryRun: true` \u2014\nfirst, on a project you did not build \u2014 which answers `wouldRemove` without\nremoving anything or adding an undo step. Neither ever removes a solid another\ncomp still uses, or a nested comp: a comp nothing uses is not footage. A comp\nanother comp *does* nest is the opposite case \u2014 deleting it takes the nesting\nlayers with it \u2014 and the `assembly` topic has the replacement flow."
+  },
+  {
+    name: "shapes",
+    description: "Shape layers through the AE MCP tools \u2014 the origin a new shape layer spawns at and why it is the comp's coordinate space, add_shape_content and its all-or-nothing contract, one fill per group, the render order inside Contents that runs opposite to the layer stack (which builds back-to-front), node references that go stale, a group's pivot, seams between shapes, centring a repeated run, and reading a shape layer cheaply. Load when a task builds or edits a shape layer.",
+    body: '# Shape layers\n\n## Where a new shape layer\'s origin is\n\n`create_shape_layer` puts the new layer\'s origin at `[0,0]` with its anchor at\n`[0,0]`, so **the layer\'s coordinate space is the comp\'s**: every vertex, rect\nposition and path you add afterwards is in comp pixels, the same space as the\ncomp size, another layer\'s position, `sourceRect` and a screenshot. After\nEffects\' own spawn point is the comp centre, which silently offsets a drawing\nauthored in comp coordinates by half a frame; pass `position: "center"` if you\nwant that back, or any `[x, y]` to place the origin yourself. The result echoes\nthe position and anchor it ended up with, so nobody has to render a frame to\nlearn the coordinate system.\n\n## Adding contents\n\n`add_shape_content` builds one node at a time under `Contents` \u2014 `rect`,\n`ellipse`, `star`, `path`, `fill`, `stroke`, `trim`, `repeater`, `merge`,\n`group`. Properties are set with friendly names in the same call (`size`,\n`position`, `roundness`, `color`, `width`, `lineCap`, \u2026). For a custom path,\n`{type: "path", vertices: [[x, y], \u2026], closed: true}` \u2014 the key is `vertices`,\nnot `points`. `set_shape_path` replaces a path\'s vertices and tangents later;\n`set_shape_property` sets one property on a node, optionally as a keyframe.\n\nThe tool is **all-or-nothing**: if a key cannot be applied, the whole node is\nremoved and the error names the bad keys, so a success result means everything\nlanded. Do not add defensive re-reads for it \u2014 but do read the error, since it\nusually means the property is named differently on that node type, and a\n`get_layer_full({\u2026, include: ["shape"]})` shows the real name.\n\n**A fill or stroke applies to every path above it in its group.** One Fill\nunder two paths fills both, so an open stroked path beside a filled shape in\nthe same group renders as a filled polygon. One group per path-and-paint\npairing: `{type: "group"}` first, then the path and its fill or stroke inside\nit through `parentGroupPath`.\n\n**Render order is the opposite of the layer stack.** Inside `Contents`, index 1\nrenders in *front*, and each `add_shape_content` call appends behind the\nprevious one. So build **front-to-back**: details, text plates and\ntraffic-light dots first, the big background rectangle last. Getting it\nbackwards is silent \u2014 no error, just a solid slab where the artwork should be.\n`zOrder: "front"` places a node at index 1 for you, but it needs an internal\n`moveTo`, which disturbs *nested* renders of the comp on AE 26.3; prefer\nordering the calls. If existing content is in the wrong order, rebuild it rather\nthan reordering, and verify with a screenshot of a comp that **nests** it, not\nonly the comp that owns it. None of this applies to the layer stack: moving\nwhole layers is `reorder_layer`, a different mechanism with none of these\ncaveats. The stack runs the other way: every new layer \u2014 `create_*`,\n`duplicate_layer`, a `layers.add*()` in a script \u2014 lands at index 1, on top,\nso a stack is built **back-to-front**, the plate first and the label after,\nand a script re-run from the middle re-stacks whatever it recreates over what\nwas already there.\n\n**Node references go stale.** Adding a sibling to a group invalidates a\nreference you already hold to another node in it \u2014 add a Stroke and an earlier\nFill reference starts throwing `Object is invalid`. Add every node first, then\nset values and expressions by addressing nodes by name. The tool re-fetches\nafter every insert for the same reason.\n\n## Animating a group\n\nA group drawn in comp coordinates pivots at the comp origin: its Transform\'s\nanchor point is `[0,0]`, which with the layer\'s origin at `[0,0]` is the comp\'s\ntop-left corner, so a scale or rotation keyed on the group swings the artwork\naround that corner. Before keying a group, set its anchor point to the pivot\nyou mean *and* its position to the same value \u2014 `set_shape_property` with\n`contentPath: ["Contents", "<group>", "Transform"]` and `property: "Anchor\nPoint"`, then `"Position"` \u2014 which leaves the artwork where it is and turns it\nabout the pivot.\n\n## Seams and runs\n\n**Two shapes that meet on a shared edge show the seam when they move.**\nAnti-aliasing leaves both edges partly transparent, so a hairline of whatever\nis behind flickers along the join under a camera move, worst over a dark\nground. Overlap the back shape 10\u201320 px under the front one rather than\nbutting them.\n\n**Centring a repeated run** \u2014 a Repeater tape, a dashed band \u2014 of copies `s`\nwide at pitch `p` across a width `W` starting at `left`:\n`copies = floor((W \u2212 s) / p) + 1`, and the first copy\'s centre is\n`left + (W \u2212 s \u2212 (copies \u2212 1)\xB7p) / 2 + s/2`. With that `copies` on the\nRepeater and that centre as the first element\'s position the run is\nsymmetrical whatever `W` is; dashes with equal gaps are `p = 2s`.\n\n## Reading a shape layer\n\nUse `shapeDetail: "compact"` on `get_layer_full`. It returns one indented line\nper group \u2014 the group\'s name, its matchName, then its own properties as\n`name=value`, with `[3 keys]` or `[expr]` on the animated ones and\n`(at defaults)` for a group Transform nobody has touched. Every name the write\ntools address a node by is still on the line, at a fraction of the cost of the\nJSON form. Reach for `"full"` when you need exact values, keyframe detail or\nindices, and `shapeDepth` to stop the walk at a depth on a heavy layer.\n\nOne thing is left out of both forms: **Material Options**, the 48-property 3D\nextrusion block AE hangs off every vector group. It only means anything for an\nextruded shape under the Cinema 4D renderer, and on a 2D shape layer it is most\nof the weight of the read \u2014 a single 68px circle costs 4,400 tokens with it, of\nwhich the geometry is about 40. `materialsOmitted` counts what was skipped;\n`shapeMaterials: true` brings it back.\n\n## Scripting shapes by hand\n\nThe raw-scripting traps \u2014 the spawn point of `addShape()`, polystar types that\nhide their own properties, stroke dashes that refuse to take \u2014 are in the\n`extendscript-gotchas` topic, along with the `shape()` helper that lands a\nscripted layer at `[0,0]`.'
+  },
+  {
+    name: "sound",
+    description: "Sound effects and beds through the AE MCP tools \u2014 place_audio_cues for a whole cue list in one undo step, what levelDb actually means and why a level copied from another cue is meaningless, peak for a one-shot and RMS for a bed with the onset on the beat, loops, fades and stretch per cue, a trim clamped at the file's end, a bed that follows a move, the dry run, a file that will not place, and the audio facts a hand-written loop gets wrong. Load when a task places, levels or times sound.",
+    body: "# Sound\n\n`place_audio_cues` scores a scene in one call: a list of cues \u2014 each a file (or\nan already-imported `footageId`), a comp `time` and a `levelDb` \u2014 becomes one\naudio layer each, imported once however many cues name the same file, named,\ntrimmed, labelled, in a single undo step. Reach for it the moment you are\nplacing more than two or three sounds; the alternative is dozens of round trips\nor a `run_jsx` loop that has to know that `layer.property(\"ADBE Audio Levels\")`\nreturns null on an audio layer.\n\nIt is **all-or-nothing**: every cue is checked (the file exists, the item has\nan audio track, the time is inside the comp) before a single layer is made, and\nif a later one still fails, everything the call created is removed and the\nerror names the cue by index. `dryRun: true` checks a list against the project\nwithout importing, creating, or even adding an undo step, and answers with\ncounts, `wouldImport`, `wouldReuse` and the failing cues by index \u2014 never the\nresolved list. Each cue names its sound with exactly one of `path` or\n`footageId`; `inPoint` and `outPoint` trim in **comp** time, not file time. An\n`outPoint` past the file's placed length \u2014 its duration times `stretch` \u2014 is\nclamped to it without a word, so read the out point back from the result; a\nsound that must run longer is `loop: true`, not a longer trim.\n\n## Levels\n\n`levelDb` is decibels, After Effects' own unit: **`0` is the file as recorded**,\nnegative is quieter, and it is written explicitly even when you omit it. Two\nthings follow:\n\n- **A level copied from another cue is meaningless.** Files in one sound bank\n  routinely differ by 30 dB as recorded \u2014 a whoosh mastered hot and a room tone\n  mastered quiet \u2014 so `-6` on one is nothing like `-6` on the other. Measure\n  before you set: peak and RMS of the file (`ffmpeg -af volumedetect`, `sox\n  stat`, or whatever the shell has; where there is no shell, ask the user what\n  the file sounds like against the others), then choose a level that brings it\n  to where you want it, not a number that looked right last time.\n- **Read the level back off the layer.** The result carries one small entry\n  per cue \u2014 `layerId`, `name`, `time`, and what an option changed \u2014 and does\n  not echo the level; `run_jsx` with\n  `return layerById(compId, layerId).audioLevels.value` reads it. Ask the user\n  to preview if they can \u2014 a level is the one property in this toolset that no\n  screenshot can check.\n- **Match a one-shot by peak and a bed by RMS.** A hit is heard at its peak\n  and a bed at its average, so a bed levelled by peak sits too low and a hit\n  levelled by RMS jumps out. And put the file's *onset* on the beat, not its\n  start: a one-shot with silence before the hit goes at `time: beat \u2212 onset`\n  with `inPoint: beat` to trim the silence, which is also how a hit is\n  shortened under a visual shorter than the file.\n\n## Loops, fades and stretch\n\nThree per-cue options cover what a scoring pass otherwise redoes in `run_jsx`,\nand each moves something After Effects then quietly resets \u2014 which is the\nreason to take them from the tool rather than script them:\n\n- **`loop: true`** repeats the sound to the cue's `outPoint`, or to the end of\n  the comp when there is none \u2014 beds and ambiences. It enables time remapping\n  with a wrap-around expression on Time Remap, keeps the two keyframes AE\n  creates (removing them hides the property), and re-asserts the out point,\n  because enabling remapping resets it. `inPoint` still trims the front of the\n  file the way it does on any layer.\n- **`fadeIn` / `fadeOut`**, in seconds, keyframe Audio Levels at the in and\n  out point the layer actually has, between the call-level `fadeFloorDb`\n  (default `-48`, the bottom of AE's own slider) and the cue's `levelDb`. A\n  fade that does not fit the cue's placed length, or a floor at or above the\n  cue's level, is refused by cue index with nothing placed; for a file not yet\n  imported the fit is checked right after the import, before any layer exists.\n  The result carries `fadeFloorDb` when any cue faded.\n- **`stretch`** is a percentage: `100` unchanged, `200` half speed at a lower\n  pitch. The start time and any trims are re-asserted after it, because AE\n  moves them when stretch changes. A loop that is also stretched has the factor\n  baked into its expression, so changing the stretch by hand afterwards leaves\n  the loop wrapping at the old rate \u2014 set it here, or place the cue again.\n\nEvery option is validated with the rest of the list before anything is\ncreated, and the result names what an option changed \u2014 `looped`, `stretch`,\n`fadeIn`, `fadeOut`, and the in and out point read back \u2014 only on the cues it\napplied to.\n\n## Timing\n\nCue times are comp times, and a cue placed in a shot comp is at that comp's\nlocal time, so a cue list for a master and a cue list for a shot are different\nlists \u2014 put a sound where the thing that makes it lives. Comp markers at the\nbeats (the `assembly` topic) are the right skeleton for a cue list, and a cue's\n`name` is worth setting to the beat it belongs to.\n\nA sound that belongs to a move follows the move. Under an eased camera, a bed\nrun at a constant rate and level comes apart from the picture at every ease;\ndrive the bed's Time Remap from the distance the camera has travelled and its\nlevel from the camera's `speed` (expressions on the audio layer reading the\nnull's position), so it slows, stops and rises with the move.\n\n## A file that will not place\n\nA file that imports with no audio track, or refuses to import at all, is worth\nchecking for its sample format before anything else: a 32-bit float WAV\n(format tag 3) is the usual case. Convert it to 16-bit PCM \u2014 `afconvert -f\nWAVE -d LEI16 in.wav out.wav` on macOS, `ffmpeg -i in.wav -c:a pcm_s16le\nout.wav` anywhere \u2014 and keep a sound bank at 16-bit PCM so it never comes up.\n\n## Scripting sound by hand\n\nThe raw-scripting facts \u2014 `layer.audioLevels` rather than a property lookup,\n`layer.timeRemap` for a loop, and the Time Remap keys that must not be cleared\n\u2014 are in the `extendscript-gotchas` topic."
   },
   {
     name: "style-guide",
     description: "Help a motion designer capture their house style \u2014 palette, type, motion and layout \u2014 into the house-style.md file that sits next to their After Effects project and shapes everything built afterwards. Load when the user asks to create, edit or review their style guide, when they say work does not look like theirs, or when get_house_style reports none exists.",
-    body: '# Capturing a house style\n\nA house style is the difference between an assistant that builds *a* lower third\nand one that builds *their* lower third. It lives in `house-style.md` beside the\n`.aep` file, and `get_house_style` reads it before any build task.\n\nYour job here is to get one written with as little effort from the user as\npossible. They are a motion designer. They know exactly what their work looks\nlike and will struggle to dictate it as a specification \u2014 so do not ask them to.\n\n## Two ways in. Prefer the first.\n\n### 1. Read it off work they already like\n\nThis is far better than any questionnaire, because it produces real numbers\ninstead of adjectives.\n\n1. Ask which comp to learn from \u2014 "point me at something that looks the way you\n   want everything to look."\n2. `get_comp` for size and frame rate, then `get_layer_full` on the layers that\n   carry the look: the text, the background, the accent shapes.\n3. Pull out the concrete values \u2014 hex colours, font families and sizes, tracking,\n   corner radii, stroke widths, the position of things relative to the frame.\n4. Read the keyframes too. `get_keyframes` plus the ease settings tell you the\n   timing signature: how long a standard in-animation takes, whether it\n   overshoots, whether anything is ever linear.\n5. Show them what you found, in their language, and ask what to change:\n\n   > Here\'s what I read off that comp: near-black background `#0B0D12`, white\n   > text in Inter Semibold at 64px with slightly tight tracking, one green\n   > accent `#3DC46E`. Things scale in over about 0.4s with an overshoot to 108%\n   > and easy ease on both ends. Nothing sits perfectly still \u2014 there\'s a slow\n   > wiggle on the chip. Does that sound like your style, or was that comp a\n   > one-off?\n\n6. Write it with `set_house_style`.\n\n### 2. Ask, when there is nothing to read\n\nOnly if the project is empty or they have no reference. Keep it to four\nquestions, and offer concrete options rather than open ones \u2014 "dark or light\nbackground?" beats "what\'s your palette?". Then build one small example, show it\nwith `screenshot_frame`, and refine from their reaction. Reacting is easier than\nspecifying.\n\n## What makes a guide that actually works\n\n**Numbers, not adjectives.** `#131521 at 92% opacity` is usable. "Dark and clean"\nis not. If a corner radius, a stroke width or a hold duration matters, write the\nnumber. Anything vague will be silently reinterpreted every time it is read.\n\n**Rules, not just values.** The most valuable lines are the prohibitions: "never\nput text directly on footage \u2014 always on a rounded chip", "keep total runtime\nunder 8 seconds", "no linear motion unless something mechanical is moving".\nThose are what stop work drifting.\n\n**Only what you verified.** Do not pad the file with plausible-sounding defaults\nthey never asked for. A short guide that is true beats a complete one that is\nhalf invented. Leave a heading empty rather than filling it with a guess.\n\n## Keep it current\n\nWhen the user corrects the same thing twice \u2014 "no, the accent green, not the\nblue" \u2014 that is a missing rule, not a one-off. Offer to add it:\n\n> I\'ve had to switch that green twice now. Want me to put it in the style guide\n> so it\'s the default from here?\n\nRead the existing guide with `get_house_style` before writing, and preserve what\nis already there. `set_house_style` replaces the whole file, so send back the\nfull document, not just your additions.\n\n## The one thing to warn them about\n\n`house-style.md` is written next to the `.aep`, so **the project has to have been\nsaved at least once** \u2014 an unsaved project has no folder to write into, and\n`get_house_style` will say so. If that happens, ask them to save the project\nfirst, then write the guide.\n\nThe file is plain markdown. Tell them where it is and that they can edit it in\nany text editor without going through you.\n\n## Starting point\n\nWhen writing a guide from scratch, this is the shape to fill in. Drop headings\nyou have nothing real to put under.\n\n```markdown\n# House style\n\n## Palette\n| Role | Colour | Notes |\n|---|---|---|\n| Background | `#0B0D12` | |\n| Primary text | `#FFFFFF` | |\n| Accent | `#3DC46E` | Emphasis and positive values |\n| Negative | `#E03333` | |\n\n## Type\n- Headings: Inter Semibold, 56\u201372px, tracking -10\n- Body: Inter Regular, 28\u201334px\n- Left-aligned unless stated otherwise\n\n## Motion\n- Standard in: scale 0 \u2192 108 \u2192 100, easy ease, ~0.4s\n- Standard out: scale \u2192 0, ~0.3s\n- Easy ease on everything; no linear motion unless mechanical\n- Subtle wiggle on position so nothing sits perfectly still\n\n## Layout\n- 1920\xD71080 at 30fps\n- 120px safe margin from every edge\n- Lower thirds sit bottom-left, above the margin\n\n## Rules\n- Never put text directly on footage \u2014 always on a rounded chip\n- Total runtime under 8 seconds\n```'
+    body: '# Capturing a house style\n\nA house style is the difference between an assistant that builds *a* lower third\nand one that builds *their* lower third. It lives in `house-style.md` beside the\n`.aep` file, and `get_house_style` reads it before any build task.\n\nYour job here is to get one written with as little effort from the user as\npossible. They are a motion designer. They know exactly what their work looks\nlike and will struggle to dictate it as a specification \u2014 so do not ask them to.\n\n## Two ways in. Prefer the first.\n\n### 1. Read it off work they already like\n\nThis is far better than any questionnaire, because it produces real numbers\ninstead of adjectives.\n\n1. Ask which comp to learn from \u2014 "point me at something that looks the way you\n   want everything to look."\n2. `get_comp` for size and frame rate, then `get_layer_full` on the layers that\n   carry the look: the text, the background, the accent shapes.\n3. Pull out the concrete values \u2014 hex colours, font families and sizes, tracking,\n   corner radii, stroke widths, the position of things relative to the frame.\n4. Read the keyframes too. `get_keyframes` plus the ease settings tell you the\n   timing signature: how long a standard in-animation takes, whether it\n   overshoots, whether anything is ever linear.\n5. Show them what you found, in their language, and ask what to change:\n\n   > Here\'s what I read off that comp: near-black background `#0B0D12`, white\n   > text in Inter Semibold at 64px with slightly tight tracking, one green\n   > accent `#3DC46E`. Things scale in over about 0.4s with an overshoot to 108%\n   > and easy ease on both ends. Nothing sits perfectly still \u2014 there\'s a slow\n   > wiggle on the chip. Does that sound like your style, or was that comp a\n   > one-off?\n\n6. Write it with `set_house_style`.\n\n### 2. Ask, when there is nothing to read\n\nOnly if the project is empty or they have no reference. Keep it to four\nquestions, and offer concrete options rather than open ones \u2014 "dark or light\nbackground?" beats "what\'s your palette?". Then build one small example, show it\nwith `screenshot_frame`, and refine from their reaction. Reacting is easier than\nspecifying.\n\n## What makes a guide that actually works\n\n**Numbers, not adjectives.** `#131521 at 92% opacity` is usable. "Dark and clean"\nis not. If a corner radius, a stroke width or a hold duration matters, write the\nnumber. Anything vague will be silently reinterpreted every time it is read.\n\n**Rules, not just values.** The most valuable lines are the prohibitions: "never\nput text directly on footage \u2014 always on a rounded chip", "keep total runtime\nunder 8 seconds", "no linear motion unless something mechanical is moving".\nThose are what stop work drifting.\n\n**Only what you verified.** Do not pad the file with plausible-sounding defaults\nthey never asked for. A short guide that is true beats a complete one that is\nhalf invented. Leave a heading empty rather than filling it with a guess.\n\n## Keep it current\n\nWhen the user corrects the same thing twice \u2014 "no, the accent green, not the\nblue" \u2014 that is a missing rule, not a one-off. Offer to add it:\n\n> I\'ve had to switch that green twice now. Want me to put it in the style guide\n> so it\'s the default from here?\n\nRead the existing guide with `get_house_style` before writing, and preserve what\nis already there. `set_house_style` replaces the whole file, so send back the\nfull document, not just your additions.\n\n## The one thing to warn them about\n\n`house-style.md` is written next to the `.aep`, so **the project has to have been\nsaved at least once** \u2014 an unsaved project has no folder to write into, and\n`get_house_style` will say so. If that happens, ask them to save the project\nfirst, then write the guide.\n\nThe file is plain markdown. Tell them where it is and that they can edit it in\nany text editor without going through you.\n\n## The digest contract\n\n`get_house_style` answers with a digest by default, and the digest is built by\na parser that recognises a fixed vocabulary. **The template\'s headings are the\ncontract.** A guide written under them comes back `structured: true` with every\nsection read; a guide written under other headings comes back with those\nsections named in `sectionsOmitted`, or \u2014 when nothing at all is recognised \u2014\n`structured: false` with the document\'s opening text and no palette, which the\nnext session will read as "this project has no rules". So write the guide in\nthe shape below, and when the user\'s own guide uses different headings, tell\nthem which ones were skipped rather than letting them believe it was read.\n\nWhat the parser recognises:\n\n- **Headings** \u2014 markdown `#` headings of any level, and the underlined\n  (`===` / `---`) forms. A heading is classified by the words in it:\n  *palette, colour, color, swatch* \u2192 palette; *type, typography, font,\n  lettering, typeface* \u2192 type; *motion, animation, timing, easing, ease,\n  transition* \u2192 motion; *layout, grid, spacing, composition, margin, safe area,\n  framing, rule, constraint* \u2192 layout. "Rules" is read as layout on purpose.\n  A subsection under a classified heading is folded into it (`### Display`\n  under `## Type`); a top-level title such as `# House style` with no prose of\n  its own is fine.\n- **Colours** \u2014 every hex (`#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`) anywhere in\n  the document, not only under Palette. It is named by the text before it on\n  the line, or by the first non-hex cell of its table row, so `Accent: #3DC46E`\n  and a table row whose first cell is *Accent* both come back as *Accent*. A\n  colour written as `rgb(\u2026)` or by name is not a palette entry.\n- **Size** \u2014 up to 24 colours, 3 type lines, 8 layout lines and about 240\n  characters of motion. Put the lines that matter most first under each\n  heading; what is dropped is counted in the digest\'s `note`.\n\n## Starting point\n\nWhen writing a guide from scratch, this is the shape to fill in \u2014 its headings\nare the ones the digest reads. Drop headings you have nothing real to put\nunder.\n\n```markdown\n# House style\n\n## Palette\n| Role | Colour | Notes |\n|---|---|---|\n| Background | `#0B0D12` | |\n| Primary text | `#FFFFFF` | |\n| Accent | `#3DC46E` | Emphasis and positive values |\n| Negative | `#E03333` | |\n\n## Type\n- Headings: Inter Semibold, 56\u201372px, tracking -10\n- Body: Inter Regular, 28\u201334px\n- Left-aligned unless stated otherwise\n\n## Motion\n- Standard in: scale 0 \u2192 108 \u2192 100, easy ease, ~0.4s\n- Standard out: scale \u2192 0, ~0.3s\n- Easy ease on everything; no linear motion unless mechanical\n- Subtle wiggle on position so nothing sits perfectly still\n\n## Layout\n- 1920\xD71080 at 30fps\n- 120px safe margin from every edge\n- Lower thirds sit bottom-left, above the margin\n\n## Rules\n- Never put text directly on footage \u2014 always on a rounded chip\n- Total runtime under 8 seconds\n```'
+  },
+  {
+    name: "text",
+    description: "Text layers through the AE MCP tools \u2014 alignment as live paragraph justification rather than a measured anchor, tracking set explicitly so the Character panel cannot leak in, what set_text controls, and sizing a background to the text. Load when a task creates, restyles or lays out a text layer.",
+    body: '# Text layers\n\n`create_text_layer` defaults to `anchorAlign: "left"`, which sets **paragraph\njustification** and leaves the anchor point at `[0,0]`, so `position` is the\nstart of the first baseline. Pass `"center"` or `"right"` for those, `"none"`\nfor AE\'s raw behaviour. Because the alignment is justification rather than a\nmeasured offset, it stays correct when the text changes later \u2014 retyped, driven\nby an expression, or edited through Essential Graphics in Premiere. Never "fix"\nalignment by writing an anchor point computed from `sourceRectAtTime()`: it is\nright once and wrong from the next edit onward.\n\nTracking is set to `0` unless you pass one, because AE\'s `addText()` otherwise\ninherits whatever the user\'s Character panel was last left on, and the same\ncall then renders differently on two machines.\n\n`set_text` controls the text and its styling \u2014 font, size, fill and stroke,\ntracking, leading, justification, faux bold and italic, caps, baseline shift.\n`add_text_animator` adds an animator group (position, scale, rotation, opacity,\ntracking, skew, fill and stroke colour) with an optional range selector, which\nis how per-character animation is built.\n\n**Verify alignment by the bounds, not by eye.** `get_layer_full({\u2026, include:\n["bounds"]})` returns `sourceRect`: a centred layer\'s `left` is about\n`-width / 2`, a left-justified layer\'s about `0`, a right-justified layer\'s\nabout `-width`. That is the check to make after a script has touched a\n`TextDocument`; the tools check their own writes, below.\n\n**To fit a background to text**, read `sourceRect` from the same call and size\nthe shape from its width and height plus padding, positioned from its `left`\nand `top`. A `sourceRectAtTime()` expression on the background does the same\nthing live, and stays right when the text is retyped.\n\n**The justification you got is the one in the result, not the one you asked\nfor.** On 26.3 the Source Text round trip can hand back a different alignment\nfrom the one written \u2014 a left-aligned layer re-centred by a `set_text` that\nchanged only `text`. So `set_text` and `create_text_layer` read the\njustification back after every write, write it once more on its own if it\nmoved, and throw naming expected and actual if it still disagrees;\n`create_text_layer` removes the layer first, so a failure never leaves a layer\nyou have no id for. Both results carry `justification` as a name and\n`justificationReasserted`, and an unknown justification name is refused rather\nthan ignored. Trust `justification` in the result over your own argument.\n\n**From `run_jsx`, set justification through the tool** \u2014\n`OPS.set_text({compId, layerId, justification: "center"})` inside the script \u2014\nrather than by assigning `TextDocument.justification`, which on 26.3 stores the\nwrong value and gets no read-back. The `extendscript-gotchas` topic has the\nmeasurement under Text.'
+  },
+  {
+    name: "whats-new",
+    description: "What changed in the After Effects tools, one section per release, newest first \u2014 each entry leads with the rule as it now stands and quotes the old rule it replaces, so a project's own notes can be found and corrected. Read it when a call behaves differently from what you expected, when the user says a tool used to do something else, or with `since` to see only the releases after the one this project last absorbed.",
+    body: "<!--\nFormat contract. `ae_guide({topic: \"whats-new\", since: \"<version>\"})` filters\nthis file by machine and the absorb-release prompt greps project docs with it:\n\n- One `## <semver>` section per release, newest first. No other `##` heading\n  below the first release heading; group inside a release with `###`.\n- Everything above the first `## <semver>` is the preamble. It is returned with\n  every filtered read, so it stays short.\n- An entry is one bullet. It opens with a **bold phrase stating the rule as it\n  now stands**, present tense, then the reason and what changed.\n- A bullet whose rule replaces something a project's own docs may say carries\n  one or more indented `supersedes:` lines directly under it, each quoting the\n  OLD rule in the words a project doc would have used. They are grep targets:\n  short, literal, no markdown.\n-->\n\n# What changed\n\nRead this when something behaves differently from what you expected, or when the\nuser tells you a tool used to work another way. It is the release notes an agent\nneeds rather than the ones a human reads: one section per release, newest first.\nEvery entry leads with the rule as it now stands; a `supersedes:` line under it\nquotes the old rule in the words a project's own notes would have used, so those\nnotes can be searched for and corrected. Pass `since` \u2014 as in\n`ae_guide({topic: \"whats-new\", since: \"0.4.0\"})` \u2014 to get only the releases\nafter that version; the absorb-release prompt is the flow that applies them to\na project once and records the version so the history is not read again.\n\n**When this topic and a tool's own schema disagree, believe the schema.** It is\nrefreshed at each release and a build in between can be ahead of it.\n\n**The panel is versioned separately from the tools, and it does not update\nitself.** It loads at After Effects launch and only at launch, so after any\nupgrade the tools can be newer than the code answering them. When that happens a\ncall returns a remediation message rather than a confusing `Unknown op` \u2014 relay\nit. The distinction worth reading carefully: if it says the panel is *installed*\nbut the running one is older, running `setup_panel` again changes nothing and\nonly quitting and reopening After Effects will.\n\n## 0.5.0\n\nThe release where the guidance split into a core and references, the journal\nstarted coming to you instead of you going to it, and three more things After\nEffects does silently \u2014 a batch's progress no client ever saw, a broken\nexpression reported as ok, a justification that did not land \u2014 became\nvisible. Two results changed shape; those are first, because a caller reading\nthe old shape gets nothing rather than an error.\n\n### Two results changed shape\n\n- **`find_layers` returns `{matches, count, compsSearched, included}`, and a\n  match is id, index, name, sourceType, compId and compName unless `include`\n  asks for more.** It used to answer a bare array of full layer summaries \u2014\n  flags, timing, parent, on every match \u2014 with no way to bound it, so nine name\n  matches cost about two thousand tokens, re-sent on every later request.\n  `include` takes the `list_layers` section names (`flags`, `timing`,\n  `parent`); unlike `list_layers`, omitting it means the bounded record, not\n  everything, and the result echoes `included`. A caller that read the old\n  array reads `matches` now.\n  supersedes: find_layers cannot be bounded\n  supersedes: find_layers returns an array of layer summaries\n- **`place_audio_cues` results carry one small entry per cue \u2014 `layerId`,\n  `name`, `time`, plus what an option changed \u2014 and `dryRun` answers counts,\n  `wouldImport`, `wouldReuse` and the failing cues only.** The per-cue\n  `levelDb`, `label`, `index` and `itemId` were echoes of the request, and a\n  seven-cue dry run that found nothing wrong cost about 1,500 tokens of them.\n  Read a level off the layer, not out of the result.\n  supersedes: place_audio_cues echoes the levelDb written for every cue\n  supersedes: dryRun on place_audio_cues returns the resolved cue list\n\n### Three silences, now reported\n\n- **`run_batch` over 500 ops returns its `jobId` before the first chunk runs,\n  and progress is delivered on `await_job` \u2014 send that call with a progress\n  token and `notifications/progress` arrive while it waits.** Nothing can ride\n  on the `run_batch` call itself: its response is already back, and a\n  notification sent on a request's token after its response is one every\n  spec-compliant client has already stopped listening for \u2014 which is where\n  every progress message for a long batch went before 0.5.0, seen by no real\n  client. `get_job` polls the same state without a token.\n  supersedes: run_batch progress arrives on the run_batch call\n  supersedes: pass a progressToken on run_batch to see its progress\n- **`set_expression` throws when After Effects cannot evaluate the expression,\n  and `get_expression` returns `expressionError`.** Assigning an expression\n  succeeds whatever the text says, and AE's only report is a warning banner in\n  its interface; the tool now evaluates the property after the write and fails\n  with AE's message and the property path. The expression stays written \u2014 fix\n  it and call again, or `clear_expression`. `toggle_expression({enabled:\n  true})` verifies the same way. A non-empty `expressionError` means the\n  property is not being driven by that expression, whatever `enabled` says.\n  supersedes: set_expression reports success for a broken expression\n  supersedes: ask the user to check the property for an expression warning banner\n- **`set_text` and `create_text_layer` read the justification back after every\n  write, re-assert it once if it moved, and throw naming expected and actual\n  if it still disagrees.** On 26.3 a `set_text` that changed only `text` has\n  re-centred a left-aligned layer. Both results carry `justification` as a\n  name and `justificationReasserted`; a failing `create_text_layer` removes\n  the layer it made, so nothing is left without an id. An unknown\n  justification name is refused rather than ignored.\n  supersedes: set_text leaves justification alone when you do not pass it\n  supersedes: verify alignment by sourceRect after every set_text\n\n### Deleting a comp, and what it leaves behind\n\n- **`delete_comp` reports `unusedSolidsLeft`, and `purgeUnusedSolids: true`\n  removes the comp's own now-unused solids in the same undo step.** A solid's\n  source is a footage item in the Solids folder, and deleting the comp only\n  ever removed the layer, so a session that built and discarded comps left\n  hundreds behind. Only the deleted comp's own solids are considered; one\n  another comp still uses is kept and reported in `keptSolids` with that comp.\n  supersedes: delete_comp removes a comp and its solids\n  supersedes: sweep the Solids folder by hand after deleting comps\n- **`purge_unused_footage` sweeps the project: solids only by default,\n  `solidsOnly: false` for every unused footage item, `folderId` to scope it,\n  `dryRun: true` to list `wouldRemove` without an undo step.** Never a comp or\n  a folder \u2014 a nested comp nothing uses is not footage.\n  supersedes: remove unused footage with run_jsx\n\n### Sound\n\n- **`place_audio_cues` takes `loop`, `fadeIn`/`fadeOut` and `stretch` per cue,\n  and `fadeFloorDb` per call.** `loop: true` time-remaps with a wrap-around\n  expression, keeps AE's two default keys and re-asserts the out point; fades\n  keyframe Audio Levels at the layer's real in and out between the floor\n  (default `-48`) and the cue's level, and a fade that does not fit is refused\n  by cue index; `stretch` is a percentage with the start time and trims\n  re-asserted after it. A stretched loop bakes the factor into its expression,\n  so a later hand change to stretch leaves the loop at the old rate. All of it\n  is validated before anything is created and rolled back with the rest.\n  supersedes: loop a bed with run_jsx and timeRemap after place_audio_cues\n  supersedes: fade audio in run_jsx after placing the cues\n\n### The journal comes to you\n\n- **A failed call ends with `Known from earlier sessions: <scope:id> \u2014 <title>`\n  for up to three entries matching its tool and error text, and the\n  `list_known_issues({id})` call that opens the first.** Nobody reads the\n  journal ahead of time any more; the pointer arrives with the failure, and a\n  match moves the entry's `lastSeen`.\n  supersedes: read list_known_issues before nontrivial work\n  supersedes: check list_known_issues before guessing\n- **`log_issue` takes `errorText` and `kind`, and the same tool with the same\n  error text extends the existing entry even under a new title** \u2014 the result\n  says `mergedBy: \"errorText\"` and keeps the existing title. `kind:\n  \"ae-quirk\"` marks a permanent After Effects behaviour; the default\n  `tool-bug` is presumed fixed once last seen on an older server. Entries\n  record `firstVersion` and `lastVersion`.\n  supersedes: call list_known_issues first so you reuse the title when logging\n- **Entries archive themselves \u2014 unseen for 30 days, or a `tool-bug` last seen\n  on an older server \u2014 and `archive_issue({id, reason})` retires one by\n  hand.** Archived entries are hidden from the index and counted in\n  `archivedCount`; `includeArchived: true` lists them, a read by `id` always\n  works, and a fresh `log_issue` reopens one with `reopened: true`. Index\n  lines carry `kind`, `lastSeen` and `lastVersion` and no summary sentence,\n  sorted by tool match and then most recently seen.\n  supersedes: the journal only grows, entries are never removed\n- **The report flow checks the tracker before drafting.** An entry a closed\n  report already covers is archived with that URL; one an open report covers\n  is marked reported. Bodies go through a file, and \"all of them\" is one\n  approval.\n\n### Reading the history once\n\n- **`ae_guide({topic: \"whats-new\", since: \"<version>\"})` returns only the\n  releases after that version, opening with the server's own version**, and\n  this file has a shape a machine can filter: one section per release, every\n  entry leading with the rule as it now stands, `supersedes:` lines under it\n  quoting the old rule. The absorb-release prompt (`/absorb-release` where\n  prompts are commands) applies the delta to a project's notes once and\n  records the version in the `Tools version last absorbed:` line\n  `init_project` writes into AGENTS.md.\n  supersedes: read the whole whats-new guide after every update\n\n### The guidance\n\n- **The `after-effects` topic is a core of what silently produces wrong output\n  on any task, and each subject is its own topic** \u2014 `animation`, `shapes`,\n  `text`, `assembly`, `extendscript-gotchas`, `sound`, `mogrt-and-footage`,\n  `issue-journal`, `whats-new` \u2014 twelve `ae_guide` topics in all with\n  `style-guide` and `ae-setup`. In Claude Code and claude.ai the references\n  are the files in the `after-effects` skill's `references/` folder, opened\n  only when the core points at them. Keyframes, easing and rigging are in\n  `animation`; raw scripting, with the ease-arity table, in\n  `extendscript-gotchas` and nowhere else.\n  supersedes: the after-effects skill covers keyframes text and shapes in one file\n  supersedes: the ease arity table is in the main guide\n- **Four more After Effects facts, measured on 26.3, in `extendscript-gotchas`:**\n  removing the last Time Remap key hides the property, so edit AE's two\n  default keys in place or put an expression over them, and re-assert\n  `outPoint` after enabling remapping; `TextDocument.justification` written\n  from a script lands as RIGHT when handed CENTER, so set it through\n  `set_text`; `OutputModule.setSettings` rejects Format, Channels, Depth and\n  Color as read-only, so build an output template in the UI and apply it by\n  name; and the ease arity is not derivable from a value's dimension, so\n  never size a `KeyframeEase` array by hand.\n  supersedes: clear the Time Remap keys before adding your own\n  supersedes: set justification on the TextDocument from run_jsx\n  supersedes: set the output module codec with setSettings from run_jsx\n- **The references carry the craft rules a project would otherwise keep in\n  its own notes** (issue #103). `extendscript-gotchas`: a `.value` read at\n  the playhead, a `setValue` that throws with the value applied on a comp not\n  in a viewer, effects addressed by a name that is not unique and references\n  that go stale when one is added, a track matte that switches its matte's\n  video off, `replaceSource` keeping the old timing, `item.typeName`, Time\n  Remap keys added before the defaults are removed. `animation`: a held pose\n  as a hold key, a waypoint that must not stop, parenting at rest and before\n  the pop with the parent-space arithmetic, a mirrored parent mirroring its\n  text, expression text built from numbers, a shake as an expression over\n  keys. `assembly`: a precomp clamped at its source, reversing with time\n  remap, controls shared across every instance, a resized comp shifting what\n  nests it, collapse transformations and motion blur across a nesting,\n  replacing a nested comp, and verifying an assembly, a small detail, a\n  doubtful tile and a cut. `sound`: peak for a one-shot and RMS for a bed\n  with the onset on the beat, a trim clamped at the file's end, a bed that\n  follows a move, a float WAV that will not place. `shapes`: one fill per\n  group, the layer stack built back-to-front, a group's pivot, seams between\n  shapes, centring a repeated run.\n\n### Connecting, and staying connected\n\n- **The server follows the panel's port.** A call refused on the port the\n  server remembered makes it look again \u2014 7777 first, then the port file \u2014\n  switch to whichever answers as the panel, and re-send the call once. Only a\n  refused connection triggers this; a timed-out call reached After Effects and\n  is never re-sent (issue #92). `AE_MCP_PORT` is a hard pin: with it set, no\n  other port is ever tried.\n  supersedes: reconnect the MCP server when ops fail on a port check_setup does not report\n- **`check_setup` reports the port that actually answers**, flags a stale\n  port file, and carries a new `portAgreement` check. When calls go to one\n  port and the panel answers on another, its advice is to retry or reconnect\n  the MCP server. It never tells you to restart After Effects for that.\n  supersedes: cannot reach the panel means nothing is listening so restart After Effects\n- **The panel waits instead of moving when an older copy of itself holds\n  7777.** It says so in its own window, names the holder, and takes the port\n  over the moment that copy exits, with no restart. Two After Effects\n  instances on one machine opt back into walking with `\"allowPortWalk\": true`\n  in `~/.engineroom-ae-mcp/config.json`; the same file's `\"port\"` moves the\n  panel. The port file only ever names a port that was really bound and is\n  removed when the panel unloads.\n  supersedes: the panel walks up to the next free port when 7777 is taken\n- **A panel that never loads on Windows gets a diagnosis, not a restart\n  loop.** `check_setup` reads CEP's own log and, when CEP refused the panel's\n  signature \u2014 an Adobe CEP 12 bug that ignores PlayerDebugMode \u2014 reports\n  `panelSignature` with the steps to self-sign the installed panel with\n  Adobe's ZXPSignCmd (issue #91). With no log yet, it gives the one command\n  that turns CEP logging on. `setup_panel` now turns that logging on itself\n  where it was never set, warns when it is about to replace a self-signed\n  panel (`signedInstallOverwritten`, since the fresh copy needs signing\n  again), and reports a signed panel as up to date rather than partial.\n  supersedes: check_setup all green but the panel never loads means restart After Effects again\n- **`check_setup` under an `AE_MCP_PORT` pin still asks 7777 and the port\n  file, and a pinned wrong port is reported as the pin, not as a dead panel.**\n  The pin decides where ops go and is never walked past; the diagnosis says so,\n  names the port the panel is really answering on, and tells you to change or\n  unset `AE_MCP_PORT` and reconnect the MCP server \u2014 never to restart After\n  Effects. A refused op under a pin says the same in its own message.\n\n### Found by the live pass\n\n- **`init_project` refuses the home directory and the filesystem root however\n  they were arrived at, an explicit `dir` included.** Before this only the\n  working-directory fallback was guarded, so `dir: \"~\"` resolved by a client,\n  or `dir: \"/\"`, scaffolded `AGENTS.md` and a `renders/` folder into a home\n  directory and reported success.\n- **`set_house_style` writes `house-style.md` with Unix line endings.**\n  ExtendScript's default on macOS turned every line break into a bare carriage\n  return: the tools read the file back correctly, so the round trip looked\n  fine, but a designer opening the file in an editor saw one long line.\n\n## 0.4.0\n\nThe release where verifying a change stopped meaning reading the whole thing\nback \u2014 and where a live pass against After Effects 2026 found four things this\nserver had been claiming that were never true. Those are first, because an agent\nthat learned the old story will otherwise repeat it to a user.\n\n### Four things that were never true, and are now fixed\n\n- **`run_batch` is one undo step up to 500 ops; over 500 it is one step per\n  chunk of 25, and `singleUndo: true` makes it one step up to 2000.** The\n  one-step guarantee it shipped with before 0.4.0 did not exist on either path:\n  After Effects discards an undo group opened in one script call and closed in\n  another, so a 600-op batch landed as about six hundred separate steps while\n  reporting one. Now up to 500 ops is genuinely one step; over 500 is one step\n  per chunk of 25 \u2014 around 24 for 600 ops \u2014 with the measured count in\n  `undoSteps` and a `note` saying it in words. `singleUndo: true` runs the batch\n  in a single blocking call, which freezes AE's interface for the duration and\n  reports no progress. Read `undoSteps` before you tell anyone how to undo the\n  work.\n  supersedes: run_batch is one undo step\n  supersedes: a long run_batch is one undo step\n- **`transactional: true` stops at the first failure, rolls nothing back, and\n  says so: `rolledBack: false` with the stop point named.** It never rolled\n  anything back \u2014 it fired one menu-command Undo, and menu commands silently do\n  nothing over this bridge; one Undo is one step, not a batch, in any case. The\n  ops before the failure stay applied. Use `diff: true` to see what landed.\n  supersedes: transactional: true rolls the batch back on failure\n- **`reorder_layer` works, and takes exactly one of `beforeLayerId`,\n  `afterLayerId` or `toIndex`.** Every call it served before 0.4.0 threw\n  `parent is not an INDEXED_GROUP`, because it used a shape-node method on a\n  layer. Prefer the id forms, because this is the op that invalidates indexes;\n  `toIndex` means the index the layer **ends up at**.\n  supersedes: reorder_layer is broken, use run_jsx\n  supersedes: reorder_layer throws parent is not an INDEXED_GROUP\n- **`downsample: 1` is full resolution, whatever the viewer's Resolution\n  dropdown is set to.** Before 0.4.0 factor 1 skipped setting the comp's\n  resolution at all, so it inherited the viewer's setting \u2014 on a comp a designer\n  had left at Quarter, `downsample: 1` returned a quarter-size frame and\n  `downsample: 2` returned one four times larger. The response was honest about\n  the dimensions; the picture was not the one asked for. Factor 1 is now set\n  explicitly like any other and restored afterwards.\n  supersedes: downsample: 1 means the viewer's resolution\n  supersedes: set the viewer to Full before a downsample: 1 screenshot\n\n### Two calls changed under you\n\n- **`create_shape_layer` spawns at `[0,0]`**, with the anchor at `[0,0]`, so the\n  layer's coordinate space *is* the comp's and every vertex, rect position and\n  path you add afterwards is in comp pixels. After Effects' own spawn point is\n  the comp centre, which silently offsets a drawing authored in comp coordinates\n  by half a frame \u2014 easy to miss on a downsampled screenshot. `position:\n  \"center\"` restores AE's behaviour, and any `[x,y]` places the origin yourself.\n  The result echoes what it ended up with.\n  supersedes: a new shape layer spawns at the comp centre\n  supersedes: shape paths are offset by half a frame, subtract the comp centre\n- **`get_house_style` returns a digest, not the document; `detail: \"full\"`\n  returns the document.** The digest is a few hundred tokens: palette as named\n  hexes, type, motion, layout, and a note naming anything it could not summarise.\n  You need the full document before `set_house_style`, which replaces the file\n  rather than patching it. An unstructured guide comes back `structured: false`\n  with its opening text, which is an honest \"I could not read this as a spec\"\n  rather than an empty answer.\n  supersedes: do not call get_house_style, read the digest in these notes instead\n  supersedes: get_house_style returns the whole style guide\n\n### Verify with a diff instead of a second read\n\n- **`snapshot_comp` and `diff_comp` fingerprint a comp and report what moved.**\n  Fingerprint before a write, then ask: layers added, removed, renamed,\n  retimed, re-parented, keyframe counts, expressions and effects gained or lost\n  \u2014 and a count of the layers that did not move. Tens of tokens where two full\n  reads were thousands. It does **not** record property values, expression\n  text, effect parameters, masks or shape contents, so `changeCount: 0` means\n  none of the recorded fields moved, not that the comp is identical.\n  supersedes: verify a write by reading the comp back with list_layers and get_layer_full\n- **`diff: true` on `run_jsx` and `run_batch` does the same inside the call**,\n  so there is no window between the write and the fingerprint \u2014 and on a\n  failure the diff rides on the error, which is how you find where a\n  half-applied script stopped.\n\n### Screenshots\n\n- **`screenshot_frame` takes `times` (2\u20136) and returns one tiled contact\n  sheet**, each tile labelled with its own time, held to roughly the pixel\n  budget of a single frame. Judging motion is one call now, not three: one\n  image in your context instead of three, and one render request instead of\n  three back-to-back ones, which is the pattern that provoked stale frames.\n  `time` and `times` are mutually exclusive; there is no `times` on\n  `screenshot_layer`.\n  supersedes: screenshot each time separately to judge motion\n- **Three screenshot failures, each with its own remedy.** `Stale frame` (AE\n  served an earlier render \u2014 wait, retry higher), `Corrupt frame` (the file is\n  not a whole PNG; not a timeout \u2014 retry at downsample 6\u20138 or shoot the precomps\n  separately), `Render timed out` (still rendering \u2014 wait before retrying, or a\n  retry queues behind it). A frame that is genuinely all-transparent is still\n  `empty: true` with no image. On a sheet, one bad tile is drawn as a marked\n  block and named in `warning`; the rest of the sheet is good.\n  supersedes: truncated PNG from screenshot_frame means retry it\n\n### run_jsx\n\n- **A `run_jsx` failure names the line of *your* script and prints its text**,\n  and says so honestly when the number cannot be mapped rather than guessing.\n  This was claimed once before it was true: until the 0.4.0 live pass every\n  error said line 1 and printed line 1's text, with the real number only in the\n  parenthetical after it, because AE reports `Error.start`/`Error.end` as `0`\n  on every error rather than as the character offsets its documentation\n  describes.\n  supersedes: run_jsx line numbers are wrong, count from the wrapper\n  supersedes: run_jsx reports line 1 for every error\n- **`diff: true` on `run_jsx` reaches After Effects.** The server was building\n  a fresh argument object and dropping every field it did not enumerate, so the\n  flag was discarded before the call left. The same flag on `run_batch` always\n  worked, which is what hid it.\n  supersedes: diff: true on run_jsx does nothing\n- **`scriptPath` and `libraries` keep a long script and its shared helpers out\n  of the conversation entirely.** Libraries are inlined ahead of the script in\n  the same scope, so their functions are callable from it; they are\n  re-evaluated on every call, so keep them to declarations rather than to work.\n- **Helpers are in scope**, each wrapping a trap: `compById`, `layerById`,\n  `walkProperty`, `addKeys`, `ease` (which sizes the KeyframeEase array using\n  the same code `set_temporal_ease` uses, not a copy), `shape` (which lands at\n  `[0,0]`), and `withoutUndoGroup`. The whole `OPS` table is callable too.\n\n### New tools, and one thing you no longer have to get right\n\n- **`duplicate_comp` returns the new comp id**, so you never look for the copy\n  by name. Shallow by default like AE's own Duplicate \u2014 the copy's precomp\n  layers point at the *same* nested comps \u2014 with `deep: true` for a real\n  variant.\n  supersedes: duplicate a comp with run_jsx and find the copy by name\n- **`place_audio_cues` scores a scene in one call**: a cue list becomes one\n  audio layer each, imported once per file, named, trimmed, levelled in dB, in a\n  single undo step, all-or-nothing, with a `dryRun`.\n  supersedes: place audio with run_jsx, one layer at a time\n- **`set_temporal_ease` and `add_keyframe` size the ease array themselves.**\n  Pass one `{influence, speed}` pair per side; the count that worked comes back\n  as `easeDimensions`. The bare `parameter 2` failure is no longer yours to\n  avoid.\n  supersedes: set_temporal_ease fails with parameter 2, pass the right number of KeyframeEase objects by hand\n  supersedes: set_temporal_ease fails on Scale, use run_jsx\n- **`export_mogrt` refuses an empty Essential Graphics panel up front**, naming\n  the controller count. It used to attempt the export and then blame a modal\n  dialog, which under the default dialog suppression is the one cause ruled out\n  by construction. When an export does fail now, the message says what was\n  checked and \u2014 if dialogs were suppressed \u2014 that the cause is genuinely\n  unknown, because AE answers with a bare boolean and has no way to say why.\n  supersedes: export_mogrt fails with a modal dialog when the comp has no Essential Graphics controllers\n\n### Underneath\n\n- **Writes are serialized, one at a time, for the whole session**, so two\n  writes issued together run in the order you issued them and a long\n  `run_batch` holds the lock until its last chunk lands \u2014 nothing else drops\n  into the middle of work the user asked for as one thing. A call that waited\n  says `queuedBehind` and `waitedMs`. Reads are never queued. There is a new\n  diagnosis to tell apart from a bridge timeout: a call *dropped while waiting\n  for the write queue* never reached After Effects, so re-sending it is safe \u2014\n  which is the opposite of what a timeout means.\n  supersedes: never issue two writes in the same turn, the order is not guaranteed\n- **The issue journal has two scopes.** `project` is this project's notes;\n  `user` travels with the person across every project, so log tool and After\n  Effects behaviour there. Ids are unique only within a journal, so open an\n  entry with the qualified form the listing shows (`user:\u2026`).\n- **The guidance lives in `ae_guide` and the skill, not in what the server sends\n  every session.** What the server sends is a short pointer rather than a\n  summary, because it was resident in every request the user ever made. The\n  narrative is `ae_guide({topic: \"after-effects\"})`, with `extendscript-gotchas`\n  behind it for raw `run_jsx` and this topic for changes. In Claude Code and\n  claude.ai the same text is the `after-effects` skill and the files in its\n  `references/` folder \u2014 load one carrier, not both.\n- **Rigging is written down**, in the `animation` topic: opacity does not propagate\n  through parenting, and a camera null is parented to while it is still at\n  identity.\n\n## 0.3.1\n\n- **`get_layer_full` omits `ADBE Vector Materials Group` unless\n  `shapeMaterials: true`.** That is the 48-property 3D extrusion model AE hangs\n  off every vector group, which means nothing on a 2D shape layer. It was around\n  three quarters of the bytes of a shape read: one 68px circle cost 4,400\n  tokens, of which the geometry was about 40. `materialsOmitted` counts what was\n  dropped; `shapeMaterials: true` brings it back for a genuinely extruded shape.\n  A group Transform still at its creation values collapses to `atDefaults:\n  true` the same way.\n  supersedes: shape reads are huge, avoid get_layer_full on shape layers\n- **`shapeDetail: \"compact\"` returns one indented line per group** instead of\n  the JSON tree \u2014 every name the write tools address a node by, with `[3 keys]`\n  or `[expr]` marking the animated properties. Measured end to end on one real\n  layer: 13,369 characters before 0.3.1, 3,052 once the materials block went,\n  643 compact. Reach for `\"full\"` only when you need exact values or keyframe\n  indices.\n- **`run_jsx` never answers a bare `null`.** A script whose last statement is a\n  bare expression completes and returns nothing \u2014 `\"ping\";` does not return\n  `\"ping\"` \u2014 and that used to be indistinguishable on the wire from a script\n  that never ran. It now comes back as `{ok: true, returned: null, undoGroup,\n  note}`, which means *it ran to completion*. Do not re-run it: nothing rolls\n  back, so a second run of a script that duplicated a layer or wrote keyframes\n  does all of it twice. A returned value still comes back bare, falsy ones\n  included.\n  supersedes: a null from run_jsx means the script did not run, run it again\n\n## 0.3.0\n\n- **`list_comps`, `list_layers` and `get_layer_full` take `include` to name the\n  sections you want**, plus `maxKeyframes` and `shapeDepth` on the deep read.\n  Omit them all and you get everything, exactly as before. Anything left out is\n  named and counted in the response (`included`, `keyframesOmitted`,\n  `childrenOmitted`), so a short answer never passes for a complete one. This\n  matters more than it sounds: a tool result is re-sent to you on every later\n  request for the rest of the session, so one unbounded read is paid for many\n  times.\n  supersedes: get_layer_full returns everything, there is no way to bound it\n- **Screenshots downsample themselves.** Omit `downsample` and it is derived\n  from the comp \u2014 2 at 1080p, 3 at 4K, aiming at a long edge near 1280px. The\n  result reports the size actually returned. Pass `downsample: 1` only when you\n  genuinely need full resolution.\n  supersedes: always pass downsample on screenshot_frame or it returns full resolution\n- **A stale frame is an error, not a picture.** AE sometimes re-serves a frame\n  it rendered for an unrelated request, at a different time and even at a\n  different downsample factor, with nothing in the response to say so. Those\n  are refused with `Stale frame` naming the request whose pixels came back.\n  Wait a few seconds and retry at a higher `downsample`.\n- **A fully transparent frame comes back as `{empty: true, reason}`** with no\n  image. That is a fact about the composition \u2014 wrong time, layer outside its\n  in/out points, disabled, zero opacity \u2014 not something to retry.\n- **`import_footage` and `create_footage_layer` bring footage in**, and the\n  import refuses an SVG whose `viewBox` asks for one aspect ratio and imports at\n  another: that is a real AE bug which renders as nothing at all, with no error\n  at any stage.\n  supersedes: import footage with run_jsx and importFile\n- **`export_mogrt` exports a Motion Graphics template and suppresses the modal\n  dialogs** that otherwise freeze this whole connection until someone clicks\n  them in After Effects. Never drive `exportAsMotionGraphicsTemplate` from\n  `run_jsx`.\n  supersedes: export a mogrt with run_jsx and exportAsMotionGraphicsTemplate\n- **Text alignment is justification**, not a measured anchor offset, so it\n  stays correct when the text changes later. Tracking is set explicitly rather\n  than inherited from the user's Character panel.\n  supersedes: anchorAlign moves the anchor point, re-align text after every edit"
   }
 ];
 var PROMPTS = [
+  {
+    name: "absorb-release",
+    description: "After the After Effects tools update \u2014 read what changed since this project last caught up, fix the notes in this folder the update made stale, retire journal entries whose fix has shipped, and record the version so the history is not read again",
+    argumentHint: "[the version this project last absorbed, if its docs do not say]",
+    body: '# Absorb a tools update\n\nThe After Effects tools have updated, or the user thinks they have. A release\nchanges what the tools do, and what earlier sessions wrote down about them in\nthis project \u2014 workarounds in AGENTS.md or CLAUDE.md, entries in the issue\njournal \u2014 does not update itself. This flow reads the delta once, corrects those\nnotes, and records the version so no later session reads the history again.\n\n`$ARGUMENTS` is the version the project last absorbed, if the user typed one.\n\n## When to run this\n\nAt the start of a session, compare two versions:\n\n- **Recorded**: the line `Tools version last absorbed: <version>` in the\n  project\'s docs. `init_project` writes it into AGENTS.md.\n- **Running**: the server\'s own version. `list_known_issues` returns it as\n  `serverVersion`, and every `ae_guide({topic: "whats-new"})` answer opens with\n  it.\n\nRunning newer than recorded, or no recorded line at all, is the cue. Two things\nupdate separately, so there can be two versions to look at: the MCP server (via\nnpx, the standalone binary, or the Claude Desktop bundle) and, in Claude Code,\nthe plugin that carries the skills and this command, whose version is in its\n`.claude-plugin/plugin.json`. The **server\'s** version is the one this flow\nrecords, because the server is what answers tool calls and what serves the\nwhats-new topic. If the plugin is ahead of the server, the skill text may\ndescribe tools the server does not have yet \u2014 say so, and suggest updating the\nserver rather than the notes.\n\n## 1. Find the recorded version\n\nLook for `Tools version last absorbed:` in AGENTS.md, then CLAUDE.md,\n`.cursor/rules/`, `.windsurfrules`, `.github/copilot-instructions.md` and any\nnotes under `.ae-mcp/`. `$ARGUMENTS` overrides whatever is found.\n\nNothing recorded and nothing typed: ask whether these tools have been used in\nthis project before. If they have, treat it as never absorbed and read the whole\nhistory \u2014 one long read, once. If the project is new, there is nothing to\nabsorb: go to step 5 and just record the version.\n\n## 2. Read the delta\n\nCall `ae_guide({topic: "whats-new", since: "<recorded>"})`. The first line\nnames the server version \u2014 keep it for step 5. If it says nothing is newer, tell\nthe user they are up to date, make sure the recorded line exists (step 5), and\nstop.\n\nOtherwise, every bullet leads with the rule as it now stands, and a\n`supersedes:` line under it quotes the old rule in the words a project\'s notes\nwould have used. Those lines are what the next step searches for.\n\n## 3. Correct the project\'s own notes\n\nFor every `supersedes:` line, search the files from step 1 for the old rule \u2014\nthe phrase, and its key words, because a note will rarely match word for word.\n`house-style.md` is about the look, not the tools; leave it alone.\n\nFor each hit, show the user the note as it stands, the rule that replaces it,\nand the edit you propose: a rewrite when the note still says something true, a\ndeletion when it only described a bug that is now fixed. A note that mentions a\nworkaround also teaches the workaround, so prefer deleting to rephrasing. These\nare their notes \u2014 collect the proposed edits, get one yes, then make them.\nNever edit silently.\n\nNo hits: say so in one line and move on.\n\n## 4. Retire journal entries whose fix has shipped\n\nCall `list_known_issues({status: "reported"})`. A reported entry carries the URL\nof the issue that was filed. If `gh` is installed and signed in (`gh auth\nstatus`), check each one:\n\n```bash\ngh issue view <number> --repo <repo> --json state,stateReason\n```\n\n- `CLOSED` with `stateReason: COMPLETED` \u2014 the fix shipped. Call\n  `archive_issue({id, reason: "<url> closed"})`, using the scope-qualified id\n  the listing shows (`user:\u2026`, `project:\u2026`).\n- `CLOSED` with `NOT_PLANNED` \u2014 the behaviour is staying, so the workaround is\n  still worth having. Leave it.\n- `OPEN` \u2014 leave it.\n\nNever archive an entry tagged `kind: "ae-quirk"` on the strength of a closed\nissue: those describe After Effects itself, not a tool bug, and a release does\nnot change them.\n\nThen glance at the unreported entries against the delta: an entry whose symptom\na bullet says is fixed can be archived with the release as the reason \u2014 propose\nit, do not assume.\n\nIf `gh` is missing or not signed in, do not install or configure it. List the\nreported entries with their URLs so the user can check them, and leave the\njournal as it is.\n\n## 5. Record the version\n\nWrite `Tools version last absorbed: <server version>` \u2014 the version from the\nfirst line of step 2 \u2014 replacing the existing line, or adding it under a\n`## Tool updates` heading in AGENTS.md when there was none. No AGENTS.md: use\nthe file the project reads (CLAUDE.md, or the rules file found in step 1). No\nproject docs at all \u2014 a Claude Desktop session with no folder, say \u2014 tell the\nuser there is nowhere to write it, suggest `init_project` for when they next\nwant a project folder, and stop.\n\nAfter this the history is not loaded again for this project until the next\nupdate.\n\n## 6. Say what happened\n\nOne short paragraph, in plain language: which version, how many notes were\ncorrected, which journal entries were retired. No file paths they did not ask\nabout, and no talk of "supersedes lines" \u2014 that is machinery.'
+  },
   {
     name: "create-style-guide",
     description: "Capture or update the look of this project \u2014 palette, type, motion and layout \u2014 into the style guide that shapes everything built afterwards",
@@ -1963,7 +3360,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 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.'
+    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 checks and the draft below need the symptom,\nerror text and workaround, 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. Remember the\n  answer: if they said "all of them", step 4 takes one approval for the lot, not\n  one per entry.\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. Check whether the maintainers already know\n\nBefore drafting anything, look at what has already been sent to them \u2014 sending\nthe same problem twice wastes their time and the user\'s. `repo` came back from\nstep 1.\n\n```bash\ngh issue list --repo <repo> --state all --limit 200 --json number,title,state,url\n```\n\nMatch each chosen entry against that list by the tool it names and by its error\ntext: a title that names the same tool and the same failure, or quotes the same\nerror, is the same problem however it is worded. When a title alone does not\nsettle it, read the body:\n\n```bash\ngh issue view <number> --repo <repo> --json title,body,state,url\n```\n\nFor every entry that matches something:\n\n- **The match is closed** \u2014 it has already been dealt with. Do not send it again.\n  Call `archive_issue` with the entry\'s scope-qualified id and the existing link\n  as the reason (`"already closed upstream: <url>"`), so it leaves the list and no\n  later session offers it. Tell the user in one plain sentence that this one was\n  already fixed or already handled, with the link; if the fix came in a newer\n  version than `serverVersion`, say that updating is how to get it.\n- **The match is open** \u2014 it is known and still being looked at. Do not send a\n  second copy. Call `mark_issue_reported` with the entry\'s scope-qualified id and\n  the existing link, and tell the user it is already on the maintainers\' list,\n  with the link. If they have something to add, it belongs on that one.\n\nOnly the entries with no match go on to step 3. If none are left, say so and\nstop.\n\nIf `gh` is missing or not signed in, skip this step, say so in one line, and\ncarry on \u2014 step 5 has the fallback for sending.\n\n## 3. 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## 4. 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\nIf they chose "all of them" in step 1, show every draft together, once, and take\none yes for the lot. Do not ask again for each one.\n\n## 5. Send it\n\nTry `gh` first. Write the body to a temporary file and pass the file \u2014 a\nmulti-line markdown body with backticks and quotes does not survive being quoted\non a command line:\n\n```bash\ngh issue create --repo <repo> --title "<title>" --body-file <temp-file>\n```\n\nOne call per draft; remove the temporary file afterwards.\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## 6. 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. Use the same\nscope-qualified id the listing gave you (`user:\u2026`, `project:\u2026`): the two\njournals can hold the same slug, reporting one says nothing about the other, and\nan unqualified id leaves which one moved to chance. Then tell them where it went,\nin 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);
@@ -1973,40 +3370,60 @@ 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, 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.";
+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\nRead the guidance before you build. `ae_guide({topic: "after-effects"})` is the\ncore \u2014 orienting, bounded reads, verifying a write, screenshots, the bridge\nfailures \u2014 and points at one topic per subject (shapes, text, animation, raw\nscripting, sound, \u2026). In Claude Code and claude.ai the `after-effects` skill is\nthe same text \u2014 load one carrier, not both.\nTopics: ae-setup, after-effects, animation, assembly, extendscript-gotchas, issue-journal, mogrt-and-footage, shapes, sound, style-guide, text, whats-new.\n\nThree habits that matter before that call returns:\n\n- Identify by `id`, never by `index` \u2014 a layer\'s index shifts on every insert.\n- Bound your reads (`include`, `shapeDetail: "compact"`) and treat screenshots as\n  one-off diagnostics rather than a feedback loop. Every tool result is re-sent\n  to you on every later request in the session.\n- If a tool reports it cannot reach After Effects, call `check_setup` and relay\n  its `nextSteps` verbatim; do not diagnose CEP by hand.';
 
 // src/issues/journal.ts
-import fs7 from "node:fs";
-import os4 from "node:os";
-import path8 from "node:path";
+import fs9 from "node:fs";
+import os5 from "node:os";
+import path10 from "node:path";
 var REPO = "Engine-Room-Games/after-effects-mcp";
 var NEW_ISSUE_URL = `https://github.com/${REPO}/issues/new`;
+var ARCHIVE_AFTER_DAYS = 30;
 var SECTION_SYMPTOM = "What went wrong";
 var SECTION_CAUSE = "Why";
 var SECTION_WORKAROUND = "What worked";
+var ERROR_TEXT_CHARS = 400;
+var ISSUE_KINDS = ["tool-bug", "ae-quirk"];
 function journalRoot() {
-  const override = process.env.AE_MCP_HOME?.trim();
-  if (override && override.length > 0) return { dir: override, scope: "project" };
+  const override = journalOverride();
+  if (override) return { dir: override, scope: "project" };
   const cwd = process.cwd();
-  const unusable = cwd === path8.parse(cwd).root || cwd === os4.homedir();
+  const unusable = cwd === path10.parse(cwd).root || cwd === os5.homedir();
   if (!unusable) {
     try {
-      fs7.accessSync(cwd, fs7.constants.W_OK);
-      return { dir: path8.join(cwd, ".ae-mcp"), scope: "project" };
+      fs9.accessSync(cwd, fs9.constants.W_OK);
+      return { dir: path10.join(cwd, ".ae-mcp"), scope: "project" };
     } catch {
     }
   }
-  return { dir: path8.join(os4.homedir(), ".after-effects-mcp"), scope: "home" };
+  return { dir: path10.join(os5.homedir(), ".after-effects-mcp"), scope: "home" };
 }
-function journalDir() {
-  return path8.join(journalRoot().dir, "issues");
+function userJournalRoot() {
+  const override = journalOverride();
+  if (override) return { dir: path10.join(override, "user"), scope: "user" };
+  return { dir: path10.join(os5.homedir(), ".ae-mcp"), scope: "user" };
 }
-function ensureJournalDir() {
-  const { dir } = journalRoot();
-  const issues = path8.join(dir, "issues");
-  fs7.mkdirSync(issues, { recursive: true });
-  const ignore = path8.join(dir, ".gitignore");
-  if (!fs7.existsSync(ignore)) fs7.writeFileSync(ignore, "*\n", "utf8");
+function journalOverride() {
+  const override = process.env.AE_MCP_HOME?.trim();
+  return override && override.length > 0 ? override : null;
+}
+function journals() {
+  const project = journalRoot();
+  const user = userJournalRoot();
+  if (path10.resolve(project.dir) === path10.resolve(user.dir)) return [project];
+  return [project, user];
+}
+function issuesDir(journal) {
+  return path10.join(journal.dir, "issues");
+}
+function journalFor(scope) {
+  return scope === "user" ? userJournalRoot() : journalRoot();
+}
+function ensureJournalDir(journal) {
+  const issues = issuesDir(journal);
+  fs9.mkdirSync(issues, { recursive: true });
+  const ignore = path10.join(journal.dir, ".gitignore");
+  if (!fs9.existsSync(ignore)) fs9.writeFileSync(ignore, "*\n", "utf8");
   return issues;
 }
 function slugify(text) {
@@ -2019,10 +3436,16 @@ function today() {
 function oneLine(text) {
   return text.replace(/\s+/g, " ").trim();
 }
-function entryPath(id) {
-  const dir = path8.resolve(journalDir());
-  const file = path8.resolve(dir, `${id}.md`);
-  if (path8.dirname(file) !== dir) throw new Error(`Invalid issue id: ${id}`);
+function clipErrorText(text) {
+  if (!text) return void 0;
+  const line = oneLine(stripDecorations(text));
+  if (line.length === 0) return void 0;
+  return line.length > ERROR_TEXT_CHARS ? line.slice(0, ERROR_TEXT_CHARS) : line;
+}
+function entryPath(id, journal) {
+  const dir = path10.resolve(issuesDir(journal));
+  const file = path10.resolve(dir, `${id}.md`);
+  if (path10.dirname(file) !== dir) throw new Error(`Invalid issue id: ${id}`);
   return file;
 }
 function render(entry) {
@@ -2031,18 +3454,22 @@ function render(entry) {
     `id: ${entry.id}`,
     `title: ${oneLine(entry.title)}`,
     `tools: ${entry.tools.join(", ")}`,
+    `kind: ${entry.kind}`,
+    `errorText: ${entry.errorText ?? ""}`,
     `firstSeen: ${entry.firstSeen}`,
     `lastSeen: ${entry.lastSeen}`,
+    `firstVersion: ${entry.firstVersion ?? ""}`,
+    `lastVersion: ${entry.lastVersion ?? ""}`,
     `occurrences: ${entry.occurrences}`,
     `reported: ${entry.reported}`,
-    `issueUrl: ${entry.issueUrl ?? ""}`,
-    "---",
-    "",
-    `## ${SECTION_SYMPTOM}`,
-    "",
-    entry.symptom.trim(),
-    ""
+    `issueUrl: ${entry.issueUrl ?? ""}`
   ];
+  if (entry.archived) {
+    lines.push("archived: true");
+    lines.push(`archivedReason: ${oneLine(entry.archivedReason ?? "")}`);
+    lines.push(`archivedAt: ${entry.archivedAt ?? ""}`);
+  }
+  lines.push("---", "", `## ${SECTION_SYMPTOM}`, "", entry.symptom.trim(), "");
   if (entry.cause && entry.cause.trim().length > 0) {
     lines.push(`## ${SECTION_CAUSE}`, "", entry.cause.trim(), "");
   }
@@ -2063,7 +3490,11 @@ function readSections(body) {
   });
   return sections;
 }
-function parse(text, fallbackId) {
+function parseKind(raw) {
+  const kind = (raw ?? "").trim().toLowerCase();
+  return ISSUE_KINDS.includes(kind) ? kind : "tool-bug";
+}
+function parse(text, fallbackId, scope = "project") {
   const meta = {};
   let body = text;
   const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
@@ -2076,16 +3507,26 @@ function parse(text, fallbackId) {
     body = text.slice(fm[0].length);
   }
   const sections = readSections(body);
+  const nonEmpty = (v) => v && v.length > 0 ? v : void 0;
   const occurrences = Number.parseInt(meta.occurrences ?? "1", 10);
   return {
     id: meta.id || fallbackId,
     title: meta.title || fallbackId.replace(/-/g, " "),
+    // The folder decides this, never the file — see IssueEntry.scope.
+    scope,
     tools: (meta.tools ?? "").split(",").map((t) => t.trim()).filter((t) => t.length > 0),
+    kind: parseKind(meta.kind),
+    errorText: clipErrorText(meta.errorText),
     firstSeen: meta.firstSeen || "",
     lastSeen: meta.lastSeen || meta.firstSeen || "",
+    firstVersion: nonEmpty(meta.firstVersion),
+    lastVersion: nonEmpty(meta.lastVersion),
     occurrences: Number.isFinite(occurrences) && occurrences > 0 ? occurrences : 1,
     reported: meta.reported === "true",
-    issueUrl: meta.issueUrl && meta.issueUrl.length > 0 ? meta.issueUrl : void 0,
+    issueUrl: nonEmpty(meta.issueUrl),
+    archived: meta.archived === "true",
+    archivedReason: nonEmpty(meta.archivedReason),
+    archivedAt: nonEmpty(meta.archivedAt),
     // A hand-edited file with no recognised headings still has its text kept,
     // rather than being silently reduced to an empty entry.
     symptom: sections.get(SECTION_SYMPTOM.toLowerCase()) ?? (sections.size === 0 ? body.trim() : ""),
@@ -2093,135 +3534,673 @@ function parse(text, fallbackId) {
     workaround: sections.get(SECTION_WORKAROUND.toLowerCase()) ?? ""
   };
 }
-function readEntry(file) {
+function readEntry(file, scope) {
   try {
-    return parse(fs7.readFileSync(file, "utf8"), path8.basename(file, ".md"));
+    return parse(fs9.readFileSync(file, "utf8"), path10.basename(file, ".md"), scope);
   } catch {
     return null;
   }
 }
+function writeEntry(entry, journal) {
+  ensureJournalDir(journal);
+  const file = entryPath(entry.id, journal);
+  fs9.writeFileSync(file, render(entry), "utf8");
+  return file;
+}
+function parseVersion(v) {
+  const m = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v);
+  if (!m) return null;
+  return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1;
+  }
+  if (pa.pre && !pb.pre) return -1;
+  if (!pa.pre && pb.pre) return 1;
+  if (pa.pre && pb.pre) return pa.pre < pb.pre ? -1 : pa.pre > pb.pre ? 1 : 0;
+  return 0;
+}
+function daysBetween(from, to) {
+  const a = Date.parse(from);
+  const b = Date.parse(to);
+  if (Number.isNaN(a) || Number.isNaN(b)) return null;
+  return Math.floor((b - a) / 864e5);
+}
+function archiveContext() {
+  return { today: today(), version: packageVersion() };
+}
+function archiveReason(entry, ctx) {
+  if (entry.archived) return entry.archivedReason || "archived by hand";
+  const age = daysBetween(entry.lastSeen, ctx.today);
+  if (age !== null && age >= ARCHIVE_AFTER_DAYS) return `not seen for ${age} days`;
+  if (entry.kind !== "ae-quirk" && entry.lastVersion) {
+    const cmp = compareVersions(entry.lastVersion, ctx.version);
+    if (cmp !== null && cmp < 0) {
+      return `last seen on ${entry.lastVersion}; this server is ${ctx.version}, so it is presumed fixed until seen again`;
+    }
+  }
+  return null;
+}
+function toolsOverlap(a, b) {
+  const set = new Set(a.map((t) => t.trim().toLowerCase()));
+  return b.some((t) => set.has(t.trim().toLowerCase()));
+}
+function uniqueTools(...lists) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const list of lists) {
+    for (const t of list ?? []) {
+      const key = t.trim().toLowerCase();
+      if (key.length === 0 || seen.has(key)) continue;
+      seen.add(key);
+      out.push(t.trim());
+    }
+  }
+  return out;
+}
+var DECORATION_CUTS = [
+  /(?:^|\s)at line \d+ of /,
+  /(?:^|\s)After Effects reported line/,
+  /(?:^|\s)Everything before the failure already ran/,
+  /\s\|\|\s*Changed before it stopped/,
+  /(?:^|\s)Known from earlier sessions:/
+];
+function stripDecorations(text) {
+  let out = text.replace(/^\s*AE\s*:\s*/i, "");
+  for (const cut of DECORATION_CUTS) {
+    const m = cut.exec(out);
+    if (m) out = out.slice(0, m.index);
+  }
+  return out.replace(/\s*\(line \d+\)\s*$/, "").trim();
+}
+function normalizeErrorText(text, opts = {}) {
+  let t = stripDecorations(text).toLowerCase().replace(/\b[a-z]:\\[^\s'"`]+/g, " ").replace(/file:\/\/[^\s'"`]+/g, " ").replace(/(?:^|[\s(=:,])\/[^\s'"`)]+/g, " ");
+  if (!opts.keepQuotes) {
+    t = t.replace(/"[^"\n]*"|`[^`\n]*`/g, " ").replace(/(?<![a-z])'[^'\n]*'(?![a-z])/g, " ");
+  }
+  return t.replace(/[^a-z]+/g, "");
+}
+var MATCH_MIN_CHARS = 20;
+var MATCH_PREFIX_CHARS = 60;
+function errorTextsMatch(a, b) {
+  if (!a || !b) return false;
+  const na = normalizeErrorText(a);
+  const nb = normalizeErrorText(b);
+  if (na.length === 0 || nb.length === 0) return false;
+  if (na === nb) return true;
+  const shorter = Math.min(na.length, nb.length);
+  if (shorter >= MATCH_MIN_CHARS && (na.startsWith(nb) || nb.startsWith(na))) return true;
+  return shorter >= MATCH_PREFIX_CHARS && na.slice(0, MATCH_PREFIX_CHARS) === nb.slice(0, MATCH_PREFIX_CHARS);
+}
+function entryMatchesFailure(entry, tool, errorText) {
+  if (!toolsOverlap(entry.tools, [tool])) return false;
+  if (entry.errorText) return errorTextsMatch(entry.errorText, errorText);
+  const needle = normalizeErrorText(errorText).slice(0, MATCH_PREFIX_CHARS);
+  if (needle.length < MATCH_MIN_CHARS) return false;
+  return normalizeErrorText(entry.symptom, { keepQuotes: true }).includes(needle) || normalizeErrorText(entry.symptom).includes(needle);
+}
 function logIssue(input) {
-  const id = slugify(input.title);
-  const file = entryPath(id);
-  const existing = fs7.existsSync(file) ? readEntry(file) : null;
+  const journal = journalFor(input.scope ?? "project");
+  const version = packageVersion();
+  const tools = uniqueTools(input.tools);
+  let id = slugify(input.title);
+  let existing = fs9.existsSync(entryPath(id, journal)) ? readEntry(entryPath(id, journal), journal.scope) : null;
+  let mergedBy;
+  if (existing) {
+    mergedBy = "title";
+  } else if (input.errorText && tools.length > 0) {
+    const errorText = input.errorText;
+    const twin = readJournalEntries(journal).find(
+      (e) => e.id !== id && tools.some((t) => entryMatchesFailure(e, t, errorText))
+    );
+    if (twin) {
+      existing = twin;
+      id = twin.id;
+      mergedBy = "errorText";
+    }
+  }
+  const reopened = existing?.archived === true;
+  const incomingError = clipErrorText(input.errorText);
   const entry = {
     id,
-    title: oneLine(input.title),
-    tools: input.tools ?? existing?.tools ?? [],
+    // On an error-text merge the existing title stays: it is the id, and the
+    // one the index has been showing.
+    title: mergedBy === "errorText" ? existing.title : oneLine(input.title),
+    scope: journal.scope,
+    tools: uniqueTools(existing?.tools, tools),
+    kind: input.kind ?? existing?.kind ?? "tool-bug",
+    // The recorded text is the one that has been matching, so a re-log of the
+    // same error — a different number, a different name, pasted with its
+    // decorations — leaves it alone. Only a genuinely different error under
+    // this title replaces it: that is the caller's statement, not a paste.
+    errorText: incomingError && existing?.errorText && errorTextsMatch(existing.errorText, incomingError) ? existing.errorText : incomingError ?? existing?.errorText,
     firstSeen: existing?.firstSeen || today(),
     lastSeen: today(),
+    firstVersion: existing?.firstVersion || version,
+    lastVersion: version,
     // Repeats are worth counting: an entry seen five times is the one most
     // worth reporting, and the count is the only evidence of that.
     occurrences: (existing?.occurrences ?? 0) + 1,
     // Reporting state belongs to the entry, not to this sighting — a fresh
-    // description of a known problem must not un-report it.
+    // description of a known problem must not un-report it. And it belongs to
+    // the entry *in this scope*: the two journals are separate records of
+    // separate claims, so reporting one says nothing about the other.
     reported: existing?.reported ?? false,
     issueUrl: existing?.issueUrl,
+    // A deliberate new sighting outranks a retirement: the entry was archived
+    // as gone, and here it is. The flag clears and the result says so.
+    archived: false,
     symptom: input.symptom,
     // A cause worked out once is not lost because a later sighting was logged
     // without one.
     cause: input.cause ?? existing?.cause,
     workaround: input.workaround
   };
-  ensureJournalDir();
-  fs7.writeFileSync(file, render(entry), "utf8");
+  const file = writeEntry(entry, journal);
+  const alsoIn = journals().filter((j) => j.scope !== journal.scope).filter((j) => fs9.existsSync(entryPath(id, j))).map((j) => j.scope);
   return {
     id,
+    title: entry.title,
     path: file,
+    scope: journal.scope,
+    kind: entry.kind,
     occurrences: entry.occurrences,
     previouslyLogged: existing !== null,
+    ...mergedBy ? { mergedBy } : {},
     reported: entry.reported,
-    issueUrl: entry.issueUrl
+    issueUrl: entry.issueUrl,
+    lastVersion: version,
+    ...reopened ? { reopened: true, previousArchiveReason: existing?.archivedReason } : {},
+    ...alsoIn.length > 0 ? { alsoIn } : {},
+    ...mergedBy === "errorText" ? {
+      note: `Merged into the existing entry "${entry.title}" (${journal.scope}:${id}): same tool, same error text. The title you passed was not used \u2014 reuse this one to extend it again.`
+    } : {}
   };
 }
-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;
+var DEFAULT_LIMIT = 50;
+function withVerdict(e, reason) {
+  return reason === null ? { ...e, archived: false, archivedReason: void 0 } : { ...e, archived: true, archivedReason: reason };
 }
-function toIndexEntry(e) {
+function toIndexEntry(e, reason) {
   return {
     id: e.id,
     title: e.title,
+    scope: e.scope,
     tools: e.tools,
+    kind: e.kind,
     lastSeen: e.lastSeen,
+    ...e.lastVersion ? { lastVersion: e.lastVersion } : {},
     occurrences: e.occurrences,
     reported: e.reported,
-    summary: summarize(e)
+    ...reason !== null ? { archived: true, archivedReason: reason } : {}
   };
 }
-function readAllEntries() {
-  const dir = journalDir();
+function readJournalEntries(journal) {
+  const dir = issuesDir(journal);
   try {
-    return fs7.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path8.join(dir, f))).filter((e) => e !== null);
+    return fs9.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path10.join(dir, f), journal.scope)).filter((e) => e !== null);
   } catch {
     return [];
   }
 }
+function selectedJournals(filter) {
+  if (filter === "all") return journals();
+  if (filter === "user") return journals().filter((j) => j.scope === "user");
+  return journals().filter((j) => j.scope === "project" || j.scope === "home");
+}
+function readAllEntries(filter = "all") {
+  return selectedJournals(filter).flatMap(readJournalEntries);
+}
+var SCOPE_PREFIX = /^(project|home|user)\s*:\s*(.+)$/i;
+function resolveEntry(raw, entries) {
+  const qualified = SCOPE_PREFIX.exec(raw.trim());
+  if (qualified) {
+    const scope = qualified[1].toLowerCase();
+    const slug2 = slugify(qualified[2]);
+    const inScope = (e) => e.scope === scope || scope === "project" && e.scope === "home";
+    const hit = entries.find((e) => inScope(e) && e.id === slug2);
+    if (hit) return { found: hit, alsoIn: [] };
+  }
+  const slug = slugify(raw);
+  const matches = entries.filter((e) => e.id === slug);
+  if (matches.length === 0) return null;
+  return { found: matches[0], alsoIn: matches.slice(1).map((e) => e.scope) };
+}
+function knownIds(entries) {
+  return entries.map((e) => `${e.scope}:${e.id}`).join(", ");
+}
 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 project = journalRoot();
+  const filter = options.scope ?? "all";
+  const consulted = selectedJournals(filter);
+  const perJournal = consulted.map((j) => ({ journal: j, entries: readJournalEntries(j) }));
+  const entries = perJournal.flatMap((p) => p.entries);
+  const ctx = options.context ?? archiveContext();
   const envelope = {
-    dir,
-    scope,
+    dir: issuesDir(project),
+    scope: project.scope,
+    journals: perJournal.map(({ journal, entries: e }) => ({
+      scope: journal.scope,
+      dir: issuesDir(journal),
+      count: e.length
+    })),
     repo: REPO,
     newIssueUrl: NEW_ISSUE_URL,
-    serverVersion: packageVersion(),
+    serverVersion: ctx.version,
     platform: process.platform
   };
   const wantedId = options.id?.trim();
   if (wantedId) {
-    const found = entries.find((e) => e.id === slugify(wantedId));
-    if (!found) {
+    const resolved = resolveEntry(wantedId, entries);
+    if (!resolved) {
       throw new Error(
-        `No journal entry with id "${wantedId}".` + (entries.length > 0 ? ` Known ids: ${entries.map((e) => e.id).join(", ")}` : " The journal is empty.")
+        `No journal entry with id "${wantedId}".` + (entries.length > 0 ? ` Known ids: ${knownIds(entries)}` : " The journal is empty.")
       );
     }
-    return { ...envelope, detail: "full", count: 1, issues: [found] };
+    return {
+      ...envelope,
+      detail: "full",
+      count: 1,
+      issues: [withVerdict(resolved.found, archiveReason(resolved.found, ctx))],
+      // Same slug in the other journal: say so, and name the call that opens it,
+      // rather than letting one of the two silently win.
+      ...resolved.alsoIn.length > 0 ? {
+        next: `Also written down in the ${resolved.alsoIn.join(" and ")} journal \u2014 list_known_issues({ id: "${resolved.alsoIn[0]}:${resolved.found.id}" }) reads that one.`
+      } : {}
+    };
   }
   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 namesTool = (e) => wanted !== void 0 && e.tools.some((t) => t.toLowerCase() === wanted);
+  const matched = 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);
+    return namesTool(e) || e.title.toLowerCase().includes(wanted);
   });
-  filtered.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences);
+  const verdicts = new Map(matched.map((e) => [e, archiveReason(e, ctx)]));
+  const archivedCount = matched.filter((e) => verdicts.get(e) !== null).length;
+  const filtered = options.includeArchived ? matched : matched.filter((e) => verdicts.get(e) === null);
+  filtered.sort(
+    (a, b) => Number(namesTool(b)) - Number(namesTool(a)) || b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences
+  );
+  const limit = options.limit && options.limit > 0 ? options.limit : DEFAULT_LIMIT;
+  const shown = filtered.slice(0, limit);
+  const omitted = filtered.length - shown.length;
   const detail = options.detail ?? "index";
+  const first = shown[0];
+  const hidden = options.includeArchived ? 0 : archivedCount;
+  const nextParts = [];
+  if (detail === "index" && first) {
+    nextParts.push(
+      `list_known_issues({ id: "${first.scope}:${first.id}" }) for the cause and the workaround. Prefix any id from this list with its own scope.`
+    );
+  }
+  if (omitted > 0) nextParts.push(`${omitted} more matched \u2014 narrow with tool/query, or raise limit.`);
+  if (hidden > 0) {
+    nextParts.push(
+      `${hidden} archived ${hidden === 1 ? "entry is" : "entries are"} hidden (not seen for ${ARCHIVE_AFTER_DAYS} days, last seen on an older server, or retired with archive_issue) \u2014 includeArchived: true lists them.`
+    );
+  }
   return {
     ...envelope,
     detail,
     count: filtered.length,
-    issues: detail === "full" ? filtered : filtered.map(toIndexEntry),
+    archivedCount,
+    issues: detail === "full" ? shown.map((e) => withVerdict(e, verdicts.get(e) ?? null)) : shown.map((e) => toIndexEntry(e, verdicts.get(e) ?? null)),
+    // Truncation is named and counted. A short answer that looked complete
+    // would be the same class of lie as a swallowed error.
+    ...omitted > 0 ? { omitted } : {},
     // 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.' } : {}
+    // how to reach it, every time there is one to reach — and since ids are
+    // only unique within a journal, spell the scope-qualified form out on a
+    // real entry rather than leaving the caller to guess the syntax.
+    ...nextParts.length > 0 ? { next: nextParts.join(" ") } : {}
   };
 }
-function markReported(id, url) {
-  const file = entryPath(slugify(id));
-  const entry = fs7.existsSync(file) ? readEntry(file) : null;
-  if (!entry) {
-    const known = readAllEntries().map((e) => e.id);
+function locate(id) {
+  const entries = readAllEntries();
+  const resolved = resolveEntry(id, entries);
+  if (!resolved) {
     throw new Error(
-      `No journal entry with id "${id}".` + (known.length > 0 ? ` Known ids: ${known.join(", ")}` : "")
+      `No journal entry with id "${id}".` + (entries.length > 0 ? ` Known ids: ${knownIds(entries)}` : "")
     );
   }
+  const entry = resolved.found;
+  const journal = journals().find((j) => j.scope === entry.scope);
+  if (!journal) throw new Error(`Journal for scope "${entry.scope}" is no longer readable.`);
+  return { entry, journal };
+}
+function markReported(id, url) {
+  const { entry, journal } = locate(id);
   entry.reported = true;
   if (url) entry.issueUrl = oneLine(url);
-  fs7.writeFileSync(file, render(entry), "utf8");
+  writeEntry(entry, journal);
+  return entry;
+}
+function archiveIssue(id, reason) {
+  const { entry, journal } = locate(id);
+  entry.archived = true;
+  entry.archivedReason = oneLine(reason);
+  entry.archivedAt = today();
+  writeEntry(entry, journal);
   return entry;
 }
 
+// src/issues/failures.ts
+import fs10 from "node:fs";
+import path11 from "node:path";
+var MAX_MATCHES = 3;
+var JournalCache = class {
+  files = /* @__PURE__ */ new Map();
+  /** Files parsed since construction — the number the test watches to prove the cache is one. */
+  reads = 0;
+  entries(refs = journals()) {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const journal of refs) {
+      const dir = issuesDir(journal);
+      let names;
+      try {
+        names = fs10.readdirSync(dir).filter((f) => f.endsWith(".md"));
+      } catch {
+        continue;
+      }
+      for (const name of names) {
+        const file = path11.join(dir, name);
+        seen.add(file);
+        let st;
+        try {
+          st = fs10.statSync(file);
+        } catch {
+          continue;
+        }
+        const cached = this.files.get(file);
+        if (cached && cached.size === st.size && cached.mtimeMs === st.mtimeMs) {
+          if (cached.entry) out.push(cached.entry);
+          continue;
+        }
+        this.reads++;
+        const entry = readEntry(file, journal.scope);
+        this.files.set(file, { size: st.size, mtimeMs: st.mtimeMs, entry });
+        if (entry) out.push(entry);
+      }
+    }
+    for (const file of this.files.keys()) if (!seen.has(file)) this.files.delete(file);
+    return out;
+  }
+  /**
+   * After this module writes an entry, the cached copy is the one it wrote —
+   * so the next lookup does not re-parse a file whose content it already holds
+   * even on a filesystem whose mtime resolution would not show the write.
+   */
+  refresh(file, entry) {
+    try {
+      const st = fs10.statSync(file);
+      this.files.set(file, { size: st.size, mtimeMs: st.mtimeMs, entry });
+    } catch {
+      this.files.delete(file);
+    }
+  }
+};
+function matchFailure(cache, tool, errorText, ctx = archiveContext(), refs = journals()) {
+  const hits = cache.entries(refs).filter((e) => entryMatchesFailure(e, tool, errorText)).sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences);
+  return {
+    matches: hits.slice(0, MAX_MATCHES).map((entry) => ({ entry, archivedReason: archiveReason(entry, ctx) })),
+    total: hits.length
+  };
+}
+function describeMatches(found) {
+  const lines = found.matches.map(({ entry, archivedReason }) => {
+    const where = `${entry.scope}:${entry.id}`;
+    const tail = archivedReason ? ` (archived: ${archivedReason})` : "";
+    return `Known from earlier sessions: ${where} \u2014 ${entry.title}${tail}`;
+  });
+  const more = found.total - found.matches.length;
+  if (more > 0) lines.push(`\u2026and ${more} more matching ${more === 1 ? "entry" : "entries"}.`);
+  const first = found.matches[0];
+  lines.push(
+    `list_known_issues({ id: "${first.entry.scope}:${first.entry.id}" }) has the cause and the workaround.`
+  );
+  return lines.join("\n");
+}
+function bumpSighting(cache, match, ctx) {
+  const { entry } = match;
+  if (entry.lastSeen === ctx.today && entry.lastVersion === ctx.version) return;
+  const journal = journals().find((j) => j.scope === entry.scope);
+  if (!journal) return;
+  try {
+    entry.lastSeen = ctx.today;
+    entry.lastVersion = ctx.version;
+    const file = writeEntry(entry, journal);
+    cache.refresh(file, entry);
+  } catch (e) {
+    logger.warn(`Could not update journal entry ${entry.scope}:${entry.id} after a matching failure: ${e.message}`);
+  }
+}
+function annotateFailure(cache, tool, message, ctx) {
+  try {
+    const context = ctx ?? archiveContext();
+    const found = matchFailure(cache, tool, message, context);
+    if (found.matches.length === 0) return message;
+    for (const match of found.matches) bumpSighting(cache, match, context);
+    return `${message}
+
+${describeMatches(found)}`;
+  } catch (e) {
+    logger.warn(`Journal lookup for a failed ${tool} call was skipped: ${e.message}`);
+    return message;
+  }
+}
+
+// src/style/summary.ts
+var HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/g;
+var SECTION_KEYWORDS = [
+  { key: "palette", words: ["palette", "colour", "color", "swatch"] },
+  { key: "type", words: ["type", "typograph", "font", "lettering", "typeface"] },
+  { key: "motion", words: ["motion", "animation", "timing", "easing", "ease", "transition"] },
+  // "Rules" is in the template this project's own style-guide guide hands out,
+  // and it holds constraints of exactly the kind the layout bullets carry. It
+  // would otherwise be named as unsummarised on almost every guide written.
+  {
+    key: "layout",
+    words: ["layout", "grid", "spacing", "composition", "margin", "safe area", "framing", "rule", "constraint"]
+  }
+];
+var MAX_PALETTE = 24;
+var MAX_TYPE_LINES = 3;
+var MAX_LAYOUT_LINES = 8;
+var MAX_MOTION_CHARS = 240;
+var MAX_LINE_CHARS = 160;
+var MAX_SECTIONS_OMITTED = 12;
+var HEAD_CHARS = 900;
+function findHeadings(lines) {
+  const headings = [];
+  let fenced = false;
+  let frontmatter = /^---\s*$/.test(lines[0] ?? "");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    if (frontmatter) {
+      if (i > 0 && /^---\s*$/.test(line)) frontmatter = false;
+      continue;
+    }
+    const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (atx) {
+      headings.push({ level: atx[1].length, text: atx[2].trim(), from: i + 1 });
+      continue;
+    }
+    const underline = /^ {0,3}(={3,}|-{3,})\s*$/.exec(line);
+    if (underline && i > 0) {
+      const above = lines[i - 1].trim();
+      if (above.length > 0 && !/^ {0,3}#{1,6}\s/.test(above) && !/^[-=*_\s]+$/.test(above)) {
+        headings.push({ level: underline[1].startsWith("=") ? 1 : 2, text: above, from: i + 1 });
+      }
+    }
+  }
+  return headings;
+}
+function classifyAll(heading) {
+  const text = heading.toLowerCase();
+  const kinds = /* @__PURE__ */ new Set();
+  for (const { key, words } of SECTION_KEYWORDS) {
+    if (words.some((w) => text.includes(w))) kinds.add(key);
+  }
+  return kinds;
+}
+function ownLines(lines, headings, index) {
+  const here = headings[index];
+  const next = headings[index + 1];
+  const end = next === void 0 ? lines.length : next.from - (isSetext(lines, next) ? 2 : 1);
+  return lines.slice(here.from, Math.max(here.from, end));
+}
+function isSetext(lines, heading) {
+  const underline = lines[heading.from - 1];
+  return underline !== void 0 && /^ {0,3}(={3,}|-{3,})\s*$/.test(underline);
+}
+function condense(line) {
+  let text = line.trim();
+  if (/^\|/.test(text)) {
+    const cells = text.split("|").map((c) => c.trim()).filter((c) => c.length > 0);
+    if (cells.every((c) => /^:?-{2,}:?$/.test(c))) return "";
+    text = cells.join(" \xB7 ");
+  }
+  text = text.replace(/^#{1,6}\s+/, "").replace(/^[-*+]\s+/, "").replace(/^\d+[.)]\s+/, "").replace(/^>\s?/, "").replace(/\*\*|__|`/g, "").trim();
+  return text.length > MAX_LINE_CHARS ? `${text.slice(0, MAX_LINE_CHARS).trimEnd()}\u2026` : text;
+}
+function contentLines(lines) {
+  return lines.map(condense).filter((l) => l.length > 0 && !/^```/.test(l));
+}
+function readPalette(lines) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of lines) {
+    HEX.lastIndex = 0;
+    const hexes = raw.match(HEX);
+    if (!hexes) continue;
+    const isTableRow = /^\s*\|/.test(raw);
+    let name = "";
+    if (isTableRow) {
+      const cells = raw.split("|").map((c) => c.trim().replace(/\*\*|__|`/g, "").trim()).filter((c) => c.length > 0);
+      name = cells.find((c) => !/^#[0-9a-fA-F]{3,8}$/.test(c) && !/^:?-{2,}:?$/.test(c)) ?? "";
+    } else {
+      name = raw.slice(0, raw.indexOf(hexes[0])).replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*+]\s+/, "").replace(/^\s*\d+[.)]\s+/, "").replace(/^\s*>\s?/, "").replace(/\*\*|__|`/g, "").replace(/[|]/g, " ").replace(/\s+/g, " ").trim().replace(/[:=–—-]+$/, "").trim();
+    }
+    if (name.length > 40) name = `${name.slice(0, 40).trimEnd()}\u2026`;
+    for (const hex of hexes) {
+      const key = hex.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push({ name, hex });
+      name = "";
+      if (found.length >= MAX_PALETTE) return found;
+    }
+  }
+  return found;
+}
+function summarizeHouseStyle(content) {
+  const lines = content.split(/\r\n|\r|\n/);
+  const headings = findHeadings(lines);
+  const buckets = { type: [], motion: [], layout: [] };
+  const omitted = [];
+  const absorbed = new Array(headings.length).fill(false);
+  const ownCache = /* @__PURE__ */ new Map();
+  const own = (i) => {
+    let value = ownCache.get(i);
+    if (!value) ownCache.set(i, value = contentLines(ownLines(lines, headings, i)));
+    return value;
+  };
+  headings.forEach((heading, i) => {
+    if (absorbed[i]) return;
+    const kinds = classifyAll(heading.text);
+    if (kinds.size === 0) {
+      if (own(i).length > 0 && !omitted.includes(heading.text)) omitted.push(heading.text);
+      return;
+    }
+    const body = [...own(i)];
+    for (let j = i + 1; j < headings.length && headings[j].level > heading.level; j++) {
+      if (classifyAll(headings[j].text).size > 0) break;
+      absorbed[j] = true;
+      const sub = own(j);
+      if (sub.length === 0) continue;
+      body.push(`${headings[j].text}: ${sub[0]}`, ...sub.slice(1));
+    }
+    const bucketed = [...kinds].filter((k) => k !== "palette");
+    if (bucketed.length === 0 || body.length === 0) return;
+    for (const kind of bucketed) buckets[kind].push(...body);
+  });
+  const palette = readPalette(lines);
+  const type = buckets.type.slice(0, MAX_TYPE_LINES);
+  const layout = buckets.layout.slice(0, MAX_LAYOUT_LINES);
+  const motionJoined = buckets.motion.join("; ");
+  const motion = motionJoined.length > MAX_MOTION_CHARS ? `${motionJoined.slice(0, MAX_MOTION_CHARS).trimEnd()}\u2026` : motionJoined;
+  const structured = palette.length > 0 || type.length > 0 || layout.length > 0 || motion.length > 0;
+  const chars = content.length;
+  if (!structured) {
+    const head = content.trim().slice(0, HEAD_CHARS);
+    return {
+      summary: {
+        structured: false,
+        palette: [],
+        type: [],
+        motion: "",
+        layout: [],
+        head: head + (content.trim().length > head.length ? "\u2026" : ""),
+        ...omitted.length > 0 ? { sectionsOmitted: omitted.slice(0, MAX_SECTIONS_OMITTED) } : {}
+      },
+      note: `This style guide has no palette, type, motion or layout section this summariser could recognise, so the text above is the opening of the document verbatim and nothing has been interpreted. Call get_house_style({ detail: "full" }) to read all ${chars} characters.`
+    };
+  }
+  const dropped = [];
+  if (buckets.type.length > type.length) dropped.push(`${buckets.type.length - type.length} more type lines`);
+  if (buckets.layout.length > layout.length)
+    dropped.push(`${buckets.layout.length - layout.length} more layout lines`);
+  if (omitted.length > 0) dropped.push(`sections: ${omitted.slice(0, MAX_SECTIONS_OMITTED).join(", ")}`);
+  return {
+    summary: {
+      structured: true,
+      palette,
+      type,
+      motion,
+      layout,
+      ...omitted.length > 0 ? { sectionsOmitted: omitted.slice(0, MAX_SECTIONS_OMITTED) } : {}
+    },
+    note: `This is a summary, not the style guide. The document is ${chars} characters; call get_house_style({ detail: "full" }) for all of it before editing it or when a detail here is not enough.` + (dropped.length > 0 ? ` Not summarised \u2014 ${dropped.join("; ")}.` : "")
+  };
+}
+function applyHouseStyleDetail(result, detail) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+  const r = result;
+  if (typeof r.content !== "string" || r.content.length === 0) return result;
+  if (detail === "full") return { ...r, detail: "full" };
+  const { summary, note } = summarizeHouseStyle(r.content);
+  const { content, ...rest } = r;
+  return {
+    ...rest,
+    detail: "summary",
+    // The caller has to be able to judge whether the full read is worth it.
+    characters: content.length,
+    lines: content.split(/\r\n|\r|\n/).length,
+    summary,
+    note
+  };
+}
+
 // src/util/pngImage.ts
 function imageContent(meta, base64) {
   return {
@@ -2247,15 +4226,21 @@ var SERVER_OPS = /* @__PURE__ */ new Set([
   "ae_guide",
   "log_issue",
   "list_known_issues",
-  "mark_issue_reported"
+  "mark_issue_reported",
+  "archive_issue"
 ]);
+var SNAPSHOT_OPS = /* @__PURE__ */ new Set(["snapshot_comp", "diff_comp"]);
+function isWriteOp(name) {
+  const effect = schemas_exports.OpMutation[name];
+  return effect === void 0 ? true : effect === "write";
+}
 var GUIDE_URI_PREFIX = "ae://guide/";
 var AwaitJobSchema = schemas_exports.AwaitJob;
 var GetJobSchema = schemas_exports.GetJob;
 var CancelJobSchema = schemas_exports.CancelJob;
-function createServer() {
+function createServer(opts = {}) {
   const server = new Server(
-    { name: "after-effects-mcp", version: "0.3.1" },
+    { name: "after-effects-mcp", version: "0.5.0" },
     {
       capabilities: { tools: {}, logging: {}, prompts: {}, resources: {} },
       // Clients that honour this fold it into the system prompt, which is the
@@ -2264,28 +4249,33 @@ function createServer() {
       instructions: SERVER_INSTRUCTIONS
     }
   );
-  const bridge = new HttpClient();
+  const bridge = opts.bridge ?? new HttpClient();
   const jobs = new JobManager();
-  const ws = new WsClient(bridge.port, jobs);
+  const writes = new WriteQueue();
+  const snapshots = new SnapshotStore();
+  const ws = new WsClient(bridge, jobs);
   ws.start();
   const panelGate = createPanelGate(bridge);
+  const journalCache = new JournalCache();
+  const fail = (tool, message) => errorResult(annotateFailure(journalCache, tool, message));
   bridge.health().then(
     (h) => logger.info(`Bridge healthy on port ${h.port}`),
-    (e) => logger.warn(`Bridge not reachable yet: ${e.message}`)
+    async (e) => {
+      logger.warn(`Bridge not reachable yet: ${e.message}`);
+      if (!(e instanceof BridgeUnreachableError)) return;
+      const located = await bridge.rediscover().catch(() => null);
+      if (located?.found && located.found.port !== bridge.port) {
+        await bridge.switchPort(located.found.port);
+        logger.info(`Bridge healthy on port ${bridge.port}`);
+      }
+    }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    const tools = Object.keys(OpSchemas2).map((name) => {
-      const schema = OpSchemas2[name];
-      const jsonSchema = zodToJsonSchema(schema, {
-        target: "jsonSchema7",
-        $refStrategy: "none"
-      });
-      return {
-        name,
-        description: descriptions[name] ?? `AE op: ${name}`,
-        inputSchema: toDraft2020(jsonSchema)
-      };
-    });
+    const tools = Object.keys(OpSchemas2).map((name) => ({
+      name,
+      description: descriptions[name] ?? `AE op: ${name}`,
+      inputSchema: toolInputSchema(name)
+    }));
     return { tools };
   });
   server.setRequestHandler(ListPromptsRequestSchema, async () => ({
@@ -2334,8 +4324,13 @@ function createServer() {
       try {
         if (name === "await_job") {
           const a = AwaitJobSchema.parse(rawArgs);
-          const st = await jobs.waitFor(a.jobId, a.timeoutMs ?? 6e5);
-          return textResult(st);
+          const forward = progressToken !== void 0 ? forwardJobProgress(jobs, a.jobId, progressToken, extra) : null;
+          try {
+            const st = await jobs.waitFor(a.jobId, a.timeoutMs ?? 6e5);
+            return textResult(st);
+          } finally {
+            await forward?.settle();
+          }
         }
         if (name === "get_job") {
           const a = GetJobSchema.parse(rawArgs);
@@ -2348,14 +4343,15 @@ function createServer() {
           jobs.cancel(a.jobId);
           return textResult({ ok: true });
         }
+        const setupOpts = () => ({ opPort: bridge.port, candidates: [...bridge.candidates(), ...diagnosticPortCandidates()] });
         if (name === "check_setup") {
-          return textResult(await checkSetup());
+          return textResult(await checkSetup(setupOpts()));
         }
         if (name === "setup_panel") {
           const a = schemas_exports.SetupPanel.parse(rawArgs);
           const installed = await installPanel({ enableDebugMode: a.enableDebugMode, force: a.force });
           panelGate.invalidate();
-          return textResult({ ...installed, setup: await checkSetup() });
+          return textResult({ ...installed, setup: await checkSetup(setupOpts()) });
         }
         if (name === "init_project") {
           const a = schemas_exports.InitProject.parse(rawArgs);
@@ -2374,11 +4370,20 @@ function createServer() {
           const a = schemas_exports.AeGuide.parse(rawArgs);
           const guide = getGuide(a.topic);
           if (!guide) return errorResult(`Unknown guide topic: ${a.topic}`);
+          if (a.topic === "whats-new") {
+            const rendered = renderWhatsNew(guide.body, { since: a.since, serverVersion: packageVersion() });
+            return { content: [{ type: "text", text: rendered.text }] };
+          }
+          if (a.since !== void 0) {
+            return errorResult(
+              `\`since\` filters the whats-new topic only; the ${a.topic} topic has no release sections to filter. Call ae_guide({topic: "${a.topic}"}) without \`since\`, or ae_guide({topic: "whats-new", since: "${a.since}"}) for what changed.`
+            );
+          }
           return { content: [{ type: "text", text: guide.body }] };
         }
         if (name === "log_issue") {
           const a = schemas_exports.LogIssue.parse(rawArgs);
-          return textResult(logIssue(a));
+          return textResult(logIssue({ ...a, scope: a.scope ?? "project" }));
         }
         if (name === "list_known_issues") {
           const a = schemas_exports.ListKnownIssues.parse(rawArgs);
@@ -2390,41 +4395,82 @@ function createServer() {
               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"
+              detail: a.detail ?? "index",
+              // Both journals by default — the whole point of the user one is
+              // that a fresh project folder does not start ignorant.
+              scope: a.scope ?? "all",
+              limit: a.limit,
+              // Hidden unless asked: an archived entry is one that stopped
+              // biting, was superseded by a release, or was retired on purpose.
+              includeArchived: a.includeArchived ?? false
             })
           );
         }
         if (name === "mark_issue_reported") {
           const a = schemas_exports.MarkIssueReported.parse(rawArgs);
           const entry = markReported(a.id, a.url);
-          return textResult({ ok: true, id: entry.id, reported: true, issueUrl: entry.issueUrl });
+          return textResult({ ok: true, id: entry.id, scope: entry.scope, reported: true, issueUrl: entry.issueUrl });
+        }
+        if (name === "archive_issue") {
+          const a = schemas_exports.ArchiveIssue.parse(rawArgs);
+          const entry = archiveIssue(a.id, a.reason);
+          return textResult({
+            ok: true,
+            id: entry.id,
+            scope: entry.scope,
+            archived: true,
+            reason: entry.archivedReason,
+            archivedAt: entry.archivedAt,
+            note: "The file is kept and can be reopened by a later log_issue with the same title or the same tool and error text."
+          });
         }
       } catch (e) {
-        return errorResult(e.message);
+        return fail(name, invalidArgsText(name, e));
       }
     }
     let args;
     try {
       args = OpSchemas2[name].parse(rawArgs);
     } catch (e) {
-      return errorResult(`Invalid arguments for ${name}: ${e.message}`);
+      return fail(name, invalidArgsText(name, e));
+    }
+    if (name === "run_jsx") {
+      try {
+        args = resolveRunJsxSource(args);
+      } catch (e) {
+        return fail(name, e.message);
+      }
     }
     const staleness = await panelGate.check();
     if (staleness) return errorResult(staleness);
+    let lease = null;
+    if (isWriteOp(name)) {
+      try {
+        lease = await writes.acquire(name, extra?.signal);
+      } catch (e) {
+        return fail(name, e.message);
+      }
+    }
+    const wait = lease?.wait ?? null;
     try {
-      const result = await bridge.runOp(name, args, progressToken);
+      if (SNAPSHOT_OPS.has(name)) return await runSnapshotOp(name, args, bridge, snapshots);
+      const result = await bridge.runOp(name, args);
       if (ASYNC_OPS.has(name) && isAsyncEnvelope(result)) {
         const env = result;
         jobs.register(env.jobId, env.total);
-        if (progressToken !== void 0) {
-          jobs.bindProgressEmitter(env.jobId, (jid, progress, total, message) => {
-            void server.notification({
-              method: "notifications/progress",
-              params: { progressToken, progress, total, message }
-            });
-          });
-        }
-        return textResult({ jobId: env.jobId, async: true, total: env.total });
+        lease?.extendUntil(jobs.waitFor(env.jobId, writes.holdCeilingMs));
+        return textResult(
+          {
+            jobId: env.jobId,
+            async: true,
+            total: env.total,
+            chunkSize: env.chunkSize,
+            undoStepsEstimate: env.undoStepsEstimate,
+            undoGroupName: env.undoGroupName,
+            note: withProgressNote(env.note, env.jobId)
+          },
+          wait
+        );
       }
       if (VISION_OPS.has(name) && isEmptyFrameResult(result)) return textResult(result);
       if (VISION_OPS.has(name) && isVisionResult(result)) {
@@ -2446,32 +4492,107 @@ function createServer() {
             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
+            warning: v.warning,
+            // Present only for a `times` call. `tiles` is what makes the sheet
+            // readable as data as well as a picture — cell rectangle, time and
+            // status per tile, in the order they were asked for.
+            contactSheet: v.contactSheet,
+            cols: v.cols,
+            rows: v.rows,
+            cellWidth: v.cellWidth,
+            cellHeight: v.cellHeight,
+            tiles: v.tiles
           },
           v.base64
         );
       }
-      return textResult(result);
+      if (name === "get_house_style") {
+        const detail = args.detail ?? "summary";
+        return textResult(applyHouseStyleDetail(result, detail), wait);
+      }
+      return textResult(result, wait);
     } catch (e) {
-      if (e instanceof BridgeTimeoutError) return errorResult(e.message);
-      if (e instanceof BridgeUnreachableError) return errorResult(e.message);
+      if (e instanceof BridgeTimeoutError) return fail(name, e.message);
+      if (e instanceof BridgeUnreachableError) return fail(name, e.message);
       if (e instanceof AeError) {
-        if (e.code) return errorResult(e.message);
+        if (e.code) return fail(name, e.message);
         if (/^Unknown op: /.test(e.message)) {
           panelGate.invalidate();
           return errorResult(unknownOpMessage(name));
         }
-        return errorResult(`AE: ${e.message}${e.line ? ` (line ${e.line})` : ""}`);
+        return fail(name, aeErrorText(e));
       }
-      return errorResult(e.message);
+      return fail(name, e.message);
+    } finally {
+      lease?.release();
     }
   });
   return server;
 }
+function forwardJobProgress(jobs, jobId, progressToken, extra) {
+  const inFlight = /* @__PURE__ */ new Set();
+  const unbind = jobs.bindProgressEmitter(jobId, (_jid, progress, total, message) => {
+    const p = extra.sendNotification({ method: "notifications/progress", params: { progressToken, progress, total, message } }).catch((e) => logger.warn(`progress notification for job ${jobId} was not sent: ${e.message}`));
+    inFlight.add(p);
+    void p.finally(() => inFlight.delete(p));
+  });
+  return {
+    async settle() {
+      unbind();
+      await Promise.all(inFlight);
+    }
+  };
+}
+function withProgressNote(note, jobId) {
+  const progress = `Follow it with await_job({jobId: "${jobId}"}), which blocks until the batch finishes and returns its result. Progress is delivered on THAT call: send it with a progressToken and notifications/progress arrive while it waits, every one before its response. None can ride on this run_batch call \u2014 its response is already back before the first chunk runs. get_job({jobId: "${jobId}"}) reads the same state without a token.`;
+  return note ? `${note} ${progress}` : progress;
+}
+async function runSnapshotOp(name, args, bridge, snapshots) {
+  if (name === "snapshot_comp") {
+    const a = args;
+    const fingerprint = await bridge.runOp("_comp_fingerprint", { compId: a.compId });
+    const snap = snapshots.store(fingerprint);
+    return textResult({
+      snapshotId: snap.id,
+      compId: snap.compId,
+      compName: snap.compName,
+      layers: snap.layerCount,
+      takenAt: new Date(snap.takenAt).toISOString(),
+      next: `Do the work, then diff_comp({ since: "${snap.id}" }).`,
+      lifetime: "Held in this MCP server's memory for the length of the session, not written into the After Effects project.",
+      covers: SNAPSHOT_COVERS,
+      fingerprint: a.includeFingerprint ? fingerprint : void 0
+    });
+  }
+  const d = args;
+  const previous = snapshots.get(d.since);
+  if (!previous) return errorResult(snapshots.missingMessage(d.since));
+  if (d.compId !== void 0 && d.compId !== previous.compId) {
+    return errorResult(
+      `Snapshot ${d.since} is of comp ${previous.compId} ("${previous.compName}"), not comp ${d.compId}. A diff only means anything against a snapshot of the same comp \u2014 omit compId, or snapshot_comp(${d.compId}) first.`
+    );
+  }
+  const res = await bridge.runOp("_comp_diff", {
+    compId: previous.compId,
+    since: previous.fingerprint
+  });
+  const next = snapshots.store(res.fingerprint);
+  return textResult({
+    ...res.diff,
+    since: d.since,
+    snapshotId: next.id,
+    fingerprint: d.includeFingerprint ? res.fingerprint : void 0
+  });
+}
+var SNAPSHOT_COVERS = "Records layer id/name/index/type, in/out/start, parent, enabled, keyframe counts, expression count and effect count, plus comp size/duration/frame rate/work area/markers. Property values, expression text, effect parameters and shape contents are not recorded.";
 function createPanelGate(bridge) {
   const RECHECK_MS = 6e4;
   let verdict = null;
   let checkedAt = 0;
+  bridge.onPortChange(() => {
+    verdict = null;
+    checkedAt = 0;
+  });
   return {
     /** The message to return instead of forwarding, or null to proceed. */
     async check() {
@@ -2508,10 +4629,12 @@ async function clientRoots(server) {
     return void 0;
   }
 }
-function textResult(value) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
-  };
+function textResult(value, wait) {
+  const json = (v) => ({ type: "text", text: JSON.stringify(v, null, 2) });
+  if (!wait) return { content: [json(value)] };
+  const merged = mergeWait(value, wait);
+  if (merged) return { content: [json(merged)] };
+  return { content: [json(value), json(wait)] };
 }
 function errorResult(message) {
   return {
@@ -2519,6 +4642,7 @@ function errorResult(message) {
     isError: true
   };
 }
+var JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
 function toDraft2020(node) {
   if (Array.isArray(node)) return node.map(toDraft2020);
   if (!node || typeof node !== "object") return node;
@@ -2533,8 +4657,41 @@ function toDraft2020(node) {
       out.items = false;
     }
   }
+  if (typeof out.$schema === "string") out.$schema = JSON_SCHEMA_DIALECT;
   return out;
 }
+function withCrossFieldConstraints(zodSchema, jsonSchema, opName) {
+  for (const { path: path12, rule } of schemas_exports.crossFieldRulesIn(zodSchema)) {
+    const where = path12.join(".") || "(root)";
+    if (!rule) {
+      logger.warn(
+        `${opName} carries a refinement at ${where} that is not a declared cross-field rule. It is enforced on every call and absent from the schema the model is shown, so an agent can only learn it by having a call rejected. Declare it with crossField() in packages/shared/src/schemas.ts.`
+      );
+      continue;
+    }
+    let node = jsonSchema;
+    for (const step of path12) {
+      node = step === schemas_exports.ARRAY_ELEMENT ? node?.items : node?.properties?.[step];
+      if (!node || typeof node !== "object") break;
+    }
+    if (!node || typeof node !== "object") {
+      logger.warn(
+        `${opName}: the cross-field rule at ${where} has no matching node in the emitted JSON Schema, so it ships enforced but invisible.`
+      );
+      continue;
+    }
+    const fragment = schemas_exports.crossFieldJsonSchema(rule);
+    const collides = Object.keys(fragment).some((k) => k in node);
+    if (collides) (node.allOf ??= []).push(fragment);
+    else Object.assign(node, fragment);
+  }
+  return jsonSchema;
+}
+function toolInputSchema(opName) {
+  const schema = OpSchemas2[opName];
+  const jsonSchema = zodToJsonSchema(schema, { target: "jsonSchema7", $refStrategy: "none" });
+  return withCrossFieldConstraints(schema, toDraft2020(jsonSchema), opName);
+}
 function isAsyncEnvelope(v) {
   return !!(v && typeof v === "object" && "async" in v && v.async === true && "jobId" in v);
 }
@@ -2585,7 +4742,7 @@ ${USAGE}`);
   await server.connect(transport);
   logger.info("MCP server running on stdio");
 }
-var VERSION = "0.3.1";
+var VERSION = "0.5.0";
 main().catch((e) => {
   logger.error("fatal", e.message);
   process.exit(1);