aimship 0.0.0-stage → 0.1.0-preview.11

package/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing
+
+This repository is standalone. Runtime, tests and packaging must not read a parent workspace or private planning material. Use synthetic fixtures and temporary user homes for installation tests; never test by overwriting real skills, configurations, delivery materials or business projects.
+
+Node.js 22+ is the intended runtime floor. Run `npm test` for deterministic tool tests (one worker by default) and `npm run check:package` for distributable-content checks. `npm pack` creates a local package. There are no runtime third-party dependencies.
+
+The manual [Check Windows workflow](.github/workflows/check-windows.yml) runs the full tests and documentation/package checks on a standard Windows runner, sequentially across Node 22, 24 and 26. Select the intended commit's branch when dispatching and record the resolved commit and environment from the run. It uses isolated test homes, does not publish or install into a real user's configuration, and does not establish AI-tool integration coverage.
+
+Keep agent workflow semantics in `skills/aimship/references`, deterministic file/state/install behavior in `lib`, and host entry handling thin. Changes should be driven by requirements or observed failures, with appropriate checks. Do not introduce route taxonomies, automatic agent scheduling, per-batch full testing gates, or a generic workflow platform.
+
+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, gives the explicit first-use entry and expected receipt, 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 without a requirements document, 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 stage mappings and document/identifier rules in the [shared agent references](skills/aimship/references/document-patterns.md); the Guide provides a brief explanation of traceability and retains user-facing [SQL and engineering version guidance](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="local-source-trial"></a>
+## Local source trial without installation
+
+To try unreleased initialization changes, open a session with access to the checkout and a separate disposable materials directory. Explicitly ask to use the checkout's `skills/aimship/SKILL.md`, read its core, and run `node bin/aimship.mjs bind` from this package root. Verify the returned releaseRoot/corePath/cliPath all point into that checkout and schemaVersion is 3; a version string alone is insufficient when local code retains the published version. Then provide a concrete synthetic request, the trial materials path, and the desired stop. Do not load the installed launcher or run install.
+
+In the next session, explicitly request that same source Skill and bind again, then provide the original delivery directory and ask to resume. Check its saved deliveryId, revision, review status and next action. This exercises source rules and local tooling without replacing global entries. Whether a specific host automatically discovers a checkout Skill is separate and must be tested rather than promised. Check `test/initialization.test.mjs` for deterministic initialization, interruption, old-format and approval-bypass regressions; their synthetic decisions are not real AI-host evidence.
+
+<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.
+
+## 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 -f operation=publish
+```
+
+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 `latest` tag, so a successful new publication makes that approved version the default immediately. After verifying the downloaded bytes and provenance, it synchronizes the compatibility `preview` tag and confirms both channels. `latest` is the default installation channel; pointing it at a preview version does not make that version stable. 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` and `npm dist-tag`. The tag permission is separate from publishing permission and must be explicitly authorized by the package owner; the workflow never changes the trust configuration. Tag operations require npm 11.21+ or 12.2+ (the workflow pins npm 11.21.0). Staged publishing is not used. No long-lived npm token is stored. Only jobs that publish or synchronize tags have `id-token: write`; validation has no OIDC permission, and all jobs have only `contents: read` for repository access. 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, unrecognized version formats, or a newer `latest` or `preview` version stops the operation. Direct publication under `latest` uses the existing publish permission; synchronizing `preview` or promoting an already published version requires the separate tag permission. A failed tag update may leave publication complete but channel synchronization pending; do not republish or create a replacement version. 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.
+
+To finish channel synchronization for an **already published, explicitly approved** release, run the current `main` workflow with `operation=sync-tags` and the original release tag:
+
+```sh
+gh workflow run publish-preview.yml --repo clsx/aimship --ref main -f tag=vX.Y.Z-preview.N -f operation=sync-tags
+```
+
+This operation never publishes a package or moves a Git tag. It compares the existing npm tarball with the original tagged source, checks its registry integrity and provenance availability, and updates only tags that do not already match. Each write is preceded by a fresh registry check; an old run cannot intentionally roll either channel back. The shared workflow concurrency group serializes these operations, but npm offers no compare-and-swap for changes made outside this workflow: avoid concurrent manual tag edits. On a denied or uncertain write, inspect the registry and logs before any authorized retry. Do not switch credentials or broaden trusted-publisher permissions automatically.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clsx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# Aimship
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](README.zh-CN.md) · [Guide](docs/guide.md)
+
+**Aimship is a software delivery workflow for AI tools, connecting requirements, design, implementation, review and verification.**
+
+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.
+
+<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)
+
+<a id="quick-start"></a>
+<a id="install"></a>
+## Installation
+
+Requires **Node.js 22+ and npm**.
+
+### Published preview
+
+```sh
+npx aimship@preview install --host codex
+```
+
+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 "./MyDeliveries"
+```
+
+The example uses a `MyDeliveries` folder under the current working directory; you can replace it with an absolute path to your preferred location. 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.
+
+## Start a delivery
+
+Explicitly select Aimship in your AI tool, or ask it to **use Aimship** for a concrete request. For example: “Use Aimship to deliver an export of the currently filtered orders. First clarify the fields; code will be prepared later.” A PRD, code repository and settled technical conditions are not required. A product name alone prompts a short clarification first.
+
+The agent preserves your request, helps you make the materials location accessible, and creates or resumes one delivery. Its receipt shows the actual saved directory, `status.md`, current work and next step. Opening a project or mentioning the name in passing does not activate Aimship. In a new session, explicitly use Aimship again and identify the same delivery; see the [Guide](docs/guide.md#start). Source edits do not update an installed Skill; contributors can use the [local source trial](CONTRIBUTING.md#local-source-trial).
+
+<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).
+
+### 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
+
+<a id="use-cases-and-examples"></a>
+The [Guide](docs/guide.md) explains how to start a delivery, review documents, inspect results, handle requirement changes and continue work. [Contributing](CONTRIBUTING.md) covers development and isolated validation; the [CLI protocol](docs/cli.md) serves agents and tool developers.
+
+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

@@ -0,0 +1,158 @@
+# Aimship
+
+[English](README.md) · [使用指南](docs/guide.zh-CN.md)
+
+**Aimship 是面向 AI 工具的软件交付流程，贯通需求、设计、实施、审核与验证。**
+
+面向有开发基础、对一项需求交付负责的开发者。你提供目标、已有资料和代码位置，Aimship 帮助 Agent 将需求整理为清晰的范围、有依据的设计、可执行的计划和经过验证的成果，并衔接各阶段的工作，让你能了解推进过程、理解关键决定、判断实际交付结果。
+
+<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**。
+
+### 安装已发布的预览版
+
+```sh
+npx aimship@preview install --host codex
+```
+
+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 "./MyDeliveries"
+```
+
+示例使用当前执行目录下的 `MyDeliveries` 文件夹，也可以替换为所需位置的绝对路径。此选项设置后续新交付的默认资料位置，不是代码仓库位置，也不会搬迁已有资料。后续安装保留已有配置；无需逐项目安装。
+
+安装后，按[使用指南](docs/guide.zh-CN.md#hosts)在 AI 工具中选择 Aimship。AI 工具集成仍处于实验阶段，真实 Skill 发现和跨工具接续仍需验证。
+
+## 开始一次交付
+
+在 AI 工具中明确选择 Aimship，或明确要求**使用 Aimship** 处理具体诉求。例如：“使用 Aimship 交付按当前筛选条件导出订单的功能，先确认导出字段，代码稍后准备。”不要求先有 PRD、代码仓库或明确的技术条件。只有产品名称时，Agent 会先简短澄清实际问题。
+
+Agent 保留原始诉求，引导准备资料位置的访问条件，然后创建或续接同一次交付。回执会说明实际保存目录、`status.md`、当前工作和下一步。打开项目空间或偶然提到名称不会启用 Aimship。新会话仍需明确使用 Aimship 并定位原交付，详见[指南](docs/guide.zh-CN.md#start)。源码修改不会更新已安装的 Skill；贡献者可按[本地源码体验](CONTRIBUTING.md#local-source-trial)加载。
+
+<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)刷新对应会话。
+
+### 查询已安装版本
+
+```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；下载失败不算安装完成。 |
+
+## 文档与贡献
+
+<a id="适用场景与示例"></a>
+[使用指南](docs/guide.zh-CN.md)介绍如何开始交付、审核文档、查看成果、处理需求变更和继续工作。[贡献指南](CONTRIBUTING.md)说明开发和隔离验证；[CLI 协议](docs/cli.md)供 Agent 和工具开发者查阅。
+
+Aimship 目前处于预览阶段，流程、使用体验和兼容性仍在完善。欢迎通过 [GitHub Issues](https://github.com/clsx/aimship/issues)反馈实际使用中遇到的问题和改进建议；参与开发请先阅读贡献指南。
+
+采用 [MIT 许可证](LICENSE)。

package/bin/aimship.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { run } from '../lib/cli.mjs';
+
+export async function main(argv = process.argv.slice(2), options = {}) {
+  try {
+    const data = await run(argv, { sourceRoot: path.dirname(path.dirname(fileURLToPath(import.meta.url))), ...options });
+    process.stdout.write(JSON.stringify({ ok: true, ...data }, null, 2) + '\n');
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ ok: false, error: { code: error.code ?? 'IO_ERROR', message: error.message, recovery: error.recovery ?? 'Inspect the error and existing files; retry only after resolving the cause.', ...(error.details === undefined ? {} : { details: error.details }) } }, null, 2) + '\n');
+    process.exitCode = 1;
+  }
+}
+const invokedPath = process.argv[1] ? await fs.realpath(process.argv[1]).catch(() => null) : null;
+if (invokedPath === await fs.realpath(fileURLToPath(import.meta.url))) await main();

package/docs/cli.md

@@ -0,0 +1,115 @@
+# Local tool protocol
+
+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.
+
+## Create and bind
+
+`bind` returns fixed CLI/core/stage paths, version and configured data root. Keep that binding for the session. Installation does not create deliveries.
+
+Before init, save the nonempty original input in `source/request.md`. A concrete request needs no PRD, code or known technical conditions yet. No templates are automatically created. Minimal input:
+
+```json
+{
+  "goal": {"summary":"Export the currently filtered orders", "endpoint":null},
+  "goalRef":"source/request.md",
+  "documentPolicy":{"authority":null,"interaction":null,"prototypeCovered":null,"interface":null,"databases":null},
+  "documents":[],
+  "stageRuns":[{"id":"requirements-1","stage":"requirements","scope":"Order export","progress":"active","inputRefs":["source/request.md"],"outputRefs":[]}],
+  "currentRun":"requirements-1",
+  "next":{"action":"Clarify export fields and acceptance criteria","inputRefs":["source/request.md"]}
+}
+```
+
+Only goal.summary is required in the input; absent endpoint defaults to null, goalRef to source/request.md, documents to [], and documentPolicy fields to null. Known facts may be supplied. Null means unknown, while false/none/[] mean explicitly not applicable. The CLI validates saved structure, not whether the user's request is concrete or authorized; the Agent must establish that before creating records.
+
+```sh
+node '<stable-launcher>' bind
+node '<fixed-cli>' init '<delivery-dir>' --rules-version '<bound-version>' --input '<init.json>'
+```
+
+init uses schema 3, 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. Its receipt contains actual identity, directory/state/status paths, bound version, current stage and next action; statusPath is null when view repair is needed. Verify the saved files before presenting the user receipt. Repeated init returns ALREADY_EXISTS; read/resume the same delivery and render a missing view instead of replaying creation.
+
+`documentPolicy.authority`: null while the requirement authority is undecided; 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 the first real PRD/Scope and switch goalRef in the same update; this reference-only transition does not need a fabricated goal decision. Actual goal/endpoint changes still require goal.decisionRef. Early frame/requirements/scope work can be active without the draft; done requires it. Design requires approved requirements and an agreed endpoint, but may analyze unknown technical conditions. Resolve those conditions before completing design or starting dependent contract/cases/plan/implementation. Required document approvals remain checked even when producer runs are absent; existing stage ordering and review semantics are unchanged.
+
+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 '<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>'
+```
+
+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.
+
+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.
+
+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.
+
+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.
+
+## 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>' 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
+```
+
+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 3 is used for new deliveries; older tools treat it as unknown/read-only. Existing schema 2 continues without automatic conversion, and its recorded history is preserved. 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.
+
+`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.

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