@fenglimg/fabric-shared 2.2.0 → 2.3.0-rc.10

package/dist/{chunk-2GLIAZ5M.js → chunk-ASS2KBB7.js}

@@ -151,11 +151,15 @@ var mountedStoreSchema = z.object({
   // Git remote locator for this clone, if any. Absent = local-only store
   // (valid; doctor nudges to add a remote for backup — R5#5, P6).
   remote: z.string().min(1).optional(),
-  // v2.1.0-rc.1 P3: marks the implicit personal store (the one minted by
-  // `install --global`). Exactly one mounted store carries personal=true; it
-  // is the write target for personal-scope entries (R5#3) and always in the
-  // read-set (S11). Optional (no default) so the output type stays a plain
-  // optional — consumers coalesce `?? false` when building resolver input.
+  // v2.1.0-rc.1 P3: marks a personal store (the kind minted by
+  // `install --global`). 语义 A (multi-personal): MULTIPLE mounted stores may
+  // carry personal=true — a machine can mount several personal stores and
+  // switch which is ACTIVE via globalConfig.active_personal_store. The ACTIVE
+  // personal is the write target for personal-scope entries (R5#3) and the one
+  // in the read-set (S11); non-active personal stores stay mounted but out of
+  // the read-set. Absent active pointer ⇒ resolver falls back to the first
+  // mounted personal (back-compat). Optional (no default) so the output type
+  // stays a plain optional — consumers coalesce `?? false`.
   personal: z.boolean().optional(),
   // Whether writes are accepted into this store from this machine. Optional;
   // consumers coalesce `?? true`. Shared stores cloned read-only set false.
@@ -174,15 +178,34 @@ var globalConfigSchema = z.object({
   // All stores mounted on this machine. The implicit personal store is
   // included here once initialized. Default empty so a fresh global config
   // (before `install --global`) parses cleanly.
-  stores: z.array(mountedStoreSchema).optional().default([])
+  stores: z.array(mountedStoreSchema).optional().default([]),
+  // 语义 A (multi-personal): alias/UUID of the ACTIVE personal store among the
+  // possibly-many `personal:true` stores in `stores[]`. Machine-wide (personal
+  // is uid-scoped identity, KT-DEC-0020) — switching it in any repo takes
+  // effect everywhere. Set by `fabric store switch-personal <alias>` and the
+  // install personal slot. Absent ⇒ the resolver falls back to the first
+  // mounted personal, so legacy single-personal configs are unchanged.
+  active_personal_store: z.string().min(1).optional()
 }).passthrough();
 
 // src/store/global-config-io.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+function isTestRuntime() {
+  return process.env.VITEST !== void 0 || process.env.VITEST_WORKER_ID !== void 0;
+}
 function resolveGlobalRoot() {
-  return join(process.env.FABRIC_HOME ?? homedir(), ".fabric");
+  const fabricHome = process.env.FABRIC_HOME;
+  if (fabricHome !== void 0 && fabricHome !== "") {
+    return join(fabricHome, ".fabric");
+  }
+  if (isTestRuntime()) {
+    throw new Error(
+      "resolveGlobalRoot(): FABRIC_HOME must be set under the test runner \u2014 refusing to fall back to the real home dir (~/.fabric). Repoint process.env.FABRIC_HOME to an isolated temp dir in beforeEach (see plan-context.test.ts for the pattern)."
+    );
+  }
+  return join(homedir(), ".fabric");
 }
 function globalConfigPath(globalRoot = resolveGlobalRoot()) {
   return join(globalRoot, "fabric-global.json");

package/dist/chunk-KFFBQRL5.js

@@ -0,0 +1,152 @@
+import {
+  resolveGlobalLocale
+} from "./chunk-ASS2KBB7.js";
+
+// src/templates/bootstrap-canonical.ts
+var BOOTSTRAP_MARKER_BEGIN = "<!-- fabric:bootstrap:begin -->";
+var BOOTSTRAP_MARKER_END = "<!-- fabric:bootstrap:end -->";
+var BOOTSTRAP_REGEX = /(?:\r?\n){0,2}<!-- fabric:bootstrap:begin -->[\s\S]*?<!-- fabric:bootstrap:end -->/;
+var BOOTSTRAP_CANONICAL_ZH = `# Fabric Bootstrap
+
+\u672C\u9879\u76EE\u4F7F\u7528 Fabric \u7BA1\u7406\u8DE8\u5BA2\u6237\u7AEF AI \u77E5\u8BC6\u4E0E\u884C\u4E3A\u89C4\u5219\u3002\u672C\u6587\u4EF6\u7531 \`fabric install\` \u540C\u6B65\u5230\u4E24\u7AEF managed block,**\u4E0D\u8981\u624B\u52A8\u7F16\u8F91\u4E24\u7AEF\u7684 block**,\u53EA\u6539\u8FD9\u91CC + \u91CD\u8DD1 \`fabric install\`\u3002
+
+## For Developers
+
+\u8FD9\u4E2A\u6587\u4EF6\u662F **AI \u5BA2\u6237\u7AEF\u7684\u7B56\u7565\u4E0E\u89C4\u7EA6\u914D\u7F6E**,\u4E0D\u662F dev onboarding\u3002\u4F60\u4E0D\u9700\u8981\u8BFB Self-archive / Cite / Phase 0.4 \u7B49\u7EC6\u8282\u3002
+\u4F5C\u4E3A dev \u4F60\u53EA\u9700\u8981:\u5728\u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 \`fabric install\`,\u7528 \`fabric store bind <alias>\` / \`fabric store switch-write <alias>\` \u63A5\u5165\u5199\u5165 store,\u51FA\u95EE\u9898\u8DD1 \`fabric doctor\`\u3002
+**\u4E25\u7981\u624B\u52A8\u7F16\u8F91 \`.fabric/agents.meta.json\`** \u2014 \u6D3E\u751F\u72B6\u6001\u7531 engine \u91CD\u5EFA\u3002
+
+## 5 \u5206\u949F\u4E0A\u624B (Dev Quickstart)
+
+**Fabric \u662F\u4EC0\u4E48**:\u8DE8\u5BA2\u6237\u7AEF(Claude Code / Codex CLI)\u7684 AI \u77E5\u8BC6\u5C42\u3002\u628A\u56E2\u961F/\u9879\u76EE\u7684 **decisions / pitfalls / guidelines / models / processes** \u5B58\u4E3A markdown,hook \u81EA\u52A8 surface \u7ED9 AI,\u8BA9 AI \u4E0D\u7528\u6BCF\u6B21\u91CD\u5B66\u3002
+
+**\u4F60\u8981\u505A\u7684 (DO)** vs **engine \u81EA\u52A8\u7684 (DON'T \u624B\u52A8)**:
+
+| \u4F60 DO | \u4F60 DON'T |
+| --- | --- |
+| \u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 \`fabric install\` | \u624B\u7F16 \`.fabric/agents.meta.json\` |
+| \u5F02\u5E38\u65F6\u8DD1 \`fabric doctor\` (--fix \u81EA\u6108) | \u624B\u7F16 \`.claude/hooks/\` \u4E0B \`.cjs\` |
+| \u7528 \`fabric-archive\` / \`fabric-review\` / \`fabric store ...\` \u7BA1\u7406 store-backed knowledge | \u624B\u5199\u4EFB\u4F55\u975E store knowledge \u6839 |
+| \`npm install -g @fenglimg/fabric-cli@latest\` \u5347\u7EA7 | \u80CC 35 \u6761 doctor lint \u4EE3\u7801 |
+
+**4 \u6B65\u5FAA\u73AF**: \`fabric install\` (\u4E00\u6B21) \u2192 \u7ED1\u5B9A\u5E76\u9009\u62E9\u5199\u5165 store \u2192 AI \u6B63\u5E38\u5DE5\u4F5C (hook on session start + edit) \u2192 AI \u901A\u8FC7 MCP \u5199\u5165\u5F53\u524D write store \u7684 pending \u6761\u76EE\u5E76\u8FD4\u56DE \`pending_path\` \u2192 \u7528 \`fabric-review\` skill \u5BA1\u6838\u3002
+
+**\u771F\u4F8B**:\u67D0 sprite \u9ED1\u8FB9 root cause \u662F \`atlas.premultiplyAlpha\` flag \u53CD\u5411 \u2014 \u5F52\u6863\u8FDB store \u7684 \`knowledge/pitfalls/\` \u540E,\u4E0B\u6B21\u540C\u7C7B\u95EE\u9898 AI \u81EA\u52A8 reference\u3002
+
+\u5B8C\u6574 maintainer \u7248\u89C1 \`docs/USER-QUICKSTART.md\`\u3002
+
+## \u884C\u4E3A\u89C4\u5219
+- **\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\u524D**:\u5148 \`fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])\` \u2014\u2014 \u4E00\u6B21\u8C03\u7528\u62FF\u56DE\u76F8\u5173 KB \u7684\u63CF\u8FF0 + \u539F\u751F\u8BFB\u53D6\u8DEF\u5F84(\`entries[].read_path\`)\u3002\`fab_recall\` \u4E0D\u518D\u6295\u9012\u6B63\u6587;\u9700\u8981\u67D0\u6761\u6B63\u6587\u65F6\u76F4\u63A5\u5BF9\u5176 \`entries[].read_path\` \u505A\u539F\u751F Read(\`Read <store>/knowledge/<type>/<id>--*.md\`),\u8FD9\u4F1A\u88AB PostToolUse hook \u8BB0\u4E3A \`knowledge_body_read\`\u3002lean \u9ED8\u8BA4:\u63CF\u8FF0+\u7D22\u5F15\u5DF2\u591F\u53D1\u73B0\u6761\u76EE,\u6B63\u6587\u6309\u9700\u8BFB\u4E00\u6B21,\u4E0D\u6BCF\u8F6E\u91CD\u704C(KT-GLD-0005)\u3002
+- **\`.fabric/agents.meta.json\` \u4E25\u7981\u624B\u52A8\u7F16\u8F91**;engine \u4F1A\u81EA\u52A8\u540C\u6B65\u6D3E\u751F\u72B6\u6001,\u663E\u5F0F reconcile \u8DD1 \`fabric doctor --fix\`\u3002
+
+## \u77E5\u8BC6\u5E93(KB)
+- **Discovery**:SessionStart hook \u5217 broad-scoped \u6761\u76EE(\u6761\u76EE\u6309 \`semantic_scope\` \u5206\u4E09\u5C42:\`team\` \u56E2\u961F\u901A\u7528 / \`project:<id>\` \u672C\u9879\u76EE\u4E13\u5C5E(\u4EC5\u5728\u7ED1\u5B9A\u8BE5\u9879\u76EE\u7684\u4ED3\u5E93\u6D6E\u73B0)/ \`personal\` \u4E2A\u4EBA \`KP-*\`,\u4E09\u8005\u5F15\u7528\u65B9\u5F0F\u76F8\u540C);edit \u6587\u4EF6\u65F6 PreToolUse hook \u53EF\u80FD\u89E6\u53D1 narrow hint\u3002
+- **Scope \u4E09\u8F74(\u4E3A\u4EC0\u4E48\u6CA1\u6D6E\u73B0)** (KT-MOD-0001):\u4E00\u6761\u77E5\u8BC6\u662F\u5426\u6D6E\u73B0\u7531\u4E09\u4E2A**\u6B63\u4EA4**\u8F74\u51B3\u5B9A \u2014\u2014 \u2460 \`semantic_scope\` \u53D7\u4F17(\`team\` / \`project:<id>\` / \`personal\`;\u7ED1\u9519\u9879\u76EE\u5219\u4E0D\u663E)\u2461 \`relevance_scope\` \u65F6\u673A(\`broad\` \u5E38\u9A7B / \`narrow\` \u4EC5\u7F16\u8F91\u5339\u914D\u6587\u4EF6\u65F6\u6D6E\u73B0)\u2462 \`store\` \u7269\u7406\u5E93(\u6CA1 \`fabric store bind\` \u5C31\u4E0D\u8BFB)\u3002\u4E09\u8F74\u540D\u5B57\u4F1A\u649E("team" \u65E2\u662F\u53D7\u4F17\u503C\u4E5F\u53EF\u662F store \u522B\u540D),\u6240\u4EE5\u56F0\u60D1"\u4E3A\u4EC0\u4E48\u8FD9\u6761\u6CA1\u6D6E\u73B0"\u65F6\u8DD1 \`fabric audit why-not-surfaced <id>\` \u9010\u56E0\u8BCA\u65AD(store \u6CA1\u7ED1 / scope \u4E0D\u5339\u914D / narrow \u65F6\u673A)\u3002
+- **Usage**:\u8D70\u5355\u6B65 \`fab_recall(paths=[...])\` \u4E00\u6B21\u62FF\u56DE\u76F8\u5173 KB \u7684\u63CF\u8FF0 + \u8BFB\u53D6\u8DEF\u5F84;\u9700\u8981\u67D0\u6761\u6B63\u6587\u65F6\u5BF9\u5176 \`entries[].read_path\` \u505A\u539F\u751F Read \u53D6\u56DE(\u4E0D\u518D\u8D70 MCP \u4E8C\u6B21\u53D6\u6B63\u6587)\u3002
+- **session_id**: \u8C03\u7528 \`fab_recall\` \u65F6, \u52A1\u5FC5\u628A\u5F53\u524D client session id \u4F5C\u4E3A \`session_id\` \u53C2\u6570\u4F20\u5165(Claude Code \u7684 session id \u5728 stdin payload \u4E2D, Codex \u7684\u5BF9\u5E94 identifier \u540C\u7406)\u3002\u8FD9\u80FD\u8BA9 \`fabric doctor --archive-history\` \u4E0E \`fabric-hint.cjs\` Stop hook \u51C6\u786E\u8BC6\u522B\u8DE8\u4F1A\u8BDD debt \u72B6\u6001\u3002
+- **Skills (4)**:\u5199\u6D41\u7A0B \`fabric-archive\`(\u542B source mode \u51B7\u542F\u52A8\u4ECE git/docs \u56DE\u704C)/ \`fabric-review\`(\u542B retire \u8BED\u4E49\u6DD8\u6C70 + relate \u5173\u8054\u5EFA\u8FB9 \u5B50\u6D41\u7A0B);store \u8FD0\u7EF4 \`fabric-store\` / \`fabric-sync\`\u3002
+- **Language**:\u6E32\u67D3\u6309 \`~/.fabric/fabric-global.json\` \u7684 \`language\` \u5B57\u6BB5(machine-wide tone)\u3002
+- **Archive cadence nudge** (rc.36): \u6BCF\u5B8C\u6210\u4E00\u6279 Edit(\u9ED8\u8BA4 ~20 \u6B21, \u4E0E Stop hook \u9608\u503C config \`archive_edit_threshold\` \u4E00\u81F4)/ \u663E\u8457 decision \u540E,\u5728\u5408\u9002\u56DE\u5408\u4E3B\u52A8 propose \u8C03 \`fabric-archive\` skill \u2014 archive \u6CA1\u5EFA\u7ACB\u9891\u7387\u4F1A\u8BA9 KB \u6162\u901F\u6B7B\u6389\u3002
+- **Review backlog nudge** (rc.36): \u9700\u8981\u5224\u65AD pending backlog \u65F6\u8D70 \`fab_pending action="list"\` \u6216 \`fabric-review\` \u8FD4\u56DE\u7684 \`pending_path\`;\u4E0D\u8981 glob \u9879\u76EE\u672C\u5730 \`.fabric/knowledge/pending\`\u3002\u5F53\u53EF\u89C1 pending \u7D2F\u79EF >10 \u6761\u65F6,\u5728\u5408\u9002\u56DE\u5408\u4E3B\u52A8 propose \u8C03 \`fabric-review\` skill \u6279\u91CF\u5BA1,\u907F\u514D draft \u5361\u6B7B\u3002
+
+## Self-archive policy (v2.2 C1: \u7CBE\u7B80\u8BF4\u660E\u4E66)
+
+\u51FA\u73B0\u660E\u786E\u5F52\u6863\u4FE1\u53F7\u65F6, \u4E8E\u8BE5 turn \u672B\u5C3E\u81EA\u4E3B\u8C03\u7528 \`fabric-archive\` skill(AI \u81EA\u89E6\u53D1\u5165\u53E3 E3):
+
+- **\u89E6\u53D1** (\u4E8C\u9009\u4E00): \u2460 **User-driven normative** \u2014 \u7528\u6237\u8BF4 \`\u4EE5\u540E\` / \`always\` / \`never\` / \`\u4E0B\u6B21\` / \`\u8BB0\u4E00\u4E0B\`, \u6216\u5728 \u22652 \u5019\u9009\u95F4\u6743\u8861\u540E\u9501\u5B9A\u65B9\u5411, \u6216\u62D2\u4E86\u5EFA\u8BAE\u5E76\u7ED9\u4E86\u7406\u7531(\u7406\u7531\u5373\u77E5\u8BC6); \u2461 **Wrong-turn-and-revert** \u2014 \u4F60\u8BD5\u4E86 path X \u53CD\u601D\u540E\u6539\u8D70 path Y("\u5426\u5B9A+\u66FF\u4EE3"\u4E24\u6B65\u7ED3\u6784, \u975E\u5355\u7EAF\u63A2\u7D22\u5931\u8D25)\u3002
+- **\u4E0D\u89E6\u53D1**: \u7528\u6237\u7EAF\u8BE2\u95EE / \u7B80\u5355 refactor\xB7typo / \u51ED\u7A7A"\u6211\u5B66\u5230\u4E86"\u7684\u6D1E\u5BDF\u3002
+- **\u9632 loop**: \u540C turn \u6700\u591A\u81EA\u8C03 1 \u6B21; \u540C session \u540C outcome \u4E0D\u91CD\u590D; skill \u5185 Phase 2.5 viability gate \u515C\u5E95\u3002
+- **\u56DE\u6267 (marker-free)**: \u76F4\u63A5\u81EA\u8C03 \`fabric-archive\` skill \u5373\u53EF, \u65E0\u9700\u6253\u5370\u4EFB\u4F55\u6697\u53F7\u5B57\u7B26\u4E32 \u2014\u2014 skill \u9ED8\u8BA4\u628A AI \u81EA\u8C03\u8BC6\u522B\u4E3A E3(\u786E\u5B9A\u6027 else \u8DEF\u7531, \u4E0D\u518D\u4F9D\u8D56 AI \u8F93\u51FA\u7CBE\u786E\u5B57\u7B26\u4E32)\u3002skill \u843D pending \u540E\u8FD4\u56DE \`pending_path\`, \u4E0D\u8BE5\u8BB0\u5C31\u56DE \`undo\`(\u6211\u8C03 fab_review reject)\u3002
+
+## Cite policy (v2.2 C1: recall \u81EA\u52A8\u8BB0\u8D26, \u96F6\u9996\u884C\u8D1F\u62C5)
+
+- **\u6838\u5FC3 (recall-first \u81EA\u52A8\u8BB0\u8D26)**: \u6539\u4EFB\u4F55\u6587\u4EF6\u524D\u5148 \`fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])\`\u3002\u7CFB\u7EDF\u6309"\u672C session recall \u547D\u4E2D\u7684 path \u4E0E\u7F16\u8F91\u76EE\u6807\u91CD\u53E0"\u81EA\u52A8\u628A\u53EC\u56DE\u7684 KB \u8BB0\u4E3A\u8BE5\u6B21 edit \u7684\u5F15\u7528 \u2014\u2014 **\u65E0\u9700\u624B\u5199\u4EFB\u4F55\u56DE\u590D\u9996\u884C**(C1 \u5220\u9664\u9996\u884C \`KB:\` contract \u516B\u80A1:\u5148\u60F3\u540E\u8BF4,recall \u624D\u662F\u5F15\u7528\u53D1\u751F\u7684\u771F\u5B9E\u4FE1\u53F7)\u3002PreToolUse \u68C0\u6D4B\u4E0D\u5230\u76F8\u5173 recall \u65F6\u7ED9\u4E00\u6761\u8F6F nudge(nudge \u975E gate,\u5B88 KT-DEC-0007)\u3002
+- **\u552F\u4E00\u8981\u5F00\u53E3\u7684\u65F6\u5019 (dismissed / override)**: \u4F60\u5224\u65AD\u67D0\u53EC\u56DE KB \u4E0D\u8BE5\u5E94\u7528\u65F6,\u8BF4\u4E00\u53E5 \`dismissed: <id> (<reason>)\`;reason \u679A\u4E3E \`scope-mismatch | outdated | not-applicable | other:<text>\`\u3002\u9700\u7CBE\u786E\u6807\u6CE8\u4ECD\u53EF\u7528\u9996\u884C \`KB: <id> [applied|dismissed]\`(\u89E3\u6790\u5668\u4FDD\u7559,\u5411\u540E\u517C\u5BB9)\u3002
+- **\`[applied]\` \u9A8C\u8BC1\u4E49\u52A1**: \u5F15\u7528\u4EFB\u4F55 id(\u81EA\u52A8\u6216\u624B\u5199)\u524D\u5FC5\u987B\u5148 fab_recall \u5B9E\u9645\u6293\u56DE KB(\u6309\u9700\u5BF9\u6B63\u6587\u8DEF\u5F84\u505A\u539F\u751F Read),\u9632\u6B62\u7F16\u9020 id\u3002\u9A8C\u8BC1\u4E0D\u901A\u8FC7 = \u4E0D\u80FD cite\u3002
+- **\u7A3D\u6838\u4E0E\u5B8C\u6574\u89C4\u7EA6**: \`fabric audit cite\` \u8F93\u51FA\u8986\u76D6\u7387(\u4E0D\u963B\u65AD\u5DE5\u4F5C,\u53EA\u8BB0\u5F55);contract operator / store \u524D\u7F00 / skip\xB7dismissed \u8BCD\u5178 / \u7C7B\u578B\u8DEF\u7531 / \u88C1\u51B3\u9636\u68AF\u7B49\u5B8C\u6574\u89C4\u7EA6\u6743\u5A01\u8BE6\u53C2 \`fabric-review\` skill \u7684 \`ref/cite-contract.md\` \u2014\u2014 bootstrap \u53EA\u7559\u53EF\u6267\u884C core\u3002
+`;
+var BOOTSTRAP_CANONICAL_EN = `# Fabric Bootstrap
+
+This project uses Fabric to manage cross-client AI knowledge and behavior rules. This file is synced into the managed block on both clients by \`fabric install\` \u2014 **do not hand-edit the block on any client**; edit here + re-run \`fabric install\`.
+
+## For Developers
+
+This file is the **AI client's policy & convention config**, not dev onboarding. You don't need to read the Self-archive / Cite / Phase 0.4 details.
+As a dev you only need to: run \`fabric install\` once per repo, use \`fabric store bind <alias>\` / \`fabric store switch-write <alias>\` to wire up a write store, and run \`fabric doctor\` when something breaks.
+**Never hand-edit \`.fabric/agents.meta.json\`** \u2014 derived state is rebuilt by the engine.
+
+## Dev Quickstart
+
+**What Fabric is**: a cross-client (Claude Code / Codex CLI) AI knowledge layer. Store the team/project **decisions / pitfalls / guidelines / models / processes** as markdown; hooks surface them to the AI automatically so it doesn't re-learn every time.
+
+**What you DO** vs **what the engine does (DON'T hand-edit)**:
+
+| You DO | You DON'T |
+| --- | --- |
+| Run \`fabric install\` once per repo | Hand-edit \`.fabric/agents.meta.json\` |
+| Run \`fabric doctor\` (--fix self-heals) on trouble | Hand-edit \`.cjs\` under \`.claude/hooks/\` |
+| Use \`fabric-archive\` / \`fabric-review\` / \`fabric store ...\` to manage store-backed knowledge | Hand-write any non-store knowledge root |
+| \`npm install -g @fenglimg/fabric-cli@latest\` to upgrade | Memorize the 35 doctor lint codes |
+
+**4-step loop**: \`fabric install\` (once) \u2192 bind and pick a write store \u2192 AI works normally (hook on session start + edit) \u2192 the AI writes pending entries into the current write store via MCP and returns a \`pending_path\` \u2192 review with the \`fabric-review\` skill.
+
+**Real example**: a sprite black-edge root cause was the \`atlas.premultiplyAlpha\` flag being inverted \u2014 once archived into the store's \`knowledge/pitfalls/\`, the AI auto-references it next time a similar issue shows up.
+
+See \`docs/USER-QUICKSTART.md\` for the full maintainer version.
+
+## Behavior Rules
+- **Before modifying any file**: first \`fab_recall(paths=[<file-being-edited>])\` \u2014\u2014 a single call returns the relevant KB descriptions + native read paths (\`entries[].read_path\`). \`fab_recall\` no longer delivers bodies; when you need a body, do a native Read of its \`entries[].read_path\` (\`Read <store>/knowledge/<type>/<id>--*.md\`), which the PostToolUse hook records as \`knowledge_body_read\`. Lean default: descriptions + index already suffice to discover entries; read a body once on demand, don't re-inject it every turn (KT-GLD-0005).
+- **Never hand-edit \`.fabric/agents.meta.json\`**; the engine syncs derived state automatically \u2014 run \`fabric doctor --fix\` for an explicit reconcile.
+
+## Knowledge Base (KB)
+- **Discovery**: the SessionStart hook lists broad-scoped entries (scoped by \`semantic_scope\` across three tiers: \`team\` team-wide / \`project:<id>\` this-project-only (surfaces only in repos bound to that project) / \`personal\` \`KP-*\`, all three referenced the same way); editing a file may trigger a narrow hint via the PreToolUse hook.
+- **Scope's 3 axes (why something isn't surfacing)** (KT-MOD-0001): whether an entry surfaces is decided by three **orthogonal** axes \u2014 \u2460 \`semantic_scope\` audience (\`team\` / \`project:<id>\` / \`personal\`; the wrong project binding hides it) \u2461 \`relevance_scope\` timing (\`broad\` always-on / \`narrow\` only when you edit a matching file) \u2462 \`store\` physical lib (not read without \`fabric store bind\`). The axis names collide ("team" is both an audience value and a possible store alias), so when puzzled about "why isn't this surfacing" run \`fabric audit why-not-surfaced <id>\` for a per-cause diagnosis (store unbound / scope mismatch / narrow timing).
+- **Usage**: go one-step \`fab_recall(paths=[...])\` to fetch the relevant KB descriptions + read paths in one call; when you need a body, do a native Read of its \`entries[].read_path\` (no second MCP round-trip for the body).
+- **session_id**: when calling \`fab_recall\`, always pass the current client session id as the \`session_id\` argument (Claude Code's session id is in the stdin payload; Codex's corresponding identifier likewise). This lets \`fabric doctor --archive-history\` and the \`fabric-hint.cjs\` Stop hook track cross-session debt accurately.
+- **Skills (4)**: write flow \`fabric-archive\` (with source-mode cold-start backfill from git/docs) / \`fabric-review\` (with retire-deprecation + relate-edge sub-flows); store ops \`fabric-store\` / \`fabric-sync\`.
+- **Language**: rendered per the \`language\` field in \`~/.fabric/fabric-global.json\` (machine-wide tone).
+- **Archive cadence nudge** (rc.36): after each batch of edits (default ~20, matching the Stop hook threshold config \`archive_edit_threshold\`) / a significant decision, proactively propose the \`fabric-archive\` skill at a suitable turn \u2014 without an archive cadence the KB slowly dies.
+- **Review backlog nudge** (rc.36): to judge the pending backlog, go through \`fab_pending action="list"\` or the \`pending_path\` returned by \`fabric-review\`; don't glob the project-local \`.fabric/knowledge/pending\`. When the visible pending count exceeds 10, proactively propose the \`fabric-review\` skill at a suitable turn to batch-review and avoid draft deadlock.
+
+## Self-archive policy (v2.2 C1: lean spec)
+
+When a clear archival signal appears, autonomously invoke the \`fabric-archive\` skill at the end of that turn (AI self-trigger entry E3):
+
+- **Trigger** (either): \u2460 **User-driven normative** \u2014 the user says \`\u4EE5\u540E\` / \`always\` / \`never\` / \`\u4E0B\u6B21\` / \`\u8BB0\u4E00\u4E0B\`, or locks a direction with rationale after weighing \u22652 candidates, or rejects a suggestion and states a reason (the reason is knowledge); \u2461 **Wrong-turn-and-revert** \u2014 you tried path X, then after reflection switched to path Y (a two-step "negate + replace" structure, not mere exploratory failure).
+- **Does NOT trigger**: pure user questions / simple refactor\xB7typo / a baseless "I learned something" insight.
+- **Anti-loop**: at most 1 self-invocation per turn; no repeat for the same outcome in the same session; the skill's Phase 2.5 viability gate is the backstop.
+- **Receipt (marker-free)**: just invoke the \`fabric-archive\` skill directly \u2014 no marker string to print: the skill routes an AI self-invocation to E3 by default (deterministic else-branch, no longer dependent on the AI emitting an exact string). The skill returns \`pending_path\` after writing pending \u2014 reply \`undo\` if it shouldn't be recorded (I'll call fab_review reject).
+
+## Cite policy (v2.2 C1: recall auto-accounting, zero first-line burden)
+
+- **Core (recall-first auto-accounting)**: before changing any file, run \`fab_recall(paths=[<file-being-edited>])\` first. The system auto-accounts the recalled KB as that edit's citation by "paths recall-hit this session overlap the edit target" \u2014\u2014 **no hand-written first reply line needed** (C1 removes the first-line \`KB:\` contract boilerplate: think-then-speak, recall is the real signal that a citation happened). The PreToolUse hook gives a soft nudge when it detects no relevant recall (nudge, not a gate, per KT-DEC-0007).
+- **The only time to speak up (dismissed / override)**: when you judge a recalled KB should NOT apply, say one line \`dismissed: <id> (<reason>)\`; reason enum \`scope-mismatch | outdated | not-applicable | other:<text>\`. For precise annotation you may still use a first-line \`KB: <id> [applied|dismissed]\` (parser retained, backward compatible).
+- **\`[applied]\` verification duty**: citing any id (auto or hand-written) requires first fetching the KB via fab_recall (a native Read of its body path when needed) to prevent fabricated ids. Verification failing = you cannot cite.
+- **Audit & full spec**: \`fabric audit cite\` reports coverage (does not block your work, only records); the full spec (contract operators / store prefix / skip\xB7dismissed dictionaries / type routing / adjudication ladder) lives authoritatively in the \`fabric-review\` skill's \`ref/cite-contract.md\` \u2014\u2014 bootstrap keeps only the executable core.
+`;
+var BOOTSTRAP_CANONICAL_BY_LOCALE = {
+  "zh-CN": BOOTSTRAP_CANONICAL_ZH,
+  en: BOOTSTRAP_CANONICAL_EN
+};
+function resolveBootstrapCanonical(locale) {
+  return BOOTSTRAP_CANONICAL_BY_LOCALE[locale ?? resolveGlobalLocale()];
+}
+function matchBootstrapCanonicalLocale(body) {
+  for (const locale of Object.keys(BOOTSTRAP_CANONICAL_BY_LOCALE)) {
+    if (BOOTSTRAP_CANONICAL_BY_LOCALE[locale] === body) {
+      return locale;
+    }
+  }
+  return null;
+}
+
+export {
+  BOOTSTRAP_MARKER_BEGIN,
+  BOOTSTRAP_MARKER_END,
+  BOOTSTRAP_REGEX,
+  BOOTSTRAP_CANONICAL_ZH,
+  BOOTSTRAP_CANONICAL_EN,
+  BOOTSTRAP_CANONICAL_BY_LOCALE,
+  resolveBootstrapCanonical,
+  matchBootstrapCanonicalLocale
+};