diff --git a/README.md b/README.md
index 422a6de..1bd33db 100644
--- a/README.md
+++ b/README.md
@@ -17,25 +17,15 @@ through an external AI model (currently OpenAI Codex).
 
 ## Key features
 
-**Two stages** — works on both planning and implementation:
 - **Plan review** — review the plan BEFORE writing code. Catch architecture
   mistakes, missing steps, and risks early
 - **Code review** — review the implementation. Bugs, security, data loss
 - **Code-vs-plan** — verify the implementation matches the plan
-
-**Lightweight** — one file, no server, no broker, no dependencies beyond
-the reviewer CLI. Compare with [codex-plugin-cc](https://github.com/openai/codex-plugin-cc):
-~15 JS modules, App Server, JSON-RPC broker, lifecycle hooks.
-This skill is a text instruction that any AI agent can interpret.
-
-**Iterative** — Claude doesn't just show the review and stop.
-It actively fixes issues based on reviewer feedback and resubmits
-for re-review. Up to 5 rounds until approved.
-
-**Designed for extensibility** — the skill relies on basic agent capabilities:
-run a command, read a file, edit a file. The prompts and review workflow
-are model-agnostic. Currently uses OpenAI Codex as the reviewer;
-adding other backends (Gemini, local models) is on the roadmap.
+- **Iterative** — Claude fixes issues based on reviewer feedback and resubmits
+  for re-review. Up to 5 rounds until approved
+- **Lightweight** — one `SKILL.md` file, no server, no broker. Compare with
+  [codex-plugin-cc](https://github.com/openai/codex-plugin-cc):
+  ~15 JS modules, App Server, JSON-RPC broker, lifecycle hooks
 
 ## How it works
 
@@ -63,104 +53,168 @@ adding other backends (Gemini, local models) is on the roadmap.
 
 Mode is auto-detected from context, or you can force it with an argument.
 
-## Installation
+## Quick start
 
-### Requirements
+### 1. Prerequisites
 
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- [OpenAI Codex CLI](https://github.com/openai/codex): `npm install -g @openai/codex`
-- OpenAI API key (`OPENAI_API_KEY` environment variable)
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) and
+[OpenAI Codex CLI](https://github.com/openai/codex) must be installed.
 
-### Setup
+Verify both are available:
 
 ```bash
-# Clone the repository
-git clone https://github.com/<your-username>/adversarial-review.git
+claude --version   # Claude Code CLI
+codex --version    # OpenAI Codex CLI (>= 0.115.0)
+```
 
-# Symlink into Claude Code skills directory
+If Codex is missing: `npm install -g @openai/codex`
+
+**Authentication.** Codex needs an OpenAI account. Either:
+- Sign in interactively: `codex` (opens browser)
+- Or set `CODEX_API_KEY` env var for non-interactive use
+
+### 2. Install the skill
+
+```bash
+git clone https://github.com/dementev-dev/adversarial-review.git
 ln -s "$(pwd)/adversarial-review" ~/.agents/skills/adversarial-review
 ```
 
-After symlinking, the skill is available as `/adversarial-review` in Claude Code.
+Verify the skill is visible to Claude Code:
 
-### Recommended permissions
+```bash
+ls -la ~/.agents/skills/adversarial-review/SKILL.md
+```
 
-The skill runs git, codex, and `/tmp` write commands that will trigger
-permission prompts. To avoid repeated confirmations, add these to your
-`.claude/settings.local.json`:
+### 3. Add permissions
 
-```json
+The skill runs `git`, `codex exec`, and writes temp files to `/tmp`.
+Without pre-approved permissions, Claude Code will prompt for each action.
+
+**Where to add.** Since the skill is installed globally
+(`~/.agents/skills/`), permissions should go into the global config
+so they work in any project:
+
+| Install scope | Config file |
+|---------------|-------------|
+| Global (recommended) | `~/.claude/settings.json` |
+| Single project | `<project>/.claude/settings.local.json` |
+
+Merge the following rules into the `permissions.allow` array of the
+chosen config file:
+
+```jsonc
+// --- adversarial-review permissions ---
+// Git: diff, status, branch detection
+"Bash(git diff*)",
+"Bash(git status*)",
+"Bash(git symbolic-ref*)",
+"Bash(git rev-parse*)",
+// Codex: review execution (always wrapped in timeout)
+"Bash(timeout 600 codex exec *)",
+// Temp files: prompts, plans, output capture
+"Write(/tmp/codex-plan-*)",
+"Write(/tmp/codex-prompt-*)",
+"Read(/tmp/codex-review-*)",
+"Read(/tmp/codex-stderr-*)",
+// Cleanup and output piping
+"Bash(rm -f /tmp/codex-*)",
+"Bash(tee *)"
+```
+
+<details>
+<summary>Full example (if the config file is empty or does not exist)</summary>
+
+```jsonc
 {
   "permissions": {
     "allow": [
+      // adversarial-review
       "Bash(git diff*)",
       "Bash(git status*)",
       "Bash(git symbolic-ref*)",
       "Bash(git rev-parse*)",
       "Bash(timeout 600 codex exec *)",
       "Write(/tmp/codex-plan-*)",
-      "Write(/tmp/codex-prompt-*)"
+      "Write(/tmp/codex-prompt-*)",
+      "Read(/tmp/codex-review-*)",
+      "Read(/tmp/codex-stderr-*)",
+      "Bash(rm -f /tmp/codex-*)",
+      "Bash(tee *)"
     ]
   }
 }
 ```
 
-**Note:** The `codex exec` rule allows any `codex exec` invocation wrapped
-in `timeout 600`. The skill only uses read-only mode (`-s read-only`), but
-Claude Code's permission patterns are prefix-based and cannot enforce flag
+</details>
+
+**Security note:** The `codex exec` rule allows any `codex exec` invocation
+wrapped in `timeout 600`. The skill only uses read-only mode (`-s read-only`),
+but Claude Code's permission patterns are prefix-based and cannot enforce flag
 constraints. If you prefer tighter control, omit the `codex exec` rule and
-approve each review invocation manually.
+approve each invocation manually.
 
-## Usage
+### 4. Use
 
-```
-# Auto-detect what to review
-/adversarial-review
-
-# Review a plan
-/adversarial-review plan
-
-# Review code changes
-/adversarial-review code
-
-# Review a specific file
-/adversarial-review path/to/plan.md
-
-# Use higher reasoning effort
-/adversarial-review xhigh
-
-# Use a different model
-/adversarial-review model:gpt-5.3-codex
+```bash
+/adversarial-review                       # auto-detect mode
+/adversarial-review plan                  # force plan review
+/adversarial-review code                  # force code review
+/adversarial-review path/to/f             # review a specific file
+/adversarial-review xhigh                 # higher reasoning effort
+/adversarial-review model:gpt-5.3-codex   # use a different model
 ```
 
 ## Prompt architecture
 
-The skill uses XML-structured prompts inspired by adversarial review methodology:
+The skill uses XML-structured prompts with adversarial stance:
 
 - **`<role>`** — adversarial reviewer, defaults to skepticism
 - **`<operating_stance>`** — break confidence, not validate
 - **`<attack_surface>`** — concrete checklist: auth, data integrity,
   race conditions, rollback safety, schema drift, error handling, observability
 - **`<finding_bar>`** — every finding must answer 4 questions:
-  what can go wrong, why this code is vulnerable, impact, recommendation
+  what can go wrong, why vulnerable, impact, recommendation
 - **`<scope_exclusions>`** — no style, naming, or speculative comments
 - **`<calibration>`** — one strong finding > five weak ones
 
 ## Example output
 
-See [examples/review-output.md](examples/review-output.md) for a sample
-adversarial review output.
+See [examples/review-output.md](examples/review-output.md) for a sample review.
+
+## Troubleshooting
+
+**`codex exec` exits with model error.**
+Some models are unavailable with ChatGPT accounts (e.g. `o3-mini`).
+The default `gpt-5.4` works with both ChatGPT and API key auth.
+Override with `/adversarial-review model:<name>`.
+
+**Permission prompts on every action.**
+Add the permissions from the [setup section](#3-add-permissions). Check that
+the file is valid JSON and in the right location (project `.claude/settings.local.json`
+or global `~/.claude/settings.json`).
+
+**Codex hangs / timeout (exit code 124).**
+All `codex exec` calls are wrapped in `timeout 600` (10 minutes). If you see
+exit code 124, the reviewer did not respond in time. Retry — this is usually
+transient.
+
+**Resume fails with session error.**
+The skill uses `codex exec resume <session-id>` for rounds 2+. If the session
+expired or the ID was not captured, the skill falls back to a fresh `codex exec`
+automatically. No action needed.
+
+**Plan Mode exits when writing temp files.**
+In Claude Code Plan Mode, writing to `/tmp` may trigger a permission prompt
+or exit Plan Mode. This is a known Claude Code limitation. It does not affect
+review correctness.
 
 ## Known limitations
 
-- **Plan Mode and `/tmp` writes.** In Claude Code Plan Mode, writing review
-  prompts to `/tmp` may trigger a permission prompt or cause Plan Mode to exit.
-  This does not affect review correctness — the review mode is already determined,
-  and only the plan file and temp files are modified.
-- **`resume` inherits sandbox.** The `codex exec resume` command does not accept
-  `-s` (sandbox) — sandbox is inherited from the original session. The first
-  `codex exec` call sets the sandbox to `read-only`, and all subsequent resume
-  rounds use the same setting.
+- **Plan Mode and `/tmp` writes.** Writing review prompts to `/tmp` may trigger
+  a permission prompt or cause Plan Mode to exit. Does not affect review correctness.
+- **`resume` inherits sandbox.** `codex exec resume` does not accept `-s` —
+  sandbox is inherited from the original session (always `read-only`).
 
 ## Roadmap
 
@@ -171,21 +225,16 @@ adversarial review output.
 
 ## Inspiration
 
-The adversarial prompt structure was developed after studying
-[openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0)
-— the official OpenAI plugin for code review with Codex in Claude Code.
+Adversarial prompt structure developed after studying
+[openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0).
 
-What we borrowed as ideas:
-- XML-structured prompts (`<role>`, `<operating_stance>`, `<attack_surface>`, etc.)
-- Adversarial stance: "break confidence, not validate"
-- Attack surface checklist approach
-- Finding bar: 4 questions each finding must answer
-- Calibration rules: prefer strong findings over weak ones
+Borrowed ideas: XML-structured prompts, adversarial stance, attack surface
+checklist, finding bar, calibration rules.
 
 What we did differently:
-- **Iterative loop** — Claude actively fixes issues and resubmits (vs "stop and ask user")
+- **Iterative loop** — Claude fixes issues and resubmits (not "stop and ask user")
 - **Plan review** — reviews plans before code, not just code
-- **Single file** — one SKILL.md vs 15+ JS modules with App Server
+- **Single file** — one SKILL.md vs 15+ JS modules
 - **Verbatim output** — reviewer findings shown as-is, not rephrased
 
 ## License