@engine-room/after-effects-mcp 0.1.1 → 0.2.0

package/bin/server.js

@@ -9,167 +9,277 @@ var __export = (target, all) => {
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/cli/init.ts
+import path2 from "node:path";
+
+// src/setup/scaffold.ts
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-var HOUSE_STYLE = `---
-name: house-style
-description: The visual and motion style for this project \u2014 palette, type, timing and layout rules. Load whenever building or editing anything in After Effects for this project.
----
-
-# House style
-
-<!--
-  This file is yours. Claude reads it before building anything in After Effects,
-  so whatever you write here becomes the default look of your work.
-
-  Replace the placeholders below with your own values. Be specific and concrete:
-  "dark navy #131521 at 92% opacity" is usable, "modern and clean" is not. If a
-  number matters \u2014 a corner radius, a stroke width, a hold duration \u2014 write the
-  number down.
-
-  The fastest way to fill this in: build one piece the way you like it, then ask
-  Claude "read this comp and write it up in my house-style skill".
--->
-
-## Palette
-
-| Role | Colour | Notes |
-|---|---|---|
-| Background | \`#000000\` | |
-| Primary text | \`#FFFFFF\` | |
-| Accent | \`#3DC46E\` | Used for emphasis and positive values |
-| Warning / negative | \`#E03333\` | |
-
-## Type
-
-- **Headings:** _font name_, weight, size range
-- **Body:** _font name_, weight, size range
-- **Tracking / leading:** _your defaults_
-- Text is left-aligned unless stated otherwise.
-
-## Motion
-
-- **Standard in:** scale 0 \u2192 108 \u2192 100 with easy ease, over ~0.4s
-- **Standard out:** scale \u2192 0 over ~0.3s
-- **Easing:** easy ease on everything; no linear motion unless mechanical
-- **Idle life:** subtle \`wiggle()\` on position so nothing sits perfectly still
-
-## Layout
-
-- Comp size and frame rate: _e.g. 1920\xD71080 at 30fps_
-- Safe margins: _e.g. 120px from every edge_
-- Where elements sit by default: _e.g. lower third, left-aligned_
-
-## Rules
-
-- _Anything that should always or never happen. E.g. "never put text directly on
-  footage \u2014 always on a rounded chip", "keep total runtime under 8 seconds"._
-`;
-var CLAUDE_MD = `# {{NAME}}
+var ScaffoldError = class extends Error {
+};
+function detectClient(clientName) {
+  const n = (clientName ?? "").toLowerCase();
+  if (!n) return "generic";
+  if (n.includes("claude-code") || n.includes("claude code")) return "claude-code";
+  if (n.includes("claude-ai") || n.includes("claude desktop")) return "claude-desktop";
+  if (n.includes("cursor")) return "cursor";
+  if (n.includes("windsurf") || n.includes("codeium")) return "windsurf";
+  if (n.includes("codex")) return "codex";
+  if (n.includes("visual studio code") || n.includes("vscode") || n.includes("copilot")) return "vscode";
+  return "generic";
+}
+var MCP_SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "@engine-room/after-effects-mcp"]
+};
+function mcpConfigFor(client) {
+  const standard = JSON.stringify({ mcpServers: { "after-effects": MCP_SERVER_ENTRY } }, null, 2) + "\n";
+  switch (client) {
+    case "claude-code":
+      return { rel: ".mcp.json", json: standard };
+    case "cursor":
+      return { rel: path.join(".cursor", "mcp.json"), json: standard };
+    case "vscode":
+      return {
+        rel: path.join(".vscode", "mcp.json"),
+        json: JSON.stringify({ servers: { "after-effects": { type: "stdio", ...MCP_SERVER_ENTRY } } }, null, 2) + "\n"
+      };
+    default:
+      return void 0;
+  }
+}
+function globalConfigHint(client) {
+  const standard = JSON.stringify({ mcpServers: { "after-effects": MCP_SERVER_ENTRY } }, null, 2) + "\n";
+  const home = os.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"),
+        json: standard
+      };
+    case "windsurf":
+      return { path: path.join(home, ".codeium", "windsurf", "mcp_config.json"), json: standard };
+    case "codex":
+      return {
+        path: path.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}
 
-After Effects project folder. The tools drive After Effects directly from here.
+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.
 
 ## How to work in this folder
 
 1. Open After Effects with the project you want to work on.
-2. Describe what you want in plain language \u2014 "build a lower third that says
-   Chapter One and slides in from the left".
+2. Say what you want in plain language \u2014 "build a lower third that says Chapter
+   One and slides in from the left".
 3. The current state of the comp is read, the change is made, and you see it.
 
 ## Style
 
-The look of everything built here is defined in
-\`.claude/skills/house-style/SKILL.md\`. Edit that file to change the defaults \u2014
-palette, type, timing, layout. It is read automatically.
+The look of everything built here comes from \`house-style.md\`, which sits next
+to the After Effects project file itself. Ask for a style guide and one gets
+written from a comp you already like; edit it in any text editor afterwards.
+
+It travels with the .aep, so it applies wherever the project is opened.
+
+## When a tool misbehaves
+
+Check \`list_known_issues\` before guessing \u2014 an earlier session may already have
+solved it. Anything newly worked out goes in with \`log_issue\`, and the
+report-ae-issue prompt sends it to the maintainers.
 
 ## Conventions for this project
 
-<!-- Anything specific to this project rather than to your general style:
-     naming conventions for comps and layers, delivery specs, the client's
+<!-- Anything specific to this project rather than to your general style: naming
+     conventions for comps and layers, delivery specs, the client's
      requirements, what lives in which comp. -->
 
 - Renders go in \`renders/\`.
 `;
-var MCP_JSON = `{
-  "mcpServers": {
-    "after-effects": {
-      "command": "npx",
-      "args": ["-y", "@engine-room/after-effects-mcp"]
-    }
+function pointerContent(rel) {
+  const body = `# After Effects project
+
+See [AGENTS.md](AGENTS.md) for how this folder works, and \`house-style.md\`
+beside the .aep for the look everything should follow.
+`;
+  if (rel.endsWith(".mdc")) {
+    return `---
+description: How this After Effects project folder works
+alwaysApply: true
+---
+
+${body}`;
   }
+  return body;
 }
-`;
-var KNOWN_FLAGS = ["--no-mcp", "--with-mcp"];
+function pointerFiles(client) {
+  switch (client) {
+    case "claude-code":
+      return ["CLAUDE.md"];
+    case "cursor":
+      return [path.join(".cursor", "rules", "after-effects.mdc")];
+    case "windsurf":
+      return [".windsurfrules"];
+    case "vscode":
+      return [path.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" };
+  }
+  const root = roots?.find((r) => r && r.trim().length > 0);
+  if (root) return { dir: path.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" };
+}
+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)]];
+  for (const rel of pointerFiles(opts.client)) files.push([rel, pointerContent(rel)]);
+  files.push([path.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)));
+  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 hint = opts.withMcpConfig && !projectConfig ? globalConfigHint(opts.client) : void 0;
+  const nextSteps = [
+    "Open After Effects and open (or save) the project you want to work on.",
+    "Ask to set up After Effects if the tools cannot reach it yet \u2014 that installs the panel, once per machine.",
+    "Ask for a style guide, pointing at a comp that already looks the way you want. It is saved next to the .aep."
+  ];
+  if (hint) nextSteps.unshift(`Add the After Effects server to ${hint.path}, then restart the app.`);
+  return {
+    dir,
+    name,
+    client: opts.client,
+    written: files.map(([rel]) => rel),
+    resolvedFrom,
+    mcpConfigHint: hint,
+    nextSteps
+  };
+}
+
+// src/cli/init.ts
+var CLIENTS = [
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "vscode",
+  "windsurf",
+  "codex",
+  "generic"
+];
 function parseInitArgs(argv) {
-  const positional = argv.filter((a) => !a.startsWith("-"));
-  const withMcp = !argv.includes("--no-mcp");
-  const unknown = argv.filter((a) => a.startsWith("-") && !KNOWN_FLAGS.includes(a));
-  if (unknown.length > 0) return { error: `Unknown option: ${unknown[0]}` };
+  const positional = [];
+  let withMcp = true;
+  let client = "claude-code";
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--no-mcp") withMcp = false;
+    else if (arg === "--with-mcp") withMcp = true;
+    else if (arg === "--client" || arg.startsWith("--client=")) {
+      const value = arg.startsWith("--client=") ? arg.slice("--client=".length) : argv[++i];
+      if (!value) return { error: "--client needs a value." };
+      if (!CLIENTS.includes(value)) {
+        return { error: `Unknown client "${value}". One of: ${CLIENTS.join(", ")}.` };
+      }
+      client = value;
+    } else if (arg.startsWith("-")) {
+      return { error: `Unknown option: ${arg}` };
+    } else positional.push(arg);
+  }
   if (positional.length === 0) return { error: "Missing target directory." };
   if (positional.length > 1) return { error: `Expected one directory, got ${positional.length}.` };
-  return { dir: positional[0], withMcp };
+  return { dir: positional[0], withMcp, client };
 }
 function runInit(argv) {
   const parsed = parseInitArgs(argv);
   if ("error" in parsed) {
-    process.stderr.write(`${parsed.error}
-
-Usage: npx @engine-room/after-effects-mcp init <directory> [--no-mcp]
-`);
-    return 1;
-  }
-  const target = path.resolve(parsed.dir);
-  const name = path.basename(target);
-  const files = [
-    ["CLAUDE.md", CLAUDE_MD.replace("{{NAME}}", name)],
-    [path.join(".claude", "skills", "house-style", "SKILL.md"), HOUSE_STYLE],
-    [path.join("renders", ".gitkeep"), ""]
-  ];
-  if (parsed.withMcp) files.push([".mcp.json", MCP_JSON]);
-  const existing = files.map(([rel]) => rel).filter((rel) => fs.existsSync(path.join(target, rel)));
-  if (existing.length > 0) {
     process.stderr.write(
-      `Refusing to overwrite existing files in ${target}:
-` + existing.map((f) => `  ${f}
-`).join("") + `
-Delete them first, or choose a different directory.
+      `${parsed.error}
+
+Usage: npx @engine-room/after-effects-mcp init <directory> [--no-mcp] [--client <name>]
+       clients: ${CLIENTS.join(", ")} (default claude-code)
 `
     );
     return 1;
   }
-  for (const [rel, content] of files) {
-    const full = path.join(target, rel);
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, content, "utf8");
+  let result;
+  try {
+    result = scaffold({
+      dir: parsed.dir,
+      client: parsed.client,
+      withMcpConfig: parsed.withMcp
+    });
+  } catch (e) {
+    if (e instanceof ScaffoldError) {
+      process.stderr.write(`${e.message}
+`);
+      return 1;
+    }
+    throw e;
+  }
+  const lines = [`Created ${result.dir}`, ``];
+  for (const rel of result.written) {
+    if (rel.endsWith(".gitkeep")) lines.push(`  ${pad(path2.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`);
   }
-  const out = [
-    `Created ${target}`,
-    ``,
-    `  CLAUDE.md                                what this project is`,
-    `  .claude/skills/house-style/SKILL.md      your look \u2014 edit this first`,
-    `  renders/                                 exports land here`,
-    ...parsed.withMcp ? [`  .mcp.json                                connects your client to After Effects`] : [],
-    ``,
-    `Next:`,
-    `  1. Open the folder in your MCP client:  cd ${parsed.dir}`,
-    `  2. Open After Effects, then ask it to set up After Effects.`,
-    `  3. Fill in .claude/skills/house-style/SKILL.md with your palette, type and timing.`,
-    ...parsed.withMcp ? [] : [
+  lines.push(``, `Next:`);
+  lines.push(`  1. Open the folder in your AI client:  cd ${parsed.dir}`);
+  result.nextSteps.forEach((s, i) => lines.push(`  ${i + 2}. ${s}`));
+  if (result.mcpConfigHint) {
+    lines.push(
+      ``,
+      `${parsed.client} configures servers globally rather than per folder. Add this to`,
+      `${result.mcpConfigHint.path}:`,
       ``,
-      `This folder has no .mcp.json, so your client must already provide the`,
-      `After Effects tools some other way.`
-    ],
-    ``
-  ].join("\n");
-  process.stdout.write(out);
+      result.mcpConfigHint.json.trimEnd()
+    );
+  }
+  lines.push(``);
+  process.stdout.write(lines.join("\n"));
   return 0;
 }
+function pad(s) {
+  return s.padEnd(38);
+}
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 
@@ -232,6 +342,7 @@ __export(schemas_exports, {
   AddMask: () => AddMask,
   AddShapeContent: () => AddShapeContent,
   AddTextAnimator: () => AddTextAnimator,
+  AeGuide: () => AeGuide,
   AwaitJob: () => AwaitJob,
   CancelJob: () => CancelJob,
   CheckSetup: () => CheckSetup,
@@ -251,18 +362,24 @@ __export(schemas_exports, {
   DeleteLayer: () => DeleteLayer,
   DuplicateLayer: () => DuplicateLayer,
   FindLayers: () => FindLayers,
+  GUIDE_TOPICS: () => GUIDE_TOPICS,
   GetComp: () => GetComp,
   GetCompTree: () => GetCompTree,
   GetExpression: () => GetExpression,
+  GetHouseStyle: () => GetHouseStyle,
   GetJob: () => GetJob,
   GetKeyframes: () => GetKeyframes,
   GetLayerFull: () => GetLayerFull,
   GetProjectSummary: () => GetProjectSummary,
+  InitProject: () => InitProject,
   Interpolation: () => Interpolation,
   ListAvailableEffects: () => ListAvailableEffects,
   ListComps: () => ListComps,
   ListEffects: () => ListEffects,
+  ListKnownIssues: () => ListKnownIssues,
   ListLayers: () => ListLayers,
+  LogIssue: () => LogIssue,
+  MarkIssueReported: () => MarkIssueReported,
   OpSchemas: () => OpSchemas,
   ParentLayer: () => ParentLayer,
   PropertyPath: () => PropertyPath,
@@ -280,6 +397,7 @@ __export(schemas_exports, {
   SetEffectEnabled: () => SetEffectEnabled,
   SetEffectParam: () => SetEffectParam,
   SetExpression: () => SetExpression,
+  SetHouseStyle: () => SetHouseStyle,
   SetInterpolation: () => SetInterpolation,
   SetLayer: () => SetLayer,
   SetMask: () => SetMask,
@@ -664,11 +782,41 @@ var FindLayers = z2.object({
   hasEffectMatchName: z2.string().optional()
 });
 var RunJsx = z2.object({ code: z2.string() });
+var GetHouseStyle = z2.object({}).strict();
+var SetHouseStyle = z2.object({
+  content: z2.string().min(1).describe("The complete style guide as markdown. Replaces the file, so send the whole document."),
+  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."),
   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 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.")
+}).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."),
+  name: z2.string().optional().describe("Project name for the generated docs. Defaults to the folder name."),
+  client: z2.enum(["auto", "claude-code", "claude-desktop", "cursor", "vscode", "windsurf", "codex", "generic"]).default("auto").optional().describe("Which client's layout to write. 'auto' detects it from the MCP handshake \u2014 leave it alone unless the user says otherwise."),
+  withMcpConfig: z2.boolean().default(false).optional().describe("Also write a client MCP config pointing at this server. Default false: you are already connected, so the user does not need one.")
+}).strict();
+var LogIssue = z2.object({
+  title: z2.string().min(3).describe("One line naming the problem, specific enough to recognise again. Becomes the entry's id."),
+  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'].")
+}).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.")
+}).strict();
+var MarkIssueReported = z2.object({
+  id: z2.string().describe("The entry id returned by log_issue or list_known_issues."),
+  url: z2.string().optional().describe("Link to the issue that was opened.")
+}).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() });
@@ -742,13 +890,23 @@ var OpSchemas = {
   find_layers: FindLayers,
   // raw
   run_jsx: RunJsx,
+  // house style
+  get_house_style: GetHouseStyle,
+  set_house_style: SetHouseStyle,
   // jobs
   await_job: AwaitJob,
   get_job: GetJob,
   cancel_job: CancelJob,
   // setup
   check_setup: CheckSetup,
-  setup_panel: SetupPanel
+  setup_panel: SetupPanel,
+  init_project: InitProject,
+  // guidance
+  ae_guide: AeGuide,
+  // issue journal
+  log_issue: LogIssue,
+  list_known_issues: ListKnownIssues,
+  mark_issue_reported: MarkIssueReported
 };
 
 // src/util/errors.ts
@@ -793,8 +951,8 @@ var logger = {
 
 // src/bridge/discovery.ts
 import fs2 from "node:fs";
-import os from "node:os";
-import path2 from "node:path";
+import os2 from "node:os";
+import path3 from "node:path";
 var DEFAULT_PORT = 7777;
 function discoverPort() {
   const envPort = process.env.AE_MCP_PORT;
@@ -803,7 +961,7 @@ function discoverPort() {
     if (Number.isFinite(n)) return n;
   }
   try {
-    const f = path2.join(os.homedir(), ".engineroom-ae-mcp", "port");
+    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);
@@ -822,6 +980,8 @@ var HttpClient = class {
     this.port = port ?? discoverPort();
     this.base = `http://127.0.0.1:${this.port}`;
   }
+  // `bundleHash` is absent on panels installed before it was added; callers must
+  // treat undefined as "too old to say" rather than as a mismatch.
   async health() {
     try {
       const r = await fetch(`${this.base}/health`, { signal: AbortSignal.timeout(2e3) });
@@ -1100,24 +1260,34 @@ var descriptions = {
   find_layers: "Search across one or all comps for layers matching name/type/effect filters.",
   // ---------- raw ----------
   run_jsx: "Escape hatch: arbitrary ExtendScript in an undo group. `comp`/`app`/`OPS`/helpers in scope. Use `return X` to send a value back; complex AE objects are coerced to plain props.",
+  // ---------- house style ----------
+  get_house_style: "The user's palette, type, motion and layout defaults for the project that is open, read from `house-style.md` beside the .aep. Call it once before building anything so your work matches the rest of theirs. `found:false` means none exists yet \u2014 build with sensible defaults and offer to capture one afterwards. Cheap; never a reason to skip.",
+  set_house_style: "Write the project's style guide. Replaces the whole file, so read it first and send the merged document \u2014 `overwrite:true` is required to replace an existing one. The project must have been saved at least once, since the file lives beside the .aep. Use the style-guide topic of ae_guide for how to capture a style worth writing down.",
+  // ---------- 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.",
   // ---------- 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.",
   cancel_job: "Set cancel flag; chunked loop stops at next boundary.",
   // ---------- setup ----------
-  check_setup: "Diagnose the After Effects connection: panel installed, up to date, 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, then relay `nextSteps` to the user in plain language.",
-  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 or out of date. 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. Afterwards, AE must be restarted; if the preference was newly enabled, a one-time Mac reboot may also be needed."
+  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.",
+  // ---------- issue journal ----------
+  list_known_issues: "Problems earlier sessions hit with these tools, with the workarounds that worked. Read it when a tool fails in a way you don't immediately understand \u2014 pass `tool` to narrow it to that one \u2014 and before nontrivial work. It can save you rediscovering a fix that already cost someone an hour. Also returns the repo and server version needed to report one.",
+  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."
 };
 
 // src/setup/check.ts
-import crypto from "node:crypto";
-import fs4 from "node:fs";
-import path4 from "node:path";
+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 os2 from "node:os";
-import path3 from "node:path";
+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";
@@ -1125,48 +1295,64 @@ function isSupportedPlatform() {
   return process.platform === "darwin" || process.platform === "win32";
 }
 function packageRoot() {
-  let dir = path3.dirname(fileURLToPath(import.meta.url));
+  let dir = path4.dirname(fileURLToPath(import.meta.url));
   for (let i = 0; i < 8; i++) {
-    if (fs3.existsSync(path3.join(dir, "package.json"))) return dir;
-    const parent = path3.dirname(dir);
+    if (fs3.existsSync(path4.join(dir, "package.json"))) return dir;
+    const parent = path4.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path3.dirname(fileURLToPath(import.meta.url));
+  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 {
+    }
+  }
+  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.
-    path3.resolve(packageRoot(), "..", "ae-panel"),
-    path3.join(packageRoot(), "panel")
+    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(path3.join(dir, "CSXS", "manifest.xml"))) return dir;
+    if (fs3.existsSync(path4.join(dir, "CSXS", "manifest.xml"))) return dir;
   }
   return null;
 }
 function cepExtensionsDir() {
   if (process.platform === "win32") {
-    const appData = process.env.APPDATA ?? path3.join(os2.homedir(), "AppData", "Roaming");
-    return path3.join(appData, "Adobe", "CEP", "extensions");
+    const appData = process.env.APPDATA ?? path4.join(os3.homedir(), "AppData", "Roaming");
+    return path4.join(appData, "Adobe", "CEP", "extensions");
   }
-  return path3.join(os2.homedir(), "Library", "Application Support", "Adobe", "CEP", "extensions");
+  return path4.join(os3.homedir(), "Library", "Application Support", "Adobe", "CEP", "extensions");
 }
 function installedPanelDir() {
-  return path3.join(cepExtensionsDir(), BUNDLE_ID);
+  return path4.join(cepExtensionsDir(), BUNDLE_ID);
 }
 function wsModuleDir() {
   try {
     const require2 = createRequire(import.meta.url);
     const entry = require2.resolve("ws");
-    const marker = `${path3.sep}node_modules${path3.sep}ws${path3.sep}`;
+    const marker = `${path4.sep}node_modules${path4.sep}ws${path4.sep}`;
     const idx = entry.lastIndexOf(marker);
     if (idx >= 0) return entry.slice(0, idx + marker.length - 1);
-    return path3.dirname(entry);
+    return path4.dirname(entry);
   } catch {
-    return null;
+    const beside = path4.join(executableDir(), "node_modules", "ws");
+    return fs3.existsSync(beside) ? beside : null;
   }
 }
 function copyRecursive(src, dst) {
@@ -1174,7 +1360,7 @@ function copyRecursive(src, dst) {
   if (stat.isDirectory()) {
     fs3.mkdirSync(dst, { recursive: true });
     for (const entry of fs3.readdirSync(src)) {
-      copyRecursive(path3.join(src, entry), path3.join(dst, entry));
+      copyRecursive(path4.join(src, entry), path4.join(dst, entry));
     }
   } else if (stat.isSymbolicLink()) {
     fs3.symlinkSync(fs3.readlinkSync(src), dst);
@@ -1183,6 +1369,56 @@ function copyRecursive(src, dst) {
   }
 }
 
+// src/setup/panelVersion.ts
+import crypto from "node:crypto";
+import fs4 from "node:fs";
+import path5 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;
+  return cachedSourceHash;
+}
+function installedBundleHash(installedPanel) {
+  return hashFile(path5.join(installedPanel, "jsx", "bundle.jsx"));
+}
+function hashFile(file) {
+  try {
+    return crypto.createHash("sha256").update(fs4.readFileSync(file)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+var STALE_PANEL_ADVICE = "Tell the user this in plain language, then do it: the After Effects panel is older than these tools and does not understand everything they can do now. Run setup_panel, then ask them to quit and reopen After Effects. Do not retry the failed call until they confirm it has restarted.";
+function assessPanel(runningHash, installedHash) {
+  const shipped = sourceBundleHash();
+  if (!shipped) return { state: "unknown", message: "" };
+  if (runningHash === shipped) return { state: "current", message: "" };
+  if (typeof runningHash !== "string" || runningHash.length === 0) {
+    if (installedHash === shipped) {
+      return {
+        state: "restart-needed",
+        message: "The After Effects panel has been updated on disk, but After Effects is still running the previous version. Ask the user to quit and reopen After Effects, then try again."
+      };
+    }
+    return {
+      state: "unknown",
+      message: "The After Effects panel is too old to report its version, which means it predates these tools. " + STALE_PANEL_ADVICE
+    };
+  }
+  if (installedHash === shipped) {
+    return {
+      state: "restart-needed",
+      message: "The After Effects panel has been updated on disk, but After Effects is still running the previous version. Ask the user to quit and reopen After Effects, then try again. Running setup_panel again will not help \u2014 only a restart loads the new panel."
+    };
+  }
+  return { state: "update-needed", message: `The After Effects panel is out of date. ${STALE_PANEL_ADVICE}` };
+}
+function unknownOpMessage(op) {
+  return `The After Effects panel does not recognise "${op}". That always means the installed panel is older than these tools \u2014 this op did not exist when it was installed. ${STALE_PANEL_ADVICE}`;
+}
+
 // src/setup/platform.ts
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -1263,7 +1499,7 @@ function debugModeLocation() {
 // src/setup/check.ts
 function sha256(file) {
   try {
-    return crypto.createHash("sha256").update(fs4.readFileSync(file)).digest("hex");
+    return crypto2.createHash("sha256").update(fs5.readFileSync(file)).digest("hex");
   } catch {
     return null;
   }
@@ -1272,7 +1508,8 @@ async function bridgeReachable(port) {
   try {
     const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2e3) });
     if (!res.ok) return { ok: false, detail: `port ${port} returned HTTP ${res.status}` };
-    return { ok: true, detail: `responding on port ${port}` };
+    const body = await res.json().catch(() => ({}));
+    return { ok: true, detail: `responding on port ${port}`, bundleHash: body.bundleHash };
   } catch (e) {
     return { ok: false, detail: `no response on port ${port} (${e.message})` };
   }
@@ -1301,7 +1538,7 @@ 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 = fs4.existsSync(path4.join(installed, "CSXS", "manifest.xml"));
+  const isInstalled = fs5.existsSync(path6.join(installed, "CSXS", "manifest.xml"));
   checks.push({
     name: "panelInstalled",
     ok: isInstalled,
@@ -1309,8 +1546,8 @@ async function checkSetup() {
     fix: isInstalled ? void 0 : "Run the setup_panel tool to install it."
   });
   if (isInstalled && source) {
-    const installedHash = sha256(path4.join(installed, "jsx", "bundle.jsx"));
-    const sourceHash = sha256(path4.join(source, "jsx", "bundle.jsx"));
+    const installedHash = sha256(path6.join(installed, "jsx", "bundle.jsx"));
+    const sourceHash = sha256(path6.join(source, "jsx", "bundle.jsx"));
     const upToDate = installedHash !== null && installedHash === sourceHash;
     checks.push({
       name: "panelUpToDate",
@@ -1334,6 +1571,16 @@ async function checkSetup() {
     detail: bridge.detail,
     fix: bridge.ok ? void 0 : "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")));
+    const ok = assessment.state === "current";
+    checks.push({
+      name: "panelRunningCurrent",
+      ok,
+      detail: ok ? "After Effects is running the panel that ships with these tools" : assessment.state === "restart-needed" ? "After Effects is still running the previous panel \u2014 the update needs a restart to take effect" : assessment.state === "unknown" ? "the running panel is too old to report its version" : "After Effects is running a panel older than these tools",
+      fix: ok ? void 0 : assessment.message
+    });
+  }
   if (bridge.ok && !isInstalled) {
     checks.push({
       name: "panelIdentity",
@@ -1366,8 +1613,8 @@ function buildNextSteps(checks, ready) {
     steps.push(identity.fix);
   }
   if (by("afterEffectsRunning")?.ok === false) {
-    steps.push("Open After Effects 2026.");
-  } else if (needsInstall) {
+    steps.push(needsInstall ? "Open After Effects 2026 \u2014 the panel loads with it." : "Open After Effects 2026.");
+  } else if (needsInstall || by("panelRunningCurrent")?.ok === false) {
     steps.push("Quit and reopen After Effects so it picks up the panel.");
   }
   if (steps.length === 0 && by("bridgeReachable")?.ok === false) {
@@ -1378,8 +1625,8 @@ function buildNextSteps(checks, ready) {
 }
 
 // src/setup/install.ts
-import fs5 from "node:fs";
-import path5 from "node:path";
+import fs6 from "node:fs";
+import path7 from "node:path";
 async function installPanel(opts = {}) {
   const actions = [];
   const notes = [];
@@ -1392,13 +1639,13 @@ 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 (!fs5.existsSync(path5.join(source, "jsx", "bundle.jsx"))) {
+  if (!fs6.existsSync(path7.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 target = installedPanelDir();
-  const existing = fs5.lstatSync(target, { throwIfNoEntry: false });
+  const existing = fs6.lstatSync(target, { throwIfNoEntry: false });
   if (existing?.isSymbolicLink() && !opts.force) {
-    const linkTarget = fs5.readlinkSync(target);
+    const linkTarget = fs6.readlinkSync(target);
     return {
       ok: true,
       panelPath: target,
@@ -1412,17 +1659,17 @@ async function installPanel(opts = {}) {
     };
   }
   if (existing) {
-    fs5.rmSync(target, { recursive: true, force: true });
+    fs6.rmSync(target, { recursive: true, force: true });
     actions.push("Removed the previously installed panel.");
   }
-  fs5.mkdirSync(path5.dirname(target), { recursive: true });
+  fs6.mkdirSync(path7.dirname(target), { recursive: true });
   copyRecursive(source, target);
   actions.push(`Installed the panel to ${target}.`);
   const ws = wsModuleDir();
   if (ws) {
-    const dest = path5.join(target, "node_modules", "ws");
-    fs5.mkdirSync(path5.dirname(dest), { recursive: true });
-    fs5.rmSync(dest, { recursive: true, force: true });
+    const dest = path7.join(target, "node_modules", "ws");
+    fs6.mkdirSync(path7.dirname(dest), { recursive: true });
+    fs6.rmSync(dest, { recursive: true, force: true });
     copyRecursive(ws, dest);
     actions.push("Copied the `ws` module the panel needs at runtime.");
   } else {
@@ -1456,6 +1703,255 @@ async function installPanel(opts = {}) {
   };
 }
 
+// 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## Install before they open After Effects, if you still can\n\nThe panel loads at launch and only at launch. So the order matters, and it is\nthe opposite of what people assume:\n\n- **After Effects is closed** \u2014 install now. When they open it, the panel is\n  simply there. No restart, nothing to ask for. This is the good path, and on a\n  first-time setup you can usually get it.\n- **After Effects is open** \u2014 install, then they have to quit and reopen it.\n  Unavoidable, but worth avoiding: if they have not opened AE yet in this\n  conversation, do the install *first* and tell them to open it after.\n\n`check_setup` reports `afterEffectsRunning`, so you always know which case you\nare in before you say anything.\n\n## The repair path\n\n1. **`check_setup`** \u2014 find out what is actually wrong.\n2. **`setup_panel`** \u2014 if the panel is missing or out of date. Tell the user what it will do *before* you call it: it copies the panel into their Adobe extensions folder and switches on the Adobe preference that permits unsigned panels. Both changes are user-level and reversible.\n3. **Get the panel loaded.** If AE was closed, ask them to open it. If it was already open, ask them to quit and reopen it. You cannot do either for them.\n4. **`check_setup`** again to confirm.\n\n## What the individual failures mean\n\n| Check | Meaning when it fails |\n|---|---|\n| `platform` | Not macOS or Windows. After Effects only runs on those two, so there is nothing to fix. |\n| `panelAssetsPresent` | The server package is incomplete \u2014 it needs reinstalling. |\n| `cepDebugMode` | Adobe refuses to load unsigned panels until this preference is on. `setup_panel` sets it. |\n| `panelInstalled` | The panel is not in the Adobe extensions folder yet. `setup_panel` installs it. |\n| `panelUpToDate` | The files on disk are older than this server. Run `setup_panel`. |\n| `panelRunningCurrent` | AE is *running* an older panel than these tools ship. This is the one that predicts whether calls will actually work \u2014 `panelUpToDate` can pass while this fails, for the whole window between installing an update and restarting AE. |\n| `afterEffectsRunning` | AE is closed. If the panel also needs installing, install it now and then ask them to open AE \u2014 that saves a restart. |\n| `bridgeReachable` | Everything is installed but the panel isn't answering \u2014 almost always fixed by restarting AE. |\n\n## The reboot case\n\n`cepDebugMode` is an Adobe preference that, on some macOS builds, only takes effect after a **restart of the Mac** \u2014 not just of After Effects. If `setup_panel` reports `rebootRecommended: true` and restarting AE alone did not fix it, ask the user to reboot once. This is a one-time cost, never needed again.\n\n## When a tool says the panel is out of date\n\nYou may get an error saying the panel is older than these tools, or that it does\nnot recognise an op. That is a version mismatch, not a broken tool, and the\nmessage tells you which of the two fixes applies:\n\n- **\"updated on disk \u2026 still running the previous version\"** \u2014 `setup_panel` has\n  already done its part. Only a restart of After Effects will help; running it\n  again will not.\n- **anything else** \u2014 run `setup_panel`, then get AE restarted.\n\nEither way, do not retry the failed call until the user confirms AE has\nrestarted. Say it as a version mismatch in plain language, not as a failure:\ntheir tools moved ahead of the panel, and it takes a restart to catch up.\n\n## If it still will not connect\n\nAsk the user to open **Window > Extensions > AE MCP Bridge** inside After Effects. That panel shows its own status and a log, and will say whether it started, which port it took, or what error it hit. Have them read it back to you.\n\nA common cause is a stale install: the panel loaded an older script bundle than the server expects. `check_setup`'s `panelUpToDate` catches that \u2014 the fix is `setup_panel` followed by an AE restart."
+  },
+  {
+    name: "after-effects",
+    description: "How to drive Adobe After Effects well through the AE MCP tools \u2014 orienting in a project, building and animating layers, keyframes and easing, expressions, effects, text and shapes, and the gotchas that silently produce wrong output. Load whenever a task involves After Effects, motion graphics, comps, layers, or keyframes.",
+    body: '# Driving After Effects\n\nYou have direct control of a live After Effects session. The user sees every change immediately, and every tool call is a real undo step in their project. Work like a motion designer at the keyboard, not like a script that fires blind.\n\n## Read the house style first\n\n`get_house_style` returns the style guide for the project that is currently open\n\u2014 palette, type, motion defaults, layout rules \u2014 read from `house-style.md`\nsitting next to the `.aep` file. Call it once at the start of any build task and\nfollow what it says. It costs one cheap call and it is the difference between\nwork that matches everything else the user has made and work that does not.\n\nIf it reports `found: false`, build with sensible defaults and offer once, at the\nend, to capture a style guide from what you just made. Don\'t nag about it.\n\n## Orient before you touch anything\n\nNever guess at project state. Cheap reads exist for exactly this:\n\n| Question | Tool |\n|---|---|\n| What\'s in this project? | `get_project_summary` |\n| What comps exist? | `list_comps` |\n| What\'s in this comp? | `get_comp_tree` |\n| Everything about one layer | `get_layer_full` \u2B50 |\n| Where is a layer, by name/type/effect? | `find_layers` |\n\n`get_layer_full` is the one to reach for. It returns transforms **with their keyframes and expressions**, effects with every parameter, masks, markers, and `sourceRect` (the layer\'s visible bounds) in a single call. Prefer one `get_layer_full` over four narrow queries \u2014 it is faster and it shows you context you did not know to ask for.\n\n## Identify things by ID, never by index\n\nEvery comp and layer has a stable numeric `id`. Layer `index` is a 1-based position that **shifts whenever layers are added, deleted, or reordered**. Store `(compId, layerId)` and pass those. An index captured before a `create_*` call may point at a different layer by the time you use it.\n\n## Read, then write, then verify\n\n1. Read the current state (`get_layer_full`).\n2. Make the change.\n3. Verify by reading back the properties \u2014 not by screenshotting.\n\nProperty values are the ground truth. A screenshot tells you something *looks* wrong; `get_layer_full` tells you *why*.\n\n## Screenshots are a diagnostic, not a feedback loop\n\n`screenshot_frame` and `screenshot_layer` are **one-off checks**. Do not screenshot every frame, do not scrub through time, do not screenshot after every edit.\n\n- Take at most 2\u20133 across an animation \u2014 typically start, middle, end.\n- **Always pass `downsample`** on large comps: `2` for 1080p, `3`\u2013`4` for 4K. A full-resolution 4K frame is large enough to blow out your context in one call.\n- The result reports the dimensions actually returned and warns if the downsample could not be applied \u2014 trust those numbers rather than assuming.\n\nTo check motion, read the keyframe values. That is exact; a picture is not.\n\n## Bulk work goes through run_batch\n\nBuilding 40 layers with 40 separate calls is slow and produces 40 undo steps. `run_batch` runs many ops in one ExtendScript pass as a **single undo step**, which is also what the user expects when they ask to undo "that thing you just built".\n\n- `transactional: true` (the default) rolls back the whole batch on the first error.\n- Over 500 ops it returns a `jobId` and streams progress; call `await_job(jobId)` for the final result.\n\n## Keyframes and easing\n\n`add_keyframe` sets a value at a time. Interpolation is separate:\n\n- `set_interpolation` \u2014 linear / bezier / hold, per keyframe, in and out.\n- `set_temporal_ease` \u2014 influence and speed, the "easy ease" controls.\n- `set_spatial_tangents` \u2014 the shape of a motion path through a position keyframe.\n\n**The array-size trap.** `set_temporal_ease` wants one ease entry *per dimension* for ordinary multi-dimensional properties (Scale, Color), but exactly **one** entry for spatial properties (Position, Anchor Point) regardless of whether the layer is 2D or 3D \u2014 because the ease applies along the motion path, not per axis. If you see `Value array does not have 1 elements`, you fed a spatial property one entry per axis.\n\n## Expressions\n\n`set_expression` takes a `propertyPath` such as `["Transform","Position"]` or `["Effects","Gaussian Blur","Blurriness"]`. Expressions are ExtendScript-flavoured JavaScript evaluated by AE per frame.\n\nExpressions are usually a better answer than dense keyframes for anything procedural \u2014 wiggle, loops, counters, follow-through, time remapping. They stay editable by the user afterwards, where a wall of baked keyframes does not.\n\nUse `get_expression` to read one back and `toggle_expression` to disable without deleting.\n\n## Effects\n\nEffects are added by **matchName**, not display name: `add_effect({matchName: "ADBE Gaussian Blur 2"})`. If you do not know a matchName, call `list_available_effects` and search it \u2014 do not guess. `list_effects` shows what is already on a layer, with every parameter.\n\nSet parameters with `set_effect_param` by parameter name (e.g. `"Blurriness"`).\n\n## Text\n\n`create_text_layer` places **point text anchored at the bounding-box centre**, which is not where you would expect from the visible left edge. The tool defaults to `anchorAlign: "left"` so that `position` lines up with the left edge as a designer would read it. Pass `"center"` or `"right"` when you want those, `"none"` for AE\'s raw behaviour.\n\n`set_text` controls font, size, colour, tracking, leading and justification. To auto-fit a background to text, read `sourceRect` from `get_layer_full` and size the shape from its width and height plus padding.\n\n## Shapes\n\n`add_shape_content` builds one node at a time under `Contents` \u2014 `rect`, `ellipse`, `star`, `path`, `fill`, `stroke`, `trim`, `repeater`, `merge`, `group`. Properties are set with friendly names in the same call (`size`, `position`, `roundness`, `color`, `width`, `lineCap`, \u2026).\n\nThis tool is **all-or-nothing**: if a key cannot be applied, the whole node is removed and you get an error naming the bad key. A success result therefore means everything landed. Don\'t add defensive re-reads for it, but do read the error carefully \u2014 it usually means the property is named differently on that node type, and `get_layer_full` will show you the real name.\n\nFor a custom path, use `{type: "path", vertices: [[x,y], \u2026], closed: true}`. The key is `vertices`, not `points`.\n\n## The escape hatch\n\n`run_jsx` executes arbitrary ExtendScript with `app`, `comp`, `OPS` and the helper functions in scope. Reach for it when a needed operation has no tool \u2014 duplicating a comp, driving the render queue, batch-renaming.\n\nTwo warnings: ExtendScript is **single-threaded**, so a long synchronous loop freezes the user\'s AE UI; and returned objects are flattened, so return a string you have assembled yourself rather than a nested object.\n\n## When something costs you real time\n\nThese tools have rough edges, and the same ones catch every session. Two tools\nexist so that each one is only paid for once.\n\n**`list_known_issues`** \u2014 what earlier sessions hit and how they got past it.\nRead it when a tool fails in a way you do not immediately understand, before you\nstart guessing. The answer is often already there.\n\n**`log_issue`** \u2014 write down what you worked out, the moment you work it out.\n\nLog something when all three are true: it cost real effort, it was the tool\'s\nfault rather than yours, and the next session would hit it too. A schema that\naccepts an argument AE then rejects, an error message that names the wrong\nthing, a property whose real name is nothing like its display name. Not your own\ntypos. Not "I forgot the layer was 3D".\n\nWrite the entry for someone who has not seen the failure: the exact error text,\nthe call that produced it, and a workaround concrete enough to apply directly.\nReuse the existing title when you are extending an entry \u2014 that keeps one good\nrecord instead of five thin ones.\n\n### Then offer to pass it on\n\nIf `log_issue` comes back with `reported: false`, mention it to the user \u2014 but\nfinish the actual work first, and put it at the very end, after you have told\nthem what you built. It is a footnote, not the headline.\n\nSay it the way you would to a colleague who does not write code. What you were\ntrying to do, that it fought back, that you got there anyway, and that you can\nsend it to the people who maintain the tool so the next person does not lose the\nsame time. Something like:\n\n> Done \u2014 the lower third is in. One thing worth mentioning: getting the ease\n> onto that position keyframe took a lot longer than it should have, because the\n> tool kept rejecting a value it had just asked for. I found a way around it and\n> made a note. Want me to send it to the people who maintain this so they can\n> fix it properly?\n\nDo not say "GitHub issue", "file a bug" or "open a ticket" unless they say it\nfirst. If they say yes, use the **report-ae-issue** prompt this server provides\n(`/report-ae-issue` where your client exposes prompts as commands) \u2014 it handles\nthe rest. If they say no, drop it; the note stays and can be offered again\nanother time.\n\nNever claim you have reported something you have not.\n\n## When something is not connected\n\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay its `nextSteps` to the user in plain language. Do not try to diagnose CEP by hand.'
+  },
+  {
+    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```'
+  }
+];
+var PROMPTS = [
+  {
+    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",
+    argumentHint: "[the comp to learn the style from, if you have one in mind]",
+    body: "# Set up the style guide\n\nThe user wants everything you build to look like *their* work rather than\ngeneric motion graphics. That is what the style guide is for. It is saved as\n`house-style.md` next to their After Effects project and read before every build.\n\n`$ARGUMENTS` may name a comp to learn from.\n\nLoad the `style-guide` topic of `ae_guide` and follow it. In short:\n\n1. `get_house_style` first. If one exists, you are editing, not creating \u2014 read\n   it, keep what is there, and send the whole merged document back.\n2. Prefer reading the style off work they already like over asking them to\n   describe it. Ask which comp, then `get_comp` and `get_layer_full` on the\n   layers that carry the look, and `get_keyframes` for the timing signature.\n3. Show what you found in plain language and let them correct it. Adjectives\n   from you, numbers in the file.\n4. Write it with `set_house_style` (`overwrite: true` when replacing), then tell\n   them where it is and that they can edit it in any text editor.\n\nTwo things that will stop you: the project must have been **saved** at least\nonce, and `set_house_style` replaces the whole file rather than patching it.\n\nIf they have nothing to learn from, do not run a long interview. Ask four\nquestions with concrete options, build one small example, screenshot it, and\nrefine from their reaction \u2014 reacting is much easier than specifying."
+  },
+  {
+    name: "init-after-effects",
+    description: "Set up After Effects from scratch \u2014 install the panel, create a project folder, and capture a house style",
+    argumentHint: "[folder to set the project up in, if you know it]",
+    body: "# Set up After Effects\n\nThe user has just connected these tools and wants to start working. Take them\nall the way from nothing to a first build. They are a motion designer, not a\ndeveloper \u2014 they should never be asked to open a terminal, edit JSON, or read a\nfile path they did not ask about.\n\n`$ARGUMENTS` is the folder they named, if they named one.\n\nWork through these in order, and **stop at the first one that needs something\nfrom them**. Do not run ahead and report four steps at once.\n\n## 1. Install the panel \u2014 before they open After Effects\n\nCall `check_setup`. It is read-only and safe.\n\n**Do not ask them to open After Effects yet.** The panel only loads when AE\nlaunches, so installing while AE is still closed means it is simply there when\nthey open it \u2014 no restart to ask for. If AE is already running you have to ask\nfor one, which is why this step comes first.\n\n- **Everything green** \u2014 say so in one line and move on.\n- **Anything red** \u2014 explain what `setup_panel` is about to do before calling\n  it: it copies a small panel into their Adobe extensions folder and switches on\n  the Adobe setting that allows unsigned panels. Both are user-level and\n  reversible. Call it, then:\n  - if `afterEffectsRunning` was false, ask them to **open** After Effects;\n  - if it was true, ask them to **quit and reopen** it.\n\n  Then `check_setup` again to confirm.\n\nIf it still fails, load the `ae-setup` topic of `ae_guide` and work through it.\nDo not improvise CEP diagnostics.\n\n## 2. Where does the project live?\n\nCall `init_project`. Pass `dir` when you know it \u2014 from `$ARGUMENTS`, or from\nwhat the user says. If you do not know, **ask before calling**: \"which folder\nshould this project live in? A new empty one is fine.\"\n\nNever invent a path. If the tool reports it could not work out where to write,\nthat is exactly what it means \u2014 ask, then call again with `dir`.\n\nTell them the folder it created and what is in it, in one sentence. Do not paste\nthe file list.\n\n## 3. Now bring up After Effects\n\nBy this point the panel is installed, so this is the moment to have them open\nAfter Effects and load the project they want to work on \u2014 or create one and\n**save** it. Saving matters: the style guide is written next to the .aep, and an\nunsaved project has no folder to put it in.\n\n`get_project_summary` will tell you what is open.\n\n## 4. Offer a style guide\n\nCall `get_house_style`. If one already exists, say what it covers and stop \u2014\nthey are set up.\n\nIf not, offer it in their terms:\n\n> Do you want me to set up a style guide? If you point me at a comp that already\n> looks the way you like, I'll read the colours, fonts and timing off it and save\n> them next to your project. Everything I build afterwards follows it.\n\nIf they say yes, load the `style-guide` topic of `ae_guide` and follow it \u2014 read\na comp they nominate, show them what you found in plain language, and write it\nwith `set_house_style`. If they say no, drop it; it can be offered again later.\n\n## 5. Hand over\n\nClose with one short paragraph: they are set up, and here is the kind of thing\nthey can now ask for. Give one concrete example rather than a list of features:\n\n> You're set. Try something like \"build a lower third that says Chapter One and\n> slides in from the left\" \u2014 I'll read the comp, build it, and you'll see it\n> happen in After Effects."
+  },
+  {
+    name: "report-ae-issue",
+    description: "Send a problem you hit with the After Effects tools to the people who maintain them",
+    argumentHint: "[what went wrong, in your own words]",
+    body: '# Report a problem with the After Effects tools\n\nThe user wants to tell the maintainers about something that did not work. They are\nmost likely a motion designer, not a developer: they may never have seen GitHub,\nand they should not have to. Do the technical part yourself and only ask them\nthings they can actually answer.\n\n`$ARGUMENTS` is what they typed, if anything.\n\n## 1. Find out what to report\n\nCall `list_known_issues` with `status: "unreported"`. It returns entries earlier\nsessions wrote down, plus `repo`, `newIssueUrl`, `serverVersion` and `platform`.\n\n- **Entries exist** \u2014 show them as a short numbered list, one plain sentence each\n  ("Text layers ended up in the wrong place when a font was missing"), not the\n  raw titles. Ask which to send; offer "all of them" as an option.\n- **No entries, but `$ARGUMENTS` describes something** \u2014 work from that. Ask what\n  they were trying to do and what happened instead, then `log_issue` it so it is\n  recorded before you send it.\n- **Nothing either way** \u2014 say there is nothing recorded to send, and that you\n  will write things down as you hit them from now on. Stop there.\n\n## 2. Draft it\n\nShort. A maintainer should understand the problem in fifteen seconds.\n\n**Title:** one line, concrete. `set_temporal_ease fails on Position with "Value\narray does not have 1 elements"` \u2014 not `Keyframe bug`.\n\n**Body:** four short sections, a couple of sentences each.\n\n```markdown\n**What happens**\n<the failing call and the exact error, or the wrong result>\n\n**Why** (if known)\n<one line \u2014 omit this section entirely if unknown>\n\n**Workaround**\n<what got past it>\n\n**Environment**\nafter-effects-mcp <serverVersion> \xB7 <platform> \xB7 After Effects 2026\n```\n\nInclude the failing call and error text verbatim \u2014 that is the part that makes it\nfixable. Leave out the user\'s own content: comp and layer names from their\nproject, file paths, client names, anything about the video they are making. If a\ndetail like that is load-bearing, replace it with a placeholder.\n\n## 3. Show it and get a yes\n\nShow the finished title and body and ask whether to send it. This posts publicly\nto a repository under their name if `gh` is authenticated, so it needs a real\nanswer, not an assumption. If they want to change the wording, change it.\n\n## 4. Send it\n\nTry `gh` first:\n\n```bash\ngh issue create --repo <repo> --title "<title>" --body "<body>"\n```\n\nIf `gh` is missing or not authenticated, do not try to install or configure it.\nBuild a prefilled link instead \u2014 URL-encode the title and body onto\n`<newIssueUrl>` as `?title=\u2026&body=\u2026` \u2014 and give it to them with one line of\ninstruction: open this, it will already be filled in, press the green button. A\nGitHub account is needed to press it; if they do not have one, say so plainly and\noffer to write the text out for them to send another way.\n\n## 5. Close the loop\n\nOn success, call `mark_issue_reported` with the entry `id` and the URL, so no\nlater session asks them to report the same thing twice. Then tell them where it\nwent, in one sentence, with the link.\n\nIf they decline, leave the entry alone \u2014 it stays unreported and can be offered\nagain another day. Do not mark it.'
+  }
+];
+var GUIDE_NAMES = GUIDES.map((g) => g.name);
+function getGuide(name) {
+  return GUIDES.find((g) => g.name === name);
+}
+function getPrompt(name) {
+  return PROMPTS.find((p) => p.name === name);
+}
+var SERVER_INSTRUCTIONS = "You are driving a live After Effects session through this server. The user sees\nevery change as it happens and every call is a real undo step in their project.\n\nSix things that are not obvious from the tool list:\n\n1. Read the house style before you build. `get_house_style` returns the user's\n   palette, type and motion defaults for the project that is open. One cheap call.\n2. Orient before you touch anything. `get_layer_full` returns a layer's\n   transforms with keyframes and expressions, every effect and parameter, masks,\n   markers and visible bounds in a single call \u2014 prefer it over several narrow reads.\n3. Identify by id, never by index. Layer `index` shifts whenever layers are\n   added, deleted or reordered. Carry `(compId, layerId)`.\n4. Verify by reading properties back, not by screenshotting. Screenshots are\n   one-off diagnostics: 2-3 across an animation, and always pass `downsample`\n   (2 for 1080p, 3-4 for 4K) or a single frame can fill your context.\n5. Bulk work goes through `run_batch` \u2014 one ExtendScript pass, one undo step.\n6. When a tool fails in a way you do not understand, call `list_known_issues`\n   before guessing; an earlier session may have solved it already. When you solve\n   a new one, `log_issue` it.\n\nCall `ae_guide` for the full guidance on any of this \u2014 topics: ae-setup, after-effects, style-guide.\nIf a tool reports it cannot reach After Effects, call `check_setup` and relay\nits `nextSteps` verbatim; do not diagnose CEP by hand.";
+
+// src/issues/journal.ts
+import fs7 from "node:fs";
+import os4 from "node:os";
+import path8 from "node:path";
+var REPO = "Engine-Room-Games/after-effects-mcp";
+var NEW_ISSUE_URL = `https://github.com/${REPO}/issues/new`;
+var SECTION_SYMPTOM = "What went wrong";
+var SECTION_CAUSE = "Why";
+var SECTION_WORKAROUND = "What worked";
+function journalRoot() {
+  const override = process.env.AE_MCP_HOME?.trim();
+  if (override && override.length > 0) return { dir: override, scope: "project" };
+  const cwd = process.cwd();
+  const unusable = cwd === path8.parse(cwd).root || cwd === os4.homedir();
+  if (!unusable) {
+    try {
+      fs7.accessSync(cwd, fs7.constants.W_OK);
+      return { dir: path8.join(cwd, ".ae-mcp"), scope: "project" };
+    } catch {
+    }
+  }
+  return { dir: path8.join(os4.homedir(), ".after-effects-mcp"), scope: "home" };
+}
+function journalDir() {
+  return path8.join(journalRoot().dir, "issues");
+}
+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");
+  return issues;
+}
+function slugify(text) {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : `issue-${Date.now()}`;
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+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}`);
+  return file;
+}
+function render(entry) {
+  const lines = [
+    "---",
+    `id: ${entry.id}`,
+    `title: ${oneLine(entry.title)}`,
+    `tools: ${entry.tools.join(", ")}`,
+    `firstSeen: ${entry.firstSeen}`,
+    `lastSeen: ${entry.lastSeen}`,
+    `occurrences: ${entry.occurrences}`,
+    `reported: ${entry.reported}`,
+    `issueUrl: ${entry.issueUrl ?? ""}`,
+    "---",
+    "",
+    `## ${SECTION_SYMPTOM}`,
+    "",
+    entry.symptom.trim(),
+    ""
+  ];
+  if (entry.cause && entry.cause.trim().length > 0) {
+    lines.push(`## ${SECTION_CAUSE}`, "", entry.cause.trim(), "");
+  }
+  lines.push(`## ${SECTION_WORKAROUND}`, "", entry.workaround.trim(), "");
+  return lines.join("\n");
+}
+function readSections(body) {
+  const marks = [];
+  for (const heading of [SECTION_SYMPTOM, SECTION_CAUSE, SECTION_WORKAROUND]) {
+    const m = new RegExp(`^##[ \\t]+${heading}[ \\t]*$`, "im").exec(body);
+    if (m) marks.push({ key: heading.toLowerCase(), from: m.index, to: m.index + m[0].length });
+  }
+  marks.sort((a, b) => a.from - b.from);
+  const sections = /* @__PURE__ */ new Map();
+  marks.forEach((mark, i) => {
+    const end = i + 1 < marks.length ? marks[i + 1].from : body.length;
+    sections.set(mark.key, body.slice(mark.to, end).trim());
+  });
+  return sections;
+}
+function parse(text, fallbackId) {
+  const meta = {};
+  let body = text;
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (fm) {
+    for (const line of fm[1].split(/\r?\n/)) {
+      const sep = line.indexOf(":");
+      if (sep <= 0) continue;
+      meta[line.slice(0, sep).trim()] = line.slice(sep + 1).trim();
+    }
+    body = text.slice(fm[0].length);
+  }
+  const sections = readSections(body);
+  const occurrences = Number.parseInt(meta.occurrences ?? "1", 10);
+  return {
+    id: meta.id || fallbackId,
+    title: meta.title || fallbackId.replace(/-/g, " "),
+    tools: (meta.tools ?? "").split(",").map((t) => t.trim()).filter((t) => t.length > 0),
+    firstSeen: meta.firstSeen || "",
+    lastSeen: meta.lastSeen || meta.firstSeen || "",
+    occurrences: Number.isFinite(occurrences) && occurrences > 0 ? occurrences : 1,
+    reported: meta.reported === "true",
+    issueUrl: meta.issueUrl && meta.issueUrl.length > 0 ? meta.issueUrl : void 0,
+    // 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() : ""),
+    cause: sections.get(SECTION_CAUSE.toLowerCase()) || void 0,
+    workaround: sections.get(SECTION_WORKAROUND.toLowerCase()) ?? ""
+  };
+}
+function readEntry(file) {
+  try {
+    return parse(fs7.readFileSync(file, "utf8"), path8.basename(file, ".md"));
+  } catch {
+    return null;
+  }
+}
+function logIssue(input) {
+  const id = slugify(input.title);
+  const file = entryPath(id);
+  const existing = fs7.existsSync(file) ? readEntry(file) : null;
+  const entry = {
+    id,
+    title: oneLine(input.title),
+    tools: input.tools ?? existing?.tools ?? [],
+    firstSeen: existing?.firstSeen || today(),
+    lastSeen: today(),
+    // 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.
+    reported: existing?.reported ?? false,
+    issueUrl: existing?.issueUrl,
+    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");
+  return {
+    id,
+    path: file,
+    occurrences: entry.occurrences,
+    previouslyLogged: existing !== null,
+    reported: entry.reported,
+    issueUrl: entry.issueUrl
+  };
+}
+function listIssues(status = "all", tool) {
+  const { scope } = journalRoot();
+  const dir = journalDir();
+  let entries = [];
+  try {
+    entries = fs7.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => readEntry(path8.join(dir, f))).filter((e) => e !== null);
+  } catch {
+    entries = [];
+  }
+  const wanted = tool?.trim().toLowerCase();
+  const filtered = entries.filter((e) => {
+    const byStatus = status === "all" ? true : status === "reported" ? e.reported : !e.reported;
+    if (!byStatus) return false;
+    if (!wanted) return true;
+    return e.tools.some((t) => t.toLowerCase() === wanted) || e.title.toLowerCase().includes(wanted);
+  });
+  filtered.sort((a, b) => b.lastSeen.localeCompare(a.lastSeen) || b.occurrences - a.occurrences);
+  return {
+    dir,
+    scope,
+    repo: REPO,
+    newIssueUrl: NEW_ISSUE_URL,
+    serverVersion: packageVersion(),
+    platform: process.platform,
+    count: filtered.length,
+    issues: filtered
+  };
+}
+function markReported(id, url) {
+  const file = entryPath(slugify(id));
+  const entry = fs7.existsSync(file) ? readEntry(file) : null;
+  if (!entry) {
+    const known = listIssues("all").issues.map((e) => e.id);
+    throw new Error(
+      `No journal entry with id "${id}".` + (known.length > 0 ? ` Known ids: ${known.join(", ")}` : "")
+    );
+  }
+  entry.reported = true;
+  if (url) entry.issueUrl = oneLine(url);
+  fs7.writeFileSync(file, render(entry), "utf8");
+  return entry;
+}
+
 // src/util/pngImage.ts
 function imageContent(meta, base64) {
   return {
@@ -1467,22 +1963,42 @@ function imageContent(meta, base64) {
 }
 
 // src/server.ts
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 var { OpSchemas: OpSchemas2 } = schemas_exports;
 var VISION_OPS = /* @__PURE__ */ new Set(["screenshot_frame", "screenshot_layer"]);
 var ASYNC_OPS = /* @__PURE__ */ new Set(["run_batch"]);
-var SERVER_OPS = /* @__PURE__ */ new Set(["await_job", "get_job", "cancel_job", "check_setup", "setup_panel"]);
+var SERVER_OPS = /* @__PURE__ */ new Set([
+  "await_job",
+  "get_job",
+  "cancel_job",
+  "check_setup",
+  "setup_panel",
+  "init_project",
+  "ae_guide",
+  "log_issue",
+  "list_known_issues",
+  "mark_issue_reported"
+]);
+var GUIDE_URI_PREFIX = "ae://guide/";
 var AwaitJobSchema = schemas_exports.AwaitJob;
 var GetJobSchema = schemas_exports.GetJob;
 var CancelJobSchema = schemas_exports.CancelJob;
 function createServer() {
   const server = new Server(
-    { name: "after-effects-mcp", version: "0.1.1" },
-    { capabilities: { tools: {}, logging: {} } }
+    { name: "after-effects-mcp", version: "0.2.0" },
+    {
+      capabilities: { tools: {}, logging: {}, prompts: {}, resources: {} },
+      // Clients that honour this fold it into the system prompt, which is the
+      // only way non-Claude clients get the cross-cutting guidance at all —
+      // skills and slash commands do not exist outside Claude's own clients.
+      instructions: SERVER_INSTRUCTIONS
+    }
   );
   const bridge = new HttpClient();
   const jobs = new JobManager();
   const ws = new WsClient(bridge.port, jobs);
   ws.start();
+  const panelGate = createPanelGate(bridge);
   bridge.health().then(
     (h) => logger.info(`Bridge healthy on port ${h.port}`),
     (e) => logger.warn(`Bridge not reachable yet: ${e.message}`)
@@ -1502,6 +2018,41 @@ function createServer() {
     });
     return { tools };
   });
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: PROMPTS.map((p) => ({
+      name: p.name,
+      description: p.description,
+      arguments: p.argumentHint ? [{ name: "arguments", description: p.argumentHint, required: false }] : []
+    }))
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+    const prompt = getPrompt(req.params.name);
+    if (!prompt) throw new Error(`Unknown prompt: ${req.params.name}`);
+    const given = req.params.arguments?.arguments ?? "";
+    return {
+      description: prompt.description,
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: prompt.body.replaceAll("$ARGUMENTS", given) }
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: GUIDES.map((g) => ({
+      uri: `${GUIDE_URI_PREFIX}${g.name}`,
+      name: g.name,
+      description: g.description,
+      mimeType: "text/markdown"
+    }))
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    const uri = req.params.uri;
+    const guide = uri.startsWith(GUIDE_URI_PREFIX) ? getGuide(uri.slice(GUIDE_URI_PREFIX.length)) : void 0;
+    if (!guide) throw new Error(`Unknown resource: ${uri}`);
+    return { contents: [{ uri, mimeType: "text/markdown", text: guide.body }] };
+  });
   server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
     const name = req.params.name;
     const rawArgs = req.params.arguments ?? {};
@@ -1533,8 +2084,41 @@ function createServer() {
         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() });
         }
+        if (name === "init_project") {
+          const a = schemas_exports.InitProject.parse(rawArgs);
+          const client = !a.client || a.client === "auto" ? detectClient(server.getClientVersion()?.name) : a.client;
+          return textResult(
+            scaffold({
+              dir: a.dir,
+              name: a.name,
+              client,
+              withMcpConfig: a.withMcpConfig ?? false,
+              roots: a.dir ? void 0 : await clientRoots(server)
+            })
+          );
+        }
+        if (name === "ae_guide") {
+          const a = schemas_exports.AeGuide.parse(rawArgs);
+          const guide = getGuide(a.topic);
+          if (!guide) return errorResult(`Unknown guide topic: ${a.topic}`);
+          return { content: [{ type: "text", text: guide.body }] };
+        }
+        if (name === "log_issue") {
+          const a = schemas_exports.LogIssue.parse(rawArgs);
+          return textResult(logIssue(a));
+        }
+        if (name === "list_known_issues") {
+          const a = schemas_exports.ListKnownIssues.parse(rawArgs);
+          return textResult(listIssues(a.status ?? "all", a.tool));
+        }
+        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 });
+        }
       } catch (e) {
         return errorResult(e.message);
       }
@@ -1545,6 +2129,8 @@ function createServer() {
     } catch (e) {
       return errorResult(`Invalid arguments for ${name}: ${e.message}`);
     }
+    const staleness = await panelGate.check();
+    if (staleness) return errorResult(staleness);
     try {
       const result = await bridge.runOp(name, args, progressToken);
       if (ASYNC_OPS.has(name) && isAsyncEnvelope(result)) {
@@ -1583,12 +2169,54 @@ function createServer() {
       return textResult(result);
     } catch (e) {
       if (e instanceof BridgeUnreachableError) return errorResult(e.message);
-      if (e instanceof AeError) return errorResult(`AE: ${e.message}${e.line ? ` (line ${e.line})` : ""}`);
+      if (e instanceof AeError) {
+        if (/^Unknown op: /.test(e.message)) {
+          panelGate.invalidate();
+          return errorResult(unknownOpMessage(name));
+        }
+        return errorResult(`AE: ${e.message}${e.line ? ` (line ${e.line})` : ""}`);
+      }
       return errorResult(e.message);
     }
   });
   return server;
 }
+function createPanelGate(bridge) {
+  const RECHECK_MS = 6e4;
+  let verdict = null;
+  let checkedAt = 0;
+  return {
+    /** The message to return instead of forwarding, or null to proceed. */
+    async check() {
+      if (verdict !== null) return verdict;
+      if (Date.now() - checkedAt < RECHECK_MS) return null;
+      try {
+        const health = await bridge.health();
+        const assessment = assessPanel(health.bundleHash, installedBundleHash(installedPanelDir()));
+        checkedAt = Date.now();
+        verdict = assessment.state === "current" || assessment.state === "unknown" ? null : assessment.message;
+        if (assessment.state === "unknown" && assessment.message) logger.warn(assessment.message);
+        return verdict;
+      } catch {
+        return null;
+      }
+    },
+    invalidate() {
+      verdict = null;
+      checkedAt = 0;
+    }
+  };
+}
+async function clientRoots(server) {
+  if (!server.getClientCapabilities()?.roots) return void 0;
+  try {
+    const { roots } = await server.listRoots();
+    return roots.map((r) => r.uri).filter((uri) => uri.startsWith("file://")).map((uri) => fileURLToPath2(uri));
+  } catch (e) {
+    logger.warn(`Client advertised roots but listing them failed: ${e.message}`);
+    return void 0;
+  }
+}
 function textResult(value) {
   return {
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -1663,7 +2291,7 @@ ${USAGE}`);
   await server.connect(transport);
   logger.info("MCP server running on stdio");
 }
-var VERSION = "0.1.1";
+var VERSION = "0.2.0";
 main().catch((e) => {
   logger.error("fatal", e.message);
   process.exit(1);