agentsmesh 0.33.0 → 0.34.0

package/dist/engine.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { parse, stringify, parseDocument, isMap, Document, isSeq, isScalar, Scalar, Pair, YAMLSeq } from 'yaml';
+import { existsSync, readFileSync, constants, readdirSync, realpathSync, statSync } from 'fs';
 import { basename, join, dirname, relative, win32, posix, sep, resolve, extname } from 'path';
 import { readFile, rm, mkdir, readdir, lstat, unlink, writeFile, rename, chmod, access, stat, realpath, mkdtemp, cp } from 'fs/promises';
 import { setTimeout } from 'timers/promises';
-import { existsSync, readFileSync, constants, readdirSync, realpathSync, statSync } from 'fs';
 import { parse as parse$1, stringify as stringify$1 } from 'smol-toml';
 import { Buffer } from 'buffer';
 import { homedir, tmpdir } from 'os';
@@ -94,8 +94,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({
@@ -398,24 +407,28 @@ var init_target_ids = __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 {
@@ -447,8 +460,11 @@ ${yamlStr}
 
 ${body}`;
 }
+var OPENER, CLOSER;
 var init_markdown = __esm({
   "src/utils/text/markdown.ts"() {
+    OPENER = /^---[ \t]*\r?\n/;
+    CLOSER = /^---[ \t]*\r?$/m;
   }
 });
 
@@ -508,11 +524,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",
@@ -698,7 +728,7 @@ var init_conf_merge = __esm({
 });
 
 // src/core/errors.ts
-var AgentsMeshError, ConfigNotFoundError, ConfigValidationError, TargetNotFoundError, ImportError, GenerationError, RemoteFetchError, LockAcquisitionError, FileSystemError;
+var AgentsMeshError, ConfigNotFoundError, ConfigValidationError, CanonicalParseError, TargetNotFoundError, ImportError, GenerationError, RemoteFetchError, LockAcquisitionError, FileSystemError;
 var init_errors = __esm({
   "src/core/errors.ts"() {
     AgentsMeshError = class extends Error {
@@ -733,6 +763,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;
+      }
+    };
     TargetNotFoundError = class extends AgentsMeshError {
       target;
       constructor(target34, options) {
@@ -806,6 +851,11 @@ function normalizeLineEndings(content) {
 function executableModeFor(path) {
   return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
 }
+function normalizeTextPayload(path, content) {
+  if (!shouldNormalizeLineEndings(path)) return content;
+  const withoutBom = content.startsWith(UTF8_BOM) ? content.slice(UTF8_BOM.length) : content;
+  return normalizeLineEndings(withoutBom);
+}
 var UTF8_BOM, TEXT_EXTENSIONS, TEXT_DOTFILES, EXECUTABLE_SCRIPT_EXTENSIONS;
 var init_fs_text_encoding = __esm({
   "src/utils/filesystem/fs-text-encoding.ts"() {
@@ -1306,10 +1356,8 @@ function stripManagedBlock(content, start, end) {
   return content.replace(managedBlockPattern(start, end), "").trim();
 }
 function splitFrontmatterPrefix(content) {
-  if (content.indexOf("---") !== 0) return { prefix: "", body: content.trim() };
-  const close = content.indexOf("---", 3);
-  if (close === -1) return { prefix: "", body: content.trim() };
-  return { prefix: content.slice(0, close + 3), body: content.slice(close + 3).trim() };
+  const split = splitFrontmatter(content);
+  return split === null ? { prefix: "", body: content.trim() } : { prefix: split.prefix, body: split.body };
 }
 function insertAtBodyTop(content, block) {
   const { prefix, body } = splitFrontmatterPrefix(content);
@@ -1410,6 +1458,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 -->";
@@ -1575,10 +1624,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() || ""
   );
@@ -2476,6 +2532,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] === "/") {
@@ -2605,10 +2681,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;
     }
@@ -2678,7 +2755,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,
@@ -2695,7 +2772,7 @@ function rewriteFileLinks(input) {
       }
     );
     if (!rewritten) return match;
-    return `${rewritten}${lineNumSuffix}${suffix}`;
+    return `${encodeLinkPath(rewritten, candidate !== rawCandidate)}${lineNumSuffix}${suffix}`;
   });
   return { content, missing: [...missing] };
 }
@@ -2705,6 +2782,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();
   }
@@ -3588,7 +3666,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) {
@@ -7125,6 +7203,21 @@ var init_embedded_rules = __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 {};
@@ -7207,14 +7300,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;
@@ -7229,6 +7322,7 @@ async function parseMcp(mcpPath) {
 }
 var init_mcp = __esm({
   "src/canonical/features/mcp.ts"() {
+    init_syntax_error();
     init_fs();
   }
 });
@@ -9008,10 +9102,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`
@@ -10242,9 +10336,8 @@ var init_cline2 = __esm({
     };
   }
 });
-function ruleSlug2(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);
@@ -10265,12 +10358,12 @@ function codexRuleDirectory(rule) {
     const dir = directoryFromGlob(glob);
     if (dir) return dir;
   }
-  return ruleSlug2(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({
@@ -10278,10 +10371,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"() {
@@ -10892,6 +10984,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) {
@@ -10904,9 +10999,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;
@@ -10918,7 +11015,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 });
   }
@@ -11743,6 +11841,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 = [];
@@ -11774,11 +11889,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"
+    ];
   }
 });
 
@@ -11853,6 +11978,7 @@ var init_codex_cli2 = __esm({
       generateMcp: generateMcp6,
       generateHooks: generateHooks6,
       generatePermissions: generatePermissions7,
+      lint: lintAgents3,
       importFrom: importFromCodex
     };
     project6 = {
@@ -11900,7 +12026,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;
       },
@@ -12556,7 +12682,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();
@@ -12724,7 +12850,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 = {
@@ -12981,7 +13107,7 @@ var init_hook_format = __esm({
     init_hook_entry();
   }
 });
-function ruleSlug3(source) {
+function ruleSlug2(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -13015,7 +13141,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 = ruleSlug3(rule.source);
+    const slug = ruleSlug2(rule.source);
     const frontmatter = {
       description: rule.description || void 0,
       applyTo: rule.globs.length === 1 ? rule.globs[0] : rule.globs
@@ -14504,13 +14630,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();
   }
 });
@@ -14605,7 +14736,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) {
@@ -15043,14 +15174,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;
@@ -15337,11 +15465,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."
     )
   );
 }
@@ -15674,7 +15802,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) {
@@ -16242,7 +16370,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]
     };
   }
 });
@@ -20220,7 +20349,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]
@@ -20868,7 +20998,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 [];
@@ -20959,7 +21089,7 @@ var init_kimi_code2 = __esm({
       generateHooks: generateHooks14,
       generatePermissions: generatePermissions16,
       importFrom: importFromKimiCode,
-      lint: lintAgents4
+      lint: lintAgents5
     };
     capabilities9 = {
       rules: "native",
@@ -23257,7 +23387,7 @@ function lintAgentFields(agent) {
     )
   ];
 }
-function lintAgents5(canonical) {
+function lintAgents6(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     diagnostics.push(...lintAgentFields(agent));
@@ -23319,7 +23449,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,
@@ -27134,7 +27264,7 @@ var init_constants34 = __esm({
     WINDSURF_GLOBAL_AGENTS_SKILLS_DIR = ".agents/skills";
   }
 });
-function ruleSlug4(source) {
+function ruleSlug3(source) {
   const name = basename(source, ".md");
   return name === "_root" ? "root" : name;
 }
@@ -27155,7 +27285,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 = ruleSlug4(rule.source);
+    const slug = ruleSlug3(rule.source);
     const normalizedTrigger = rule.trigger || (rule.globs.length > 0 ? "glob" : void 0);
     const frontmatter = {
       description: rule.description || void 0,
@@ -27259,19 +27389,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)) {
@@ -27299,6 +27444,7 @@ var init_hooks4 = __esm({
   "src/targets/windsurf/generator/hooks.ts"() {
     init_hook_command();
     init_constants34();
+    init_hook_events();
   }
 });
 
@@ -27430,6 +27576,57 @@ var init_skills_adapter5 = __esm({
     init_constants34();
   }
 });
+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_hooks5 = __esm({
+  "src/canonical/features/hooks.ts"() {
+    init_syntax_error();
+    init_fs();
+    init_hook_command();
+    VALID_TYPES = ["command", "prompt"];
+  }
+});
 async function importWindsurfHooks(projectRoot, results) {
   const hooksPath = join(projectRoot, WINDSURF_HOOKS_FILE);
   const hooksContent = await readFileSafe(hooksPath);
@@ -27437,9 +27634,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({
@@ -27451,54 +27649,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 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) {
+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_hooks5();
+    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) {
@@ -27522,8 +27729,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();
   }
@@ -27673,7 +27880,8 @@ var init_importer32 = __esm({
     init_constants34();
     init_importer_workflows();
     init_skills_adapter5();
-    init_importer_hooks_mcp();
+    init_importer_hooks2();
+    init_importer_mcp();
   }
 });
 
@@ -27758,9 +27966,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(["", "*", ".*"]);
   }
 });
 
@@ -27916,6 +28143,7 @@ var init_windsurf2 = __esm({
       lintRules: lintRules32,
       lint: {
         commands: lintCommands10,
+        hooks: lintHooks23,
         mcp: lintMcp13,
         permissions: lintPermissions22
       },
@@ -29785,6 +30013,7 @@ function ruleNameFromSource(source) {
 }
 
 // src/core/generate/collision.ts
+init_fs_text_encoding();
 init_target_ids();
 var AGENTS_SUFFIX = "AGENTS.md";
 function statusRank(status) {
@@ -29893,7 +30122,7 @@ function assertNoCaseOnlyPathCollisions(results) {
   }
 }
 function refreshResultStatus(result2) {
-  const status = result2.currentContent === void 0 ? "created" : result2.currentContent !== result2.content ? "updated" : "unchanged";
+  const status = result2.currentContent === void 0 ? "created" : normalizeTextPayload(result2.path, result2.currentContent) !== normalizeTextPayload(result2.path, result2.content) ? "updated" : "unchanged";
   return result2.status === status ? result2 : { ...result2, status };
 }
 
@@ -30298,8 +30527,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);
@@ -30788,24 +31055,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;
@@ -30917,6 +31174,13 @@ async function resolveExtendPaths(config, configDir, options = {}) {
   return result2;
 }
 
+// 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();
@@ -31056,7 +31320,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;
@@ -31110,7 +31375,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;
@@ -31170,15 +31436,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;
@@ -31300,20 +31565,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;
@@ -31323,52 +31589,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_hooks5();
 
 // src/canonical/features/ignore.ts
 init_fs();
@@ -31395,9 +31617,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 {
@@ -31411,13 +31633,13 @@ async function loadCanonicalFiles(canonicalDirOrProjectRoot, opts = {}) {
     ignore
   };
 }
-function ruleSlug5(r) {
+function ruleSlug4(r) {
   return basename(r.source, ".md");
 }
 function mergeCanonicalFiles(base, overlay) {
-  const baseRuleMap = new Map(base.rules.map((r) => [ruleSlug5(r), r]));
+  const baseRuleMap = new Map(base.rules.map((r) => [ruleSlug4(r), r]));
   for (const r of overlay.rules) {
-    baseRuleMap.set(ruleSlug5(r), r);
+    baseRuleMap.set(ruleSlug4(r), r);
   }
   const baseCmdMap = new Map(base.commands.map((c2) => [c2.name, c2]));
   for (const c2 of overlay.commands) {
@@ -32300,6 +32522,7 @@ function gateExtendElevatedArtifacts(canonical, ext) {
   });
 }
 init_mcp();
+init_hooks5();
 
 // src/install/pack/pack-reader.ts
 init_fs();
@@ -33026,47 +33249,6 @@ function collectOrphans(graph, findings) {
   }
 }
 
-// src/lessons/ranking-text.ts
-var STOP = /* @__PURE__ */ new Set([
-  "the",
-  "a",
-  "an",
-  "to",
-  "of",
-  "in",
-  "and",
-  "or",
-  "for",
-  "is",
-  "on",
-  "at",
-  "with",
-  "be",
-  "as",
-  "it",
-  "that",
-  "this",
-  "its",
-  "must"
-]);
-function tokenize(text) {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
-}
-
-// src/lessons/keyword-signal.ts
-var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
-function isLowSignalKeyword(pattern) {
-  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
-}
-function splitRawTokens(pattern) {
-  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
-}
-function keywordNeedleLosesTokens(pattern) {
-  const raw = splitRawTokens(pattern);
-  if (raw.length < 2) return false;
-  return tokenize(pattern).length !== raw.length;
-}
-
 // src/lessons/regex-linear/nfa-compile.ts
 var MAX_NFA_STATES = 2e3;
 var Builder = class {
@@ -33479,6 +33661,10 @@ function isSafeRegexPattern(pattern) {
   if (pattern.length > MAX_PATTERN_LENGTH) return false;
   return compileLinearMatcher(pattern) !== null;
 }
+function getCommandMatcher(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) return null;
+  return compileLinearMatcher(pattern);
+}
 
 // src/lessons/validate-quality.ts
 function collectDuplicateRules(graph, findings) {
@@ -33583,6 +33769,52 @@ function collectFanout(graph, findings) {
     });
   }
 }
+function normalizeRule(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/lessons/ranking-text.ts
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "to",
+  "of",
+  "in",
+  "and",
+  "or",
+  "for",
+  "is",
+  "on",
+  "at",
+  "with",
+  "be",
+  "as",
+  "it",
+  "that",
+  "this",
+  "its",
+  "must"
+]);
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
+}
+
+// src/lessons/keyword-signal.ts
+var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
+function isLowSignalKeyword(pattern) {
+  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
+}
+function splitRawTokens(pattern) {
+  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function keywordNeedleLosesTokens(pattern) {
+  const raw = splitRawTokens(pattern);
+  if (raw.length < 2) return false;
+  return tokenize(pattern).length !== raw.length;
+}
+
+// src/lessons/validate-keywords.ts
 function collectLowSignalKeywords(graph, findings) {
   const activeTriggerIds2 = /* @__PURE__ */ new Set();
   for (const lesson of Object.values(graph.lessons)) {
@@ -33596,7 +33828,7 @@ function collectLowSignalKeywords(graph, findings) {
     findings.push({
       level: "warning",
       code: "LOW_SIGNAL_KEYWORD",
-      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
+      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
       triggerId
     });
   }
@@ -33621,9 +33853,62 @@ function collectStopwordKeywords(graph, findings) {
     });
   }
 }
-function normalizeRule(rule) {
-  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+
+// src/lessons/glob-breadth.ts
+var WILDCARD = /[*?[\]]/;
+function globNarrowness(pattern) {
+  const segments = pattern.replaceAll("\\", "/").split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.length === 0) return 0;
+  let literal = 0;
+  let globstars = 0;
+  for (const segment of segments) {
+    if (segment === "**") globstars += 1;
+    else if (!WILDCARD.test(segment)) literal += 1;
+  }
+  return literal / (segments.length + globstars);
+}
+var BROAD_GLOB_NARROWNESS = 0.34;
+function isBroadFileGlob(pattern) {
+  return globNarrowness(pattern) < BROAD_GLOB_NARROWNESS;
+}
+
+// src/lessons/command-pattern-breadth.ts
+var COMMAND_PROBE_CORPUS = [
+  "git status",
+  'git commit -m "wip"',
+  "pnpm test",
+  "npx vitest run src/x.test.ts",
+  "ls -la",
+  "cat README.md",
+  "rm -rf dist",
+  "mkdir -p build/out",
+  "node scripts/build.js",
+  "docker compose up -d",
+  "curl -s https://example.com",
+  "echo hello > out.txt",
+  "sed -i 's/a/b/' file.txt",
+  "pnpm lint --fix",
+  "python3 -m pytest",
+  "cargo build --release",
+  "make",
+  "npm install --global typescript",
+  "cp a.txt b.txt",
+  "grep -rn TODO src"
+];
+var BROAD_HIT_RATIO = 0.5;
+var PROBE_BUDGET = 1e5;
+function isBroadCommandPattern(pattern) {
+  const matcher = getCommandMatcher(pattern);
+  if (matcher === null) return false;
+  if (matcher.test("", { remaining: PROBE_BUDGET })) return true;
+  let hits = 0;
+  for (const command of COMMAND_PROBE_CORPUS) {
+    if (matcher.test(command, { remaining: PROBE_BUDGET })) hits += 1;
+  }
+  return hits > COMMAND_PROBE_CORPUS.length * BROAD_HIT_RATIO;
 }
+
+// src/lessons/validate-liveness.ts
 function activeTriggerIds(graph) {
   const ids = /* @__PURE__ */ new Set();
   for (const lesson of Object.values(graph.lessons)) {
@@ -33669,6 +33954,34 @@ function collectRunnerAnchoredPatterns(graph, findings) {
     });
   }
 }
+function collectBroadFileGlobs(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadFileGlob(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${trigger.pattern}) matches most of the repository, so it outranks nothing and crowds the recall budget. Narrow it to the directory or file class the rule is really about, or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+function collectBroadCommandPatterns(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadCommandPattern(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_COMMAND_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) matches nearly every command, so the lesson fires on every recall. Key it on the action (e.g. \`\\bgit commit\\b\`), or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
 
 // src/lessons/validate.ts
 function validateLessonsGraph(graph, options = {}) {
@@ -33696,6 +34009,8 @@ function validateLessonsGraph(graph, options = {}) {
   collectLowSignalKeywords(graph, findings);
   collectStopwordKeywords(graph, findings);
   collectRunnerAnchoredPatterns(graph, findings);
+  collectBroadCommandPatterns(graph, findings);
+  collectBroadFileGlobs(graph, findings);
   if (options.knownPaths !== void 0) collectDeadFileGlobs(graph, findings, options.knownPaths);
   const ok = findings.every((f) => f.level !== "error");
   return { ok, findings };
@@ -33747,13 +34062,13 @@ function diag(level, file, message) {
 
 // src/core/lint/linter.ts
 var EXCLUDE_DIRS = ["node_modules", ".git", "dist", "coverage", ".agentsmesh"];
+function isExcludedProjectPath(rel2) {
+  const posix9 = rel2.replaceAll("\\", "/");
+  return EXCLUDE_DIRS.some((d) => posix9.includes(`/${d}/`) || posix9.startsWith(`${d}/`));
+}
 async function getProjectFiles(projectRoot) {
   const all = await readDirRecursive(projectRoot);
-  const filtered = all.filter((p) => {
-    const rel2 = relative(projectRoot, p);
-    return !EXCLUDE_DIRS.some((d) => rel2.includes(`/${d}/`) || rel2.startsWith(`${d}/`));
-  });
-  return filtered.map((p) => relative(projectRoot, p));
+  return all.filter((p) => !isExcludedProjectPath(relative(projectRoot, p))).map((p) => relative(projectRoot, p));
 }
 async function runLint(config, canonical, projectRoot, targetFilter, options = {}) {
   const scope = options.scope ?? "project";
@@ -34015,6 +34330,7 @@ async function diffOutputChecksums(rootBase, lockOutputs) {
 // src/core/generate/stale-cleanup.ts
 init_fs();
 init_builtin_targets();
+init_registry();
 async function listFiles2(root, base = root) {
   const entries = await readdir(root, { withFileTypes: true });
   const files = [];
@@ -34035,6 +34351,11 @@ function retainedDirs(inactiveTargets, scope) {
   }
   return dirs;
 }
+function primaryEmitted(target34, scope, expected) {
+  const descriptor34 = getBuiltinTargetDefinition(target34) ?? getDescriptor(target34);
+  const primary = getTargetLayout(target34, scope)?.rootInstructionPath ?? descriptor34?.generators.primaryRootInstructionPath;
+  return primary !== void 0 && expected.has(primary);
+}
 async function findStaleGeneratedOutputs(args) {
   const expected = new Set(args.expectedPaths);
   const stale = /* @__PURE__ */ new Set();
@@ -34046,7 +34367,13 @@ async function findStaleGeneratedOutputs(args) {
     const managed = getTargetManagedOutputs(target34, scope);
     if (!managed) continue;
     for (const file of managed.coOwnedFiles ?? []) coOwned.add(file);
-    for (const file of managed.files) stale.add(file);
+    for (const file of managed.files) {
+      if (generated !== null && !generated.has(file)) continue;
+      stale.add(file);
+    }
+    if (primaryEmitted(target34, scope, expected)) {
+      for (const file of managed.supersededFiles ?? []) stale.add(file);
+    }
     for (const dir of managed.dirs) {
       if (retained.has(dir)) continue;
       const absDir = join(args.projectRoot, dir);