agentsmesh 0.31.0 → 0.33.0

package/dist/lessons.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, realpathSync, appendFileSync } from 'fs';
+import { resolve, dirname, join, relative, sep, basename, extname } from 'path';
+import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
 import { createHash } from 'crypto';
 import picomatch from 'picomatch';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync, readdirSync, realpathSync, appendFileSync, statSync } from 'fs';
-import { resolve, join, relative, sep, dirname, basename, extname } from 'path';
-import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
 import { mkdir, rm, writeFile, readFile, stat, lstat, unlink, rename, chmod } from 'fs/promises';
 import { tmpdir, hostname } from 'os';
 import 'timers/promises';
@@ -52,6 +52,157 @@ var LessonsGraphSchema = z.object({
 function parseGraph(raw) {
   return LessonsGraphSchema.parse(raw);
 }
+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 loadLessonsGraphResilient(projectRoot) {
+  const path = graphFilePath(projectRoot);
+  if (!existsSync(path)) return { status: "absent", graph: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const version = parsed?.version;
+    if (typeof version === "number" && version > CURRENT_GRAPH_VERSION) {
+      return { status: "newer-version", graph: null, version };
+    }
+    return { status: "ok", graph: parseGraph(parsed) };
+  } catch (error) {
+    return {
+      status: "corrupt",
+      graph: null,
+      error: error instanceof Error ? error : new Error(String(error))
+    };
+  }
+}
+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(canonicalize(graph), null, 2)}
+`;
+}
+function canonicalize(value) {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a < b ? -1 : 1
+    );
+    const out = {};
+    for (const [k, v] of entries) out[k] = canonicalize(v);
+    return out;
+  }
+  return value;
+}
+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 = makeTriggerId(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_PREFIX = {
+  file_glob: "glob",
+  command_pattern: "cmd",
+  keyword: "kw"
+};
+function makeTriggerId(spec) {
+  const hash = createHash("sha1").update(`${spec.kind}|${spec.pattern}`).digest("hex").slice(0, 8);
+  return `t-${TRIGGER_PREFIX[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 rel of LEGACY_ARTIFACT_REL) {
+    const abs = join(baseDir, rel);
+    if (!existsSync(abs)) continue;
+    rmSync(abs, { recursive: true, force: true });
+    deleted.push(abs);
+  }
+  return deleted;
+}
 function normalizeRule(rule) {
   return rule.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -85,7 +236,7 @@ function mergeTriggers(graph, spec) {
       if (!triggerIds.includes(existing)) triggerIds.push(existing);
       continue;
     }
-    const id = makeTriggerId(spec2);
+    const id = makeTriggerId2(spec2);
     graph.triggers[id] = { kind: spec2.kind, pattern: spec2.pattern };
     reverseLookup.set(key, id);
     triggerIds.push(id);
@@ -96,14 +247,14 @@ function mergeTriggers(graph, spec) {
 function triggerKey(t) {
   return `${t.kind}|${t.pattern}`;
 }
-var TRIGGER_PREFIX = {
+var TRIGGER_PREFIX2 = {
   file_glob: "glob",
   command_pattern: "cmd",
   keyword: "kw"
 };
-function makeTriggerId(spec) {
+function makeTriggerId2(spec) {
   const hash = createHash("sha1").update(triggerKey(spec)).digest("hex").slice(0, 8);
-  return `t-${TRIGGER_PREFIX[spec.kind]}-${hash}`;
+  return `t-${TRIGGER_PREFIX2[spec.kind]}-${hash}`;
 }
 function makeLessonId(graph, topic, ruleKey) {
   const slug = ruleToSlug(ruleKey);
@@ -397,338 +548,32 @@ function jaccard(a, b) {
   for (const t of a) if (b.has(t)) intersection += 1;
   return intersection / (a.size + b.size - intersection);
 }
-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 loadLessonsGraphResilient(projectRoot) {
-  const path = graphFilePath(projectRoot);
-  if (!existsSync(path)) return { status: "absent", graph: null };
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    const version = parsed?.version;
-    if (typeof version === "number" && version > CURRENT_GRAPH_VERSION) {
-      return { status: "newer-version", graph: null, version };
-    }
-    return { status: "ok", graph: parseGraph(parsed) };
-  } catch (error) {
-    return {
-      status: "corrupt",
-      graph: null,
-      error: error instanceof Error ? error : new Error(String(error))
-    };
+
+// src/core/errors.ts
+var AgentsMeshError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "AgentsMeshError";
+    this.code = code;
   }
-}
-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(canonicalize(graph), null, 2)}
-`;
-}
-function canonicalize(value) {
-  if (value === null) return null;
-  if (Array.isArray(value)) return value.map(canonicalize);
-  if (typeof value === "object") {
-    const entries = Object.entries(value).sort(
-      ([a], [b]) => a < b ? -1 : 1
+};
+var 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 ${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
     );
-    const out = {};
-    for (const [k, v] of entries) out[k] = canonicalize(v);
-    return out;
-  }
-  return value;
-}
-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 rel of LEGACY_ARTIFACT_REL) {
-    const abs = join(baseDir, rel);
-    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
-  };
-}
-var BASE_REL = ".agentsmesh/lessons";
-function lessonsPaths(projectRoot) {
-  const base = join(projectRoot, BASE_REL);
-  return {
-    base,
-    graph: join(base, "lessons.json"),
-    config: join(base, "config.json"),
-    journal: join(base, "journal.md"),
-    index: join(base, "index.yaml"),
-    topicsDir: join(base, "topics")
-  };
-}
-function toRelPath(projectRoot, absolute) {
-  return relative(projectRoot, absolute).split(sep).join("/");
-}
-var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
-
-Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
-
-**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
-
-**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
-
-**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
-
-// 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 = CURRENT_GRAPH_VERSION;
-    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/core/errors.ts
-var AgentsMeshError = class extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.name = "AgentsMeshError";
-    this.code = code;
-  }
-};
-var 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 ${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;
+    this.name = "LockAcquisitionError";
+    this.lockPath = lockPath;
+    this.holder = holder;
+    this.label = label;
   }
 };
 var FileSystemError = class extends AgentsMeshError {
@@ -856,7 +701,7 @@ function getHostname() {
   return hostname();
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // src/lessons/lessons-lock.ts
@@ -1807,255 +1652,159 @@ function findExistingLessonByRule(graph, ruleKey) {
   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;
-}
-
-// src/lessons/prune.ts
-function planPrune(graph, options = {}) {
-  const cap = Math.max(1, options.cap ?? MAX_RECOMMENDED_TRIGGERS);
-  const fanout = buildFanout(graph);
-  const trimmedLessons = [];
-  const keptByLesson = /* @__PURE__ */ new Map();
-  for (const [id, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    if (options.trimOverCap === false || lesson.triggers.length <= cap) {
-      keptByLesson.set(id, lesson.triggers);
-      continue;
-    }
-    const ordered = [...lesson.triggers].sort((a, b) => {
-      const fa = fanout.get(a);
-      const fb = fanout.get(b);
-      return fa !== fb ? fa - fb : a < b ? -1 : 1;
-    });
-    const drop = new Set(ordered.slice(cap));
-    const kept = lesson.triggers.filter((t) => !drop.has(t));
-    keptByLesson.set(id, kept);
-    trimmedLessons.push({ id, removedTriggers: [...drop], keptCount: kept.length });
-  }
-  const removedDeadGlobs = [];
-  const unreachableLessons = [];
-  if (options.knownPaths !== void 0) {
-    const dead = deadFileGlobIds(graph, options.knownPaths);
-    if (dead.size > 0) {
-      for (const [id, kept] of keptByLesson) {
-        const deadInLesson = kept.filter((t) => dead.has(t));
-        if (deadInLesson.length === 0) continue;
-        const remaining = kept.filter((t) => !dead.has(t));
-        if (remaining.length >= 1) {
-          keptByLesson.set(id, remaining);
-          removedDeadGlobs.push({ id, removedTriggers: deadInLesson, keptCount: remaining.length });
-        } else {
-          unreachableLessons.push(id);
-        }
-      }
-      unreachableLessons.sort();
+// 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 live = /* @__PURE__ */ new Set();
-  for (const kept of keptByLesson.values()) for (const t of kept) live.add(t);
-  const removedTriggerIds = Object.keys(graph.triggers).filter((t) => !live.has(t)).sort();
-  const referencedTopics = /* @__PURE__ */ new Set();
-  for (const lesson of Object.values(graph.lessons)) {
-    for (const topic of lesson.topics) referencedTopics.add(topic);
-  }
-  const removedTopicIds = Object.keys(graph.topics).filter((t) => !referencedTopics.has(t)).sort();
-  return { removedTriggerIds, removedTopicIds, trimmedLessons, removedDeadGlobs, unreachableLessons, cap };
+  });
+  const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
+  return {
+    wroteGraphPath: paths.graph,
+    deletedPaths,
+    topicCount: touchedTopics.size,
+    lessonCount: addedLessons,
+    triggerCount: addedTriggers.size
+  };
 }
-function applyPruneToGraph(graph, plan) {
-  for (const trim of [...plan.trimmedLessons, ...plan.removedDeadGlobs ?? []]) {
-    const lesson = graph.lessons[trim.id];
-    if (lesson === void 0) continue;
-    const drop = new Set(trim.removedTriggers);
-    graph.lessons[trim.id] = { ...lesson, triggers: lesson.triggers.filter((t) => !drop.has(t)) };
-  }
-  for (const topicId of plan.removedTopicIds) delete graph.topics[topicId];
-  const dead = new Set(plan.removedTriggerIds);
-  if (dead.size === 0) return;
-  for (const [id, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.triggers.some((t) => dead.has(t))) {
-      graph.lessons[id] = { ...lesson, triggers: lesson.triggers.filter((t) => !dead.has(t)) };
-    }
-  }
-  for (const t of dead) delete graph.triggers[t];
+var BASE_REL = ".agentsmesh/lessons";
+function lessonsPaths(projectRoot) {
+  const base = join(projectRoot, BASE_REL);
+  return {
+    base,
+    graph: join(base, "lessons.json"),
+    config: join(base, "config.json"),
+    journal: join(base, "journal.md"),
+    index: join(base, "index.yaml"),
+    topicsDir: join(base, "topics")
+  };
 }
-function isEmptyPrunePlan(plan) {
-  return plan.removedTriggerIds.length === 0 && plan.removedTopicIds.length === 0 && plan.trimmedLessons.length === 0 && plan.removedDeadGlobs.length === 0;
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
 }
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
 
-// src/lessons/auto-prune.ts
-function isAutoPruneEnabled(projectRoot) {
-  const path = lessonsPaths(projectRoot).config;
-  if (!existsSync(path)) return false;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed !== "object" || parsed === null) return false;
-    return parsed.autoPrune === true;
-  } catch {
-    return false;
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command> --session auto\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always --session auto\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
+
+// 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 maybeAutoPrune(projectRoot, knownPaths) {
-  if (!isAutoPruneEnabled(projectRoot)) return null;
-  const preview = tryLoadLessonsGraph(projectRoot);
-  if (preview === null) return null;
-  if (isEmptyPrunePlan(planPrune(preview, { trimOverCap: false, knownPaths }))) return null;
-  let summary = { removedTriggers: 0, removedTopics: 0, detachedDeadGlobs: 0 };
-  await mutateLessonsGraph(projectRoot, (graph) => {
-    const plan = planPrune(graph, { trimOverCap: false, knownPaths });
-    if (isEmptyPrunePlan(plan)) return;
-    applyPruneToGraph(graph, plan);
-    summary = {
-      removedTriggers: plan.removedTriggerIds.length,
-      removedTopics: plan.removedTopicIds.length,
-      detachedDeadGlobs: plan.removedDeadGlobs.reduce((n, t) => n + t.removedTriggers.length, 0)
-    };
-  });
-  const total = summary.removedTriggers + summary.removedTopics + summary.detachedDeadGlobs;
-  return total > 0 ? summary : null;
-}
-function appendJsonl(path, record, opts) {
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}
-`, "utf8");
-  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
-}
-function capJsonl(path, maxRecords) {
-  if (!existsSync(path)) return;
-  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
-  if (lines.length <= maxRecords) return;
-  const kept = lines.slice(lines.length - maxRecords);
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${kept.join("\n")}
-`, "utf8");
-  renameSync(tmp, path);
-}
-function readJsonl(path) {
-  if (!existsSync(path)) return [];
-  const out = [];
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (line.trim().length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch {
+};
+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
+      });
     }
   }
-  return out;
-}
-var MAX_RECALL_LOG_RECORDS = 5e3;
-var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
-var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
-var SESSION_ENV = "AGENTSMESH_SESSION_ID";
-function sessionId(env = process.env) {
-  const raw = env[SESSION_ENV];
-  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
-}
-function recallLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
-}
-function isTelemetryEnabled(env = process.env) {
-  return env[TELEMETRY_ENV] === "1";
-}
-function appendRecallRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env)) return;
-  appendJsonl(recallLogPath(projectRoot), record, {
-    maxRecords: MAX_RECALL_LOG_RECORDS,
-    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
+  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 = CURRENT_GRAPH_VERSION;
+    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/capture-telemetry.ts
-var MAX_CAPTURE_LOG_RECORDS = 5e3;
-var CAPTURE_LOG_TRIM_TRIGGER_BYTES = 2e6;
-function captureLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
-}
-function appendCaptureRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env)) return;
-  appendJsonl(captureLogPath(projectRoot), record, {
-    maxRecords: MAX_CAPTURE_LOG_RECORDS,
-    trimTriggerBytes: CAPTURE_LOG_TRIM_TRIGGER_BYTES
-  });
-}
-function recordCapture(projectRoot, triggerKinds, result, env = process.env) {
-  if (!isTelemetryEnabled(env)) return;
-  const session = sessionId(env);
-  appendCaptureRecord(
-    projectRoot,
-    {
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      isNewLesson: result?.isNewLesson ?? false,
-      isNewTopic: result?.isNewTopic ?? false,
-      newTriggerCount: result?.newTriggerIds.length ?? 0,
-      triggerKinds,
-      blocked: result === null,
-      warningCodes: result?.warnings.map((w) => w.code) ?? [],
-      ...session !== void 0 ? { session } : {},
-      ...result !== null ? { lessonId: result.id } : {}
-    },
-    env
-  );
-}
-function normalizeRecallFile(file, projectRoot) {
-  const forward = file.replaceAll("\\", "/");
-  const direct = relativize(projectRoot, forward);
-  if (!direct.startsWith("../")) return direct;
-  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
-  return viaReal.startsWith("../") ? direct : viaReal;
-}
-function relativize(root, forward) {
-  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
-  return rel === "" ? forward.replaceAll("\\", "/") : rel;
-}
-function safeRealpath(path) {
-  try {
-    return realpathSync(path);
-  } catch {
-    const parent = dirname(path);
-    if (parent === path) return path;
-    return resolve(safeRealpath(parent), basename(path));
-  }
+// 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}`;
 }
-var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
-var MAX_FILES = 2e5;
-function listProjectFiles(projectRoot) {
-  const out = /* @__PURE__ */ new Set();
+async function maybeAutoMigrateLessons(projectRoot) {
+  if (existsSync(graphFilePath(projectRoot))) return false;
+  const paths = lessonsPaths(projectRoot);
+  if (!existsSync(paths.index)) return false;
   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()) {
-          out.add(toRelPath(projectRoot, join(dir, entry.name)));
-          if (out.size > MAX_FILES) return out;
-        }
-      }
-    }
-  } catch {
-    return null;
+    await importLegacyLessons(projectRoot, { migratedAt: todayIso2() });
+    return true;
+  } catch (err) {
+    if (err instanceof LessonsGraphExistsError) return false;
+    throw err;
   }
-  return out;
 }
 
 // src/lessons/keyword-match.ts
@@ -2142,6 +1891,171 @@ function triggerMatches(trigger, query, budget) {
       return keywordMatches(trigger.pattern, query);
   }
 }
+function appendJsonl(path, record, opts) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}
+`, "utf8");
+  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
+}
+function capJsonl(path, maxRecords) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length <= maxRecords) return;
+  const kept = lines.slice(lines.length - maxRecords);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${kept.join("\n")}
+`, "utf8");
+  renameSync(tmp, path);
+}
+function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/lessons/telemetry.ts
+var MAX_RECALL_LOG_RECORDS = 5e3;
+var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
+var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
+var SESSION_ENV = "AGENTSMESH_SESSION_ID";
+function sessionId(env = process.env) {
+  const raw = env[SESSION_ENV];
+  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
+}
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+}
+function isTelemetryEnabled(env = process.env) {
+  return env[TELEMETRY_ENV] === "1";
+}
+function appendRecallRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(recallLogPath(projectRoot), record, {
+    maxRecords: MAX_RECALL_LOG_RECORDS,
+    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+
+// src/lessons/cmd-fastpath.ts
+var FASTPATH_DIR = "agentsmesh-lessons-cmdidx";
+function shortHash(value) {
+  let h = 5381;
+  for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
+  return h.toString(36);
+}
+function commandFastpathCachePath(projectRoot) {
+  return join(tmpdir(), FASTPATH_DIR, `${shortHash(resolve(projectRoot))}.json`);
+}
+function currentGraphStamp(projectRoot) {
+  try {
+    const s = statSync(graphFilePath(projectRoot));
+    return { mtimeMs: s.mtimeMs, size: s.size };
+  } catch {
+    return null;
+  }
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function readCache(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const c = parsed;
+    const stamp = c.stamp;
+    if (typeof stamp?.mtimeMs !== "number" || typeof stamp.size !== "number" || !isStringArray(c.commandPatterns) || !isStringArray(c.keywordPatterns)) {
+      return null;
+    }
+    return {
+      stamp: { mtimeMs: stamp.mtimeMs, size: stamp.size },
+      commandPatterns: c.commandPatterns,
+      keywordPatterns: c.keywordPatterns
+    };
+  } catch {
+    return null;
+  }
+}
+function refreshCommandFastpath(projectRoot, graph, preReadStamp) {
+  try {
+    if (preReadStamp === null) return;
+    const stamp = currentGraphStamp(projectRoot);
+    if (stamp === null) return;
+    if (stamp.mtimeMs !== preReadStamp.mtimeMs || stamp.size !== preReadStamp.size) return;
+    const path = commandFastpathCachePath(projectRoot);
+    const existing = readCache(path);
+    if (existing !== null && existing.stamp.mtimeMs === stamp.mtimeMs && existing.stamp.size === stamp.size) {
+      return;
+    }
+    const reachable = /* @__PURE__ */ new Set();
+    for (const lesson of Object.values(graph.lessons)) {
+      if (lesson.status !== "active" || lesson.scope === "always") continue;
+      for (const t of lesson.triggers) reachable.add(t);
+    }
+    const commandPatterns = [];
+    const keywordPatterns = [];
+    for (const [id, trigger] of Object.entries(graph.triggers)) {
+      if (!reachable.has(id)) continue;
+      if (trigger.kind === "command_pattern") commandPatterns.push(trigger.pattern);
+      else if (trigger.kind === "keyword") keywordPatterns.push(trigger.pattern);
+    }
+    const cache2 = { stamp, commandPatterns, keywordPatterns };
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache2), "utf8");
+    renameSync(tmp, path);
+  } catch {
+  }
+}
+function normalizeRecallFile(file, projectRoot) {
+  const forward = file.replaceAll("\\", "/");
+  const direct = relativize(projectRoot, forward);
+  if (!direct.startsWith("../")) return direct;
+  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
+  return viaReal.startsWith("../") ? direct : viaReal;
+}
+function relativize(root, forward) {
+  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
+  return rel === "" ? forward.replaceAll("\\", "/") : rel;
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    if (parent === path) return path;
+    return resolve(safeRealpath(parent), basename(path));
+  }
+}
+
+// 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;
+}
 
 // src/lessons/ranking.ts
 var DEFAULT_RECALL_LIMIT = 10;
@@ -2236,7 +2150,8 @@ function defaultLessonsConfig() {
   return {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
-    autoPrune: false
+    autoPrune: false,
+    repairTriggers: false
   };
 }
 function positiveInt(value) {
@@ -2297,48 +2212,116 @@ function loadEffectiveness(projectRoot) {
   return map;
 }
 var SEEN_DIR = "agentsmesh-lessons-seen";
-function openSessionDedup(options = {}) {
-  if (options.disabled === true) return null;
-  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
-  if (id === void 0) return null;
-  const path = seenPath(id, options.projectRoot);
-  return { sessionId: id, seen: loadSeen(path), path };
-}
-function shortHash(value) {
+function shortHash2(value) {
   let h = 5381;
   for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
   return h.toString(36);
 }
-function seenPath(id, projectRoot) {
+function seenStorePath(id, projectRoot) {
   const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 200);
-  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash(resolve(projectRoot))}`;
+  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash2(resolve(projectRoot))}`;
   return join(tmpdir(), SEEN_DIR, `${scoped}.json`);
 }
-function loadSeen(path) {
-  if (!existsSync(path)) return /* @__PURE__ */ new Set();
+function readSeenStore(path) {
+  if (!existsSync(path)) return { ids: /* @__PURE__ */ new Set(), stamps: null };
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
-    return new Set(parsed.filter((x) => typeof x === "string"));
+    if (Array.isArray(parsed)) {
+      const ids = new Set(parsed.filter((x) => typeof x === "string"));
+      return { ids, stamps: null };
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      const seen = parsed.seen;
+      if (typeof seen === "object" && seen !== null) {
+        const stamps = /* @__PURE__ */ new Map();
+        for (const [id, ms] of Object.entries(seen)) {
+          if (typeof ms === "number") stamps.set(id, ms);
+        }
+        const lastAt = parsed.lastAt;
+        return {
+          ids: new Set(stamps.keys()),
+          stamps,
+          ...typeof lastAt === "number" ? { lastAt } : {}
+        };
+      }
+    }
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
+  } catch {
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
+  }
+}
+function writeSeenStore(path, data, lastAt) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const body = data instanceof Map ? JSON.stringify({ v: 2, lastAt: lastAt ?? Date.now(), seen: Object.fromEntries(data) }) : JSON.stringify(data);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body, "utf8");
+    renameSync(tmp, path);
   } catch {
-    return /* @__PURE__ */ new Set();
   }
 }
+var AUTO_SESSION_IDLE_MS = 30 * 60 * 1e3;
+var FUTURE_TOLERANCE_MS = 6e4;
+function stampAgeMs(stamp, now = Date.now()) {
+  if (stamp - now > FUTURE_TOLERANCE_MS) return Number.POSITIVE_INFINITY;
+  return Math.max(0, now - stamp);
+}
+function isIdleSession(stamps, lastAt) {
+  if (stamps === null || stamps.size === 0) return false;
+  let newest = lastAt ?? 0;
+  for (const ms of stamps.values()) if (ms > newest) newest = ms;
+  return stampAgeMs(newest) > AUTO_SESSION_IDLE_MS;
+}
+
+// src/lessons/seen-cache.ts
+function openSessionDedup(options = {}) {
+  if (options.disabled === true) return null;
+  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
+  if (id === void 0) return null;
+  const path = seenStorePath(id, options.projectRoot);
+  const store = readSeenStore(path);
+  const stale = options.ttlMs !== void 0 && isIdleSession(store.stamps, store.lastAt);
+  const stamps = stale ? null : store.stamps;
+  return {
+    sessionId: id,
+    seen: stale ? /* @__PURE__ */ new Set() : visibleSeen(store.ids, stamps, options.ttlMs),
+    path,
+    stamps,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+  };
+}
+function visibleSeen(ids, stamps, ttlMs) {
+  if (ttlMs === void 0) return ids;
+  if (stamps === null) return /* @__PURE__ */ new Set();
+  const now = Date.now();
+  const fresh = /* @__PURE__ */ new Set();
+  for (const [id, ms] of stamps) if (stampAgeMs(ms, now) <= ttlMs) fresh.add(id);
+  return fresh;
+}
 function filterUnseen(dedup, matches) {
   return matches.filter((m) => !dedup.seen.has(m.id));
 }
 function commitSeen(dedup, returnedIds) {
-  if (returnedIds.length === 0) return;
+  if (returnedIds.length === 0) {
+    if (dedup.ttlMs !== void 0 && dedup.stamps !== null) {
+      writeSeenStore(dedup.path, dedup.stamps);
+    }
+    return;
+  }
+  if (dedup.ttlMs !== void 0 || dedup.stamps !== null) {
+    const now = Date.now();
+    const merged = /* @__PURE__ */ new Map();
+    for (const [id, ms] of dedup.stamps ?? []) {
+      if (dedup.ttlMs === void 0 || now - ms <= dedup.ttlMs) merged.set(id, ms);
+    }
+    for (const id of returnedIds) merged.set(id, now);
+    writeSeenStore(dedup.path, merged);
+    return;
+  }
   const union3 = new Set(dedup.seen);
   for (const id of returnedIds) union3.add(id);
   if (union3.size === dedup.seen.size) return;
-  try {
-    mkdirSync(dirname(dedup.path), { recursive: true });
-    const tmp = `${dedup.path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify([...union3]), "utf8");
-    renameSync(tmp, dedup.path);
-  } catch {
-  }
+  writeSeenStore(dedup.path, [...union3]);
 }
 
 // src/lessons/recall.ts
@@ -2347,6 +2330,7 @@ async function recallLessons(projectRoot, query, options = {}) {
     await maybeAutoMigrateLessons(projectRoot);
   } catch {
   }
+  const preReadStamp = currentGraphStamp(projectRoot);
   const load = loadLessonsGraphResilient(projectRoot);
   if (load.status === "corrupt") {
     return { lessons: [], totalMatches: 0, suppressed: 0, corrupt: true };
@@ -2356,12 +2340,14 @@ async function recallLessons(projectRoot, query, options = {}) {
   }
   if (load.status === "absent") return { lessons: [], totalMatches: 0, suppressed: 0 };
   const graph = load.graph;
+  refreshCommandFastpath(projectRoot, graph, preReadStamp);
   const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
   const matches = queryLessons(graph, matchQuery);
   const dedup = openSessionDedup({
     explicit: options.sessionId,
     disabled: options.noDedup,
-    projectRoot
+    projectRoot,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
   });
   const forRank = dedup === null ? matches : filterUnseen(dedup, matches);
   const cfg = loadRecallConfig(projectRoot);
@@ -2369,22 +2355,27 @@ async function recallLessons(projectRoot, query, options = {}) {
     limit: options.limit ?? cfg.limit,
     maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens,
     // Down-rank proven fire-but-fail lessons (empty ⇒ neutral, so recall is
-    // unchanged until the outcome log has real signal). Read from the side-channel.
-    effectiveness: loadEffectiveness(projectRoot)
+    // unchanged until the outcome log has real signal). Read from the side-channel
+    // only when something survived matching+dedup — a no-match recall must not pay
+    // the (up to 2MB) outcome-log read for a ranking of nothing.
+    effectiveness: forRank.length === 0 ? /* @__PURE__ */ new Map() : loadEffectiveness(projectRoot)
   });
   if (dedup !== null)
     commitSeen(
       dedup,
       lessons.map((l) => l.id)
     );
-  recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, { bypassed: false });
+  recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, {
+    bypassed: false,
+    session: options.sessionId
+  });
   return { lessons, totalMatches: matches.length, suppressed: matches.length - forRank.length };
 }
 function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, options = {}) {
   if (!isTelemetryEnabled()) return;
   const byKind = collectMatchedTriggersByKind(graph, query);
   const countVia = (set) => matches.filter(({ lesson }) => lesson.triggers.some((t) => set.has(t))).length;
-  const session = sessionId();
+  const session = options.session ?? sessionId();
   appendRecallRecord(projectRoot, {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     hasFile: query.file !== void 0,
@@ -2404,6 +2395,255 @@ function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, opti
     ...session !== void 0 ? { session } : {}
   });
 }
+
+// src/lessons/prune.ts
+function planPrune(graph, options = {}) {
+  const cap = Math.max(1, options.cap ?? MAX_RECOMMENDED_TRIGGERS);
+  const fanout = buildFanout(graph);
+  const trimmedLessons = [];
+  const keptByLesson = /* @__PURE__ */ new Map();
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (options.trimOverCap === false || lesson.triggers.length <= cap) {
+      keptByLesson.set(id, lesson.triggers);
+      continue;
+    }
+    const ordered = [...lesson.triggers].sort((a, b) => {
+      const fa = fanout.get(a);
+      const fb = fanout.get(b);
+      return fa !== fb ? fa - fb : a < b ? -1 : 1;
+    });
+    const drop = new Set(ordered.slice(cap));
+    const kept = lesson.triggers.filter((t) => !drop.has(t));
+    keptByLesson.set(id, kept);
+    trimmedLessons.push({ id, removedTriggers: [...drop], keptCount: kept.length });
+  }
+  const removedDeadGlobs = [];
+  const unreachableLessons = [];
+  if (options.knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, options.knownPaths);
+    if (dead.size > 0) {
+      for (const [id, kept] of keptByLesson) {
+        const deadInLesson = kept.filter((t) => dead.has(t));
+        if (deadInLesson.length === 0) continue;
+        const remaining = kept.filter((t) => !dead.has(t));
+        if (remaining.length >= 1) {
+          keptByLesson.set(id, remaining);
+          removedDeadGlobs.push({ id, removedTriggers: deadInLesson, keptCount: remaining.length });
+        } else {
+          unreachableLessons.push(id);
+        }
+      }
+      unreachableLessons.sort();
+    }
+  }
+  const live = /* @__PURE__ */ new Set();
+  for (const kept of keptByLesson.values()) for (const t of kept) live.add(t);
+  const removedTriggerIds = Object.keys(graph.triggers).filter((t) => !live.has(t)).sort();
+  const referencedTopics = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    for (const topic of lesson.topics) referencedTopics.add(topic);
+  }
+  const removedTopicIds = Object.keys(graph.topics).filter((t) => !referencedTopics.has(t)).sort();
+  return { removedTriggerIds, removedTopicIds, trimmedLessons, removedDeadGlobs, unreachableLessons, cap };
+}
+function applyPruneToGraph(graph, plan) {
+  for (const trim of [...plan.trimmedLessons, ...plan.removedDeadGlobs ?? []]) {
+    const lesson = graph.lessons[trim.id];
+    if (lesson === void 0) continue;
+    const drop = new Set(trim.removedTriggers);
+    graph.lessons[trim.id] = { ...lesson, triggers: lesson.triggers.filter((t) => !drop.has(t)) };
+  }
+  for (const topicId of plan.removedTopicIds) delete graph.topics[topicId];
+  const dead = new Set(plan.removedTriggerIds);
+  if (dead.size === 0) return;
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.triggers.some((t) => dead.has(t))) {
+      graph.lessons[id] = { ...lesson, triggers: lesson.triggers.filter((t) => !dead.has(t)) };
+    }
+  }
+  for (const t of dead) delete graph.triggers[t];
+}
+function isEmptyPrunePlan(plan) {
+  return plan.removedTriggerIds.length === 0 && plan.removedTopicIds.length === 0 && plan.trimmedLessons.length === 0 && plan.removedDeadGlobs.length === 0;
+}
+
+// src/lessons/auto-prune.ts
+function isAutoPruneEnabled(projectRoot) {
+  const path = lessonsPaths(projectRoot).config;
+  if (!existsSync(path)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return false;
+    return parsed.autoPrune === true;
+  } catch {
+    return false;
+  }
+}
+async function maybeAutoPrune(projectRoot, knownPaths) {
+  if (!isAutoPruneEnabled(projectRoot)) return null;
+  const preview = tryLoadLessonsGraph(projectRoot);
+  if (preview === null) return null;
+  if (isEmptyPrunePlan(planPrune(preview, { trimOverCap: false, knownPaths }))) return null;
+  let summary = { removedTriggers: 0, removedTopics: 0, detachedDeadGlobs: 0 };
+  await mutateLessonsGraph(projectRoot, (graph) => {
+    const plan = planPrune(graph, { trimOverCap: false, knownPaths });
+    if (isEmptyPrunePlan(plan)) return;
+    applyPruneToGraph(graph, plan);
+    summary = {
+      removedTriggers: plan.removedTriggerIds.length,
+      removedTopics: plan.removedTopicIds.length,
+      detachedDeadGlobs: plan.removedDeadGlobs.reduce((n, t) => n + t.removedTriggers.length, 0)
+    };
+  });
+  const total = summary.removedTriggers + summary.removedTopics + summary.detachedDeadGlobs;
+  return total > 0 ? summary : null;
+}
+var MAX_CAPTURE_LOG_RECORDS = 5e3;
+var CAPTURE_LOG_TRIM_TRIGGER_BYTES = 2e6;
+function captureLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
+}
+function appendCaptureRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(captureLogPath(projectRoot), record, {
+    maxRecords: MAX_CAPTURE_LOG_RECORDS,
+    trimTriggerBytes: CAPTURE_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+function recordCapture(projectRoot, triggerKinds, result, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  const session = sessionId(env);
+  appendCaptureRecord(
+    projectRoot,
+    {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      isNewLesson: result?.isNewLesson ?? false,
+      isNewTopic: result?.isNewTopic ?? false,
+      newTriggerCount: result?.newTriggerIds.length ?? 0,
+      triggerKinds,
+      blocked: result === null,
+      warningCodes: result?.warnings.map((w) => w.code) ?? [],
+      ...session !== void 0 ? { session } : {},
+      ...result !== null ? { lessonId: result.id } : {}
+    },
+    env
+  );
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
+var MAX_FILES = 2e5;
+function listProjectFiles(projectRoot) {
+  const out = /* @__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()) {
+          out.add(toRelPath(projectRoot, join(dir, entry.name)));
+          if (out.size > MAX_FILES) return out;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return out;
+}
+function isTriggerRepairEnabled(projectRoot) {
+  const path = lessonsPaths(projectRoot).config;
+  if (!existsSync(path)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return false;
+    return parsed.repairTriggers === true;
+  } catch {
+    return false;
+  }
+}
+function evidencePath(evidence, knownPaths) {
+  for (const entry of evidence ?? []) {
+    const candidate = entry.replaceAll("\\", "/").replace(/(:\d+)+$/, "").trim();
+    if (knownPaths.has(candidate)) return candidate;
+  }
+  return void 0;
+}
+function classGlobFor(path) {
+  const slash = path.lastIndexOf("/");
+  const dir = slash === -1 ? "" : path.slice(0, slash + 1);
+  const base = path.slice(slash + 1);
+  const dot = base.lastIndexOf(".");
+  return `${dir}*${dot > 0 ? base.slice(dot) : ""}`;
+}
+function repairFileGlobs(files, evidence, knownPaths, repairs) {
+  const out = [];
+  for (const glob of files) {
+    const needsNarrow = knownPaths !== void 0 && (isBroadGlob(glob) || fileGlobMatchCount(glob, knownPaths) > WIDE_GLOB_MATCH_COUNT);
+    if (!needsNarrow || evidence === void 0 || !picomatch(glob, { dot: true })(evidence)) {
+      if (!out.includes(glob)) out.push(glob);
+      continue;
+    }
+    const derived = classGlobFor(evidence);
+    const derivedOk = derived !== glob && picomatch(derived, { dot: true })(evidence) && fileGlobMatchCount(derived, knownPaths) <= fileGlobMatchCount(glob, knownPaths);
+    if (!derivedOk) {
+      if (!out.includes(glob)) out.push(glob);
+      continue;
+    }
+    if (!out.includes(derived)) out.push(derived);
+    repairs.push({
+      code: "NARROWED_GLOB",
+      message: `Narrowed broad file glob "${glob}" to the evidence file's class "${derived}". Review: for general/library behavior, re-point at the file-CLASS recurrence surface (a '**/.../*Name*.ts'-style glob) where the rule will actually recur.`
+    });
+  }
+  return out;
+}
+function repairKeywords(keywords, repairs) {
+  const out = [];
+  for (const kw of keywords) {
+    const tokens = tokenize(kw);
+    if (tokens.length === 0) {
+      repairs.push({
+        code: "DROPPED_KEYWORD",
+        message: `Dropped keyword trigger "${kw}" \u2014 it tokenizes to nothing (stopwords/short words only) and can never fire.`
+      });
+      continue;
+    }
+    if (!out.includes(kw)) out.push(kw);
+    if (!keywordNeedleLosesTokens(kw) && !isLowSignalKeyword(kw)) continue;
+    const variant = tokens.slice(0, MAX_RECOMMENDED_KEYWORD_TOKENS).join(" ");
+    if (variant.toLowerCase() === kw.toLowerCase() || out.includes(variant)) continue;
+    out.push(variant);
+    repairs.push({
+      code: "KEYWORD_VARIANT_ADDED",
+      message: `Keyword trigger "${kw}" cannot match on the mandatory --file/--cmd token path; added the matchable variant "${variant}" beside it (the original still matches prompt text).`
+    });
+  }
+  return out;
+}
+function repairTriggers(input, knownPaths) {
+  const repairs = [];
+  const evidence = knownPaths === void 0 ? void 0 : evidencePath(input.evidence, knownPaths);
+  const files = input.triggers.files === void 0 ? void 0 : repairFileGlobs(input.triggers.files, evidence, knownPaths, repairs);
+  const keywords = input.triggers.keywords === void 0 ? void 0 : repairKeywords(input.triggers.keywords, repairs);
+  if (repairs.length === 0) return { input, repairs };
+  const total = (files?.length ?? 0) + (input.triggers.commands?.length ?? 0) + (keywords?.length ?? 0);
+  if (total === 0) return { input, repairs: [] };
+  return {
+    input: {
+      ...input,
+      triggers: {
+        ...files !== void 0 ? { files } : {},
+        ...input.triggers.commands !== void 0 ? { commands: input.triggers.commands } : {},
+        ...keywords !== void 0 ? { keywords } : {}
+      }
+    },
+    repairs
+  };
+}
+
+// src/lessons/capture.ts
 async function captureLesson(projectRoot, input, options = {}) {
   await maybeAutoMigrateLessons(projectRoot);
   const triggerKinds = {
@@ -2412,11 +2652,14 @@ async function captureLesson(projectRoot, input, options = {}) {
     keyword: input.triggers.keywords?.length ?? 0
   };
   const knownPaths = options.knownPaths ?? listProjectFiles(projectRoot) ?? void 0;
+  const repair = isTriggerRepairEnabled(projectRoot) ? repairTriggers(input, knownPaths) : null;
+  const effective = repair === null ? input : repair.input;
   try {
-    const result = await addLesson(projectRoot, input, { ...options, knownPaths });
-    recordCapture(projectRoot, triggerKinds, result);
+    const result = await addLesson(projectRoot, effective, { ...options, knownPaths });
+    const repaired = repair === null || repair.repairs.length === 0 ? result : { ...result, warnings: [...result.warnings, ...repair.repairs] };
+    recordCapture(projectRoot, triggerKinds, repaired);
     const autoPruned = await maybeAutoPrune(projectRoot, knownPaths);
-    return autoPruned === null ? result : { ...result, autoPruned };
+    return autoPruned === null ? repaired : { ...repaired, autoPruned };
   } catch (err) {
     recordCapture(projectRoot, triggerKinds, null);
     throw err;
@@ -2736,6 +2979,17 @@ ${placed}` : placed;
 
 // src/targets/projection/lessons-paragraph.ts
 var LEGACY_RAW_FORMS = [
+  // Pre-`--session auto` wording (2026-07): strip sentinel-less copies so a
+  // project scaffolded before the dedup correlator dedups on the next scaffold.
+  `## Lessons (BLOCKING)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`,
   `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
 
 Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
@@ -2793,14 +3047,18 @@ regression / wrong assumption / surprise and you have not captured (nor stated
 
 ## Recall \u2014 before each edit/command, and at task start
 
-\`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule.
-Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
+\`agentsmesh lessons query --file <path> --cmd <command> --session auto\`, then apply every
+rule. Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
 for a specific edit is the anti-pattern** \u2014 anchor those to \`--file\`/\`--cmd\`. But at the
 START of a task (or when planning), run \`agentsmesh lessons query --keyword "<the task's
-key terms>" --always\`: that surfaces the conceptual rules no file/command names PLUS the
-universal always-on lessons \u2014 the manual equivalent of the automatic prompt recall on
-hook-capable tools. Author a \`keyword\` trigger beside a \`file_glob\` on conceptual lessons
-so they are reachable both ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`).
+key terms>" --always --session auto\`: that surfaces the conceptual rules no file/command
+names PLUS the universal always-on lessons \u2014 the manual equivalent of the automatic prompt
+recall on hook-capable tools. **Always pass \`--session auto\`**: it suppresses rules already
+shown this session so repeat recalls stay quiet (without it every recall re-delivers the
+whole matched set); \`--no-dedup\` re-shows everything after a context reset. Author a
+\`keyword\` trigger beside a \`file_glob\` on conceptual lessons so they are reachable both
+ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`; session dedup
+is on by default there \u2014 \`no_dedup:true\` to re-show).
 
 ## Capture \u2014 Gate Function (before any completion claim)