feat: add agent-driven installation contract

.github/workflows/ci.yml

@@ -37,3 +37,6 @@ jobs:
 
       - name: Run installed-package smoke
         run: npm run smoke:package
+
+      - name: Run Agent bootstrap smoke
+        run: npm run smoke:agent-bootstrap

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+- Add a canonical Agent installation contract so Codex can install OpenDomain
+  without changing host project package metadata, initialize its managed
+  adapter, and prove readiness with diagnostics and validation.
+- Make the npm prerelease channel explicit with `@alpha` and document a
+  checksum-verified, user-local standalone fallback.
+- Add isolated global-install smoke coverage for Agent bootstrap in a non-Node
+  workspace.
+
 ## 0.1.0-alpha.8 - 2026-08-03
 
 - Add Node SEA standalone CLI builds for macOS arm64/x64, Linux x64, and

INSTALL.md

@@ -0,0 +1,111 @@
+# OpenDomain Agent Installation Contract
+
+This is the canonical installation contract for shell-capable AI agents.
+
+When a user asks you to install OpenDomain in the current workspace, complete
+this workflow unless the user's instructions or repository policy are stricter.
+Do not add OpenDomain to the project's dependencies, scripts, package manifest,
+or lockfiles.
+
+## Preconditions
+
+Before changing anything:
+
+1. Confirm the intended workspace root and inspect its repository instructions.
+2. Confirm that shell execution and writes to the workspace are allowed.
+3. Confirm that network access is available for a new installation or upgrade.
+4. Preserve existing project files and report any ownership conflict.
+
+Installation can require the user's approval because it changes their tool
+environment. Never bypass an approval boundary, expose credentials, disable
+integrity checks, or silently escalate privileges. If a precondition is not
+available, stop and report the exact blocker and any changes already made.
+
+## Select An Installation Path
+
+First run `opendomain --version` if `opendomain` is already on `PATH`. A usable
+existing CLI does not need to be installed again; continue with workspace
+initialization or update below.
+
+### npm Alpha Channel
+
+Prefer npm when a supported Node.js and npm tool environment is already
+available. OpenDomain currently supports Node.js 20 or Node.js 22 and newer;
+Node.js 21 is not supported.
+
+During the prerelease period, always name the alpha distribution tag:
+
+```bash
+npm install --global @echopath-labs/opendomain@alpha
+opendomain --version
+```
+
+This is a global tool installation. Do not run `npm install` without
+`--global` from the user's project. If the configured global prefix is not
+writable, use a user-owned npm prefix or ask the user to approve an appropriate
+environment change. Do not use `sudo npm install` by default.
+
+### Verified Standalone Executable
+
+Use the standalone fallback when a compatible npm environment is unavailable:
+
+1. Open the official [OpenDomain releases](https://github.com/echopath-labs/openDomain/releases)
+   and select the intended release, normally the newest non-draft release.
+2. Detect the operating system and architecture, then select the matching
+   `opendomain-v<version>-<target>` asset. Windows assets end in `.exe`.
+3. Download that executable and `SHA256SUMS.txt` from the same release.
+4. Verify the executable against its exact line in the checksum manifest using
+   `shasum -a 256` on macOS, `sha256sum` on Linux, or `Get-FileHash -Algorithm
+   SHA256` in PowerShell.
+5. Only after verification, place it as `opendomain` (or `opendomain.exe`) in a
+   user-writable executable directory on `PATH`, such as `$HOME/.local/bin`.
+6. Run `opendomain --version` and confirm the expected version.
+
+Supported standalone targets and minimum systems are listed in the project
+[README](README.md#standalone-binary-recommended). Never execute an asset when
+the matching checksum is absent or different. Do not silently use `sudo` to
+write to a system directory.
+
+## Initialize The Current Workspace
+
+After the CLI is available, stay in the intended repository root.
+
+If `opendomain/config.yaml` already exists and selects Codex, synchronize the
+managed integration:
+
+```bash
+opendomain update --json
+```
+
+Otherwise initialize the canonical workspace and Codex adapter:
+
+```bash
+opendomain init --tools codex --json
+```
+
+Initialization may create the canonical `opendomain/` workspace, generated
+`.codex/skills/opendomain-*` Skills, and one managed OpenDomain block in
+`AGENTS.md`. It must preserve user-owned content and existing package metadata.
+
+## Prove Readiness
+
+Run both checks before reporting success:
+
+```bash
+opendomain doctor --json
+opendomain validate --json
+```
+
+Installation is complete only when the CLI version command, initialization or
+update, diagnostics, and validation all exit successfully. Report:
+
+- the installed OpenDomain version and installation path;
+- whether the workspace was initialized or updated;
+- the managed files created or updated;
+- the `doctor` and `validate` outcomes;
+- confirmation that project package metadata was not created or modified.
+
+If any command fails, report that command and its actionable diagnostic. Do not
+claim that automatic Agent use is ready. Once the generated Codex integration
+is healthy, its repository instructions and Skills route grounding assurance,
+domain exploration, candidate-first modeling, and Candidate review.

README.md

@@ -64,6 +64,19 @@ The source of truth remains Markdown with YAML front matter stored in Git.
 
 ## Installation And Usage
 
+### Install With Codex
+
+In a shell-enabled Codex session, users can ask:
+
+> Install OpenDomain in this workspace.
+
+Codex should follow the canonical [Agent Installation Contract](INSTALL.md).
+It installs OpenDomain as a user tool, initializes or updates the
+repository-local Codex adapter, and proves readiness with `doctor` and
+`validate`. The workflow must not add a `package.json`, lockfile, dependency,
+or npm script to the host project. Network, shell, filesystem, and approval
+boundaries still apply and must be reported when unavailable.
+
 ### Standalone Binary (Recommended)
 
 Download the binary and `SHA256SUMS.txt` for the same version from
@@ -89,9 +102,12 @@ On macOS or Linux, make the file executable, rename it, and place it on `PATH`:
 
 ```bash
 chmod +x opendomain-v<version>-<target>
-sudo install opendomain-v<version>-<target> /usr/local/bin/opendomain
+mkdir -p "${XDG_BIN_HOME:-$HOME/.local/bin}"
+install -m 0755 opendomain-v<version>-<target> "${XDG_BIN_HOME:-$HOME/.local/bin}/opendomain"
 ```
 
+Ensure that the selected user-owned directory is on `PATH`.
+
 On Windows, rename the asset to `opendomain.exe` and place it in a directory on
 `PATH`. Then initialize a project without adding Node.js metadata:
 
@@ -105,21 +121,25 @@ opendomain validate
 Upgrade by downloading, verifying, and replacing the binary with the asset from
 a newer release. The initial macOS binaries are ad-hoc signed but not notarized;
 Windows binaries are not Authenticode signed. Checksums detect file changes but
-do not establish publisher identity. Homebrew distribution is planned as a
-separate follow-up and is not yet an installation channel.
+do not establish publisher identity. Homebrew is not currently an installation
+channel and will be reconsidered after the project reaches stable distribution
+maturity.
 
 ### npm (Alternative)
 
 Users who already manage a Node.js tool environment can install the same CLI
 from npm:
 
 ```bash
-npm install -g @echopath-labs/opendomain
+npm install -g @echopath-labs/opendomain@alpha
 opendomain init --tools codex
 opendomain doctor
 opendomain validate
 ```
 
+The explicit `@alpha` tag is required during the prerelease period so npm does
+not resolve an older `latest` dist-tag.
+
 Both distribution channels run the same CLI. OpenDomain does not
 create or modify the host project's `package.json`, lockfile, dependency list,
 or npm scripts. `init --tools codex` adds the canonical `opendomain/` workspace,

README.zh-CN.md

@@ -134,6 +134,17 @@ OpenDomain 当前不做：
 
 ## 30 秒开始
 
+### 让 Codex 安装
+
+在可以执行 Shell 的 Codex 会话中，可以直接提出：
+
+> 帮我在当前工作区安装 OpenDomain。
+
+Codex 应遵循正式的 [Agent 安装契约](INSTALL.md)，把 OpenDomain 安装为用户工具，
+初始化或更新仓库局部的 Codex adapter，并通过 `doctor` 和 `validate` 提供可核验的
+完成证据。整个过程不得向宿主项目添加 `package.json`、lockfile、依赖或 npm
+scripts。网络、Shell、文件写入或审批权限不可用时，Codex 必须明确报告阻塞原因。
+
 ### 独立二进制（推荐）
 
 从 [GitHub Releases](https://github.com/echopath-labs/openDomain/releases) 下载同一
@@ -158,9 +169,12 @@ macOS 或 Linux 用户需要添加执行权限并放入 `PATH`：
 
 ```bash
 chmod +x opendomain-v<version>-<target>
-sudo install opendomain-v<version>-<target> /usr/local/bin/opendomain
+mkdir -p "${XDG_BIN_HOME:-$HOME/.local/bin}"
+install -m 0755 opendomain-v<version>-<target> "${XDG_BIN_HOME:-$HOME/.local/bin}/opendomain"
 ```
 
+需要确保所选的用户目录已经加入 `PATH`。
+
 Windows 用户可将文件改名为 `opendomain.exe`，再放入 `PATH` 中的目录。随后直接在
 项目中初始化，不需要 Node.js、`package.json` 或 npm scripts：
 
@@ -173,8 +187,8 @@ opendomain validate
 
 升级时下载新版本、重新校验 SHA-256，然后替换旧二进制。首批 macOS 产物只做
 ad-hoc signing，尚未 notarize；Windows 产物尚未做 Authenticode 签名。checksum
-可以发现文件变化，但不等价于发布者身份证明。Homebrew 将在后续独立阶段提供，
-当前还不是可用安装渠道。
+可以发现文件变化，但不等价于发布者身份证明。Homebrew 当前不是可用安装渠道，
+将在项目达到稳定分发成熟度后重新评估。
 
 ### npm（可选）
 
@@ -184,12 +198,14 @@ ad-hoc signing，尚未 notarize；Windows 产物尚未做 Authenticode 签名
 全局安装 CLI：
 
 ```bash
-npm install -g @echopath-labs/opendomain
+npm install -g @echopath-labs/opendomain@alpha
 opendomain init --tools codex
 opendomain doctor
 opendomain validate
 ```
 
+预发布阶段必须显式使用 `@alpha`，避免 npm 解析到较旧的 `latest` dist-tag。
+
 两种分发渠道运行相同 CLI。OpenDomain 不会在宿主项目中创建或修改
 `package.json`、lockfile、依赖声明或 npm scripts。`init --tools codex` 会创建
 canonical `opendomain/`、生成 `.codex/skills/opendomain-*`，并在 `AGENTS.md`

opendomain/candidates/candidate-0012-agent-native-project-adoption.md

@@ -22,10 +22,19 @@ evidence:
     location: tests/agent-workspace.test.mjs
     summary: Conformance tests require Codex integration to initialize and update without creating package.json or package-lock.json.
     confidence: high
+  - type: human_review
+    location: INSTALL.md
+    summary: The maintainer approved a canonical Agent installation contract in which Codex selects a user-tool installation path, initializes the workspace, and proves readiness without changing host package metadata.
+    confidence: high
+  - type: test
+    location: scripts/smoke-agent-bootstrap.mjs
+    summary: A packed OpenDomain CLI installs into an isolated global prefix and initializes a healthy Codex integration in a non-Node workspace without creating package metadata.
+    confidence: high
 possible_conflicts:
-  - The OpenDomain CLI is still distributed through npm and requires a user-level Node.js runtime until standalone binaries are released.
+  - The npm path still requires a supported user-level Node.js runtime; standalone binaries provide a fallback but add platform and checksum-selection requirements.
   - Agent-specific repository files remain necessary even though host language package metadata is not.
-  - Homebrew and standalone binary delivery are separate changes and have not yet provided external adoption evidence.
+  - Natural-language installation still depends on Agent discovery plus network, shell, filesystem, and human approval boundaries.
+  - The installation contract and isolated smoke do not yet provide external-project adoption or upgrade evidence.
 review:
   state: proposed
   suggested_reviewer: opendomain-maintainer
@@ -51,6 +60,6 @@ human workflow.
 
 ## Requested Human Review
 
-Keep this rule proposed until the Codex bootstrap, standalone binary, Homebrew
-installation, and at least one external project adoption confirm that a
-package-manager-neutral project workspace remains practical across upgrades.
+Keep this rule proposed until at least one external project adoption and an
+upgrade cycle confirm that the package-manager-neutral workspace and Agent
+installation contract remain practical outside OpenDomain's own repository.

package.json

@@ -36,6 +36,7 @@
     "scripts/smoke-installed-package.mjs",
     "schemas/",
     "examples/erp/",
+    "INSTALL.md",
     "README.md",
     "README.zh-CN.md",
     "LICENSE",
@@ -53,6 +54,7 @@
     "prepare:demo": "cd examples/erp && node ../../bin/opendomain.mjs prepare openspec/changes/order-cancellation/spec.md",
     "demo": "node ./bin/opendomain.mjs demo order-cancellation",
     "build:standalone": "node ./scripts/build-standalone.mjs",
+    "smoke:agent-bootstrap": "node ./scripts/smoke-agent-bootstrap.mjs",
     "smoke:package": "node ./scripts/smoke-installed-package.mjs",
     "smoke:standalone": "node ./scripts/smoke-standalone.mjs",
     "prepublishOnly": "npm test && npm run opendomain -- validate"