aimship 0.0.0-stage → 0.1.0-preview.4

package/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# 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.
+
+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.

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,45 @@
-# 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)
+
+Aimship helps you organize and carry out development tasks in AI coding tools. Use it to develop features, fix bugs, refactor code or prepare a design.
+
+From the initial request to delivery, Aimship arranges the stages needed for the task and keeps a record of requirements, designs, progress and results. When requirements change, the relevant materials are updated. New conversations can continue from those records, reducing the need to explain the background again or organize progress notes manually.
+
+Each task has its own delivery folder under `~/Aimship/`, while code stays in its repository. You can work on several independent tasks at once, or limit a task to requirements analysis or design.
+
+## Installation
+
+Requires Node.js 22+ and npm. Select a host with `--host`: `codex`, `cursor` or `claude-code`.
+
+```sh
+npx aimship@preview install --host codex
+```
+
+The npm command becomes available when the preview is published. For the current source or a local package, see the [installation guide](docs/installation.md).
+
+Aimship shares one installation across projects and selected hosts. It does not require a global npm install. After installation, start a new host session and enable access to the delivery folder and code repositories as needed.
+
+## Usage
+
+Select Aimship in the host: `$aimship` in Codex CLI, or `/aimship` in Cursor and Claude Code. Describe the intended result:
+
+> Use Aimship to add Excel export to the order list.
+
+Aimship uses the request and available materials to clarify the scope and arrange the work. Include any specific limits in your request, such as “Design only for this task.”
+
+To continue in a new session, provide the existing delivery directory:
+
+> Use Aimship to continue the task in `~/Aimship/order-export/`.
+
+Use the same delivery directory when switching hosts, with access authorized separately in each host. Multiple independent deliveries can progress at once; keep one writing session per delivery. See the [user guide](docs/guide.md#work-on-two-requests-at-once) for shared-repository and worktree examples.
+
+## Documentation and feedback
+
+- [Installation guide](docs/installation.md): host setup, updates, version and status queries, uninstall and troubleshooting.
+- [User guide](docs/guide.md): scope, stages, changes, parallel deliveries and session handoff.
+- [Tool protocol](docs/cli.md): state and recovery commands for agents and contributors.
+
+The preview is intended for experimentation and feedback. Host integration requirements are described in the installation guide. Report bugs and feature requests through [GitHub Issues](https://github.com/clsx/aimship/issues). See [Contributing](CONTRIBUTING.md) to contribute.
+
+Released under the [MIT License](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,45 @@
+# Aimship
+
+[English](README.md)
+
+Aimship 帮助你在 AI 编程工具中组织和推进开发任务，适用于功能开发、问题修复、技术重构和方案设计。
+
+从提出需求到完成交付，Aimship 根据任务需要安排工作阶段，并保存需求、设计、进度和结果。需求发生变化时，相关资料随之更新；切换会话后，可以根据已有记录继续工作，减少重复解释背景和手动整理进度的负担。
+
+每项任务在 `~/Aimship/` 下拥有独立的交付资料目录，代码保留在原仓库。你可以同时推进多个独立任务，也可以只委托其中的需求分析或设计工作。
+
+## 安装
+
+需要 Node.js 22+ 和 npm。通过 `--host` 选择宿主：`codex`、`cursor` 或 `claude-code`。
+
+```sh
+npx aimship@preview install --host codex
+```
+
+此 npm 命令在预览版发布后可用。当前源码或本地安装包的使用方式见[安装指南](docs/installation.md)。
+
+多个项目和已接入宿主共用一份 Aimship，无需全局安装 npm 包。安装后开启新的宿主会话，并按实际需要授权访问交付目录和代码仓库。
+
+## 使用
+
+在宿主中选择 Aimship：Codex CLI 使用 `$aimship`，Cursor 和 Claude Code 使用 `/aimship`，随后描述预期结果：
+
+> 使用 Aimship，为订单列表增加导出 Excel 的功能。
+
+Aimship 会根据需求和已有资料帮助明确范围、安排工作。有具体限制时，可以在需求中补充，例如“本次只完成设计”。
+
+在新会话中继续工作时，提供已有交付目录：
+
+> 使用 Aimship 继续 `~/Aimship/order-export/` 中的任务。
+
+切换宿主时使用同一交付目录，并分别完成访问授权。多个独立交付可以同时推进；同一次交付保持一个写入会话。同仓库与 worktree 的使用实例见[使用指南](docs/guide.md#work-on-two-requests-at-once)。
+
+## 文档与反馈
+
+- [安装指南](docs/installation.md)：宿主接入、更新、版本与状态查询、卸载及常见问题。
+- [使用指南](docs/guide.md)：范围、阶段、变更、并行交付与会话交接。
+- [工具协议](docs/cli.md)：供 Agent 与贡献者使用的状态及恢复命令。
+
+预览版用于试用和收集反馈，宿主集成要求见安装指南。Bug 和功能建议请通过[GitHub Issues](https://github.com/clsx/aimship/issues) 提交；参与贡献请参阅[贡献说明](CONTRIBUTING.md)。
+
+本项目采用 [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,62 @@
+# Local tool protocol
+
+The agent normally runs these tools to handle file structure and version/revision checks, not business decisions. Cross-delivery overlap checking is an agent workflow using existing state and focused local Git metadata, not a CLI concurrency guarantee or a new registry. All commands emit JSON; errors include a code, message and recovery advice with a nonzero exit status. Run `node bin/aimship.mjs help` in a source checkout for the complete current interface.
+
+## Bind and create
+
+An installed entry invokes the stable `.aimship/bin/aimship.mjs` launcher. `bind` returns the active immutable release, core, stage directory, CLI path, rules version, configured material root and config/custom locations. Use the returned fixed CLI and version for this session. Paths in examples below are placeholders to replace with your actual paths, safely quoted for your shell.
+
+```sh
+node '<stable-launcher>' bind
+node '<fixed-cli>' init '<delivery-dir>' --rules-version '0.1.0-preview.4' --input '<init.json>'
+```
+
+Before `init`, save the original request and current requirements/Scope in the actual delivery directory. `init` creates state once; it does not create requirement templates or infer authority. Minimal input:
+
+```json
+{
+  "goal": {"summary": "Explain the selected design", "endpoint": "Design handoff"},
+  "goalRef": "requirements.md",
+  "stageRuns": [],
+  "next": {"action": "Record the agreed stage arrangement", "inputRefs": ["requirements.md"]}
+}
+```
+
+Identity, schema/rules version, revision and timestamps are tool-managed. Do not include them in init input. A useful arrangement contains distinct `stageRuns` with `id`, `stage`, `scope`, `progress`, `inputRefs`, and `outputRefs`. `currentRun` names one of them or is null. Associate repositories as `{id, path, role}` with an absolute actual checkout/worktree root. IDs are local to this delivery; they do not establish cross-delivery repository identity. Use role and current scope to distinguish read-only reference from intended code writes; record actual authorized scope and working basis in the associated requirements/evidence.
+
+## Read, update and check
+
+```sh
+node '<fixed-cli>' read '<delivery-dir>' --rules-version '0.1.0-preview.4'
+node '<fixed-cli>' update '<delivery-dir>' --revision 0 --rules-version '0.1.0-preview.4' --input '<patch.json>'
+node '<fixed-cli>' check '<delivery-dir>' --rules-version '0.1.0-preview.4'
+node '<fixed-cli>' resume '<delivery-dir>' --rules-version '0.1.0-preview.4'
+```
+
+Use the revision just read; a conflict requires rereading and reconciling. Updates recursively merge objects but replace arrays in full. `null` is a value, not deletion. `--input -` reads a JSON object from stdin. Completed stage runs need `resultRef`; retained old results use `priorResultRef` or `historyResultRefs`. Removing an already-started run or historical result reference is rejected.
+
+References are delivery-relative, `repo:<id>/<relative-path>`, or HTTP(S) URLs, with optional fragments. Current checks inspect goal/next/current-input paths; `--all` also checks registered historical, decision, outcome, checkpoint and rule-change references. A file-existence result does not validate its fragment, contents or meaning. Remote references are not fetched by this tool. `resume.canProceed` is false for a recorded blocked current run, missing input paths or version mismatch. A true value only means these structural blockers were not found; the agent still checks authority, unresolved decisions and stage completion. Unknown schemas remain readable but cannot be overwritten.
+
+`progress` is planned/active/blocked/done. Results are passed/failed/not-run/unknown/mixed; applicability is current/needs-review/unknown. `outcome.goal` is in-progress/met/not-met/unknown; acceptance is not-recorded/accepted/declined/unknown. A met goal requires a goal conclusion reference; acceptance requires its own decision reference. These are separate from merge/deployment references. The agent must assess the evidence; fields are not proof of success.
+
+Changing the goal or goal reference requires a new `goal.decisionRef`; the tool preserves the old goal and outcome. Reopening increments `cycle` by one, retains a prior closure reference and resets current acceptance. Important changes remain in `openChanges` with stable ID/reference and open/closed status rather than disappearing when resolved.
+
+## Recovery and rules adoption
+
+Writes save `state.previous.json` and replace state atomically. If state is damaged, inspect actual artifacts and the backup before explicit recovery:
+
+```sh
+node '<fixed-cli>' recover '<delivery-dir>' --revision '<backup-revision>' --rules-version '<bound-version>'
+```
+
+Recovery preserves damaged bytes and refuses to roll back a valid or newer unknown state. It cannot reconstruct unrecorded effects. A stale lock requires confirming there is no active writer before removing only that lock. No parallel workflow scheduling is provided.
+
+When an upgrade makes an old session mismatch, stop new stages. A compatible old tool can `checkpoint` only `{checkpoint: {summary, ref?}, next: {...}}` with its old rules version and current revision. It cannot complete a run or goal. Reload the active rules, inspect compatibility at a stable point, then use the active tool's `adopt` with input `{compatibilityRef: "results.md#rules-switch"}`. This records a rule switch without changing historical business facts. Schema 1 is the initial format; no legacy DeliveryArc migration or invented older Aimship migration is provided. Unsupported formats require a future supported migration and remain preserved meanwhile.
+
+## Installation diagnostics
+
+User-facing installation, explicit update, version/status and uninstall commands are documented in one [installation guide](installation.md). `install` performs software installation and updates; this protocol's `update` continues to mean a revision-checked delivery-state update.
+
+`--version` distinguishes the CLI/tool version from the active installed release. Use the stable launcher for the current installation. `status` is read-only, inspects the known installation and managed entry files, and reports registration separately from entry integrity. It does not establish host loading, login, permissions or semantic delivery readiness. The key fields are `installation`, `healthy`, `installedActiveVersion`, `pending`, `registeredHosts`, `hosts`, and `issues`. Each host separates `registered`, `entryPresent`, `entryIntegrity`, `sharedWith`, `hostLoaded`, `login`, and `permissions`; the final three remain `not-verified`. `unselectedHostDiscoveryPossible` warns about compatible discovery. A diagnostic command may exit successfully while reporting `healthy: false`; inspect its data. `--version` includes `toolVersion` and `installedActiveVersion`, which may differ when called from an older release.
+
+Installation transition results include previous and target versions; failures retain pending information for recovery. Disconnecting a named host retains the core, even when no registered hosts remain; full uninstall is a separate invocation without `--host`. Shared entries needed by another registration remain present. No purge-history command exists.

package/docs/guide.md

@@ -0,0 +1,59 @@
+# Using Aimship
+
+## Describe the work and its endpoint
+
+Explicitly select Aimship and say what result you want, where the relevant materials/code are, and how far the agent may proceed. An existing clear instruction is enough; you do not need to prepare a complete PRD. A design-only goal may need no code repository.
+
+The agent records the original request and current requirements/Scope, proposes the stages needed for this goal, and explains meaningful choices. Once the arrangement is accepted, it remains the execution order. You decide material business, scope, compatibility, cost or data choices; routine engineering choices do not require repeated approval. Silence does not approve an unanswered proposal.
+
+Materials default to a delivery folder beneath `~/Aimship`, configurable at installation. Code remains in place, linked by repository identity and location in the delivery state. The material directory need not be the host's main workspace. Access is handled when an actual operation needs it; the agent must not silently move the materials or disable host controls.
+
+## Work on two requests at once
+
+You can keep `~/Aimship/notification-preferences/` and `~/Aimship/invoice-export/` active at the same time. Each has its own goal, stages and state, with one writing session per delivery. They may use different repositories or the same repository.
+
+For example, request A is implementing in an app checkout while request B is designing invoice export using that code as a read-only reference. B may continue design after a brief overlap note. Before B writes code, the agent checks the recorded work again: if both would edit A's checkout, use your existing choice to implement sequentially or use a separate worktree/checkout. If B already has an isolated worktree, reuse it. Neither file isolation nor finishing B's branch means the changes are already merged or business-compatible. The handoff names the actual code directories, branch/commit, uncommitted work and pending integration.
+
+When code scope is associated/changed, implementation begins or a working directory changes, the agent checks accessible delivery states in known material roots, including older unfinished deliveries rather than only recent ones. It reads focused Scope/plan sections only if needed. Ended deliveries are not counted as active writers; their pending integration may still be a dependency. Known shared interfaces, databases or test resources are arranged in the existing plan, even across different repositories.
+
+This reports overlaps found in recorded deliveries. Stale records, inaccessible or unknown custom roots and work outside Aimship can hide overlaps. No matching record is not a guarantee of safety. There is no global lock, automatic worktree creation, agent scheduling or automatic merge; the agent preserves existing branches and unknown changes.
+
+## Keep only useful artifacts
+
+Every delivery has current requirements and state, with the original request traceable. A small fix can use a short requirement, state, and a results document with separate diagnosis/review/verification/handoff sections. A larger feature can have interaction, technical design, contracts, a batch plan and test cases. Unselected responsibilities do not produce empty templates.
+
+External PRDs, prototypes and images remain unchanged. Scope identifies their adopted versions, requirement mappings, conflicts and decisions. A link alone may not preserve a source version. Text extraction, visual inspection, browser interaction and original-format editing are different capabilities; the agent must identify missing parts.
+
+Reuse existing engineering HTTP contracts. If database structures or data change, the design links a separate delivery-local SQL file with its dialect and conditions. SQL is a normal deliverable: generating it does not authorize changing migrations or running it.
+
+## Review, verify and change
+
+For multiple batches, implement and review each batch, review the integrated change, then execute the independent verification plan. Test code can be developed during implementation. A single review can cover both batch and overall scope for a single batch if the record says so.
+
+Results identify the actual code/document version, scope, executor, environment and evidence. Review is not a runtime test. Missing accounts, tools or environments remain unexecuted checks with a concrete next action; they are not deleted to produce a passing report.
+
+A meaningful change gets one record explaining reason, old/new meaning, decision and affected work. Editable requirements/design/contracts/SQL/tests are updated, affected conclusions are reviewed, and old evidence remains historical. Unrelated work is not reset. An implementation defect is fixed against the requirement, not hidden by weakening it.
+
+## Continue in another conversation
+
+At a stable phase or batch boundary ask for a handoff to a new conversation. The agent saves state, current facts, unresolved changes and next-step references, then supplies a short prompt with the absolute delivery path. Open the new conversation yourself and explicitly resume Aimship there. A different host uses that same directory and state; do not copy the materials. It needs its own authorized access to the material and code roots.
+
+The new conversation reads that state and the needed current inputs. It does not need the entire chat, repeat agreed goals, or rerun every test. After compression it reloads missing rules and inputs using the saved binding. If the location is lost, provide the delivery path. Avoid concurrent writing sessions for the same delivery; independent deliveries can progress separately.
+
+If a referenced repository moved, give the new location; the agent checks identity before repairing it. Interrupted operations need inspection of actual artifacts before continuation, especially operations with side effects. A revision conflict is reconciled, never force-overwritten.
+
+## Update or stop using Aimship
+
+Use the single [installation guide](installation.md) for commands, host reload differences and troubleshooting.
+
+Explicitly install the desired local release/version using the same installer. Daily work uses fixed local files, not repeated `npx ...@latest` calls. Installation preserves customizations and delivery content, and reports conflicts with modified or unrelated skill files.
+
+When a session's old rules differ from the current installation, finish saving current facts and switch at a stable point. Reload the new core/current stage, assess compatibility and adopt the new rules. If context cannot reliably refresh, resume the same delivery in a new conversation. Unknown formats remain read-only; unsupported migration is reported rather than guessed. Ended deliveries are not swept or rewritten during upgrade.
+
+Uninstall through the stable launcher as documented in [the CLI guide](cli.md). It removes only confirmed managed files, retaining delivery materials, custom content and necessary configuration. Removing delivery data is a separate explicit action.
+
+## Decide when work is done
+
+The endpoint controls completion. A design commission ends with its agreed design; development includes its required validation. Asking to see current results does not shorten the goal. An explicit decision to end earlier preserves the original goal and outstanding work in the handoff.
+
+Goal achieved, user acceptance, merge and deployment remain separate. Small later corrections can reopen the delivery while retaining its previous closure; a new goal or substantial redesign starts a related delivery. Aimship does not automatically manage parent/child work or multiple agents.

package/docs/installation.md

@@ -0,0 +1,117 @@
+# Installation and lifecycle
+
+## Installation layout
+
+Aimship installs fixed releases under `~/.aimship/` and a stable launcher at `~/.aimship/bin/aimship.mjs`. User configuration and custom content are separate from release files. A current release and at most one ordinary recovery release are retained; changed or unowned files are preserved and reported.
+
+Choose `codex`, `cursor` or `claude-code` using repeatable `--host`. Registered hosts use one core and rules version. No per-project install, administrator privilege, npm global install, background updater or resident process is required. Source checkout, local tarball and registry examples all invoke this same installer; choose the appropriate source, do not stack them as separate host installations or add manual skill copies alongside managed entries. Installing software, connecting a host and starting a delivery are separate actions. Installation never creates `~/Aimship` or an empty delivery and never changes code repositories.
+
+Node 22+ and npm are required. Installation and tool behavior have been checked on macOS arm64 with Node 24 and 26. Node 22 and other operating systems are not yet verified. Shell examples below use a POSIX shell. Preserve any existing installation before resolving conflicts.
+
+## Source and local packages
+
+From the source checkout:
+
+```sh
+node bin/aimship.mjs install --host codex
+```
+
+From the directory containing a supplied tarball:
+
+```sh
+npx --offline file:./aimship-0.1.0-preview.4.tgz install --host codex
+```
+
+Run these against your real home only when you intend to install. Repeat `--host` to connect multiple hosts in that operation. No login to npm is needed to consume a local tarball; npm still needs a writable cache. The installer reports the installation home, previous/target version, action/result, registered hosts and entry locations. A zero exit status is not proof that a host has loaded the skill.
+
+### Isolated trial
+
+These commands use one disposable installation and npm cache, not your real configuration. Put the candidate tarball in your current directory first:
+
+```sh
+trial=$(mktemp -d)
+trial=$(cd "$trial" && pwd -P)
+npx --yes --offline --cache "$trial/npm-cache" file:./aimship-0.1.0-preview.4.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 only Aimship's managed installation. It does not make the running host discover this home, log in, or inherit permissions. The installed launcher and fixed release CLI default later management operations to their own installation home. An explicit `--home` overrides that target. After inspection, the disposable directory can be removed by its owner; do not substitute a real home for this temporary variable.
+
+## Registry installation after publication
+
+This candidate has not been published. After the maintainer confirms the package identity and publishes this exact preview, the proposed initial command is:
+
+```sh
+npx aimship@preview install --host codex
+```
+
+The `preview` tag selects the preview channel. To select an exact version, replace `@preview` with its version number. Confirm the package installation when npm prompts. npm obtains the installer; it copies a complete local release, so subsequent use does not depend on that npm cache. Do not use an unversioned command and assume it selects the preview channel. A missing package/version is a distribution failure, not a successful installation.
+
+## Host entry and reload
+
+| Host | Managed entry | Explicit use | After install, update or disconnect |
+| --- | --- | --- | --- |
+| Codex | `~/.agents/skills/aimship/` with `agents/openai.yaml` | Select Aimship; CLI `$aimship` | Start a new conversation or restart the CLI, then inspect its actual skill selector. If stale, restart the app. |
+| Cursor | Same `.agents/skills/aimship/` entry | `/aimship` | Start a new agent session; inspect Customize → Skills in the editor. Restart the host if the list remains stale. |
+| Claude Code | `~/.claude/skills/aimship/` | `/aimship` | Start a new session and inspect slash-command discovery; restart the host if stale. |
+
+These host integrations are experimental; end-to-end host behavior and cross-host continuation have not yet been verified. Check skill discovery and directory access in your host before starting a delivery. Each host needs its own authentication, model availability and permission to access materials and code. Do not disable permission controls or grant unrelated directories. No cloud synchronization is installed or enabled.
+
+Codex and Cursor share the managed entry. Cursor also documents compatibility discovery from Claude/Codex directories. Aimship registers only selected hosts; it cannot guarantee that an unselected compatible host will not display an entry. If two same-name entries appear, inspect their paths and installation version rather than deleting unrelated files. Shared entry presence is distinct from registration, host discovery, login and permission. See the official [Cursor directories](https://cursor.com/docs/skills) and [Codex skill locations](https://learn.chatgpt.com/docs/build-skills).
+
+After an update, a running conversation may retain old rules. Save current facts, reload the bound core and current stage at a stable point, and use the existing compatibility/adoption process; start a new conversation if context cannot reliably refresh. Version mismatch stops new workflow writes. Never infer that installation instantly changed an active conversation.
+
+## Add a host, inspect and update
+
+Reuse the installed core without fetching another package:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" install --host cursor
+node "$HOME/.aimship/bin/aimship.mjs" --version
+node "$HOME/.aimship/bin/aimship.mjs" status
+```
+
+Repeating the same install is safe for unchanged managed files. Adding a host preserves existing registrations. `status` reads Aimship's known installation files and managed entries; it does not scan projects or query host accounts. It separates registered hosts, missing/modified files, shared entries, pending installation and active version from unverified host capabilities. It is diagnostic, not a semantic delivery validator.
+
+To update from a new local release, run that release's `install` command with the same installation home. No `--host` is necessary for an existing installation: registered hosts are retained, and a core whose last host was disconnected remains a core-only installation. After publication, the explicit preview-channel update is:
+
+```sh
+npx aimship@preview install
+```
+
+There is one installation/update operation: `install`. `update` in the low-level CLI modifies delivery state and is **not** a software updater. The installer reports old and target versions and the result, updates the shared core and selected entries, and preserves configuration, custom content and every delivery. Completed deliveries are not traversed or rewritten. No automatic update runs in the background.
+
+## Disconnect or uninstall
+
+Disconnect one host, leaving the core and other registrations usable:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" uninstall --host cursor
+```
+
+If another registered host needs a shared entry, that file is retained and reported. Disconnecting the last host retains the core so version/status and later host connection remain available. A compatible host may still discover an entry used by another host; this command does not change that host's settings.
+
+Remove all managed programs and entries:
+
+```sh
+node "$HOME/.aimship/bin/aimship.mjs" uninstall
+```
+
+Full uninstall retains all delivery materials, user code, custom files and necessary configuration. Modified/unowned files are preserved and listed. No option purges delivery history. The launcher is removed on complete removal; inspect the returned result. Restart existing host sessions to discard cached rules.
+
+## Troubleshooting and recovery
+
+- **Foreign or modified entry/release:** read the reported path, keep its contents and resolve ownership or merge customizations explicitly. Do not force-overwrite it to obtain a successful exit status.
+- **Partial installation:** `status` can identify pending work. Rerun the exact pending package against the same home after correcting the reported cause. Binding/new workflow writes remain suspended until recovery completes. Do not choose a different version mid-recovery.
+- **Launcher unavailable:** run `node bin/aimship.mjs status --home <installation-home>` from the exact source/package installer. A missing launcher or damaged diagnostic module cannot diagnose itself. `status` reports facts without repairing them; only after inspecting the cause should you rerun the exact installer or reconcile retained files.
+- **Unexpected version:** use the stable launcher for the installed active version. A CLI inside an older release can report a different tool version; reload the current binding before continuing. A source checkout is not automatically an installed release.
+- **Package not found/authentication error:** confirm the exact package/version and public registry. Installation of a public release does not itself prove publish rights. Do not paste credentials into a bug report.
+- **Skill absent or duplicated:** inspect the actual host selector and returned entry paths after reloading. A file check alone cannot diagnose host discovery; retain this as unverified until observed.
+- **Directory denied:** authorize only the needed delivery/code roots in that host. Shared material storage does not share permissions. Report the exact denied operation rather than relocating user materials or changing security settings.
+- **Different host/session:** explicitly resume the same absolute delivery directory and inspect state/current inputs. Do not copy materials, reset the goal or run two writers. See [the user guide](guide.md).
+
+The initial data root can be selected with `--data-root` on installation. Existing configuration is retained on later installs; no language setting or second installation mode is introduced. Low-level state/version/recovery contracts are in [the CLI protocol](cli.md).

package/lib/cli.mjs

@@ -0,0 +1,159 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { exists, fail, noSymlinks, readJSON } from './io.mjs';
+import { install, installPaths, installationStatus, installationVersion, readConfig, uninstall } from './install.mjs';
+import { SCHEMA_VERSION, STAGES, assertInstallationComplete, assertRules, checkReferences, initState, readState, recoverState, updateState, validateState } from './state.mjs';
+
+const HELP = {
+  usage: 'node <aimship.mjs> <command> [delivery-directory] [options]',
+  commands: {
+    status: 'status [--home <dir>]. Read only Aimship-managed paths and fixed entries. Report registration, shared entry presence/integrity, active version, pending work and config problems. Host loading, login and access permissions remain unverified; no directories are created.',
+    bind: 'Resolve active installation once. Returns immutable release/core/stage/CLI paths plus configured dataRoot, configPath and customPath. Source mode returns the default data root with null config/custom paths. No directories are created. Optional --home is for isolated testing.',
+    init: 'init <dir> --input <json-file|-> --rules-version <version>. Create state once; input requires goal {summary, endpoint} and goalRef. Does not create templates.',
+    read: 'read <dir> [--rules-version <version>]. Read-only JSON access; unknown schemas remain readable.',
+    update: 'update <dir> --revision <N> --rules-version <version> --input <json-file|->. Recursively merge objects; arrays replace in full. Identity/history fields are managed. null is a literal value, not deletion.',
+    check: 'check <dir> [--rules-version <version>] [--all]. Check structure and current input references (or every registered reference). Does not prove semantics, anchor contents, remote access, or validation results.',
+    resume: 'resume <dir> [--rules-version <version>]. Read state and return fixed rule paths, required inputs, warnings, and continuation text; never execute work or rewrite state.',
+    checkpoint: 'checkpoint <dir> --revision <N> --rules-version <old-version> --input <json-file|->. Save only checkpoint {summary, ref?} and next when a version mismatch interrupts ongoing work. Cannot complete work.',
+    adopt: 'adopt <dir> --revision <N> --rules-version <active-version> --input <json-file|->. Input is {compatibilityRef}; records the assessed stable-point rule switch without changing business history.',
+    recover: 'recover <dir> --revision <backup-revision> --rules-version <version>. Restore state.previous.json only over missing/corrupt state; preserve corrupted bytes. Inspect actual artifacts afterward; nothing reruns.',
+    install: 'install --host <codex|cursor|claude-code> [--host ...] [--data-root <dir>] [--home <dir>]. Explicitly copy the whole release into .aimship. Repeated installs retain registered hosts. Installed tools default to their owning home; explicit --home overrides it for isolated testing. Data root is configured, never created.',
+    uninstall: 'uninstall [--host <host> ...] [--home <dir>]. --host disconnects selected hosts, retaining shared core even when no hosts remain. Omit --host for full product uninstall. Delivery data, config, custom and modified/unowned files are retained. Installed tools default to their owning home; explicit --home overrides it.',
+    help: 'help [command]. Every command supports --help. --version reports the executing tool version and installed active version separately. install is the only installation/update entry; update modifies delivery state.'
+  },
+  stateProtocol: {
+    schemaVersion: SCHEMA_VERSION,
+    stages: STAGES,
+    progress: ['planned', 'active', 'blocked', 'done'],
+    result: ['passed', 'failed', 'not-run', 'unknown', 'mixed'],
+    applicability: ['current', 'needs-review', 'unknown'],
+    outcome: { goal: ['in-progress', 'met', 'not-met', 'unknown'], acceptance: ['not-recorded', 'accepted', 'declined', 'unknown'] },
+    stageInstance: { id: 'stable-instance-id', stage: '<stage>', scope: 'batch or whole-delivery scope', progress: 'planned', inputRefs: [], outputRefs: [], resultRef: 'results.md#unique-historical-section (required when done)' },
+    references: 'delivery-relative/path#optional-fragment, repo:<registered-id>/<repo-relative-path>#fragment, or HTTP(S) URL. Local paths cannot escape their root. Repository registration: {id, path: absolute-path, role}.',
+    topLevel: {
+      managed: 'schemaVersion, revision, deliveryId, rulesVersion, createdAt, updatedAt, goalHistory, rulesHistory. Do not supply these in init/update.',
+      requiredInit: 'goal: {summary, endpoint}; goalRef: current requirements or Scope reference. Save the original request in that referenced document before init.',
+      stageRuns: 'Ordered array of stageInstance objects, default []. Every ID is unique; currentRun must match one of these IDs or be null. Stage types may repeat with distinct IDs.',
+      currentRun: 'Instance ID or null (default). Do not invent an ID without registering its instance in stageRuns.',
+      repositories: 'Array of {id, path: absolute-path, role, ...optional-version-facts}, default []. No repository is required for a design-only goal.',
+      openChanges: 'Array of {id, ref, status: open|closed}, default []; close records rather than deleting history.',
+      outcome: 'Defaults to {goal: in-progress, acceptance: not-recorded}. A met goal needs goalConclusionRef; recorded acceptance needs acceptanceRef. Optional handoffRef, mergeRef, deploymentRef retain independent facts.',
+      next: '{action, inputRefs?: []}; defaults to continuing the confirmed arrangement.',
+      cycle: 'Positive integer, default 1. A reopening increments by one, appends a closureRef and resets current acceptance.',
+      closureRefs: 'Historical closure references, default []. Preserve them across reopenings.'
+    },
+    minimalInit: {
+      goal: { summary: 'Repair the search empty-state message', endpoint: 'Implement, review, and verify the agreed repair' },
+      goalRef: 'requirements.md',
+      stageRuns: [{ id: 'diagnose-1', stage: 'diagnose', scope: 'Search empty-state repair', progress: 'planned', inputRefs: ['requirements.md'], outputRefs: [] }],
+      currentRun: 'diagnose-1',
+      next: { action: 'Reproduce and diagnose the reported message', inputRefs: ['requirements.md'] }
+    },
+    safety: 'Done is execution progress only. Results, applicability, goal attainment, acceptance, merge, and deployment are independent. Preserve old result references with priorResultRef/historyResultRefs. Goal revision needs a new goal.decisionRef; prior goals are retained automatically.'
+  }
+};
+function parse(argv) {
+  const positional = []; const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const item = argv[i];
+    if (!item.startsWith('--')) { positional.push(item); continue; }
+    const name = item.slice(2);
+    if (!['help', 'version', 'all', 'input', 'rules-version', 'revision', 'host', 'home', 'data-root'].includes(name)) fail('USAGE', `Unknown option: ${item}`, 'Run help for command usage.');
+    const value = ['help', 'version', 'all'].includes(name) ? true : argv[++i];
+    if (value === undefined || (typeof value === 'string' && value.startsWith('--'))) fail('USAGE', `Missing value for ${item}`, 'Provide the option value.');
+    if (name === 'host') (options.hosts ??= []).push(value);
+    else { if (Object.hasOwn(options, name)) fail('USAGE', `Repeated option: ${item}`, 'Provide one value; only --host is repeatable.'); options[name] = value; }
+  }
+  return { positional, options };
+}
+async function inputJSON(file) {
+  if (!file) fail('USAGE', '--input is required.', 'Use a JSON file or --input - to read stdin.');
+  if (file !== '-') return readJSON(path.resolve(file));
+  try { let raw = ''; for await (const chunk of process.stdin) raw += chunk; return JSON.parse(raw); } catch (e) { fail('INVALID_JSON', 'Cannot parse JSON from stdin.', 'Provide one valid JSON object.', { cause: e.message }); }
+}
+function revisionOf(value) {
+  if (!/^(0|[1-9][0-9]*)$/.test(value ?? '') || !Number.isSafeInteger(Number(value))) fail('USAGE', '--revision requires a nonnegative integer.', 'Use the exact revision returned by read (backup revision for recover).');
+  return Number(value);
+}
+function installedRoot(sourceRoot) { return path.basename(path.dirname(sourceRoot)) === 'releases' ? path.dirname(path.dirname(sourceRoot)) : null; }
+async function runtimeFor(sourceRoot, options, explicitRoot) {
+  const pkg = await readJSON(path.join(sourceRoot, 'package.json'));
+  const root = explicitRoot ?? installedRoot(sourceRoot) ?? (options.home ? installPaths(options.home).root : null);
+  let activeVersion = pkg.version;
+  let installPending = null;
+  if (root) {
+    const manifest = await readJSON(path.join(root, 'install-manifest.json'));
+    if (manifest.schemaVersion !== 1 || manifest.product !== 'aimship') fail('INSTALL_FORMAT', 'Unknown installation manifest.', 'Use a compatible installer.');
+    installPending = manifest.pending ?? null;
+    if (await exists(path.join(root, 'active.json'))) {
+      const active = await readJSON(path.join(root, 'active.json'));
+      if (active.launcherProtocol !== 1 || typeof active.version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.-]+)?$/.test(active.version)) fail('INSTALL_FORMAT', 'Active pointer has an unsupported protocol or version.', 'Reinstall the exact complete package.');
+      activeVersion = active.version;
+    } else if (!installPending) fail('NOT_INSTALLED', 'No active installation exists.', 'Install the exact package explicitly.');
+  }
+  return { version: pkg.version, activeVersion, installPending, releaseRoot: sourceRoot, installRoot: root, launcher: root ? path.join(root, 'bin', 'aimship.mjs') : path.join(sourceRoot, 'bin', 'aimship.mjs') };
+}
+async function binding(runtime) {
+  assertInstallationComplete(runtime);
+  const root = runtime.installRoot ? path.join(runtime.installRoot, 'releases', runtime.activeVersion) : runtime.releaseRoot;
+  await noSymlinks(root);
+  const pkg = await readJSON(path.join(root, 'package.json'));
+  if (pkg.version !== runtime.activeVersion) fail('RELEASE_CONFLICT', 'Active pointer and release package version differ.', 'Repair installation before continuing.');
+  const corePath = path.join(root, 'skills', 'aimship', 'references', 'core.md');
+  if (!await exists(corePath)) fail('INCOMPLETE_RELEASE', 'The bound core is missing.', 'Repair the exact installation before continuing.');
+  const configPath = runtime.installRoot ? path.join(runtime.installRoot, 'config.json') : null;
+  let dataRoot = path.join(os.homedir(), 'Aimship');
+  if (configPath) {
+    dataRoot = (await readConfig(configPath)).dataRoot;
+  }
+  return { version: pkg.version, schemaVersion: SCHEMA_VERSION, launcherProtocol: 1, releaseRoot: root, corePath, stageDirectory: path.join(root, 'skills', 'aimship', 'references', 'stages'), cliPath: path.join(root, 'bin', 'aimship.mjs'), launcherPath: runtime.launcher, nodePath: process.execPath, dataRoot, configPath, customPath: runtime.installRoot ? path.join(runtime.installRoot, 'custom') : null, configurationStatus: runtime.installRoot ? 'installed' : 'source-default' };
+}
+function allowed(command, options) {
+  const common = ['help', 'version'];
+  const perCommand = { status: ['home'], bind: ['home'], init: ['input', 'rules-version', 'home'], read: ['rules-version', 'home'], update: ['input', 'rules-version', 'revision', 'home'], check: ['all', 'rules-version', 'home'], resume: ['rules-version', 'home'], checkpoint: ['input', 'rules-version', 'revision', 'home'], adopt: ['input', 'rules-version', 'revision', 'home'], recover: ['rules-version', 'revision', 'home'], install: ['hosts', 'home', 'data-root'], uninstall: ['hosts', 'home'], help: [] };
+  for (const key of Object.keys(options)) if (![...common, ...(perCommand[command] ?? [])].includes(key)) fail('USAGE', `Option --${key} is not valid for ${command}.`, `Run help ${command}.`);
+}
+export async function run(argv, context) {
+  if (Number(process.versions.node.split('.')[0]) < 22) fail('NODE_VERSION', 'Aimship requires Node.js 22 or later.', 'Install a maintained Node LTS release and rerun this exact package.');
+  const { positional, options } = parse(argv); const command = positional[0] ?? 'help';
+  const pkg = await readJSON(path.join(context.sourceRoot, 'package.json'));
+  const owningInstallRoot = context.installRoot ?? installedRoot(context.sourceRoot);
+  const installHome = options.home ?? (owningInstallRoot ? path.dirname(owningInstallRoot) : undefined);
+  if (options.version) {
+    const installed = await installationVersion({ home: installHome });
+    return { command: 'version', data: { version: pkg.version, toolVersion: pkg.version, installedActiveVersion: installed.installedActiveVersion, installation: installed.installation, pendingVersion: installed.pending?.version ?? null, node: process.version, integrity: 'Use status for managed-file and config integrity; host loading, login and permissions are not verified.', issues: [installed.manifest.error, installed.active.error].filter(Boolean) } };
+  }
+  if (command === 'help' || options.help) {
+    const subject = command === 'help' ? positional[1] : command;
+    if (subject && !HELP.commands[subject]) fail('USAGE', `Unknown command: ${subject}`, 'Run help.');
+    return { command: 'help', data: subject ? { usage: HELP.commands[subject], stateProtocol: HELP.stateProtocol } : HELP };
+  }
+  if (!HELP.commands[command]) fail('USAGE', `Unknown command: ${command}`, 'Run help.');
+  allowed(command, options);
+  if (['install', 'uninstall', 'bind', 'status'].includes(command) ? positional.length !== 1 : positional.length !== 2) fail('USAGE', 'Unexpected or missing positional arguments.', `Run help ${command}.`);
+  if (command === 'status') return { command, data: { toolVersion: pkg.version, ...await installationStatus({ home: installHome }) } };
+  if (command === 'install') return { command, data: await install(context.sourceRoot, { home: installHome, hosts: options.hosts, dataRoot: options['data-root'] }) };
+  if (command === 'uninstall') return { command, data: await uninstall({ home: installHome, hosts: options.hosts }) };
+  const runtime = await runtimeFor(context.sourceRoot, options, context.installRoot);
+  if (command === 'bind') return { command, data: await binding(runtime) };
+  const directory = path.resolve(positional[1]); const rulesVersion = options['rules-version'];
+  if (command === 'init') return { command, data: await initState(directory, await inputJSON(options.input), rulesVersion, runtime) };
+  if (['update', 'checkpoint', 'adopt'].includes(command)) return { command, data: await updateState(directory, await inputJSON(options.input), revisionOf(options.revision), rulesVersion, runtime, command) };
+  if (command === 'recover') return { command, data: await recoverState(directory, revisionOf(options.revision), rulesVersion, runtime) };
+  const read = await readState(directory);
+  let mismatch = null;
+  if (!read.readOnly) { try { assertRules(read.state, rulesVersion, runtime); } catch (error) { mismatch = { code: error.code, ...error.details, recovery: error.recovery }; } }
+  if (command === 'read') return { command, data: { state: read.state, readOnly: read.readOnly, versionMismatch: mismatch, statePath: path.join(directory, 'state.json') } };
+  if (read.readOnly) return { command, data: { state: read.state, readOnly: true, canProceed: false, reason: 'Unknown schema: no structure checking, mutation, or automatic work is permitted.' } };
+  validateState(read.state); const references = await checkReferences(directory, read.state, options.all);
+  const missing = references.filter(x => !['exists', 'not-checked'].includes(x.status));
+  if (command === 'check') {
+    if (missing.length) fail('REFERENCE_CHECK', 'Required references are missing or inaccessible.', 'Repair the specific registered paths; do not scan the disk or overwrite source materials.', { references, versionMismatch: mismatch });
+    if (mismatch) fail('VERSION_MISMATCH', 'State is structurally valid, but rules are not bound consistently.', mismatch.recovery, mismatch);
+    return { command, data: { structure: 'valid', references, semantics: 'not-checked' } };
+  }
+  const currentRun = read.state.stageRuns.find(x => x.id === read.state.currentRun) ?? null;
+  const blocked = currentRun?.progress === 'blocked';
+  return { command, data: { state: read.state, binding: await binding(runtime), readOnly: false, canProceed: !mismatch && missing.length === 0 && !blocked, versionMismatch: mismatch, references, currentRun, continuation: `Use Aimship to continue ${directory}; first read state.json and the current inputs it references, then follow the confirmed arrangement. Inspect unfinished effects and related artifacts before repeating any action.`, warnings: ['Resume does not rerun work, tests, migrations, or other side effects.', 'Structural readiness does not establish authorization, business readiness, or goal completion.', ...(blocked ? [`Current run ${currentRun.id} is recorded as blocked. Resolve its documented blocker before progressing this work.`] : []), ...(missing.length ? ['Some required paths must be repaired.'] : []), ...(read.state.checkpoint ? ['Inspect the saved checkpoint and current artifacts.'] : [])] } };
+}