@jay-framework/aiditor 0.18.4 → 0.19.3

package/dist/index.js

@@ -5,6 +5,7 @@ import path, { extname } from "path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import fs$1 from "fs";
 import crypto from "crypto";
+import { load } from "js-yaml";
 import { getLogger } from "@jay-framework/logger";
 import { fileURLToPath } from "url";
 import { spawn } from "child_process";
@@ -271,6 +272,517 @@ function buildChatPrompt(config, pageRoute, renderedUrl, userMessage) {
   ];
   return lines.filter((l) => l !== null).join("\n");
 }
+const REJECTED_ITEM_FIELDS = [
+  "kind",
+  "parameters",
+  "component",
+  "allowedScopes"
+];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(obj, field, path2, errors) {
+  const value = obj[field];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    errors.push({
+      path: `${path2}.${field}`,
+      message: "required non-empty string"
+    });
+    return null;
+  }
+  return value.trim();
+}
+function optionalString(obj, field) {
+  const value = obj[field];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function validateAddMenuItem(raw, path2) {
+  const errors = [];
+  if (!isRecord(raw)) {
+    return {
+      item: null,
+      errors: [{ path: path2, message: "item must be an object" }]
+    };
+  }
+  for (const field of REJECTED_ITEM_FIELDS) {
+    if (field in raw) {
+      errors.push({
+        path: `${path2}.${field}`,
+        message: `field "${field}" is not allowed in Add Menu catalog items`
+      });
+    }
+  }
+  const id = requiredString(raw, "id", path2, errors);
+  const title = requiredString(raw, "title", path2, errors);
+  const category = requiredString(raw, "category", path2, errors);
+  const prompt = requiredString(raw, "prompt", path2, errors);
+  if (errors.length > 0 || !id || !title || !category || !prompt) {
+    return { item: null, errors };
+  }
+  return {
+    item: {
+      id,
+      title,
+      category,
+      prompt,
+      pluginName: optionalString(raw, "pluginName"),
+      packageName: optionalString(raw, "packageName"),
+      subCategory: optionalString(raw, "subCategory"),
+      thumbnail: optionalString(raw, "thumbnail")
+    },
+    errors
+  };
+}
+function validateAddMenuCatalogFile(raw, sourcePath) {
+  const errors = [];
+  if (!isRecord(raw)) {
+    return {
+      file: null,
+      errors: [{ path: sourcePath, message: "catalog file must be an object" }]
+    };
+  }
+  if (!Array.isArray(raw.items)) {
+    return {
+      file: null,
+      errors: [
+        { path: `${sourcePath}.items`, message: "items must be an array" }
+      ]
+    };
+  }
+  const items = [];
+  raw.items.forEach((entry, index) => {
+    const result = validateAddMenuItem(entry, `${sourcePath}.items[${index}]`);
+    errors.push(...result.errors);
+    if (result.item) items.push(result.item);
+  });
+  if (items.length === 0 && errors.length > 0) {
+    return { file: null, errors };
+  }
+  return { file: { items }, errors };
+}
+function parsePluginsIndexYaml(yaml) {
+  const entries = [];
+  let currentPlugin = null;
+  let inContracts = false;
+  for (const line of yaml.split("\n")) {
+    const pluginMatch = line.match(/^  - name:\s*(.+)$/);
+    if (pluginMatch && !line.startsWith("      ")) {
+      currentPlugin = pluginMatch[1].trim();
+      inContracts = false;
+      continue;
+    }
+    if (line.trim() === "contracts:") {
+      inContracts = true;
+      continue;
+    }
+    if (inContracts && currentPlugin) {
+      const contractMatch = line.match(/^      - name:\s*(.+)$/);
+      if (contractMatch) {
+        entries.push({
+          pluginName: currentPlugin,
+          contractName: contractMatch[1].trim()
+        });
+        continue;
+      }
+      const descMatch = line.match(/^        description:\s*(.+)$/);
+      if (descMatch && entries.length > 0) {
+        const last = entries[entries.length - 1];
+        if (last.pluginName === currentPlugin) {
+          last.description = descMatch[1].trim();
+        }
+        continue;
+      }
+      const typeMatch = line.match(/^        type:\s*(.+)$/);
+      if (typeMatch && entries.length > 0) {
+        const last = entries[entries.length - 1];
+        if (last.pluginName === currentPlugin) {
+          last.isDynamic = typeMatch[1].trim() === "dynamic";
+        }
+      }
+    }
+    if (line.match(/^    actions:/) || line.match(/^    routes:/)) {
+      inContracts = false;
+    }
+  }
+  return entries;
+}
+function packageNameToPluginName(packageName) {
+  const prefix = "@jay-framework/";
+  if (packageName.startsWith(prefix)) {
+    return packageName.slice(prefix.length);
+  }
+  return packageName;
+}
+async function readPackageJsonDeps(projectRoot) {
+  const raw = await fs.readFile(
+    path.join(projectRoot, "package.json"),
+    "utf-8"
+  );
+  const pkg = JSON.parse(raw);
+  return { ...pkg.devDependencies, ...pkg.dependencies };
+}
+async function getInstalledPlugins(projectRoot) {
+  const deps = await readPackageJsonDeps(projectRoot);
+  const installed = [];
+  for (const [packageName, spec] of Object.entries(deps)) {
+    if (!packageName.startsWith("@jay-framework/")) continue;
+    installed.push({
+      pluginName: packageNameToPluginName(packageName),
+      packageName,
+      installSpec: spec
+    });
+  }
+  return installed;
+}
+async function isPluginInstalled(projectRoot, pluginName) {
+  const installed = await getInstalledPlugins(projectRoot);
+  return installed.some((p) => p.pluginName === pluginName);
+}
+async function parsePluginsIndexContracts(projectRoot) {
+  const indexPath = path.join(projectRoot, "agent-kit", "plugins-index.yaml");
+  try {
+    const yaml = await fs.readFile(indexPath, "utf-8");
+    return parsePluginsIndexYaml(yaml);
+  } catch (e) {
+    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+    if (code === "ENOENT") return [];
+    throw e;
+  }
+}
+async function parsePluginYamlContracts(projectRoot, pluginName) {
+  const pluginYamlPath = path.join(
+    projectRoot,
+    "node_modules",
+    "@jay-framework",
+    pluginName,
+    "plugin.yaml"
+  );
+  try {
+    const yaml = await fs.readFile(pluginYamlPath, "utf-8");
+    const entries = [];
+    let inContracts = false;
+    for (const line of yaml.split("\n")) {
+      if (line.trim() === "contracts:") {
+        inContracts = true;
+        continue;
+      }
+      if (inContracts) {
+        const nameMatch = line.match(/^  - name:\s*(.+)$/);
+        if (nameMatch) {
+          entries.push({
+            pluginName,
+            contractName: nameMatch[1].trim()
+          });
+        }
+        if (line.match(/^actions:/) || line.match(/^routes:/)) {
+          break;
+        }
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+const ADD_MENU_DIR = path.join("agent-kit", "aiditor", "add-menu");
+function packageNameFromItem(item) {
+  if (item.packageName) return item.packageName;
+  if (item.pluginName) return `@jay-framework/${item.pluginName}`;
+  const colon = item.id.indexOf(":");
+  if (colon > 0) {
+    return `@jay-framework/${item.id.slice(0, colon)}`;
+  }
+  return null;
+}
+function pluginNameFromItem(item) {
+  if (item.pluginName) return item.pluginName;
+  const colon = item.id.indexOf(":");
+  if (colon > 0) return item.id.slice(0, colon);
+  return null;
+}
+function groupAddMenuItems(items) {
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const sub = item.subCategory ?? null;
+    let subMap = byCategory.get(item.category);
+    if (!subMap) {
+      subMap = /* @__PURE__ */ new Map();
+      byCategory.set(item.category, subMap);
+    }
+    const list = subMap.get(sub) ?? [];
+    list.push(item);
+    subMap.set(sub, list);
+  }
+  return [...byCategory.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([category, subMap]) => ({
+    category,
+    subCategories: [...subMap.entries()].sort(([a], [b]) => {
+      const sa = a ?? "";
+      const sb = b ?? "";
+      return sa.localeCompare(sb);
+    }).map(([subCategory, subItems]) => ({
+      subCategory,
+      items: subItems.sort((a, b) => a.title.localeCompare(b.title))
+    }))
+  }));
+}
+async function listAddMenuItems(projectRoot) {
+  const addMenuDir = path.join(projectRoot, ADD_MENU_DIR);
+  const warnings = [];
+  let yamlFiles = [];
+  try {
+    const entries = await fs.readdir(addMenuDir);
+    yamlFiles = entries.filter((name) => name.endsWith(".yaml") || name.endsWith(".yml")).map((name) => path.join(addMenuDir, name)).sort((a, b) => a.localeCompare(b));
+  } catch (e) {
+    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
+    if (code === "ENOENT") {
+      return { items: [], categories: [], warnings: [] };
+    }
+    throw e;
+  }
+  const installed = await getInstalledPlugins(projectRoot);
+  const installedPackages = new Set(installed.map((p) => p.packageName));
+  const installedPlugins = new Set(installed.map((p) => p.pluginName));
+  const byId = /* @__PURE__ */ new Map();
+  for (const filePath of yamlFiles) {
+    const relPath = path.relative(projectRoot, filePath);
+    let rawContent;
+    try {
+      rawContent = await fs.readFile(filePath, "utf-8");
+    } catch {
+      warnings.push(`Could not read Add Menu catalog file: ${relPath}`);
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = load(rawContent);
+    } catch (err) {
+      warnings.push(
+        `Invalid YAML in ${relPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      continue;
+    }
+    const validated = validateAddMenuCatalogFile(parsed, relPath);
+    if (validated.errors.length > 0) {
+      for (const err of validated.errors) {
+        warnings.push(`${err.path}: ${err.message}`);
+      }
+      continue;
+    }
+    for (const item of validated.file.items) {
+      const prev = byId.get(item.id);
+      if (prev) {
+        warnings.push(
+          `Duplicate Add Menu item id "${item.id}": "${prev.sourcePath}" overwritten by "${relPath}"`
+        );
+      }
+      byId.set(item.id, { item, sourcePath: relPath });
+    }
+  }
+  const merged = [...byId.values()].map((entry) => entry.item);
+  const filtered = merged.filter((item) => {
+    const pkg = packageNameFromItem(item);
+    const plugin = pluginNameFromItem(item);
+    if (pkg && installedPackages.has(pkg)) return true;
+    if (plugin && installedPlugins.has(plugin)) return true;
+    return false;
+  });
+  return {
+    items: filtered.sort((a, b) => a.title.localeCompare(b.title)),
+    categories: groupAddMenuItems(filtered),
+    warnings
+  };
+}
+const CATALOG = [
+  {
+    pluginName: "wix-server-client",
+    packageName: "@jay-framework/wix-server-client",
+    description: "Wix API client and authentication",
+    kind: "service-only",
+    requires: [],
+    showInAddPagePicker: false,
+    configFiles: ["config/.wix.yaml"]
+  },
+  {
+    pluginName: "wix-cart",
+    packageName: "@jay-framework/wix-cart",
+    description: "Shopping cart headless components",
+    kind: "headless",
+    requires: ["wix-server-client"],
+    showInAddPagePicker: true
+  },
+  {
+    pluginName: "wix-stores",
+    packageName: "@jay-framework/wix-stores",
+    description: "Wix Stores product search, product page, categories",
+    kind: "headless",
+    requires: ["wix-server-client", "wix-cart"],
+    showInAddPagePicker: true,
+    configFiles: ["config/.wix-stores.yaml"]
+  },
+  {
+    pluginName: "wix-stores-v1",
+    packageName: "@jay-framework/wix-stores-v1",
+    description: "Wix Stores v1 catalog API",
+    kind: "headless",
+    requires: ["wix-server-client", "wix-cart"],
+    showInAddPagePicker: true
+  },
+  {
+    pluginName: "wix-data",
+    packageName: "@jay-framework/wix-data",
+    description: "Wix Data collections CMS",
+    kind: "headless",
+    requires: ["wix-server-client"],
+    showInAddPagePicker: true,
+    configFiles: ["config/.wix-data.yaml"]
+  },
+  {
+    pluginName: "wix-media",
+    packageName: "@jay-framework/wix-media",
+    description: "Wix media service (no page components)",
+    kind: "service-only",
+    requires: ["wix-server-client"],
+    showInAddPagePicker: true
+  },
+  {
+    pluginName: "ui-kit",
+    packageName: "@jay-framework/ui-kit",
+    description: "Jay UI kit headless components",
+    kind: "headless",
+    requires: [],
+    showInAddPagePicker: true
+  },
+  {
+    pluginName: "gemini-agent",
+    packageName: "@jay-framework/gemini-agent",
+    description: "Gemini AI agent plugin",
+    kind: "headless",
+    requires: [],
+    showInAddPagePicker: true,
+    configFiles: ["config/.gemini-agent.yaml"]
+  },
+  {
+    pluginName: "webmcp",
+    packageName: "@jay-framework/webmcp",
+    description: "Web MCP tooling",
+    kind: "tooling",
+    requires: [],
+    showInAddPagePicker: false
+  },
+  {
+    pluginName: "aiditor",
+    packageName: "@jay-framework/aiditor",
+    description: "AIditor self plugin",
+    kind: "tooling",
+    requires: [],
+    showInAddPagePicker: false
+  }
+];
+function getJayPluginCatalog() {
+  return CATALOG.map((e) => ({ ...e, requires: [...e.requires] }));
+}
+function getCatalogEntry(pluginName) {
+  return CATALOG.find((e) => e.pluginName === pluginName);
+}
+const DEFAULT_COMPONENT_KEYS = {
+  "product-page": "p",
+  "product-search": "search",
+  "cart-indicator": "cart",
+  "cart-page": "cartPage",
+  "category-list": "categories"
+};
+function getDefaultComponentKey(contractName) {
+  if (contractName in DEFAULT_COMPONENT_KEYS) {
+    return DEFAULT_COMPONENT_KEYS[contractName];
+  }
+  return contractName.charAt(0) || "c";
+}
+function pagePluginSelectionsToAttachments(selectedPlugins) {
+  const attachments = [];
+  for (const plugin of selectedPlugins) {
+    for (const contract of plugin.contracts) {
+      attachments.push({
+        itemId: `${plugin.pluginName}:${contract.contractName}`
+      });
+    }
+  }
+  return attachments;
+}
+const ADD_MENU_Q3_RULE = `Add Menu usage (Q3 — follow strictly):
+- Each attached Add Menu item describes a **resource in scope**, not a fixed number of DOM instances.
+- Wire **only** attachments the user referenced in prose, \`@Title\` mentions, or marker instructions.
+- Do **not** implement an attachment's prompt if the user did not reference it.
+- One headless import per resource; multiple instances with different props when the brief requires.`;
+function resolveAddMenuAttachments(input) {
+  if (input.addMenuAttachments?.length) return input.addMenuAttachments;
+  if (input.selectedPlugins?.length) {
+    return pagePluginSelectionsToAttachments(input.selectedPlugins);
+  }
+  return [];
+}
+function buildAddMenuAttachmentPromptSection(attachments, itemById, options) {
+  const scoped = options?.annotationId ? attachments.filter((a) => a.annotationId === options.annotationId) : attachments.filter((a) => !a.annotationId);
+  if (scoped.length === 0) return "";
+  const lines = ["", "## Add Menu attachments", "", ADD_MENU_Q3_RULE, ""];
+  for (const attachment of scoped) {
+    const item = itemById.get(attachment.itemId);
+    if (!item) {
+      lines.push(
+        `### ${attachment.itemId}`,
+        "",
+        "(catalog item not found)",
+        ""
+      );
+      continue;
+    }
+    const scope = attachment.annotationId ? `Marker #${attachment.annotationId}` : "Request-level";
+    lines.push(
+      `### ${item.title} (${item.id})`,
+      `Scope: ${scope}`,
+      "",
+      item.prompt.trim(),
+      ""
+    );
+  }
+  return lines.join("\n");
+}
+function buildLegacyPluginManifestPromptSection(selectedPlugins) {
+  if (!selectedPlugins.length) return "";
+  const lines = [
+    "",
+    "## Page plugin manifest (legacy — prefer Add Menu attachments)",
+    "",
+    "| Plugin | Contract | Key |",
+    "| --- | --- | --- |"
+  ];
+  for (const plugin of selectedPlugins) {
+    for (const contract of plugin.contracts) {
+      const key = contract.componentKey ?? getDefaultComponentKey(contract.contractName);
+      lines.push(
+        `| ${plugin.packageName} | ${contract.contractName} | ${key} |`
+      );
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function buildRouteMigrationPromptSection(routeMigration) {
+  if (!routeMigration) return "";
+  return [
+    "",
+    "## Planned route migration (apply only if user request requires it)",
+    "",
+    `- Current route: \`${routeMigration.currentRoute}\``,
+    `- Planned route: \`${routeMigration.plannedRoute}\``,
+    `- Triggering Add Menu items: ${routeMigration.triggeringItemIds.join(", ")}`,
+    "",
+    "Migrate page files to the planned route only when the user's instruction uses the attached route-param components.",
+    ""
+  ].join("\n");
+}
 function buildNonVisualPrompt(config, notes, imagePath) {
   const lines = [
     `Project directory: ${config.projectDir}`,
@@ -290,6 +802,27 @@ function structuredAnnotationBindings(ann) {
   if (ann.pluginBinding) return [ann.pluginBinding];
   return [];
 }
+function appendAddMenuLinesForAnnotation(body, ann, itemById, indent = "") {
+  const attachments = ann.addMenuAttachments ?? [];
+  if (attachments.length === 0) return;
+  const section = buildAddMenuAttachmentPromptSection(
+    attachments.map((a) => ({
+      itemId: a.itemId,
+      annotationId: a.annotationId ?? ann.id
+    })),
+    itemById,
+    { annotationId: ann.id }
+  );
+  if (!section.trim()) return;
+  for (const line of section.trim().split("\n")) {
+    body.push(`${indent}${line}`);
+  }
+}
+function appendLegacyBindingLines(body, ann, markerId, indent = "") {
+  const bindings = structuredAnnotationBindings(ann);
+  if (bindings.length === 0) return;
+  appendBindingPromptLines(body, bindings, markerId, indent);
+}
 function appendBindingPromptLines(body, bindings, markerId, indent = "") {
   if (bindings.length === 0) return;
   body.push(`${indent}Headless bindings:`);
@@ -336,7 +869,9 @@ function parseNotesField(notes) {
         structured: null,
         structuredVideo: {
           annotations: j.annotations,
-          previewNavLog
+          previewNavLog,
+          addMenuAttachments: j.addMenuAttachments,
+          routeMigration: j.routeMigration
         },
         plain: ""
       };
@@ -345,7 +880,11 @@ function parseNotesField(notes) {
       (a) => a && typeof a === "object" && typeof a.id === "string" && typeof a.instruction === "string" && typeof a.mode === "string"
     )) {
       return {
-        structured: { annotations: j.annotations },
+        structured: {
+          annotations: j.annotations,
+          addMenuAttachments: j.addMenuAttachments,
+          routeMigration: j.routeMigration
+        },
         structuredVideo: null,
         plain: ""
       };
@@ -354,7 +893,7 @@ function parseNotesField(notes) {
   }
   return empty();
 }
-function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, attachmentPathsByAnnotationId) {
+function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, attachmentPathsByAnnotationId, addMenu = { itemById: /* @__PURE__ */ new Map() }) {
   const preamble = [
     `Project directory: ${config.projectDir}`,
     "",
@@ -373,6 +912,18 @@ function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, att
     ""
   ];
   const body = [];
+  const routeMigration = parsed.structured?.routeMigration ?? void 0;
+  const requestAddMenu = parsed.structured?.addMenuAttachments ?? [];
+  if (requestAddMenu.length > 0) {
+    const section = buildAddMenuAttachmentPromptSection(
+      requestAddMenu,
+      addMenu.itemById
+    );
+    if (section.trim()) body.push(section.trim(), "");
+  }
+  if (routeMigration) {
+    body.push(buildRouteMigrationPromptSection(routeMigration).trim(), "");
+  }
   if (parsed.structured) {
     body.push("Annotations (apply in order):", "");
     const sorted = [...parsed.structured.annotations].sort(
@@ -382,7 +933,10 @@ function buildVisualPromptDual(config, pageRoute, renderedUrl, dual, parsed, att
       const pin = ann.id;
       const paths = attachmentPathsByAnnotationId.get(pin) ?? [];
       body.push(`Annotation ${pin} (${ann.mode})`);
-      appendBindingPromptLines(body, structuredAnnotationBindings(ann), ann.id);
+      appendAddMenuLinesForAnnotation(body, ann, addMenu.itemById);
+      if (!ann.addMenuAttachments?.length) {
+        appendLegacyBindingLines(body, ann, ann.id);
+      }
       body.push(`Instruction: ${ann.instruction.trim()}`);
       if (paths.length > 0) {
         body.push(
@@ -407,7 +961,7 @@ function pinOrder(annotations) {
     return a.id.localeCompare(b.id, void 0, { sensitivity: "base" });
   });
 }
-function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frames, parsed, attachmentPathsByPin) {
+function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frames, parsed, attachmentPathsByPin, addMenu = { itemById: /* @__PURE__ */ new Map() }) {
   const sv = parsed.structuredVideo;
   const navLines = [];
   if (sv?.previewNavLog && sv.previewNavLog.length > 0) {
@@ -441,7 +995,20 @@ function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frame
   for (const [i, a] of pinOrder(sv.annotations).entries()) {
     pinById.set(a.id, String(i + 1));
   }
-  const body = ["Per-moment captures:", ""];
+  const body = [];
+  const routeMigration = sv.routeMigration;
+  const requestAddMenu = sv.addMenuAttachments ?? [];
+  if (requestAddMenu.length > 0) {
+    const section = buildAddMenuAttachmentPromptSection(
+      requestAddMenu,
+      addMenu.itemById
+    );
+    if (section.trim()) body.push(section.trim(), "");
+  }
+  if (routeMigration) {
+    body.push(buildRouteMigrationPromptSection(routeMigration).trim(), "");
+  }
+  body.push("Per-moment captures:", "");
   for (const fr of frames) {
     body.push(
       `Moment ${fr.frameIndex + 1} — t=${fr.timeSec.toFixed(2)}s`,
@@ -455,12 +1022,10 @@ function buildVisualPromptVideo(config, pageRoute, renderedUrl, videoPath, frame
       const pinNum = pinById.get(ann.id) ?? "?";
       const paths = attachmentPathsByPin.get(pinNum) ?? [];
       body.push(`- Pin ${pinNum} (id ${ann.id}) — ${ann.mode}`);
-      appendBindingPromptLines(
-        body,
-        structuredAnnotationBindings(ann),
-        ann.id,
-        "  "
-      );
+      appendAddMenuLinesForAnnotation(body, ann, addMenu.itemById, "  ");
+      if (!ann.addMenuAttachments?.length) {
+        appendLegacyBindingLines(body, ann, ann.id, "  ");
+      }
       body.push(`  Instruction: ${ann.instruction.trim()}`);
       if (ann.previewUrlAtTime) {
         body.push(
@@ -500,6 +1065,10 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
   const parsed = parseNotesField(input.notes);
   const isVideo = input.visualTask === "5";
   const isVisual = !!input.visualTask;
+  const catalog = await listAddMenuItems(projectDir);
+  const addMenu = {
+    itemById: new Map(catalog.items.map((item) => [item.id, item]))
+  };
   let promptContent;
   if (isVideo) {
     let videoPath = "";
@@ -541,7 +1110,8 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
       videoPath,
       frames,
       parsed,
-      attachmentPathsByPin
+      attachmentPathsByPin,
+      addMenu
     );
   } else if (isVisual && input.screenshot_markers_only) {
     const ssDir = path.join(taskDir, "screenshots");
@@ -570,7 +1140,8 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
       input.renderedUrl ?? "",
       dual,
       parsed,
-      attachmentPathsByAnnotationId
+      attachmentPathsByAnnotationId,
+      addMenu
     );
   } else if (input.messageKind === "chat") {
     promptContent = buildChatPrompt(
@@ -606,164 +1177,59 @@ const submitTaskAction = makeJayStream("aiditor.submitTask").withFiles().withHan
     systemPrompt
   };
   try {
-    async function* streamAgentQuery(opts) {
-      for await (const message of query({
-        prompt: promptContent,
-        options: {
-          ...sharedOptions,
-          ...opts
-        }
-      })) {
-        for (const chunk of transformSDKMessage(message)) {
-          yield chunk;
-        }
-      }
-    }
-    let didStaleResumeRetry = false;
-    try {
-      if (sessionPlan.useResume) {
-        yield* streamAgentQuery({ resume: sessionPlan.sessionId });
-      } else {
-        yield* streamAgentQuery({
-          sessionId: sessionPlan.sessionId,
-          title: routeKey
-        });
-      }
-    } catch (err) {
-      if (sessionPlan.useResume && !didStaleResumeRetry) {
-        didStaleResumeRetry = true;
-        const fresh = await replaceRouteSessionAfterStaleResume(
-          projectDir,
-          routeKey
-        );
-        try {
-          yield* streamAgentQuery({
-            sessionId: fresh.sessionId,
-            title: routeKey
-          });
-        } catch (err2) {
-          yield {
-            type: "error",
-            message: err2 instanceof Error ? err2.message : String(err2)
-          };
-        }
-      } else {
-        yield {
-          type: "error",
-          message: err instanceof Error ? err.message : String(err)
-        };
-      }
-    }
-  } finally {
-    endRouteQuery(routeKey);
-  }
-  yield { type: "done" };
-});
-const CATALOG = [
-  {
-    pluginName: "wix-server-client",
-    packageName: "@jay-framework/wix-server-client",
-    description: "Wix API client and authentication",
-    kind: "service-only",
-    requires: [],
-    showInAddPagePicker: false,
-    configFiles: ["config/.wix.yaml"]
-  },
-  {
-    pluginName: "wix-cart",
-    packageName: "@jay-framework/wix-cart",
-    description: "Shopping cart headless components",
-    kind: "headless",
-    requires: ["wix-server-client"],
-    showInAddPagePicker: true
-  },
-  {
-    pluginName: "wix-stores",
-    packageName: "@jay-framework/wix-stores",
-    description: "Wix Stores product search, product page, categories",
-    kind: "headless",
-    requires: ["wix-server-client", "wix-cart"],
-    showInAddPagePicker: true,
-    configFiles: ["config/.wix-stores.yaml"]
-  },
-  {
-    pluginName: "wix-stores-v1",
-    packageName: "@jay-framework/wix-stores-v1",
-    description: "Wix Stores v1 catalog API",
-    kind: "headless",
-    requires: ["wix-server-client", "wix-cart"],
-    showInAddPagePicker: true
-  },
-  {
-    pluginName: "wix-data",
-    packageName: "@jay-framework/wix-data",
-    description: "Wix Data collections CMS",
-    kind: "headless",
-    requires: ["wix-server-client"],
-    showInAddPagePicker: true,
-    configFiles: ["config/.wix-data.yaml"]
-  },
-  {
-    pluginName: "wix-media",
-    packageName: "@jay-framework/wix-media",
-    description: "Wix media service (no page components)",
-    kind: "service-only",
-    requires: ["wix-server-client"],
-    showInAddPagePicker: true
-  },
-  {
-    pluginName: "ui-kit",
-    packageName: "@jay-framework/ui-kit",
-    description: "Jay UI kit headless components",
-    kind: "headless",
-    requires: [],
-    showInAddPagePicker: true
-  },
-  {
-    pluginName: "gemini-agent",
-    packageName: "@jay-framework/gemini-agent",
-    description: "Gemini AI agent plugin",
-    kind: "headless",
-    requires: [],
-    showInAddPagePicker: true,
-    configFiles: ["config/.gemini-agent.yaml"]
-  },
-  {
-    pluginName: "webmcp",
-    packageName: "@jay-framework/webmcp",
-    description: "Web MCP tooling",
-    kind: "tooling",
-    requires: [],
-    showInAddPagePicker: false
-  },
-  {
-    pluginName: "aiditor",
-    packageName: "@jay-framework/aiditor",
-    description: "AIditor self plugin",
-    kind: "tooling",
-    requires: [],
-    showInAddPagePicker: false
-  }
-];
-function getJayPluginCatalog() {
-  return CATALOG.map((e) => ({ ...e, requires: [...e.requires] }));
-}
-function getCatalogEntry(pluginName) {
-  return CATALOG.find((e) => e.pluginName === pluginName);
-}
-const DEFAULT_COMPONENT_KEYS = {
-  "product-page": "p",
-  "product-search": "search",
-  "cart-indicator": "cart",
-  "cart-page": "cartPage",
-  "category-list": "categories"
-};
-function getDefaultComponentKey(contractName) {
-  if (contractName in DEFAULT_COMPONENT_KEYS) {
-    return DEFAULT_COMPONENT_KEYS[contractName];
+    async function* streamAgentQuery(opts) {
+      for await (const message of query({
+        prompt: promptContent,
+        options: {
+          ...sharedOptions,
+          ...opts
+        }
+      })) {
+        for (const chunk of transformSDKMessage(message)) {
+          yield chunk;
+        }
+      }
+    }
+    let didStaleResumeRetry = false;
+    try {
+      if (sessionPlan.useResume) {
+        yield* streamAgentQuery({ resume: sessionPlan.sessionId });
+      } else {
+        yield* streamAgentQuery({
+          sessionId: sessionPlan.sessionId,
+          title: routeKey
+        });
+      }
+    } catch (err) {
+      if (sessionPlan.useResume && !didStaleResumeRetry) {
+        didStaleResumeRetry = true;
+        const fresh = await replaceRouteSessionAfterStaleResume(
+          projectDir,
+          routeKey
+        );
+        try {
+          yield* streamAgentQuery({
+            sessionId: fresh.sessionId,
+            title: routeKey
+          });
+        } catch (err2) {
+          yield {
+            type: "error",
+            message: err2 instanceof Error ? err2.message : String(err2)
+          };
+        }
+      } else {
+        yield {
+          type: "error",
+          message: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+  } finally {
+    endRouteQuery(routeKey);
   }
-  return contractName.charAt(0) || "c";
-}
+  yield { type: "done" };
+});
 class AddPagePromptLoadError extends Error {
   constructor(message) {
     super(message);
@@ -814,34 +1280,6 @@ async function listDirFiles(dir, prefix) {
     return [];
   }
 }
-function buildPluginManifestPromptSection(selectedPlugins) {
-  const lines = [
-    "",
-    "## Page plugin manifest (authoritative)",
-    "",
-    "The user selected these headless components for this page. You MUST:",
-    '1. Add `<script type="application/jay-headless" plugin="..." contract="..." key="...">` for each entry',
-    "2. Bind UI using contract ViewState and refs per agent-kit designer guides",
-    "3. Run jay-stack validate",
-    "",
-    "| Plugin | Contract | Key | Notes |",
-    "| --- | --- | --- | --- |"
-  ];
-  for (const plugin of selectedPlugins) {
-    for (const contract of plugin.contracts) {
-      const key = contract.componentKey ?? getDefaultComponentKey(contract.contractName);
-      lines.push(
-        `| ${plugin.packageName} | ${contract.contractName} | ${key} | |`
-      );
-    }
-  }
-  lines.push(
-    "",
-    "If Wix config is incomplete, implement layout and headless imports; live store data may be unavailable until config/.wix.yaml is filled.",
-    ""
-  );
-  return lines.join("\n");
-}
 async function buildAddPagePrompt(input) {
   const { system, skill } = await loadAddPageAgentPrompts();
   const contentPath = path.join(input.requestDir, "content.md");
@@ -870,7 +1308,13 @@ async function buildAddPagePrompt(input) {
 ## Retry mode
 The page at route \`${input.pageRoute}\` may already have partial files from a previous run. Read existing page files and **fix** validate errors rather than recreating from scratch.
 ` : "";
-  const manifestSection = input.selectedPlugins && input.selectedPlugins.length > 0 ? buildPluginManifestPromptSection(input.selectedPlugins) : "";
+  const attachments = resolveAddMenuAttachments(input);
+  const catalog = await listAddMenuItems(input.projectDir);
+  const itemById = new Map(catalog.items.map((item) => [item.id, item]));
+  const addMenuSection = attachments.length > 0 ? buildAddMenuAttachmentPromptSection(attachments, itemById) : input.selectedPlugins?.length ? buildLegacyPluginManifestPromptSection(input.selectedPlugins) : "";
+  const routeMigrationSection = buildRouteMigrationPromptSection(
+    input.routeMigration
+  );
   const userMessage = `# Add Page task
 
 Create **one** Jay Stack page at route: \`${input.pageRoute}\` (${input.routeKind}).
@@ -898,7 +1342,7 @@ Asset files live under the request folder. **Copy** cited assets from \`${input.
 - Match user intent from content.md and design.md as closely as possible.
 - Reuse existing site patterns (header, footer, styling) from other pages when design.md requests it.
 - Summarize files created and how they cover the brief when done.
-${manifestSection}
+${addMenuSection}${routeMigrationSection}
 ---
 
 ${skill}`;
@@ -2062,7 +2506,9 @@ const submitAddPageAction = makeJayStream("aiditor.submitAddPage").withServices(
       pageRoute: normalizedRoute,
       routeKind,
       isRetry: input.isRetry,
-      selectedPlugins: request.selectedPlugins
+      selectedPlugins: request.selectedPlugins,
+      addMenuAttachments: request.addMenuAttachments,
+      routeMigration: request.routeMigration
     })) {
       yield chunk;
       if (chunk.type === "error") {
@@ -2090,227 +2536,103 @@ const submitAddPageAction = makeJayStream("aiditor.submitAddPage").withServices(
       message: "Validation failed.",
       text: validateResult.errors.join("\n"),
       validateErrors: validateResult.errors
-    };
-    yield { type: "done" };
-    return;
-  }
-  await updatePageRequestStatus(projectDir, input.requestId, "completed");
-  await devServer.refreshRoutes();
-  const jayHtmlPath = await resolveJayHtmlPathForPageRoute(
-    projectDir,
-    normalizedRoute,
-    devServer.listRoutes()
-  );
-  if (jayHtmlPath) {
-    try {
-      await savePageBriefFromRequest(projectDir, jayHtmlPath, {
-        requestId: input.requestId,
-        pageRoute: normalizedRoute,
-        contentMd: input.contentMd,
-        designMd: input.designMd
-      });
-    } catch (err) {
-      getLogger().warn(
-        `[Add Page] Failed to save page brief for ${normalizedRoute}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  yield {
-    type: "result",
-    message: `Page created at ${normalizedRoute}.`,
-    text: normalizedRoute
-  };
-  yield { type: "done" };
-});
-const generateAddPageBriefFromImageAction = makeJayQuery(
-  "aiditor.generateAddPageBriefFromImage"
-).withMethod("POST").withFiles().withHandler(
-  async (input) => {
-    const imageFiles = extractImageFilesFromExtraFiles(input.extraFiles);
-    const validationError = validateBriefFillImages(imageFiles);
-    if (validationError) {
-      return { ok: false, error: validationError };
-    }
-    const projectDir = process.cwd();
-    if (input.requestId) {
-      const request = await readPageRequest(projectDir, input.requestId);
-      if (!request) {
-        return {
-          ok: false,
-          error: `Page request not found: ${input.requestId}`
-        };
-      }
-    }
-    try {
-      const images = imageFiles.map(readImageAsBase64);
-      const result = await generateBriefFromImages(
-        {
-          target: input.target,
-          images,
-          contextNotes: input.contextNotes,
-          pageRoute: input.pageRoute
-        },
-        { projectDir }
-      );
-      const referenceAttachments = [];
-      if (input.requestId) {
-        for (const file of imageFiles) {
-          const id = generatePageRequestId();
-          const filename = sanitizeAttachmentFilename(file.name);
-          const relPath = `references/${filename}`;
-          const destPath = path.join(
-            getPageRequestDir(projectDir, input.requestId),
-            relPath
-          );
-          persistUpload(file, destPath);
-          await addPageRequestAttachment(
-            projectDir,
-            input.requestId,
-            { id, path: relPath, label: filename },
-            "reference"
-          );
-          referenceAttachments.push({ id, path: relPath, filename });
-        }
-      }
-      return {
-        ok: true,
-        markdown: result.markdown,
-        suggestedRoute: result.suggestedRoute,
-        suggestedRouteKind: result.suggestedRouteKind,
-        referenceAttachments
-      };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err)
-      };
-    }
-  }
-);
-function parsePluginsIndexYaml(yaml) {
-  const entries = [];
-  let currentPlugin = null;
-  let inContracts = false;
-  for (const line of yaml.split("\n")) {
-    const pluginMatch = line.match(/^  - name:\s*(.+)$/);
-    if (pluginMatch && !line.startsWith("      ")) {
-      currentPlugin = pluginMatch[1].trim();
-      inContracts = false;
-      continue;
-    }
-    if (line.trim() === "contracts:") {
-      inContracts = true;
-      continue;
-    }
-    if (inContracts && currentPlugin) {
-      const contractMatch = line.match(/^      - name:\s*(.+)$/);
-      if (contractMatch) {
-        entries.push({
-          pluginName: currentPlugin,
-          contractName: contractMatch[1].trim()
-        });
-        continue;
-      }
-      const descMatch = line.match(/^        description:\s*(.+)$/);
-      if (descMatch && entries.length > 0) {
-        const last = entries[entries.length - 1];
-        if (last.pluginName === currentPlugin) {
-          last.description = descMatch[1].trim();
-        }
-        continue;
-      }
-      const typeMatch = line.match(/^        type:\s*(.+)$/);
-      if (typeMatch && entries.length > 0) {
-        const last = entries[entries.length - 1];
-        if (last.pluginName === currentPlugin) {
-          last.isDynamic = typeMatch[1].trim() === "dynamic";
-        }
-      }
-    }
-    if (line.match(/^    actions:/) || line.match(/^    routes:/)) {
-      inContracts = false;
-    }
-  }
-  return entries;
-}
-function packageNameToPluginName(packageName) {
-  const prefix = "@jay-framework/";
-  if (packageName.startsWith(prefix)) {
-    return packageName.slice(prefix.length);
-  }
-  return packageName;
-}
-async function readPackageJsonDeps(projectRoot) {
-  const raw = await fs.readFile(
-    path.join(projectRoot, "package.json"),
-    "utf-8"
-  );
-  const pkg = JSON.parse(raw);
-  return { ...pkg.devDependencies, ...pkg.dependencies };
-}
-async function getInstalledPlugins(projectRoot) {
-  const deps = await readPackageJsonDeps(projectRoot);
-  const installed = [];
-  for (const [packageName, spec] of Object.entries(deps)) {
-    if (!packageName.startsWith("@jay-framework/")) continue;
-    installed.push({
-      pluginName: packageNameToPluginName(packageName),
-      packageName,
-      installSpec: spec
-    });
-  }
-  return installed;
-}
-async function isPluginInstalled(projectRoot, pluginName) {
-  const installed = await getInstalledPlugins(projectRoot);
-  return installed.some((p) => p.pluginName === pluginName);
-}
-async function parsePluginsIndexContracts(projectRoot) {
-  const indexPath = path.join(projectRoot, "agent-kit", "plugins-index.yaml");
-  try {
-    const yaml = await fs.readFile(indexPath, "utf-8");
-    return parsePluginsIndexYaml(yaml);
-  } catch (e) {
-    const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
-    if (code === "ENOENT") return [];
-    throw e;
+    };
+    yield { type: "done" };
+    return;
   }
-}
-async function parsePluginYamlContracts(projectRoot, pluginName) {
-  const pluginYamlPath = path.join(
-    projectRoot,
-    "node_modules",
-    "@jay-framework",
-    pluginName,
-    "plugin.yaml"
+  await updatePageRequestStatus(projectDir, input.requestId, "completed");
+  await devServer.refreshRoutes();
+  const jayHtmlPath = await resolveJayHtmlPathForPageRoute(
+    projectDir,
+    normalizedRoute,
+    devServer.listRoutes()
   );
-  try {
-    const yaml = await fs.readFile(pluginYamlPath, "utf-8");
-    const entries = [];
-    let inContracts = false;
-    for (const line of yaml.split("\n")) {
-      if (line.trim() === "contracts:") {
-        inContracts = true;
-        continue;
+  if (jayHtmlPath) {
+    try {
+      await savePageBriefFromRequest(projectDir, jayHtmlPath, {
+        requestId: input.requestId,
+        pageRoute: normalizedRoute,
+        contentMd: input.contentMd,
+        designMd: input.designMd
+      });
+    } catch (err) {
+      getLogger().warn(
+        `[Add Page] Failed to save page brief for ${normalizedRoute}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  yield {
+    type: "result",
+    message: `Page created at ${normalizedRoute}.`,
+    text: normalizedRoute
+  };
+  yield { type: "done" };
+});
+const generateAddPageBriefFromImageAction = makeJayQuery(
+  "aiditor.generateAddPageBriefFromImage"
+).withMethod("POST").withFiles().withHandler(
+  async (input) => {
+    const imageFiles = extractImageFilesFromExtraFiles(input.extraFiles);
+    const validationError = validateBriefFillImages(imageFiles);
+    if (validationError) {
+      return { ok: false, error: validationError };
+    }
+    const projectDir = process.cwd();
+    if (input.requestId) {
+      const request = await readPageRequest(projectDir, input.requestId);
+      if (!request) {
+        return {
+          ok: false,
+          error: `Page request not found: ${input.requestId}`
+        };
       }
-      if (inContracts) {
-        const nameMatch = line.match(/^  - name:\s*(.+)$/);
-        if (nameMatch) {
-          entries.push({
-            pluginName,
-            contractName: nameMatch[1].trim()
-          });
-        }
-        if (line.match(/^actions:/) || line.match(/^routes:/)) {
-          break;
+    }
+    try {
+      const images = imageFiles.map(readImageAsBase64);
+      const result = await generateBriefFromImages(
+        {
+          target: input.target,
+          images,
+          contextNotes: input.contextNotes,
+          pageRoute: input.pageRoute
+        },
+        { projectDir }
+      );
+      const referenceAttachments = [];
+      if (input.requestId) {
+        for (const file of imageFiles) {
+          const id = generatePageRequestId();
+          const filename = sanitizeAttachmentFilename(file.name);
+          const relPath = `references/${filename}`;
+          const destPath = path.join(
+            getPageRequestDir(projectDir, input.requestId),
+            relPath
+          );
+          persistUpload(file, destPath);
+          await addPageRequestAttachment(
+            projectDir,
+            input.requestId,
+            { id, path: relPath, label: filename },
+            "reference"
+          );
+          referenceAttachments.push({ id, path: relPath, filename });
         }
       }
+      return {
+        ok: true,
+        markdown: result.markdown,
+        suggestedRoute: result.suggestedRoute,
+        suggestedRouteKind: result.suggestedRouteKind,
+        referenceAttachments
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err)
+      };
     }
-    return entries;
-  } catch {
-    return [];
   }
-}
+);
 const LOCAL_SPEC_PREFIXES = ["portal:", "file:", "workspace:"];
 function isRegistryInstallSpec(installSpec) {
   if (!installSpec) return true;
@@ -2721,9 +3043,35 @@ async function checkPluginUpdate(projectRoot, pluginName, packageName, installSp
     message: updateAvailable ? `Update available: ${installedVersion} → ${latestVersion}` : installedVersion ? `Up to date (${installedVersion})` : void 0
   };
 }
+const writeQueues = /* @__PURE__ */ new Map();
 function getSetupCachePath(projectRoot) {
   return path.join(projectRoot, ".aiditor", "plugin-setup-status.json");
 }
+function getSetupCacheTempPath(projectRoot) {
+  return `${getSetupCachePath(projectRoot)}.tmp`;
+}
+function enqueueCacheWrite(projectRoot, operation) {
+  const previous = writeQueues.get(projectRoot) ?? Promise.resolve();
+  const next = previous.catch(() => void 0).then(operation);
+  writeQueues.set(
+    projectRoot,
+    next.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+  return next;
+}
+async function writeSetupCacheFile(projectRoot, cache2) {
+  const dir = path.join(projectRoot, ".aiditor");
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = getSetupCachePath(projectRoot);
+  const tempPath = getSetupCacheTempPath(projectRoot);
+  const body = `${JSON.stringify(cache2, null, 2)}
+`;
+  await fs.writeFile(tempPath, body, "utf-8");
+  await fs.rename(tempPath, filePath);
+}
 async function readSetupCache(projectRoot) {
   const filePath = getSetupCachePath(projectRoot);
   try {
@@ -2732,20 +3080,20 @@ async function readSetupCache(projectRoot) {
   } catch (e) {
     const code = e && typeof e === "object" && "code" in e ? e.code : void 0;
     if (code === "ENOENT") return {};
+    if (e instanceof SyntaxError) {
+      const backupPath = `${filePath}.corrupt-${Date.now()}`;
+      await fs.rename(filePath, backupPath).catch(() => void 0);
+      return {};
+    }
     throw e;
   }
 }
 async function writeSetupCacheEntry(projectRoot, pluginName, entry) {
-  const cache2 = await readSetupCache(projectRoot);
-  cache2[pluginName] = entry;
-  const dir = path.join(projectRoot, ".aiditor");
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(
-    getSetupCachePath(projectRoot),
-    `${JSON.stringify(cache2, null, 2)}
-`,
-    "utf-8"
-  );
+  return enqueueCacheWrite(projectRoot, async () => {
+    const cache2 = await readSetupCache(projectRoot);
+    cache2[pluginName] = entry;
+    await writeSetupCacheFile(projectRoot, cache2);
+  });
 }
 function getCachedSetupStatus(cache2, pluginName) {
   return cache2[pluginName];
@@ -2906,57 +3254,133 @@ async function* ensureProjectPlugin(projectRoot, pluginName, options) {
     message: parsed.message
   };
 }
-const PLUGIN_MANIFEST_START = "<!-- aiditor:plugins:start -->";
-const PLUGIN_MANIFEST_END = "<!-- aiditor:plugins:end -->";
-function formatManifestLine(packageName, contractName, componentKey) {
-  const key = componentKey ?? getDefaultComponentKey(contractName);
-  return `- ${packageName} / ${contractName} (key: ${key})`;
-}
-function buildPluginManifestSection(selectedPlugins) {
-  const lines = [
-    PLUGIN_MANIFEST_START,
-    "",
-    "## Plugins & contracts (selected)",
-    ""
-  ];
-  for (const plugin of selectedPlugins) {
-    for (const contract of plugin.contracts) {
-      lines.push(
-        formatManifestLine(
-          plugin.packageName,
-          contract.contractName,
-          contract.componentKey
-        )
-      );
+function parseContractParamsFromYaml(contractYaml, contractName, pluginName) {
+  const lines = contractYaml.split("\n");
+  let inParams = false;
+  const allParams = [];
+  const requiredParams = [];
+  for (const line of lines) {
+    if (!inParams) {
+      if (line.match(/^params:\s*$/)) {
+        inParams = true;
+      }
+      continue;
+    }
+    if (line.match(/^[a-zA-Z]/) && !line.startsWith(" ")) {
+      break;
+    }
+    const paramMatch = line.match(/^\s{2}([a-zA-Z0-9_]+):\s*(.+)$/);
+    if (paramMatch) {
+      const name = paramMatch[1];
+      const typePart = paramMatch[2].trim();
+      allParams.push(name);
+      const isOptional = typePart.endsWith("?") || line.match(/^\s{2}[a-zA-Z0-9_]+\?:/) !== null;
+      if (!isOptional) {
+        requiredParams.push(name);
+      }
     }
   }
-  lines.push(PLUGIN_MANIFEST_END);
-  return lines.join("\n");
+  if (allParams.length === 0) return null;
+  return { contractName, pluginName, requiredParams, allParams };
 }
-function syncPluginManifestInContentMd(contentMd, selectedPlugins) {
-  const section = buildPluginManifestSection(selectedPlugins);
-  const startIx = contentMd.indexOf(PLUGIN_MANIFEST_START);
-  const endIx = contentMd.indexOf(PLUGIN_MANIFEST_END);
-  if (startIx >= 0 && endIx > startIx) {
-    const before = contentMd.slice(0, startIx).trimEnd();
-    const after = contentMd.slice(endIx + PLUGIN_MANIFEST_END.length).trimStart();
-    const parts = [before, section, after].filter((p) => p.length > 0);
-    return parts.length > 0 ? `${parts.join("\n\n")}
-` : `${section}
-`;
+function contractNameFromItemId(itemId) {
+  const colon = itemId.indexOf(":");
+  if (colon < 0 || colon === itemId.length - 1) return null;
+  return itemId.slice(colon + 1);
+}
+function pluginNameFromItemId(itemId) {
+  const colon = itemId.indexOf(":");
+  if (colon <= 0) return null;
+  return itemId.slice(0, colon);
+}
+async function resolveContractParamsForItem(projectRoot, item) {
+  const pluginName = item.pluginName ?? pluginNameFromItemId(item.id);
+  const contractName = contractNameFromItemId(item.id);
+  if (!pluginName || !contractName) return null;
+  const contractPath = path.join(
+    projectRoot,
+    "agent-kit",
+    "materialized-contracts",
+    pluginName,
+    `${contractName}.jay-contract`
+  );
+  let yaml;
+  try {
+    yaml = await fs.readFile(contractPath, "utf-8");
+  } catch {
+    return null;
   }
-  const hasContracts = selectedPlugins.some((p) => p.contracts.length > 0);
-  if (!hasContracts) return contentMd;
-  const trimmed = contentMd.trimEnd();
-  if (trimmed.length === 0) {
-    return `${section}
-`;
+  return parseContractParamsFromYaml(yaml, contractName, pluginName);
+}
+const listAddMenuItemsAction = makeJayQuery("aiditor.listAddMenuItems").withServices(DEV_SERVER_SERVICE).withHandler(async () => {
+  const projectRoot = process.cwd();
+  return listAddMenuItems(projectRoot);
+});
+const resolveAddMenuContractParamsAction = makeJayQuery(
+  "aiditor.resolveAddMenuContractParams"
+).withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
+  const projectRoot = process.cwd();
+  const resolved = await resolveContractParamsForItem(projectRoot, {
+    id: input.itemId,
+    pluginName: input.pluginName
+  });
+  if (!resolved) {
+    return {
+      contractName: null,
+      pluginName: null,
+      requiredParams: null,
+      allParams: null
+    };
   }
-  return `${trimmed}
-
-${section}
-`;
+  return {
+    contractName: resolved.contractName,
+    pluginName: resolved.pluginName,
+    requiredParams: resolved.requiredParams,
+    allParams: resolved.allParams
+  };
+});
+async function syncAddMenuAttachmentsCore(projectRoot, input) {
+  const request = await readPageRequest(projectRoot, input.requestId);
+  if (!request) {
+    return { ok: false, contentMd: "", error: "Page request not found." };
+  }
+  const requestDir = path.join(
+    projectRoot,
+    ".aiditor",
+    "page-requests",
+    input.requestId
+  );
+  const contentPath = path.join(requestDir, "content.md");
+  let contentMd = "";
+  if (input.contentMd !== void 0) {
+    contentMd = input.contentMd;
+    await writePageRequestMarkdown(projectRoot, input.requestId, {
+      contentMd,
+      designMd: await fs.readFile(path.join(requestDir, "design.md"), "utf-8").catch(() => "")
+    });
+  } else {
+    try {
+      contentMd = await fs.readFile(contentPath, "utf-8");
+    } catch {
+      contentMd = "";
+    }
+  }
+  await writePageRequest(projectRoot, {
+    ...request,
+    addMenuAttachments: input.addMenuAttachments,
+    routeMigration: input.routeMigration,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return { ok: true, contentMd };
 }
+const syncAddMenuAttachmentsAction = makeJayQuery(
+  "aiditor.syncAddMenuAttachments"
+).withServices(DEV_SERVER_SERVICE).withHandler(
+  async (input) => {
+    const projectRoot = process.cwd();
+    return syncAddMenuAttachmentsCore(projectRoot, input);
+  }
+);
 async function contractsForPlugin(projectRoot, pluginName) {
   const fromIndex = await parsePluginsIndexContracts(projectRoot);
   const filtered = fromIndex.filter((c) => c.pluginName === pluginName);
@@ -3205,37 +3629,12 @@ const syncAddPagePluginManifestAction = makeJayQuery(
 ).withServices(DEV_SERVER_SERVICE).withHandler(
   async (input) => {
     const projectRoot = process.cwd();
-    const request = await readPageRequest(projectRoot, input.requestId);
-    if (!request) {
-      return { ok: false, contentMd: "", error: "Page request not found." };
-    }
-    const requestDir = path.join(
-      projectRoot,
-      ".aiditor",
-      "page-requests",
-      input.requestId
-    );
-    const contentPath = path.join(requestDir, "content.md");
-    let contentMd = "";
-    try {
-      contentMd = await fs.readFile(contentPath, "utf-8");
-    } catch {
-      contentMd = "";
-    }
-    const nextMd = syncPluginManifestInContentMd(
-      contentMd,
-      input.selectedPlugins
-    );
-    await writePageRequestMarkdown(projectRoot, input.requestId, {
-      contentMd: nextMd,
-      designMd: await fs.readFile(path.join(requestDir, "design.md"), "utf-8").catch(() => "")
-    });
-    await writePageRequest(projectRoot, {
-      ...request,
-      selectedPlugins: input.selectedPlugins,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    return syncAddMenuAttachmentsCore(projectRoot, {
+      requestId: input.requestId,
+      addMenuAttachments: pagePluginSelectionsToAttachments(
+        input.selectedPlugins
+      )
     });
-    return { ok: true, contentMd: nextMd };
   }
 );
 const writePluginSourceAction = makeJayQuery("aiditor.writePluginSource").withServices(DEV_SERVER_SERVICE).withHandler(async (input) => {
@@ -3243,8 +3642,81 @@ const writePluginSourceAction = makeJayQuery("aiditor.writePluginSource").withSe
   await writePluginSource(projectRoot, input);
   return { ok: true };
 });
-setActionCallerOptions({ timeout: 12e4 });
-const page = makeJayStackComponent().withProps();
+const AIDITOR_ADD_MENU_DOC = "aiditor-add-menu.md";
+const INSTRUCTIONS_LINK_LINE = "- [Add Menu integration](./aiditor-add-menu.md) — contribute catalog items for AIditor";
+async function resolveTemplateDir(fromModuleUrl) {
+  const thisDir = path.dirname(fileURLToPath(fromModuleUrl));
+  const candidates = [
+    path.join(thisDir, "agent-kit-template", "plugin"),
+    path.join(thisDir, "..", "agent-kit-template", "plugin"),
+    path.join(thisDir, "..", "..", "agent-kit-template", "plugin")
+  ];
+  for (const dir of candidates) {
+    const probe = path.join(dir, AIDITOR_ADD_MENU_DOC);
+    try {
+      await fs.access(probe);
+      return dir;
+    } catch {
+    }
+  }
+  throw new Error(
+    `aiditor add-menu template not found (searched from ${thisDir})`
+  );
+}
+async function appendInstructionsLink(instructionsPath, force) {
+  let content;
+  try {
+    content = await fs.readFile(instructionsPath, "utf-8");
+  } catch {
+    return false;
+  }
+  if (content.includes(AIDITOR_ADD_MENU_DOC) && !force) {
+    return false;
+  }
+  if (content.includes(AIDITOR_ADD_MENU_DOC) && force) {
+    return false;
+  }
+  const next = content.trimEnd() + `
+
+## Add Menu
+
+${INSTRUCTIONS_LINK_LINE}
+`;
+  await fs.writeFile(instructionsPath, next, "utf-8");
+  return true;
+}
+async function setupAiditor(ctx) {
+  const templateDir = await resolveTemplateDir(import.meta.url);
+  const srcDoc = path.join(templateDir, AIDITOR_ADD_MENU_DOC);
+  const agentKitPluginDir = path.join(ctx.projectRoot, "agent-kit", "plugin");
+  const destDoc = path.join(agentKitPluginDir, AIDITOR_ADD_MENU_DOC);
+  await fs.mkdir(agentKitPluginDir, { recursive: true });
+  const filesCreated = [];
+  const filesUpdated = [];
+  let exists = false;
+  try {
+    await fs.access(destDoc);
+    exists = true;
+  } catch {
+    exists = false;
+  }
+  if (!exists || ctx.force) {
+    await fs.copyFile(srcDoc, destDoc);
+    if (exists) filesUpdated.push(`agent-kit/plugin/${AIDITOR_ADD_MENU_DOC}`);
+    else filesCreated.push(`agent-kit/plugin/${AIDITOR_ADD_MENU_DOC}`);
+  }
+  const instructionsPath = path.join(agentKitPluginDir, "INSTRUCTIONS.md");
+  const linked = await appendInstructionsLink(instructionsPath, ctx.force);
+  if (linked) {
+    filesUpdated.push("agent-kit/plugin/INSTRUCTIONS.md");
+  }
+  return {
+    status: "configured",
+    message: "AIditor Add Menu contributor guide installed.",
+    ...filesCreated.length > 0 ? { filesCreated } : {},
+    ...filesUpdated.length > 0 ? { filesUpdated } : {}
+  };
+}
 const aiditorShell = makeJayStackComponent().withProps().withSlowlyRender(async () => {
   return phaseOutput({}, { headline: "AIditor" });
 }).withFastRender(async (_props, carryForward) => {
@@ -3256,6 +3728,8 @@ const aiditorShell = makeJayStackComponent().withProps().withSlowlyRender(async
     carryForward
   }));
 });
+setActionCallerOptions({ timeout: 12e4 });
+const page = makeJayStackComponent().withProps();
 export {
   page as aiditorPage,
   aiditorShell,
@@ -3268,6 +3742,7 @@ export {
   getPageParamsAction,
   getPluginSetupStatusAction,
   getProjectInfoAction,
+  listAddMenuItemsAction,
   listFreezesAction,
   listJayPluginsAction,
   listPluginContractsAction,
@@ -3275,10 +3750,13 @@ export {
   readFileAction,
   reclassifyAddPageAssetAction,
   rerunPluginSetupAction,
+  resolveAddMenuContractParamsAction,
   saveAddPageDraftAction,
+  setupAiditor,
   startAddPageRequestAction,
   submitAddPageAction,
   submitTaskAction,
+  syncAddMenuAttachmentsAction,
   syncAddPagePluginManifestAction,
   uploadAddPageAssetAction,
   writePluginSourceAction