agentsmesh 0.22.0 → 0.23.0

package/dist/index.js

@@ -1,18 +1,19 @@
 import { z } from 'zod';
-import { parse, stringify } from 'yaml';
-import { join, relative, sep, dirname, isAbsolute, resolve, basename, win32, posix, extname } from 'path';
-import { access, readdir, readFile, realpath, stat, rm, mkdir, lstat, unlink, writeFile, rename, chmod, mkdtemp, cp } from 'fs/promises';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, constants, realpathSync, statSync } 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 { createTwoFilesPatch } from 'diff';
 import picomatch from 'picomatch';
+import { createTwoFilesPatch } from 'diff';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -46,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([
@@ -120,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,
@@ -131,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(),
@@ -631,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 {
@@ -804,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");
@@ -890,6 +933,7 @@ var init_fs = __esm({
     init_fs_text_encoding();
     init_fs_traverse();
     init_fs_text_encoding();
+    init_rename_retry();
   }
 });
 function escapeRegExp(value) {
@@ -898,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/");
@@ -998,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 -->";
@@ -1012,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);
@@ -1286,7 +1315,7 @@ function generateEmbeddedSkills(canonical, skillsDir) {
   }
   return outputs;
 }
-async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, normalize2) {
+async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, normalize) {
   const entries = await readdir(join(projectRoot, skillsDir), {
     encoding: "utf8",
     withFileTypes: true
@@ -1301,7 +1330,7 @@ async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, n
     const destinationSkillDir = join(projectRoot, AB_SKILLS, entry.name);
     const destinationSkillFile = join(destinationSkillDir, "SKILL.md");
     const { frontmatter, body } = parseFrontmatter(
-      normalize2(sourceSkillContent, sourceSkillFile, destinationSkillFile)
+      normalize(sourceSkillContent, sourceSkillFile, destinationSkillFile)
     );
     const projectedCommand = parseCommandSkillFrontmatter(frontmatter, entry.name);
     if (projectedCommand) {
@@ -1311,7 +1340,7 @@ async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, n
       const commandPath = join(destDir, `${projectedCommand.name}.md`);
       await writeFileAtomic(
         commandPath,
-        serializeImportedCommand(projectedCommand, normalize2(body, sourceSkillFile, commandPath))
+        serializeImportedCommand(projectedCommand, normalize(body, sourceSkillFile, commandPath))
       );
       results.push({
         fromTool,
@@ -1329,7 +1358,7 @@ async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, n
       const agentPath = join(destDir, `${projectedAgent.name}.md`);
       await writeFileAtomic(
         agentPath,
-        serializeImportedAgent(projectedAgent, normalize2(body, sourceSkillFile, agentPath))
+        serializeImportedAgent(projectedAgent, normalize(body, sourceSkillFile, agentPath))
       );
       results.push({
         fromTool,
@@ -1360,7 +1389,7 @@ async function importEmbeddedSkills(projectRoot, skillsDir, fromTool, results, n
       if (sourceContent === null) continue;
       const destinationPath = join(destinationSkillDir, relativePath);
       await mkdirp(dirname(destinationPath));
-      await writeFileAtomic(destinationPath, normalize2(sourceContent, sourcePath, destinationPath));
+      await writeFileAtomic(destinationPath, normalize(sourceContent, sourcePath, destinationPath));
       results.push({
         fromTool,
         fromPath: sourcePath,
@@ -2010,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)) {
@@ -2517,7 +2545,7 @@ var init_import_descriptor = __esm({
     ];
   }
 });
-async function runSingleFile(spec, sources, projectRoot, fromTool, normalize2) {
+async function runSingleFile(spec, sources, projectRoot, fromTool, normalize) {
   if (!spec.canonicalRootFilename) {
     throw new Error(`singleFile spec for ${spec.feature} must set canonicalRootFilename`);
   }
@@ -2528,7 +2556,7 @@ async function runSingleFile(spec, sources, projectRoot, fromTool, normalize2) {
     if (content === null) continue;
     await mkdirp(destDir);
     const destPath = join(destDir, spec.canonicalRootFilename);
-    const normalizeTo = (destinationFile) => normalize2(content, srcPath, destinationFile);
+    const normalizeTo = (destinationFile) => normalize(content, srcPath, destinationFile);
     if (spec.map) {
       let mapping;
       try {
@@ -2571,7 +2599,7 @@ async function runSingleFile(spec, sources, projectRoot, fromTool, normalize2) {
   }
   return [];
 }
-async function runDirectory(spec, sources, projectRoot, fromTool, normalize2) {
+async function runDirectory(spec, sources, projectRoot, fromTool, normalize) {
   const mapper = resolveMapper(spec);
   const destDir = join(projectRoot, spec.canonicalDir);
   const results = [];
@@ -2582,7 +2610,7 @@ async function runDirectory(spec, sources, projectRoot, fromTool, normalize2) {
       destDir,
       extensions: [...spec.extensions ?? [".md"]],
       fromTool,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ srcPath, relativePath, content, normalizeTo }) => {
         if (isPreservedBoilerplate(basename(srcPath))) return null;
         let mapping;
@@ -2687,28 +2715,28 @@ async function runMcpJson(spec, sources, projectRoot, fromTool) {
   }
   return [];
 }
-function dispatchSpec(spec, sources, projectRoot, fromTool, normalize2) {
+function dispatchSpec(spec, sources, projectRoot, fromTool, normalize) {
   switch (spec.mode) {
     case "singleFile":
-      return runSingleFile(spec, sources, projectRoot, fromTool, normalize2);
+      return runSingleFile(spec, sources, projectRoot, fromTool, normalize);
     case "directory":
-      return runDirectory(spec, sources, projectRoot, fromTool, normalize2);
+      return runDirectory(spec, sources, projectRoot, fromTool, normalize);
     case "flatFile":
       return runFlatFile(spec, sources, projectRoot, fromTool);
     case "mcpJson":
       return runMcpJson(spec, sources, projectRoot, fromTool);
   }
 }
-async function runSpec(spec, scope, projectRoot, fromTool, normalize2) {
+async function runSpec(spec, scope, projectRoot, fromTool, normalize) {
   const primary = resolveScopedSources(spec.source, scope);
   const fallback = resolveScopedSources(spec.fallbacks, scope);
   if (primary.length === 0 && fallback.length === 0) return [];
   if (primary.length > 0) {
-    const results = await dispatchSpec(spec, primary, projectRoot, fromTool, normalize2);
+    const results = await dispatchSpec(spec, primary, projectRoot, fromTool, normalize);
     if (results.length > 0) return results;
   }
   if (fallback.length > 0) {
-    return dispatchSpec(spec, fallback, projectRoot, fromTool, normalize2);
+    return dispatchSpec(spec, fallback, projectRoot, fromTool, normalize);
   }
   return [];
 }
@@ -2721,11 +2749,11 @@ function specsForFeature(importer, feature) {
 async function runDescriptorImport(descriptor31, projectRoot, scope, options) {
   const importer = descriptor31.importer;
   if (!importer) return [];
-  const normalize2 = options?.normalize ?? await createImportReferenceNormalizer(descriptor31.id, projectRoot, scope);
+  const normalize = options?.normalize ?? await createImportReferenceNormalizer(descriptor31.id, projectRoot, scope);
   const results = [];
   for (const feature of IMPORT_FEATURE_ORDER) {
     for (const spec of specsForFeature(importer, feature)) {
-      results.push(...await runSpec(spec, scope, projectRoot, descriptor31.id, normalize2));
+      results.push(...await runSpec(spec, scope, projectRoot, descriptor31.id, normalize));
     }
   }
   return results;
@@ -2749,10 +2777,10 @@ var init_descriptor_import_runner = __esm({
 async function importFromAider(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(AIDER_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(AIDER_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? AIDER_GLOBAL_SKILLS_DIR : AIDER_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, AIDER_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, AIDER_TARGET, results, normalize);
   return results;
 }
 var init_importer = __esm({
@@ -3339,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";
@@ -4991,10 +5019,10 @@ var init_mcp_import = __esm({
 async function importFromAmp(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(AMP_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor3, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(AMP_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor3, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? AMP_GLOBAL_SKILLS_DIR : AMP_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, AMP_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, AMP_TARGET, results, normalize);
   const mcpFile = scope === "global" ? AMP_GLOBAL_MCP_FILE : AMP_MCP_FILE;
   await importAmpMcp(projectRoot, mcpFile, results);
   return results;
@@ -5206,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 [
           {
@@ -5342,7 +5371,7 @@ var init_embedded_rules = __esm({
     init_import_metadata();
   }
 });
-async function importRootRule(projectRoot, results, normalize2, scope) {
+async function importRootRule(projectRoot, results, normalize, scope) {
   const primary = scope === "global" ? ANTIGRAVITY_GLOBAL_ROOT : ANTIGRAVITY_RULES_ROOT;
   const candidates = scope === "project" ? [primary, ANTIGRAVITY_RULES_ROOT_LEGACY] : [primary];
   for (const rel2 of candidates) {
@@ -5356,10 +5385,10 @@ async function importRootRule(projectRoot, results, normalize2, scope) {
       rulesDir: ANTIGRAVITY_CANONICAL_RULES_DIR,
       sourcePath: srcPath,
       fromTool: ANTIGRAVITY_TARGET,
-      normalize: normalize2
+      normalize
     });
     results.push(...split.results);
-    const { body } = parseFrontmatter(normalize2(split.rootContent, srcPath, destPath));
+    const { body } = parseFrontmatter(normalize(split.rootContent, srcPath, destPath));
     const output = await serializeImportedRuleWithFallback(destPath, { root: true }, body);
     await mkdirp(join(projectRoot, ANTIGRAVITY_CANONICAL_RULES_DIR));
     await writeFileAtomic(destPath, output);
@@ -5375,15 +5404,15 @@ async function importRootRule(projectRoot, results, normalize2, scope) {
 async function importFromAntigravity(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(ANTIGRAVITY_TARGET, projectRoot, scope);
-  await importRootRule(projectRoot, results, normalize2, scope);
-  results.push(...await runDescriptorImport(descriptor4, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(ANTIGRAVITY_TARGET, projectRoot, scope);
+  await importRootRule(projectRoot, results, normalize, scope);
+  results.push(...await runDescriptorImport(descriptor4, projectRoot, scope, { normalize }));
   await importEmbeddedSkills(
     projectRoot,
     scope === "global" ? ANTIGRAVITY_GLOBAL_SKILLS_DIR : ANTIGRAVITY_SKILLS_DIR,
     ANTIGRAVITY_TARGET,
     results,
-    normalize2
+    normalize
   );
   return results;
 }
@@ -5799,7 +5828,7 @@ function canonicalRuleMeta(frontmatter, isRoot) {
   }
   return meta;
 }
-async function importRules(projectRoot, results, normalize2, scope) {
+async function importRules(projectRoot, results, normalize, scope) {
   const rulesDir = scope === "global" ? AUGMENT_CODE_GLOBAL_RULES_DIR : AUGMENT_CODE_RULES_DIR;
   const destDir = join(projectRoot, AUGMENT_CODE_CANONICAL_RULES_DIR);
   results.push(
@@ -5808,7 +5837,7 @@ async function importRules(projectRoot, results, normalize2, scope) {
       destDir,
       extensions: [".md"],
       fromTool: AUGMENT_CODE_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ relativePath, normalizeTo }) => {
         const isRoot = relativePath === "_root.md" || basename(relativePath) === "_root.md";
         const destPath = join(destDir, relativePath);
@@ -5827,7 +5856,7 @@ async function importRules(projectRoot, results, normalize2, scope) {
     })
   );
 }
-async function importCommands(projectRoot, results, normalize2, scope) {
+async function importCommands(projectRoot, results, normalize, scope) {
   const commandsDir = scope === "global" ? AUGMENT_CODE_GLOBAL_COMMANDS_DIR : AUGMENT_CODE_COMMANDS_DIR;
   const destDir = join(projectRoot, ".agentsmesh/commands");
   results.push(
@@ -5836,7 +5865,7 @@ async function importCommands(projectRoot, results, normalize2, scope) {
       destDir,
       extensions: [".md"],
       fromTool: AUGMENT_CODE_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ relativePath, normalizeTo }) => {
         const name = basename(relativePath, ".md");
         const destPath = join(destDir, `${name}.md`);
@@ -5859,11 +5888,11 @@ async function importCommands(projectRoot, results, normalize2, scope) {
 async function importFromAugmentCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(AUGMENT_CODE_TARGET, projectRoot, scope);
-  await importRules(projectRoot, results, normalize2, scope);
-  await importCommands(projectRoot, results, normalize2, scope);
+  const normalize = await createImportReferenceNormalizer(AUGMENT_CODE_TARGET, projectRoot, scope);
+  await importRules(projectRoot, results, normalize, scope);
+  await importCommands(projectRoot, results, normalize, scope);
   const skillsDir = scope === "global" ? AUGMENT_CODE_GLOBAL_SKILLS_DIR : AUGMENT_CODE_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, AUGMENT_CODE_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, AUGMENT_CODE_TARGET, results, normalize);
   const settingsFile = scope === "global" ? AUGMENT_CODE_GLOBAL_SETTINGS_FILE : AUGMENT_CODE_SETTINGS_FILE;
   await importAugmentSettings(projectRoot, settingsFile, results);
   if (scope === "project") {
@@ -5958,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;
@@ -6092,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 }];
       },
@@ -6481,7 +6510,7 @@ var init_settings_helpers2 = __esm({
     init_constants7();
   }
 });
-async function importClaudeSkills(projectRoot, results, normalize2) {
+async function importClaudeSkills(projectRoot, results, normalize) {
   const skillsBaseDir = join(projectRoot, CLAUDE_SKILLS_DIR);
   const destBase = join(projectRoot, CLAUDE_CANONICAL_SKILLS_DIR);
   const allFiles = await readDirRecursive(skillsBaseDir);
@@ -6492,7 +6521,7 @@ async function importClaudeSkills(projectRoot, results, normalize2) {
     const destSkillDir = join(destBase, skillName);
     const skillMdContent = await readFileSafe(skillMdPath);
     if (skillMdContent === null) continue;
-    const normalizedSkillMd = normalize2(
+    const normalizedSkillMd = normalize(
       skillMdContent,
       skillMdPath,
       join(destSkillDir, "SKILL.md")
@@ -6510,7 +6539,7 @@ async function importClaudeSkills(projectRoot, results, normalize2) {
       const relPath = relative(skillDir, filePath);
       const destPath = join(destSkillDir, relPath);
       await mkdirp(dirname(destPath));
-      const normalized = normalize2(fileContent, filePath, destPath);
+      const normalized = normalize(fileContent, filePath, destPath);
       await writeFileAtomic(
         destPath,
         relPath === "SKILL.md" ? await serializeImportedSkillWithFallback(
@@ -6542,9 +6571,9 @@ var init_importer_skills = __esm({
 async function importFromClaudeCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer("claude-code", projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor6, projectRoot, scope, { normalize: normalize2 }));
-  await importClaudeSkills(projectRoot, results, normalize2);
+  const normalize = await createImportReferenceNormalizer("claude-code", projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor6, projectRoot, scope, { normalize }));
+  await importClaudeSkills(projectRoot, results, normalize);
   await importClaudeHooksJson(projectRoot, results);
   await importSettings(projectRoot, results);
   return results;
@@ -6667,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) {
@@ -6682,7 +6714,7 @@ var init_claude_code2 = __esm({
       }
     };
     globalLayout6 = {
-      rootInstructionPath: CLAUDE_ROOT,
+      rootInstructionPath: CLAUDE_NESTED_ROOT,
       skillDir: ".claude/skills",
       renderPrimaryRootInstruction: renderClaudeGlobalPrimaryInstructions,
       managedOutputs: {
@@ -6695,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,
@@ -6703,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;
       },
@@ -6766,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
@@ -6815,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" } }
+        ]
+      }
     };
   }
 });
@@ -7004,7 +7054,7 @@ var init_importer_mappers = __esm({
     init_constants8();
   }
 });
-async function importClineRules(projectRoot, results, normalize2) {
+async function importClineRules(projectRoot, results, normalize) {
   const destRulesDir = join(projectRoot, CLINE_CANONICAL_RULES_DIR);
   const clineRulesPath = join(projectRoot, CLINE_RULES_DIR);
   const clineRulesRaw = join(projectRoot, CLINE_RULES_DIR);
@@ -7020,7 +7070,7 @@ async function importClineRules(projectRoot, results, normalize2) {
       await mkdirp(destRulesDir);
       const destPath = join(destRulesDir, "_root.md");
       const { frontmatter, body } = parseFrontmatter(
-        normalize2(flatContent, clineRulesRaw, destPath)
+        normalize(flatContent, clineRulesRaw, destPath)
       );
       const hasRoot = frontmatter.root === true;
       const outFm = hasRoot ? frontmatter : { ...frontmatter, root: true };
@@ -7046,7 +7096,7 @@ async function importClineRules(projectRoot, results, normalize2) {
       await mkdirp(destRulesDir);
       const destPath = join(destRulesDir, "_root.md");
       const { frontmatter, body } = parseFrontmatter(
-        normalize2(agentsMdContent, agentsMdPath, destPath)
+        normalize(agentsMdContent, agentsMdPath, destPath)
       );
       const hasRoot = frontmatter.root === true;
       const outFm = hasRoot ? frontmatter : { ...frontmatter, root: true };
@@ -7068,7 +7118,7 @@ async function importClineRules(projectRoot, results, normalize2) {
           rootSourcePath = first;
           await mkdirp(destRulesDir);
           const destPath = join(destRulesDir, "_root.md");
-          const { frontmatter, body } = parseFrontmatter(normalize2(fc, first, destPath));
+          const { frontmatter, body } = parseFrontmatter(normalize(fc, first, destPath));
           const hasRoot = frontmatter.root === true;
           const outFm = hasRoot ? frontmatter : { ...frontmatter, root: true };
           const outContent = await serializeImportedRuleWithFallback(destPath, outFm, body);
@@ -7086,7 +7136,7 @@ async function importClineRules(projectRoot, results, normalize2) {
     rootSourcePath = rootPath;
     await mkdirp(destRulesDir);
     const destPath = join(destRulesDir, "_root.md");
-    const { frontmatter, body } = parseFrontmatter(normalize2(rootContent, rootPath, destPath));
+    const { frontmatter, body } = parseFrontmatter(normalize(rootContent, rootPath, destPath));
     const hasRoot = frontmatter.root === true;
     const outFm = hasRoot ? frontmatter : { ...frontmatter, root: true };
     const outContent = await serializeImportedRuleWithFallback(destPath, outFm, body);
@@ -7104,7 +7154,7 @@ async function importClineRules(projectRoot, results, normalize2) {
       destDir: destRulesDir,
       extensions: [".md"],
       fromTool: "cline",
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ srcPath, relativePath, normalizeTo }) => {
         if (srcPath === rootSourcePath) return null;
         return mapClineRuleFile(relativePath, destRulesDir, normalizeTo);
@@ -7391,12 +7441,12 @@ var init_skill_import_pipeline = __esm({
 });
 
 // src/targets/cline/skills-adapter.ts
-async function importClineSkills(projectRoot, results, normalize2, skillsRelDir = CLINE_SKILLS_DIR) {
+async function importClineSkills(projectRoot, results, normalize, skillsRelDir = CLINE_SKILLS_DIR) {
   const options = {
     projectRoot,
     destCanonicalSkillsDir: CLINE_CANONICAL_SKILLS_DIR,
     targetName: "cline",
-    normalize: normalize2,
+    normalize,
     results
   };
   await importSkillsDirectory([skillsRelDir], options, [
@@ -7450,8 +7500,8 @@ var init_hook_importer = __esm({
 });
 async function importFromCline(projectRoot) {
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(CLINE_TARGET, projectRoot);
-  const clineRulesIsFile = await importClineRules(projectRoot, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(CLINE_TARGET, projectRoot);
+  const clineRulesIsFile = await importClineRules(projectRoot, results, normalize);
   const ignorePath = join(projectRoot, CLINE_IGNORE);
   const ignoreContent = await readFileSafe(ignorePath);
   if (ignoreContent !== null && ignoreContent.trim()) {
@@ -7482,12 +7532,12 @@ async function importFromCline(projectRoot) {
         destDir: destCommandsDir,
         extensions: [".md"],
         fromTool: "cline",
-        normalize: normalize2,
+        normalize,
         mapEntry: ({ relativePath, normalizeTo }) => mapClineWorkflowFile(relativePath, destCommandsDir, normalizeTo)
       })
     );
   }
-  await importClineSkills(projectRoot, results, normalize2);
+  await importClineSkills(projectRoot, results, normalize);
   await importClineHooks(projectRoot, results);
   return results;
 }
@@ -7694,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 }
     };
   }
@@ -8070,12 +8130,12 @@ var init_mcp_helpers = __esm({
 });
 
 // src/targets/codex-cli/skills-adapter.ts
-async function importSkills(projectRoot, results, normalize2) {
+async function importSkills(projectRoot, results, normalize) {
   const options = {
     projectRoot,
     destCanonicalSkillsDir: CODEX_CANONICAL_SKILLS_DIR,
     targetName: CODEX_TARGET,
-    normalize: normalize2,
+    normalize,
     results
   };
   await importSkillsDirectory([CODEX_SKILLS_DIR, CODEX_SKILLS_FALLBACK_DIR], options, [
@@ -8089,7 +8149,7 @@ var init_skills_adapter2 = __esm({
     init_constants28();
   }
 });
-async function importCodexAgentsFromToml(projectRoot, results, normalize2) {
+async function importCodexAgentsFromToml(projectRoot, results, normalize) {
   const agentsPath = join(projectRoot, CODEX_AGENTS_DIR);
   const agentsDestDir = join(projectRoot, CODEX_CANONICAL_AGENTS_DIR);
   try {
@@ -8109,7 +8169,7 @@ async function importCodexAgentsFromToml(projectRoot, results, normalize2) {
       const mcpServers = Array.isArray(parsed.mcp_servers) ? parsed.mcp_servers.filter((s) => typeof s === "string") : [];
       await mkdirp(agentsDestDir);
       const destPath = join(agentsDestDir, `${name}.md`);
-      const normalizedBody = normalize2(body, srcPath, destPath);
+      const normalizedBody = normalize(body, srcPath, destPath);
       const agent = {
         name,
         description,
@@ -8185,7 +8245,7 @@ var init_codex_rules_embed = __esm({
     init_constants28();
   }
 });
-async function importCodexNonRootRuleFiles(projectRoot, destDir, normalize2) {
+async function importCodexNonRootRuleFiles(projectRoot, destDir, normalize) {
   const results = [];
   const codexRulesPath = join(projectRoot, CODEX_RULES_DIR);
   try {
@@ -8196,7 +8256,7 @@ async function importCodexNonRootRuleFiles(projectRoot, destDir, normalize2) {
       if (!content) continue;
       const relativePath = relative(codexRulesPath, srcPath).replace(/\\/g, "/");
       const destPath = join(destDir, relativePath);
-      const { frontmatter, body } = parseFrontmatter(normalize2(content, srcPath, destPath));
+      const { frontmatter, body } = parseFrontmatter(normalize(content, srcPath, destPath));
       await mkdirp(destDir);
       const outFm = frontmatter.root === true ? frontmatter : { ...frontmatter, root: false };
       const outContent = await serializeImportedRuleWithFallback(destPath, outFm, body);
@@ -8224,7 +8284,7 @@ async function importCodexNonRootRuleFiles(projectRoot, destDir, normalize2) {
             globs: embedded.meta.globs,
             root: false
           },
-          normalize2(embedded.body, srcPath, destPath)
+          normalize(embedded.body, srcPath, destPath)
         );
         await writeFileAtomic(destPath, outContent);
       } else {
@@ -8236,7 +8296,7 @@ async function importCodexNonRootRuleFiles(projectRoot, destDir, normalize2) {
             globs: [],
             codex_emit: "execution"
           },
-          normalize2(raw.trim(), srcPath, destPath)
+          normalize(raw.trim(), srcPath, destPath)
         );
         await writeFileAtomic(destPath, outContent);
       }
@@ -8260,7 +8320,7 @@ var init_import_codex_non_root_rules = __esm({
     init_codex_rules_embed();
   }
 });
-async function importCodexRules(projectRoot, results, normalize2, normalizeWindsurf, layoutScope) {
+async function importCodexRules(projectRoot, results, normalize, normalizeWindsurf, layoutScope) {
   const codexPath = join(projectRoot, CODEX_MD);
   const agentsPath = join(projectRoot, AGENTS_MD);
   const globalOverridePath = join(projectRoot, CODEX_GLOBAL_AGENTS_OVERRIDE_MD);
@@ -8282,14 +8342,14 @@ async function importCodexRules(projectRoot, results, normalize2, normalizeWinds
       rulesDir: CODEX_CANONICAL_RULES_DIR,
       sourcePath,
       fromTool: "codex-cli",
-      normalize: normalize2
+      normalize
     });
     results.push(...split.results);
-    const normalizedContent = sourcePath === agentsPath || sourcePath === globalAgentsPath || sourcePath === globalOverridePath ? normalize2(
+    const normalizedContent = sourcePath === agentsPath || sourcePath === globalAgentsPath || sourcePath === globalOverridePath ? normalize(
       normalizeWindsurf(split.rootContent, sourcePath, destPath),
       sourcePath,
       destPath
-    ) : normalize2(split.rootContent, sourcePath, destPath);
+    ) : normalize(split.rootContent, sourcePath, destPath);
     const { frontmatter, body } = parseFrontmatter(normalizedContent);
     const outFm = frontmatter.root === true ? frontmatter : { ...frontmatter, root: true };
     const outContent = await serializeImportedRuleWithFallback(destPath, outFm, body);
@@ -8301,8 +8361,8 @@ async function importCodexRules(projectRoot, results, normalize2, normalizeWinds
       feature: "rules"
     });
   }
-  await importInstructionMirrors(projectRoot, destDir, results, normalize2);
-  results.push(...await importCodexNonRootRuleFiles(projectRoot, destDir, normalize2));
+  await importInstructionMirrors(projectRoot, destDir, results, normalize);
+  results.push(...await importCodexNonRootRuleFiles(projectRoot, destDir, normalize));
   if (layoutScope !== "global") {
     results.push(
       ...await importFileDirectory({
@@ -8310,7 +8370,7 @@ async function importCodexRules(projectRoot, results, normalize2, normalizeWinds
         destDir,
         extensions: ["AGENTS.md", "AGENTS.override.md"],
         fromTool: "codex-cli",
-        normalize: normalize2,
+        normalize,
         mapEntry: async ({ srcPath, normalizeTo }) => {
           const relDir = relative(projectRoot, dirname(srcPath)).replace(/\\/g, "/");
           const fileName = basename(srcPath);
@@ -8344,7 +8404,7 @@ async function importCodexRules(projectRoot, results, normalize2, normalizeWinds
     );
   }
 }
-async function importInstructionMirrors(projectRoot, destDir, results, normalize2) {
+async function importInstructionMirrors(projectRoot, destDir, results, normalize) {
   try {
     const files = await readDirRecursive(join(projectRoot, CODEX_INSTRUCTIONS_DIR));
     const instructionFiles = files.filter((file) => file.endsWith(".md"));
@@ -8355,7 +8415,7 @@ async function importInstructionMirrors(projectRoot, destDir, results, normalize
       const content = await readFileSafe(srcPath);
       if (!content) continue;
       const destPath = join(destDir, relativePath);
-      const { frontmatter, body } = parseFrontmatter(normalize2(content, srcPath, destPath));
+      const { frontmatter, body } = parseFrontmatter(normalize(content, srcPath, destPath));
       await mkdirp(destDir);
       const outFm = frontmatter.root === true ? frontmatter : { ...frontmatter, root: false };
       const outContent = await serializeImportedRuleWithFallback(destPath, outFm, body);
@@ -8388,15 +8448,15 @@ var init_importer_rules2 = __esm({
 async function importFromCodex(projectRoot, options) {
   const layoutScope = options?.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(CODEX_TARGET, projectRoot, layoutScope);
+  const normalize = await createImportReferenceNormalizer(CODEX_TARGET, projectRoot, layoutScope);
   const normalizeWindsurf = await createImportReferenceNormalizer(
     "windsurf",
     projectRoot,
     layoutScope
   );
-  await importCodexRules(projectRoot, results, normalize2, normalizeWindsurf, layoutScope);
-  await importSkills(projectRoot, results, normalize2);
-  await importCodexAgentsFromToml(projectRoot, results, normalize2);
+  await importCodexRules(projectRoot, results, normalize, normalizeWindsurf, layoutScope);
+  await importSkills(projectRoot, results, normalize);
+  await importCodexAgentsFromToml(projectRoot, results, normalize);
   await importMcp(projectRoot, results);
   return results;
 }
@@ -8612,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 }
     };
@@ -8769,9 +8834,9 @@ async function importMcp2(projectRoot, results) {
 }
 async function importFromContinue(projectRoot) {
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(CONTINUE_TARGET, projectRoot);
-  results.push(...await runDescriptorImport(descriptor9, projectRoot, "project", { normalize: normalize2 }));
-  await importEmbeddedSkills(projectRoot, CONTINUE_SKILLS_DIR, CONTINUE_TARGET, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(CONTINUE_TARGET, projectRoot);
+  results.push(...await runDescriptorImport(descriptor9, projectRoot, "project", { normalize }));
+  await importEmbeddedSkills(projectRoot, CONTINUE_SKILLS_DIR, CONTINUE_TARGET, results, normalize);
   await importMcp2(projectRoot, results);
   return results;
 }
@@ -9115,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 }
     };
   }
@@ -9436,14 +9516,14 @@ var init_hook_parser = __esm({
     init_constants29();
   }
 });
-async function importSkills2(projectRoot, results, normalize2, skillsDirRel = COPILOT_SKILLS_DIR) {
+async function importSkills2(projectRoot, results, normalize, skillsDirRel = COPILOT_SKILLS_DIR) {
   const skillsDir = join(projectRoot, skillsDirRel);
   const directorySkills = await findDirectorySkills(skillsDir);
   const options = {
     projectRoot,
     destCanonicalSkillsDir: COPILOT_CANONICAL_SKILLS_DIR,
     targetName: COPILOT_TARGET,
-    normalize: normalize2,
+    normalize,
     results
   };
   for (const [skillName, skillDir] of directorySkills) {
@@ -9461,12 +9541,12 @@ var init_skills_adapter3 = __esm({
 async function importFromCopilot(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(COPILOT_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor10, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(COPILOT_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor10, projectRoot, scope, { normalize }));
   await importSkills2(
     projectRoot,
     results,
-    normalize2,
+    normalize,
     scope === "global" ? COPILOT_GLOBAL_SKILLS_DIR : COPILOT_SKILLS_DIR
   );
   if (scope === "project") await importHooks(projectRoot, results);
@@ -9482,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];
@@ -9771,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();
@@ -9985,7 +10140,8 @@ var init_copilot2 = __esm({
         ".github/skills",
         ".github/agents",
         ".github/hooks"
-      ]
+      ],
+      nativeInstall: { inferPick: inferCopilotPickFromPath }
     };
   }
 });
@@ -10087,10 +10243,10 @@ var init_generator12 = __esm({
 async function importFromCrush(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(CRUSH_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor11, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(CRUSH_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor11, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? CRUSH_GLOBAL_SKILLS_DIR : CRUSH_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, CRUSH_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, CRUSH_TARGET, results, normalize);
   await importCrushConfigJson(projectRoot, results);
   return results;
 }
@@ -10775,7 +10931,7 @@ var init_import_root_helpers = __esm({
     init_constants11();
   }
 });
-async function importCursorRules(projectRoot, results, normalize2) {
+async function importCursorRules(projectRoot, results, normalize) {
   const destDir = join(projectRoot, CURSOR_CANONICAL_RULES_DIR);
   let rootWritten = false;
   const rulesDir = join(projectRoot, CURSOR_RULES_DIR);
@@ -10785,7 +10941,7 @@ async function importCursorRules(projectRoot, results, normalize2) {
       destDir,
       extensions: [".mdc"],
       fromTool: "cursor",
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ srcPath, relativePath, normalizeTo }) => {
         if (rootWritten) {
           const raw = await readFileSafe(srcPath);
@@ -10809,7 +10965,7 @@ async function importCursorRules(projectRoot, results, normalize2) {
         results,
         sourcePath: agentsPath,
         content: agentsContent,
-        normalize: normalize2
+        normalize
       });
     }
   }
@@ -10822,7 +10978,7 @@ async function importCursorRules(projectRoot, results, normalize2) {
         results,
         sourcePath: cursorRulesPath,
         content: cursorRulesContent,
-        normalize: normalize2
+        normalize
       });
     }
   }
@@ -10967,14 +11123,14 @@ var init_settings_helpers3 = __esm({
     init_constants11();
   }
 });
-async function importSkills3(projectRoot, results, normalize2, skillsRelDir = CURSOR_SKILLS_DIR) {
+async function importSkills3(projectRoot, results, normalize, skillsRelDir = CURSOR_SKILLS_DIR) {
   const skillsDir = join(projectRoot, skillsRelDir);
   const directorySkills = await findDirectorySkills(skillsDir);
   const options = {
     projectRoot,
     destCanonicalSkillsDir: CURSOR_CANONICAL_SKILLS_DIR,
     targetName: "cursor",
-    normalize: normalize2,
+    normalize,
     results
   };
   for (const [skillName, skillDir] of directorySkills) {
@@ -11015,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;
@@ -11026,7 +11182,7 @@ async function hasGlobalCursorArtifacts(projectRoot) {
   if (commandFiles.some((f) => f.endsWith(".md"))) return true;
   return false;
 }
-async function importGlobalCursorRulesFromDir(projectRoot, results, normalize2) {
+async function importGlobalCursorRulesFromDir(projectRoot, results, normalize) {
   const destDir = join(projectRoot, CURSOR_CANONICAL_RULES_DIR);
   let rootWritten = false;
   const rulesDir = join(projectRoot, CURSOR_RULES_DIR);
@@ -11035,7 +11191,7 @@ async function importGlobalCursorRulesFromDir(projectRoot, results, normalize2)
     destDir,
     extensions: [".mdc"],
     fromTool: CURSOR_TARGET2,
-    normalize: normalize2,
+    normalize,
     mapEntry: async ({ srcPath, relativePath, normalizeTo }) => {
       if (rootWritten) {
         const raw = await readFileSafe(srcPath);
@@ -11052,7 +11208,7 @@ async function importGlobalCursorRulesFromDir(projectRoot, results, normalize2)
   results.push(...batch);
   return rootWritten;
 }
-async function importGlobalUserRules(projectRoot, results, normalize2) {
+async function importGlobalUserRules(projectRoot, results, normalize) {
   const srcPath = join(projectRoot, CURSOR_GLOBAL_USER_RULES);
   const raw = await readFileSafe(srcPath);
   if (raw === null || raw.trim() === "") return false;
@@ -11061,10 +11217,10 @@ async function importGlobalUserRules(projectRoot, results, normalize2) {
     results,
     sourcePath: srcPath,
     content: raw.trim(),
-    normalize: normalize2
+    normalize
   });
 }
-async function importGlobalDotCursorAgents(projectRoot, results, normalize2) {
+async function importGlobalDotCursorAgents(projectRoot, results, normalize) {
   const srcPath = join(projectRoot, CURSOR_DOT_CURSOR_AGENTS);
   const raw = await readFileSafe(srcPath);
   if (raw === null || raw.trim() === "") return false;
@@ -11073,7 +11229,7 @@ async function importGlobalDotCursorAgents(projectRoot, results, normalize2) {
     results,
     sourcePath: srcPath,
     content: raw.trim(),
-    normalize: normalize2
+    normalize
   });
 }
 async function importGlobalMcp(projectRoot, results) {
@@ -11097,7 +11253,7 @@ async function importGlobalMcp(projectRoot, results) {
     feature: "mcp"
   });
 }
-async function importGlobalAgents(projectRoot, results, normalize2) {
+async function importGlobalAgents(projectRoot, results, normalize) {
   const agentsDir = join(projectRoot, CURSOR_AGENTS_DIR);
   const destDir = join(projectRoot, CURSOR_CANONICAL_AGENTS_DIR);
   results.push(
@@ -11106,12 +11262,12 @@ async function importGlobalAgents(projectRoot, results, normalize2) {
       destDir,
       extensions: [".md"],
       fromTool: CURSOR_TARGET2,
-      normalize: normalize2,
+      normalize,
       mapEntry: ({ relativePath, normalizeTo }) => mapCursorAgentFile(relativePath, destDir, normalizeTo)
     })
   );
 }
-async function importGlobalCommands(projectRoot, results, normalize2) {
+async function importGlobalCommands(projectRoot, results, normalize) {
   const commandsDir = join(projectRoot, CURSOR_COMMANDS_DIR);
   const destDir = join(projectRoot, CURSOR_CANONICAL_COMMANDS_DIR);
   results.push(
@@ -11120,7 +11276,7 @@ async function importGlobalCommands(projectRoot, results, normalize2) {
       destDir,
       extensions: [".md"],
       fromTool: CURSOR_TARGET2,
-      normalize: normalize2,
+      normalize,
       mapEntry: ({ relativePath, normalizeTo }) => mapCursorCommandFile(relativePath, destDir, normalizeTo)
     })
   );
@@ -11142,14 +11298,14 @@ var init_import_global_exports_helpers = __esm({
 async function importFromCursorGlobalExports(projectRoot) {
   if (!await hasGlobalCursorArtifacts(projectRoot)) return [];
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(CURSOR_TARGET2, projectRoot, "global");
-  let rootWritten = await importGlobalCursorRulesFromDir(projectRoot, results, normalize2);
-  if (!rootWritten) rootWritten = await importGlobalUserRules(projectRoot, results, normalize2);
-  if (!rootWritten) await importGlobalDotCursorAgents(projectRoot, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(CURSOR_TARGET2, projectRoot, "global");
+  let rootWritten = await importGlobalCursorRulesFromDir(projectRoot, results, normalize);
+  if (!rootWritten) rootWritten = await importGlobalUserRules(projectRoot, results, normalize);
+  if (!rootWritten) await importGlobalDotCursorAgents(projectRoot, results, normalize);
   await importGlobalMcp(projectRoot, results);
-  await importSkills3(projectRoot, results, normalize2, CURSOR_SKILLS_DIR);
-  await importGlobalAgents(projectRoot, results, normalize2);
-  await importGlobalCommands(projectRoot, results, normalize2);
+  await importSkills3(projectRoot, results, normalize, CURSOR_SKILLS_DIR);
+  await importGlobalAgents(projectRoot, results, normalize);
+  await importGlobalCommands(projectRoot, results, normalize);
   await importSettings2(projectRoot, results);
   await importIgnore(projectRoot, results);
   return results;
@@ -11188,10 +11344,10 @@ async function importFromCursor(projectRoot, options = {}) {
     return importFromCursorGlobalExports(projectRoot);
   }
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer("cursor", projectRoot);
-  await importCursorRules(projectRoot, results, normalize2);
-  results.push(...await runDescriptorImport(descriptor12, projectRoot, "project", { normalize: normalize2 }));
-  await importSkills3(projectRoot, results, normalize2);
+  const normalize = await createImportReferenceNormalizer("cursor", projectRoot);
+  await importCursorRules(projectRoot, results, normalize);
+  results.push(...await runDescriptorImport(descriptor12, projectRoot, "project", { normalize }));
+  await importSkills3(projectRoot, results, normalize);
   await importMcp3(projectRoot, results);
   await importSettings2(projectRoot, results);
   await importIgnore(projectRoot, results);
@@ -11498,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
     };
   }
@@ -11549,14 +11722,14 @@ var init_generator15 = __esm({
 async function importFromDeepagentsCli(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(
+  const normalize = await createImportReferenceNormalizer(
     DEEPAGENTS_CLI_TARGET,
     projectRoot,
     scope
   );
-  results.push(...await runDescriptorImport(descriptor13, projectRoot, scope, { normalize: normalize2 }));
+  results.push(...await runDescriptorImport(descriptor13, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? DEEPAGENTS_CLI_GLOBAL_SKILLS_DIR : DEEPAGENTS_CLI_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, DEEPAGENTS_CLI_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, DEEPAGENTS_CLI_TARGET, results, normalize);
   return results;
 }
 var init_importer13 = __esm({
@@ -11883,10 +12056,10 @@ var init_mcp_import2 = __esm({
 async function importFromFactoryDroid(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(FACTORY_DROID_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor14, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(FACTORY_DROID_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor14, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? FACTORY_DROID_GLOBAL_SKILLS_DIR : FACTORY_DROID_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, FACTORY_DROID_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, FACTORY_DROID_TARGET, results, normalize);
   const mcpFile = scope === "global" ? FACTORY_DROID_GLOBAL_MCP_FILE : FACTORY_DROID_MCP_FILE;
   await importFactoryDroidMcp(projectRoot, mcpFile, results);
   return results;
@@ -12259,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 [];
@@ -12700,7 +12873,7 @@ var init_importer_strip = __esm({
   "src/targets/gemini-cli/importer-strip.ts"() {
   }
 });
-async function importGeminiSkillsAndAgents(projectRoot, results, normalize2) {
+async function importGeminiSkillsAndAgents(projectRoot, results, normalize) {
   const geminiSkillsPath = join(projectRoot, GEMINI_SKILLS_DIR);
   const skillDirs = await readDirRecursive(geminiSkillsPath);
   const skillMdFiles = skillDirs.filter((f) => basename(f) === "SKILL.md");
@@ -12716,7 +12889,7 @@ async function importGeminiSkillsAndAgents(projectRoot, results, normalize2) {
       const agentPath = join(agentsDir, `${projectedAgent.name}.md`);
       await writeFileAtomic(
         agentPath,
-        serializeImportedAgent(projectedAgent, normalize2(rawParsed.body, srcPath, agentPath))
+        serializeImportedAgent(projectedAgent, normalize(rawParsed.body, srcPath, agentPath))
       );
       results.push({
         fromTool: "gemini-cli",
@@ -12727,7 +12900,7 @@ async function importGeminiSkillsAndAgents(projectRoot, results, normalize2) {
       continue;
     }
     const destPath = join(projectRoot, GEMINI_CANONICAL_SKILLS_DIR, skillName, "SKILL.md");
-    const normalized = normalize2(content, srcPath, destPath);
+    const normalized = normalize(content, srcPath, destPath);
     const skillDir = join(projectRoot, GEMINI_CANONICAL_SKILLS_DIR, skillName);
     await mkdirp(skillDir);
     const { frontmatter, body } = parseFrontmatter(normalized);
@@ -12749,7 +12922,7 @@ async function importGeminiSkillsAndAgents(projectRoot, results, normalize2) {
       const relPath = relative(dirname(srcPath), absPath).replace(/\\/g, "/");
       const destSupportPath = join(skillDir, relPath);
       await mkdirp(dirname(destSupportPath));
-      await writeFileAtomic(destSupportPath, normalize2(supportContent, absPath, destSupportPath));
+      await writeFileAtomic(destSupportPath, normalize(supportContent, absPath, destSupportPath));
       results.push({
         fromTool: "gemini-cli",
         fromPath: absPath,
@@ -12771,7 +12944,7 @@ async function importGeminiSkillsAndAgents(projectRoot, results, normalize2) {
       const agentsDir = join(projectRoot, GEMINI_CANONICAL_AGENTS_DIR);
       await mkdirp(agentsDir);
       const destPath = join(agentsDir, relativeMdPath);
-      const normalizedBody = normalize2(body, srcPath, destPath);
+      const normalizedBody = normalize(body, srcPath, destPath);
       await writeFileAtomic(
         destPath,
         await serializeImportedAgentWithFallback(
@@ -12805,7 +12978,7 @@ var init_importer_skills_agents = __esm({
     init_constants30();
   }
 });
-async function importRootRule2(projectRoot, results, normalize2) {
+async function importRootRule2(projectRoot, results, normalize) {
   const normalizeCodex = await createImportReferenceNormalizer("codex-cli", projectRoot);
   const rulesDir = join(projectRoot, GEMINI_CANONICAL_RULES_DIR);
   const compatAgentsRootPath = join(projectRoot, GEMINI_COMPAT_AGENTS);
@@ -12836,10 +13009,10 @@ async function importRootRule2(projectRoot, results, normalize2) {
     rulesDir: GEMINI_CANONICAL_RULES_DIR,
     sourcePath: rootSourcePath,
     fromTool: GEMINI_TARGET,
-    normalize: normalize2
+    normalize
   });
   results.push(...split.results);
-  const compatNormalized = normalize2(split.rootContent, rootSourcePath, destPath);
+  const compatNormalized = normalize(split.rootContent, rootSourcePath, destPath);
   const normalizedRoot = stripProjectRootCanonicalPrefix(
     compatNormalized.replace(/\.agents\/skills\//g, ".agentsmesh/skills/").replace(/\.agents\\skills\\/g, ".agentsmesh/skills/"),
     projectRoot
@@ -12861,10 +13034,10 @@ async function importRootRule2(projectRoot, results, normalize2) {
 }
 async function importFromGemini(projectRoot) {
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(GEMINI_TARGET, projectRoot);
-  await importRootRule2(projectRoot, results, normalize2);
-  results.push(...await runDescriptorImport(descriptor15, projectRoot, "project", { normalize: normalize2 }));
-  await importGeminiSkillsAndAgents(projectRoot, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(GEMINI_TARGET, projectRoot);
+  await importRootRule2(projectRoot, results, normalize);
+  results.push(...await runDescriptorImport(descriptor15, projectRoot, "project", { normalize }));
+  await importGeminiSkillsAndAgents(projectRoot, results, normalize);
   await importGeminiSettings(projectRoot, results);
   await importGeminiIgnore(projectRoot, results);
   results.push(...await importGeminiPolicies(projectRoot));
@@ -12886,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);
@@ -12997,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"() {
@@ -13020,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();
@@ -13215,6 +13419,7 @@ var init_gemini_cli2 = __esm({
       },
       buildImportPaths: buildGeminiCliImportPaths,
       detectionPaths: ["GEMINI.md", ".gemini"],
+      nativeInstall: { inferPick: inferGeminiPick },
       conversionDefaults: { agentsToSkills: false }
     };
   }
@@ -13265,10 +13470,10 @@ var init_generator19 = __esm({
 async function importFromGoose(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(GOOSE_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor16, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(GOOSE_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor16, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? GOOSE_GLOBAL_SKILLS_DIR : GOOSE_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, GOOSE_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, GOOSE_TARGET, results, normalize);
   return results;
 }
 var init_importer16 = __esm({
@@ -13500,8 +13705,8 @@ var init_generator20 = __esm({
 // src/targets/jules/importer.ts
 async function importFromJules(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
-  const normalize2 = await createImportReferenceNormalizer(JULES_TARGET, projectRoot, scope);
-  return runDescriptorImport(descriptor17, projectRoot, scope, { normalize: normalize2 });
+  const normalize = await createImportReferenceNormalizer(JULES_TARGET, projectRoot, scope);
+  return runDescriptorImport(descriptor17, projectRoot, scope, { normalize });
 }
 var init_importer17 = __esm({
   "src/targets/jules/importer.ts"() {
@@ -13770,7 +13975,7 @@ var init_generator21 = __esm({
     init_constants16();
   }
 });
-async function importRootRule3(projectRoot, results, normalize2) {
+async function importRootRule3(projectRoot, results, normalize) {
   const sources = [JUNIE_DOT_AGENTS, JUNIE_GUIDELINES, JUNIE_CI_GUIDELINES, JUNIE_AGENTS_FALLBACK];
   const destPath = join(projectRoot, JUNIE_CANONICAL_ROOT_RULE);
   for (const relPath of sources) {
@@ -13783,10 +13988,10 @@ async function importRootRule3(projectRoot, results, normalize2) {
       rulesDir: JUNIE_CANONICAL_RULES_DIR,
       sourcePath: srcPath,
       fromTool: JUNIE_TARGET,
-      normalize: normalize2
+      normalize
     });
     results.push(...split.results);
-    const { frontmatter, body } = parseFrontmatter(normalize2(split.rootContent, srcPath, destPath));
+    const { frontmatter, body } = parseFrontmatter(normalize(split.rootContent, srcPath, destPath));
     const output = await serializeImportedRuleWithFallback(
       destPath,
       {
@@ -13808,10 +14013,10 @@ async function importRootRule3(projectRoot, results, normalize2) {
 }
 async function importFromJunie(projectRoot) {
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(JUNIE_TARGET, projectRoot);
-  await importRootRule3(projectRoot, results, normalize2);
-  results.push(...await runDescriptorImport(descriptor18, projectRoot, "project", { normalize: normalize2 }));
-  await importEmbeddedSkills(projectRoot, JUNIE_SKILLS_DIR, JUNIE_TARGET, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(JUNIE_TARGET, projectRoot);
+  await importRootRule3(projectRoot, results, normalize);
+  results.push(...await runDescriptorImport(descriptor18, projectRoot, "project", { normalize }));
+  await importEmbeddedSkills(projectRoot, JUNIE_SKILLS_DIR, JUNIE_TARGET, results, normalize);
   return results;
 }
 var init_importer18 = __esm({
@@ -14056,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" } }
+        ]
+      }
     };
   }
 });
@@ -14203,7 +14424,7 @@ async function pathExists(absolutePath) {
     return false;
   }
 }
-async function importLegacyRules(projectRoot, results, normalize2) {
+async function importLegacyRules(projectRoot, results, normalize) {
   const srcDir = join(projectRoot, KILO_CODE_LEGACY_RULES_DIR);
   if (!await pathExists(srcDir)) return;
   const destDir = join(projectRoot, KILO_CODE_CANONICAL_RULES_DIR);
@@ -14212,7 +14433,7 @@ async function importLegacyRules(projectRoot, results, normalize2) {
   const rootContent = hasCurrentRoot ? null : await readFileSafe(rootSourceFile);
   if (rootContent !== null) {
     const destPath = join(projectRoot, CANONICAL_ROOT_RULE_PATH);
-    const normalized = normalize2(rootContent, rootSourceFile, destPath);
+    const normalized = normalize(rootContent, rootSourceFile, destPath);
     const { body } = parseFrontmatter(normalized);
     const serialized = await serializeImportedRuleWithFallback(destPath, { root: true }, body);
     await writeFileAtomic(destPath, serialized);
@@ -14229,7 +14450,7 @@ async function importLegacyRules(projectRoot, results, normalize2) {
       destDir,
       extensions: [".md"],
       fromTool: KILO_CODE_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ srcPath, relativePath, content, normalizeTo }) => {
         const mapping = await kiloNonRootRuleMapper({
           absolutePath: srcPath,
@@ -14245,7 +14466,7 @@ async function importLegacyRules(projectRoot, results, normalize2) {
     })
   );
 }
-async function importLegacyWorkflows(projectRoot, results, normalize2) {
+async function importLegacyWorkflows(projectRoot, results, normalize) {
   const srcDir = join(projectRoot, KILO_CODE_LEGACY_WORKFLOWS_DIR);
   if (!await pathExists(srcDir)) return;
   const destDir = join(projectRoot, KILO_CODE_CANONICAL_COMMANDS_DIR);
@@ -14255,7 +14476,7 @@ async function importLegacyWorkflows(projectRoot, results, normalize2) {
       destDir,
       extensions: [".md"],
       fromTool: KILO_CODE_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ srcPath, relativePath, content, normalizeTo }) => {
         const mapping = await kiloCommandMapper({
           absolutePath: srcPath,
@@ -14270,7 +14491,7 @@ async function importLegacyWorkflows(projectRoot, results, normalize2) {
     })
   );
 }
-async function importLegacyModes(projectRoot, results, normalize2) {
+async function importLegacyModes(projectRoot, results, normalize) {
   const sourceFile = join(projectRoot, KILO_CODE_LEGACY_MODES_FILE);
   const content = await readFileSafe(sourceFile);
   if (content === null) return;
@@ -14299,7 +14520,7 @@ ${whenToUse}` : role;
     if (description) frontmatter.description = description;
     if (typeof mode.name === "string" && mode.name.length > 0) frontmatter.name = mode.name;
     const serialized = await serializeImportedAgentWithFallback(destPath, frontmatter, body);
-    const normalized = normalize2(serialized, sourceFile, destPath);
+    const normalized = normalize(serialized, sourceFile, destPath);
     await writeFileAtomic(destPath, normalized);
     results.push({
       feature: "agents",
@@ -14312,25 +14533,25 @@ ${whenToUse}` : role;
 async function importFromKiloCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(KILO_CODE_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor19, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(KILO_CODE_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor19, projectRoot, scope, { normalize }));
   await importEmbeddedSkills(
     projectRoot,
     KILO_CODE_SKILLS_DIR,
     KILO_CODE_TARGET,
     results,
-    normalize2
+    normalize
   );
   if (scope === "project") {
-    await importLegacyRules(projectRoot, results, normalize2);
-    await importLegacyWorkflows(projectRoot, results, normalize2);
-    await importLegacyModes(projectRoot, results, normalize2);
+    await importLegacyRules(projectRoot, results, normalize);
+    await importLegacyWorkflows(projectRoot, results, normalize);
+    await importLegacyModes(projectRoot, results, normalize);
     await importEmbeddedSkills(
       projectRoot,
       KILO_CODE_LEGACY_SKILLS_DIR,
       KILO_CODE_TARGET,
       results,
-      normalize2
+      normalize
     );
   }
   return results;
@@ -14799,14 +15020,14 @@ function canonicalRuleMeta2(frontmatter) {
   if (inclusion === "fileMatch") meta.trigger = "glob";
   return meta;
 }
-async function importRoot(projectRoot, results, normalize2, scope) {
+async function importRoot(projectRoot, results, normalize, scope) {
   const candidates = scope === "global" ? [KIRO_GLOBAL_STEERING_AGENTS_MD, KIRO_AGENTS_MD] : [KIRO_AGENTS_MD, KIRO_GLOBAL_STEERING_AGENTS_MD];
   for (const rel2 of candidates) {
     const srcPath = join(projectRoot, rel2);
     const content = await readFileSafe(srcPath);
     if (content === null) continue;
     const destPath = join(projectRoot, KIRO_CANONICAL_ROOT_RULE);
-    const { frontmatter, body } = parseFrontmatter(normalize2(content, srcPath, destPath));
+    const { frontmatter, body } = parseFrontmatter(normalize(content, srcPath, destPath));
     await writeFileAtomic(
       destPath,
       await serializeImportedRuleWithFallback(destPath, { ...frontmatter, root: true }, body)
@@ -14820,7 +15041,7 @@ async function importRoot(projectRoot, results, normalize2, scope) {
     return;
   }
 }
-async function importNonRootRules(projectRoot, results, normalize2) {
+async function importNonRootRules(projectRoot, results, normalize) {
   const destDir = join(projectRoot, KIRO_CANONICAL_RULES_DIR);
   results.push(
     ...await importFileDirectory({
@@ -14828,7 +15049,7 @@ async function importNonRootRules(projectRoot, results, normalize2) {
       destDir,
       extensions: [".md"],
       fromTool: KIRO_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ relativePath, normalizeTo }) => {
         if (basename(relativePath) === "AGENTS.md") return null;
         const destPath = join(destDir, relativePath);
@@ -14870,11 +15091,11 @@ async function importHooks2(projectRoot, results) {
 async function importFromKiro(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(KIRO_TARGET, projectRoot, scope);
-  await importRoot(projectRoot, results, normalize2, scope);
-  await importNonRootRules(projectRoot, results, normalize2);
-  results.push(...await runDescriptorImport(descriptor20, projectRoot, scope, { normalize: normalize2 }));
-  await importEmbeddedSkills(projectRoot, KIRO_SKILLS_DIR, KIRO_TARGET, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(KIRO_TARGET, projectRoot, scope);
+  await importRoot(projectRoot, results, normalize, scope);
+  await importNonRootRules(projectRoot, results, normalize);
+  results.push(...await runDescriptorImport(descriptor20, projectRoot, scope, { normalize }));
+  await importEmbeddedSkills(projectRoot, KIRO_SKILLS_DIR, KIRO_TARGET, results, normalize);
   if (scope === "project") await importHooks2(projectRoot, results);
   return results;
 }
@@ -15258,9 +15479,9 @@ async function importMcp4(projectRoot, scope, results) {
 async function importFromOpenCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(OPENCODE_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor21, projectRoot, scope, { normalize: normalize2 }));
-  await importEmbeddedSkills(projectRoot, OPENCODE_SKILLS_DIR, OPENCODE_TARGET, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(OPENCODE_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor21, projectRoot, scope, { normalize }));
+  await importEmbeddedSkills(projectRoot, OPENCODE_SKILLS_DIR, OPENCODE_TARGET, results, normalize);
   await importMcp4(projectRoot, scope, results);
   return results;
 }
@@ -15619,10 +15840,10 @@ var init_generator25 = __esm({
 async function importFromPiAgent(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(PI_AGENT_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor22, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(PI_AGENT_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor22, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? PI_AGENT_GLOBAL_SKILLS_DIR : PI_AGENT_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, PI_AGENT_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, PI_AGENT_TARGET, results, normalize);
   return results;
 }
 var init_importer22 = __esm({
@@ -15931,10 +16152,10 @@ var init_generator26 = __esm({
 async function importFromQwenCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(QWEN_CODE_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor23, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(QWEN_CODE_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor23, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? QWEN_GLOBAL_SKILLS_DIR : QWEN_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, QWEN_CODE_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, QWEN_CODE_TARGET, results, normalize);
   return results;
 }
 var init_importer23 = __esm({
@@ -16202,14 +16423,14 @@ var init_generator27 = __esm({
 async function importFromReplitAgent(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(REPLIT_AGENT_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor24, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(REPLIT_AGENT_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor24, projectRoot, scope, { normalize }));
   await importEmbeddedSkills(
     projectRoot,
     REPLIT_AGENT_SKILLS_DIR,
     REPLIT_AGENT_TARGET,
     results,
-    normalize2
+    normalize
   );
   return results;
 }
@@ -16500,7 +16721,7 @@ var init_import_mappers9 = __esm({
     };
   }
 });
-async function importPerModeRules(projectRoot, results, normalize2) {
+async function importPerModeRules(projectRoot, results, normalize) {
   const rooDir = join(projectRoot, ROO_CODE_DIR);
   let entries;
   try {
@@ -16517,7 +16738,7 @@ async function importPerModeRules(projectRoot, results, normalize2) {
         destDir,
         extensions: [".md"],
         fromTool: ROO_CODE_TARGET,
-        normalize: normalize2,
+        normalize,
         mapEntry: async ({ srcPath, relativePath, content, normalizeTo }) => {
           const mapping = await rooNonRootRuleMapper({
             absolutePath: srcPath,
@@ -16536,10 +16757,10 @@ async function importPerModeRules(projectRoot, results, normalize2) {
 async function importFromRooCode(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(ROO_CODE_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor25, projectRoot, scope, { normalize: normalize2 }));
-  await importPerModeRules(projectRoot, results, normalize2);
-  await importEmbeddedSkills(projectRoot, ROO_CODE_SKILLS_DIR, ROO_CODE_TARGET, results, normalize2);
+  const normalize = await createImportReferenceNormalizer(ROO_CODE_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor25, projectRoot, scope, { normalize }));
+  await importPerModeRules(projectRoot, results, normalize);
+  await importEmbeddedSkills(projectRoot, ROO_CODE_SKILLS_DIR, ROO_CODE_TARGET, results, normalize);
   return results;
 }
 var init_importer25 = __esm({
@@ -16853,10 +17074,10 @@ var init_generator29 = __esm({
 async function importFromRovodev(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(ROVODEV_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor26, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(ROVODEV_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor26, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? ROVODEV_GLOBAL_SKILLS_DIR : ROVODEV_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, ROVODEV_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, ROVODEV_TARGET, results, normalize);
   return results;
 }
 var init_importer26 = __esm({
@@ -17114,14 +17335,14 @@ var init_generator30 = __esm({
     init_constants25();
   }
 });
-async function importRoot2(projectRoot, results, normalize2, scope) {
+async function importRoot2(projectRoot, results, normalize, scope) {
   const candidates = scope === "global" ? [TRAE_GLOBAL_ROOT_RULE, TRAE_PROJECT_RULES] : [TRAE_PROJECT_RULES, TRAE_GLOBAL_ROOT_RULE];
   for (const rel2 of candidates) {
     const srcPath = join(projectRoot, rel2);
     const content = await readFileSafe(srcPath);
     if (content === null) continue;
     const destPath = join(projectRoot, CANONICAL_ROOT_RULE);
-    const { frontmatter, body } = parseFrontmatter(normalize2(content, srcPath, destPath));
+    const { frontmatter, body } = parseFrontmatter(normalize(content, srcPath, destPath));
     await mkdirp(join(projectRoot, TRAE_CANONICAL_RULES_DIR));
     await writeFileAtomic(
       destPath,
@@ -17136,7 +17357,7 @@ async function importRoot2(projectRoot, results, normalize2, scope) {
     return;
   }
 }
-async function importNonRootRules2(projectRoot, results, normalize2, scope) {
+async function importNonRootRules2(projectRoot, results, normalize, scope) {
   const srcDir = join(projectRoot, scope === "global" ? TRAE_GLOBAL_RULES_DIR : TRAE_RULES_DIR);
   const destDir = join(projectRoot, TRAE_CANONICAL_RULES_DIR);
   results.push(
@@ -17145,7 +17366,7 @@ async function importNonRootRules2(projectRoot, results, normalize2, scope) {
       destDir,
       extensions: [".md"],
       fromTool: TRAE_TARGET,
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ relativePath, normalizeTo }) => {
         const filename = basename(relativePath);
         if (filename === "project_rules.md" || filename === "rules.md") return null;
@@ -17168,16 +17389,16 @@ async function importNonRootRules2(projectRoot, results, normalize2, scope) {
 async function importFromTrae(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(TRAE_TARGET, projectRoot, scope);
-  await importRoot2(projectRoot, results, normalize2, scope);
-  await importNonRootRules2(projectRoot, results, normalize2, scope);
-  results.push(...await runDescriptorImport(descriptor27, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(TRAE_TARGET, projectRoot, scope);
+  await importRoot2(projectRoot, results, normalize, scope);
+  await importNonRootRules2(projectRoot, results, normalize, scope);
+  results.push(...await runDescriptorImport(descriptor27, projectRoot, scope, { normalize }));
   await importEmbeddedSkills(
     projectRoot,
     scope === "global" ? TRAE_GLOBAL_SKILLS_DIR : TRAE_SKILLS_DIR,
     TRAE_TARGET,
     results,
-    normalize2
+    normalize
   );
   return results;
 }
@@ -17404,10 +17625,10 @@ var init_generator31 = __esm({
 async function importFromWarp(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(WARP_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor28, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(WARP_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor28, projectRoot, scope, { normalize }));
   const skillsDir = scope === "global" ? WARP_GLOBAL_SKILLS_DIR : WARP_SKILLS_DIR;
-  await importEmbeddedSkills(projectRoot, skillsDir, WARP_TARGET, results, normalize2);
+  await importEmbeddedSkills(projectRoot, skillsDir, WARP_TARGET, results, normalize);
   return results;
 }
 var init_importer28 = __esm({
@@ -17869,7 +18090,7 @@ function toStringArray8(value) {
   }
   return [];
 }
-async function importWorkflows(projectRoot, results, normalize2) {
+async function importWorkflows(projectRoot, results, normalize) {
   const workflowsDir = join(projectRoot, WINDSURF_WORKFLOWS_DIR);
   const workflowFiles = await readDirRecursive(workflowsDir);
   const workflowMdFiles = workflowFiles.filter((f) => f.endsWith(".md"));
@@ -17880,7 +18101,7 @@ async function importWorkflows(projectRoot, results, normalize2) {
     const relativePath = relative(workflowsDir, srcPath).replace(/\\/g, "/");
     await mkdirp(destCommandsDir);
     const destPath = join(destCommandsDir, relativePath);
-    const normalized = normalize2(content, srcPath, destPath);
+    const normalized = normalize(content, srcPath, destPath);
     const { frontmatter, body } = parseFrontmatter(normalized);
     const outContent = await serializeImportedCommandWithFallback(
       destPath,
@@ -17914,12 +18135,12 @@ var init_importer_workflows = __esm({
 });
 
 // src/targets/windsurf/skills-adapter.ts
-async function importSkills4(projectRoot, results, normalize2, skillsRelDir = WINDSURF_SKILLS_DIR) {
+async function importSkills4(projectRoot, results, normalize, skillsRelDir = WINDSURF_SKILLS_DIR) {
   const options = {
     projectRoot,
     destCanonicalSkillsDir: WINDSURF_CANONICAL_SKILLS_DIR,
     targetName: "windsurf",
-    normalize: normalize2,
+    normalize,
     results
   };
   await importSkillsDirectory([skillsRelDir], options, [
@@ -18033,7 +18254,7 @@ var init_importer_hooks_mcp = __esm({
 async function importFromWindsurf(projectRoot, options) {
   const layoutScope = options?.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(WINDSURF_TARGET, projectRoot);
+  const normalize = await createImportReferenceNormalizer(WINDSURF_TARGET, projectRoot);
   const normalizeCodex = await createImportReferenceNormalizer("codex-cli", projectRoot);
   const destRulesDir = join(projectRoot, WINDSURF_CANONICAL_RULES_DIR);
   const rootPath = join(projectRoot, WINDSURF_RULES_ROOT);
@@ -18041,7 +18262,7 @@ async function importFromWindsurf(projectRoot, options) {
   if (rootContent !== null) {
     await mkdirp(destRulesDir);
     const destPath = join(destRulesDir, "_root.md");
-    const body = normalize2(rootContent, rootPath, destPath).trim();
+    const body = normalize(rootContent, rootPath, destPath).trim();
     const outContent = await serializeImportedRuleWithFallback(destPath, { root: true }, body);
     await writeFileAtomic(destPath, outContent);
     results.push({
@@ -18057,7 +18278,7 @@ async function importFromWindsurf(projectRoot, options) {
     if (agentsMdContent !== null) {
       await mkdirp(destRulesDir);
       const destPath = join(destRulesDir, "_root.md");
-      const body = normalize2(
+      const body = normalize(
         normalizeCodex(agentsMdContent, agentsMdPath, destPath),
         agentsMdPath,
         destPath
@@ -18079,7 +18300,7 @@ async function importFromWindsurf(projectRoot, options) {
         destDir: destRulesDir,
         extensions: ["AGENTS.md"],
         fromTool: "windsurf",
-        normalize: normalize2,
+        normalize,
         mapEntry: async ({ srcPath, normalizeTo }) => {
           const relDir = relative(projectRoot, dirname(srcPath)).replace(/\\/g, "/");
           if (!relDir || relDir === "." || basename(srcPath) !== "AGENTS.md") return null;
@@ -18110,7 +18331,7 @@ async function importFromWindsurf(projectRoot, options) {
       destDir: destRulesDir,
       extensions: [".md"],
       fromTool: "windsurf",
-      normalize: normalize2,
+      normalize,
       mapEntry: async ({ relativePath, normalizeTo }) => {
         if (relativePath === "_root.md" && rootContent !== null) return null;
         const destPath = join(destRulesDir, relativePath);
@@ -18158,8 +18379,8 @@ async function importFromWindsurf(projectRoot, options) {
       });
     }
   }
-  await importWorkflows(projectRoot, results, normalize2);
-  await importSkills4(projectRoot, results, normalize2);
+  await importWorkflows(projectRoot, results, normalize);
+  await importSkills4(projectRoot, results, normalize);
   await importWindsurfHooks(projectRoot, results);
   await importWindsurfMcp(projectRoot, results);
   return results;
@@ -18406,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 }
     };
   }
@@ -18473,8 +18704,8 @@ var init_mcp_import3 = __esm({
 async function importFromZed(projectRoot, options = {}) {
   const scope = options.scope ?? "project";
   const results = [];
-  const normalize2 = await createImportReferenceNormalizer(ZED_TARGET, projectRoot, scope);
-  results.push(...await runDescriptorImport(descriptor30, projectRoot, scope, { normalize: normalize2 }));
+  const normalize = await createImportReferenceNormalizer(ZED_TARGET, projectRoot, scope);
+  results.push(...await runDescriptorImport(descriptor30, projectRoot, scope, { normalize }));
   const mcpFile = scope === "global" ? ZED_GLOBAL_SETTINGS_FILE : ZED_SETTINGS_FILE;
   await importZedMcp(projectRoot, mcpFile, results);
   return results;
@@ -18680,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)) {
@@ -18735,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") {
@@ -18791,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";
   }
@@ -18804,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();
@@ -18842,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,
@@ -19272,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",
@@ -19280,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;
@@ -19297,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) {
@@ -19805,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, {
@@ -19911,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);
@@ -20235,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 });
@@ -22586,156 +22855,1085 @@ function lintRuleScopeInversion(input) {
   }
   return out2;
 }
-var TriggersSchema = 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 ClusterSchema = z.object({
-  topic: z.string().regex(/^[a-z0-9-]+$/, "topic must be kebab-case"),
-  /**
-   * Project-relative path (forward slashes) to the cluster's markdown body.
-   * Conventionally `.agentsmesh/lessons/topics/<topic>.md`, but any project
-   * path is accepted — universal across every agent target.
-   */
-  file: z.string().regex(/\.md$/, "file must be a .md path"),
-  summary: z.string().min(1),
-  triggers: TriggersSchema
-});
-var LessonsIndexSchema = z.object({
-  version: z.literal(1),
-  /**
-   * Zero clusters is valid — supports `agentsmesh init --lessons` scaffolding a
-   * fresh project. Topics accumulate via `distill:apply` as failures are
-   * captured.
-   */
-  clusters: z.array(ClusterSchema)
-});
-function parseIndex(raw) {
-  return LessonsIndexSchema.parse(raw);
+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/lessons/graph-store.ts
+var GRAPH_REL_PATH = ".agentsmesh/lessons/lessons.json";
+function graphFilePath(projectRoot) {
+  return resolve(projectRoot, GRAPH_REL_PATH);
+}
+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"),
-    ledger: join(base, "distill-ledger.yaml"),
-    proposal: join(base, "distill-proposal.md"),
     topicsDir: join(base, "topics")
   };
 }
 function toRelPath(projectRoot, absolute) {
   return relative(projectRoot, absolute).split(sep).join("/");
 }
-var LESSONS_JOURNAL_TEMPLATE = "# Lessons Learned\n\n";
-var LESSONS_INDEX_TEMPLATE = "version: 1\nclusters: []\n";
-var LESSONS_PROCEDURAL_RULE = `## Lessons (MUST do \u2014 non-negotiable)
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
 
-Two rituals. Universal across every agent harness \u2014 described in tool-agnostic action verbs ("read a file", "edit a file", "run a shell command"); use whatever read / write-patch / shell-exec tool your harness exposes. Skipping either ritual is a process violation; the same paid-for failure recurs next session.
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
 
-**Recall \u2014 BEFORE editing any file or running any shell command:**
+**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.
 
-1. Read \`.agentsmesh/lessons/index.yaml\`.
-2. For every cluster whose triggers match \u2014 \`file_globs\` against the target file path, \`command_patterns\` (regex) against the shell command, or \`keywords\` (case-insensitive substring) against the active task description \u2014 read its \`file\` (e.g. \`.agentsmesh/lessons/topics/<topic>.md\`).
-3. Apply the loaded rules to the action.
-4. Then \u2014 and only then \u2014 perform the edit or run the command.
+**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>\`.
 
-Rejected excuses: *"the edit is small"* \u2192 apply it. *"I read this earlier in the session"* \u2192 context may have compacted; re-read. *"no trigger fires"* \u2192 proceed; you've done your part.
-
-**Capture \u2014 IMMEDIATELY after any failure** (test, CI, lint, code review, user correction, regression you spotted yourself, OR any mistake by anyone in the loop):
-
-1. Append one bullet to \`.agentsmesh/lessons/journal.md\` in this exact shape:
-   \`- **<short heading>**: <what went wrong>. <root cause>. <imperative rule that prevents recurrence>.\`
-2. Read \`.agentsmesh/lessons/index.yaml\` and identify which topic the lesson belongs to (use the \`summary:\` fields).
-3. If the lesson teaches a NEW rule: edit that topic's \`## Rules\` section to add it, citing \`(Evidence: L<journal-line>)\`. If it only reinforces an existing rule, the journal entry alone suffices.
-
-Rejected excuses: *"it wasn't really a failure"* \u2192 if you fixed something, it was. *"I'll capture it later"* \u2192 no; do it now while context is fresh. *"no topic fits"* \u2192 still record in journal; an unrouted bullet is recoverable, a forgotten one is not.
-
-**These two rituals are load-bearing. Treat them with the same discipline as TDD.**`;
+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;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return out2;
+}
 
-// src/core/lint/shared/lessons.ts
-var LESSONS_TARGET = "lessons";
-var INDEX_REL = ".agentsmesh/lessons/index.yaml";
-var ROOT_RULE_REL = ".agentsmesh/rules/_root.md";
-var LESSONS_HEADING = /^## Lessons \(/m;
-var RULES_HEADING = /^## Rules\b/m;
-function lintLessonsSubsystem(projectRoot, scope) {
-  if (scope === "global") return [];
-  const paths = lessonsPaths(projectRoot);
-  if (!existsSync(paths.index)) return [];
-  const out2 = [];
-  const parsed = LessonsIndexSchema.safeParse(parse(readFileSync(paths.index, "utf8")));
-  if (!parsed.success) {
-    return [diag("error", INDEX_REL, `index.yaml is invalid: ${parsed.error.issues[0].message}`)];
+// 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
+        });
+      }
+    }
+    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 (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
+      });
+    }
   }
-  for (const cluster of parsed.data.clusters) {
-    const topicAbs = join(projectRoot, cluster.file);
-    if (!existsSync(topicAbs)) {
-      out2.push(
-        diag("error", cluster.file, `topic file for cluster "${cluster.topic}" does not exist.`)
-      );
+}
+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
+      });
+    }
+    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
+      });
+    }
+  }
+}
+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 (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
+      });
+    }
+  }
+}
+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 (!RULES_HEADING.test(readFileSync(topicAbs, "utf8"))) {
-      out2.push(
-        diag("warning", cluster.file, `topic "${cluster.topic}" is missing a "## Rules" section.`)
-      );
+    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
+      });
     }
-    for (const pattern of cluster.triggers.command_patterns) {
-      try {
-        new RegExp(pattern);
-      } catch {
-        out2.push(
-          diag(
-            "warning",
-            INDEX_REL,
-            `cluster "${cluster.topic}" command_patterns entry is not a valid regex: ${pattern}`
-          )
-        );
+  }
+  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;
     }
   }
-  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.'
-      )
-    );
+}
+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
+      });
+    }
   }
-  return out2;
 }
-function diag(level, file, message) {
-  return { level, file, target: LESSONS_TARGET, message };
+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/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/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));
 }
-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)];
+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);
@@ -23138,203 +24336,1190 @@ function copyTargetDescriptor(descriptor31) {
 function getTargetCatalog() {
   return Object.freeze(BUILTIN_TARGETS.map(copyTargetDescriptor));
 }
-function normalize(bullet) {
-  return bullet.split("\n").map((line) => line.replace(/\s+$/, "")).join("\n").trim().replace(/^[-*]\s+/, "");
-}
-function hashBullet(bullet) {
-  return createHash("sha256").update(normalize(bullet)).digest("hex").slice(0, 16);
-}
-
-// src/lessons/bullet-parser.ts
-function parseBullets(markdown) {
-  const bullets = [];
-  let current = null;
-  let lineNumber = 0;
-  for (const line of markdown.split("\n")) {
-    lineNumber += 1;
-    if (/^[-*]\s+/.test(line)) {
-      if (current !== null) bullets.push(current);
-      current = { text: line, lineNumber };
-    } else if (current !== null) {
-      if (line.length === 0) {
-        bullets.push(current);
-        current = null;
-      } else if (/^\s+\S/.test(line)) {
-        current.text += `
-${line}`;
-      } else {
-        bullets.push(current);
-        current = null;
-      }
+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;
+    }
+    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 rules;
+}
+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/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/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 maybeAutoMigrateLessons(projectRoot) {
+  if (existsSync(graphFilePath(projectRoot))) return false;
+  const paths = lessonsPaths(projectRoot);
+  if (!existsSync(paths.index)) return false;
+  try {
+    await importLegacyLessons(projectRoot, { migratedAt: todayIso2() });
+    return true;
+  } catch (err) {
+    if (err instanceof LessonsGraphExistsError) return false;
+    throw err;
+  }
+}
+
+// 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);
   }
-  if (current !== null) bullets.push(current);
-  return bullets;
 }
-function fileMatch(globs, path) {
-  return globs.some((g) => picomatch(g, { dot: true })(path));
+async function tryAcquire(lockPath) {
+  try {
+    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(() => {
+    });
+  };
 }
-function cmdMatch(patterns, cmd) {
-  return patterns.some((p) => {
+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 {
-      return new RegExp(p).test(cmd);
+      const info = await stat(lockPath);
+      const ageMs = Date.now() - info.mtimeMs;
+      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
     } catch {
-      return false;
     }
-  });
+    return null;
+  }
+}
+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 kwMatch(keywords, text) {
-  const lower = text.toLowerCase();
-  return keywords.some((k) => lower.includes(k.toLowerCase()));
-}
-function matchTriggers(clusters, event) {
-  return clusters.filter((c2) => {
-    const t = c2.triggers;
-    switch (event.kind) {
-      case "edit":
-      case "write":
-        return fileMatch(t.file_globs, event.filePath);
-      case "bash":
-        return cmdMatch(t.command_patterns, event.command);
-      case "task":
-        return kwMatch(t.keywords, event.text);
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+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();
+  }
+}
+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";
+    }
+    return null;
+  }
+  return null;
+}
+function blockingDeadTriggers(graph, triggerIds) {
+  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
+}
+
+// src/lessons/add.ts
+function countInputTriggers(triggers) {
+  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
+}
+async function addLesson(projectRoot, input, options = {}) {
+  return mutateLessonsGraph(projectRoot, (graph) => addLessonInto(graph, input, options), {
+    retries: options.retries
   });
 }
-var LedgerSchema = z.object({
-  version: z.literal(1),
-  assignments: z.record(z.string(), z.string())
-});
-function loadLedger(path) {
-  if (!existsSync(path)) return { version: 1, assignments: {} };
-  return LedgerSchema.parse(parse(readFileSync(path, "utf8")));
-}
-function saveLedger(path, ledger) {
-  writeFileSync(path, stringify(ledger), "utf8");
-}
-
-// src/lessons/scoring.ts
-function scoreBullet(bullet, clusters) {
-  const lower = bullet.toLowerCase();
-  return clusters.map((cluster) => {
-    const t = cluster.triggers;
-    const kwHits = t.keywords.filter((k) => lower.includes(k.toLowerCase())).length;
-    const pathHits = t.file_globs.filter((g) => {
-      const stem = g.replace(/[*{}[\]?!]/g, "").replace(/\/+/g, "/").trim();
-      return stem.length > 2 && lower.includes(stem.toLowerCase());
-    }).length;
-    const cmdHits = t.command_patterns.filter((p) => {
-      try {
-        return new RegExp(p, "i").test(bullet);
-      } catch {
-        return false;
-      }
-    }).length;
-    return { cluster, score: kwHits * 2 + pathHits + cmdHits };
-  }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score);
-}
-function loadLessonsIndex(projectRoot) {
-  const raw = readFileSync(lessonsPaths(projectRoot).index, "utf8");
-  return parseIndex(parse(raw));
-}
-function readTriggeredLessons(projectRoot, event) {
-  const index = loadLessonsIndex(projectRoot);
-  const contentByPath = /* @__PURE__ */ new Map();
-  return matchTriggers(index.clusters, normalizeToolEvent(projectRoot, event)).map(
-    (cluster) => {
-      const filePath = resolveProjectFile(projectRoot, cluster.file);
-      let content = contentByPath.get(cluster.file);
-      if (content === void 0) {
-        content = readFileSync(filePath, "utf8");
-        contentByPath.set(cluster.file, content);
+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 {
+      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 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;
+  }
+  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);
+  }
+  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 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/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;
       }
-      return {
-        cluster,
-        relativePath: cluster.file,
-        filePath,
-        content
-      };
     }
+    if (hit) return true;
+  }
+  return false;
+}
+function keywordMatches(pattern, query) {
+  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+    return true;
+  }
+  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
+}
+
+// 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;
+}
+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 formatLessonBullet(input) {
-  const heading = compact(input.heading);
-  if (heading.length === 0) throw new Error("Lesson heading must not be empty.");
-  return [
-    `- **${heading}**:`,
-    sentence(input.whatWentWrong),
-    sentence(input.rootCause),
-    sentence(input.rule)
-  ].join(" ");
-}
-function appendLessonToJournal(projectRoot, input) {
-  const journalPath = lessonsPaths(projectRoot).journal;
-  const bullet = formatLessonBullet(input);
-  const current = existsSync(journalPath) ? readFileSync(journalPath, "utf8") : "";
-  const prefix = current.length === 0 || current.endsWith("\n") ? "" : "\n";
-  const lineNumber = nextLineNumber(current);
-  mkdirSync(dirname(journalPath), { recursive: true });
-  appendFileSync(journalPath, `${prefix}${bullet}
-`, "utf8");
-  return { journalPath, bullet, lineNumber };
+function defaultLessonsConfig() {
+  return {
+    recallLimit: DEFAULT_RECALL_LIMIT,
+    recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
+    autoPrune: false
+  };
 }
-function resolveProjectFile(projectRoot, relPath) {
-  if (isAbsolute(relPath) || /^[A-Za-z]:[\\/]/.test(relPath)) {
-    throw new Error(`Lessons file must be project-relative: ${relPath}`);
+
+// src/lessons/merge.ts
+async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {
+  return mutateLessonsGraph(projectRoot, (graph) => mergeInto(graph, loserId, keeperId), {
+    retries: options.retries
+  });
+}
+function mergeInto(graph, loserId, keeperId) {
+  if (loserId === keeperId) {
+    throw new Error(`mergeLessons: cannot merge lesson "${loserId}" into itself.`);
   }
-  const root = resolve(projectRoot);
-  const filePath = resolve(root, relPath);
-  const backToRoot = relative(root, filePath);
-  if (backToRoot === "" || backToRoot.startsWith("..") || isAbsolute(backToRoot)) {
-    throw new Error(`Lessons file escapes the project root: ${relPath}`);
+  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}).`);
   }
-  return filePath;
+  if (loser.status !== "active") {
+    throw new Error(
+      `mergeLessons: loser "${loserId}" is already ${loser.status}; nothing to merge.`
+    );
+  }
+  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 normalizeToolEvent(projectRoot, event) {
-  if (event.kind !== "edit" && event.kind !== "write") return event;
-  return { ...event, filePath: normalizeEventPath(projectRoot, event.filePath) };
+function union2(base, extra) {
+  const out2 = [...base];
+  for (const item of extra) {
+    if (!out2.includes(item)) out2.push(item);
+  }
+  return out2;
 }
-function normalizeEventPath(projectRoot, filePath) {
-  const normalized = filePath.replaceAll("\\", "/");
-  const root = resolve(projectRoot).replaceAll("\\", "/");
-  if (normalized === root) return ".";
-  if (normalized.startsWith(`${root}/`)) return normalized.slice(root.length + 1);
-  return normalized.replace(/^\.\//, "");
+
+// 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 compact(value) {
-  return value.replace(/\s+/g, " ").trim();
+
+// 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 sentence(value) {
-  const compacted = compact(value);
-  if (compacted.length === 0) throw new Error("Lesson sentence must not be empty.");
-  return /[.!?]$/.test(compacted) ? compacted : `${compacted}.`;
+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;
+}
+
+// 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 nextLineNumber(current) {
-  if (current.length === 0) return 1;
-  const lineCount = current.split("\n").length;
-  return current.endsWith("\n") ? lineCount : lineCount + 1;
+function stripLessonsParagraph(content) {
+  const withoutBlock = stripManagedBlock(content, LESSONS_CONTRACT_START, LESSONS_CONTRACT_END);
+  return stripRawProceduralRule(withoutBlock).trim();
 }
-function scaffoldLessons(projectRoot) {
+function stripRawProceduralRule(content) {
+  return content.replace(`
+
+${LESSONS_PROCEDURAL_RULE}`, "").replace(LESSONS_PROCEDURAL_RULE, "");
+}
+
+// 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.topicsDir, { recursive: true });
-  for (const [path, template] of [
-    [paths.journal, LESSONS_JOURNAL_TEMPLATE],
-    [paths.index, LESSONS_INDEX_TEMPLATE]
-  ]) {
-    if (existsSync(path)) {
-      skipped.push(path);
-    } else {
-      mkdirSync(dirname(path), { recursive: true });
-      writeFileSync(path, template, "utf8");
-      created.push(path);
-    }
+  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 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;
   }
-  const rootRuleUpdated = appendProceduralRule(projectRoot);
-  return { created, skipped, rootRuleUpdated };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(defaultLessonsConfig(), null, 2)}
+`, "utf8");
+  created.push(configPath);
 }
-function appendProceduralRule(projectRoot) {
+function injectProceduralBlock(projectRoot) {
   const rootRule = join(projectRoot, ".agentsmesh/rules/_root.md");
   if (!existsSync(rootRule)) {
     mkdirSync(dirname(rootRule), { recursive: true });
@@ -23343,23 +25528,21 @@ root: true
 description: ""
 ---
 
-# Operational Guidelines
+${LESSONS_PARAGRAPH_BLOCK}
 
-${LESSONS_PROCEDURAL_RULE}
+# Operational Guidelines
 `;
     writeFileSync(rootRule, seeded, "utf8");
     return true;
   }
   const current = readFileSync(rootRule, "utf8");
-  if (/^## Lessons \(/m.test(current)) return false;
-  const next = current.endsWith("\n") ? current : `${current}
+  const desired = `${appendLessonsParagraph(current)}
 `;
-  writeFileSync(rootRule, `${next}
-${LESSONS_PROCEDURAL_RULE}
-`, "utf8");
+  if (desired === current) return false;
+  writeFileSync(rootRule, desired, "utf8");
   return true;
 }
 
-export { AgentsMeshError, ConfigNotFoundError, ConfigValidationError, FileSystemError, GenerationError, ImportError, LESSONS_INDEX_TEMPLATE, LESSONS_JOURNAL_TEMPLATE, LESSONS_PROCEDURAL_RULE, LessonsIndexSchema, LockAcquisitionError, RemoteFetchError, TargetNotFoundError, appendLessonToJournal, check, computeDiff2 as computeDiff, diff, formatDiffSummary, formatLessonBullet, generate, getAllDescriptors, getDescriptor, getTargetCatalog, hashBullet, importFrom, lessonsPaths, lint, loadCanonical, loadCanonicalFiles, loadConfig2 as loadConfig, loadConfigFromDirectory, loadLedger, loadLessonsIndex, loadProjectContext, matchTriggers, parseBullets, parseIndex, readTriggeredLessons, registerTargetDescriptor, resolveOutputCollisions, saveLedger, scaffoldLessons, scoreBullet, toRelPath };
+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