@fenglimg/fabric-server 2.0.0-rc.22 → 2.0.0-rc.25

package/dist/{chunk-7N3FW5LX.js → chunk-HAXROPQM.js}

@@ -160,8 +160,8 @@ function getLegacyLedgerPath(projectRoot) {
 function getEventLedgerPath(projectRoot) {
   return join2(projectRoot, EVENT_LEDGER_PATH);
 }
-async function ensureParentDirectory(path) {
-  await mkdir(dirname(path), { recursive: true });
+async function ensureParentDirectory(path2) {
+  await mkdir(dirname(path2), { recursive: true });
 }
 function sha256(content) {
   return `sha256:${createHash("sha256").update(content).digest("hex")}`;
@@ -241,24 +241,24 @@ async function readEventLedger(projectRoot, options = {}) {
   const events = lines.map((line) => line.trim()).filter((line) => line.length > 0).map((line, index) => parseEventLedgerLine(line, index)).filter((entry) => entry !== null).filter((entry) => options.event_type === void 0 || entry.event_type === options.event_type).filter((entry) => options.since === void 0 || entry.ts >= options.since).filter((entry) => options.correlation_id === void 0 || entry.correlation_id === options.correlation_id).filter((entry) => options.session_id === void 0 || entry.session_id === options.session_id);
   return { events, warnings };
 }
-async function truncateLedgerToLastNewline(path) {
-  const raw = await readFile2(path);
+async function truncateLedgerToLastNewline(path2) {
+  const raw = await readFile2(path2);
   const content = raw.toString("utf8");
   if (content.endsWith("\n") || content.length === 0) {
     return { truncated_bytes: 0, corrupted_path: "" };
   }
   const lastNewlineIndex = content.lastIndexOf("\n");
   if (lastNewlineIndex === -1) {
-    const corruptedPath2 = `${path}.corrupted.${Date.now()}`;
+    const corruptedPath2 = `${path2}.corrupted.${Date.now()}`;
     await writeFile(corruptedPath2, raw);
-    await truncate(path, 0);
+    await truncate(path2, 0);
     return { truncated_bytes: raw.length, corrupted_path: corruptedPath2 };
   }
   const keepByteLength = Buffer.byteLength(content.slice(0, lastNewlineIndex + 1), "utf8");
   const corruptedBytes = raw.slice(keepByteLength);
-  const corruptedPath = `${path}.corrupted.${Date.now()}`;
+  const corruptedPath = `${path2}.corrupted.${Date.now()}`;
   await writeFile(corruptedPath, corruptedBytes);
-  await truncate(path, keepByteLength);
+  await truncate(path2, keepByteLength);
   return { truncated_bytes: corruptedBytes.length, corrupted_path: corruptedPath };
 }
 function parseEventLedgerLine(line, index) {
@@ -428,6 +428,27 @@ import {
   parseKnowledgeId
 } from "@fenglimg/fabric-shared";
 import { atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
+async function loadKbIdTypeMap(projectRootInput) {
+  const projectRoot = normalizeProjectRoot(projectRootInput);
+  const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
+  const meta = await readExistingMeta(metaPath);
+  const map = /* @__PURE__ */ new Map();
+  if (meta === void 0) {
+    return map;
+  }
+  for (const node of Object.values(meta.nodes)) {
+    const stableId = node.stable_id;
+    if (stableId === void 0 || !isKnowledgeStableId(stableId)) {
+      continue;
+    }
+    const knowledgeType = node.description?.knowledge_type;
+    if (knowledgeType === void 0) {
+      continue;
+    }
+    map.set(stableId, knowledgeType);
+  }
+  return map;
+}
 async function buildKnowledgeMeta(projectRootInput) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   assertExistingDirectory(projectRoot);
@@ -870,8 +891,8 @@ function flattenKeys(value, keys = {}) {
   }
   return keys;
 }
-function toPosixPath(path) {
-  return path.split(sep2).join("/");
+function toPosixPath(path2) {
+  return path2.split(sep2).join("/");
 }
 function deriveRuleIdentity(file, source, existing) {
   const declaredKnowledgeId = extractDeclaredKnowledgeId(source);
@@ -959,7 +980,7 @@ function extractRuleDescription(source) {
   };
 }
 function extractRuleSections(source) {
-  const sections = Array.from(source.matchAll(/^(?:#{2,6})\s+\[([A-Z_]+)\]\s*$/gmu)).map((match) => match[1]).filter((section, index, all) => all.indexOf(section) === index);
+  const sections = Array.from(source.matchAll(/^#{2,6}\s+(.+?)\s*$/gmu)).map((match) => match[1].trim()).filter((section, index, all) => section.length > 0 && all.indexOf(section) === index);
   return sections.length > 0 ? sections : void 0;
 }
 function extractDescriptionFromFrontmatter(frontmatter) {
@@ -1147,11 +1168,11 @@ async function readMetaEntries(projectRoot) {
     return map;
   }
   for (const node of Object.values(parsed.nodes ?? {})) {
-    const path = node.content_ref ?? node.file;
+    const path2 = node.content_ref ?? node.file;
     const stable_id = node.stable_id;
     const content_hash = node.hash;
-    if (path !== void 0 && stable_id !== void 0 && content_hash !== void 0) {
-      map.set(path, { stable_id, path, content_hash });
+    if (path2 !== void 0 && stable_id !== void 0 && content_hash !== void 0) {
+      map.set(path2, { stable_id, path: path2, content_hash });
     }
   }
   return map;
@@ -1407,7 +1428,8 @@ async function reconcileKnowledge(projectRoot, opts) {
       throw error;
     }
   }
-  if (events.length > 0 || revisionDrift) {
+  const forceWriteForDescriptionHeal = trigger === "auto-heal-description";
+  if (events.length > 0 || revisionDrift || forceWriteForDescriptionHeal) {
     await writeKnowledgeMeta(projectRoot, { source: "sync_meta" });
     if (events.length > 0) {
       await appendRuleSyncEvents(projectRoot, events);
@@ -1417,7 +1439,7 @@ async function reconcileKnowledge(projectRoot, opts) {
   }
   const duration_ms = Date.now() - startTime;
   const reconciledFiles = events.map((e) => e.path);
-  if (trigger !== void 0 && (events.length > 0 || revisionDrift)) {
+  if (trigger !== void 0 && (events.length > 0 || revisionDrift || forceWriteForDescriptionHeal)) {
     if (trigger === "startup") {
       await appendEventLedgerEvent(projectRoot, {
         event_type: "meta_reconciled_on_startup",
@@ -1448,10 +1470,103 @@ async function reconcileKnowledge(projectRoot, opts) {
   };
 }
 
+// src/services/serve-lock.ts
+import fs from "fs";
+import path from "path";
+import { createTranslator, detectNodeLocale } from "@fenglimg/fabric-shared";
+import { IOFabricError as IOFabricError2 } from "@fenglimg/fabric-shared/errors";
+var LOCK_FILENAME = ".serve.lock";
+var t = createTranslator(detectNodeLocale());
+var ServeLockHeldError = class extends IOFabricError2 {
+  code = "SERVE_LOCK_HELD";
+  httpStatus = 423;
+};
+function lockPath(projectRoot) {
+  return path.join(projectRoot, ".fabric", LOCK_FILENAME);
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    const err = e;
+    if (err.code === "ESRCH") return false;
+    if (err.code === "EPERM") return true;
+    throw e;
+  }
+}
+function acquireLock(projectRoot, opts) {
+  const p = lockPath(projectRoot);
+  if (fs.existsSync(p)) {
+    let state = null;
+    try {
+      state = JSON.parse(fs.readFileSync(p, "utf8"));
+    } catch {
+    }
+    if (state && state.pid && state.pid !== process.pid && isAlive(state.pid) && !opts?.force) {
+      throw new ServeLockHeldError(
+        `serve lock held by live PID ${state.pid}`,
+        {
+          actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
+          details: state
+        }
+      );
+    }
+    if (state && state.pid && !isAlive(state.pid)) {
+      process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 overwriting
+`);
+    }
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(
+    p,
+    JSON.stringify({ pid: process.pid, acquiredAt: Date.now(), host: process.env.HOSTNAME })
+  );
+}
+function releaseLock(projectRoot) {
+  const p = lockPath(projectRoot);
+  try {
+    if (fs.existsSync(p)) {
+      const state = JSON.parse(fs.readFileSync(p, "utf8"));
+      if (state.pid === process.pid) {
+        fs.unlinkSync(p);
+      }
+    }
+  } catch {
+  }
+}
+function readLockState(projectRoot) {
+  const p = lockPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function checkLockOrThrow(projectRoot, opts) {
+  const state = readLockState(projectRoot);
+  if (state === null) return;
+  if (state.pid === process.pid) return;
+  if (!isAlive(state.pid)) {
+    process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 ignoring
+`);
+    return;
+  }
+  if (opts?.force) return;
+  throw new ServeLockHeldError(
+    `serve lock held by live PID ${state.pid}`,
+    {
+      actionHint: t("cli.serve.lock-held.action-hint", { pid: String(state.pid) }),
+      details: state
+    }
+  );
+}
+
 // src/services/doctor.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync2, statSync as statSync4 } from "fs";
-import { access, mkdir as mkdir4, readFile as readFile5, rename, writeFile as writeFile2 } from "fs/promises";
+import { access, mkdir as mkdir4, readFile as readFile5, rename, unlink, writeFile as writeFile2 } from "fs/promises";
 import { constants } from "fs";
 import { homedir as homedir3 } from "os";
 import { isAbsolute as isAbsolute2, join as join6, posix, relative as nodeRelative, resolve as resolve3, sep as sep3 } from "path";
@@ -1466,7 +1581,9 @@ import {
   BOOTSTRAP_CANONICAL,
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
-  BOOTSTRAP_REGEX
+  BOOTSTRAP_REGEX,
+  ONBOARD_SLOT_NAMES,
+  ONBOARD_SLOT_TOTAL
 } from "@fenglimg/fabric-shared";
 import { detectFramework } from "@fenglimg/fabric-shared/node";
 import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText4 } from "@fenglimg/fabric-shared/node/atomic-write";
@@ -1600,8 +1717,10 @@ async function runDoctorReport(target) {
   const relevancePathsDrift = inspectRelevancePathsDrift(projectRoot);
   const narrowTooFew = inspectNarrowTooFew(projectRoot, lintNow);
   const sessionHintsStale = inspectSessionHintsStale(projectRoot, lintNow);
+  const staleServeLock = inspectStaleServeLock(projectRoot, lintNow);
   const relevanceFieldsMissing = inspectRelevanceFieldsMissing(projectRoot);
   const skillMdYamlInvalid = inspectSkillMdYamlInvalid(projectRoot);
+  const onboardCoverage = inspectOnboardCoverage(projectRoot);
   const checks = [
     createBootstrapAnchorCheck(bootstrapAnchor),
     // v2.0.0-rc.19 TASK-004: bootstrap marker migration check sits adjacent to
@@ -1616,7 +1735,8 @@ async function runDoctorReport(target) {
     createKnowledgeDirMissingCheck(knowledgeDirMissing),
     // v2.0.0-rc.22 TASK-006: baseline filename format. Sits adjacent to
     // knowledge_dir_missing — both are knowledge-layout invariants. manual_error
-    // kind; resolution delegates to `fab scan` (no --fix path).
+    // kind; resolution is manual file deletion (rc.23 TASK-012 (F8a) removed
+    // the baseline-emit pipeline, so no auto-fix exists).
     createBaselineFilenameFormatCheck(baselineFilenameFormat),
     createForensicCheck(forensic, framework.kind, entryPoints.length),
     // v2.0: removed `createInitContextCheck` — `.fabric/init-context.json`
@@ -1670,6 +1790,10 @@ async function runDoctorReport(target) {
     createNarrowTooFewCheck(narrowTooFew),
     // rc.6 TASK-021 (E3): session-hints cache hygiene (lint #27). Info kind.
     createSessionHintsStaleCheck(sessionHintsStale),
+    // rc.23 TASK-010 (e): stale .fabric/.serve.lock advisory. Info kind —
+    // does not bump report status. `--fix` unlinks the corpse and emits
+    // `serve_lock_cleared`.
+    createStaleServeLockCheck(staleServeLock),
     // v2.0.0-rc.9 TASK-003 (A3): relevance fields back-fill (lint #28).
     // Info kind — applies to pending entries only; canonical entries get
     // the fields written verbatim by fab_review.approve/modify.
@@ -1677,6 +1801,11 @@ async function runDoctorReport(target) {
     // rc.12 lint #29: skill_md_yaml_invalid. Warning kind — surfaces
     // SKILL.md frontmatter that Codex CLI silently drops at load.
     createSkillMdYamlInvalidCheck(skillMdYamlInvalid),
+    // v2.0.0-rc.23 TASK-014 (F8c): Onboard coverage advisory. Info kind.
+    // Surfaces uncovered S5 onboard slots and recommends /fabric-archive
+    // first-run phase. Sits adjacent to Skill markdown YAML — both are
+    // Skill-adjacent advisories. --fix never mutates onboard state.
+    createOnboardCoverageCheck(onboardCoverage),
     createPreexistingRootFilesCheck(preexistingRootFiles)
     // v2.0 / rc.2: `createLegacyClientPathCheck` removed. The schema now
     // rejects retired clientPaths keys (windsurf/rooCode/geminiCLI) at Zod
@@ -1717,7 +1846,7 @@ async function runDoctorReport(target) {
       warningCount: warnings.length,
       infoCount: infos.length,
       targetFiles: Object.fromEntries(
-        TARGET_FILE_PATHS.map((path) => [path, existsSync4(join6(projectRoot, path))])
+        TARGET_FILE_PATHS.map((path2) => [path2, existsSync4(join6(projectRoot, path2))])
       )
     }
   };
@@ -1731,11 +1860,11 @@ async function runDoctorFix(target) {
   )) {
     const migrated = await migrateBootstrapMarkers(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "bootstrap_marker_migration_required"));
-    for (const path of migrated.paths) {
+    for (const path2 of migrated.paths) {
       await appendEventLedgerEvent(projectRoot, {
         event_type: "bootstrap_marker_migrated",
-        path,
-        migrated_count: migrated.countPerPath[path] ?? 1,
+        path: path2,
+        migrated_count: migrated.countPerPath[path2] ?? 1,
         legacy_marker: "fabric:knowledge-base",
         new_marker: "fabric:bootstrap",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -1814,6 +1943,31 @@ async function runDoctorFix(target) {
     await fixMcpConfigInWrongFile(projectRoot);
     fixed.push(findIssue(before.fixable_errors, "mcp_config_in_wrong_file"));
   }
+  if (before.infos.some((issue) => issue.code === "stale_serve_lock")) {
+    const lockInspection = inspectStaleServeLock(projectRoot, Date.now());
+    if (lockInspection.present && !lockInspection.pidAlive) {
+      const lockFilePath = join6(projectRoot, ".fabric", ".serve.lock");
+      try {
+        await unlink(lockFilePath);
+      } catch (err) {
+        const errno = err;
+        if (errno.code !== "ENOENT") throw err;
+      }
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "serve_lock_cleared",
+        pid: lockInspection.pid,
+        age_ms: lockInspection.ageMs,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }).catch(() => {
+      });
+      fixed.push({
+        code: "stale_serve_lock",
+        name: "Serve lock",
+        message: `Removed stale .fabric/.serve.lock (dead PID ${lockInspection.pid}).`,
+        path: ".fabric/.serve.lock"
+      });
+    }
+  }
   const report = await runDoctorReport(projectRoot);
   return {
     changed: fixed.length > 0,
@@ -2027,8 +2181,8 @@ async function applyStaleArchive(projectRoot, candidate, now) {
       if (renameError instanceof Error && "code" in renameError && renameError.code === "EXDEV") {
         const data = await readFile5(sourceAbs);
         await writeFile2(destAbs, data);
-        const { unlink } = await import("fs/promises");
-        await unlink(sourceAbs);
+        const { unlink: unlink2 } = await import("fs/promises");
+        await unlink2(sourceAbs);
       } else {
         throw renameError;
       }
@@ -2100,8 +2254,8 @@ async function applyPendingAutoArchive(projectRoot, candidate, now) {
         if (renameError instanceof Error && "code" in renameError && renameError.code === "EXDEV") {
           const data = await readFile5(candidate.pending_path_abs);
           await writeFile2(candidate.archived_to_abs, data);
-          const { unlink } = await import("fs/promises");
-          await unlink(candidate.pending_path_abs);
+          const { unlink: unlink2 } = await import("fs/promises");
+          await unlink2(candidate.pending_path_abs);
         } else {
           throw renameError;
         }
@@ -2158,8 +2312,8 @@ async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
   const absPath = join6(projectRoot, candidate.path);
   try {
-    const { unlink } = await import("fs/promises");
-    await unlink(absPath);
+    const { unlink: unlink2 } = await import("fs/promises");
+    await unlink2(absPath);
     return {
       kind: "knowledge_session_hints_stale_cleanup",
       path: candidate.path,
@@ -2213,9 +2367,9 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path = join6(projectRoot, ".fabric", "forensic.json");
+  const path2 = join6(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile5(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile5(path2, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -2326,15 +2480,15 @@ function inspectContentRefs(projectRoot, meta) {
   return { missing, invalid };
 }
 async function inspectEventLedger(projectRoot) {
-  const path = getEventLedgerPath(projectRoot);
-  const exists = existsSync4(path);
+  const path2 = getEventLedgerPath(projectRoot);
+  const exists = existsSync4(path2);
   if (!exists) {
-    return { exists: false, writable: false, parseable: false, hasPartialWrite: false, partialWriteByteOffset: 0, partialWriteByteLength: 0, path };
+    return { exists: false, writable: false, parseable: false, hasPartialWrite: false, partialWriteByteOffset: 0, partialWriteByteLength: 0, path: path2 };
   }
   try {
-    await access(path, constants.W_OK);
+    await access(path2, constants.W_OK);
     const { warnings } = await readEventLedger(projectRoot);
-    const raw = await readFile5(path, "utf8");
+    const raw = await readFile5(path2, "utf8");
     const invalidLine = raw.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).find((line) => !isValidJsonLine(line));
     const partialWarning = warnings.find((w) => w.kind === "partial_write_at_tail");
     return {
@@ -2344,7 +2498,7 @@ async function inspectEventLedger(projectRoot) {
       hasPartialWrite: partialWarning !== void 0,
       partialWriteByteOffset: partialWarning?.byte_offset ?? 0,
       partialWriteByteLength: partialWarning?.byte_length ?? 0,
-      path,
+      path: path2,
       error: invalidLine === void 0 ? void 0 : "events.jsonl contains an invalid JSON line."
     };
   } catch (error) {
@@ -2355,16 +2509,16 @@ async function inspectEventLedger(projectRoot) {
       hasPartialWrite: false,
       partialWriteByteOffset: 0,
       partialWriteByteLength: 0,
-      path,
+      path: path2,
       error: error instanceof Error ? error.message : String(error)
     };
   }
 }
 async function inspectKnowledgeTestIndex(projectRoot) {
-  const path = join6(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
+  const path2 = join6(projectRoot, ".fabric", ".cache", "knowledge-test.index.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
-    const index = knowledgeTestIndexSchema2.parse(JSON.parse(await readFile5(path, "utf8")));
+    const index = knowledgeTestIndexSchema2.parse(JSON.parse(await readFile5(path2, "utf8")));
     return {
       present: true,
       valid: true,
@@ -2590,8 +2744,8 @@ function inspectKnowledgeDirMissing(projectRoot) {
   const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
   const missingSubdirs = [];
   for (const sub of KNOWLEDGE_SUBDIRS3) {
-    const path = join6(knowledgeRoot, sub);
-    if (!existsSync4(path)) {
+    const path2 = join6(knowledgeRoot, sub);
+    if (!existsSync4(path2)) {
       missingSubdirs.push(`.fabric/knowledge/${sub}`);
     }
   }
@@ -2660,7 +2814,7 @@ function createBaselineFilenameFormatCheck(inspection) {
     "manual_error",
     "lint-baseline-filename-format",
     `${inspection.offenders.length} baseline knowledge file${inspection.offenders.length === 1 ? "" : "s"} use${inspection.offenders.length === 1 ? "s" : ""} the deprecated bare-slug filename format and must be migrated to \`\${id}--\${slug}.md\`. First: ${detail}.`,
-    "Run `fab scan` to auto-migrate baseline filenames to the canonical `${id}--${slug}.md` format."
+    "Delete the legacy bare-slug baseline file(s) manually \u2014 the baseline pipeline was removed in rc.23 and is no longer an auto-fix path."
   );
 }
 function createKnowledgeDirMissingCheck(inspection) {
@@ -2889,7 +3043,9 @@ function collectMdFilesUnder(out, projectRoot, rootDir, relPrefix) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const abs = join6(dir, entry.name);
       if (entry.isDirectory()) {
-        stack.push(abs);
+        if (entry.name !== "pending" && entry.name !== "archive") {
+          stack.push(abs);
+        }
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
         const rel = posix.join(relPrefix, abs.slice(rootDir.length + 1).replace(/\\/gu, "/"));
         out.add(rel);
@@ -2991,7 +3147,7 @@ function inspectCounterDesync(meta) {
       ["guideline", "GLD"],
       ["pitfall", "PIT"],
       ["process", "PRO"]
-    ].find(([t]) => t === parsed.type)?.[1];
+    ].find(([t2]) => t2 === parsed.type)?.[1];
     if (typeCode === void 0) {
       continue;
     }
@@ -3582,6 +3738,20 @@ function inspectSessionHintsStale(projectRoot, now) {
   candidates.sort((a, b) => a.path.localeCompare(b.path));
   return { candidates };
 }
+function inspectStaleServeLock(projectRoot, now) {
+  const state = readLockState(projectRoot);
+  if (state === null) {
+    return { present: false };
+  }
+  const ageMs = Math.max(0, now - state.acquiredAt);
+  return {
+    present: true,
+    pid: state.pid,
+    acquiredAt: state.acquiredAt,
+    ageMs,
+    pidAlive: isAlive(state.pid)
+  };
+}
 function inspectNarrowTooFew(projectRoot, now) {
   let total = 0;
   let narrowWithPaths = 0;
@@ -3740,6 +3910,28 @@ function createSessionHintsStaleCheck(inspection) {
     "Run `fab doctor --apply-lint` to delete stale session-hints cache files."
   );
 }
+function createStaleServeLockCheck(inspection) {
+  if (!inspection.present) {
+    return okCheck("Serve lock", "No .fabric/.serve.lock present.");
+  }
+  if (inspection.pidAlive) {
+    return okCheck(
+      "Serve lock",
+      `.fabric/.serve.lock held by live PID ${inspection.pid}.`
+    );
+  }
+  const days = Math.floor(inspection.ageMs / MS_PER_DAY);
+  const hours = Math.floor(inspection.ageMs / (60 * 60 * 1e3));
+  const acquiredAgo = days >= 1 ? `${days} day${days === 1 ? "" : "s"} ago` : `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  return issueCheck(
+    "Serve lock",
+    "ok",
+    "info",
+    "stale_serve_lock",
+    `[advisory] .fabric/.serve.lock holds dead PID ${inspection.pid} (acquired ${acquiredAgo}). Run \`fab doctor --fix\` to remove.`,
+    "Run `fab doctor --fix` to remove the stale .fabric/.serve.lock."
+  );
+}
 function extractKnowledgeFrontmatterRelevanceScope(source) {
   const FM_PATTERN = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u;
   const fm = FM_PATTERN.exec(source);
@@ -4244,6 +4436,117 @@ function createSkillMdYamlInvalidCheck(inspection) {
     'Quote the value with double quotes (`description: "\u2026"`) or rewrite the inner `key: value` token to `key=value`.'
   );
 }
+var KNOWLEDGE_CANONICAL_TYPE_DIRS_FOR_ONBOARD = [
+  "decisions",
+  "pitfalls",
+  "guidelines",
+  "models",
+  "processes"
+];
+function inspectOnboardCoverage(projectRoot) {
+  const filled = {};
+  for (const slot of ONBOARD_SLOT_NAMES) {
+    filled[slot] = [];
+  }
+  const knowledgeRoot = join6(projectRoot, ".fabric", "knowledge");
+  if (existsSync4(knowledgeRoot)) {
+    for (const typeDir of KNOWLEDGE_CANONICAL_TYPE_DIRS_FOR_ONBOARD) {
+      const dir = join6(knowledgeRoot, typeDir);
+      if (!existsSync4(dir)) continue;
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        if (!entry.name.endsWith(".md")) continue;
+        const filePath = join6(dir, entry.name);
+        let content;
+        try {
+          content = readFileSync2(filePath, "utf8");
+        } catch {
+          continue;
+        }
+        const slot = readFrontmatterScalar(content, "onboard_slot");
+        if (slot === void 0) continue;
+        if (!ONBOARD_SLOT_NAMES.includes(slot)) continue;
+        const stableId = readFrontmatterScalar(content, "id") ?? entry.name.replace(/\.md$/u, "");
+        filled[slot].push(stableId);
+      }
+    }
+  }
+  for (const slot of ONBOARD_SLOT_NAMES) {
+    filled[slot].sort();
+  }
+  const optedOut = readOnboardOptedOut(projectRoot);
+  const missing = ONBOARD_SLOT_NAMES.filter((slot) => {
+    if (filled[slot].length > 0) return false;
+    if (optedOut.includes(slot)) return false;
+    return true;
+  });
+  return { filled, missing, opted_out: optedOut };
+}
+function readOnboardOptedOut(projectRoot) {
+  const path2 = join6(projectRoot, ".fabric", "fabric-config.json");
+  if (!existsSync4(path2)) return [];
+  let raw;
+  try {
+    raw = readFileSync2(path2, "utf8");
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return [];
+  }
+  const list = parsed.onboard_slots_opted_out;
+  if (!Array.isArray(list)) return [];
+  return list.filter((v) => typeof v === "string");
+}
+function readFrontmatterScalar(content, key) {
+  const match = /^---\n([\s\S]*?)\n---/u.exec(content);
+  if (match === null) return void 0;
+  const block = match[1];
+  if (block === void 0) return void 0;
+  for (const rawLine of block.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    const sep4 = line.indexOf(":");
+    if (sep4 === -1) continue;
+    if (line.slice(0, sep4).trim() !== key) continue;
+    let value = line.slice(sep4 + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      value = value.slice(1, -1);
+    }
+    return value;
+  }
+  return void 0;
+}
+function createOnboardCoverageCheck(inspection) {
+  const filledCount = ONBOARD_SLOT_NAMES.filter(
+    (slot) => inspection.filled[slot].length > 0
+  ).length;
+  if (inspection.missing.length === 0) {
+    return okCheck(
+      "Onboard coverage",
+      `Onboard coverage: ${filledCount}/${ONBOARD_SLOT_TOTAL} \u2713 (opted-out: ${inspection.opted_out.length}).`
+    );
+  }
+  return issueCheck(
+    "Onboard coverage",
+    "ok",
+    "info",
+    "onboard_coverage_incomplete",
+    `Onboard slots not yet covered: [${inspection.missing.join(", ")}]. ${filledCount}/${ONBOARD_SLOT_TOTAL} filled; ${inspection.opted_out.length} opted-out.`,
+    "Run /fabric-archive to onboard \u2014 the Skill's first-run phase will tour the project and propose pending entries for each unclaimed slot."
+  );
+}
 function createNarrowTooFewCheck(inspection) {
   const { structural_flagged, telemetry_flagged } = inspection;
   if (!structural_flagged && !telemetry_flagged) {
@@ -4652,9 +4955,9 @@ async function fixCounterDesync(projectRoot) {
   await atomicWriteJson2(metaPath, updated, { indent: 2 });
 }
 async function ensureEventLedger(projectRoot) {
-  const path = getEventLedgerPath(projectRoot);
-  await ensureParentDirectory(path);
-  await writeFile2(path, "", { encoding: "utf8", flag: "a" });
+  const path2 = getEventLedgerPath(projectRoot);
+  await ensureParentDirectory(path2);
+  await writeFile2(path2, "", { encoding: "utf8", flag: "a" });
 }
 var CITE_POLICY_VERSION = "2.0.0-rc.20";
 async function ensureCitePolicyActivatedMarker(projectRoot) {
@@ -4681,6 +4984,48 @@ async function ensureCitePolicyActivatedMarker(projectRoot) {
     return { marker_ts: 0, emitted_now: false };
   }
 }
+async function ensureCiteContractPolicyActivatedMarker(projectRoot) {
+  let driftStatus;
+  try {
+    const inspection = await inspectL1BootstrapSnapshotDrift(projectRoot);
+    driftStatus = inspection.status;
+  } catch {
+    driftStatus = "drift";
+  }
+  if (driftStatus !== "ok") {
+    return { marker_ts: 0, emitted_now: false, blocked_by: "bootstrap_drift" };
+  }
+  let existing;
+  try {
+    const { events } = await readEventLedger(projectRoot, {
+      event_type: "cite_contract_policy_activated"
+    });
+    if (events.length > 0) {
+      existing = events[0];
+    }
+  } catch {
+    return { marker_ts: 0, emitted_now: false, blocked_by: null };
+  }
+  if (existing !== void 0) {
+    return { marker_ts: existing.ts, emitted_now: false, blocked_by: null };
+  }
+  try {
+    const stored = await appendEventLedgerEvent(projectRoot, {
+      event_type: "cite_contract_policy_activated"
+    });
+    return { marker_ts: stored.ts, emitted_now: true, blocked_by: null };
+  } catch {
+    return { marker_ts: 0, emitted_now: false, blocked_by: null };
+  }
+}
+function parseNoneSentinel(kbLineRaw) {
+  if (typeof kbLineRaw !== "string" || kbLineRaw.length === 0) return "unspecified";
+  const m = kbLineRaw.match(/^KB:\s*none\b\s*(?:\[([^\]]*)\])?\s*$/i);
+  if (m === null) return "unspecified";
+  const inner = (m[1] ?? "").trim().toLowerCase();
+  if (inner === "no-relevant" || inner === "not-applicable") return inner;
+  return "unspecified";
+}
 function categorizeCiteTag(tag) {
   if (tag === "planned" || tag === "recalled" || tag === "chained-from" || tag === "none") {
     return { category: tag };
@@ -4710,7 +5055,10 @@ function matchesRelevancePath(editPath, relevancePaths) {
   return false;
 }
 async function runDoctorCiteCoverage(projectRoot, options) {
+  const layerFilter = options.layer ?? "all";
   const marker = await ensureCitePolicyActivatedMarker(projectRoot);
+  const contractMarker = await ensureCiteContractPolicyActivatedMarker(projectRoot);
+  const idTypeMap = await loadKbIdTypeMap(projectRoot);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const zeroMetrics = {
     edits_touched: 0,
@@ -4719,6 +5067,20 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     expected_but_missed: 0,
     total_turns: 0
   };
+  const contractStatus = contractMarker.blocked_by === "bootstrap_drift" ? "skipped:bootstrap_drift" : contractMarker.marker_ts === 0 ? "awaiting_marker" : "ok";
+  const zeroContractMetrics = {
+    decisions_cited: 0,
+    pitfalls_cited: 0,
+    contract_with: 0,
+    contract_missing: 0,
+    hard_violated: 0,
+    cite_id_unresolved: 0,
+    skip_count: {}
+  };
+  const zeroLayerType = {
+    team: {},
+    personal: {}
+  };
   if (marker.marker_ts === 0) {
     return {
       status: "skipped",
@@ -4726,11 +5088,17 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       marker_emitted_now: false,
       since_ts: options.since,
       client_filter: options.client,
+      layer_filter: layerFilter,
       metrics: zeroMetrics,
+      contract_metrics_status: contractStatus,
+      contract_metrics: zeroContractMetrics,
+      per_layer_type: zeroLayerType,
+      contract_marker_ts: contractMarker.marker_ts,
       generated_at: generatedAt
     };
   }
   const effectiveSince = Math.max(marker.marker_ts, options.since);
+  const contractEffectiveSince = contractStatus === "ok" ? Math.max(contractMarker.marker_ts, options.since) : Number.POSITIVE_INFINITY;
   let ledgerEvents = [];
   try {
     const result = await readEventLedger(projectRoot, { since: effectiveSince });
@@ -4742,7 +5110,12 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       marker_emitted_now: marker.emitted_now,
       since_ts: effectiveSince,
       client_filter: options.client,
+      layer_filter: layerFilter,
       metrics: zeroMetrics,
+      contract_metrics_status: contractStatus,
+      contract_metrics: zeroContractMetrics,
+      per_layer_type: zeroLayerType,
+      contract_marker_ts: contractMarker.marker_ts,
       generated_at: generatedAt
     };
   }
@@ -4764,7 +5137,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         break;
     }
   }
-  const filteredTurns = options.client === "all" ? assistantTurns : assistantTurns.filter((t) => t.client === options.client);
+  const filteredTurns = options.client === "all" ? assistantTurns : assistantTurns.filter((t2) => t2.client === options.client);
   let clientSessionIds = null;
   if (options.client !== "all") {
     clientSessionIds = /* @__PURE__ */ new Set();
@@ -4819,6 +5192,7 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     return false;
   };
   const dismissedHistogram = {};
+  const noneHistogram = {};
   const perClientAccum = /* @__PURE__ */ new Map();
   const emptyMetrics = () => ({
     edits_touched: 0,
@@ -4834,6 +5208,80 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     perClientAccum.set(client, existing);
   };
   const sessionCitedKbs = /* @__PURE__ */ new Map();
+  const sessionEditPaths = /* @__PURE__ */ new Map();
+  for (const edit of editEvents) {
+    const sid = edit.session_id;
+    if (typeof sid !== "string" || sid.length === 0) continue;
+    const list = sessionEditPaths.get(sid) ?? [];
+    list.push(normalizePath(edit.path));
+    sessionEditPaths.set(sid, list);
+  }
+  let decisionsCited = 0;
+  let pitfallsCited = 0;
+  let contractWith = 0;
+  let contractMissing = 0;
+  let hardViolated = 0;
+  let citeIdUnresolved = 0;
+  const skipCount = {};
+  const layerTypeAccum = { team: {}, personal: {} };
+  const bumpLayerType = (citeId, type) => {
+    const layer = citeId.startsWith("KP-") ? "personal" : citeId.startsWith("KT-") ? "team" : null;
+    if (layer === null) return;
+    layerTypeAccum[layer][type] = (layerTypeAccum[layer][type] ?? 0) + 1;
+  };
+  const passesLayerFilter = (citeId) => {
+    if (layerFilter === "all") return true;
+    if (layerFilter === "team") return citeId.startsWith("KT-");
+    return citeId.startsWith("KP-");
+  };
+  const evaluateOperatorViolation = (sessionId, operators) => {
+    const editPaths = typeof sessionId === "string" && sessionId.length > 0 ? sessionEditPaths.get(sessionId) ?? [] : [];
+    for (const op of operators) {
+      switch (op.kind) {
+        case "edit": {
+          let matched = false;
+          for (const p of editPaths) {
+            if (minimatch(p, op.target, { dot: true, matchBase: false })) {
+              matched = true;
+              break;
+            }
+          }
+          if (!matched) return true;
+          break;
+        }
+        case "not_edit": {
+          for (const p of editPaths) {
+            if (minimatch(p, op.target, { dot: true, matchBase: false })) {
+              return true;
+            }
+          }
+          break;
+        }
+        case "require": {
+          let found = false;
+          for (const p of editPaths) {
+            if (p.includes(op.target)) {
+              found = true;
+              break;
+            }
+          }
+          if (!found) return true;
+          break;
+        }
+        case "forbid": {
+          for (const p of editPaths) {
+            if (p.includes(op.target)) {
+              return true;
+            }
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    return false;
+  };
   let totalTurns = 0;
   let qualifyingCites = 0;
   let recalledUnverified = 0;
@@ -4868,7 +5316,11 @@ async function runDoctorCiteCoverage(projectRoot, options) {
           dismissedHistogram[key] = (dismissedHistogram[key] ?? 0) + 1;
           break;
         }
-        case "none":
+        case "none": {
+          const sentinel = parseNoneSentinel(turn.kb_line_raw);
+          noneHistogram[sentinel] = (noneHistogram[sentinel] ?? 0) + 1;
+          break;
+        }
         default:
           break;
       }
@@ -4879,6 +5331,40 @@ async function runDoctorCiteCoverage(projectRoot, options) {
         m.recalled_unverified += 1;
       });
     }
+    if (contractStatus === "ok" && turn.ts >= contractEffectiveSince) {
+      const commitments = turn.cite_commitments ?? [];
+      for (let i = 0; i < turn.cite_ids.length; i += 1) {
+        const citeId = turn.cite_ids[i];
+        if (typeof citeId !== "string" || citeId.length === 0) continue;
+        if (!passesLayerFilter(citeId)) continue;
+        const kbType = idTypeMap.get(citeId);
+        if (kbType === void 0) {
+          citeIdUnresolved += 1;
+          bumpLayerType(citeId, "unresolved");
+          continue;
+        }
+        bumpLayerType(citeId, kbType);
+        if (kbType === "decision" || kbType === "pitfall") {
+          if (kbType === "decision") decisionsCited += 1;
+          else pitfallsCited += 1;
+          const commitment = commitments[i];
+          const operators = commitment?.operators ?? [];
+          const skipReason = commitment?.skip_reason ?? null;
+          if (skipReason !== null) {
+            skipCount[skipReason] = (skipCount[skipReason] ?? 0) + 1;
+            continue;
+          }
+          if (operators.length === 0) {
+            contractMissing += 1;
+            continue;
+          }
+          contractWith += 1;
+          if (evaluateOperatorViolation(sid, operators)) {
+            hardViolated += 1;
+          }
+        }
+      }
+    }
   }
   let editsTouched = 0;
   let expectedButMissed = 0;
@@ -4913,18 +5399,96 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       perClient[client] = m;
     }
   }
+  const contractMetrics = {
+    decisions_cited: decisionsCited,
+    pitfalls_cited: pitfallsCited,
+    contract_with: contractWith,
+    contract_missing: contractMissing,
+    hard_violated: hardViolated,
+    cite_id_unresolved: citeIdUnresolved,
+    skip_count: skipCount
+  };
   return {
     status: "ok",
     marker_ts: marker.marker_ts,
     marker_emitted_now: marker.emitted_now,
     since_ts: effectiveSince,
     client_filter: options.client,
+    layer_filter: layerFilter,
     metrics,
     ...perClient !== void 0 ? { per_client: perClient } : {},
     ...Object.keys(dismissedHistogram).length > 0 ? { dismissed_reason_histogram: dismissedHistogram } : {},
+    ...Object.keys(noneHistogram).length > 0 ? { none_reason_histogram: noneHistogram } : {},
+    contract_metrics_status: contractStatus,
+    contract_metrics: contractMetrics,
+    per_layer_type: layerTypeAccum,
+    contract_marker_ts: contractMarker.marker_ts,
     generated_at: generatedAt
   };
 }
+async function runDoctorArchiveHistory(projectRoot, options) {
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const nowMs = Date.now();
+  let events = [];
+  try {
+    const result = await readEventLedger(projectRoot, {
+      event_type: "session_archive_attempted",
+      since: options.since
+    });
+    events = result.events;
+  } catch {
+    return {
+      entries: [],
+      total: 0,
+      since_ms: options.since,
+      generated_at: generatedAt
+    };
+  }
+  const mostRecentBySession = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.event_type !== "session_archive_attempted") {
+      continue;
+    }
+    const sessionId = event.session_id;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      continue;
+    }
+    const prior = mostRecentBySession.get(sessionId);
+    if (prior === void 0 || event.ts > prior.ts) {
+      mostRecentBySession.set(sessionId, event);
+    }
+  }
+  const entries = [];
+  for (const [sessionId, event] of mostRecentBySession.entries()) {
+    const ageHours = Math.max(
+      0,
+      Math.floor((nowMs - event.covered_through_ts) / 36e5)
+    );
+    entries.push({
+      session_id_short: truncateSessionId(sessionId),
+      last_attempted_at: new Date(event.ts).toISOString(),
+      outcome: event.outcome,
+      candidates_proposed: event.candidates_proposed,
+      covered_through_ts: event.covered_through_ts,
+      age_since_covered_hours: ageHours
+    });
+  }
+  entries.sort(
+    (a, b) => a.last_attempted_at < b.last_attempted_at ? 1 : a.last_attempted_at > b.last_attempted_at ? -1 : 0
+  );
+  return {
+    entries,
+    total: entries.length,
+    since_ms: options.since,
+    generated_at: generatedAt
+  };
+}
+function truncateSessionId(sessionId) {
+  if (sessionId.length <= 8) {
+    return sessionId;
+  }
+  return `${sessionId.slice(0, 8)}...`;
+}
 function createFixMessage(fixed, report) {
   const fixedText = fixed.length === 0 ? "No deterministic doctor fixes were needed." : `Applied ${fixed.length} deterministic doctor fix${fixed.length === 1 ? "" : "es"}.`;
   const manualText = report.manual_errors.length === 0 ? "No manual errors remain." : `${report.manual_errors.length} manual error${report.manual_errors.length === 1 ? "" : "s"} remain.`;
@@ -4941,8 +5505,8 @@ function isValidJsonLine(line) {
 function normalizeTarget(targetInput) {
   return isAbsolute2(targetInput) ? targetInput : resolve3(process.cwd(), targetInput);
 }
-function normalizePath(path) {
-  return posix.normalize(path.split("\\").join("/"));
+function normalizePath(path2) {
+  return posix.normalize(path2.split("\\").join("/"));
 }
 function collectEntryPoints(root) {
   if (!existsSync4(root) || !statSync4(root).isDirectory()) {
@@ -5012,6 +5576,123 @@ function reduceStatus(statuses) {
 function isMissingFileError(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+var ENRICH_DESC_FIELDS = ["intent_clues", "tech_stack", "impact", "must_read_if"];
+var ENRICH_DESC_FIELD_PATTERNS = {
+  intent_clues: /^intent_clues\s*:/mu,
+  tech_stack: /^tech_stack\s*:/mu,
+  impact: /^impact\s*:/mu,
+  must_read_if: /^must_read_if\s*:/mu
+};
+async function enrichDescriptions(projectRoot, opts = {}) {
+  const auto = opts.auto === true;
+  const dryRun = opts.dryRun === true;
+  const mode = auto ? "auto" : "interactive";
+  const candidates = [];
+  let scanned = 0;
+  let modified = 0;
+  let skipped = 0;
+  for (const visit of iterateCanonicalFilenames(projectRoot)) {
+    const layerRoot = visit.layer === "team" ? join6(projectRoot, ".fabric", "knowledge") : resolvePersonalKnowledgeRoot();
+    const absPath = join6(layerRoot, visit.type, visit.filename);
+    scanned += 1;
+    let source;
+    try {
+      source = await readFile5(absPath, "utf8");
+    } catch {
+      continue;
+    }
+    const fmMatch = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/u.exec(source);
+    if (fmMatch === null) {
+      candidates.push({
+        path: visit.displayPath,
+        missing: [...ENRICH_DESC_FIELDS],
+        modified: false,
+        added_fields: [],
+        error: "frontmatter not parseable"
+      });
+      continue;
+    }
+    const block = fmMatch[1];
+    const missing = ENRICH_DESC_FIELDS.filter(
+      (field) => !ENRICH_DESC_FIELD_PATTERNS[field].test(block)
+    );
+    if (missing.length === 0) {
+      skipped += 1;
+      continue;
+    }
+    if (!auto || dryRun) {
+      candidates.push({
+        path: visit.displayPath,
+        missing,
+        modified: false,
+        added_fields: []
+      });
+      continue;
+    }
+    const mustReadIf = synthesizeMustReadIfStub(source, visit.filename);
+    const additions = [];
+    for (const field of missing) {
+      if (field === "must_read_if") {
+        additions.push({ field, line: `must_read_if: ${yamlQuoteIfNeeded(mustReadIf)}` });
+      } else {
+        additions.push({ field, line: `${field}: []` });
+      }
+    }
+    const trailing = block.endsWith("\n") ? "" : "\n";
+    const replacedBlock = `${block}${trailing}${additions.map((a) => a.line).join("\n")}`;
+    const blockStart = source.indexOf(block);
+    if (blockStart < 0) {
+      candidates.push({
+        path: visit.displayPath,
+        missing,
+        modified: false,
+        added_fields: [],
+        error: "frontmatter block not located after match"
+      });
+      continue;
+    }
+    const rewritten = source.slice(0, blockStart) + replacedBlock + source.slice(blockStart + block.length);
+    await atomicWriteText4(absPath, rewritten);
+    modified += 1;
+    candidates.push({
+      path: visit.displayPath,
+      missing,
+      modified: true,
+      added_fields: additions.map((a) => a.field)
+    });
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "knowledge_enriched",
+      path: visit.displayPath,
+      added_fields: additions.map((a) => a.field),
+      mode,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }).catch(() => {
+    });
+  }
+  candidates.sort((a, b) => a.path.localeCompare(b.path));
+  return { mode, dryRun, scanned, modified, skipped, candidates };
+}
+function synthesizeMustReadIfStub(source, filename) {
+  const h1Match = /^#\s+(.+?)\s*$/mu.exec(source);
+  let raw = h1Match !== null ? h1Match[1] : filename.replace(/^K[PT]-[A-Z]+-\d+--/, "").replace(/\.md$/u, "").replace(/-/g, " ");
+  raw = raw.trim();
+  if (raw.length === 0) {
+    raw = "describes a knowledge invariant for this project";
+  }
+  if (raw.length > 120) {
+    raw = `${raw.slice(0, 117)}...`;
+  }
+  return raw;
+}
+function yamlQuoteIfNeeded(value) {
+  if (value.length === 0) {
+    return '""';
+  }
+  if (/[:#"'\\[\]{},&*!|>%@`]/.test(value) || /^[\s-?]/.test(value) || /\s$/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
 
 // src/services/load-active-meta.ts
 async function loadActiveMeta(projectRoot, opts = {}) {
@@ -5168,16 +5849,16 @@ async function loadGetKnowledgeContext(projectRoot) {
   contextCache.set("context", projectRoot, context);
   return context;
 }
-async function resolveKnowledgeForPath(projectRoot, context, path, options = {}) {
-  const matchedNodes = matchRuleNodes(context.meta, path);
+async function resolveKnowledgeForPath(projectRoot, context, path2, options = {}) {
+  const matchedNodes = matchRuleNodes(context.meta, path2);
   const loaded = await loadMatchedRules(projectRoot, matchedNodes);
   return buildKnowledgePayload(context, loaded, options);
 }
 function normalizeKnowledgePath(value) {
   return value.replaceAll("\\", "/");
 }
-function matchRuleNodes(meta, path) {
-  const requestedPath = normalizeKnowledgePath(path);
+function matchRuleNodes(meta, path2) {
+  const requestedPath = normalizeKnowledgePath(path2);
   return Object.entries(meta.nodes).filter(([, node]) => shouldLoadNodeForPath(requestedPath, node)).sort((left, right) => {
     const [leftId, leftNode] = left;
     const [rightId, rightNode] = right;
@@ -5321,6 +6002,7 @@ export {
   appendEventLedgerEvent,
   readEventLedger,
   flushAndSyncEventLedger,
+  loadKbIdTypeMap,
   buildKnowledgeMeta,
   writeKnowledgeMeta,
   computeKnowledgeBasedAgentsMeta,
@@ -5336,8 +6018,15 @@ export {
   loadActiveMetaOrStale,
   getKnowledge,
   normalizeKnowledgePath,
+  ServeLockHeldError,
+  acquireLock,
+  releaseLock,
+  readLockState,
+  checkLockOrThrow,
   runDoctorReport,
   runDoctorFix,
   runDoctorApplyLint,
-  runDoctorCiteCoverage
+  runDoctorCiteCoverage,
+  runDoctorArchiveHistory,
+  enrichDescriptions
 };