skill-family-engineering-kit 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+<!-- release-skill:changelog:start version=0.2.1 locale=en baseline=sha256:3457c97a9a2f25fd233a1947dcd9c88fb40279e90ae5b437bea1f7660ac6ce60 -->
+## [0.2.1] - 2026-08-10
+
+This release adds a candidate Quickstart Profile projection bundle while preserving the Kit's four-command boundary and adds bilingual package release documentation.
+
+### Added
+
+- Adds a candidate builder and CLI for a deterministic, self-contained Quickstart Profile projection bundle with source-closure and bundle digests.
+- Adds complete English and Simplified Chinese package documentation, including an agent quick-reference section.
+
+### Changed
+
+- Manages the current README and CHANGELOG release sections from one bilingual, versioned notes source.
+- Distributes the project NOTICE separately from the existing third-party notices and license closure.
+
+### Upgrade Notes
+
+The candidate bundle remains under the existing projection authorization boundary. It does not add a fifth top-level Kit command or replace THIRD_PARTY_NOTICES.
+<!-- release-skill:changelog:end version=0.2.1 locale=en -->

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,21 @@
+# 变更日志
+
+<!-- release-skill:changelog:start version=0.2.1 locale=zh-CN baseline=sha256:f43f41fadfa1dc9affd87825a382af6aed91050ef36a0c0854a6b04c2ba7fcea -->
+## [0.2.1] - 2026-08-10
+
+本版新增 Quickstart Profile 候选投影包，同时保持 Kit 四命令边界，并补齐双语包发布文档。
+
+### 新增
+
+- 新增候选构建函数与 CLI，用于生成确定性、自包含的 Quickstart Profile 投影包，并记录源码闭包与投影包摘要。
+- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+
+### 变更
+
+- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+- 项目 NOTICE 与现有第三方声明及许可证闭包分开分发。
+
+### 升级说明
+
+候选投影包仍受既有 projection 授权边界约束。它不增加第五个 Kit 顶层命令，也不替代 THIRD_PARTY_NOTICES。
+<!-- release-skill:changelog:end version=0.2.1 locale=zh-CN -->

package/NOTICE

@@ -0,0 +1,10 @@
+Skill Family Foundation
+=======================
+
+Copyright 2026 广州市风荷科技有限公司
+
+Licensed under the Apache License, Version 2.0.
+
+This NOTICE contains project attribution for Skill Family Foundation. Third-party
+attribution and license texts distributed with skill-family-engineering-kit are
+recorded separately in THIRD_PARTY_NOTICES and the corresponding license files.

package/README.md

@@ -1,21 +1,52 @@
 <!-- release-skill:safe-first-command -->
 <!-- release-skill:external-write-boundary -->
+> 简体中文版：[README.zh-CN.md](./README.zh-CN.md)
 
 # skill-family-engineering-kit
 
-开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
+<!-- release-skill:release-version: 0.2.1 -->
 
-| 命令 | 用途 | 副作用 |
+An engineering toolkit used in development and CI. There are **exactly four** top-level commands, and no fifth:
+
+<!-- release-skill:managed:start id=latest-release -->
+**0.2.1** (2026-08-10)
+
+This release adds a candidate Quickstart Profile projection bundle while preserving the Kit's four-command boundary and adds bilingual package release documentation.
+
+**Added**
+
+- Adds a candidate builder and CLI for a deterministic, self-contained Quickstart Profile projection bundle with source-closure and bundle digests.
+- Adds complete English and Simplified Chinese package documentation, including an agent quick-reference section.
+
+**Changed**
+
+- Manages the current README and CHANGELOG release sections from one bilingual, versioned notes source.
+- Distributes the project NOTICE separately from the existing third-party notices and license closure.
+
+**Upgrade Notes**
+
+The candidate bundle remains under the existing projection authorization boundary. It does not add a fifth top-level Kit command or replace THIRD_PARTY_NOTICES.
+<!-- release-skill:managed:end id=latest-release -->
+
+| Command | Purpose | Side effects |
 | --- | --- | --- |
-| `scaffold` | 在空目录生成 Skill Family 项目骨架 | 只向空目标目录写入骨架文件（原子写、路径收容）；非空或冲突目标被拒绝且不被触碰 |
-| `adopt-plan` | 严格只读地规划存量仓采用 | 无——不写任何文件（含临时文件），不运行 git 写命令；计划输出到 stdout |
-| `projection` | 投影受管生成物 | 只写 manifest 授权且被目标声明为受管的路径；未授权、手写与越界路径一律拒绝（拒绝时零写入） |
-| `check` | 契约/漂移/闭包/版本/文档事实/Git 前置状态诊断 | 无——只诊断、绝不自动修复；git 仅只读探测 |
+| `scaffold` | Generate a Skill Family project skeleton in an empty directory | Only writes skeleton files to the empty target directory (atomic write, path containment); non-empty or conflicting targets are rejected and not touched |
+| `adopt-plan` | Strictly read-only planning of adopting an existing repo | None — writes no files (including temp files), runs no git write commands; plan output goes to stdout |
+| `projection` | Project managed artifacts | Only writes paths authorized by manifest and declared managed by the target; unauthorized, hand-written, and out-of-bounds paths are all rejected (zero writes on rejection) |
+| `check` | Contract/drift/closure/version/doc-fact/Git-precondition diagnostics | None — only diagnoses, never auto-fixes; git is read-only probe only |
+
+## Problem It Solves
+
+The engineering stage often carries two kinds of risk: either each skeleton generates its own copy and each projection writes its own copy, causing structural drift; or diagnostic tools conveniently "auto-fix", silently mutating the caller's repo. Kit consolidates engineering actions into four read-only or restricted-write commands, making "generate, inventory, project, diagnose" reproducible, auditable, and never auto-modifying across boundaries.
 
-## 使用
+## Core Mental Model
+
+Kit is the "engineering stage" layer, depending on the Harness and Contracts. It does only four things: generate a precise skeleton for a new project, perform a read-only adoption inventory of an existing repo, mechanically project managed facts to a target, and perform read-only diagnostics on engineering inconsistencies. `report` and `host` are sub-actions hanging under the four commands and do not change the "four-command" boundary. All write actions go through the Harness's atomic contained write, leaving no half-written artifact on failure.
+
+## Installation and Minimal Example
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.2.0
+npm install --save-dev skill-family-engineering-kit@0.2.1
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -23,17 +54,31 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- skill-family-kit check --root <repo>
 ```
 
-### 报告子动作
+The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.2.1 -- skill-family-kit --help`.
+
+### Report sub-action
 
 ```sh
 npm exec -- skill-family-kit projection report --root <repo> --model <report-model.json> --result <operation-result.json> --out <report.md> --binding <binding.json>
 npm exec -- skill-family-kit check report --root <repo> --report <report.md> --model <report-model.json> --result <operation-result.json> --binding <binding.json>
 ```
 
-调用方必须先构造合法 report model；Kit 不从开放的业务 `outputs` 推导事实。所有事实文本按字面转义，失败结果的
-完整 errors 必须出现在 model 和中性报告中。
+The caller must first construct a valid report model; Kit does not derive facts from open business `outputs`. All fact text is escaped literally, and the full errors of a failed result must appear in both the model and the neutral report.
 
-### 宿主子动作
+### Candidate Quickstart projection bundle
+
+Use the candidate subpath to build a deterministic projection manifest containing the Quickstart Profile schemas, runner, and required runtime dependency closure:
+
+```js
+import {
+  buildQuickstartProfileProjection,
+  QUICKSTART_PROFILE_TARGET_PREFIX,
+} from "skill-family-engineering-kit/candidate/quickstart-profile";
+```
+
+Pass the returned `manifest` to the stable `runProjection` API; the candidate helper does not write files or add a fifth top-level command. This subpath is public but **not stable** and may change or be removed in a later minor release. Pin the exact package version, inspect the returned manifest before authorization, and keep candidate imports outside a stable consumer API.
+
+### Host sub-action
 
 ```sh
 npm exec -- skill-family-kit adopt-plan host-describe --host <id> --hosts-root <dir>
@@ -42,63 +87,120 @@ npm exec -- skill-family-kit scaffold host-build --root <workspace> --host <id>
 npm exec -- skill-family-kit adopt-plan host-plan --root <workspace> --host <id> --path-category <id> --build-manifest <relpath> --probe-facts <relpath> --hosts-root <dir>
 ```
 
-Profile 必须显式提供，Kit 不默认绑定具体宿主。probe 默认不启动进程；只有同时给出
-`--allow-host-spawn --host-executable <绝对路径>` 才执行冻结版本向量。`host-apply` 稳定拒绝，未实现安装、更新或卸载。
-Codex 的技能目标路径固定为 `.agents/skills`；其他受支持宿主只按已登记 Profile 提供；Qoder 为 `unsupported`，本版只参考其结构，不提供完整 driver，也不声称已在 Qoder 运行。adapter source 只接受已声明的文本闭包，不支持二进制投影；精确宿主支持矩阵见本版本 CHANGELOG 与已登记 Profile。
+The Profile must be provided explicitly; Kit does not bind a specific host by default. Probe starts no process by default; only when both `--allow-host-spawn --host-executable <absolute-path>` are given is the frozen version vector executed. `host-apply` is stably rejected; install, update, or uninstall is not implemented. Codex's skill target path is fixed at `.agents/skills`; other supported hosts are offered only per registered Profile; Qoder is `unsupported`, this version only references its structure, provides no full driver, and does not claim to have run in Qoder. adapter source only accepts declared text closures; binary projection is not supported; see this version's CHANGELOG and registered Profile for the precise host support matrix.
 
-零安装形式（不修改 package.json）：
+## Typical Use Cases
 
-```sh
-npm exec --package=skill-family-engineering-kit@0.2.0 -- skill-family-kit --help
-```
+- New project skeleton: `scaffold` (does not overwrite a non-empty existing repo).
+- Existing-repo adoption inventory: `adopt-plan` (strictly read-only, no file writes, no auto-migration).
+- Managed projection: `projection` + Profile (does not overwrite handwritten files).
+- Engineering diagnostics: `check` (diagnosis only, no fix, `--only` narrows scope).
 
-## 边界机制
+## Boundary Mechanisms
 
-- `scaffold` 的目标必须是**空目录**（任何条目含点文件都算非空），或其父目录已存在的不存在路径（只创建最后一级）。
-  全部写入经 harness 的原子收容写（`writeFileAtomic`），失败不留半成品，路径不能越出目标根。
-- `adopt-plan` 结构性只读：实现中不存在任何写调用，连临时文件都不产生；计划字节与 `scaffold`
-  同源（`describeSkeletonFiles` 单一事实源），因此「计划即动作」。dirty 仓运行前后字节级零变化。
-- `projection` 采用两阶段执行：先对每个条目做路径分类、收容预检、自投影检查、manifest 授权检查、
-  手写保护与冲突守卫；任一条目违规则整体拒绝、零写入。覆盖既有文件必须声明精确的 `expect.sha256`
-  前置状态；内容相同的既有文件是幂等 no-op。写入失败时尽力还原已覆盖文件的前置字节。
-- `check` 只诊断：无写调用、无 `--fix/--apply/--repair` 模式（此类标志在入口处被拒绝）。
-  Git 前置状态仅用文件系统事实加至多一次冻结参数矢量的只读 `git status --porcelain=2`
-  （`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`，不刷新索引）。
+- `scaffold`'s target must be an **empty directory** (any entry including dotfiles counts as non-empty), or a non-existent path whose parent directory exists (only the last level is created). All writes go through the harness's atomic contained write (`writeFileAtomic`), leaving no half-written artifact on failure, and paths cannot escape the target root.
+- `adopt-plan` is structurally read-only: there is no write call in the implementation, not even a temp file; the plan bytes share the same source as `scaffold` (single source of truth `describeSkeletonFiles`), hence "the plan is the action". A dirty repo has zero byte-level change before and after running.
+- `projection` uses two-phase execution: first, for each entry, it performs path classification, containment pre-check, self-projection check, manifest authorization check, hand-written protection, and conflict guard; if any entry violates, the whole is rejected with zero writes. Overwriting an existing file must declare the precise `expect.sha256` precondition; an existing file with identical content is an idempotent no-op. On write failure it best-effort restores the pre-write bytes of already-overwritten files.
+- `check` is diagnosis only: no write calls, no `--fix/--apply/--repair` modes (such flags are rejected at the entry point). Git precondition state uses only filesystem facts plus at most one read-only `git status --porcelain=2` with a frozen parameter vector (`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`, no index refresh).
 
-## 错误码与退出码
+## Error Codes and Exit Codes
 
-错误码复用 contracts 冻结的 SFC\* 体系，不新增码：
+Error codes reuse the contracts frozen SFC\* system; no new codes are added:
 
-- `SFC2002`（UNKNOWN_OPERATION）——入口收到四命令词表之外的命令名；
-- `SFC2003`（INVALID_PARAMS）——选项/参数值违规，或请求 `--fix` 等不存在的变更模式；
-- `SFC2004`（EXECUTION_FAILED）——执行期失败，`details.kind` 为稳定的 kit 级 kind
-  （如 `target-not-empty`、`unauthorized-path`、`handwritten-overwrite`、`conflict-drift`）；
-  harness 抛出的收容类 kind（`path-traversal`、`symlink-escape` 等）原样透传；
-- `SFC1001`（SCHEMA_VALIDATION_FAILED）——`check` 发现的合同文档未通过注册 Schema。
+- `SFC2002` (UNKNOWN_OPERATION) — the entry receives a command name outside the four-command vocabulary;
+- `SFC2003` (INVALID_PARAMS) — option/argument value violation, or requesting a non-existent mutation mode like `--fix`;
+- `SFC2004` (EXECUTION_FAILED) — runtime failure, with `details.kind` as a stable kit-level kind (e.g., `target-not-empty`, `unauthorized-path`, `handwritten-overwrite`, `conflict-drift`); containment kinds thrown by the harness (`path-traversal`, `symlink-escape`, etc.) pass through unchanged;
+- `SFC1001` (SCHEMA_VALIDATION_FAILED) — a contract document found by `check` failed the registered Schema.
 
-进程退出码：`0` 成功/无发现；`1` check 有发现；`2` 拒绝/用法/机制错误。
+Process exit codes: `0` success / no findings; `1` check has findings; `2` rejection / usage / mechanism error.
 
-## 目标工作区文档约定
+## Target Workspace Document Conventions
 
-- `skill-family.project-manifest.json` —— contracts 的 project-manifest 实例（项目身份与 managedFiles 声明）；
-- `skill-family.managed-file-lock.json` —— contracts 的 managed-file-lock 实例（受管路径与内容哈希锁定）；
-- `skill-family.projection.json` —— projection 的授权 manifest（kit 级文档）。
+- `skill-family.project-manifest.json` — the contracts project-manifest instance (project identity and managedFiles declaration);
+- `skill-family.managed-file-lock.json` — the contracts managed-file-lock instance (managed path and content-hash lock);
+- `skill-family.projection.json` — the projection authorization manifest (kit-level document).
 
-projection 只写同时满足两个条件的路径：manifest 列出，且目标自身的登记
-（file-registry / project-manifest managedFiles / managed-file-lock）声明为受管。
-匹配手写模式的路径永不写入，即使有受管声明也拒绝。
+`projection` only writes paths that satisfy both conditions: listed by the manifest, and declared managed by the target's own registry (file-registry / project-manifest managedFiles / managed-file-lock). Paths matching hand-written patterns are never written, even if a managed declaration exists, they are rejected.
 
-## 禁止项
+## Prohibited Items
 
-本包不得执行 git init、commit、push、tag、stash、分支切换、发布、删除、远端写入或发布状态复述；
-不实现第五个顶层命令；不做业务判断、模型调用、远程网络。
+This package must not perform git init, commit, push, tag, stash, branch switch, publish, delete, remote write, or publish-state recital; it does not implement a fifth top-level command; it does no business judgments, model calls, or remote networking.
 
-## 安装
+## Troubleshooting
 
-```sh
-npm install skill-family-engineering-kit@0.2.0
-```
+`check`'s exit code 1 means findings, exit code 2 means usage or mechanism error. If it fails, confirm the target repo exists and `skill-family.project-manifest.json` is well-formed; when path overrun or hand-written protection triggers, the command rejects the write and reports `SFC2004`.
+
+## Further Documentation
+
+- Architecture boundaries and routing: [Architecture](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/), [Agent architecture routing](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- Capability catalog: [capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- Adoption and migration: [Migration guide](https://ifoohoo.github.io/skill-family-engineering-kit/migration/)
+- Side-effect matrix: [Failure and side-effect matrix](https://ifoohoo.github.io/skill-family-engineering-kit/reference/failure-and-side-effect-matrix/)
+
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
+
+### Use when
+
+- You need to generate a new project skeleton, perform a read-only adoption inventory of an existing repo, managed projection, or engineering diagnostics.
+- You need to produce report text from a rendered model, or perform tiered checks on a report.
+- You need a deterministic, self-contained projection manifest for an exact-version Quickstart candidate trial.
+
+### Do not use when
+
+- You need auto-fix (`check` does not fix), or auto-migration (`adopt-plan` writes no files).
+- You need host apply/install/update/uninstall or a full Qoder driver (explicitly unsupported).
+- You need a stable Quickstart API or expect the candidate helper to bypass `runProjection` authorization.
+
+### Capability selection
+
+- `foundation.kit.scaffold`: generate a precise skeleton in an empty directory, atomic + contained.
+- `foundation.kit.adopt-plan`: strictly read-only inventory and completion determination of an existing repo.
+- `foundation.kit.projection`: managed projection, write only after full validation, zero writes on failure.
+- `foundation.kit.check`: seven check classes, diagnosis only, no fix.
+- `foundation.kit.report`: projection/check report sub-action orchestration.
+- `foundation.kit.git-probe`: read-only whitelisted Git status probe.
+- `foundation.kit.host`: describe/build/probe/plan, apply stably rejected.
+- `foundation.kit.licensing`: Profile authorization-data loading and generation.
+- `foundation.kit.identity-check`: identity-drift and Profile-consistency checks.
+- `foundation.kit.cli`: four-command dispatch and mutation-flag entry rejection.
+- `foundation.kit.quickstart-profile-candidate`: exact-version deterministic Quickstart projection-manifest bundle.
+
+### Required inputs
+
+- Target root (scaffold needs an empty directory; adopt-plan/projection/check need an accessible repo).
+- Profile identifier (host sub-action must be provided explicitly).
+
+### Outputs and evidence
+
+- Skeleton files, adoption classification / completion determination, projected files, findings list, report text.
+- Evidence: `packages/skill-family-engineering-kit/test/scaffold.test.mjs`, `adopt-plan.test.mjs`, `projection.test.mjs`, `check.test.mjs`, `host.test.mjs`, `git-probe.test.mjs`.
+
+### Side effects
+
+- scaffold/projection/host-build write files to the contained target (atomic + contained).
+- adopt-plan and check are strictly read-only; git is read-only whitelisted probe only.
+- `FORBIDDEN_SIDE_EFFECTS` includes git-init/commit/push/tag, publish, remote-write.
+
+### Failure semantics
+
+- Stable error codes such as `SFC2002/2003/2004/1001`; exit codes 0/1/2.
+- check findings exit code 1, mechanism/usage error exit code 2.
+
+### Architectural invariants
+
+- The top-level commands are fixed at 4, not expanded; `REFUSED_MUTATION_FLAGS` is rejected at the CLI entry.
+- Diagnosis only, no fix; projection only, no overwrite of handwritten.
+
+### Route elsewhere when
+
+- Remote publish: route to release-skill.
+- host apply/install/update/uninstall: explicitly unsupported.
+- Business state machine / migration execution: stays with the caller or a later version.
 
-## 故障诊断
+### Machine-readable sources
 
-`check` 退出码 1 表示有发现，退出码 2 表示用法或机制错误。如失败，确认目标仓库存在且 `skill-family.project-manifest.json` 形状合法；路径越界或手写保护触发时命令会拒绝写入并报告 `SFC2004`。
+- Public capability catalog: [`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json) (`foundation.kit.*` entries).
+- Package-local source: `src/*.mjs`.
+- Package-local candidate source: `candidate/*`; public import: `skill-family-engineering-kit/candidate/quickstart-profile`.
+<!-- agent-quick-reference:end -->

package/README.zh-CN.md

@@ -0,0 +1,207 @@
+<!-- release-skill:safe-first-command -->
+<!-- release-skill:external-write-boundary -->
+
+> English version: [README.md](./README.md)
+
+# skill-family-engineering-kit
+
+<!-- release-skill:release-version: 0.2.1 -->
+
+开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
+
+<!-- release-skill:managed:start id=latest-release -->
+**0.2.1** (2026-08-10)
+
+本版新增 Quickstart Profile 候选投影包，同时保持 Kit 四命令边界，并补齐双语包发布文档。
+
+**新增**
+
+- 新增候选构建函数与 CLI，用于生成确定性、自包含的 Quickstart Profile 投影包，并记录源码闭包与投影包摘要。
+- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+
+**变更**
+
+- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+- 项目 NOTICE 与现有第三方声明及许可证闭包分开分发。
+
+**升级说明**
+
+候选投影包仍受既有 projection 授权边界约束。它不增加第五个 Kit 顶层命令，也不替代 THIRD_PARTY_NOTICES。
+<!-- release-skill:managed:end id=latest-release -->
+
+| 命令 | 用途 | 副作用 |
+| --- | --- | --- |
+| `scaffold` | 在空目录生成 Skill Family 项目骨架 | 只向空目标目录写入骨架文件（原子写、路径收容）；非空或冲突目标被拒绝且不被触碰 |
+| `adopt-plan` | 严格只读地规划存量仓采用 | 无——不写任何文件（含临时文件），不运行 git 写命令；计划输出到 stdout |
+| `projection` | 投影受管生成物 | 只写 manifest 授权且被目标声明为受管的路径；未授权、手写与越界路径一律拒绝（拒绝时零写入） |
+| `check` | 契约/漂移/闭包/版本/文档事实/Git 前置状态诊断 | 无——只诊断、绝不自动修复；git 仅只读探测 |
+
+## 解决的问题
+
+工程阶段常出现两类风险：要么骨架各生成一套、投影各写一遍，导致结构漂移；要么诊断工具顺手「自动修复」，悄悄改动调用方的仓。Kit 把工程动作收敛成四个只读或受限写入的命令，让「生成、盘点、投影、诊断」都可复现、可审计，且绝不越界自动修改。
+
+## 核心心智模型
+
+Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事：为新项目生成精确骨架、对存量仓做只读采用盘点、把受管事实机械投影到目标、对工程不一致做只读诊断。`report` 与 `host` 是挂接在四个命令下的子动作，不改变「四命令」的边界。所有写动作都经 Harness 的原子收容写，失败不留半成品。
+
+## 安装和最小示例
+
+```sh
+npm install --save-dev skill-family-engineering-kit@0.2.1
+npm exec -- skill-family-kit --help
+npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
+npm exec -- skill-family-kit adopt-plan --root <repo>
+npm exec -- skill-family-kit projection --root <repo>
+npm exec -- skill-family-kit check --root <repo>
+```
+
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.2.1 -- skill-family-kit --help`。
+
+### 报告子动作
+
+```sh
+npm exec -- skill-family-kit projection report --root <repo> --model <report-model.json> --result <operation-result.json> --out <report.md> --binding <binding.json>
+npm exec -- skill-family-kit check report --root <repo> --report <report.md> --model <report-model.json> --result <operation-result.json> --binding <binding.json>
+```
+
+调用方必须先构造合法 report model；Kit 不从开放的业务 `outputs` 推导事实。所有事实文本按字面转义，失败结果的完整 errors 必须出现在 model 和中性报告中。
+
+### Candidate Quickstart 投影包
+
+需要生成确定性的投影 manifest，并携带 Quickstart Profile Schema、runner 与必要运行时依赖闭包时，使用 candidate 子路径：
+
+```js
+import {
+  buildQuickstartProfileProjection,
+  QUICKSTART_PROFILE_TARGET_PREFIX,
+} from "skill-family-engineering-kit/candidate/quickstart-profile";
+```
+
+以上辅助函数不写文件，也不增加第五个顶层命令。调用方需要把返回的 `manifest` 交给稳定的 `runProjection` API。该子路径公开但**不稳定**，后续小版本可以修改或移除；调用方需要锁定精确包版本，在授权前检查 manifest，并避免通过自身稳定 API 再导出 candidate 导入。
+
+### 宿主子动作
+
+```sh
+npm exec -- skill-family-kit adopt-plan host-describe --host <id> --hosts-root <dir>
+npm exec -- skill-family-kit adopt-plan host-probe --host <id> --hosts-root <dir>
+npm exec -- skill-family-kit scaffold host-build --root <workspace> --host <id> --path-category <id> --input <relpath> --out <relpath> --hosts-root <dir>
+npm exec -- skill-family-kit adopt-plan host-plan --root <workspace> --host <id> --path-category <id> --build-manifest <relpath> --probe-facts <relpath> --hosts-root <dir>
+```
+
+Profile 必须显式提供，Kit 不默认绑定具体宿主。probe 默认不启动进程；只有同时给出 `--allow-host-spawn --host-executable <绝对路径>` 才执行冻结版本向量。`host-apply` 稳定拒绝，未实现安装、更新或卸载。Codex 的技能目标路径固定为 `.agents/skills`；其他受支持宿主只按已登记 Profile 提供；Qoder 为 `unsupported`，本版只参考其结构，不提供完整 driver，也不声称已在 Qoder 运行。adapter source 只接受已声明的文本闭包，不支持二进制投影；精确宿主支持矩阵见本版本 CHANGELOG 与已登记 Profile。
+
+## 典型使用场景
+
+- 新项目骨架：`scaffold`（不覆盖非空存量仓）。
+- 存量采用盘点：`adopt-plan`（严格只读，不写文件、不自动迁移）。
+- 受管投影：`projection` + Profile（不覆盖 handwritten 文件）。
+- 工程诊断：`check`（只诊断不修复，`--only` 缩小范围）。
+
+## 边界机制
+
+- `scaffold` 的目标必须是**空目录**（任何条目含点文件都算非空），或其父目录已存在的不存在路径（只创建最后一级）。全部写入经 harness 的原子收容写（`writeFileAtomic`），失败不留半成品，路径不能越出目标根。
+- `adopt-plan` 结构性只读：实现中不存在任何写调用，连临时文件都不产生；计划字节与 `scaffold` 同源（`describeSkeletonFiles` 单一事实源），因此「计划即动作」。dirty 仓运行前后字节级零变化。
+- `projection` 采用两阶段执行：先对每个条目做路径分类、收容预检、自投影检查、manifest 授权检查、手写保护与冲突守卫；任一条目违规则整体拒绝、零写入。覆盖既有文件必须声明精确的 `expect.sha256` 前置状态；内容相同的既有文件是幂等 no-op。写入失败时尽力还原已覆盖文件的前置字节。
+- `check` 只诊断：无写调用、无 `--fix/--apply/--repair` 模式（此类标志在入口处被拒绝）。Git 前置状态仅用文件系统事实加至多一次冻结参数矢量的只读 `git status --porcelain=2`（`--no-optional-locks` + `GIT_OPTIONAL_LOCKS=0`，不刷新索引）。
+
+## 错误码与退出码
+
+错误码复用 contracts 冻结的 SFC\* 体系，不新增码：
+
+- `SFC2002`（UNKNOWN_OPERATION）——入口收到四命令词表之外的命令名；
+- `SFC2003`（INVALID_PARAMS）——选项/参数值违规，或请求 `--fix` 等不存在的变更模式；
+- `SFC2004`（EXECUTION_FAILED）——执行期失败，`details.kind` 为稳定的 kit 级 kind（如 `target-not-empty`、`unauthorized-path`、`handwritten-overwrite`、`conflict-drift`）；harness 抛出的收容类 kind（`path-traversal`、`symlink-escape` 等）原样透传；
+- `SFC1001`（SCHEMA_VALIDATION_FAILED）——`check` 发现的合同文档未通过注册 Schema。
+
+进程退出码：`0` 成功/无发现；`1` check 有发现；`2` 拒绝/用法/机制错误。
+
+## 目标工作区文档约定
+
+- `skill-family.project-manifest.json` —— contracts 的 project-manifest 实例（项目身份与 managedFiles 声明）；
+- `skill-family.managed-file-lock.json` —— contracts 的 managed-file-lock 实例（受管路径与内容哈希锁定）；
+- `skill-family.projection.json` —— projection 的授权 manifest（kit 级文档）。
+
+projection 只写同时满足两个条件的路径：manifest 列出，且目标自身的登记（file-registry / project-manifest managedFiles / managed-file-lock）声明为受管。匹配手写模式的路径永不写入，即使有受管声明也拒绝。
+
+## 禁止项
+
+本包不得执行 git init、commit、push、tag、stash、分支切换、发布、删除、远端写入或发布状态复述；不实现第五个顶层命令；不做业务判断、模型调用、远程网络。
+
+## 故障诊断
+
+`check` 退出码 1 表示有发现，退出码 2 表示用法或机制错误。如失败，确认目标仓库存在且 `skill-family.project-manifest.json` 形状合法；路径越界或手写保护触发时命令会拒绝写入并报告 `SFC2004`。
+
+## 深入文档入口
+
+- 架构边界与路由：[架构说明](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/)、[智能体架构路由](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- 能力目录：[capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- 采用与迁移：[迁移指南](https://ifoohoo.github.io/skill-family-engineering-kit/migration/)
+- 副作用矩阵：[失败与副作用矩阵](https://ifoohoo.github.io/skill-family-engineering-kit/reference/failure-and-side-effect-matrix/)
+
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
+
+### Use when
+
+- 需要生成新项目骨架、对存量仓做只读采用盘点、受管投影或工程诊断。
+- 需要从已渲染 model 产出报告文本，或对报告做分级检查。
+- 需要为锁定精确版本的 Quickstart candidate 试验生成确定、自包含的投影 manifest。
+
+### Do not use when
+
+- 需要自动修复（`check` 不修复）、自动迁移（`adopt-plan` 不写文件）。
+- 需要 host apply/install/update/uninstall 或 Qoder 完整 driver（明确 unsupported）。
+- 需要稳定 Quickstart API，或希望 candidate 辅助函数绕过 `runProjection` 授权。
+
+### Capability selection
+
+- `foundation.kit.scaffold`：空目录生成精确骨架，原子 + 收容。
+- `foundation.kit.adopt-plan`：存量仓严格只读盘点与完成判定。
+- `foundation.kit.projection`：受管投影，全校验后才写，失败零写。
+- `foundation.kit.check`：七类检查只诊断不修复。
+- `foundation.kit.report`：projection/check report 子动作编排。
+- `foundation.kit.git-probe`：只读白名单 Git 状态探测。
+- `foundation.kit.host`：describe/build/probe/plan，apply 稳定拒绝。
+- `foundation.kit.licensing`：Profile 授权数据加载与生成。
+- `foundation.kit.identity-check`：身份漂移与 Profile 一致性检查。
+- `foundation.kit.cli`：四命令分派与变更旗标入口拒绝。
+- `foundation.kit.quickstart-profile-candidate`：锁定精确版本后构建确定的 Quickstart 投影 manifest 包。
+
+### Required inputs
+
+- 目标根（scaffold 需空目录；adopt-plan/projection/check 需可访问仓）。
+- Profile 标识（host 子动作必须显式提供）。
+
+### Outputs and evidence
+
+- 骨架文件、采用分类/完成判定、投影文件、发现清单、报告文本。
+- 证据：`packages/skill-family-engineering-kit/test/scaffold.test.mjs`、`adopt-plan.test.mjs`、`projection.test.mjs`、`check.test.mjs`、`host.test.mjs`、`git-probe.test.mjs`。
+
+### Side effects
+
+- scaffold/projection/host-build 在受收容目标写文件（原子 + 收容）。
+- adopt-plan 与 check 严格只读，git 仅只读白名单探测。
+- `FORBIDDEN_SIDE_EFFECTS` 含 git-init/commit/push/tag、publish、remote-write。
+
+### Failure semantics
+
+- `SFC2002/2003/2004/1001` 等稳定错误码；退出码 0/1/2。
+- check 发现退出码 1，机制/用法错误退出码 2。
+
+### Architectural invariants
+
+- 顶层命令固定 4 个，不扩张；`REFUSED_MUTATION_FLAGS` 在 CLI 入口即拒。
+- 只诊断不修复，只投影不覆盖 handwritten。
+
+### Route elsewhere when
+
+- 远端发布：转 release-skill。
+- host apply/install/update/uninstall：明确 unsupported。
+- 业务状态机/迁移执行：留在调用方或后续版本。
+
+### Machine-readable sources
+
+- 公开能力目录：[`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)（`foundation.kit.*` 条目）。
+- 包内源：`src/*.mjs`。
+- 包内 Candidate 源：`candidate/*`；公共导入：`skill-family-engineering-kit/candidate/quickstart-profile`。
+<!-- agent-quick-reference:end -->

package/candidate/index.mjs

@@ -0,0 +1,4 @@
+export {
+  buildQuickstartProfileProjection,
+  QUICKSTART_PROFILE_TARGET_PREFIX,
+} from "./profile-bundle.mjs";