@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.10

package/README.md

@@ -7,19 +7,22 @@
 1. 在 monorepo 根目录运行 `pnpm install`。
 2. 用 `pnpm --filter @fenglimg/fabric-cli build` 构建 CLI。
 3. 在目标项目运行 `fabric install`，完成一站式安装。
-4. 启动 `fabric serve`，再去客户端里验证 `fab_plan_context` 和 `fab_get_knowledge_sections`。
+4. 重启 Claude Code / Codex CLI，在客户端里验证 `fab_recall`。
 
-`fabric install` 会自动准备 bootstrap、MCP 配置和 git hooks。公共命令面只保留 `install`、`doctor`、`serve`、`uninstall`、`config`（rc.23 起移除了 baseline scan 机制，知识库唯一合法来源是 Skill 路径：`fabric-archive` / `fabric-import` / `fabric-review`）。
+`fabric install` 会自动准备 bootstrap、MCP stdio 配置和 git hooks。当前公共命令面包括 `install`、`store`、`sync`、`info`、`doctor`、`uninstall`、`config`；`metrics`、`plan-context-hint`、`onboard-coverage` 是 hidden/internal 命令；`whoami` / `status` / `scope-explain` 作为 deprecated alias 保留到 v3。`fabric serve` 已 quarantine 到 `packages/server-http-experimental/`，主线不再注册。
 
 ## 常用命令
 
 - `fabric install`
 - `fabric doctor`
 - `fabric doctor --json`
-- `fabric doctor --strict`
 - `fabric doctor --fix`
-- `fabric serve`
+- `fabric doctor --fix-knowledge`
+- `fabric store list`
+- `fabric sync`
+- `fabric info`
+- `fabric metrics`（hidden/internal）
 - `fabric uninstall`
 - `fabric config`（rc.16 起将提供配置面板；当前为占位提示）
 
-`fabric doctor --fix` 只修复确定性的派生状态，例如 `.fabric/agents.meta.json`、`.fabric/.cache/knowledge-test.index.json`、缺失的 `.fabric/events.jsonl` 和 stale hashes；语义冲突、缺失 rule section、未完成的初始化确认仍需要人工处理。
+`fabric doctor --fix` 只修复确定性的派生状态，例如 `.fabric/agents.meta.json`、`.fabric/.cache/knowledge-test.index.json`、缺失的 `.fabric/events.jsonl` 和 stale hashes。知识条目的 demote/archive/default backfill 走 `fabric doctor --fix-knowledge` 或 `fabric-review`；语义冲突、未完成的初始化确认和本地客户端配置问题仍需要人工处理。

package/dist/chunk-27HK6H5Y.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import {
+  storeGitRemote
+} from "./chunk-QPAW6IYT.js";
+import {
+  loadProjectConfig
+} from "./chunk-QFIVFZRH.js";
+import {
+  loadGlobalConfig,
+  resolveGlobalRoot
+} from "./chunk-FNHDQTPC.js";
+
+// src/lib/unknown-flags.ts
+function warnUnknownFlags(known) {
+  const knownSet = /* @__PURE__ */ new Set([...known, "help", "version"]);
+  const unknown = [];
+  for (const tok of process.argv.slice(2)) {
+    if (!tok.startsWith("--")) continue;
+    const name = tok.slice(2).split("=")[0].replace(/^no-/, "");
+    if (name.length === 0) continue;
+    if (!knownSet.has(name)) unknown.push(tok.split("=")[0]);
+  }
+  if (unknown.length > 0) {
+    process.stderr.write(`[fabric] ignored unknown flag(s): ${unknown.join(", ")}
+`);
+  }
+}
+
+// src/store/info-ops.ts
+function whoami(globalRoot = resolveGlobalRoot()) {
+  const config = loadGlobalConfig(globalRoot);
+  if (config === null) {
+    return null;
+  }
+  return {
+    uid: config.uid,
+    stores: config.stores.map((s) => ({
+      alias: s.alias,
+      mount_name: s.mount_name ?? null,
+      store_uuid: s.store_uuid,
+      // F4: parity with `fabric store list` — local-only reflects the store
+      // repo's TRUE git remote (what sync actually pushes to), not the registry
+      // metadata. A store with a physical `origin` but no registry `remote`
+      // (e.g. the personal store) was misreported as local-only by whoami while
+      // `store list` honestly showed its remote. Both now read the same source.
+      local_only: storeGitRemote(s.alias, globalRoot) === void 0
+    }))
+  };
+}
+function projectStatus(projectRoot, globalRoot = resolveGlobalRoot()) {
+  const global = loadGlobalConfig(globalRoot);
+  const project = loadProjectConfig(projectRoot);
+  return {
+    uid: global?.uid ?? null,
+    mounted: (global?.stores ?? []).map((s) => s.alias),
+    project_id: project?.project_id ?? null,
+    is_fabric_project: project !== null,
+    required: (project?.required_stores ?? []).map((r) => r.id),
+    active_write_store: project?.active_write_store ?? null,
+    default_write_store: project?.default_write_store ?? null,
+    write_routes: project?.write_routes ?? []
+  };
+}
+
+export {
+  warnUnknownFlags,
+  whoami,
+  projectStatus
+};

package/dist/{chunk-BATF4PEJ.js → chunk-2KBCTMID.js}

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
 import {
   resolveClients
-} from "./chunk-MF3OTILQ.js";
+} from "./chunk-3IOLS5EK.js";
+import {
+  loadGlobalConfig,
+  resolveGlobalRoot,
+  saveGlobalConfig
+} from "./chunk-FNHDQTPC.js";
 import {
   t
-} from "./chunk-PWLW3B57.js";
+} from "./chunk-HORSMSZL.js";
 
 // src/commands/config.ts
 import { existsSync, statSync } from "fs";
@@ -18,8 +23,9 @@ import {
 } from "@fenglimg/fabric-shared";
 import { atomicWriteJson } from "@fenglimg/fabric-shared/node/atomic-write";
 import { defineCommand } from "citty";
+var LANGUAGE_FIELD_KEY = "fabric_language";
 async function loadFabricConfig(workspaceRoot) {
-  const configPath = resolve(workspaceRoot, "fabric.config.json");
+  const configPath = resolve(workspaceRoot, ".fabric", "fabric-config.json");
   if (!existsSync(configPath)) {
     return {};
   }
@@ -178,8 +184,8 @@ var configCmd = defineCommand({
     "onboard-reset": onboardResetCmd
   },
   async run({ args }) {
-    const argvSub = process.argv[3];
-    if (argvSub === "dismiss-slot" || argvSub === "onboard-reset") {
+    const argvAfterConfig = process.argv.slice(3);
+    if (argvAfterConfig.includes("dismiss-slot") || argvAfterConfig.includes("onboard-reset")) {
       return;
     }
     const workspaceRoot = resolve(args.target ?? process.cwd());
@@ -201,6 +207,10 @@ var configCmd = defineCommand({
     let edited = false;
     while (true) {
       const current = await readPanelConfig(configPath);
+      const globalLanguage = loadGlobalConfig(resolveGlobalRoot())?.language;
+      if (globalLanguage !== void 0) {
+        current[LANGUAGE_FIELD_KEY] = globalLanguage;
+      }
       const fields = getPanelFields();
       const fieldChoice = await select({
         message: t("cli.config.menu.field-select"),
@@ -234,9 +244,22 @@ var configCmd = defineCommand({
         continue;
       }
       try {
-        const refreshed = await readPanelConfig(configPath);
-        const merged = { ...refreshed, [field.key]: newValue };
-        await atomicWriteJson(configPath, merged);
+        if (field.key === LANGUAGE_FIELD_KEY) {
+          const globalRoot = resolveGlobalRoot();
+          const globalConfig = loadGlobalConfig(globalRoot);
+          if (globalConfig === null) {
+            log.error(t("cli.config.errors.uninit-workspace.message"));
+            continue;
+          }
+          saveGlobalConfig(
+            { ...globalConfig, language: newValue },
+            globalRoot
+          );
+        } else {
+          const refreshed = await readPanelConfig(configPath);
+          const merged = { ...refreshed, [field.key]: newValue };
+          await atomicWriteJson(configPath, merged);
+        }
         edited = true;
         log.success(
           t("cli.config.write.success", {

package/dist/chunk-3D7B2UAZ.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import {
+  regenerateBindingsSnapshot
+} from "./chunk-PTGQAZEW.js";
+import {
+  storeBind,
+  storeProjectCreate,
+  storeProjectList,
+  storeSetWriteRoute,
+  storeSwitchWrite
+} from "./chunk-QPAW6IYT.js";
+import {
+  loadProjectConfig,
+  saveProjectConfig
+} from "./chunk-QFIVFZRH.js";
+
+// src/install/migrate-root-config.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var ROOT_AUTHORITATIVE_KEYS = /* @__PURE__ */ new Set([
+  "embed_enabled",
+  "embed_model",
+  "embed_weight",
+  "plan_context_top_k",
+  "recall_relevance_ratio",
+  "mcpPayloadLimits",
+  "selection_token_ttl_ms",
+  "orphan_demote_proven_days",
+  "orphan_demote_verified_days",
+  "orphan_demote_draft_days",
+  "clientPaths"
+]);
+function readJsonObject(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function migrateRootConfig(projectRoot) {
+  const rootPath = join(projectRoot, "fabric.config.json");
+  const fabricPath = join(projectRoot, ".fabric", "fabric-config.json");
+  const result = {
+    migrated: false,
+    mergedKeys: [],
+    rootPath,
+    fabricPath
+  };
+  const rootConfig = readJsonObject(rootPath);
+  if (rootConfig === null) {
+    if (existsSync(rootPath)) {
+      rmSync(rootPath, { force: true });
+      result.migrated = true;
+    }
+    return result;
+  }
+  const fabricConfig = readJsonObject(fabricPath) ?? {};
+  const merged = { ...fabricConfig };
+  const mergedKeys = [];
+  for (const [key, value] of Object.entries(rootConfig)) {
+    const fabricHasKey = Object.prototype.hasOwnProperty.call(merged, key);
+    if (ROOT_AUTHORITATIVE_KEYS.has(key) || !fabricHasKey) {
+      if (!fabricHasKey || merged[key] !== value) {
+        mergedKeys.push(key);
+      }
+      merged[key] = value;
+    }
+  }
+  mkdirSync(dirname(fabricPath), { recursive: true });
+  writeFileSync(fabricPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  rmSync(rootPath, { force: true });
+  result.migrated = true;
+  result.mergedKeys = mergedKeys;
+  return result;
+}
+
+// src/install/store-project-onboarding.ts
+import { execFileSync } from "child_process";
+import { randomUUID } from "crypto";
+import { basename } from "path";
+function ensureProjectId(projectRoot, uuid = randomUUID()) {
+  const config = loadProjectConfig(projectRoot) ?? {};
+  if (typeof config.project_id === "string" && config.project_id.length > 0) {
+    return config.project_id;
+  }
+  saveProjectConfig({ ...config, project_id: uuid }, projectRoot);
+  return uuid;
+}
+function suggestStoreProjectId(projectRoot) {
+  return normalizeStoreProjectId(readGitRemoteName(projectRoot) ?? basename(projectRoot));
+}
+function normalizeStoreProjectId(value) {
+  const normalized = value.trim().replace(/\.git$/iu, "").toLowerCase().replace(/[^a-z0-9_-]+/gu, "-").replace(/-+/gu, "-").replace(/^[-_]+|[-_]+$/gu, "");
+  return normalized.length > 0 ? normalized : "project";
+}
+async function ensureStoreProjectBinding(projectRoot, storeAlias, options) {
+  const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const project_id = ensureProjectId(projectRoot, options.uuid);
+  const currentConfig = loadProjectConfig(projectRoot);
+  const requested = options.requestedProjectId ?? currentConfig?.active_project ?? suggestStoreProjectId(projectRoot);
+  const active_project = normalizeStoreProjectId(requested);
+  const projects = await storeProjectList(storeAlias, options.globalRoot);
+  const project_created = !projects.some((project) => project.id === active_project);
+  if (project_created) {
+    await storeProjectCreate(storeAlias, active_project, now, {
+      name: active_project,
+      globalRoot: options.globalRoot
+    });
+  }
+  const entry = options.suggestedRemote === void 0 ? { id: storeAlias } : { id: storeAlias, suggested_remote: options.suggestedRemote };
+  await storeBind(projectRoot, entry, { project: active_project, globalRoot: options.globalRoot });
+  storeSwitchWrite(projectRoot, storeAlias, { globalRoot: options.globalRoot });
+  storeSetWriteRoute(projectRoot, `project:${active_project}`, storeAlias, {
+    globalRoot: options.globalRoot
+  });
+  regenerateBindingsSnapshot(projectRoot, {
+    now,
+    globalRoot: options.globalRoot
+  });
+  return { project_id, active_project, project_created };
+}
+function readGitRemoteName(projectRoot) {
+  try {
+    const remote = execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      cwd: projectRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (remote.length === 0) {
+      return null;
+    }
+    const lastSegment = remote.split(/[/:\\]/u).filter(Boolean).at(-1);
+    return lastSegment === void 0 ? null : lastSegment.replace(/\.git$/iu, "");
+  } catch {
+    return null;
+  }
+}
+
+export {
+  migrateRootConfig,
+  suggestStoreProjectId,
+  normalizeStoreProjectId,
+  ensureStoreProjectBinding
+};

package/dist/{chunk-MF3OTILQ.js → chunk-3IOLS5EK.js}

@@ -231,16 +231,6 @@ var ClaudeCodeCLIWriter = class extends JsonClientConfigWriter {
     return this.scope === "user" ? join(homedir(), ".claude.json") : join(workspaceRoot, ".mcp.json");
   }
 };
-var CursorWriter = class extends JsonClientConfigWriter {
-  clientKind = "Cursor";
-  constructor(configuredPath) {
-    super(configuredPath);
-  }
-  defaultPath(workspaceRoot) {
-    const cursorDir = join(workspaceRoot, ".cursor");
-    return existsSync(cursorDir) ? join(cursorDir, "mcp.json") : null;
-  }
-};
 
 // src/config/claude-code.ts
 function getClaudeDesktopConfigPath() {
@@ -307,7 +297,7 @@ function serializeTomlInlineTable(values) {
   const entries = Object.entries(values).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key} = ${escapeTomlString(value)}`);
   return `{ ${entries.join(", ")} }`;
 }
-function serializeCodexServerBlock(serverName, serverEntry) {
+function serializeCodexServerBlock(serverName, serverEntry, preservedUserLines = []) {
   const lines = [
     `[mcp_servers.${serverName}]`,
     `command = ${escapeTomlString(serverEntry.command)}`,
@@ -316,40 +306,53 @@ function serializeCodexServerBlock(serverName, serverEntry) {
   if (serverEntry.env !== void 0 && Object.keys(serverEntry.env).length > 0) {
     lines.push(`env = ${serializeTomlInlineTable(serverEntry.env)}`);
   }
+  lines.push(...preservedUserLines);
   return `${lines.join("\n")}
 `;
 }
+var CODEX_MANAGED_BLOCK_KEYS = /* @__PURE__ */ new Set(["command", "args", "env"]);
+function extractCodexBlockUserLines(blockText) {
+  const out = [];
+  const lines = blockText.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (/^\[/.test(trimmed)) continue;
+    const keyMatch = /^([A-Za-z0-9_-]+)\s*=/.exec(trimmed);
+    if (keyMatch !== null && CODEX_MANAGED_BLOCK_KEYS.has(keyMatch[1])) {
+      continue;
+    }
+    out.push(trimmed);
+  }
+  return out;
+}
 function trimTrailingBlankLines(value) {
   return value.replace(/\s+$/u, "");
 }
 function removeCodexServerBlock(rawConfig, serverName) {
   const normalized = rawConfig.replace(/\r\n/g, "\n");
   const escaped = serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const legacyPattern = new RegExp(
-    String.raw`\n?\[mcp\.servers\.${escaped}\]\n[\s\S]*?(?=\n\[[^\n]+\]\n|$)`,
-    "g"
-  );
   const currentPattern = new RegExp(
     String.raw`\n?\[mcp_servers\.${escaped}\]\n[\s\S]*?(?=\n\[[^\n]+\]\n|$)`,
     "g"
   );
-  const withoutLegacy = normalized.replace(legacyPattern, "");
-  const withoutCurrent = withoutLegacy.replace(currentPattern, "");
+  const withoutCurrent = normalized.replace(currentPattern, "");
   const changed = withoutCurrent !== normalized;
   const text = changed ? `${trimTrailingBlankLines(withoutCurrent)}
 ` : rawConfig;
   return { text, changed };
 }
 function upsertCodexServerBlock(rawConfig, serverName, serverEntry) {
-  const block = serializeCodexServerBlock(serverName, serverEntry);
   const normalized = rawConfig.replace(/\r\n/g, "\n");
-  const legacyPattern = new RegExp(String.raw`\n?\[mcp\.servers\.${serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\]\n[\s\S]*?(?=\n\[[^\n]+\]\n|$)`, "g");
+  const escaped = serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const currentPattern = new RegExp(
-    String.raw`\n?\[mcp_servers\.${serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\]\n[\s\S]*?(?=\n\[[^\n]+\]\n|$)`,
+    String.raw`\n?\[mcp_servers\.${escaped}\]\n[\s\S]*?(?=\n\[[^\n]+\]\n|$)`,
     "g"
   );
-  const withoutLegacy = normalized.replace(legacyPattern, "");
-  const withoutExisting = withoutLegacy.replace(currentPattern, "");
+  const existingMatch = normalized.match(currentPattern);
+  const preservedUserLines = existingMatch !== null && existingMatch.length > 0 ? extractCodexBlockUserLines(existingMatch[0]) : [];
+  const block = serializeCodexServerBlock(serverName, serverEntry, preservedUserLines);
+  const withoutExisting = normalized.replace(currentPattern, "");
   const trimmed = trimTrailingBlankLines(withoutExisting);
   if (trimmed.length === 0) {
     return block;
@@ -454,12 +457,6 @@ function resolveClients(workspaceRoot, fabricConfig = {}, opts = {}) {
     (configuredPath) => new ClaudeCodeDesktopWriter(configuredPath),
     hasExplicitPath(clientPaths, "claudeCodeDesktop") ? clientPaths.claudeCodeDesktop : void 0
   );
-  addIfDetected(
-    writers,
-    existsSync4(join4(workspaceRoot, ".cursor")),
-    (configuredPath) => new CursorWriter(configuredPath),
-    hasExplicitPath(clientPaths, "cursor") ? clientPaths.cursor : void 0
-  );
   addIfDetected(
     writers,
     existsSync4(join4(homedir4(), ".codex")),
@@ -472,7 +469,6 @@ function detectClientSupports(workspaceRoot, fabricConfig = {}) {
   const clientPaths = fabricConfig.clientPaths;
   const claudeDetected = existsSync4(join4(homedir4(), ".claude")) || existsSync4(join4(workspaceRoot, ".claude"));
   const claudeDesktopDetected = existsSync4(getClaudeDesktopConfigPath());
-  const cursorDetected = existsSync4(join4(workspaceRoot, ".cursor"));
   const codexDetected = existsSync4(join4(homedir4(), ".codex"));
   return [
     {
@@ -504,22 +500,35 @@ function detectClientSupports(workspaceRoot, fabricConfig = {}) {
       }
     },
     {
-      clientKind: "Cursor",
-      label: "Cursor",
-      detected: cursorDetected || hasExplicitPath(clientPaths, "cursor"),
-      configPath: ".cursor/mcp.json",
+      clientKind: "CodexCLI",
+      label: "Codex CLI",
+      detected: codexDetected || hasExplicitPath(clientPaths, "codexCLI"),
+      configPath: "~/.codex/config.toml",
       capabilities: {
         bootstrap: true,
         mcp: true,
-        hook: false,
-        skill: false
+        hook: true,
+        skill: true
+      },
+      installedCapabilities: {
+        hook: existsSync4(join4(workspaceRoot, ".codex", "hooks.json")),
+        // F6: the v2 skills (fabric-archive/review/import/…) DO install to
+        // `.codex/skills/` now, so probe that directory instead of the stale
+        // hardcoded `false` (which made `fabric install` always re-report Codex
+        // skills as uninstalled even right after installing them).
+        skill: existsSync4(join4(workspaceRoot, ".codex", "skills"))
       }
     },
     {
-      clientKind: "CodexCLI",
-      label: "Codex CLI",
+      clientKind: "CodexDesktop",
+      label: "Codex Desktop",
+      // Codex Desktop shares the same ~/.codex config as Codex CLI — there is no
+      // separate adapter work: installing the Codex CLI assets (MCP config /
+      // hooks / skills) makes Desktop ready too. Display-only row mirroring Codex
+      // CLI's detection + installed state; no dedicated writer (CodexTOMLConfigWriter
+      // already targets the shared config, so removing/adding it once covers both).
       detected: codexDetected || hasExplicitPath(clientPaths, "codexCLI"),
-      configPath: "~/.codex/config.toml",
+      configPath: "~/.codex/config.toml (shared with Codex CLI)",
       capabilities: {
         bootstrap: true,
         mcp: true,
@@ -528,10 +537,7 @@ function detectClientSupports(workspaceRoot, fabricConfig = {}) {
       },
       installedCapabilities: {
         hook: existsSync4(join4(workspaceRoot, ".codex", "hooks.json")),
-        // v2/rc.2: v1 client-side init skill removed; skill-installation probes
-        // will return once rc.2/3/4 introduce the v2 skills (fabric-archive,
-        // fabric-review, fabric-import). Until then there is nothing to probe.
-        skill: false
+        skill: existsSync4(join4(workspaceRoot, ".codex", "skills"))
       }
     }
   ];

package/dist/{plan-context-hint-FC6P3WFE.js → chunk-722JU5BP.js}

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import {
   resolveDevMode
-} from "./chunk-COI5VDFU.js";
+} from "./chunk-WA3DYGSY.js";
 
 // src/commands/plan-context-hint.ts
 import { defineCommand } from "citty";
-import { planContext } from "@fenglimg/fabric-server";
+import {
+  buildAlwaysActiveBodies,
+  buildKnowledgeCensus,
+  planContext
+} from "@fenglimg/fabric-server";
 var ALL_PATHS_SENTINEL = "**";
 var planContextHintCommand = defineCommand({
   meta: {
@@ -56,22 +60,49 @@ async function runPlanContextHint(opts) {
   const targetPaths = all ? [ALL_PATHS_SENTINEL] : explicitPaths.length > 0 ? explicitPaths : [ALL_PATHS_SENTINEL];
   const resolution = resolveDevMode(opts.target, process.cwd());
   const result = await planContext(resolution.target, {
-    paths: targetPaths
+    paths: targetPaths,
+    // lifecycle-refactor W3-T2 (§7 图谱消费 / §5): default-enable graph二阶召回 for
+    // the hint path. planContext appends the one-hop `related` neighbours that
+    // ranked outside top_k of the surfaced set and reports them in
+    // `related_appended` (appended id → source id). Honest no-op when the
+    // surfaced set declares no in-corpus related edge.
+    include_related: true
   });
   const candidates = result.candidates;
-  const entries = candidates.map((item) => ({
-    id: item.stable_id,
-    type: item.description.knowledge_type ?? "",
-    maturity: item.description.maturity ?? "",
-    summary: item.description.summary,
-    relevance_scope: item.description.relevance_scope ?? "broad"
-  }));
+  const relatedAppended = result.related_appended ?? {};
+  const entries = candidates.map((item) => {
+    const relatedTo = relatedAppended[item.stable_id];
+    return {
+      id: item.stable_id,
+      type: item.description.knowledge_type ?? "",
+      maturity: item.description.maturity ?? "",
+      summary: item.description.summary,
+      relevance_scope: item.description.relevance_scope ?? "broad",
+      // W2-2 (KT-DEC-0027): forward the must_read_if trigger hook for the
+      // SessionStart REFERENCE rendering. Omitted when absent/empty.
+      ...typeof item.description.must_read_if === "string" && item.description.must_read_if.length > 0 ? { must_read_if: item.description.must_read_if } : {},
+      // Only set when this entry was pulled in via a graph edge — its presence
+      // is the honest signal, never synthesized for ordinarily-ranked entries.
+      ...typeof relatedTo === "string" ? { related_to: relatedTo } : {}
+    };
+  });
   let narrow_count = 0;
   let broad_only_count = 0;
   for (const e of entries) {
     if (e.relevance_scope === "narrow") narrow_count += 1;
     else broad_only_count += 1;
   }
+  const alwaysBodies = await buildAlwaysActiveBodies(resolution.target).catch(() => []);
+  const census = await buildKnowledgeCensus(resolution.target).catch(
+    () => ({
+      by_type: {},
+      by_layer: { team: 0, personal: 0, project: 0 },
+      broad_by_type: {},
+      narrow_total: 0,
+      dropped_other_project: 0,
+      total: 0
+    })
+  );
   const output = {
     version: 2,
     revision_hash: result.revision_hash,
@@ -81,7 +112,15 @@ async function runPlanContextHint(opts) {
     // semantics unchanged from rc.18 (total candidate count).
     broad_count: candidates.length,
     narrow_count,
-    broad_only_count
+    broad_only_count,
+    always_bodies: alwaysBodies.map((b) => ({
+      id: b.stable_id,
+      type: b.type,
+      layer: b.layer,
+      summary: b.summary,
+      body: b.body
+    })),
+    census
   };
   if (result.auto_healed === true) {
     output.auto_healed = true;
@@ -97,8 +136,9 @@ function parsePathsArg(raw) {
   }
   return raw.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
 }
+
 export {
-  plan_context_hint_default as default,
   planContextHintCommand,
+  plan_context_hint_default,
   runPlanContextHint
 };