diff --git a/adapters/README.md b/adapters/README.md
index f4edce8c..08ba5338 100644
--- a/adapters/README.md
+++ b/adapters/README.md
@@ -10,7 +10,7 @@ file you need into your project and edit it.
 |---|---|---|
 | [claude-code/](claude-code/) | Anthropic's Claude Code CLI | `.mcp.json` snippet, `CLAUDE.md` excerpt |
 | [cursor/](cursor/) | Cursor IDE | `mcp.json` snippet |
-| [codex/](codex/) | OpenAI's Codex CLI | `config.toml` snippet |
+| [codex/](codex/) | OpenAI's Codex CLI | `.codex/config.toml`, `AGENTS.md` snippet |
 | [continue/](continue/) | Continue.dev | `config.json` snippet |
 | [openclaw/](openclaw/) | OpenClaw plugin host | `.openclaw/plugins.json`, `AGENTS.md` excerpt |
 | [generic-mcp/](generic-mcp/) | Any MCP-speaking host | annotated reference |
diff --git a/adapters/codex/README.md b/adapters/codex/README.md
index cfb324a4..cbe80424 100644
--- a/adapters/codex/README.md
+++ b/adapters/codex/README.md
@@ -4,10 +4,37 @@ Wires `vouch serve` into [OpenAI's Codex CLI][codex] as an MCP server.
 
 [codex]: https://github.com/openai/codex
 
-## Setup
+## Quick start
 
-Codex reads MCP server config from `~/.codex/config.toml`. Add a
-`vouch` entry:
+```bash
+vouch install-mcp codex
+```
+
+This writes a project-local `.codex/config.toml` (T1) and, at T2,
+appends a fenced snippet to `AGENTS.md` so Codex knows how to use the
+KB tools. Restart any running Codex session.
+
+## Tiers
+
+| Tier | What it adds | File |
+|---|---|---|
+| T1 | MCP wire — `vouch serve` as an MCP server | `.codex/config.toml` |
+| T2 | AGENTS.md snippet — standing instructions for recall, propose-don't-write, and the human review gate | `AGENTS.md` (fenced) |
+
+Install a specific tier:
+
+```bash
+vouch install-mcp codex --tier T1   # MCP config only
+vouch install-mcp codex --tier T2   # MCP config + AGENTS.md snippet
+```
+
+Re-running is idempotent: existing files are left alone, and an
+existing `AGENTS.md` fence is preserved without duplicating the block.
+
+## Manual setup
+
+If you prefer to edit the config by hand, add a `vouch` entry to
+`~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.vouch]
@@ -18,7 +45,9 @@ args = ["serve"]
 VOUCH_AGENT = "codex"
 ```
 
-Restart any running `codex` session.
+Or use the project-local form (what `vouch install-mcp codex --tier T1`
+writes) at `<project>/.codex/config.toml`. The project-local form is
+preferred because it doesn't touch home-directory state.
 
 ## Notes
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index bb9ac038..cd28caa5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -111,16 +111,24 @@ git add .vouch && git commit -m "kb: approve auth-uses-jwt"
 you need:
 
 ```bash
-claude mcp add vouch -- vouch serve    # or: codex mcp add vouch -- vouch serve
+claude mcp add vouch -- vouch serve    # Claude Code
+codex mcp add vouch -- vouch serve     # OpenAI Codex CLI
 ```
 
-Add `-e VOUCH_AGENT=claude-code` to attribute the agent's proposals to it
-rather than your shell user. Confirm with `claude mcp list` (look for
-`vouch … ✓ Connected`).
+Add `-e VOUCH_AGENT=claude-code` (or `VOUCH_AGENT=codex`) to attribute the
+agent's proposals to it rather than your shell user. Confirm with
+`claude mcp list` or `codex mcp list` (look for `vouch … ✓ Connected`).
 
-Prefer a config file, or want the brain-first `CLAUDE.md`, slash commands, and
-hooks too? Run `vouch install-mcp claude-code` — or drop this into `.mcp.json`
-at the project root by hand:
+Prefer a config file, or want the brain-first `CLAUDE.md`/`AGENTS.md`,
+slash commands, and hooks too? Run the installer for your host:
+
+```bash
+vouch install-mcp claude-code   # Claude Code
+vouch install-mcp codex         # OpenAI Codex CLI
+```
+
+Or drop the config in by hand — for Claude Code, put this into `.mcp.json`
+at the project root:
 
 ```json
 {