@echopath-labs/forgerail 0.1.0-alpha.2 → 0.1.0-alpha.4

package/docs/adoption.zh-CN.md

@@ -1,51 +1,88 @@
 # 渐进式采用
 
-ForgeRail 将“能力可用”与“项目采用”明确分开。安装 Agent Plugin 或可选 CLI，只让能力可用；不会修改工作区 instructions、创建持久化状态、启用 Capability Pack，也不会授权任何外部副作用。
+ForgeRail 明确区分**安装**、**能力可用**、**项目采用**和**执行授权**。安装 Plugin 只是让 Agent 能发现引导能力；不会编辑工作区 instructions、创建持久状态、启用 Capability Pack 或批准任何外部影响。
 
-## 三级模型
+本文对应候选版本 `0.1.0-alpha.4` / `v0.1.0-alpha.4`。是否已可安装以公开 Release 为准，源码文档本身不代表发布完成。
 
-### Level 0 — Plugin Only
+默认从 Plugin Only 开始。只有重复证据表明“小范围持久绑定”比每次显式调用更有价值时，才升级采用层级。
 
-这是默认级别。宿主 Agent 可以发现 Skills，但工作区保持不变。偶尔显式调用或依靠 Agent 按描述判断触发已经足够时，应停留在此级别。
+## Level 0 — Plugin Only
 
-### Level 1 — Lightweight Adoption
+这是默认且推荐的首次体验。工作区保持不变，同时可以使用四个 Skills：
 
-只有在 Agent 展示精确 Adoption Plan、用户确认其中写入后才采用：
+- `$forgerail`：为有边界的工程任务提供引航；
+- `$forgerail-workspace-diagnosis`：生成只读项目概览；
+- `$workspace-health-review`：进行独立的工作区健康复盘；
+- `$architecture-convergence-audit`：复核能力重复和 owner 漂移。
 
-- 单宿主且原则简短时，只向宿主原生 instruction 入口提出一个带版本 managed block；
-- 多宿主时，提出 `FORGERAIL.md` 作为可移植 Adoption Contract，各宿主只保留指向它的薄绑定。
+偶发诊断、陌生仓库、早期试用，以及已有 instructions 足够清晰的项目，都适合保持 Plugin Only。
 
-planner 永远只读：
+## Level 1 — Lightweight Adoption
+
+只有重复使用 ForgeRail 确实需要一个小型、可审查的项目绑定时，才采用这一层。
+
+- 单宿主项目在 adapter 支持时，可以在宿主原生 instruction 文件中加入一个带版本的 managed block。
+- 多宿主项目，或 adapter 只支持薄引用的单宿主项目，使用 `FORGERAIL.md` 作为可移植 Adoption Contract，再用薄绑定连接宿主。
+- 项目已有 instructions、规格、ADR、CI 和文档继续在各自领域保持权威。
+
+可选 planner 只读运行：
 
 ```bash
-forgerail adoption-plan --workspace . --host codex
-forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+# 默认：只解析当前工作区中检测到的已注册宿主。
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --selection all-detected
+
+# 从已验证的 Host Adapter Registry 中明确选择一部分。
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --host codex
+
+# 选择当前已验证 registry 中的全部 adapter。
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --selection all-available
 ```
 
-计划会给出当前/目标级别、精确路径与内容、基线 SHA-256、必需确认、验证步骤、宿主支持状态和明确非变更项。ForgeRail 刻意不提供 `apply-adoption` 命令；宿主 Agent 必须先展示候选或 diff，等待确认，只执行获批写入，再返回 Host Binding Receipt。
+只读诊断不会跟随所选工作区内部的链接。它只读取有界的常规 `package.json` 和已注册 Host 绑定文件，每个文件最多 4 MiB；内容被消费前还会按 canonical workspace 复核已打开路径。不安全、发生变化、非常规或超限条目会作为“不可用证据”交给人类复核。只有安全受限的约定目录中至少存在一个有界常规 `.md` 文件时，才会报告 Markdown 记录实践；枚举上限为 4,096 项，空目录、超限目录、链接或非常规条目都不算 ADR 实践。
+
+当前 Agent 可以把“只处理 Codex”“处理项目正在使用的全部 Agent”或“处理当前 registry 中的全部 adapter”等自然语言意图翻译成上述确定性模式。ForgeRail Core 不猜 instruction 路径、模板名称，也不猜如何处理已有但未受管的绑定；检测目标、绑定目标、绑定模板和已有内容策略都由版本化 Host Adapter 持有。若同时省略 `--host` 和 `--selection`，默认使用 `all-detected`；若未检测到任何已注册宿主，planner 会要求显式选择宿主或使用 `all-available`，而不是猜测。供人类复核的 plan 会保留模式，以及一份以解析后 adapter ID 为键的 `hostSelection.hosts` 映射；不会再用请求/解析数组重复 Host 身份。
+
+每个 proposal 必须展示当前与目标层级、准确路径和内容、基线摘要、所需确认、验证步骤、支持状态与明确不执行的动作。ForgeRail 有意不提供 `apply-adoption` 命令。Agent 应先展示 proposal，等待人类判断。Node 集成必须把已批准的 `approvalSha256` 与可变 proposal 分开保存，并在应用时重新核验 canonical workspace 路径与已打开目录身份；即使摘要格式有效，apply 也只接受 `create`、`append-managed-block`、`replace-managed-block` 三种操作。同一路径下替换成另一个目录会使批准失效。若替换既有 binding 后的 post-install 校验失败，ForgeRail 会把保留的原 inode 直接原子重命名覆盖已核验的新候选；无法安全恢复时保留 recovery evidence，并回抛原始失败。随后只写入获批路径，在新任务中验证发现结果，并返回 Host Binding Receipt。
 
-### Level 2 — Persisted Governance
+如果并发内容占用了已批准目标，导致无法安全自动回滚，ForgeRail 会把原 binding 保留为同目录的 `.forgerail-<随机值>.bak`，并在错误中给出项目相对路径。请先比较该文件与当前目标，再通过新的受审查操作恢复所需内容；只有确认恢复完成后才删除 recovery 文件。ForgeRail 不会把这类保留文件误报为成功写入。
 
-只有现有工作区来源无法清楚承载的证据才可能需要此级别，例如机器读取配置、CI 强制或反复出现的跨宿主冲突。ForgeRail alpha.1 不创建也不提出 `.forgerail/` 状态；未来必须先定义 owner、优先级、迁移与删除语义。
+### 只处理部分宿主，以及接收外部计划
+
+只有选中的宿主进入严格写入规划。其他已注册绑定使用与诊断相同的有界、不跟随链接的读取方式：已读到的受管绑定计入当前层级，并明确提示会保留；无法读取的条目记为未知，不阻塞所选宿主。`currentLevel` 表达可读的工作区现状，`proposedLevel` 和写入范围只针对本次选择；`no-change` 不会移除未选中的绑定。只选部分宿主并不等于自动合并其他宿主的规则，批准新共享契约前应核对并存提示。
+
+外部传入的计划必须先通过 `validateContract("adoption-plan", plan)` **整份校验**，然后才能批准或应用其中任何写入；单条写入摘要不能代替整份校验。运行时会拒绝大小写折叠后的重复目标、祖先/后代目标和与保留 `FORGERAIL.md` 冲突的宿主目标；仅用 JSON Schema 无法比较任意条目之间的路径。thin-reference 模板必须在自己的受管块中引用准确的共享 `FORGERAIL.md`；这是结构检查，不是 Agent 已遵循指令的证明。
+
+## Level 2 — Persisted Governance
+
+当前 alpha 暂不启用机器消费的 ForgeRail 持久状态。只有重要证据无法通过项目现有来源表达，例如反复出现跨宿主冲突或确有机器强制策略需求时，才应考虑这一层。
+
+ForgeRail 目前不会创建 `.forgerail/`。未来设计必须先定义 ownership、precedence、migration、recovery 和 deletion 语义。
 
 ## 宿主支持
 
-| 宿主 | 原生入口 | alpha.1 状态 | 验证 |
+| 宿主 | 原生目标 | Alpha.4 状态 | 验证边界 |
 | --- | --- | --- | --- |
-| Codex | `AGENTS.md` | `supported` | 在采用范围内启动新的 Codex 任务，确认绑定生效并发现三个主插件 Skills。 |
-| Claude Code | `CLAUDE.md` | `profile-only` | 已建模目标和薄绑定，但在宿主专项验证完成前不声称端到端激活。 |
-| Cursor | `.cursor/rules/forgerail.mdc` | `profile-only` | 已建模 Rules 入口，但不声称 Skill 发现和端到端激活已验证。 |
+| Codex | `AGENTS.md` | `supported` | 新 Codex 任务发现全部四个主 Skills，且已批准绑定处于作用域内 |
+| Claude Code | `CLAUDE.md` | `profile-only` | 已建模目标与薄绑定，不声称端到端激活已验证 |
+| Cursor | `.cursor/rules/forgerail.mdc` | `profile-only` | 已建模目标，不声称 Skill discovery 和端到端激活已验证 |
+
+未知宿主必须先有受审查的 Host Adapter，ForgeRail 才能生成绑定。每个 adapter 都必须提供 thin-reference 投影，使 `all-detected` 与 `all-available` 始终能通过共享契约组合；adapter 还可以为单个显式 Host 额外提供 managed-block 投影。Registry 将目标、检测路径和模板路径限制在 ASCII 安全的跨平台路径字符集中，并拒绝尾随句点别名和 Windows 设备名称，再对剩余身份进行大小写折叠。所有绑定目标必须互不相同、互不构成祖先/后代关系，且不得与保留的 `FORGERAIL.md` 冲突。每个模板还必须只包含一对有序、归属于该 adapter 的 marker 边界。Host Adapter 只是宿主投影边界，不是 ForgeRail Core，也不是第二套策略真相。
+
+## Capability Pack 始终独立
 
-未知宿主必须先有经过审查的 Host Adapter 才能生成绑定。Host Adapter 是投影边界，不是 ForgeRail Core，也不是第二套规则源。
+不要因为 Pack 已安装就把它写入项目 instructions。只有项目证据确实需要该能力时才建议使用。每个 Pack 保持独立的认证、审批、验证、回滚和生命周期边界。
 
-## 可选跨工作区编排
+Cross-Workspace Orchestration 只适合真实的多 owner、多仓库或多发布边界，并且依赖关系允许安全并行的情况；不应该把普通单仓库人为拆成复杂任务。RelayPact 可以传输有边界的委派，EchoPath 可以支持恢复与上下文；两者都不是 ForgeRail 的运行时依赖。
 
-不要因为安装了 orchestration Pack 就把它写进工作区 binding。只有观察到多个独立 owner/repository/release 边界和一个安全并行依赖波次后才建议采用；普通单仓工作继续使用 ForgeRail Core。
+## 完成与移除
 
-如果项目反复使用该模式，在取得精确 durable-write 确认后，沿用现有 OpenSpec、Spec Kit、ADR、Markdown、issue 或 instruction 习惯记录，不创建新的编排状态目录。创建任务以及每类 durable、远端、发布或 lifecycle 操作仍保留各自授权。
+Lightweight Adoption 只有满足以下条件才算完成：
 
-## 核验与移除
+1. 实际文件摘要与获批 plan 一致；
+2. 在新任务或等价 fresh check 中完成 supported host discovery；
+3. 没有偏差，或偏差已经明确接受；
+4. receipt 准确记录改了什么、没有改什么。
 
-只有 applied digest 与获批 plan 一致、支持宿主在新任务或等价支持检查中完成发现、deviations 为空且非变更项已记录，采用才能 close 为 complete。`profile-only` 宿主在完成自身专项检查前仍保持未验证。
+卸载 Plugin 不会自动移除已采用的 instructions。应通过另一个精确、受审查的 plan 修改或移除 managed block，避免破坏无关内容。
 
-卸载 ForgeRail 不会静默删除项目已经采用的 instructions。插件卸载与项目绑定移除是两件事；修改或移除 managed block 也要经过新的审查计划，以保护无关项目内容。
+正常使用请从[安装指南](installation.zh-CN.md)开始，在出现真实项目需要前保持 Plugin Only。

package/docs/architecture-acceptance.md

@@ -5,7 +5,7 @@ Accepted on 2026-08-12:
 - Core + Workspace Diagnosis + Workspace Health Review ship in the main Agent Plugin.
 - GitHub Rulesets, Release Safety, and Thread Closure begin as external Capability Packs.
 - Workspace Profile is computed from existing sources; no `.forgerail/profile.yaml` is created by default.
-- A lightweight npm/npx CLI is approved for deterministic diagnosis, contract validation, installation inspection, and bundle construction; it is not a prerequisite for using the Agent Plugin.
+- A lightweight npm/npx CLI is approved for deterministic diagnosis, contract validation, and installation inspection; it is not a prerequisite for using the Agent Plugin. Public-projection bundle construction is a source-repository maintainer tool and is not exposed by the installed CLI.
 - Adoption is progressive: Plugin Only by default, explicitly confirmed Lightweight Adoption through Host Adapters, and evidence-gated Persisted Governance deferred beyond alpha.1.
 - Host instruction entries are projections of one portable Adoption Contract. Codex is supported; Claude Code and Cursor remain profile-only until host-specific activation is verified.
 

package/docs/composable-autonomy.zh-CN.md

@@ -1,22 +1,20 @@
 # ForgeRail 可组合自治架构记录
 
-状态：Active product-local architecture record
+状态：公开产品架构说明
 
-日期：2026-08-20
+更新：2026-08-31
 
-Owner workspace：ForgeRail canonical private source workspace
+Owner：ForgeRail
 
-Canonical product source：`plugins/forgerail/`
+产品源：本仓库中的 ForgeRail Plugin 与契约实现
 
-Canonical architecture change：`openspec/changes/evolve-forgerail-engineering-governance-control-system/`
-
-跨产品基线：`docs/architecture/echopath-labs-composable-product-system.md`（根聚合架构；由根索引维护）
+相关公开文档：[控制、授权与验证契约](control-authority-validation-contracts.zh-CN.md)与[跨工作区 Pack 组合契约](cross-workspace-pack-composition-contract.zh-CN.md)
 
 ## 1. 目的与适用范围
 
-本文只记录 ForgeRail 在 EchoPath Labs 可组合自治体系中的产品边界、独立最小闭环、可选输入输出、降级行为和互操作约束。它不复制根聚合架构，也不替代 ForgeRail Control System 的 OpenSpec requirements、versioned schemas 或验证证据。
+本文记录 ForgeRail 在 EchoPath Labs 可组合自治体系中的产品边界、独立最小闭环、可选输入输出、降级行为和互操作约束。它不替代 ForgeRail Control System 的 versioned schemas、实现或验证证据。
 
-本文不授权 task 2.10、evaluator/runtime 实现、公开投影、remote、merge、release、publication、migration 或 lifecycle 变更。
+本文是公开架构说明，不构成实现、远端操作、发布、迁移或生命周期变更的授权。
 
 ## 2. 产品结论
 
@@ -136,7 +134,7 @@ ForgeRail standalone 是正式产品模式，不是缺少生态产品后的残
 
 ## 8. Reference-only interop
 
-ForgeRail 当前 canonical ecosystem contract 已定义 OpenDomain、OpenSpec 与 EchoPath 的 optional、versioned、additive interop。RelayPact 与 KeptNear 的关系来自跨产品架构 baseline，在 ForgeRail task 2.10 前只作为 reference-only adapter boundary：
+ForgeRail 的 ecosystem contract 将 OpenDomain、OpenSpec 与 EchoPath 建模为 optional、versioned、additive interop。RelayPact 与 KeptNear 只通过 reference-only adapter boundary 与 ForgeRail 组合：
 
 - 不把 RelayPact 或 KeptNear schema 引入 ForgeRail Core；
 - 不创建共享 runtime package 或共享数据库；
@@ -144,9 +142,9 @@ ForgeRail 当前 canonical ecosystem contract 已定义 OpenDomain、OpenSpec
 - consumer 使用 source product、schema/version、object identity、digest 与 locator 引用源对象；
 - unsupported version 或缺失 required proof 必须 fail closed，optional missing 必须显式降级。
 
-## 9. Task 2.10 前置 delta 结论
+## 9. 跨产品对象边界
 
-task 2.10 固定 ForgeRail 自有对象的 canonical serialization、stable ordering、digest、sanitized exposure、idempotency、unknown-field 与 version negotiation。开始前必须遵守以下已完成的边界评审：
+ForgeRail 当前只对已经实现并有验证覆盖的对象提供各自的 schema、字段级校验、特定 digest、sanitized exposure 与 unknown-field fail-closed 行为；这不能推导为系统级 canonical serialization、stable ordering、统一 digest、idempotency 或 version negotiation 已经完成。上述通用协议仍属于后续任务。跨产品对象只能被引用或适配，不能取得 ForgeRail Core 的所有权。
 
 ### 9.1 Task Envelope 与 Delegation Envelope
 
@@ -169,15 +167,11 @@ task 2.10 固定 ForgeRail 自有对象的 canonical serialization、stable orde
 - EchoPath 不复制或重新计算 ForgeRail state machine，不把 projection 当 current control truth；declared reason 与 inferred causal candidate 必须分开。
 - RelayPact 可以引用一个 ForgeRail decision/revision/receipt，但其 execution lifecycle 与 terminal decision 不由该 revision 驱动或替代。
 
-详细 delta 表与 task 2.10 entry gate 位于：
-
-`openspec/changes/evolve-forgerail-engineering-governance-control-system/inventory/composable-autonomy-delta-review-20260820.md`
-
-## 10. 当前状态与下一入口
+详细的公开契约与验证入口参见[控制、授权与验证契约](control-authority-validation-contracts.zh-CN.md)与[Control System fixture matrix](control-system-fixture-matrix.zh-CN.md)。
 
-- task 2.5–2.9：schemas、composition contract 与 pre-evaluator fixtures 已完成并有 focused evidence。
-- task 2.10：`not_started`；本文和 delta review 完成架构前置，但不构成启动授权。
-- task 2.11：`not_started`；必须另行证明 contracts 保持 local-first、event-driven 且无外部产品/host hard dependency。
-- evaluator/runtime、public projection、release 与 lifecycle：未启动、未授权。
+## 10. 使用边界与后续演进
 
-下一次 ForgeRail 恢复首先读取本文，再读取 delta review，随后读取 active change 的 `tasks.md` 2.10–2.11。不要通过公开投影恢复 canonical architecture。
+- 当前公开 schemas、composition contract 与 pre-evaluator fixtures 用于解释和验证产品边界。
+- evaluator/runtime 必须保持 local-first、event-driven，并通过独立版本和验证证明没有外部产品或 Host Agent 硬依赖。
+- 公开文档只描述产品契约，不携带私有工作区的计划、任务状态、审批记录或恢复入口。
+- 后续演进应从本仓库的版本化契约、测试和发布说明开始，而不是依赖任何未公开的开发过程记录。

package/docs/installation.md

@@ -1,33 +1,59 @@
-# Installation And Adoption
+# Install ForgeRail
 
-ForgeRail is primarily an Agent Plugin. The npm package is an optional deterministic CLI and compatibility payload.
+ForgeRail is primarily a Codex Agent Plugin. The default installation does not add Node.js, `package.json`, `node_modules`, or `.forgerail/` to the project you use it with.
 
-The canonical source currently proposes `@echopath-labs/forgerail@0.1.0-alpha.2` / `v0.1.0-alpha.2`, but that candidate is not yet remotely integrated or released. Do not construct an installation command from a local version proposal. The commands below remain bound to the currently released alpha.1 until a separately approved alpha.2 release completes.
+The current public prerelease is `0.1.0-alpha.4`. Pin the immutable Git tag so another user can reproduce the same Plugin snapshot.
 
-## Install
+## Prerequisites
 
-The intended default human route is the Universal Plugins Directory in ChatGPT or Codex. ForgeRail is **not currently available there**: the local Skills-only candidate still needs separately approved submission, OpenAI review, and developer publication. When a verified ForgeRail listing becomes available, use that interface and confirm the publisher and requested capabilities before installation.
+- Codex with the `codex plugin` command available;
+- Git/network access to GitHub during installation;
+- a new Codex task after installation so Plugin discovery starts from a fresh host context.
 
-The current available Agent Plugin route is the immutable `v0.1.0-alpha.1` EchoPath Labs Marketplace snapshot:
+The target project does not require Node.js, `package.json`, `node_modules`, or `.forgerail/`. Node.js 22 or newer is required only if you choose to run ForgeRail's optional npm CLI.
+
+## Install the Codex Plugin
 
 ```bash
-codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4
 codex plugin add forgerail@echopath-labs
 ```
 
-Start a new Codex task after installation so discovery uses the installed snapshot. The new task must discover:
+Then start a new Codex task in the project you want to assess.
+
+## Verify the installation
+
+Run:
+
+```bash
+codex plugin list
+```
+
+Confirm that the `forgerail@echopath-labs` Plugin is enabled. In the new task, Codex should discover these four namespaced Skills:
 
 - `$forgerail`;
 - `$forgerail-workspace-diagnosis`;
-- `$workspace-health-review`.
+- `$workspace-health-review`;
+- `$architecture-convergence-audit`.
+
+If another Plugin defines the same short Skill name, use the exact namespaced name shown by Codex.
+
+## First use: stay read-only
 
-This Agent Plugin route does not require the target project to have Node.js, `package.json`, `node_modules`, or the optional npm CLI.
+Send this request to Codex:
 
-The versioned Marketplace registration is the Plugin release identity; do not replace the tag with a mutable branch when reproducibility matters. For local canonical testing, build a disposable bundle or npm tarball; do not point production workspaces at an uncommitted source tree.
+```text
+Use $forgerail to assess this project read-only. Follow its existing AGENTS.md,
+specification, ADR, CI, and documentation habits first. Do not modify files or
+perform remote actions. Recommend Plugin Only or Lightweight Adoption, show the
+evidence and uncertainties, and wait for my confirmation before any write.
+```
+
+A useful first result identifies the workspace and task boundary, applicable project rules, unresolved conflicts, the smallest suitable adoption level, validation evidence, explicit non-actions, and the next decision for a human. Installation alone never authorizes a write or remote operation.
 
 ## Optional Capability Pack Plugins
 
-Install only the packs the project needs. Installation makes a pack available; it does not authenticate, activate, require, or approve its external effects.
+Capability Packs are separate Plugins with separate authentication, risk, and lifecycle boundaries. Install only the ones the project actually needs:
 
 ```bash
 codex plugin add forgerail-github-rulesets@echopath-labs
@@ -36,59 +62,65 @@ codex plugin add forgerail-thread-closure@echopath-labs
 codex plugin add forgerail-cross-workspace-orchestration@echopath-labs
 ```
 
-The Rulesets and Release Safety packs remain read-first. Ruleset mutations, repository protection changes, publishing, deployment, and lifecycle changes require their own exact approvals.
-
-Install Cross-Workspace Orchestration only when a master task must coordinate multiple genuine owner/repository/release boundaries and dependency evidence exposes safe parallel stages. It is not for an ordinary single repository or monorepo folder split. Installation leaves it `available`; invoke it explicitly, or adopt it through existing project instructions only after review. It does not create tasks or durable records, and remote integration, release, and lifecycle approvals remain independent.
-
-Host task/thread APIs are not portable. Codex, Claude Code, Cursor, and other hosts must provide verified create/inspect/wait/message/resume capabilities through a Host Adapter; otherwise use user-created sessions, stable handoffs, or serial execution. RelayPact is an optional delegation transport and EchoPath is an optional recovery/context source, not runtime dependencies.
+Installation only makes a Pack available. It does not authenticate, enable, invoke, or approve the Pack, and it does not grant repository, release, deployment, or lifecycle authority.
 
 ## Optional npm CLI
 
-The npm package is not required by the Agent Plugin. The official package is organization-scoped as `@echopath-labs/forgerail`; the unscoped `forgerail` package remains a reservation and is not an install or rollback source. After registry publication, use an exact scoped prerelease when validating or diagnosing a workspace:
+The CLI is useful for deterministic validation or read-only diagnosis, but it is not required for Plugin use:
 
 ```bash
-npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 validate
-npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 diagnose --workspace .
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 diagnose --workspace .
 ```
 
-For a persistent CLI shim:
+For a global CLI:
 
 ```bash
-npm install --global @echopath-labs/forgerail@0.1.0-alpha.1
+npm install --global @echopath-labs/forgerail@0.1.0-alpha.4
 forgerail validate
 ```
 
-## Adoption
+The official package is scoped. The unscoped `forgerail` package is only a reservation and is not an installation source.
+
+## Upgrade or reinstall
 
-Installation makes capabilities available. It does not edit a project's `AGENTS.md`, create `.forgerail/`, install OpenSpec, or make Workspace Health mandatory. Project adoption is a separate, explicit decision.
+Marketplace registrations are exact-tag snapshots. To move to a newer release, remove the installed Plugin and Marketplace registration using the current `codex plugin` command surface, register the new exact tag, reinstall the Plugin, and start a new task. Verify the four Skills and repeat the read-only smoke test before relying on it.
 
-ForgeRail uses progressive adoption:
+Do not replace the exact tag with a mutable branch when reproducibility matters. An upgrade must not modify project files or persisted governance unless the user separately approves an exact adoption plan.
 
-1. **Plugin Only** is the default and leaves the workspace unchanged.
-2. **Lightweight Adoption** requires an exact read-only plan and user confirmation. One host gets a versioned managed block; multiple hosts may share `FORGERAIL.md` through thin bindings.
-3. **Persisted Governance** is evidence-gated and deferred in alpha.1; the CLI will not generate `.forgerail/` state.
+## Uninstall
 
-The optional CLI can prepare, but never apply, a candidate:
+Use `codex plugin remove forgerail@echopath-labs`, then remove the `echopath-labs` Marketplace registration if you no longer use any Plugin from it. Remove the optional global CLI with:
 
 ```bash
-forgerail adoption-plan --workspace . --host codex
-forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+npm uninstall --global @echopath-labs/forgerail
 ```
 
-Codex is the only `supported` Host Adapter in alpha.1. Claude Code and Cursor are published as `profile-only` boundaries so their target files and limitations are explicit without claiming verified activation. The host Agent must show the exact proposal, obtain confirmation, preserve unrelated content, write only the approved paths, then verify discovery in a new task or equivalent supported check and return a Host Binding Receipt.
+Uninstalling ForgeRail must not delete project instructions, specifications, receipts, Git history, or other project records. Remove a previously approved Lightweight Adoption block only through a separate reviewed change.
+
+## Troubleshooting
+
+### The Skills do not appear
+
+1. Confirm the Marketplace and Plugin are listed and enabled with `codex plugin list`.
+2. Confirm the registration is pinned to `v0.1.0-alpha.4`.
+3. Start a new Codex task; an already-running task may not refresh Plugin discovery.
+4. Use the namespaced Skill name if another Plugin or personal Skill has the same short name.
+
+### The project asks for Node.js
 
-See [Progressive Adoption](adoption.md) for the full model, support matrix, verification, and removal semantics.
+Plugin Only should not require project-local Node.js. Check that you are invoking the installed Plugin rather than running `npx`, `npm install`, or repository source. Please report a bug if normal Plugin use creates `package.json`, `node_modules`, or `.forgerail/`.
 
-## Upgrade And Reinstall
+### ForgeRail proposes too much process
 
-Register the new exact Marketplace tag, reinstall the selected Plugin names from `echopath-labs`, then start a new Codex task. Repeat Skill discovery and a bounded read-only diagnosis smoke. Upgrade only between exact `@echopath-labs/forgerail` versions. Reinstall must preserve project files and Profile sources.
+Ask it to remain read-only and explain why Plugin Only is insufficient. ForgeRail should recommend the smallest useful level and follow existing project governance before proposing new files.
 
-## Rollback And Uninstall
+### A command requests credentials or remote authority
 
-Re-register the last validated Marketplace tag and reinstall the selected Plugin names, or return to the frozen AGW version. Remove ForgeRail Plugins with the Codex plugin command surface and remove the optional CLI with `npm uninstall --global @echopath-labs/forgerail`; do not delete project records, Agent instructions, or Git history. AGW remains the compatibility rollback until the migration gate is separately approved.
+Stop and review the exact Pack, identity, scope, and approval boundary. ForgeRail installation is never approval for login, publishing, repository administration, deployment, or lifecycle mutation.
 
-## Release Boundary
+For more help, see [SUPPORT.md](../SUPPORT.md). Report security concerns privately using [SECURITY.md](../SECURITY.md).
 
-Creating or submitting a Universal Plugins Directory draft, publishing a reviewed listing, publishing npm, moving `latest`, pushing a public candidate, tagging, creating a GitHub Release, or changing AGW lifecycle requires its own exact approval and receipt.
+## Adoption is separate
 
-See the historical [ForgeRail 0.1.0-alpha.1 Release Runbook](release.md) for the current release and the [ForgeRail 0.1.0-alpha.2 Candidate Runbook](release-alpha2.md) for the proposed source-first gate order. Neither document grants execution authority.
+Installation makes ForgeRail available. It does not edit `AGENTS.md`, install OpenSpec, create `.forgerail/`, or make Workspace Health mandatory. See [Progressive Adoption](adoption.md) before approving any durable project integration.

package/docs/installation.zh-CN.md

@@ -1,23 +1,58 @@
-# 安装与采用
+# 安装 ForgeRail
 
-ForgeRail 的主要形态是 Agent Plugin；npm 包是可选的确定性 CLI 与兼容载荷。
+ForgeRail 首先是一个 Codex Agent Plugin。默认安装不会在目标项目中加入 Node.js、`package.json`、`node_modules` 或 `.forgerail/`。
 
-canonical source 当前拟议 `@echopath-labs/forgerail@0.1.0-alpha.2` / `v0.1.0-alpha.2`，但该候选尚未远端集成或发布。不要根据本地版本提案自行拼装安装命令。以下命令继续绑定当前已发布 alpha.1，直到另行批准的 alpha.2 发布完成。
+当前公开预发布版本是 `0.1.0-alpha.4`。请固定不可变 Git tag，让其他用户能够复现同一个 Plugin 快照。
 
-面向人的目标默认入口是 ChatGPT 或 Codex 中的 Universal Plugins Directory。ForgeRail **当前尚未在该目录上线**：本地 Skills-only 候选仍需独立提交审批、OpenAI 审查和开发者发布。以后只有在核对真实 ForgeRail listing、publisher 和能力请求后，才应从界面安装。
+## 准备条件
 
-当前可用的 Agent Plugin 路径是不可变的 EchoPath Labs Marketplace `v0.1.0-alpha.1` 快照：
+- Codex 已提供 `codex plugin` 命令；
+- 安装时能够通过 Git/网络访问 GitHub；
+- 安装后新建一个 Codex 任务，让宿主从新的上下文发现 Plugin。
+
+目标项目**不需要** Node.js。只有选择运行可选 npm CLI 时，才需要 Node.js 22 或更高版本。
+
+## 安装 Codex Plugin
 
 ```bash
-codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4
 codex plugin add forgerail@echopath-labs
 ```
 
-安装后启动一个新的 Codex 任务，使插件发现基于已安装快照。新任务必须发现 `$forgerail`、`$forgerail-workspace-diagnosis` 和 `$workspace-health-review`。需要可复现安装时，不要用可变分支替代精确 tag。
+然后在需要评估的项目中启动一个新的 Codex 任务。
+
+## 验证安装
+
+运行：
+
+```bash
+codex plugin list
+```
+
+确认 `forgerail@echopath-labs` 已启用。新任务应能发现四个带命名空间的 Skills：
 
-通过该 Agent Plugin 路径使用 ForgeRail，不要求目标项目安装 Node.js，也不要求存在 `package.json`、`node_modules` 或可选 npm CLI。
+- `$forgerail`；
+- `$forgerail-workspace-diagnosis`；
+- `$workspace-health-review`；
+- `$architecture-convergence-audit`。
 
-GitHub Rulesets、Release Safety 与 Thread Closure 是单独插件，只按项目需要安装：
+如果其他 Plugin 定义了同名短 Skill，请使用 Codex 显示的完整命名空间名称。
+
+## 第一次使用：保持只读
+
+把下面这段话发给 Codex：
+
+```text
+使用 $forgerail 对当前项目进行只读评估。优先沿用已有的 AGENTS.md、规格、
+ADR、CI 和文档习惯。不要修改文件，也不要执行远端操作。建议使用 Plugin Only
+还是 Lightweight Adoption，展示依据和不确定项，并在任何写入前等待我确认。
+```
+
+一个有用的首次结果应说明：工作区与任务边界、适用的项目规则、尚未解决的冲突、最小采用层级、验证依据、明确没有执行的动作，以及下一项需要人类判断的事情。仅安装 ForgeRail 绝不等于批准写入或远端操作。
+
+## 可选 Capability Pack Plugins
+
+Capability Pack 是独立 Plugin，拥有独立的认证、风险和生命周期边界。只安装项目真正需要的 Pack：
 
 ```bash
 codex plugin add forgerail-github-rulesets@echopath-labs
@@ -26,41 +61,65 @@ codex plugin add forgerail-thread-closure@echopath-labs
 codex plugin add forgerail-cross-workspace-orchestration@echopath-labs
 ```
 
-安装只让能力可用，不等于认证、启用、要求或批准外部副作用。Ruleset、仓库保护、发布、部署和生命周期变更仍需各自的精确审批。
-
-只有当主控任务需要协调多个真正独立的 owner workspace、repository 或 release identity，且依赖证据表明存在安全并行阶段时，才安装 Cross-Workspace Orchestration。普通单仓任务或 monorepo 目录拆分不适用。安装后状态仍是 `available`；必须显式调用，或在审查后沿用项目已有 instructions 采用。它不会自动创建任务或 durable record，远端集成、发布和 lifecycle 审批仍相互独立。
+安装只会让 Pack 可用，不会自动认证、启用、调用或批准它，也不会授予仓库管理、发布、部署或生命周期权限。
 
-不同宿主不共享同一套 task/thread API。Codex、Claude Code、Cursor 等必须由 Host Adapter 明确声明并验证 create/inspect/wait/message/resume 能力；缺失时降级为用户创建的独立会话、稳定 handoff 或串行执行。RelayPact 只是可选委派 transport，EchoPath 只是可选恢复/上下文来源，均非运行时硬依赖。
+## 可选 npm CLI
 
-安装只代表能力可用，不会修改项目 `AGENTS.md`、创建 `.forgerail/`、安装 OpenSpec 或要求项目启用 Workspace Health。项目采用、能力启用和长期规约变更都需要单独确认。
+CLI 可用于确定性验证或只读诊断，但不是使用 Plugin 的前提：
 
-ForgeRail 采用渐进式三级模型：
-
-1. **Plugin Only** 是默认状态，工作区零修改；
-2. **Lightweight Adoption** 必须先生成精确只读计划并经用户确认；单宿主使用带版本 managed block，多宿主可使用 `FORGERAIL.md` 加薄绑定；
-3. **Persisted Governance** 只在真实证据支持时考虑，alpha.1 延期且 CLI 不会生成 `.forgerail/` 状态。
+```bash
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 diagnose --workspace .
+```
 
-可选 CLI 只生成候选，不会应用：
+如果需要全局 CLI：
 
 ```bash
-forgerail adoption-plan --workspace . --host codex
-forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+npm install --global @echopath-labs/forgerail@0.1.0-alpha.4
+forgerail validate
 ```
 
-alpha.1 只有 Codex Host Adapter 是 `supported`；Claude Code 与 Cursor 以 `profile-only` 发布，明确目标入口与限制，但不声称已验证激活。宿主 Agent 必须展示精确候选、取得确认、保护无关内容、只写获批路径，再在新任务或等价支持检查中验证发现并返回 Host Binding Receipt。
+官方包是 scoped package。未加 scope 的 `forgerail` 只是名称保留包，不是安装来源。
+
+## 升级或重装
 
-完整模型、支持矩阵、验证与移除语义见[渐进式采用](adoption.zh-CN.md)。
+Marketplace 注册对应精确 tag 快照。升级时，应使用当前 `codex plugin` 命令先移除已安装 Plugin 和旧 Marketplace 注册，再注册新的精确 tag、重新安装 Plugin，并启动新任务。确认四个 Skills 可发现，并重新完成只读冒烟测试。
 
-Agent Plugin 不依赖 npm CLI。官方包名为 `@echopath-labs/forgerail`；未作用域 `forgerail` 只保留名称占位，不是安装或回滚来源。registry 发布后，可用精确 scoped 版本执行离线校验和只读诊断：
+需要可复现性时，不要用可变分支替代精确 tag。升级不能修改项目文件或持久治理状态，除非用户另外批准了精确的采用计划。
+
+## 卸载
+
+使用 `codex plugin remove forgerail@echopath-labs`；如果不再使用该 Marketplace 中的其他 Plugin，再移除 `echopath-labs` Marketplace 注册。可选全局 CLI 可这样移除：
 
 ```bash
-npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 validate
-npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 diagnose --workspace .
-npm install --global @echopath-labs/forgerail@0.1.0-alpha.1
+npm uninstall --global @echopath-labs/forgerail
 ```
 
-升级时注册新的精确 Marketplace tag，重新安装已选择的插件，再启动新的 Codex 任务验证 Skill 发现与只读诊断；npm CLI 只能在精确 `@echopath-labs/forgerail` 版本之间升级。回滚时重新注册最近已验证 tag，或退回冻结的 AGW 版本；卸载可选 CLI 使用 `npm uninstall --global @echopath-labs/forgerail`，不得删除项目记录、Agent instructions 或 Git 历史。
+卸载 ForgeRail 不应删除项目 instructions、规格、receipt、Git 历史或其他项目记录。已经批准的 Lightweight Adoption 内容只能通过另一次受审查的变更移除。
+
+## 常见问题
+
+### 看不到 Skills
+
+1. 使用 `codex plugin list` 确认 Marketplace 和 Plugin 已列出并启用。
+2. 确认 Marketplace 固定在 `v0.1.0-alpha.4`。
+3. 新建 Codex 任务；已运行的任务可能不会刷新 Plugin discovery。
+4. 如果有同名 Skill，使用带命名空间的完整名称。
+
+### 项目提示需要 Node.js
+
+Plugin Only 不应要求项目安装 Node.js。确认你调用的是已安装 Plugin，而不是在运行 `npx`、`npm install` 或仓库源码。如果正常 Plugin 使用创建了 `package.json`、`node_modules` 或 `.forgerail/`，请报告 bug。
+
+### ForgeRail 建议了过多流程
+
+要求它保持只读，并解释为什么 Plugin Only 不够。ForgeRail 应优先沿用项目已有治理方式，只建议最小有用层级。
+
+### 某个命令要求凭据或远端权限
+
+停止操作并核对准确的 Pack、身份、范围和审批边界。安装 ForgeRail 永远不代表批准登录、发布、仓库管理、部署或生命周期变更。
+
+更多帮助见 [SUPPORT.md](../SUPPORT.md)。安全问题请按 [SECURITY.md](../SECURITY.md) 私下报告。
 
-创建或提交 Universal Plugins Directory draft、发布已审查 listing、npm 发布、移动 `latest`、推送公共候选、tag、GitHub Release 和 AGW 生命周期变更都属于各自独立的精确审批门。
+## 安装不等于采用
 
-当前发布的历史门序见 [ForgeRail 0.1.0-alpha.1 发布 Runbook](release.zh-CN.md)，拟议 source-first 门序见 [ForgeRail 0.1.0-alpha.2 候选 Runbook](release-alpha2.zh-CN.md)。两份文档都不授予执行权限。
+安装只是让 ForgeRail 可用；它不会编辑 `AGENTS.md`、安装 OpenSpec、创建 `.forgerail/`，也不会强制使用 Workspace Health。批准任何持久项目接入前，请先阅读[渐进式采用](adoption.zh-CN.md)。

package/docs/release-alpha3.md

@@ -0,0 +1,25 @@
+# ForgeRail 0.1.0-alpha.3 Forward-Fix Runbook
+
+This source-first runbook governs the proposed `@echopath-labs/forgerail@0.1.0-alpha.3`, tag `v0.1.0-alpha.3`, and matching Agent Plugin projection. It does not grant `remote_integration_approval`, `release_approval`, `submission_approval`, `rollback_approval`, or `lifecycle_change_approval`. The unscoped `forgerail@0.0.0-reserved.0` remains a reservation and must never receive product code or serve as an install or rollback source.
+
+## Candidate integration
+
+The public candidate is an ordinary child of the observed remote `main`. That observed base is exactly `dba155d7f7092a3f852bf2c0244a35bd153fcedb`. A future exact `remote_integration_approval` may push only the signed commit to `codex/forgerail-alpha3-scoped`, create one Draft PR, and observe Node.js 22 and 24 Plugin Contracts CI. The Draft PR base and publication comparison baseline remain bound to the observed remote `main`.
+
+Any correction is an ordinary source-first successor commit. Do not force push, rewrite the candidate, transition the PR to Ready, merge, tag, publish, or create a release under remote-integration authority. Install and discover each external Capability Pack separately; availability never implies authentication, enablement, or mutation authority.
+
+## Compatibility proof
+
+The main Plugin must expose no more than three `defaultPrompt` entries while all four Skills remain independently discoverable and directly invokable. The third prompt is an either-or router between Workspace Health Review and Architecture Convergence Audit; it does not merge their ownership or activate both. Validate the exact projection in a fresh disposable Codex host and fail only on a ForgeRail-owned prompt-overflow warning. Icon path warnings owned by `openai-primary-runtime/template-creator` are external observations and must not be repaired by copying or editing that Plugin.
+
+## Separate release gate
+
+Only a later exact `release_approval` can authorize Ready/merge, scoped npm publication, dist-tags, annotated tag, GitHub prerelease, and disposable consumer verification. The merged public `main` tree must equal the final signed projection tree before release validation begins.
+
+Run Node.js 22 and 24 checks for Core, contracts, external Packs, frozen AGW behavior coverage, release source, Directory readiness, disposable consumer lifecycle, pack metadata, and audit. Verify GitHub API/SSH/npm identity as `chasechou007` without exposing credentials. Preserve Apache-2.0, the unscoped reservation, and the immutable alpha.1 and alpha.2 package/tag history.
+
+Do not unpublish or move an immutable version or Git tag. A shipped defect requires a forward version. Installation and diagnosis must leave project files unchanged unless the user separately approves an exact managed binding; return a Host Binding Receipt and confirm no implicit `.forgerail/` state.
+
+## Independent Directory and lifecycle gates
+
+Universal Plugins Directory draft, submission, review publication, verified publisher identity, Apps Management Write, portal regions and assets remain under a separate `submission_approval` or publication gate. AGW deprecation, redirect, archive, or deletion requires `lifecycle_change_approval`. No approval is transitive.

package/docs/release-alpha3.zh-CN.md

@@ -0,0 +1,25 @@
+# ForgeRail 0.1.0-alpha.3 Forward-Fix Runbook
+
+本 source-first runbook 约束拟议的 `@echopath-labs/forgerail@0.1.0-alpha.3`、tag `v0.1.0-alpha.3` 与对应 Agent Plugin 投影。文档本身不授予 `remote_integration_approval`、`release_approval`、`submission_approval`、`rollback_approval` 或 `lifecycle_change_approval`。未作用域 `forgerail@0.0.0-reserved.0` 继续只作占位，不得接收产品代码，也不是安装或回滚来源。
+
+## 候选集成
+
+公共候选是已观测远端 `main` 的普通子 commit。该基线精确为 `dba155d7f7092a3f852bf2c0244a35bd153fcedb`。未来精确 `remote_integration_approval` 只能把签名 commit 推到 `codex/forgerail-alpha3-scoped`，创建一个 Draft PR，并观察 Node.js 22 and 24 Plugin Contracts CI。Draft PR base 与 publication comparison baseline 继续绑定已观测远端 `main`。
+
+任何修正都必须形成普通的 source-first successor commit。remote integration 权限不允许 force push、历史重写、转 Ready、merge、tag、publish 或创建 Release。每个外部 Capability Pack 分别安装与发现；可用不等于认证、启用或获得 mutation authority。
+
+## 兼容性证明
+
+主 Plugin 的 `defaultPrompt` 不得超过三条，同时四个 Skills 必须继续独立发现与直接调用。第三条只是 Workspace Health Review 与 Architecture Convergence Audit 的二选一路由，不合并 owner，也不同时激活两者。必须在 fresh disposable Codex host 验证精确投影，只有 ForgeRail 自有 prompt overflow warning 才判失败。归属 `openai-primary-runtime/template-creator` 的 icon 路径告警是 external observation，不得通过复制或修改该外部 Plugin 修复。
+
+## 独立发布门
+
+只有后续精确 `release_approval` 才能授权 Ready/merge、scoped npm 发布、dist-tag、annotated tag、GitHub prerelease 与一次性消费者验证。发布验证开始前，合并后的公共 `main` tree 必须等于最终签名 projection tree。
+
+在 Node.js 22 和 24 上运行 Core、contracts、external Packs、冻结 AGW 行为覆盖、release source、Directory readiness、一次性 consumer、pack metadata 与 audit。不得暴露凭据地确认 GitHub API/SSH/npm 身份为 `chasechou007`。保持 Apache-2.0、未作用域占位，以及不可变 alpha.1/alpha.2 package/tag 历史。
+
+Do not unpublish 或移动不可变 version/tag。已发布缺陷使用前向版本修复。安装和诊断默认不修改项目；只有用户另行批准精确 managed binding 后才写入，并返回 Host Binding Receipt，确认没有隐式 `.forgerail/` 状态。
+
+## 独立 Directory 与生命周期门
+
+Universal Plugins Directory draft、submit、review publication、verified publisher identity、Apps Management Write、portal regions/assets 继续属于独立 `submission_approval` 或 publication gate。AGW deprecation、redirect、archive 或 deletion 需要 `lifecycle_change_approval`。任何审批都不传递。