feat(host): add WorkBuddy as a first-class init agent

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable public changes to AOCI-CODE will be documented in this file.
 
 ## Unreleased
 
+- Add WorkBuddy as a first-class `init --agent` host. WorkBuddy exposes no
+  project-scoped MCP surface — its only entry is the machine-level
+  `~/.workbuddy/mcp.json` — so `init --agent workbuddy` merges an entry there
+  and writes nothing into the repository: no Baseline path, no `.gitignore`
+  line, no host file for `git status` to report. Because that file is shared by
+  every project while a server is bound to one `--repo`, the installer never
+  overwrites a foreign entry: an `aoci` key already pointing at another
+  repository stays byte-for-byte intact and the new entry is written as
+  `aoci-<project>`, and a conflict on both keys is reported rather than
+  resolved. The status predicate scans every entry for one bound to the current
+  repository, so another repository's `aoci` never reads as installed here.
+  `--hooks` is inert for this host because it exposes no pre-write lifecycle
+  hook surface, and the managed `AGENTS.md` block is prepended for this host
+  alone, because that host injects only the first few thousand characters of the
+  file into model context and a trailing block is never read; every other host
+  keeps the existing append behavior, guarded by a regression test.
 - Fix the repair guidance for a mistyped or self-computed Code binding. Since
   rc16 the Maintain response no longer repeats `code_plan.candidates`, but the
   `code_candidate_source_sha256_mismatch`, `code_candidate_id_mismatch`, and

README.md

@@ -128,7 +128,7 @@ How long the first index takes depends on repository size. A normal integration
 
 - A verified release package or a checkout of the canonical AOCI-CODE source repository.
 - For source builds only: the Go toolchain declared by `go.mod`, `make`, and the other tools the repository requires.
-- A supported MCP host, such as Codex, Claude Code, Cursor, or OpenCode.
+- A supported MCP host, such as Codex, Claude Code, Cursor, OpenCode, or WorkBuddy.
 - Normal read and write access to the target repository.
 
 AOCI-CODE integrates with the MCP host, not with a model-provider API. DeepSeek
@@ -260,7 +260,7 @@ The index and the current managed source should converge back to `aligned`. If t
 "$AOCI" --repo . doctor
 ```
 
-To confirm which AOCI the host is actually connected to, read what the server reports about itself rather than what is on disk. In any `aoci_overview` `check_only` response or any `aoci_maintain` response, `cognition_receipt.mcp_service_version` is the running version and `runtime_repository_root` is the repository it governs. The matching binary path is the `command` in the project's `.mcp.json` or the equivalent host configuration: `.codex/config.toml`, `opencode.json`, or `.cursor/mcp.json`. Replacing bytes on disk does not change a running MCP process, so recheck against those facts after an upgrade or a rollback.
+To confirm which AOCI the host is actually connected to, read what the server reports about itself rather than what is on disk. In any `aoci_overview` `check_only` response or any `aoci_maintain` response, `cognition_receipt.mcp_service_version` is the running version and `runtime_repository_root` is the repository it governs. The matching binary path is the `command` in the project's `.mcp.json` or the equivalent host configuration: `.codex/config.toml`, `opencode.json`, `.cursor/mcp.json`, or the machine-level `~/.workbuddy/mcp.json`. Replacing bytes on disk does not change a running MCP process, so recheck against those facts after an upgrade or a rollback.
 
 For a one-off walkthrough, use `examples/minimal-repository` in the repository.
 
@@ -310,11 +310,15 @@ aoci.database.txt           Database: optional table-level entries; absent by de
 Initializing a new project creates the Root, Meta, and an empty Code Volume; Database is absent by default. AOCI-CODE does not generate business meaning for the repository or the database on its own.
 
 `aoci init --agent <name>` additionally writes host integration configuration
-(`.mcp.json`, `.claude/settings.json`, `.codex/config.toml`, or `opencode.json`)
-whose command and repository paths are machine-bound absolute paths. Add those
-files to the repository's `.gitignore` and do not commit them: a committed copy
-breaks on every other machine, and because the installers detect an existing
-entry by key presence, re-running `init` there silently keeps the broken paths.
+(`.mcp.json`, `.claude/settings.json`, `.codex/config.toml`, `opencode.json`, or
+the machine-level `~/.workbuddy/mcp.json`)
+whose command and repository paths are machine-bound absolute paths. Add the
+project-level ones to the repository's `.gitignore` and do not commit them: a
+committed copy breaks on every other machine, and because the installers detect
+an existing entry by key presence, re-running `init` there silently keeps the
+broken paths. The WorkBuddy file is machine-level rather than project-level, so
+it belongs to no repository and `init` writes nothing into the working tree for
+that host.
 
 ## How a development task runs
 
@@ -551,6 +555,7 @@ The Code Volume, the Database Volume, and scope can evolve together, but they sh
 - **Claude Code** can install a `PreToolUse` hook.
 - **OpenCode V1** gets a strict project-level `opencode.json`.
 - **Cursor** only returns a reference configuration snippet; nothing is written to the project.
+- **WorkBuddy** gets a merged entry in the machine-level `~/.workbuddy/mcp.json` and nothing in the repository. A foreign `aoci` key is never overwritten; the entry is written as `aoci-<project>` instead, and a conflict on both keys is reported rather than resolved. `--hooks` is inert because that host exposes no pre-write hook surface, and the managed agent block is placed at the top of `AGENTS.md` because this host injects only its first few thousand characters into model context.
 
 After configuration, check whether the current host session already exposes the AOCI tools. Refresh or reopen that project session only if it has not loaded the new server. A new session normally reads the rules and the Whole-Index once. While the index identity remains valid and no known host compaction has occurred, later tasks reuse what the model already has; the whole index is not injected again mechanically.
 
@@ -560,6 +565,7 @@ After configuration, check whether the current host session already exposes the
 | **Claude Code** | Project-level MCP; optional thin `PreToolUse` guard | The hook only provides a pre-write reminder or stale guard; it is not the agent runtime |
 | **OpenCode V1** | Strict project-root `opencode.json` via `--agent opencode` | Continue immediately if tools are loaded; otherwise refresh or reopen the project session |
 | **Cursor** | Returns an MCP reference configuration snippet | Does not write project configuration; you complete the integration manually for the host |
+| **WorkBuddy** | Merged entry in the machine-level `~/.workbuddy/mcp.json` via `--agent workbuddy` | Machine-level, not project-scoped: one file serves every project, and each repository needs its own entry (or its own server key). No pre-write hook surface, so `--hooks` does nothing here |
 | **Other MCP hosts** | Connect to the standard stdio server | Require manual configuration and host-specific validation |
 
 ```bash
@@ -568,6 +574,7 @@ aoci --repo /absolute/path/to/repository init --agent codex --hooks
 aoci --repo /absolute/path/to/repository init --agent claude --hooks
 aoci --repo /absolute/path/to/repository init --agent opencode
 aoci --repo /absolute/path/to/repository init --agent cursor
+aoci --repo /absolute/path/to/repository init --agent workbuddy
 ```
 
 Codex `--hooks` limits a compaction handoff to receipt identity, unfinished

README.zh-CN.md

@@ -121,7 +121,7 @@ Root、Meta 与参与其中的对象 Volume 共同组成当前 Whole-Index。在
 
 - 经验证的 Release 软件包，或 canonical AOCI-CODE 源码仓库的工作副本；
 - 从源码构建时，需要 `go.mod` 声明的 Go 工具链、`make` 及仓库要求的其他工具；使用已验证的 Release 二进制本身不需要 Go 或 `make`；
-- 一个受支持的 MCP 宿主，例如 Codex、Claude Code、Cursor 或 OpenCode；
+- 一个受支持的 MCP 宿主，例如 Codex、Claude Code、Cursor、OpenCode 或 WorkBuddy；
 - 对目标仓库的正常读写权限。
 
 AOCI-CODE 接入的是 MCP 宿主，不直接接入模型供应商 API。DeepSeek 等模型只有在承载它们的
@@ -250,7 +250,7 @@ Agent 会用 `aoci ui --detach --json` 在后台启动面板并把链接交给
 "$AOCI" --repo . doctor
 ```
 
-要确认宿主此刻真正连着哪一个 AOCI，看服务端自报的身份，而不是磁盘上的文件：任何 `aoci_overview` 的 `check_only` 响应、或任何 `aoci_maintain` 响应里，`cognition_receipt.mcp_service_version` 是正在运行的版本，`runtime_repository_root` 是它治理的仓库。对应的二进制路径是项目 `.mcp.json` 或等价宿主配置（`.codex/config.toml`、`opencode.json`、`.cursor/mcp.json`）里的 `command`。替换磁盘上的字节不会改变已在运行的 MCP 进程，因此升级或回滚后要按这些事实复核。
+要确认宿主此刻真正连着哪一个 AOCI，看服务端自报的身份，而不是磁盘上的文件：任何 `aoci_overview` 的 `check_only` 响应、或任何 `aoci_maintain` 响应里，`cognition_receipt.mcp_service_version` 是正在运行的版本，`runtime_repository_root` 是它治理的仓库。对应的二进制路径是项目 `.mcp.json` 或等价宿主配置（`.codex/config.toml`、`opencode.json`、`.cursor/mcp.json`，或机器级的 `~/.workbuddy/mcp.json`）里的 `command`。替换磁盘上的字节不会改变已在运行的 MCP 进程，因此升级或回滚后要按这些事实复核。
 
 如需一次性演练，可使用仓库中的 `examples/minimal-repository`。
 
@@ -299,7 +299,7 @@ aoci.database.txt           Database：可选的表级认知；默认不存在
 
 新项目初始化时会创建 Volume Root、Meta 和一个空的 Code Volume；Database 默认不存在。AOCI-CODE 不会自动生成仓库业务语义或 Database 语义。
 
-`aoci init --agent <name>` 还会写入宿主集成配置（`.mcp.json`、`.claude/settings.json`、`.codex/config.toml` 或 `opencode.json`），其中的命令与仓库路径是本机绑定的绝对路径。请把这些文件加入仓库的 `.gitignore` 且不要提交：提交后的副本在任何其他机器上都会失效，而安装器按条目是否存在做幂等判断，在那台机器上重跑 `init` 会静默保留坏路径。
+`aoci init --agent <name>` 还会写入宿主集成配置（`.mcp.json`、`.claude/settings.json`、`.codex/config.toml`、`opencode.json`，或机器级的 `~/.workbuddy/mcp.json`），其中的命令与仓库路径是本机绑定的绝对路径。请把**项目级**的那些文件加入仓库的 `.gitignore` 且不要提交：提交后的副本在任何其他机器上都会失效，而安装器按条目是否存在做幂等判断，在那台机器上重跑 `init` 会静默保留坏路径。WorkBuddy 的文件是机器级而非项目级，不属于任何仓库，`init` 为该宿主不往工作区写任何东西。
 
 
 ## 🔄 一次完整开发任务如何运行
@@ -533,14 +533,15 @@ Code Volume、Database Volume 和 Scope 可以共同演进，但它们共享同
 
 ## 🔌 宿主集成
 
-`aoci init` 始终写入托管的 AI Agent 规则，但宿主接入行为不同：Codex 写入项目级 MCP 配置，并可通过 `--hooks` 选择安装上下文压缩prompt与 `SessionStart(compact)`，但仍不安装文件编辑Hook；Claude Code 可以安装 `PreToolUse` Hook；OpenCode V1 使用严格的项目级 `opencode.json`；Cursor 只返回参考配置片段，不写入项目配置。配置完成后，先检查当前宿主会话是否已显示 AOCI 工具；仅在尚未加载新 server 时刷新或重新打开项目会话。新会话通常先读取一次 Rules 与 Whole-Index；只要认知身份仍有效且没有发生已知Host上下文压缩，后续任务会复用当前认知，不会机械地重复注入整个索引。
+`aoci init` 始终写入托管的 AI Agent 规则，但宿主接入行为不同：Codex 写入项目级 MCP 配置，并可通过 `--hooks` 选择安装上下文压缩prompt与 `SessionStart(compact)`，但仍不安装文件编辑Hook；Claude Code 可以安装 `PreToolUse` Hook；OpenCode V1 使用严格的项目级 `opencode.json`；Cursor 只返回参考配置片段，不写入项目配置；WorkBuddy 则合并写入机器级的 `~/.workbuddy/mcp.json`、不往仓库里写任何东西——该文件被所有项目共享而 server 硬绑 `--repo`，所以它**绝不覆盖**指向别的仓库的 `aoci` 键，而是改写 `aoci-<项目名>`，两个键名都被占用时报错交人工；该宿主没有写前 Hook 接口，故 `--hooks` 在此无效；又因它只把 `AGENTS.md` 开头一段注入模型上下文，`init` 会把托管区块放到该文件**最前面**（其它宿主仍保持文末追加）。配置完成后，先检查当前宿主会话是否已显示 AOCI 工具；仅在尚未加载新 server 时刷新或重新打开项目会话。新会话通常先读取一次 Rules 与 Whole-Index；只要认知身份仍有效且没有发生已知Host上下文压缩，后续任务会复用当前认知，不会机械地重复注入整个索引。
 
 | 宿主 | 当前接入方式 | 边界 |
 | --- | --- | --- |
 | **Codex** | 项目级 stdio MCP；可选 `--hooks` 压缩prompt与 `SessionStart(compact)` | 必须通过Codex `/hooks` 审查并信任；不安装文件编辑Hook |
 | **Claude Code** | 项目级 MCP；可选 `PreToolUse` 薄守卫 | Hook 只负责写前提示或 Stale 守卫，不是 AI Agent runtime |
 | **OpenCode V1** | 通过 `--agent opencode` 写入严格的项目根 `opencode.json` | 工具已加载可直接继续；否则刷新或重新打开项目会话 |
 | **Cursor** | 返回 MCP 参考配置片段 | 不写入项目配置，仍需按宿主手工完成接入 |
+| **WorkBuddy** | 通过 `--agent workbuddy` 合并写入机器级 `~/.workbuddy/mcp.json` | 机器级而非项目级：一份文件服务所有项目，每个仓库需要自己的条目（或自己的 server 键名）；该宿主没有写前 Hook 接口，`--hooks` 在此无效 |
 | **其他 MCP Host** | 连接标准 stdio Server | 需要手工配置并完成宿主专项验证 |
 
 ```bash
@@ -549,6 +550,7 @@ aoci --repo /absolute/path/to/repository init --agent codex --hooks
 aoci --repo /absolute/path/to/repository init --agent claude --hooks
 aoci --repo /absolute/path/to/repository init --agent opencode
 aoci --repo /absolute/path/to/repository init --agent cursor
+aoci --repo /absolute/path/to/repository init --agent workbuddy
 ```
 
 Codex `--hooks` 把压缩handoff限制为receipt身份、未完成write或Recovery状态，以及立即重载指令；不得保留或摘要Whole-Index或Overview/Attestation正文。`PreCompact` Hook不能向宿主压缩输入注入文本，也不能从中删除历史，因此无法单独落实该边界。依赖此能力前，应通过Codex `/hooks` 审查并信任安装的项目Hook。

docs/agent-integrations.md

@@ -11,11 +11,14 @@ session only when it has not loaded the new server; hosts that support dynamic
 MCP reload do not require a blanket application restart.
 
 The host configuration files written by `aoci init --agent` (`.mcp.json`,
-`.claude/settings.json`, `.codex/config.toml`, `opencode.json`) embed
-machine-bound absolute binary and repository paths, and must not be committed:
-a committed copy is broken on every other machine, and because each installer
-detects an existing entry by key presence, re-running `init` there silently
-keeps the broken paths.
+`.claude/settings.json`, `.codex/config.toml`, `opencode.json`,
+`~/.workbuddy/mcp.json`) embed machine-bound absolute binary and repository
+paths. Every project-level one must not be committed: a committed copy is broken
+on every other machine, and because each installer detects an existing entry by
+key presence, re-running `init` there silently keeps the broken paths.
+WorkBuddy's file is the exception that proves the rule: it is machine-level
+rather than project-level, so it never belongs to a repository, and `init`
+writes nothing into the working tree for that host.
 
 `init` adds the files it just wrote to the repository's `.gitignore` under its
 own marked block, so an ordinary `init` then `scan` leaves them out of Git and
@@ -170,6 +173,45 @@ Cursor version before adding it manually:
 
 This limitation must remain visible in compatibility claims; a reference template is not native-host validation.
 
+## WorkBuddy
+
+```bash
+aoci --repo /absolute/path/to/repository init --agent workbuddy
+```
+
+WorkBuddy has no project-scoped MCP configuration surface. Its only entry is the
+machine-level `~/.workbuddy/mcp.json`, so `init` merges an entry there and
+writes nothing into the repository: no Baseline path, no `.gitignore` line, and
+no host file for `git status` to report. The merged entry has the same shape
+every other stdio host uses:
+
+```json
+{
+  "mcpServers": {
+    "aoci": {
+      "command": "/absolute/path/to/aoci",
+      "args": ["--repo", "/absolute/path/to/repository", "mcp"]
+    }
+  }
+}
+```
+
+That file is shared by every project while an aoci server is bound to one
+`--repo`, so this installer never overwrites a foreign entry. When an `aoci`
+key already points at a different repository it writes `aoci-<project>` instead
+and leaves the existing entry byte-for-byte intact; when that scoped key is also
+taken by a third repository it reports the conflict and changes nothing.
+
+Two host facts shape the rest of the behavior:
+
+- No pre-write lifecycle hook surface exists, so `--hooks` is inert for this
+  host. The installer ignores it rather than pretending it installed a hook.
+- The host injects roughly the first 8000 characters of `AGENTS.md` into model
+  context, so a managed block appended at the end of that file is never read.
+  For this host alone, `init` places the managed block at the top of `AGENTS.md`;
+  every other host keeps the existing append behavior, and a file that already
+  carries the block still gets an in-place replacement that never moves it.
+
 ## Deterministic offline mode
 
 AI is disabled by default. To make that state explicit: