agentsmesh 0.21.0 → 0.23.0

package/dist/index.js

@@ -1,16 +1,18 @@
 import { z } from 'zod';
-import { stringify, parse } from 'yaml';
-import { join, basename, dirname, relative, win32, posix, sep, extname, resolve } from 'path';
-import { access, readdir, readFile, realpath, stat, rm, mkdir, lstat, unlink, writeFile, rename, chmod, mkdtemp, cp } from 'fs/promises';
-import { constants, existsSync, realpathSync, statSync, readFileSync } from 'fs';
+import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
+import { join, resolve, relative, sep, dirname, basename, win32, posix, extname } from 'path';
+import { mkdir, access, readdir, rm, readFile, realpath, stat, writeFile, lstat, unlink, rename, chmod, 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 } from 'smol-toml';
 import { Buffer } from 'buffer';
-import { homedir, tmpdir } from 'os';
+import { homedir, hostname, tmpdir } from 'os';
 import { createHash } from 'crypto';
 import { execFile } from 'child_process';
 import { fileURLToPath, pathToFileURL, URL } from 'url';
 import { promisify } from 'util';
 import * as tar from 'tar';
+import picomatch from 'picomatch';
 import { createTwoFilesPatch } from 'diff';
 
 var __defProp = Object.defineProperty;
@@ -45,7 +47,7 @@ function validateCapabilityImplementations(descriptor31, capabilities17, ctx, pa
 function validateDescriptor(value) {
   return targetDescriptorSchema.parse(value);
 }
-var capabilityLevelSchema, capabilitiesSchema, generatorsSchema, pathResolversSchema, layoutSchema, globalSupportSchema, legacyGlobalKeys, generatorRequirements, settingsBackedFeatures, conversionDefaultsSchema, metadataSchema, targetDescriptorSchemaBase, targetDescriptorSchema;
+var capabilityLevelSchema, capabilitiesSchema, generatorsSchema, pathResolversSchema, layoutSchema, globalSupportSchema, legacyGlobalKeys, generatorRequirements, settingsBackedFeatures, conversionDefaultsSchema, metadataSchema, nativePickStrategySchema, nativeInstallSchema, targetDescriptorSchemaBase, targetDescriptorSchema;
 var init_target_descriptor_schema = __esm({
   "src/targets/catalog/target-descriptor.schema.ts"() {
     capabilityLevelSchema = z.union([
@@ -119,6 +121,22 @@ var init_target_descriptor_schema = __esm({
       officialUrl: z.string().min(1),
       shortDescription: z.string().min(1)
     }).passthrough();
+    nativePickStrategySchema = z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("basename"), suffix: z.string().min(1) }),
+      z.object({ kind: z.literal("skillDir") }),
+      z.object({ kind: z.literal("firstSegment") })
+    ]);
+    nativeInstallSchema = z.object({
+      pickPaths: z.array(
+        z.object({
+          prefix: z.string().min(1),
+          feature: z.enum(["commands", "rules", "agents", "skills"]),
+          strategy: nativePickStrategySchema
+        })
+      ).optional(),
+      inferPick: z.function().optional(),
+      dialectHints: z.array(z.object({ frontmatterKey: z.string().min(1) })).optional()
+    }).strict();
     targetDescriptorSchemaBase = z.object({
       id: z.string().regex(/^[a-z][a-z0-9-]*$/, "Target id must be lowercase with hyphens"),
       metadata: metadataSchema,
@@ -130,6 +148,7 @@ var init_target_descriptor_schema = __esm({
       globalSupport: globalSupportSchema.optional(),
       buildImportPaths: z.function(),
       detectionPaths: z.array(z.string()),
+      nativeInstall: nativeInstallSchema.optional(),
       excludeFromStarterInit: z.boolean().optional(),
       conversionDefaults: conversionDefaultsSchema.optional(),
       emitScopedSettings: z.function().optional(),
@@ -630,15 +649,19 @@ var init_errors = __esm({
     LockAcquisitionError = class extends AgentsMeshError {
       lockPath;
       holder;
+      /** Human-readable lock name surfaced in the message, e.g. "lessons lock". */
+      label;
       constructor(lockPath, holder, options) {
+        const label = options?.label ?? "lock";
         super(
           "AM_LOCK_ACQUISITION_FAILED",
-          `Could not acquire generate lock at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
+          `Could not acquire ${label} at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
           options
         );
         this.name = "LockAcquisitionError";
         this.lockPath = lockPath;
         this.holder = holder;
+        this.label = label;
       }
     };
     FileSystemError = class extends AgentsMeshError {
@@ -803,6 +826,27 @@ var init_fs_traverse = __esm({
     MAX_SEGMENT_REPETITIONS = 3;
   }
 });
+async function renameWithRetry(from, to, options = {}) {
+  const attempts = options.attempts ?? 5;
+  const delayMs = options.delayMs ?? 50;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await rename(from, to);
+      return;
+    } catch (err) {
+      const code = err.code;
+      const transient = code !== void 0 && TRANSIENT_RENAME_CODES.has(code);
+      if (!transient || attempt >= attempts - 1) throw err;
+      await setTimeout$1(delayMs * 2 ** attempt);
+    }
+  }
+}
+var TRANSIENT_RENAME_CODES;
+var init_rename_retry = __esm({
+  "src/utils/filesystem/rename-retry.ts"() {
+    TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY", "EEXIST"]);
+  }
+});
 async function readFileSafe(path) {
   try {
     const data = await readFile(path, "utf-8");
@@ -889,6 +933,7 @@ var init_fs = __esm({
     init_fs_text_encoding();
     init_fs_traverse();
     init_fs_text_encoding();
+    init_rename_retry();
   }
 });
 function escapeRegExp(value) {
@@ -897,19 +942,24 @@ function escapeRegExp(value) {
 function managedBlockPattern(start, end) {
   return new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, "g");
 }
-function replaceManagedBlock(content, start, end, block) {
-  const pattern = managedBlockPattern(start, end);
-  if (pattern.test(content)) {
-    return content.replace(pattern, block).trim();
-  }
-  const trimmed = content.trim();
-  return trimmed ? `${trimmed}
-
-${block}` : block;
-}
 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() };
+}
+function insertAtBodyTop(content, block) {
+  const { prefix, body } = splitFrontmatterPrefix(content);
+  const placed = body ? `${block}
+
+${body}` : block;
+  return prefix ? `${prefix}
+
+${placed}` : placed;
+}
 function ruleSource(source) {
   const normalized = source.replace(/\\/g, "/");
   const meshIndex = normalized.lastIndexOf(".agentsmesh/");
@@ -997,11 +1047,13 @@ function extractEmbeddedRules(content) {
   });
   return { rootContent: rootContent.trim(), rules };
 }
-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 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"() {
     ROOT_CONTRACT_START = "<!-- agentsmesh:root-generation-contract:start -->";
     ROOT_CONTRACT_END = "<!-- agentsmesh:root-generation-contract:end -->";
+    LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
+    LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
     EMBEDDED_RULES_START = "<!-- agentsmesh:embedded-rules:start -->";
     EMBEDDED_RULES_END = "<!-- agentsmesh:embedded-rules:end -->";
     EMBEDDED_RULE_END = "<!-- agentsmesh:embedded-rule:end -->";
@@ -1011,31 +1063,9 @@ var init_managed_blocks = __esm({
 });
 
 // src/targets/projection/root-instruction-paragraph.ts
-function normalizeWhitespace(value) {
-  return value.replace(/\s+/g, " ").trim();
-}
 function appendAgentsmeshRootInstructionParagraph(content) {
-  const trimmed = content.trim();
-  if (trimmed.includes(ROOT_CONTRACT_START) && trimmed.includes(ROOT_CONTRACT_END)) {
-    return replaceManagedBlock(
-      trimmed,
-      ROOT_CONTRACT_START,
-      ROOT_CONTRACT_END,
-      AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH
-    );
-  }
-  const norm = normalizeWhitespace(trimmed);
-  if (norm.includes(normalizeWhitespace(AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH))) {
-    return trimmed;
-  }
-  for (const legacy of LEGACY_FORMS) {
-    if (norm.includes(normalizeWhitespace(legacy))) {
-      return trimmed.replace(legacy, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH);
-    }
-  }
-  return trimmed ? `${trimmed}
-
-${AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH}` : AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH;
+  const withoutPrior = stripAgentsmeshRootInstructionParagraph(content);
+  return insertAtBodyTop(withoutPrior, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH);
 }
 function stripAgentsmeshRootInstructionParagraph(content) {
   let result = stripManagedBlock(content, ROOT_CONTRACT_START, ROOT_CONTRACT_END);
@@ -1049,7 +1079,7 @@ ${legacy}`, "");
   }
   return result.trim();
 }
-var ROOT_INSTRUCTION_BODY_V1, ROOT_INSTRUCTION_BODY_V2, ROOT_INSTRUCTION_BODY_V3, ROOT_INSTRUCTION_BODY_V4, ROOT_INSTRUCTION_BODY_V5, ROOT_INSTRUCTION_BODY_V6, ROOT_INSTRUCTION_BODY_V7, ROOT_INSTRUCTION_BODY_V8, ROOT_INSTRUCTION_BODY, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, AGENTSMESH_CONTRACT_WITH_V1_BODY, AGENTSMESH_CONTRACT_WITH_V2_BODY, AGENTSMESH_CONTRACT_WITH_V3_BODY, AGENTSMESH_CONTRACT_WITH_V4_BODY, AGENTSMESH_CONTRACT_WITH_V5_BODY, AGENTSMESH_CONTRACT_WITH_V6_BODY, AGENTSMESH_CONTRACT_WITH_V7_BODY, AGENTSMESH_CONTRACT_WITH_V8_BODY, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_FORMS;
+var ROOT_INSTRUCTION_BODY_V1, ROOT_INSTRUCTION_BODY_V2, ROOT_INSTRUCTION_BODY_V3, ROOT_INSTRUCTION_BODY_V4, ROOT_INSTRUCTION_BODY_V5, ROOT_INSTRUCTION_BODY_V6, ROOT_INSTRUCTION_BODY_V7, ROOT_INSTRUCTION_BODY_V8, ROOT_INSTRUCTION_BODY_V9, ROOT_INSTRUCTION_BODY_V10, ROOT_INSTRUCTION_BODY, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION, AGENTSMESH_CONTRACT_WITH_V1_BODY, AGENTSMESH_CONTRACT_WITH_V2_BODY, AGENTSMESH_CONTRACT_WITH_V3_BODY, AGENTSMESH_CONTRACT_WITH_V4_BODY, AGENTSMESH_CONTRACT_WITH_V5_BODY, AGENTSMESH_CONTRACT_WITH_V6_BODY, AGENTSMESH_CONTRACT_WITH_V7_BODY, AGENTSMESH_CONTRACT_WITH_V8_BODY, AGENTSMESH_CONTRACT_WITH_V9_BODY, AGENTSMESH_CONTRACT_WITH_V10_BODY, AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH, LEGACY_FORMS;
 var init_root_instruction_paragraph = __esm({
   "src/targets/projection/root-instruction-paragraph.ts"() {
     init_managed_blocks();
@@ -1061,7 +1091,9 @@ var init_root_instruction_paragraph = __esm({
     ROOT_INSTRUCTION_BODY_V6 = "Create canonical files in `.agentsmesh`: `rules/_root.md` and `rules/*.md` are Markdown rules; `commands/*.md`, `agents/*.md`, and `skills/*/SKILL.md` plus supporting files use Claude-style frontmatter Markdown; `mcp.json` is MCP JSON; `hooks.yaml` and `permissions.yaml` are YAML; `ignore` is gitignore-style text. Then run `agentsmesh generate`.";
     ROOT_INSTRUCTION_BODY_V7 = "`.agentsmesh` is the only folder you edit or add these files in: `rules/_root.md` and `rules/*.md` are Markdown rules; `commands/*.md`, `agents/*.md`, and `skills/*/SKILL.md` plus supporting files use Claude-style frontmatter Markdown; `mcp.json` is MCP JSON; `hooks.yaml` and `permissions.yaml` are YAML; `ignore` is gitignore-style text. Do not edit generated tool files; run `agentsmesh generate`.";
     ROOT_INSTRUCTION_BODY_V8 = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, and `merge` as needed; never edit generated tool files.";
-    ROOT_INSTRUCTION_BODY = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY_V9 = "`agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY_V10 = "**MUST follow when changing any rule, agent, command, skill, hook, MCP server, permission, or ignore pattern.** `agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally), and `.agentsmesh` is the only place to add or edit canonical items: `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed; never edit generated tool files.";
+    ROOT_INSTRUCTION_BODY = "**NEVER edit generated files** (`.claude/`, `.cursor/`, `AGENTS.md`, `.github/copilot-instructions.md`, and similar target outputs) \u2014 `agentsmesh generate` overwrites them. **All changes MUST go through `.agentsmesh` first**: edit `rules/_root.md`, `rules/*.md`, `commands/*.md`, `agents/*.md`, `skills/*/SKILL.md` plus supporting files, `mcp.json`, `hooks.yaml`, `permissions.yaml`, and `ignore`; `agentsmesh.yaml` selects targets/features (`agentsmesh.local.yaml` overrides locally); if missing run `agentsmesh init`, use `agentsmesh import --from <tool>` for native configs, `agentsmesh install <source>` or `install --sync` for reusable packs, then run `agentsmesh generate`. Use `diff`, `lint`, `check`, `watch`, `matrix`, `merge`, and `refresh` as needed.";
     LEGACY_AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = ROOT_INSTRUCTION_BODY_V1;
     LEGACY_AGENTSMESH_ROOT_INSTRUCTION_SECTION = `## Project-Specific Rules
 
@@ -1090,12 +1122,20 @@ ${ROOT_INSTRUCTION_BODY_V7}`;
     AGENTSMESH_CONTRACT_WITH_V8_BODY = `## AgentsMesh Generation Contract
 
 ${ROOT_INSTRUCTION_BODY_V8}`;
+    AGENTSMESH_CONTRACT_WITH_V9_BODY = `## AgentsMesh Generation Contract
+
+${ROOT_INSTRUCTION_BODY_V9}`;
+    AGENTSMESH_CONTRACT_WITH_V10_BODY = `## AgentsMesh Generation Contract
+
+${ROOT_INSTRUCTION_BODY_V10}`;
     AGENTSMESH_ROOT_INSTRUCTION_PARAGRAPH = `${ROOT_CONTRACT_START}
 ## AgentsMesh Generation Contract
 
 ${ROOT_INSTRUCTION_BODY}
 ${ROOT_CONTRACT_END}`;
     LEGACY_FORMS = [
+      AGENTSMESH_CONTRACT_WITH_V10_BODY,
+      AGENTSMESH_CONTRACT_WITH_V9_BODY,
       AGENTSMESH_CONTRACT_WITH_V8_BODY,
       AGENTSMESH_CONTRACT_WITH_V7_BODY,
       AGENTSMESH_CONTRACT_WITH_V6_BODY,
@@ -1999,9 +2039,8 @@ function shouldRewritePathToken(fullContent, start, end, matchText, rewriteBareP
   const before = fullContent[start - 1];
   const after = fullContent[end];
   if (isMarkdownReferenceDefinitionDestination(fullContent, start, candidateEnd)) return true;
-  if (before === "'" && after === "'" || before === '"' && after === '"' || before === "`" && after === "`") {
-    return true;
-  }
+  if (before === "`" && after === "`") return true;
+  if (before === "'" && after === "'" || before === '"' && after === '"') return false;
   if (before === "<" && after === ">") return true;
   if (before === "[" && after === "]") {
     if (!rewriteBarePathTokens && !isRootRelativePathToken(normalizedCandidate) && markdownBracketLabelDuplicatesDestination(fullContent, start, matchText)) {
@@ -3328,12 +3367,12 @@ var init_augment_code = __esm({
 });
 
 // src/targets/claude-code/constants.ts
-var CLAUDE_CODE_TARGET, CLAUDE_ROOT, CLAUDE_LEGACY_ROOT, CLAUDE_RULES_DIR, CLAUDE_COMMANDS_DIR, CLAUDE_AGENTS_DIR, CLAUDE_SKILLS_DIR, CLAUDE_SETTINGS, CLAUDE_HOOKS_JSON, CLAUDE_OUTPUT_STYLES_DIR, CLAUDE_IGNORE, CLAUDE_MCP_JSON, CLAUDE_GLOBAL_MCP_JSON, CLAUDE_CANONICAL_RULES_DIR, CLAUDE_CANONICAL_COMMANDS_DIR, CLAUDE_CANONICAL_AGENTS_DIR, CLAUDE_CANONICAL_SKILLS_DIR, CLAUDE_CANONICAL_MCP, CLAUDE_CANONICAL_PERMISSIONS, CLAUDE_CANONICAL_HOOKS, CLAUDE_CANONICAL_IGNORE;
+var CLAUDE_CODE_TARGET, CLAUDE_ROOT, CLAUDE_NESTED_ROOT, CLAUDE_RULES_DIR, CLAUDE_COMMANDS_DIR, CLAUDE_AGENTS_DIR, CLAUDE_SKILLS_DIR, CLAUDE_SETTINGS, CLAUDE_HOOKS_JSON, CLAUDE_OUTPUT_STYLES_DIR, CLAUDE_IGNORE, CLAUDE_MCP_JSON, CLAUDE_GLOBAL_MCP_JSON, CLAUDE_CANONICAL_RULES_DIR, CLAUDE_CANONICAL_COMMANDS_DIR, CLAUDE_CANONICAL_AGENTS_DIR, CLAUDE_CANONICAL_SKILLS_DIR, CLAUDE_CANONICAL_MCP, CLAUDE_CANONICAL_PERMISSIONS, CLAUDE_CANONICAL_HOOKS, CLAUDE_CANONICAL_IGNORE;
 var init_constants7 = __esm({
   "src/targets/claude-code/constants.ts"() {
     CLAUDE_CODE_TARGET = "claude-code";
-    CLAUDE_ROOT = ".claude/CLAUDE.md";
-    CLAUDE_LEGACY_ROOT = "CLAUDE.md";
+    CLAUDE_ROOT = "CLAUDE.md";
+    CLAUDE_NESTED_ROOT = ".claude/CLAUDE.md";
     CLAUDE_RULES_DIR = ".claude/rules";
     CLAUDE_COMMANDS_DIR = ".claude/commands";
     CLAUDE_AGENTS_DIR = ".claude/agents";
@@ -5195,7 +5234,8 @@ var init_amp2 = __esm({
           markAsRoot: true
         }
       },
-      emitScopedSettings(canonical, _scope) {
+      emitScopedSettings(canonical, _scope, enabledFeatures) {
+        if (!enabledFeatures.has("mcp")) return [];
         if (!canonical.mcp || Object.keys(canonical.mcp.mcpServers).length === 0) return [];
         return [
           {
@@ -5947,12 +5987,12 @@ function mergeAugmentSettings(existing, newContent) {
   if (overlay.hooks !== void 0) base.hooks = overlay.hooks;
   return JSON.stringify(base, null, 2);
 }
-function buildSettingsContent(canonical) {
+function buildSettingsContent(canonical, enabledFeatures) {
   const settings = {};
-  if (canonical.mcp && Object.keys(canonical.mcp.mcpServers).length > 0) {
+  if (enabledFeatures.has("mcp") && canonical.mcp && Object.keys(canonical.mcp.mcpServers).length > 0) {
     settings.mcpServers = canonical.mcp.mcpServers;
   }
-  if (canonical.hooks && Object.keys(canonical.hooks).length > 0) {
+  if (enabledFeatures.has("hooks") && canonical.hooks && Object.keys(canonical.hooks).length > 0) {
     settings.hooks = serializeHooksForSettings(canonical.hooks);
   }
   if (Object.keys(settings).length === 0) return null;
@@ -6081,8 +6121,8 @@ var init_augment_code2 = __esm({
         ],
         layout: globalLayout5
       },
-      emitScopedSettings(canonical) {
-        const content = buildSettingsContent(canonical);
+      emitScopedSettings(canonical, _scope, enabledFeatures) {
+        const content = buildSettingsContent(canonical, enabledFeatures);
         if (content === null) return [];
         return [{ path: AUGMENT_CODE_SETTINGS_FILE, content }];
       },
@@ -6656,7 +6696,10 @@ var init_claude_code2 = __esm({
       skillDir: ".claude/skills",
       managedOutputs: {
         dirs: [".claude/agents", ".claude/commands", ".claude/rules", ".claude/skills"],
-        files: [".claude/CLAUDE.md", ".claude/settings.json", ".claudeignore", ".mcp.json"]
+        // CLAUDE_NESTED_ROOT is the pre-migration project location; listing it here lets
+        // `cleanupStaleGeneratedOutputs` evict a leftover `.claude/CLAUDE.md` once generation
+        // writes the root `CLAUDE.md`, so Claude Code never concatenates both into context.
+        files: [CLAUDE_ROOT, CLAUDE_NESTED_ROOT, ".claude/settings.json", ".claudeignore", ".mcp.json"]
       },
       paths: {
         rulePath(slug, _rule) {
@@ -6671,7 +6714,7 @@ var init_claude_code2 = __esm({
       }
     };
     globalLayout6 = {
-      rootInstructionPath: CLAUDE_ROOT,
+      rootInstructionPath: CLAUDE_NESTED_ROOT,
       skillDir: ".claude/skills",
       renderPrimaryRootInstruction: renderClaudeGlobalPrimaryInstructions,
       managedOutputs: {
@@ -6684,7 +6727,7 @@ var init_claude_code2 = __esm({
           ".agents/skills"
         ],
         files: [
-          ".claude/CLAUDE.md",
+          CLAUDE_NESTED_ROOT,
           ".claude/settings.json",
           CLAUDE_GLOBAL_MCP_JSON,
           CLAUDE_HOOKS_JSON,
@@ -6692,6 +6735,7 @@ var init_claude_code2 = __esm({
         ]
       },
       rewriteGeneratedPath(path) {
+        if (path === CLAUDE_ROOT) return CLAUDE_NESTED_ROOT;
         if (path === CLAUDE_MCP_JSON) return CLAUDE_GLOBAL_MCP_JSON;
         return path;
       },
@@ -6755,10 +6799,11 @@ var init_claude_code2 = __esm({
       importer: {
         rules: [
           {
-            // Root rule: prefer .claude/CLAUDE.md, fall back to legacy CLAUDE.md (project only).
+            // Root rule: project prefers root CLAUDE.md, falls back to nested .claude/CLAUDE.md;
+            // global reads the nested .claude/CLAUDE.md.
             feature: "rules",
             mode: "singleFile",
-            source: { project: [CLAUDE_ROOT, CLAUDE_LEGACY_ROOT], global: [CLAUDE_ROOT] },
+            source: { project: [CLAUDE_ROOT, CLAUDE_NESTED_ROOT], global: [CLAUDE_NESTED_ROOT] },
             canonicalDir: CLAUDE_CANONICAL_RULES_DIR,
             canonicalRootFilename: "_root.md",
             markAsRoot: true
@@ -6804,7 +6849,23 @@ var init_claude_code2 = __esm({
         }
       },
       buildImportPaths: buildClaudeCodeImportPaths,
-      detectionPaths: ["CLAUDE.md", ".claude/rules", ".claude/commands"]
+      detectionPaths: [CLAUDE_ROOT, CLAUDE_NESTED_ROOT, ".claude/rules", ".claude/commands"],
+      nativeInstall: {
+        pickPaths: [
+          {
+            prefix: ".claude/commands",
+            feature: "commands",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".claude/rules", feature: "rules", strategy: { kind: "basename", suffix: ".md" } },
+          {
+            prefix: ".claude/agents",
+            feature: "agents",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".claude/skills/", feature: "skills", strategy: { kind: "firstSegment" } }
+        ]
+      }
     };
   }
 });
@@ -7683,6 +7744,16 @@ var init_cline2 = __esm({
       },
       buildImportPaths: buildClineImportPaths,
       detectionPaths: [".clinerules", ".cline"],
+      nativeInstall: {
+        pickPaths: [
+          { prefix: CLINE_SKILLS_DIR, feature: "skills", strategy: { kind: "skillDir" } },
+          {
+            prefix: CLINE_WORKFLOWS_DIR,
+            feature: "commands",
+            strategy: { kind: "basename", suffix: ".md" }
+          }
+        ]
+      },
       conversionDefaults: { agentsToSkills: true }
     };
   }
@@ -8601,6 +8672,11 @@ var init_codex_cli2 = __esm({
         ".codex/agents",
         ".codex/rules"
       ],
+      nativeInstall: {
+        pickPaths: [
+          { prefix: ".codex", feature: "rules", strategy: { kind: "basename", suffix: ".md" } }
+        ]
+      },
       excludeFromStarterInit: true,
       conversionDefaults: { commandsToSkills: true, agentsToSkills: false }
     };
@@ -9104,6 +9180,21 @@ var init_continue2 = __esm({
       },
       buildImportPaths: buildContinueImportPaths,
       detectionPaths: [".continue/rules", ".continue/skills", ".continue/mcpServers"],
+      nativeInstall: {
+        pickPaths: [
+          {
+            prefix: ".continue/rules",
+            feature: "rules",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          {
+            prefix: ".continue/prompts",
+            feature: "commands",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".continue/skills", feature: "skills", strategy: { kind: "skillDir" } }
+        ]
+      },
       conversionDefaults: { agentsToSkills: true }
     };
   }
@@ -9471,6 +9562,80 @@ var init_importer10 = __esm({
     init_copilot2();
   }
 });
+async function skillNamesFromNativeSkillDir(scanRoot) {
+  const files = await readDirRecursive(scanRoot);
+  const names = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    if (basename(f) === "SKILL.md") {
+      names.add(basename(dirname(f)));
+      continue;
+    }
+    const rel2 = relative(scanRoot, f).replace(/\\/g, "/");
+    if (!rel2.includes("/") && f.toLowerCase().endsWith(".md")) {
+      names.add(basename(f, ".md"));
+    }
+  }
+  return [...names].filter(Boolean).sort();
+}
+var init_native_skill_scan = __esm({
+  "src/install/native/native-skill-scan.ts"() {
+    init_fs();
+  }
+});
+async function inferCopilotPickFromPath(repoRoot, posixPath) {
+  const scan = join(repoRoot, ...posixPath.split("/"));
+  if (posixPath.startsWith(COPILOT_PROMPTS_DIR)) {
+    const files = await readDirRecursive(scan);
+    const commands = [
+      ...new Set(
+        files.filter((f) => f.toLowerCase().endsWith(".prompt.md")).map((f) => basename(f, ".prompt.md"))
+      )
+    ].sort();
+    return commands.length ? { commands } : {};
+  }
+  if (posixPath.startsWith(".github/copilot") && !posixPath.includes("copilot-instructions.md")) {
+    const files = await readDirRecursive(scan);
+    const rules = [
+      ...new Set(
+        files.filter((f) => f.includes(".instructions.md")).map((f) => basename(f).replace(/\.instructions\.md$/i, ""))
+      )
+    ].sort();
+    return rules.length ? { rules } : {};
+  }
+  if (posixPath.startsWith(".github/instructions")) {
+    const files = await readDirRecursive(scan);
+    const names = /* @__PURE__ */ new Set();
+    for (const f of files) {
+      const b = basename(f);
+      if (b.toLowerCase().endsWith(".instructions.md"))
+        names.add(b.replace(/\.instructions\.md$/i, ""));
+      else if (b.toLowerCase().endsWith(".md")) names.add(basename(f, ".md"));
+    }
+    const rules = [...names].sort();
+    return rules.length ? { rules } : {};
+  }
+  if (posixPath.startsWith(".github/skills")) {
+    const skills = await skillNamesFromNativeSkillDir(scan);
+    return skills.length ? { skills } : {};
+  }
+  if (posixPath.startsWith(".github/agents")) {
+    const files = await readDirRecursive(scan);
+    const agents = [
+      ...new Set(
+        files.filter((f) => f.toLowerCase().endsWith(".agent.md")).map((f) => basename(f, ".agent.md"))
+      )
+    ].sort();
+    return agents.length ? { agents } : {};
+  }
+  return {};
+}
+var init_native_path_pick_infer_copilot = __esm({
+  "src/install/native/native-path-pick-infer-copilot.ts"() {
+    init_fs();
+    init_constants29();
+    init_native_skill_scan();
+  }
+});
 function pruneUndefined3(record) {
   for (const key of Object.keys(record)) {
     if (record[key] === void 0) delete record[key];
@@ -9760,6 +9925,7 @@ var init_copilot2 = __esm({
     init_generator11();
     init_constants29();
     init_importer10();
+    init_native_path_pick_infer_copilot();
     init_import_mappers4();
     init_linter10();
     init_import_map_builders();
@@ -9974,7 +10140,8 @@ var init_copilot2 = __esm({
         ".github/skills",
         ".github/agents",
         ".github/hooks"
-      ]
+      ],
+      nativeInstall: { inferPick: inferCopilotPickFromPath }
     };
   }
 });
@@ -11004,8 +11171,8 @@ async function hasGlobalCursorArtifacts(projectRoot) {
     join(projectRoot, CURSOR_COMMANDS_DIR)
   ];
   for (const p of candidates) {
-    const stat8 = await readFileSafe(p);
-    if (stat8 !== null && stat8.trim() !== "") return true;
+    const stat9 = await readFileSafe(p);
+    if (stat9 !== null && stat9.trim() !== "") return true;
   }
   const skillFiles = await readDirRecursive(join(projectRoot, CURSOR_SKILLS_DIR));
   if (skillFiles.some((f) => f.endsWith(".md"))) return true;
@@ -11487,6 +11654,23 @@ var init_cursor2 = __esm({
       },
       buildImportPaths: buildCursorImportPaths,
       detectionPaths: [".cursor/rules", ".cursor/mcp.json"],
+      nativeInstall: {
+        pickPaths: [
+          { prefix: ".cursor/rules", feature: "rules", strategy: { kind: "basename", suffix: ".mdc" } },
+          {
+            prefix: ".cursor/commands",
+            feature: "commands",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          {
+            prefix: ".cursor/agents",
+            feature: "agents",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".cursor/skills", feature: "skills", strategy: { kind: "skillDir" } }
+        ],
+        dialectHints: [{ frontmatterKey: "alwaysApply" }]
+      },
       preservesManualActivation: true
     };
   }
@@ -12248,18 +12432,18 @@ function mapHookEvent2(event) {
       return null;
   }
 }
-function generateGeminiSettingsFiles(canonical) {
+function generateGeminiSettingsFiles(canonical, enabledFeatures) {
   const settings = {};
   let hasAnyNativeSettings = false;
-  if (canonical.mcp && Object.keys(canonical.mcp.mcpServers).length > 0) {
+  if (enabledFeatures.has("mcp") && canonical.mcp && Object.keys(canonical.mcp.mcpServers).length > 0) {
     settings.mcpServers = canonical.mcp.mcpServers;
     hasAnyNativeSettings = true;
   }
-  if (canonical.agents.length > 0) {
+  if (enabledFeatures.has("agents") && canonical.agents.length > 0) {
     settings.experimental = { enableAgents: true };
     hasAnyNativeSettings = true;
   }
-  if (canonical.hooks) {
+  if (enabledFeatures.has("hooks") && canonical.hooks) {
     const hookEntries = Object.entries(canonical.hooks).flatMap(([event, entries]) => {
       const mappedEvent = mapHookEvent2(event);
       if (!mappedEvent || !Array.isArray(entries)) return [];
@@ -12875,6 +13059,36 @@ var init_importer15 = __esm({
     init_importer_skills_agents();
   }
 });
+function isUnderGeminiCommands(pathInRepoPosix) {
+  const p = pathInRepoPosix.replace(/^\/+|\/+$/g, "");
+  return p === ".gemini/commands" || p.startsWith(".gemini/commands/");
+}
+async function inferGeminiCommandNamesFromFiles(repoRoot, pathInRepoPosix) {
+  const commandsRoot = join(repoRoot, ...GEMINI_COMMANDS_DIR.split("/"));
+  const scanDir = join(repoRoot, ...pathInRepoPosix.split("/"));
+  const files = await readDirRecursive(scanDir);
+  const names = [];
+  for (const f of files) {
+    if (!/\.(toml|md)$/i.test(f)) continue;
+    const rel2 = relative(commandsRoot, f).replace(/\\/g, "/");
+    if (rel2.startsWith("..") || rel2 === "") continue;
+    const noExt = rel2.replace(/\.(toml|md)$/i, "");
+    const name = noExt.split("/").filter(Boolean).join(":");
+    if (name) names.push(name);
+  }
+  return [...new Set(names)].sort();
+}
+async function inferGeminiPick(repoRoot, posixPath) {
+  if (!isUnderGeminiCommands(posixPath)) return {};
+  const commands = await inferGeminiCommandNamesFromFiles(repoRoot, posixPath);
+  return commands.length ? { commands } : {};
+}
+var init_gemini_install_commands = __esm({
+  "src/install/native/gemini-install-commands.ts"() {
+    init_fs();
+    init_constants30();
+  }
+});
 async function mapGeminiRuleFile(relativePath, destDir, normalizeTo) {
   const relativeMdPath = relativePath.replace(/\\/g, "/");
   const destPath = join(destDir, relativeMdPath);
@@ -12986,12 +13200,12 @@ var init_lint12 = __esm({
 });
 
 // src/targets/gemini-cli/scoped-settings-emit.ts
-function emitScopedGeminiSettings(canonical, scope) {
+function emitScopedGeminiSettings(canonical, scope, enabledFeatures) {
   if (scope === "project") {
     const caps = getTargetCapabilities("gemini-cli", scope);
     if (caps?.ignore.flavor !== "settings-embedded") return [];
   }
-  return generateGeminiSettingsFiles(canonical);
+  return generateGeminiSettingsFiles(canonical, enabledFeatures);
 }
 var init_scoped_settings_emit = __esm({
   "src/targets/gemini-cli/scoped-settings-emit.ts"() {
@@ -13009,6 +13223,7 @@ var init_gemini_cli2 = __esm({
     init_policies_generator();
     init_constants30();
     init_importer15();
+    init_gemini_install_commands();
     init_import_mappers6();
     init_linter15();
     init_import_map_builders();
@@ -13204,6 +13419,7 @@ var init_gemini_cli2 = __esm({
       },
       buildImportPaths: buildGeminiCliImportPaths,
       detectionPaths: ["GEMINI.md", ".gemini"],
+      nativeInstall: { inferPick: inferGeminiPick },
       conversionDefaults: { agentsToSkills: false }
     };
   }
@@ -14045,7 +14261,23 @@ var init_junie2 = __esm({
         ".junie/skills",
         ".junie/mcp/mcp.json",
         ".aiignore"
-      ]
+      ],
+      nativeInstall: {
+        pickPaths: [
+          {
+            prefix: ".junie/commands",
+            feature: "commands",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".junie/rules", feature: "rules", strategy: { kind: "basename", suffix: ".md" } },
+          {
+            prefix: ".junie/agents",
+            feature: "agents",
+            strategy: { kind: "basename", suffix: ".md" }
+          },
+          { prefix: ".junie/skills", feature: "skills", strategy: { kind: "skillDir" } }
+        ]
+      }
     };
   }
 });
@@ -15900,9 +16132,18 @@ function generateIgnore12(canonical) {
   if (!canonical.ignore || canonical.ignore.length === 0) return [];
   return [{ path: QWEN_IGNORE, content: canonical.ignore.join("\n") }];
 }
+function renderQwenGlobalInstructions(canonical) {
+  const root = canonical.rules.find((rule) => rule.root);
+  const nonRootRules = canonical.rules.filter((rule) => {
+    if (rule.root) return false;
+    return rule.targets.length === 0 || rule.targets.includes(QWEN_CODE_TARGET);
+  });
+  return appendEmbeddedRulesBlock(root?.body.trim() ?? "", nonRootRules);
+}
 var init_generator26 = __esm({
   "src/targets/qwen-code/generator.ts"() {
     init_markdown();
+    init_managed_blocks();
     init_constants21();
   }
 });
@@ -15985,6 +16226,7 @@ var init_qwen_code2 = __esm({
     };
     globalLayout22 = {
       rootInstructionPath: QWEN_GLOBAL_ROOT,
+      renderPrimaryRootInstruction: renderQwenGlobalInstructions,
       skillDir: QWEN_GLOBAL_SKILLS_DIR,
       managedOutputs: {
         dirs: [QWEN_GLOBAL_COMMANDS_DIR, QWEN_GLOBAL_AGENTS_DIR, QWEN_GLOBAL_SKILLS_DIR],
@@ -18385,6 +18627,16 @@ var init_windsurf2 = __esm({
       },
       buildImportPaths: buildWindsurfImportPaths,
       detectionPaths: [".windsurfrules", ".windsurf"],
+      nativeInstall: {
+        pickPaths: [
+          {
+            prefix: ".windsurf/rules",
+            feature: "rules",
+            strategy: { kind: "basename", suffix: ".md" }
+          }
+        ],
+        dialectHints: [{ frontmatterKey: "trigger" }]
+      },
       conversionDefaults: { agentsToSkills: true }
     };
   }
@@ -18659,7 +18911,8 @@ var init_zed2 = __esm({
           markAsRoot: true
         }
       },
-      emitScopedSettings(canonical, _scope) {
+      emitScopedSettings(canonical, _scope, enabledFeatures) {
+        if (!enabledFeatures.has("mcp")) return [];
         if (!canonical.mcp || Object.keys(canonical.mcp.mcpServers).length === 0) return [];
         const contextServers = {};
         for (const [name, server] of Object.entries(canonical.mcp.mcpServers)) {
@@ -18714,7 +18967,10 @@ function getBuiltinTargetDefinition(target31) {
 function getTargetCapabilities(target31, scope = "project") {
   const descriptor31 = getBuiltinTargetDefinition(target31) ?? getDescriptor(target31);
   if (!descriptor31) return void 0;
-  const raw = scope === "global" ? descriptor31.globalSupport?.capabilities ?? descriptor31.capabilities : descriptor31.capabilities;
+  if (scope === "global" && !descriptor31.globalSupport) {
+    return normalizeTargetCapabilities(ALL_NONE_CAPABILITIES);
+  }
+  const raw = scope === "global" ? descriptor31.globalSupport.capabilities : descriptor31.capabilities;
   return normalizeTargetCapabilities(raw);
 }
 function getTargetDetectionPaths(target31, scope = "project") {
@@ -18770,6 +19026,7 @@ function isConversionUpgrading(descriptor31, feature, config, scope) {
 function getEffectiveTargetSupportLevel(target31, feature, config, scope = "project") {
   const baseLevel = getTargetCapabilities(target31, scope)?.[feature]?.level ?? "none";
   const descriptor31 = getBuiltinTargetDefinition(target31) ?? getDescriptor(target31);
+  if (scope === "global" && descriptor31 && !descriptor31.globalSupport) return "none";
   if (baseLevel === "none" && isConversionUpgrading(descriptor31, feature, config, scope)) {
     return "embedded";
   }
@@ -18783,7 +19040,7 @@ function resolveTargetFeatureGenerator(target31, feature, config, scope = "proje
   const pick = PICK_FEATURE_GENERATOR[feature];
   return pick === null ? void 0 : pick(descriptor31.generators);
 }
-var BUILTIN_TARGETS, _builtinTargetsMap, PICK_FEATURE_GENERATOR;
+var ALL_NONE_CAPABILITIES, BUILTIN_TARGETS, _builtinTargetsMap, PICK_FEATURE_GENERATOR;
 var init_builtin_targets = __esm({
   "src/targets/catalog/builtin-targets.ts"() {
     init_conversions();
@@ -18821,6 +19078,17 @@ var init_builtin_targets = __esm({
     init_warp2();
     init_windsurf2();
     init_zed2();
+    ALL_NONE_CAPABILITIES = {
+      rules: "none",
+      additionalRules: "none",
+      commands: "none",
+      agents: "none",
+      skills: "none",
+      mcp: "none",
+      hooks: "none",
+      ignore: "none",
+      permissions: "none"
+    };
     BUILTIN_TARGETS = [
       descriptor,
       descriptor2,
@@ -19251,6 +19519,23 @@ function rewriteGeneratedReferences(results, canonical, config, projectRoot, sco
 init_path_helpers();
 init_link_rebaser_helpers();
 
+// src/utils/output/color.ts
+function noColorRequested() {
+  const value = process.env.NO_COLOR;
+  return value !== void 0 && value !== "";
+}
+function forceColorRequested() {
+  const value = process.env.FORCE_COLOR;
+  if (value === void 0) return void 0;
+  return value !== "0" && value !== "false";
+}
+function colorEnabled(stream = process.stdout) {
+  const forced = forceColorRequested();
+  if (forced !== void 0) return forced;
+  if (noColorRequested()) return false;
+  return stream.isTTY === true;
+}
+
 // src/utils/output/logger.ts
 var C = {
   green: "\x1B[32m",
@@ -19259,16 +19544,14 @@ var C = {
   cyan: "\x1B[36m",
   reset: "\x1B[0m"
 };
-function out(text) {
-  {
-    process.stdout.write(text);
-  }
+function outStream() {
+  return process.stdout;
 }
-function noColor() {
-  return process.env.NO_COLOR !== void 0 && process.env.NO_COLOR !== "";
+function out(text) {
+  outStream().write(text);
 }
-function c(code, text) {
-  return noColor() ? text : `${code}${text}${C.reset}`;
+function c(code, text, stream) {
+  return colorEnabled(stream) ? `${code}${text}${C.reset}` : text;
 }
 function pad(str, width) {
   const len = [...str].length;
@@ -19276,20 +19559,20 @@ function pad(str, width) {
 }
 var logger = {
   info(msg) {
-    out(c(C.cyan, msg) + "\n");
+    out(c(C.cyan, msg, outStream()) + "\n");
   },
   warn(msg) {
-    process.stderr.write(c(C.yellow, "\u26A0 ") + msg + "\n");
+    process.stderr.write(c(C.yellow, "\u26A0 ", process.stderr) + msg + "\n");
   },
   error(msg) {
-    process.stderr.write(c(C.red, "\u2717 ") + msg + "\n");
+    process.stderr.write(c(C.red, "\u2717 ", process.stderr) + msg + "\n");
   },
   success(msg) {
-    out(c(C.green, "\u2713 ") + msg + "\n");
+    out(c(C.green, "\u2713 ", outStream()) + msg + "\n");
   },
   debug(msg) {
     if (process.env.AGENTSMESH_DEBUG === "1") {
-      out(c(C.cyan, "[debug] ") + msg + "\n");
+      out(c(C.cyan, "[debug] ", outStream()) + msg + "\n");
     }
   },
   table(rows) {
@@ -19784,12 +20067,12 @@ async function generateHooksFeature(results, targets, canonical, projectRoot, sc
     }
   }
 }
-async function generateScopedSettingsFeature(results, targets, canonical, projectRoot, scope) {
+async function generateScopedSettingsFeature(results, targets, canonical, projectRoot, scope, enabledFeatures) {
   for (const target31 of targets) {
     const descriptor31 = getBuiltinTargetDefinition(target31) ?? getDescriptor(target31);
     const emit = descriptor31?.emitScopedSettings;
     if (!emit) continue;
-    const outputs = emit(canonical, scope);
+    const outputs = emit(canonical, scope, enabledFeatures);
     if (outputs.length === 0) continue;
     for (const out2 of outputs) {
       await emitGeneratedOutput(results, target31, out2, projectRoot, scope, {
@@ -19890,7 +20173,14 @@ async function generate(ctx) {
     }
   }
   if (hasMcp || hasIgnore || hasHooks || hasAgents || hasPermissions) {
-    await generateScopedSettingsFeature(results, targets, canonical, projectRoot, scope);
+    await generateScopedSettingsFeature(
+      results,
+      targets,
+      canonical,
+      projectRoot,
+      scope,
+      enabledFeatures
+    );
   }
   const decoratedResults = decoratePrimaryRootInstructions(results, canonical, scope);
   const sharedPaths = computeSharedRootInstructionPaths(decoratedResults, scope);
@@ -20214,7 +20504,7 @@ async function fetchGitRemoteExtend(parsed, extendName, options, cacheDir, build
     await cloneRepo(resolveCloneUrl(parsed), stagedRepoDir);
     if (parsed.ref) await checkoutRef(stagedRepoDir, parsed.ref);
     await rm(cacheRoot, { recursive: true, force: true });
-    await rename(stagedRoot, cacheRoot);
+    await renameWithRetry(stagedRoot, cacheRoot);
     return readCachedRepo(cacheRepoDir);
   } catch (err) {
     await rm(stagedRoot, { recursive: true, force: true });
@@ -22565,430 +22855,2694 @@ function lintRuleScopeInversion(input) {
   }
   return out2;
 }
+var CURRENT_GRAPH_VERSION = 1;
+var MAX_RULE_LENGTH = 2e3;
+var IdSchema = z.string().regex(/^[a-z0-9-]+$/, "id must be kebab-case");
+var DateSchema = z.string().regex(
+  /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z?)?$/,
+  "createdAt must be ISO-8601 date or datetime"
+);
+var TopicSchema = z.object({
+  summary: z.string().min(1, "topic summary must not be empty")
+}).strict();
+var TriggerKindSchema = z.enum(["file_glob", "command_pattern", "keyword"]);
+var TriggerSchema = z.object({
+  kind: TriggerKindSchema,
+  pattern: z.string().min(1, "trigger pattern must not be empty")
+}).strict();
+var LessonStatusSchema = z.enum(["active", "deprecated", "superseded"]);
+var LessonSchema = z.object({
+  rule: z.string().min(1, "lesson rule must not be empty"),
+  rationale: z.string().min(1).optional(),
+  topics: z.array(IdSchema).min(1, "lesson must reference at least one topic"),
+  triggers: z.array(IdSchema),
+  evidence: z.array(z.string().min(1)),
+  status: LessonStatusSchema,
+  supersededBy: IdSchema.optional(),
+  createdAt: DateSchema
+}).strict();
+var LessonsGraphSchema = z.object({
+  version: z.literal(CURRENT_GRAPH_VERSION),
+  lessons: z.record(IdSchema, LessonSchema),
+  topics: z.record(IdSchema, TopicSchema),
+  triggers: z.record(IdSchema, TriggerSchema)
+}).strict();
+function parseGraph(raw) {
+  return LessonsGraphSchema.parse(raw);
+}
 
-// src/core/lint/linter.ts
-var EXCLUDE_DIRS = ["node_modules", ".git", "dist", "coverage", ".agentsmesh"];
-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));
+// src/lessons/graph-store.ts
+var GRAPH_REL_PATH = ".agentsmesh/lessons/lessons.json";
+function graphFilePath(projectRoot) {
+  return resolve(projectRoot, GRAPH_REL_PATH);
 }
-async function runLint(config, canonical, projectRoot, targetFilter, options = {}) {
-  const scope = options.scope ?? "project";
-  const allTargets = [...config.targets, ...config.pluginTargets ?? []];
-  const targets = targetFilter ? allTargets.filter((t) => targetFilter.includes(t)) : allTargets;
-  const hasRules = config.features.includes("rules");
-  const hasCommands = config.features.includes("commands");
-  const hasMcp = config.features.includes("mcp");
-  const hasPermissions = config.features.includes("permissions");
-  const hasHooks = config.features.includes("hooks");
-  const diagnostics = [];
-  const projectFiles = scope === "global" ? [] : await getProjectFiles(projectRoot);
-  for (const target31 of targets) {
-    const fullDesc = getDescriptor(target31);
-    const descriptor31 = isBuiltinTargetId(target31) ? getTargetCatalogEntry(target31) : fullDesc;
-    if (descriptor31?.capabilities) {
-      diagnostics.push(
-        ...lintSilentFeatureDrops({
-          target: target31,
-          capabilities: descriptor31.capabilities,
-          canonical,
-          enabledFeatures: config.features
-        })
-      );
-    }
-    if (hasHooks) {
-      diagnostics.push(
-        ...lintHookScriptReferences({
-          target: target31,
-          canonical,
-          hasScriptProjection: fullDesc?.postProcessHookOutputs !== void 0
-        })
-      );
+function loadLessonsGraph(projectRoot) {
+  const raw = readFileSync(graphFilePath(projectRoot), "utf8");
+  return parseGraph(JSON.parse(raw));
+}
+function tryLoadLessonsGraph(projectRoot) {
+  if (!existsSync(graphFilePath(projectRoot))) return null;
+  return loadLessonsGraph(projectRoot);
+}
+function saveLessonsGraph(projectRoot, graph) {
+  const path = graphFilePath(projectRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, serializeGraph(graph), "utf8");
+  renameSync(tmp, path);
+}
+function serializeGraph(graph) {
+  return `${JSON.stringify(canonicalize2(graph), null, 2)}
+`;
+}
+function canonicalize2(value) {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map(canonicalize2);
+  if (typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a < b ? -1 : 1
+    );
+    const out2 = {};
+    for (const [k, v] of entries) out2[k] = canonicalize2(v);
+    return out2;
+  }
+  return value;
+}
+var BASE_REL = ".agentsmesh/lessons";
+function lessonsPaths(projectRoot) {
+  const base = join(projectRoot, BASE_REL);
+  return {
+    base,
+    graph: join(base, "lessons.json"),
+    config: join(base, "config.json"),
+    journal: join(base, "journal.md"),
+    index: join(base, "index.yaml"),
+    topicsDir: join(base, "topics")
+  };
+}
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
+}
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
+
+**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): \`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.
+
+**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): \`agentsmesh lessons add "<rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+No shell? Use the \`lessons_query\` / \`lessons_add\` MCP tools. Skip either and the system does not exist.`;
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
+var MAX_FILES = 2e5;
+function listProjectFiles(projectRoot) {
+  const out2 = /* @__PURE__ */ new Set();
+  try {
+    const stack = [projectRoot];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRS.has(entry.name)) stack.push(join(dir, entry.name));
+        } else if (entry.isFile()) {
+          out2.add(toRelPath(projectRoot, join(dir, entry.name)));
+          if (out2.size > MAX_FILES) return out2;
+        }
+      }
     }
-    if (hasRules) {
-      diagnostics.push(
-        ...lintRuleScopeInversion({
-          target: target31,
-          canonical,
-          preservesManualActivation: fullDesc?.preservesManualActivation === true
-        })
-      );
+  } catch {
+    return null;
+  }
+  return out2;
+}
+
+// src/lessons/validate-checks.ts
+function collectDanglingRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of lesson.topics) {
+      if (graph.topics[topicId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TOPIC",
+          message: `Lesson "${lessonId}" references unknown topic "${topicId}".`,
+          lessonId,
+          topicId
+        });
+      }
     }
-    if (hasRules && descriptor31?.lintRules) {
-      diagnostics.push(...descriptor31.lintRules(canonical, projectRoot, projectFiles, { scope }));
+    for (const triggerId of lesson.triggers) {
+      if (graph.triggers[triggerId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TRIGGER",
+          message: `Lesson "${lessonId}" references unknown trigger "${triggerId}".`,
+          lessonId,
+          triggerId
+        });
+      }
     }
-    if (fullDesc?.generators.lint) {
-      diagnostics.push(...fullDesc.generators.lint(canonical));
+    if (lesson.supersededBy !== void 0 && graph.lessons[lesson.supersededBy] === void 0) {
+      findings.push({
+        level: "error",
+        code: "DANGLING_SUPERSEDER",
+        message: `Lesson "${lessonId}" supersededBy unknown lesson "${lesson.supersededBy}".`,
+        lessonId
+      });
     }
-    const lintOpts = { scope };
-    if (hasCommands && descriptor31?.lint?.commands) {
-      diagnostics.push(...descriptor31.lint.commands(canonical, lintOpts));
+  }
+}
+function collectDuplicateRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of firstDuplicates(lesson.topics)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TOPIC_REF",
+        message: `Lesson "${lessonId}" references topic "${topicId}" more than once.`,
+        lessonId,
+        topicId
+      });
     }
-    if (hasMcp && descriptor31?.lint?.mcp) {
-      diagnostics.push(...descriptor31.lint.mcp(canonical, lintOpts));
+    for (const triggerId of firstDuplicates(lesson.triggers)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TRIGGER_REF",
+        message: `Lesson "${lessonId}" references trigger "${triggerId}" more than once.`,
+        lessonId,
+        triggerId
+      });
     }
-    if (hasPermissions && descriptor31?.lint?.permissions) {
-      diagnostics.push(...descriptor31.lint.permissions(canonical, lintOpts));
+  }
+}
+function firstDuplicates(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const dup = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) dup.add(id);
+    else seen.add(id);
+  }
+  return [...dup];
+}
+function collectStatusInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "superseded" && lesson.supersededBy === void 0) {
+      findings.push({
+        level: "error",
+        code: "SUPERSEDED_WITHOUT_TARGET",
+        message: `Lesson "${lessonId}" has status "superseded" but no supersededBy target.`,
+        lessonId
+      });
     }
-    if (hasHooks && descriptor31?.lint?.hooks) {
-      diagnostics.push(...descriptor31.lint.hooks(canonical, lintOpts));
+    if (lesson.status === "active" && lesson.supersededBy !== void 0) {
+      findings.push({
+        level: "error",
+        code: "ACTIVE_WITH_SUPERSEDER",
+        message: `Lesson "${lessonId}" has status "active" but declares supersededBy.`,
+        lessonId
+      });
     }
   }
-  const hasErrors = diagnostics.some((d) => d.level === "error");
-  return { diagnostics, hasErrors };
 }
-function computeDiff(results) {
-  const diffs = [];
-  const summary = { new: 0, updated: 0, unchanged: 0, deleted: 0 };
-  for (const r of results) {
-    if (r.status === "unchanged") {
-      summary.unchanged++;
+function collectLifecycleInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.supersededBy === void 0) continue;
+    if (lesson.supersededBy === lessonId) {
+      findings.push({
+        level: "error",
+        code: "SELF_SUPERSEDED",
+        message: `Lesson "${lessonId}" is superseded by itself.`,
+        lessonId
+      });
       continue;
     }
-    if (r.status === "created") {
-      summary.new++;
-      const patch = createTwoFilesPatch(
-        `${r.path} (current)`,
-        `${r.path} (generated)`,
-        "",
-        r.content,
-        void 0,
-        void 0,
-        { context: 3 }
+    const target31 = graph.lessons[lesson.supersededBy];
+    if (target31 !== void 0 && target31.status !== "active") {
+      findings.push({
+        level: "error",
+        code: "INACTIVE_SUPERSEDER",
+        message: `Lesson "${lessonId}" is superseded by "${lesson.supersededBy}", which is itself ${target31.status} \u2014 the chain dead-ends with no live replacement.`,
+        lessonId
+      });
+    }
+  }
+  collectSupersedeCycles(graph, findings);
+}
+function collectSupersedeCycles(graph, findings) {
+  const reported = /* @__PURE__ */ new Set();
+  for (const startId of Object.keys(graph.lessons)) {
+    const seen = /* @__PURE__ */ new Set();
+    let cur = startId;
+    while (cur !== void 0) {
+      if (seen.has(cur)) {
+        if (cur !== startId || reported.has(cur)) break;
+        reported.add(cur);
+        findings.push({
+          level: "error",
+          code: "SUPERSEDE_CYCLE",
+          message: `Lesson "${startId}" is part of a supersededBy cycle.`,
+          lessonId: startId
+        });
+        break;
+      }
+      seen.add(cur);
+      const next = graph.lessons[cur]?.supersededBy;
+      if (next === cur) break;
+      cur = next;
+    }
+  }
+}
+function collectReachability(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "active" && lesson.triggers.length === 0) {
+      findings.push({
+        level: "warning",
+        code: "UNREACHABLE_LESSON",
+        message: `Active lesson "${lessonId}" has no triggers and can never be recalled.`,
+        lessonId
+      });
+    }
+  }
+}
+function collectOrphans(graph, findings) {
+  const referencedTopics = /* @__PURE__ */ new Set();
+  const referencedTriggers = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    for (const t of lesson.topics) referencedTopics.add(t);
+    for (const t of lesson.triggers) referencedTriggers.add(t);
+  }
+  for (const topicId of Object.keys(graph.topics)) {
+    if (!referencedTopics.has(topicId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TOPIC",
+        message: `Topic "${topicId}" is not referenced by any lesson.`,
+        topicId
+      });
+    }
+  }
+  for (const triggerId of Object.keys(graph.triggers)) {
+    if (!referencedTriggers.has(triggerId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TRIGGER",
+        message: `Trigger "${triggerId}" is not referenced by any lesson.`,
+        triggerId
+      });
+    }
+  }
+}
+
+// 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 {
+  states = [];
+  alloc() {
+    if (this.states.length >= MAX_NFA_STATES) {
+      throw new Error(`NFA state limit exceeded (${MAX_NFA_STATES}); pattern expands too large`);
+    }
+    this.states.push({ eps: [], asserts: [], chars: [] });
+    return this.states.length - 1;
+  }
+};
+function isNonLineTerminator(c2) {
+  return c2 !== "\n" && c2 !== "\r" && c2 !== "\u2028" && c2 !== "\u2029";
+}
+function compileNode(b, node) {
+  switch (node.k) {
+    case "empty":
+    case "assert": {
+      const s = b.alloc();
+      const e = b.alloc();
+      if (node.k === "assert") b.states[s].asserts.push({ kind: node.kind, target: e });
+      else b.states[s].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "char":
+    case "any":
+    case "class": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const test = node.k === "char" ? (c2) => c2 === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
+      b.states[s].chars.push({ test, target: e });
+      return { start: s, end: e };
+    }
+    case "concat": {
+      if (node.items.length === 0) return compileNode(b, { k: "empty" });
+      let first = null;
+      let prevEnd = -1;
+      for (const item of node.items) {
+        const frag = compileNode(b, item);
+        if (first === null) first = frag;
+        else b.states[prevEnd].eps.push(frag.start);
+        prevEnd = frag.end;
+      }
+      return { start: first.start, end: prevEnd };
+    }
+    case "alt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      for (const opt of node.opts) {
+        const frag = compileNode(b, opt);
+        b.states[s].eps.push(frag.start);
+        b.states[frag.end].eps.push(e);
+      }
+      return { start: s, end: e };
+    }
+    case "opt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "star": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: s, end: e };
+    }
+    case "plus": {
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: frag.start, end: e };
+    }
+  }
+}
+function compileNfa(ast) {
+  const b = new Builder();
+  const { start, end } = compileNode(b, ast);
+  return { states: b.states, start, accept: end };
+}
+
+// src/lessons/regex-linear/nfa.ts
+function wordBoundary(input, pos) {
+  const before = pos > 0 && /[A-Za-z0-9_]/.test(input[pos - 1]);
+  const after = pos < input.length && /[A-Za-z0-9_]/.test(input[pos]);
+  return before !== after;
+}
+function assertHolds(kind, input, pos) {
+  switch (kind) {
+    case "start":
+      return pos === 0;
+    case "end":
+      return pos === input.length;
+    case "wordB":
+      return wordBoundary(input, pos);
+    case "nonWordB":
+      return !wordBoundary(input, pos);
+  }
+}
+function buildMatcher(ast) {
+  const { states, start, accept } = compileNfa(ast);
+  const closure = (set, idx, input, pos, budget) => {
+    const stack = [idx];
+    while (stack.length > 0) {
+      if (budget.remaining <= 0) return;
+      const cur = stack.pop();
+      if (set.has(cur)) continue;
+      set.add(cur);
+      budget.remaining -= 1;
+      for (const t of states[cur].eps) if (!set.has(t)) stack.push(t);
+      for (const a of states[cur].asserts) {
+        if (assertHolds(a.kind, input, pos) && !set.has(a.target)) stack.push(a.target);
+      }
+    }
+  };
+  return {
+    // The input is matched in full (no truncation — truncation would miss suffix
+    // matches and let `$` falsely match an invented endpoint). Work is bounded by
+    // the shared budget instead: when it runs out we report a safe non-match.
+    test(input, budget) {
+      const b = budget ?? { remaining: Number.POSITIVE_INFINITY };
+      if (b.remaining <= 0) return false;
+      let current = /* @__PURE__ */ new Set();
+      for (let pos = 0; pos <= input.length; pos += 1) {
+        closure(current, start, input, pos, b);
+        if (current.has(accept)) return true;
+        if (b.remaining <= 0) return false;
+        if (pos === input.length) break;
+        const ch = input[pos];
+        const next = /* @__PURE__ */ new Set();
+        for (const s of current) {
+          b.remaining -= 1;
+          for (const t of states[s].chars) {
+            if (t.test(ch)) closure(next, t.target, input, pos + 1, b);
+          }
+        }
+        current = next;
+      }
+      return current.has(accept);
+    }
+  };
+}
+
+// src/lessons/regex-linear/ast.ts
+var UnsupportedRegexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedRegexError";
+  }
+};
+
+// src/lessons/regex-linear/parse-helpers.ts
+var MAX_REPEAT = 1e3;
+var isWord = (c2) => /[A-Za-z0-9_]/.test(c2);
+function expandRepeat(atom, min, max) {
+  const items = [];
+  for (let k = 0; k < min; k += 1) items.push(atom);
+  if (max === Infinity) {
+    items.push({ k: "star", node: atom });
+  } else {
+    for (let k = min; k < max; k += 1) items.push({ k: "opt", node: atom });
+  }
+  if (items.length === 0) return { k: "empty" };
+  return items.length === 1 ? items[0] : { k: "concat", items };
+}
+function escapeClass(c2) {
+  switch (c2) {
+    case "d":
+      return (x) => x >= "0" && x <= "9";
+    case "D":
+      return (x) => !(x >= "0" && x <= "9");
+    case "w":
+      return isWord;
+    case "W":
+      return (x) => !isWord(x);
+    case "s":
+      return (x) => /\s/.test(x);
+    case "S":
+      return (x) => !/\s/.test(x);
+    default:
+      return null;
+  }
+}
+var HEX2 = /^[0-9a-fA-F]{2}$/;
+var HEX4 = /^[0-9a-fA-F]{4}$/;
+function readUnicodeEscape(src, i, c2) {
+  if (c2 === "x") {
+    const hex2 = src.slice(i, i + 2);
+    return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
+  }
+  const hex = src.slice(i, i + 4);
+  return HEX4.test(hex) ? { ch: String.fromCharCode(parseInt(hex, 16)), len: 4 } : { ch: "u", len: 0 };
+}
+function readControlEscape(src, i) {
+  const x = src[i];
+  if (x === void 0 || !/[A-Za-z]/.test(x)) {
+    throw new UnsupportedRegexError("\\c must be followed by a letter");
+  }
+  return { ch: String.fromCharCode(x.charCodeAt(0) & 31), len: 1 };
+}
+function classEscapeChar(src, i, e) {
+  if (e === "b") return { ch: "\b", len: 0 };
+  if (e === "c") return readControlEscape(src, i);
+  if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
+  return { ch: escapeLiteral(e), len: 0 };
+}
+function escapeLiteral(c2) {
+  switch (c2) {
+    case "t":
+      return "	";
+    case "n":
+      return "\n";
+    case "r":
+      return "\r";
+    case "f":
+      return "\f";
+    case "v":
+      return "\v";
+    case "0":
+      return "\0";
+    default:
+      return c2;
+  }
+}
+
+// src/lessons/regex-linear/parse.ts
+function parseRegex(src) {
+  let i = 0;
+  const peek = () => src[i];
+  const eat = () => src[i++];
+  function parseAlt() {
+    const opts = [parseConcat()];
+    while (peek() === "|") {
+      i += 1;
+      opts.push(parseConcat());
+    }
+    return opts.length === 1 ? opts[0] : { k: "alt", opts };
+  }
+  function parseConcat() {
+    const items = [];
+    while (i < src.length && peek() !== "|" && peek() !== ")") {
+      items.push(parseQuantified());
+    }
+    if (items.length === 0) return { k: "empty" };
+    return items.length === 1 ? items[0] : { k: "concat", items };
+  }
+  function parseQuantified() {
+    const atom = parseAtom();
+    const q = peek();
+    if (q === "*" || q === "+" || q === "?") {
+      i += 1;
+      if (peek() === "?") i += 1;
+      return q === "*" ? { k: "star", node: atom } : q === "+" ? { k: "plus", node: atom } : { k: "opt", node: atom };
+    }
+    if (q === "{") {
+      const repeat = tryParseBrace();
+      if (repeat !== null) return expandRepeat(atom, repeat.min, repeat.max);
+    }
+    return atom;
+  }
+  function tryParseBrace() {
+    const m = /^\{(\d+)(,(\d*)?)?\}/.exec(src.slice(i));
+    if (m === null) return null;
+    i += m[0].length;
+    if (peek() === "?") i += 1;
+    const min = Number(m[1]);
+    const max = m[2] === void 0 ? min : m[3] === "" || m[3] === void 0 ? Infinity : Number(m[3]);
+    if (min > MAX_REPEAT || max !== Infinity && max > MAX_REPEAT) {
+      throw new UnsupportedRegexError(`Repeat count over ${MAX_REPEAT} not supported: {${m[1]}\u2026}`);
+    }
+    return { min, max };
+  }
+  function parseAtom() {
+    const c2 = peek();
+    if (c2 === "(") return parseGroup();
+    if (c2 === "[") return parseClass();
+    if (c2 === "\\") return parseEscape();
+    if (c2 === ".") {
+      i += 1;
+      return { k: "any" };
+    }
+    if (c2 === "^") {
+      i += 1;
+      return { k: "assert", kind: "start" };
+    }
+    if (c2 === "$") {
+      i += 1;
+      return { k: "assert", kind: "end" };
+    }
+    if (c2 === void 0 || c2 === "*" || c2 === "+" || c2 === "?" || c2 === ")") {
+      throw new UnsupportedRegexError(`Unexpected '${c2 ?? "<end>"}' in pattern`);
+    }
+    i += 1;
+    return { k: "char", ch: c2 };
+  }
+  function parseGroup() {
+    i += 1;
+    if (peek() === "?") {
+      const c2 = src[i + 1];
+      if (c2 === "=" || c2 === "!" || c2 === "<") {
+        if (!(c2 === "<" && /[A-Za-z]/.test(src[i + 2] ?? ""))) {
+          throw new UnsupportedRegexError("Lookaround assertions are not supported");
+        }
+      }
+      if (c2 === ":") i += 2;
+      else if (c2 === "<") {
+        i += 2;
+        while (i < src.length && src[i] !== ">") i += 1;
+        i += 1;
+      }
+    }
+    const inner = parseAlt();
+    if (peek() !== ")") throw new UnsupportedRegexError("Unbalanced group");
+    i += 1;
+    return inner;
+  }
+  function parseEscape() {
+    i += 1;
+    const c2 = peek();
+    if (c2 === void 0) throw new UnsupportedRegexError("Trailing backslash");
+    if (/[1-9]/.test(c2) || c2 === "k")
+      throw new UnsupportedRegexError("Backreferences are not supported");
+    i += 1;
+    if (c2 === "b") return { k: "assert", kind: "wordB" };
+    if (c2 === "B") return { k: "assert", kind: "nonWordB" };
+    const cls = escapeClass(c2);
+    if (cls !== null) return { k: "class", test: cls };
+    if (c2 === "x" || c2 === "u" || c2 === "c") {
+      const { ch, len } = c2 === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c2);
+      i += len;
+      return { k: "char", ch };
+    }
+    return { k: "char", ch: escapeLiteral(c2) };
+  }
+  function parseClass() {
+    i += 1;
+    const negate = peek() === "^";
+    if (negate) i += 1;
+    const tests = [];
+    while (i < src.length && peek() !== "]") {
+      tests.push(parseClassMember());
+    }
+    if (peek() !== "]") throw new UnsupportedRegexError("Unterminated character class");
+    i += 1;
+    const base = (c2) => tests.some((t) => t(c2));
+    return { k: "class", test: negate ? (c2) => !base(c2) : base };
+  }
+  function parseClassMember() {
+    let lo;
+    if (peek() === "\\") {
+      i += 1;
+      const e = eat();
+      const cls = escapeClass(e);
+      if (cls !== null) return cls;
+      const r = classEscapeChar(src, i, e);
+      i += r.len;
+      lo = r.ch;
+    } else {
+      lo = eat();
+    }
+    if (peek() === "-" && src[i + 1] !== void 0 && src[i + 1] !== "]") {
+      i += 1;
+      let hi;
+      if (peek() === "\\") {
+        i += 1;
+        const e2 = eat();
+        const r = classEscapeChar(src, i, e2);
+        i += r.len;
+        hi = r.ch;
+      } else {
+        hi = eat();
+      }
+      const a = lo.codePointAt(0);
+      const b = hi.codePointAt(0);
+      return (c2) => {
+        const p = c2.codePointAt(0);
+        return p >= a && p <= b;
+      };
+    }
+    return (c2) => c2 === lo;
+  }
+  const ast = parseAlt();
+  if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
+  return ast;
+}
+
+// src/lessons/regex-linear/index.ts
+var cache = /* @__PURE__ */ new Map();
+function compileLinearMatcher(pattern) {
+  const hit = cache.get(pattern);
+  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
+  let matcher;
+  try {
+    matcher = buildMatcher(parseRegex(pattern));
+  } catch {
+    matcher = null;
+  }
+  cache.set(pattern, matcher);
+  return matcher;
+}
+
+// src/lessons/regex-safety.ts
+var MAX_PATTERN_LENGTH = 1e3;
+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) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    const key = normalizeRule(lesson.rule);
+    const bucket = byKey.get(key) ?? [];
+    bucket.push(lessonId);
+    byKey.set(key, bucket);
+  }
+  for (const [key, ids] of byKey) {
+    if (ids.length < 2) continue;
+    const sorted = [...ids].sort();
+    for (const lessonId of sorted) {
+      const others = sorted.filter((other) => other !== lessonId);
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_RULE",
+        message: `Lesson "${lessonId}" duplicates rule text of: ${others.join(", ")} (normalized key: "${key.slice(0, 60)}").`,
+        lessonId
+      });
+    }
+  }
+}
+function collectInvalidTriggerPatterns(graph, findings) {
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    try {
+      new RegExp(trigger.pattern);
+    } catch (err) {
+      findings.push({
+        level: "error",
+        code: "INVALID_TRIGGER_PATTERN",
+        message: `Trigger "${triggerId}" has an invalid command_pattern regex (${trigger.pattern}): ${err instanceof Error ? err.message : String(err)}.`,
+        triggerId
+      });
+      continue;
+    }
+    if (!isSafeRegexPattern(trigger.pattern)) {
+      findings.push({
+        level: "error",
+        code: "UNSAFE_TRIGGER_PATTERN",
+        message: `Trigger "${triggerId}" has a command_pattern regex outside the provably-linear subset (${trigger.pattern}): it can backtrack catastrophically (e.g. a quantified group like (a+)+ or (a|aa)+, adjacent repetition like a+a+, or a backreference/lookaround). Rewrite using a linear pattern.`,
+        triggerId
+      });
+    }
+  }
+}
+function collectBackslashGlobPatterns(graph, findings) {
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!trigger.pattern.includes("\\")) continue;
+    findings.push({
+      level: "error",
+      code: "BACKSLASH_GLOB_PATTERN",
+      message: `Trigger "${triggerId}" has a file_glob pattern with a backslash (${trigger.pattern}); recall normalizes paths to forward slashes, so it never fires. Replace \\ with /.`,
+      triggerId
+    });
+  }
+}
+function collectDuplicateTriggers(graph, findings) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    const key = `${trigger.kind}|${trigger.pattern}`;
+    const bucket = byKey.get(key) ?? [];
+    bucket.push(triggerId);
+    byKey.set(key, bucket);
+  }
+  for (const [key, ids] of byKey) {
+    if (ids.length < 2) continue;
+    const sorted = [...ids].sort();
+    for (const triggerId of sorted) {
+      const others = sorted.filter((other) => other !== triggerId);
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TRIGGER",
+        message: `Trigger "${triggerId}" duplicates (kind, pattern) of: ${others.join(", ")} (key: "${key}").`,
+        triggerId
+      });
+    }
+  }
+}
+var HIGH_FANOUT_THRESHOLD = 10;
+function collectFanout(graph, findings) {
+  const fanout = /* @__PURE__ */ new Map();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) fanout.set(t, (fanout.get(t) ?? 0) + 1);
+  }
+  let over = 0;
+  let max = 0;
+  for (const n of fanout.values()) {
+    if (n > HIGH_FANOUT_THRESHOLD) over += 1;
+    if (n > max) max = n;
+  }
+  if (over > 0) {
+    findings.push({
+      level: "warning",
+      code: "HIGH_FANOUT_TRIGGERS",
+      message: `${over} trigger(s) each match more than ${HIGH_FANOUT_THRESHOLD} active lessons (max ${max}); recall returns the ranked top by default \u2014 consider per-lesson trigger refinement to improve precision.`
+    });
+  }
+}
+function collectLowSignalKeywords(graph, findings) {
+  const activeTriggerIds2 = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) activeTriggerIds2.add(t);
+  }
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "keyword") continue;
+    if (!activeTriggerIds2.has(triggerId)) continue;
+    if (!isLowSignalKeyword(trigger.pattern)) continue;
+    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.`,
+      triggerId
+    });
+  }
+}
+function collectStopwordKeywords(graph, findings) {
+  const activeTriggerIds2 = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) activeTriggerIds2.add(t);
+  }
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "keyword") continue;
+    if (!activeTriggerIds2.has(triggerId)) continue;
+    if (tokenize(trigger.pattern).length !== 0 && !keywordNeedleLosesTokens(trigger.pattern)) {
+      continue;
+    }
+    findings.push({
+      level: "warning",
+      code: "STOPWORD_KEYWORD",
+      message: `Keyword trigger "${triggerId}" (${trigger.pattern}) loses tokens to stopword filtering, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art"), or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+function normalizeRule(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function activeTriggerIds(graph) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) ids.add(t);
+  }
+  return ids;
+}
+function deadFileGlobIds(graph, knownPaths) {
+  const active = activeTriggerIds(graph);
+  const paths = [...knownPaths];
+  const dead = /* @__PURE__ */ new Set();
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    const isMatch = picomatch(trigger.pattern, { dot: true });
+    if (!paths.some((p) => isMatch(p))) dead.add(triggerId);
+  }
+  return dead;
+}
+function collectDeadFileGlobs(graph, findings, knownPaths) {
+  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
+    findings.push({
+      level: "warning",
+      code: "DEAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file in the working tree \u2014 the lesson is unreachable via this trigger (a rename likely moved the path). Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
+      triggerId
+    });
+  }
+}
+var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
+function collectRunnerAnchoredPatterns(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 (!RUNNER_ANCHOR.test(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "RUNNER_ANCHORED_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) is anchored to one runner \u2014 it won't fire for the same task via another runner (e.g. \`npx\` vs \`pnpm\`). Drop the \`^<runner>\` anchor and key on the task (e.g. \`\\bvitest\\b\`).`,
+      triggerId
+    });
+  }
+}
+
+// src/lessons/validate.ts
+function validateLessonsGraph(graph, options = {}) {
+  const findings = [];
+  const schemaResult = LessonsGraphSchema.safeParse(graph);
+  if (!schemaResult.success) {
+    findings.push({
+      level: "error",
+      code: "SCHEMA_INVALID",
+      message: schemaResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")
+    });
+    return { ok: false, findings };
+  }
+  collectDanglingRefs(graph, findings);
+  collectDuplicateRefs(graph, findings);
+  collectStatusInvariants(graph, findings);
+  collectLifecycleInvariants(graph, findings);
+  collectDuplicateRules(graph, findings);
+  collectReachability(graph, findings);
+  collectInvalidTriggerPatterns(graph, findings);
+  collectBackslashGlobPatterns(graph, findings);
+  collectDuplicateTriggers(graph, findings);
+  collectOrphans(graph, findings);
+  collectFanout(graph, findings);
+  collectLowSignalKeywords(graph, findings);
+  collectStopwordKeywords(graph, findings);
+  collectRunnerAnchoredPatterns(graph, findings);
+  if (options.knownPaths !== void 0) collectDeadFileGlobs(graph, findings, options.knownPaths);
+  const ok = findings.every((f) => f.level !== "error");
+  return { ok, findings };
+}
+
+// src/core/lint/shared/lessons.ts
+var LESSONS_TARGET = "lessons";
+var GRAPH_REL = ".agentsmesh/lessons/lessons.json";
+var ROOT_RULE_REL = ".agentsmesh/rules/_root.md";
+var LESSONS_HEADING = /^## Lessons \(/m;
+function lintLessonsSubsystem(projectRoot, scope) {
+  if (scope === "global") return [];
+  const paths = lessonsPaths(projectRoot);
+  if (!existsSync(paths.graph)) return [];
+  const out2 = [];
+  let graph;
+  try {
+    graph = loadLessonsGraph(projectRoot);
+  } catch (err) {
+    return [
+      diag(
+        "error",
+        GRAPH_REL,
+        `lessons.json failed to load: ${err instanceof Error ? err.message : String(err)}`
+      )
+    ];
+  }
+  const knownPaths = listProjectFiles(projectRoot) ?? void 0;
+  const report = validateLessonsGraph(graph, { knownPaths });
+  for (const finding of report.findings) {
+    out2.push(diag(finding.level, GRAPH_REL, `[${finding.code}] ${finding.message}`));
+  }
+  const rootRuleAbs = join(projectRoot, ROOT_RULE_REL);
+  const rootRuleBody = existsSync(rootRuleAbs) ? readFileSync(rootRuleAbs, "utf8") : "";
+  if (!LESSONS_HEADING.test(rootRuleBody)) {
+    out2.push(
+      diag(
+        "warning",
+        ROOT_RULE_REL,
+        'lessons procedural rule ("## Lessons (...)") is missing from _root.md \u2014 recall/capture enforcement will not fire.'
+      )
+    );
+  }
+  return out2;
+}
+function diag(level, file, message) {
+  return { level, file, target: LESSONS_TARGET, message };
+}
+
+// src/core/lint/linter.ts
+var EXCLUDE_DIRS = ["node_modules", ".git", "dist", "coverage", ".agentsmesh"];
+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));
+}
+async function runLint(config, canonical, projectRoot, targetFilter, options = {}) {
+  const scope = options.scope ?? "project";
+  const allTargets = [...config.targets, ...config.pluginTargets ?? []];
+  const targets = targetFilter ? allTargets.filter((t) => targetFilter.includes(t)) : allTargets;
+  const hasRules = config.features.includes("rules");
+  const hasCommands = config.features.includes("commands");
+  const hasMcp = config.features.includes("mcp");
+  const hasPermissions = config.features.includes("permissions");
+  const hasHooks = config.features.includes("hooks");
+  const diagnostics = [...lintLessonsSubsystem(projectRoot, scope)];
+  const projectFiles = scope === "global" ? [] : await getProjectFiles(projectRoot);
+  for (const target31 of targets) {
+    const fullDesc = getDescriptor(target31);
+    const descriptor31 = isBuiltinTargetId(target31) ? getTargetCatalogEntry(target31) : fullDesc;
+    if (descriptor31?.capabilities) {
+      diagnostics.push(
+        ...lintSilentFeatureDrops({
+          target: target31,
+          capabilities: descriptor31.capabilities,
+          canonical,
+          enabledFeatures: config.features
+        })
       );
-      diffs.push({ path: r.path, patch });
+    }
+    if (hasHooks) {
+      diagnostics.push(
+        ...lintHookScriptReferences({
+          target: target31,
+          canonical,
+          hasScriptProjection: fullDesc?.postProcessHookOutputs !== void 0
+        })
+      );
+    }
+    if (hasRules) {
+      diagnostics.push(
+        ...lintRuleScopeInversion({
+          target: target31,
+          canonical,
+          preservesManualActivation: fullDesc?.preservesManualActivation === true
+        })
+      );
+    }
+    if (hasRules && descriptor31?.lintRules) {
+      diagnostics.push(...descriptor31.lintRules(canonical, projectRoot, projectFiles, { scope }));
+    }
+    if (fullDesc?.generators.lint) {
+      diagnostics.push(...fullDesc.generators.lint(canonical));
+    }
+    const lintOpts = { scope };
+    if (hasCommands && descriptor31?.lint?.commands) {
+      diagnostics.push(...descriptor31.lint.commands(canonical, lintOpts));
+    }
+    if (hasMcp && descriptor31?.lint?.mcp) {
+      diagnostics.push(...descriptor31.lint.mcp(canonical, lintOpts));
+    }
+    if (hasPermissions && descriptor31?.lint?.permissions) {
+      diagnostics.push(...descriptor31.lint.permissions(canonical, lintOpts));
+    }
+    if (hasHooks && descriptor31?.lint?.hooks) {
+      diagnostics.push(...descriptor31.lint.hooks(canonical, lintOpts));
+    }
+  }
+  const hasErrors = diagnostics.some((d) => d.level === "error");
+  return { diagnostics, hasErrors };
+}
+function computeDiff(results) {
+  const diffs = [];
+  const summary = { new: 0, updated: 0, unchanged: 0, deleted: 0 };
+  for (const r of results) {
+    if (r.status === "unchanged") {
+      summary.unchanged++;
+      continue;
+    }
+    if (r.status === "created") {
+      summary.new++;
+      const patch = createTwoFilesPatch(
+        `${r.path} (current)`,
+        `${r.path} (generated)`,
+        "",
+        r.content,
+        void 0,
+        void 0,
+        { context: 3 }
+      );
+      diffs.push({ path: r.path, patch });
+      continue;
+    }
+    if (r.status === "updated" && r.currentContent !== void 0) {
+      summary.updated++;
+      const patch = createTwoFilesPatch(
+        `${r.path} (current)`,
+        `${r.path} (generated)`,
+        r.currentContent,
+        r.content,
+        void 0,
+        void 0,
+        { context: 3 }
+      );
+      diffs.push({ path: r.path, patch });
+      continue;
+    }
+  }
+  return { diffs, summary };
+}
+function formatDiffSummary(summary) {
+  return `${summary.new} files would be created, ${summary.updated} updated, ${summary.unchanged} unchanged, ${summary.deleted} deleted`;
+}
+
+// src/config/core/lock.ts
+init_fs();
+
+// src/utils/crypto/hash.ts
+init_fs_text_encoding();
+function hashContent(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+async function hashFile(path) {
+  try {
+    const bytes = await readFile(path);
+    return createHash("sha256").update(bytes).digest("hex");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+
+// src/config/core/lock.ts
+var LOCK_FILENAME = ".lock";
+var CANONICAL_PATTERNS = [
+  (r) => r.startsWith("rules/") && r.endsWith(".md"),
+  (r) => r.startsWith("commands/") && r.endsWith(".md"),
+  (r) => r.startsWith("agents/") && r.endsWith(".md"),
+  (r) => r.match(/^skills\/[^/]+\/.+$/) !== null,
+  (r) => r === "mcp.json",
+  (r) => r === "permissions.yaml",
+  (r) => r === "hooks.yaml",
+  (r) => r === "ignore"
+];
+function isCanonical(relPath) {
+  if (relPath.startsWith("packs/")) return false;
+  return CANONICAL_PATTERNS.some((p) => p(relPath));
+}
+var FEATURE_PATTERNS = {
+  rules: (path) => path.startsWith("rules/"),
+  commands: (path) => path.startsWith("commands/"),
+  agents: (path) => path.startsWith("agents/"),
+  skills: (path) => /^skills\/[^/]+\/.+$/.test(path),
+  mcp: (path) => path === "mcp.json",
+  permissions: (path) => path === "permissions.yaml",
+  hooks: (path) => path === "hooks.yaml",
+  ignore: (path) => path === "ignore"
+};
+async function readLock(abDir) {
+  const lockPath = join(abDir, LOCK_FILENAME);
+  const content = await readFileSafe(lockPath);
+  if (content === null) return null;
+  try {
+    const raw = parse(content);
+    if (!raw || typeof raw !== "object") return null;
+    return {
+      generatedAt: String(raw.generated_at ?? ""),
+      generatedBy: String(raw.generated_by ?? ""),
+      libVersion: String(raw.lib_version ?? ""),
+      checksums: raw.checksums && typeof raw.checksums === "object" ? raw.checksums : {},
+      extends: raw.extends && typeof raw.extends === "object" ? raw.extends : {},
+      packs: raw.packs && typeof raw.packs === "object" ? raw.packs : {}
+    };
+  } catch {
+    return null;
+  }
+}
+async function buildChecksums(abDir) {
+  if (!await exists(abDir)) return {};
+  const files = await readDirRecursive(abDir);
+  const result = {};
+  for (const fullPath of files) {
+    const rel2 = relative(abDir, fullPath).replace(/\\/g, "/");
+    if (rel2 === LOCK_FILENAME) continue;
+    if (!isCanonical(rel2)) continue;
+    const h = await hashFile(fullPath);
+    if (h !== null) {
+      result[rel2] = h.startsWith("sha256:") ? h : `sha256:${h}`;
+    }
+  }
+  return result;
+}
+function detectLockedFeatureViolations(lockChecksums, currentChecksums, lockFeatures) {
+  if (lockFeatures.length === 0) return [];
+  const matchers = lockFeatures.map((feature) => FEATURE_PATTERNS[feature]).filter((matcher) => matcher !== void 0);
+  if (matchers.length === 0) return [];
+  const allPaths = /* @__PURE__ */ new Set([...Object.keys(lockChecksums), ...Object.keys(currentChecksums)]);
+  const violations = [];
+  for (const path of allPaths) {
+    if (!matchers.some((matcher) => matcher(path))) continue;
+    if (lockChecksums[path] !== currentChecksums[path]) violations.push(path);
+  }
+  return violations;
+}
+async function buildExtendChecksums(resolvedExtends) {
+  const result = {};
+  for (const ext of resolvedExtends) {
+    if (ext.version !== void 0) {
+      result[ext.name] = ext.version;
+      continue;
+    }
+    const abDir = join(ext.resolvedPath, ".agentsmesh");
+    const checksums = await buildChecksums(abDir);
+    const fingerprint = Object.keys(checksums).sort().map((p) => `${p}:${checksums[p]}`).join("\n");
+    const h = hashContent(fingerprint);
+    const hex = h.startsWith("sha256:") ? h : `sha256:${h}`;
+    result[ext.name] = `local:${hex}`;
+  }
+  return result;
+}
+
+// src/core/check/lock-sync.ts
+async function checkLockSync(opts) {
+  const { config, configDir, canonicalDir } = opts;
+  const lock = await readLock(canonicalDir);
+  if (lock === null) {
+    return {
+      inSync: false,
+      hasLock: false,
+      modified: [],
+      added: [],
+      removed: [],
+      extendsModified: [],
+      lockedViolations: []
+    };
+  }
+  const current = await buildChecksums(canonicalDir);
+  const resolvedExtends = await resolveExtendPaths(config, configDir);
+  const currentExtends = resolvedExtends.length > 0 ? await buildExtendChecksums(resolvedExtends) : {};
+  const lockPaths = new Set(Object.keys(lock.checksums));
+  const currentPaths = new Set(Object.keys(current));
+  const modified = [];
+  const added = [];
+  const removed = [];
+  for (const path of lockPaths) {
+    const c2 = current[path];
+    if (c2 === void 0) {
+      removed.push(path);
+    } else if (c2 !== lock.checksums[path]) {
+      modified.push(path);
+    }
+  }
+  for (const path of currentPaths) {
+    if (!lockPaths.has(path)) {
+      added.push(path);
+    }
+  }
+  const extendNames = /* @__PURE__ */ new Set([...Object.keys(lock.extends), ...Object.keys(currentExtends)]);
+  const extendsModified = [];
+  for (const name of extendNames) {
+    if (currentExtends[name] !== lock.extends[name]) {
+      extendsModified.push(name);
+    }
+  }
+  const lockedViolations = detectLockedFeatureViolations(
+    lock.checksums,
+    current,
+    config.collaboration?.lock_features ?? []
+  );
+  const inSync = modified.length === 0 && added.length === 0 && removed.length === 0 && extendsModified.length === 0;
+  return {
+    inSync,
+    hasLock: true,
+    modified,
+    added,
+    removed,
+    extendsModified,
+    lockedViolations
+  };
+}
+
+// src/public/engine.ts
+init_registry();
+init_target_ids();
+async function importFrom(target31, opts) {
+  const descriptor31 = getDescriptor(target31);
+  if (!descriptor31) {
+    throw new TargetNotFoundError(target31, {
+      supported: [...TARGET_IDS, ...getAllDescriptors().map((d) => d.id)]
+    });
+  }
+  return descriptor31.generators.importFrom(opts.root, { scope: opts.scope ?? "project" });
+}
+async function loadConfig2(projectRoot) {
+  return loadConfigFromDir(projectRoot);
+}
+async function loadConfigFromDirectory(configDir) {
+  return loadConfigFromExactDir(configDir);
+}
+async function loadProjectContext(projectRoot, options = {}) {
+  const scope = options.scope ?? "project";
+  const { config, context } = await loadScopedConfig(projectRoot, scope);
+  await bootstrapPlugins(config, projectRoot);
+  const { canonical } = await loadCanonicalWithExtends(
+    config,
+    context.configDir,
+    { refreshRemoteCache: options.refreshRemoteCache === true },
+    context.canonicalDir
+  );
+  return {
+    config,
+    canonical,
+    projectRoot: context.rootBase,
+    scope,
+    configDir: context.configDir,
+    canonicalDir: context.canonicalDir
+  };
+}
+async function lint(opts) {
+  const filter = opts.targetFilter ? [...opts.targetFilter] : void 0;
+  return runLint(opts.config, opts.canonical, opts.projectRoot, filter, {
+    scope: opts.scope
+  });
+}
+function computeDiff2(results) {
+  return computeDiff([...results]);
+}
+async function diff(ctx) {
+  const results = await generate(ctx);
+  const computed = computeDiff(results);
+  return { ...computed, results };
+}
+async function check(opts) {
+  return checkLockSync(opts);
+}
+
+// src/public/canonical.ts
+init_errors();
+async function loadCanonical(projectRoot, options = {}) {
+  if (options.includeExtends === false) {
+    return loadCanonicalFiles(options.canonicalDir ?? projectRoot);
+  }
+  if (options.config === void 0 && options.configDir !== void 0 || options.config !== void 0 && options.configDir === void 0) {
+    throw new Error("loadCanonical options require both config and configDir, or neither.");
+  }
+  try {
+    const loaded = options.config !== void 0 && options.configDir !== void 0 ? { config: options.config, configDir: options.configDir } : await loadConfigFromDir(projectRoot);
+    const { canonical } = await loadCanonicalWithExtends(
+      loaded.config,
+      loaded.configDir,
+      { refreshRemoteCache: options.refreshRemoteCache === true },
+      options.canonicalDir
+    );
+    return canonical;
+  } catch (err) {
+    if (err instanceof ConfigNotFoundError && options.config === void 0 && options.configDir === void 0) {
+      return loadCanonicalFiles(options.canonicalDir ?? projectRoot);
+    }
+    throw err;
+  }
+}
+
+// src/public/targets.ts
+init_builtin_targets();
+init_registry();
+init_descriptor_import_runner();
+function copyCapabilities(capabilities17) {
+  return Object.freeze({ ...capabilities17 });
+}
+function copyGenerators(generators) {
+  return Object.freeze({ ...generators });
+}
+function copyOutputFamily(family) {
+  return Object.freeze({
+    ...family,
+    explicitPaths: family.explicitPaths === void 0 ? void 0 : Object.freeze([...family.explicitPaths])
+  });
+}
+function copyManagedOutputs(outputs) {
+  return Object.freeze({
+    dirs: Object.freeze([...outputs.dirs]),
+    files: Object.freeze([...outputs.files])
+  });
+}
+function copyLayout(layout) {
+  return Object.freeze({
+    ...layout,
+    outputFamilies: layout.outputFamilies === void 0 ? void 0 : Object.freeze(layout.outputFamilies.map(copyOutputFamily)),
+    managedOutputs: layout.managedOutputs === void 0 ? void 0 : copyManagedOutputs(layout.managedOutputs),
+    paths: Object.freeze({ ...layout.paths })
+  });
+}
+function copyGlobalSupport(globalSupport) {
+  return Object.freeze({
+    ...globalSupport,
+    capabilities: copyCapabilities(globalSupport.capabilities),
+    detectionPaths: Object.freeze([...globalSupport.detectionPaths]),
+    layout: copyLayout(globalSupport.layout)
+  });
+}
+function copyTargetDescriptor(descriptor31) {
+  return Object.freeze({
+    ...descriptor31,
+    generators: copyGenerators(descriptor31.generators),
+    capabilities: copyCapabilities(descriptor31.capabilities),
+    globalSupport: descriptor31.globalSupport === void 0 ? void 0 : copyGlobalSupport(descriptor31.globalSupport),
+    lint: descriptor31.lint === void 0 ? void 0 : Object.freeze({ ...descriptor31.lint }),
+    project: copyLayout(descriptor31.project),
+    supportsConversion: descriptor31.supportsConversion === void 0 ? void 0 : Object.freeze({ ...descriptor31.supportsConversion }),
+    detectionPaths: Object.freeze([...descriptor31.detectionPaths]),
+    sharedArtifacts: descriptor31.sharedArtifacts === void 0 ? void 0 : Object.freeze({ ...descriptor31.sharedArtifacts })
+  });
+}
+function getTargetCatalog() {
+  return Object.freeze(BUILTIN_TARGETS.map(copyTargetDescriptor));
+}
+function normalizeRule2(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function union(base, extra) {
+  const out2 = [...base];
+  for (const item of extra) if (!out2.includes(item)) out2.push(item);
+  return out2;
+}
+function mergeTriggers(graph, spec) {
+  const requested = [
+    // Normalize `\` → `/` so a Windows-shaped glob matches: recall relativizes
+    // every `--file` to forward slashes (normalizeRecallFile), so a backslash
+    // pattern stored raw would silently never fire. Normalizing here also lets
+    // a backslash pattern dedupe against the forward-slash node it equals.
+    ...(spec.files ?? []).map(
+      (p) => ({ kind: "file_glob", pattern: p.replaceAll("\\", "/") })
+    ),
+    ...(spec.commands ?? []).map((p) => ({ kind: "command_pattern", pattern: p })),
+    ...(spec.keywords ?? []).map((p) => ({ kind: "keyword", pattern: p }))
+  ];
+  const reverseLookup = /* @__PURE__ */ new Map();
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    reverseLookup.set(triggerKey(trigger), id);
+  }
+  const triggerIds = [];
+  const newTriggerIds = [];
+  for (const spec2 of requested) {
+    const key = triggerKey(spec2);
+    const existing = reverseLookup.get(key);
+    if (existing !== void 0) {
+      if (!triggerIds.includes(existing)) triggerIds.push(existing);
       continue;
     }
-    if (r.status === "updated" && r.currentContent !== void 0) {
-      summary.updated++;
-      const patch = createTwoFilesPatch(
-        `${r.path} (current)`,
-        `${r.path} (generated)`,
-        r.currentContent,
-        r.content,
-        void 0,
-        void 0,
-        { context: 3 }
-      );
-      diffs.push({ path: r.path, patch });
+    const id = makeTriggerId(spec2);
+    graph.triggers[id] = { kind: spec2.kind, pattern: spec2.pattern };
+    reverseLookup.set(key, id);
+    triggerIds.push(id);
+    newTriggerIds.push(id);
+  }
+  return { triggerIds, newTriggerIds };
+}
+function triggerKey(t) {
+  return `${t.kind}|${t.pattern}`;
+}
+var TRIGGER_PREFIX = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId(spec) {
+  const hash = createHash("sha1").update(triggerKey(spec)).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX[spec.kind]}-${hash}`;
+}
+function makeLessonId(graph, topic, ruleKey) {
+  const slug = ruleToSlug(ruleKey);
+  const base = slug.length > 0 ? `${topic}-${slug}` : `${topic}-${createHash("sha1").update(ruleKey).digest("hex").slice(0, 8)}`;
+  let candidate = base;
+  let i = 2;
+  while (graph.lessons[candidate] !== void 0) {
+    candidate = `${base}-${i}`;
+    i += 1;
+  }
+  return candidate;
+}
+function ruleToSlug(rule) {
+  const words = rule.replace(/[^a-z0-9 ]+/g, " ").split(/\s+/).filter((w) => w.length > 0).slice(0, 5);
+  return words.join("-").slice(0, 40).replace(/-+$/, "");
+}
+function todayIso() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+// src/lessons/add-errors.ts
+var UnknownTopicError = class extends Error {
+  constructor(topic) {
+    super(`Unknown topic: ${topic}. Pass allowNewTopic + topicSummary to create it.`);
+    this.topic = topic;
+    this.name = "UnknownTopicError";
+  }
+  code = "UNKNOWN_TOPIC";
+};
+var RuleTooLongError = class extends Error {
+  constructor(length, max) {
+    super(
+      `Lesson rule is ${length} characters (max ${max}). A rule should be one imperative sentence \u2014 trim it to the essential instruction, or split it into separate lessons.`
+    );
+    this.length = length;
+    this.max = max;
+    this.name = "RuleTooLongError";
+  }
+  code = "OVERSIZED_RULE";
+};
+var NoTriggerError = class extends Error {
+  code = "NO_TRIGGER";
+  constructor() {
+    super(
+      "A lesson needs at least one trigger to be recallable. Pass --trigger-file <glob> (preferred), --trigger-cmd <regex>, or --trigger-kw <text>."
+    );
+    this.name = "NoTriggerError";
+  }
+};
+var UnrecallableLessonError = class extends Error {
+  constructor(deadTriggers) {
+    super(
+      "This capture would create a lesson with no effective trigger \u2014 every trigger is dead on the mandatory --file/--cmd recall path, so the lesson could never be recalled there:\n" + deadTriggers.map((t) => `  \u2022 ${t.kind} "${t.pattern}" \u2014 ${t.reason}`).join("\n") + '\nFix: add a precise --trigger-file <glob> (preferred) or a valid --trigger-cmd <regex>; for a keyword, drop the stopwords (e.g. "state art" not "state of the art").'
+    );
+    this.deadTriggers = deadTriggers;
+    this.name = "UnrecallableLessonError";
+  }
+  code = "UNRECALLABLE_LESSON";
+};
+
+// src/lessons/capture-guardrails.ts
+var NEAR_DUPLICATE_THRESHOLD = 0.6;
+var MAX_RECOMMENDED_TRIGGERS = 8;
+function isBroadGlob(pattern) {
+  const p = pattern.trim();
+  if (p === "*" || p === "**") return true;
+  if (!p.includes("**")) return false;
+  const basename69 = p.slice(p.lastIndexOf("/") + 1);
+  return basename69.startsWith("*");
+}
+function inspectCapturedLesson(graph, lessonId, knownPaths) {
+  const lesson = graph.lessons[lessonId];
+  if (lesson === void 0) return [];
+  const warnings = [];
+  if (lesson.triggers.length > MAX_RECOMMENDED_TRIGGERS) {
+    warnings.push({
+      code: "OVERSIZED_LESSON_TRIGGERS",
+      message: `Lesson "${lessonId}" has ${lesson.triggers.length} triggers (recommended \u2264 ${MAX_RECOMMENDED_TRIGGERS}); broad trigger sets fire on too many edits and dilute recall \u2014 prefer a few specific triggers.`
+    });
+  }
+  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
+  const broad = triggers.filter((t) => t.kind === "file_glob" && isBroadGlob(t.pattern)).map((t) => t.pattern);
+  if (broad.length > 0) {
+    warnings.push({
+      code: "BROAD_GLOB_TRIGGER",
+      message: `Lesson "${lessonId}" has broad file glob(s) (${broad.join(", ")}) that match large swaths of the tree; prefer a path specific to the lesson.`
+    });
+  }
+  if (triggers.length > 0 && triggers.every((t) => t.kind === "keyword")) {
+    warnings.push({
+      code: "KEYWORD_ONLY_LESSON",
+      message: `Lesson "${lessonId}" has only keyword triggers; mandatory --file/--cmd recall surfaces these only when the keyword appears as a path/command token, so it fires less reliably \u2014 add a file_glob or command_pattern trigger for precise recall.`
+    });
+  }
+  const lowSignal = triggers.filter((t) => t.kind === "keyword" && isLowSignalKeyword(t.pattern)).map((t) => t.pattern);
+  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.`
+    });
+  }
+  const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
+  if (stopworded.length > 0) {
+    warnings.push({
+      code: "STOPWORD_KEYWORD",
+      message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
+    });
+  }
+  if (knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, knownPaths);
+    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
+    if (deadHere.length > 0) {
+      warnings.push({
+        code: "DEAD_GLOB",
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
+      });
+    }
+  }
+  return warnings;
+}
+function nearDuplicateWarning(graph, lessonId) {
+  const subject = graph.lessons[lessonId];
+  if (subject === void 0) return null;
+  const subjectTokens = new Set(tokenize(subject.rule));
+  if (subjectTokens.size === 0) return null;
+  let best = null;
+  for (const [id, other] of Object.entries(graph.lessons)) {
+    if (id === lessonId || other.status !== "active") continue;
+    const otherTokens = new Set(tokenize(other.rule));
+    if (otherTokens.size === 0) continue;
+    const score = jaccard(subjectTokens, otherTokens);
+    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
+      best = { id, score };
+    }
+  }
+  if (best === null) return null;
+  return {
+    code: "NEAR_DUPLICATE_LESSON",
+    message: `Lesson "${lessonId}" closely resembles active lesson "${best.id}" (~${Math.round(best.score * 100)}% token overlap); consider updating "${best.id}" instead of adding a paraphrase (recall would surface both).`
+  };
+}
+function jaccard(a, b) {
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
+var LegacyTriggersSchema = z.object({
+  file_globs: z.array(z.string()),
+  command_patterns: z.array(z.string()),
+  keywords: z.array(z.string())
+}).refine((t) => t.file_globs.length + t.command_patterns.length + t.keywords.length > 0, {
+  message: "cluster must declare at least one trigger of any type"
+});
+var LegacyClusterSchema = z.object({
+  topic: z.string().regex(/^[a-z0-9-]+$/),
+  file: z.string().regex(/\.md$/),
+  summary: z.string().min(1),
+  triggers: LegacyTriggersSchema
+});
+var LegacyIndexSchema = z.object({
+  version: z.literal(1),
+  clusters: z.array(LegacyClusterSchema)
+});
+function collectClusterTriggerIds(cluster, triggersById, triggerIdByKey) {
+  const specs = [
+    ...cluster.triggers.file_globs.map((p) => ({ kind: "file_glob", pattern: p })),
+    ...cluster.triggers.command_patterns.map(
+      (p) => ({ kind: "command_pattern", pattern: p })
+    ),
+    ...cluster.triggers.keywords.map((p) => ({ kind: "keyword", pattern: p }))
+  ];
+  const ids = [];
+  for (const spec of specs) {
+    const key = `${spec.kind}|${spec.pattern}`;
+    let id = triggerIdByKey.get(key);
+    if (id === void 0) {
+      id = makeTriggerId2(spec);
+      triggerIdByKey.set(key, id);
+      triggersById.set(id, { kind: spec.kind, pattern: spec.pattern });
+    }
+    if (!ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+var TRIGGER_PREFIX2 = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId2(spec) {
+  const hash = createHash("sha1").update(`${spec.kind}|${spec.pattern}`).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX2[spec.kind]}-${hash}`;
+}
+var RULE_HEADING_RE = /^##\s+Rules\b.*$/i;
+var NEXT_HEADING_RE = /^##\s+/;
+var RULE_LINE_RE = /^(\d+)\.\s+(.+?)\s*$/;
+var EVIDENCE_TAIL_RE = /\s*\(Evidence:?\s+([^)]+)\)\s*$/;
+var EVIDENCE_REF_RE = /L\d+/g;
+function parseRulesSection(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  let inRules = false;
+  const rules = [];
+  for (const line of lines) {
+    if (!inRules) {
+      if (RULE_HEADING_RE.test(line)) inRules = true;
       continue;
     }
+    if (NEXT_HEADING_RE.test(line)) break;
+    const m = RULE_LINE_RE.exec(line);
+    if (m === null) continue;
+    const ruleIndex = Number(m[1]);
+    let body = m[2];
+    const evidence = [];
+    let tail = EVIDENCE_TAIL_RE.exec(body);
+    while (tail !== null) {
+      const refs = tail[1];
+      const matches = refs.match(EVIDENCE_REF_RE);
+      if (matches !== null) evidence.unshift(...matches);
+      body = body.slice(0, tail.index).trimEnd();
+      tail = EVIDENCE_TAIL_RE.exec(body);
+    }
+    rules.push({ index: ruleIndex, body, evidence });
   }
-  return { diffs, summary };
+  return rules;
 }
-function formatDiffSummary(summary) {
-  return `${summary.new} files would be created, ${summary.updated} updated, ${summary.unchanged} unchanged, ${summary.deleted} deleted`;
+var LEGACY_ARTIFACT_REL = [
+  "index.yaml",
+  "journal.md",
+  "journal.legacy.md",
+  "topics",
+  "distill-ledger.yaml",
+  "distill-proposal.md"
+];
+function deleteLegacyArtifacts(baseDir) {
+  const deleted = [];
+  for (const rel2 of LEGACY_ARTIFACT_REL) {
+    const abs = join(baseDir, rel2);
+    if (!existsSync(abs)) continue;
+    rmSync(abs, { recursive: true, force: true });
+    deleted.push(abs);
+  }
+  return deleted;
+}
+
+// src/lessons/import-legacy-merge.ts
+async function mergeLegacy(projectRoot, paths, specs, summaryByTopic, options) {
+  let addedLessons = 0;
+  const addedTriggers = /* @__PURE__ */ new Set();
+  const touchedTopics = /* @__PURE__ */ new Set();
+  await mutateLessonsGraphLocked(projectRoot, (g) => {
+    addedLessons = 0;
+    addedTriggers.clear();
+    touchedTopics.clear();
+    for (const spec of specs) {
+      const result = addLessonInto(g, spec, {
+        allowNewTopic: true,
+        topicSummary: summaryByTopic.get(spec.topic),
+        // Legacy lessons may predate the ≥1-trigger requirement; recover them
+        // as-is rather than dropping historical knowledge.
+        allowNoTrigger: true
+      });
+      if (result.isNewLesson) addedLessons += 1;
+      for (const t of result.newTriggerIds) addedTriggers.add(t);
+      touchedTopics.add(spec.topic);
+    }
+  });
+  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  return {
+    wroteGraphPath: paths.graph,
+    deletedPaths,
+    topicCount: touchedTopics.size,
+    lessonCount: addedLessons,
+    triggerCount: addedTriggers.size
+  };
 }
 
-// src/config/core/lock.ts
-init_fs();
+// src/lessons/import-legacy.ts
+var LessonsGraphExistsError = class extends Error {
+  code = "LESSONS_GRAPH_EXISTS";
+  constructor() {
+    super("importLegacyLessons: a non-empty lessons.json already exists; pass force to overwrite.");
+    this.name = "LessonsGraphExistsError";
+  }
+};
+async function importLegacyLessons(projectRoot, options) {
+  const paths = lessonsPaths(projectRoot);
+  const indexRaw = readFileSync(paths.index, "utf8");
+  const index = LegacyIndexSchema.parse(parse(indexRaw));
+  const topics = {};
+  const triggersById = /* @__PURE__ */ new Map();
+  const triggerIdByKey = /* @__PURE__ */ new Map();
+  const lessons = {};
+  const specs = [];
+  const summaryByTopic = /* @__PURE__ */ new Map();
+  for (const cluster of index.clusters) {
+    topics[cluster.topic] = { summary: cluster.summary };
+    summaryByTopic.set(cluster.topic, cluster.summary);
+    const clusterTriggerIds = collectClusterTriggerIds(cluster, triggersById, triggerIdByKey);
+    const topicFile = join(projectRoot, cluster.file);
+    if (!existsSync(topicFile)) {
+      throw new Error(
+        `importLegacyLessons: declared topic file is missing: ${cluster.file}. Refusing to migrate (legacy artifacts left intact).`
+      );
+    }
+    const topicMarkdown = readFileSync(topicFile, "utf8");
+    for (const { index: ruleIndex, body, evidence } of parseRulesSection(topicMarkdown)) {
+      const lessonEvidence = [
+        `legacy:${cluster.file}#rule-${ruleIndex}`,
+        ...evidence.map((e) => `legacy:${e}`)
+      ];
+      lessons[`${cluster.topic}-rule-${ruleIndex}`] = {
+        rule: body,
+        topics: [cluster.topic],
+        triggers: clusterTriggerIds,
+        evidence: lessonEvidence,
+        status: "active",
+        createdAt: options.migratedAt
+      };
+      specs.push({
+        rule: body,
+        topic: cluster.topic,
+        triggers: {
+          files: cluster.triggers.file_globs,
+          commands: cluster.triggers.command_patterns,
+          keywords: cluster.triggers.keywords
+        },
+        evidence: lessonEvidence,
+        createdAt: options.migratedAt
+      });
+    }
+  }
+  if (options.merge === true)
+    return mergeLegacy(projectRoot, paths, specs, summaryByTopic, options);
+  const triggers = Object.fromEntries(triggersById.entries());
+  await mutateLessonsGraphLocked(projectRoot, (g) => {
+    const populated = Object.keys(g.lessons).length > 0 || Object.keys(g.topics).length > 0 || Object.keys(g.triggers).length > 0;
+    if (options.force !== true && populated) {
+      throw new LessonsGraphExistsError();
+    }
+    g.version = 1;
+    g.lessons = lessons;
+    g.topics = topics;
+    g.triggers = triggers;
+  });
+  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  return {
+    wroteGraphPath: paths.graph,
+    deletedPaths,
+    topicCount: Object.keys(topics).length,
+    lessonCount: Object.keys(lessons).length,
+    triggerCount: triggersById.size
+  };
+}
 
-// src/utils/crypto/hash.ts
-init_fs_text_encoding();
-function hashContent(content) {
-  return createHash("sha256").update(content, "utf8").digest("hex");
+// src/lessons/auto-migrate.ts
+function todayIso2() {
+  const now = /* @__PURE__ */ new Date();
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
 }
-async function hashFile(path) {
+async function maybeAutoMigrateLessons(projectRoot) {
+  if (existsSync(graphFilePath(projectRoot))) return false;
+  const paths = lessonsPaths(projectRoot);
+  if (!existsSync(paths.index)) return false;
   try {
-    const bytes = await readFile(path);
-    return createHash("sha256").update(bytes).digest("hex");
+    await importLegacyLessons(projectRoot, { migratedAt: todayIso2() });
+    return true;
   } catch (err) {
-    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
-      return null;
-    }
+    if (err instanceof LessonsGraphExistsError) return false;
     throw err;
   }
 }
 
-// src/config/core/lock.ts
-var LOCK_FILENAME = ".lock";
-var CANONICAL_PATTERNS = [
-  (r) => r.startsWith("rules/") && r.endsWith(".md"),
-  (r) => r.startsWith("commands/") && r.endsWith(".md"),
-  (r) => r.startsWith("agents/") && r.endsWith(".md"),
-  (r) => r.match(/^skills\/[^/]+\/.+$/) !== null,
-  (r) => r === "mcp.json",
-  (r) => r === "permissions.yaml",
-  (r) => r === "hooks.yaml",
-  (r) => r === "ignore"
-];
-function isCanonical(relPath) {
-  if (relPath.startsWith("packs/")) return false;
-  return CANONICAL_PATTERNS.some((p) => p(relPath));
+// src/utils/filesystem/process-lock.ts
+init_errors();
+var DEFAULT_STALE_MS = 6e4;
+var DEFAULT_RETRIES = 30;
+var DEFAULT_RETRY_DELAY_MS = 200;
+var YOUNG_LOCK_GRACE_MS = 2e3;
+async function acquireProcessLock(lockPath, opts = {}) {
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const stale = opts.staleMs ?? DEFAULT_STALE_MS;
+  await mkdir(dirname(lockPath), { recursive: true });
+  let attempt = 0;
+  while (true) {
+    const acquired = await tryAcquire(lockPath);
+    if (acquired) return acquired;
+    const existing = await inspectLock(lockPath);
+    if (existing !== "young" && isStale(existing, stale)) {
+      await rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      continue;
+    }
+    if (attempt >= retries) {
+      const holder = existing === "young" ? null : existing;
+      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
+    }
+    attempt++;
+    await sleep2(delay);
+  }
 }
-var FEATURE_PATTERNS = {
-  rules: (path) => path.startsWith("rules/"),
-  commands: (path) => path.startsWith("commands/"),
-  agents: (path) => path.startsWith("agents/"),
-  skills: (path) => /^skills\/[^/]+\/.+$/.test(path),
-  mcp: (path) => path === "mcp.json",
-  permissions: (path) => path === "permissions.yaml",
-  hooks: (path) => path === "hooks.yaml",
-  ignore: (path) => path === "ignore"
-};
-async function readLock(abDir) {
-  const lockPath = join(abDir, LOCK_FILENAME);
-  const content = await readFileSafe(lockPath);
-  if (content === null) return null;
+async function tryAcquire(lockPath) {
   try {
-    const raw = parse(content);
-    if (!raw || typeof raw !== "object") return null;
-    return {
-      generatedAt: String(raw.generated_at ?? ""),
-      generatedBy: String(raw.generated_by ?? ""),
-      libVersion: String(raw.lib_version ?? ""),
-      checksums: raw.checksums && typeof raw.checksums === "object" ? raw.checksums : {},
-      extends: raw.extends && typeof raw.extends === "object" ? raw.extends : {},
-      packs: raw.packs && typeof raw.packs === "object" ? raw.packs : {}
-    };
+    await mkdir(lockPath, { recursive: false });
+  } catch (err) {
+    if (err.code === "EEXIST") return null;
+    throw err;
+  }
+  const metadataPath = join(lockPath, "holder.json");
+  const metadata = {
+    pid: process.pid,
+    started: Date.now(),
+    hostname: getHostname()
+  };
+  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
+  let released = false;
+  const cleanup = () => {
+    if (released) return;
+    released = true;
+    try {
+      rmSync(lockPath, { recursive: true, force: true });
+    } catch {
+    }
+  };
+  const signalHandler = (signal) => {
+    cleanup();
+    process.kill(process.pid, signal);
+  };
+  process.once("SIGINT", signalHandler);
+  process.once("SIGTERM", signalHandler);
+  process.once("exit", cleanup);
+  return async () => {
+    if (released) return;
+    released = true;
+    process.off("SIGINT", signalHandler);
+    process.off("SIGTERM", signalHandler);
+    process.off("exit", cleanup);
+    await rm(lockPath, { recursive: true, force: true }).catch(() => {
+    });
+  };
+}
+async function inspectLock(lockPath) {
+  try {
+    const raw = await readFile(join(lockPath, "holder.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isLockMetadata(parsed)) return null;
+    return parsed;
   } catch {
+    try {
+      const info = await stat(lockPath);
+      const ageMs = Date.now() - info.mtimeMs;
+      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
+    } catch {
+    }
     return null;
   }
 }
-async function buildChecksums(abDir) {
-  if (!await exists(abDir)) return {};
-  const files = await readDirRecursive(abDir);
-  const result = {};
-  for (const fullPath of files) {
-    const rel2 = relative(abDir, fullPath).replace(/\\/g, "/");
-    if (rel2 === LOCK_FILENAME) continue;
-    if (!isCanonical(rel2)) continue;
-    const h = await hashFile(fullPath);
-    if (h !== null) {
-      result[rel2] = h.startsWith("sha256:") ? h : `sha256:${h}`;
-    }
+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);
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
   }
-  return result;
 }
-function detectLockedFeatureViolations(lockChecksums, currentChecksums, lockFeatures) {
-  if (lockFeatures.length === 0) return [];
-  const matchers = lockFeatures.map((feature) => FEATURE_PATTERNS[feature]).filter((matcher) => matcher !== void 0);
-  if (matchers.length === 0) return [];
-  const allPaths = /* @__PURE__ */ new Set([...Object.keys(lockChecksums), ...Object.keys(currentChecksums)]);
-  const violations = [];
-  for (const path of allPaths) {
-    if (!matchers.some((matcher) => matcher(path))) continue;
-    if (lockChecksums[path] !== currentChecksums[path]) violations.push(path);
+function describeHolder(meta) {
+  if (!meta) return "unknown (unreadable lock metadata)";
+  const host = meta.hostname ? `${meta.hostname}:` : "";
+  return `${host}pid ${meta.pid} (running ${Date.now() - meta.started}ms)`;
+}
+function isLockMetadata(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.pid === "number" && typeof v.started === "number";
+}
+function getHostname() {
+  return hostname();
+}
+function sleep2(ms) {
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
+}
+
+// src/lessons/lessons-lock.ts
+var LESSONS_LOCK_FILENAME = ".lessons.lock";
+function lessonsLockPath(projectRoot) {
+  return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
+}
+async function acquireLessonsLock(projectRoot, opts = {}) {
+  const lockPath = lessonsLockPath(projectRoot);
+  await mkdir(dirname(lockPath), { recursive: true });
+  return acquireProcessLock(lockPath, { ...opts, label: "lessons lock" });
+}
+
+// src/lessons/mutate.ts
+function emptyGraph() {
+  return { version: 1, lessons: {}, topics: {}, triggers: {} };
+}
+async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
+  const release = await acquireLessonsLock(projectRoot, { retries: options.retries });
+  try {
+    const graph = tryLoadLessonsGraph(projectRoot) ?? emptyGraph();
+    const result = await mutator(graph);
+    const report = validateLessonsGraph(graph);
+    if (!report.ok) {
+      const errors = report.findings.filter((f) => f.level === "error").map((f) => `${f.code}: ${f.message}`).join("; ");
+      throw new Error(`mutateLessonsGraph: refusing to write an invalid graph \u2014 ${errors}`);
+    }
+    saveLessonsGraph(projectRoot, graph);
+    return result;
+  } finally {
+    await release();
   }
-  return violations;
 }
-async function buildExtendChecksums(resolvedExtends) {
-  const result = {};
-  for (const ext of resolvedExtends) {
-    if (ext.version !== void 0) {
-      result[ext.name] = ext.version;
-      continue;
+async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  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";
     }
-    const abDir = join(ext.resolvedPath, ".agentsmesh");
-    const checksums = await buildChecksums(abDir);
-    const fingerprint = Object.keys(checksums).sort().map((p) => `${p}:${checksums[p]}`).join("\n");
-    const h = hashContent(fingerprint);
-    const hex = h.startsWith("sha256:") ? h : `sha256:${h}`;
-    result[ext.name] = `local:${hex}`;
+    return null;
   }
-  return result;
+  return null;
+}
+function blockingDeadTriggers(graph, triggerIds) {
+  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
 }
 
-// src/core/check/lock-sync.ts
-async function checkLockSync(opts) {
-  const { config, configDir, canonicalDir } = opts;
-  const lock = await readLock(canonicalDir);
-  if (lock === null) {
+// 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
+  });
+}
+function addLessonInto(graph, input, options) {
+  const ruleKey = normalizeRule2(input.rule);
+  const trimmedRule = input.rule.trim();
+  if (trimmedRule.length > MAX_RULE_LENGTH) {
+    throw new RuleTooLongError(trimmedRule.length, MAX_RULE_LENGTH);
+  }
+  const existingId = findExistingLessonByRule(graph, ruleKey);
+  const isNewTopic = graph.topics[input.topic] === void 0;
+  if (isNewTopic) {
+    if (options.allowNewTopic !== true) throw new UnknownTopicError(input.topic);
+    if (options.topicSummary === void 0 || options.topicSummary.length === 0) {
+      throw new Error(`addLesson: new topic "${input.topic}" requires topicSummary.`);
+    }
+    graph.topics[input.topic] = { summary: options.topicSummary };
+  }
+  if (options.allowNoTrigger !== true) {
+    const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
+    if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
+      throw new NoTriggerError();
+    }
+  }
+  const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
+  if (options.allowNoTrigger !== true) {
+    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 (existingId !== null) {
+    const existing = 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 } : {}
+    };
     return {
-      inSync: false,
-      hasLock: false,
-      modified: [],
-      added: [],
-      removed: [],
-      extendsModified: [],
-      lockedViolations: []
+      id: existingId,
+      isNewLesson: false,
+      isNewTopic,
+      newTriggerIds,
+      // Near-duplicate detection is meaningless on an upsert (the lesson IS the
+      // match), so only DEAD_GLOB/hygiene warnings apply here.
+      warnings: inspectCapturedLesson(graph, existingId, options.knownPaths)
     };
   }
-  const current = await buildChecksums(canonicalDir);
-  const resolvedExtends = await resolveExtendPaths(config, configDir);
-  const currentExtends = resolvedExtends.length > 0 ? await buildExtendChecksums(resolvedExtends) : {};
-  const lockPaths = new Set(Object.keys(lock.checksums));
-  const currentPaths = new Set(Object.keys(current));
-  const modified = [];
-  const added = [];
-  const removed = [];
-  for (const path of lockPaths) {
-    const c2 = current[path];
-    if (c2 === void 0) {
-      removed.push(path);
-    } else if (c2 !== lock.checksums[path]) {
-      modified.push(path);
-    }
+  const id = makeLessonId(graph, input.topic, ruleKey);
+  graph.lessons[id] = {
+    rule: trimmedRule,
+    topics: [input.topic],
+    triggers: triggerIds,
+    evidence: input.evidence === void 0 ? [] : [...input.evidence],
+    status: "active",
+    createdAt: input.createdAt ?? todayIso(),
+    ...input.rationale === void 0 ? {} : { rationale: input.rationale }
+  };
+  const warnings = inspectCapturedLesson(graph, id, options.knownPaths);
+  const nearDup = nearDuplicateWarning(graph, id);
+  return {
+    id,
+    isNewLesson: true,
+    isNewTopic,
+    newTriggerIds,
+    warnings: nearDup === null ? warnings : [...warnings, nearDup]
+  };
+}
+function findExistingLessonByRule(graph, ruleKey) {
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (normalizeRule2(lesson.rule) === ruleKey) return id;
   }
-  for (const path of currentPaths) {
-    if (!lockPaths.has(path)) {
-      added.push(path);
-    }
+  return null;
+}
+
+// src/lessons/ranking-signals.ts
+function buildFanout(graph) {
+  const fanout = /* @__PURE__ */ new Map();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) fanout.set(t, (fanout.get(t) ?? 0) + 1);
   }
-  const extendNames = /* @__PURE__ */ new Set([...Object.keys(lock.extends), ...Object.keys(currentExtends)]);
-  const extendsModified = [];
-  for (const name of extendNames) {
-    if (currentExtends[name] !== lock.extends[name]) {
-      extendsModified.push(name);
-    }
+  return fanout;
+}
+function buildTopicCoherence(matches) {
+  const topicCount = /* @__PURE__ */ new Map();
+  for (const { lesson } of matches) {
+    for (const t of lesson.topics) topicCount.set(t, (topicCount.get(t) ?? 0) + 1);
   }
-  const lockedViolations = detectLockedFeatureViolations(
-    lock.checksums,
-    current,
-    config.collaboration?.lock_features ?? []
-  );
-  const inSync = modified.length === 0 && added.length === 0 && removed.length === 0 && extendsModified.length === 0;
-  return {
-    inSync,
-    hasLock: true,
-    modified,
-    added,
-    removed,
-    extendsModified,
-    lockedViolations
-  };
+  const coherence = /* @__PURE__ */ new Map();
+  for (const { id, lesson } of matches) {
+    let best = 0;
+    for (const t of lesson.topics) best = Math.max(best, topicCount.get(t));
+    coherence.set(id, best);
+  }
+  return coherence;
+}
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
 }
 
-// src/public/engine.ts
-init_registry();
-init_target_ids();
-async function importFrom(target31, opts) {
-  const descriptor31 = getDescriptor(target31);
-  if (!descriptor31) {
-    throw new TargetNotFoundError(target31, {
-      supported: [...TARGET_IDS, ...getAllDescriptors().map((d) => d.id)]
-    });
+// src/lessons/capture-telemetry.ts
+function captureLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
+}
+
+// src/lessons/keyword-match.ts
+function splitTokens(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function deriveHaystackTokens(query) {
+  const parts = [];
+  if (query.file !== void 0) parts.push(query.file);
+  if (query.command !== void 0) parts.push(query.command);
+  return parts.length === 0 ? [] : splitTokens(parts.join(" "));
+}
+function containsRun(needle, hay) {
+  if (needle.length === 0) return false;
+  for (let i = 0; i + needle.length <= hay.length; i += 1) {
+    let hit = true;
+    for (let j = 0; j < needle.length; j += 1) {
+      if (hay[i + j] !== needle[j]) {
+        hit = false;
+        break;
+      }
+    }
+    if (hit) return true;
   }
-  return descriptor31.generators.importFrom(opts.root, { scope: opts.scope ?? "project" });
+  return false;
 }
-async function loadConfig2(projectRoot) {
-  return loadConfigFromDir(projectRoot);
+function keywordMatches(pattern, query) {
+  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+    return true;
+  }
+  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
 }
-async function loadConfigFromDirectory(configDir) {
-  return loadConfigFromExactDir(configDir);
+
+// src/lessons/query.ts
+var COMMAND_MATCH_BUDGET = 5e6;
+function queryLessons(graph, query) {
+  if (query.file === void 0 && query.command === void 0 && query.keyword === void 0) {
+    return [];
+  }
+  const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
+  const matched = [];
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (lesson.triggers.some((t) => matchedTriggerIds.has(t))) {
+      matched.push({ id, lesson });
+    }
+  }
+  matched.sort((a, b) => a.id < b.id ? -1 : 1);
+  return matched;
 }
-async function loadProjectContext(projectRoot, options = {}) {
-  const scope = options.scope ?? "project";
-  const { config, context } = await loadScopedConfig(projectRoot, scope);
-  await bootstrapPlugins(config, projectRoot);
-  const { canonical } = await loadCanonicalWithExtends(
-    config,
-    context.configDir,
-    { refreshRemoteCache: options.refreshRemoteCache === true },
-    context.canonicalDir
+function collectMatchedTriggersByKind(graph, query) {
+  const byKind = {
+    file_glob: /* @__PURE__ */ new Set(),
+    command_pattern: /* @__PURE__ */ new Set(),
+    keyword: /* @__PURE__ */ new Set()
+  };
+  const budget = { remaining: COMMAND_MATCH_BUDGET };
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    if (triggerMatches(trigger, query, budget)) byKind[trigger.kind].add(id);
+  }
+  return byKind;
+}
+function collectMatchedTriggerIds(graph, query) {
+  const { file_glob, command_pattern, keyword } = collectMatchedTriggersByKind(graph, query);
+  return /* @__PURE__ */ new Set([...file_glob, ...command_pattern, ...keyword]);
+}
+function triggerMatches(trigger, query, budget) {
+  switch (trigger.kind) {
+    case "file_glob":
+      if (query.file === void 0) return false;
+      return picomatch(trigger.pattern, { dot: true })(query.file);
+    case "command_pattern": {
+      if (query.command === void 0) return false;
+      const matcher = getCommandMatcher(trigger.pattern);
+      return matcher !== null && matcher.test(query.command, budget);
+    }
+    case "keyword":
+      return keywordMatches(trigger.pattern, query);
+  }
+}
+
+// src/lessons/ranking.ts
+var DEFAULT_RECALL_LIMIT = 10;
+var DEFAULT_RECALL_MAX_TOKENS = 400;
+var RRF_K = 60;
+var SPECIFICITY_WEIGHT = 3;
+var TOPIC_COHERENCE_WEIGHT = 2;
+var BM25_WEIGHT = 1;
+function rankMap(items) {
+  const sorted = [...items].sort(
+    (a, b) => b.value !== a.value ? b.value - a.value : a.id < b.id ? -1 : 1
   );
+  const ranks = /* @__PURE__ */ new Map();
+  let prevValue = null;
+  let prevRank = 0;
+  sorted.forEach((item, i) => {
+    const rank = prevValue !== null && item.value === prevValue ? prevRank : i + 1;
+    ranks.set(item.id, rank);
+    prevValue = item.value;
+    prevRank = rank;
+  });
+  return ranks;
+}
+function estTokens(rule) {
+  return Math.ceil(rule.length / 4);
+}
+function rankLessons(graph, query, matches, options = {}) {
+  if (matches.length === 0) return [];
+  const terms = queryTerms(query);
+  const corpus = buildCorpus(graph);
+  const fanout = buildFanout(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));
+    return {
+      id,
+      lesson,
+      bm25: bm25(terms, lesson.rule, corpus),
+      specificity,
+      // `id` is a matched lesson, and buildTopicCoherence keys every matched id.
+      topicCoherence: coherence.get(id),
+      matchedTriggers: hitTriggers
+    };
+  });
+  const bm25Ranks = rankMap(scored.map((s) => ({ id: s.id, value: s.bm25 })));
+  const specRanks = rankMap(scored.map((s) => ({ id: s.id, value: s.specificity })));
+  const topicRanks = rankMap(scored.map((s) => ({ id: s.id, value: s.topicCoherence })));
+  const ranked = scored.map((s) => ({
+    id: s.id,
+    lesson: s.lesson,
+    score: SPECIFICITY_WEIGHT / (RRF_K + specRanks.get(s.id)) + TOPIC_COHERENCE_WEIGHT / (RRF_K + topicRanks.get(s.id)) + BM25_WEIGHT / (RRF_K + bm25Ranks.get(s.id)),
+    reason: {
+      matchedTriggers: s.matchedTriggers,
+      bm25: s.bm25,
+      specificity: s.specificity,
+      topicCoherence: s.topicCoherence
+    }
+  })).sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const ca = a.lesson.createdAt;
+    const cb = b.lesson.createdAt;
+    if (ca !== cb) return ca < cb ? 1 : -1;
+    return a.id < b.id ? -1 : 1;
+  });
+  return applyCaps(ranked, options);
+}
+function applyCaps(ranked, options) {
+  let out2 = ranked;
+  if (options.limit !== void 0 && options.limit >= 0) out2 = out2.slice(0, options.limit);
+  if (options.maxTokens !== void 0 && out2.length > 0) {
+    const budgeted = [out2[0]];
+    let used = estTokens(out2[0].lesson.rule);
+    for (const row of out2.slice(1)) {
+      const cost = estTokens(row.lesson.rule);
+      if (used + cost > options.maxTokens) break;
+      used += cost;
+      budgeted.push(row);
+    }
+    out2 = budgeted;
+  }
+  return out2;
+}
+function defaultLessonsConfig() {
   return {
-    config,
-    canonical,
-    projectRoot: context.rootBase,
-    scope,
-    configDir: context.configDir,
-    canonicalDir: context.canonicalDir
+    recallLimit: DEFAULT_RECALL_LIMIT,
+    recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
+    autoPrune: false
   };
 }
-async function lint(opts) {
-  const filter = opts.targetFilter ? [...opts.targetFilter] : void 0;
-  return runLint(opts.config, opts.canonical, opts.projectRoot, filter, {
-    scope: opts.scope
+
+// src/lessons/merge.ts
+async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {
+  return mutateLessonsGraph(projectRoot, (graph) => mergeInto(graph, loserId, keeperId), {
+    retries: options.retries
   });
 }
-function computeDiff2(results) {
-  return computeDiff([...results]);
-}
-async function diff(ctx) {
-  const results = await generate(ctx);
-  const computed = computeDiff(results);
-  return { ...computed, results };
-}
-async function check(opts) {
-  return checkLockSync(opts);
-}
-
-// src/public/canonical.ts
-init_errors();
-async function loadCanonical(projectRoot, options = {}) {
-  if (options.includeExtends === false) {
-    return loadCanonicalFiles(options.canonicalDir ?? projectRoot);
+function mergeInto(graph, loserId, keeperId) {
+  if (loserId === keeperId) {
+    throw new Error(`mergeLessons: cannot merge lesson "${loserId}" into itself.`);
   }
-  if (options.config === void 0 && options.configDir !== void 0 || options.config !== void 0 && options.configDir === void 0) {
-    throw new Error("loadCanonical options require both config and configDir, or neither.");
+  const loser = graph.lessons[loserId];
+  if (loser === void 0) throw new Error(`mergeLessons: unknown lesson "${loserId}".`);
+  const keeper = graph.lessons[keeperId];
+  if (keeper === void 0) throw new Error(`mergeLessons: unknown lesson "${keeperId}".`);
+  if (keeper.status !== "active") {
+    throw new Error(`mergeLessons: keeper "${keeperId}" is not active (status: ${keeper.status}).`);
   }
-  try {
-    const loaded = options.config !== void 0 && options.configDir !== void 0 ? { config: options.config, configDir: options.configDir } : await loadConfigFromDir(projectRoot);
-    const { canonical } = await loadCanonicalWithExtends(
-      loaded.config,
-      loaded.configDir,
-      { refreshRemoteCache: options.refreshRemoteCache === true },
-      options.canonicalDir
+  if (loser.status !== "active") {
+    throw new Error(
+      `mergeLessons: loser "${loserId}" is already ${loser.status}; nothing to merge.`
     );
-    return canonical;
-  } catch (err) {
-    if (err instanceof ConfigNotFoundError && options.config === void 0 && options.configDir === void 0) {
-      return loadCanonicalFiles(options.canonicalDir ?? projectRoot);
-    }
-    throw err;
   }
+  graph.lessons[keeperId] = {
+    ...keeper,
+    triggers: union2(keeper.triggers, loser.triggers),
+    topics: union2(keeper.topics, loser.topics),
+    evidence: union2(keeper.evidence, loser.evidence)
+  };
+  graph.lessons[loserId] = { ...loser, status: "superseded", supersededBy: keeperId };
+  return { loserId, keeperId };
+}
+function union2(base, extra) {
+  const out2 = [...base];
+  for (const item of extra) {
+    if (!out2.includes(item)) out2.push(item);
+  }
+  return out2;
 }
 
-// src/public/targets.ts
-init_builtin_targets();
-init_registry();
-init_descriptor_import_runner();
-function copyCapabilities(capabilities17) {
-  return Object.freeze({ ...capabilities17 });
+// src/lessons/strip-markers.ts
+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"),
+  // " (L174)" / " (L92, L163)"
+  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]\.?`, "g")
+  // " [L161, L208]"
+];
+var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
+function stripLegacyMarkers(rule) {
+  let out2 = rule;
+  for (const pattern of LINE_REF_PATTERNS) out2 = out2.replace(pattern, "");
+  out2 = out2.replace(ALSO_RELEVANT_PATTERN, " ");
+  return out2.trim();
+}
+function applyStrip(graph) {
+  const changedIds = [];
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    const stripped = stripLegacyMarkers(lesson.rule);
+    if (stripped === lesson.rule || stripped.length === 0) continue;
+    changedIds.push(id);
+    graph.lessons[id] = { ...lesson, rule: stripped };
+  }
+  return changedIds.sort();
+}
+async function stripMarkersInGraph(projectRoot, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  const existing = tryLoadLessonsGraph(projectRoot);
+  if (existing === null) return { changedIds: [], changedCount: 0 };
+  if (options.dryRun === true) {
+    const changedIds2 = applyStrip(existing);
+    return { changedIds: changedIds2, changedCount: changedIds2.length };
+  }
+  let changedIds = [];
+  await mutateLessonsGraph(projectRoot, (graph) => {
+    changedIds = applyStrip(graph);
+  });
+  return { changedIds, changedCount: changedIds.length };
+}
+var RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
+var RECALL_HOOK_MATCHER = "Edit|Write|Bash";
+function injectRecallHook(projectRoot) {
+  const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
+  if (!existsSync(path)) return false;
+  const doc = parseDocument(readFileSync(path, "utf8"));
+  const existing = doc.get("PostToolUse");
+  const post = existing instanceof YAMLSeq ? existing : new YAMLSeq();
+  const present = post.items.some(
+    (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
+  );
+  if (present) return false;
+  post.add(
+    doc.createNode({ matcher: RECALL_HOOK_MATCHER, type: "command", command: RECALL_HOOK_COMMAND })
+  );
+  doc.set("PostToolUse", post);
+  writeFileSync(path, String(doc), "utf8");
+  return true;
 }
-function copyGenerators(generators) {
-  return Object.freeze({ ...generators });
+
+// src/utils/filesystem/gitignore.ts
+init_fs();
+async function ensureGitignoreEntries(projectRoot, entries) {
+  const gitignorePath = join(projectRoot, ".gitignore");
+  const current = await readFileSafe(gitignorePath) ?? "";
+  const existing = new Set(
+    current.split("\n").map((s) => s.trim()).filter((s) => s.length > 0 && !s.startsWith("#"))
+  );
+  const toAdd = entries.filter((e) => !isCoveredByExisting(e, existing));
+  if (toAdd.length === 0) return false;
+  const suffix = current.endsWith("\n") || current === "" ? "" : "\n";
+  await writeFileAtomic(gitignorePath, current + suffix + toAdd.join("\n") + "\n");
+  return true;
 }
-function copyOutputFamily(family) {
-  return Object.freeze({
-    ...family,
-    explicitPaths: family.explicitPaths === void 0 ? void 0 : Object.freeze([...family.explicitPaths])
-  });
+function isCoveredByExisting(candidate, existing) {
+  if (existing.has(candidate)) return true;
+  let parent = candidate.replace(/\/$/, "");
+  while (parent.includes("/")) {
+    parent = parent.slice(0, parent.lastIndexOf("/"));
+    if (parent === "") break;
+    if (existing.has(parent) || existing.has(`${parent}/`) || existing.has(`${parent}/**`)) {
+      return true;
+    }
+  }
+  return false;
 }
-function copyManagedOutputs(outputs) {
-  return Object.freeze({
-    dirs: Object.freeze([...outputs.dirs]),
-    files: Object.freeze([...outputs.files])
-  });
+
+// src/targets/projection/lessons-paragraph.ts
+init_managed_blocks();
+var LESSONS_PARAGRAPH_BLOCK = `${LESSONS_CONTRACT_START}
+${LESSONS_PROCEDURAL_RULE}
+${LESSONS_CONTRACT_END}`;
+function appendLessonsParagraph(content) {
+  const withoutPrior = stripLessonsParagraph(content);
+  return insertAtBodyTop(withoutPrior, LESSONS_PARAGRAPH_BLOCK);
 }
-function copyLayout(layout) {
-  return Object.freeze({
-    ...layout,
-    outputFamilies: layout.outputFamilies === void 0 ? void 0 : Object.freeze(layout.outputFamilies.map(copyOutputFamily)),
-    managedOutputs: layout.managedOutputs === void 0 ? void 0 : copyManagedOutputs(layout.managedOutputs),
-    paths: Object.freeze({ ...layout.paths })
-  });
+function stripLessonsParagraph(content) {
+  const withoutBlock = stripManagedBlock(content, LESSONS_CONTRACT_START, LESSONS_CONTRACT_END);
+  return stripRawProceduralRule(withoutBlock).trim();
 }
-function copyGlobalSupport(globalSupport) {
-  return Object.freeze({
-    ...globalSupport,
-    capabilities: copyCapabilities(globalSupport.capabilities),
-    detectionPaths: Object.freeze([...globalSupport.detectionPaths]),
-    layout: copyLayout(globalSupport.layout)
-  });
+function stripRawProceduralRule(content) {
+  return content.replace(`
+
+${LESSONS_PROCEDURAL_RULE}`, "").replace(LESSONS_PROCEDURAL_RULE, "");
 }
-function copyTargetDescriptor(descriptor31) {
-  return Object.freeze({
-    ...descriptor31,
-    generators: copyGenerators(descriptor31.generators),
-    capabilities: copyCapabilities(descriptor31.capabilities),
-    globalSupport: descriptor31.globalSupport === void 0 ? void 0 : copyGlobalSupport(descriptor31.globalSupport),
-    lint: descriptor31.lint === void 0 ? void 0 : Object.freeze({ ...descriptor31.lint }),
-    project: copyLayout(descriptor31.project),
-    supportsConversion: descriptor31.supportsConversion === void 0 ? void 0 : Object.freeze({ ...descriptor31.supportsConversion }),
-    detectionPaths: Object.freeze([...descriptor31.detectionPaths]),
-    sharedArtifacts: descriptor31.sharedArtifacts === void 0 ? void 0 : Object.freeze({ ...descriptor31.sharedArtifacts })
-  });
+
+// src/lessons/skill.ts
+init_markdown();
+var LESSONS_SKILL_NAME = "lessons";
+var LESSONS_SKILL_DESCRIPTION = "Full operating manual for the agentsmesh lessons system (recall + capture). Consult when running any `agentsmesh lessons` subcommand (query, add, topics, show, deprecate, merge, untrigger, strip-markers, journal, validate, stats, prune, import-md), choosing a topic or trigger flags, using the lessons MCP tools, or when unsure how to phrase or capture a lesson.";
+var LESSONS_SKILL_BODY = `# Lessons \u2014 operating manual
+
+Two commands: **Recall** before you act, **Capture** after any failure. The graph
+\`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit.
+
+## Recall \u2014 before each file edit and each state-changing command
+
+\`agentsmesh lessons query --file <path> --cmd <command>\` (add \`--keyword <text>\` to
+match by task), then apply every rule returned. Scope is MUTATING actions: file edits
+and state-changing commands (build/test/install/migrate/git-write). Pure-read commands
+(cat/ls/grep/git-log; read-only) and the recall query itself are **exempt** \u2014 no
+infinite regress. A predicate-less query is rejected; **keyword-only recall is the
+anti-pattern** \u2014 most lessons are keyed to a \`file_glob\`/\`command_pattern\` and won't
+surface (the CLI warns). Excuses ("small edit", "I already know this", "later") all
+mean: query first \u2014 skipping recall on a mutating action is a process violation, and
+the user will check.
+
+## Capture \u2014 immediately after any failure
+
+Any failure counts, not just red tests: a failing test/CI/lint/typecheck, a code
+review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's.
+
+\`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`
+
+- **At least one _effective_ trigger is required.** A capture is rejected
+  (\`UNRECALLABLE_LESSON\`) when EVERY trigger is dead on the mandatory \`--file\`/\`--cmd\`
+  recall path \u2014 a stopword-only keyword ("state of the art"), or an invalid/ReDoS
+  command regex \u2014 because the lesson could never be recalled there. Prefer
+  \`--trigger-file\`: the most reliable trigger, it fires on \`--file\` recall. A keyword
+  alone is discouraged (\`KEYWORD_ONLY_LESSON\`); paraphrasing an existing rule warns
+  (\`NEAR_DUPLICATE_LESSON\` \u2014 update that lesson instead).
+- **One imperative sentence.** A rule over 2000 chars is rejected (\`OVERSIZED_RULE\`) \u2014
+  trim it or split into separate lessons; don't paste a log/diff.
+- Widen with \`--trigger-cmd <regex>\` / \`--trigger-kw <text>\`. New area:
+  \`--new-topic --topic-summary "<line>"\` (list ids with \`agentsmesh lessons topics\`).
+
+## No shell? \u2014 MCP tools
+
+\`lessons_query\`, \`lessons_add\`, \`lessons_topics\`, \`lessons_show\` (inspect a topic),
+\`lessons_deprecate\` (retire). validate / prune / merge / import-md are CLI-only.
+
+## Other subcommands
+
+\`agentsmesh lessons <cmd>\`: \`show\` \xB7 \`deprecate\` (\`--superseded-by\`) \xB7 \`merge\` \xB7
+\`untrigger\` \xB7 \`strip-markers\` \xB7 \`prune\` (\`--apply\`; trims over-cap triggers, GCs
+orphan triggers/topics) \xB7 \`journal\` \xB7 \`validate\` \xB7 \`stats\` \xB7 \`import-md\`. Full
+help: \`agentsmesh lessons --help\`.
+
+## Config (\`.agentsmesh/lessons/config.json\`)
+
+\`recallLimit\` / \`recallMaxTokens\` (canonical recall caps; per-call overrides
+\`--top\` / \`--max-tokens\`). \`recallMaxTokens\` is approximate \u2014 \`rule.length / 4\`,
+not a real tokenizer. \`autoPrune: true\` (default off) auto-GCs structural cruft
+after each capture \u2014 orphan triggers/topics + non-stranding dead globs, the safe
+half of \`prune\`; never trims/strands an active lesson, git-reversible.
+
+## Dedup (opt-in)
+
+Set \`--session <id>\` (or \`AGENTSMESH_SESSION_ID\`) and lessons already delivered this
+session are suppressed, so each recall carries only what is new (\`--no-dedup\` opts
+out). With no session id, recall is fully stateless \u2014 unchanged.`;
+var LESSONS_SKILL_FILE = serializeFrontmatter(
+  { name: LESSONS_SKILL_NAME, description: LESSONS_SKILL_DESCRIPTION },
+  LESSONS_SKILL_BODY
+);
+
+// src/lessons/init.ts
+async function scaffoldLessons(projectRoot) {
+  const paths = lessonsPaths(projectRoot);
+  const created = [];
+  const updated = [];
+  const skipped = [];
+  mkdirSync(paths.base, { recursive: true });
+  await maybeAutoMigrateLessons(projectRoot);
+  if (existsSync(paths.graph)) {
+    skipped.push(paths.graph);
+  } else {
+    await mutateLessonsGraphLocked(projectRoot, () => {
+    });
+    created.push(paths.graph);
+  }
+  seedLessonsConfig(projectRoot, created, skipped);
+  seedLessonsSkill(projectRoot, created, updated, skipped);
+  const rootRuleUpdated = injectProceduralBlock(projectRoot);
+  const recallHookInjected = injectRecallHook(projectRoot);
+  const gitignoreUpdated = await ensureGitignoreEntries(projectRoot, [
+    toRelPath(projectRoot, recallLogPath(projectRoot)),
+    toRelPath(projectRoot, captureLogPath(projectRoot))
+  ]);
+  return { created, updated, skipped, rootRuleUpdated, gitignoreUpdated, recallHookInjected };
 }
-function getTargetCatalog() {
-  return Object.freeze(BUILTIN_TARGETS.map(copyTargetDescriptor));
+function seedLessonsSkill(projectRoot, created, updated, skipped) {
+  const skillPath = join(projectRoot, ".agentsmesh/skills", LESSONS_SKILL_NAME, "SKILL.md");
+  const desired = `${LESSONS_SKILL_FILE}
+`;
+  if (!existsSync(skillPath)) {
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, desired, "utf8");
+    created.push(skillPath);
+    return;
+  }
+  if (readFileSync(skillPath, "utf8") === desired) {
+    skipped.push(skillPath);
+    return;
+  }
+  writeFileSync(skillPath, desired, "utf8");
+  updated.push(skillPath);
+}
+function seedLessonsConfig(projectRoot, created, skipped) {
+  const configPath = lessonsPaths(projectRoot).config;
+  if (existsSync(configPath)) {
+    skipped.push(configPath);
+    return;
+  }
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(defaultLessonsConfig(), null, 2)}
+`, "utf8");
+  created.push(configPath);
+}
+function injectProceduralBlock(projectRoot) {
+  const rootRule = join(projectRoot, ".agentsmesh/rules/_root.md");
+  if (!existsSync(rootRule)) {
+    mkdirSync(dirname(rootRule), { recursive: true });
+    const seeded = `---
+root: true
+description: ""
+---
+
+${LESSONS_PARAGRAPH_BLOCK}
+
+# Operational Guidelines
+`;
+    writeFileSync(rootRule, seeded, "utf8");
+    return true;
+  }
+  const current = readFileSync(rootRule, "utf8");
+  const desired = `${appendLessonsParagraph(current)}
+`;
+  if (desired === current) return false;
+  writeFileSync(rootRule, desired, "utf8");
+  return true;
 }
 
-export { AgentsMeshError, ConfigNotFoundError, ConfigValidationError, FileSystemError, GenerationError, ImportError, LockAcquisitionError, RemoteFetchError, TargetNotFoundError, check, computeDiff2 as computeDiff, diff, formatDiffSummary, generate, getAllDescriptors, getDescriptor, getTargetCatalog, importFrom, lint, loadCanonical, loadCanonicalFiles, loadConfig2 as loadConfig, loadConfigFromDirectory, loadProjectContext, registerTargetDescriptor, resolveOutputCollisions };
+export { AgentsMeshError, ConfigNotFoundError, ConfigValidationError, DEFAULT_RECALL_LIMIT, FileSystemError, GenerationError, ImportError, LESSONS_PROCEDURAL_RULE, LessonsGraphSchema, LockAcquisitionError, RemoteFetchError, TargetNotFoundError, UnknownTopicError, acquireLessonsLock, addLesson, check, computeDiff2 as computeDiff, diff, formatDiffSummary, generate, getAllDescriptors, getDescriptor, getTargetCatalog, graphFilePath, importFrom, importLegacyLessons, lessonsPaths, lint, loadCanonical, loadCanonicalFiles, loadConfig2 as loadConfig, loadConfigFromDirectory, loadLessonsGraph, loadProjectContext, mergeLessons, mutateLessonsGraph, parseGraph, queryLessons, rankLessons, registerTargetDescriptor, resolveOutputCollisions, scaffoldLessons, serializeGraph, stripLegacyMarkers, stripMarkersInGraph, toRelPath, tryLoadLessonsGraph, validateLessonsGraph };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map