aimship 0.0.0-stage → 0.1.0-preview.7

package/docs/guide.md

@@ -0,0 +1,277 @@
+# Aimship Guide
+
+[中文](guide.zh-CN.md) · [README](../README.md)
+
+This guide covers installation, use and maintenance. Delivery goals and relevant materials form the workflow inputs; the agent maintains delivery records as work progresses.
+
+[Install](#install) · [Host setup](#hosts) · [Start](#start) · [Documents and stages](#artifacts) · [Review and changes](#changes) · [Continue](#continue) · [Parallel work](#parallel) · [Update](#update) · [Uninstall](#uninstall) · [Troubleshoot](#troubleshoot) · [Completion](#completion)
+
+<a id="install"></a>
+## 1. Install Aimship
+
+Requires **Node.js 22+ and npm**. Installation and tool behavior have been checked on macOS arm64 with Node 24 and 26; Node 22 and other operating systems remain unverified. Command examples use a POSIX shell.
+
+### Published preview
+
+```sh
+npx aimship@preview install --host codex
+```
+
+Choose `codex`, `cursor` or `claude-code`. To connect several hosts, 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.
+
+### Source or local package
+
+From the Aimship source checkout:
+
+```sh
+node bin/aimship.mjs install --host codex
+```
+
+For a supplied tarball, replace `VERSION` with its actual version and run from the directory containing it:
+
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
+```
+
+These are alternative ways to run the same installer. No global npm install or administrator privilege is required. A local tarball requires a writable npm cache but no npm login. Use your real home only when you intend to install there.
+
+### Installation and delivery locations
+
+| Location | Purpose |
+| --- | --- |
+| `~/.aimship/` | Fixed software releases, configuration and custom content |
+| `~/.aimship/bin/aimship.mjs` | Stable launcher for the active installed release |
+| `~/Aimship/<request>/` | One delivery's documents and internal `.aimship/` records |
+| Your existing repositories | Code, branches and worktrees; linked from delivery state |
+
+Installation does not create a delivery or move code. Select an initial material root with `--data-root` if needed; later installs retain existing configuration. There is no language setting or per-project installation. The installer keeps the active release and at most one ordinary recovery release, preserving changed or unowned files.
+
+For an isolated trial, place the supplied tarball in the current directory, replace `VERSION`, then run:
+
+```sh
+trial=$(mktemp -d)
+trial=$(cd "$trial" && pwd -P)
+npx --yes --offline --cache "$trial/npm-cache" file:./aimship-VERSION.tgz install --home "$trial/home" --host codex
+node "$trial/home/.aimship/bin/aimship.mjs" --version
+node "$trial/home/.aimship/bin/aimship.mjs" status
+node "$trial/home/.aimship/bin/aimship.mjs" install --host cursor
+node "$trial/home/.aimship/bin/aimship.mjs" uninstall --host cursor
+node "$trial/home/.aimship/bin/aimship.mjs" uninstall
+```
+
+`--home` redirects managed installation files; it does not make your running host discover that home or inherit permissions. The installed launcher defaults subsequent operations to its own installation home. Remove the disposable directory after inspection if desired; do not replace it with a real home.
+
+<a id="hosts"></a>
+## 2. Select Aimship in your host
+
+| Host | Managed entry | Explicit use | Reload after installation or changes |
+| --- | --- | --- | --- |
+| Codex | `~/.agents/skills/aimship/` | Select Aimship; `$aimship` in CLI | Start a new conversation or restart the CLI; check the actual skill selector. Restart the app if stale. |
+| Cursor | Same `.agents/skills/aimship/` entry | `/aimship` | Start a new agent session and inspect Customize → Skills; restart if stale. |
+| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | Start a new session and inspect slash-command discovery; restart if stale. |
+
+Host integrations are experimental. Actual end-to-end discovery, directory access and cross-host continuation still require validation. Each host needs its own login, model availability and permission to access the relevant material and code roots. An installation file check is not proof that the host loaded the Skill. No cloud synchronization is enabled.
+
+Codex and Cursor share a managed entry. Compatible hosts may also discover entries outside their primary location, so registration and discovery are different. Inspect paths and versions if duplicates appear; preserve unrelated or customized entries. See the official [Cursor documentation](https://cursor.com/docs/skills) and [Codex skill locations](https://learn.chatgpt.com/docs/build-skills).
+
+Add a host using the already installed version, and inspect installation health:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
+node "$HOME/.aimship/bin/aimship.mjs" --version
+node "$HOME/.aimship/bin/aimship.mjs" status
+```
+
+The CLI `status` command reports installation health. A delivery's `status.md` reports its work progress. They serve different purposes.
+
+<a id="start"></a>
+<a id="describe-the-work-and-its-endpoint"></a>
+## 3. Delivery goals and authorization
+
+A delivery request should specify the expected outputs, input and code locations, and authorization boundaries. A complete PRD is not required in advance:
+
+> Use Aimship to add order export. Use the existing app repository and these screenshots. Complete implementation, review and verification; leave deployment for later.
+
+> Use Aimship to assess the notification preferences feature. Produce requirements, a prototype and a technical design. Stop before implementation.
+
+The agent preserves the original commission in `source/request.md`, chooses the requirement authority and proposes the required stages and their order. Once accepted, that arrangement governs execution. Important business, scope, compatibility, cost or data decisions come back to you; routine engineering decisions stay within your authorization. Silence does not approve an unanswered proposal.
+
+A design-only task may need no writable code repository. The delivery directory need not be the host's main workspace: grant access when an actual operation needs it. The agent must not silently move materials to bypass access restrictions.
+
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+## 4. Documents, stages and generation rules
+
+Use the [annotated directory tree](../README.md#delivery-structure-and-documents) as the layout reference. Formal documents are directly in the request directory, new prototypes in `prototype/`, preserved inputs in `source/`, and machine records/evidence in `.aimship/`. There is no extra `docs/` or `sql/` layer within a delivery.
+
+### Choose the requirement authority
+
+| Input condition | Requirement document | Prototype handling |
+| --- | --- | --- |
+| An authoritative PRD/prototype is supplied for adoption | `scope.md` records adopted versions, scope, gaps, decisions and acceptance; originals remain unchanged | Reuse covered interactions; create a prototype for uncovered interaction changes within the commissioned endpoint |
+| An idea, discussion, screenshots or scattered references | Author `prd.md`, including scope and acceptance | Create a prototype when the commissioned work changes interactions and existing material does not cover them |
+| Technical refactoring or a known-cause fix | Author `prd.md` describing the technical goal, boundaries, behavior constraints and acceptance | No prototype when there is no interaction change |
+| Independent investigation, review-only or verification-only | PRD/Scope defines that commission and its endpoint | Do not invent a future implementation or prototype |
+
+`prd.md` and `scope.md` are alternatives for the requirement authority, not duplicate descriptions to create together. If you explicitly commission maintenance of an existing editable authoritative PRD and it fully expresses this delivery's scope, authorization and endpoint, register and reuse it. Earlier authorship alone does not make adopted material editable.
+
+Preserve incoming versions in `source/`, including externally supplied PRDs, prototypes and images. Generated formal documents stay in the locations above. External originals are not rewritten when requirements change. A URL alone may not preserve a version; the agent records the available source/version and any access gaps. Reading text, inspecting a visual, interacting with a prototype and editing its original format are distinct capabilities.
+
+### Stage outputs and content
+
+Stage names are stable identifiers. This table is a catalog, not a fixed sequence; the accepted arrangement selects stages and dependencies. Every delivery retains the original request, a requirement/scope authority and state records, even when no separate requirements stage is needed. Sharing `plan.md` or `testing.md` does not complete both stages automatically: each stage retains its own status and result. Documents are drafted when their stage begins, and file creation alone does not establish completion.
+
+| Stage | When used | Output and content |
+| --- | --- | --- |
+| `frame` | The problem or intended result needs clarification | Goal/background section of PRD/Scope: problem, outcome, non-goals and assumptions |
+| `requirements` | Requirements need authoring or adoption | `prd.md`: goals, scope, requirements, states, acceptance and arrangement; or `scope.md`: source adoption, scope, exclusions, decisions, acceptance and arrangement |
+| `scope` | Commission boundaries need explicit resolution | Update PRD scope or Scope goals/boundaries; no second requirements document |
+| `prototype` | Required interaction changes are not covered by existing material | New HTML at `prototype/index.html` with related assets; other agreed formats or reused entries are registered |
+| `diagnose` | An independent investigation is explicitly arranged | `diagnosis.md`: goal, symptoms, environment, evidence, causes, unknowns and conclusion |
+| `tech-design` | Technical solution needs designing | `tech-design.md`: basis, architecture, modules, data/contracts, errors, risks and requirement coverage; required SQL is ready before this stage finishes |
+| `contract` | A contract needs creating or changing | HTTP: `openapi.yaml` or the registered engineering authority; record an agreed format for non-HTTP contracts |
+| `plan` | Before any implementation, including one small batch | `plan.md`: basis, batches, tasks, validation approach, execution section and remaining work |
+| `test-design` | Test cases need authoring | `testing.md`: basis, environment, cases/assertions and requirement/acceptance coverage |
+| `implement` | Execute the accepted plan | Code in its repositories; actual task status, objects and deviations in the same `plan.md` |
+| `review` | Review a batch, the integrated result or a review-only commission | `review.md`: review basis, each review's scope/findings/resolution and conclusion |
+| `verify` | Execute versioned cases after the required review, or a verification-only commission | Append execution batches/RUNs, actual results/evidence, retests and conclusion to the same `testing.md` |
+| `handoff` | Deliver the agreed endpoint | `handoff.md`: goal, artifacts, usage, review/verification results, limits and completion/acceptance/integration outcomes |
+
+During development, `plan` completes before the first implementation. Each implementation batch is reviewed, followed by overall review and independent verification. Test code can be authored during implementation; there is no full testing gate imposed after each batch. For one batch, one review may cover both batch and overall scope if explicitly recorded. Verification-only work may adopt existing versioned cases without claiming to have executed `test-design`.
+
+Ordinary debugging and known-cause bugs do not add `diagnose`. Fix implementation defects in implementation, design errors in technical design, requirement gaps in PRD/Scope, and incorrect expectations in versioned cases. A major unknown requiring separate investigation needs a recorded stage adjustment; dependent work waits.
+
+### SQL, changes and progress
+
+| Artifact | Generation rule and content |
+| --- | --- |
+| `database.sql` | Required when database structures or data change; one database target uses this single root-level file |
+| `database-<id>.sql` | Multiple independent database targets get one file each; use a stable target ID |
+| `change-log.md` | Record meaningful changes: reason, old/new meaning, decision, affected documents/work and remaining actions |
+| `status.md` | Generated reading entry: goal, progress, blockers, next action and document links |
+| `.aimship/state.json` | Managed state: goal/stages, document references, version binding and associated repositories/worktrees/code locations |
+
+SQL identifies the target, dialect, version/schema basis and execution conditions, and links ordered statements to requirements/design. It is prepared before technical design completes. A Markdown SQL snippet or migration reference does not replace this deliverable. Generating SQL does not authorize executing it or changing a repository's migration mechanism.
+
+Existing engineering HTTP contracts remain authoritative; avoid a second competing copy. Project current and target versions are recorded in PRD/Scope with their engineering source and observation basis; an unspecified version remains unspecified. `plan.md` records actual changes, while review and test results identify the exact commit/build or uncommitted content. Each repository has its own version and object references. These differ from Aimship’s rules version, state schema and save revision. The handoff records final code objects and actual merge/release status; a target version does not establish publication.
+
+### Fixed outlines and traceable identifiers
+
+New documents follow [shared templates and rules](../skills/aimship/references/document-patterns.md). Section order and stable anchors are retained; visible headings can be translated. Inapplicable sections explain why. Short tasks use the same outline, with shorter content. Unselected stages do not produce empty documents, and there is no arbitrary small-task merging.
+
+| Identifier | Meaning |
+| --- | --- |
+| `REQ-001`, `AC-001` | Requirement and acceptance criterion |
+| `B-001`, `TASK-001` | Implementation batch and task |
+| `PAGE-001`, `Q-001` | Prototype page and tracked question |
+| `TC-001`, `RUN-001` | Test case and actual verification run |
+| `REV-001`, `CHG-001` | Review and meaningful change |
+
+Each series starts at `001` and advances beyond its historical maximum, including retired items; three digits are the minimum width. An ID is never reused for a different obligation. Within a namespace and version, an identity has one effective definition; other documents reference it. Classification or layout changes retain the ID, while splits/merges create new IDs linked to the originals.
+
+References connect requirements/acceptance to design, tasks, code objects, reviews, case versions and actual runs. These relationships may be many-to-many: `REQ-001` and `TC-001` are not related merely because their numbers match. Shared rules, permissions and quality requirements receive independent identities when independently testable. External IDs retain their spelling and source/version namespace; sources without IDs receive local mappings to their original locations. Changed case meaning gets a new version; earlier failures and their case/code versions remain traceable.
+
+For example: `REQ-001 → AC-002 → TC-004@1 → RUN-003` records the explicit requirement-to-result relationship. A RUN also identifies the tested code/build and evidence; the case ID alone does not prove execution.
+
+The tools check structure, references and basic coverage. The agent must still assess whether the content and assertions actually satisfy the requirement; valid metadata alone is not proof.
+
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+## 5. Results and change management
+
+Start with `status.md`, then follow the relevant links. Review records assess the change; verification records show executed assertions. Each result identifies the actual object/version, scope, executor, environment and evidence. Missing accounts, tools or environments remain blocked or unexecuted checks with a next action, never passing tests.
+
+For a meaningful change, the agent records the decision once, updates the affected editable requirements/design/contracts/SQL/cases and rechecks affected conclusions. Original sources and historical results stay preserved. Unrelated completed work is not reset, and implementation failures are not hidden by weakening acceptance criteria.
+
+Tell the agent about a change, or edit the relevant formal document and ask it to reconcile the change. `status.md` is a generated view; manual edits do not change the goal or confer acceptance. Preserve any such edits before requesting regeneration. Internal JSON and view metadata are tool-managed.
+
+<a id="continue"></a>
+<a id="continue-in-another-conversation"></a>
+## 6. Progress checkpoints and session continuation
+
+At a stable stage or batch boundary, ask the agent to save progress and provide a continuation prompt with the absolute delivery path. Open the next conversation yourself and select Aimship:
+
+> Use Aimship to continue the delivery at `/absolute/path/to/Aimship/20261023-order-export/`. Read its state and current documents, then continue the recorded next step.
+
+Use that same directory when changing hosts; authorize access separately. The new conversation reads current state and relevant inputs, without requiring the entire chat or repeating every test. There is no automatic session creation or cloud synchronization.
+
+If a code repository moved, give its new location; identity must be checked before repairing the reference. After an interruption, inspect actual artifacts and side effects before retrying. Revision conflicts need reconciliation rather than force-overwriting. Read/check/resume report stale or modified views; explicit render regenerates them after preserving manual changes. A saved state with a failed view needs view repair, not replay of the successful state write.
+
+<a id="parallel"></a>
+<a id="work-on-two-requests-at-once"></a>
+## 7. Parallel deliveries
+
+Keep separate delivery directories, for example `~/Aimship/notification-preferences/` and `~/Aimship/order-export/`, with one writing session per delivery. Code may live in different repositories or the same repository.
+
+If A is implementing in an app checkout, B can still design using it as a read-only reference. Before B also writes code, use sequential implementation or a separate checkout/worktree, reusing existing isolation when available. Shared interfaces, databases and test resources also need coordination in the plan. Completing a branch does not mean integration is complete.
+
+The agent checks accessible records in known material roots when code scope or working directories change and before implementation. This includes older unfinished deliveries; ended deliveries may still have pending integration dependencies. Unknown roots, inaccessible/stale records and work outside Aimship limit this check. Aimship provides no global lock, automatic agent scheduler, automatic worktree creation or automatic merge.
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+## 8. Software updates and delivery compatibility
+
+For the published preview channel:
+
+```sh
+npx aimship@preview install
+```
+
+For a source/local candidate, run that release's installer against the same installation home. Existing registered hosts, configuration, custom content and deliveries are retained. Repeating an install is safe for unchanged managed files. The installer reports previous/target versions and conflicts; no background updater or resident process runs.
+
+**Software updates use `install`.** The low-level `update` command edits delivery state, not installed software. Daily work uses the fixed local launcher and rules, not repeated package downloads.
+
+An active conversation may retain old rules after installation. Save current facts and adopt the current core/stage rules at a stable point; use a new conversation if context cannot refresh reliably. A version mismatch prevents new workflow writes until reconciled.
+
+For schema 1 deliveries, explicitly migrate the selected delivery, adopt the new rules, then reconcile documents before continuing stages. Migration preserves originals and historical results; it does not invent missing historical plans or automatically rewrite every document. Unknown formats remain read-only. Completed deliveries are not swept during software upgrades. The agent/contributor [CLI protocol](cli.md) documents recovery details.
+
+<a id="uninstall"></a>
+## 9. Host disconnection and uninstallation
+
+Disconnect one host while retaining the core and other registrations:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
+```
+
+Shared entries remain when another registered host needs them. Disconnecting the last host still retains the core for diagnostics or reconnection; compatible hosts might continue discovering a remaining shared entry.
+
+Remove all managed software and host entries:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" 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 host sessions to discard cached rules. Deleting delivery history is a separate explicit action.
+
+<a id="troubleshoot"></a>
+## 10. Troubleshoot
+
+| Symptom | What to do |
+| --- | --- |
+| Aimship is absent or duplicated | Reload the host and inspect its actual selector plus reported entry paths/versions. Do not delete unrelated entries. Installation health alone does not establish host discovery. |
+| Directory access denied | Authorize the required material/code roots in that host. Report the exact operation; do not move materials or disable permission controls to bypass it. |
+| Modified or foreign managed path | Preserve the contents, inspect ownership and explicitly reconcile customizations before retrying. |
+| Partial installation | Inspect `status`, fix the reported cause and rerun the exact pending package against the same home. Do not switch versions mid-recovery. |
+| Launcher missing or damaged | From the exact source/package installer, run `node bin/aimship.mjs status --home <installation-home>`. This diagnoses without repair; inspect before rerunning the installer. |
+| Unexpected version | Query the stable installed launcher. A source checkout or an older release's CLI can report a different version; reload the current binding. |
+| Package/version unavailable or authentication failure | Confirm the package, exact version and registry. A failed download is not a completed installation. Keep credentials out of reports. |
+| Stale or manually edited `status.md` | Ask the agent to read current state/documents, preserve edits and explicitly regenerate the view. Do not overwrite state from the view. |
+| A formal document changed outside the workflow | Reconcile its meaning and affected work; matching state/view revisions do not prove that document content is unchanged. |
+| An old delivery cannot advance | Have the agent inspect migration, rule adoption and document reconciliation separately. Preserve historical results and report unresolved blockers. |
+
+For a bug report, include the Aimship version, host/version, exact command or operation, expected/actual result and a minimal synthetic reproduction. Redact credentials and private paths/data. Use [GitHub Issues](https://github.com/clsx/aimship/issues); contributors can follow [CONTRIBUTING](../CONTRIBUTING.md).
+
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+## 11. Delivery completion criteria
+
+The commissioned endpoint governs completion. A design commission ends with its agreed design; development includes its required review and validation. Asking to preview current results does not shorten the goal. Explicitly ending earlier retains the original goal and outstanding work in the handoff.
+
+Goal achieved, user acceptance, merge and deployment remain separate. Small later corrections can reopen a delivery while preserving its earlier closure; a new goal or substantial redesign starts a related delivery. Parent/child delivery management and multi-agent orchestration are not automated.

package/docs/guide.zh-CN.md

@@ -0,0 +1,277 @@
+# Aimship 使用指南
+
+[English](guide.md) · [README](../README.zh-CN.md)
+
+本指南涵盖安装、使用和维护。交付目标与相关资料作为流程输入，交付记录由 Agent 随工作推进维护。
+
+[安装](#install) · [宿主设置](#hosts) · [开始需求](#start) · [文档与阶段](#artifacts) · [审核与变更](#changes) · [进度接续](#continue) · [并行需求](#parallel) · [升级](#update) · [卸载](#uninstall) · [排障](#troubleshoot) · [结束交付](#completion)
+
+<a id="install"></a>
+## 1. 安装 Aimship
+
+需要 **Node.js 22+ 和 npm**。安装与工具行为已在 macOS arm64、Node 24 和 26 上检查；Node 22 及其他操作系统仍待验证。以下命令使用 POSIX shell 写法。
+
+### 安装已发布的预览版
+
+```sh
+npx aimship@preview install --host codex
+```
+
+宿主可选 `codex`、`cursor` 或 `claude-code`。连接多个宿主时重复该选项：
+
+```sh
+npx aimship@preview install --host codex --host claude-code
+```
+
+按 npm 提示确认获取安装包。`@preview` 表示已发布的预览通道，也可以替换为明确版本号，例如 `@0.1.0-preview.7`。预览通道用于实验性版本，不代表稳定版。
+
+### 从源码或本地包安装
+
+在 Aimship 源码仓库中执行：
+
+```sh
+node bin/aimship.mjs install --host codex
+```
+
+使用 tarball 安装时，将 `VERSION` 替换为实际版本号，在包所在目录执行：
+
+```sh
+npx --offline file:./aimship-VERSION.tgz install --host codex
+```
+
+这些方式运行的是同一套安装器，选择其中一种即可。不需要全局 npm 安装或管理员权限；本地包需要可写的 npm 缓存，不需要登录 npm。只有确实要安装到日常环境时才使用真实用户目录。
+
+### 软件与交付资料目录
+
+| 位置 | 用途 |
+| --- | --- |
+| `~/.aimship/` | 固定版本的软件、配置和自定义内容 |
+| `~/.aimship/bin/aimship.mjs` | 当前已安装版本的稳定入口 |
+| `~/Aimship/<需求>/` | 一个交付的文档及其内部 `.aimship/` 记录 |
+| 现有代码仓库 | 代码、分支和 worktree，通过交付状态关联 |
+
+安装不会新建空交付或搬动代码。首次安装可用 `--data-root` 指定资料根目录，后续安装保留已有配置。无需配置语言，也无需逐项目安装。安装器保留当前版本及最多一个普通恢复版本，遇到被修改或不属于它管理的文件会保留并报告。
+
+如需隔离试用，将提供的 tarball 放在当前目录，替换 `VERSION` 后执行：
+
+```sh
+trial=$(mktemp -d)
+trial=$(cd "$trial" && pwd -P)
+npx --yes --offline --cache "$trial/npm-cache" file:./aimship-VERSION.tgz install --home "$trial/home" --host codex
+node "$trial/home/.aimship/bin/aimship.mjs" --version
+node "$trial/home/.aimship/bin/aimship.mjs" status
+node "$trial/home/.aimship/bin/aimship.mjs" install --host cursor
+node "$trial/home/.aimship/bin/aimship.mjs" uninstall --host cursor
+node "$trial/home/.aimship/bin/aimship.mjs" uninstall
+```
+
+`--home` 只改变受管理安装文件的位置，不会让当前宿主自动发现这个目录或继承权限。安装后的稳定入口默认继续管理自己的安装目录。检查结束后可删除该临时目录，不要将其替换成真实用户目录。
+
+<a id="hosts"></a>
+## 2. 在宿主中选择 Aimship
+
+| 宿主 | 管理的入口 | 显式调用 | 安装或变更后如何刷新 |
+| --- | --- | --- | --- |
+| Codex | `~/.agents/skills/aimship/` | 选择 Aimship；CLI 中用 `$aimship` | 新建会话或重启 CLI，检查实际 Skill 选择器；列表未刷新时重启应用 |
+| Cursor | 同一个 `.agents/skills/aimship/` 入口 | `/aimship` | 新建 Agent 会话，检查 Customize → Skills；列表未刷新时重启宿主 |
+| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | 新建会话并检查斜杠命令；列表未刷新时重启宿主 |
+
+宿主集成仍处于实验阶段。真实环境中的发现、目录访问和跨宿主接续仍需验证。每个宿主分别需要登录、可用模型以及相关资料和代码根目录的访问权限。安装文件检查通过，不代表宿主已经加载 Skill。Aimship 不启用云同步。
+
+Codex 和 Cursor 共用一个管理入口。兼容宿主还可能发现其他位置的入口，因此“登记了宿主”和“宿主实际发现 Skill”是不同的事。如果出现重复项，先检查路径和版本，保留无关或定制过的入口。可参考官方 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
+
+直接使用已安装版本添加宿主，并查看安装健康状态：
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
+node "$HOME/.aimship/bin/aimship.mjs" --version
+node "$HOME/.aimship/bin/aimship.mjs" status
+```
+
+CLI 的 `status` 命令查看软件安装状态；交付目录的 `status.md` 查看需求进度，两者用途不同。
+
+<a id="start"></a>
+<a id="describe-the-work-and-its-endpoint"></a>
+## 3. 交付目标与授权范围
+
+发起交付时，应明确预期成果、资料与代码位置，以及本次授权范围。无需预先准备完整 PRD：
+
+> 使用 Aimship 增加订单导出功能。使用现有应用仓库和这些截图，完成实施、review 和验证，部署留到后续。
+
+> 使用 Aimship 梳理通知偏好功能，产出需求、原型和技术方案，本次先不实施。
+
+Agent 在 `source/request.md` 保留原始委托，确定需求依据，并提出需要的阶段和顺序。安排被接受后，就按该顺序执行。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常工程取舍由 Agent 处理。没有回应不等于批准待决提案。
+
+仅做方案时可以不需要可写代码仓库。交付目录不必是宿主的主工作区，在实际操作需要时授权访问即可。Agent 不应为绕过访问限制擅自搬动资料。
+
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+## 4. 文档、阶段和生成规则
+
+目录位置以 [README 的注释目录树](../README.zh-CN.md#交付目录与文档)为准：正式文档直接放在需求目录，新原型放在 `prototype/`，原始资料放在 `source/`，内部状态和证据放在 `.aimship/`。交付内不再增加 `docs/` 或 `sql/` 层级。
+
+### 需求依据与输入条件
+
+| 输入条件 | 需求文档 | 原型处理 |
+| --- | --- | --- |
+| 提供权威 PRD／原型供本次采用 | 用 `scope.md` 记录采用版本、本次范围、缺口、决定和验收，保留原件 | 已覆盖的交互复用；委托范围内有未覆盖的交互变化时补原型 |
+| 只有想法、讨论、截图或零散参考 | 自编 `prd.md`，其中包含范围和验收 | 委托范围内涉及交互变化、且现有材料未覆盖时生成原型 |
+| 技术重构或已知原因的修复 | 自编 `prd.md`，说明技术目标、边界、行为约束和验收 | 不涉及交互变化就不生成原型 |
+| 独立调查、只做 review 或只做验证 | PRD／Scope 只定义本次委托及终点 | 不虚构后续实施需求或原型 |
+
+`prd.md` 和 `scope.md` 是需求依据的两种选择，不应默认同时创建两份重复描述。如果你明确委托维护一份已有、可编辑的权威 PRD，且它完整表达本次范围、授权和终点，可以登记复用。仅凭“以前由我们编写”不能认定采用的原件可以修改。
+
+外来的 PRD、原型、图片等按采用版本保留在 `source/`，自己生成的正式文档按上述位置存放。需求变化时不改写外部原件。单独一个链接未必能保留资料版本，Agent 应记录可用来源、版本和访问缺口。提取文本、查看视觉内容、操作原型和编辑原格式，是不同能力。
+
+### 阶段产物与内容
+
+阶段名称是稳定标识。下表是阶段目录，不是强制顺序；实际选用哪些阶段及其依赖，由接受后的执行安排决定。即使无需单独执行需求阶段，每次交付仍保留原始委托、需求／范围依据和状态记录。共用 `plan.md` 或 `testing.md` 不代表两个阶段同时完成，各阶段分别记录状态和结果。文档在对应阶段开始时形成草稿，文件已创建不等于阶段已完成。
+
+| 阶段 | 使用条件 | 产物及内容 |
+| --- | --- | --- |
+| `frame` 问题定义 | 问题或预期结果仍需澄清 | PRD／Scope 的目标与背景章节：问题、目标、非目标和假设 |
+| `requirements` 需求 | 需要编写或采用需求 | `prd.md`：目标、范围、需求、状态、验收和执行安排；或 `scope.md`：资料采用、本次范围、排除项、决定、验收和执行安排 |
+| `scope` 范围确认 | 需要明确本次委托边界 | 更新 PRD 的范围或 Scope 的目标／边界，不再新建另一份需求说明 |
+| `prototype` 原型 | 所需交互变化未被现有资料覆盖 | 新 HTML 使用 `prototype/index.html`，相关资源放在同目录；其他约定格式或复用入口单独登记 |
+| `diagnose` 调查定位 | 明确安排了独立调查 | `diagnosis.md`：目标、现象、环境、证据、原因、未知项和结论 |
+| `tech-design` 技术方案 | 需要设计技术实现 | `tech-design.md`：依据、架构、模块、数据／契约、异常、风险和需求覆盖；需要的 SQL 在该阶段结束前完成 |
+| `contract` 契约 | 需要新增或调整契约 | HTTP 使用 `openapi.yaml` 或已登记的工程权威契约；非 HTTP 契约登记约定格式 |
+| `plan` 实施计划 | 任何实施开始前，包括单个小批次 | `plan.md`：依据、批次、任务、验证安排、执行记录章节和剩余工作 |
+| `test-design` 测试设计 | 需要编写测试用例 | `testing.md`：依据、环境、用例／断言，以及需求和验收覆盖 |
+| `implement` 实施 | 执行已确定的计划 | 在代码仓库实施；同一份 `plan.md` 记录实际任务状态、代码对象和偏差 |
+| `review` 审核 | 审核某批、整体成果，或单独受托 review | `review.md`：审核依据、各次审核范围、发现与处理、结论 |
+| `verify` 验证 | 必要 review 后执行带版本用例，或单独受托验证 | 在同一份 `testing.md` 追加执行批次／RUN、实际结果、证据、重测和结论 |
+| `handoff` 交接 | 交付约定终点的成果 | `handoff.md`：目标、产物、使用方式、审核／验证结果、限制，以及完成／验收／集成状态 |
+
+开发流程中，`plan` 必须先于首次实施完成。每批实施后 review，全部完成后整体 review，再独立验证。实施时可以编写测试代码，但不额外设置逐批全量测试门禁。只有一批时，一次 review 可以明确覆盖批次和整体范围。单独委托验证时，可以采用已有、明确版本的用例，不声称重新执行过 `test-design`。
+
+普通开发调试、已知原因的 Bug 不增加 `diagnose`。实现错误回到实施，设计错误回到技术方案，需求缺口回到 PRD／Scope，错误的测试预期回到带版本的用例。出现需要独立调查的重大未知项时，应记录阶段调整，相关依赖工作暂停。
+
+### SQL、变更和进度
+
+| 产物 | 生成规则与内容 |
+| --- | --- |
+| `database.sql` | 数据库结构或数据发生变化时需要；一个数据库目标在需求根目录使用这一份文件 |
+| `database-<id>.sql` | 多个独立数据库目标各一份，`id` 使用稳定的目标标识 |
+| `change-log.md` | 有重要变更时记录原因、旧／新含义、决定、影响文档与工作，以及剩余动作 |
+| `status.md` | 自动生成的阅读入口，显示目标、进度、阻塞、下一步和文档链接 |
+| `.aimship/state.json` | 工具维护的状态，包含目标／阶段、文档引用、版本绑定及关联仓库／worktree／代码位置 |
+
+SQL 标明目标、方言、版本／结构依据、执行条件，按顺序组织语句并关联需求和设计，在技术方案结束前准备完成。Markdown 中的 SQL 片段或迁移文件引用不能替代它。生成 SQL 不代表获准执行数据库操作或修改工程迁移机制。
+
+已有工程 HTTP 契约继续作为权威来源，避免维护另一份相互冲突的副本。项目当前版本和目标版本在 PRD／Scope 中记录，并注明工程来源和观察依据；未设置版本时如实说明。`plan.md` 记录实际改动，审核与测试结果定位准确的 commit、构建或未提交内容。多仓库分别记录版本和对象引用，与 Aimship 规则版本、状态格式及保存 revision 区分。交接记录最终代码对象和真实合并／发布状态，目标版本不代表已发布版本。
+
+### 固定大纲和可追溯编号
+
+新文档遵循[统一模板和规则](../skills/aimship/references/document-patterns.md)，保留章节顺序和稳定锚点，可翻译展示标题。不适用章节说明原因，小需求使用相同大纲、缩短内容。未选择的阶段不生成空文档，也不按“小需求”随意合并文件。
+
+| 编号 | 含义 |
+| --- | --- |
+| `REQ-001`、`AC-001` | 需求、验收标准 |
+| `B-001`、`TASK-001` | 实施批次、任务 |
+| `PAGE-001`、`Q-001` | 原型页面、待决问题 |
+| `TC-001`、`RUN-001` | 测试用例、实际验证执行 |
+| `REV-001`、`CHG-001` | 审核、重要变更 |
+
+各类编号从 `001` 开始，在包含已废弃条目的历史最大值后递增，三位是最小补零宽度。旧编号不用于另一项义务。同一命名空间和适用版本内，一个编号只有一处有效定义，其他文档引用该定义。分类或排版变化保留编号，拆分／合并则创建新编号并关联原编号。
+
+需求／验收通过引用关联到设计、任务、代码对象、审核、用例版本和实际执行，允许多对多关联；不能因数字相同就认定 `REQ-001` 对应 `TC-001`。可独立测试的公共规则、权限和质量要求应具有独立身份。外部编号保留原样，并携带来源／版本命名空间；无原编号时建立指向原文位置的本地映射。用例含义改变后产生新版本，先前失败及当时的用例和代码版本仍可追溯。
+
+例如，`REQ-001 → AC-002 → TC-004@1 → RUN-003` 表示明确的需求到结果关联。RUN 同时记录被测代码／构建及证据，仅存在用例编号不能证明已执行。
+
+工具检查结构、引用和基础覆盖；Agent 仍需判断正文和断言是否真正满足需求。元信息合法不等于内容正确。
+
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+## 5. 结果查阅与变更处理
+
+通过 `status.md` 查看交付概况，并访问相关文档。Review 说明对改动的审核，验证记录说明实际执行了哪些断言。每项结果应定位对象／版本、范围、执行者、环境和证据。缺账号、工具或环境的检查保留为阻塞或未执行，并注明下一步，不能计为通过。
+
+重要变更记录一次决定，然后更新受影响的可编辑需求、设计、契约、SQL 和用例，复核受影响的结论。原始资料与历史结果保留，无关的已完成工作不重置，也不通过降低验收标准掩盖实现失败。
+
+变更可以通过指令提出，也可以修改正式文档后要求 Agent 核对并同步影响。`status.md` 是生成视图，手动修改不能改变目标或代表验收；重建前需保留手改内容。内部 JSON 和视图元信息由工具管理。
+
+<a id="continue"></a>
+<a id="continue-in-another-conversation"></a>
+## 6. 进度保存与会话接续
+
+在阶段或批次的稳定边界，请 Agent 保存进度并给出包含绝对交付路径的接续提示词。自行打开新会话，选择 Aimship：
+
+> 使用 Aimship 继续 `/绝对路径/Aimship/20261023-订单导出/` 中的交付。读取状态和当前文档，继续执行已记录的后续工作。
+
+切换宿主也使用同一个目录，并分别授权访问。新会话读取当前状态和必要输入，不要求复制完整聊天或重复所有测试。不会自动创建会话或进行云同步。
+
+代码仓库搬迁后，提供新位置，核对仓库身份后修复引用。操作中断后，先检查真实产物与副作用再重试。revision 冲突需要协调，不能强制覆盖。读取、检查和接续会报告过期或手改视图；保留手改后通过明确的 render 重建。状态保存成功而视图生成失败时，只修复视图，不重放已经成功的状态写入。
+
+<a id="parallel"></a>
+<a id="work-on-two-requests-at-once"></a>
+## 7. 多需求并行管理
+
+不同需求使用不同交付目录，例如 `~/Aimship/通知偏好/` 和 `~/Aimship/订单导出/`，每个交付只保留一个写入会话。代码可以关联不同仓库，也可以关联同一个仓库。
+
+A 正在应用 checkout 中实施时，B 可以将其作为只读参考继续设计。B 也要写代码之前，安排串行实施或独立 checkout／worktree；已有隔离环境时优先复用。共享接口、数据库和测试资源也需要在计划中协调。分支完成不等于集成完成。
+
+关联或改变代码范围、改变工作目录、准备实施时，Agent 检查已知资料根目录中可访问的记录，包括较早但未结束的交付；已结束交付也可能留下待集成依赖。未知目录、不可访问或过期记录、Aimship 外的工作会限制检查范围。Aimship 不提供全局锁、自动 Agent 调度、自动创建 worktree 或自动合并。
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+## 8. 软件升级与交付兼容
+
+升级到已发布的预览通道版本：
+
+```sh
+npx aimship@preview install
+```
+
+源码／本地候选版本则使用该版本的安装器，指向相同安装目录。已有宿主登记、配置、自定义内容和交付资料都会保留。未修改的管理文件可重复安装，安装器报告旧／新版本及冲突。没有后台自动升级或常驻进程。
+
+**软件升级使用 `install`。** 底层 `update` 命令修改交付状态，不是软件升级。日常使用绑定的本地稳定入口和规则，无需反复下载 npm 包。
+
+安装升级后，正在运行的会话仍可能保留旧规则。先保存现状，再在稳定边界采用当前核心和阶段规则；无法可靠刷新上下文时开启新会话。版本不一致需先协调，才能继续写入流程状态。
+
+schema 1 的旧交付，需要显式迁移选中的交付、采用新规则、整理文档后，再继续阶段推进。迁移保留原件和历史结果，不补造过去缺失的计划，也不会自动重写全部正文。未知格式保持只读，软件升级不会扫描改写所有已结束交付。供 Agent／贡献者使用的 [CLI 协议](cli.md)说明具体恢复方式。
+
+<a id="uninstall"></a>
+## 9. 宿主断开与卸载
+
+只断开一个宿主，保留核心和其他宿主登记：
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
+```
+
+其他已登记宿主还需要的共享入口会保留。断开最后一个宿主也保留核心，以便诊断或重新连接；兼容宿主仍可能发现剩余的共享入口。
+
+移除所有受管理的软件和宿主入口：
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" uninstall
+```
+
+完整卸载保留交付资料、用户代码、自定义文件和必要配置。修改过或不属于它管理的文件会保留并报告。完全移除后，稳定入口也会移除；重启宿主会话以清除缓存规则。删除交付历史是另一项需要明确提出的操作。
+
+<a id="troubleshoot"></a>
+## 10. 常见问题
+
+| 现象 | 处理方式 |
+| --- | --- |
+| 找不到 Aimship，或出现重复项 | 刷新宿主，检查实际选择器及返回的入口路径／版本。不要删除无关入口；安装健康不代表宿主已经发现 Skill。 |
+| 目录访问被拒绝 | 在该宿主授权需要的资料／代码根目录，报告具体操作，不搬动资料或关闭权限控制来绕过限制。 |
+| 管理位置被修改或被其他文件占用 | 保留内容，检查归属，明确合并定制内容后再重试。 |
+| 安装只完成了一部分 | 查看 `status`，排除报告的原因，在同一目录重跑完全相同的待恢复版本；不要在恢复途中换版本。 |
+| 稳定入口缺失或损坏 | 在对应版本的源码／包安装器中执行 `node bin/aimship.mjs status --home <安装用户目录>`；该操作只诊断，检查原因后再运行安装器修复。 |
+| 版本与预期不一致 | 查询稳定安装入口；源码或旧版本 CLI 可能报告不同版本，继续前刷新当前绑定。 |
+| 包／版本不存在或认证失败 | 核对包名、明确版本和 registry。下载失败不算安装完成，不在问题报告中粘贴凭据。 |
+| `status.md` 过期或被手改 | 请 Agent 读取当前状态和正文，保留手改内容后明确重建视图，不用视图覆盖状态。 |
+| 正式文档在流程外被修改 | 核对含义与受影响工作；状态和视图 revision 相同，也不证明正文未变。 |
+| 旧交付无法继续 | 请 Agent 分别检查迁移、规则采用和文档整理，保留历史结果并报告未解决的阻塞。 |
+
+反馈问题时附上 Aimship 版本、宿主／版本、具体命令或操作、预期与实际结果，以及最小合成复现。隐去凭据、个人路径和私有资料，通过 [GitHub Issues](https://github.com/clsx/aimship/issues)提交。参与开发请看 [CONTRIBUTING](../CONTRIBUTING.md)。
+
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+## 11. 交付完成条件
+
+以本次委托的终点为准：设计委托完成约定方案即可，开发委托包含必要的审核和验证。要求预览当前结果不代表缩短目标。明确提前结束时，在交接中保留原目标和未完成工作。
+
+目标完成、用户验收、合并和部署分别记录。后续小修正可重开原交付并保留此前关闭记录；新目标或大幅重新设计则建立关联的新交付。父子交付管理和多 Agent 编排暂不自动化。

package/docs/installation.md

@@ -0,0 +1,24 @@
+# Installation guide moved
+
+Installation and lifecycle instructions now live in the complete user guide. This page preserves the old entry point.
+
+- [English guide](guide.md#install)
+- [中文使用指南](guide.zh-CN.md#install)
+
+<a id="installation-layout"></a>
+<a id="source-and-local-packages"></a>
+<a id="isolated-trial"></a>
+<a id="registry-installation-after-publication"></a>
+Installation layout, source/local packages and isolated trials: [English](guide.md#install) · [中文](guide.zh-CN.md#install).
+
+<a id="host-entry-and-reload"></a>
+Host entry and reload: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts).
+
+<a id="add-a-host-inspect-and-update"></a>
+Add a host and inspect the installation: [English](guide.md#hosts) · [中文](guide.zh-CN.md#hosts). Update software: [English](guide.md#update) · [中文](guide.zh-CN.md#update).
+
+<a id="disconnect-or-uninstall"></a>
+Disconnect or uninstall: [English](guide.md#uninstall) · [中文](guide.zh-CN.md#uninstall).
+
+<a id="troubleshooting-and-recovery"></a>
+Troubleshooting and recovery: [English](guide.md#troubleshoot) · [中文](guide.zh-CN.md#troubleshoot).