diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index e75a71f..b310ebf 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Parallel Codex workers inside Claude Code.",
-    "version": "0.5.0"
+    "version": "0.5.1"
   },
   "plugins": [
     {
       "name": "magic-codex",
       "source": "./plugin",
       "description": "Parallel Codex workers inside Claude Code — multi-agent orchestration with git worktree isolation, resumable sessions, and dual-model PR review.",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "author": {
         "name": "Wenqing Yu"
       },
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 302a2d5..d206dc4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,15 @@
 
 All notable changes documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.5.1] — 2026-04-29
+
+Docs-only release.
+
+### Changed
+- **Model recommendations refreshed for the mid-2026 codex lineup.** The 2025-era per-role split (`gpt-5.2-codex` for code, `gpt-5` for review, `o3` for planning) collapsed: `gpt-5.5` now handles all three workloads and the dial that matters is reasoning effort, configured via codex CLI profiles (`[profiles.coding]`, `[profiles.deep]`, `[profiles.fast]`). The README "Choosing models" section and `magic-codex.toml.example` now both lead with "leave model unset, configure your `~/.codex/config.toml`" and only show in-magic-codex pinning for the budget-capping case (e.g., `[roles.generic] model = "gpt-5-codex-mini"`).
+- **`magic-codex.toml.example` filename bug fixed.** Header comments referenced the wrong file (`codex-team.toml`); the actual loader reads `magic-codex.toml`. Corrected.
+- **README role table** corrected to show implementer's `danger-full-access` default (was still showing `workspace-write` from before the 0.4.0 switch).
+
 ## [0.5.0] — 2026-04-28
 
 ### Added
diff --git a/README.md b/README.md
index 0425211..557044c 100644
--- a/README.md
+++ b/README.md
@@ -192,33 +192,61 @@ Built-in presets (`src/roles/defaults/`):
 
 | Role | Sandbox | Worktree | Timeout |
 |---|---|---|---|
-| `implementer` | `workspace-write` | branch-per-agent | 30 min |
+| `implementer` | `danger-full-access` | branch-per-agent | 30 min |
 | `reviewer` | `read-only` | detached at PR head (when `pr_number` given) | 10 min |
 | `planner` | `read-only` | none | 15 min |
 | `generic` | `read-only` | none | 15 min |
 
-**Model selection.** By default, each role inherits whatever model your `~/.codex/config.toml` selects. Override per-role or per-spawn:
+> Implementer's `danger-full-access` default landed in 0.4.0. `workspace-write` empirically dropped `.git/worktrees/<id>/index.lock` writes for ~33-67% of macOS spawns even with the writable_roots workaround. The agent is already isolated to a throwaway worktree branch, so `danger-full-access` is the smaller blast radius. Override via `[roles.implementer] sandbox = "workspace-write"` if you need stricter network egress isolation; the lock denials will still happen but 0.4.1's silent-failure detection surfaces them as `failed/kind=sandbox_denied` instead of a misleading `completed`.
+
+### Choosing models
+
+**The per-role model split that was useful in 2025 collapsed in 2026.** `gpt-5.5` (with `gpt-5.4` as a fallback during rollout) is now the unified top model for implementation, review, and planning. The dial that matters is **reasoning effort**, configured via codex CLI profiles — not via magic-codex.
+
+**Recommended approach:** leave `model` unset on every role in `magic-codex.toml` and let codex inherit your `~/.codex/config.toml` defaults + profiles.
+
+A solid codex baseline:
 
 ```toml
-# magic-codex.toml
-[roles.implementer]
-model = "gpt-5-codex"        # or whatever Codex accepts
+# ~/.codex/config.toml
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+service_tier = "fast"
+review_model = "gpt-5.5"
+
+[profiles.coding]   # daily work
+model_reasoning_effort = "high"
+
+[profiles.deep]     # hard reviews / planning / refactors
+model_reasoning_effort = "xhigh"
+web_search = "live"
+
+[profiles.fast]     # cheap iteration
+model = "gpt-5-codex-mini"
+model_reasoning_effort = "medium"
+```
 
-[roles.reviewer]
-model = "gpt-5"              # strong reasoning for dual-review
-timeout_seconds = 900
+Switch profiles with `codex --profile <name>` at the codex CLI level. magic-codex passes through to the codex MCP server, which honors your codex config — no magic-codex changes needed when you adjust profiles.
+
+**When to pin a model in `magic-codex.toml`:** only when you want a role to diverge from your codex default. The most common case is budget-capping the `generic` role:
+
+```toml
+[roles.generic]
+model = "gpt-5-codex-mini"   # cheap for repetitive work
 ```
 
-Per-spawn override:
+Per-spawn overrides remain available:
 
 ```json
 {
   "role": "reviewer",
   "prompt": "...",
-  "overrides": { "model": "gpt-5", "timeout_seconds": 1200 }
+  "overrides": { "model": "gpt-5.5", "timeout_seconds": 1200 }
 }
 ```
 
+See `magic-codex.toml.example` for a copy-paste starter and a richer set of profile recommendations.
+
 ---
 
 ## PR review flow
diff --git a/magic-codex.toml.example b/magic-codex.toml.example
index 782bed1..4dfd074 100644
--- a/magic-codex.toml.example
+++ b/magic-codex.toml.example
@@ -1,6 +1,6 @@
-# magic-cc-codex-worker — project config
-# Copy to `codex-team.toml` at your repo root (commit it for team-wide conventions).
-# Per-user overrides live at `~/.codex-team/config.toml`.
+# magic-codex — project config
+# Copy to `magic-codex.toml` at your repo root (commit it for team-wide conventions).
+# Per-user overrides live at `~/.magic-codex/config.toml` (not committed).
 
 # --- Delegation policy ---
 # How aggressively should Claude offload work to Codex?
@@ -8,18 +8,54 @@
 [delegation]
 level = "balance"
 
-# --- Role overrides ---
-# Only specified fields override the built-in defaults.
-# See src/roles/defaults/*.toml for the full defaults.
+# --- Models ---
+# Recommended approach (mid-2026): leave magic-codex's `model` field
+# UNSET on every role and let codex inherit your `~/.codex/config.toml`
+# defaults + profiles. magic-codex passes through to the codex MCP
+# server, which already honors your codex global config.
+#
+# A solid `~/.codex/config.toml` baseline looks like this:
+#
+#   model = "gpt-5.5"                        # gpt-5.4 as fallback during rollout
+#   model_reasoning_effort = "high"
+#   model_reasoning_summary = "concise"
+#   service_tier = "fast"
+#   review_model = "gpt-5.5"                 # used by codex's /review
+#   web_search = "cached"
+#
+#   [profiles.coding]   model_reasoning_effort = "high"   # daily work
+#   [profiles.deep]     model_reasoning_effort = "xhigh"  # hard reviews / planning
+#   [profiles.fast]     model = "gpt-5-codex-mini"        # cheap iteration
+#
+# Switch profiles via `codex --profile <name>` at the codex CLI level.
+# magic-codex doesn't currently surface a per-spawn `profile` field, so
+# the codex global config is where reasoning-depth / web-search /
+# service-tier knobs live.
+#
+# WHEN TO PIN A MODEL IN magic-codex.toml: only when you want a role to
+# diverge from your codex default — e.g., budget-cap the `generic` role
+# to `gpt-5-codex-mini` while implementer/reviewer/planner ride the
+# stronger default.
 
 # [roles.implementer]
-# model = "gpt-5-codex"         # override to pin a specific Codex model
+# # Inherit codex default (gpt-5.5 + your `coding` profile reasoning depth).
+# # Pin only if you want a different model than your codex global.
+# # model = "gpt-5.5"
 # timeout_seconds = 1800
-# sandbox = "workspace-write"
+# sandbox = "danger-full-access"   # default since 0.4.0; see CHANGELOG
 
 # [roles.reviewer]
-# model = "gpt-5"               # force a strong reasoning model for dual-review
+# # Same as implementer — inherit. If you have a `deep` codex profile
+# # configured, you'd switch to it via `codex --profile deep` rather
+# # than overriding here.
+# # model = "gpt-5.5"
 # timeout_seconds = 900
 
 # [roles.planner]
-# model = "gpt-5"
+# # Inherit. Pair with codex `deep` profile for complex decomposition.
+# # model = "gpt-5.5"
+# timeout_seconds = 1200
+
+# [roles.generic]
+# # Cheap path for trivial repetitive work. Pin to mini to budget-cap.
+# # model = "gpt-5-codex-mini"
diff --git a/package.json b/package.json
index 88535de..e958380 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "magic-cc-codex-worker",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Parallel Codex workers inside Claude Code — multi-agent orchestration.",
   "private": true,
   "license": "SEE LICENSE IN LICENSE",
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
index aa5648f..828ad5d 100644
--- a/plugin/.claude-plugin/plugin.json
+++ b/plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "magic-codex",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Parallel Codex workers inside Claude Code — multi-agent orchestration with git worktree isolation, resumable sessions, and dual-model PR review.",
   "author": {
     "name": "Wenqing Yu",
diff --git a/plugin/dist/index.js b/plugin/dist/index.js
index 2da1f69..71e4823 100755
--- a/plugin/dist/index.js
+++ b/plugin/dist/index.js
@@ -27716,7 +27716,7 @@ var CodexChild = class {
       stderr: "pipe"
     });
     this.client = new Client(
-      { name: "magic-codex", version: "0.5.0" },
+      { name: "magic-codex", version: "0.5.1" },
       { capabilities: {} }
     );
     await this.client.connect(this.transport);
@@ -28278,7 +28278,7 @@ async function main() {
     mfConventions
   });
   const server = new Server(
-    { name: "magic-codex", version: "0.5.0" },
+    { name: "magic-codex", version: "0.5.1" },
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
diff --git a/src/index.ts b/src/index.ts
index 780f8b0..cdf22f5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -182,7 +182,7 @@ async function main() {
   });
 
   const server = new Server(
-    { name: "magic-codex", version: "0.5.0" },
+    { name: "magic-codex", version: "0.5.1" },
     { capabilities: { tools: {} } },
   );
 
diff --git a/src/mcp/codex-client.ts b/src/mcp/codex-client.ts
index 132d0f4..28f8284 100644
--- a/src/mcp/codex-client.ts
+++ b/src/mcp/codex-client.ts
@@ -52,7 +52,7 @@ export class CodexChild {
       stderr: "pipe",
     });
     this.client = new Client(
-      { name: "magic-codex", version: "0.5.0" },
+      { name: "magic-codex", version: "0.5.1" },
       { capabilities: {} },
     );
     await this.client.connect(this.transport);