@fenglimg/fabric-server 1.7.0 → 1.8.0-rc.2

package/dist/{chunk-PTFSYO4Y.js → chunk-EGGZFXMO.js}

@@ -82,29 +82,86 @@ var ContextCache = class {
 };
 var contextCache = new ContextCache(5e3);
 
+// src/meta-reader.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { agentsMetaSchema } from "@fenglimg/fabric-shared";
+import { IOFabricError } from "@fenglimg/fabric-shared/errors";
+import { agentsMetaNodeSchema, agentsMetaSchema as agentsMetaSchema2 } from "@fenglimg/fabric-shared";
+var AgentsMetaFileMissingError = class extends IOFabricError {
+  constructor(metaPath, opts) {
+    super(`Fabric agents metadata file is missing: ${metaPath}`, {
+      actionHint: opts?.actionHint ?? "Run `fab init` to scaffold the .fabric/agents.meta.json file"
+    });
+    this.metaPath = metaPath;
+  }
+  metaPath;
+  code = "FABRIC_META_MISSING";
+  httpStatus = 404;
+};
+var AgentsMetaInvalidError = class extends IOFabricError {
+  constructor(metaPath, cause, opts) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Fabric agents metadata file is invalid: ${metaPath}. ${detail}`, {
+      actionHint: opts?.actionHint ?? "Check the agents.meta.json file for schema errors and regenerate if needed"
+    });
+    this.metaPath = metaPath;
+  }
+  metaPath;
+  code = "FABRIC_META_INVALID";
+  httpStatus = 500;
+};
+function getAgentsMetaPath(projectRoot) {
+  return join(projectRoot, ".fabric", "agents.meta.json");
+}
+function resolveProjectRoot() {
+  return process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
+}
+async function readAgentsMeta(projectRoot) {
+  const cached = contextCache.get("meta", projectRoot);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const metaPath = getAgentsMetaPath(projectRoot);
+  let raw;
+  try {
+    raw = await readFile(metaPath, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      throw new AgentsMetaFileMissingError(metaPath);
+    }
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = agentsMetaSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    throw new AgentsMetaInvalidError(metaPath, error);
+  }
+  contextCache.set("meta", projectRoot, parsed);
+  return parsed;
+}
+
 // src/services/_shared.ts
-import { dirname, join, resolve, sep } from "path";
+import { dirname, join as join2, resolve, sep } from "path";
 import { createHash } from "crypto";
-import { mkdir, rename, writeFile } from "fs/promises";
+import { mkdir } from "fs/promises";
+import { PathEscapeError } from "@fenglimg/fabric-shared/errors";
+import { atomicWriteText, atomicWriteJson } from "@fenglimg/fabric-shared/node/atomic-write";
 var FABRIC_DIR = ".fabric";
 var LEDGER_FILE = ".intent-ledger.jsonl";
 var LEDGER_PATH = `${FABRIC_DIR}/${LEDGER_FILE}`;
 var LEGACY_LEDGER_PATH = LEDGER_FILE;
 var EVENT_LEDGER_FILE = "events.jsonl";
 var EVENT_LEDGER_PATH = `${FABRIC_DIR}/${EVENT_LEDGER_FILE}`;
-async function atomicWriteText(path, content) {
-  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(tempPath, content, "utf8");
-  await rename(tempPath, path);
-}
 function getLedgerPath(projectRoot) {
-  return join(projectRoot, LEDGER_PATH);
+  return join2(projectRoot, LEDGER_PATH);
 }
 function getLegacyLedgerPath(projectRoot) {
-  return join(projectRoot, LEGACY_LEDGER_PATH);
+  return join2(projectRoot, LEGACY_LEDGER_PATH);
 }
 function getEventLedgerPath(projectRoot) {
-  return join(projectRoot, EVENT_LEDGER_PATH);
+  return join2(projectRoot, EVENT_LEDGER_PATH);
 }
 async function ensureParentDirectory(path) {
   await mkdir(dirname(path), { recursive: true });
@@ -118,10 +175,13 @@ function isNodeError(error) {
 
 // src/services/event-ledger.ts
 import { randomUUID } from "crypto";
-import { appendFile, readFile } from "fs/promises";
+import { existsSync, fsyncSync, openSync, closeSync } from "fs";
+import { readFile as readFile2, truncate, writeFile } from "fs/promises";
 import {
   eventLedgerEventSchema
 } from "@fenglimg/fabric-shared";
+import { createLedgerWriteQueue } from "@fenglimg/fabric-shared/node/atomic-write";
+var ledgerQueue = createLedgerWriteQueue();
 async function appendEventLedgerEvent(projectRoot, event) {
   const eventPath = getEventLedgerPath(projectRoot);
   const nextEvent = eventLedgerEventSchema.parse({
@@ -132,22 +192,60 @@ async function appendEventLedgerEvent(projectRoot, event) {
     schema_version: 1
   });
   await ensureParentDirectory(eventPath);
-  await appendFile(eventPath, `${JSON.stringify(nextEvent)}
-`, "utf8");
+  await ledgerQueue.append(eventPath, JSON.stringify(nextEvent));
   return nextEvent;
 }
 async function readEventLedger(projectRoot, options = {}) {
   const eventPath = getEventLedgerPath(projectRoot);
   let raw;
   try {
-    raw = await readFile(eventPath, "utf8");
+    raw = await readFile2(eventPath, "utf8");
   } catch (error) {
     if (isNodeError2(error) && error.code === "ENOENT") {
-      return [];
+      return { events: [], warnings: [] };
     }
     throw error;
   }
-  return raw.split(/\r?\n/).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);
+  const warnings = [];
+  const lines = raw.split(/\r?\n/);
+  const hasTrailingNewline = raw.endsWith("\n");
+  let partialLine;
+  if (!hasTrailingNewline && lines.length > 0) {
+    partialLine = lines.pop();
+  }
+  if (partialLine !== void 0 && partialLine.trim().length > 0) {
+    const fullContentBeforePartial = raw.slice(0, raw.length - partialLine.length);
+    const byteOffset = Buffer.byteLength(fullContentBeforePartial, "utf8");
+    const byteLength = Buffer.byteLength(partialLine, "utf8");
+    warnings.push({
+      kind: "partial_write_at_tail",
+      byte_offset: byteOffset,
+      byte_length: byteLength,
+      snippet_first_120: partialLine.slice(0, 120)
+    });
+  }
+  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);
+  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()}`;
+    await writeFile(corruptedPath2, raw);
+    await truncate(path, 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()}`;
+  await writeFile(corruptedPath, corruptedBytes);
+  await truncate(path, keepByteLength);
+  return { truncated_bytes: corruptedBytes.length, corrupted_path: corruptedPath };
 }
 function parseEventLedgerLine(line, index) {
   try {
@@ -170,24 +268,35 @@ function createDerivedId(index, line) {
 function isNodeError2(error) {
   return error instanceof Error;
 }
+function flushAndSyncEventLedger(projectRoot) {
+  const ledgerPath = getEventLedgerPath(projectRoot);
+  if (!existsSync(ledgerPath)) return;
+  const fd = openSync(ledgerPath, "r+");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
 
 // src/services/rule-meta-builder.ts
-import { readdir, readFile as readFile2 } from "fs/promises";
-import { existsSync, statSync } from "fs";
-import { isAbsolute, join as join2, relative, resolve as resolve2, sep as sep2 } from "path";
+import { readdir, readFile as readFile3 } from "fs/promises";
+import { existsSync as existsSync2, statSync } from "fs";
+import { isAbsolute, join as join3, relative, resolve as resolve2, sep as sep2 } from "path";
 import {
   RULE_TEST_INDEX_SCHEMA_VERSION,
-  agentsMetaSchema,
+  agentsMetaSchema as agentsMetaSchema3,
   deriveAgentsMetaLayer,
   deriveAgentsMetaStableId,
   deriveAgentsMetaTopologyType,
   ruleTestIndexSchema
 } from "@fenglimg/fabric-shared";
+import { atomicWriteText as atomicWriteText2 } from "@fenglimg/fabric-shared/node/atomic-write";
 async function buildRuleMeta(projectRootInput) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   assertExistingDirectory(projectRoot);
-  const metaPath = join2(projectRoot, ".fabric", "agents.meta.json");
-  const ruleTestIndexPath = join2(projectRoot, ".fabric", "rule-test.index.json");
+  const metaPath = join3(projectRoot, ".fabric", "agents.meta.json");
+  const ruleTestIndexPath = join3(projectRoot, ".fabric", "rule-test.index.json");
   const existingMeta = await readExistingMeta(metaPath);
   const existingRuleTestIndex = await readExistingRuleTestIndex(ruleTestIndexPath);
   const meta = await computeRulesBasedAgentsMeta(projectRoot, existingMeta);
@@ -200,17 +309,17 @@ async function buildRuleMeta(projectRootInput) {
 }
 async function writeRuleMeta(projectRootInput, options) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
-  const metaPath = join2(projectRoot, ".fabric", "agents.meta.json");
-  const ruleTestIndexPath = join2(projectRoot, ".fabric", "rule-test.index.json");
+  const metaPath = join3(projectRoot, ".fabric", "agents.meta.json");
+  const ruleTestIndexPath = join3(projectRoot, ".fabric", "rule-test.index.json");
   const existingMeta = await readExistingMeta(metaPath);
   const result = await buildRuleMeta(projectRoot);
   if (!result.changed) {
     return result;
   }
   await ensureParentDirectory(metaPath);
-  await atomicWriteText(metaPath, `${JSON.stringify(result.meta, null, 2)}
+  await atomicWriteText2(metaPath, `${JSON.stringify(result.meta, null, 2)}
 `);
-  await atomicWriteText(ruleTestIndexPath, `${JSON.stringify(result.ruleTestIndex, null, 2)}
+  await atomicWriteText2(ruleTestIndexPath, `${JSON.stringify(result.ruleTestIndex, null, 2)}
 `);
   if (existingMeta === void 0 || stableStringify(existingMeta) !== stableStringify(result.meta)) {
     await recordBaselineSynced(projectRoot, {
@@ -227,7 +336,7 @@ async function writeRuleMeta(projectRootInput, options) {
 async function computeRulesBasedAgentsMeta(projectRootInput, existingMeta) {
   const projectRoot = normalizeProjectRoot(projectRootInput);
   assertExistingDirectory(projectRoot);
-  const previousMeta = existingMeta ?? await readExistingMeta(join2(projectRoot, ".fabric", "agents.meta.json"));
+  const previousMeta = existingMeta ?? await readExistingMeta(join3(projectRoot, ".fabric", "agents.meta.json"));
   const existingByContentRef = indexExistingNodesByContentRef(previousMeta);
   const ruleFiles = await findFabricRuleFiles(projectRoot);
   const nodes = {};
@@ -236,7 +345,7 @@ async function computeRulesBasedAgentsMeta(projectRootInput, existingMeta) {
     nodes.L0 = bootstrapNode;
   }
   for (const contentRef of ruleFiles) {
-    const source = await readFile2(join2(projectRoot, contentRef), "utf8");
+    const source = await readFile3(join3(projectRoot, contentRef), "utf8");
     const existing = existingByContentRef.get(contentRef);
     const id = deriveNodeId(contentRef);
     const hash = sha256(source);
@@ -320,14 +429,14 @@ function normalizeProjectRoot(projectRoot) {
   return isAbsolute(projectRoot) ? projectRoot : resolve2(process.cwd(), projectRoot);
 }
 function assertExistingDirectory(projectRoot) {
-  if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+  if (!existsSync2(projectRoot) || !statSync(projectRoot).isDirectory()) {
     throw new Error(`Target directory does not exist: ${projectRoot}`);
   }
 }
 async function readExistingMeta(metaPath) {
   let raw;
   try {
-    raw = await readFile2(metaPath, "utf8");
+    raw = await readFile3(metaPath, "utf8");
   } catch (error) {
     if (isNodeError3(error) && error.code === "ENOENT") {
       return void 0;
@@ -335,7 +444,7 @@ async function readExistingMeta(metaPath) {
     throw error;
   }
   try {
-    return agentsMetaSchema.parse(JSON.parse(raw));
+    return agentsMetaSchema3.parse(JSON.parse(raw));
   } catch {
     return void 0;
   }
@@ -343,7 +452,7 @@ async function readExistingMeta(metaPath) {
 async function readExistingRuleTestIndex(indexPath) {
   let raw;
   try {
-    raw = await readFile2(indexPath, "utf8");
+    raw = await readFile3(indexPath, "utf8");
   } catch (error) {
     if (isNodeError3(error) && error.code === "ENOENT") {
       return void 0;
@@ -357,8 +466,8 @@ async function readExistingRuleTestIndex(indexPath) {
   }
 }
 async function findFabricRuleFiles(projectRoot) {
-  const rulesRoot = join2(projectRoot, ".fabric", "rules");
-  if (!existsSync(rulesRoot) || !statSync(rulesRoot).isDirectory()) {
+  const rulesRoot = join3(projectRoot, ".fabric", "rules");
+  if (!existsSync2(rulesRoot) || !statSync(rulesRoot).isDirectory()) {
     return [];
   }
   const files = [];
@@ -369,7 +478,7 @@ async function findFabricRuleFiles(projectRoot) {
       continue;
     }
     for (const entry of await readdir(current, { withFileTypes: true })) {
-      const absolutePath = join2(current, entry.name);
+      const absolutePath = join3(current, entry.name);
       const relativePath = toPosixPath(relative(projectRoot, absolutePath));
       if (entry.isDirectory()) {
         stack.push(absolutePath);
@@ -385,7 +494,7 @@ async function findFabricVerifyAnnotations(projectRoot) {
   const annotations = [];
   const annotationPattern = /^\s*\/\/\s*@fabric-verify\s+([A-Za-z0-9][A-Za-z0-9/_-]*)\s*$/u;
   for (const testFile of files) {
-    const source = await readFile2(join2(projectRoot, testFile), "utf8");
+    const source = await readFile3(join3(projectRoot, testFile), "utf8");
     const testHash = sha256(source);
     const lines = source.split(/\r?\n/u);
     for (const [index, line] of lines.entries()) {
@@ -413,7 +522,7 @@ async function findTestFiles(projectRoot) {
       continue;
     }
     for (const entry of await readdir(current, { withFileTypes: true })) {
-      const absolutePath = join2(current, entry.name);
+      const absolutePath = join3(current, entry.name);
       const relativePath = toPosixPath(relative(projectRoot, absolutePath));
       const [rootSegment] = relativePath.split("/");
       if (entry.isDirectory()) {
@@ -513,11 +622,11 @@ function createDefaultNodeMeta(contentRef) {
 }
 async function createBootstrapNode(projectRoot, existing) {
   const contentRef = ".fabric/bootstrap/README.md";
-  const bootstrapPath = join2(projectRoot, contentRef);
-  if (!existsSync(bootstrapPath)) {
+  const bootstrapPath = join3(projectRoot, contentRef);
+  if (!existsSync2(bootstrapPath)) {
     return void 0;
   }
-  const hash = sha256(await readFile2(bootstrapPath, "utf8"));
+  const hash = sha256(await readFile3(bootstrapPath, "utf8"));
   const identity = {
     stableId: existing?.stable_id ?? deriveAgentsMetaStableId(contentRef),
     identitySource: existing?.identity_source ?? "derived"
@@ -722,80 +831,335 @@ function isNodeError3(error) {
   return error instanceof Error;
 }
 
-// src/services/doctor.ts
-import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "fs";
-import { access, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import { constants } from "fs";
-import { isAbsolute as isAbsolute3, join as join7, posix as posix2, resolve as resolve4 } from "path";
-import {
-  agentsMetaSchema as agentsMetaSchema4,
-  forensicReportSchema,
-  ruleTestIndexSchema as ruleTestIndexSchema2
-} from "@fenglimg/fabric-shared";
-import { detectFramework } from "@fenglimg/fabric-shared/node";
-
-// src/services/rule-sections.ts
-import { readFile as readFile5 } from "fs/promises";
-import { join as join6 } from "path";
-
-// src/meta-reader.ts
-import { readFile as readFile3 } from "fs/promises";
-import { join as join3 } from "path";
-import { agentsMetaSchema as agentsMetaSchema2 } from "@fenglimg/fabric-shared";
-import { agentsMetaNodeSchema, agentsMetaSchema as agentsMetaSchema3 } from "@fenglimg/fabric-shared";
-var AgentsMetaFileMissingError = class extends Error {
-  constructor(metaPath) {
-    super(`Fabric agents metadata file is missing: ${metaPath}`);
-    this.metaPath = metaPath;
-    this.name = "AgentsMetaFileMissingError";
+// src/services/rule-sync.ts
+import { readdir as readdir2, readFile as readFile4, stat } from "fs/promises";
+import { existsSync as existsSync3, statSync as statSync2 } from "fs";
+import { join as join4, relative as relative2, sep as sep3 } from "path";
+import { RuleValidationError } from "@fenglimg/fabric-shared/errors";
+var lastSyncState = /* @__PURE__ */ new Map();
+var freshSyncCooldown = /* @__PURE__ */ new Map();
+var SYNC_COOLDOWN_MS = 500;
+function invalidateRuleSyncCooldown(projectRoot) {
+  freshSyncCooldown.delete(projectRoot);
+}
+async function readMetaEntries(projectRoot) {
+  const metaPath = join4(projectRoot, ".fabric", "agents.meta.json");
+  const map = /* @__PURE__ */ new Map();
+  let raw;
+  try {
+    raw = await readFile4(metaPath, "utf8");
+  } catch {
+    return map;
   }
-  metaPath;
-  code = "FABRIC_META_MISSING";
-};
-var AgentsMetaInvalidError = class extends Error {
-  constructor(metaPath, cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    super(`Fabric agents metadata file is invalid: ${metaPath}. ${detail}`);
-    this.metaPath = metaPath;
-    this.name = "AgentsMetaInvalidError";
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return map;
+  }
+  for (const node of Object.values(parsed.nodes ?? {})) {
+    const path = 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 });
+    }
   }
-  metaPath;
-  code = "FABRIC_META_INVALID";
-};
-function getAgentsMetaPath(projectRoot) {
-  return join3(projectRoot, ".fabric", "agents.meta.json");
+  return map;
 }
-function resolveProjectRoot() {
-  return process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
+async function findRuleFiles(projectRoot) {
+  const rulesRoot = join4(projectRoot, ".fabric", "rules");
+  if (!existsSync3(rulesRoot) || !statSync2(rulesRoot).isDirectory()) {
+    return [];
+  }
+  const files = [];
+  const stack = [rulesRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === void 0) {
+      continue;
+    }
+    for (const entry of await readdir2(current, { withFileTypes: true })) {
+      const absolutePath = join4(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(absolutePath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const rel = toPosixPath2(relative2(projectRoot, absolutePath));
+        files.push(rel);
+      }
+    }
+  }
+  return files.sort();
 }
-async function readAgentsMeta(projectRoot) {
-  const cached = contextCache.get("meta", projectRoot);
-  if (cached !== void 0) {
-    return cached;
+function toPosixPath2(p) {
+  return p.split(sep3).join("/");
+}
+function validateFrontmatter(source, filePath, throwOnInvalid) {
+  if (!source.startsWith("---")) {
+    return null;
   }
-  const metaPath = getAgentsMetaPath(projectRoot);
-  let raw;
+  const endIdx = source.indexOf("\n---", 3);
+  if (endIdx === -1) {
+    const msg = `Unterminated YAML frontmatter in ${filePath}`;
+    if (throwOnInvalid) {
+      throw new RuleValidationError(msg, {
+        actionHint: "Run `fab doctor --fix` to repair frontmatter",
+        fixable: true,
+        details: { file: filePath }
+      });
+    }
+    return {
+      code: "rule_frontmatter_invalid",
+      file: filePath,
+      action_hint: "Run `fab doctor --fix` to repair frontmatter"
+    };
+  }
+  const frontmatter = source.slice(3, endIdx).trim();
+  for (const line of frontmatter.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      continue;
+    }
+    if (!trimmed.includes(":") && !trimmed.startsWith("-")) {
+      const msg = `Invalid YAML frontmatter line "${trimmed}" in ${filePath}`;
+      if (throwOnInvalid) {
+        throw new RuleValidationError(msg, {
+          actionHint: "Run `fab doctor --fix` to repair frontmatter",
+          fixable: true,
+          details: { file: filePath, line: trimmed }
+        });
+      }
+      return {
+        code: "rule_frontmatter_invalid",
+        file: filePath,
+        action_hint: "Run `fab doctor --fix` to repair frontmatter"
+      };
+    }
+  }
+  return null;
+}
+async function processSingleFile(projectRoot, relPath, metaEntry, source, throwOnInvalidFrontmatter) {
+  const absPath = join4(projectRoot, relPath);
   try {
-    raw = await readFile3(metaPath, "utf8");
-  } catch (error) {
-    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-      throw new AgentsMetaFileMissingError(metaPath);
+    await stat(absPath);
+  } catch {
+    if (metaEntry !== void 0) {
+      return {
+        event: {
+          type: "rule_removed",
+          stable_id: metaEntry.stable_id,
+          path: relPath,
+          prev_hash: metaEntry.content_hash,
+          new_hash: null,
+          changed_fields: ["content"],
+          source
+        },
+        warning: null
+      };
     }
-    throw error;
+    return { event: null, warning: null };
   }
-  let parsed;
+  let content;
   try {
-    parsed = agentsMetaSchema2.parse(JSON.parse(raw));
-  } catch (error) {
-    throw new AgentsMetaInvalidError(metaPath, error);
+    content = await readFile4(absPath, "utf8");
+  } catch {
+    return { event: null, warning: null };
+  }
+  const newHash = sha256(content);
+  const now = Date.now();
+  const debounce = lastSyncState.get(absPath);
+  if (debounce !== void 0 && newHash === debounce.hash && now - debounce.ts < 500) {
+    return { event: null, warning: null };
+  }
+  if (metaEntry !== void 0 && newHash === metaEntry.content_hash) {
+    lastSyncState.set(absPath, { ts: now, hash: newHash });
+    return { event: null, warning: null };
+  }
+  const warning = validateFrontmatter(content, relPath, throwOnInvalidFrontmatter);
+  if (warning !== null) {
+    lastSyncState.set(absPath, { ts: now, hash: newHash });
+    return { event: null, warning };
+  }
+  const prevHash = metaEntry?.content_hash ?? debounce?.hash ?? null;
+  const stableId = metaEntry?.stable_id ?? relPath;
+  const eventType = metaEntry === void 0 ? "rule_added" : "rule_content_changed";
+  lastSyncState.set(absPath, { ts: now, hash: newHash });
+  return {
+    event: {
+      type: eventType,
+      stable_id: stableId,
+      path: relPath,
+      prev_hash: prevHash,
+      new_hash: newHash,
+      changed_fields: ["content"],
+      source
+    },
+    warning: null
+  };
+}
+async function appendRuleSyncEvents(projectRoot, events) {
+  if (events.length === 0) {
+    return;
+  }
+  const driftedIds = events.map((e) => e.stable_id);
+  const missingFiles = events.filter((e) => e.type === "rule_removed").map((e) => e.path);
+  const staleFiles = events.filter((e) => e.type !== "rule_removed").map((e) => e.path);
+  if (missingFiles.length > 0 || staleFiles.length > 0) {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "rule_drift_detected",
+      drifted_stable_ids: driftedIds,
+      missing_files: missingFiles,
+      stale_files: staleFiles
+    });
   }
-  contextCache.set("meta", projectRoot, parsed);
-  return parsed;
+}
+async function ensureRulesFresh(projectRoot, opts) {
+  const mode = opts?.mode ?? "incremental";
+  const cooldownExpiry = freshSyncCooldown.get(projectRoot);
+  if (cooldownExpiry !== void 0 && Date.now() < cooldownExpiry && mode !== "full") {
+    return { status: "fresh", events: [], warnings: [] };
+  }
+  const throwOnInvalidFrontmatter = opts?.throwOnInvalidFrontmatter ?? false;
+  const source = "ensureRulesFresh";
+  const events = [];
+  const warnings = [];
+  const metaEntries = await readMetaEntries(projectRoot);
+  const ruleFiles = await findRuleFiles(projectRoot);
+  const filesToCheck = ruleFiles;
+  for (const relPath of filesToCheck) {
+    const metaEntry = metaEntries.get(relPath);
+    const result = await processSingleFile(projectRoot, relPath, metaEntry, source, throwOnInvalidFrontmatter);
+    if (result.event !== null) {
+      events.push(result.event);
+    }
+    if (result.warning !== null) {
+      warnings.push(result.warning);
+    }
+  }
+  for (const [relPath, entry] of metaEntries) {
+    if (!ruleFiles.includes(relPath)) {
+      const absPath = join4(projectRoot, relPath);
+      if (!existsSync3(absPath)) {
+        events.push({
+          type: "rule_removed",
+          stable_id: entry.stable_id,
+          path: relPath,
+          prev_hash: entry.content_hash,
+          new_hash: null,
+          changed_fields: ["content"],
+          source
+        });
+      }
+    }
+  }
+  if (events.length === 0 && warnings.length === 0) {
+    freshSyncCooldown.set(projectRoot, Date.now() + SYNC_COOLDOWN_MS);
+    return { status: "fresh", events: [], warnings: [] };
+  }
+  if (events.length > 0) {
+    await appendRuleSyncEvents(projectRoot, events);
+    contextCache.invalidate("file_watch", projectRoot);
+  }
+  freshSyncCooldown.delete(projectRoot);
+  const status = warnings.length > 0 ? "errors" : "reconciled";
+  return {
+    status,
+    events,
+    warnings,
+    reconciled_files: events.map((e) => e.path)
+  };
+}
+async function reconcileRules(projectRoot, opts) {
+  freshSyncCooldown.delete(projectRoot);
+  const trigger = opts?.trigger;
+  const startTime = Date.now();
+  const source = "reconcileRules";
+  const events = [];
+  const warnings = [];
+  const metaEntries = await readMetaEntries(projectRoot);
+  const ruleFiles = await findRuleFiles(projectRoot);
+  for (const relPath of ruleFiles) {
+    const metaEntry = metaEntries.get(relPath);
+    const result = await processSingleFile(projectRoot, relPath, metaEntry, source, false);
+    if (result.event !== null) {
+      events.push(result.event);
+    }
+    if (result.warning !== null) {
+      warnings.push(result.warning);
+    }
+  }
+  for (const [relPath, entry] of metaEntries) {
+    if (!ruleFiles.includes(relPath)) {
+      const absPath = join4(projectRoot, relPath);
+      if (!existsSync3(absPath)) {
+        events.push({
+          type: "rule_removed",
+          stable_id: entry.stable_id,
+          path: relPath,
+          prev_hash: entry.content_hash,
+          new_hash: null,
+          changed_fields: ["content"],
+          source
+        });
+      }
+    }
+  }
+  if (events.length > 0) {
+    await writeRuleMeta(projectRoot, { source: "sync_meta" });
+    await appendRuleSyncEvents(projectRoot, events);
+    contextCache.invalidate("file_watch", projectRoot);
+  }
+  const duration_ms = Date.now() - startTime;
+  const reconciledFiles = events.map((e) => e.path);
+  if (trigger !== void 0 && events.length > 0) {
+    if (trigger === "startup") {
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "meta_reconciled_on_startup",
+        reconciled_files: reconciledFiles,
+        duration_ms,
+        source: "reconcileRules"
+      });
+    } else {
+      await appendEventLedgerEvent(projectRoot, {
+        event_type: "meta_reconciled",
+        reconciled_files: reconciledFiles,
+        duration_ms,
+        trigger,
+        source: "reconcileRules"
+      });
+    }
+  }
+  if (events.length === 0 && warnings.length === 0) {
+    return { status: "fresh", events: [], warnings: [] };
+  }
+  const status = warnings.length > 0 ? "errors" : "reconciled";
+  return {
+    status,
+    events,
+    warnings,
+    reconciled_files: reconciledFiles
+  };
 }
 
+// src/services/doctor.ts
+import { existsSync as existsSync4, mkdirSync, readdirSync, readFileSync, rmdirSync, renameSync, statSync as statSync3, unlinkSync } from "fs";
+import { access, readFile as readFile7, writeFile as writeFile2 } from "fs/promises";
+import { constants } from "fs";
+import { isAbsolute as isAbsolute3, join as join8, posix as posix2, resolve as resolve4 } from "path";
+import {
+  agentsMetaSchema as agentsMetaSchema4,
+  forensicReportSchema,
+  ruleTestIndexSchema as ruleTestIndexSchema2
+} from "@fenglimg/fabric-shared";
+import { detectFramework } from "@fenglimg/fabric-shared/node";
+
+// src/services/rule-sections.ts
+import { readFile as readFile6 } from "fs/promises";
+import { join as join7 } from "path";
+
 // src/services/audit-log.ts
-import { open, stat } from "fs/promises";
-import { isAbsolute as isAbsolute2, join as join4, posix, relative as relative2, resolve as resolve3 } from "path";
+import { open, stat as stat2 } from "fs/promises";
+import { isAbsolute as isAbsolute2, join as join5, posix, relative as relative3, resolve as resolve3 } from "path";
 var AUDIT_LOG_FILE = `${FABRIC_DIR}/audit.jsonl`;
 var DEFAULT_AUDIT_WINDOW_MS = 5 * 60 * 1e3;
 async function appendGetRulesAuditEvent(projectRoot, input) {
@@ -842,7 +1206,7 @@ async function appendRuleSelectionAuditEvent(projectRoot, input) {
 function normalizeAuditPath(projectRoot, value) {
   const normalizedProjectRoot = resolve3(projectRoot);
   const candidate = isAbsolute2(value) ? resolve3(value) : resolve3(normalizedProjectRoot, value);
-  const relativePath = relative2(normalizedProjectRoot, candidate);
+  const relativePath = relative3(normalizedProjectRoot, candidate);
   if (relativePath.length > 0 && relativePath !== "." && !relativePath.startsWith("..") && !isAbsolute2(relativePath)) {
     return posix.normalize(relativePath.split("\\").join("/"));
   }
@@ -899,8 +1263,8 @@ async function appendAuditLogEventLedgerEvents(projectRoot, entries, metadata =
 }
 
 // src/services/get-rules.ts
-import { readFile as readFile4 } from "fs/promises";
-import { join as join5 } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join6 } from "path";
 import { minimatch } from "minimatch";
 var PRIORITY_ORDER = {
   high: 0,
@@ -939,7 +1303,7 @@ async function loadGetRulesContext(projectRoot) {
     return cached;
   }
   const meta = await readAgentsMeta(projectRoot);
-  const l0Content = await readFile4(join5(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
+  const l0Content = await readFile5(join6(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
   const context = {
     meta,
     l0Content,
@@ -1078,7 +1442,7 @@ async function readRuleContent(projectRoot, file, fileContentCache) {
   if (cached !== void 0) {
     return await cached;
   }
-  const pending = readFile4(join5(projectRoot, file), "utf8");
+  const pending = readFile5(join6(projectRoot, file), "utf8");
   fileContentCache.set(file, pending);
   return await pending;
 }
@@ -1376,7 +1740,7 @@ async function getRuleSections(projectRoot, input) {
   const diagnostics = [];
   const rules = [];
   for (const rule of selectedRules) {
-    const content = await readFile5(join6(projectRoot, rule.path), "utf8");
+    const content = await readFile6(join7(projectRoot, rule.path), "utf8");
     const parsedSections = parseRuleSections(content);
     const sections = {};
     for (const section of input.sections) {
@@ -1498,6 +1862,9 @@ function pickSelectionReasons(selectedStableIds, reasons) {
 }
 
 // src/services/doctor.ts
+import { atomicWriteJson as atomicWriteJson2, atomicWriteText as atomicWriteText3 } from "@fenglimg/fabric-shared/node/atomic-write";
+import { buildBootstrapContent, FABRIC_BOOTSTRAP_PATH } from "@fenglimg/fabric-shared/node/bootstrap-guide";
+var LEGACY_CLIENT_PATH_KEYS = ["windsurf", "rooCode", "geminiCLI"];
 var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
 var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
   ".fabric",
@@ -1539,8 +1906,16 @@ async function runDoctorReport(target) {
     inspectRuleSections(projectRoot),
     inspectRuleTestIndex(projectRoot)
   ]);
-  const taxonomyExists = existsSync2(join7(projectRoot, ".fabric", "INITIAL_TAXONOMY.md"));
-  const bootstrapExists = existsSync2(join7(projectRoot, ".fabric", "bootstrap", "README.md"));
+  const mcpConfigInWrongFile = inspectMcpConfigInWrongFile(projectRoot);
+  const metaManuallyDiverged = await inspectMetaManuallyDiverged(projectRoot);
+  const rulesDirUnindexed = inspectRulesDirUnindexed(projectRoot, meta);
+  const stableIdCollision = await inspectStableIdCollisions(projectRoot);
+  const claudeSkillLegacyPath = inspectClaudeSkillLegacyPath(projectRoot);
+  const claudeHookLegacyPath = inspectClaudeHookLegacyPath(projectRoot);
+  const preexistingRootFiles = inspectPreexistingRootFiles(projectRoot);
+  const legacyClientPaths = inspectLegacyClientPaths(projectRoot);
+  const taxonomyExists = existsSync4(join8(projectRoot, ".fabric", "INITIAL_TAXONOMY.md"));
+  const bootstrapExists = existsSync4(join8(projectRoot, ".fabric", "bootstrap", "README.md"));
   const checks = [
     createBootstrapCheck(bootstrapExists),
     createTaxonomyCheck(taxonomyExists),
@@ -1550,17 +1925,28 @@ async function runDoctorReport(target) {
     createRuleContentRefCheck(meta),
     createRuleSectionsCheck(ruleSections),
     createRuleTestIndexCheck(ruleTestIndex),
-    createEventLedgerCheck(eventLedger)
+    createEventLedgerCheck(eventLedger),
+    createEventLedgerPartialWriteCheck(eventLedger),
+    createMcpConfigInWrongFileCheck(mcpConfigInWrongFile),
+    createMetaManuallyDivergedCheck(metaManuallyDiverged),
+    createRulesDirUnindexedCheck(rulesDirUnindexed),
+    createStableIdCollisionCheck(stableIdCollision),
+    createClaudeSkillLegacyPathCheck(claudeSkillLegacyPath),
+    createClaudeHookLegacyPathCheck(claudeHookLegacyPath),
+    createPreexistingRootFilesCheck(preexistingRootFiles),
+    createLegacyClientPathCheck(legacyClientPaths)
   ];
   const fixableErrors = collectIssues(checks, "fixable_error");
   const manualErrors = collectIssues(checks, "manual_error");
   const warnings = collectIssues(checks, "warning");
+  const infos = collectIssues(checks, "info");
   return {
     status: reduceStatus(checks.map((check) => check.status)),
     checks,
     fixable_errors: fixableErrors,
     manual_errors: manualErrors,
     warnings,
+    infos,
     summary: {
       target: projectRoot,
       framework: {
@@ -1576,8 +1962,9 @@ async function runDoctorReport(target) {
       fixableErrorCount: fixableErrors.length,
       manualErrorCount: manualErrors.length,
       warningCount: warnings.length,
+      infoCount: infos.length,
       targetFiles: Object.fromEntries(
-        TARGET_FILE_PATHS.map((path) => [path, existsSync2(join7(projectRoot, path))])
+        TARGET_FILE_PATHS.map((path) => [path, existsSync4(join8(projectRoot, path))])
       )
     }
   };
@@ -1595,16 +1982,57 @@ async function runDoctorFix(target) {
     fixed.push(findIssue(before.fixable_errors, "event_ledger_missing"));
   }
   if (before.fixable_errors.some(
-    (issue) => ["agents_meta_missing", "agents_meta_stale", "rule_test_index_missing", "rule_test_index_stale"].includes(issue.code)
+    (issue) => [
+      "agents_meta_missing",
+      "agents_meta_stale",
+      "rule_test_index_missing",
+      "rule_test_index_stale",
+      "content_ref_missing",
+      "rules_dir_unindexed"
+    ].includes(issue.code)
   )) {
-    await writeRuleMeta(projectRoot, { source: "doctor_fix" });
+    await reconcileRules(projectRoot, { trigger: "doctor" });
     for (const issue of before.fixable_errors.filter(
-      (candidate) => ["agents_meta_missing", "agents_meta_stale", "rule_test_index_missing", "rule_test_index_stale"].includes(candidate.code)
+      (candidate) => [
+        "agents_meta_missing",
+        "agents_meta_stale",
+        "rule_test_index_missing",
+        "rule_test_index_stale",
+        "content_ref_missing",
+        "rules_dir_unindexed"
+      ].includes(candidate.code)
     )) {
       fixed.push(issue);
     }
     contextCache.invalidate("meta_write", projectRoot);
   }
+  if (before.fixable_errors.some((issue) => issue.code === "event_ledger_partial_write")) {
+    const ledgerPath = getEventLedgerPath(projectRoot);
+    const truncResult = await truncateLedgerToLastNewline(ledgerPath);
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "event_ledger_truncated",
+      byte_offset: truncResult.truncated_bytes,
+      byte_length: truncResult.truncated_bytes,
+      corrupted_path: truncResult.corrupted_path
+    });
+    fixed.push(findIssue(before.fixable_errors, "event_ledger_partial_write"));
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "mcp_config_in_wrong_file")) {
+    await fixMcpConfigInWrongFile(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "mcp_config_in_wrong_file"));
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "claude_skill_legacy_path")) {
+    await fixClaudeSkillLegacyPath(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "claude_skill_legacy_path"));
+  }
+  if (before.fixable_errors.some((issue) => issue.code === "claude_hook_legacy_path")) {
+    await fixClaudeHookLegacyPath(projectRoot);
+    fixed.push(findIssue(before.fixable_errors, "claude_hook_legacy_path"));
+  }
+  if (before.warnings.some((issue) => issue.code === "legacy_client_path_present")) {
+    await fixLegacyClientPaths(projectRoot);
+    fixed.push(findIssue(before.warnings, "legacy_client_path_present"));
+  }
   const report = await runDoctorReport(projectRoot);
   return {
     changed: fixed.length > 0,
@@ -1616,9 +2044,9 @@ async function runDoctorFix(target) {
   };
 }
 async function inspectForensic(projectRoot) {
-  const path = join7(projectRoot, ".fabric", "forensic.json");
+  const path = join8(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile6(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile7(path, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -1628,9 +2056,9 @@ async function inspectForensic(projectRoot) {
   }
 }
 async function inspectInitContext(projectRoot) {
-  const path = join7(projectRoot, ".fabric", "init-context.json");
+  const path = join8(projectRoot, ".fabric", "init-context.json");
   try {
-    JSON.parse(await readFile6(path, "utf8"));
+    JSON.parse(await readFile7(path, "utf8"));
     return { exists: true, validJson: true };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -1639,11 +2067,32 @@ async function inspectInitContext(projectRoot) {
     return { exists: true, validJson: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
+function inspectMcpConfigInWrongFile(projectRoot) {
+  const settingsPath = join8(projectRoot, ".claude", "settings.json");
+  if (!existsSync4(settingsPath)) {
+    return { hasWrongEntry: false, settingsPath };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { hasWrongEntry: false, settingsPath };
+    }
+    const settings = parsed;
+    const mcpServers = settings.mcpServers;
+    if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+      return { hasWrongEntry: false, settingsPath };
+    }
+    const hasWrongEntry = "fabric" in mcpServers;
+    return { hasWrongEntry, settingsPath };
+  } catch {
+    return { hasWrongEntry: false, settingsPath };
+  }
+}
 async function inspectMeta(projectRoot) {
-  const metaPath = join7(projectRoot, ".fabric", "agents.meta.json");
+  const metaPath = join8(projectRoot, ".fabric", "agents.meta.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
-    const raw = await readFile6(metaPath, "utf8");
+    const raw = await readFile7(metaPath, "utf8");
     const meta = agentsMetaSchema4.parse(JSON.parse(raw));
     const contentRefIssues = inspectContentRefs(projectRoot, meta);
     const changed = built === null ? false : built.changed;
@@ -1702,7 +2151,7 @@ function inspectContentRefs(projectRoot, meta) {
   for (const node of Object.values(meta.nodes)) {
     const contentRef = normalizePath(node.content_ref ?? node.file);
     if (contentRef === ".fabric/bootstrap/README.md") {
-      if (!existsSync2(join7(projectRoot, contentRef))) {
+      if (!existsSync4(join8(projectRoot, contentRef))) {
         missing.push(contentRef);
       }
       continue;
@@ -1711,7 +2160,7 @@ function inspectContentRefs(projectRoot, meta) {
       invalid.push(contentRef);
       continue;
     }
-    if (!existsSync2(join7(projectRoot, contentRef))) {
+    if (!existsSync4(join8(projectRoot, contentRef))) {
       missing.push(contentRef);
     }
   }
@@ -1719,19 +2168,23 @@ function inspectContentRefs(projectRoot, meta) {
 }
 async function inspectEventLedger(projectRoot) {
   const path = getEventLedgerPath(projectRoot);
-  const exists = existsSync2(path);
+  const exists = existsSync4(path);
   if (!exists) {
-    return { exists: false, writable: false, parseable: false, path };
+    return { exists: false, writable: false, parseable: false, hasPartialWrite: false, partialWriteByteOffset: 0, partialWriteByteLength: 0, path };
   }
   try {
     await access(path, constants.W_OK);
-    await readEventLedger(projectRoot);
-    const raw = await readFile6(path, "utf8");
+    const { warnings } = await readEventLedger(projectRoot);
+    const raw = await readFile7(path, "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 {
       exists: true,
       writable: true,
       parseable: invalidLine === void 0,
+      hasPartialWrite: partialWarning !== void 0,
+      partialWriteByteOffset: partialWarning?.byte_offset ?? 0,
+      partialWriteByteLength: partialWarning?.byte_length ?? 0,
       path,
       error: invalidLine === void 0 ? void 0 : "events.jsonl contains an invalid JSON line."
     };
@@ -1740,6 +2193,9 @@ async function inspectEventLedger(projectRoot) {
       exists: true,
       writable: false,
       parseable: false,
+      hasPartialWrite: false,
+      partialWriteByteOffset: 0,
+      partialWriteByteLength: 0,
       path,
       error: error instanceof Error ? error.message : String(error)
     };
@@ -1747,10 +2203,10 @@ async function inspectEventLedger(projectRoot) {
 }
 async function inspectRuleSections(projectRoot) {
   const invalidFiles = [];
-  const files = findRuleFiles(projectRoot);
+  const files = findRuleFiles2(projectRoot);
   for (const file of files) {
     try {
-      parseRuleSections(await readFile6(join7(projectRoot, file), "utf8"));
+      parseRuleSections(await readFile7(join8(projectRoot, file), "utf8"));
     } catch (error) {
       invalidFiles.push({
         file,
@@ -1764,10 +2220,10 @@ async function inspectRuleSections(projectRoot) {
   };
 }
 async function inspectRuleTestIndex(projectRoot) {
-  const path = join7(projectRoot, ".fabric", "rule-test.index.json");
+  const path = join8(projectRoot, ".fabric", "rule-test.index.json");
   const built = await tryBuildRuleMeta(projectRoot);
   try {
-    const index = ruleTestIndexSchema2.parse(JSON.parse(await readFile6(path, "utf8")));
+    const index = ruleTestIndexSchema2.parse(JSON.parse(await readFile7(path, "utf8")));
     return {
       present: true,
       valid: true,
@@ -1788,13 +2244,13 @@ async function inspectRuleTestIndex(projectRoot) {
 }
 function createBootstrapCheck(exists) {
   if (!exists) {
-    return issueCheck("Bootstrap README", "error", "fixable_error", "bootstrap_missing", ".fabric/bootstrap/README.md is missing.");
+    return issueCheck("Bootstrap README", "error", "fixable_error", "bootstrap_missing", ".fabric/bootstrap/README.md is missing.", "Run `fab doctor --fix` to generate the bootstrap guide.");
   }
   return okCheck("Bootstrap README", ".fabric/bootstrap/README.md exists.");
 }
 function createTaxonomyCheck(exists) {
   if (!exists) {
-    return issueCheck("Initial taxonomy", "error", "manual_error", "taxonomy_missing", ".fabric/INITIAL_TAXONOMY.md is missing.");
+    return issueCheck("Initial taxonomy", "error", "manual_error", "taxonomy_missing", ".fabric/INITIAL_TAXONOMY.md is missing.", "Run `fab init` to regenerate project scaffolding including INITIAL_TAXONOMY.md.");
   }
   return okCheck("Initial taxonomy", ".fabric/INITIAL_TAXONOMY.md exists.");
 }
@@ -1805,29 +2261,30 @@ function createForensicCheck(forensic, frameworkKind, entryPointCount) {
       "error",
       "manual_error",
       "forensic_missing",
-      `${forensic.error ?? ".fabric/forensic.json is missing."} Live scan detects ${frameworkKind} with ${entryPointCount} entry point${entryPointCount === 1 ? "" : "s"}.`
+      `${forensic.error ?? ".fabric/forensic.json is missing."} Live scan detects ${frameworkKind} with ${entryPointCount} entry point${entryPointCount === 1 ? "" : "s"}.`,
+      "Run `fab init` to regenerate .fabric/forensic.json."
     );
   }
   if (!forensic.valid) {
-    return issueCheck("Scan evidence", "error", "manual_error", "forensic_invalid", forensic.error ?? ".fabric/forensic.json is invalid.");
+    return issueCheck("Scan evidence", "error", "manual_error", "forensic_invalid", forensic.error ?? ".fabric/forensic.json is invalid.", "Run `fab init` to regenerate .fabric/forensic.json.");
   }
   return okCheck("Scan evidence", `.fabric/forensic.json is valid for ${forensic.report?.framework.kind ?? "unknown"}.`);
 }
 function createInitContextCheck(initContext) {
   if (!initContext.exists) {
-    return issueCheck("Init context", "error", "manual_error", "init_context_missing", initContext.error ?? ".fabric/init-context.json is missing.");
+    return issueCheck("Init context", "error", "manual_error", "init_context_missing", initContext.error ?? ".fabric/init-context.json is missing.", "Run the fabric-init skill in Claude Code or Codex CLI to complete initialization. See docs/migration-1.8.md FAQ.");
   }
   if (!initContext.validJson) {
-    return issueCheck("Init context", "error", "manual_error", "init_context_invalid", initContext.error ?? ".fabric/init-context.json is invalid.");
+    return issueCheck("Init context", "error", "manual_error", "init_context_invalid", initContext.error ?? ".fabric/init-context.json is invalid.", "Delete .fabric/init-context.json and run `fab init` to regenerate it.");
   }
   return okCheck("Init context", ".fabric/init-context.json is valid JSON.");
 }
 function createMetaCheck(meta) {
   if (!meta.present) {
-    return issueCheck("Agents metadata", "error", "fixable_error", "agents_meta_missing", ".fabric/agents.meta.json is missing.");
+    return issueCheck("Agents metadata", "error", "fixable_error", "agents_meta_missing", ".fabric/agents.meta.json is missing.", "Run `fab doctor --fix` to rebuild agents.meta.json from .fabric/rules/.");
   }
   if (!meta.valid) {
-    return issueCheck("Agents metadata", "error", "manual_error", "agents_meta_invalid", meta.readError ?? ".fabric/agents.meta.json is invalid.");
+    return issueCheck("Agents metadata", "error", "manual_error", "agents_meta_invalid", meta.readError ?? ".fabric/agents.meta.json is invalid.", "Delete .fabric/agents.meta.json and run `fab doctor --fix` to regenerate it.");
   }
   if (meta.stale) {
     return issueCheck(
@@ -1835,14 +2292,15 @@ function createMetaCheck(meta) {
       "error",
       "fixable_error",
       "agents_meta_stale",
-      `.fabric/agents.meta.json revision ${meta.revision} does not match .fabric/rules derived revision ${meta.computedRevision ?? "<unknown>"}.`
+      `.fabric/agents.meta.json revision ${meta.revision} does not match .fabric/rules derived revision ${meta.computedRevision ?? "<unknown>"}.`,
+      "Run `fab doctor --fix` to reconcile agents.meta.json with the current rule files."
     );
   }
   return okCheck("Agents metadata", `.fabric/agents.meta.json revision ${meta.revision} is aligned with .fabric/rules.`);
 }
 function createRuleContentRefCheck(meta) {
   if (!meta.valid) {
-    return issueCheck("Rule content refs", "error", "manual_error", "content_refs_unavailable", "Cannot inspect content_ref entries until agents.meta.json is valid.");
+    return issueCheck("Rule content refs", "error", "manual_error", "content_refs_unavailable", "Cannot inspect content_ref entries until agents.meta.json is valid.", "Fix agents.meta.json first: run `fab doctor --fix`.");
   }
   if (meta.invalidContentRefs.length > 0) {
     return issueCheck(
@@ -1850,16 +2308,18 @@ function createRuleContentRefCheck(meta) {
       "error",
       "manual_error",
       "content_ref_outside_rules",
-      `${meta.invalidContentRefs.length} content_ref entr${meta.invalidContentRefs.length === 1 ? "y is" : "ies are"} outside .fabric/rules.`
+      `${meta.invalidContentRefs.length} content_ref entr${meta.invalidContentRefs.length === 1 ? "y is" : "ies are"} outside .fabric/rules.`,
+      "Edit agents.meta.json to ensure all content_ref values point inside .fabric/rules/."
     );
   }
   if (meta.missingContentRefs.length > 0) {
     return issueCheck(
       "Rule content refs",
       "error",
-      "manual_error",
+      "fixable_error",
       "content_ref_missing",
-      `${meta.missingContentRefs.length} content_ref target${meta.missingContentRefs.length === 1 ? "" : "s"} are missing.`
+      `${meta.missingContentRefs.length} content_ref target${meta.missingContentRefs.length === 1 ? "" : "s"} are missing. Run \`fab doctor --fix\` to reconcile.`,
+      "Run `fab doctor --fix` to reconcile agents.meta.json with the files present in .fabric/rules/."
     );
   }
   return okCheck("Rule content refs", "All content_ref entries resolve to .fabric/rules files or bootstrap README.");
@@ -1871,46 +2331,77 @@ function createRuleSectionsCheck(snapshot) {
       "error",
       "manual_error",
       "rule_sections_invalid",
-      `${snapshot.invalidFiles.length} rule file${snapshot.invalidFiles.length === 1 ? "" : "s"} could not be parsed.`
+      `${snapshot.invalidFiles.length} rule file${snapshot.invalidFiles.length === 1 ? "" : "s"} could not be parsed.`,
+      "Edit the rule file(s) to fix the section structure, then re-run `fab doctor`."
     );
   }
   return okCheck("Rule sections", `${snapshot.checkedCount} .fabric/rules file${snapshot.checkedCount === 1 ? "" : "s"} parsed.`);
 }
 function createRuleTestIndexCheck(index) {
   if (!index.present) {
-    return issueCheck("Rule-test index", "error", "fixable_error", "rule_test_index_missing", index.error);
+    return issueCheck("Rule-test index", "error", "fixable_error", "rule_test_index_missing", index.error, "Run `fab doctor --fix` to rebuild .fabric/rule-test.index.json.");
   }
   if (!index.valid) {
-    return issueCheck("Rule-test index", "error", "manual_error", "rule_test_index_invalid", index.error);
+    return issueCheck("Rule-test index", "error", "manual_error", "rule_test_index_invalid", index.error, "Delete .fabric/rule-test.index.json and run `fab doctor --fix` to regenerate it.");
   }
   if (index.stale) {
-    return issueCheck("Rule-test index", "error", "fixable_error", "rule_test_index_stale", ".fabric/rule-test.index.json is stale.");
+    return issueCheck("Rule-test index", "error", "fixable_error", "rule_test_index_stale", ".fabric/rule-test.index.json is stale.", "Run `fab doctor --fix` to rebuild the rule-test index.");
   }
   return okCheck("Rule-test index", `${index.linkCount} link${index.linkCount === 1 ? "" : "s"} and ${index.orphanCount} orphan annotation${index.orphanCount === 1 ? "" : "s"} indexed.`);
 }
 function createEventLedgerCheck(ledger) {
   if (!ledger.exists) {
-    return issueCheck("Event ledger", "error", "fixable_error", "event_ledger_missing", ".fabric/events.jsonl is missing.");
+    return issueCheck("Event ledger", "error", "fixable_error", "event_ledger_missing", ".fabric/events.jsonl is missing.", "Run `fab doctor --fix` to create .fabric/events.jsonl.");
   }
   if (!ledger.writable) {
-    return issueCheck("Event ledger", "error", "manual_error", "event_ledger_not_writable", ledger.error ?? ".fabric/events.jsonl is not writable.");
+    return issueCheck("Event ledger", "error", "manual_error", "event_ledger_not_writable", ledger.error ?? ".fabric/events.jsonl is not writable.", "Check file permissions on .fabric/events.jsonl and ensure no other process holds a write lock.");
   }
   if (!ledger.parseable) {
-    return issueCheck("Event ledger", "error", "manual_error", "event_ledger_invalid", ledger.error ?? ".fabric/events.jsonl is invalid.");
+    return issueCheck("Event ledger", "error", "manual_error", "event_ledger_invalid", ledger.error ?? ".fabric/events.jsonl is invalid.", "Delete .fabric/events.jsonl and run `fab doctor --fix` to recreate it.");
   }
   return okCheck("Event ledger", ".fabric/events.jsonl exists, is writable, and is parseable.");
 }
+function createMcpConfigInWrongFileCheck(inspection) {
+  if (inspection.hasWrongEntry) {
+    return issueCheck(
+      "Claude MCP config location",
+      "error",
+      "fixable_error",
+      "mcp_config_in_wrong_file",
+      `.claude/settings.json contains mcpServers.fabric \u2014 this file is for hooks/permissions only. Run --fix to remove it, then re-run fab init to write .mcp.json.`,
+      "Run `fab doctor --fix` to remove mcpServers.fabric from .claude/settings.json, then run `fab init` to write .mcp.json."
+    );
+  }
+  return okCheck("Claude MCP config location", "mcpServers.fabric is not in .claude/settings.json.");
+}
+function createEventLedgerPartialWriteCheck(ledger) {
+  if (!ledger.exists || !ledger.writable) {
+    return okCheck("Event ledger partial write", "No partial-write check needed (ledger missing or not writable).");
+  }
+  if (ledger.hasPartialWrite) {
+    return issueCheck(
+      "Event ledger partial write",
+      "error",
+      "fixable_error",
+      "event_ledger_partial_write",
+      `events.jsonl has a partial write at byte offset ${ledger.partialWriteByteOffset} (${ledger.partialWriteByteLength} corrupted bytes). Run --fix to truncate and preserve corrupted bytes.`,
+      "Run `fab doctor --fix` to truncate the partial write and restore events.jsonl to a valid state."
+    );
+  }
+  return okCheck("Event ledger partial write", "events.jsonl has no partial trailing write.");
+}
 function okCheck(name, message) {
   return { name, status: "ok", message };
 }
-function issueCheck(name, status, kind, code, message) {
+function issueCheck(name, status, kind, code, message, actionHint) {
   return {
     name,
     status,
     kind,
     code,
     fixable: kind === "fixable_error",
-    message
+    message,
+    actionHint
   };
 }
 function collectIssues(checks, kind) {
@@ -1927,10 +2418,403 @@ function findIssue(issues, code) {
     message: code
   };
 }
+async function inspectMetaManuallyDiverged(projectRoot) {
+  const metaPath = join8(projectRoot, ".fabric", "agents.meta.json");
+  if (!existsSync4(metaPath)) {
+    return { extraMetaEntries: [], hashMismatchEntries: [], readable: false };
+  }
+  let meta;
+  try {
+    const raw = await readFile7(metaPath, "utf8");
+    meta = agentsMetaSchema4.parse(JSON.parse(raw));
+  } catch (error) {
+    return {
+      extraMetaEntries: [],
+      hashMismatchEntries: [],
+      readable: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const extraMetaEntries = [];
+  const hashMismatchEntries = [];
+  for (const node of Object.values(meta.nodes)) {
+    const contentRef = node.content_ref ?? node.file;
+    const absPath = join8(projectRoot, contentRef);
+    if (!existsSync4(absPath)) {
+      extraMetaEntries.push(contentRef);
+      continue;
+    }
+    try {
+      const content = readFileSync(absPath, "utf8");
+      const diskHash = sha256(content);
+      if (node.hash !== "" && node.hash !== diskHash) {
+        hashMismatchEntries.push(contentRef);
+      }
+    } catch {
+      extraMetaEntries.push(contentRef);
+    }
+  }
+  return { extraMetaEntries, hashMismatchEntries, readable: true };
+}
+function inspectRulesDirUnindexed(projectRoot, meta) {
+  const rulesDir = join8(projectRoot, ".fabric", "rules");
+  if (!existsSync4(rulesDir)) {
+    return { unindexedFiles: [] };
+  }
+  const physicalMdFiles = /* @__PURE__ */ new Set();
+  const stack = [rulesDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (dir === void 0) {
+      continue;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(abs);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const rel = posix2.join(".fabric/rules", abs.slice(rulesDir.length + 1).replace(/\\/gu, "/"));
+        physicalMdFiles.add(rel);
+      }
+    }
+  }
+  const indexedRefs = /* @__PURE__ */ new Set();
+  if (meta.valid && meta.meta !== null) {
+    for (const node of Object.values(meta.meta.nodes)) {
+      const ref = normalizePath(node.content_ref ?? node.file);
+      indexedRefs.add(ref);
+    }
+  }
+  const unindexedFiles = [...physicalMdFiles].filter((f) => !indexedRefs.has(f)).sort();
+  return { unindexedFiles };
+}
+function createRulesDirUnindexedCheck(inspection) {
+  if (inspection.unindexedFiles.length > 0) {
+    return issueCheck(
+      "Rules dir unindexed",
+      "error",
+      "fixable_error",
+      "rules_dir_unindexed",
+      `${inspection.unindexedFiles.length} .md file${inspection.unindexedFiles.length === 1 ? "" : "s"} in .fabric/rules/ not indexed in agents.meta.json. Run \`fab doctor --fix\` to index the missing rule files.`,
+      "Run `fab doctor --fix` to index the missing rule files."
+    );
+  }
+  return okCheck("Rules dir unindexed", "All .fabric/rules/ .md files are indexed in agents.meta.json.");
+}
+async function inspectStableIdCollisions(projectRoot) {
+  const rulesDir = join8(projectRoot, ".fabric", "rules");
+  if (!existsSync4(rulesDir)) {
+    return { collisions: [] };
+  }
+  const mdFiles = [];
+  const stack = [rulesDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (dir === void 0) {
+      continue;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join8(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(abs);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        mdFiles.push(abs);
+      }
+    }
+  }
+  const stableIdToFiles = /* @__PURE__ */ new Map();
+  const DECLARED_ID_PATTERN = /^(?:\uFEFF)?(?:---\r?\n[\s\S]*?\r?\n---\s*(?:\r?\n|$))?<!--\s*fab:rule-id\s+([A-Za-z0-9][A-Za-z0-9/_-]*)\s*-->\s*(?:\r?\n|$)/u;
+  for (const absPath of mdFiles) {
+    let source;
+    try {
+      source = await readFile7(absPath, "utf8");
+    } catch {
+      continue;
+    }
+    const match = DECLARED_ID_PATTERN.exec(source);
+    if (match === null) {
+      continue;
+    }
+    const stableId = match[1];
+    const relPath = posix2.join(".fabric/rules", absPath.slice(rulesDir.length + 1).replace(/\\/gu, "/"));
+    const existing = stableIdToFiles.get(stableId) ?? [];
+    existing.push(relPath);
+    stableIdToFiles.set(stableId, existing);
+  }
+  const collisions = [];
+  for (const [stable_id, files] of stableIdToFiles) {
+    if (files.length > 1) {
+      collisions.push({ stable_id, files: files.sort() });
+    }
+  }
+  return { collisions: collisions.sort((a, b) => a.stable_id.localeCompare(b.stable_id)) };
+}
+function createStableIdCollisionCheck(inspection) {
+  if (inspection.collisions.length > 0) {
+    const first = inspection.collisions[0];
+    const detail = inspection.collisions.length === 1 ? `stable_id "${first.stable_id}" is declared in ${first.files.length} files: ${first.files.join(", ")}.` : `${inspection.collisions.length} stable_id collision${inspection.collisions.length === 1 ? "" : "s"} detected. First: "${first.stable_id}" in ${first.files.join(", ")}.`;
+    return issueCheck(
+      "Stable ID collision",
+      "warn",
+      "warning",
+      "stable_id_collision",
+      `${detail} Edit one of the rule files to use a unique stable_id.`,
+      "Edit one of the colliding rule files to declare a different `<!-- fab:rule-id X -->` value."
+    );
+  }
+  return okCheck("Stable ID collision", "No declared stable_id collisions found in .fabric/rules/.");
+}
+function createMetaManuallyDivergedCheck(inspection) {
+  if (!inspection.readable) {
+    return okCheck("Meta manual divergence", "agents.meta.json not readable; skipping divergence check.");
+  }
+  if (inspection.extraMetaEntries.length > 0) {
+    return issueCheck(
+      "Meta manual divergence",
+      "warn",
+      "warning",
+      "meta_manually_diverged",
+      `agents.meta.json has ${inspection.extraMetaEntries.length} entr${inspection.extraMetaEntries.length === 1 ? "y" : "ies"} with no backing file on disk. Run --fix to reconcile.`,
+      "Run `fab doctor --fix` to reconcile agents.meta.json with the rule files currently on disk."
+    );
+  }
+  if (inspection.hashMismatchEntries.length > 0) {
+    return issueCheck(
+      "Meta manual divergence",
+      "warn",
+      "warning",
+      "meta_manually_diverged",
+      `agents.meta.json has ${inspection.hashMismatchEntries.length} entr${inspection.hashMismatchEntries.length === 1 ? "y" : "ies"} whose hash does not match the file on disk. Run --fix to reconcile.`,
+      "Run `fab doctor --fix` to reconcile agents.meta.json with the current rule file contents."
+    );
+  }
+  return okCheck("Meta manual divergence", "agents.meta.json is consistent with rule files on disk.");
+}
+function inspectPreexistingRootFiles(projectRoot) {
+  const candidates = ["CLAUDE.md", "AGENTS.md"];
+  const detected = candidates.filter((name) => existsSync4(join8(projectRoot, name)));
+  return { detected };
+}
+function createPreexistingRootFilesCheck(inspection) {
+  if (inspection.detected.length === 0) {
+    return okCheck("Preexisting root markdown", "No CLAUDE.md or AGENTS.md detected at project root.");
+  }
+  return {
+    name: "Preexisting root markdown",
+    status: "ok",
+    kind: "info",
+    code: "preexisting_root_claude_md",
+    fixable: false,
+    message: `${inspection.detected.join(", ")} detected at project root. These root files are not auto-loaded by Fabric MCP.`,
+    actionHint: "Move rule content to `.fabric/rules/` if you want it available in MCP responses."
+  };
+}
+function inspectClaudeSkillLegacyPath(projectRoot) {
+  const legacyPath = join8(projectRoot, ".claude", "skills", "agents-md-init", "SKILL.md");
+  const newPath = join8(projectRoot, ".claude", "skills", "fabric-init", "SKILL.md");
+  const hasLegacy = existsSync4(legacyPath) && !existsSync4(newPath);
+  return { hasLegacy, legacyPath, newPath };
+}
+function createClaudeSkillLegacyPathCheck(inspection) {
+  if (inspection.hasLegacy) {
+    return issueCheck(
+      "Claude skill path",
+      "error",
+      "fixable_error",
+      "claude_skill_legacy_path",
+      `.claude/skills/agents-md-init/SKILL.md exists at the legacy path. Run --fix to migrate it to .claude/skills/fabric-init/SKILL.md (user edits preserved).`,
+      "Run `fab doctor --fix` to rename agents-md-init/ to fabric-init/, preserving any user edits to SKILL.md."
+    );
+  }
+  return okCheck("Claude skill path", ".claude/skills/fabric-init/SKILL.md is at the canonical path (or not present).");
+}
+async function fixClaudeSkillLegacyPath(projectRoot) {
+  const legacyPath = join8(projectRoot, ".claude", "skills", "agents-md-init", "SKILL.md");
+  const newPath = join8(projectRoot, ".claude", "skills", "fabric-init", "SKILL.md");
+  if (!existsSync4(legacyPath)) {
+    return;
+  }
+  mkdirSync(join8(newPath, ".."), { recursive: true });
+  renameSync(legacyPath, newPath);
+  const legacyDir = join8(legacyPath, "..");
+  try {
+    rmdirSync(legacyDir);
+  } catch {
+  }
+  await appendEventLedgerEvent(projectRoot, {
+    event_type: "claude_skill_path_migrated",
+    from: legacyPath,
+    to: newPath
+  });
+}
+var LEGACY_HOOK_FILENAME = "agents-md-init-reminder.cjs";
+var NEW_HOOK_FILENAME = "fabric-init-reminder.cjs";
+function inspectClaudeHookLegacyPath(projectRoot) {
+  const legacyHookPath = join8(projectRoot, ".claude", "hooks", LEGACY_HOOK_FILENAME);
+  const newHookPath = join8(projectRoot, ".claude", "hooks", NEW_HOOK_FILENAME);
+  const settingsPath = join8(projectRoot, ".claude", "settings.json");
+  const hasLegacyFile = existsSync4(legacyHookPath);
+  let hasLegacySettingsCommand = false;
+  if (existsSync4(settingsPath)) {
+    try {
+      const raw = readFileSync(settingsPath, "utf8");
+      hasLegacySettingsCommand = raw.includes(LEGACY_HOOK_FILENAME);
+    } catch {
+    }
+  }
+  return { hasLegacyFile, hasLegacySettingsCommand, legacyHookPath, newHookPath, settingsPath };
+}
+function createClaudeHookLegacyPathCheck(inspection) {
+  if (inspection.hasLegacyFile || inspection.hasLegacySettingsCommand) {
+    return issueCheck(
+      "Claude hook path",
+      "error",
+      "fixable_error",
+      "claude_hook_legacy_path",
+      `.claude/hooks/${LEGACY_HOOK_FILENAME} (or its reference in .claude/settings.json) exists at the legacy path. Run --fix to migrate to ${NEW_HOOK_FILENAME}.`,
+      `Run \`fab doctor --fix\` to rename ${LEGACY_HOOK_FILENAME} to ${NEW_HOOK_FILENAME} and update .claude/settings.json hook commands.`
+    );
+  }
+  return okCheck("Claude hook path", `.claude/hooks/${NEW_HOOK_FILENAME} is at the canonical path (or not present).`);
+}
+async function fixClaudeHookLegacyPath(projectRoot) {
+  const { hasLegacyFile, hasLegacySettingsCommand, legacyHookPath, newHookPath, settingsPath } = inspectClaudeHookLegacyPath(projectRoot);
+  if (hasLegacyFile) {
+    if (existsSync4(newHookPath)) {
+      unlinkSync(legacyHookPath);
+    } else {
+      mkdirSync(join8(newHookPath, ".."), { recursive: true });
+      renameSync(legacyHookPath, newHookPath);
+    }
+  }
+  if (hasLegacySettingsCommand) {
+    try {
+      const raw = readFileSync(settingsPath, "utf8");
+      const updated = raw.split(LEGACY_HOOK_FILENAME).join(NEW_HOOK_FILENAME);
+      if (updated !== raw) {
+        const parsed = JSON.parse(updated);
+        await atomicWriteJson2(settingsPath, parsed);
+      }
+    } catch {
+    }
+  }
+  if (hasLegacyFile || hasLegacySettingsCommand) {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "claude_hook_path_migrated",
+      from: legacyHookPath,
+      to: newHookPath
+    });
+  }
+}
+function inspectLegacyClientPaths(projectRoot) {
+  const configPath = join8(projectRoot, "fabric.config.json");
+  if (!existsSync4(configPath)) {
+    return { presentKeys: [] };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { presentKeys: [] };
+    }
+    const config = parsed;
+    const clientPaths = config.clientPaths;
+    if (clientPaths === null || typeof clientPaths !== "object" || Array.isArray(clientPaths)) {
+      return { presentKeys: [] };
+    }
+    const cp = clientPaths;
+    const presentKeys = LEGACY_CLIENT_PATH_KEYS.filter((key) => key in cp);
+    return { presentKeys };
+  } catch {
+    return { presentKeys: [] };
+  }
+}
+function createLegacyClientPathCheck(inspection) {
+  if (inspection.presentKeys.length > 0) {
+    return issueCheck(
+      "Legacy client paths",
+      "warn",
+      "warning",
+      "legacy_client_path_present",
+      `fabric.config.json contains deprecated clientPaths keys: ${inspection.presentKeys.join(", ")}. These clients are removed in 1.8.0; run --fix to clean now or accept the upcoming removal.`,
+      "Run `fab doctor --fix` to remove deprecated clientPaths keys (windsurf, rooCode, geminiCLI) from fabric.config.json."
+    );
+  }
+  return okCheck("Legacy client paths", "No deprecated clientPaths keys found in fabric.config.json.");
+}
+async function fixLegacyClientPaths(projectRoot) {
+  const configPath = join8(projectRoot, "fabric.config.json");
+  if (!existsSync4(configPath)) {
+    return;
+  }
+  let config;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return;
+    }
+    config = parsed;
+  } catch {
+    return;
+  }
+  const clientPaths = config.clientPaths;
+  if (clientPaths === null || typeof clientPaths !== "object" || Array.isArray(clientPaths)) {
+    return;
+  }
+  const cp = clientPaths;
+  const removed = [];
+  for (const key of LEGACY_CLIENT_PATH_KEYS) {
+    if (key in cp) {
+      delete cp[key];
+      removed.push(key);
+    }
+  }
+  if (removed.length === 0) {
+    return;
+  }
+  const updatedConfig = { ...config, clientPaths: cp };
+  await atomicWriteJson2(configPath, updatedConfig, { indent: 2 });
+  await appendEventLedgerEvent(projectRoot, {
+    event_type: "legacy_client_path_present",
+    removed
+  });
+}
+async function fixMcpConfigInWrongFile(projectRoot) {
+  const settingsPath = join8(projectRoot, ".claude", "settings.json");
+  if (!existsSync4(settingsPath)) {
+    return;
+  }
+  let settings;
+  try {
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return;
+    }
+    settings = parsed;
+  } catch {
+    return;
+  }
+  const mcpServers = settings.mcpServers;
+  if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    return;
+  }
+  const { fabric: _removed, ...remainingServers } = mcpServers;
+  const cleaned = { ...settings };
+  if (Object.keys(remainingServers).length === 0) {
+    delete cleaned.mcpServers;
+  } else {
+    cleaned.mcpServers = remainingServers;
+  }
+  await atomicWriteJson2(settingsPath, cleaned, { indent: 2 });
+  await appendEventLedgerEvent(projectRoot, {
+    event_type: "mcp_config_migrated",
+    source: "doctor_fix",
+    removed_from: ".claude/settings.json"
+  });
+}
 async function writeDefaultBootstrap(projectRoot) {
-  const path = join7(projectRoot, ".fabric", "bootstrap", "README.md");
+  const path = join8(projectRoot, FABRIC_BOOTSTRAP_PATH);
   await ensureParentDirectory(path);
-  await atomicWriteText(path, "# Fabric Bootstrap\n\nProject-specific Fabric bootstrap notes.\n");
+  await atomicWriteText3(path, buildBootstrapContent(projectRoot));
 }
 async function ensureEventLedger(projectRoot) {
   const path = getEventLedgerPath(projectRoot);
@@ -1942,9 +2826,9 @@ function createFixMessage(fixed, report) {
   const manualText = report.manual_errors.length === 0 ? "No manual errors remain." : `${report.manual_errors.length} manual error${report.manual_errors.length === 1 ? "" : "s"} remain.`;
   return `${fixedText} ${manualText}`;
 }
-function findRuleFiles(projectRoot) {
-  const rulesRoot = join7(projectRoot, ".fabric", "rules");
-  if (!existsSync2(rulesRoot) || !statSync2(rulesRoot).isDirectory()) {
+function findRuleFiles2(projectRoot) {
+  const rulesRoot = join8(projectRoot, ".fabric", "rules");
+  if (!existsSync4(rulesRoot) || !statSync3(rulesRoot).isDirectory()) {
     return [];
   }
   const files = [];
@@ -1955,7 +2839,7 @@ function findRuleFiles(projectRoot) {
       continue;
     }
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const absolutePath = join7(current, entry.name);
+      const absolutePath = join8(current, entry.name);
       const relativePath = normalizePath(absolutePath.slice(projectRoot.length + 1));
       if (entry.isDirectory()) {
         stack.push(absolutePath);
@@ -1981,7 +2865,7 @@ function normalizePath(path) {
   return posix2.normalize(path.split("\\").join("/"));
 }
 function collectEntryPoints(root) {
-  if (!existsSync2(root) || !statSync2(root).isDirectory()) {
+  if (!existsSync4(root) || !statSync3(root).isDirectory()) {
     return [];
   }
   const entries = [];
@@ -1992,7 +2876,7 @@ function collectEntryPoints(root) {
       continue;
     }
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const absolutePath = join7(current, entry.name);
+      const absolutePath = join8(current, entry.name);
       const relativePath = normalizePath(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -2052,8 +2936,6 @@ function isMissingFileError(error) {
 export {
   AGENTS_MD_RESOURCE_URI,
   contextCache,
-  AgentsMetaFileMissingError,
-  AgentsMetaInvalidError,
   resolveProjectRoot,
   readAgentsMeta,
   LEDGER_PATH,
@@ -2066,10 +2948,7 @@ export {
   isNodeError,
   appendEventLedgerEvent,
   readEventLedger,
-  getRules,
-  planContext,
-  RULE_SECTION_NAMES,
-  getRuleSections,
+  flushAndSyncEventLedger,
   buildRuleMeta,
   writeRuleMeta,
   computeRulesBasedAgentsMeta,
@@ -2078,6 +2957,12 @@ export {
   deriveRuleMetaTopologyType,
   isSameRuleTestIndex,
   stableStringify,
+  invalidateRuleSyncCooldown,
+  ensureRulesFresh,
+  reconcileRules,
+  getRules,
+  planContext,
+  getRuleSections,
   runDoctorReport,
   runDoctorFix
 };