@fenglimg/fabric-cli 2.0.0-rc.27 → 2.0.0-rc.28

package/templates/skills/fabric-import/ref/i18n-policy.md

@@ -0,0 +1,73 @@
+# UX i18n Policy — fabric-import full reference
+
+> **Loaded on demand.** Only consult when you need to disambiguate which of the 5 classes a given string belongs to. SKILL.md gives the operative rule.
+
+## UX i18n Policy (5-class bilingualization)
+
+The skill consults `fabric_language` from `.fabric/fabric-config.json`
+(固化于 install 时，via `scan.ts:detectExistingLanguage`; default `"en"` when no
+CJK signal is detected in README + docs/; may resolve to `"match-existing"`,
+`"zh-CN"`, `"en"`, or `"zh-CN-hybrid"`). All user-facing text in the
+following 5 categories MUST be rendered in the resolved language:
+
+1. **Roll-up templates** — final summary blocks (`# Import Summary — phase=...`,
+   `## Phase 2 — Mining`, `## Phase 3 — Dedup`, etc.). zh-CN ↔ en mirror.
+2. **Errors / Preconditions warnings** — abort + gate-fail messages (e.g.
+   "请先运行 fabric install 完成基线扫描…" / "Please run fabric install first…").
+   zh-CN ↔ en mirror.
+3. **Confirmation prompts** — re-run-within-24h prompt, reset prompts, etc.
+   zh-CN ↔ en mirror.
+4. **Dry-run table headers** — `# Import Dry Run — would propose N pending
+   entries…` + the `| # | Source | Type | Slug | Scope | Summary |` header row.
+   zh-CN ↔ en mirror.
+5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
+   zh-CN ↔ en mirror. fabric-import itself does not surface AskUserQuestion
+   in the current contract (the rare re-run prompt is free-text), but if a
+   future version adds one, this rule applies.
+
+Rendering rule:
+
+- `fabric_language === "zh-CN"` → emit the zh-CN variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "en"` → emit the en variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_get_knowledge_sections`), CLI command names (e.g. `fab install`), file paths, technical concepts (`Skill`, `SessionStart`, `hook`, `MCP`, `revision_hash`, `pending`, `proven`, `verified`, `draft`).
+- `fabric_language === "match-existing"` or any other value → emit the en variant; pure monolingual.
+
+Protected tokens (`fab_extract_knowledge`, `fab_review`, `relevance_scope`,
+`relevance_paths`, `broad`, `narrow`, `source_sessions`, `proposed_reason`,
+`session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`,
+`pending_path`, `layer`, `team`, `personal`,
+`knowledge_scope_degraded`, `MUST`, `NEVER`, `.fabric/knowledge/`, etc.)
+are NEVER translated — they appear verbatim in both language variants.
+The bilingualization scope is prose ONLY.
+
+### AskUserQuestion i18n Policy (value vs label)
+
+When a skill (this one or any sibling skill the user is composing with)
+issues an `AskUserQuestion`, the `header` and `question` strings are
+user-facing prose → translated per `fabric_language`. The `options[]`
+array entries (e.g. `["approve", "reject", "modify", "defer", "skip"]` in
+fabric-review) are **routing keys** consumed by the skill state machine —
+they MUST remain English regardless of `fabric_language`.
+
+```ts
+// EN (fabric_language === "en")
+AskUserQuestion({
+  header: "Review pending entry",
+  question: "What action for '{title}'?",
+  options: ["approve", "reject", "modify", "defer", "skip"]
+})
+
+// zh-CN (fabric_language === "zh-CN")
+AskUserQuestion({
+  header: "审核 pending 条目",
+  question: "对 '{title}' 执行什么操作？",
+  options: ["approve", "reject", "modify", "defer", "skip"]   // 不翻译 — routing key
+})
+```
+
+Rationale: localizing routing keys would force every routing branch to
+dual-string match (e.g. `if (choice === "approve" || choice === "通过")`),
+which doubles the surface area for protected-token regressions and breaks
+the option-list invariants that downstream tooling depends on. Keeping
+`options[]` English-only is contract-locked across all three skills.
+

package/templates/skills/fabric-import/ref/state-recovery.md

@@ -0,0 +1,57 @@
+# Phase 0 + 0.1 — State Recovery (fabric-import ref-only)
+
+> **Loaded on demand.** Only relevant when a prior import crashed mid-phase, leaving `.tmp-*` residue or a torn `.fabric/.import-state.json`. SKILL.md's hot path inline says "scan for .tmp residue + load state" — this file is the full recovery procedure (atomic-write pattern, sweep rules, corruption detection, fallback to fresh import).
+
+## Phase 0 — Init & .tmp Residue Scan
+
+Before reading `.fabric/.import-state.json`, scan for residue left by a
+prior crashed run. Skill state writes use a 2-step atomic pattern (Write
+`.tmp` then `Bash mv`); a crash between Step A and Step B leaves a
+`.fabric/.import-state.json.tmp` sidecar that the next invocation MUST
+triage.
+
+1. Does `.fabric/.import-state.json.tmp` exist? (`Bash: ls .fabric/.import-state.json.tmp 2>/dev/null`)
+   - **Does not exist** → proceed normally to Phase 0.1 (no residue work).
+   - **Exists** → triage:
+     1. `Read` the `.tmp` file; try `JSON.parse` on the content.
+     2. Compare `mtime` of `.tmp` vs `.fabric/.import-state.json` via `Bash: stat`.
+        - **Parse OK + .tmp mtime newer than main file** → rescue:
+          `Bash: mv .fabric/.import-state.json.tmp .fabric/.import-state.json`
+          (commits the last incomplete write atomically).
+        - **Parse OK + .tmp mtime older than main file** → stale residue
+          from an earlier run that subsequently completed; delete it:
+          `Bash: rm .fabric/.import-state.json.tmp`.
+        - **Parse fails** (syntax error / unterminated structure / truncated
+          mid-write) → half-written, unrecoverable; delete it:
+          `Bash: rm .fabric/.import-state.json.tmp`.
+     3. After triage, proceed to Phase 0.1.
+
+The 5-minute mtime heuristic (treat any `.tmp` older than 5 minutes as
+stale regardless of parse result) is an acceptable conservative simplification:
+no legitimate atomic write window stays open that long; anything older
+than 5 minutes is definitely crash residue. Implementations MAY use either
+the mtime-comparison rule above OR the 5-minute staleness rule.
+
+### Phase 0.1 — State Corruption Recovery
+
+After residue triage, `Read` `.fabric/.import-state.json`. Detect
+corruption if ANY of the following hold:
+
+- `JSON.parse` throws (syntax error / unterminated structure / truncated)
+- Missing required field: `phase` OR `started_at` OR `last_checkpoint_at`
+- `phase` value not in the enum `{P1-done, P2-done, complete}`
+
+On corruption (any condition above):
+
+1. `Bash: mv .fabric/.import-state.json .fabric/.import-state.json.corrupt-<ISO8601>`
+   (preserve the corrupt file for postmortem; do NOT silently overwrite).
+2. Phase 1 restarts from scratch (Phase 1 produces no MCP calls, so re-run
+   is safe — re-globbing `.fabric/knowledge/team/**/*.md` is cheap and
+   idempotent; the `p1_baseline_titles` array is regenerated).
+3. DO NOT attempt automatic partial recovery; corrupt state is a signal
+   that something serious happened (disk-full, kill -9 mid-write, fs
+   error). Discard-and-restart is the only safe path.
+
+ENOENT (state file absent) is NOT corruption — it is the normal
+first-run state. Proceed to Phase 0.5.
+

package/templates/skills/fabric-review/SKILL.md

@@ -49,106 +49,13 @@ defaults if absent):
 
 If `.fabric/fabric-config.json` is missing or unreadable, use defaults silently.
 
-### UX i18n Policy (5-class bilingualization)
-
-The skill consults `fabric_language` from `.fabric/fabric-config.json`
-(固化于 init 时，via `lib/detect-language.ts:detectExistingLanguage`; default `"en"` when no
-CJK signal is detected in README + docs/; may resolve to `"match-existing"`,
-`"zh-CN"`, `"en"`, or `"zh-CN-hybrid"`). All user-facing text in the
-following 5 categories MUST be rendered in the resolved language:
-
-1. **Roll-up templates** — the `# Review Summary — mode={...}` final block,
-   the `## Health Overview` dashboard in health mode, and any per-item
-   display blocks (`## [type=...] [layer=...] pending_path=...` lines).
-   zh-CN ↔ en mirror.
-2. **Errors / Preconditions warnings** — abort + trigger-miss messages
-   (e.g. "没有触发 review 信号…" / "No review signal detected…").
-   zh-CN ↔ en mirror.
-3. **Confirmation prompts** — free-text reject-reason follow-up, the
-   "Type relevance_paths (comma-separated globs, …)" narrow-scope
-   follow-up, and any other free-text prompts. zh-CN ↔ en mirror.
-4. **Dry-run table headers** — fabric-review does not currently expose
-   a dry-run mode; this slot is reserved for parity with fabric-import.
-   IF a future revision adds dry-run, the table header MUST be
-   bilingualized per this policy. zh-CN ↔ en mirror.
-5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
-   zh-CN ↔ en mirror. fabric-review is the heaviest AskUserQuestion
-   consumer (per-item action, layer-flip target, stale-item action,
-   modify-extended option set), so this class applies broadly.
-
-Rendering rule:
-
-- `fabric_language === "zh-CN"` → emit the zh-CN variant; pure monolingual, no language mixing inside a single user-facing block.
-- `fabric_language === "en"` → emit the en variant; pure monolingual, no language mixing inside a single user-facing block.
-- `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_get_knowledge_sections`), CLI command names (e.g. `fab install`), file paths, technical concepts (`Skill`, `SessionStart`, `hook`, `MCP`, `revision_hash`, `pending`, `proven`, `verified`, `draft`).
-- `fabric_language === "match-existing"` or any other value → emit the en variant; pure monolingual.
-
-Protected tokens (`fab_review`, `relevance_scope`, `relevance_paths`,
-`narrow`, `broad`, `source_sessions`, `proposed_reason`, `session_context`,
-`pending_path`, `layer`, `team`, `personal`, `knowledge_scope_degraded`,
-`MUST`, `NEVER`, `.fabric/knowledge/`, etc.) are NEVER translated — they
-appear verbatim in both language variants. The bilingualization scope is
-prose ONLY.
-
-### AskUserQuestion i18n Policy (value vs label)
-
-When this skill issues an `AskUserQuestion`, the `header` and `question`
-strings are user-facing prose → translated per `fabric_language`. The
-`options[]` array entries are **routing keys** consumed by the skill
-state machine — they MUST remain English regardless of `fabric_language`.
-
-Canonical options arrays used by this skill (every value below stays
-English in BOTH language variants):
-
-- Per-item action: `["approve", "reject", "modify", "defer", "skip"]`
-- Per-stale-item action (health mode): `["defer", "demote", "skip"]`
-- Layer-flip target: `["team", "personal"]`
-- Modify-extended (import-origin narrow-scope nudge):
-  `["narrow scope", "edit summary", "change layer", "change maturity", "skip"]`
+### UX i18n Policy
 
-Worked example — per-item action (the most common AskUserQuestion in this skill):
+Read `.fabric/fabric-config.json` → `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`). Emit user-facing prose in the resolved variant. Protected tokens (`fab_review`, `fab_extract_knowledge`, `relevance_scope`, layer/scope enum values, `stable_id`, the verbatim `强 team` / `强 personal` / `默认 team` block) are NEVER translated.
 
-```ts
-// EN (fabric_language === "en")
-AskUserQuestion({
-  header: "Review pending entry",
-  question: "What action for '{title}'?  ({pending_path})",
-  options: ["approve", "reject", "modify", "defer", "skip"]
-})
+`AskUserQuestion` policy: `header` + `question` translate; `options[]` are routing keys — stay English regardless of locale.
 
-// zh-CN (fabric_language === "zh-CN")
-AskUserQuestion({
-  header: "审核 pending 条目",
-  question: "对 '{title}' 执行什么操作？({pending_path})",
-  options: ["approve", "reject", "modify", "defer", "skip"]   // 不翻译 — routing key
-})
-```
-
-Worked example — layer-flip target:
-
-```ts
-// EN
-AskUserQuestion({
-  header: "Layer-flip target",
-  question: "Move '{title}' to which layer?  (current: {current_layer})",
-  options: ["team", "personal"]
-})
-
-// zh-CN
-AskUserQuestion({
-  header: "Layer 切换目标",
-  question: "将 '{title}' 切换到哪一层？(当前: {current_layer})",
-  options: ["team", "personal"]   // 不翻译 — routing key
-})
-```
-
-Rationale: localizing routing keys would force every routing branch to
-dual-string match (e.g. `if (choice === "approve" || choice === "通过")`),
-which doubles the surface area for protected-token regressions and breaks
-the option-list invariants that downstream tooling (the Skill's own
-`switch` statements over `choice`, plus any future MCP-level audit lint
-that scans for these specific string literals) depends on. Keeping
-`options[]` English-only is contract-locked across all three skills.
+**For the full 5-class taxonomy + edge cases:** `Read packages/cli/templates/skills/fabric-review/ref/i18n-policy.md` (or `.claude/skills/fabric-review/ref/i18n-policy.md` post-install).
 
 ## Mode Inference (System Infers — NEVER Ask)
 
@@ -624,94 +531,6 @@ Skills MUST ensure:
 
 Also surface a one-line `git status` of `.fabric/knowledge/` so the user sees the file moves caused by approve / layer-flip.
 
-## Worked Examples
-
-### Example A — pending mode with semantic check flagging a duplicate (user chooses reject)
-
-User: "review the pending knowledge".
-
-Inferred mode: `pending` (Step 1 keyword "review … pending").
-
-Skill flow:
-
-1. `fab_review action="list"` → returns 3 pending items.
-2. Semantic check on item 2 (`pending/decisions/single-cjs-hook.md`) — `fab_review action="search"` with `query="single cjs hook"` filter `type=decisions` returns canonical `KT-D-0007--single-cjs-hook-across-clients.md` (similarity high).
-3. Display block:
-
-   ```md
-   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
-   Title: 单 .cjs hook 跨客户端
-   Summary: 三客户端 stdout JSON 格式一致，单脚本即可。
-   ⚠ Possible duplicate of KT-D-0007 (LLM 主观判断 dup/subsumption；具体阈值不可量化)
-   ```
-
-4. AskUserQuestion fires; user picks `reject`.
-5. Free-text follow-up: user types `duplicate of KT-D-7`.
-6. `fab_review action="reject"` with `pending_paths=["knowledge/pending/decisions/single-cjs-hook.md"]` and `reason="duplicate of KT-D-7"`.
-7. Roll-up reports: 1 rejected, 0 approved, events appended.
-
-### Example B — revisit mode with layer flip (KT → KP)
-
-User: "look at KT-G-3, that's actually personal not team".
-
-Inferred mode: `revisit` (Step 1 keyword "look at <id>").
-
-Skill flow:
-
-1. Read `.fabric/knowledge/team/guidelines/KT-G-0003--indent-style.md`. Display body to user.
-2. AskUserQuestion `{options: ["approve", "modify", "reject", "skip"]}` — user picks `modify`.
-3. Skill detects user-stated intent "actually personal not team" — surface AskUserQuestion `{options: ["team", "personal"]}` with current layer=team noted; user confirms `personal`.
-4. Call:
-
-   ```ts
-   mcp__fabric__fab_review({
-     action: "modify",
-     pending_path: "knowledge/team/guidelines/KT-G-0003--indent-style.md",
-     changes: { layer: "personal" }
-   })
-   ```
-
-5. Server returns `{prior_stable_id: "KT-G-0003", new_stable_id: "KP-G-0001"}`.
-6. Roll-up: `Layer flipped: KT-G-0003 → KP-G-0001`. `git status` shows the rename across layer roots.
-
-### Example C — health mode finding stale entries (defer 2, demote 1)
-
-User: "anything stale in our knowledge base?"
-
-Inferred mode: `health` (Step 1 keyword "stale").
-
-Skill flow:
-
-1. `fab_review action="list"` (no filter) + tail events.jsonl for trailing-30d demoted/layer_changed counts.
-2. Compute stale candidates: 3 pending entries with mtime >14d (KP-G-5 candidate-pending, KT-P-9 candidate-pending, KP-G-3 canonical draft with no evidence-append in 21d).
-3. Render dashboard then loop per stale item.
-4. Per-item AskUserQuestion fires:
-   - KP-G-5 → user picks `defer` (until="2026-06-01") → `fab_review action="defer"` with `until` set.
-   - KT-P-9 → user picks `defer` (no until) → `fab_review action="defer"` with no `until`.
-   - KP-G-3 → user picks `demote` → `fab_review action="modify"` with `changes.maturity="draft"` (already draft; equivalently demote means reject if pending — skill chooses correct action by inspecting current state).
-5. Roll-up: 2 deferred, 1 modified, events appended (`knowledge_deferred ×2`, `knowledge_promote_started/promoted` not relevant; `knowledge_layer_changed` not relevant).
-
-### Example D — narrowing an imported decision
-
-User: "review the pending knowledge".
-
-Inferred mode: `pending`. Skill lists 5 pending entries; entry 3's frontmatter 
-shows `source_sessions[0] = "fabric-import-2026-05-10"` → import-origin.
-
-Display block prepends warning line. User picks `modify` on entry 3.
-AskUserQuestion fires with extended options including `narrow scope`.
-User picks `narrow scope`; free-text follow-up: 
-`packages/server/src/retry/**, packages/server/src/lib/retry.ts`
-
-Skill calls:
-
-mcp__fabric__fab_review({
-  action: "modify",
-  pending_path: "knowledge/pending/decisions/<slug>.md",
-  changes: {
-    relevance_scope: "narrow",
-    relevance_paths: ["packages/server/src/retry/**", "packages/server/src/lib/retry.ts"]
-  }
-})
+## Worked Examples (ref-only)
 
-Roll-up confirms `relevance_scope: narrow` written to frontmatter.
+Four worked examples (pending-mode dedupe / revisit layer-flip / health mode / narrowing imported entries) live in `packages/cli/templates/skills/fabric-review/ref/worked-examples.md` (or `.claude/skills/fabric-review/ref/worked-examples.md` post-install). Load when you want to see how the full Mode + AskUserQuestion + MCP-call shape composes on real candidate sets.

package/templates/skills/fabric-review/ref/i18n-policy.md

@@ -0,0 +1,105 @@
+# UX i18n Policy — fabric-review full reference
+
+> **Loaded on demand.** Only consult when you need to disambiguate which of the 5 classes a given string belongs to. SKILL.md gives the operative rule.
+
+## UX i18n Policy (5-class bilingualization)
+
+The skill consults `fabric_language` from `.fabric/fabric-config.json`
+(固化于 init 时，via `lib/detect-language.ts:detectExistingLanguage`; default `"en"` when no
+CJK signal is detected in README + docs/; may resolve to `"match-existing"`,
+`"zh-CN"`, `"en"`, or `"zh-CN-hybrid"`). All user-facing text in the
+following 5 categories MUST be rendered in the resolved language:
+
+1. **Roll-up templates** — the `# Review Summary — mode={...}` final block,
+   the `## Health Overview` dashboard in health mode, and any per-item
+   display blocks (`## [type=...] [layer=...] pending_path=...` lines).
+   zh-CN ↔ en mirror.
+2. **Errors / Preconditions warnings** — abort + trigger-miss messages
+   (e.g. "没有触发 review 信号…" / "No review signal detected…").
+   zh-CN ↔ en mirror.
+3. **Confirmation prompts** — free-text reject-reason follow-up, the
+   "Type relevance_paths (comma-separated globs, …)" narrow-scope
+   follow-up, and any other free-text prompts. zh-CN ↔ en mirror.
+4. **Dry-run table headers** — fabric-review does not currently expose
+   a dry-run mode; this slot is reserved for parity with fabric-import.
+   IF a future revision adds dry-run, the table header MUST be
+   bilingualized per this policy. zh-CN ↔ en mirror.
+5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
+   zh-CN ↔ en mirror. fabric-review is the heaviest AskUserQuestion
+   consumer (per-item action, layer-flip target, stale-item action,
+   modify-extended option set), so this class applies broadly.
+
+Rendering rule:
+
+- `fabric_language === "zh-CN"` → emit the zh-CN variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "en"` → emit the en variant; pure monolingual, no language mixing inside a single user-facing block.
+- `fabric_language === "zh-CN-hybrid"` → emit Chinese narrative prose with English technical terms preserved. Protected tokens (always EN): MCP tool names (e.g. `fab_get_knowledge_sections`), CLI command names (e.g. `fab install`), file paths, technical concepts (`Skill`, `SessionStart`, `hook`, `MCP`, `revision_hash`, `pending`, `proven`, `verified`, `draft`).
+- `fabric_language === "match-existing"` or any other value → emit the en variant; pure monolingual.
+
+Protected tokens (`fab_review`, `relevance_scope`, `relevance_paths`,
+`narrow`, `broad`, `source_sessions`, `proposed_reason`, `session_context`,
+`pending_path`, `layer`, `team`, `personal`, `knowledge_scope_degraded`,
+`MUST`, `NEVER`, `.fabric/knowledge/`, etc.) are NEVER translated — they
+appear verbatim in both language variants. The bilingualization scope is
+prose ONLY.
+
+### AskUserQuestion i18n Policy (value vs label)
+
+When this skill issues an `AskUserQuestion`, the `header` and `question`
+strings are user-facing prose → translated per `fabric_language`. The
+`options[]` array entries are **routing keys** consumed by the skill
+state machine — they MUST remain English regardless of `fabric_language`.
+
+Canonical options arrays used by this skill (every value below stays
+English in BOTH language variants):
+
+- Per-item action: `["approve", "reject", "modify", "defer", "skip"]`
+- Per-stale-item action (health mode): `["defer", "demote", "skip"]`
+- Layer-flip target: `["team", "personal"]`
+- Modify-extended (import-origin narrow-scope nudge):
+  `["narrow scope", "edit summary", "change layer", "change maturity", "skip"]`
+
+Worked example — per-item action (the most common AskUserQuestion in this skill):
+
+```ts
+// EN (fabric_language === "en")
+AskUserQuestion({
+  header: "Review pending entry",
+  question: "What action for '{title}'?  ({pending_path})",
+  options: ["approve", "reject", "modify", "defer", "skip"]
+})
+
+// zh-CN (fabric_language === "zh-CN")
+AskUserQuestion({
+  header: "审核 pending 条目",
+  question: "对 '{title}' 执行什么操作？({pending_path})",
+  options: ["approve", "reject", "modify", "defer", "skip"]   // 不翻译 — routing key
+})
+```
+
+Worked example — layer-flip target:
+
+```ts
+// EN
+AskUserQuestion({
+  header: "Layer-flip target",
+  question: "Move '{title}' to which layer?  (current: {current_layer})",
+  options: ["team", "personal"]
+})
+
+// zh-CN
+AskUserQuestion({
+  header: "Layer 切换目标",
+  question: "将 '{title}' 切换到哪一层？(当前: {current_layer})",
+  options: ["team", "personal"]   // 不翻译 — routing key
+})
+```
+
+Rationale: localizing routing keys would force every routing branch to
+dual-string match (e.g. `if (choice === "approve" || choice === "通过")`),
+which doubles the surface area for protected-token regressions and breaks
+the option-list invariants that downstream tooling (the Skill's own
+`switch` statements over `choice`, plus any future MCP-level audit lint
+that scans for these specific string literals) depends on. Keeping
+`options[]` English-only is contract-locked across all three skills.
+

package/templates/skills/fabric-review/ref/worked-examples.md

@@ -0,0 +1,95 @@
+# Worked Examples — fabric-review full reference
+
+> **Loaded on demand.** Four end-to-end mode walkthroughs (pending dedupe / revisit layer-flip / health mode / narrowing imported entries). SKILL.md gives the operative contract; load these to see how Mode + AskUserQuestion + MCP-call shape composes on real candidates.
+
+## Worked Examples
+
+## Example A — pending mode with semantic check flagging a duplicate (user chooses reject)
+
+User: "review the pending knowledge".
+
+Inferred mode: `pending` (Step 1 keyword "review … pending").
+
+Skill flow:
+
+1. `fab_review action="list"` → returns 3 pending items.
+2. Semantic check on item 2 (`pending/decisions/single-cjs-hook.md`) — `fab_review action="search"` with `query="single cjs hook"` filter `type=decisions` returns canonical `KT-D-0007--single-cjs-hook-across-clients.md` (similarity high).
+3. Display block:
+
+   ```md
+   ## [type=decisions] [layer=team] pending_path=knowledge/pending/decisions/single-cjs-hook.md
+   Title: 单 .cjs hook 跨客户端
+   Summary: 三客户端 stdout JSON 格式一致，单脚本即可。
+   ⚠ Possible duplicate of KT-D-0007 (LLM 主观判断 dup/subsumption；具体阈值不可量化)
+   ```
+
+4. AskUserQuestion fires; user picks `reject`.
+5. Free-text follow-up: user types `duplicate of KT-D-7`.
+6. `fab_review action="reject"` with `pending_paths=["knowledge/pending/decisions/single-cjs-hook.md"]` and `reason="duplicate of KT-D-7"`.
+7. Roll-up reports: 1 rejected, 0 approved, events appended.
+
+### Example B — revisit mode with layer flip (KT → KP)
+
+User: "look at KT-G-3, that's actually personal not team".
+
+Inferred mode: `revisit` (Step 1 keyword "look at <id>").
+
+Skill flow:
+
+1. Read `.fabric/knowledge/team/guidelines/KT-G-0003--indent-style.md`. Display body to user.
+2. AskUserQuestion `{options: ["approve", "modify", "reject", "skip"]}` — user picks `modify`.
+3. Skill detects user-stated intent "actually personal not team" — surface AskUserQuestion `{options: ["team", "personal"]}` with current layer=team noted; user confirms `personal`.
+4. Call:
+
+   ```ts
+   mcp__fabric__fab_review({
+     action: "modify",
+     pending_path: "knowledge/team/guidelines/KT-G-0003--indent-style.md",
+     changes: { layer: "personal" }
+   })
+   ```
+
+5. Server returns `{prior_stable_id: "KT-G-0003", new_stable_id: "KP-G-0001"}`.
+6. Roll-up: `Layer flipped: KT-G-0003 → KP-G-0001`. `git status` shows the rename across layer roots.
+
+### Example C — health mode finding stale entries (defer 2, demote 1)
+
+User: "anything stale in our knowledge base?"
+
+Inferred mode: `health` (Step 1 keyword "stale").
+
+Skill flow:
+
+1. `fab_review action="list"` (no filter) + tail events.jsonl for trailing-30d demoted/layer_changed counts.
+2. Compute stale candidates: 3 pending entries with mtime >14d (KP-G-5 candidate-pending, KT-P-9 candidate-pending, KP-G-3 canonical draft with no evidence-append in 21d).
+3. Render dashboard then loop per stale item.
+4. Per-item AskUserQuestion fires:
+   - KP-G-5 → user picks `defer` (until="2026-06-01") → `fab_review action="defer"` with `until` set.
+   - KT-P-9 → user picks `defer` (no until) → `fab_review action="defer"` with no `until`.
+   - KP-G-3 → user picks `demote` → `fab_review action="modify"` with `changes.maturity="draft"` (already draft; equivalently demote means reject if pending — skill chooses correct action by inspecting current state).
+5. Roll-up: 2 deferred, 1 modified, events appended (`knowledge_deferred ×2`, `knowledge_promote_started/promoted` not relevant; `knowledge_layer_changed` not relevant).
+
+### Example D — narrowing an imported decision
+
+User: "review the pending knowledge".
+
+Inferred mode: `pending`. Skill lists 5 pending entries; entry 3's frontmatter 
+shows `source_sessions[0] = "fabric-import-2026-05-10"` → import-origin.
+
+Display block prepends warning line. User picks `modify` on entry 3.
+AskUserQuestion fires with extended options including `narrow scope`.
+User picks `narrow scope`; free-text follow-up: 
+`packages/server/src/retry/**, packages/server/src/lib/retry.ts`
+
+Skill calls:
+
+mcp__fabric__fab_review({
+  action: "modify",
+  pending_path: "knowledge/pending/decisions/<slug>.md",
+  changes: {
+    relevance_scope: "narrow",
+    relevance_paths: ["packages/server/src/retry/**", "packages/server/src/lib/retry.ts"]
+  }
+})
+
+Roll-up confirms `relevance_scope: narrow` written to frontmatter.