aimship 0.1.0-preview.7 → 0.1.0-preview.9

package/CONTRIBUTING.md

@@ -12,13 +12,50 @@ Use GitHub Issues for bugs and feature suggestions. Provide the version, host de
 
 ## 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.
+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 generic prompt tutorials; a contextual continuation entry belongs in the Guide. Keep detailed artifact, stage and identifier rules in the bilingual [Guide appendix](docs/guide.md#document-details). 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
@@ -31,3 +68,17 @@ The output directory must not exist. The harness creates isolated code and deliv
 - **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.
+
+## Preview releases
+
+The [Publish preview workflow](.github/workflows/publish-preview.yml) is manually dispatched in `clsx/aimship`. It does not publish on push. Review and commit the versioned source, run tests and documentation/package checks, push the default branch and an exact `vX.Y.Z-preview.N` tag, then select that same tag as both the workflow ref and its `tag` input. The tagged commit must contain the workflow and matching `package.json` version. For example, with the GitHub CLI:
+
+```sh
+gh workflow run publish-preview.yml --repo clsx/aimship --ref vX.Y.Z-preview.N -f tag=vX.Y.Z-preview.N
+```
+
+Validation runs on a GitHub-hosted runner without OIDC permission. It checks the release context, runs the full tests and documentation/package checks, and packs once. Every tarball member is compared with the source. The publishing job receives that exact artifact, rechecks its source and digest, and publishes `aimship` publicly to `https://registry.npmjs.org` with the `preview` tag. It verifies the downloaded bytes, provenance and unchanged `latest` tag. Actions and runner Node/npm versions are pinned in the workflow; these CI versions are not a replacement for the package's stated runtime requirements or a claim of cross-platform validation.
+
+The npm package's trusted publisher must identify GitHub Actions, owner `clsx`, repository `aimship`, workflow filename `publish-preview.yml`, no environment, and allow direct `npm publish`. Staged publishing is not used. No long-lived npm token is stored. Only the publishing job has `id-token: write`; both jobs have `contents: read`. This is an ongoing publishing permission for that workflow, so changes to it deserve release-security review. A newly created npm trust must complete its first successful publication within npm's required window; see [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+On any uncertain publish result, inspect the registry and run logs before retrying. An existing version with different integrity stops the workflow; an identical version is verified without republishing. Missing provenance or unexpected dist-tags also stops verification rather than silently changing settings. Preserve the run URL, commit, artifact digest and registry outcome. Create the GitHub prerelease separately after successful npm verification, using the same tag and validated package; the publishing workflow has no repository write permission. Do not reuse a released version for changed package contents.

package/README.md

@@ -2,89 +2,151 @@
 
 [中文](README.zh-CN.md) · [Guide](docs/guide.md)
 
-**A development workflow for AI coding tools, connecting requirements, implementation and verification.**
+**A software delivery workflow for AI tools, connecting requirements, design, implementation, review and verification.**
 
-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.
+For developers responsible for delivering a requirement. 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 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.
+<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 current status, the document and review focus, then waits. After explicit approval is saved, work continues within the group; at a suggested session boundary it provides next work and a continuation entry, with the option to continue here; requested changes lead to revision, self-check and another review. Document approval remains separate from final delivery acceptance; an explicitly limited partial result is not presented as standard complete delivery.
+
+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)
 
-## Quick start
+<a id="quick-start"></a>
+<a id="install"></a>
+## Installation
 
-Requires **Node.js 22+ and npm**. Choose `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
 ```
 
-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:
+Choose `codex`, `cursor` or `claude-code`. To connect several tools, repeat the option:
 
-> 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.
+```sh
+npx aimship@preview install --host codex --host claude-code
+```
 
-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).
+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.
 
-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.
+### A specific version or local package
 
-## Delivery workflow
+To install an exact published version, for example:
 
-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.
+```sh
+npx aimship@0.1.0-preview.7 install --host codex
+```
 
-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.
+If you already have an Aimship `.tgz` package, replace `VERSION` with its actual version and run from the directory containing it:
 
-<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
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
 ```
 
-Formal documents are directly in the request folder. `source/` preserves adopted originals; `.aimship/` holds internal records. The software itself is installed separately in `~/.aimship/`.
+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).
 
-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.
+### Optional: choose a delivery material location
 
-## Use cases and examples
+The default delivery material root is `~/Aimship/`. On the first installation, use `--data-root` to choose another location:
 
-| 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.” |
+```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
+```
 
-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).
+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).
+
+### Check the installed version
+
+```sh
+npx aimship@preview --version
+```
+
+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.
+
+### Check installation health
+
+```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
+```
+
+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.
+
+<a id="installation-troubleshooting"></a>
+## Installation and upgrade problems
+
+| 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 contributions
 
-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.
+<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. Artifact and traceability details are also in the Guide; [CONTRIBUTING](CONTRIBUTING.md) covers development and isolated validation; the [CLI protocol](docs/cli.md) serves agents and tool developers.
 
-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.
+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

@@ -2,89 +2,151 @@
 
 [English](README.md) · [使用指南](docs/guide.zh-CN.md)
 
-**面向 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**。宿主可选 `codex`、`cursor` 或 `claude-code`：
+需要 **Node.js 22+ 和 npm**。以下命令使用 POSIX shell 写法。
+
+### 安装已发布的预览版
 
 ```sh
 npx aimship@preview install --host codex
 ```
 
-安装后开启新的宿主会话，选择 Aimship：Codex CLI 使用 `$aimship`，Cursor 和 Claude Code 使用 `/aimship`。在需要时授权访问交付目录和相关代码仓库，然后描述任务：
+AI 工具可选 `codex`、`cursor` 或 `claude-code`。连接多个 AI 工具时重复该选项：
 
-> 使用 Aimship 给订单列表增加 Excel 导出功能。代码在我现有的仓库中。本次完成实施和验证，部署留待后续处理。
+```sh
+npx aimship@preview install --host codex --host claude-code
+```
 
-该 npm 命令安装已发布的预览通道版本。指定版本、源码或本地包的安装方式，参见[安装说明](docs/guide.zh-CN.md#install)。
+按 npm 提示确认获取安装包。`@preview` 表示已发布的预览通道，也可以替换为明确版本号，例如 `@0.1.0-preview.7`。预览通道用于实验性版本，不代表稳定版。
 
-安装一次即可用于多个项目和已选择的宿主。宿主集成仍处于实验阶段，真实 Skill 发现和跨宿主接续仍需验证。宿主未显示 Aimship 时，请参阅[宿主设置](docs/guide.zh-CN.md#hosts)。
+### 指定版本或本地包
 
-## 交付流程
+安装指定的已发布版本，例如：
 
-1. **明确需求。** 保留原始资料，自编 PRD 或通过 Scope 承接已有需求，确认本次目标和执行顺序。
-2. **准备实施。** 按确定的条件产出原型、技术方案、契约、实施计划和测试用例。
-3. **实施与审核。** 每批实施后进行 review，全部完成后再做整体 review。
-4. **验证与交接。** 对实际成果执行用例，保留失败和重测记录，说明交付结果与遗留事项。
+```sh
+npx aimship@0.1.0-preview.7 install --host codex
+```
 
-这是开发交付的基本过程，并非每个需求都要执行全部阶段。只做设计、review 或验证的委托，在约定的终点结束。普通调试在当前流程中处理；只有明确安排独立调查时才加入调查阶段。
+如果已有 Aimship 的 `.tgz` 安装包，将 `VERSION` 替换为实际版本号，在包所在目录执行：
 
-<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-另一个需求/           # 独立的资料与进度
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
 ```
 
-正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
+选择一种安装方式即可。不需要全局 npm 安装、管理员权限或 npm 登录；npm 缓存需要可写。源码开发和隔离安装验证见[贡献指南](CONTRIBUTING.md#isolated-installation-check)。
 
-文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[使用指南](docs/guide.zh-CN.md#artifacts)进一步说明每种文档的生成条件和具体内容。
+### 可选：指定交付资料位置
 
-## 适用场景与示例
+默认交付资料根目录为 `~/Aimship/`。首次安装时，可以用 `--data-root` 指定其他位置：
 
-| 场景 | 委托示例 |
-| --- | --- |
-| 已有 PRD 和原型 | “根据这些资料开发订单导出，保留原件，实施前先确认本次范围。” |
-| 功能需求分析与设计 | “梳理通知偏好功能，完成原型和技术方案，本次先不实施。” |
-| 技术重构 | “重构计价模块，不改变对外行为，完成实施和验证。” |
-| 故障调查 | “调查偶发超时的原因，给出证据和结论，本次先不修复。” |
+```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
+```
 
-多个独立需求可以同时推进，每个交付只保留一个写入会话。共享代码时，安排串行实施或使用独立 checkout／worktree，详见[并行需求](docs/guide.zh-CN.md#parallel)。
+该命令保留已有 AI 工具，同时安装所选预览版本；如果预览通道有更新，也会升级软件。随后按[AI 工具设置](docs/guide.zh-CN.md#hosts)刷新对应会话。
+
+### 查询已安装版本
+
+```sh
+npx aimship@preview --version
+```
+
+输出中的 `installedActiveVersion` 是当前已安装版本，`toolVersion` 是此次 npx 运行的包版本，两者可能不同。查询本身不会升级安装。
+
+### 检查安装状态
+
+```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 工具会话以清除缓存规则。删除交付历史是另一项需要明确提出的操作。
+
+<a id="installation-troubleshooting"></a>
+## 安装与升级问题
+
+| 现象 | 处理方式 |
+| --- | --- |
+| 找不到 Aimship 或出现重复项 | 按[AI 工具设置](docs/guide.zh-CN.md#hosts)刷新会话并检查入口；安装健康不代表 AI 工具已经加载 Skill。 |
+| 管理位置被修改或被其他文件占用 | 保留内容，检查归属，明确合并定制内容后再重试。 |
+| 安装中断或稳定入口损坏 | 使用上面的 `status` 命令检查安装，排除原因后在同一目录重跑完全相同的待恢复版本；不要在恢复途中换版本。自定义安装用户目录可追加 `--home <安装用户目录>` 进行检查。 |
+| 版本与预期不一致 | 核对版本查询中的 `installedActiveVersion` 和 `toolVersion`，继续交付前刷新会话中的规则。 |
+| 包／版本不存在或下载失败 | 核对包名、明确版本和 registry；下载失败不算安装完成。 |
 
 ## 文档与贡献
 
-**[使用指南](docs/guide.zh-CN.md)**涵盖安装、日常使用、文档规则、进度接续、升级和排障。[CONTRIBUTING](CONTRIBUTING.md)说明开发与贡献要求；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
+<a id="适用场景与示例"></a>
+**[使用指南](docs/guide.zh-CN.md)**说明如何开始需求、审核文档、查看成果、处理变更和接续。产物与追溯细则也在指南中；[CONTRIBUTING](CONTRIBUTING.md)说明开发和隔离验证；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
 
-通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈问题和建议。Aimship 目前为预览版；目标完成、用户验收、合并和部署分别记录。
+Aimship 目前处于预览阶段，流程、使用体验和兼容性仍在完善。欢迎通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈实际使用中遇到的问题和改进建议；参与开发请先阅读贡献指南。
 
 采用 [MIT 许可证](LICENSE)。

package/docs/cli.md

@@ -28,7 +28,7 @@ init allocates deliveryId and revision 0, creates `.aimship/state.json`, and gen
 
 `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}`. 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.
+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
 
@@ -79,4 +79,34 @@ Reconcile legacy documents by role, preserve original text/results/version basis
 
 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 [user guide](guide.md#update) for lifecycle operations and their separate host-discovery limits.
+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.
+
+`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.
+
+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.
+
+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.
+
+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.
+
+See the [Agent review workflow](../skills/aimship/references/document-review.md) for presentation, automatic continuation after approval and compatibility responsibilities.
+
+## Standard completeness and session suggestions
+
+New state defaults to `deliveryPolicy: {version: 1}`. The standard main sequence is requirements/acceptance, technical and applicable contract/interaction artifacts, cases, plan, implementation with batch review, overall review, verification, handoff/acceptance. Do not present stageRuns as an arbitrary menu of core stages. Preserve existing materials and inspect them before adoption; reuse does not imply approval.
+
+An explicit limited-scope decision (including no cases and testing) is referenced by `deliveryPolicy.partialRef` in existing PRD/Scope/change material. Such a scope may reach `outcome.goal: met` and have a real acceptance decision, but derived `completion.status` remains `partial-scope`, never `standard-complete`. Adding/changing/removing this basis needs a new goal.decisionRef, preserving goal history; set partialRef to null to restore standard scope. Standard goal completion checks recorded stages/approvals, passing batch and overall review, passing independent verification, handoff and resolvable evidence; standard-complete additionally requires recorded acceptance. These checks cannot prove actual execution or semantic quality. Failed or omitted checks must never be labeled passed.
+
+Reviews identify their actual implementation coverage with `reviewOf: [implementationRunId, ...]`; overall review has `overall: true`. For a single batch one review may explicitly cover both. An unresolved failed review prevents standard completion even if an earlier overall review passed. A passing repair review or retest may list the superseded review/RUN result references in its existing `historyResultRefs`, preserving old failures; the Agent must verify that it actually resolves or covers them on current objects. Verification must follow the applicable overall review. Merely setting a link is not semantic evidence.
+
+`run.sessionGroup` is an advisory group ID persisted when a new policy-enabled run is saved: requirements; technical/contract/prototype; cases; plan; each implementation batch with its batch review; overall review; each verify batch. Adjusting groups does not change document approval, add a stage, or block work. `read/check/resume` expose `session.action`, groups and a concise continuation entry; pending review and unconfirmed saves do not return a next-stage entry. `writeResult.session` becomes reconcile-save with no entry if view saving fails, even when stateSaved is true. Repair at the returned revision; do not repeat the approval update. At a confirmed saved group boundary, the Agent suggests a new session without executing the next group in that response. A user request to continue here proceeds with the normal authorized update.
+
+`read` and `resume` accept optional `--delivery-id <known-id>` to reject a wrong directory binding. A directory remains required; no implicit latest-delivery lookup exists. Resume is read-only and inspects actual state, approval/content versions, references and view diagnostics; old prompts grant no approval. The Agent must additionally inspect relevant complete formal documents, actual artifacts and unfinished effects before acting.
+
+Old states without deliveryPolicy stay valid and report `historical-unassessed`; existing goal/acceptance is not rewritten. After active-rule adoption if needed, explicitly update deliveryPolicy together with a readable `compatibilityRef` assessing scope and evidence, without inventing old approvals or runs. A preserved historical met value is not automatically a new standard-complete claim. Reconcile gaps before claiming new completion; explicit limited scope remains distinguishable. Unknown future delivery policies are read-only and cannot be recovered over.