aimship 0.1.0-preview.4 → 0.1.0-preview.7

package/CONTRIBUTING.md

@@ -9,3 +9,25 @@ Keep agent workflow semantics in `skills/aimship/references`, deterministic file
 A passing structural test does not prove agent behavior. Record actual host/version/model/permission conditions for behavioral checks; leave unavailable combinations unverified. Review affected changes and preserve historical failure evidence when retesting.
 
 Use GitHub Issues for bugs and feature suggestions. Provide the version, host details and a minimal synthetic reproduction; redact credentials, personal paths and delivery data.
+
+## Documentation
+
+Users enter through the English/Chinese README and Guide. Keep both languages equivalent when changing installation, workflow or artifact rules. The Guide owns installation, usage, continuation, lifecycle and troubleshooting; old installation/example URLs retain short compatibility pointers. The [CLI protocol](docs/cli.md) serves agents and contributors.
+
+Validate public links and the shared stage/template mapping with `npm run check:docs`. Treat [artifact-map.json](skills/aimship/references/artifact-map.json) and the [document rules](skills/aimship/references/document-patterns.md) as the mapping to check against; update user-facing explanations when that mapping changes.
+
+<a id="executable-examples"></a>
+## Executable examples
+
+From a source checkout, run:
+
+```sh
+node scripts/run-examples.mjs <new-output-directory>
+```
+
+The output directory must not exist. The harness creates isolated code and delivery folders, exercises real functions with Node assertions, and saves readable documents, state and evidence. It does not install Aimship, touch user deliveries, access the network or publish anything. Do not use a real delivery as the output. The scripts are source-checkout tools, not installed user commands.
+
+- **Authored, single batch:** a line-normalization PRD, plan before implementation, one review covering batch/overall scope, and independent normal/empty/error assertions. Execution updates the same plan; cases and RUN results share the testing document.
+- **Adopted, multiple batches:** preserved catalog PRD/prototype inputs, Scope mappings, shared price validation and quoting with each batch reviewed. A discount change keeps case v1 and adds v2, updates earlier review applicability and binds exact code hashes. A deliberate rounding fault produces a failed RUN, followed by repair review and a successful retest while retaining failure history. Shared business rules, role restrictions and performance requirements have independent identities and acceptance.
+
+These examples check local document/state behavior. They do not establish automatic Skill discovery, real cross-host continuation, UI interaction or HTTP acceptance. Run output records assertions and limitations. Results from older schemas do not establish current behavior.

package/README.md

@@ -1,45 +1,90 @@
 # Aimship
 
-[中文](README.zh-CN.md)
+[中文](README.zh-CN.md) · [Guide](docs/guide.md)
 
-Aimship helps you organize and carry out development tasks in AI coding tools. Use it to develop features, fix bugs, refactor code or prepare a design.
+**A development workflow for AI coding tools, connecting requirements, implementation and verification.**
 
-From the initial request to delivery, Aimship arranges the stages needed for the task and keeps a record of requirements, designs, progress and results. When requirements change, the relevant materials are updated. New conversations can continue from those records, reducing the need to explain the background again or organize progress notes manually.
+Aimship supports feature development, defect fixes, technical refactoring and solution design. It arranges stages around the delivery goal, maintains requirements, design, implementation and verification records, and supports continuation from existing materials.
 
-Each task has its own delivery folder under `~/Aimship/`, while code stays in its repository. You can work on several independent tasks at once, or limit a task to requirements analysis or design.
+Each request has an independent delivery directory under `~/Aimship/`, while code remains in its repositories. A commission can cover the full development workflow or specific outputs such as requirements analysis or technical design.
 
-## Installation
+## Quick start
 
-Requires Node.js 22+ and npm. Select a host with `--host`: `codex`, `cursor` or `claude-code`.
+Requires **Node.js 22+ and npm**. Choose `codex`, `cursor` or `claude-code`:
 
 ```sh
 npx aimship@preview install --host codex
 ```
 
-The npm command becomes available when the preview is published. For the current source or a local package, see the [installation guide](docs/installation.md).
-
-Aimship shares one installation across projects and selected hosts. It does not require a global npm install. After installation, start a new host session and enable access to the delivery folder and code repositories as needed.
-
-## Usage
-
-Select Aimship in the host: `$aimship` in Codex CLI, or `/aimship` in Cursor and Claude Code. Describe the intended result:
+Start a new host session and select Aimship: `$aimship` in Codex CLI, or `/aimship` in Cursor and Claude Code. Authorize access to the delivery folder and relevant repositories when needed, then describe the work:
+
+> Use Aimship to add Excel export to the order list. The code is in my existing repository. Complete implementation and verification; leave deployment for later.
+
+The npm command installs the published preview channel. For a specific version, source checkout or local package, see the [installation instructions](docs/guide.md#install).
+
+One installation serves your projects and selected hosts. Host integrations are experimental: actual Skill discovery and cross-host continuation still need validation. See [host setup](docs/guide.md#hosts) if Aimship does not appear.
+
+## Delivery workflow
+
+1. **Establish the requirements.** Preserve original inputs, author a PRD or adopt existing requirements through Scope, and agree on the outcome and execution order.
+2. **Prepare the work.** Produce the needed prototype, technical design, contracts, implementation plan and test cases.
+3. **Implement and review.** Implement each batch and review it, then review the integrated change.
+4. **Verify and hand off.** Execute the cases against the actual result, preserve failures and retests, and record the outcome and remaining work.
+
+This outlines the development delivery process; not every request requires every stage. Design-only, review-only and verification-only commissions stop at their agreed endpoint. Ordinary debugging stays in the current workflow; a separate investigation stage is used only when explicitly arranged.
+
+<a id="what-a-delivery-contains"></a>
+## Delivery structure and documents
+
+**`status.md`** is the delivery overview, with the current stage, blockers, next actions and document links. The tree below lists delivery artifacts and their purposes. Files are generated according to the selected stages and input conditions; unselected stages produce no empty documents. `prd.md` and `scope.md` are alternative requirement entries, not two files required for every delivery.
+
+```text
+~/Aimship/
+├── 20261023-order-export/         # One request, one delivery folder
+│   ├── status.md                 # Generated overview and reading entry
+│   ├── prd.md                    # Authored requirements, scope and acceptance
+│   ├── scope.md                  # Used instead of PRD when adopting authoritative inputs
+│   ├── tech-design.md            # Architecture, changes, data, risks and requirement coverage
+│   ├── plan.md                   # Implementation batches, tasks and actual execution
+│   ├── testing.md                # Test cases, coverage, runs and retest results
+│   ├── review.md                 # Batch/overall reviews, findings and follow-up
+│   ├── handoff.md                # Delivered result, usage, validation and remaining work
+│   ├── diagnosis.md              # Only for an independent investigation
+│   ├── change-log.md             # Meaningful changes, decisions and affected work
+│   ├── openapi.yaml              # New HTTP contract; reuse an existing authority when available
+│   ├── database.sql              # SQL for one database; multiple targets use database-<id>.sql
+│   ├── prototype/                # Newly authored prototypes when required
+│   │   └── index.html            # Entry for an HTML prototype; its assets stay here
+│   ├── source/                   # Preserved original request and adopted input versions
+│   │   ├── request.md            # Original commission or source entry
+│   │   └── …                     # External PRD, prototype, screenshots and other inputs
+│   └── .aimship/                 # Managed state and supporting evidence
+│       ├── state.json            # Stages, references, versions and repository/worktree links
+│       ├── state.previous.json   # Previous state for recovery after writes
+│       ├── view.json             # Metadata for the generated status view
+│       └── evidence/             # Evidence retained when needed
+└── 20261024-another-request/      # Independent request and progress
+```
 
-> Use Aimship to add Excel export to the order list.
+Formal documents are directly in the request folder. `source/` preserves adopted originals; `.aimship/` holds internal records. The software itself is installed separately in `~/.aimship/`.
 
-Aimship uses the request and available materials to clarify the scope and arrange the work. Include any specific limits in your request, such as “Design only for this task.”
+Filenames, outlines and identifier rules come from shared templates. Requirements and acceptance criteria link to implementation tasks, reviews and versioned test cases/results. The [Guide](docs/guide.md#artifacts) explains exactly when each artifact is produced and what it contains.
 
-To continue in a new session, provide the existing delivery directory:
+## Use cases and examples
 
-> Use Aimship to continue the task in `~/Aimship/order-export/`.
+| Use case | Example request |
+| --- | --- |
+| Existing PRD and prototype | “Use these materials for order export. Preserve the originals and confirm the scope before implementation.” |
+| Feature requirements and design | “Help define notification preferences and produce a prototype and technical design. Stop before implementation.” |
+| Refactor | “Refactor the pricing module without changing observable behavior. Implement and verify it.” |
+| Investigate a failure | “Investigate this intermittent timeout and report the cause and evidence. Do not implement a fix yet.” |
 
-Use the same delivery directory when switching hosts, with access authorized separately in each host. Multiple independent deliveries can progress at once; keep one writing session per delivery. See the [user guide](docs/guide.md#work-on-two-requests-at-once) for shared-repository and worktree examples.
+Independent deliveries can progress at the same time, with one writing session per delivery. When they share code, arrange sequential implementation or separate checkouts/worktrees. See [parallel work](docs/guide.md#parallel).
 
-## Documentation and feedback
+## Documentation and contributions
 
-- [Installation guide](docs/installation.md): host setup, updates, version and status queries, uninstall and troubleshooting.
-- [User guide](docs/guide.md): scope, stages, changes, parallel deliveries and session handoff.
-- [Tool protocol](docs/cli.md): state and recovery commands for agents and contributors.
+The **[Guide](docs/guide.md)** covers installation, daily use, document rules, continuation, updates and troubleshooting. For contributors, [CONTRIBUTING](CONTRIBUTING.md) covers development and checks; the [CLI protocol](docs/cli.md) is the agent/tool reference.
 
-The preview is intended for experimentation and feedback. Host integration requirements are described in the installation guide. Report bugs and feature requests through [GitHub Issues](https://github.com/clsx/aimship/issues). See [Contributing](CONTRIBUTING.md) to contribute.
+Report bugs and feature requests through [GitHub Issues](https://github.com/clsx/aimship/issues). Aimship is a preview; completed work, user acceptance, merge and deployment are recorded separately.
 
 Released under the [MIT License](LICENSE).

package/README.zh-CN.md

@@ -1,45 +1,90 @@
 # Aimship
 
-[English](README.md)
+[English](README.md) · [使用指南](docs/guide.zh-CN.md)
 
-Aimship 帮助你在 AI 编程工具中组织和推进开发任务，适用于功能开发、问题修复、技术重构和方案设计。
+**面向 AI 编程工具的开发交付流程，贯通需求、实施与验证。**
 
-从提出需求到完成交付，Aimship 根据任务需要安排工作阶段，并保存需求、设计、进度和结果。需求发生变化时，相关资料随之更新；切换会话后，可以根据已有记录继续工作，减少重复解释背景和手动整理进度的负担。
+Aimship 适用于功能开发、缺陷修复、技术重构和方案设计。根据交付目标安排所需阶段，维护需求、设计、实施和验证记录，并支持基于已有资料接续工作。
 
-每项任务在 `~/Aimship/` 下拥有独立的交付资料目录，代码保留在原仓库。你可以同时推进多个独立任务，也可以只委托其中的需求分析或设计工作。
+每个需求在 `~/Aimship/` 下使用独立交付目录，代码保留在原仓库。交付范围可以覆盖完整开发流程，也可以限定为需求分析、技术方案等指定成果。
 
-## 安装
+## 快速开始
 
-需要 Node.js 22+ 和 npm。通过 `--host` 选择宿主：`codex`、`cursor` 或 `claude-code`。
+需要 **Node.js 22+ 和 npm**。宿主可选 `codex`、`cursor` 或 `claude-code`：
 
 ```sh
 npx aimship@preview install --host codex
 ```
 
-此 npm 命令在预览版发布后可用。当前源码或本地安装包的使用方式见[安装指南](docs/installation.md)。
-
-多个项目和已接入宿主共用一份 Aimship，无需全局安装 npm 包。安装后开启新的宿主会话，并按实际需要授权访问交付目录和代码仓库。
-
-## 使用
-
-在宿主中选择 Aimship：Codex CLI 使用 `$aimship`，Cursor 和 Claude Code 使用 `/aimship`，随后描述预期结果：
+安装后开启新的宿主会话，选择 Aimship：Codex CLI 使用 `$aimship`，Cursor 和 Claude Code 使用 `/aimship`。在需要时授权访问交付目录和相关代码仓库，然后描述任务：
+
+> 使用 Aimship 给订单列表增加 Excel 导出功能。代码在我现有的仓库中。本次完成实施和验证，部署留待后续处理。
+
+该 npm 命令安装已发布的预览通道版本。指定版本、源码或本地包的安装方式，参见[安装说明](docs/guide.zh-CN.md#install)。
+
+安装一次即可用于多个项目和已选择的宿主。宿主集成仍处于实验阶段，真实 Skill 发现和跨宿主接续仍需验证。宿主未显示 Aimship 时，请参阅[宿主设置](docs/guide.zh-CN.md#hosts)。
+
+## 交付流程
+
+1. **明确需求。** 保留原始资料，自编 PRD 或通过 Scope 承接已有需求，确认本次目标和执行顺序。
+2. **准备实施。** 按确定的条件产出原型、技术方案、契约、实施计划和测试用例。
+3. **实施与审核。** 每批实施后进行 review，全部完成后再做整体 review。
+4. **验证与交接。** 对实际成果执行用例，保留失败和重测记录，说明交付结果与遗留事项。
+
+这是开发交付的基本过程，并非每个需求都要执行全部阶段。只做设计、review 或验证的委托，在约定的终点结束。普通调试在当前流程中处理；只有明确安排独立调查时才加入调查阶段。
+
+<a id="一个需求会留下哪些文档"></a>
+## 交付目录与文档
+
+**`status.md`** 是交付进度的统一阅读入口，包含当前阶段、阻塞事项、后续操作和文档链接。下方列出交付产物及其用途；实际生成范围由所选阶段和输入条件确定，未选阶段不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
+
+```text
+~/Aimship/
+├── 20261023-订单导出/             # 每个需求一个独立交付目录
+│   ├── status.md                 # 自动生成的进度总览和阅读入口
+│   ├── prd.md                    # 自编需求：目标、范围、需求和验收标准
+│   ├── scope.md                  # 采用权威外部资料时使用，替代自编 PRD
+│   ├── tech-design.md            # 技术方案：架构、改动、数据、风险和需求覆盖
+│   ├── plan.md                   # 实施计划：批次、任务及实际执行记录
+│   ├── testing.md                # 测试用例、覆盖关系、执行与重测结果
+│   ├── review.md                 # 各批及整体审核、发现的问题和处理结论
+│   ├── handoff.md                # 交付结果、使用方式、验证结论和遗留事项
+│   ├── diagnosis.md              # 仅独立调查时生成的定位与证据记录
+│   ├── change-log.md             # 重要变更、决定及受影响的工作
+│   ├── openapi.yaml              # 新建 HTTP 契约；已有权威契约优先复用
+│   ├── database.sql              # 单数据库 SQL；多目标为 database-<id>.sql
+│   ├── prototype/                # 符合生成条件时新建的原型
+│   │   └── index.html            # HTML 原型入口，相关资源也放在此目录
+│   ├── source/                   # 保留原始需求和采用的外部资料版本
+│   │   ├── request.md            # 原始委托或来源入口
+│   │   └── …                     # 外部 PRD、原型、截图及其他输入
+│   └── .aimship/                 # 工具维护的内部状态与辅助证据
+│       ├── state.json            # 阶段、引用、版本及仓库／worktree 关联
+│       ├── state.previous.json   # 写入后用于恢复的上一版状态
+│       ├── view.json             # 进度视图的生成元信息
+│       └── evidence/             # 按需保留的验证等证据
+└── 20261024-另一个需求/           # 独立的资料与进度
+```
 
-> 使用 Aimship，为订单列表增加导出 Excel 的功能。
+正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
 
-Aimship 会根据需求和已有资料帮助明确范围、安排工作。有具体限制时，可以在需求中补充，例如“本次只完成设计”。
+文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[使用指南](docs/guide.zh-CN.md#artifacts)进一步说明每种文档的生成条件和具体内容。
 
-在新会话中继续工作时，提供已有交付目录：
+## 适用场景与示例
 
-> 使用 Aimship 继续 `~/Aimship/order-export/` 中的任务。
+| 场景 | 委托示例 |
+| --- | --- |
+| 已有 PRD 和原型 | “根据这些资料开发订单导出，保留原件，实施前先确认本次范围。” |
+| 功能需求分析与设计 | “梳理通知偏好功能，完成原型和技术方案，本次先不实施。” |
+| 技术重构 | “重构计价模块，不改变对外行为，完成实施和验证。” |
+| 故障调查 | “调查偶发超时的原因，给出证据和结论，本次先不修复。” |
 
-切换宿主时使用同一交付目录，并分别完成访问授权。多个独立交付可以同时推进；同一次交付保持一个写入会话。同仓库与 worktree 的使用实例见[使用指南](docs/guide.md#work-on-two-requests-at-once)。
+多个独立需求可以同时推进，每个交付只保留一个写入会话。共享代码时，安排串行实施或使用独立 checkout／worktree，详见[并行需求](docs/guide.zh-CN.md#parallel)。
 
-## 文档与反馈
+## 文档与贡献
 
-- [安装指南](docs/installation.md)：宿主接入、更新、版本与状态查询、卸载及常见问题。
-- [使用指南](docs/guide.md)：范围、阶段、变更、并行交付与会话交接。
-- [工具协议](docs/cli.md)：供 Agent 与贡献者使用的状态及恢复命令。
+**[使用指南](docs/guide.zh-CN.md)**涵盖安装、日常使用、文档规则、进度接续、升级和排障。[CONTRIBUTING](CONTRIBUTING.md)说明开发与贡献要求；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
 
-预览版用于试用和收集反馈，宿主集成要求见安装指南。Bug 和功能建议请通过[GitHub Issues](https://github.com/clsx/aimship/issues) 提交；参与贡献请参阅[贡献说明](CONTRIBUTING.md)。
+通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈问题和建议。Aimship 目前为预览版；目标完成、用户验收、合并和部署分别记录。
 
-本项目采用 [MIT 许可证](LICENSE)。
+采用 [MIT 许可证](LICENSE)。

package/docs/cli.md

@@ -1,62 +1,82 @@
 # Local tool protocol
 
-The agent normally runs these tools to handle file structure and version/revision checks, not business decisions. Cross-delivery overlap checking is an agent workflow using existing state and focused local Git metadata, not a CLI concurrency guarantee or a new registry. All commands emit JSON; errors include a code, message and recovery advice with a nonzero exit status. Run `node bin/aimship.mjs help` in a source checkout for the complete current interface.
+Commands emit JSON. Errors include code/message/recovery and use a nonzero exit. `help` describes options; installation `status` is separate from a delivery's generated `status.md`. The agent interprets business meaning and authorization. Examples use placeholders for absolute paths and the bound version.
 
-## Bind and create
+## Create and bind
 
-An installed entry invokes the stable `.aimship/bin/aimship.mjs` launcher. `bind` returns the active immutable release, core, stage directory, CLI path, rules version, configured material root and config/custom locations. Use the returned fixed CLI and version for this session. Paths in examples below are placeholders to replace with your actual paths, safely quoted for your shell.
+`bind` returns fixed CLI/core/stage paths, version and configured data root. Keep that binding for the session. Installation does not create deliveries.
 
-```sh
-node '<stable-launcher>' bind
-node '<fixed-cli>' init '<delivery-dir>' --rules-version '0.1.0-preview.4' --input '<init.json>'
-```
-
-Before `init`, save the original request and current requirements/Scope in the actual delivery directory. `init` creates state once; it does not create requirement templates or infer authority. Minimal input:
+Before init, save `source/request.md` and the PRD/Scope draft from the [templates](../skills/aimship/references/document-patterns.md). No templates are automatically created. Example input:
 
 ```json
 {
-  "goal": {"summary": "Explain the selected design", "endpoint": "Design handoff"},
-  "goalRef": "requirements.md",
-  "stageRuns": [],
-  "next": {"action": "Record the agreed stage arrangement", "inputRefs": ["requirements.md"]}
+  "goal": {"summary":"Define the selected design", "endpoint":"Design handoff"},
+  "goalRef":"prd.md",
+  "documentPolicy":{"authority":"authored","interaction":false,"prototypeCovered":false,"interface":"none","databases":[]},
+  "documents":[{"kind":"prd","path":"prd.md","mode":"new","version":"1"}],
+  "stageRuns":[],
+  "next":{"action":"Draft the agreed design","inputRefs":["prd.md"]}
 }
 ```
 
-Identity, schema/rules version, revision and timestamps are tool-managed. Do not include them in init input. A useful arrangement contains distinct `stageRuns` with `id`, `stage`, `scope`, `progress`, `inputRefs`, and `outputRefs`. `currentRun` names one of them or is null. Associate repositories as `{id, path, role}` with an absolute actual checkout/worktree root. IDs are local to this delivery; they do not establish cross-delivery repository identity. Use role and current scope to distinguish read-only reference from intended code writes; record actual authorized scope and working basis in the associated requirements/evidence.
+```sh
+node '<stable-launcher>' bind
+node '<fixed-cli>' init '<delivery-dir>' --rules-version '<bound-version>' --input '<init.json>'
+```
+
+init allocates deliveryId and revision 0, creates `.aimship/state.json`, and generates `status.md`. Add that ID to the document information at the next save point. Identity/version/timestamps, documentDigests, identityHistory, retiredIdentities and legacyRunIds are managed; never supply them in a patch. `writeResult` is return metadata, not state input.
+
+`documentPolicy.authority`: authored → prd.md; adopted → scope.md; editable → an explicitly authorized existing PRD containing this commission's complete scope/authorization/endpoint. `legacy` is migration-only. `interaction`, `prototypeCovered`, `interface` (none/http/other) and target `databases` IDs record artifact conditions. They do not select a preset route.
 
-## Read, update and check
+Register documents as `{kind,path,mode,version}`. Kinds: prd, scope, tech-design, plan, testing, review, diagnosis, handoff, change-log, prototype, contract, sql, source. New formal Markdown follows the artifact map's root filename and ordered anchors. Reused files additionally need `basisRef` recording location/version/coverage/gaps and editability; unsupported content is explicitly not checked. New HTML prototype is prototype/index.html; register other agreed formats. HTTP contracts use openapi.yaml unless reused. SQL filenames follow database count. Source files are immutable adopted versions by workflow, not OS access controls.
+
+## Update and inspect
 
 ```sh
-node '<fixed-cli>' read '<delivery-dir>' --rules-version '0.1.0-preview.4'
-node '<fixed-cli>' update '<delivery-dir>' --revision 0 --rules-version '0.1.0-preview.4' --input '<patch.json>'
-node '<fixed-cli>' check '<delivery-dir>' --rules-version '0.1.0-preview.4'
-node '<fixed-cli>' resume '<delivery-dir>' --rules-version '0.1.0-preview.4'
+node '<fixed-cli>' read '<delivery-dir>' --rules-version '<bound-version>'
+node '<fixed-cli>' update '<delivery-dir>' --revision 0 --rules-version '<bound-version>' --input '<patch.json>'
+node '<fixed-cli>' check '<delivery-dir>' --all --rules-version '<bound-version>'
+node '<fixed-cli>' resume '<delivery-dir>' --rules-version '<bound-version>'
 ```
 
-Use the revision just read; a conflict requires rereading and reconciling. Updates recursively merge objects but replace arrays in full. `null` is a value, not deletion. `--input -` reads a JSON object from stdin. Completed stage runs need `resultRef`; retained old results use `priorResultRef` or `historyResultRefs`. Removing an already-started run or historical result reference is rejected.
+Objects merge, arrays replace entirely; null is literal, not deletion. `--input -` accepts stdin JSON. A revision conflict requires rereading and reconciling, not guessing a revision. Keep one writing session per delivery.
+
+Stage runs are ordered `{id,stage,scope,progress,inputRefs,outputRefs}`. currentRun refers to one ID or null. Progress: planned/active/blocked/done; result: passed/failed/not-run/unknown/mixed; applicability: current/needs-review/unknown. Done requires a precise resultRef. Preserve past results in priorResultRef/historyResultRefs; do not delete started runs. Shared files never complete two runs automatically. Plan must complete before implementation; batch review, then overall review, then independent verify remains the agent's semantic responsibility.
 
-References are delivery-relative, `repo:<id>/<relative-path>`, or HTTP(S) URLs, with optional fragments. Current checks inspect goal/next/current-input paths; `--all` also checks registered historical, decision, outcome, checkpoint and rule-change references. A file-existence result does not validate its fragment, contents or meaning. Remote references are not fetched by this tool. `resume.canProceed` is false for a recorded blocked current run, missing input paths or version mismatch. A true value only means these structural blockers were not found; the agent still checks authority, unresolved decisions and stage completion. Unknown schemas remain readable but cannot be overwritten.
+New Markdown uses explicit `<a id="..."></a>` anchors. Definition metadata in the document supplies namespace/ID/version/status/refs; see document-patterns. REV and RUN additionally set `run` to the stageRun ID and use a result anchor such as `review.md#rev-001-v1` or `testing.md#run-001-v1`. Basic uniqueness, exact reference resolution, REQ→AC, AC→TC and RUN→TC versions are checked; prose truth, every-assertion coverage and object versions require Agent review. `nextIds` reports historical maxima plus one, including retired IDs. Keep historical definitions; retired identities cannot be reused.
 
-`progress` is planned/active/blocked/done. Results are passed/failed/not-run/unknown/mixed; applicability is current/needs-review/unknown. `outcome.goal` is in-progress/met/not-met/unknown; acceptance is not-recorded/accepted/declined/unknown. A met goal requires a goal conclusion reference; acceptance requires its own decision reference. These are separate from merge/deployment references. The agent must assess the evidence; fields are not proof of success.
+References stay delivery-root-relative despite state being internal, or use `repo:<id>/<path>` / HTTP(S). Repository records `{id,path,role}` name actual absolute checkout/worktree roots. A branch is not a code version. Paths cannot escape roots through traversal or symlinks. check defaults to current inputs; --all adds registered history/decisions/outcomes. Exact fragments in registered new Markdown are checked; reused/remote/unsupported ones return not-checked. That does not establish semantics or passing verification.
 
-Changing the goal or goal reference requires a new `goal.decisionRef`; the tool preserves the old goal and outcome. Reopening increments `cycle` by one, retains a prior closure reference and resets current acceptance. Important changes remain in `openChanges` with stable ID/reference and open/closed status rather than disappearing when resolved.
+Read/check/resume are read-only. They return view diagnostics and changed registered documents; matching revisions do not prove unchanged formal content. Resume canProceed is conservative structural readiness, never authorization or acceptance. Read returns conflicting layout candidates and unknown formats without rewriting them. `scan <material-root>` reads immediate delivery children in both layouts, deduplicates deliveryId and reports conflicting/unknown/inaccessible records. It neither scans unknown roots nor determines code-writing safety; inspect recorded roles/scopes and actual Git/worktree identity.
 
-## Recovery and rules adoption
+## State and view recovery
 
-Writes save `state.previous.json` and replace state atomically. If state is damaged, inspect actual artifacts and the backup before explicit recovery:
+State writes are atomic per file and keep `.aimship/state.previous.json`. Across formal documents/state/status there is no transaction. First persist unfinished intent, edit and inspect documents, then save state. Managed document digests detect some external changes, never semantic equivalence.
+
+A write returns the actual state revision and `writeResult: {stateSaved:true,revision,view}`. If view status is protected/error, the JSON is already saved. Do not replay the business patch; explicitly repair:
 
 ```sh
-node '<fixed-cli>' recover '<delivery-dir>' --revision '<backup-revision>' --rules-version '<bound-version>'
+node '<fixed-cli>' render '<delivery-dir>' --revision '<saved-revision>' --rules-version '<bound-version>'
+node '<fixed-cli>' render '<delivery-dir>' --revision '<saved-revision>' --rules-version '<bound-version>' --preserve-edits
 ```
 
-Recovery preserves damaged bytes and refuses to roll back a valid or newer unknown state. It cannot reconstruct unrecorded effects. A stale lock requires confirming there is no active writer before removing only that lock. No parallel workflow scheduling is provided.
+The delivery identity, view digest and state revision are stored in `.aimship/view.json`; identity and revision must both match for a view to be current. Missing/stale views can be regenerated; modified or untrusted existing status is preserved in place by default. --preserve-edits first saves its full bytes to `.aimship/status-edits-<id>.md`, then rebuilds. Inspect the preserved intent and update formal authority separately. View text does not authorize acceptance, scope changes or publication. render does not increment state revision.
+
+`recover <dir> --revision <backup-revision> --rules-version <bound-version>` restores only over missing/corrupt state, preserves corrupt bytes and advances revision. It refuses a valid or unknown state. Inspect actual effects afterward, never automatically repeat them. Remove only a stale task lock after confirming no writer exists.
 
-When an upgrade makes an old session mismatch, stop new stages. A compatible old tool can `checkpoint` only `{checkpoint: {summary, ref?}, next: {...}}` with its old rules version and current revision. It cannot complete a run or goal. Reload the active rules, inspect compatibility at a stable point, then use the active tool's `adopt` with input `{compatibilityRef: "results.md#rules-switch"}`. This records a rule switch without changing historical business facts. Schema 1 is the initial format; no legacy DeliveryArc migration or invented older Aimship migration is provided. Unsupported formats require a future supported migration and remain preserved meanwhile.
+## Explicit migration and rule adoption
+
+Schema 1 root state remains readable; normal updates/adopt require migration first. Unknown schemas stay read-only. To migrate one selected old delivery, record a compatibility assessment and original/new artifact mapping:
+
+```sh
+node '<new-fixed-cli>' migrate '<delivery-dir>' --revision '<old-revision>' --rules-version '<new-version>' --input '<assessment.json>'
+node '<new-fixed-cli>' adopt '<delivery-dir>' --revision '<returned-revision>' --rules-version '<new-version>' --input '<assessment.json>'
+```
 
-## Installation diagnostics
+Both inputs are `{"compatibilityRef":"change-log.md#rules-switch"}`. Migration saves original state/recovery bytes under `.aimship/legacy/`, journals checksums in `.aimship/migration.json`, converts layout/schema and increments revision while retaining old rulesVersion. Interrupted migration resumes with the original parameters only after checksum checks; conflicting copies are preserved. Adopt separately records the assessed rule change. It does not convert business meaning.
 
-User-facing installation, explicit update, version/status and uninstall commands are documented in one [installation guide](installation.md). `install` performs software installation and updates; this protocol's `update` continues to mean a revision-checked delivery-state update.
+Reconcile legacy documents by role, preserve original text/results/version basis, register reused files or create new forward-looking documents. Move evidence/host configuration only with mapped references and correct relative-link/workspace resolution. Never fabricate a past plan stage or tests. Unchanged completed historical execution records retain their old format, verified against the preserved migration target. Changing applicability alone does not rewrite that history. Planned or in-progress runs and any run whose execution facts change must satisfy current artifact contracts; an old ID is not an exemption. After adoption, legacy document policy still blocks stage/outcome advancement and resume readiness; reconcile documents and set the current policy first. Subsequent new runs follow the new mapping. Finished deliveries are never swept by install.
 
-`--version` distinguishes the CLI/tool version from the active installed release. Use the stable launcher for the current installation. `status` is read-only, inspects the known installation and managed entry files, and reports registration separately from entry integrity. It does not establish host loading, login, permissions or semantic delivery readiness. The key fields are `installation`, `healthy`, `installedActiveVersion`, `pending`, `registeredHosts`, `hosts`, and `issues`. Each host separates `registered`, `entryPresent`, `entryIntegrity`, `sharedWith`, `hostLoaded`, `login`, and `permissions`; the final three remain `not-verified`. `unselectedHostDiscoveryPossible` warns about compatible discovery. A diagnostic command may exit successfully while reporting `healthy: false`; inspect its data. `--version` includes `toolVersion` and `installedActiveVersion`, which may differ when called from an older release.
+A compatible old fixed tool can checkpoint only next/checkpoint facts during version mismatch, once per active version. It cannot complete stages. Save before migration, reload new rules, migrate then adopt. Old tools must not write migrated schema 2. No DeliveryArc migration is provided.
 
-Installation transition results include previous and target versions; failures retain pending information for recovery. Disconnecting a named host retains the core, even when no registered hosts remain; full uninstall is a separate invocation without `--host`. Shared entries needed by another registration remain present. No purge-history command exists.
+Goal changes need a new goal.decisionRef; prior goals/outcomes are retained. A met goal requires goalConclusionRef; acceptance needs its own acceptanceRef. Merge and deployment refs remain independent. Reopening increments cycle, appends closureRefs and resets acceptance. See the [user guide](guide.md#update) for lifecycle operations and their separate host-discovery limits.

package/docs/examples.md

@@ -0,0 +1,5 @@
+# Executable examples moved
+
+The synthetic examples are developer checks. Their instructions and coverage now live in [Contributing](../CONTRIBUTING.md#executable-examples).
+
+For everyday use, see the [Guide](guide.md) or [中文使用指南](guide.zh-CN.md).