diff --git a/README.md b/README.md
index cf30b64..d346be1 100644
--- a/README.md
+++ b/README.md
@@ -3,26 +3,48 @@
 [![CI](https://github.com/rishi-opensource/vim-claude-code/actions/workflows/ci.yml/badge.svg)](https://github.com/rishi-opensource/vim-claude-code/actions/workflows/ci.yml)
 [![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](CHANGELOG.md)
 
-A Vim plugin that integrates the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI directly into your editor. Run Claude Code in a managed terminal, send code context with a single keystroke, and get automatic file reloading when Claude edits your files — all without leaving Vim.
+**AI-powered coding, inside Vim. No context switching.**
 
-## Features
+`vim-claude-code` brings [Claude Code](https://docs.anthropic.com/en/docs/claude-code) directly into your editor. Fix bugs, write tests, review diffs, generate commits, and refactor code — all without leaving Vim.
 
-- **One-key toggle** — Open and close Claude Code with `<C-\>`
-- **22 sub-commands** — Explain, fix, refactor, test, document, commit, review, and more
-- **Selection-aware** — Commands use visual selection when active, otherwise detect the current function
-- **Multiple window layouts** — Right split (default), bottom split, top split, floating popup, or dedicated tab
-- **Automatic file refresh** — Buffers reload when Claude modifies files on disk
-- **Git-aware** — Starts Claude at the repository root; separate sessions per repo
-- **Diff preview** — Side-by-side diff tab when Claude proposes file edits (Edit, Write, MultiEdit)
-- **Health check** — `:Claude doctor` verifies your environment before you start
-- **Configurable** — 20+ `g:` variables with buffer-local overrides
+One keypress opens Claude in a split panel. Another hides it. Your session persists across toggles. Claude edits your files; your buffers reload automatically. You stay in flow.
+
+## Why vim-claude-code?
+
+Most AI coding tools pull you out of your editor — into a browser, a chat window, or a separate terminal. `vim-claude-code` keeps everything inside Vim:
+
+- **No copy-pasting** — commands automatically capture your visual selection or current function
+- **No tab switching** — Claude runs in a managed split, toggled with a single key
+- **No blind edits** — every file change Claude proposes shows up as a reviewable diff before anything is written to disk
+- **No workflow interruption** — buffers reload automatically when Claude modifies files
 
 ## Demos
 
 ![vim-claude-code highlight reel](assets/00-highlight-reel.gif)
 
-> **Key features in one clip** — toggle, fix, test generation, explain, git workflow, command discovery, and refactor.
-> See [DEMO.md](doc/DEMO.md) for individual walkthroughs of other features.
+> Toggle, fix bugs, generate tests, explain code, git workflows, diff preview, terminal zoom, and more — all from within Vim.
+> See [DEMO.md](doc/DEMO.md) for individual feature walkthroughs.
+
+## Features at a Glance
+
+### Stay in Flow
+- **One-key toggle** — `<C-\>` opens and hides Claude. Session persists across toggles.
+- **Terminal Zoom** — Maximize Claude to full-screen with `<C-w>z`, tmux-style. Restore your split instantly.
+- **Auto file refresh** — Buffers reload when Claude edits your files. No manual `:e` needed.
+- **Multiple layouts** — Right split (default), bottom, top, left, floating popup, or dedicated tab.
+
+### Context-Aware Commands
+- **Selection-aware** — Commands use your visual selection when active, otherwise detect the current function automatically.
+- **22 sub-commands** — Explain, fix, refactor, test, document, commit, review, rename, optimize, debug, and more. All tab-completable.
+- **Git-aware** — Claude starts at your repo root. Separate sessions per repository.
+
+### Review Before Claude Writes
+- **Diff preview** — Every file edit Claude proposes opens a side-by-side diff tab. Review what changes, then accept or reject. You stay in control.
+
+### Full Git Workflow
+- **Commit messages** — Generated from your staged diff, with conventional commit support.
+- **Code review** — Claude reviews your current diff with configurable strictness and security checks.
+- **PR descriptions** — Generated from your branch changes without leaving the editor.
 
 ## Requirements
 
@@ -34,8 +56,7 @@ A Vim plugin that integrates the [Claude Code](https://docs.anthropic.com/en/doc
 ## Installation
 
 > **Stable release — v1.4.0**
-> Pin to the latest stable release using the examples below, or omit the tag
-> to always track the latest commit on `main`.
+> Pin to the latest stable release using the examples below, or omit the tag to always track `main`.
 
 ### [vim-plug](https://github.com/junegunn/vim-plug)
 ```vim
@@ -57,33 +78,42 @@ Plugin 'rishi-opensource/vim-claude-code'
 
 ### [pathogen](https://github.com/tpope/vim-pathogen)
 ```sh
-git clone --branch v1.4.0 https://github.com/rishi-opensource/vim-claude-code.git
+git clone --branch v1.4.0 https://github.com/rishi-opensource/vim-claude-code.git ~/.vim/bundle/vim-claude-code
 ```
 
 ### Native packages (Vim 8+)
 ```sh
 mkdir -p ~/.vim/pack/plugins/start
-git clone --branch v1.4.0 https://github.com/rishi-opensource/vim-claude-code.git
+git clone --branch v1.4.0 https://github.com/rishi-opensource/vim-claude-code.git ~/.vim/pack/plugins/start/vim-claude-code
 ```
 
 ## Quick Start
 
-Run `:Claude` or press `<C-\>` to open Claude Code. Press it again to hide; again to restore. The session persists.
-
-All sub-commands are tab-completable:
-```
-:Claude <Tab>
+**1. Open Claude:**
+```vim
+:Claude
+" or press <C-\>
 ```
 
-Run a health check to verify your setup:
+**2. Run a health check:**
 ```vim
 :Claude doctor
 ```
+This reports `[OK]` / `[FAIL]` for every dependency and tells you exactly what to fix.
+
+**3. Explore commands with tab completion:**
+```vim
+:Claude <Tab>
+```
+
+The Claude session persists — toggling with `<C-\>` hides and restores the same session.
 
 ## Commands
 
 ### Terminal
 
+*Open, hide, and manage the Claude terminal session.*
+
 | Command | Description |
 |---|---|
 | `:Claude` | Toggle the Claude Code terminal |
@@ -93,6 +123,8 @@ Run a health check to verify your setup:
 
 ### Code Intelligence
 
+*Commands work on your visual selection when active, or auto-detect the current function.*
+
 | Command | Flags | Description |
 |---|---|---|
 | `:Claude explain` | `--brief`, `--detailed` | Explain selected code or current function |
@@ -101,7 +133,9 @@ Run a health check to verify your setup:
 | `:Claude test` | `--framework {name}`, `--edge-cases` | Generate unit tests |
 | `:Claude doc` | `--inline`, `--markdown` | Generate documentation |
 
-### Git
+### Git Workflow
+
+*From staged diff to commit message to PR description — without opening a browser.*
 
 | Command | Flags | Description |
 |---|---|---|
@@ -111,53 +145,91 @@ Run a health check to verify your setup:
 
 ### Architecture & Planning
 
+*Think through larger problems with Claude before writing code.*
+
 | Command | Description |
 |---|---|
-| `:Claude plan` | Generate implementation plan for current file |
-| `:Claude analyze` | Analyze for complexity, performance, and security |
+| `:Claude plan` | Generate an implementation plan for the current file |
+| `:Claude analyze` | Analyze for complexity, performance, and security issues |
 
-### Workflow
+### Workflow Utilities
+
+*Direct in-editor actions — apply suggestions, debug errors, rename symbols, or zoom the terminal.*
 
 | Command | Description |
 |---|---|
 | `:Claude rename` | Suggest better variable/function names |
 | `:Claude optimize` | Optimize code for performance |
-| `:Claude debug` | Analyze error on current line |
+| `:Claude debug` | Analyze the error on the current line |
 | `:Claude apply` | Apply Claude's last suggestion to the file (prompts for confirmation) |
+| `:Claude zoom` | Toggle full-screen (zoom) mode for the Claude terminal |
 
-### Diff Preview
+### Meta
 
 | Command | Description |
 |---|---|
-| `:Claude preview install` | Register diff preview hooks in `.claude/settings.local.json` |
-| `:Claude preview uninstall` | Remove diff preview hooks |
-| `:Claude preview close` | Manually close an open diff tab |
-| `:Claude preview status` | Show diff preview status and dependency checks |
-| `:Claude zoom` | Toggle full-screen (zoom) mode for the terminal |
+| `:Claude chat` | Send a free-form message with current file context |
+| `:Claude context` | Preview what context will be sent to Claude |
+| `:Claude model [name]` | Switch model (`sonnet`, `opus`, `haiku`) |
+
+### Utility
+
+| Command | Description |
+|---|---|
+| `:Claude version` | Show plugin version, Vim version, Claude CLI version, and terminal support |
+| `:Claude doctor` | Health check: verifies Claude CLI, Git, terminal support, and Vim version |
+
+## Reviewing Claude's Edits — Diff Preview
+
+![diff preview demo](assets/16-diff-preview.gif)
+
+When Claude proposes changes to a file, a **side-by-side diff tab opens automatically** before anything is written to disk:
+
+```
+  [current file]    │    [proposed changes]
+```
+
+Review exactly what Claude wants to change, then use these keys in the diff tab:
 
-When enabled, every time Claude proposes a file edit (Edit, Write, or MultiEdit), a side-by-side diff tab opens showing the **current** file on the left and the **proposed** changes on the right. Review the diff, then accept or reject in the Claude terminal. Press `q` to close the diff tab.
+| Key | Action |
+|---|---|
+| `ga` | Accept — send `y` to Claude, apply the change |
+| `gr` | Reject — send `n` to Claude, discard the change |
+| `q` | Close the diff tab without responding |
 
-Requires `python3`. Optionally uses Vim `+clientserver` for instant diffs (falls back to file-based polling).
+**Enable diff preview for your project:**
+```vim
+:Claude preview install
+```
 
-Auto-enable on startup:
+This registers Claude Code hooks in `.claude/settings.local.json`. To auto-enable on every Vim startup:
 ```vim
 let g:claude_code_diff_preview = 1
 ```
 
-### Meta
+**Diff preview commands:**
 
 | Command | Description |
 |---|---|
-| `:Claude chat` | Send a free-form message with current file context |
-| `:Claude context` | Preview what context will be sent to Claude |
-| `:Claude model [name]` | Switch model (`sonnet`, `opus`, `haiku`) |
+| `:Claude preview install` | Register diff preview hooks in `.claude/settings.local.json` |
+| `:Claude preview uninstall` | Remove diff preview hooks |
+| `:Claude preview close` | Manually close an open diff tab |
+| `:Claude preview status` | Show diff preview status and dependency checks |
 
-### Utility
+Requires `python3`. Uses Vim `+clientserver` for instant diffs when available, falls back to polling.
 
-| Command | Description |
-|---|---|
-| `:Claude version` | Show plugin version, Vim version, Claude CLI version, and terminal support |
-| `:Claude doctor` | Health check: verifies Claude CLI, Git, terminal support, and Vim version |
+## Full-Screen Focus — Terminal Zoom
+
+![zoom demo](assets/17-terminal-zoom.gif)
+
+Working through a complex problem? Press `<C-w>z` inside the Claude terminal to **maximize it full-screen** — just like tmux's zoom. Press again to restore your split layout.
+
+This is especially useful when Claude is generating a long response and you want to read it without distractions.
+
+```vim
+" Customize the zoom key
+let g:claude_code_map_zoom = '<C-w>z'
+```
 
 ## Keymaps
 
@@ -194,21 +266,21 @@ let g:claude_code_map_keys = 0
 let g:claude_code_map_extended_keys = 0
 ```
 
-## Window Modes
+## Window Layouts
 
-Set `g:claude_code_position` to one of:
+Set `g:claude_code_position` to match your preferred workflow:
 
 | Value | Layout |
 |---|---|
+| `'right'` | Vertical split on the right (default) |
 | `'bottom'` | Horizontal split at the bottom |
 | `'top'` | Horizontal split at the top |
 | `'left'` | Vertical split on the left |
-| `'right'` | Vertical split on the right (default) |
 | `'float'` | Floating popup (requires `+popupwin`) |
 | `'tab'` | Dedicated tab page |
 
 ```vim
-" Bottom split at 30% (override the default right split)
+" Bottom split at 30%
 let g:claude_code_position   = 'bottom'
 let g:claude_code_split_ratio = 0.3
 
@@ -251,47 +323,6 @@ let g:claude_code_float_border = 'double'
 
 Buffer-local `b:claude_code_*` overrides take precedence over `g:` variables.
 
-## Plugin Structure
-
-```
-vim-claude-code/
-├── plugin/
-│   └── claude_code.vim           # Entry point: command + keymaps
-├── autoload/
-│   └── claude_code/
-│       ├── config.vim            # Configuration defaults + get/set
-│       ├── terminal.vim          # Terminal lifecycle (create/toggle/close)
-│       ├── terminal_bridge.vim   # Terminal lookup and prompt dispatch
-│       ├── window.vim            # Window layout utilities
-│       ├── git.vim               # Git root detection with caching
-│       ├── keymaps.vim           # Terminal-local keymaps
-│       ├── refresh.vim           # File change detection and reload
-│       ├── util.vim              # Shared helpers (selection, context, error, debug)
-│       ├── commands.vim          # explain, fix, refactor, test, doc
-│       ├── git_commands.vim      # commit, review, pr
-│       ├── arch_commands.vim     # plan, analyze
-│       ├── workflow_commands.vim # rename, optimize, debug, apply
-│       ├── meta_commands.vim     # chat, context, model, version, doctor
-│       └── diff.vim              # Diff preview display, polling, hook management
-├── bin/
-│   ├── vim-preview-diff.py       # PreToolUse hook script computes proposed diffs
-│   └── vim-close-diff.py         # PostToolUse hook script
-├── test/
-│   ├── vimrc                     # Minimal vimrc for test runner
-│   └── test_dispatch.vader       # Vader test suite
-├── .github/
-│   └── workflows/
-│       └── ci.yml                # GitHub Actions CI (Vim 8 + Vim 9)
-└── doc/
-    └── claude_code.txt           # :help documentation
-```
-
-## Help
-
-```vim
-:help claude-code
-```
-
 ## Troubleshooting
 
 **Run the health check first:**
@@ -302,42 +333,21 @@ This reports `[OK]` / `[FAIL]` for each dependency and tells you exactly what to
 
 ---
 
-**E117: Unknown function** — Run `:helptags ALL` then restart Vim. Ensure the
-plugin directory is on your `runtimepath`.
+**E117: Unknown function** — Run `:helptags ALL` then restart Vim. Ensure the plugin directory is on your `runtimepath`.
 
-**Terminal does not open** — Verify `vim --version | grep +terminal`. The plugin
-requires Vim compiled with `+terminal`. Run `:Claude doctor` to confirm.
+**Terminal does not open** — Verify `vim --version | grep +terminal`. The plugin requires Vim compiled with `+terminal`.
 
-**Claude not found** — Ensure `claude` is in `$PATH`: `which claude`. Run
-`:Claude doctor` to confirm.
+**Claude not found** — Ensure `claude` is in `$PATH`: `which claude`.
 
-**File changes not detected** — Check `g:claude_code_refresh_enable` is `1` and
-that `autoread` is not globally disabled in your vimrc.
+**File changes not detected** — Check `g:claude_code_refresh_enable` is `1` and that `autoread` is not globally disabled in your vimrc.
 
 **Debug logging** — Enable verbose output to diagnose issues:
 ```vim
 let g:claude_code_debug = 1
 ```
-All internal events (dispatch, terminal launch, git calls, refresh) will be
-printed to the message area. Disable again with `let g:claude_code_debug = 0`.
-
-## 🚧 Roadmap
-
-### v1.x
-
-- UX improvements and workflow refinements
-- Add more intelligent `:Claude` subcommands
-- Improve diagnostics and configuration options
-
-### v2.0
-
-- Official Neovim support
-- Improved terminal/window handling
-- Floating window UI (Neovim)
-
-## Releases
+All internal events (dispatch, terminal launch, git calls, refresh) will be printed to the message area.
 
-This project utilizes [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and changelog generation. For details on how commit messages trigger releases, see [doc/RELEASING.md](doc/RELEASING.md).
+For full in-editor documentation, run `:help claude-code`.
 
 ## License
 
@@ -345,4 +355,4 @@ MIT — see [LICENSE](LICENSE).
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for full details.
+See [CHANGELOG.md](CHANGELOG.md) for full details. This project uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning. See [doc/RELEASING.md](doc/RELEASING.md) for details.
diff --git a/assets/00-highlight-reel.gif b/assets/00-highlight-reel.gif
index ea233de..e697e3b 100644
Binary files a/assets/00-highlight-reel.gif and b/assets/00-highlight-reel.gif differ
diff --git a/assets/01-toggle-terminal.gif b/assets/01-toggle-terminal.gif
index 0548eef..7372fcc 100644
Binary files a/assets/01-toggle-terminal.gif and b/assets/01-toggle-terminal.gif differ
diff --git a/assets/02-fix-bugs.gif b/assets/02-fix-bugs.gif
index 2e7a11a..acf9771 100644
Binary files a/assets/02-fix-bugs.gif and b/assets/02-fix-bugs.gif differ
diff --git a/assets/03-visual-select-test.gif b/assets/03-visual-select-test.gif
index e00c923..9d5ddc5 100644
Binary files a/assets/03-visual-select-test.gif and b/assets/03-visual-select-test.gif differ
diff --git a/assets/04-git-workflow.gif b/assets/04-git-workflow.gif
index 176cbbd..b306fb0 100644
Binary files a/assets/04-git-workflow.gif and b/assets/04-git-workflow.gif differ
diff --git a/assets/05-command-discovery.gif b/assets/05-command-discovery.gif
index 2a634cc..08fcd04 100644
Binary files a/assets/05-command-discovery.gif and b/assets/05-command-discovery.gif differ
diff --git a/assets/06-explain-code.gif b/assets/06-explain-code.gif
index 9353cc9..96c1ee6 100644
Binary files a/assets/06-explain-code.gif and b/assets/06-explain-code.gif differ
diff --git a/assets/07-refactor-extract.gif b/assets/07-refactor-extract.gif
index 270c576..8f59488 100644
Binary files a/assets/07-refactor-extract.gif and b/assets/07-refactor-extract.gif differ
diff --git a/assets/08-window-layouts.gif b/assets/08-window-layouts.gif
index 3fa1bb7..9cbe267 100644
Binary files a/assets/08-window-layouts.gif and b/assets/08-window-layouts.gif differ
diff --git a/assets/09-doctor-healthcheck.gif b/assets/09-doctor-healthcheck.gif
index 383c723..03c5b1d 100644
Binary files a/assets/09-doctor-healthcheck.gif and b/assets/09-doctor-healthcheck.gif differ
diff --git a/assets/10-chat-freeform.gif b/assets/10-chat-freeform.gif
index 9a60650..60e7516 100644
Binary files a/assets/10-chat-freeform.gif and b/assets/10-chat-freeform.gif differ
diff --git a/assets/11-multi-instance.gif b/assets/11-multi-instance.gif
index e794517..7ba6dfe 100644
Binary files a/assets/11-multi-instance.gif and b/assets/11-multi-instance.gif differ
diff --git a/assets/12-auto-refresh.gif b/assets/12-auto-refresh.gif
index 6c04b3a..04d6ed2 100644
Binary files a/assets/12-auto-refresh.gif and b/assets/12-auto-refresh.gif differ
diff --git a/assets/13-review-security.gif b/assets/13-review-security.gif
index 7eda732..d84260d 100644
Binary files a/assets/13-review-security.gif and b/assets/13-review-security.gif differ
diff --git a/assets/14-analyze-complexity.gif b/assets/14-analyze-complexity.gif
index 21c5661..c71217c 100644
Binary files a/assets/14-analyze-complexity.gif and b/assets/14-analyze-complexity.gif differ
diff --git a/assets/15-doc-generation.gif b/assets/15-doc-generation.gif
index e0f4f52..e5d620b 100644
Binary files a/assets/15-doc-generation.gif and b/assets/15-doc-generation.gif differ
diff --git a/assets/16-diff-preview.gif b/assets/16-diff-preview.gif
new file mode 100644
index 0000000..689667c
Binary files /dev/null and b/assets/16-diff-preview.gif differ
diff --git a/assets/17-terminal-zoom.gif b/assets/17-terminal-zoom.gif
new file mode 100644
index 0000000..1e13b03
Binary files /dev/null and b/assets/17-terminal-zoom.gif differ