aimship 0.1.0-preview.4 → 0.1.0-preview.8

package/CONTRIBUTING.md

@@ -9,3 +9,62 @@ 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
+
+The English/Chinese README introduces the software delivery workflow, its value and outputs, and owns installation, upgrades, host management, version/health queries and uninstallation. The Guide owns the annotated delivery directory and document overview, and explains usage by scenario: starting from an idea, adopting materials, changing existing code, reading results, changing requirements, continuing and completing delivery. Avoid fixed prompt examples. Keep detailed artifact, stage and identifier rules in the bilingual [document reference](docs/reference.md). Keep both languages equivalent. Put source development and isolated validation procedures here, and agent/tool details in the [CLI protocol](docs/cli.md). Old installation/example URLs retain short compatibility pointers rather than duplicate command instructions.
+
+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="isolated-installation-check"></a>
+## Isolated installation lifecycle check
+
+This is a contributor check of a package's installer and fixed launcher, not a required user setup sequence. For source development, run `npm pack` from the checkout to obtain a local tarball. Use a new candidate version when distributed content changes; do not replace an already released or installed version with different contents.
+
+Place the package in the current directory and replace `VERSION` below. This POSIX shell example creates a disposable home and npm cache, runs from a separate consumer directory so npm cannot select the source checkout, and removes its temporary files on exit. Capture stdout outside the temporary directory if you need to retain evidence.
+
+```sh
+(
+  set -eu
+  package_file="file:$(pwd -P)/aimship-VERSION.tgz"
+  trial=$(mktemp -d)
+  trial=$(cd "$trial" && pwd -P)
+  trap 'rm -rf "$trial"' EXIT
+  mkdir "$trial/consumer"
+  cd "$trial/consumer"
+  run_package() {
+    npx --yes --offline --cache "$trial/npm-cache" "$package_file" "$@" --home "$trial/home"
+  }
+
+  run_package install --host codex
+  node "$trial/home/.aimship/bin/aimship.mjs" --version
+  node "$trial/home/.aimship/bin/aimship.mjs" status
+  run_package install --host cursor
+  run_package uninstall --host cursor
+  run_package status
+  run_package uninstall
+  run_package status
+)
+```
+
+Inspect the JSON results: installation should activate the package version; the fixed launcher should report that same installed version and healthy files; adding Cursor should retain Codex; disconnecting Cursor should retain Codex and the core; full uninstall should leave no active release or registered hosts. The two `node` calls deliberately exercise the installed launcher independently of npx. Delivery data, custom files, modified files and upgrade/recovery behavior require separate fixtures and assertions; this smoke check does not cover them.
+
+`--home` redirects managed installation files only. It does not make a running host discover that home or grant directory permissions. Never replace the disposable home with a real user home for validation. A successful lifecycle check does not establish real host discovery or cross-host continuation.
+
+<a id="executable-examples"></a>
+## Executable examples
+
+The harness records explicitly labeled synthetic self-checks and approvals, exercises review stops before automatic continuation, and preserves CHG/reapproval history. These are deterministic tool checks, not real user decisions or host E2E evidence.
+
+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,152 @@
 # 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 software delivery workflow for AI tools, connecting requirements, design, implementation, review 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.
+You provide the goal, existing materials and code locations. Aimship helps the agent turn them into a clear scope, a reasoned design, an implementation plan and verified results. It connects these stages so that you can follow the work, understand key decisions and assess what has actually been delivered.
 
-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.
+<a id="what-a-delivery-contains"></a>
+<a id="delivery-structure-and-documents"></a>
+<a id="delivery-artifacts"></a>
+Standard document outlines, identifiers and references connect requirements and acceptance criteria to designs, implementation tasks, reviews and test results. Documents are produced as needed for the delivery goal, giving you a consistent basis for review without requiring an empty template for every stage.
 
+<a id="delivery-workflow"></a>
+By default, you review documents individually after the agent's self-check. The agent presents the document, a short summary and the next step, then waits for your review. Explicit approval automatically advances to the next authorized stage according to your arrangements; requested changes lead to revision, self-check and another review. Document approval remains separate from final delivery acceptance.
+
+Documents and state are saved throughout the work, keeping progress, decisions and verification evidence traceable and reducing the need to repeat background or reconstruct earlier work.
+
+[Install](#install) · [Guide](docs/guide.md) · [Upgrade and AI tools](#update) · [Uninstall](#uninstall)
+
+<a id="quick-start"></a>
+<a id="install"></a>
 ## Installation
 
-Requires Node.js 22+ and npm. Select a host with `--host`: `codex`, `cursor` or `claude-code`.
+Requires **Node.js 22+ and npm**. Command examples use a POSIX shell.
+
+### Published preview
 
 ```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).
+Choose `codex`, `cursor` or `claude-code`. To connect several tools, repeat the option:
+
+```sh
+npx aimship@preview install --host codex --host claude-code
+```
+
+Confirm npm's package installation prompt. `@preview` selects the published preview channel; an exact published version, such as `@0.1.0-preview.7`, can be used instead. The preview channel is experimental and does not imply a stable release.
+
+### A specific version or local package
+
+To install an exact published version, for example:
+
+```sh
+npx aimship@0.1.0-preview.7 install --host codex
+```
+
+If you already have an Aimship `.tgz` package, replace `VERSION` with its actual version and run from the directory containing it:
+
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
+```
+
+Choose one installation method. No global npm installation, administrator privilege or npm login is required; the npm cache must be writable. For source development and isolated installation checks, see [Contributing](CONTRIBUTING.md#isolated-installation-check).
+
+### Optional: choose a delivery material location
+
+The default delivery material root is `~/Aimship/`. On the first installation, use `--data-root` to choose another location:
+
+```sh
+npx aimship@preview install --host codex --data-root "$HOME/MyDeliveries"
+```
+
+This sets the default material location for new deliveries. It is not a code repository location and does not move existing materials. Later installations retain the configuration; no per-project installation is needed.
+
+After installation, follow the [Guide](docs/guide.md#hosts) to select Aimship in your tool. AI tool integrations are experimental: actual Skill discovery and continuation across AI tools still need validation.
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+<a id="upgrades-and-host-management"></a>
+<a id="upgrades-and-ai-development-tools"></a>
+## Upgrades and AI tools
+
+For the published preview channel:
+
+```sh
+npx aimship@preview install
+```
+
+Installation and upgrades use the same `install` command. Existing tool registrations, configuration, custom content and deliveries are retained. The installer reports previous/target versions, results and conflicts; no background updater or resident process runs. For a specific version or local package, use the [installation commands](#install) against the original installation home.
+
+<a id="add-a-host"></a>
+<a id="add-an-ai-development-tool"></a>
+### Add an AI tool
+
+For example, connect Cursor after installing for Codex:
+
+```sh
+npx aimship@preview install --host cursor
+```
+
+This retains existing tools and installs the selected preview version; it also upgrades the software if the preview channel has advanced. Then refresh the relevant session as described in [tool setup](docs/guide.md#hosts).
 
-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.
+### Check the installed version
 
-## Usage
+```sh
+npx aimship@preview --version
+```
 
-Select Aimship in the host: `$aimship` in Codex CLI, or `/aimship` in Cursor and Claude Code. Describe the intended result:
+In the output, `installedActiveVersion` is the active installed version and `toolVersion` is the package npx is running. They may differ. This query does not upgrade the installation.
 
-> Use Aimship to add Excel export to the order list.
+### Check installation health
 
-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.”
+```sh
+npx aimship@preview status
+```
+
+This checks the software installation, tool registrations and managed files, reporting health and pending problems. It cannot confirm that a tool loaded the Skill. For delivery progress, open that delivery's `status.md`.
+
+These commands use npx to obtain and run the selected package. During delivery work, the agent uses the fixed local launcher and rules without repeated package downloads.
+
+After an upgrade, save current work and follow [session continuation](docs/guide.md#continue) to reconcile rules and delivery state. Upgrading the software does not automatically migrate existing deliveries.
+
+<a id="uninstall"></a>
+## Uninstallation
+
+Disconnect one tool while retaining the core and other registrations:
+
+```sh
+npx aimship@preview uninstall --host cursor
+```
+
+Shared entries remain when another registered tool needs them. Disconnecting the last tool still retains the core for diagnostics or reconnection; compatible tools might continue discovering a remaining shared entry.
+
+Remove all managed software and tool entries:
+
+```sh
+npx aimship@preview uninstall
+```
 
-To continue in a new session, provide the existing delivery directory:
+Full uninstall retains delivery materials, user code, custom files and necessary configuration. Modified/unowned files are preserved and reported. The launcher is removed on complete removal. Restart tool sessions to discard cached rules. Deleting delivery history is a separate explicit action.
 
-> Use Aimship to continue the task in `~/Aimship/order-export/`.
+<a id="installation-troubleshooting"></a>
+## Installation and upgrade problems
 
-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.
+| Symptom | What to do |
+| --- | --- |
+| Aimship is absent or duplicated | Refresh the session and inspect entries using [tool setup](docs/guide.md#hosts); installation health does not prove the tool loaded the Skill. |
+| A managed path is modified or occupied by other files | Preserve the contents, inspect ownership and explicitly reconcile customizations before retrying. |
+| Installation was interrupted or the launcher is damaged | Use the `status` command above, resolve the cause, then rerun the exact pending version against the same home. Do not switch versions during recovery. Append `--home <installation-home>` when checking a custom installation home. |
+| Unexpected version | Compare `installedActiveVersion` and `toolVersion`, then refresh the session's rules before continuing delivery work. |
+| Package/version unavailable or download failed | Check the package, exact version and registry; a failed download is not a completed installation. |
 
-## 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.
+<a id="use-cases-and-examples"></a>
+The **[Guide](docs/guide.md)** explains how to start work, review documents, inspect results, handle changes and resume. The [document reference](docs/reference.md) covers artifact rules; [CONTRIBUTING](CONTRIBUTING.md) covers development and isolated validation; the [CLI protocol](docs/cli.md) serves agents and tool developers.
 
-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.
+Aimship is in preview, with ongoing improvements to the workflow, usability and compatibility. Share problems and suggestions from actual use through [GitHub Issues](https://github.com/clsx/aimship/issues); read the contribution guide before contributing to development.
 
 Released under the [MIT License](LICENSE).

package/README.zh-CN.md

@@ -1,45 +1,152 @@
 # Aimship
 
-[English](README.md)
+[English](README.md) · [使用指南](docs/guide.zh-CN.md)
 
-Aimship 帮助你在 AI 编程工具中组织和推进开发任务，适用于功能开发、问题修复、技术重构和方案设计。
+**面向 AI 工具的软件交付流程，贯通需求、设计、实施、审核与验证。**
 
-从提出需求到完成交付，Aimship 根据任务需要安排工作阶段，并保存需求、设计、进度和结果。需求发生变化时，相关资料随之更新；切换会话后，可以根据已有记录继续工作，减少重复解释背景和手动整理进度的负担。
+你提供目标、已有资料和代码位置，Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
 
-每项任务在 `~/Aimship/` 下拥有独立的交付资料目录，代码保留在原仓库。你可以同时推进多个独立任务，也可以只委托其中的需求分析或设计工作。
+<a id="一个需求会留下哪些文档"></a>
+<a id="交付目录与文档"></a>
+<a id="交付成果"></a>
+统一的文档大纲、编号和引用，将需求与验收标准关联到设计、实施任务、审核和测试结果。文档按交付目标和实际需要生成，既提供一致的阅读与核对依据，也不要求每个阶段都填一份空模板。
 
+<a id="交付流程"></a>
+默认由你逐份审核经过 Agent 自检的文档。Agent 给出文档、短摘要和下一步，等待你审核；明确通过后，按你的安排自动衔接下一授权阶段。提出修改意见时，Agent 修订、自检后重新送审。文档通过与最终交付验收分别记录。
+
+文档与状态在工作过程中持续保存，使进度、决定和验证依据可追溯，减少重复交代背景和重新梳理已有工作的负担。
+
+[安装](#install) · [使用指南](docs/guide.zh-CN.md) · [升级与 AI 工具管理](#update) · [卸载](#uninstall)
+
+<a id="快速开始"></a>
+<a id="install"></a>
 ## 安装
 
-需要 Node.js 22+ 和 npm。通过 `--host` 选择宿主：`codex`、`cursor` 或 `claude-code`。
+需要 **Node.js 22+ 和 npm**。以下命令使用 POSIX shell 写法。
+
+### 安装已发布的预览版
 
 ```sh
 npx aimship@preview install --host codex
 ```
 
-此 npm 命令在预览版发布后可用。当前源码或本地安装包的使用方式见[安装指南](docs/installation.md)。
+AI 工具可选 `codex`、`cursor` 或 `claude-code`。连接多个 AI 工具时重复该选项：
+
+```sh
+npx aimship@preview install --host codex --host claude-code
+```
+
+按 npm 提示确认获取安装包。`@preview` 表示已发布的预览通道，也可以替换为明确版本号，例如 `@0.1.0-preview.7`。预览通道用于实验性版本，不代表稳定版。
+
+### 指定版本或本地包
+
+安装指定的已发布版本，例如：
+
+```sh
+npx aimship@0.1.0-preview.7 install --host codex
+```
+
+如果已有 Aimship 的 `.tgz` 安装包，将 `VERSION` 替换为实际版本号，在包所在目录执行：
+
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
+```
+
+选择一种安装方式即可。不需要全局 npm 安装、管理员权限或 npm 登录；npm 缓存需要可写。源码开发和隔离安装验证见[贡献指南](CONTRIBUTING.md#isolated-installation-check)。
+
+### 可选：指定交付资料位置
+
+默认交付资料根目录为 `~/Aimship/`。首次安装时，可以用 `--data-root` 指定其他位置：
+
+```sh
+npx aimship@preview install --host codex --data-root "$HOME/MyDeliveries"
+```
+
+此选项设置后续新交付的默认资料位置，不是代码仓库位置，也不会搬迁已有资料。后续安装保留已有配置；无需逐项目安装。
+
+安装后，按[使用指南](docs/guide.zh-CN.md#hosts)在 AI 工具中选择 Aimship。AI 工具集成仍处于实验阶段，真实 Skill 发现和跨工具接续仍需验证。
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+<a id="升级与宿主管理"></a>
+<a id="升级与-ai-开发工具管理"></a>
+## 升级与 AI 工具管理
+
+升级到已发布的预览通道版本：
+
+```sh
+npx aimship@preview install
+```
+
+安装和升级使用同一个 `install` 命令。已有 AI 工具登记、配置、自定义内容和交付资料都会保留。安装器报告旧／目标版本、结果及冲突；没有后台自动升级或常驻进程。指定版本或本地包也使用[安装说明](#install)中的命令，指向原来的安装目录。
+
+<a id="添加宿主"></a>
+<a id="添加-ai-开发工具"></a>
+### 添加 AI 工具
+
+例如，已有 Codex 安装后再接入 Cursor：
+
+```sh
+npx aimship@preview install --host cursor
+```
+
+该命令保留已有 AI 工具，同时安装所选预览版本；如果预览通道有更新，也会升级软件。随后按[AI 工具设置](docs/guide.zh-CN.md#hosts)刷新对应会话。
 
-多个项目和已接入宿主共用一份 Aimship，无需全局安装 npm 包。安装后开启新的宿主会话，并按实际需要授权访问交付目录和代码仓库。
+### 查询已安装版本
 
-## 使用
+```sh
+npx aimship@preview --version
+```
 
-在宿主中选择 Aimship：Codex CLI 使用 `$aimship`，Cursor 和 Claude Code 使用 `/aimship`，随后描述预期结果：
+输出中的 `installedActiveVersion` 是当前已安装版本，`toolVersion` 是此次 npx 运行的包版本，两者可能不同。查询本身不会升级安装。
 
-> 使用 Aimship，为订单列表增加导出 Excel 的功能。
+### 检查安装状态
 
-Aimship 会根据需求和已有资料帮助明确范围、安排工作。有具体限制时，可以在需求中补充，例如“本次只完成设计”。
+```sh
+npx aimship@preview status
+```
+
+此命令检查软件安装、AI 工具登记和受管理文件，报告是否健康及待处理问题；它不能确认 AI 工具已加载 Skill。查看需求进度请打开交付目录的 `status.md`。
+
+以上命令由 npx 获取并运行所选包；日常交付由 Agent 使用固定的本地入口和规则，无需反复下载包。
+
+升级后，先保存当前工作，再按[会话接续](docs/guide.zh-CN.md#continue)核对规则和交付状态；已有交付不会因为软件升级自动完成迁移。
+
+<a id="uninstall"></a>
+## 卸载
+
+只断开一个 AI 工具，保留核心和其他 AI 工具登记：
+
+```sh
+npx aimship@preview uninstall --host cursor
+```
+
+其他已登记 AI 工具还需要的共享入口会保留。断开最后一个 AI 工具也保留核心，以便诊断或重新连接；兼容 AI 工具仍可能发现剩余的共享入口。
+
+移除所有受管理的软件和 AI 工具入口：
+
+```sh
+npx aimship@preview uninstall
+```
 
-在新会话中继续工作时，提供已有交付目录：
+完整卸载保留交付资料、用户代码、自定义文件和必要配置。修改过或不属于它管理的文件会保留并报告。完全移除后，稳定入口也会移除；重启 AI 工具会话以清除缓存规则。删除交付历史是另一项需要明确提出的操作。
 
-> 使用 Aimship 继续 `~/Aimship/order-export/` 中的任务。
+<a id="installation-troubleshooting"></a>
+## 安装与升级问题
 
-切换宿主时使用同一交付目录，并分别完成访问授权。多个独立交付可以同时推进；同一次交付保持一个写入会话。同仓库与 worktree 的使用实例见[使用指南](docs/guide.md#work-on-two-requests-at-once)。
+| 现象 | 处理方式 |
+| --- | --- |
+| 找不到 Aimship 或出现重复项 | 按[AI 工具设置](docs/guide.zh-CN.md#hosts)刷新会话并检查入口；安装健康不代表 AI 工具已经加载 Skill。 |
+| 管理位置被修改或被其他文件占用 | 保留内容，检查归属，明确合并定制内容后再重试。 |
+| 安装中断或稳定入口损坏 | 使用上面的 `status` 命令检查安装，排除原因后在同一目录重跑完全相同的待恢复版本；不要在恢复途中换版本。自定义安装用户目录可追加 `--home <安装用户目录>` 进行检查。 |
+| 版本与预期不一致 | 核对版本查询中的 `installedActiveVersion` 和 `toolVersion`，继续交付前刷新会话中的规则。 |
+| 包／版本不存在或下载失败 | 核对包名、明确版本和 registry；下载失败不算安装完成。 |
 
-## 文档与反馈
+## 文档与贡献
 
-- [安装指南](docs/installation.md)：宿主接入、更新、版本与状态查询、卸载及常见问题。
-- [使用指南](docs/guide.md)：范围、阶段、变更、并行交付与会话交接。
-- [工具协议](docs/cli.md)：供 Agent 与贡献者使用的状态及恢复命令。
+<a id="适用场景与示例"></a>
+**[使用指南](docs/guide.zh-CN.md)**说明如何开始需求、审核文档、查看成果、处理变更和接续。[交付文档参考](docs/reference.zh-CN.md)说明产物规则；[CONTRIBUTING](CONTRIBUTING.md)说明开发和隔离验证；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
 
-预览版用于试用和收集反馈，宿主集成要求见安装指南。Bug 和功能建议请通过[GitHub Issues](https://github.com/clsx/aimship/issues) 提交；参与贡献请参阅[贡献说明](CONTRIBUTING.md)。
+Aimship 目前处于预览阶段，流程、使用体验和兼容性仍在完善。欢迎通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈实际使用中遇到的问题和改进建议；参与开发请先阅读贡献指南。
 
-本项目采用 [MIT 许可证](LICENSE)。
+采用 [MIT 许可证](LICENSE)。

package/docs/cli.md

@@ -1,62 +1,98 @@
 # 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>'
+```
 
-## Read, update and check
+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.
+
+Register documents as `{kind,path,mode,version,assetRefs?}`. List local/repository prototype images, scripts and other review-relevant assets in assetRefs so their bytes participate in the document fingerprint; the Agent must identify the complete asset set. 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.
 
-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.
+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.
 
-`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.
+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.
 
-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.
+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.
 
-## Recovery and rules adoption
+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.
 
-Writes save `state.previous.json` and replace state atomically. If state is damaged, inspect actual artifacts and the backup before explicit recovery:
+## State and view 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.
+
+## 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>'
+```
+
+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.
+
+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.
+
+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.
+
+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 [README](../README.md#update) for software lifecycle operations and the [Guide](guide.md#hosts) for host-discovery limits.
+
+## Document review protocol
+
+Schema 2 now includes `reviewPolicy: 1` and append-only `reviewHistory` (new deliveries default to both). Old states remain readable with `review-adoption-required`; at the recorded compatibility point enable the policy with an empty history, without inventing historical approval. Rule adoption and document approval remain separate. This additive protocol requires the current rules version; keep old tools bound to their old rules.
+
+Each record has `{id, kind, document, version, digest, sourceRef, summary}`. Kinds are `self-check`, `approved`, `changes-requested`, and `editorial`. `self-check` requires `result: "passed"` or `"failed"`; only a passing self-check can support approval. `approved` additionally requires `decision: "explicit-approval"`; `editorial` requires `previousDigest`. Use unique local review-record IDs (for example `approval-1`); these are state record identifiers, not a replacement for REQ/AC/CHG. Send the complete preserved history plus new records through revision-checked `update`. Existing records cannot be edited, removed or reordered. The tool records `sourceDigest` from readable local or repo-relative evidence; keep it unchanged when sending history back. Evidence files are versioned/immutable: changed or missing evidence produces evidence-changed and does not release dependencies; preserve the original bytes and add new decisions in new evidence files. Evidence fragments use explicit anchors. A remote source must have a local preserved decision excerpt with its original locator and date.
 
-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.
+`read`, `check`, and `resume` return `review.documents` with current `path`, `version`, `digest`, `selfCheck`, `approval` and status. First append a self-check of those exact bytes; after presenting the document and receiving explicit approval, append an approved record binding the same version/digest and the actual user message. Questions, silence, and “show the result” cannot be recorded as approval. A hash/source reference validates the record's content basis, **not user identity or authenticity**. Never synthesize a real approval to make an update pass.
 
-## Installation diagnostics
+Production `progress: done` may be saved while approval is pending. Starting/completing dependent runs is blocked until prerequisite completion and document approval are current. Runs default to depending on their predecessor; explicit `dependsOn: [preceding-run-ids]` supports recorded independent branches, while input/output producers and earlier selected development prerequisites also apply. The initial applicable development order is requirements/Scope, technical design, interface/SQL, test-design, plan, implement. Unselected stages are not created. Contract can produce only SQL when no interface change applies; technical design no longer requires SQL files before completion.
 
-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.
+For new `plan.md` and `testing.md`, fingerprints cover the content before the fixed `execution` and `runs` anchors respectively. Append implementation and RUN/conclusion evidence after those boundaries. Reused formats and other documents use whole-file content; remote/binary or linked-asset semantic inspection still belongs to the host/Agent. `done`, matching hashes and structural checks do not prove semantic quality.
 
-`--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 material change needs an open CHG with impact/decision evidence, a revised document version, a new self-check and explicit reapproval. Old review records remain. Affected producer/dependent runs become `needs-review`; update currentRun/next to the re-review stop and restore applicability after evidence-backed rechecking in dependency order. Independent branches are preserved. An `editorial` record carries a prior approval only after a same-version self-check explains a formatting/typo change and references its previous digest; it is not a new user approval. Do not hide changed design in excluded result sections. Final `outcome.acceptance` stays independent.
 
-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.
+See the [Agent review workflow](../skills/aimship/references/document-review.md) for presentation, automatic continuation after approval and compatibility responsibilities.

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).