docs: clarify codex mcp install syntax

Author: CharlieGreenman

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to `state-trace` are documented here. The format roughly fol
 
 ## [Unreleased]
 
+### Changed
+
+- Clarified MCP install docs to mirror Geometra's per-client syntax, with explicit Codex project-level, global, and uninstall commands.
+
 ## [0.3.3] — 2026-04-25
 
 ### Added

README.md

@@ -204,15 +204,6 @@ python3 -m pip install --upgrade "state-trace[mcp]"
 state-trace-mcp
 ```
 
-For project-scoped MCP installs, generate a local `.mcp.json` from the installed package. The generated config uses an absolute `state-trace-mcp` path so clients with a minimal PATH can still start it.
-
-```bash
-cd /path/to/your/repo
-state-trace-mcp-config --namespace "$(basename "$PWD")" > .mcp.json
-# If your shell cannot find the console script:
-python3 -m state_trace.mcp_config --namespace "$(basename "$PWD")" > .mcp.json
-```
-
 Environment config:
 
 - `STATE_TRACE_STORAGE_PATH` — durable path; `.db`/`.sqlite` uses the SQLite backend. Default: `~/.state-trace/memory.db`.
@@ -221,19 +212,26 @@ Environment config:
 
 Tools exposed: `store`, `retrieve`, `retrieve_brief`, `record_action`, `record_observation`, `record_test_result`, `ingest_agent_log_file`, `current_state`, `failed_hypotheses`, `list_namespaces`, `graph_snapshot`.
 
-### OpenAI Codex
+### Install
+
+<details>
+<summary>OpenAI Codex</summary>
 
-Recommended per-repo install:
+**Project-level install (recommended, one repo at a time):**
 
 ```bash
 python3 -m pip install --upgrade "state-trace[mcp]"
 cd /path/to/your/repo
 state-trace-mcp-config --namespace "$(basename "$PWD")" > .mcp.json
-# If your shell cannot find the console script:
+```
+
+If your shell cannot find `state-trace-mcp-config`:
+
+```bash
 python3 -m state_trace.mcp_config --namespace "$(basename "$PWD")" > .mcp.json
 ```
 
-Manual project-level `.mcp.json`:
+Or manually add to `.mcp.json` in the repo:
 
 ```json
 {
@@ -252,48 +250,109 @@ Manual project-level `.mcp.json`:
 
 Restart Codex after adding or changing `.mcp.json`.
 
-Codex also supports global MCP config:
+**Global install:**
 
 ```bash
-STATE_TRACE_MCP="$(python3 -c 'from state_trace.mcp_config import resolve_entrypoint; print(resolve_entrypoint())')"
+python3 -m pip install --upgrade "state-trace[mcp]"
 codex mcp add state-trace \
   --env STATE_TRACE_NAMESPACE=repo-x \
-  --env STATE_TRACE_STORAGE_PATH=/Users/me/.state-trace/repo-x.db \
-  -- "$STATE_TRACE_MCP"
+  --env STATE_TRACE_STORAGE_PATH="$HOME/.state-trace/repo-x.db" \
+  -- "$(python3 -c 'from state_trace.mcp_config import resolve_entrypoint; print(resolve_entrypoint())')"
 ```
 
-Use the project `.mcp.json` path when you want state-trace mounted one repo at a time.
+**Uninstall:**
 
-### Claude Code
+```bash
+codex mcp remove state-trace
+```
 
-Project-level `.mcp.json` is the same as Codex. For a global install:
+For project-level installs, remove the `state-trace` entry from `.mcp.json`.
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+**One-line install:**
 
 ```bash
+python3 -m pip install --upgrade "state-trace[mcp]"
 claude mcp add state-trace -- state-trace-mcp
 ```
 
-To uninstall:
+Or manually add to `.mcp.json` (project-level) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "state-trace": {
+      "command": "/absolute/path/to/state-trace-mcp",
+      "env": {
+        "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/repo-x.db",
+        "STATE_TRACE_NAMESPACE": "repo-x",
+        "STATE_TRACE_CAPACITY_LIMIT": "256"
+      }
+    }
+  }
+}
+```
+
+**Uninstall:**
 
 ```bash
 claude mcp remove state-trace
 ```
 
-### Cursor
+To uninstall manually, remove the `state-trace` entry from the config file.
+
+</details>
+
+<details>
+<summary>Cursor</summary>
 
 Open Settings → MCP → Add new MCP server, or add the same `mcpServers.state-trace` entry to `.cursor/mcp.json`.
 
-### Other MCP clients
+```json
+{
+  "mcpServers": {
+    "state-trace": {
+      "command": "/absolute/path/to/state-trace-mcp",
+      "env": {
+        "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/repo-x.db",
+        "STATE_TRACE_NAMESPACE": "repo-x",
+        "STATE_TRACE_CAPACITY_LIMIT": "256"
+      }
+    }
+  }
+}
+```
+
+To uninstall, remove the entry from MCP settings.
+
+</details>
+
+<details>
+<summary>Other MCP clients</summary>
 
 Any MCP client that supports stdio transport can run:
 
 ```json
 {
-  "command": "/absolute/path/to/state-trace-mcp"
+  "command": "/absolute/path/to/state-trace-mcp",
+  "env": {
+    "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/repo-x.db",
+    "STATE_TRACE_NAMESPACE": "repo-x",
+    "STATE_TRACE_CAPACITY_LIMIT": "256"
+  }
 }
 ```
 
 Use `python3 -m state_trace.mcp_config` to print a complete config with storage, namespace, and capacity env vars.
 
+To uninstall, remove the server entry from your client's MCP configuration.
+
+</details>
+
 ## Online agent loop
 
 ```python