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

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile19 } from "fs/promises";
-import { join as join23, resolve as resolve4 } from "path";
+import { readFile as readFile20 } from "fs/promises";
+import { join as join25, 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";
@@ -742,7 +742,7 @@ var SUPPORTED_EMBED_MODELS = /* @__PURE__ */ new Set([
 function readEmbedConfig(projectRoot) {
   try {
     const config = readFabricConfig(projectRoot);
-    const enabled = config.embed_enabled === true;
+    const enabled = config.embed_enabled !== false;
     const rawWeight = config.embed_weight;
     const weight = typeof rawWeight === "number" && Number.isInteger(rawWeight) && rawWeight >= 0 && rawWeight <= 49 ? rawWeight : 30;
     const rawModel = config.embed_model;
@@ -817,6 +817,15 @@ function readOrphanDemoteThresholdDays(projectRoot) {
     return {};
   }
 }
+function readFusion(projectRoot) {
+  try {
+    const raw = readFabricConfig(projectRoot).fusion;
+    if (raw === "rrf" || raw === "additive") return raw;
+    return "auto";
+  } catch {
+    return "auto";
+  }
+}
 function readConflictLintThreshold(projectRoot) {
   try {
     const cfgPath = join4(projectRoot, ".fabric", "fabric-config.json");
@@ -1534,11 +1543,44 @@ function buildBm25Model(docs) {
   for (const field of BM25_FIELDS) {
     avgFieldLength[field] = totalDocs > 0 ? totalFieldLength[field] / totalDocs : 0;
   }
+  const serialized = {
+    version: 1,
+    totalDocs,
+    documentFrequency: [...documentFrequency],
+    avgFieldLength,
+    perDoc: [...perDoc].map(([id, stats]) => ({
+      id,
+      fieldTermFreq: emptyFieldRecord(() => []),
+      fieldLength: { ...stats.fieldLength }
+    }))
+  };
+  for (const entry of serialized.perDoc) {
+    const stats = perDoc.get(entry.id);
+    if (stats === void 0) continue;
+    for (const field of BM25_FIELDS) {
+      entry.fieldTermFreq[field] = [...stats.fieldTermFreq[field]];
+    }
+  }
+  return modelFromStats(serialized);
+}
+function modelFromStats(serialized) {
+  const totalDocs = serialized.totalDocs;
+  const documentFrequency = new Map(serialized.documentFrequency);
+  const avgFieldLength = serialized.avgFieldLength;
+  const perDoc = /* @__PURE__ */ new Map();
+  for (const entry of serialized.perDoc) {
+    const fieldTermFreq = emptyFieldRecord(() => /* @__PURE__ */ new Map());
+    for (const field of BM25_FIELDS) {
+      fieldTermFreq[field] = new Map(entry.fieldTermFreq[field]);
+    }
+    perDoc.set(entry.id, { fieldTermFreq, fieldLength: entry.fieldLength });
+  }
   const idf = (term) => {
     const n = documentFrequency.get(term) ?? 0;
     return Math.log(1 + (totalDocs - n + 0.5) / (n + 0.5));
   };
   return {
+    __serialized: serialized,
     scoreDoc(id, queryTerms) {
       const data = perDoc.get(id);
       if (data === void 0 || queryTerms.length === 0) {
@@ -1574,9 +1616,48 @@ function buildBm25Model(docs) {
     }
   };
 }
+function serializeBm25Model(model) {
+  return model.__serialized;
+}
+function rehydrateBm25Model(serialized) {
+  return modelFromStats(serialized);
+}
 function buildQueryTerms(text) {
   return tokenize(text);
 }
+function rankDocuments(model, ids, queryTerms) {
+  if (queryTerms.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const scored = [];
+  ids.forEach((id, order) => {
+    const score = model.scoreDoc(id, queryTerms);
+    if (score > 0) {
+      scored.push({ id, score, order });
+    }
+  });
+  scored.sort((a, b) => a.score !== b.score ? b.score - a.score : a.order - b.order);
+  const ranks = /* @__PURE__ */ new Map();
+  scored.forEach((entry, index) => {
+    ranks.set(entry.id, index + 1);
+  });
+  return ranks;
+}
+function rankByScore(ids, scores) {
+  const scored = [];
+  ids.forEach((id, order) => {
+    const score = scores.get(id) ?? 0;
+    if (score > 0) {
+      scored.push({ id, score, order });
+    }
+  });
+  scored.sort((a, b) => a.score !== b.score ? b.score - a.score : a.order - b.order);
+  const ranks = /* @__PURE__ */ new Map();
+  scored.forEach((entry, index) => {
+    ranks.set(entry.id, index + 1);
+  });
+  return ranks;
+}
 
 // src/services/conflict-lint.ts
 function buildSimilarityModel(docs) {
@@ -2670,13 +2751,37 @@ var LEDGER_DUAL_WRITE_METRIC_NAMES = {
   edit_intent_checked: METRIC_COUNTER_NAMES.edit_intent_checked
 };
 
+// src/services/plan-context.ts
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { join as join10 } from "path";
+
 // src/services/vector-retrieval.ts
+import { mkdirSync } from "fs";
+import { join as join9 } from "path";
+import { resolveGlobalRoot as resolveGlobalRoot3 } from "@fenglimg/fabric-shared";
 var embedderLoad;
 var OPTIONAL_EMBED_PACKAGE = "fastembed";
+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 = () => {
+  process.stderr.write(MISSING_EMBEDDER_HINT);
+};
+var missingEmbedderHinted = false;
+var emitMissingEmbedderHint = defaultMissingEmbedderHint;
+function hintMissingEmbedderOnce() {
+  if (missingEmbedderHinted) {
+    return;
+  }
+  missingEmbedderHinted = true;
+  emitMissingEmbedderHint();
+}
+function defaultEmbedCacheDir() {
+  return join9(resolveGlobalRoot3(), "cache", "embed");
+}
 function buildEmbedInitOptions(modelName) {
   return {
     maxLength: 512,
-    cacheDir: process.env.FABRIC_EMBED_CACHE_DIR,
+    cacheDir: process.env.FABRIC_EMBED_CACHE_DIR ?? defaultEmbedCacheDir(),
     ...typeof modelName === "string" && modelName.length > 0 ? { model: modelName } : {}
   };
 }
@@ -2685,11 +2790,14 @@ async function loadEmbedder(modelName) {
     embedderLoad = (async () => {
       try {
         const moduleName = OPTIONAL_EMBED_PACKAGE;
-        const mod = await import(moduleName);
+        const mod = await embedderModuleLoader(moduleName);
         if (mod?.FlagEmbedding?.init === void 0) {
+          hintMissingEmbedderOnce();
           return null;
         }
-        const model = await mod.FlagEmbedding.init(buildEmbedInitOptions(modelName));
+        const initOpts = buildEmbedInitOptions(modelName);
+        mkdirSync(initOpts.cacheDir, { recursive: true });
+        const model = await mod.FlagEmbedding.init(initOpts);
         return {
           async embed(texts) {
             const out = [];
@@ -2702,6 +2810,7 @@ async function loadEmbedder(modelName) {
           }
         };
       } catch {
+        hintMissingEmbedderOnce();
         return null;
       }
     })();
@@ -2732,7 +2841,7 @@ function cosineSimilarity(a, b) {
   if (!Number.isFinite(sim)) {
     return 0;
   }
-  return Math.max(-1, Math.min(1, sim));
+  return Math.max(0, Math.min(1, sim));
 }
 var docVectorCache = /* @__PURE__ */ new Map();
 var DOC_VECTOR_CACHE_MAX = 1e4;
@@ -2837,56 +2946,28 @@ async function planContext(projectRoot, input) {
     ...input.known_tech ?? [],
     ...Object.values(input.detected_entities ?? {}).flat()
   ].join(" ");
-  const scoringContext = {
-    nowMs: Date.now(),
-    targetPaths: input.target_paths ?? dedupePaths(input.paths),
-    queryTerms: buildQueryTerms(queryText)
-  };
   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 docTexts = /* @__PURE__ */ new Map();
-  for (const item of rawItems) {
-    docTexts.set(item.stable_id, documentTextForItem(item.description));
-  }
-  scoringContext.docTexts = docTexts;
-  if (scoringContext.queryTerms.length > 0 && rawItems.length > 0) {
-    scoringContext.bm25 = getOrBuildBm25Model(revision, rawItems, docTexts);
-  }
-  scoringContext.scopeRank = buildScopeRankMap(rawItems, projectRoot);
-  const embedConfig = readEmbedConfig(projectRoot);
-  if (embedConfig.enabled && queryText.trim().length > 0 && rawItems.length > 0) {
-    const embedder = await loadEmbedder(embedConfig.model);
-    const vectorScores = await buildVectorScores(
-      embedder,
-      queryText,
-      rawItems.map((item) => ({
-        stable_id: item.stable_id,
-        text: docTexts.get(item.stable_id) ?? documentTextForItem(item.description)
-      }))
-    );
-    if (vectorScores !== null) {
-      scoringContext.vectorScores = vectorScores;
-      scoringContext.vectorWeight = embedConfig.weight;
-    }
-  }
-  const scoredSorted = sortDescriptionItems(rawItems, scoringContext);
-  const seenStableIds = /* @__PURE__ */ new Set();
-  const rankedScored = scoredSorted.filter(({ item }) => {
-    if (seenStableIds.has(item.stable_id)) return false;
-    seenStableIds.add(item.stable_id);
-    return true;
+  const scoringContext = await buildScoringContext(projectRoot, revision, rawItems, {
+    queryText,
+    targetPaths: input.target_paths ?? dedupePaths(input.paths)
   });
+  const rankedScored = rankDescriptionItems(rawItems, scoringContext, "triage");
   const rankedCandidates = rankedScored.map((entry) => entry.item);
-  const topK = readPlanContextTopK(projectRoot);
-  const cappedScored = rankedScored.slice(0, topK);
-  const relevanceRatio = readRecallRelevanceRatio(projectRoot);
-  const hasQuery = scoringContext.queryTerms.length > 0;
-  const maxScore = rankedScored.length > 0 ? rankedScored[0].score : 0;
-  const relevanceFloor = maxScore * relevanceRatio;
-  const survivingScored = hasQuery && maxScore > 0 && relevanceRatio > 0 ? cappedScored.filter((entry) => entry.score >= relevanceFloor) : cappedScored;
+  const survivingScored = rankDescriptionItems(rawItems, scoringContext, "recall", {
+    topK: readPlanContextTopK(projectRoot),
+    relevanceRatio: readRecallRelevanceRatio(projectRoot)
+  });
   const topKCandidates = survivingScored.map((entry) => entry.item);
+  const candidateScores = /* @__PURE__ */ new Map();
+  for (const entry of survivingScored) {
+    candidateScores.set(entry.item.stable_id, {
+      score: entry.score,
+      score_breakdown: scoreBreakdownForItem(entry.item, scoringContext)
+    });
+  }
   const topKIds = new Set(topKCandidates.map((item) => item.stable_id));
   const retrievalDropped = rankedCandidates.filter((item) => !topKIds.has(item.stable_id)).map((item) => ({ id: item.stable_id, reason: "retrieval_budget" }));
   const omittedCandidateCount = retrievalDropped.length;
@@ -2992,6 +3073,8 @@ async function planContext(projectRoot, input) {
     // ONLY when at least one neighbour was actually appended. Empty (graph-empty
     // no-op) → field omitted, steady-state wire shape unchanged.
     ...Object.keys(relatedAppended).length > 0 ? { related_appended: relatedAppended } : {},
+    // P1 recall-observability: runtime-only score channel (Map → {} on the wire).
+    ...candidateScores.size > 0 ? { candidate_scores: candidateScores } : {},
     ...payloadTrimDropped > 0 ? { payload_trimmed: true } : {},
     ...payloadOverBudget ? { payload_over_budget: true } : {}
   };
@@ -3080,10 +3163,38 @@ function partitionEmptyShells(items) {
 }
 var bm25ModelCache = null;
 var bm25BuildCount = 0;
-function getOrBuildBm25Model(revision, rawItems, docTexts) {
+var BM25_CACHE_DIR = ".fabric/cache/bm25";
+function bm25CachePath(projectRoot, revision) {
+  const safe = revision.replace(/[^A-Za-z0-9_-]/g, "_");
+  return join10(projectRoot, BM25_CACHE_DIR, `${safe}.json`);
+}
+async function loadBm25ModelFromDisk(projectRoot, revision) {
+  try {
+    const raw = await readFile5(bm25CachePath(projectRoot, revision), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) return null;
+    return rehydrateBm25Model(parsed);
+  } catch {
+    return null;
+  }
+}
+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");
+  } catch {
+  }
+}
+async function getOrBuildBm25Model(projectRoot, revision, rawItems, docTexts) {
   if (bm25ModelCache !== null && bm25ModelCache.revision === revision) {
     return bm25ModelCache.model;
   }
+  const fromDisk = await loadBm25ModelFromDisk(projectRoot, revision);
+  if (fromDisk !== null) {
+    bm25ModelCache = { revision, model: fromDisk };
+    return fromDisk;
+  }
   bm25BuildCount += 1;
   const model = buildBm25Model(
     rawItems.map((item) => ({
@@ -3092,6 +3203,7 @@ function getOrBuildBm25Model(revision, rawItems, docTexts) {
     }))
   );
   bm25ModelCache = { revision, model };
+  await saveBm25ModelToDisk(projectRoot, revision, model);
   return model;
 }
 function compareStableIds(a, b) {
@@ -3137,6 +3249,51 @@ function compareScopeThenId(left, right, scopeRank) {
   }
   return compareStableIds(left.stable_id, right.stable_id);
 }
+async function buildScoringContext(projectRoot, revision, rawItems, opts) {
+  const scoringContext = {
+    nowMs: Date.now(),
+    targetPaths: opts.targetPaths,
+    queryTerms: buildQueryTerms(opts.queryText)
+  };
+  const docTexts = /* @__PURE__ */ new Map();
+  for (const item of rawItems) {
+    docTexts.set(item.stable_id, documentTextForItem(item.description));
+  }
+  scoringContext.docTexts = docTexts;
+  if (scoringContext.queryTerms.length > 0 && rawItems.length > 0) {
+    scoringContext.bm25 = await getOrBuildBm25Model(projectRoot, revision, rawItems, docTexts);
+  }
+  scoringContext.scopeRank = buildScopeRankMap(rawItems, projectRoot);
+  const embedConfig = readEmbedConfig(projectRoot);
+  if (embedConfig.enabled && opts.queryText.trim().length > 0 && rawItems.length > 0) {
+    const embedder = await loadEmbedder(embedConfig.model);
+    const vectorScores = await buildVectorScores(
+      embedder,
+      opts.queryText,
+      rawItems.map((item) => ({
+        stable_id: item.stable_id,
+        text: docTexts.get(item.stable_id) ?? documentTextForItem(item.description)
+      }))
+    );
+    if (vectorScores !== null) {
+      scoringContext.vectorScores = vectorScores;
+      scoringContext.vectorWeight = embedConfig.weight;
+    }
+  }
+  const configuredFusion = readFusion(projectRoot);
+  const vectorActive = scoringContext.vectorScores !== void 0 && scoringContext.vectorScores.size > 0;
+  scoringContext.fusion = configuredFusion === "auto" ? vectorActive ? "rrf" : "additive" : configuredFusion;
+  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) {
+      scoringContext.bm25Ranks = rankDocuments(scoringContext.bm25, rankIds, scoringContext.queryTerms);
+    }
+    if (scoringContext.vectorScores !== void 0) {
+      scoringContext.vectorRanks = rankByScore(rankIds, scoringContext.vectorScores);
+    }
+  }
+  return scoringContext;
+}
 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 }));
@@ -3151,6 +3308,25 @@ function sortDescriptionItems(rawItems, scoringContext) {
   );
   return scored;
 }
+function rankDescriptionItems(items, scoringContext, mode, options = {}) {
+  const sorted = sortDescriptionItems(items, scoringContext);
+  const seen = /* @__PURE__ */ new Set();
+  const rankedScored = sorted.filter(({ item }) => {
+    if (seen.has(item.stable_id)) return false;
+    seen.add(item.stable_id);
+    return true;
+  });
+  if (mode === "triage") {
+    return rankedScored;
+  }
+  const topK = options.topK ?? rankedScored.length;
+  const cappedScored = rankedScored.slice(0, topK);
+  const relevanceRatio = options.relevanceRatio ?? 0;
+  const hasQuery = scoringContext.queryTerms.length > 0;
+  const maxScore = rankedScored.length > 0 ? rankedScored[0].score : 0;
+  const relevanceFloor = maxScore * relevanceRatio;
+  return hasQuery && maxScore > 0 && relevanceRatio > 0 ? cappedScored.filter((entry) => entry.score >= relevanceFloor) : cappedScored;
+}
 function documentTextForItem(description) {
   return [
     description.summary,
@@ -3199,6 +3375,9 @@ var BM25_WEIGHT = 50;
 var SALIENCE_PROVEN = 15;
 var SALIENCE_VERIFIED = 8;
 var SALIENCE_DRAFT = 0;
+var RRF_K = 10;
+var RRF_NORMALIZATION = 2e3;
+var RRF_STRUCTURAL_SCALE = 0.2;
 function salienceScore(item) {
   switch (item.description?.maturity) {
     case "proven":
@@ -3209,35 +3388,87 @@ function salienceScore(item) {
       return SALIENCE_DRAFT;
   }
 }
-function scoreDescriptionItem(item, context) {
-  let score = 0;
-  if (context.bm25 !== void 0 && context.queryTerms.length > 0) {
-    score += BM25_WEIGHT * context.bm25.scoreDoc(item.stable_id, context.queryTerms);
+function contentScore(item, context) {
+  const hasQuery = context.queryTerms.length > 0;
+  if (context.fusion === "rrf" && hasQuery) {
+    let rrf = 0;
+    const bm25Rank = context.bm25Ranks?.get(item.stable_id);
+    if (bm25Rank !== void 0) rrf += 1 / (RRF_K + bm25Rank);
+    const vectorRank = context.vectorRanks?.get(item.stable_id);
+    if (vectorRank !== void 0) rrf += 1 / (RRF_K + vectorRank);
+    return RRF_NORMALIZATION * rrf;
+  }
+  let content = 0;
+  if (context.bm25 !== void 0 && hasQuery) {
+    content += BM25_WEIGHT * context.bm25.scoreDoc(item.stable_id, context.queryTerms);
   }
   if (context.vectorScores !== void 0) {
-    score += (context.vectorWeight ?? 0) * (context.vectorScores.get(item.stable_id) ?? 0);
+    content += (context.vectorWeight ?? 0) * (context.vectorScores.get(item.stable_id) ?? 0);
   }
-  score += salienceScore(item);
+  return content;
+}
+function recencyBoost(item, context) {
   const createdAtRaw = item.description?.created_at;
   if (typeof createdAtRaw === "string" && createdAtRaw.length > 0) {
     const createdMs = Date.parse(createdAtRaw);
     if (Number.isFinite(createdMs) && context.nowMs - createdMs < RECENCY_WINDOW_MS) {
-      score += RECENCY_BOOST;
+      return RECENCY_BOOST;
     }
   }
-  if (context.targetPaths.length > 0) {
-    const relevancePaths = item.description?.relevance_paths ?? [];
-    let best = 0;
-    outer: for (const rp of relevancePaths) {
-      for (const tp of context.targetPaths) {
-        const tier = localityTier(rp, tp);
-        if (tier > best) best = tier;
-        if (best === LOCALITY_SAME_FILE) break outer;
-      }
+  return 0;
+}
+function localityBoost(item, context) {
+  if (context.targetPaths.length === 0) return 0;
+  const relevancePaths = item.description?.relevance_paths ?? [];
+  let best = 0;
+  outer: for (const rp of relevancePaths) {
+    for (const tp of context.targetPaths) {
+      const tier = localityTier(rp, tp);
+      if (tier > best) best = tier;
+      if (best === LOCALITY_SAME_FILE) break outer;
     }
-    score += best;
   }
-  return score;
+  return best;
+}
+function structuralScaleFor(context) {
+  return context.fusion === "rrf" && context.queryTerms.length > 0 ? RRF_STRUCTURAL_SCALE : 1;
+}
+function scoreDescriptionItem(item, context) {
+  const content = contentScore(item, context);
+  const structural = salienceScore(item) + recencyBoost(item, context) + localityBoost(item, context);
+  return content + structuralScaleFor(context) * structural;
+}
+function scoreBreakdownForItem(item, context) {
+  const hasQuery = context.queryTerms.length > 0;
+  const rrfMode = context.fusion === "rrf" && hasQuery;
+  let bm25 = 0;
+  let vector = 0;
+  let bm25Rank;
+  let vectorRank;
+  if (rrfMode) {
+    bm25Rank = context.bm25Ranks?.get(item.stable_id);
+    if (bm25Rank !== void 0) bm25 = RRF_NORMALIZATION * (1 / (RRF_K + bm25Rank));
+    vectorRank = context.vectorRanks?.get(item.stable_id);
+    if (vectorRank !== void 0) vector = RRF_NORMALIZATION * (1 / (RRF_K + vectorRank));
+  } else {
+    bm25 = context.bm25 !== void 0 && hasQuery ? BM25_WEIGHT * context.bm25.scoreDoc(item.stable_id, context.queryTerms) : 0;
+    vector = context.vectorScores !== void 0 ? (context.vectorWeight ?? 0) * (context.vectorScores.get(item.stable_id) ?? 0) : 0;
+  }
+  const scale = structuralScaleFor(context);
+  const salience = salienceScore(item) * scale;
+  const recency = recencyBoost(item, context) * scale;
+  const locality = localityBoost(item, context) * scale;
+  const final = bm25 + vector + salience + recency + locality;
+  return {
+    final,
+    ...bm25 !== 0 ? { bm25 } : {},
+    ...bm25Rank !== void 0 ? { bm25_rank: bm25Rank } : {},
+    ...vector !== 0 ? { vector } : {},
+    ...vectorRank !== void 0 ? { vector_rank: vectorRank } : {},
+    salience,
+    recency,
+    locality
+  };
 }
 function localityTier(relevancePath, targetPath) {
   if (relevancePath === targetPath) return LOCALITY_SAME_FILE;
@@ -3274,7 +3505,13 @@ function relatedLookupKeys(stableId) {
 var RECALL_DIRECTIVE = "These entries are auto-accounted as citations for edits whose paths overlap this recall \u2014 no first-line cite needed. Speak up only to dismiss one you judge inapplicable: `dismissed: <id> (<reason>)`.";
 async function recall(projectRoot, input) {
   const planResult = await planContext(projectRoot, input);
-  const { selection_token: _token, payload_trimmed: _pt, payload_over_budget: _pob, ...planRest } = planResult;
+  const {
+    selection_token: _token,
+    payload_trimmed: _pt,
+    payload_over_budget: _pob,
+    candidate_scores: candidateScores,
+    ...planRest
+  } = planResult;
   let bodyIndex;
   try {
     bodyIndex = await buildCrossStoreBodyIndex(projectRoot);
@@ -3323,13 +3560,15 @@ async function recall(projectRoot, input) {
   const pathByStableId = new Map(paths.map((p) => [p.stable_id, p]));
   const entries = planRest.candidates.map((c, index) => {
     const readPath = pathByStableId.get(c.stable_id);
+    const scored = candidateScores?.get(c.stable_id);
     return {
       stable_id: c.stable_id,
       rank: index + 1,
       description: c.description,
       ...readPath ? { read_path: readPath.path } : {},
       ...readPath?.store ? { store: readPath.store } : {},
-      ...isAlwaysActive(c) ? { body_in_context: true } : {}
+      ...isAlwaysActive(c) ? { body_in_context: true } : {},
+      ...scored ? { score: scored.score, score_breakdown: scored.score_breakdown } : {}
     };
   });
   const { entries: _reqProfiles, candidates: _candidates, ...planRestNoLists } = planRest;
@@ -3679,9 +3918,9 @@ 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 readFile6, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
+import { readFile as readFile7, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
 import { homedir } from "os";
-import { basename, isAbsolute, join as join10, relative, resolve as resolve2, sep as sep2 } from "path";
+import { basename, isAbsolute, join as join12, relative, resolve as resolve2, sep as sep2 } from "path";
 
 // src/services/promotion-gate.ts
 function toLocalId(id) {
@@ -3721,8 +3960,8 @@ import { allocateStoreKnowledgeId, isPersonalScope as isPersonalScope2 } from "@
 
 // src/services/pending-dedupe.ts
 import { existsSync as existsSync4 } from "fs";
-import { readdir, readFile as readFile5, unlink } from "fs/promises";
-import { join as join9 } from "path";
+import { readdir, readFile as readFile6, 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;
 var SOURCE_SESSIONS_LINE = /^source_sessions:\s*\[(.*)\]\s*$/mu;
@@ -3795,7 +4034,7 @@ async function mergePendingTwins(projectRoot) {
       continue;
     }
     for (const type of PENDING_TYPES) {
-      const dir = join9(pendingBase2, type);
+      const dir = join11(pendingBase2, type);
       if (!existsSync4(dir)) continue;
       let names;
       try {
@@ -3816,10 +4055,10 @@ async function mergePendingTwins(projectRoot) {
         if (groupNames.length < 2) continue;
         const parsed = [];
         for (const name of groupNames) {
-          const abs = join9(dir, name);
+          const abs = join11(dir, name);
           let content;
           try {
-            content = await readFile5(abs, "utf8");
+            content = await readFile6(abs, "utf8");
           } catch {
             continue;
           }
@@ -3919,7 +4158,7 @@ async function reviewPending(projectRoot, input) {
     case "search":
       return {
         action: "search",
-        items: await searchEntries(projectRoot, input.query, input.filters)
+        items: await triageSearch(projectRoot, input.query, input.filters)
       };
     default: {
       const exhaustive = input;
@@ -3999,7 +4238,7 @@ async function listPending(projectRoot, filters) {
   }
   for (const source of sources) {
     for (const type of typesToScan) {
-      const dir = join10(source.root, type);
+      const dir = join12(source.root, type);
       if (!existsSync5(dir)) {
         continue;
       }
@@ -4011,10 +4250,10 @@ async function listPending(projectRoot, filters) {
       }
       for (const name of entries) {
         if (!name.endsWith(".md")) continue;
-        const absolutePath = join10(dir, name);
+        const absolutePath = join12(dir, name);
         let content;
         try {
-          content = await readFile6(absolutePath, "utf8");
+          content = await readFile7(absolutePath, "utf8");
         } catch {
           continue;
         }
@@ -4124,7 +4363,7 @@ async function approveOne(projectRoot, pendingPath) {
   let targetAbs;
   let writtenTarget = false;
   try {
-    const content = await readFile6(sourceAbs, "utf8");
+    const content = await readFile7(sourceAbs, "utf8");
     const fm = parseFrontmatter(content);
     const pluralType = fm.type;
     if (pluralType === void 0 || !PLURAL_TYPES.includes(pluralType)) {
@@ -4138,7 +4377,7 @@ async function approveOne(projectRoot, pendingPath) {
     );
     allocatedId = stableId;
     const newFilename = `${stableId}--${slug}.md`;
-    targetAbs = join10(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
+    targetAbs = join12(resolveStoreCanonicalBase(layer, projectRoot), pluralType, newFilename);
     await ensureParentDirectory(targetAbs);
     const rewritten = rewriteFrontmatterMerge(
       rewriteFrontmatterForPromote(content, stableId),
@@ -4196,7 +4435,7 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile6(sandboxed.abs, "utf8");
+        const content = await readFile7(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) {
@@ -4223,7 +4462,7 @@ async function modifyEntry(projectRoot, pendingPath, changes) {
   if (target === null) {
     throw new Error(`modify target not found: ${pendingPath}`);
   }
-  const content = await readFile6(target.absPath, "utf8");
+  const content = await readFile7(target.absPath, "utf8");
   const fm = parseFrontmatter(content);
   const currentLayer = fm.layer ?? "team";
   if (fm.maturity === "verified" && changes.maturity === "proven" && fm.id !== void 0) {
@@ -4325,7 +4564,7 @@ async function modifyLayerFlip(projectRoot, target, content, fm, changes) {
     pluralType,
     resolveWriteTargetStoreDir(toLayer, projectRoot)
   );
-  const toAbs = join10(
+  const toAbs = join12(
     resolveStoreCanonicalBase(toLayer, projectRoot),
     pluralType,
     `${newStableId}--${slug}.md`
@@ -4425,7 +4664,7 @@ function getSearchDirectoryCache(cacheKey) {
   return created;
 }
 async function listIndexedSearchEntries(source, type) {
-  const dir = join10(source.root, type);
+  const dir = join12(source.root, type);
   let entries;
   try {
     entries = await readdir2(dir);
@@ -4438,7 +4677,7 @@ async function listIndexedSearchEntries(source, type) {
   const indexed = [];
   for (const name of entries) {
     if (!name.endsWith(".md")) continue;
-    const absolutePath = join10(dir, name);
+    const absolutePath = join12(dir, name);
     let fingerprint;
     try {
       const st = await stat2(absolutePath);
@@ -4455,7 +4694,7 @@ async function listIndexedSearchEntries(source, type) {
     }
     let content;
     try {
-      content = await readFile6(absolutePath, "utf8");
+      content = await readFile7(absolutePath, "utf8");
       searchEntryIndexContentReads += 1;
     } catch {
       directoryCache.files.delete(absolutePath);
@@ -4482,9 +4721,41 @@ async function listIndexedSearchEntries(source, type) {
   }
   return indexed;
 }
-async function searchEntries(projectRoot, query, filters) {
+function matchesTriageQuery(indexed, lowerQuery, includeBody) {
+  const haystacks = [
+    indexed.fm.title ?? "",
+    indexed.fm.summary ?? "",
+    ...indexed.fm.tags ?? [],
+    indexed.name,
+    includeBody ? indexed.body : ""
+  ].map((s) => s.toLowerCase());
+  return haystacks.some((h) => h.includes(lowerQuery));
+}
+function pendingEntryToRankerItem(indexed) {
+  const { fm, name } = indexed;
+  const slug = name.replace(/\.md$/u, "");
+  const summary = fm.summary ?? fm.title ?? slug;
+  const description = {
+    summary,
+    intent_clues: [],
+    tech_stack: [],
+    impact: [],
+    must_read_if: fm.title ?? summary,
+    ...fm.id !== void 0 ? { id: fm.id } : {},
+    ...fm.type !== void 0 ? { knowledge_type: fm.type } : {},
+    maturity: fm.maturity ?? "draft",
+    knowledge_layer: indexed.layer,
+    ...fm.semantic_scope !== void 0 ? { semantic_scope: fm.semantic_scope } : {},
+    ...fm.created_at !== void 0 ? { created_at: fm.created_at } : {},
+    tags: fm.tags ?? [],
+    relevance_scope: fm.relevance_scope ?? "broad",
+    relevance_paths: fm.relevance_paths ?? []
+  };
+  return { stable_id: indexed.absolutePath, description };
+}
+async function triageSearch(projectRoot, query, filters) {
   const lowerQuery = query.toLowerCase();
-  const items = [];
+  const includeBody = filters?.include_body === true;
   const sources = [];
   for (const layer of ["team", "personal"]) {
     const isPersonal = layer === "personal";
@@ -4507,10 +4778,12 @@ async function searchEntries(projectRoot, query, filters) {
     }
   }
   const typesToScan = filters?.type !== void 0 ? [filters.type] : PLURAL_TYPES;
+  const matchedByKey = /* @__PURE__ */ new Map();
+  const rankerItems = [];
   for (const source of sources) {
     for (const type of typesToScan) {
       for (const indexed of await listIndexedSearchEntries(source, type)) {
-        const { absolutePath, fm, layer, maturity, name } = indexed;
+        const { fm, layer, maturity } = indexed;
         if (filters?.layer !== void 0 && filters.layer !== "both" && filters.layer !== layer) {
           continue;
         }
@@ -4531,42 +4804,56 @@ async function searchEntries(projectRoot, query, filters) {
         if (!isVisibleByLifecycle(fm, filters)) {
           continue;
         }
-        const bodyForSearch = filters?.include_body === true ? indexed.body : "";
-        const haystacks = [
-          fm.title ?? "",
-          fm.summary ?? "",
-          ...fm.tags ?? [],
-          name,
-          bodyForSearch
-        ].map((s) => s.toLowerCase());
-        const matches = haystacks.some((h) => h.includes(lowerQuery));
-        if (!matches) continue;
-        const reportedPath = source.isStore ? absolutePath : source.isPersonal ? `~/${relative(resolvePersonalRoot(), absolutePath)}` : relative(projectRoot, absolutePath);
-        items.push({
-          area: source.isPending ? "pending" : "canonical",
-          path: reportedPath,
-          ...source.isPersonal ? { path_absolute: absolutePath } : {},
-          type,
-          layer,
-          maturity,
-          // Only pending entries carry an origin tag (canonical hits live
-          // outside the dual-pending-root convention).
-          ...source.isPending ? { origin: source.isPersonal ? "personal" : "team" } : {},
-          ...fm.tags !== void 0 && fm.tags.length > 0 ? { tags: fm.tags } : {},
-          ...fm.title !== void 0 ? { title: fm.title } : {},
-          ...fm.summary !== void 0 ? { summary: fm.summary } : {},
-          ...fm.status !== void 0 ? { status: fm.status } : {},
-          ...fm.deferred_until !== void 0 ? { deferred_until: fm.deferred_until } : {},
-          // v2.0.0-rc.27 TASK-006 (audit §2.23): body emission when opted in.
-          ...filters?.include_body === true ? { body: bodyForSearch } : {},
-          // Canonical hits always have an id; pending hits typically don't
-          // yet — surface the frontmatter id when present so consumers can
-          // dedupe across runs.
-          ...fm.id !== void 0 ? { stable_id: fm.id } : {}
-        });
+        if (!matchesTriageQuery(indexed, lowerQuery, includeBody)) continue;
+        const item = pendingEntryToRankerItem(indexed);
+        matchedByKey.set(item.stable_id, { indexed, source, type });
+        rankerItems.push(item);
       }
     }
   }
+  if (rankerItems.length === 0) {
+    return [];
+  }
+  let revision;
+  try {
+    revision = await computeReadSetRevision(projectRoot);
+  } catch {
+    revision = "triage-search";
+  }
+  const scoringContext = await buildScoringContext(projectRoot, revision, rankerItems, {
+    queryText: query,
+    targetPaths: []
+  });
+  const ranked = rankDescriptionItems(rankerItems, scoringContext, "triage");
+  const items = [];
+  for (const { item } of ranked) {
+    const match = matchedByKey.get(item.stable_id);
+    if (match === void 0) continue;
+    const { indexed, source, type } = match;
+    const { absolutePath, fm, layer, maturity } = indexed;
+    const reportedPath = source.isStore ? absolutePath : source.isPersonal ? `~/${relative(resolvePersonalRoot(), absolutePath)}` : relative(projectRoot, absolutePath);
+    items.push({
+      area: source.isPending ? "pending" : "canonical",
+      path: reportedPath,
+      ...source.isPersonal ? { path_absolute: absolutePath } : {},
+      type,
+      layer,
+      maturity,
+      // Only pending entries carry an origin tag (canonical hits live
+      // outside the dual-pending-root convention).
+      ...source.isPending ? { origin: source.isPersonal ? "personal" : "team" } : {},
+      ...fm.tags !== void 0 && fm.tags.length > 0 ? { tags: fm.tags } : {},
+      ...fm.title !== void 0 ? { title: fm.title } : {},
+      ...fm.summary !== void 0 ? { summary: fm.summary } : {},
+      ...fm.status !== void 0 ? { status: fm.status } : {},
+      ...fm.deferred_until !== void 0 ? { deferred_until: fm.deferred_until } : {},
+      // v2.0.0-rc.27 TASK-006 (audit §2.23): body emission when opted in.
+      ...includeBody ? { body: indexed.body } : {},
+      // Canonical hits always have an id; pending hits typically don't yet —
+      // surface the frontmatter id when present so consumers can dedupe.
+      ...fm.id !== void 0 ? { stable_id: fm.id } : {}
+    });
+  }
   return items;
 }
 async function deferAll(projectRoot, pendingPaths, until, reason) {
@@ -4576,7 +4863,7 @@ async function deferAll(projectRoot, pendingPaths, until, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile6(sandboxed.abs, "utf8");
+        const content = await readFile7(sandboxed.abs, "utf8");
         stableId = parseFrontmatter(content).id;
         const patch = {
           status: "deferred",
@@ -4917,9 +5204,9 @@ function registerPending(server, tracker) {
 }
 
 // src/services/doctor.ts
-import { access as access4, readFile as readFile16, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
+import { access as access4, readFile as readFile17, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile4 } from "fs/promises";
 import { constants as constants2 } from "fs";
-import { isAbsolute as isAbsolute2, join as join21, posix as posix5, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute2, join as join23, posix as posix5, resolve as resolve3 } from "path";
 import {
   createTranslator,
   forensicReportSchema,
@@ -5133,13 +5420,13 @@ function createKnowledgeSummaryOpaqueCheck(t, inspection) {
 }
 
 // src/services/doctor-stable-id-collision.ts
-import { readFile as readFile7 } from "fs/promises";
-import { basename as basename2, join as join11 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { basename as basename2, join as join13 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput4,
   createStoreResolver as createStoreResolver4,
   readKnowledgeAcrossStores as readKnowledgeAcrossStores2,
-  resolveGlobalRoot as resolveGlobalRoot3,
+  resolveGlobalRoot as resolveGlobalRoot4,
   storeRelativePathForMount as storeRelativePathForMount3
 } from "@fenglimg/fabric-shared";
 var ID_LINE = /^id:\s*"?([^"\n]+?)"?\s*$/mu;
@@ -5155,13 +5442,13 @@ function resolveIntegrityStores(projectRoot) {
   const personalUuids = new Set(
     input.mountedStores.filter((s) => s.personal).map((s) => s.store_uuid)
   );
-  const globalRoot = resolveGlobalRoot3();
+  const globalRoot = resolveGlobalRoot4();
   const dirs = readSet.stores.map((entry) => {
     const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
     return {
       store_uuid: entry.store_uuid,
       alias: entry.alias,
-      dir: join11(globalRoot, storeRelativePathForMount3(mounted ?? { store_uuid: entry.store_uuid }))
+      dir: join13(globalRoot, storeRelativePathForMount3(mounted ?? { store_uuid: entry.store_uuid }))
     };
   });
   return { dirs, personalUuids };
@@ -5180,7 +5467,7 @@ async function inspectStoreStableIdIntegrity(projectRoot) {
   for (const ref of await readKnowledgeAcrossStores2(resolved.dirs)) {
     let source;
     try {
-      source = await readFile7(ref.file, "utf8");
+      source = await readFile8(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -5265,7 +5552,7 @@ function createLayerMismatchCheck(t, inspection) {
 // src/services/doctor-relevance-paths.ts
 import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync as existsSync6, readdirSync, statSync as statSync3 } from "fs";
-import { join as join12, sep as sep3 } from "path";
+import { join as join14, sep as sep3 } from "path";
 import { minimatch } from "minimatch";
 var MS_PER_DAY = 24 * 60 * 60 * 1e3;
 var RELEVANCE_PATHS_DRIFT_WINDOW_DAYS = 90;
@@ -5308,7 +5595,7 @@ function collectWorkspacePaths(projectRoot) {
       continue;
     }
     for (const entry of entries) {
-      const abs = join12(current, entry.name);
+      const abs = join14(current, entry.name);
       const rel = toPosix(abs.slice(projectRoot.length + 1));
       if (rel.length === 0) continue;
       if (entry.isDirectory()) {
@@ -5501,16 +5788,16 @@ function createNarrowNoPathsCheck(t, inspection) {
 }
 
 // src/services/doctor-broad-index.ts
-import { readFile as readFile8 } from "fs/promises";
-import { join as join13 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join15 } from "path";
 var DEFAULT_BROAD_INDEX_BACKSTOP = 50;
 var BROAD_INDEX_BACKSTOP_MIN = 20;
 var BROAD_INDEX_BACKSTOP_MAX = 500;
 var BROAD_INDEX_DRIFT_RATIO = 0.8;
 async function readBroadIndexBackstop(projectRoot) {
-  const configPath = join13(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join15(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile8(configPath, "utf8");
+    const raw = await readFile9(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.broad_index_backstop;
@@ -5827,15 +6114,15 @@ function createBroadReviewRecheckCheck(t, inspection) {
 }
 
 // src/services/doctor-scope-lint.ts
-import { readFile as readFile9 } from "fs/promises";
-import { join as join14 } from "path";
+import { readFile as readFile10 } from "fs/promises";
+import { join as join16 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput5,
   createStoreResolver as createStoreResolver5,
   isPersonalScope as isPersonalScope3,
   readKnowledgeAcrossStores as readKnowledgeAcrossStores3,
   readStoreProjects,
-  resolveGlobalRoot as resolveGlobalRoot4,
+  resolveGlobalRoot as resolveGlobalRoot5,
   scopeRoot as scopeRoot2,
   storeRelativePathForMount as storeRelativePathForMount4
 } from "@fenglimg/fabric-shared";
@@ -5860,10 +6147,10 @@ async function resolveLintStores(projectRoot) {
   const personalUuids = new Set(
     input.mountedStores.filter((s) => s.personal).map((s) => s.store_uuid)
   );
-  const globalRoot = resolveGlobalRoot4();
+  const globalRoot = resolveGlobalRoot5();
   return Promise.all(readSet.stores.map(async (entry) => {
     const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
-    const dir = join14(
+    const dir = join16(
       globalRoot,
       storeRelativePathForMount4(mounted ?? { store_uuid: entry.store_uuid })
     );
@@ -5895,7 +6182,7 @@ async function lintStoreScopes(projectRoot) {
     }
     let source;
     try {
-      source = await readFile9(ref.file, "utf8");
+      source = await readFile10(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -6018,7 +6305,7 @@ function createUnboundProjectCheck(t, violation) {
 
 // src/services/doctor-store-counters.ts
 import { existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
-import { join as join15 } from "path";
+import { join as join17 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput6,
   createStoreResolver as createStoreResolver6,
@@ -6027,7 +6314,7 @@ import {
   parseKnowledgeId as parseKnowledgeId2,
   readStoreCounters,
   reconcileStoreCounters,
-  resolveGlobalRoot as resolveGlobalRoot5,
+  resolveGlobalRoot as resolveGlobalRoot6,
   STORE_KNOWLEDGE_TYPE_DIRS,
   STORE_LAYOUT as STORE_LAYOUT2,
   storeRelativePathForMount as storeRelativePathForMount5
@@ -6041,11 +6328,11 @@ function resolveCounterStores(projectRoot) {
   if (readSet.stores.length === 0) {
     return [];
   }
-  const globalRoot = resolveGlobalRoot5();
+  const globalRoot = resolveGlobalRoot6();
   return readSet.stores.map((entry) => ({
     uuid: entry.store_uuid,
     alias: entry.alias,
-    dir: join15(
+    dir: join17(
       globalRoot,
       storeRelativePathForMount5(
         input.mountedStores.find((s) => s.store_uuid === entry.store_uuid) ?? {
@@ -6073,7 +6360,7 @@ function readEntryId(file) {
 function computeStoreDiskMax(storeDir) {
   const max = defaultAgentsMetaCounters();
   for (const type of STORE_KNOWLEDGE_TYPE_DIRS) {
-    const dir = join15(storeDir, STORE_LAYOUT2.knowledgeDir, type);
+    const dir = join17(storeDir, STORE_LAYOUT2.knowledgeDir, type);
     if (!existsSync7(dir)) {
       continue;
     }
@@ -6087,7 +6374,7 @@ function computeStoreDiskMax(storeDir) {
       if (!name.endsWith(".md")) {
         continue;
       }
-      const parsed = parseKnowledgeId2(readEntryId(join15(dir, name)) ?? "");
+      const parsed = parseKnowledgeId2(readEntryId(join17(dir, name)) ?? "");
       if (parsed === null) {
         continue;
       }
@@ -6170,14 +6457,14 @@ function createStoreCounterCheck(t, drifts) {
 
 // src/services/doctor-store-orphan.ts
 import { readdirSync as readdirSync3 } from "fs";
-import { join as join16 } from "path";
+import { join as join18 } from "path";
 import {
   STORES_ROOT_DIR,
   addMountedStore,
   disambiguateAlias,
   loadGlobalConfig,
   readStoreIdentity,
-  resolveGlobalRoot as resolveGlobalRoot6,
+  resolveGlobalRoot as resolveGlobalRoot7,
   saveGlobalConfig
 } from "@fenglimg/fabric-shared";
 var STORE_BY_ALIAS_DIR = "by-alias";
@@ -6188,21 +6475,21 @@ function listDir(dir) {
     return [];
   }
 }
-function inspectStoreOrphans(globalRoot = resolveGlobalRoot6()) {
+function inspectStoreOrphans(globalRoot = resolveGlobalRoot7()) {
   const config = loadGlobalConfig(globalRoot);
   if (config === null) {
     return [];
   }
   const registered = new Set(config.stores.map((s) => s.store_uuid));
-  const storesRoot = join16(globalRoot, STORES_ROOT_DIR);
+  const storesRoot = join18(globalRoot, STORES_ROOT_DIR);
   const orphans = [];
   for (const group of listDir(storesRoot)) {
     if (group === STORE_BY_ALIAS_DIR) {
       continue;
     }
-    const groupDir = join16(storesRoot, group);
+    const groupDir = join18(storesRoot, group);
     for (const mount of listDir(groupDir)) {
-      const dir = join16(groupDir, mount);
+      const dir = join18(groupDir, mount);
       const identity = readStoreIdentity(dir);
       if (identity === null || registered.has(identity.store_uuid)) {
         continue;
@@ -6212,7 +6499,7 @@ function inspectStoreOrphans(globalRoot = resolveGlobalRoot6()) {
   }
   return orphans;
 }
-function fixStoreOrphans(globalRoot = resolveGlobalRoot6()) {
+function fixStoreOrphans(globalRoot = resolveGlobalRoot7()) {
   let config = loadGlobalConfig(globalRoot);
   if (config === null) {
     return [];
@@ -6339,8 +6626,8 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
 }
 
 // src/services/doctor-skill-lints.ts
-import { readdir as readdir3, readFile as readFile10 } from "fs/promises";
-import { join as join17, posix as posix2 } from "path";
+import { readdir as readdir3, readFile as readFile11 } from "fs/promises";
+import { join as join19, 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;
@@ -6370,8 +6657,8 @@ async function listMarkdownFiles(dir) {
 async function inspectSkillRefMirror(projectRoot) {
   const driftedPaths = [];
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const claudeRef = join17(projectRoot, ".claude", "skills", slug, "ref");
-    const codexRef = join17(projectRoot, ".codex", "skills", slug, "ref");
+    const claudeRef = join19(projectRoot, ".claude", "skills", slug, "ref");
+    const codexRef = join19(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);
@@ -6388,8 +6675,8 @@ async function inspectSkillRefMirror(projectRoot) {
       let codexBody;
       try {
         [claudeBody, codexBody] = await Promise.all([
-          readFile10(join17(claudeRef, fname), "utf8"),
-          readFile10(join17(codexRef, fname), "utf8")
+          readFile11(join19(claudeRef, fname), "utf8"),
+          readFile11(join19(codexRef, fname), "utf8")
         ]);
       } catch {
         continue;
@@ -6408,10 +6695,10 @@ async function inspectSkillTokenBudget(projectRoot) {
   const overSize = [];
   let highestSeverity = "ok";
   for (const slug of FABRIC_SKILL_SLUGS) {
-    const skillMdPath = join17(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile10(skillMdPath, "utf8");
+      body = await readFile11(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6432,10 +6719,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 = join17(projectRoot, ".claude", "skills", slug, "SKILL.md");
+    const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile10(skillMdPath, "utf8");
+      body = await readFile11(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6466,7 +6753,7 @@ async function inspectSkillDescription(projectRoot) {
 async function inspectSkillMdYamlInvalid(projectRoot) {
   const candidates = [];
   for (const rootRel of SKILL_MD_FRONTMATTER_ROOTS) {
-    const rootAbs = join17(projectRoot, rootRel);
+    const rootAbs = join19(projectRoot, rootRel);
     let dirEntries;
     try {
       dirEntries = await readdir3(rootAbs, { withFileTypes: true });
@@ -6475,10 +6762,10 @@ async function inspectSkillMdYamlInvalid(projectRoot) {
     }
     for (const dirEntry of dirEntries) {
       if (!dirEntry.isDirectory()) continue;
-      const skillFile = join17(rootAbs, dirEntry.name, "SKILL.md");
+      const skillFile = join19(rootAbs, dirEntry.name, "SKILL.md");
       let raw;
       try {
-        raw = await readFile10(skillFile, "utf8");
+        raw = await readFile11(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -6601,8 +6888,8 @@ function createSkillMdYamlInvalidCheck(t, inspection) {
 }
 
 // src/services/doctor-retired-references-lint.ts
-import { readdir as readdir4, readFile as readFile11, stat as stat3 } from "fs/promises";
-import { join as join18, posix as posix3, relative as relative2 } from "path";
+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";
 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)" },
@@ -6625,7 +6912,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", join18(".fabric", "AGENTS.md")];
+var BOOTSTRAP_FILES = ["AGENTS.md", "CLAUDE.md", join20(".fabric", "AGENTS.md")];
 function isCommentLine(line) {
   const t = line.trim();
   return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
@@ -6639,7 +6926,7 @@ async function walkFiles(dir, exts) {
   }
   const out = [];
   for (const e of entries) {
-    const full = join18(dir, e.name);
+    const full = join20(dir, e.name);
     if (e.isDirectory()) {
       out.push(...await walkFiles(full, exts));
     } else if (exts.some((ext) => e.name.endsWith(ext))) {
@@ -6665,29 +6952,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 = join18(projectRoot, rel);
+    const abs = join20(projectRoot, rel);
     try {
       if ((await stat3(abs)).isFile()) {
         scannedFiles += 1;
-        scanText(toRel(abs), await readFile11(abs, "utf8"), false, hits);
+        scanText(toRel(abs), await readFile12(abs, "utf8"), false, hits);
       }
     } catch {
     }
   }
   for (const dir of SKILL_DIRS) {
-    for (const file of await walkFiles(join18(projectRoot, dir), [".md"])) {
+    for (const file of await walkFiles(join20(projectRoot, dir), [".md"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile11(file, "utf8"), false, hits);
+        scanText(toRel(file), await readFile12(file, "utf8"), false, hits);
       } catch {
       }
     }
   }
   for (const dir of HOOK_DIRS) {
-    for (const file of await walkFiles(join18(projectRoot, dir), [".cjs"])) {
+    for (const file of await walkFiles(join20(projectRoot, dir), [".cjs"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile11(file, "utf8"), true, hits);
+        scanText(toRel(file), await readFile12(file, "utf8"), true, hits);
       } catch {
       }
     }
@@ -6722,8 +7009,8 @@ function createRetiredReferenceCheck(t, inspection) {
 
 // src/services/doctor-hooks-lints.ts
 import { constants } from "fs";
-import { access, readdir as readdir5, readFile as readFile12, stat as stat4 } from "fs/promises";
-import { join as join19, posix as posix4 } from "path";
+import { access, readdir as readdir5, readFile as readFile13, stat as stat4 } from "fs/promises";
+import { join as join21, posix as posix4 } from "path";
 import { Script } from "vm";
 var HOOKS_RUNTIME_CLIENT_DIRS = [
   { client: "claude", dir: ".claude/hooks" },
@@ -6785,14 +7072,14 @@ async function isFile(absPath) {
   }
 }
 async function inspectHooksWired(projectRoot) {
-  const claudeEntries = await readDirectoryFileNames(join19(projectRoot, ".claude"));
+  const claudeEntries = await readDirectoryFileNames(join21(projectRoot, ".claude"));
   if (claudeEntries === null) {
     return { status: "skipped", missingHooks: [] };
   }
-  const settingsPath = join19(projectRoot, ".claude", "settings.json");
+  const settingsPath = join21(projectRoot, ".claude", "settings.json");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile12(settingsPath, "utf8"));
+    parsed = JSON.parse(await readFile13(settingsPath, "utf8"));
   } catch {
     return { status: "missing-settings", missingHooks: [] };
   }
@@ -6815,8 +7102,8 @@ async function inspectHooksWired(projectRoot) {
 }
 async function inspectHookCacheWritability(projectRoot) {
   const relPath = posix4.join(".fabric", ".cache");
-  const fabricDir = join19(projectRoot, ".fabric");
-  const cacheDir = join19(projectRoot, ".fabric", ".cache");
+  const fabricDir = join21(projectRoot, ".fabric");
+  const cacheDir = join21(projectRoot, ".fabric", ".cache");
   try {
     try {
       const cacheStats = await stat4(cacheDir);
@@ -6865,12 +7152,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 = join19(projectRoot, dir);
+    const absDir = join21(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join19(absDir, name);
+      const abs = join21(absDir, name);
       if (!await isFile(abs)) continue;
       const arr = hookFilesByBasename.get(name) ?? [];
       arr.push({ client, abs });
@@ -6885,7 +7172,7 @@ async function inspectHooksContentDrift(projectRoot) {
     const hashes = [];
     for (const { client, abs } of copies) {
       try {
-        const body = await readFile12(abs, "utf8");
+        const body = await readFile13(abs, "utf8");
         hashes.push({ client, sha: sha256(body) });
       } catch {
       }
@@ -6907,18 +7194,18 @@ async function inspectHooksRuntime(projectRoot) {
   const issues = [];
   let scanned = 0;
   for (const { client, dir } of HOOKS_RUNTIME_CLIENT_DIRS) {
-    const absDir = join19(projectRoot, dir);
+    const absDir = join21(projectRoot, dir);
     const entries = await readDirectoryFileNames(absDir);
     if (entries === null) continue;
     for (const name of entries) {
       if (!name.endsWith(".cjs")) continue;
-      const abs = join19(absDir, name);
+      const abs = join21(absDir, name);
       const displayPath = `${dir}/${name}`;
       if (!await isFile(abs)) continue;
       scanned += 1;
       let body;
       try {
-        body = await readFile12(abs, "utf8");
+        body = await readFile13(abs, "utf8");
       } catch (err) {
         issues.push({
           path: displayPath,
@@ -7055,8 +7342,8 @@ function createHookCacheWritabilityCheck(t, inspection) {
 }
 
 // src/services/doctor-bootstrap-lints.ts
-import { access as access2, readFile as readFile13 } from "fs/promises";
-import { join as join20 } from "path";
+import { access as access2, readFile as readFile14 } from "fs/promises";
+import { join as join22 } from "path";
 import {
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
@@ -7088,17 +7375,17 @@ async function fileExists(path) {
 }
 async function inspectBootstrapAnchor(projectRoot) {
   const [hasAgentsMd, hasClaudeMd] = await Promise.all([
-    fileExists(join20(projectRoot, "AGENTS.md")),
-    fileExists(join20(projectRoot, "CLAUDE.md"))
+    fileExists(join22(projectRoot, "AGENTS.md")),
+    fileExists(join22(projectRoot, "CLAUDE.md"))
   ]);
   return { hasAgentsMd, hasClaudeMd };
 }
 async function inspectL1BootstrapSnapshotDrift(target) {
-  const abs = join20(target, ".fabric", "AGENTS.md");
+  const abs = join22(target, ".fabric", "AGENTS.md");
   const canonical = resolveBootstrapCanonical();
   let onDisk;
   try {
-    onDisk = await readFile13(abs, "utf8");
+    onDisk = await readFile14(abs, "utf8");
   } catch {
     return { status: "missing", canonical, onDisk: null };
   }
@@ -7124,17 +7411,17 @@ function createL1BootstrapSnapshotDriftCheck(t, inspection) {
   );
 }
 async function inspectL2ManagedBlockDrift(target) {
-  const snapshotPath = join20(target, ".fabric", "AGENTS.md");
+  const snapshotPath = join22(target, ".fabric", "AGENTS.md");
   let snapshot;
   try {
-    snapshot = await readFile13(snapshotPath, "utf8");
+    snapshot = await readFile14(snapshotPath, "utf8");
   } catch {
     return { status: "ok", drifted: [] };
   }
-  const projectRulesPath = join20(target, ".fabric", "project-rules.md");
+  const projectRulesPath = join22(target, ".fabric", "project-rules.md");
   let expectedBody = snapshot;
   try {
-    const projectRules = await readFile13(projectRulesPath, "utf8");
+    const projectRules = await readFile14(projectRulesPath, "utf8");
     expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -7143,12 +7430,12 @@ ${projectRules}`;
   const drifted = [];
   let anyManagedBlockFound = false;
   const blockTargets = [
-    join20(target, "AGENTS.md")
+    join22(target, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     let content;
     try {
-      content = await readFile13(abs, "utf8");
+      content = await readFile14(abs, "utf8");
     } catch {
       continue;
     }
@@ -7171,9 +7458,9 @@ ${projectRules}`;
       drifted.push({ path: abs, expected: expectedBody, actual: body });
     }
   }
-  const claudeMdPath = join20(target, "CLAUDE.md");
+  const claudeMdPath = join22(target, "CLAUDE.md");
   try {
-    const claudeContent = await readFile13(claudeMdPath, "utf8");
+    const claudeContent = await readFile14(claudeMdPath, "utf8");
     anyManagedBlockFound = true;
     const lines = claudeContent.split(/\r?\n/u);
     const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
@@ -7241,7 +7528,7 @@ import { appendFile as appendFile3 } from "fs/promises";
 import { minimatch as minimatch2 } from "minimatch";
 
 // src/services/cite-rollup.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile15 } from "fs/promises";
 import { createLedgerWriteQueue as createLedgerWriteQueue3 } from "@fenglimg/fabric-shared/node/atomic-write";
 var citeRollupQueue = createLedgerWriteQueue3();
 async function appendCiteRollupRow(projectRoot, row) {
@@ -7253,7 +7540,7 @@ async function readCiteRollup(projectRoot) {
   const path = getCiteRollupPath(projectRoot);
   let raw;
   try {
-    raw = await readFile14(path, "utf8");
+    raw = await readFile15(path, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") return [];
     throw error;
@@ -8383,7 +8670,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(join21(projectRoot, path))])
+      TARGET_FILE_PATHS.map(async (path) => [path, await pathExists(join23(projectRoot, path))])
     )
   );
   const checks = [
@@ -8587,7 +8874,7 @@ async function runDoctorFix(target) {
   const fixed = [];
   const ledgerWarnings = [];
   if (before.fixable_errors.some((issue) => issue.code === "bootstrap_snapshot_drift")) {
-    const snapshotPath = join21(projectRoot, ".fabric", "AGENTS.md");
+    const snapshotPath = join23(projectRoot, ".fabric", "AGENTS.md");
     await ensureParentDirectory(snapshotPath);
     await atomicWriteText4(snapshotPath, resolveBootstrapCanonical2());
     fixed.push(findIssue(before.fixable_errors, "bootstrap_snapshot_drift"));
@@ -8660,7 +8947,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 = join21(projectRoot, ".fabric", ".serve.lock");
+      const lockFilePath = join23(projectRoot, ".fabric", ".serve.lock");
       try {
         await unlink4(lockFilePath);
       } catch (err) {
@@ -8777,7 +9064,7 @@ function createApplyLintMessage(succeeded, failed, manualErrorCount) {
 }
 async function applySessionHintsStaleCleanup(projectRoot, candidate) {
   const detail = `deleted (${candidate.age_days}d old)`;
-  const absPath = join21(projectRoot, candidate.path);
+  const absPath = join23(projectRoot, candidate.path);
   try {
     const { unlink: unlink5 } = await import("fs/promises");
     await unlink5(absPath);
@@ -8802,9 +9089,9 @@ function truncateErrorMessage(error) {
   return raw.length > 240 ? `${raw.slice(0, 237)}...` : raw;
 }
 async function inspectForensic(projectRoot) {
-  const path = join21(projectRoot, ".fabric", "forensic.json");
+  const path = join23(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile16(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile17(path, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -8834,7 +9121,7 @@ async function inspectEventLedger(projectRoot) {
   try {
     await access4(path, constants2.W_OK);
     const { warnings } = await readEventLedger(projectRoot);
-    const raw = await readFile16(path, "utf8");
+    const raw = await readFile17(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 = [];
@@ -9379,7 +9666,7 @@ async function inspectPreexistingRootFiles(projectRoot) {
   const candidates = ["CLAUDE.md", "AGENTS.md"];
   const detected = [];
   for (const name of candidates) {
-    if (await pathExists(join21(projectRoot, name))) {
+    if (await pathExists(join23(projectRoot, name))) {
       detected.push(name);
     }
   }
@@ -9464,7 +9751,7 @@ async function buildLastActiveIndex(projectRoot) {
   return map;
 }
 async function inspectSessionHintsStale(projectRoot, now) {
-  const cacheDir = join21(projectRoot, ".fabric", ".cache");
+  const cacheDir = join23(projectRoot, ".fabric", ".cache");
   let entries;
   try {
     entries = await readdirAsync(cacheDir, { withFileTypes: true });
@@ -9476,7 +9763,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 = join21(cacheDir, entry.name);
+    const absPath = join23(cacheDir, entry.name);
     let mtimeMs = 0;
     try {
       mtimeMs = (await statAsync(absPath)).mtimeMs;
@@ -9508,9 +9795,9 @@ function inspectStaleServeLock(projectRoot, now) {
   };
 }
 async function readUnderseedThresholdFromConfig(projectRoot) {
-  const configPath = join21(projectRoot, ".fabric", "fabric-config.json");
+  const configPath = join23(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile16(configPath, "utf8");
+    const raw = await readFile17(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -9626,10 +9913,10 @@ async function inspectOnboardCoverage(projectRoot) {
   return { filled, missing, opted_out: optedOut };
 }
 async function readOnboardOptedOut(projectRoot) {
-  const path = join21(projectRoot, ".fabric", "fabric-config.json");
+  const path = join23(projectRoot, ".fabric", "fabric-config.json");
   let raw;
   try {
-    raw = await readFile16(path, "utf8");
+    raw = await readFile17(path, "utf8");
   } catch {
     return [];
   }
@@ -9731,22 +10018,22 @@ async function* iterateCanonicalFilenames(projectRoot) {
   }
 }
 async function rewriteThreeEndManagedBlocks(projectRoot) {
-  const snapshotPath = join21(projectRoot, ".fabric", "AGENTS.md");
+  const snapshotPath = join23(projectRoot, ".fabric", "AGENTS.md");
   if (!await pathExists(snapshotPath)) {
     return;
   }
   let snapshot;
   try {
-    snapshot = await readFile16(snapshotPath, "utf8");
+    snapshot = await readFile17(snapshotPath, "utf8");
   } catch {
     return;
   }
-  const projectRulesPath = join21(projectRoot, ".fabric", "project-rules.md");
+  const projectRulesPath = join23(projectRoot, ".fabric", "project-rules.md");
   const hasProjectRules = await pathExists(projectRulesPath);
   let expectedBody = snapshot;
   if (hasProjectRules) {
     try {
-      const projectRules = await readFile16(projectRulesPath, "utf8");
+      const projectRules = await readFile17(projectRulesPath, "utf8");
       expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -9757,7 +10044,7 @@ ${projectRules}`;
 ${expectedBody}
 ${BOOTSTRAP_MARKER_END2}`;
   const blockTargets = [
-    join21(projectRoot, "AGENTS.md")
+    join23(projectRoot, "AGENTS.md")
   ];
   for (const abs of blockTargets) {
     if (!await pathExists(abs)) {
@@ -9765,7 +10052,7 @@ ${BOOTSTRAP_MARKER_END2}`;
     }
     let existing;
     try {
-      existing = await readFile16(abs, "utf8");
+      existing = await readFile17(abs, "utf8");
     } catch {
       continue;
     }
@@ -9790,11 +10077,11 @@ ${managedBlock}
     }
     await atomicWriteText4(abs, next);
   }
-  const claudeMdPath = join21(projectRoot, "CLAUDE.md");
+  const claudeMdPath = join23(projectRoot, "CLAUDE.md");
   if (await pathExists(claudeMdPath)) {
     let claudeContent;
     try {
-      claudeContent = await readFile16(claudeMdPath, "utf8");
+      claudeContent = await readFile17(claudeMdPath, "utf8");
     } catch {
       return;
     }
@@ -9821,7 +10108,7 @@ ${managedBlock}
 async function ensureEventLedger(projectRoot) {
   const path = getEventLedgerPath(projectRoot);
   await ensureParentDirectory(path);
-  await writeFile3(path, "", { encoding: "utf8", flag: "a" });
+  await writeFile4(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"}.`;
@@ -9860,7 +10147,7 @@ async function collectEntryPoints(root) {
       continue;
     }
     for (const entry of await readdirAsync(current, { withFileTypes: true })) {
-      const absolutePath = join21(current, entry.name);
+      const absolutePath = join23(current, entry.name);
       const relativePath = normalizePath2(absolutePath.slice(root.length + 1));
       if (relativePath.length === 0) {
         continue;
@@ -9936,7 +10223,7 @@ async function enrichDescriptions(projectRoot, opts = {}) {
     scanned += 1;
     let source;
     try {
-      source = await readFile16(absPath, "utf8");
+      source = await readFile17(absPath, "utf8");
     } catch {
       continue;
     }
@@ -10074,14 +10361,14 @@ async function runDoctorConflictLint(projectRoot, opts = {}) {
 }
 
 // src/services/why-not-surfaced.ts
-import { readFile as readFile17 } from "fs/promises";
-import { basename as basename3, join as join22 } from "path";
+import { readFile as readFile18 } from "fs/promises";
+import { basename as basename3, join as join24 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput7,
   createStoreResolver as createStoreResolver7,
   loadProjectConfig as loadProjectConfig4,
   readKnowledgeAcrossStores as readKnowledgeAcrossStores4,
-  resolveGlobalRoot as resolveGlobalRoot7,
+  resolveGlobalRoot as resolveGlobalRoot8,
   scopeRoot as scopeRoot3,
   storeRelativePathForMount as storeRelativePathForMount6
 } from "@fenglimg/fabric-shared";
@@ -10111,11 +10398,11 @@ async function explainWhyNotSurfaced(projectRoot, query) {
   if (input === null) {
     return base;
   }
-  const globalRoot = resolveGlobalRoot7();
+  const globalRoot = resolveGlobalRoot8();
   const allStores = input.mountedStores.map((s) => ({
     store_uuid: s.store_uuid,
     alias: s.alias,
-    dir: join22(globalRoot, storeRelativePathForMount6(s))
+    dir: join24(globalRoot, storeRelativePathForMount6(s))
   }));
   const refs = await readKnowledgeAcrossStores4(allStores);
   const candidate = refs.find((ref) => fileMatchesId(ref.file, localId));
@@ -10124,7 +10411,7 @@ async function explainWhyNotSurfaced(projectRoot, query) {
   }
   let source;
   try {
-    source = await readFile17(candidate.file, "utf8");
+    source = await readFile18(candidate.file, "utf8");
   } catch {
     return base;
   }
@@ -10212,7 +10499,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 readFile18, rm } from "fs/promises";
+import { access as access5, copyFile, readFile as readFile19, rm } from "fs/promises";
 import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
 async function resolveLedgerPaths(projectRoot) {
   const primaryPath = getLedgerPath(projectRoot);
@@ -10240,7 +10527,7 @@ async function readLegacyLedger(projectRoot) {
   const { readPath } = await resolveLedgerPaths(projectRoot);
   let raw;
   try {
-    raw = await readFile18(readPath, "utf8");
+    raw = await readFile19(readPath, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return [];
@@ -10495,8 +10782,8 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync9(join23(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync9(join23(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync9(join25(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync9(join25(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.`;
 }
@@ -10523,7 +10810,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.3.0-rc.1"
+      version: "2.3.0-rc.3"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -10543,10 +10830,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path = join23(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join25(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
       if (existsSync9(path)) {
-        text = await readFile19(path, "utf8");
+        text = await readFile20(path, "utf8");
       }
       return {
         contents: [
@@ -10644,6 +10931,7 @@ export {
   LEGACY_LEDGER_PATH,
   METRICS_LEDGER_PATH,
   METRIC_COUNTER_NAMES,
+  OPTIONAL_EMBED_PACKAGE,
   RETIRED_TOKENS,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
@@ -10654,6 +10942,7 @@ export {
   createFabricServer,
   createInFlightTracker,
   createShutdownHandler,
+  defaultEmbedCacheDir,
   detectUnboundProject,
   drainCounters,
   enrichDescriptions,
@@ -10670,9 +10959,12 @@ export {
   inspectRetiredReferences,
   lintConflicts,
   loadConflictEntries,
+  loadEmbedder,
   pairSimilarity,
   planContext,
+  readEmbedConfig,
   readEventLedger,
+  readFusion,
   readLedger,
   readMetrics,
   readSelectionToken,