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

package/dist/{chunk-F46ORPOA.js → chunk-XHHCRDIR.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   deepMerge
-} from "./chunk-MF3OTILQ.js";
+} from "./chunk-XC5RUHLK.js";
 
 // src/install/write-bootstrap-snapshot.ts
 import { existsSync, readFileSync } from "fs";
@@ -55,10 +55,15 @@ var SKILL_TEMPLATE_REL = "skills/fabric-archive/SKILL.md";
 var SKILL_REVIEW_TEMPLATE_REL = "skills/fabric-review/SKILL.md";
 var SKILL_IMPORT_TEMPLATE_REL = "skills/fabric-import/SKILL.md";
 var SKILL_SYNC_TEMPLATE_REL = "skills/fabric-sync/SKILL.md";
+var SKILL_STORE_TEMPLATE_REL = "skills/fabric-store/SKILL.md";
+var SKILL_AUDIT_TEMPLATE_REL = "skills/fabric-audit/SKILL.md";
+var SKILL_CONNECT_TEMPLATE_REL = "skills/fabric-connect/SKILL.md";
 var HOOK_SCRIPT_TEMPLATE_REL = "hooks/fabric-hint.cjs";
 var HOOK_BROAD_SCRIPT_TEMPLATE_REL = "hooks/knowledge-hint-broad.cjs";
 var HOOK_NARROW_SCRIPT_TEMPLATE_REL = "hooks/knowledge-hint-narrow.cjs";
 var HOOK_CITE_EVICT_SCRIPT_TEMPLATE_REL = "hooks/cite-policy-evict.cjs";
+var HOOK_SESSION_END_SCRIPT_TEMPLATE_REL = "hooks/session-end-marker.cjs";
+var HOOK_POST_TOOLUSE_SCRIPT_TEMPLATE_REL = "hooks/post-tooluse-mutation.cjs";
 var HOOK_LIB_TEMPLATE_DIR_REL = "hooks/lib";
 var CLAUDE_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/claude-code.json";
 var CODEX_HOOK_CONFIG_TEMPLATE_REL = "hooks/configs/codex-hooks.json";
@@ -81,6 +86,23 @@ var SKILL_DESTINATIONS = {
   fabricSync: [
     ".claude/skills/fabric-sync/SKILL.md",
     ".codex/skills/fabric-sync/SKILL.md"
+  ],
+  // v2.1 ADJ-NEWN-1/#4: fabric-store knowledge-store ops skill, same 2-client
+  // coverage as the sibling skills.
+  fabricStore: [
+    ".claude/skills/fabric-store/SKILL.md",
+    ".codex/skills/fabric-store/SKILL.md"
+  ],
+  // v2.2 SK1-audit (W2-T5): fabric-audit semantic-deprecation skill, same
+  // 2-client coverage as the sibling skills.
+  fabricAudit: [
+    ".claude/skills/fabric-audit/SKILL.md",
+    ".codex/skills/fabric-audit/SKILL.md"
+  ],
+  // v2.2 SK2-connect (W3-T2): fabric-connect knowledge-graph relation skill.
+  fabricConnect: [
+    ".claude/skills/fabric-connect/SKILL.md",
+    ".codex/skills/fabric-connect/SKILL.md"
   ]
 };
 var DEPRECATED_SKILL_DIRS = [
@@ -115,6 +137,18 @@ var HOOK_SCRIPT_DESTINATIONS = {
     ".claude/hooks/cite-policy-evict.cjs",
     ".codex/hooks/cite-policy-evict.cjs",
     ".cursor/hooks/cite-policy-evict.cjs"
+  ],
+  // lifecycle-refactor W2-T2: SessionEnd marker hook — all three clients.
+  sessionEndMarker: [
+    ".claude/hooks/session-end-marker.cjs",
+    ".codex/hooks/session-end-marker.cjs",
+    ".cursor/hooks/session-end-marker.cjs"
+  ],
+  // lifecycle-refactor W2-T3: PostToolUse mutation marker hook — all three.
+  postTooluseMutation: [
+    ".claude/hooks/post-tooluse-mutation.cjs",
+    ".codex/hooks/post-tooluse-mutation.cjs",
+    ".cursor/hooks/post-tooluse-mutation.cjs"
   ]
 };
 var HOOK_LIB_DESTINATIONS = [
@@ -128,25 +162,51 @@ var HOOK_CONFIG_TARGETS = {
   cursor: ".cursor/hooks.json"
 };
 var HOOK_CONFIG_ARRAY_PATHS = {
-  claudeCode: ["hooks.Stop", "hooks.SessionStart", "hooks.PreToolUse"],
-  codex: ["events.Stop", "events.SessionStart", "events.PreToolUse"],
-  cursor: ["hooks.stop", "hooks.sessionStart", "hooks.preToolUse"]
+  // F2: "hooks.UserPromptSubmit" MUST be listed — the Claude Code template
+  // ships a UserPromptSubmit cite-policy hook, so without this path deepMerge
+  // array-REPLACEs (instead of append-with-dedupe) on re-install, silently
+  // clobbering any user-defined UserPromptSubmit hook.
+  // lifecycle-refactor W2-T2/T3: PostToolUse + SessionEnd arrays added so
+  // deepMerge append-with-dedupes them on re-install (omitting them would
+  // array-REPLACE, clobbering any user-defined entries in those slots).
+  claudeCode: [
+    "hooks.Stop",
+    "hooks.SessionStart",
+    "hooks.PreToolUse",
+    "hooks.UserPromptSubmit",
+    "hooks.PostToolUse",
+    "hooks.SessionEnd"
+  ],
+  codex: ["events.Stop", "events.SessionStart", "events.PreToolUse", "events.PostToolUse", "events.SessionEnd"],
+  cursor: ["hooks.stop", "hooks.sessionStart", "hooks.preToolUse", "hooks.postToolUse", "hooks.sessionEnd"]
 };
 var FABRIC_HOOK_COMMAND_PATHS = {
   claudeCode: {
     fabricHint: "${CLAUDE_PROJECT_DIR}/.claude/hooks/fabric-hint.cjs",
     knowledgeHintBroad: "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-broad.cjs",
-    knowledgeHintNarrow: "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-narrow.cjs"
+    knowledgeHintNarrow: "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-narrow.cjs",
+    // F3: the UserPromptSubmit cite-policy-evict hook must be a known fabric
+    // command so uninstall prunes it (matches the literal in claude-code.json).
+    citePolicyEvict: "${CLAUDE_PROJECT_DIR}/.claude/hooks/cite-policy-evict.cjs",
+    // lifecycle-refactor W2-T2/T3: SessionEnd + PostToolUse marker hooks.
+    sessionEndMarker: "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-end-marker.cjs",
+    postTooluseMutation: "${CLAUDE_PROJECT_DIR}/.claude/hooks/post-tooluse-mutation.cjs"
   },
   codex: {
     fabricHint: '"$(git rev-parse --show-toplevel)/.codex/hooks/fabric-hint.cjs"',
     knowledgeHintBroad: '"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-broad.cjs"',
-    knowledgeHintNarrow: '"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-narrow.cjs"'
+    knowledgeHintNarrow: '"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-narrow.cjs"',
+    citePolicyEvict: '"$(git rev-parse --show-toplevel)/.codex/hooks/cite-policy-evict.cjs"',
+    sessionEndMarker: '"$(git rev-parse --show-toplevel)/.codex/hooks/session-end-marker.cjs"',
+    postTooluseMutation: '"$(git rev-parse --show-toplevel)/.codex/hooks/post-tooluse-mutation.cjs"'
   },
   cursor: {
     fabricHint: ".cursor/hooks/fabric-hint.cjs",
     knowledgeHintBroad: ".cursor/hooks/knowledge-hint-broad.cjs",
-    knowledgeHintNarrow: ".cursor/hooks/knowledge-hint-narrow.cjs"
+    knowledgeHintNarrow: ".cursor/hooks/knowledge-hint-narrow.cjs",
+    citePolicyEvict: ".cursor/hooks/cite-policy-evict.cjs",
+    sessionEndMarker: ".cursor/hooks/session-end-marker.cjs",
+    postTooluseMutation: ".cursor/hooks/post-tooluse-mutation.cjs"
   }
 };
 function readFabricLanguagePreference(projectRoot) {
@@ -257,6 +317,51 @@ async function installFabricSyncSkill(projectRoot, _options = {}) {
   }
   return results;
 }
+async function installFabricStoreSkill(projectRoot, _options = {}) {
+  const source = await readTemplate(SKILL_STORE_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-store");
+  const targets = SKILL_DESTINATIONS.fabricStore.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill-store", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
+  }
+  return results;
+}
+async function installFabricAuditSkill(projectRoot, _options = {}) {
+  const source = await readTemplate(SKILL_AUDIT_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-audit");
+  const targets = SKILL_DESTINATIONS.fabricAudit.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill-audit", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
+  }
+  return results;
+}
+async function installFabricConnectSkill(projectRoot, _options = {}) {
+  const source = await readTemplate(SKILL_CONNECT_TEMPLATE_REL);
+  validateSkillCanonicalSize(source, "fabric-connect");
+  const targets = SKILL_DESTINATIONS.fabricConnect.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const staleMsg = inspectStaleInstall(target, source);
+    const result = await copyTextIdempotent("skill-connect", source, target);
+    if (staleMsg && result.status === "written") {
+      result.message = result.message ? `${staleMsg}; ${result.message}` : staleMsg;
+    }
+    results.push(result);
+  }
+  return results;
+}
 async function cleanupDeprecatedSkills(projectRoot) {
   const results = [];
   for (const rel of DEPRECATED_SKILL_DIRS) {
@@ -443,6 +548,38 @@ async function installCitePolicyEvictHook(projectRoot, _options = {}) {
   }
   return results;
 }
+async function installSessionEndMarkerHook(projectRoot, _options = {}) {
+  const source = await readTemplate(HOOK_SESSION_END_SCRIPT_TEMPLATE_REL);
+  const targets = HOOK_SCRIPT_DESTINATIONS.sessionEndMarker.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const result = await copyTextIdempotent("hook-session-end-script", source, target);
+    if (result.status === "written" && process.platform !== "win32") {
+      try {
+        chmodSync(target, 493);
+      } catch {
+      }
+    }
+    results.push(result);
+  }
+  return results;
+}
+async function installPostTooluseMutationHook(projectRoot, _options = {}) {
+  const source = await readTemplate(HOOK_POST_TOOLUSE_SCRIPT_TEMPLATE_REL);
+  const targets = HOOK_SCRIPT_DESTINATIONS.postTooluseMutation.map((rel) => join2(projectRoot, rel));
+  const results = [];
+  for (const target of targets) {
+    const result = await copyTextIdempotent("hook-post-tooluse-script", source, target);
+    if (result.status === "written" && process.platform !== "win32") {
+      try {
+        chmodSync(target, 493);
+      } catch {
+      }
+    }
+    results.push(result);
+  }
+  return results;
+}
 async function installHookLibs(projectRoot, _options = {}) {
   const libTemplateDir = findTemplatePath(HOOK_LIB_TEMPLATE_DIR_REL);
   let libFiles;
@@ -887,12 +1024,17 @@ export {
   installFabricReviewSkill,
   installFabricImportSkill,
   installFabricSyncSkill,
+  installFabricStoreSkill,
+  installFabricAuditSkill,
+  installFabricConnectSkill,
   cleanupDeprecatedSkills,
   installSharedSkillLib,
   installArchiveHintHook,
   installKnowledgeHintBroadHook,
   installKnowledgeHintNarrowHook,
   installCitePolicyEvictHook,
+  installSessionEndMarkerHook,
+  installPostTooluseMutationHook,
   installHookLibs,
   mergeClaudeCodeHookConfig,
   mergeCodexHookConfig,

package/dist/{config-XJIPZNUP.js → config-VJMXCLXW.js}

@@ -3,9 +3,9 @@ import {
   configCmd,
   config_default,
   installMcpClients
-} from "./chunk-BATF4PEJ.js";
-import "./chunk-MF3OTILQ.js";
-import "./chunk-PWLW3B57.js";
+} from "./chunk-F6ITRM7T.js";
+import "./chunk-XC5RUHLK.js";
+import "./chunk-2CY4BMTH.js";
 export {
   configCmd,
   config_default as default,

package/dist/{doctor-QVNPHLJK.js → doctor-J4O3X54I.js}

@@ -2,24 +2,25 @@
 import {
   paint,
   symbol
-} from "./chunk-WWNXR34K.js";
+} from "./chunk-BO4XIZWZ.js";
 import {
   resolveDevMode
 } from "./chunk-COI5VDFU.js";
 import {
   getDoctorTranslator,
   t
-} from "./chunk-PWLW3B57.js";
+} from "./chunk-2CY4BMTH.js";
 import {
-  missingRequiredStores
-} from "./chunk-HFQVXY6P.js";
-import {
-  loadProjectConfig
-} from "./chunk-LFIKMVY7.js";
+  detectAliasLinkDrift,
+  missingRequiredStores,
+  syncStoreAliasLinks,
+  unboundAvailableStores
+} from "./chunk-5ZUMLCD5.js";
 import {
   loadGlobalConfig,
+  loadProjectConfig,
   resolveGlobalRoot
-} from "./chunk-RYAFBNES.js";
+} from "./chunk-XCBVSGCS.js";
 
 // src/commands/doctor.ts
 import { confirm, isCancel } from "@clack/prompts";
@@ -32,7 +33,8 @@ import {
   runDoctorCiteCoverage,
   runDoctorFix,
   runDoctorHistoryAll,
-  runDoctorReport
+  runDoctorReport,
+  runDoctorConflictLint
 } from "@fenglimg/fabric-server";
 
 // src/store/doctor-checks.ts
@@ -57,6 +59,23 @@ function storeDoctorChecks(projectRoot, globalRoot = resolveGlobalRoot()) {
       message: `required store '${missing.id}' is not mounted; run \`fabric store add\``
     });
   }
+  for (const store of unboundAvailableStores(projectRoot, globalRoot)) {
+    diagnostics.push({
+      code: "unbound_available_store",
+      severity: "info",
+      ref: store.alias,
+      message: `store '${store.alias}' is mounted but not bound to this project; run \`fabric store bind ${store.alias}\` to read its knowledge here (then \`fabric store switch-write ${store.alias}\` to write team knowledge into it)`
+    });
+  }
+  const aliasDrift = detectAliasLinkDrift(globalRoot);
+  if (aliasDrift.length > 0) {
+    diagnostics.push({
+      code: "store_alias_link_drift",
+      severity: "info",
+      ref: aliasDrift.join(", "),
+      message: `by-alias readability link(s) out of sync for ${aliasDrift.join(", ")}; run \`fabric doctor --fix\` to repair ~/.fabric/stores/by-alias/`
+    });
+  }
   for (const store of global.stores) {
     if (store.remote === void 0 && store.personal !== true) {
       diagnostics.push({
@@ -208,6 +227,17 @@ var doctorCommand = defineCommand({
       type: "string",
       description: t("cli.doctor.args.history.description"),
       valueHint: "archive|fix|all"
+    },
+    // v2.1 ④ conflict-detection (P4): knowledge-conflict lint surface.
+    "lint-conflicts": {
+      type: "boolean",
+      description: t("cli.doctor.args.lint-conflicts.description"),
+      default: false
+    },
+    deep: {
+      type: "boolean",
+      description: t("cli.doctor.args.deep.description"),
+      default: false
     }
   },
   async run({ args }) {
@@ -362,6 +392,22 @@ var doctorCommand = defineCommand({
       renderCiteCoverageReport(report2, args.json === true, dt);
       return;
     }
+    if (args["lint-conflicts"] === true) {
+      if (fix || fixKnowledge || citeCoverage) {
+        writeStderr(dt("cli.doctor.errors.lint-conflicts-mutex"));
+        process.exitCode = 1;
+        return;
+      }
+      const report2 = await runDoctorConflictLint(resolution.target, {
+        deep: args.deep === true
+      });
+      if (args.json === true) {
+        writeStdout(JSON.stringify(report2, null, 2));
+      } else {
+        renderConflictLintReport(report2, args.deep === true, dt);
+      }
+      return;
+    }
     if (fixKnowledge && fix) {
       writeStderr(dt("cli.doctor.errors.fix-knowledge-fix-mutually-exclusive"));
       process.exitCode = 1;
@@ -373,29 +419,37 @@ var doctorCommand = defineCommand({
     if (fixKnowledge) {
       const preReport = await runDoctorReport(resolution.target);
       const plan = computeFixKnowledgePlan(preReport);
-      const yesFlag = args.yes === true;
-      const envBypass = process.env.FABRIC_NONINTERACTIVE === "1";
-      if (plan.totalCount === 0) {
+      if (args["dry-run"] === true) {
+        if (plan.totalCount > 0) {
+          renderFixKnowledgePlan(plan);
+        }
+        report = preReport;
       } else {
-        renderFixKnowledgePlan(plan);
-        const decision = await resolveFixKnowledgeConsent({
-          yesFlag,
-          envBypass,
-          plan
-        });
-        if (decision === "abort") {
-          process.exitCode = 1;
-          return;
+        const yesFlag = args.yes === true;
+        const envBypass = process.env.FABRIC_NONINTERACTIVE === "1";
+        if (plan.totalCount === 0) {
+        } else {
+          renderFixKnowledgePlan(plan);
+          const decision = await resolveFixKnowledgeConsent({
+            yesFlag,
+            envBypass,
+            plan
+          });
+          if (decision === "abort") {
+            process.exitCode = 1;
+            return;
+          }
         }
+        fixKnowledgeReport = await runDoctorFixKnowledge(resolution.target);
+        report = fixKnowledgeReport.report;
       }
-      fixKnowledgeReport = await runDoctorFixKnowledge(resolution.target);
-      report = fixKnowledgeReport.report;
     } else if (fix) {
       if (args["dry-run"] === true) {
         report = await runDoctorReport(resolution.target);
       } else {
         fixReport = await runDoctorFix(resolution.target);
         report = fixReport.report;
+        syncStoreAliasLinks();
       }
     } else {
       report = await runDoctorReport(resolution.target);
@@ -418,7 +472,7 @@ var doctorCommand = defineCommand({
         renderFixKnowledgeMutations(fixKnowledgeReport, dt);
       } else if (fixReport !== null) {
         writeStdout(fixReport.message);
-      } else if (fix && args["dry-run"] === true) {
+      } else if ((fix || fixKnowledge) && args["dry-run"] === true) {
         writeStdout(dt("cli.doctor.fix-dry-run-banner"));
       }
       renderHumanReport(report, dt, args.verbose === true);
@@ -447,7 +501,7 @@ var doctorCommand = defineCommand({
 var doctor_default = doctorCommand;
 function renderHumanReport(report, dt, verbose) {
   writeStdout(`${renderStatus(report.status)} ${paint.ai("fabric doctor")} ${paint.human(report.summary.target)}`);
-  renderTldrHeader(report);
+  renderTldrHeader(report, dt, verbose);
   for (const check of report.checks) {
     writeStdout(`${renderStatus(check.status)} ${check.name}: ${check.message}`);
   }
@@ -520,16 +574,16 @@ function writeIssueSection(title, issues, options) {
     }
   }
 }
-function renderTldrHeader(report) {
+function renderTldrHeader(report, dt, verbose) {
   const ranked = [];
   for (const issue of report.fixable_errors) {
-    ranked.push({ severity: "fixable", code: issue.code, message: issue.message });
+    ranked.push({ severity: "fixable", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
   }
   for (const issue of report.manual_errors) {
-    ranked.push({ severity: "manual", code: issue.code, message: issue.message });
+    ranked.push({ severity: "manual", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
   }
   for (const issue of report.warnings) {
-    ranked.push({ severity: "warn", code: issue.code, message: issue.message });
+    ranked.push({ severity: "warn", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
   }
   if (ranked.length === 0) {
     writeStdout(`${symbol.ok} TL;DR: all 48 checks green \u2014 nothing to fix.`);
@@ -543,6 +597,11 @@ function renderTldrHeader(report) {
     const marker = item.severity === "fixable" ? symbol.error : item.severity === "manual" ? symbol.error : symbol.warn;
     const truncated = item.message.length > 140 ? `${item.message.slice(0, 137)}...` : item.message;
     writeStdout(`  ${marker} ${item.code}: ${truncated}`);
+    if (item.actionHint !== void 0 && item.actionHint.length > 0) {
+      writeStdout(
+        item.audience === "maintainer" && !verbose ? `    \u2192 ${dt("doctor.maintainer-hint-folded")}` : `    \u2192 ${item.actionHint}`
+      );
+    }
   }
 }
 function renderStatus(status) {
@@ -689,10 +748,42 @@ function renderCiteCoverageReport(report, jsonMode, dt) {
   const complianceRate = report.metrics.cite_compliance_rate;
   const complianceStr = complianceRate === null || complianceRate === void 0 ? dt("doctor.cite.metric.complianceNA") : `${(complianceRate * 100).toFixed(1)}% (${report.metrics.compliant_cites ?? 0}/${(report.metrics.compliant_cites ?? 0) + (report.metrics.noncompliant_cites ?? 0)})`;
   lines.push(`  ${dt("doctor.cite.metric.complianceRate")}: ${complianceStr}`);
+  const recallRate = report.metrics.recall_coverage_rate;
+  const recallStr = recallRate === null || recallRate === void 0 ? dt("doctor.cite.metric.recallCoverageNA") : `${(recallRate * 100).toFixed(1)}% (${report.metrics.recall_backed_edits ?? 0}/${report.metrics.edits_touched})`;
+  lines.push(`  ${dt("doctor.cite.metric.recallCoverage")}: ${recallStr}`);
   const uncorrelatable = report.metrics.uncorrelatable_edits ?? 0;
   if (uncorrelatable > 0) {
     lines.push(`  ${dt("doctor.cite.metric.uncorrelatableEdits")}: ${uncorrelatable}`);
   }
+  if (report.metrics.exposed_and_mutated !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.exposedAndMutated")}: ${report.metrics.exposed_and_mutated.count}`
+    );
+  }
+  if (report.metrics.mutations_observed !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.mutationsObserved")}: ${report.metrics.mutations_observed.count}`
+    );
+  }
+  if (report.metrics.mutation_pool !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.mutationPool")}: ${report.metrics.mutation_pool.attributed} / ${report.metrics.mutation_pool.unattributed_workspace_dirty} (attributed / unattributed_workspace_dirty)`
+    );
+  }
+  if (report.metrics.sessions_closed !== void 0) {
+    lines.push(
+      `  ${dt("doctor.cite.metric.sessionsClosed")}: ${report.metrics.sessions_closed.count}`
+    );
+  }
+  if (report.metrics.by_store !== void 0) {
+    const storeKeys = Object.keys(report.metrics.by_store).sort();
+    if (storeKeys.length > 0) {
+      lines.push(`  ${dt("doctor.cite.metric.byStore")}:`);
+      for (const store of storeKeys) {
+        lines.push(`    ${store}: ${report.metrics.by_store[store].qualifying_cites}`);
+      }
+    }
+  }
   if (report.per_client !== void 0 && Object.keys(report.per_client).length > 1) {
     lines.push("");
     lines.push(`### ${dt("doctor.cite.section.perClient")}`);
@@ -794,6 +885,38 @@ function appendContractSection(lines, report, dt) {
     );
   }
 }
+function renderConflictLintReport(report, deepRequested, dt) {
+  const lines = [];
+  lines.push(dt("doctor.conflict.header"));
+  lines.push("");
+  if (report.candidate_count === 0) {
+    lines.push(`  ${symbol.ok} ${dt("doctor.conflict.none")}`);
+    writeStdout(lines.join("\n"));
+    return;
+  }
+  lines.push(
+    `  ${dt("doctor.conflict.summary", {
+      candidates: String(report.candidate_count),
+      conflicts: String(report.conflict_count),
+      threshold: report.threshold.toFixed(2)
+    })}`
+  );
+  if (deepRequested && !report.deep) {
+    lines.push(`  ${symbol.warn} ${dt("doctor.conflict.deep_no_judge")}`);
+  }
+  lines.push("");
+  for (const pair of report.pairs) {
+    const sym = pair.verdict === "conflict" ? symbol.error : symbol.warn;
+    const verdictLabel = dt(`doctor.conflict.verdict.${pair.verdict}`);
+    const pct = `${(pair.similarity * 100).toFixed(0)}%`;
+    let line = `  ${sym} [${pair.a} \u2194 ${pair.b}] (${pair.knowledge_type}/${pair.layer}) ${pct} \u2014 ${verdictLabel}`;
+    if (pair.rationale !== void 0 && pair.rationale.length > 0) {
+      line += `: ${pair.rationale}`;
+    }
+    lines.push(line);
+  }
+  writeStdout(lines.join("\n"));
+}
 function renderEnrichDescriptionsReport(report, dt) {
   const header = `${symbol.ok} ${paint.ai("fabric doctor --enrich-descriptions")} mode=${report.mode}${report.dryRun ? " (dry-run)" : ""} scanned=${report.scanned} modified=${report.modified} skipped=${report.skipped}`;
   writeStdout(header);
@@ -916,5 +1039,6 @@ function formatTimestampForTable(iso) {
 export {
   doctor_default as default,
   doctorCommand,
-  parseSinceDuration
+  parseSinceDuration,
+  renderTldrHeader
 };

package/dist/index.js

@@ -1,47 +1,88 @@
 #!/usr/bin/env node
 import {
   t
-} from "./chunk-PWLW3B57.js";
+} from "./chunk-2CY4BMTH.js";
 
 // src/index.ts
 import { realpathSync } from "fs";
 import { resolve } from "path";
 import { fileURLToPath } from "url";
-import { defineCommand, runMain } from "citty";
+import { defineCommand, runCommand, runMain } from "citty";
 
 // src/commands/index.ts
 var allCommands = {
-  install: () => import("./install-2HDO5FTQ.js").then((module) => module.default),
+  install: () => import("./install-BULNDUIM.js").then((module) => module.default),
   // v2.1.0-rc.1 P3: multi-store lifecycle command group (list/add/remove/explain).
-  store: () => import("./store-XTSE5TY6.js").then((module) => module.default),
+  store: () => import("./store-66NK2FTQ.js").then((module) => module.default),
   // v2.1.0-rc.1 P3 (S9/S17/S37): multi-store pull --rebase + push, conflict resume.
-  sync: () => import("./sync-BJCWDPNC.js").then((module) => module.default),
+  sync: () => import("./sync-EA5HZMXM.js").then((module) => module.default),
   // v2.1.0-rc.1 P3 (F5): read-only identity/status info commands.
-  whoami: () => import("./whoami-B6AEMSEV.js").then((module) => module.default),
-  status: () => import("./status-GLQWLWH6.js").then((module) => module.default),
-  "scope-explain": () => import("./scope-explain-2F2R5URO.js").then((module) => module.default),
-  doctor: () => import("./doctor-QVNPHLJK.js").then((module) => module.default),
-  uninstall: () => import("./uninstall-TAXSUSKH.js").then((module) => module.default),
-  config: () => import("./config-XJIPZNUP.js").then((module) => module.default),
-  "plan-context-hint": () => import("./plan-context-hint-FC6P3WFE.js").then((module) => module.default),
+  whoami: () => import("./whoami-66YKY5DZ.js").then((module) => module.default),
+  status: () => import("./status-PANEGKU2.js").then((module) => module.default),
+  "scope-explain": () => import("./scope-explain-BWRWBCCP.js").then((module) => module.default),
+  doctor: () => import("./doctor-J4O3X54I.js").then((module) => module.default),
+  uninstall: () => import("./uninstall-F75MPKQC.js").then((module) => module.default),
+  config: () => import("./config-VJMXCLXW.js").then((module) => module.default),
+  "plan-context-hint": () => import("./plan-context-hint-CHVZGOZ5.js").then((module) => module.default),
   // v2.0.0-rc.23 TASK-014 (F8c): S5 onboard-slot coverage. Used by the
   // fabric-archive Skill's first-run phase to detect unclaimed slots.
-  "onboard-coverage": () => import("./onboard-coverage-MFCAEBDO.js").then((module) => module.default),
+  "onboard-coverage": () => import("./onboard-coverage-JWQWDZW7.js").then((module) => module.default),
   // v2.0.0-rc.37 NEW-34: text dashboard over .fabric/metrics.jsonl.
-  metrics: () => import("./metrics-ACEQFPDU.js").then((module) => module.default)
+  metrics: () => import("./metrics-RER6NLFC.js").then((module) => module.default)
 };
 
+// src/lib/error-render.ts
+function hasActionHint(err) {
+  if (err === null || typeof err !== "object") return false;
+  const candidate = err;
+  return typeof candidate.message === "string" && candidate.message.length > 0 && typeof candidate.actionHint === "string" && candidate.actionHint.length > 0;
+}
+function renderFabricError(err, stream = process.stderr) {
+  stream.write(`${err.message}
+`);
+  stream.write(`  -> ${err.actionHint}
+`);
+}
+function renderTopLevelError(err, stream = process.stderr) {
+  if (hasActionHint(err)) {
+    renderFabricError(err, stream);
+    return "fabric-error";
+  }
+  return "other";
+}
+
 // src/index.ts
 var main = defineCommand({
   meta: {
     name: "fabric",
-    version: "2.1.0-rc.2",
+    version: "2.2.0-rc.3",
     description: t("cli.main.description")
   },
   subCommands: allCommands
 });
 async function run() {
-  await runMain(main);
+  const rawArgs = process.argv.slice(2);
+  const wantsHelp = rawArgs.some((arg) => arg === "--help" || arg === "-h");
+  const wantsVersion = rawArgs.length === 1 && (rawArgs[0] === "--version" || rawArgs[0] === "-v");
+  if (wantsHelp || wantsVersion) {
+    await runMain(main, { rawArgs });
+    return;
+  }
+  try {
+    await runCommand(main, { rawArgs });
+  } catch (err) {
+    if (renderTopLevelError(err) === "fabric-error") {
+      process.exit(1);
+    }
+    const code = err !== null && typeof err === "object" ? err.code : void 0;
+    const isCittyUsageError = err instanceof Error && err.name === "CLIError" || typeof code === "string" && (code.startsWith("E_") || code.startsWith("EARG") || code === "EUSAGE");
+    if (isCittyUsageError) {
+      await runMain(main, { rawArgs });
+      return;
+    }
+    console.error(err, "\n");
+    process.exit(1);
+  }
 }
 var entrypoint = process.argv[1];
 var currentFilePath = fileURLToPath(import.meta.url);