agentsmesh 0.33.0 → 0.34.0

package/dist/canonical.js

@@ -24,7 +24,7 @@ var __export = (target34, all) => {
 };
 
 // src/core/errors.ts
-var AgentsMeshError, ConfigNotFoundError, ConfigValidationError, FileSystemError;
+var AgentsMeshError, ConfigNotFoundError, ConfigValidationError, CanonicalParseError, FileSystemError;
 var init_errors = __esm({
   "src/core/errors.ts"() {
     AgentsMeshError = class extends Error {
@@ -59,6 +59,21 @@ var init_errors = __esm({
         this.issues = issues;
       }
     };
+    CanonicalParseError = class extends AgentsMeshError {
+      path;
+      constructor(path, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(
+          "AM_CONFIG_INVALID",
+          `Invalid canonical file ${path}: ${detail}. Fix the syntax and try again.`,
+          {
+            cause
+          }
+        );
+        this.name = "CanonicalParseError";
+        this.path = path;
+      }
+    };
     FileSystemError = class extends AgentsMeshError {
       path;
       errnoCode;
@@ -332,24 +347,28 @@ var init_fs = __esm({
   }
 });
 function parseFrontmatter(content) {
-  const open = content.indexOf("---");
-  if (open !== 0) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-  const close = content.indexOf("---", 3);
-  if (close === -1) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-  const yamlStr = content.slice(3, close).trim();
-  const body = content.slice(close + 3).trim();
+  const split = splitFrontmatter(content);
+  if (split === null) return { frontmatter: {}, body: content.trim() };
+  const yamlStr = split.yaml.trim();
   const frontmatter = yamlStr === "" ? {} : parse(yamlStr) ?? {};
-  return { frontmatter, body };
+  return { frontmatter, body: split.body };
+}
+function splitFrontmatter(content) {
+  const opener = OPENER.exec(content);
+  if (opener === null) return null;
+  const yamlStart = opener[0].length;
+  const closer = CLOSER.exec(content.slice(yamlStart));
+  if (closer === null) return null;
+  const closeStart = yamlStart + closer.index;
+  const closeEnd = closeStart + closer[0].length;
+  return {
+    yaml: content.slice(yamlStart, closeStart),
+    body: content.slice(closeEnd).trim(),
+    prefix: content.slice(0, closeEnd)
+  };
 }
 function extractBody(content) {
-  if (content.indexOf("---") !== 0) return content.trim();
-  const close = content.indexOf("---", 3);
-  if (close === -1) return content.trim();
-  return content.slice(close + 3).trim();
+  return splitFrontmatter(content)?.body ?? content.trim();
 }
 function tryParseFrontmatter(content, filePath2) {
   try {
@@ -381,8 +400,11 @@ ${yamlStr}
 
 ${body}`;
 }
+var OPENER, CLOSER;
 var init_markdown = __esm({
   "src/utils/text/markdown.ts"() {
+    OPENER = /^---[ \t]*\r?\n/;
+    CLOSER = /^---[ \t]*\r?$/m;
   }
 });
 
@@ -465,6 +487,21 @@ var init_boilerplate_filter = __esm({
   }
 });
 
+// src/canonical/features/syntax-error.ts
+function failSyntax(filePath2, cause, onParseError) {
+  const error = new CanonicalParseError(filePath2, cause);
+  if (onParseError !== void 0) {
+    onParseError(error, filePath2);
+    return null;
+  }
+  throw error;
+}
+var init_syntax_error = __esm({
+  "src/canonical/features/syntax-error.ts"() {
+    init_errors();
+  }
+});
+
 // src/canonical/features/mcp.ts
 function parseStringMap(raw) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
@@ -547,14 +584,14 @@ function stripJsonComments(text) {
   }
   return result2;
 }
-async function parseMcp(mcpPath) {
+async function parseMcp(mcpPath, onParseError) {
   const content = await readFileSafe(mcpPath);
   if (!content) return null;
   let parsed;
   try {
     parsed = JSON.parse(stripJsonComments(content));
-  } catch {
-    return null;
+  } catch (err) {
+    return failSyntax(mcpPath, err, onParseError);
   }
   if (!parsed || typeof parsed !== "object") return null;
   const mcpServersRaw = parsed.mcpServers;
@@ -569,6 +606,7 @@ async function parseMcp(mcpPath) {
 }
 var init_mcp = __esm({
   "src/canonical/features/mcp.ts"() {
+    init_syntax_error();
     init_fs();
   }
 });
@@ -598,6 +636,57 @@ var init_hook_command = __esm({
   "src/core/hook-command.ts"() {
   }
 });
+function toHookEntry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw;
+  const matcher = obj.matcher;
+  if (typeof matcher !== "string") return null;
+  const command = getHookText(obj);
+  if (!command) return null;
+  const type = typeof obj.type === "string" && VALID_TYPES.includes(obj.type) ? obj.type : void 0;
+  const timeout = typeof obj.timeout === "number" && Number.isFinite(obj.timeout) ? obj.timeout : void 0;
+  const prompt = getHookPrompt(obj) || void 0;
+  return {
+    matcher,
+    command,
+    ...timeout !== void 0 && { timeout },
+    ...type && { type },
+    ...prompt && { prompt }
+  };
+}
+async function parseHooks(hooksPath, onParseError) {
+  const content = await readFileSafe(hooksPath);
+  if (content === null) return null;
+  if (!content.trim()) return {};
+  let parsed;
+  try {
+    parsed = parse(content);
+  } catch (err) {
+    return failSyntax(hooksPath, err, onParseError);
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const result2 = {};
+  const obj = parsed;
+  for (const [key, val] of Object.entries(obj)) {
+    if (!Array.isArray(val)) continue;
+    const entries = [];
+    for (const item of val) {
+      const entry = toHookEntry(item);
+      if (entry) entries.push(entry);
+    }
+    if (entries.length > 0) result2[key] = entries;
+  }
+  return result2;
+}
+var VALID_TYPES;
+var init_hooks = __esm({
+  "src/canonical/features/hooks.ts"() {
+    init_syntax_error();
+    init_fs();
+    init_hook_command();
+    VALID_TYPES = ["command", "prompt"];
+  }
+});
 function capabilityLevel(capability) {
   return typeof capability === "string" ? capability : capability.level;
 }
@@ -665,8 +754,17 @@ var init_target_descriptor_schema = __esm({
     managedOutputsSchema = z.object({
       dirs: z.array(z.string()),
       files: z.array(z.string()),
-      coOwnedFiles: z.array(z.string()).optional()
+      coOwnedFiles: z.array(z.string()).optional(),
+      supersededFiles: z.array(z.string()).optional()
     }).passthrough().superRefine((value, ctx) => {
+      for (const file of value.supersededFiles ?? []) {
+        if (!value.files.includes(file) && !(value.coOwnedFiles ?? []).includes(file)) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: ["supersededFiles"],
+          message: `"${file}" is in managedOutputs.supersededFiles and another managedOutputs list.`
+        });
+      }
       for (const file of value.coOwnedFiles ?? []) {
         if (!value.files.includes(file)) continue;
         ctx.addIssue({
@@ -1007,11 +1105,25 @@ var init_command_skill = __esm({
     LEGACY_CODEX_COMMAND_SKILL_PREFIX = "ab-command-";
   }
 });
+var RECALL_HOOK_COMMAND;
+var init_recall_hook_scaffold = __esm({
+  "src/lessons/recall-hook-scaffold.ts"() {
+    RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
+  }
+});
 
 // src/core/hook-types.ts
+function isBestEffortHookEvent(event, entries) {
+  if (!BEST_EFFORT_HOOK_EVENTS.has(event)) return false;
+  if (!Array.isArray(entries)) return true;
+  return entries.every(
+    (entry) => typeof entry === "object" && entry !== null && typeof entry.command === "string" && entry.command.includes(RECALL_HOOK_COMMAND)
+  );
+}
 var BEST_EFFORT_HOOK_EVENTS;
 var init_hook_types = __esm({
   "src/core/hook-types.ts"() {
+    init_recall_hook_scaffold();
     BEST_EFFORT_HOOK_EVENTS = /* @__PURE__ */ new Set([
       "UserPromptSubmit",
       "PostToolUseFailure",
@@ -1409,6 +1521,7 @@ function extractEmbeddedRules(content) {
 var ROOT_CONTRACT_START, ROOT_CONTRACT_END, EMBEDDED_RULES_START, EMBEDDED_RULES_END, EMBEDDED_RULE_END, EMBEDDED_RULE_START_PREFIX, EMBEDDED_RULE_START_SUFFIX;
 var init_managed_blocks = __esm({
   "src/targets/projection/managed-blocks.ts"() {
+    init_markdown();
     ROOT_CONTRACT_START = "<!-- agentsmesh:root-generation-contract:start -->";
     ROOT_CONTRACT_END = "<!-- agentsmesh:root-generation-contract:end -->";
     EMBEDDED_RULES_START = "<!-- agentsmesh:embedded-rules:start -->";
@@ -1570,10 +1683,17 @@ async function serializeImportedCommandWithFallback(destinationPath, imported, b
   })();
   const description = imported.hasDescription ? imported.description ?? "" : typeof existingFrontmatter.description === "string" ? existingFrontmatter.description : "";
   const allowedTools = imported.hasAllowedTools ? imported.allowedTools ?? [] : existingAllowedTools;
+  const {
+    description: _d,
+    "allowed-tools": _a,
+    allowedTools: _c,
+    ...preserved
+  } = existingFrontmatter;
   return serializeFrontmatter(
     {
       description,
-      "allowed-tools": allowedTools
+      "allowed-tools": allowedTools,
+      ...preserved
     },
     body.trim() || ""
   );
@@ -2471,6 +2591,26 @@ var init_link_rebaser_resolution = __esm({
   }
 });
 
+// src/core/reference/link-uri-encoding.ts
+function decodeLinkPath(token, role) {
+  if (role !== "markdown-link-dest" || !token.includes("%")) return token;
+  try {
+    return decodeURIComponent(token);
+  } catch {
+    return token;
+  }
+}
+function encodeLinkPath(path, enabled) {
+  if (!enabled) return path;
+  return path.split("/").map(
+    (segment) => segment === "" || segment === "." || segment === ".." ? segment : encodeURIComponent(segment)
+  ).join("/");
+}
+var init_link_uri_encoding = __esm({
+  "src/core/reference/link-uri-encoding.ts"() {
+  }
+});
+
 // src/core/reference/link-token-guards.ts
 function isTildeHomeRelativePathToken(fullContent, matchOffset, matchText) {
   if (matchOffset >= 2 && fullContent[matchOffset - 2] === "~" && fullContent[matchOffset - 1] === "/") {
@@ -2600,10 +2740,11 @@ function rewriteFileLinks(input) {
     const { candidate: punctStripped, suffix } = stripTrailingPunctuation(match);
     if (!punctStripped) return match;
     const lineNumMatch = LINE_NUMBER_SUFFIX.exec(punctStripped);
-    const candidate = lineNumMatch ? punctStripped.slice(0, lineNumMatch.index) : punctStripped;
+    const rawCandidate = lineNumMatch ? punctStripped.slice(0, lineNumMatch.index) : punctStripped;
     const lineNumSuffix = lineNumMatch ? lineNumMatch[0] : "";
-    if (!candidate) return match;
-    const tokenContext = getTokenContext(fullContent, offset, offset + candidate.length);
+    if (!rawCandidate) return match;
+    const tokenContext = getTokenContext(fullContent, offset, offset + rawCandidate.length);
+    const candidate = decodeLinkPath(rawCandidate, tokenContext.role);
     if (tokenContext.role !== "markdown-link-dest" && WINDOWS_ABSOLUTE_PATH.test(candidate)) {
       return match;
     }
@@ -2673,7 +2814,7 @@ function rewriteFileLinks(input) {
     const targetTop = targetFromRoot.split("/").filter(Boolean)[0] ?? "";
     const tokenIsCanonicalMesh = normalizeSeparators(candidate).startsWith(".agentsmesh/");
     const preferRelativeProseInSameSurface = !tokenIsCanonicalMesh && !targetIsDirectory && destTop.length > 0 && destTop === targetTop && destTop.startsWith(".") && destTop !== ".agentsmesh";
-    const forceRelative = preferRelativeProseInSameSurface || tokenContext.role === "markdown-link-dest" || isMarkdownLinkDestinationToken(fullContent, offset, candidate);
+    const forceRelative = preferRelativeProseInSameSurface || tokenContext.role === "markdown-link-dest" || isMarkdownLinkDestinationToken(fullContent, offset, rawCandidate);
     const rewritten = formatLinkPathForDestination(
       input.projectRoot,
       input.destinationFile,
@@ -2690,7 +2831,7 @@ function rewriteFileLinks(input) {
       }
     );
     if (!rewritten) return match;
-    return `${rewritten}${lineNumSuffix}${suffix}`;
+    return `${encodeLinkPath(rewritten, candidate !== rawCandidate)}${lineNumSuffix}${suffix}`;
   });
   return { content, missing: [...missing] };
 }
@@ -2700,6 +2841,7 @@ var init_link_rebaser = __esm({
     init_link_rebaser_helpers();
     init_link_rebaser_output();
     init_link_rebaser_resolution();
+    init_link_uri_encoding();
     init_link_token_guards();
     init_link_token_context();
   }
@@ -3504,7 +3646,7 @@ function unsupportedHookEventNames(hooks, supportedEvents) {
   if (!hooks) return [];
   const supported = new Set(supportedEvents);
   return Object.keys(hooks).filter(
-    (event) => !supported.has(event) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => !supported.has(event) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function createUnsupportedHookWarning(event, target34, supportedEvents, options) {
@@ -8816,10 +8958,10 @@ var init_claude_code2 = __esm({
       skillDir: ".claude/skills",
       managedOutputs: {
         dirs: [".claude/agents", ".claude/commands", ".claude/rules", ".claude/skills"],
-        // CLAUDE_NESTED_ROOT is the pre-migration project location; listing it here lets
-        // `cleanupStaleGeneratedOutputs` evict a leftover `.claude/CLAUDE.md` once generation
+        files: [CLAUDE_ROOT, ".claudeignore"],
+        // CLAUDE_NESTED_ROOT is the pre-migration project location: evicted once a run
         // writes the root `CLAUDE.md`, so Claude Code never concatenates both into context.
-        files: [CLAUDE_ROOT, CLAUDE_NESTED_ROOT, ".claudeignore"],
+        supersededFiles: [CLAUDE_NESTED_ROOT],
         // `.mcp.json` is the shared project MCP file teams hand-commit and
         // deepagents-cli writes too; agentsmesh owns only `mcpServers` in it.
         // `.claude/settings.json` is co-owned through the `SETTINGS_JSON_PATHS`
@@ -10050,9 +10192,8 @@ var init_cline2 = __esm({
     };
   }
 });
-function ruleSlug3(source) {
-  return basename(source, ".md");
-}
+
+// src/targets/codex-cli/codex-rule-paths.ts
 function directoryFromGlob(glob) {
   let normalized = glob.trim();
   if (normalized.startsWith("./")) normalized = normalized.slice(2);
@@ -10073,12 +10214,12 @@ function codexRuleDirectory(rule) {
     const dir = directoryFromGlob(glob);
     if (dir) return dir;
   }
-  return ruleSlug3(rule.source);
+  return null;
 }
 function codexNestedAgentsPath(rule) {
   const dir = codexRuleDirectory(rule);
   const filename = rule.codexInstructionVariant === "override" ? "AGENTS.override.md" : "AGENTS.md";
-  return `${dir}/${filename}`;
+  return dir === null ? filename : `${dir}/${filename}`;
 }
 var GLOB_METACHAR;
 var init_codex_rule_paths = __esm({
@@ -10086,10 +10227,9 @@ var init_codex_rule_paths = __esm({
     GLOB_METACHAR = /[*?[\]]/;
   }
 });
-
-// src/targets/codebuff/rule-paths.ts
 function codebuffNestedKnowledgePath(rule) {
-  return `${codexRuleDirectory(rule)}/AGENTS.md`;
+  const dir = codexRuleDirectory(rule) ?? basename(rule.source, ".md");
+  return `${dir}/AGENTS.md`;
 }
 var init_rule_paths = __esm({
   "src/targets/codebuff/rule-paths.ts"() {
@@ -10700,6 +10840,9 @@ function eligibleAdvisoryRules(canonical) {
     return rule.targets.length === 0 || rule.targets.includes("codex-cli");
   });
 }
+function isRootEmbedded(rule) {
+  return codexNestedAgentsPath(rule) === AGENTS_MD;
+}
 function groupByNestedPath2(rules) {
   const groups = /* @__PURE__ */ new Map();
   for (const rule of rules) {
@@ -10712,9 +10855,11 @@ function groupByNestedPath2(rules) {
 }
 function generateRules9(canonical) {
   const root = canonical.rules.find((r) => r.root);
+  const advisory = eligibleAdvisoryRules(canonical);
   const outputs = [];
   if (root) {
-    outputs.push({ path: AGENTS_MD, content: root.body.trim() });
+    const content = appendEmbeddedRulesBlock(root.body.trim(), advisory.filter(isRootEmbedded));
+    outputs.push({ path: AGENTS_MD, content });
   }
   for (const rule of canonical.rules) {
     if (rule.root) continue;
@@ -10726,7 +10871,8 @@ function generateRules9(canonical) {
       content: toSafeCodexRulesContent(rule.body)
     });
   }
-  for (const [path, rules] of groupByNestedPath2(eligibleAdvisoryRules(canonical))) {
+  const nested = advisory.filter((rule) => !isRootEmbedded(rule));
+  for (const [path, rules] of groupByNestedPath2(nested)) {
     const content = rules.map((rule) => rule.body.trim()).filter((body) => body.length > 0).join("\n\n");
     outputs.push({ path, content });
   }
@@ -10953,7 +11099,7 @@ function generateHooks6(canonical) {
     supportedEvents: CODEX_SUPPORTED_HOOK_EVENTS
   });
 }
-var init_hooks = __esm({
+var init_hooks2 = __esm({
   "src/targets/codex-cli/generator/hooks.ts"() {
     init_wrapped_command_hooks();
     init_constants10();
@@ -11034,7 +11180,7 @@ var init_generator9 = __esm({
     init_skills();
     init_agents();
     init_mcp2();
-    init_hooks();
+    init_hooks2();
     init_permissions();
   }
 });
@@ -11551,6 +11697,23 @@ var init_linter9 = __esm({
 });
 
 // src/targets/codex-cli/lint.ts
+function lintAgents3(canonical) {
+  const diagnostics = [];
+  for (const agent of canonical.agents) {
+    const dropped = CODEX_DROPPED_AGENT_FIELDS.filter(
+      (field) => hasAgentValue(agent, field)
+    ).sort();
+    if (dropped.length === 0) continue;
+    diagnostics.push(
+      createWarning(
+        agent.source,
+        "codex-cli",
+        `Codex agent TOML supports name, description, developer_instructions, model, sandbox_mode and mcp_servers; canonical ${dropped.join(", ")} are not projected to ${CODEX_AGENTS_DIR}/${agent.name}.toml.`
+      )
+    );
+  }
+  return diagnostics;
+}
 function lintMcp4(canonical) {
   if (!canonical.mcp || Object.keys(canonical.mcp.mcpServers).length === 0) return [];
   const diagnostics = [];
@@ -11582,11 +11745,21 @@ function lintHooks7(canonical) {
     (event) => createUnsupportedHookWarning(event, "codex-cli", CODEX_SUPPORTED_HOOK_EVENTS)
   );
 }
+var CODEX_DROPPED_AGENT_FIELDS;
 var init_lint8 = __esm({
   "src/targets/codex-cli/lint.ts"() {
     init_helpers();
     init_mcp_servers();
+    init_agents_format();
     init_constants10();
+    CODEX_DROPPED_AGENT_FIELDS = [
+      "tools",
+      "disallowedTools",
+      "maxTurns",
+      "hooks",
+      "skills",
+      "memory"
+    ];
   }
 });
 
@@ -11661,6 +11834,7 @@ var init_codex_cli2 = __esm({
       generateMcp: generateMcp6,
       generateHooks: generateHooks6,
       generatePermissions: generatePermissions7,
+      lint: lintAgents3,
       importFrom: importFromCodex
     };
     project6 = {
@@ -11708,7 +11882,7 @@ var init_codex_cli2 = __esm({
       },
       rewriteGeneratedPath(path) {
         if (path === AGENTS_MD) return CODEX_GLOBAL_AGENTS_MD;
-        if (/\/AGENTS(\.override)?\.md$/.test(path)) return null;
+        if (/(^|\/)AGENTS(\.override)?\.md$/.test(path)) return null;
         if (path.startsWith(`${CODEX_INSTRUCTIONS_DIR}/`)) return null;
         return path;
       },
@@ -11975,7 +12149,7 @@ async function importContinueHooks(projectRoot, results) {
   });
 }
 var CONTINUE_HOOK_EVENTS, mergeContinueSettings;
-var init_hooks2 = __esm({
+var init_hooks3 = __esm({
   "src/targets/continue/hooks.ts"() {
     init_hooks_format2();
     init_settings_helpers2();
@@ -12243,7 +12417,7 @@ var init_importer10 = __esm({
     init_shared_import_helpers();
     init_constants11();
     init_permissions2();
-    init_hooks2();
+    init_hooks3();
     init_continue2();
   }
 });
@@ -12364,7 +12538,7 @@ function hasValue(agent, field) {
   if (value && typeof value === "object") return Object.keys(value).length > 0;
   return false;
 }
-function lintAgents3(canonical) {
+function lintAgents4(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     const dropped = DROPPED_FIELDS.filter((field) => hasValue(agent, field)).sort();
@@ -12384,7 +12558,7 @@ var init_lint9 = __esm({
   "src/targets/continue/lint.ts"() {
     init_helpers();
     init_constants11();
-    init_hooks2();
+    init_hooks3();
     DROPPED_FIELDS = [
       "disallowedTools",
       "permissionMode",
@@ -12510,7 +12684,7 @@ var target10, descriptor10;
 var init_continue2 = __esm({
   "src/targets/continue/index.ts"() {
     init_generator11();
-    init_hooks2();
+    init_hooks3();
     init_config_merge2();
     init_capabilities5();
     init_layout4();
@@ -12532,7 +12706,7 @@ var init_continue2 = __esm({
       generateHooks: generateHooks7,
       generateIgnore: generateIgnore8,
       // Feature-independent lint hook: agent warnings must not hang off `rules`.
-      lint: lintAgents3,
+      lint: lintAgents4,
       importFrom: importFromContinue
     };
     descriptor10 = {
@@ -12789,7 +12963,7 @@ var init_hook_format = __esm({
     init_hook_entry();
   }
 });
-function ruleSlug4(source) {
+function ruleSlug3(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -12823,7 +12997,7 @@ function generateRules11(canonical) {
     if (rule.root) continue;
     if (rule.targets.length > 0 && !rule.targets.includes("copilot")) continue;
     if (rule.globs.length === 0) continue;
-    const slug = ruleSlug4(rule.source);
+    const slug = ruleSlug3(rule.source);
     const frontmatter = {
       description: rule.description || void 0,
       applyTo: rule.globs.length === 1 ? rule.globs[0] : rule.globs
@@ -14312,13 +14486,18 @@ var init_rules2 = __esm({
 
 // src/targets/cursor/generator/commands.ts
 function generateCommands13(canonical) {
-  return canonical.commands.map((cmd) => ({
-    path: `${CURSOR_COMMANDS_DIR}/${cmd.name}.md`,
-    content: cmd.body.trim() || ""
-  }));
+  return canonical.commands.map((cmd) => {
+    const frontmatter = {};
+    if (cmd.description) frontmatter.description = cmd.description;
+    return {
+      path: `${CURSOR_COMMANDS_DIR}/${cmd.name}.md`,
+      content: serializeFrontmatter(frontmatter, cmd.body.trim() || "")
+    };
+  });
 }
 var init_commands = __esm({
   "src/targets/cursor/generator/commands.ts"() {
+    init_markdown();
     init_constants13();
   }
 });
@@ -14413,7 +14592,7 @@ var init_permissions3 = __esm({
 // src/targets/cursor/hook-format.ts
 function unmappedCursorHookEvents(hooks) {
   return Object.keys(hooks).filter(
-    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_CURSOR) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function toCursorHooks(hooks) {
@@ -14488,7 +14667,7 @@ function generateHooks10(canonical) {
   const content = JSON.stringify({ version: 1, hooks: cursorHooks }, null, 2);
   return [{ path: CURSOR_HOOKS, content }];
 }
-var init_hooks3 = __esm({
+var init_hooks4 = __esm({
   "src/targets/cursor/generator/hooks.ts"() {
     init_constants13();
     init_hook_format2();
@@ -14516,7 +14695,7 @@ var init_generator14 = __esm({
     init_skills2();
     init_agents2();
     init_permissions3();
-    init_hooks3();
+    init_hooks4();
     init_ignore();
   }
 });
@@ -14851,14 +15030,11 @@ async function hasGlobalCursorArtifacts(projectRoot) {
     join(projectRoot, CURSOR_GLOBAL_USER_RULES),
     join(projectRoot, CURSOR_MCP),
     join(projectRoot, CURSOR_HOOKS),
-    join(projectRoot, CURSOR_IGNORE),
-    join(projectRoot, CURSOR_SKILLS_DIR),
-    join(projectRoot, CURSOR_AGENTS_DIR),
-    join(projectRoot, CURSOR_COMMANDS_DIR)
+    join(projectRoot, CURSOR_IGNORE)
   ];
   for (const p of candidates) {
-    const stat7 = await readFileSafe(p);
-    if (stat7 !== null && stat7.trim() !== "") return true;
+    const content = await readFileSafe(p);
+    if (content !== null && content.trim() !== "") return true;
   }
   const skillFiles = await readDirRecursiveNoSymlinks(join(projectRoot, CURSOR_SKILLS_DIR));
   if (skillFiles.some((f) => f.endsWith(".md"))) return true;
@@ -15145,11 +15321,11 @@ function lintHooks10(canonical) {
   ];
 }
 function lintCommands6(canonical) {
-  return canonical.commands.filter((command) => command.description.length > 0 || command.allowedTools.length > 0).map(
+  return canonical.commands.filter((command) => command.allowedTools.length > 0).map(
     (command) => createWarning(
       command.source,
       "cursor",
-      "Cursor command files are plain Markdown; command description and allowed-tools metadata are not projected."
+      "Cursor command files project only description frontmatter; allowed-tools metadata is not projected."
     )
   );
 }
@@ -15482,7 +15658,7 @@ var init_mcp_merge4 = __esm({
 // src/targets/deepagents-cli/hooks-format.ts
 function unmappedDeepagentsHookEvents(hooks) {
   return Object.keys(hooks).filter(
-    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_DEEPAGENTS) && !BEST_EFFORT_HOOK_EVENTS.has(event)
+    (event) => Array.isArray(hooks[event]) && hooks[event].length > 0 && !(event in CANONICAL_TO_DEEPAGENTS) && !isBestEffortHookEvent(event, hooks[event])
   );
 }
 function toDeepagentsHooks(hooks) {
@@ -16050,7 +16226,8 @@ var init_deepagents_cli2 = __esm({
         }
       },
       buildImportPaths: buildDeepagentsCliImportPaths,
-      detectionPaths: [DEEPAGENTS_CLI_ROOT_FILE, DEEPAGENTS_CLI_MCP_FILE]
+      // `.mcp.json` is co-owned with claude-code (agentsmesh writes it), so it must not enroll this target.
+      detectionPaths: [DEEPAGENTS_CLI_ROOT_FILE]
     };
   }
 });
@@ -20028,7 +20205,8 @@ var init_layout8 = __esm({
       skillDir: KIMI_CODE_SKILLS_DIR,
       managedOutputs: {
         dirs: [KIMI_CODE_AGENTS_DIR, KIMI_CODE_SKILLS_DIR],
-        files: [KIMI_CODE_ROOT_FILE, KIMI_CODE_NESTED_ROOT_FILE],
+        files: [KIMI_CODE_ROOT_FILE],
+        supersededFiles: [KIMI_CODE_NESTED_ROOT_FILE],
         // Kimi Code's own MCP config, in the same directory as the credential-
         // bearing config.toml this layout already refuses to delete.
         coOwnedFiles: [KIMI_CODE_MCP_FILE]
@@ -20676,7 +20854,7 @@ function lintMcp9(canonical) {
   }
   return diagnostics;
 }
-function lintAgents4(canonical) {
+function lintAgents5(canonical) {
   return canonical.agents.flatMap((agent) => {
     const dropped = DROPPED_AGENT_FIELDS.filter(([, has]) => has(agent)).map(([field]) => field);
     if (dropped.length === 0) return [];
@@ -20767,7 +20945,7 @@ var init_kimi_code2 = __esm({
       generateHooks: generateHooks14,
       generatePermissions: generatePermissions16,
       importFrom: importFromKimiCode,
-      lint: lintAgents4
+      lint: lintAgents5
     };
     capabilities9 = {
       rules: "native",
@@ -23065,7 +23243,7 @@ function lintAgentFields(agent) {
     )
   ];
 }
-function lintAgents5(canonical) {
+function lintAgents6(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     diagnostics.push(...lintAgentFields(agent));
@@ -23127,7 +23305,7 @@ var init_openhands2 = __esm({
       generatePermissions: generatePermissions19,
       importFrom: importFromOpenhands,
       // Ungated by feature, so agent-only feature sets still get the warning.
-      lint: lintAgents5
+      lint: lintAgents6
     };
     descriptor24 = {
       id: OPENHANDS_TARGET,
@@ -26942,7 +27120,7 @@ var init_constants34 = __esm({
     WINDSURF_GLOBAL_AGENTS_SKILLS_DIR = ".agents/skills";
   }
 });
-function ruleSlug5(source) {
+function ruleSlug4(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -26963,7 +27141,7 @@ function generateRules32(canonical) {
   for (const rule of canonical.rules) {
     if (rule.root) continue;
     if (rule.targets.length > 0 && !rule.targets.includes("windsurf")) continue;
-    const slug = ruleSlug5(rule.source);
+    const slug = ruleSlug4(rule.source);
     const normalizedTrigger = rule.trigger || (rule.globs.length > 0 ? "glob" : void 0);
     const frontmatter = {
       description: rule.description || void 0,
@@ -27067,19 +27245,34 @@ var init_mcp4 = __esm({
   }
 });
 
-// src/targets/windsurf/generator/hooks.ts
+// src/targets/windsurf/hook-events.ts
 function windsurfEventName(event) {
-  const explicit = {
-    PreToolUse: "pre_tool_use",
-    PostToolUse: "post_tool_use",
-    Notification: "notification",
-    UserPromptSubmit: "user_prompt_submit",
-    SubagentStart: "subagent_start",
-    SubagentStop: "subagent_stop"
-  };
-  if (explicit[event]) return explicit[event];
   return event.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
 }
+function canonicalHookEventName(event) {
+  if (KNOWN_CANONICAL_HOOK_EVENTS.includes(event)) return event;
+  return WINDSURF_TO_CANONICAL.get(event) ?? null;
+}
+var KNOWN_CANONICAL_HOOK_EVENTS, WINDSURF_TO_CANONICAL;
+var init_hook_events = __esm({
+  "src/targets/windsurf/hook-events.ts"() {
+    init_hook_types();
+    KNOWN_CANONICAL_HOOK_EVENTS = [
+      "PreToolUse",
+      "PostToolUse",
+      "Notification",
+      "UserPromptSubmit",
+      "SubagentStart",
+      "SubagentStop",
+      ...BEST_EFFORT_HOOK_EVENTS
+    ];
+    WINDSURF_TO_CANONICAL = new Map(
+      KNOWN_CANONICAL_HOOK_EVENTS.map((event) => [windsurfEventName(event), event])
+    );
+  }
+});
+
+// src/targets/windsurf/generator/hooks.ts
 function toWindsurfHooks(hooks) {
   const result2 = {};
   for (const [event, entries] of Object.entries(hooks)) {
@@ -27103,10 +27296,11 @@ function generateHooks22(canonical) {
   if (Object.keys(hooks).length === 0) return [];
   return [{ path: WINDSURF_HOOKS_FILE, content: JSON.stringify({ hooks }, null, 2) }];
 }
-var init_hooks4 = __esm({
+var init_hooks5 = __esm({
   "src/targets/windsurf/generator/hooks.ts"() {
     init_hook_command();
     init_constants34();
+    init_hook_events();
   }
 });
 
@@ -27154,7 +27348,7 @@ var init_generator35 = __esm({
     init_workflows();
     init_agents4();
     init_mcp4();
-    init_hooks4();
+    init_hooks5();
     init_skills4();
     init_permissions6();
   }
@@ -27245,9 +27439,10 @@ async function importWindsurfHooks(projectRoot, results) {
   try {
     const parsed = JSON.parse(hooksContent);
     if (!parsed.hooks || typeof parsed.hooks !== "object" || Array.isArray(parsed.hooks)) return;
-    const canonical = windsurfHooksToCanonical(parsed.hooks);
-    if (Object.keys(canonical).length === 0) return;
     const destPath = join(projectRoot, WINDSURF_CANONICAL_HOOKS);
+    const existing = await parseHooks(destPath) ?? {};
+    const canonical = windsurfHooksToCanonical(parsed.hooks, existing);
+    if (Object.keys(canonical).length === 0) return;
     await mkdirp(dirname(destPath));
     await writeFileAtomic(destPath, stringify(canonical));
     results.push({
@@ -27259,54 +27454,63 @@ async function importWindsurfHooks(projectRoot, results) {
   } catch {
   }
 }
-function canonicalHookEventName(event) {
-  const explicit = {
-    pre_tool_use: "PreToolUse",
-    post_tool_use: "PostToolUse",
-    notification: "Notification",
-    user_prompt_submit: "UserPromptSubmit",
-    subagent_start: "SubagentStart",
-    subagent_stop: "SubagentStop"
-  };
-  return explicit[event] ?? event;
+function preservedMatcher(existing, event, command) {
+  const match = existing[event]?.find((entry) => entry.command === command);
+  return match?.matcher ?? WILDCARD_MATCHER;
 }
-function windsurfHooksToCanonical(hooks) {
+function legacyEntries(entry) {
+  const matcher = typeof entry.matcher === "string" && entry.matcher.trim() ? entry.matcher : WILDCARD_MATCHER;
+  const hooksList = Array.isArray(entry.hooks) ? entry.hooks : [];
+  const out2 = [];
+  for (const item of hooksList) {
+    if (!item || typeof item !== "object") continue;
+    const hook = item;
+    const command = typeof hook.command === "string" ? hook.command : typeof hook.prompt === "string" ? hook.prompt : "";
+    if (!command.trim()) continue;
+    const canonical = {
+      matcher,
+      type: hook.type === "prompt" ? "prompt" : "command",
+      command
+    };
+    if (typeof hook.timeout === "number") canonical.timeout = hook.timeout;
+    out2.push(canonical);
+  }
+  return out2;
+}
+function windsurfHooksToCanonical(hooks, existing) {
   const result2 = {};
   for (const [event, entries] of Object.entries(hooks)) {
     if (!Array.isArray(entries)) continue;
     const mappedEvent = canonicalHookEventName(event);
+    if (mappedEvent === null) continue;
     const canonicalEntries = [];
     for (const entry of entries) {
       if (!entry || typeof entry !== "object") continue;
       const e = entry;
       if (typeof e.command === "string" && e.command.trim()) {
         canonicalEntries.push({
-          matcher: ".*",
+          matcher: preservedMatcher(existing, mappedEvent, e.command),
           type: "command",
           command: e.command
         });
         continue;
       }
-      const matcher = typeof e.matcher === "string" && e.matcher.trim() ? e.matcher : ".*";
-      const hooksList = Array.isArray(e.hooks) ? e.hooks : [];
-      for (const item of hooksList) {
-        if (!item || typeof item !== "object") continue;
-        const hook = item;
-        const command = typeof hook.command === "string" ? hook.command : typeof hook.prompt === "string" ? hook.prompt : "";
-        if (!command.trim()) continue;
-        const canonical = {
-          matcher,
-          type: hook.type === "prompt" ? "prompt" : "command",
-          command
-        };
-        if (typeof hook.timeout === "number") canonical.timeout = hook.timeout;
-        canonicalEntries.push(canonical);
-      }
+      canonicalEntries.push(...legacyEntries(e));
     }
     if (canonicalEntries.length > 0) result2[mappedEvent] = canonicalEntries;
   }
   return result2;
 }
+var WILDCARD_MATCHER;
+var init_importer_hooks2 = __esm({
+  "src/targets/windsurf/importer-hooks.ts"() {
+    init_hooks();
+    init_fs();
+    init_constants34();
+    init_hook_events();
+    WILDCARD_MATCHER = "*";
+  }
+});
 async function importWindsurfMcp(projectRoot, results) {
   const sourceCandidates = [WINDSURF_MCP_EXAMPLE_FILE, WINDSURF_MCP_CONFIG_FILE];
   for (const relPath of sourceCandidates) {
@@ -27330,8 +27534,8 @@ async function importWindsurfMcp(projectRoot, results) {
     }
   }
 }
-var init_importer_hooks_mcp = __esm({
-  "src/targets/windsurf/importer-hooks-mcp.ts"() {
+var init_importer_mcp = __esm({
+  "src/targets/windsurf/importer-mcp.ts"() {
     init_fs();
     init_constants34();
   }
@@ -27481,7 +27685,8 @@ var init_importer32 = __esm({
     init_constants34();
     init_importer_workflows();
     init_skills_adapter5();
-    init_importer_hooks_mcp();
+    init_importer_hooks2();
+    init_importer_mcp();
   }
 });
 
@@ -27566,9 +27771,28 @@ function lintPermissions22(canonical) {
     )
   ];
 }
+function lintHooks23(canonical) {
+  if (!canonical.hooks) return [];
+  const diagnostics = [];
+  for (const [event, entries] of Object.entries(canonical.hooks)) {
+    for (const entry of entries ?? []) {
+      if (WILDCARD_MATCHERS.has(entry.matcher.trim())) continue;
+      diagnostics.push(
+        createWarning(
+          ".agentsmesh/hooks.yaml",
+          "windsurf",
+          `Windsurf hooks have no matcher field; ${event} hook "${entry.command}" runs on every ${event} event (matcher "${entry.matcher}" is not projected).`
+        )
+      );
+    }
+  }
+  return diagnostics;
+}
+var WILDCARD_MATCHERS;
 var init_lint31 = __esm({
   "src/targets/windsurf/lint.ts"() {
     init_helpers();
+    WILDCARD_MATCHERS = /* @__PURE__ */ new Set(["", "*", ".*"]);
   }
 });
 
@@ -27724,6 +27948,7 @@ var init_windsurf2 = __esm({
       lintRules: lintRules32,
       lint: {
         commands: lintCommands10,
+        hooks: lintHooks23,
         mcp: lintMcp13,
         permissions: lintPermissions22
       },
@@ -29301,24 +29526,14 @@ async function sweepStaleCache(cacheDir, maxAgeMs) {
 
 // src/config/remote/remote-fetcher.ts
 var MAX_CACHE_KEY_LENGTH = 80;
+var CACHE_KEY_HASH_LENGTH = 12;
 function buildCacheKey(provider, identifier, ref) {
   const safe = (value) => value.replace(/[^a-zA-Z0-9_.-]/g, "_").replace(/^\.+/, "_");
-  let key;
-  if (provider === "github") {
-    const [org, repo] = identifier.split("/", 2);
-    if (org && repo) {
-      key = `${safe(org)}--${safe(repo)}--${safe(ref)}`;
-    } else {
-      key = `${safe(provider)}__${safe(identifier)}__${safe(ref)}`;
-    }
-  } else {
-    key = `${safe(provider)}__${safe(identifier)}__${safe(ref)}`;
-  }
-  if (key.length > MAX_CACHE_KEY_LENGTH) {
-    const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
-    key = `${key.slice(0, MAX_CACHE_KEY_LENGTH - 18)}--${hash}`;
-  }
-  return key;
+  const [org, repo] = provider === "github" ? identifier.split("/", 2) : [];
+  const readable = org && repo ? `${safe(org)}--${safe(repo)}--${safe(ref)}` : `${safe(provider)}__${safe(identifier)}__${safe(ref)}`;
+  const hash = createHash("sha256").update(`${provider}|${identifier}|${ref}`).digest("hex").slice(0, CACHE_KEY_HASH_LENGTH);
+  const maxReadable = MAX_CACHE_KEY_LENGTH - CACHE_KEY_HASH_LENGTH - 2;
+  return `${readable.slice(0, maxReadable)}--${hash}`;
 }
 function getCacheDir() {
   const env = process.env.AGENTSMESH_CACHE;
@@ -29430,6 +29645,92 @@ async function resolveExtendPaths(config, configDir, options = {}) {
   return result2;
 }
 
+// src/utils/output/color.ts
+function noColorRequested() {
+  const value = process.env.NO_COLOR;
+  return value !== void 0 && value !== "";
+}
+function forceColorRequested() {
+  const value = process.env.FORCE_COLOR;
+  if (value === void 0) return void 0;
+  return value !== "0" && value !== "false";
+}
+function colorEnabled(stream = process.stdout) {
+  const forced = forceColorRequested();
+  if (forced !== void 0) return forced;
+  if (noColorRequested()) return false;
+  return stream.isTTY === true;
+}
+
+// src/utils/output/logger.ts
+var C = {
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m",
+  reset: "\x1B[0m"
+};
+function outStream() {
+  return process.stdout;
+}
+function out(text) {
+  outStream().write(text);
+}
+function c(code, text, stream) {
+  return colorEnabled(stream) ? `${code}${text}${C.reset}` : text;
+}
+function pad(str3, width) {
+  const len = [...str3].length;
+  return str3 + " ".repeat(Math.max(0, width - len));
+}
+var logger = {
+  info(msg) {
+    out(c(C.cyan, msg, outStream()) + "\n");
+  },
+  warn(msg) {
+    process.stderr.write(c(C.yellow, "\u26A0 ", process.stderr) + msg + "\n");
+  },
+  error(msg) {
+    process.stderr.write(c(C.red, "\u2717 ", process.stderr) + msg + "\n");
+  },
+  success(msg) {
+    out(c(C.green, "\u2713 ", outStream()) + msg + "\n");
+  },
+  debug(msg) {
+    if (process.env.AGENTSMESH_DEBUG === "1") {
+      out(c(C.cyan, "[debug] ", outStream()) + msg + "\n");
+    }
+  },
+  table(rows) {
+    if (rows.length === 0) return;
+    const cols = rows[0].length;
+    const widths = [];
+    for (let j = 0; j < cols; j++) {
+      let max = 0;
+      for (let i = 0; i < rows.length; i++) {
+        const len = [...rows[i][j]].length;
+        if (len > max) max = len;
+      }
+      widths[j] = max;
+    }
+    const border = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
+    out(border + "\n");
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const line = "| " + row.map((cell, j) => pad(cell, widths[j])).join(" | ") + " |";
+      out(line + "\n");
+    }
+    out(border + "\n");
+  }
+};
+
+// src/canonical/features/empty-file.ts
+function isEmptyCanonicalFile(content, path) {
+  if (content.trim() !== "") return false;
+  logger.warn(`Skipping empty canonical file ${path.replaceAll("\\", "/")}`);
+  return true;
+}
+
 // src/canonical/features/rules.ts
 init_fs();
 init_markdown();
@@ -29525,87 +29826,6 @@ function assertNoBasenameCollisions(feature, paths2, stripExt) {
     seen.set(key, { path: p, slug });
   }
 }
-
-// src/utils/output/color.ts
-function noColorRequested() {
-  const value = process.env.NO_COLOR;
-  return value !== void 0 && value !== "";
-}
-function forceColorRequested() {
-  const value = process.env.FORCE_COLOR;
-  if (value === void 0) return void 0;
-  return value !== "0" && value !== "false";
-}
-function colorEnabled(stream = process.stdout) {
-  const forced = forceColorRequested();
-  if (forced !== void 0) return forced;
-  if (noColorRequested()) return false;
-  return stream.isTTY === true;
-}
-
-// src/utils/output/logger.ts
-var C = {
-  green: "\x1B[32m",
-  red: "\x1B[31m",
-  yellow: "\x1B[33m",
-  cyan: "\x1B[36m",
-  reset: "\x1B[0m"
-};
-function outStream() {
-  return process.stdout;
-}
-function out(text) {
-  outStream().write(text);
-}
-function c(code, text, stream) {
-  return colorEnabled(stream) ? `${code}${text}${C.reset}` : text;
-}
-function pad(str3, width) {
-  const len = [...str3].length;
-  return str3 + " ".repeat(Math.max(0, width - len));
-}
-var logger = {
-  info(msg) {
-    out(c(C.cyan, msg, outStream()) + "\n");
-  },
-  warn(msg) {
-    process.stderr.write(c(C.yellow, "\u26A0 ", process.stderr) + msg + "\n");
-  },
-  error(msg) {
-    process.stderr.write(c(C.red, "\u2717 ", process.stderr) + msg + "\n");
-  },
-  success(msg) {
-    out(c(C.green, "\u2713 ", outStream()) + msg + "\n");
-  },
-  debug(msg) {
-    if (process.env.AGENTSMESH_DEBUG === "1") {
-      out(c(C.cyan, "[debug] ", outStream()) + msg + "\n");
-    }
-  },
-  table(rows) {
-    if (rows.length === 0) return;
-    const cols = rows[0].length;
-    const widths = [];
-    for (let j = 0; j < cols; j++) {
-      let max = 0;
-      for (let i = 0; i < rows.length; i++) {
-        const len = [...rows[i][j]].length;
-        if (len > max) max = len;
-      }
-      widths[j] = max;
-    }
-    const border = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
-    out(border + "\n");
-    for (let i = 0; i < rows.length; i++) {
-      const row = rows[i];
-      const line = "| " + row.map((cell, j) => pad(cell, widths[j])).join(" | ") + " |";
-      out(line + "\n");
-    }
-    out(border + "\n");
-  }
-};
-
-// src/canonical/features/unrecognized-files-warning.ts
 var ALTERNATE_RESOURCE_FORMATS = /* @__PURE__ */ new Set([".toml", ".yaml", ".yml", ".json"]);
 function warnIfUnrecognizedResourceFormats(featureLabel, dir, allFiles, parsedFiles, opts = {}) {
   if (allFiles.length === 0) return;
@@ -29650,7 +29870,8 @@ async function parseRules(rulesDir, opts = {}) {
   const rules = [];
   for (const path of mdFiles) {
     const content = await readFileSafe(path);
-    if (!content) continue;
+    if (content === null) continue;
+    if (isEmptyCanonicalFile(content, path)) continue;
     const parsed = parseOrSkipFrontmatter(content, path, opts.onParseError);
     if (!parsed) continue;
     const { frontmatter, body } = parsed;
@@ -29704,7 +29925,8 @@ async function parseCommands(commandsDir, opts = {}) {
   const commands = [];
   for (const path of mdFiles) {
     const content = await readFileSafe(path);
-    if (!content) continue;
+    if (content === null) continue;
+    if (isEmptyCanonicalFile(content, path)) continue;
     const parsed = parseOrSkipFrontmatter(content, path, opts.onParseError);
     if (!parsed) continue;
     const { frontmatter, body } = parsed;
@@ -29764,15 +29986,14 @@ async function parseAgents(agentsDir, opts = {}) {
   const agents = [];
   for (const path of mdFiles) {
     const content = await readFileSafe(path);
-    if (!content) continue;
+    if (content === null) continue;
+    if (isEmptyCanonicalFile(content, path)) continue;
     const parsed = parseOrSkipFrontmatter(content, path, opts.onParseError);
     if (!parsed) continue;
     const { frontmatter, body } = parsed;
     const name = basename(path, ".md");
     assertCanonicalName("agent", name);
-    const toolsCamel = toStrArray2(frontmatter.tools);
-    const toolsKebab = toStrArray2(frontmatter["tools"]);
-    const tools = toolsCamel.length > 0 ? toolsCamel : toolsKebab;
+    const tools = toStrArray2(frontmatter.tools);
     const disallowedCamel = toStrArray2(frontmatter.disallowedTools);
     const disallowedKebab = toStrArray2(frontmatter["disallowed-tools"]);
     const disallowedTools = disallowedCamel.length > 0 ? disallowedCamel : disallowedKebab;
@@ -29894,20 +30115,21 @@ async function parseSkills(skillsDir, opts = {}) {
 init_mcp();
 
 // src/canonical/features/permissions.ts
+init_syntax_error();
 init_fs();
 function ensureStringArray(val) {
   if (!Array.isArray(val)) return [];
   return val.filter((x) => typeof x === "string");
 }
-async function parsePermissions(permissionsPath) {
+async function parsePermissions(permissionsPath, onParseError) {
   const content = await readFileSafe(permissionsPath);
   if (content === null) return null;
   if (!content.trim()) return { allow: [], deny: [], ask: [] };
   let parsed;
   try {
     parsed = parse(content);
-  } catch {
-    return null;
+  } catch (err) {
+    return failSyntax(permissionsPath, err, onParseError);
   }
   if (!parsed || typeof parsed !== "object") return null;
   const obj = parsed;
@@ -29917,52 +30139,8 @@ async function parsePermissions(permissionsPath) {
   return { allow, deny, ask };
 }
 
-// src/canonical/features/hooks.ts
-init_fs();
-init_hook_command();
-var VALID_TYPES = ["command", "prompt"];
-function toHookEntry(raw) {
-  if (!raw || typeof raw !== "object") return null;
-  const obj = raw;
-  const matcher = obj.matcher;
-  if (typeof matcher !== "string") return null;
-  const command = getHookText(obj);
-  if (!command) return null;
-  const type = typeof obj.type === "string" && VALID_TYPES.includes(obj.type) ? obj.type : void 0;
-  const timeout = typeof obj.timeout === "number" && Number.isFinite(obj.timeout) ? obj.timeout : void 0;
-  const prompt = getHookPrompt(obj) || void 0;
-  return {
-    matcher,
-    command,
-    ...timeout !== void 0 && { timeout },
-    ...type && { type },
-    ...prompt && { prompt }
-  };
-}
-async function parseHooks(hooksPath) {
-  const content = await readFileSafe(hooksPath);
-  if (content === null) return null;
-  if (!content.trim()) return {};
-  let parsed;
-  try {
-    parsed = parse(content);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
-  const result2 = {};
-  const obj = parsed;
-  for (const [key, val] of Object.entries(obj)) {
-    if (!Array.isArray(val)) continue;
-    const entries = [];
-    for (const item of val) {
-      const entry = toHookEntry(item);
-      if (entry) entries.push(entry);
-    }
-    if (entries.length > 0) result2[key] = entries;
-  }
-  return result2;
-}
+// src/canonical/load/loader.ts
+init_hooks();
 
 // src/canonical/features/ignore.ts
 init_fs();
@@ -29989,9 +30167,9 @@ async function loadCanonicalFiles(canonicalDirOrProjectRoot, opts = {}) {
     parseCommands(join(canonicalDir, "commands"), opts),
     parseAgents(join(canonicalDir, "agents"), opts),
     parseSkills(join(canonicalDir, "skills"), opts),
-    parseMcp(join(canonicalDir, "mcp.json")),
-    parsePermissions(join(canonicalDir, "permissions.yaml")),
-    parseHooks(join(canonicalDir, "hooks.yaml")),
+    parseMcp(join(canonicalDir, "mcp.json"), opts.onParseError),
+    parsePermissions(join(canonicalDir, "permissions.yaml"), opts.onParseError),
+    parseHooks(join(canonicalDir, "hooks.yaml"), opts.onParseError),
     parseIgnore(join(canonicalDir, "ignore"))
   ]);
   return {
@@ -30894,6 +31072,7 @@ function gateExtendElevatedArtifacts(canonical, ext) {
   });
 }
 init_mcp();
+init_hooks();
 
 // src/install/pack/pack-reader.ts
 init_fs();
@@ -31217,8 +31396,46 @@ function mergeLocalConfig(project26, local) {
   if (Array.isArray(local.extends) && local.extends.length > 0) {
     merged.extends = [...project26.extends ?? [], ...local.extends];
   }
+  if (Array.isArray(local.plugins)) {
+    merged.plugins = mergeById(project26.plugins, local.plugins);
+  }
+  if (Array.isArray(local.pluginTargets)) {
+    merged.pluginTargets = [.../* @__PURE__ */ new Set([...project26.pluginTargets, ...local.pluginTargets])];
+  }
+  if (typeof local.collaboration === "object" && local.collaboration !== null && !Array.isArray(local.collaboration)) {
+    merged.collaboration = local.collaboration;
+  }
+  warnUnhandledLocalKeys(local);
   return merged;
 }
+var LOCAL_KEYS = /* @__PURE__ */ new Set([
+  "version",
+  "targets",
+  "features",
+  "overrides",
+  "conversions",
+  "extends",
+  "plugins",
+  "pluginTargets",
+  "collaboration"
+]);
+function warnUnhandledLocalKeys(local) {
+  const unknown = Object.keys(local).filter((key) => !LOCAL_KEYS.has(key));
+  if (unknown.length === 0) return;
+  logger.warn(
+    `agentsmesh.local.yaml: ignoring unknown key(s) ${unknown.join(", ")}; supported keys are ${[...LOCAL_KEYS].join(", ")}.`
+  );
+}
+function mergeById(project26, local) {
+  const byId = /* @__PURE__ */ new Map();
+  const anonymous = [];
+  for (const entry of [...project26, ...local]) {
+    const id = typeof entry === "object" && entry !== null && typeof entry.id === "string" ? entry.id : void 0;
+    if (id === void 0) anonymous.push(entry);
+    else byId.set(id, entry);
+  }
+  return [...byId.values(), ...anonymous];
+}
 async function loadConfigFromExactDir(configDir) {
   const configPath = join(configDir, CONFIG_FILENAME);
   let config = await loadConfig(configPath);