agentsmesh 0.33.0 → 0.35.0

package/dist/index.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap, isMap, Document, isSeq, isScalar, Scalar, Pair } from 'yaml';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, constants, rmSync, renameSync, readdirSync, realpathSync, statSync } from 'fs';
 import { join, resolve, relative, sep, dirname, basename, win32, posix, extname } from 'path';
 import { mkdir, access, readdir, rm, readFile, writeFile, stat, lstat, unlink, rename, chmod, realpath, mkdtemp, cp } from 'fs/promises';
 import { setTimeout as setTimeout$1 } from 'timers/promises';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, constants, rmSync, renameSync, readdirSync, realpathSync, statSync } from 'fs';
 import { parse as parse$1, stringify as stringify$1 } from 'smol-toml';
 import { Buffer } from 'buffer';
 import { homedir, hostname, 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,74 @@ var init_command_skill = __esm({
     LEGACY_CODEX_COMMAND_SKILL_PREFIX = "ab-command-";
   }
 });
+function removeEvent(doc, event) {
+  const existing = doc.get(event);
+  if (!(existing instanceof YAMLSeq)) return false;
+  const kept = existing.items.filter(
+    (item) => !(item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND)
+  );
+  if (kept.length === existing.items.length) return false;
+  if (kept.length === 0) doc.delete(event);
+  else existing.items = kept;
+  return true;
+}
+function injectEvent(doc, event, matcher) {
+  const existing = doc.get(event);
+  const seq = existing instanceof YAMLSeq ? existing : new YAMLSeq();
+  const present = seq.items.some(
+    (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
+  );
+  if (present) return false;
+  seq.add(doc.createNode({ matcher, type: "command", command: RECALL_HOOK_COMMAND }));
+  doc.set(event, seq);
+  return true;
+}
+function injectRecallHook(projectRoot) {
+  const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
+  if (!existsSync(path)) return false;
+  const doc = parseDocument(readFileSync(path, "utf8"));
+  let changed = false;
+  for (const { event, matcher } of RECALL_EVENTS) {
+    if (injectEvent(doc, event, matcher)) changed = true;
+  }
+  for (const event of RETIRED_EVENTS) {
+    if (removeEvent(doc, event)) changed = true;
+  }
+  if (changed) writeFileSync(path, String(doc), "utf8");
+  return changed;
+}
+var RECALL_HOOK_COMMAND, RECALL_HOOK_TOOL_MATCHER, RECALL_EVENTS, RETIRED_EVENTS;
+var init_recall_hook_scaffold = __esm({
+  "src/lessons/recall-hook-scaffold.ts"() {
+    RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
+    RECALL_HOOK_TOOL_MATCHER = "Edit|Write|Bash";
+    RECALL_EVENTS = [
+      { event: "PreToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
+      { event: "UserPromptSubmit", matcher: "*" },
+      // Capture-on-failure nudge (see capture-nudge.ts). BEST-EFFORT: only Claude
+      // Code's passthrough hooks emit it; whitelist targets drop it without warning
+      // (BEST_EFFORT_HOOK_EVENTS). PostToolUse is success-only, so failures need this.
+      { event: "PostToolUseFailure", matcher: "*" },
+      // Reset recall dedup after a context compaction/clear (see hook.ts SessionStart).
+      // BEST-EFFORT: targets that can't represent SessionStart just keep dedup as-is.
+      { event: "SessionStart", matcher: "*" }
+    ];
+    RETIRED_EVENTS = ["PostToolUse"];
+  }
+});
 
 // 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 +777,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 +812,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 +900,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 +1405,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 +1507,7 @@ function extractEmbeddedRules(content) {
 var ROOT_CONTRACT_START, ROOT_CONTRACT_END, LESSONS_CONTRACT_START, LESSONS_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 -->";
     LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
@@ -1577,10 +1675,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() || ""
   );
@@ -2478,6 +2583,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] === "/") {
@@ -2607,10 +2732,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;
     }
@@ -2680,7 +2806,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,
@@ -2697,7 +2823,7 @@ function rewriteFileLinks(input) {
       }
     );
     if (!rewritten) return match;
-    return `${rewritten}${lineNumSuffix}${suffix}`;
+    return `${encodeLinkPath(rewritten, candidate !== rawCandidate)}${lineNumSuffix}${suffix}`;
   });
   return { content, missing: [...missing] };
 }
@@ -2707,6 +2833,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();
   }
@@ -3590,7 +3717,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) {
@@ -7127,6 +7254,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 {};
@@ -7209,14 +7351,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;
@@ -7231,6 +7373,7 @@ async function parseMcp(mcpPath) {
 }
 var init_mcp = __esm({
   "src/canonical/features/mcp.ts"() {
+    init_syntax_error();
     init_fs();
   }
 });
@@ -9010,10 +9153,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`
@@ -10244,9 +10387,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);
@@ -10267,12 +10409,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({
@@ -10280,10 +10422,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"() {
@@ -10894,6 +11035,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) {
@@ -10906,9 +11050,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;
@@ -10920,7 +11066,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 });
   }
@@ -11745,6 +11892,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 = [];
@@ -11776,11 +11940,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"
+    ];
   }
 });
 
@@ -11855,6 +12029,7 @@ var init_codex_cli2 = __esm({
       generateMcp: generateMcp6,
       generateHooks: generateHooks6,
       generatePermissions: generatePermissions7,
+      lint: lintAgents3,
       importFrom: importFromCodex
     };
     project6 = {
@@ -11902,7 +12077,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;
       },
@@ -12558,7 +12733,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();
@@ -12726,7 +12901,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 = {
@@ -12983,7 +13158,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;
 }
@@ -13017,7 +13192,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
@@ -14506,13 +14681,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();
   }
 });
@@ -14607,7 +14787,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) {
@@ -15045,14 +15225,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 stat8 = await readFileSafe(p);
-    if (stat8 !== null && stat8.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;
@@ -15339,11 +15516,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."
     )
   );
 }
@@ -15676,7 +15853,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) {
@@ -16244,7 +16421,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]
     };
   }
 });
@@ -20222,7 +20400,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]
@@ -20870,7 +21049,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 [];
@@ -20961,7 +21140,7 @@ var init_kimi_code2 = __esm({
       generateHooks: generateHooks14,
       generatePermissions: generatePermissions16,
       importFrom: importFromKimiCode,
-      lint: lintAgents4
+      lint: lintAgents5
     };
     capabilities9 = {
       rules: "native",
@@ -23259,7 +23438,7 @@ function lintAgentFields(agent) {
     )
   ];
 }
-function lintAgents5(canonical) {
+function lintAgents6(canonical) {
   const diagnostics = [];
   for (const agent of canonical.agents) {
     diagnostics.push(...lintAgentFields(agent));
@@ -23321,7 +23500,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,
@@ -27136,7 +27315,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;
 }
@@ -27157,7 +27336,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,
@@ -27261,19 +27440,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)) {
@@ -27301,6 +27495,7 @@ var init_hooks4 = __esm({
   "src/targets/windsurf/generator/hooks.ts"() {
     init_hook_command();
     init_constants34();
+    init_hook_events();
   }
 });
 
@@ -27432,6 +27627,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);
@@ -27439,9 +27685,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({
@@ -27453,54 +27700,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_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) {
@@ -27524,8 +27780,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();
   }
@@ -27675,7 +27931,8 @@ var init_importer32 = __esm({
     init_constants34();
     init_importer_workflows();
     init_skills_adapter5();
-    init_importer_hooks_mcp();
+    init_importer_hooks2();
+    init_importer_mcp();
   }
 });
 
@@ -27760,9 +28017,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(["", "*", ".*"]);
   }
 });
 
@@ -27918,6 +28194,7 @@ var init_windsurf2 = __esm({
       lintRules: lintRules32,
       lint: {
         commands: lintCommands10,
+        hooks: lintHooks23,
         mcp: lintMcp13,
         permissions: lintPermissions22
       },
@@ -29787,6 +30064,7 @@ function ruleNameFromSource(source) {
 }
 
 // src/core/generate/collision.ts
+init_fs_text_encoding();
 init_target_ids();
 var AGENTS_SUFFIX = "AGENTS.md";
 function statusRank(status) {
@@ -29895,7 +30173,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 };
 }
 
@@ -30300,8 +30578,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);
@@ -30790,24 +31106,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;
@@ -30919,6 +31225,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();
@@ -31058,7 +31371,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;
@@ -31112,7 +31426,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;
@@ -31172,15 +31487,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;
@@ -31302,20 +31616,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;
@@ -31325,52 +31640,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();
@@ -31397,9 +31668,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 {
@@ -31413,13 +31684,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) {
@@ -32302,6 +32573,7 @@ function gateExtendElevatedArtifacts(canonical, ext) {
   });
 }
 init_mcp();
+init_hooks5();
 
 // src/install/pack/pack-reader.ts
 init_fs();
@@ -33067,88 +33339,6 @@ function collectOrphans(graph, findings) {
   }
 }
 
-// src/lessons/ranking-text.ts
-var K1 = 1.5;
-var B = 0.75;
-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));
-}
-function queryTerms(query) {
-  const parts = [];
-  if (query.keyword !== void 0) parts.push(query.keyword);
-  if (query.file !== void 0) parts.push(query.file);
-  if (query.command !== void 0) parts.push(query.command);
-  return tokenize(parts.join(" "));
-}
-function buildCorpus(graph) {
-  const docs = [];
-  const df = /* @__PURE__ */ new Map();
-  let total = 0;
-  let n = 0;
-  for (const lesson of Object.values(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    const toks = tokenize(lesson.rule);
-    n += 1;
-    total += toks.length;
-    docs.push(toks.length);
-    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
-  }
-  const N = Math.max(n, 1);
-  const idf = /* @__PURE__ */ new Map();
-  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
-  return { idf, avgdl: total / N || 1 };
-}
-function bm25(terms, ruleText, corpus) {
-  const toks = tokenize(ruleText);
-  const dl = toks.length || 1;
-  const tf = /* @__PURE__ */ new Map();
-  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
-  let score = 0;
-  for (const t of new Set(terms)) {
-    const f = tf.get(t) ?? 0;
-    if (f === 0) continue;
-    const idf = corpus.idf.get(t);
-    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
-  }
-  return score;
-}
-
-// 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 {
@@ -33669,6 +33859,93 @@ function collectFanout(graph, findings) {
     });
   }
 }
+function normalizeRule(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/lessons/ranking-text.ts
+var K1 = 1.5;
+var B = 0.75;
+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));
+}
+function queryTerms(query) {
+  const parts = [];
+  if (query.keyword !== void 0) parts.push(query.keyword);
+  if (query.file !== void 0) parts.push(query.file);
+  if (query.command !== void 0) parts.push(query.command);
+  return tokenize(parts.join(" "));
+}
+function buildCorpus(graph) {
+  const docs = [];
+  const df = /* @__PURE__ */ new Map();
+  let total = 0;
+  let n = 0;
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    const toks = tokenize(lesson.rule);
+    n += 1;
+    total += toks.length;
+    docs.push(toks.length);
+    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  const N = Math.max(n, 1);
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
+  return { idf, avgdl: total / N || 1 };
+}
+function bm25(terms, ruleText, corpus) {
+  const toks = tokenize(ruleText);
+  const dl = toks.length || 1;
+  const tf = /* @__PURE__ */ new Map();
+  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
+  let score = 0;
+  for (const t of new Set(terms)) {
+    const f = tf.get(t) ?? 0;
+    if (f === 0) continue;
+    const idf = corpus.idf.get(t);
+    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
+  }
+  return score;
+}
+
+// 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)) {
@@ -33682,7 +33959,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
     });
   }
@@ -33707,9 +33984,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)) {
@@ -33761,6 +34091,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 = {}) {
@@ -33788,6 +34146,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 };
@@ -33839,13 +34199,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";
@@ -34107,6 +34467,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 = [];
@@ -34127,6 +34488,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();
@@ -34138,7 +34504,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);
@@ -34578,6 +34950,23 @@ function todayIso() {
 }
 
 // src/lessons/add-errors.ts
+var EmptyRuleError = class extends Error {
+  code = "EMPTY_RULE";
+  constructor() {
+    super("Lesson rule must not be empty \u2014 pass one imperative sentence.");
+    this.name = "EmptyRuleError";
+  }
+};
+var BroadCommandPatternError = class extends Error {
+  constructor(pattern) {
+    super(
+      `Command pattern ${JSON.stringify(pattern)} matches nearly every command, so it would fire on every recall. Key it on the action instead \u2014 a word-bounded program + subcommand (e.g. "\\bgit commit\\b", "\\brm\\b").`
+    );
+    this.pattern = pattern;
+    this.name = "BroadCommandPatternError";
+  }
+  code = "BROAD_COMMAND_PATTERN";
+};
 var UnknownTopicError = class extends Error {
   constructor(topic) {
     super(`Unknown topic: ${topic}. Pass allowNewTopic + topicSummary to create it.`);
@@ -34617,6 +35006,77 @@ var UnrecallableLessonError = class extends Error {
   code = "UNRECALLABLE_LESSON";
 };
 
+// src/lessons/trigger-effectiveness.ts
+function ineffectiveTriggers(graph, triggerIds) {
+  const out2 = [];
+  for (const id of triggerIds) {
+    const trigger = graph.triggers[id];
+    if (trigger === void 0) continue;
+    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
+    if (reason !== null) out2.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
+  }
+  return out2;
+}
+function ineffectiveReason(kind, pattern) {
+  if (kind === "keyword") {
+    if (tokenize(pattern).length === 0) {
+      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
+    }
+    if (keywordNeedleLosesTokens(pattern)) {
+      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
+    }
+    return null;
+  }
+  if (kind === "command_pattern") {
+    let valid = true;
+    try {
+      new RegExp(pattern);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
+    }
+    if (!isSafeRegexPattern(pattern)) {
+      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
+    }
+    return null;
+  }
+  return null;
+}
+function blockingDeadTriggers(graph, triggerIds) {
+  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
+}
+
+// src/lessons/add-gates.ts
+function assertRuleShape(rule) {
+  const trimmed = rule.trim();
+  if (trimmed.length === 0) throw new EmptyRuleError();
+  if (trimmed.length > MAX_RULE_LENGTH) throw new RuleTooLongError(trimmed.length, MAX_RULE_LENGTH);
+  return trimmed;
+}
+function skipsTriggerGates(input, options) {
+  return options.allowNoTrigger === true || input.scope === "always";
+}
+function countInputTriggers(triggers) {
+  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
+}
+function assertTriggerInputs(input, options, existingTriggerCount) {
+  if (!skipsTriggerGates(input, options) && countInputTriggers(input.triggers) === 0 && existingTriggerCount === 0) {
+    throw new NoTriggerError();
+  }
+  if (options.allowNoTrigger !== true) {
+    const broad = (input.triggers.commands ?? []).find(isBroadCommandPattern);
+    if (broad !== void 0) throw new BroadCommandPatternError(broad);
+  }
+}
+function assertRecallable(graph, resultingTriggers) {
+  const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
+  if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
+    throw new UnrecallableLessonError(blockingDead);
+  }
+}
+
 // src/lessons/capture-guardrails.ts
 var WIDE_GLOB_MATCH_COUNT = 40;
 var MAX_RECOMMENDED_TRIGGERS = 8;
@@ -34655,7 +35115,7 @@ function inspectCapturedLesson(graph, lessonId, knownPaths) {
   if (lowSignal.length > 0) {
     warnings.push({
       code: "LOW_SIGNAL_KEYWORD",
-      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
+      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
     });
   }
   const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
@@ -34716,7 +35176,7 @@ function jaccard(a, b) {
 
 // src/utils/filesystem/process-lock.ts
 init_errors();
-var DEFAULT_STALE_MS = 6e4;
+var DEFAULT_STALE_MS = 6 * 60 * 60 * 1e3;
 var DEFAULT_RETRIES = 30;
 var DEFAULT_RETRY_DELAY_MS = 200;
 var YOUNG_LOCK_GRACE_MS = 2e3;
@@ -34801,10 +35261,9 @@ async function inspectLock(lockPath) {
 }
 function isStale(meta, staleMs) {
   if (!meta) return true;
-  const age = Date.now() - meta.started;
-  if (age > staleMs) return true;
-  if (meta.hostname && meta.hostname !== getHostname()) return false;
-  return !isProcessAlive(meta.pid);
+  const sameHost = !meta.hostname || meta.hostname === getHostname();
+  if (sameHost && !isProcessAlive(meta.pid)) return true;
+  return Date.now() - meta.started > staleMs;
 }
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -34881,52 +35340,7 @@ async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
   return mutateLessonsGraphLocked(projectRoot, mutator, options);
 }
 
-// src/lessons/trigger-effectiveness.ts
-function ineffectiveTriggers(graph, triggerIds) {
-  const out2 = [];
-  for (const id of triggerIds) {
-    const trigger = graph.triggers[id];
-    if (trigger === void 0) continue;
-    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
-    if (reason !== null) out2.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
-  }
-  return out2;
-}
-function ineffectiveReason(kind, pattern) {
-  if (kind === "keyword") {
-    if (tokenize(pattern).length === 0) {
-      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
-    }
-    if (keywordNeedleLosesTokens(pattern)) {
-      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
-    }
-    return null;
-  }
-  if (kind === "command_pattern") {
-    let valid = true;
-    try {
-      new RegExp(pattern);
-    } catch {
-      valid = false;
-    }
-    if (!valid) {
-      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
-    }
-    if (!isSafeRegexPattern(pattern)) {
-      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
-    }
-    return null;
-  }
-  return null;
-}
-function blockingDeadTriggers(graph, triggerIds) {
-  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
-}
-
 // src/lessons/add.ts
-function countInputTriggers(triggers) {
-  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
-}
 async function addLesson(projectRoot, input, options = {}) {
   return mutateLessonsGraph(projectRoot, (graph) => addLessonInto(graph, input, options), {
     retries: options.retries
@@ -34934,10 +35348,7 @@ async function addLesson(projectRoot, input, options = {}) {
 }
 function addLessonInto(graph, input, options) {
   const ruleKey2 = normalizeRule2(input.rule);
-  const trimmedRule = input.rule.trim();
-  if (trimmedRule.length > MAX_RULE_LENGTH) {
-    throw new RuleTooLongError(trimmedRule.length, MAX_RULE_LENGTH);
-  }
+  const trimmedRule = assertRuleShape(input.rule);
   const existingId = findExistingLessonByRule(graph, ruleKey2);
   const isNewTopic = graph.topics[input.topic] === void 0;
   if (isNewTopic) {
@@ -34947,29 +35358,23 @@ function addLessonInto(graph, input, options) {
     }
     graph.topics[input.topic] = { summary: options.topicSummary };
   }
-  const skipTriggerGates = options.allowNoTrigger === true || input.scope === "always";
-  if (!skipTriggerGates) {
-    const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
-    if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
-      throw new NoTriggerError();
-    }
-  }
+  const existing = existingId !== null ? graph.lessons[existingId] : void 0;
+  assertTriggerInputs(input, options, existing?.triggers.length ?? 0);
   const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
-  if (!skipTriggerGates) {
-    const resultingTriggers = existingId !== null ? union(graph.lessons[existingId].triggers, triggerIds) : triggerIds;
-    const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
-    if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
-      throw new UnrecallableLessonError(blockingDead);
-    }
+  if (!skipsTriggerGates(input, options)) {
+    assertRecallable(
+      graph,
+      existing === void 0 ? triggerIds : union(existing.triggers, triggerIds)
+    );
   }
   if (existingId !== null) {
-    const existing = graph.lessons[existingId];
+    const existing2 = graph.lessons[existingId];
     graph.lessons[existingId] = {
-      ...existing,
-      topics: union(existing.topics, [input.topic]),
-      triggers: union(existing.triggers, triggerIds),
-      evidence: union(existing.evidence, input.evidence ?? []),
-      ...existing.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
+      ...existing2,
+      topics: union(existing2.topics, [input.topic]),
+      triggers: union(existing2.triggers, triggerIds),
+      evidence: union(existing2.evidence, input.evidence ?? []),
+      ...existing2.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
       // Re-capturing a rule with --scope always promotes it to always-on.
       ...input.scope === "always" ? { scope: "always" } : {}
     };
@@ -35150,14 +35555,16 @@ function deriveHaystackTokens(query) {
   if (query.command !== void 0) parts.push(query.command);
   if (parts.length === 0) return [];
   const out2 = [];
-  for (const raw of parts.join(" ").split(/[^A-Za-z0-9]+/)) {
-    if (raw.length === 0) continue;
+  for (const raw of splitTokens(parts.join(" "))) {
     out2.push(raw.toLowerCase());
     const sub = raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(" ").filter((t) => t.length > 0);
     if (sub.length > 1) out2.push(...sub);
   }
   return out2;
 }
+function splitTokens(text) {
+  return text.split(/[^A-Za-z0-9]+/).filter((t) => t.length > 0);
+}
 function containsRun(needle, hay) {
   if (needle.length === 0) return false;
   for (let i = 0; i + needle.length <= hay.length; i += 1) {
@@ -35173,10 +35580,11 @@ function containsRun(needle, hay) {
   return false;
 }
 function keywordMatches(pattern, query) {
-  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+  const needle = tokenize(pattern);
+  if (query.keyword !== void 0 && containsRun(needle, splitTokens(query.keyword.toLowerCase()))) {
     return true;
   }
-  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
+  return containsRun(needle, deriveHaystackTokens(query));
 }
 
 // src/lessons/query.ts
@@ -35242,6 +35650,15 @@ function buildFanout(graph) {
   }
   return fanout;
 }
+var KEYWORD_NARROWNESS = 0.4;
+function buildNarrowness(graph) {
+  const narrowness = /* @__PURE__ */ new Map();
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind === "file_glob") narrowness.set(id, globNarrowness(trigger.pattern));
+    else narrowness.set(id, trigger.kind === "keyword" ? KEYWORD_NARROWNESS : 1);
+  }
+  return narrowness;
+}
 function buildTopicCoherence(matches) {
   const topicCount = /* @__PURE__ */ new Map();
   for (const { lesson } of matches) {
@@ -35260,7 +35677,7 @@ function buildTopicCoherence(matches) {
 var DEFAULT_RECALL_LIMIT = 10;
 var DEFAULT_RECALL_MAX_TOKENS = 400;
 var RRF_K = 60;
-var SPECIFICITY_WEIGHT = 3;
+var SPECIFICITY_WEIGHT = 5;
 var TOPIC_COHERENCE_WEIGHT = 2;
 var BM25_WEIGHT = 1;
 var EFFECTIVENESS_WEIGHT = 1;
@@ -35287,12 +35704,15 @@ function rankLessons(graph, query, matches, options = {}) {
   const terms = queryTerms(query);
   const corpus = buildCorpus(graph);
   const fanout = buildFanout(graph);
+  const narrowness = buildNarrowness(graph);
   const coherence = buildTopicCoherence(matches);
   const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
   const scored = matches.map(({ id, lesson }) => {
     const hitTriggers = lesson.triggers.filter((t) => matchedTriggerIds.has(t));
     let specificity = 0;
-    for (const t of hitTriggers) specificity = Math.max(specificity, 1 / fanout.get(t));
+    for (const t of hitTriggers) {
+      specificity = Math.max(specificity, (narrowness.get(t) ?? 1) / fanout.get(t));
+    }
     return {
       id,
       lesson,
@@ -35350,7 +35770,8 @@ function defaultLessonsConfig() {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
     autoPrune: false,
-    repairTriggers: false
+    repairTriggers: false,
+    telemetry: false
   };
 }
 function outcomeLogPath(projectRoot) {
@@ -35404,9 +35825,9 @@ var LINE_REFS = String.raw`L\d+(?:\s*,\s*L\d+)*`;
 var LINE_REF_PATTERNS = [
   new RegExp(String.raw`\s*\bSee\s+${LINE_REFS}\.?`, "g"),
   // " See L128." / " See L140, L149"
-  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)\.?`, "g"),
+  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)`, "g"),
   // " (L174)" / " (L92, L163)"
-  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]\.?`, "g")
+  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]`, "g")
   // " [L161, L208]"
 ];
 var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
@@ -35440,42 +35861,7 @@ async function stripMarkersInGraph(projectRoot, options = {}) {
   });
   return { changedIds, changedCount: changedIds.length };
 }
-var RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
-var RECALL_HOOK_TOOL_MATCHER = "Edit|Write|Bash";
-var RECALL_EVENTS = [
-  { event: "PreToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
-  { event: "PostToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
-  { event: "UserPromptSubmit", matcher: "*" },
-  // Capture-on-failure nudge (see capture-nudge.ts). BEST-EFFORT: only Claude
-  // Code's passthrough hooks emit it; whitelist targets drop it without warning
-  // (BEST_EFFORT_HOOK_EVENTS). PostToolUse is success-only, so failures need this.
-  { event: "PostToolUseFailure", matcher: "*" },
-  // Reset recall dedup after a context compaction/clear (see hook.ts SessionStart).
-  // BEST-EFFORT: targets that can't represent SessionStart just keep dedup as-is.
-  { event: "SessionStart", matcher: "*" }
-];
-function injectEvent(doc, event, matcher) {
-  const existing = doc.get(event);
-  const seq = existing instanceof YAMLSeq ? existing : new YAMLSeq();
-  const present = seq.items.some(
-    (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
-  );
-  if (present) return false;
-  seq.add(doc.createNode({ matcher, type: "command", command: RECALL_HOOK_COMMAND }));
-  doc.set(event, seq);
-  return true;
-}
-function injectRecallHook(projectRoot) {
-  const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
-  if (!existsSync(path)) return false;
-  const doc = parseDocument(readFileSync(path, "utf8"));
-  let changed = false;
-  for (const { event, matcher } of RECALL_EVENTS) {
-    if (injectEvent(doc, event, matcher)) changed = true;
-  }
-  if (changed) writeFileSync(path, String(doc), "utf8");
-  return changed;
-}
+init_recall_hook_scaffold();
 
 // src/lessons/merge-driver-setup.ts
 var LESSONS_MERGE_DRIVER = "agentsmesh-lessons";