@fenglimg/fabric-cli 1.6.0 → 1.8.0-rc.1

package/dist/{scan-QH76LC7Z.js → scan-NNBNGIZG.js}

@@ -3,10 +3,8 @@ import {
   createScanReport,
   scanCommand,
   scan_default
-} from "./chunk-QSAEGVKE.js";
-import "./chunk-AEOYCVBG.js";
-import "./chunk-WWNXR34K.js";
-import "./chunk-6ICJICVU.js";
+} from "./chunk-NMMUETVK.js";
+import "./chunk-QPCRBQ5Y.js";
 export {
   createScanReport,
   scan_default as default,

package/dist/{serve-4J2CQY25.js → serve-466QXQ5Q.js}

@@ -1,19 +1,15 @@
 #!/usr/bin/env node
 import {
   createDebugLogger,
-  resolveDevMode
-} from "./chunk-AEOYCVBG.js";
-import {
   paint,
-  symbol
-} from "./chunk-WWNXR34K.js";
-import {
+  resolveDevMode,
+  symbol,
   t
-} from "./chunk-6ICJICVU.js";
+} from "./chunk-QPCRBQ5Y.js";
 
 // src/commands/serve.ts
 import { defineCommand } from "citty";
-import { startHttpServer } from "@fenglimg/fabric-server";
+import { acquireLock, releaseLock, startHttpServer } from "@fenglimg/fabric-server";
 var DEFAULT_PORT = 7373;
 var serveCommand = defineCommand({
   meta: {
@@ -39,6 +35,11 @@ var serveCommand = defineCommand({
       type: "boolean",
       description: t("cli.serve.args.debug.description"),
       default: false
+    },
+    force: {
+      type: "boolean",
+      description: t("cli.serve.args.force.description"),
+      default: false
     }
   },
   async run({ args }) {
@@ -49,6 +50,11 @@ var serveCommand = defineCommand({
     const requestedHost = parseHost(args.host);
     const authToken = readAuthTokenFromEnv();
     const host = validateHost(requestedHost, authToken);
+    const projectRoot = resolution.target;
+    acquireLock(projectRoot, { force: args.force });
+    process.on("exit", () => {
+      releaseLock(projectRoot);
+    });
     logger(`serve target source: ${resolution.source}`);
     for (const step of resolution.chain) {
       logger(step);
@@ -56,14 +62,16 @@ var serveCommand = defineCommand({
     try {
       await startHttpServer({
         port,
-        projectRoot: resolution.target,
+        projectRoot,
         host,
         authToken
       });
     } catch (error) {
       if (isNodeError(error) && error.code === "EADDRINUSE") {
+        releaseLock(projectRoot);
         throw new Error(t("cli.serve.error.port-in-use", { port: String(port), nextPort: String(port + 1) }));
       }
+      releaseLock(projectRoot);
       throw error;
     }
     console.log(`${symbol.ok} ${paint.ai(t("cli.serve.ready.title"))} ${paint.human(`http://${host}:${port}`)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "1.6.0",
+  "version": "1.8.0-rc.1",
   "type": "module",
   "bin": {
     "fab": "dist/index.js",
@@ -14,19 +14,16 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@iarna/toml": "^2.2.5",
     "citty": "^0.2.2",
-    "minimatch": "^10.0.1",
     "picocolors": "^1.1.1",
     "string-width": "^7.2.0",
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "1.6.0",
-    "@fenglimg/fabric-shared": "1.6.0"
+    "@fenglimg/fabric-server": "1.8.0-rc.1",
+    "@fenglimg/fabric-shared": "1.8.0-rc.1"
   },
   "devDependencies": {
-    "@types/iarna__toml": "^2.0.5",
     "@types/node": "^22.15.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3"
@@ -34,6 +31,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
 }

package/templates/agents-md/AGENTS.md.template

@@ -3,10 +3,10 @@
 ## CORE RULES (DO NOT TRANSLATE)
 
 MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
-MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
-MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
-MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
+MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
+MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
 NEVER: Add import-style directive lines to this bootstrap file.
 NEVER: Put framework, domain, repository rule bodies, or submodule rules in this file.
 NEVER: Create colocated `AGENTS.md` rule files under source directories.
@@ -16,6 +16,6 @@ NEVER: Create colocated `AGENTS.md` rule files under source directories.
 - 本文件只负责启动 Fabric Bootstrap Protocol，不承载项目业务规则。
 - 详细 bootstrap 说明位于 `.fabric/bootstrap/README.md`。
 - Detected framework kind: `{ frameworkKind }`.
-- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
-- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
-- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.
+- This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/rules/root.md`；跨领域规则应放在 `.fabric/rules/_cross/`。
+- If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.

package/templates/agents-md/variants/cocos.md

@@ -3,10 +3,10 @@
 ## CORE RULES (DO NOT TRANSLATE)
 
 MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
-MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
-MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
-MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
+MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
+MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
 NEVER: Add import-style directive lines to this bootstrap file.
 NEVER: Put Cocos, asset, prefab, scene, repository rule bodies, or submodule rules in this file.
 NEVER: Create colocated `AGENTS.md` rule files under source directories.
@@ -15,6 +15,6 @@ NEVER: Create colocated `AGENTS.md` rule files under source directories.
 
 - 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Cocos 业务或编辑器规则。
 - Detected framework kind: `cocos-creator`.
-- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
-- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
-- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.
+- This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/rules/root.md`；跨领域规则应放在 `.fabric/rules/_cross/`。
+- If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.

package/templates/agents-md/variants/next.md

@@ -3,10 +3,10 @@
 ## CORE RULES (DO NOT TRANSLATE)
 
 MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
-MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
-MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
-MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
+MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
+MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
 NEVER: Add import-style directive lines to this bootstrap file.
 NEVER: Put Next.js, route, repository rule bodies, or submodule rules in this file.
 NEVER: Create colocated `AGENTS.md` rule files under source directories.
@@ -15,6 +15,6 @@ NEVER: Create colocated `AGENTS.md` rule files under source directories.
 
 - 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Next.js 业务或路由规则。
 - Detected framework kind: `next`.
-- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
-- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
-- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.
+- This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/rules/root.md`；跨领域规则应放在 `.fabric/rules/_cross/`。
+- If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.

package/templates/agents-md/variants/vite.md

@@ -3,10 +3,10 @@
 ## CORE RULES (DO NOT TRANSLATE)
 
 MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
-MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
-MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
-MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
+MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
+MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
 NEVER: Add import-style directive lines to this bootstrap file.
 NEVER: Put Vite, browser, repository rule bodies, or submodule rules in this file.
 NEVER: Create colocated `AGENTS.md` rule files under source directories.
@@ -15,6 +15,6 @@ NEVER: Create colocated `AGENTS.md` rule files under source directories.
 
 - 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Vite 业务或浏览器规则。
 - Detected framework kind: `vite`.
-- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
-- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
-- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.
+- This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/rules/root.md`；跨领域规则应放在 `.fabric/rules/_cross/`。
+- If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.

package/templates/bootstrap/CLAUDE.md

@@ -1,6 +1,8 @@
 # Fabric Bootstrap
 - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
 - 项目级 bootstrap 入口仍然是 `AGENTS.md`。
-- 修改任何文件前必须调用 `fab_get_rules(path=<被改文件>)`。
+- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_rule_sections` 获取规则段落。
+MCP 和 doctor 会写入 `.fabric/events.jsonl`。
+- 规则 baseline 变更通过 `fabric doctor --fix` 接受。
 
 @AGENTS.md

package/templates/bootstrap/GEMINI.md

@@ -1,6 +1,8 @@
 # Fabric Bootstrap
 - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
 - 项目级 bootstrap 入口仍然是 `AGENTS.md`。
-- 修改任何文件前必须调用 `fab_get_rules(path=<被改文件>)`。
+- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_rule_sections` 获取规则段落。
+MCP 和 doctor 会写入 `.fabric/events.jsonl`。
+- 规则 baseline 变更通过 `fabric doctor --fix` 接受。
 
 @AGENTS.md

package/templates/bootstrap/codex-AGENTS-header.md

@@ -1,4 +1,6 @@
 # Fabric Bootstrap
 - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
 - 此 header 仅用于把 Codex 引导到 Fabric 项目级规则入口。
-- 修改任何文件前必须调用 `fab_get_rules(path=<被改文件>)`。
+- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_rule_sections` 获取规则段落。
+MCP 和 doctor 会写入 `.fabric/events.jsonl`。
+- 规则 baseline 变更通过 `fabric doctor --fix` 接受。

package/templates/bootstrap/cursor-fabric-bootstrap.mdc

@@ -3,9 +3,8 @@ alwaysApply: true
 description: Fabric Protocol bootstrap rules
 ---
 
-# Fabric Bootstrap
-- 本项目使用 Fabric Protocol 管理规则。
-- **任何文件修改前**，必须调 MCP tool `fab_get_rules(path=<被改文件>)` 获取规则。
-- 新建 L1/L2 节点时，必须调 `fab_update_registry`，**严禁**直接编辑 `.fabric/agents.meta.json`。
-- 涉及 @HUMAN 段（`.fabric/human-lock.json` 中列出）时，必须停下来请示人类。
-- 每次完整任务结束，调 `fab_append_intent` 写一条意图记录。
+# Fabric Bootstrap
+- 本项目使用 Fabric Protocol 管理规则。
+- **任何文件修改前**，必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`，再调 `fab_get_rule_sections` 获取规则段落。
+- 新建或调整 L1/L2 节点时，修改规则源文件后运行 `fabric doctor --fix` 接受 baseline，**严禁**直接编辑 `.fabric/agents.meta.json`。
+Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。

package/templates/bootstrap/roo-fabric.md

@@ -1,6 +1,5 @@
-# Fabric Bootstrap
-- 本项目使用 Fabric Protocol 管理规则。
-- **任何文件修改前**，必须调 MCP tool `fab_get_rules(path=<被改文件>)` 获取规则。
-- 新建 L1/L2 节点时，必须调 `fab_update_registry`，**严禁**直接编辑 `.fabric/agents.meta.json`。
-- 涉及 @HUMAN 段（`.fabric/human-lock.json` 中列出）时，必须停下来请示人类。
-- 每次完整任务结束，调 `fab_append_intent` 写一条意图记录。
+# Fabric Bootstrap
+- 本项目使用 Fabric Protocol 管理规则。
+- **任何文件修改前**，必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`，再调 `fab_get_rule_sections` 获取规则段落。
+- 新建或调整 L1/L2 节点时，修改规则源文件后运行 `fabric doctor --fix` 接受 baseline，**严禁**直接编辑 `.fabric/agents.meta.json`。
+Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。

package/templates/bootstrap/windsurf-fabric.md

@@ -1,6 +1,5 @@
-# Fabric Bootstrap
-- 本项目使用 Fabric Protocol 管理规则。
-- **任何文件修改前**，必须调 MCP tool `fab_get_rules(path=<被改文件>)` 获取规则。
-- 新建 L1/L2 节点时，必须调 `fab_update_registry`，**严禁**直接编辑 `.fabric/agents.meta.json`。
-- 涉及 @HUMAN 段（`.fabric/human-lock.json` 中列出）时，必须停下来请示人类。
-- 每次完整任务结束，调 `fab_append_intent` 写一条意图记录。
+# Fabric Bootstrap
+- 本项目使用 Fabric Protocol 管理规则。
+- **任何文件修改前**，必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`，再调 `fab_get_rule_sections` 获取规则段落。
+- 新建或调整 L1/L2 节点时，修改规则源文件后运行 `fabric doctor --fix` 接受 baseline，**严禁**直接编辑 `.fabric/agents.meta.json`。
+Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。

package/templates/claude-skills/fabric-init/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: fabric-init
+description: Use this skill when fab init just completed, when forensic.json was generated, or when the user is asking to initialize AGENTS.md. This skill runs a 3-phase initialization interview, writes .fabric/init-context.json, generates layered AGENTS.md, and updates .fabric/agents.meta.json.
+allowed-tools: ["Read", "Write", "Glob", "Grep", "Bash"]
+---
+
+# fabric-init — Canonical Skill Source
+
+> This file is the single source of truth for the fabric-init skill.
+> Do NOT edit the per-client SKILL.md files directly.
+> Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
+
+## Precondition
+
+MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
+exist, stop immediately and tell the user: run `fab init` first to generate the evidence
+package.
+
+MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
+repository appears to have completed initialization already.
+
+MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
+the current repository.
+
+MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
+to do next.
+
+MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
+
+NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
+
+NEVER: Rewrite or translate protected tokens.
+
+NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
+
+Treat the following state as initialization pending:
+
+- `.fabric/forensic.json` exists
+- `.fabric/init-context.json` does not exist
+
+## Execution Flow — 3 Phases / 3 Rounds
+
+### Phase 1 — Framework Confirmation (1 round, efficient)
+
+Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
+`.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
+architecture.
+
+Example (Cocos Creator 3.x):
+
+> I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
+> `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
+> (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
+> `find/getChildByName`?
+
+Store the user's answers as verified framework assumptions before proceeding to Phase 2.
+
+### Phase 2 — Invariant Extraction (1 round, critical)
+
+Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
+3–5 invariant questions covering three categories:
+
+- `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
+- `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
+  decorator, imports only from `cc`
+- `protect`: directories or files that AI must not modify — typically
+  `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
+
+Principles:
+
+- Ask only about invariants, not about preferences.
+- Each question accepts only yes / no / a concrete rule — never accept vague answers.
+- Do not auto-infer hard constraints the user has not confirmed.
+
+### Phase 3 — Construction and Landing (1 round, automated)
+
+#### 3.1 Write `.fabric/init-context.json`
+
+Fields required:
+
+- `framework`
+- `architecture_patterns`
+- `invariants`
+- `domain_groups`
+- `interview_trail`
+- `forensic_ref`
+
+Writing rules:
+
+- `invariants[].type` MUST be one of `ban`, `require`, `protect`.
+- `domain_groups` is inferred from `entry_points` and interview results.
+- `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
+- `forensic_ref` MUST be `.fabric/forensic.json`.
+
+#### 3.2 Generate layered `AGENTS.md`
+
+Root `AGENTS.md` requirements:
+
+- MUST be within 300 lines.
+- Structure:
+  - `# {projectName} — L0 AGENTS.md`
+  - `<!-- fab:index -->`: populated with the `domain_groups` index
+  - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
+  - `## @HUMAN`: protect paths and any human-declared protection rules
+  - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
+
+If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
+Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
+
+#### 3.3 Update `.fabric/agents.meta.json`
+
+- The `nodes` tree MUST match the generated AGENTS hierarchy.
+- Update the hash of every AGENTS.md file that was written.
+- Maintain a consistent internal revision hash chain.
+
+#### 3.4 Final output
+
+List all generated files for the user and recommend running `fabric doctor --fix` for
+ongoing maintenance.
+
+## Hard Rules
+
+- Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
+- No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
+  frontmatter.
+- Root `AGENTS.md` MUST be <= 300 lines.
+- Total AGENTS nesting MUST be <= 4 levels.
+- Do not auto-infer invariants the user has not confirmed.
+- When content is uncertain, omit it — do not leave placeholders.
+
+## Output Contract
+
+On successful completion the following files exist or are updated:
+
+| File | Action |
+|------|--------|
+| `.fabric/init-context.json` | Created with all required fields |
+| `AGENTS.md` | Created (root L0) |
+| `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
+| `.fabric/agents.meta.json` | Updated nodes tree + hashes |
+
+On failure or early termination the skill MUST leave no partial files. If a write fails
+mid-sequence, report the failure and the exact file that was not written.
+
+## Protected Tokens
+
+The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
+never translated:
+
+| Token | Type |
+|-------|------|
+| `AGENTS.md` | Filename |
+| `FABRIC.md` | Filename |
+| `.fabric/agents.meta.json` | Path |
+| `.fabric/init-context.json` | Path |
+| `.fabric/forensic.json` | Path |
+| `.fabric/bootstrap/README.md` | Path |
+| `MUST` | Keyword |
+| `NEVER` | Keyword |
+| `fab init` | CLI command |
+| `fabric doctor --fix` | CLI command |
+| `<!-- fab:index -->` | HTML comment marker |
+| `@HUMAN` | Section marker |

package/templates/codex-skills/fabric-init/SKILL.md

@@ -1,27 +1,162 @@
 ---
 name: fabric-init
-description: Use this skill when `.fabric/forensic.json` exists and this repository still needs the remaining Fabric initialization steps.
+description: Use this skill when .fabric/forensic.json exists and this repository still needs the remaining Fabric initialization steps.
 ---
 
-## Hard Rules (不要翻译受保护 token)
+# fabric-init — Canonical Skill Source
 
-MUST: 先读取 `.fabric/forensic.json`，再做其他动作。
-MUST: 把 `.fabric/bootstrap/README.md` 视为当前仓库的初始化说明。
-MUST: 如果 `.fabric/init-context.json` 已存在，立即停止并报告当前仓库看起来已经完成后续初始化。
-MUST: 使用 `.fabric/forensic.json` 和仓库结构中的依据，判断接下来该做什么。
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `FABRIC.md`, `.fabric/agents.meta.json`, `.fabric/human-lock.json`, `.fabric/init-context.json`, `.fabric/forensic.json`, `MUST`, `NEVER`.
-NEVER: 在没有检查 `.fabric/init-context.json` 的情况下声称初始化已经完成。
-NEVER: 改写或翻译受保护 token。
-NEVER: 在判断下一步初始化动作时忽略 `.fabric/bootstrap/README.md`。
+> This file is the single source of truth for the fabric-init skill.
+> Do NOT edit the per-client SKILL.md files directly.
+> Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
 
-## Purpose
+## Precondition
 
-当你在 Codex 中处理这个仓库，并且 `fab init` 已经生成 `.fabric/forensic.json` 时，使用这个 skill 继续完成仓库专属的 Fabric 初始化。目标是基于当前仓库的初始化依据和内部说明，明确下一步该做什么，而不是重新解释一遍通用流程。
+MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
+exist, stop immediately and tell the user: run `fab init` first to generate the evidence
+package.
 
-## Workflow
+MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
+repository appears to have completed initialization already.
 
-1. 读取 `.fabric/forensic.json`。
-2. 读取 `.fabric/bootstrap/README.md`。
-3. 检查 `.fabric/init-context.json` 是否已经存在。
-4. 如果初始化仍未完成，明确总结当前仓库接下来要做的初始化动作。
-5. 只讨论这个仓库的后续初始化，不扩展到无关建议。
+MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
+the current repository.
+
+MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
+to do next.
+
+MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
+
+NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
+
+NEVER: Rewrite or translate protected tokens.
+
+NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
+
+Treat the following state as initialization pending:
+
+- `.fabric/forensic.json` exists
+- `.fabric/init-context.json` does not exist
+
+## Execution Flow — 3 Phases / 3 Rounds
+
+### Phase 1 — Framework Confirmation (1 round, efficient)
+
+Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
+`.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
+architecture.
+
+Example (Cocos Creator 3.x):
+
+> I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
+> `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
+> (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
+> `find/getChildByName`?
+
+Store the user's answers as verified framework assumptions before proceeding to Phase 2.
+
+### Phase 2 — Invariant Extraction (1 round, critical)
+
+Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
+3–5 invariant questions covering three categories:
+
+- `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
+- `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
+  decorator, imports only from `cc`
+- `protect`: directories or files that AI must not modify — typically
+  `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
+
+Principles:
+
+- Ask only about invariants, not about preferences.
+- Each question accepts only yes / no / a concrete rule — never accept vague answers.
+- Do not auto-infer hard constraints the user has not confirmed.
+
+### Phase 3 — Construction and Landing (1 round, automated)
+
+#### 3.1 Write `.fabric/init-context.json`
+
+Fields required:
+
+- `framework`
+- `architecture_patterns`
+- `invariants`
+- `domain_groups`
+- `interview_trail`
+- `forensic_ref`
+
+Writing rules:
+
+- `invariants[].type` MUST be one of `ban`, `require`, `protect`.
+- `domain_groups` is inferred from `entry_points` and interview results.
+- `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
+- `forensic_ref` MUST be `.fabric/forensic.json`.
+
+#### 3.2 Generate layered `AGENTS.md`
+
+Root `AGENTS.md` requirements:
+
+- MUST be within 300 lines.
+- Structure:
+  - `# {projectName} — L0 AGENTS.md`
+  - `<!-- fab:index -->`: populated with the `domain_groups` index
+  - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
+  - `## @HUMAN`: protect paths and any human-declared protection rules
+  - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
+
+If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
+Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
+
+#### 3.3 Update `.fabric/agents.meta.json`
+
+- The `nodes` tree MUST match the generated AGENTS hierarchy.
+- Update the hash of every AGENTS.md file that was written.
+- Maintain a consistent internal revision hash chain.
+
+#### 3.4 Final output
+
+List all generated files for the user and recommend running `fabric doctor --fix` for
+ongoing maintenance.
+
+## Hard Rules
+
+- Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
+- No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
+  frontmatter.
+- Root `AGENTS.md` MUST be <= 300 lines.
+- Total AGENTS nesting MUST be <= 4 levels.
+- Do not auto-infer invariants the user has not confirmed.
+- When content is uncertain, omit it — do not leave placeholders.
+
+## Output Contract
+
+On successful completion the following files exist or are updated:
+
+| File | Action |
+|------|--------|
+| `.fabric/init-context.json` | Created with all required fields |
+| `AGENTS.md` | Created (root L0) |
+| `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
+| `.fabric/agents.meta.json` | Updated nodes tree + hashes |
+
+On failure or early termination the skill MUST leave no partial files. If a write fails
+mid-sequence, report the failure and the exact file that was not written.
+
+## Protected Tokens
+
+The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
+never translated:
+
+| Token | Type |
+|-------|------|
+| `AGENTS.md` | Filename |
+| `FABRIC.md` | Filename |
+| `.fabric/agents.meta.json` | Path |
+| `.fabric/init-context.json` | Path |
+| `.fabric/forensic.json` | Path |
+| `.fabric/bootstrap/README.md` | Path |
+| `MUST` | Keyword |
+| `NEVER` | Keyword |
+| `fab init` | CLI command |
+| `fabric doctor --fix` | CLI command |
+| `<!-- fab:index -->` | HTML comment marker |
+| `@HUMAN` | Section marker |