diff --git a/.gitignore b/.gitignore
index 751e548..1d836c1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,6 @@ deps/
 
 # Test output captured during local test runs
 test_output.log
+
+# Generated vimdoc tags (plugin managers regenerate via :helptags)
+doc/tags
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..b6acb01
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,86 @@
+# Contributing to code-preview.nvim
+
+Thanks for helping out! This document covers how the plugin is built and how to run the tests.
+
+Before diving in, two pointers to the canonical sources of truth:
+
+- **[CONTEXT.md](CONTEXT.md)** — the glossary. The vocabulary the codebase is written in (*agent*, *proposal*, *preview*, *integration*, *hook entry*, *core handler*, *change*, …). Prefer these terms over synonyms in commits, issues, tests, and code.
+- **[docs/adr/](docs/adr/)** — Architecture Decision Records. The *why* behind the structure below (in-process core handler, one hook entry per OS, forced review gate, origin-prefixed statuses, …). When this doc and an ADR disagree, the ADR wins — and please update this doc.
+
+---
+
+## How it works (internals)
+
+An **agent** is an external AI coding CLI (Claude Code, OpenCode, Codex CLI, GitHub Copilot CLI) that proposes file edits and asks for permission before applying them. Each agent fires a hook on every **proposal** (one pre-tool firing — an Edit / Write / MultiEdit / ApplyPatch / Bash). code-preview intercepts that hook, renders a **preview** (the per-file diff you open and review), and tears it down once the agent reports the proposal is done.
+
+The pipeline, end to end:
+
+1. **Hook entry** — `bin/hook-entry.{sh,ps1}`. One generic shim *per OS*, shared by every agent, invoked as `hook-entry <agent> <pre|post>` (`.sh` on Unix, `.ps1` on Windows — see [ADR-0008](docs/adr/0008-one-hook-entry-per-os.md)). It takes the agent's native payload, optionally fast-path-filters noisy tools, performs **socket discovery** to find the running Neovim, and makes a single RPC call into the core handler.
+
+2. **RPC transport** — `bin/nvim-call.{sh,ps1}` (caller) and `lua/code-preview/rpc.lua` (dispatcher). Args are written to a JSON tempfile, then `luaeval` invokes the named module function with the decoded args. The dispatcher is the *only* place user-controlled data crosses the shell→Lua boundary, and it never enters a Lua source string.
+
+3. **Core handler** — `lua/code-preview/pre_tool/init.lua` and `lua/code-preview/post_tool.lua`. The agent-neutral pipeline that runs **in-process** inside the user's Neovim ([ADR-0005](docs/adr/0005-core-handler-runs-in-process.md)). It normalises the proposal, decides whether to show a preview (`visible_only` gating, shell-write detection), computes original/proposed content, and drives the diff. This is where everything that *doesn't* depend on which agent fired lives — including `permissionDecision` emission for Claude Code's [review gate](CONTEXT.md#review-gate).
+
+4. **Preview rendering** — `lua/code-preview/diff.lua`. `show_diff()` / `close_diff()`, plus layout resolution (`tab` / `vsplit` share the side-by-side renderer; `inline` is the unified-diff renderer that's the strategic direction, see [ADR-0003](docs/adr/0003-inline-renderer-as-future-default.md)).
+
+An **integration** is the per-agent adapter: an **installer** (`lua/code-preview/backends/<agent>.lua`) that wires the agent's config files to point at the hook entry, plus — for agents that need in-agent glue — adapter code. Only **OpenCode** needs the latter: a TypeScript plugin under `backends/opencode/` that bridges OpenCode's `tool.execute.before/after` API to the shared hook entry. Claude Code, Copilot CLI, and Codex have no `backends/<agent>/` directory — their installers point the agent's native shell-hook config straight at `bin/hook-entry`.
+
+> **Note:** the directory `backends/` and the env var `CODE_PREVIEW_BACKEND` are historical names for what CONTEXT.md now calls an *agent*. Don't rename them, but say "agent" in new code and docs.
+
+---
+
+## Architecture
+
+```
+lua/code-preview/
+├── init.lua             setup(), config, user commands
+├── diff.lua             preview rendering: show_diff(), close_diff(), layouts
+├── rpc.lua              RPC dispatcher — the shell→Lua boundary
+├── pidfile.lua          per-Neovim pidfile for socket discovery
+├── platform.lua         per-OS hook-command construction
+├── changes.lua          change-status registry (modified/created/deleted/bash_*)
+├── neo_tree.lua         neo-tree integration (indicators, virtual nodes, reveal)
+├── health.lua           :checkhealth code-preview
+├── log.lua              opt-in debug logging
+├── pre_tool/            in-process core handler (pre-tool side)
+│   ├── init.lua           orchestration: normalise proposal → decide preview
+│   ├── normalisers.lua    per-agent tool payload → canonical proposal
+│   ├── emitters.lua       build the RPC/permission responses
+│   └── shell_detect.lua   Tier-1 Bash write detection (redirects, mv, sed -i, …)
+├── post_tool.lua        in-process core handler (post-tool side): close previews
+├── apply/               in-process edit transformers (edit / multi_edit / patch)
+└── backends/            per-agent installers (claudecode, opencode, copilot, codex)
+
+bin/                     scripts the agent invokes + headless workers
+├── hook-entry.{sh,ps1}  generic per-OS hook entry: hook-entry <agent> <pre|post>
+├── nvim-socket.{sh,ps1}  socket discovery (pidfile + per-OS fallbacks)
+├── nvim-call.{sh,ps1}    RPC caller (JSON args tempfile → luaeval into dispatcher)
+├── apply-edit.lua        headless worker: Edit proposal → proposed content
+├── apply-multi-edit.lua  headless worker: MultiEdit
+└── apply-patch.lua       headless worker: ApplyPatch (custom patch format)
+
+backends/
+└── opencode/            OpenCode TS plugin — the only agent needing in-agent glue
+    ├── index.ts           tool.execute.before/after → hook-entry
+    ├── package.json
+    └── tsconfig.json
+```
+
+A **headless worker** is a short-lived `nvim --headless -l <script>.lua` that transforms data *outside* the user's Neovim — no UI, no access to `M.config` or open buffers. The `bin/apply-*.lua` scripts are the canonical examples; the orchestration around them lives in the in-process core handler ([ADR-0005](docs/adr/0005-core-handler-runs-in-process.md)).
+
+---
+
+## Testing
+
+Tests use [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for the core plugin and shell scripts for per-agent integration. CI runs on Ubuntu and macOS.
+
+```bash
+./tests/run.sh                     # all tests (plugin + backends)
+./tests/run.sh plugin              # core plugin tests only (plenary busted)
+./tests/run.sh backends            # all per-agent integration tests
+./tests/run.sh backends/claudecode # one agent (claudecode|opencode|copilot|codex)
+```
+
+**Dependencies:** Neovim >= 0.10, jq, bun (for OpenCode tests). Plenary auto-installs to `deps/` on first run.
+
+> **Dogfooding note:** this repo installs code-preview's own hooks (`.claude/settings.local.json`), so edits made by an agent inside this project trigger live previews. After changing plugin code, restart Neovim before testing — the running instance won't pick up the new code otherwise (see `CLAUDE.md`).
diff --git a/README.md b/README.md
index 3e5c806..e95c4ed 100644
--- a/README.md
+++ b/README.md
@@ -1,81 +1,63 @@
-# code-preview.nvim
-
-A Neovim plugin that shows a **diff preview before your AI coding agent applies any file change** — letting you review exactly what's changing before accepting.
+<div align="center">
 
-Supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [GitHub Copilot CLI](https://github.com/github/copilot-cli), and [OpenAI Codex CLI](https://github.com/openai/codex) as backends.
+<img src="assets/logo.svg" alt="code-preview.nvim logo" width="128">
 
----
+# code-preview.nvim
 
-## Demo
+**Review every edit your AI coding agent makes as a native Neovim diff — before it's written to disk.**
 
-### Claude Code
-![Claude Code demo](docs/code-preview-claudecode.gif)
+[![CI](https://github.com/Cannon07/code-preview.nvim/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/Cannon07/code-preview.nvim/actions/workflows/e2e-tests.yml)
+[![Release](https://img.shields.io/github/v/release/Cannon07/code-preview.nvim?label=release)](https://github.com/Cannon07/code-preview.nvim/releases)
+[![Neovim](https://img.shields.io/badge/Neovim-0.10%2B-57A143?logo=neovim&logoColor=white)](https://neovim.io)
+[![License: MIT](https://img.shields.io/github/license/Cannon07/code-preview.nvim)](LICENSE)
 
-### OpenCode
-![OpenCode demo](docs/code-preview-opencode.gif)
+Works with **Claude Code**, **OpenCode**, **GitHub Copilot CLI**, and **OpenAI Codex CLI** — on **macOS, Linux, and Windows**.
 
-### GitHub Copilot CLI
-![GitHub Copilot CLI demo](docs/code-preview-copilot.gif)
+<img src="assets/diff-preview.png" alt="A proposed AI edit shown as a side-by-side diff in Neovim" width="860">
 
-### OpenAI Codex CLI
-![OpenAI Codex CLI demo](docs/code-preview-codex.gif)
+</div>
 
 ---
 
-## Table of Contents
-
-- [Features](#features)
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-  - [Claude Code](#claude-code)
-  - [OpenCode](#opencode)
-  - [GitHub Copilot CLI](#github-copilot-cli)
-  - [OpenAI Codex CLI](#openai-codex-cli)
-- [How it works](#how-it-works)
-- [Configuration](#configuration)
-- [Commands](#commands)
-- [Keymaps](#keymaps)
-- [Diff Layouts](#diff-layouts)
-- [Neo-tree Integration](#neo-tree-integration-optional)
-- [Testing](#testing)
-- [Troubleshooting](#troubleshooting)
+## Demo
+
+![Claude Code demo](assets/code-preview-claudecode.gif)
+
+> Shown with Claude Code. OpenCode, GitHub Copilot CLI, and Codex CLI work the same way — expand **📺 More demos** below.
 
 ---
 
-## Features
+## Why
 
-- **Diff preview** — side-by-side or inline diff opens in Neovim before any file is written
-- **Multiple layouts** — tab, vsplit, or GitHub-style inline diff with syntax highlighting
-- **Neo-tree integration** — file tree indicators show which files are being modified, created, or deleted
-- **Multi-backend** — works with Claude Code, OpenCode, GitHub Copilot CLI, and OpenAI Codex CLI
-- **No Python dependency** — file transformations use `nvim --headless -l`
+Your AI coding agent proposes edits in its terminal — a cramped, scroll-past diff you have to eyeball before typing `y`. **code-preview.nvim** intercepts that moment and opens the proposed change as a real Neovim diff: full syntax highlighting, your colorscheme, your keymaps. Review it like any other diff, then accept or reject in the agent's CLI as usual.
 
----
+- 🔍 **See edits as native diffs** — side-by-side or GitHub-style inline, before anything touches disk
+- 🤝 **Agent-agnostic** — Claude Code, OpenCode, Copilot CLI, Codex CLI, with more agents planned
+- 🌳 **Neo-tree integration** — your file tree marks what's being modified, created, or deleted
+- 🪶 **No Python** — file transforms run through `nvim --headless -l`; the only hard dep is Neovim 0.10+
 
-## Requirements
+<details>
+<summary><b>📺 More demos</b></summary>
 
-- Neovim >= 0.10
+### OpenCode
+![OpenCode demo](assets/code-preview-opencode.gif)
 
-**For Claude Code backend:**
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) with hooks support
-- [jq](https://jqlang.github.io/jq/) — for JSON parsing in hook scripts
+### GitHub Copilot CLI
+![GitHub Copilot CLI demo](assets/code-preview-copilot.gif)
 
-**For OpenCode backend:**
-- [OpenCode](https://opencode.ai) >= 1.3.0
+### OpenAI Codex CLI
+![OpenAI Codex CLI demo](assets/code-preview-codex.gif)
 
-**For GitHub Copilot CLI backend:**
-- [GitHub Copilot CLI](https://github.com/github/copilot-cli) (generally available since Feb 2026)
+### Neo-tree integration
+![neo-tree integration demo](assets/code-preview-neotree-integration.gif)
 
-**For OpenAI Codex CLI backend:**
-- [OpenAI Codex CLI](https://github.com/openai/codex) (recent enough to support `apply_patch` PreToolUse hooks; older builds only fired hooks for `Bash`)
-- [jq](https://jqlang.github.io/jq/) — for hook payload translation
+</details>
 
 ---
 
-## Installation
+## Install
 
-### lazy.nvim
+With [lazy.nvim](https://github.com/folke/lazy.nvim):
 
 ```lua
 {
@@ -86,334 +68,222 @@ Supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCod
 }
 ```
 
-### Manual (path-based)
+<details>
+<summary>Manual (path-based)</summary>
 
 ```lua
 vim.opt.rtp:prepend("/path/to/code-preview.nvim")
 require("code-preview").setup()
 ```
 
----
+</details>
 
-## Quick Start
+**Requirements:** Neovim >= 0.10. Each agent has a couple of extra needs — see below.
 
-### Claude Code
+<details>
+<summary>Per-agent requirements</summary>
 
-1. Install the plugin and call `setup()`
-2. Open a project in Neovim
-3. Run `:CodePreviewInstallClaudeCodeHooks` — writes hooks to `.claude/settings.local.json`
-4. Restart Claude Code CLI in the project directory
-5. Ask Claude to edit a file — a diff opens automatically in Neovim
-6. Accept/reject in the CLI; the diff closes automatically on accept
-7. If rejected, press `<leader>dq` to close the diff manually
+| Agent | Needs |
+|-------|-------|
+| **Claude Code** | [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (with hooks) · [jq](https://jqlang.github.io/jq/) |
+| **OpenCode** | [OpenCode](https://opencode.ai) (a version with plugin support) |
+| **GitHub Copilot CLI** | [Copilot CLI](https://github.com/github/copilot-cli) (GA since Feb 2026) |
+| **OpenAI Codex CLI** | [Codex CLI](https://github.com/openai/codex) recent enough for `apply_patch` PreToolUse hooks · [jq](https://jqlang.github.io/jq/) |
 
-### OpenCode
+> On Windows, the Copilot CLI hook runs under PowerShell 7+ and needs no `jq`.
 
-1. Install the plugin and call `setup()`
-2. Open a project in Neovim
-3. Run `:CodePreviewInstallOpenCodeHooks` — copies the plugin to `.opencode/plugins/`
-4. Ensure your OpenCode config (`~/.config/opencode/opencode.json`) has permission prompts enabled:
-   ```json
-   {
-     "permission": {
-       "edit": "ask",
-       "bash": "ask"
-     }
-   }
-   ```
-5. Start OpenCode in the project directory
-6. Ask OpenCode to edit a file — a diff opens automatically in Neovim
-7. Accept/reject in OpenCode; the diff closes automatically on accept
-8. If rejected, press `<leader>dq` to close the diff manually
+</details>
 
-### GitHub Copilot CLI
+---
 
-1. Install the plugin and call `setup()`
-2. Open a project in Neovim
-3. Run `:CodePreviewInstallCopilotCliHooks` — writes `.github/hooks/code-preview.json`
-4. Start Copilot CLI in the project directory
-5. Ask Copilot to edit a file — a diff opens automatically in Neovim
-6. Accept/reject in the CLI; the diff closes automatically on accept
-7. If rejected, press `<leader>dq` to close the diff manually
+## Quick start
 
-> **Note:** Copilot CLI does not fire post-tool hooks on rejection, so rejected diffs remain open until you dismiss them (same as Claude Code).
+After `setup()`, the flow is the same for every agent:
 
-### OpenAI Codex CLI
+1. Open your project in Neovim.
+2. Install the agent's hooks (one command — pick your agent below) and **restart that agent's CLI**.
+3. Ask the agent to edit a file — a diff preview opens automatically in Neovim.
+4. Review it, then accept or reject in the agent. On accept, the preview closes automatically.
 
-1. Install the plugin and call `setup()`
-2. Open a project in Neovim
-3. Run `:CodePreviewInstallCodexCliHooks` — writes `.codex/hooks.json`
-4. The diff-preview workflow only makes sense when Codex asks before applying edits. Create or edit `.codex/config.toml` (project-local) or `~/.codex/config.toml` (global) and add:
+Then run the one install command for your agent (and apply any agent-specific config):
 
-   ```toml
-   approval_policy = "on-request"
-   sandbox_mode    = "read-only"
-   ```
+<details open>
+<summary><b>Claude Code</b></summary>
 
-   `approval_policy = "on-request"` and `sandbox_mode = "read-only"` ensure Codex prompts you before every edit, so the diff preview has time to open and you have time to review. Without them, Codex may apply changes without prompting and the preview window will never block on your decision.
+`:CodePreviewInstallClaudeCodeHooks` — writes hooks to `.claude/settings.local.json`. No extra config needed.
 
-   > **Note on the hooks feature flag:** Modern Codex enables hooks by default — no `[features]` entry is required. If you previously disabled them with `[features] hooks = false` (or the legacy `codex_hooks = false`), remove that line. `:CodePreviewStatus` and `:checkhealth code-preview` will warn if hooks are explicitly disabled.
-5. Start Codex CLI in the project directory
-6. Ask Codex to edit a file — a diff opens automatically in Neovim
-7. Accept/reject in the CLI; the diff closes automatically on accept
-8. If rejected, press `<leader>dq` to close the diff manually
+> **Permissions:** by default the plugin forces a review prompt on every edit, so the preview always lines up with a real accept/reject moment — even if Claude Code is in bypass/allowlist mode. To instead let Claude Code's own permission settings decide, set `diff.defer_claude_permissions = true` (you'll then only see previews for edits Claude Code already stops to ask about).
 
-> **Note:** Today's Codex models route all file edits through the `apply_patch` tool. New file creation that Codex performs via shell redirection (e.g. `printf … > foo.txt`) is not previewed — only `apply_patch` and edits via the dedicated `Edit`/`Write` tools (when emitted) are.
+</details>
 
----
+<details>
+<summary><b>OpenCode</b></summary>
 
-## How it works
+`:CodePreviewInstallOpenCodeHooks` — copies the plugin to `.opencode/plugins/`.
 
+Then enable permission prompts in `~/.config/opencode/opencode.json`:
+
+```json
+{ "permission": { "edit": "ask", "bash": "ask" } }
 ```
-AI Agent (terminal)                              Neovim
-        |                                          |
-   Proposes an Edit                                |
-        |                                          |
-   Hook/plugin fires ──→ compute diff ──→ RPC → show_diff()
-        |                                          | (side-by-side or inline)
-   CLI: "Accept? (y/n)"                            |
-        |                                     User reviews diff
-   User accepts/rejects                            |
-        |                                          |
-   Post hook fires ────→ cleanup ─────→ RPC → close_diff()
+
+</details>
+
+<details>
+<summary><b>GitHub Copilot CLI</b></summary>
+
+`:CodePreviewInstallCopilotCliHooks` — writes `.github/hooks/code-preview.json`. No extra config needed.
+
+</details>
+
+<details>
+<summary><b>OpenAI Codex CLI</b></summary>
+
+`:CodePreviewInstallCodexCliHooks` — writes `.codex/hooks.json`.
+
+Codex must ask before applying edits, so set this in `.codex/config.toml` (or `~/.codex/config.toml`):
+
+```toml
+approval_policy = "on-request"
+sandbox_mode    = "read-only"
 ```
 
-**Claude Code** uses shell-based hooks (`PreToolUse`/`PostToolUse`) configured in `.claude/settings.local.json`.
+Without it, Codex may apply changes without prompting and the preview never blocks on your decision. Hooks are enabled by default in modern Codex; if you previously set `[features] hooks = false` (or the legacy `codex_hooks = false`), remove it. Codex routes file edits through `apply_patch` — files created via shell redirection (`printf … > foo.txt`) aren't previewed.
+
+</details>
+
+> **Rejected a change?** The post-tool hook only fires on accept (and not at all on rejection for Claude Code & Copilot CLI), so press `<leader>dq` — or run `:CodePreviewCloseDiff` — to close the preview manually.
+
+---
 
-**OpenCode** uses a TypeScript plugin (`tool.execute.before`/`tool.execute.after`) loaded from `.opencode/plugins/`.
+## Supported agents
 
-**GitHub Copilot CLI** uses shell-based hooks (`preToolUse`/`postToolUse`) configured in `.github/hooks/code-preview.json`. The adapter translates Copilot's tool vocabulary (`apply_patch`, `edit`, `create`, `bash`) into the same normalized format used by the other backends.
+Every agent is first-class — same diff experience, same keymaps, same neo-tree indicators.
 
-**OpenAI Codex CLI** uses shell-based hooks (`PreToolUse`/`PostToolUse`) configured in `.codex/hooks.json`. Hooks are enabled by default in modern Codex; the only way to silence them is `[features] hooks = false` (or the legacy `codex_hooks = false`) in `.codex/config.toml`. The adapter passes `Bash` through and rewrites `apply_patch` (whose patch text lives in `tool_input.command`) into the canonical `ApplyPatch` shape with `tool_input.patch_text`.
+| Agent | Install command | Mechanism |
+|-------|-----------------|-----------|
+| Claude Code | `:CodePreviewInstallClaudeCodeHooks` | shell hooks in `.claude/settings.local.json` |
+| OpenCode | `:CodePreviewInstallOpenCodeHooks` | TS plugin in `.opencode/plugins/` |
+| GitHub Copilot CLI | `:CodePreviewInstallCopilotCliHooks` | shell hooks in `.github/hooks/code-preview.json` |
+| OpenAI Codex CLI | `:CodePreviewInstallCodexCliHooks` | shell hooks in `.codex/hooks.json` |
 
-All backends communicate with Neovim via RPC (`nvim --server <socket> --remote-send`).
+Each install command has a matching `:CodePreviewUninstall…` counterpart. More agents are planned.
 
 ---
 
 ## Configuration
 
-All options with defaults:
+`setup()` works with zero config. The most common knob is the diff **layout**:
 
 ```lua
 require("code-preview").setup({
-  debug = false,         -- enable debug logging to stdpath("log")/code-preview.log
   diff = {
-    layout   = "tab",    -- "tab" (new tab) | "vsplit" (current tab) | "inline" (GitHub-style)
-    labels   = { current = "CURRENT", proposed = "PROPOSED" },
-    equalize   = true,   -- 50/50 split widths (tab/vsplit only)
-    full_file  = true,   -- show full file, not just diff hunks (tab/vsplit only)
-    visible_only = false, -- skip diffs for files not open in any Neovim buffer
-    defer_claude_permissions = false, -- for Claude Code: let its own settings decide, don't prompt
-  },
-  highlights = {
-    current = {          -- CURRENT (original) side — tab/vsplit layouts
-      DiffAdd    = { bg = "#4c2e2e" },
-      DiffDelete = { bg = "#4c2e2e" },
-      DiffChange = { bg = "#4c3a2e" },
-      DiffText   = { bg = "#5c3030" },
-    },
-    proposed = {         -- PROPOSED side — tab/vsplit layouts
-      DiffAdd    = { bg = "#2e4c2e" },
-      DiffDelete = { bg = "#4c2e2e" },
-      DiffChange = { bg = "#2e3c4c" },
-      DiffText   = { bg = "#3e5c3e" },
-    },
-    inline = {           -- inline layout
-      added        = { bg = "#2e4c2e" },          -- added line background
-      removed      = { bg = "#4c2e2e" },          -- removed line background
-      added_text   = { bg = "#3a6e3a" },          -- changed characters (added)
-      removed_text = { bg = "#6e3a3a" },          -- changed characters (removed)
-    },
+    layout = "tab",  -- "tab" | "vsplit" | "inline"
   },
 })
 ```
 
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `:CodePreviewInstallClaudeCodeHooks` | Install Claude Code hooks to `.claude/settings.local.json` |
-| `:CodePreviewUninstallClaudeCodeHooks` | Remove Claude Code hooks (leaves other hooks intact) |
-| `:CodePreviewInstallOpenCodeHooks` | Install OpenCode plugin to `.opencode/plugins/` |
-| `:CodePreviewUninstallOpenCodeHooks` | Remove OpenCode plugin |
-| `:CodePreviewInstallCopilotCliHooks` | Install Copilot CLI hooks to `.github/hooks/code-preview.json` |
-| `:CodePreviewUninstallCopilotCliHooks` | Remove Copilot CLI hooks |
-| `:CodePreviewInstallCodexCliHooks` | Install Codex CLI hooks to `.codex/hooks.json` |
-| `:CodePreviewUninstallCodexCliHooks` | Remove Codex CLI hooks |
-| `:CodePreviewCloseDiff` | Manually close the diff (use after rejecting a change) |
-| `:CodePreviewStatus` | Show socket path, hook status, and dependency check |
-| `:CodePreviewToggleVisibleOnly` | Toggle visible_only — show diffs only for open buffers |
-| `:checkhealth code-preview` | Full health check (all backends) |
-
-## Keymaps
-
-| Key | Scope | Description |
-|-----|-------|-------------|
-| `<leader>dq` | global | Close the diff (same as `:CodePreviewCloseDiff`) |
-| `]c` | inline diff buffer | Jump to next change |
-| `[c` | inline diff buffer | Jump to previous change |
+| Layout | Description |
+|--------|-------------|
+| `"tab"` (default) | Side-by-side diff in a new tab — CURRENT left, PROPOSED right |
+| `"vsplit"` | Side-by-side as a vertical split in the current tab |
+| `"inline"` | GitHub-style unified diff in one buffer, syntax highlighting preserved, `]c` / `[c` to navigate |
 
-All defaults are configurable via `setup()`:
+You can also set the layout **per agent** — e.g. inline for Codex, a tab for everything else:
 
 ```lua
 require("code-preview").setup({
-  keys = {
-    next_change = "]c",          -- inline diff: next change
-    prev_change = "[c",          -- inline diff: previous change
-    close_all   = "<leader>dq",  -- close diff and clear indicators
+  diff = {
+    layout  = "tab",                 -- default for all agents
+    layouts = { codex = "inline" },  -- keys: claudecode | opencode | copilot | codex
   },
 })
 ```
 
-Set any entry to `false` to skip that binding, or `keys = false` to skip them all. A `<Plug>(CodePreviewCloseAll)` mapping is always defined, so you can bind it yourself even with `keys = false`:
+### A fuller example
+
+A realistic, opinionated lazy.nvim spec — inline diffs everywhere, a per-agent override, and neo-tree revealing from the git root:
 
 ```lua
-vim.keymap.set("n", "<leader>x", "<Plug>(CodePreviewCloseAll)")
+{
+  "Cannon07/code-preview.nvim",
+  event = "VeryLazy",
+  config = function()
+    require("code-preview").setup({
+      diff = {
+        layout  = "inline",              -- unified GitHub-style diff (the strategic default)
+        layouts = { opencode = "tab" },  -- override the layout per agent, to taste
+      },
+      neo_tree = { reveal_root = "git" }, -- reveal from the git root instead of cwd
+    })
+  end,
+}
 ```
 
----
-
-## Diff Layouts
+**Full option reference:** `:help code-preview-config` (or [`doc/code-preview.txt`](doc/code-preview.txt)) — every option, with the defaults kept in sync with the source.
 
-code-preview supports three diff layouts, configured via `diff.layout`:
+<details>
+<summary><b>Commands & keymaps</b></summary>
 
-| Layout | Description |
-|--------|-------------|
-| `"tab"` (default) | Side-by-side diff in a new tab — CURRENT on the left, PROPOSED on the right |
-| `"vsplit"` | Side-by-side diff as a vertical split in the current tab |
-| `"inline"` | GitHub-style unified diff in a single buffer with syntax highlighting preserved |
-
-### Inline diff features
+| Command | Description |
+|---------|-------------|
+| `:CodePreviewInstall…Hooks` / `:CodePreviewUninstall…Hooks` | Install/remove hooks for an agent (`ClaudeCode`, `OpenCode`, `CopilotCli`, `CodexCli`) |
+| `:CodePreviewCloseDiff` | Manually close the diff (use after rejecting) |
+| `:CodePreviewStatus` | Show socket path, hook status, and dependency check |
+| `:CodePreviewToggleVisibleOnly` | Toggle `visible_only` — diffs only for open buffers |
+| `:checkhealth code-preview` | Full health check (all agents) |
 
-- **Syntax highlighting** — the file's language highlighting is preserved
-- **Character-level diffs** — changed portions within a line are highlighted with a brighter background
-- **Sign column** — `+`/`-` signs indicate added/removed lines
-- **Navigation** — `]c` / `[c` to jump between changes
+| Key | Scope | Description |
+|-----|-------|-------------|
+| `<leader>dq` | global | Close the diff (same as `:CodePreviewCloseDiff`) |
+| `]c` | inline diff buffer | Jump to next change |
+| `[c` | inline diff buffer | Jump to previous change |
 
-To use inline diff:
+See `:help code-preview-commands` and `:help code-preview-keymaps` for details.
 
-```lua
-require("code-preview").setup({
-  diff = { layout = "inline" },
-})
-```
+</details>
 
 ---
 
-## Neo-tree Integration (Optional)
+## Neo-tree integration (optional)
 
-If you use [neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim), code-preview will automatically decorate your file tree with visual indicators when changes are proposed. No extra configuration is required — it works out of the box.
+If you use [neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim), code-preview decorates your file tree with indicators whenever changes are pending — no extra config, it works out of the box. If neo-tree isn't installed, nothing changes.
 
-![neo-tree integration demo](docs/code-preview-neotree-integration.gif)
-
-### What you get
-
-| Status | Icon | Name Color | Description |
-|--------|------|------------|-------------|
+| Status | Icon | Color | Meaning |
+|--------|------|-------|---------|
 | Modified | 󰏫 | Orange | An existing file is being edited |
-| Created | 󰎔 | Cyan + italic | A new file is being created (shown as a virtual node) |
+| Created | 󰎔 | Cyan + italic | A new file is being created (virtual node) |
 | Deleted | 󰆴 | Red + strikethrough | A file is being deleted via `rm` |
 
-Additional behaviors:
-- **Auto-reveal** — the tree expands to highlight the changed file
-- **Virtual nodes** — new files/directories appear in the tree before they exist on disk
-- **Clean focus** — git status, diagnostics, and modified indicators are temporarily hidden while changes are pending
-- **Auto-cleanup** — all indicators clear when you accept, reject, or press `<leader>dq`
-
-### Neo-tree configuration options
-
-All neo-tree options with defaults:
-
-```lua
-require("code-preview").setup({
-  neo_tree = {
-    enabled = true,             -- set false to disable neo-tree integration
-    reveal = true,              -- auto-reveal changed files in the tree
-    reveal_root = "cwd",        -- "cwd" (current working dir) or "git" (git root)
-    position = "right",         -- neo-tree window position: "left", "right", "float"
-    symbols = {
-      modified = "󰏫",
-      created  = "󰎔",
-      deleted  = "󰆴",
-    },
-    highlights = {
-      modified = { fg = "#e8a838", bold = true },
-      created  = { fg = "#56c8d8", bold = true },
-      deleted  = { fg = "#e06c75", bold = true, strikethrough = true },
-    },
-  },
-})
-```
-
-> **Note:** Neo-tree is a soft dependency. If neo-tree is not installed, the plugin works exactly as before — only the diff preview.
+Plus: auto-reveal of the changed file, virtual nodes for not-yet-created files, a temporarily clean focus (git status/diagnostics hidden while a change is pending), and auto-cleanup on accept/reject/`<leader>dq`. Symbols, colors, position, and reveal behavior are all configurable under the `neo_tree` table — see `:help code-preview-config`.
 
 ---
 
-## Architecture
+## How it works
 
 ```
-code-preview.nvim/
-├── lua/code-preview/
-│   ├── init.lua                     setup(), config, commands
-│   ├── diff.lua                     show_diff(), close_diff()
-│   ├── log.lua                      opt-in debug logging
-│   ├── changes.lua                  change status registry (modified/created/deleted)
-│   ├── neo_tree.lua                 neo-tree integration (icons, virtual nodes, reveal)
-│   ├── health.lua                   :checkhealth (all backends)
-│   └── backends/
-│       ├── claudecode.lua           Claude Code hook install/uninstall
-│       ├── opencode.lua             OpenCode plugin install/uninstall
-│       ├── copilot.lua              GitHub Copilot CLI hook install/uninstall
-│       └── codex.lua                OpenAI Codex CLI hook install/uninstall
-├── bin/                             Shared core scripts
-│   ├── core-pre-tool.sh             Unified PreToolUse logic
-│   ├── core-post-tool.sh            Unified PostToolUse logic
-│   ├── nvim-socket.sh               Neovim socket discovery
-│   ├── nvim-send.sh                 RPC send helper
-│   ├── apply-edit.lua               Single Edit transformer
-│   ├── apply-multi-edit.lua         MultiEdit transformer
-│   └── apply-patch.lua              ApplyPatch transformer (custom patch format)
-├── backends/
-│   ├── claudecode/                  Claude Code adapter
-│   │   ├── code-preview-diff.sh     PreToolUse hook entry point
-│   │   └── code-close-diff.sh       PostToolUse hook entry point
-│   ├── opencode/                    OpenCode adapter
-│   │   ├── index.ts                 tool.execute.before/after hooks
-│   │   ├── package.json
-│   │   └── tsconfig.json
-│   ├── copilot/                     GitHub Copilot CLI adapter
-│   │   ├── code-preview-diff.sh     preToolUse hook — translates Copilot JSON → core
-│   │   └── code-close-diff.sh       postToolUse hook — same for close
-│   └── codex/                       OpenAI Codex CLI adapter
-│       ├── code-preview-diff.sh     PreToolUse hook — translates Codex JSON → core
-│       └── code-close-diff.sh       PostToolUse hook — same for close
+AI Agent (terminal)                              Neovim
+        |                                          |
+   Proposes an Edit                                |
+        |                                          |
+   Hook/plugin fires ──→ compute diff ──→ RPC → show_diff()
+        |                                          | (side-by-side or inline)
+   CLI: "Accept? (y/n)"                       User reviews diff
+        |                                          |
+   User accepts/rejects                            |
+        |                                          |
+   Post hook fires ────→ cleanup ─────→ RPC → close_diff()
 ```
 
----
-
-## Testing
+A hook fires before the edit is applied → Neovim shows the diff → a post-tool hook cleans up after you accept or reject. That's the whole loop, for every agent.
 
-The test suite uses [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for core plugin tests and shell scripts for backend integration tests. CI runs on both Ubuntu and macOS.
-
-```bash
-./tests/run.sh                          # all tests (plugin + backends)
-./tests/run.sh plugin                   # core plugin tests only (plenary busted)
-./tests/run.sh backends                 # all backend integration tests
-./tests/run.sh backends/claudecode      # Claude Code backend only
-./tests/run.sh backends/opencode        # OpenCode backend only
-./tests/run.sh backends/copilot         # GitHub Copilot CLI backend only
-./tests/run.sh backends/codex           # OpenAI Codex CLI backend only
-```
-
-**Dependencies:** Neovim >= 0.10, jq, bun (for OpenCode tests). Plenary is auto-installed to `deps/` on first run.
+Curious about the internals — the per-OS hook entry, RPC transport, and per-agent adapters? See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
 ## Recommended companion settings
 
-For buffers to auto-reload after a file is written, add this to your Neovim config:
+So buffers auto-reload after a file is written:
 
 ```lua
 vim.o.autoread = true
@@ -421,51 +291,53 @@ vim.api.nvim_create_autocmd({ "FocusGained", "BufEnter", "CursorHold" }, {
   command = "checktime",
 })
 ```
+
 ---
 
-## Troubleshooting
+<details>
+<summary><b>Troubleshooting</b></summary>
 
 **Diff doesn't open**
-- Run `:CodePreviewStatus` — check that `Neovim socket` is found
-- Run `:checkhealth code-preview` — check for missing dependencies
-- Enable debug logging (`debug = true` in setup) and check `~/.local/state/nvim/code-preview.log`
+- `:CodePreviewStatus` — check that `Neovim socket` is found
+- `:checkhealth code-preview` — check for missing dependencies
+- Enable `debug = true` and check `~/.local/state/nvim/code-preview.log`
 - Restart the CLI agent after installing hooks (hooks are read at startup)
 
 **Claude Code hooks not firing**
-- Run `:CodePreviewInstallClaudeCodeHooks` in the project root
-- Verify `.claude/settings.local.json` contains the hook entries
-- Ensure `jq` is in PATH
-- Restart Claude Code CLI
+- Re-run `:CodePreviewInstallClaudeCodeHooks` in the project root
+- Verify `.claude/settings.local.json` contains the hook entries; ensure `jq` is in PATH; restart the CLI
 
 **OpenCode plugin not loading**
-- Run `:CodePreviewInstallOpenCodeHooks` in the project root
-- Verify `.opencode/plugins/index.ts` exists
-- Ensure `"permission": { "edit": "ask" }` is set in `~/.config/opencode/opencode.json`
-- Restart OpenCode
+- Re-run `:CodePreviewInstallOpenCodeHooks`; verify `.opencode/plugins/index.ts` exists
+- Ensure `"permission": { "edit": "ask" }` is set in `~/.config/opencode/opencode.json`; restart OpenCode
 
 **Codex CLI hooks not firing**
-- Run `:CodePreviewInstallCodexCliHooks` in the project root
-- Confirm `.codex/config.toml` does **not** contain `[features] hooks = false` (or the legacy `codex_hooks = false`) — hooks are enabled by default in modern Codex; an explicit `false` is the only way to silence them
-- Update Codex if needed — older versions required `codex_hooks = true` explicitly and only fired hooks for `Bash`, not `apply_patch`
-- Run `:CodePreviewStatus` and `:checkhealth code-preview` to verify install state and the feature flag
+- Re-run `:CodePreviewInstallCodexCliHooks`
+- Confirm `.codex/config.toml` does **not** contain `[features] hooks = false` (or the legacy `codex_hooks = false`)
+- Older Codex required `codex_hooks = true` and only fired hooks for `Bash`, not `apply_patch` — update if needed
+- `:CodePreviewStatus` / `:checkhealth code-preview` report install state and the feature flag
 
 **Copilot CLI hooks not firing**
-- Run `:CodePreviewInstallCopilotCliHooks` in the project root
-- Verify `.github/hooks/code-preview.json` exists
-- Ensure `jq` is in PATH (macOS/Linux only; the Windows hook uses PowerShell's native JSON parsing)
-- On Windows, Copilot runs the hook under **pwsh 7+** (its own requirement). If hooks silently don't fire, check your PowerShell execution policy with `Get-ExecutionPolicy` — pwsh's default `RemoteSigned` runs the local hook script, but `Restricted`/`AllSigned` blocks it (e.g. `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`)
-- Restart Copilot CLI (hooks are loaded at session start)
+- Re-run `:CodePreviewInstallCopilotCliHooks`; verify `.github/hooks/code-preview.json` exists
+- Ensure `jq` is in PATH (macOS/Linux). On Windows, Copilot runs the hook under pwsh 7+ — if it silently doesn't fire, check `Get-ExecutionPolicy` (`RemoteSigned` works; `Restricted`/`AllSigned` blocks it)
+- Restart Copilot CLI
 
 **Diff doesn't close after rejecting**
-- Press `<leader>dq` or run `:CodePreviewCloseDiff` — the post hook only fires on accept
+- Press `<leader>dq` or run `:CodePreviewCloseDiff` — the post hook only fires on accept (Claude Code & Copilot CLI)
 
 **Migrating from older versions**
-- Update `require("claude-preview")` to `require("code-preview")` in your Neovim config
+- Update `require("claude-preview")` → `require("code-preview")` in your config
 - Re-run `:CodePreviewInstallClaudeCodeHooks` to update hook paths
-- The old `:ClaudePreview*` commands have been removed — use the `:CodePreview*` equivalents
+- The old `:ClaudePreview*` commands were removed — use the `:CodePreview*` equivalents
+
+</details>
 
 ---
 
+## Contributing
+
+Architecture, internals, and how to run the tests live in [CONTRIBUTING.md](CONTRIBUTING.md). The project's vocabulary is defined in [CONTEXT.md](CONTEXT.md).
+
 ## License
 
-MIT — see [LICENSE](LICENSE)
+MIT — see [LICENSE](LICENSE).
diff --git a/docs/code-preview-claudecode.gif b/assets/code-preview-claudecode.gif
similarity index 100%
rename from docs/code-preview-claudecode.gif
rename to assets/code-preview-claudecode.gif
diff --git a/docs/code-preview-codex.gif b/assets/code-preview-codex.gif
similarity index 100%
rename from docs/code-preview-codex.gif
rename to assets/code-preview-codex.gif
diff --git a/docs/code-preview-copilot.gif b/assets/code-preview-copilot.gif
similarity index 100%
rename from docs/code-preview-copilot.gif
rename to assets/code-preview-copilot.gif
diff --git a/docs/code-preview-neotree-integration.gif b/assets/code-preview-neotree-integration.gif
similarity index 100%
rename from docs/code-preview-neotree-integration.gif
rename to assets/code-preview-neotree-integration.gif
diff --git a/docs/code-preview-opencode.gif b/assets/code-preview-opencode.gif
similarity index 100%
rename from docs/code-preview-opencode.gif
rename to assets/code-preview-opencode.gif
diff --git a/assets/diff-preview.png b/assets/diff-preview.png
new file mode 100644
index 0000000..7400502
Binary files /dev/null and b/assets/diff-preview.png differ
diff --git a/assets/logo.svg b/assets/logo.svg
new file mode 100644
index 0000000..c513d60
--- /dev/null
+++ b/assets/logo.svg
@@ -0,0 +1,44 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="code-preview.nvim logo">
+  <defs>
+    <linearGradient id="tile" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#18212F"/>
+      <stop offset="1" stop-color="#0E141F"/>
+    </linearGradient>
+    <linearGradient id="seam" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#F0626B"/>
+      <stop offset="0.5" stop-color="#F0626B"/>
+      <stop offset="0.5" stop-color="#3FB950"/>
+      <stop offset="1" stop-color="#3FB950"/>
+    </linearGradient>
+  </defs>
+
+  <!-- tile -->
+  <rect x="56" y="56" width="400" height="400" rx="104" fill="url(#tile)" stroke="#27344A" stroke-width="3"/>
+  <rect x="56.5" y="56.5" width="399" height="399" rx="103.5" fill="none" stroke="#000000" stroke-opacity="0.25" stroke-width="1"/>
+
+  <!-- diff block, scaled up to fill the tile for small-size legibility -->
+  <g transform="translate(268 256) scale(1.3) translate(-256 -256)">
+  <!-- context line (top) -->
+  <rect x="150" y="168" width="150" height="30" rx="9" fill="#28344A"/>
+
+  <!-- diff gutter seam: green over the add row, red over the remove row -->
+  <rect x="120" y="210" width="6" height="92" rx="3" fill="url(#seam)" opacity="0.95"/>
+
+  <!-- removed line (top, matching GitHub diff order) -->
+  <text x="138" y="243" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="34" font-weight="700" fill="#F0626B" text-anchor="middle">−</text>
+  <rect x="150" y="214" width="232" height="34" rx="9" fill="#F0626B" fill-opacity="0.14"/>
+  <rect x="150" y="214" width="232" height="34" rx="9" fill="none" stroke="#F0626B" stroke-opacity="0.5" stroke-width="2"/>
+  <rect x="168" y="225" width="86" height="12" rx="6" fill="#F0626B" fill-opacity="0.85"/>
+  <rect x="266" y="225" width="98" height="12" rx="6" fill="#F0626B" fill-opacity="0.45"/>
+
+  <!-- added line (bottom) -->
+  <text x="138" y="293" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="34" font-weight="700" fill="#3FB950" text-anchor="middle">+</text>
+  <rect x="150" y="264" width="232" height="34" rx="9" fill="#3FB950" fill-opacity="0.16"/>
+  <rect x="150" y="264" width="232" height="34" rx="9" fill="none" stroke="#3FB950" stroke-opacity="0.55" stroke-width="2"/>
+  <rect x="168" y="275" width="120" height="12" rx="6" fill="#3FB950" fill-opacity="0.9"/>
+  <rect x="300" y="275" width="64" height="12" rx="6" fill="#3FB950" fill-opacity="0.5"/>
+
+  <!-- context line (bottom) -->
+  <rect x="150" y="314" width="190" height="30" rx="9" fill="#28344A"/>
+  </g>
+</svg>
diff --git a/doc/code-preview.txt b/doc/code-preview.txt
new file mode 100644
index 0000000..799651e
--- /dev/null
+++ b/doc/code-preview.txt
@@ -0,0 +1,243 @@
+*code-preview.txt*        Review AI coding-agent edits as native Neovim diffs
+
+==============================================================================
+CONTENTS                                                *code-preview-contents*
+
+  1. Introduction ........................... |code-preview-introduction|
+  2. Setup .................................. |code-preview-setup|
+  3. Configuration .......................... |code-preview-config|
+  4. Commands ............................... |code-preview-commands|
+  5. Keymaps ................................ |code-preview-keymaps|
+  6. Agents ................................. |code-preview-agents|
+
+==============================================================================
+1. INTRODUCTION                                     *code-preview-introduction*
+
+                                                                 *code-preview*
+
+code-preview.nvim shows the edits an AI coding agent proposes as native Neovim
+diffs, so you review, accept, or reject changes inside your editor instead of
+eyeballing them in the agent's CLI.
+
+It supports four agents as equal first-class citizens — Claude Code, OpenCode,
+GitHub Copilot CLI, and OpenAI Codex CLI — on macOS, Linux, and Windows.
+
+The README is the landing page; this help file is the reference manual. The
+configuration block in |code-preview-config| is the canonical option reference
+and is kept in sync with the defaults in `lua/code-preview/init.lua`.
+
+==============================================================================
+2. SETUP                                                   *code-preview-setup*
+
+                                                          *code-preview.setup()*
+
+Call `setup()` once from your plugin config. It works with zero arguments;
+pass a table to override any default (see |code-preview-config|). Options are
+deep-merged over the defaults.
+>lua
+    require("code-preview").setup()
+<
+With lazy.nvim: >lua
+    {
+      "Cannon07/code-preview.nvim",
+      config = function()
+        require("code-preview").setup()
+      end,
+    }
+<
+After `setup()`, install the hooks for your agent (see |code-preview-agents|)
+and restart that agent's CLI.
+
+==============================================================================
+3. CONFIGURATION                                          *code-preview-config*
+
+Full default configuration. These values are copied verbatim from
+`lua/code-preview/init.lua` and are the source of truth for every option: >lua
+    require("code-preview").setup({
+      debug = false,  -- enable debug logging to stdpath("log")/code-preview.log
+      diff = {
+        layout = "tab",        -- "tab", "vsplit", or "inline"
+        layouts = {},          -- override layout per backend: { opencode = "tab", codex = "vsplit" }
+        labels = { current = "CURRENT", proposed = "PROPOSED" },
+        equalize = true,
+        full_file = true,
+        visible_only = false,  -- only show diffs for files open in a visible nvim window
+        defer_claude_permissions = false,  -- when true, skip permissionDecision and let Claude Code's own settings decide
+      },
+      neo_tree = {
+        enabled = true,
+        -- reveal = false disables scroll-to-file in the tree. Change indicators
+        -- (modified/created/deleted icons) still appear — to disable those too,
+        -- set neo_tree.enabled = false.
+        reveal = true,         -- reveal edited files in neo-tree
+        reveal_root = "cwd",   -- "cwd" (default) or "git" (nearest git root)
+        refresh_on_change = true,
+        position = "right",
+        symbols = {
+          modified = "󰏫",
+          created  = "󰎔",
+          deleted  = "󰆴",
+        },
+        highlights = {
+          modified = { fg = "#e8a838", bold = true },
+          created  = { fg = "#56c8d8", bold = true },
+          deleted  = { fg = "#e06c75", bold = true, strikethrough = true },
+        },
+      },
+      keys = {
+        -- Set any entry to false to skip that binding. Set `keys = false` to skip all.
+        -- <Plug>(CodePreviewCloseAll) is always defined so users can map it themselves.
+        next_change = "]c",        -- buffer-local in inline diff buffers
+        prev_change = "[c",        -- buffer-local in inline diff buffers
+        close_all   = "<leader>dq", -- global; close diff and clear indicators
+      },
+      highlights = {
+        current = {
+          DiffAdd    = { bg = "#4c2e2e" },
+          DiffDelete = { bg = "#4c2e2e" },
+          DiffChange = { bg = "#4c3a2e" },
+          DiffText   = { bg = "#5c3030" },
+        },
+        proposed = {
+          DiffAdd    = { bg = "#2e4c2e" },
+          DiffDelete = { bg = "#4c2e2e" },
+          DiffChange = { bg = "#2e3c4c" },
+          DiffText   = { bg = "#3e5c3e" },
+        },
+        inline = {
+          added        = { bg = "#2e4c2e" },
+          removed      = { bg = "#4c2e2e" },
+          added_text   = { bg = "#3a6e3a" },
+          removed_text = { bg = "#6e3a3a" },
+        },
+      },
+    })
+<
+Option notes ~
+
+                                                   *code-preview-config-layout*
+diff.layout         "tab" (default) | "vsplit" | "inline". Selects how a
+                    preview is rendered. "tab" and "vsplit" use the
+                    side-by-side renderer; "inline" uses the unified-diff
+                    renderer (with `]c`/`[c` navigation).
+
+                                                  *code-preview-config-layouts*
+diff.layouts        Per-agent layout override, keyed by agent id:
+                    `claudecode`, `opencode`, `copilot`, `codex`. Any agent
+                    not listed falls back to `diff.layout`.
+                    Example: `layouts = { codex = "inline" }`.
+
+diff.visible_only   When true, suppress previews for files not visible in any
+                    Neovim window. Change indicators still fire. Toggle at
+                    runtime with `:CodePreviewToggleVisibleOnly`.
+
+diff.defer_claude_permissions
+                    Claude Code only. When true, the plugin does not force a
+                    review gate and defers to Claude Code's own permission
+                    settings.
+
+neo_tree            Soft dependency. If neo-tree is not installed these
+                    options are inert. `enabled = false` disables the
+                    integration entirely; `reveal = false` keeps the change
+                    indicators but stops scrolling the tree to the file.
+
+keys                Set any entry to false to skip that binding, or
+                    `keys = false` to skip them all. `<Plug>(CodePreviewCloseAll)`
+                    is always defined so it can be mapped manually: >lua
+                        vim.keymap.set("n", "<leader>x",
+                          "<Plug>(CodePreviewCloseAll)")
+<
+==============================================================================
+4. COMMANDS                                             *code-preview-commands*
+
+                                       *:CodePreviewInstallClaudeCodeHooks*
+:CodePreviewInstallClaudeCodeHooks
+                    Install Claude Code hooks to `.claude/settings.local.json`.
+
+                                     *:CodePreviewUninstallClaudeCodeHooks*
+:CodePreviewUninstallClaudeCodeHooks
+                    Remove Claude Code hooks (leaves other hooks intact).
+
+                                         *:CodePreviewInstallOpenCodeHooks*
+:CodePreviewInstallOpenCodeHooks
+                    Install the OpenCode plugin to `.opencode/plugins/`.
+
+                                       *:CodePreviewUninstallOpenCodeHooks*
+:CodePreviewUninstallOpenCodeHooks
+                    Remove the OpenCode plugin.
+
+                                        *:CodePreviewInstallCopilotCliHooks*
+:CodePreviewInstallCopilotCliHooks
+                    Install Copilot CLI hooks to
+                    `.github/hooks/code-preview.json`.
+
+                                      *:CodePreviewUninstallCopilotCliHooks*
+:CodePreviewUninstallCopilotCliHooks
+                    Remove Copilot CLI hooks.
+
+                                          *:CodePreviewInstallCodexCliHooks*
+:CodePreviewInstallCodexCliHooks
+                    Install Codex CLI hooks to `.codex/hooks.json`.
+
+                                        *:CodePreviewUninstallCodexCliHooks*
+:CodePreviewUninstallCodexCliHooks
+                    Remove Codex CLI hooks.
+
+                                                    *:CodePreviewCloseDiff*
+:CodePreviewCloseDiff
+                    Manually close the diff. Use after rejecting a change.
+
+                                                       *:CodePreviewStatus*
+:CodePreviewStatus
+                    Show socket path, hook status, and a dependency check.
+
+                                            *:CodePreviewToggleVisibleOnly*
+:CodePreviewToggleVisibleOnly
+                    Toggle `diff.visible_only` — show diffs only for files
+                    open in a visible window.
+
+                                                  *:checkhealth-code-preview*
+:checkhealth code-preview
+                    Full health check across all agents.
+
+==============================================================================
+5. KEYMAPS                                               *code-preview-keymaps*
+
+Defaults (all configurable via the `keys` table, see |code-preview-config|):
+
+  <leader>dq    global              Close the diff and clear indicators
+                                    (same as `:CodePreviewCloseDiff`).
+  ]c            inline diff buffer  Jump to the next change.
+  [c            inline diff buffer  Jump to the previous change.
+
+                                              *<Plug>(CodePreviewCloseAll)*
+A `<Plug>(CodePreviewCloseAll)` mapping is always defined, regardless of the
+`keys` config, so it can be bound manually even with `keys = false`.
+
+==============================================================================
+6. AGENTS                                                 *code-preview-agents*
+
+After |code-preview.setup()|, install hooks for your agent and restart its
+CLI. The diff/review experience is identical across agents.
+
+Claude Code ~
+    `:CodePreviewInstallClaudeCodeHooks`. No extra agent config required.
+
+OpenCode ~
+    `:CodePreviewInstallOpenCodeHooks`, then enable permission prompts in
+    `~/.config/opencode/opencode.json`:
+    `{ "permission": { "edit": "ask", "bash": "ask" } }`.
+
+GitHub Copilot CLI ~
+    `:CodePreviewInstallCopilotCliHooks`. No extra agent config required.
+
+OpenAI Codex CLI ~
+    `:CodePreviewInstallCodexCliHooks`, then make Codex ask before applying
+    edits in `.codex/config.toml` (or `~/.codex/config.toml`):
+    `approval_policy = "on-request"` and `sandbox_mode = "read-only"`.
+    Hooks are enabled by default in modern Codex.
+
+For architecture and internals, see CONTRIBUTING.md and CONTEXT.md in the
+repository root.
+
+vim:tw=78:ts=8:sw=8:noet:ft=help:norl: