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

package/dist/{chunk-XEGXQOOJ.js → chunk-PNRWNUFX.js}

@@ -148,6 +148,7 @@ async function installFabricArchiveSkill(projectRoot, _options = {}) {
   for (const target of targets) {
     results.push(await copyTextIdempotent("skill", source, target));
   }
+  results.push(...await installSkillRefFiles(projectRoot, "fabric-archive"));
   return results;
 }
 async function installFabricReviewSkill(projectRoot, _options = {}) {
@@ -157,6 +158,7 @@ async function installFabricReviewSkill(projectRoot, _options = {}) {
   for (const target of targets) {
     results.push(await copyTextIdempotent("skill-review", source, target));
   }
+  results.push(...await installSkillRefFiles(projectRoot, "fabric-review"));
   return results;
 }
 async function installFabricImportSkill(projectRoot, _options = {}) {
@@ -166,6 +168,67 @@ async function installFabricImportSkill(projectRoot, _options = {}) {
   for (const target of targets) {
     results.push(await copyTextIdempotent("skill-import", source, target));
   }
+  results.push(...await installSkillRefFiles(projectRoot, "fabric-import"));
+  return results;
+}
+async function installSkillRefFiles(projectRoot, skillSlug) {
+  let refTemplateDir;
+  try {
+    refTemplateDir = findTemplatePath(`skills/${skillSlug}/ref`);
+  } catch {
+    return [
+      {
+        step: "skill-ref",
+        path: `skills/${skillSlug}/ref`,
+        status: "skipped",
+        message: `no-ref-dir: ${skillSlug}`
+      }
+    ];
+  }
+  let refFiles;
+  try {
+    refFiles = readdirSync(refTemplateDir).filter((name) => name.endsWith(".md"));
+  } catch {
+    return [
+      {
+        step: "skill-ref",
+        path: refTemplateDir,
+        status: "skipped",
+        message: `no-ref-files: ${skillSlug}`
+      }
+    ];
+  }
+  if (refFiles.length === 0) {
+    return [
+      {
+        step: "skill-ref",
+        path: refTemplateDir,
+        status: "skipped",
+        message: `no-ref-files: ${skillSlug}`
+      }
+    ];
+  }
+  const clientPrefixes = [".claude", ".codex"];
+  const results = [];
+  for (const refFile of refFiles) {
+    const sourcePath = join2(refTemplateDir, refFile);
+    let source;
+    try {
+      source = readFileSync2(sourcePath, "utf8");
+    } catch (error) {
+      results.push({
+        step: "skill-ref",
+        path: sourcePath,
+        status: "error",
+        message: error instanceof Error ? error.message : String(error)
+      });
+      continue;
+    }
+    for (const prefix of clientPrefixes) {
+      const target = join2(projectRoot, prefix, "skills", skillSlug, "ref", refFile);
+      results.push(await copyTextIdempotent("skill-ref", source, target));
+    }
+  }
   return results;
 }
 async function installArchiveHintHook(projectRoot, _options = {}) {

package/dist/index.js

@@ -11,10 +11,10 @@ import { defineCommand, runMain } from "citty";
 
 // src/commands/index.ts
 var allCommands = {
-  install: () => import("./install-UJOFZUYF.js").then((module) => module.default),
+  install: () => import("./install-MPSTI654.js").then((module) => module.default),
   doctor: () => import("./doctor-ZIQXN2T2.js").then((module) => module.default),
   serve: () => import("./serve-U3TPWDOB.js").then((module) => module.default),
-  uninstall: () => import("./uninstall-O3PXESM2.js").then((module) => module.default),
+  uninstall: () => import("./uninstall-VLLJG7JT.js").then((module) => module.default),
   config: () => import("./config-5CH4EJQ2.js").then((module) => module.default),
   "plan-context-hint": () => import("./plan-context-hint-CXTLNVSV.js").then((module) => module.default),
   // v2.0.0-rc.23 TASK-014 (F8c): S5 onboard-slot coverage. Used by the
@@ -26,7 +26,7 @@ var allCommands = {
 var main = defineCommand({
   meta: {
     name: "fabric",
-    version: "2.0.0-rc.27",
+    version: "2.0.0-rc.28",
     description: t("cli.main.description")
   },
   subCommands: allCommands

package/dist/{install-UJOFZUYF.js → install-MPSTI654.js}

@@ -18,7 +18,7 @@ import {
   writeCodexBootstrapManagedBlock,
   writeCursorBootstrapManagedBlock,
   writeFabricAgentsSnapshot
-} from "./chunk-XEGXQOOJ.js";
+} from "./chunk-PNRWNUFX.js";
 import {
   detectClientSupports
 } from "./chunk-MF3OTILQ.js";
@@ -1348,7 +1348,7 @@ function readProjectName(target) {
   return basename(target);
 }
 function getCliVersion() {
-  return true ? "2.0.0-rc.27" : "unknown";
+  return true ? "2.0.0-rc.28" : "unknown";
 }
 function sortRecord(record) {
   return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left.localeCompare(right)));

package/dist/{uninstall-O3PXESM2.js → uninstall-VLLJG7JT.js}

@@ -7,7 +7,7 @@ import {
   HOOK_SCRIPT_DESTINATIONS,
   SKILL_DESTINATIONS,
   fabricAgentsSnapshotPath
-} from "./chunk-XEGXQOOJ.js";
+} from "./chunk-PNRWNUFX.js";
 import {
   detectClientSupports,
   resolveClients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "2.0.0-rc.27",
+  "version": "2.0.0-rc.28",
   "type": "module",
   "bin": {
     "fab": "dist/index.js",
@@ -20,8 +20,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "2.0.0-rc.27",
-    "@fenglimg/fabric-shared": "2.0.0-rc.27"
+    "@fenglimg/fabric-server": "2.0.0-rc.28",
+    "@fenglimg/fabric-shared": "2.0.0-rc.28"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

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

@@ -32,7 +32,7 @@ This skill is `Check-not-Ask`, not a preference interview:
 
 ## 执行流程 (6 Phase / 1 User Review Round)
 
-### Phase -0.5 — Range Resolution (rc.25 E4 Entry Foundation)
+### Phase -0.5 — Range Resolution
 
 When the skill is invoked, the user's prompt may carry an explicit range hint —
 a time window (`今日` / `last week`), a topic keyword (`rc.20`, `cite policy`),
@@ -252,83 +252,16 @@ 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 `# Archive Review — N candidates` batch
-   review block (one per candidate) AND any final session summary the
-   skill emits after Phase 2 completes. zh-CN ↔ en mirror.
-2. **Errors / Preconditions warnings** — abort + gate-fail messages (e.g.
-   the "没有触发归档信号…" trigger-miss and the "本次会话为常规执行…"
-   viability-gate-FAIL message). zh-CN ↔ en mirror.
-3. **Confirmation prompts** — the per-candidate `Confirm? (Y to accept,
-   edit … inline, N to skip)` line in the batch review template. zh-CN
-   ↔ en mirror.
-4. **Dry-run table headers** — v2.0.0-rc.27 TASK-007 added a dry-run
-   override path (see Phase 2.5 "dry-run") so users can preview the
-   archive proposal without writing pending entries. The dry-run summary
-   header and per-candidate preview labels MUST be bilingualized per
-   this policy. zh-CN ↔ en mirror.
-5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
-   zh-CN ↔ en mirror. fabric-archive itself does not surface
-   AskUserQuestion in the current contract (Phase 1 batch review is a
-   single markdown screen, not a structured question), but if a future
-   version adds one — e.g. to confirm layer flip — 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`, `relevance_scope`,
-`relevance_paths`, `narrow`, `broad`, `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/`, the verbatim
-`强 team` / `强 personal` / `默认 team` heuristic block, 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, or `["team", "personal"]` for a layer-flip target) are
-**routing keys** consumed by the skill state machine — they MUST remain
-English regardless of `fabric_language`.
+### UX i18n Policy
 
-```ts
-// EN (fabric_language === "en")
-AskUserQuestion({
-  header: "Layer-flip target",
-  question: "Move '{title}' to which layer? (current: {current_layer})",
-  options: ["team", "personal"]
-})
+Read `.fabric/fabric-config.json` → `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`). Emit all user-facing prose in the resolved variant. Protected tokens (MCP tool names like `fab_extract_knowledge`, schema fields like `relevance_scope`, the verbatim `强 team` / `强 personal` / `默认 team` heuristic block) are NEVER translated.
 
-// zh-CN (fabric_language === "zh-CN")
-AskUserQuestion({
-  header: "Layer 切换目标",
-  question: "将 '{title}' 切换到哪一层？(当前: {current_layer})",
-  options: ["team", "personal"]   // 不翻译 — routing key
-})
-```
+`AskUserQuestion` policy: `header` + `question` translate; `options[]` are routing keys — stay English regardless of locale.
 
-Rationale: localizing routing keys would force every routing branch to
-dual-string match (e.g. `if (choice === "team" || 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.
+**For the full 5-class taxonomy + edge cases:** `Read packages/cli/templates/skills/fabric-archive/ref/i18n-policy.md` (or `.claude/skills/fabric-archive/ref/i18n-policy.md` post-install).
 
-### Phase 0.0 — Collect Cross-Session Digests (v2.0.0-rc.7 T5)
+
+### Phase 0.0 — Collect Cross-Session Digests
 
 Before any single-session collection or viability gating, stitch together
 context from every session that has accumulated since the last
@@ -459,219 +392,11 @@ events), treat all sessions as never-attempted (current default behavior) —
 step 4.5 rule (e) applies uniformly, so the filter degrades to the legacy
 "scan everything since anchor" semantics without raising errors.
 
-### Phase 0.4 — First-run Onboard Phase (rc.23 F8c)
-
-#### Phase 0.4 Trigger Gate (rc.25 — entry-context aware)
-
-Before running ANY of the onboard coverage steps below, evaluate the
-**entry-context gate**. Onboard slot collection is an interactive,
-one-time project-tone capture flow that REQUIRES live user dialogue.
-Non-user-active entries (hook / AI self-trigger / cron) either interrupt
-the user mid-work or run unattended where dialogue is impossible, so
-they MUST skip Phase 0.4 entirely and fall through to Phase 0.
-
-Read `context.entry_point` — already determined in **Phase -0.5 Range
-Resolution** (see TASK-04 / Phase -0.5 section above). The 5-entry model
-is the canonical taxonomy for this gate.
-
-##### Entry-context detection rules
-
-| Entry | Symbol | Detection rule (LLM-native, evaluated at skill entry) |
-|-------|--------|-------------------------------------------------------|
-| **E1** | `hook_passive` | stdout JSON `{decision:'block', ...}` from `archive-hint.cjs` detected at skill entry (the Stop-hook reminder path). |
-| **E2** | `explicit_user_invoke` | User prompt is a direct invocation: `fabric archive` / `/fabric-archive` / `archive what we just did` / `归档一下` / similar imperative. |
-| **E3** | `ai_self_trigger` | AI internal marker `self-archive policy triggered by signal: <X>` present (substring match on the verbatim prefix `self-archive policy triggered by signal`; `<X>` is one of the 4 self-trigger signals from AGENTS.md E3 section: `Normative` / `Wrong-turn-and-revert` / `Decision confirmation` / `Explicit dismissal`). |
-| **E4** | `user_range_rollback` | Prompt contains a **range hint** (parsed in Phase -0.5 — e.g. `今日` / `上周` / `rc.20`) AND the user is invoking. Sub-mode of E2. |
-| **E5** | `cron` | Prompt contains literal `今日复盘` / `daily recap` / `daily-archive` AND no human is present (running under `/loop`, OS cron, or scheduled trigger). |
-
-##### Gate decision
-
-```
-IF context.entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback}:
-    → gate = PROCEED       # user is live, dialogue is possible
-    → continue to Step 1 (Check coverage) below
-ELSE (E1_hook_passive | E3_ai_self_trigger | E5_cron):
-    → gate = SKIP           # no live user, onboard prompting would misfire
-    → emit one-line log: "Phase 0.4 skipped (entry=<E1|E3|E5>, no live user)"
-    → proceed directly to Phase 0
-```
-
-##### Rationale
-
-Onboard slot collection is a one-time project-tone capture flow that
-requires user dialogue. Non-user-active entries (hook / AI / cron)
-interrupt the user mid-work or run unattended where dialogue is
-impossible, so they MUST skip Phase 0.4. The S5 slot semantics
-(`tech-stack-decision`, `architecture-pattern`, ...) are user-validated
-baselines — populating them from a hook fire-and-forget or a cron daily
-recap would defeat the purpose of capturing _user-confirmed_ project
-tone.
-
-##### Tradeoff (documented in CHANGELOG)
-
-A first-time user whose ONLY invocations ever come via hook (never an
-explicit `/fabric-archive`) will not see the onboard prompt; the 5
-onboard slots remain empty. Mitigation: documentation tells users to
-run an explicit `fab archive` at least once to populate the onboard
-baseline.
-
-##### Worked example
-
-```
-$ /loop 24h /fabric-archive 今日复盘
-  → cron context, no live user
-  → Phase -0.5 detects literal "今日复盘" + no-human marker
-  → context.entry_point = E5_cron
-  → Phase 0.4 Trigger Gate evaluates: E5 ∉ {E2, E4} → SKIP
-  → emit log "Phase 0.4 skipped (entry=E5, no live user)"
-  → proceed directly to Phase 0 (collect candidates for daily window)
-```
-
-Contrast with E2:
-
-```
-$ /fabric-archive
-  → user typed explicit invocation
-  → Phase -0.5: context.entry_point = E2_explicit_user_invoke
-  → Phase 0.4 Trigger Gate evaluates: E2 ∈ {E2, E4} → PROCEED
-  → run Step 1 (Check coverage) below
-```
-
----
-
-After F8a removed the auto-`fab scan` baseline pipeline, a freshly installed
-Fabric workspace ships with an EMPTY `.fabric/knowledge/` tree. Five fixed
-**S5 onboard slots** capture the "project tone" baseline that the AI needs
-for high-quality plan_context retrieval from day one:
-
-- `tech-stack-decision` — primary languages / frameworks / runtime stack
-- `architecture-pattern` — module layout, service boundaries, layering rules
-- `code-style-tone` — naming / formatting / idiom conventions the project enforces
-- `build-system-idiom` — build tool quirks, scripts, deploy pipeline shape
-- `domain-vocabulary` — business / product terminology that names code entities
-
-This phase runs ONCE per archive-skill invocation, BEFORE Phase 0 evidence
-gathering, so coverage state is fresh for the session.
-
-#### Step 1 — Check coverage
-
-Invoke `fab onboard-coverage --json` and parse the JSON payload:
-
-```bash
-fab onboard-coverage --json
-```
-
-Expected shape:
-
-```json
-{
-  "filled":    { "tech-stack-decision": ["KT-DEC-0012"], ... },
-  "missing":   ["architecture-pattern", "code-style-tone"],
-  "opted_out": ["domain-vocabulary"],
-  "total": 5
-}
-```
-
-#### Step 2 — Decide
-
-```
-IF missing.length === 0:
-    → skip Phase 0.4 entirely; proceed to Phase 0.
-ELSE:
-    → ask the user how to handle the missing slots (Step 3).
-```
-
-#### Step 3 — Prompt user
-
-Present a single roll-up listing each missing slot. UX i18n Policy class 5
-applies: the `header` + `question` strings are translated per
-`fabric_language`; the `options[]` routing keys stay English.
-
-```ts
-AskUserQuestion({
-  header: "Onboard coverage",  // zh-CN: "首装基调覆盖"
-  question:
-    "KB is missing the following project-tone slots: " +
-    missing.join(", ") +
-    ". Tour the project and propose pending entries for each?",
-  options: ["fill-all", "fill-each", "dismiss-all", "skip"]
-})
-```
-
-`fab_extract_knowledge` is called with `onboard_slot: <slot>` set so each
-proposed entry counts toward coverage once approved via fab_review.
-
-| User choice    | Action |
-|----------------|--------|
-| `fill-all`     | For EACH slot in `missing`, run Step 4 (Tour-and-propose). All proposals share session_id; one batch review at the end (Phase 1). |
-| `fill-each`    | Loop slot-by-slot through `missing`. Per slot: ask user `confirm | dismiss | skip` (per-slot AskUserQuestion); `confirm` → run Step 4; `dismiss` → `fab config dismiss-slot <slot>`; `skip` → leave for next archive run. |
-| `dismiss-all`  | For EACH slot in `missing`, invoke `Bash("fab config dismiss-slot <slot>")`. Print a one-line confirmation each. Skip to Phase 0. |
-| `skip`         | No-op. Slots remain in `missing` for the next archive run. Skip to Phase 0. |
+### Phase 0.4 — First-run Onboard (ref-only)
 
-#### Step 4 — Tour-and-propose (per-slot)
+**SKIP this phase entirely unless** entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND a fresh `fab onboard-coverage --json` reports `missing.length > 0`. For E1 (hook), E3 (AI self-trigger), and E5 (cron), onboard is non-applicable — silently fall through to Phase 0.
 
-For each slot to fill, the LLM independently sources slot-specific evidence
-from the project (no user prompt — this is a Read-only tour):
-
-| Slot                     | Source files (LLM should Read these) |
-|--------------------------|---------------------------------------|
-| `tech-stack-decision`    | `package.json` (+ lockfile), `pyproject.toml` / `Cargo.toml` / `go.mod`, `tsconfig.json`, root README |
-| `architecture-pattern`   | Top-level dir tree (`ls -F`), 1-2 entry-point files (`src/index.ts`, `main.go`, etc.), framework-config files (`next.config`, `vite.config`, `astro.config`) |
-| `code-style-tone`        | `.editorconfig`, `prettier.config.*`, `eslint.config.*`, `biome.*`, `.prettierrc*`, framework lint config, 2-3 representative source files for naming-pattern inference |
-| `build-system-idiom`     | `package.json` `scripts` block, `Makefile`, `taskfile.yaml`, CI yml (`.github/workflows/*.yml`), Dockerfile if present |
-| `domain-vocabulary`      | README, `docs/*.md`, top-level `src/` directory names (often domain-aligned), public API entry types |
-
-After Read-ing the slot-specific sources, classify the observation:
-
-- `tech-stack-decision` → type=`decisions`, `proposed_reason=decision-confirmation`
-- `architecture-pattern` → type=`models`, `proposed_reason=new-dependency-or-pattern`
-- `code-style-tone` → type=`guidelines`, `proposed_reason=explicit-user-mark` (the project ITSELF is the mark)
-- `build-system-idiom` → type=`processes`, `proposed_reason=new-dependency-or-pattern`
-- `domain-vocabulary` → type=`models`, `proposed_reason=new-dependency-or-pattern`
-
-Call `fab_extract_knowledge` with the inferred fields PLUS `onboard_slot:
-<slot>`. The pending file's frontmatter will carry the slot label, and the
-next `fab onboard-coverage` run will see the slot as filled (once approved
-via fab_review).
-
-Example:
-
-```ts
-mcp__fabric__fab_extract_knowledge({
-  source_sessions: ["<current-session-id>"],
-  recent_paths: ["package.json", "tsconfig.json"],
-  user_messages_summary: "Project uses TypeScript + pnpm workspace + Vitest. Node 20 LTS target. ESM-only.",
-  type: "decisions",
-  slug: "primary-tech-stack",
-  layer: "team",
-  relevance_scope: "broad",        // tech stack applies everywhere
-  relevance_paths: [],
-  proposed_reason: "decision-confirmation",
-  session_context:
-    "Session goal: capture onboard tech-stack baseline.\nTurning point: read package.json + tsconfig.json + pnpm-workspace.yaml; stack confirmed.",
-  onboard_slot: "tech-stack-decision",    // ← claims the slot
-  tech_stack: ["typescript", "nodejs", "pnpm", "vitest"]
-})
-```
-
-#### Onboard phase constraints (DO NOT TRANSLATE)
-
-- MUST run BEFORE Phase 0 evidence gathering — onboard is a separate flow,
-  not interleaved with session-archive candidates.
-- MUST call `fab onboard-coverage --json` before deciding; never assume
-  coverage state.
-- NEVER fill a slot that is in `opted_out` — `fab onboard-coverage` already
-  excludes those from `missing`, but the Skill MUST NOT re-propose them
-  even if the user asks "fill all of them" — the dismiss is intentional.
-- NEVER prompt the user when `missing.length === 0` — silent skip.
-- NEVER set `onboard_slot` on a regular session-archive candidate in
-  Phase 2 — that field is RESERVED for the onboard phase. Mixing the
-  two would let session-archive proposals masquerade as onboard
-  coverage and let any random pending file claim a slot.
-- MUST emit `onboard_slot: <slot>` verbatim — the slot name is one of
-  the locked S5 strings (tech-stack-decision / architecture-pattern /
-  code-style-tone / build-system-idiom / domain-vocabulary). The
-  fab_extract_knowledge schema enum will reject anything else.
+When the gate above does fire (live user + missing slots), `Read packages/cli/templates/skills/fabric-archive/ref/phase-0-4-onboard.md` (or `.claude/skills/fabric-archive/ref/phase-0-4-onboard.md` post-install) for the full Step 1-4 (coverage check → user prompt → tour-and-propose) procedure.
 
 ### Phase 0 — Collect Candidates
 
@@ -1213,132 +938,12 @@ Next day's cron rescan: Phase 0.0 sees `covered_through_ts < max(ts of session's
 - NEVER paraphrase the verbatim layer heuristic block above — the Chinese text is contract-locked.
 - MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `.fabric/knowledge/pending/`, `fab_extract_knowledge`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`.
 
-## Worked Examples
-
-### Example 1 — decision (team)
-
-Session: User and agent debated whether the Stop-hook should be one .cjs script or three per-client scripts. Settled on one because stdout JSON shape `{"decision":"block","reason"}` is identical across Claude / Codex.
-
-Skill output:
-
-```ts
-mcp__fabric__fab_extract_knowledge({
-  source_sessions: ["WFS-2026-05-10-rc2"],
-  recent_paths: ["templates/claude-hooks/", "packages/cli/src/commands/hooks.ts"],
-  user_messages_summary: "User pushed back on three-script proposal; agreed single .cjs because stdout JSON shape is universal across Claude Code and Codex CLI.",
-  type: "decisions",
-  slug: "single-cjs-hook-script",
-  layer: "team",
-  relevance_scope: "narrow",
-  relevance_paths: [
-    "templates/claude-hooks/**/*.cjs",
-    "packages/cli/src/commands/hooks.ts"
-  ],
-  proposed_reason: "decision-confirmation",
-  session_context: "Session goal: ship Stop-hook for v2 release.\nTurning point: user rejected 3-script proposal after seeing identical stdout JSON across Claude / Codex.\nResult: single .cjs path locked in."
-})
-```
-
-Layer = team (引用本项目代码 + fabric-import 路径产物 signals). Scope = narrow (tied to hook templates + hooks command module; single-module evidence in edit_paths).
-
-### Example 2 — pitfall (team)
-
-Session: deepMerge silently replaced the existing `hooks.Stop[]` array in `.claude/settings.json` instead of appending. Cost ~30 min to diagnose.
-
-Skill output:
-
-```ts
-mcp__fabric__fab_extract_knowledge({
-  source_sessions: ["WFS-2026-05-10-rc2"],
-  recent_paths: ["packages/cli/src/config/json.ts"],
-  user_messages_summary: "deepMerge default behavior REPLACES arrays. hooks.Stop[] needs an array-append-with-dedupe special case keyed on .command string match.",
-  type: "pitfalls",
-  slug: "deepmerge-array-replace-trap",
-  layer: "team",
-  relevance_scope: "broad",
-  relevance_paths: [],
-  proposed_reason: "diagnostic-then-fix",
-  session_context: "Session goal: wire hook installer for v2.\nTurning point: spent ~30 min chasing why prior Stop[] entries vanished — root cause was deepMerge replacing arrays silently.\nResult: array-append-with-dedupe special case added."
-})
-```
-
-Layer = team (绑定本项目代码的 pitfall signal). Scope = broad (deepMerge gotcha is cross-cutting — applies anywhere JSON merge is used, not just `json.ts`).
-
-### Example 3 — guideline (personal)
-
-Session: User mentioned across three projects that they prefer 2-space indent in TypeScript and 4-space in Python.
-
-Skill output:
-
-```ts
-mcp__fabric__fab_extract_knowledge({
-  source_sessions: ["WFS-2026-05-10-rc2"],
-  recent_paths: [".editorconfig"],
-  user_messages_summary: "Personal indent preference: 2-space TS / 4-space Py. Stable across multiple projects, not project-specific.",
-  type: "guidelines",
-  slug: "indent-style-by-language",
-  layer: "personal",
-  relevance_scope: "broad",
-  relevance_paths: [],
-  proposed_reason: "explicit-user-mark",
-  session_context: "Session goal: align editor config.\nTurning point: user said '一直 prefer 2-space TS / 4-space Py，across projects'.\nResult: personal-layer guideline; not bound to this project."
-})
-```
-
-Layer = personal (跨项目通用 + 工具/编辑器偏好 signals dominate; no 强 team signal applies). Scope = broad with `relevance_paths=[]` (personal layer ALWAYS forces broad — paths don't generalize across projects per Phase 1.5 special case).
-
-## E5 周期触发 (Scheduled Daily Recap)
-
-### Overview
-
-`今日复盘` = E5 entry point. Default scope = today. Falls back to historical scan if today yields no candidates (silent-skip per Phase 2.5).
-
-E5 是 5 入口模型中唯一由 OS 调度器或 Claude Code `/loop` 周期触发的入口形态。fab 端**零代码**——不提供 `fab schedule` 子命令,亦不内嵌 daemon。用户基于自己的执行环境二选一接入: `/loop`(Claude Code 原生,推荐) 或 OS cron(跨平台 fallback)。
-
-### /loop sample (primary path for Claude Code)
-
-```
-/loop /fabric-archive 今日复盘 --cron "0 23 * * *"
-```
-
-每晚 23:00 在当前 Claude Code session 中触发 fabric-archive skill,scope = today。`/loop` 复用现有 Claude session 鉴权,无需独立 token。
-
-### OS cron sample (cross-platform alternative)
-
-```
-# crontab -e
-0 23 * * * cd /path/to/project && claude code -p "/fabric-archive 今日复盘" 2>&1 >> /var/log/fabric-daily-recap.log
-```
-
-适用于:
-- 非 Claude Code 环境(纯 server / CI 节点)
-- 希望脱离 /loop session 生命周期独立运行的场景
-- 已有 cron / launchd 调度基础设施的团队
-
-macOS 用户可改用 `launchd` plist;Linux 用户直接 `crontab -e`。命令需自行确保 `claude code` CLI 已安装且鉴权可用。
-
-### E5 prompt parse contract
-
-当用户或 cron 以 `今日复盘` / `daily recap` 字面短语触发 fabric-archive 时,skill 应按以下契约处理:
-
-- **Phase -0.5 Range Resolution**: 识别 `今日复盘` / `daily recap` 为 magic phrase, 直接设置 `time_window = today` (00:00 local timezone → current ts), 无需 AskUserQuestion 兜底。
-- **Phase 0.4 Onboard Coverage**: 跳过 (entry_point = E5_cron, 非 E2_explicit, 不弹 onboard 弹问)。
-- **Phase 2.5 Persist Archive Attempt**: 始终写入 `session_archive_attempted` event。当今日无 archive 信号触发 viability gate FAIL 时,走 silent-skip 路径(outcome = `skipped_no_signal`),skill 静默退出,cron 日志为空。
-
-### Trade-off table (/loop vs OS cron)
-
-| 维度 | /loop | OS cron |
-|---|---|---|
-| 鉴权 | 复用 Claude session | 独立 token / login |
-| 跨平台 | Claude Code 全平台一致 | macOS launchd / Linux cron 不同 |
-| Token 成本 | 累积 (长 session) | 每 tick fresh, 无累积 |
-| 调试 | Claude UI 可见 | 日志文件 |
+## Worked Examples (ref-only)
 
-### Failure modes
+Three end-to-end fab_extract_knowledge call examples (decision/team, pitfall/team, guideline/personal) live in `packages/cli/templates/skills/fabric-archive/ref/worked-examples.md` (or `.claude/skills/fabric-archive/ref/worked-examples.md` post-install). Load when you want to see all required + optional fields populated together in a realistic shape.
 
-- **/loop session crash**: 归档暂停,用户需重启 `/loop`。无自动恢复机制——`/loop` 与 Claude Code session 生命周期绑定。
-- **OS cron**: 自带恢复(下一个 tick 重新启动),但需独立 `claude code` CLI 安装与鉴权;鉴权 token 过期时 cron job 会静默失败,需人工 `claude login` 重置。
+## E5 Scheduled Daily Recap (ref-only)
 
-### NOT in scope
+Only relevant when entry_point=E5_cron (OS cron, `/loop`, or scheduled trigger). For interactive invocations, Phase -0.5 has already routed past this — nothing to load.
 
-- fab CLI does NOT provide a cron helper command — keeps fab focused on archive/install, not scheduling infrastructure. 用户自行管理调度器是显式设计决策(参见 Q3.1 入口集 + cli-design 原则"能交互别做 flag, 不做调度器")。
+When E5 fires: `Read packages/cli/templates/skills/fabric-archive/ref/e5-cron-recap.md` (or `.claude/skills/fabric-archive/ref/e5-cron-recap.md` post-install) for `/loop` vs OS cron tradeoffs + the `今日复盘` magic-phrase parse contract.