@fenglimg/fabric-server 2.3.0-rc.3 → 2.3.0-rc.5

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile20 } from "fs/promises";
-import { join as join25, resolve as resolve4 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { readFile as readFile22 } from "fs/promises";
+import { join as join27, resolve as resolve4 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -893,7 +893,7 @@ async function awaitFirstReconcileGate(timeoutMs = 5e3) {
 
 // src/services/extract-knowledge.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { join as join7 } from "path";
 import {
   PROPOSED_REASON_DESCRIPTIONS_BY_LOCALE
@@ -901,10 +901,14 @@ import {
 import { hasSecrets, isPersonalScope, redactPii, resolveGlobalLocale } from "@fenglimg/fabric-shared";
 
 // src/services/cross-store-write.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile3 } from "fs/promises";
 import { join as join5 } from "path";
 import {
+  STORE_KNOWLEDGE_TYPE_DIRS,
   STORE_LAYOUT,
   STORE_PENDING_DIR,
+  STORE_PROJECT_ID_PATTERN,
   buildStoreResolveInput,
   createStoreResolver,
   isPersonalLeakIntoSharedStore,
@@ -916,6 +920,7 @@ import {
   PersonalScopeLeakError,
   StoreWriteTargetUnresolvedError
 } from "@fenglimg/fabric-shared/errors";
+import { withFileLock as withFileLock2 } from "@fenglimg/fabric-shared/node/atomic-write";
 function writeTargetUnresolved(scope, layer) {
   const actionHint = layer === "personal" ? "run `fabric install --global` to mint your personal store, then retry" : `mount + bind a shared store, then set an explicit route: \`fabric store switch-write <alias> --scope ${scope}\``;
   return new StoreWriteTargetUnresolvedError(
@@ -952,8 +957,25 @@ function resolveWriteTargetStoreDir(layer, projectRoot, semanticScope) {
 function resolveStorePendingBase(layer, projectRoot, semanticScope) {
   return join5(resolveWriteTargetStoreDir(layer, projectRoot, semanticScope), STORE_LAYOUT.knowledgeDir, STORE_PENDING_DIR);
 }
-function resolveStoreCanonicalBase(layer, projectRoot) {
-  return join5(resolveWriteTargetStoreDir(layer, projectRoot), STORE_LAYOUT.knowledgeDir);
+var STORE_PROJECTS_DIR = "projects";
+function isValidWriteProjectSegment(project) {
+  if (project.length === 0) {
+    return false;
+  }
+  if (project === STORE_PROJECTS_DIR) {
+    return false;
+  }
+  if (STORE_KNOWLEDGE_TYPE_DIRS.includes(project)) {
+    return false;
+  }
+  return STORE_PROJECT_ID_PATTERN.test(project);
+}
+function resolveStoreCanonicalBase(layer, projectRoot, project) {
+  const base = join5(resolveWriteTargetStoreDir(layer, projectRoot), STORE_LAYOUT.knowledgeDir);
+  if (layer === "team" && project !== void 0 && isValidWriteProjectSegment(project)) {
+    return join5(base, STORE_PROJECTS_DIR, project);
+  }
+  return base;
 }
 function resolveWriteScopeMeta(layer, projectRoot, semanticScope) {
   const input = buildStoreResolveInput(projectRoot);
@@ -978,7 +1000,7 @@ function resolveWriteScopeMeta(layer, projectRoot, semanticScope) {
 }
 
 // src/services/cross-store-recall.ts
-import { readFile as readFile3, stat } from "fs/promises";
+import { readFile as readFile4, stat } from "fs/promises";
 import { join as join6 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput2,
@@ -995,7 +1017,6 @@ import {
   deriveAgentsMetaStableId,
   isKnowledgeStableId,
   KnowledgeTypeSchema,
-  LayerSchema,
   MaturitySchema,
   parseKnowledgeId,
   StableIdSchema
@@ -1078,8 +1099,7 @@ function extractRuleDescription(source) {
     id: knowledge?.id,
     knowledge_type: knowledge?.knowledge_type,
     maturity: knowledge?.maturity,
-    knowledge_layer: knowledge?.knowledge_layer,
-    layer_reason: knowledge?.layer_reason,
+    // W4/Track1 (D1): no `knowledge_layer` — layer derives from the id prefix.
     created_at: knowledge?.created_at,
     tags: knowledge?.tags,
     // v2.0-rc.5 (C1): default-safe values when there is no frontmatter at all;
@@ -1104,12 +1124,10 @@ function extractDescriptionFromFrontmatter(frontmatter) {
     tech_stack: extractInlineArray(frontmatter, "tech_stack"),
     impact: extractInlineArray(frontmatter, "impact"),
     must_read_if: extractScalar(frontmatter, "must_read_if") ?? summary,
-    entities: extractInlineArray(frontmatter, "entities"),
     id: knowledge.id,
     knowledge_type: knowledge.knowledge_type,
     maturity: knowledge.maturity,
-    knowledge_layer: knowledge.knowledge_layer,
-    layer_reason: knowledge.layer_reason,
+    // W4/Track1 (D1): no `knowledge_layer` — layer derives from the id prefix.
     created_at: knowledge.created_at,
     tags: knowledge.tags,
     relevance_scope: knowledge.relevance_scope,
@@ -1140,8 +1158,6 @@ function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
   const rawId = extractScalar(frontmatter, "id");
   const rawType = extractScalar(frontmatter, "type");
   const rawMaturity = extractScalar(frontmatter, "maturity");
-  const rawLayer = extractScalar(frontmatter, "layer");
-  const rawLayerReason = extractScalar(frontmatter, "layer_reason");
   const rawCreatedAt = extractScalar(frontmatter, "created_at");
   let id;
   if (rawId !== void 0) {
@@ -1178,16 +1194,6 @@ function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
       maturity = parsed.data;
     } else {
       process.stderr.write(`[fabric] frontmatter: unknown maturity ${JSON.stringify(rawMaturity)}; skipping
-`);
-    }
-  }
-  let knowledge_layer;
-  if (rawLayer !== void 0) {
-    const parsed = LayerSchema.safeParse(rawLayer);
-    if (parsed.success) {
-      knowledge_layer = parsed.data;
-    } else {
-      process.stderr.write(`[fabric] frontmatter: unknown layer ${JSON.stringify(rawLayer)}; skipping
 `);
     }
   }
@@ -1200,23 +1206,12 @@ function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
 `);
     }
   }
-  if (id !== void 0 && knowledge_layer !== void 0) {
-    const decoded = parseKnowledgeId(id);
-    if (decoded !== null && decoded.layer !== knowledge_layer) {
-      process.stderr.write(
-        `[fabric] frontmatter: id ${id} encodes layer ${decoded.layer} but layer field says ${knowledge_layer}; dropping both
-`
-      );
-      id = void 0;
-      knowledge_layer = void 0;
-    }
-  }
   const tags = extractInlineArray(frontmatter, "tags");
   const rawRelevanceScope = extractScalar(frontmatter, "relevance_scope");
   const relevance_scope = rawRelevanceScope === "narrow" || rawRelevanceScope === "broad" ? rawRelevanceScope : "broad";
   const relevance_paths = extractInlineArray(frontmatter, "relevance_paths");
   const rawRelated = extractInlineArray(frontmatter, "related");
-  const sourceLayer = knowledge_layer ?? (id !== void 0 ? parseKnowledgeId(id)?.layer ?? "team" : "team");
+  const sourceLayer = id !== void 0 ? parseKnowledgeId(id)?.layer ?? "team" : "team";
   const related = rawRelated.filter((targetId) => {
     if (isForbiddenCrossLayerEdge(sourceLayer, targetId)) {
       process.stderr.write(
@@ -1231,8 +1226,6 @@ function extractKnowledgeFieldsFromFrontmatter(frontmatter) {
     id,
     knowledge_type,
     maturity,
-    knowledge_layer,
-    layer_reason: rawLayerReason,
     created_at,
     tags: tags.length > 0 ? tags : void 0,
     relevance_scope,
@@ -1283,7 +1276,13 @@ async function readSetFingerprint(refs) {
   return parts.sort().join("\n");
 }
 var SEMANTIC_SCOPE_LINE = /^semantic_scope:\s*"?([^"\n]+?)"?\s*$/mu;
-function readSemanticScope(source, layer) {
+function readSemanticScope(source, layer, project) {
+  if (layer === "personal") {
+    return "personal";
+  }
+  if (typeof project === "string" && project.length > 0) {
+    return `project:${project}`;
+  }
   const match = SEMANTIC_SCOPE_LINE.exec(source);
   return match?.[1] ?? layer;
 }
@@ -1350,7 +1349,7 @@ async function walkReadSetStoresUncached(snapshot) {
   const entries = await Promise.all(snapshot.refs.map(async (ref) => {
     let source;
     try {
-      source = await readFile3(ref.file, "utf8");
+      source = await readFile4(ref.file, "utf8");
     } catch {
       return null;
     }
@@ -1362,7 +1361,7 @@ async function walkReadSetStoresUncached(snapshot) {
       type: ref.type,
       alias: ref.alias,
       layer,
-      semanticScope: readSemanticScope(source, layer),
+      semanticScope: readSemanticScope(source, layer, ref.project),
       source
     };
   }));
@@ -1380,7 +1379,9 @@ async function buildCrossStoreRawItems(projectRoot) {
       stable_id: entry.qualifiedId,
       description: {
         ...baseDescription,
-        knowledge_layer: entry.layer,
+        // W4/Track1 (D1): no `knowledge_layer` backfill — a candidate's layer is
+        // derived from its stable_id prefix (layerFromStableId in plan-context),
+        // the single source of truth (KT-DEC-0004).
         semantic_scope: entry.semanticScope
       }
     });
@@ -1622,6 +1623,144 @@ function serializeBm25Model(model) {
 function rehydrateBm25Model(serialized) {
   return modelFromStats(serialized);
 }
+var SYNONYM_PAIRS = {
+  // Code / engineering actions
+  refactor: ["restructure", "rewrite", "redesign", "reorganize", "clean", "rework"],
+  optimize: ["improve", "speed-up", "tune", "accelerate", "perf", "performance"],
+  debug: ["fix", "troubleshoot", "diagnose", "investigate", "resolve", "correct"],
+  migrate: ["port", "move", "transfer", "upgrade", "transition", "convert"],
+  "set up": ["init", "initialize", "configure", "bootstrap", "install", "onboard"],
+  implement: ["add", "build", "create", "develop", "write", "introduce", "introduce"],
+  // Architecture / design
+  architecture: ["design", "structure", "layout", "organization", "pattern", "system"],
+  "data model": ["schema", "entity", "type", "structure", "contract", "shape"],
+  // Quality / correctness
+  test: ["verify", "validate", "assert", "check", "spec", "coverage"],
+  lint: ["check", "validate", "audit", "inspect", "analyze"],
+  // Communication / impact
+  documentation: ["docs", "readme", "guide", "spec", "explanation", "reference"],
+  decision: ["adr", "rationale", "why", "motivation", "reason", "trade-off"],
+  // Change management
+  release: ["deploy", "ship", "publish", "cut", "version", "tag"],
+  rollback: ["revert", "undo", "back-out", "backout", "restore"],
+  // Containers / infra
+  container: ["docker", "image", "oci", "cri-o"],
+  deploy: ["release", "rollout", "ship", "publish", "promote"],
+  // Project / process
+  on_boarding: ["getting-started", "quickstart", "newcomer", "new-hire", "first-time"],
+  best_practice: ["convention", "guideline", "standard", "rule", "recommendation"],
+  // Tech stacks
+  api: ["endpoint", "route", "service", "interface", "rpc", "rest"],
+  typescript: ["ts", "types", "type-safe"],
+  react: ["jsx", "tsx", "component", "ui"],
+  node: ["nodejs", "runtime", "backend", "server"],
+  database: ["db", "sql", "nosql", "storage", "persistence"]
+};
+var STEMMING_PATTERNS = [
+  { suffix: "e", alternatives: ["es", "ed", "ing", "ation"] },
+  { suffix: "y", alternatives: ["ies", "ied", "ying"] }
+  // Catch-all for non-verb / already-stemmed query terms: no-op by default.
+];
+var DEFAULT_IDF_WEIGHT = 1;
+var COMMON_TERMS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "as",
+  "is",
+  "it",
+  "at",
+  "be",
+  "do",
+  "has",
+  "have",
+  "was",
+  "are",
+  "been",
+  "this",
+  "that",
+  "these",
+  "those",
+  "will",
+  "can",
+  "may",
+  "would",
+  "could",
+  "should",
+  "does",
+  "not",
+  "no",
+  "if",
+  "so",
+  "up",
+  "out",
+  "all",
+  "each",
+  "every",
+  "both",
+  "some",
+  "any",
+  "such",
+  "only",
+  "own",
+  "same",
+  "too",
+  "very",
+  "just",
+  "about",
+  "over",
+  "than",
+  "then",
+  "also"
+]);
+function idfWeight(term) {
+  return COMMON_TERMS.has(term) ? 0.3 : DEFAULT_IDF_WEIGHT;
+}
+function expandQueryTerms(text) {
+  const baseTerms = tokenize(text);
+  const weighted = /* @__PURE__ */ new Map();
+  for (const term of baseTerms) {
+    const lower = term.toLowerCase();
+    const aliases = /* @__PURE__ */ new Set();
+    const syns = SYNONYM_PAIRS[lower];
+    if (syns !== void 0) {
+      for (const s of syns) aliases.add(s);
+    }
+    for (const [key, values] of Object.entries(SYNONYM_PAIRS)) {
+      if (values.includes(lower)) {
+        aliases.add(key);
+      }
+    }
+    for (const { suffix, alternatives } of STEMMING_PATTERNS) {
+      if (lower.endsWith(suffix) && lower.length > suffix.length) {
+        const stem = lower.slice(0, -suffix.length);
+        for (const alt of alternatives) {
+          aliases.add(stem + alt);
+        }
+      }
+    }
+    const originalWeight = idfWeight(lower);
+    weighted.set(term, originalWeight);
+    for (const alias of aliases) {
+      if (!weighted.has(alias)) {
+        weighted.set(alias, originalWeight * 0.5);
+      }
+    }
+  }
+  return weighted;
+}
 function buildQueryTerms(text) {
   return tokenize(text);
 }
@@ -2021,7 +2160,7 @@ async function extractKnowledge(projectRoot, input) {
   const writeScopeMeta = resolveWriteScopeMeta(layer, projectRoot, semanticScope);
   await ensureParentDirectory(absolutePath);
   if (existsSync3(absolutePath)) {
-    const existing = await readFile4(absolutePath, "utf8");
+    const existing = await readFile5(absolutePath, "utf8");
     const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
     if (existingKey === effectiveIdempotencyKey) {
       const fresh2 = renderFreshEntry({
@@ -2154,7 +2293,7 @@ async function resolveDisambiguatedSlugPath(args) {
         idempotencyKey: candidateKey
       };
     }
-    const existing = await readFile4(candidatePath, "utf8");
+    const existing = await readFile5(candidatePath, "utf8");
     const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
     if (existingKey === candidateKey) {
       return {
@@ -2752,15 +2891,25 @@ var LEDGER_DUAL_WRITE_METRIC_NAMES = {
 };
 
 // src/services/plan-context.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
 import { join as join10 } from "path";
 
 // src/services/vector-retrieval.ts
 import { mkdirSync } from "fs";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
+import { createRequire } from "module";
 import { join as join9 } from "path";
 import { resolveGlobalRoot as resolveGlobalRoot3 } from "@fenglimg/fabric-shared";
 var embedderLoad;
 var OPTIONAL_EMBED_PACKAGE = "fastembed";
+function isEmbedderResolvable() {
+  try {
+    createRequire(import.meta.url).resolve(OPTIONAL_EMBED_PACKAGE);
+    return true;
+  } catch {
+    return false;
+  }
+}
 var embedderModuleLoader = (name) => import(name);
 var MISSING_EMBEDDER_HINT = "[fabric] vector semantic recall is enabled but the optional 'fastembed' package is unavailable \u2014 falling back to text-only ranking. Install it where the server resolves modules (e.g. `npm i -g fastembed`) to enable embeddings, or set embed_enabled:false to silence this.\n";
 var defaultMissingEmbedderHint = () => {
@@ -2858,11 +3007,63 @@ function cacheDocVector(text, vector) {
     docVectorCache.delete(lru);
   }
 }
-async function buildVectorScores(embedder, queryText, items) {
+var VECTOR_CACHE_VERSION = 1;
+var VECTOR_CACHE_DIR = ".fabric/cache/vectors";
+function vectorCachePath(projectRoot, revision) {
+  const safe = revision.replace(/[^A-Za-z0-9_-]/g, "_");
+  return join9(projectRoot, VECTOR_CACHE_DIR, `${safe}.json`);
+}
+async function loadVectorCacheFromDisk(ctx) {
+  try {
+    const raw = await readFile6(vectorCachePath(ctx.projectRoot, ctx.corpusRevision), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== VECTOR_CACHE_VERSION) return null;
+    if (parsed.embedding_model !== ctx.embeddingModel) return null;
+    if (parsed.corpus_revision !== ctx.corpusRevision) return null;
+    if (!Array.isArray(parsed.vectors) || parsed.vectors.length === 0) return null;
+    const dimension = parsed.dimension;
+    if (!Number.isInteger(dimension) || dimension <= 0) return null;
+    const out = /* @__PURE__ */ new Map();
+    for (const entry of parsed.vectors) {
+      if (!Array.isArray(entry) || entry.length !== 2) return null;
+      const [text, vector] = entry;
+      if (typeof text !== "string" || !Array.isArray(vector)) return null;
+      if (vector.length !== dimension) return null;
+      out.set(text, vector);
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+async function saveVectorCacheToDisk(ctx, vectors, dimension) {
+  try {
+    const payload = {
+      version: VECTOR_CACHE_VERSION,
+      embedding_model: ctx.embeddingModel,
+      dimension,
+      corpus_revision: ctx.corpusRevision,
+      vectors
+    };
+    const path = vectorCachePath(ctx.projectRoot, ctx.corpusRevision);
+    await mkdir4(join9(ctx.projectRoot, VECTOR_CACHE_DIR), { recursive: true });
+    await writeFile2(path, JSON.stringify(payload), "utf8");
+  } catch {
+  }
+}
+async function buildVectorScores(embedder, queryText, items, cache2) {
   if (embedder === null || queryText.trim().length === 0 || items.length === 0) {
     return null;
   }
   try {
+    if (cache2 !== void 0) {
+      const fromDisk = await loadVectorCacheFromDisk(cache2);
+      if (fromDisk !== null) {
+        for (const [text, vector] of fromDisk) {
+          cacheDocVector(text, vector);
+        }
+      }
+    }
     const missTexts = [];
     for (const item of items) {
       if (!docVectorCache.has(item.text)) {
@@ -2878,6 +3079,24 @@ async function buildVectorScores(embedder, queryText, items) {
     for (let m = 0; m < missTexts.length; m += 1) {
       cacheDocVector(missTexts[m], embedded[m + 1]);
     }
+    const staleTexts = [];
+    for (const item of items) {
+      const cached = docVectorCache.get(item.text);
+      if (cached !== void 0 && cached.length !== queryVec.length) {
+        docVectorCache.delete(item.text);
+        staleTexts.push(item.text);
+      }
+    }
+    if (staleTexts.length > 0) {
+      const reEmbedded = await embedder.embed(staleTexts);
+      if (reEmbedded.length !== staleTexts.length) {
+        return null;
+      }
+      for (let s = 0; s < staleTexts.length; s += 1) {
+        cacheDocVector(staleTexts[s], reEmbedded[s]);
+      }
+    }
+    const embeddedNewDoc = missTexts.length > 0 || staleTexts.length > 0;
     const scores = /* @__PURE__ */ new Map();
     for (const item of items) {
       const docVec = docVectorCache.get(item.text);
@@ -2886,6 +3105,20 @@ async function buildVectorScores(embedder, queryText, items) {
       }
       scores.set(item.stable_id, cosineSimilarity(queryVec, docVec));
     }
+    if (cache2 !== void 0 && embeddedNewDoc) {
+      const snapshot = [];
+      for (const item of items) {
+        const vec = docVectorCache.get(item.text);
+        if (vec !== void 0) {
+          snapshot.push([item.text, vec]);
+        }
+      }
+      const dimension = snapshot.length > 0 ? snapshot[0][1].length : 0;
+      const uniform = dimension > 0 && snapshot.every(([, v]) => v.length === dimension);
+      if (uniform) {
+        await saveVectorCacheToDisk(cache2, snapshot, dimension);
+      }
+    }
     return scores;
   } catch {
     return null;
@@ -2893,6 +3126,11 @@ async function buildVectorScores(embedder, queryText, items) {
 }
 
 // src/services/plan-context.ts
+function layerFromStableId(qualifiedId) {
+  const colon = qualifiedId.lastIndexOf(":");
+  const localId = colon === -1 ? qualifiedId : qualifiedId.slice(colon + 1);
+  return localId.startsWith("KP-") ? "personal" : "team";
+}
 var SELECTION_TOKEN_TTL_DEFAULT_MS = 30 * 60 * 1e3;
 var selectionTokenCache = /* @__PURE__ */ new Map();
 var SELECTION_TOKEN_CACHE_MAX = 1e3;
@@ -2949,7 +3187,7 @@ async function planContext(projectRoot, input) {
   const storeRawItems = await buildCrossStoreRawItems(projectRoot).catch(() => []);
   const { rawItems: allRawItems, suppressedStableIds } = partitionEmptyShells(storeRawItems);
   const effectiveLayerFilter = input.layer_filter ?? readDefaultLayerFilter(projectRoot);
-  const rawItems = effectiveLayerFilter === "both" ? allRawItems : allRawItems.filter((item) => item.description.knowledge_layer === effectiveLayerFilter);
+  const rawItems = effectiveLayerFilter === "both" ? allRawItems : allRawItems.filter((item) => layerFromStableId(item.stable_id) === effectiveLayerFilter);
   const scoringContext = await buildScoringContext(projectRoot, revision, rawItems, {
     queryText,
     targetPaths: input.target_paths ?? dedupePaths(input.paths)
@@ -3170,7 +3408,7 @@ function bm25CachePath(projectRoot, revision) {
 }
 async function loadBm25ModelFromDisk(projectRoot, revision) {
   try {
-    const raw = await readFile5(bm25CachePath(projectRoot, revision), "utf8");
+    const raw = await readFile7(bm25CachePath(projectRoot, revision), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) return null;
     return rehydrateBm25Model(parsed);
@@ -3181,8 +3419,8 @@ async function loadBm25ModelFromDisk(projectRoot, revision) {
 async function saveBm25ModelToDisk(projectRoot, revision, model) {
   try {
     const path = bm25CachePath(projectRoot, revision);
-    await mkdir4(join10(projectRoot, BM25_CACHE_DIR), { recursive: true });
-    await writeFile2(path, JSON.stringify(serializeBm25Model(model)), "utf8");
+    await mkdir5(join10(projectRoot, BM25_CACHE_DIR), { recursive: true });
+    await writeFile3(path, JSON.stringify(serializeBm25Model(model)), "utf8");
   } catch {
   }
 }
@@ -3223,7 +3461,7 @@ function buildScopeRankMap(items, projectRoot) {
     const colon = it.stable_id.indexOf(":");
     const alias = colon === -1 ? "" : it.stable_id.slice(0, colon);
     const localId = colon === -1 ? it.stable_id : it.stable_id.slice(colon + 1);
-    const semanticScope = it.description.semantic_scope ?? it.description.knowledge_layer ?? "team";
+    const semanticScope = it.description.semantic_scope ?? layerFromStableId(it.stable_id);
     return {
       global_ref: it.stable_id,
       store_uuid: aliasToUuid.get(alias) ?? alias,
@@ -3273,7 +3511,8 @@ async function buildScoringContext(projectRoot, revision, rawItems, opts) {
       rawItems.map((item) => ({
         stable_id: item.stable_id,
         text: docTexts.get(item.stable_id) ?? documentTextForItem(item.description)
-      }))
+      })),
+      { projectRoot, corpusRevision: revision, embeddingModel: embedConfig.model }
     );
     if (vectorScores !== null) {
       scoringContext.vectorScores = vectorScores;
@@ -3283,6 +3522,10 @@ async function buildScoringContext(projectRoot, revision, rawItems, opts) {
   const configuredFusion = readFusion(projectRoot);
   const vectorActive = scoringContext.vectorScores !== void 0 && scoringContext.vectorScores.size > 0;
   scoringContext.fusion = configuredFusion === "auto" ? vectorActive ? "rrf" : "additive" : configuredFusion;
+  let queryTermWeights;
+  if (scoringContext.queryTerms.length > 0) {
+    queryTermWeights = expandQueryTerms(opts.queryText);
+  }
   if (scoringContext.fusion === "rrf" && scoringContext.queryTerms.length > 0 && rawItems.length > 0) {
     const rankIds = rawItems.map((item) => item.stable_id).sort((a, b) => compareStableIds(a, b));
     if (scoringContext.bm25 !== void 0) {
@@ -3294,6 +3537,49 @@ async function buildScoringContext(projectRoot, revision, rawItems, opts) {
   }
   return scoringContext;
 }
+var PROXIMITY_WINDOW = 6;
+var PROXIMITY_BOOST_CAP = 0.15;
+function proximityBoost(item, context, contentScore2) {
+  if (contentScore2 <= 0) return 0;
+  const text = context.docTexts?.get(item.stable_id);
+  if (text === void 0 || text.length === 0) return 0;
+  const tokens = text.toLowerCase().split(/[^a-z0-9_$#]+/u).filter(Boolean);
+  const queryTerms = context.queryTerms;
+  if (queryTerms.length < 2) return 0;
+  const positions = /* @__PURE__ */ new Map();
+  for (const qt of queryTerms) {
+    const qtLower = qt.toLowerCase();
+    const pos = [];
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i] === qtLower) {
+        pos.push(i);
+      }
+    }
+    if (pos.length > 0) {
+      positions.set(qtLower, pos);
+    }
+  }
+  if (positions.size < 2) return 0;
+  const termList = [...positions.entries()];
+  let minDist = Infinity;
+  for (let i = 0; i < termList.length; i++) {
+    const [, posI] = termList[i];
+    for (let j = i + 1; j < termList.length; j++) {
+      const [, posJ] = termList[j];
+      for (const pi of posI) {
+        for (const pj of posJ) {
+          const dist = Math.abs(pi - pj);
+          if (dist < minDist) minDist = dist;
+        }
+      }
+    }
+  }
+  if (!Number.isFinite(minDist)) return 0;
+  if (minDist >= PROXIMITY_WINDOW) return 0;
+  const ratio = 1 - minDist / PROXIMITY_WINDOW;
+  const boost = contentScore2 * PROXIMITY_BOOST_CAP * ratio;
+  return boost;
+}
 function sortDescriptionItems(rawItems, scoringContext) {
   if (scoringContext === void 0) {
     return [...rawItems].sort((left, right) => compareStableIds(left.stable_id, right.stable_id)).map((item) => ({ item, score: 0 }));
@@ -3334,16 +3620,13 @@ function documentTextForItem(description) {
     ...description.intent_clues,
     ...description.tech_stack,
     ...description.impact,
-    ...description.entities ?? [],
     ...description.tags ?? []
   ].join(" ");
 }
 function documentFieldsForItem(description) {
   return {
     title: tokenize2(description.summary),
-    tags: tokenize2(
-      [...description.tags ?? [], ...description.tech_stack, ...description.entities ?? []].join(" ")
-    ),
+    tags: tokenize2([...description.tags ?? [], ...description.tech_stack].join(" ")),
     summary: tokenize2([description.must_read_if, ...description.intent_clues].join(" ")),
     body: tokenize2(description.impact.join(" "))
   };
@@ -3436,7 +3719,8 @@ function structuralScaleFor(context) {
 function scoreDescriptionItem(item, context) {
   const content = contentScore(item, context);
   const structural = salienceScore(item) + recencyBoost(item, context) + localityBoost(item, context);
-  return content + structuralScaleFor(context) * structural;
+  const proximity = proximityBoost(item, context, content);
+  return content + structuralScaleFor(context) * structural + proximity;
 }
 function scoreBreakdownForItem(item, context) {
   const hasQuery = context.queryTerms.length > 0;
@@ -3918,7 +4202,7 @@ import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-sh
 // src/services/review.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync5 } from "fs";
-import { readFile as readFile7, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
+import { readFile as readFile9, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
 import { homedir } from "os";
 import { basename, isAbsolute, join as join12, relative, resolve as resolve2, sep as sep2 } from "path";
 
@@ -3956,11 +4240,11 @@ async function hasUnresolvedDismissal(projectRoot, id) {
 }
 
 // src/services/review.ts
-import { allocateStoreKnowledgeId, isPersonalScope as isPersonalScope2 } from "@fenglimg/fabric-shared";
+import { allocateStoreKnowledgeId, isPersonalScope as isPersonalScope2, loadProjectConfig as loadProjectConfig3 } from "@fenglimg/fabric-shared";
 
 // src/services/pending-dedupe.ts
 import { existsSync as existsSync4 } from "fs";
-import { readdir, readFile as readFile6, unlink } from "fs/promises";
+import { readdir, readFile as readFile8, unlink } from "fs/promises";
 import { join as join11 } from "path";
 var PENDING_TYPES = ["decisions", "pitfalls", "guidelines", "models", "processes"];
 var DISAMBIGUATION_SUFFIX = /^(.+)-([2-9])\.md$/u;
@@ -4058,7 +4342,7 @@ async function mergePendingTwins(projectRoot) {
           const abs = join11(dir, name);
           let content;
           try {
-            content = await readFile6(abs, "utf8");
+            content = await readFile8(abs, "utf8");
           } catch {
             continue;
           }
@@ -4253,7 +4537,7 @@ async function listPending(projectRoot, filters) {
         const absolutePath = join12(dir, name);
         let content;
         try {
-          content = await readFile7(absolutePath, "utf8");
+          content = await readFile9(absolutePath, "utf8");
         } catch {
           continue;
         }
@@ -4363,7 +4647,7 @@ async function approveOne(projectRoot, pendingPath) {
   let targetAbs;
   let writtenTarget = false;
   try {
-    const content = await readFile7(sourceAbs, "utf8");
+    const content = await readFile9(sourceAbs, "utf8");
     const fm = parseFrontmatter(content);
     const pluralType = fm.type;
     if (pluralType === void 0 || !PLURAL_TYPES.includes(pluralType)) {
@@ -4377,7 +4661,12 @@ async function approveOne(projectRoot, pendingPath) {
     );
     allocatedId = stableId;
     const newFilename = `${stableId}--${slug}.md`;
-    targetAbs = join12(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
+    const promoteProject = layer === "team" ? loadProjectConfig3(projectRoot)?.active_project : void 0;
+    targetAbs = join12(
+      resolveStoreCanonicalBase(layer, projectRoot, promoteProject),
+      pluralType,
+      newFilename
+    );
     await ensureParentDirectory(targetAbs);
     const rewritten = rewriteFrontmatterMerge(
       rewriteFrontmatterForPromote(content, stableId),
@@ -4435,7 +4724,7 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile7(sandboxed.abs, "utf8");
+        const content = await readFile9(sandboxed.abs, "utf8");
         const merged = rewriteFrontmatterMerge(content, { status: "rejected" });
         const rejectedAbs = sandboxed.abs.includes(`${sep2}pending${sep2}`) ? sandboxed.abs.replace(`${sep2}pending${sep2}`, `${sep2}rejected${sep2}`) : null;
         if (rejectedAbs !== null) {
@@ -4462,7 +4751,7 @@ async function modifyEntry(projectRoot, pendingPath, changes) {
   if (target === null) {
     throw new Error(`modify target not found: ${pendingPath}`);
   }
-  const content = await readFile7(target.absPath, "utf8");
+  const content = await readFile9(target.absPath, "utf8");
   const fm = parseFrontmatter(content);
   const currentLayer = fm.layer ?? "team";
   if (fm.maturity === "verified" && changes.maturity === "proven" && fm.id !== void 0) {
@@ -4564,8 +4853,9 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
     pluralType,
     resolveWriteTargetStoreDir(toLayer, projectRoot)
   );
+  const flipProject = toLayer === "team" ? loadProjectConfig3(projectRoot)?.active_project : void 0;
   const toAbs = join12(
-    resolveStoreCanonicalBase(toLayer, projectRoot),
+    resolveStoreCanonicalBase(toLayer, projectRoot, flipProject),
     pluralType,
     `${newStableId}--${slug}.md`
   );
@@ -4587,20 +4877,22 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
     { ...effectivePatch, last_review_confirmed_at: (/* @__PURE__ */ new Date()).toISOString() },
     { id: newStableId }
   );
-  await atomicWriteText(toAbs, rewritten);
+  let moved = false;
   if (target.isInProjectTree) {
     const relSource = relative(projectRoot, target.absPath);
+    const relDest = relative(projectRoot, toAbs);
     try {
-      execFileSync("git", ["rm", "--quiet", "-f", relSource], {
+      execFileSync("git", ["mv", "-f", relSource, relDest], {
         cwd: projectRoot,
         stdio: ["ignore", "pipe", "pipe"]
       });
+      moved = true;
     } catch {
-      if (existsSync5(target.absPath)) {
-        await unlink2(target.absPath);
-      }
+      moved = false;
     }
-  } else if (existsSync5(target.absPath)) {
+  }
+  await atomicWriteText(toAbs, rewritten);
+  if (!moved && existsSync5(target.absPath) && target.absPath !== toAbs) {
     await unlink2(target.absPath);
   }
   const flipReason = `layer_flip:${priorStableId ?? "<unassigned>"}->${newStableId}`;
@@ -4694,7 +4986,7 @@ async function listIndexedSearchEntries(source, type) {
     }
     let content;
     try {
-      content = await readFile7(absolutePath, "utf8");
+      content = await readFile9(absolutePath, "utf8");
       searchEntryIndexContentReads += 1;
     } catch {
       directoryCache.files.delete(absolutePath);
@@ -4744,7 +5036,8 @@ function pendingEntryToRankerItem(indexed) {
     ...fm.id !== void 0 ? { id: fm.id } : {},
     ...fm.type !== void 0 ? { knowledge_type: fm.type } : {},
     maturity: fm.maturity ?? "draft",
-    knowledge_layer: indexed.layer,
+    // W4/Track1 (D1): no `knowledge_layer` field — layer is derived from the
+    // stable_id prefix (KT-DEC-0004), never carried on the description.
     ...fm.semantic_scope !== void 0 ? { semantic_scope: fm.semantic_scope } : {},
     ...fm.created_at !== void 0 ? { created_at: fm.created_at } : {},
     tags: fm.tags ?? [],
@@ -4863,7 +5156,7 @@ async function deferAll(projectRoot, pendingPaths, until, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile7(sandboxed.abs, "utf8");
+        const content = await readFile9(sandboxed.abs, "utf8");
         stableId = parseFrontmatter(content).id;
         const patch = {
           status: "deferred",
@@ -5204,9 +5497,9 @@ function registerPending(server, tracker) {
 }
 
 // src/services/doctor.ts
-import { access as access4, readFile as readFile17, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile4 } from "fs/promises";
+import { access as access4, readFile as readFile19, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile5 } from "fs/promises";
 import { constants as constants2 } from "fs";
-import { isAbsolute as isAbsolute2, join as join23, posix as posix5, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute2, join as join24, posix as posix5, resolve as resolve3 } from "path";
 import {
   createTranslator,
   forensicReportSchema,
@@ -5420,7 +5713,7 @@ function createKnowledgeSummaryOpaqueCheck(t, inspection) {
 }
 
 // src/services/doctor-stable-id-collision.ts
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { basename as basename2, join as join13 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput4,
@@ -5467,7 +5760,7 @@ async function inspectStoreStableIdIntegrity(projectRoot) {
   for (const ref of await readKnowledgeAcrossStores2(resolved.dirs)) {
     let source;
     try {
-      source = await readFile8(ref.file, "utf8");
+      source = await readFile10(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -5788,7 +6081,7 @@ function createNarrowNoPathsCheck(t, inspection) {
 }
 
 // src/services/doctor-broad-index.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { join as join15 } from "path";
 var DEFAULT_BROAD_INDEX_BACKSTOP = 50;
 var BROAD_INDEX_BACKSTOP_MIN = 20;
@@ -5797,7 +6090,7 @@ var BROAD_INDEX_DRIFT_RATIO = 0.8;
 async function readBroadIndexBackstop(projectRoot) {
   const configPath = join15(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile9(configPath, "utf8");
+    const raw = await readFile11(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.broad_index_backstop;
@@ -6114,7 +6407,7 @@ function createBroadReviewRecheckCheck(t, inspection) {
 }
 
 // src/services/doctor-scope-lint.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 import { join as join16 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput5,
@@ -6182,7 +6475,7 @@ async function lintStoreScopes(projectRoot) {
     }
     let source;
     try {
-      source = await readFile10(ref.file, "utf8");
+      source = await readFile12(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -6265,9 +6558,9 @@ function createScopeLintCheck(t, violations) {
 }
 
 // src/services/doctor-unbound-project.ts
-import { loadProjectConfig as loadProjectConfig3 } from "@fenglimg/fabric-shared";
+import { loadProjectConfig as loadProjectConfig4 } from "@fenglimg/fabric-shared";
 function detectUnboundProject(projectRoot) {
-  const config = loadProjectConfig3(projectRoot);
+  const config = loadProjectConfig4(projectRoot);
   const alias = config?.active_write_store;
   if (typeof alias !== "string" || alias.length === 0) {
     return null;
@@ -6315,7 +6608,7 @@ import {
   readStoreCounters,
   reconcileStoreCounters,
   resolveGlobalRoot as resolveGlobalRoot6,
-  STORE_KNOWLEDGE_TYPE_DIRS,
+  STORE_KNOWLEDGE_TYPE_DIRS as STORE_KNOWLEDGE_TYPE_DIRS2,
   STORE_LAYOUT as STORE_LAYOUT2,
   storeRelativePathForMount as storeRelativePathForMount5
 } from "@fenglimg/fabric-shared";
@@ -6359,7 +6652,7 @@ function readEntryId(file) {
 }
 function computeStoreDiskMax(storeDir) {
   const max = defaultAgentsMetaCounters();
-  for (const type of STORE_KNOWLEDGE_TYPE_DIRS) {
+  for (const type of STORE_KNOWLEDGE_TYPE_DIRS2) {
     const dir = join17(storeDir, STORE_LAYOUT2.knowledgeDir, type);
     if (!existsSync7(dir)) {
       continue;
@@ -6554,6 +6847,195 @@ function createStoreOrphanCheck(t, orphans) {
   };
 }
 
+// src/services/doctor-project-registry-drift.ts
+import { readdir as readdir3, rmdir } from "fs/promises";
+import { join as join19 } from "path";
+import {
+  addStoreProject,
+  buildStoreResolveInput as buildStoreResolveInput7,
+  createStoreResolver as createStoreResolver7,
+  readStoreProjects as readStoreProjects2,
+  resolveGlobalRoot as resolveGlobalRoot8,
+  STORE_KNOWLEDGE_TYPE_DIRS as STORE_KNOWLEDGE_TYPE_DIRS3,
+  STORE_LAYOUT as STORE_LAYOUT3,
+  STORE_PROJECT_ID_PATTERN as STORE_PROJECT_ID_PATTERN2,
+  storeRelativePathForMount as storeRelativePathForMount6
+} from "@fenglimg/fabric-shared";
+var PROJECTS_DIR = "projects";
+var EMPTY_INSPECTION = { findings: [] };
+function resolveDriftStores(projectRoot) {
+  const input = buildStoreResolveInput7(projectRoot);
+  if (input === null) {
+    return [];
+  }
+  const readSet = createStoreResolver7().resolveReadSet(input);
+  if (readSet.stores.length === 0) {
+    return [];
+  }
+  const globalRoot = resolveGlobalRoot8();
+  return readSet.stores.map((entry) => {
+    const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
+    return {
+      uuid: entry.store_uuid,
+      alias: entry.alias,
+      dir: join19(globalRoot, storeRelativePathForMount6(mounted ?? { store_uuid: entry.store_uuid }))
+    };
+  });
+}
+async function listDir2(dir) {
+  try {
+    return await readdir3(dir);
+  } catch {
+    return [];
+  }
+}
+async function listProjectFolders(storeDir) {
+  const projectsRoot = join19(storeDir, STORE_LAYOUT3.knowledgeDir, PROJECTS_DIR);
+  const reserved = /* @__PURE__ */ new Set([PROJECTS_DIR, ...STORE_KNOWLEDGE_TYPE_DIRS3]);
+  return (await listDir2(projectsRoot)).filter((id) => STORE_PROJECT_ID_PATTERN2.test(id) && !reserved.has(id)).sort();
+}
+async function folderHasEntries(storeDir, projectId) {
+  const base = join19(storeDir, STORE_LAYOUT3.knowledgeDir, PROJECTS_DIR, projectId);
+  for (const type of STORE_KNOWLEDGE_TYPE_DIRS3) {
+    const names = await listDir2(join19(base, type));
+    if (names.some((name) => name.endsWith(".md"))) {
+      return true;
+    }
+  }
+  return false;
+}
+async function inspectProjectRegistryDrift(projectRoot) {
+  const stores = resolveDriftStores(projectRoot);
+  if (stores.length === 0) {
+    return EMPTY_INSPECTION;
+  }
+  const findings = [];
+  for (const store of stores) {
+    const registered = new Set((await readStoreProjects2(store.dir)).map((p) => p.id));
+    const folders = await listProjectFolders(store.dir);
+    const folderSet = new Set(folders);
+    const base = { store_alias: store.alias, store_uuid: store.uuid, store_dir: store.dir };
+    for (const projectId of folders) {
+      if (registered.has(projectId)) {
+        if (!await folderHasEntries(store.dir, projectId)) {
+          findings.push({ ...base, project_id: projectId, kind: "empty_folder" });
+        }
+        continue;
+      }
+      const kind = await folderHasEntries(store.dir, projectId) ? "unregistered_write" : "orphan_folder";
+      findings.push({ ...base, project_id: projectId, kind });
+    }
+    void folderSet;
+  }
+  findings.sort(
+    (a, b) => a.store_alias.localeCompare(b.store_alias) || a.project_id.localeCompare(b.project_id)
+  );
+  return { findings };
+}
+async function fixProjectRegistryDrift(projectRoot) {
+  const registered = [];
+  const pruned = [];
+  const { findings } = await inspectProjectRegistryDrift(projectRoot);
+  for (const finding of findings) {
+    if (finding.kind === "empty_folder") {
+      if (await folderHasEntries(finding.store_dir, finding.project_id)) {
+        continue;
+      }
+      try {
+        const base = join19(
+          finding.store_dir,
+          STORE_LAYOUT3.knowledgeDir,
+          PROJECTS_DIR,
+          finding.project_id
+        );
+        for (const type of STORE_KNOWLEDGE_TYPE_DIRS3) {
+          await rmdir(join19(base, type)).catch(() => void 0);
+        }
+        await rmdir(base);
+        pruned.push(finding);
+      } catch {
+      }
+      continue;
+    }
+    try {
+      await addStoreProject(finding.store_dir, {
+        id: finding.project_id,
+        created_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      registered.push(finding);
+    } catch {
+    }
+  }
+  return { registered, pruned };
+}
+function createProjectRegistryDriftCheck(t, inspection) {
+  const { findings } = inspection;
+  if (findings.length === 0) {
+    return {
+      name: t("doctor.check.project_registry_drift.name"),
+      status: "ok",
+      message: t("doctor.check.project_registry_drift.ok")
+    };
+  }
+  const unregistered = findings.filter((f) => f.kind === "unregistered_write").length;
+  const orphans = findings.filter((f) => f.kind === "orphan_folder").length;
+  const empties = findings.filter((f) => f.kind === "empty_folder").length;
+  const breakdown = [
+    unregistered > 0 ? `${unregistered} unregistered-write` : null,
+    orphans > 0 ? `${orphans} orphan-folder` : null,
+    empties > 0 ? `${empties} empty-folder` : null
+  ].filter((part) => part !== null).join(", ");
+  if (unregistered > 0) {
+    const first2 = findings.find((f) => f.kind === "unregistered_write");
+    return {
+      name: t("doctor.check.project_registry_drift.name"),
+      status: "error",
+      kind: "manual_error",
+      code: "project_registry_drift",
+      fixable: true,
+      message: t("doctor.check.project_registry_drift.message.unregistered", {
+        total: String(findings.length),
+        breakdown,
+        projectId: first2.project_id,
+        storeAlias: first2.store_alias
+      }),
+      actionHint: t("doctor.check.project_registry_drift.remediation")
+    };
+  }
+  if (orphans > 0) {
+    const first2 = findings.find((f) => f.kind === "orphan_folder");
+    return {
+      name: t("doctor.check.project_registry_drift.name"),
+      status: "warn",
+      kind: "warning",
+      code: "project_registry_drift",
+      fixable: true,
+      message: t("doctor.check.project_registry_drift.message.orphan", {
+        total: String(findings.length),
+        breakdown,
+        projectId: first2.project_id,
+        storeAlias: first2.store_alias
+      }),
+      actionHint: t("doctor.check.project_registry_drift.remediation")
+    };
+  }
+  const first = findings.find((f) => f.kind === "empty_folder");
+  return {
+    name: t("doctor.check.project_registry_drift.name"),
+    status: "warn",
+    kind: "info",
+    code: "project_registry_drift",
+    fixable: true,
+    message: t("doctor.check.project_registry_drift.message.empty", {
+      total: String(findings.length),
+      breakdown,
+      projectId: first.project_id,
+      storeAlias: first.store_alias
+    }),
+    actionHint: t("doctor.check.project_registry_drift.remediation")
+  };
+}
+
 // src/services/legacy-serve-lock-probe.ts
 import {
   isAlive,
@@ -6626,8 +7108,8 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
 }
 
 // src/services/doctor-skill-lints.ts
-import { readdir as readdir3, readFile as readFile11 } from "fs/promises";
-import { join as join19, posix as posix2 } from "path";
+import { readdir as readdir4, readFile as readFile13 } from "fs/promises";
+import { join as join20, posix as posix2 } from "path";
 var FABRIC_SKILL_SLUGS = ["fabric-archive", "fabric-review"];
 var SKILL_MD_FRONTMATTER_ROOTS = [".claude/skills", ".codex/skills"];
 var SKILL_FRONTMATTER_KEY_PATTERN = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]+(.+?)[ \t]*$/u;
@@ -6649,7 +7131,7 @@ function issueCheck(name, status, kind, code, message, actionHint, audience) {
 }
 async function listMarkdownFiles(dir) {
   try {
-    return (await readdir3(dir)).filter((name) => name.endsWith(".md"));
+    return (await readdir4(dir)).filter((name) => name.endsWith(".md"));
   } catch {
     return null;
   }
@@ -6657,8 +7139,8 @@ async function listMarkdownFiles(dir) {
 async function inspectSkillRefMirror(projectRoot) {
   const driftedPaths = [];
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const claudeRef = join19(projectRoot, ".claude", "skills", slug, "ref");
-    const codexRef = join19(projectRoot, ".codex", "skills", slug, "ref");
+    const claudeRef = join20(projectRoot, ".claude", "skills", slug, "ref");
+    const codexRef = join20(projectRoot, ".codex", "skills", slug, "ref");
     const [claudeFiles, codexFiles] = await Promise.all([listMarkdownFiles(claudeRef), listMarkdownFiles(codexRef)]);
     if (claudeFiles === null || codexFiles === null) continue;
     const claudeSet = new Set(claudeFiles);
@@ -6675,8 +7157,8 @@ async function inspectSkillRefMirror(projectRoot) {
       let codexBody;
       try {
         [claudeBody, codexBody] = await Promise.all([
-          readFile11(join19(claudeRef, fname), "utf8"),
-          readFile11(join19(codexRef, fname), "utf8")
+          readFile13(join20(claudeRef, fname), "utf8"),
+          readFile13(join20(codexRef, fname), "utf8")
         ]);
       } catch {
         continue;
@@ -6695,10 +7177,10 @@ async function inspectSkillTokenBudget(projectRoot) {
   const overSize = [];
   let highestSeverity = "ok";
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join20(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile11(skillMdPath, "utf8");
+      body = await readFile13(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6719,10 +7201,10 @@ async function inspectSkillDescription(projectRoot) {
   const CJK_PATTERN = /[\u3400-\u4dbf\u4e00-\u9fff]/u;
   const ASCII_PATTERN = /[a-zA-Z]{2,}/u;
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join20(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile11(skillMdPath, "utf8");
+      body = await readFile13(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6753,19 +7235,19 @@ async function inspectSkillDescription(projectRoot) {
 async function inspectSkillMdYamlInvalid(projectRoot) {
   const candidates = [];
   for (const rootRel of SKILL_MD_FRONTMATTER_ROOTS) {
-    const rootAbs = join19(projectRoot, rootRel);
+    const rootAbs = join20(projectRoot, rootRel);
     let dirEntries;
     try {
-      dirEntries = await readdir3(rootAbs, { withFileTypes: true });
+      dirEntries = await readdir4(rootAbs, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const dirEntry of dirEntries) {
       if (!dirEntry.isDirectory()) continue;
-      const skillFile = join19(rootAbs, dirEntry.name, "SKILL.md");
+      const skillFile = join20(rootAbs, dirEntry.name, "SKILL.md");
       let raw;
       try {
-        raw = await readFile11(skillFile, "utf8");
+        raw = await readFile13(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -6888,8 +7370,8 @@ function createSkillMdYamlInvalidCheck(t, inspection) {
 }
 
 // src/services/doctor-retired-references-lint.ts
-import { readdir as readdir4, readFile as readFile12, stat as stat3 } from "fs/promises";
-import { join as join20, posix as posix3, relative as relative2 } from "path";
+import { readdir as readdir5, readFile as readFile14, stat as stat3 } from "fs/promises";
+import { join as join21, posix as posix3, relative as relative2 } from "path";
 var RETIRED_TOKENS = [
   { token: "fab_plan_context", replacement: "fab_recall", reason: "retrieval collapsed to one lean fab_recall (KT-DEC-0026)" },
   { token: "fab_get_knowledge_sections", replacement: "fab_recall", reason: "two-step fetch retired (KT-DEC-0026)" },
@@ -6912,7 +7394,7 @@ var RETIRED_TOKENS = [
 ];
 var HOOK_DIRS = [".claude/hooks", ".codex/hooks"];
 var SKILL_DIRS = [".claude/skills", ".codex/skills"];
-var BOOTSTRAP_FILES = ["AGENTS.md", "CLAUDE.md", join20(".fabric", "AGENTS.md")];
+var BOOTSTRAP_FILES = ["AGENTS.md", "CLAUDE.md", join21(".fabric", "AGENTS.md")];
 function isCommentLine(line) {
   const t = line.trim();
   return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
@@ -6920,13 +7402,13 @@ function isCommentLine(line) {
 async function walkFiles(dir, exts) {
   let entries;
   try {
-    entries = await readdir4(dir, { withFileTypes: true });
+    entries = await readdir5(dir, { withFileTypes: true });
   } catch {
     return [];
   }
   const out = [];
   for (const e of entries) {
-    const full = join20(dir, e.name);
+    const full = join21(dir, e.name);
     if (e.isDirectory()) {
       out.push(...await walkFiles(full, exts));
     } else if (exts.some((ext) => e.name.endsWith(ext))) {
@@ -6952,29 +7434,29 @@ async function inspectRetiredReferences(projectRoot) {
   let scannedFiles = 0;
   const toRel = (p) => posix3.normalize(relative2(projectRoot, p).split("\\").join("/"));
   for (const rel of BOOTSTRAP_FILES) {
-    const abs = join20(projectRoot, rel);
+    const abs = join21(projectRoot, rel);
     try {
       if ((await stat3(abs)).isFile()) {
         scannedFiles += 1;
-        scanText(toRel(abs), await readFile12(abs, "utf8"), false, hits);
+        scanText(toRel(abs), await readFile14(abs, "utf8"), false, hits);
       }
     } catch {
     }
   }
   for (const dir of SKILL_DIRS) {
-    for (const file of await walkFiles(join20(projectRoot, dir), [".md"])) {
+    for (const file of await walkFiles(join21(projectRoot, dir), [".md"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile12(file, "utf8"), false, hits);
+        scanText(toRel(file), await readFile14(file, "utf8"), false, hits);
       } catch {
       }
     }
   }
   for (const dir of HOOK_DIRS) {
-    for (const file of await walkFiles(join20(projectRoot, dir), [".cjs"])) {
+    for (const file of await walkFiles(join21(projectRoot, dir), [".cjs"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile12(file, "utf8"), true, hits);
+        scanText(toRel(file), await readFile14(file, "utf8"), true, hits);
       } catch {
       }
     }
@@ -7009,8 +7491,8 @@ function createRetiredReferenceCheck(t, inspection) {
 
 // src/services/doctor-hooks-lints.ts
 import { constants } from "fs";
-import { access, readdir as readdir5, readFile as readFile13, stat as stat4 } from "fs/promises";
-import { join as join21, posix as posix4 } from "path";
+import { access, readdir as readdir6, readFile as readFile15, stat as stat4 } from "fs/promises";
+import { join as join22, posix as posix4 } from "path";
 import { Script } from "vm";
 var HOOKS_RUNTIME_CLIENT_DIRS = [
   { client: "claude", dir: ".claude/hooks" },
@@ -7059,7 +7541,7 @@ function isHookWiredForEvent(hooks, event, hookFile) {
 }
 async function readDirectoryFileNames(dir) {
   try {
-    return await readdir5(dir);
+    return await readdir6(dir);
   } catch {
     return null;
   }
@@ -7072,14 +7554,14 @@ async function isFile(absPath) {
   }
 }
 async function inspectHooksWired(projectRoot) {
-  const claudeEntries = await readDirectoryFileNames(join21(projectRoot, ".claude"));
+  const claudeEntries = await readDirectoryFileNames(join22(projectRoot, ".claude"));
   if (claudeEntries === null) {
     return { status: "skipped", missingHooks: [] };
   }
-  const settingsPath = join21(projectRoot, ".claude", "settings.json");
+  const settingsPath = join22(projectRoot, ".claude", "settings.json");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile13(settingsPath, "utf8"));
+    parsed = JSON.parse(await readFile15(settingsPath, "utf8"));
   } catch {
     return { status: "missing-settings", missingHooks: [] };
   }
@@ -7102,8 +7584,8 @@ async function inspectHooksWired(projectRoot) {
 }
 async function inspectHookCacheWritability(projectRoot) {
   const relPath = posix4.join(".fabric", ".cache");
-  const fabricDir = join21(projectRoot, ".fabric");
-  const cacheDir = join21(projectRoot, ".fabric", ".cache");
+  const fabricDir = join22(projectRoot, ".fabric");
+  const cacheDir = join22(projectRoot, ".fabric", ".cache");
   try {
     try {
       const cacheStats = await stat4(cacheDir);
@@ -7152,12 +7634,12 @@ async function inspectHookCacheWritability(projectRoot) {
 async function inspectHooksContentDrift(projectRoot) {
   const hookFilesByBasename = /* @__PURE__ */ new Map();
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join21(projectRoot, dir);
+    const absDir = join22(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join21(absDir, name);
+      const abs = join22(absDir, name);
       if (!await isFile(abs)) continue;
       const arr = hookFilesByBasename.get(name) ?? [];
       arr.push({ client, abs });
@@ -7172,7 +7654,7 @@ async function inspectHooksContentDrift(projectRoot) {
     const hashes = [];
     for (const { client, abs } of copies) {
       try {
-        const body = await readFile13(abs, "utf8");
+        const body = await readFile15(abs, "utf8");
         hashes.push({ client, sha: sha256(body) });
       } catch {
       }
@@ -7194,18 +7676,18 @@ async function inspectHooksRuntime(projectRoot) {
   const issues = [];
   let scanned = 0;
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join21(projectRoot, dir);
+    const absDir = join22(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join21(absDir, name);
+      const abs = join22(absDir, name);
       const displayPath = `${dir}/${name}`;
       if (!await isFile(abs)) continue;
       scanned += 1;
       let body;
       try {
-        body = await readFile13(abs, "utf8");
+        body = await readFile15(abs, "utf8");
       } catch (err) {
         issues.push({
           path: displayPath,
@@ -7342,8 +7824,8 @@ function createHookCacheWritabilityCheck(t, inspection) {
 }
 
 // src/services/doctor-bootstrap-lints.ts
-import { access as access2, readFile as readFile14 } from "fs/promises";
-import { join as join22 } from "path";
+import { access as access2, readFile as readFile16 } from "fs/promises";
+import { join as join23 } from "path";
 import {
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
@@ -7375,17 +7857,17 @@ async function fileExists(path) {
 }
 async function inspectBootstrapAnchor(projectRoot) {
   const [hasAgentsMd, hasClaudeMd] = await Promise.all([
-    fileExists(join22(projectRoot, "AGENTS.md")),
-    fileExists(join22(projectRoot, "CLAUDE.md"))
+    fileExists(join23(projectRoot, "AGENTS.md")),
+    fileExists(join23(projectRoot, "CLAUDE.md"))
   ]);
   return { hasAgentsMd, hasClaudeMd };
 }
 async function inspectL1BootstrapSnapshotDrift(target) {
-  const abs = join22(target, ".fabric", "AGENTS.md");
+  const abs = join23(target, ".fabric", "AGENTS.md");
   const canonical = resolveBootstrapCanonical();
   let onDisk;
   try {
-    onDisk = await readFile14(abs, "utf8");
+    onDisk = await readFile16(abs, "utf8");
   } catch {
     return { status: "missing", canonical, onDisk: null };
   }
@@ -7411,17 +7893,17 @@ function createL1BootstrapSnapshotDriftCheck(t, inspection) {
   );
 }
 async function inspectL2ManagedBlockDrift(target) {
-  const snapshotPath = join22(target, ".fabric", "AGENTS.md");
+  const snapshotPath = join23(target, ".fabric", "AGENTS.md");
   let snapshot;
   try {
-    snapshot = await readFile14(snapshotPath, "utf8");
+    snapshot = await readFile16(snapshotPath, "utf8");
   } catch {
     return { status: "ok", drifted: [] };
   }
-  const projectRulesPath = join22(target, ".fabric", "project-rules.md");
+  const projectRulesPath = join23(target, ".fabric", "project-rules.md");
   let expectedBody = snapshot;
   try {
-    const projectRules = await readFile14(projectRulesPath, "utf8");
+    const projectRules = await readFile16(projectRulesPath, "utf8");
     expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -7430,12 +7912,12 @@ ${projectRules}`;
   const drifted = [];
   let anyManagedBlockFound = false;
   const blockTargets = [
-    join22(target, "AGENTS.md")
+    join23(target, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     let content;
     try {
-      content = await readFile14(abs, "utf8");
+      content = await readFile16(abs, "utf8");
     } catch {
       continue;
     }
@@ -7458,9 +7940,9 @@ ${projectRules}`;
       drifted.push({ path: abs, expected: expectedBody, actual: body });
     }
   }
-  const claudeMdPath = join22(target, "CLAUDE.md");
+  const claudeMdPath = join23(target, "CLAUDE.md");
   try {
-    const claudeContent = await readFile14(claudeMdPath, "utf8");
+    const claudeContent = await readFile16(claudeMdPath, "utf8");
     anyManagedBlockFound = true;
     const lines = claudeContent.split(/\r?\n/u);
     const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
@@ -7528,7 +8010,7 @@ import { appendFile as appendFile3 } from "fs/promises";
 import { minimatch as minimatch2 } from "minimatch";
 
 // src/services/cite-rollup.ts
-import { readFile as readFile15 } from "fs/promises";
+import { readFile as readFile17 } from "fs/promises";
 import { createLedgerWriteQueue as createLedgerWriteQueue3 } from "@fenglimg/fabric-shared/node/atomic-write";
 var citeRollupQueue = createLedgerWriteQueue3();
 async function appendCiteRollupRow(projectRoot, row) {
@@ -7540,7 +8022,7 @@ async function readCiteRollup(projectRoot) {
   const path = getCiteRollupPath(projectRoot);
   let raw;
   try {
-    raw = await readFile15(path, "utf8");
+    raw = await readFile17(path, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") return [];
     throw error;
@@ -8131,6 +8613,18 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       }
     }
   }
+  const editSessionIds = /* @__PURE__ */ new Set();
+  for (const edit of editEvents) {
+    if (typeof edit.session_id === "string" && edit.session_id.length > 0) {
+      editSessionIds.add(edit.session_id);
+    }
+  }
+  let recallsInWindow = 0;
+  for (const list of plannedBySession.values()) recallsInWindow += list.length;
+  let recallSessionsCorrelated = 0;
+  for (const sid of plannedBySession.keys()) {
+    if (editSessionIds.has(sid)) recallSessionsCorrelated += 1;
+  }
   const noneTotal = Object.values(noneHistogram).reduce((a, b) => a + b, 0);
   const compliantCites = qualifyingCites + noneTotal;
   const noncompliantCites = expectedButMissed;
@@ -8198,6 +8692,11 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     uncorrelatable_edits: uncorrelatableEdits,
     recall_backed_edits: recallBackedEdits,
     recall_coverage_rate: recallCoverageRate,
+    recall_diagnostics: {
+      recalls_in_window: recallsInWindow,
+      recall_sessions: plannedBySession.size,
+      recall_sessions_correlated: recallSessionsCorrelated
+    },
     exposed_and_mutated: {
       count: exposedAndMutated.count,
       ...exposedAndMutated.ids.length > 0 ? { ids: exposedAndMutated.ids } : {}
@@ -8641,6 +9140,7 @@ async function runDoctorReport(target) {
   const driftUnconsumed = await inspectDriftUnconsumed(projectRoot);
   const storeCounterDrift = inspectStoreCounters(projectRoot);
   const storeOrphans = inspectStoreOrphans();
+  const projectRegistryDrift = await inspectProjectRegistryDrift(projectRoot);
   const stableIdIntegrity = await inspectStoreStableIdIntegrity(projectRoot);
   const relevancePaths = await inspectStoreRelevancePaths(projectRoot);
   const broadIndexDrift = await inspectBroadIndexDrift(projectRoot);
@@ -8670,7 +9170,7 @@ async function runDoctorReport(target) {
   const globalCliVersion = process.env.VITEST === "true" ? { status: "ok", version: "test-skipped" } : inspectGlobalCliVersion();
   const targetFiles = Object.fromEntries(
     await Promise.all(
-      TARGET_FILE_PATHS.map(async (path) => [path, await pathExists(join23(projectRoot, path))])
+      TARGET_FILE_PATHS.map(async (path) => [path, await pathExists(join24(projectRoot, path))])
     )
   );
   const checks = [
@@ -8724,6 +9224,12 @@ async function runDoctorReport(target) {
     // (warning). `--fix` adopts it (rescue-before-delete — re-register, never
     // an on-disk delete).
     createStoreOrphanCheck(t, storeOrphans),
+    // W2 (F-003): project-registry drift over projects.json ↔ projects/ folder
+    // tree. unregistered-write (data unrouted) → manual_error; orphan-folder →
+    // warning; empty-folder → info; ghost-registration emits nothing (DA-05).
+    // `--fix` rescue-registers orphans/unregistered (addStoreProject — never a
+    // non-empty delete) and prunes only genuinely-empty registered folders.
+    createProjectRegistryDriftCheck(t, projectRegistryDrift),
     // rc.5 TASK-010: read-side underseeded-corpus check (#22). Info kind —
     // does not bump report status. Recommends running the fabric-import skill
     // to backfill knowledge when the corpus is below the threshold floor.
@@ -8874,7 +9380,7 @@ async function runDoctorFix(target) {
   const fixed = [];
   const ledgerWarnings = [];
   if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
-    const snapshotPath = join23(projectRoot, ".fabric", "AGENTS.md");
+    const snapshotPath = join24(projectRoot, ".fabric", "AGENTS.md");
     await ensureParentDirectory(snapshotPath);
     await atomicWriteText4(snapshotPath, resolveBootstrapCanonical2());
     fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
@@ -8898,6 +9404,18 @@ async function runDoctorFix(target) {
       fixed.push(findIssue(before.warnings, "store_orphan"));
     }
   }
+  const registryDriftFound = before.manual_errors.some((issue) => issue.code === "project_registry_drift") || before.warnings.some((issue) => issue.code === "project_registry_drift") || before.infos.some((issue) => issue.code === "project_registry_drift");
+  if (registryDriftFound) {
+    const result = await fixProjectRegistryDrift(projectRoot);
+    if (result.registered.length > 0 || result.pruned.length > 0) {
+      fixed.push(
+        findIssue(
+          [...before.manual_errors, ...before.warnings, ...before.infos],
+          "project_registry_drift"
+        )
+      );
+    }
+  }
   if (before.fixable_errors.some((issue) => issue.code === "event_ledger_partial_write")) {
     const ledgerPath = getEventLedgerPath(projectRoot);
     const truncResult = await truncateLedgerToLastNewline(ledgerPath);
@@ -8947,7 +9465,7 @@ async function runDoctorFix(target) {
   if (before.infos.some((issue) => issue.code === "stale_serve_lock")) {
     const lockInspection = inspectStaleServeLock(projectRoot, Date.now());
     if (lockInspection.present && !lockInspection.pidAlive) {
-      const lockFilePath = join23(projectRoot, ".fabric", ".serve.lock");
+      const lockFilePath = join24(projectRoot, ".fabric", ".serve.lock");
       try {
         await unlink4(lockFilePath);
       } catch (err) {
@@ -9064,7 +9582,7 @@ function createApplyLintMessage(succeeded, failed, manualErrorCount) {
 }
 async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
-  const absPath = join23(projectRoot, candidate.path);
+  const absPath = join24(projectRoot, candidate.path);
   try {
     const { unlink: unlink5 } = await import("fs/promises");
     await unlink5(absPath);
@@ -9089,9 +9607,9 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path = join23(projectRoot, ".fabric", "forensic.json");
+  const path = join24(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile17(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile19(path, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -9121,7 +9639,7 @@ async function inspectEventLedger(projectRoot) {
   try {
     await access4(path, constants2.W_OK);
     const { warnings } = await readEventLedger(projectRoot);
-    const raw = await readFile17(path, "utf8");
+    const raw = await readFile19(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");
     const schemaVersionSamples = [];
@@ -9666,7 +10184,7 @@ async function inspectPreexistingRootFiles(projectRoot) {
   const candidates = ["CLAUDE.md", "AGENTS.md"];
   const detected = [];
   for (const name of candidates) {
-    if (await pathExists(join23(projectRoot, name))) {
+    if (await pathExists(join24(projectRoot, name))) {
       detected.push(name);
     }
   }
@@ -9751,7 +10269,7 @@ async function buildLastActiveIndex(projectRoot) {
   return map;
 }
 async function inspectSessionHintsStale(projectRoot, now) {
-  const cacheDir = join23(projectRoot, ".fabric", ".cache");
+  const cacheDir = join24(projectRoot, ".fabric", ".cache");
   let entries;
   try {
     entries = await readdirAsync(cacheDir, { withFileTypes: true });
@@ -9763,7 +10281,7 @@ async function inspectSessionHintsStale(projectRoot, now) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith(SESSION_HINTS_FILE_PREFIX)) continue;
     if (!entry.name.endsWith(SESSION_HINTS_FILE_SUFFIX)) continue;
-    const absPath = join23(cacheDir, entry.name);
+    const absPath = join24(cacheDir, entry.name);
     let mtimeMs = 0;
     try {
       mtimeMs = (await statAsync(absPath)).mtimeMs;
@@ -9795,9 +10313,9 @@ function inspectStaleServeLock(projectRoot, now) {
   };
 }
 async function readUnderseedThresholdFromConfig(projectRoot) {
-  const configPath = join23(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join24(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile17(configPath, "utf8");
+    const raw = await readFile19(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -9913,10 +10431,10 @@ async function inspectOnboardCoverage(projectRoot) {
   return { filled, missing, opted_out: optedOut };
 }
 async function readOnboardOptedOut(projectRoot) {
-  const path = join23(projectRoot, ".fabric", "fabric-config.json");
+  const path = join24(projectRoot, ".fabric", "fabric-config.json");
   let raw;
   try {
-    raw = await readFile17(path, "utf8");
+    raw = await readFile19(path, "utf8");
   } catch {
     return [];
   }
@@ -10018,22 +10536,22 @@ async function* iterateCanonicalFilenames(projectRoot) {
   }
 }
 async function rewriteThreeEndManagedBlocks(projectRoot) {
-  const snapshotPath = join23(projectRoot, ".fabric", "AGENTS.md");
+  const snapshotPath = join24(projectRoot, ".fabric", "AGENTS.md");
   if (!await pathExists(snapshotPath)) {
     return;
   }
   let snapshot;
   try {
-    snapshot = await readFile17(snapshotPath, "utf8");
+    snapshot = await readFile19(snapshotPath, "utf8");
   } catch {
     return;
   }
-  const projectRulesPath = join23(projectRoot, ".fabric", "project-rules.md");
+  const projectRulesPath = join24(projectRoot, ".fabric", "project-rules.md");
   const hasProjectRules = await pathExists(projectRulesPath);
   let expectedBody = snapshot;
   if (hasProjectRules) {
     try {
-      const projectRules = await readFile17(projectRulesPath, "utf8");
+      const projectRules = await readFile19(projectRulesPath, "utf8");
       expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -10044,7 +10562,7 @@ ${projectRules}`;
 ${expectedBody}
 ${BOOTSTRAP_MARKER_END2}`;
   const blockTargets = [
-    join23(projectRoot, "AGENTS.md")
+    join24(projectRoot, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     if (!await pathExists(abs)) {
@@ -10052,7 +10570,7 @@ ${BOOTSTRAP_MARKER_END2}`;
     }
     let existing;
     try {
-      existing = await readFile17(abs, "utf8");
+      existing = await readFile19(abs, "utf8");
     } catch {
       continue;
     }
@@ -10077,11 +10595,11 @@ ${managedBlock}
     }
     await atomicWriteText4(abs, next);
   }
-  const claudeMdPath = join23(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join24(projectRoot, "CLAUDE.md");
   if (await pathExists(claudeMdPath)) {
     let claudeContent;
     try {
-      claudeContent = await readFile17(claudeMdPath, "utf8");
+      claudeContent = await readFile19(claudeMdPath, "utf8");
     } catch {
       return;
     }
@@ -10108,7 +10626,7 @@ ${managedBlock}
 async function ensureEventLedger(projectRoot) {
   const path = getEventLedgerPath(projectRoot);
   await ensureParentDirectory(path);
-  await writeFile4(path, "", { encoding: "utf8", flag: "a" });
+  await writeFile5(path, "", { encoding: "utf8", flag: "a" });
 }
 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"}.`;
@@ -10147,7 +10665,7 @@ async function collectEntryPoints(root) {
       continue;
     }
     for (const entry of await readdirAsync(current, { withFileTypes: true })) {
-      const absolutePath = join23(current, entry.name);
+      const absolutePath = join24(current, entry.name);
       const relativePath = normalizePath2(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -10223,7 +10741,7 @@ async function enrichDescriptions(projectRoot, opts = {}) {
     scanned += 1;
     let source;
     try {
-      source = await readFile17(absPath, "utf8");
+      source = await readFile19(absPath, "utf8");
     } catch {
       continue;
     }
@@ -10361,16 +10879,16 @@ async function runDoctorConflictLint(projectRoot, opts = {}) {
 }
 
 // src/services/why-not-surfaced.ts
-import { readFile as readFile18 } from "fs/promises";
-import { basename as basename3, join as join24 } from "path";
+import { readFile as readFile20 } from "fs/promises";
+import { basename as basename3, join as join25 } from "path";
 import {
-  buildStoreResolveInput as buildStoreResolveInput7,
-  createStoreResolver as createStoreResolver7,
-  loadProjectConfig as loadProjectConfig4,
+  buildStoreResolveInput as buildStoreResolveInput8,
+  createStoreResolver as createStoreResolver8,
+  loadProjectConfig as loadProjectConfig5,
   readKnowledgeAcrossStores as readKnowledgeAcrossStores4,
-  resolveGlobalRoot as resolveGlobalRoot8,
+  resolveGlobalRoot as resolveGlobalRoot9,
   scopeRoot as scopeRoot3,
-  storeRelativePathForMount as storeRelativePathForMount6
+  storeRelativePathForMount as storeRelativePathForMount7
 } from "@fenglimg/fabric-shared";
 var SEMANTIC_SCOPE_LINE3 = /^semantic_scope:\s*"?([^"\n]+?)"?\s*$/mu;
 var RELEVANCE_SCOPE_LINE = /^relevance_scope:\s*"?(broad|narrow)"?\s*$/mu;
@@ -10394,15 +10912,15 @@ async function explainWhyNotSurfaced(projectRoot, query) {
     activeProject: null,
     relevanceScope: null
   };
-  const input = buildStoreResolveInput7(projectRoot);
+  const input = buildStoreResolveInput8(projectRoot);
   if (input === null) {
     return base;
   }
-  const globalRoot = resolveGlobalRoot8();
+  const globalRoot = resolveGlobalRoot9();
   const allStores = input.mountedStores.map((s) => ({
     store_uuid: s.store_uuid,
     alias: s.alias,
-    dir: join24(globalRoot, storeRelativePathForMount6(s))
+    dir: join25(globalRoot, storeRelativePathForMount7(s))
   }));
   const refs = await readKnowledgeAcrossStores4(allStores);
   const candidate = refs.find((ref) => fileMatchesId(ref.file, localId));
@@ -10411,7 +10929,7 @@ async function explainWhyNotSurfaced(projectRoot, query) {
   }
   let source;
   try {
-    source = await readFile18(candidate.file, "utf8");
+    source = await readFile20(candidate.file, "utf8");
   } catch {
     return base;
   }
@@ -10420,9 +10938,9 @@ async function explainWhyNotSurfaced(projectRoot, query) {
   }
   const semanticScope = SEMANTIC_SCOPE_LINE3.exec(source)?.[1] ?? null;
   const relevanceScope = RELEVANCE_SCOPE_LINE.exec(source)?.[1] ?? "broad";
-  const activeProject = loadProjectConfig4(projectRoot)?.active_project ?? null;
+  const activeProject = loadProjectConfig5(projectRoot)?.active_project ?? null;
   const boundUuids = new Set(
-    createStoreResolver7().resolveReadSet(input).stores.map((s) => s.store_uuid)
+    createStoreResolver8().resolveReadSet(input).stores.map((s) => s.store_uuid)
   );
   const storeBound = boundUuids.has(candidate.store_uuid);
   const found = {
@@ -10464,6 +10982,191 @@ function buildColdEvalBatch(candidates) {
   return { rubric: COLD_EVAL_RUBRIC, candidates: judgeable };
 }
 
+// src/services/doctor-related-graph.ts
+function buildRelatedGraph(nodes) {
+  const brokenLinks = [];
+  const inDegree = /* @__PURE__ */ new Map();
+  const allIds = /* @__PURE__ */ new Set();
+  const edgeSources = [];
+  for (const node of nodes) {
+    const bareId = extractBareStableId(node.qualifiedId);
+    allIds.add(node.qualifiedId);
+    if (bareId !== null) {
+      allIds.add(bareId);
+    }
+    const related = node.related;
+    if (related !== void 0 && related.length > 0) {
+      edgeSources.push({ source: node.qualifiedId, related });
+      for (const rel of related) {
+        inDegree.set(rel, (inDegree.get(rel) ?? 0) + 1);
+      }
+    }
+  }
+  for (const { source, related } of edgeSources) {
+    for (const rel of related) {
+      if (!allIds.has(rel)) {
+        brokenLinks.push({ source, target: rel });
+      }
+    }
+  }
+  const hubEntries = [...inDegree.entries()].map(([stableId, degree]) => ({ stableId, inDegree: degree })).sort((a, b) => b.inDegree - a.inDegree || a.stableId.localeCompare(b.stableId));
+  return {
+    brokenLinks,
+    hubEntries,
+    totalEntries: nodes.length
+  };
+}
+function extractBareStableId(qualifiedId) {
+  const colonIdx = qualifiedId.indexOf(":");
+  if (colonIdx > 0 && colonIdx < qualifiedId.length - 1) {
+    return qualifiedId.slice(colonIdx + 1);
+  }
+  return null;
+}
+async function inspectRelatedGraph(projectRoot) {
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  return buildRelatedGraph(
+    entries.map((entry) => ({
+      qualifiedId: entry.qualifiedId,
+      related: entry.description.related
+    }))
+  );
+}
+
+// src/services/store-precheck.ts
+import { existsSync as existsSync9, readFileSync as readFileSync4 } from "fs";
+import { join as join26 } from "path";
+import {
+  buildStoreResolveInput as buildStoreResolveInput9,
+  createStoreResolver as createStoreResolver9,
+  resolveGlobalRoot as resolveGlobalRoot10,
+  storeRelativePathForMount as storeRelativePathForMount8
+} from "@fenglimg/fabric-shared";
+var CACHE_TTL_MS = 6e4;
+var cache = /* @__PURE__ */ new Map();
+function clearPrecheckCache() {
+  cache.clear();
+}
+function evaluateStoreDir(storeDir, identity) {
+  if (!existsSync9(storeDir)) {
+    return {
+      uuid: identity.uuid,
+      alias: identity.alias,
+      reachable: false,
+      reason: `directory not found at ${storeDir}`
+    };
+  }
+  const storeJsonPath = join26(storeDir, "store.json");
+  const gitDirPath = join26(storeDir, ".git");
+  const hasStoreJson = existsSync9(storeJsonPath) && isValidStoreJson(storeJsonPath);
+  const hasGitDir = existsSync9(gitDirPath);
+  if (!hasStoreJson && !hasGitDir) {
+    return {
+      uuid: identity.uuid,
+      alias: identity.alias,
+      reachable: false,
+      reason: `no store.json or .git found in ${storeDir}`
+    };
+  }
+  return { uuid: identity.uuid, alias: identity.alias, reachable: true };
+}
+function isValidStoreJson(path) {
+  try {
+    JSON.parse(readFileSync4(path, "utf8"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function precheckStoreReachability(projectRoot, globalRoot = resolveGlobalRoot10(), now = Date.now()) {
+  const cached = cache.get(projectRoot);
+  if (cached !== void 0 && cached.expiresAt > now) {
+    return cached.result;
+  }
+  const input = buildStoreResolveInput9(projectRoot, globalRoot);
+  if (input === null) {
+    const result2 = { stores: [], allReachable: true };
+    cache.set(projectRoot, { result: result2, expiresAt: now + CACHE_TTL_MS });
+    return result2;
+  }
+  const readSet = createStoreResolver9().resolveReadSet(input);
+  const stores = readSet.stores.map((entry) => {
+    const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
+    const storeDir = join26(
+      globalRoot,
+      storeRelativePathForMount8(mounted ?? { store_uuid: entry.store_uuid })
+    );
+    return evaluateStoreDir(storeDir, { uuid: entry.store_uuid, alias: entry.alias });
+  });
+  const result = {
+    stores,
+    allReachable: stores.every((s) => s.reachable)
+  };
+  cache.set(projectRoot, { result, expiresAt: now + CACHE_TTL_MS });
+  return result;
+}
+
+// src/services/doctor-consumption-lint.ts
+var DEFAULT_WINDOW_DAYS = 30;
+var DEFAULT_TOP_N = 10;
+var DEFAULT_MIN_TOTAL_ENTRIES = 20;
+var DEFAULT_MIN_CONSUMED_WINDOWS = 30;
+var DEFAULT_MIN_CONSUMED_EVENTS = 50;
+var CONSUMED_PREFIX = "knowledge_consumed:";
+var MS_PER_DAY5 = 24 * 60 * 60 * 1e3;
+function resolveConfig(config) {
+  return {
+    windowDays: config?.windowDays ?? DEFAULT_WINDOW_DAYS,
+    topN: config?.topN ?? DEFAULT_TOP_N,
+    minTotalEntries: config?.minTotalEntries ?? DEFAULT_MIN_TOTAL_ENTRIES,
+    minConsumedWindows: config?.minConsumedWindows ?? DEFAULT_MIN_CONSUMED_WINDOWS,
+    minConsumedEvents: config?.minConsumedEvents ?? DEFAULT_MIN_CONSUMED_EVENTS
+  };
+}
+function aggregateConsumption(rows, allQualifiedIds, now, config) {
+  const cfg = resolveConfig(config);
+  const cutoffMs = now - cfg.windowDays * MS_PER_DAY5;
+  const consumed = /* @__PURE__ */ new Map();
+  let consumedWindows = 0;
+  let totalConsumedEvents = 0;
+  for (const row of rows) {
+    const rowTs = Date.parse(row.timestamp);
+    if (!Number.isFinite(rowTs) || rowTs < cutoffMs) continue;
+    if (row.counters === null || typeof row.counters !== "object") continue;
+    let windowHadConsumption = false;
+    for (const [counterName, rawCount] of Object.entries(row.counters)) {
+      if (!counterName.startsWith(CONSUMED_PREFIX)) continue;
+      const count = typeof rawCount === "number" ? rawCount : 0;
+      if (count <= 0) continue;
+      const id = counterName.slice(CONSUMED_PREFIX.length);
+      if (id.length === 0) continue;
+      consumed.set(id, (consumed.get(id) ?? 0) + count);
+      totalConsumedEvents += count;
+      windowHadConsumption = true;
+    }
+    if (windowHadConsumption) consumedWindows += 1;
+  }
+  const topConsumed = [...consumed.entries()].map(([stableId, count]) => ({ stableId, count })).sort((a, b) => b.count - a.count || a.stableId.localeCompare(b.stableId)).slice(0, cfg.topN);
+  const dataMature = consumedWindows >= cfg.minConsumedWindows && totalConsumedEvents >= cfg.minConsumedEvents && allQualifiedIds.length >= cfg.minTotalEntries;
+  const zeroConsumed = dataMature ? allQualifiedIds.filter((id) => !consumed.has(id)).sort((a, b) => a.localeCompare(b)) : [];
+  return {
+    topConsumed,
+    zeroConsumed,
+    totalEntries: allQualifiedIds.length,
+    consumedEntries: consumed.size,
+    consumedWindows,
+    totalConsumedEvents,
+    dataMature,
+    windowDays: cfg.windowDays
+  };
+}
+async function inspectConsumption(projectRoot, config, now = Date.now()) {
+  const rows = await readMetrics(projectRoot);
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  const allQualifiedIds = entries.map((entry) => entry.qualifiedId);
+  return aggregateConsumption(rows, allQualifiedIds, now, config);
+}
+
 // src/services/rotation-tick.ts
 var DEFAULT_TICK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
 var tickTimers = /* @__PURE__ */ new Map();
@@ -10499,7 +11202,7 @@ import { IOFabricError as IOFabricError2, RuleError } from "@fenglimg/fabric-sha
 
 // src/services/read-ledger.ts
 import { randomUUID as randomUUID7 } from "crypto";
-import { access as access5, copyFile, readFile as readFile19, rm } from "fs/promises";
+import { access as access5, copyFile, readFile as readFile21, rm } from "fs/promises";
 import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
 async function resolveLedgerPaths(projectRoot) {
   const primaryPath = getLedgerPath(projectRoot);
@@ -10527,7 +11230,7 @@ async function readLegacyLedger(projectRoot) {
   const { readPath } = await resolveLedgerPaths(projectRoot);
   let raw;
   try {
-    raw = await readFile19(readPath, "utf8");
+    raw = await readFile21(readPath, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return [];
@@ -10782,8 +11485,8 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync9(join25(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync9(join25(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync10(join27(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync10(join27(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
   if (preexisting.length === 0) return null;
   return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves knowledge from mounted stores via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
@@ -10810,7 +11513,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.3.0-rc.3"
+      version: "2.3.0-rc.5"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -10830,10 +11533,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path = join25(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join27(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
-      if (existsSync9(path)) {
-        text = await readFile20(path, "utf8");
+      if (existsSync10(path)) {
+        text = await readFile22(path, "utf8");
       }
       return {
         contents: [
@@ -10933,11 +11636,15 @@ export {
   METRIC_COUNTER_NAMES,
   OPTIONAL_EMBED_PACKAGE,
   RETIRED_TOKENS,
+  aggregateConsumption,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
   buildColdEvalBatch,
   buildKnowledgeCensus,
+  buildRelatedGraph,
   bumpCounter,
+  clearPrecheckCache,
+  collectStoreCanonicalEntries,
   contextCache,
   createFabricServer,
   createInFlightTracker,
@@ -10946,6 +11653,7 @@ export {
   detectUnboundProject,
   drainCounters,
   enrichDescriptions,
+  evaluateStoreDir,
   explainWhyNotSurfaced,
   extractKnowledge,
   findConflictCandidates,
@@ -10956,12 +11664,16 @@ export {
   getLedgerPath,
   getLegacyLedgerPath,
   getMetricsLedgerPath,
+  inspectConsumption,
+  inspectRelatedGraph,
   inspectRetiredReferences,
+  isEmbedderResolvable,
   lintConflicts,
   loadConflictEntries,
   loadEmbedder,
   pairSimilarity,
   planContext,
+  precheckStoreReachability,
   readEmbedConfig,
   readEventLedger,
   readFusion,