diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..e50001077
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,112 @@
+# Contributing
+
+Small, focused changes are easiest to review. For a bug report, start with
+[Troubleshooting](docs/troubleshooting.md#reporting-a-bug). For a feature or
+architecture change, describe the workflow first so we can agree on its scope.
+
+## Development
+
+Run commands from the repository root. `make help` lists targets and examples.
+
+| Command | Purpose |
+| --- | --- |
+| `make check` | Formatting checks, Lua type checks, and all tests |
+| `make format-check` | Check Lua formatting without changing files |
+| `make typecheck` | Check Lua types |
+| `make test` | Run all tests |
+| `make test-minimal` / `make test-unit` | Run a smaller suite |
+| `make test-replay` | Run V1/V2 snapshot replay tests |
+| `make replay` | Launch the interactive replay tester |
+| `make replay-regenerate` | Regenerate expected snapshots with confirmation |
+| `make topology` | Scan dependency topology |
+| `make topology-diff` | Compare dependency topology snapshots |
+
+Use `TEST` for a suite or file, `FILTER` for test-name filtering, and `ARGS` for
+underlying tool options:
+
+```sh
+make test TEST=tests/unit/formatter_spec.lua
+make test TEST=unit FILTER="Timer"
+make typecheck ARGS="-f github"
+make replay ARGS="-c ReplayAll"
+make replay-regenerate FILE=v2/formatters.json
+make topology ARGS="--json"
+make topology-diff ARGS="--from main --to HEAD --json"
+```
+
+For replay regeneration, `FILE` is relative to `tests/data`. See
+[dependency topology docs](scripts/dependency-topology/README.md) for scanner
+options and policy details.
+
+Read [`AGENTS.md`](AGENTS.md) and any instructions in the directory you change.
+For Lua changes, format **changed files only** with `stylua`, run
+`make format-check`, and get `make typecheck` to zero errors. Run relevant tests
+and report missing tools or unrelated failures rather than silently fixing
+unrelated files. `make format` formats the whole project; do not use it for a
+small patch.
+
+## Documentation
+
+Documentation lives in this repository, not a wiki. Update it in the same PR as
+the code it describes.
+
+### Where a change belongs
+
+- **README:** what the plugin does, installation, a quick start, and links.
+  No defaults table or full action list.
+- **Guides in `docs/`:** explain a task in the order someone performs it.
+- **Reference pages:** exact settings, command/API contracts, and caveats.
+- **Recipes:** optional, self-contained workflows with prerequisites and undo
+  instructions. Start from the [template](docs/recipes/TEMPLATE.md).
+- **`doc/opencode.txt`:** a short `:help` entry point that points to `docs/`.
+
+### Writing and examples
+
+Write for someone in the middle of a task. Say what to press and what happens.
+Skip adjectives like “seamless” or “powerful”; an example says more. Label
+experimental and V1-only behavior in the section that describes it.
+
+Describe what the user sees, not how the code works. Internal names, state
+fields, and protocol details belong in code comments or the PR description.
+Add a warning only when an action can lose work or leak data, and say it once.
+
+Check defaults and keys against [`config.lua`](lua/opencode/config.lua), API
+names against [`api.lua`](lua/opencode/api.lua), and commands against their
+[handlers](lua/opencode/commands/handlers). The full defaults table lives only in
+[`docs/configuration.md`](docs/configuration.md); update it when `config.lua`
+changes. Provider, agent, and server settings belong to OpenCode, so link to its
+docs instead of repeating them.
+
+Lua examples should run as pasted. Say whether a block goes in a lazy.nvim spec
+or in `setup()`. When showing a remap, disable the old key explicitly.
+
+### Screenshots and videos
+
+Capture the real plugin, not a mockup:
+
+- Use a small project with readable code. Keep one theme and font size across
+  a set of images, and crop empty space rather than context.
+- Show the action and its result. Cut install waits and long model thinking;
+  aim for 15–30 seconds per clip.
+- Remove secrets, personal paths, private prompts, and URLs that contain
+  credentials. `<leader>oDu` copies such a URL.
+- Write alt text that describes what the image shows. Give a video a one-line
+  summary in the surrounding text.
+- Upload recordings as GitHub attachments and put the URL on its own line
+  instead of using a `<video>` tag. Small, stable images can go in `docs/assets/`.
+- Do not add a screenshot that shows the same state as an existing one.
+
+Missing media is better than a broken link. If a page needs a capture you
+cannot make, describe it in the PR instead of adding a placeholder.
+
+### Before submitting a docs change
+
+- Preview Markdown on GitHub or a compatible renderer.
+- Check relative links, heading anchors, and code fences.
+- Compare commands, keys, API names, and defaults with the current source.
+- Test executable examples where practical; note anything not exercised.
+- For vimdoc edits, run `:helptags doc` in a checkout and open `:help opencode.nvim`.
+  Do not commit generated `doc/tags`.
+
+Docs-only changes do not need the test suite. In the PR, say which examples you
+ran and which you only read through.
diff --git a/README.md b/README.md
index 3580f3f18..bb1a2f097 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # 🤖 opencode.nvim
 
-> neovim frontend for opencode - a terminal-based AI coding agent
+A Neovim frontend for [OpenCode](https://opencode.ai). Chat with the agent in a
+side panel, send it files, selections, and diagnostics, and review its edits
+without leaving the editor.
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/sst/opencode/dev/packages/web/src/assets/logo-ornate-dark.svg" alt="Opencode logo" width="30%" />
-</div>
+---
 
 <div align="center">
 
@@ -12,1537 +12,105 @@
 [![GitHub stars](https://img.shields.io/github/stars/sudo-tee/opencode.nvim?style=for-the-badge)](https://github.com/sudo-tee/opencode.nvim/stargazers)
 ![Last Commit](https://img.shields.io/github/last-commit/sudo-tee/opencode.nvim?style=for-the-badge)
 
-<a href="https://www.buymeacoffee.com/sudo.tee"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" height="20px"></a>
+<a href="https://www.buymeacoffee.com/sudo.tee"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" height="30px"></a>
 
 </div>
 
-## ✨ Description
-
-> [!IMPORTANT]
->
-> ### OpenCode V1 and V2 support
->
-> This implementation supports OpenCode V1 and V2 through automatic protocol detection and includes a major internal rewrite.
->
-> To keep using the legacy plugin implementation, pin the [`v1` branch](https://github.com/sudo-tee/opencode.nvim/tree/v1):
->
-> ```lua
-> { "sudo-tee/opencode.nvim", branch = "v1" }
-> ```
->
-> The `v1` branch is a legacy implementation, not a requirement for connecting to an OpenCode V1 server.
-
-This plugin provides a bridge between neovim and the [opencode](https://github.com/sst/opencode) AI agent, creating a chat interface while capturing editor context (current file, selections) to enhance your prompts. It maintains persistent sessions tied to your workspace, allowing for continuous conversations with the AI assistant similar to what tools like Cursor AI offer.
-
-## Main Features
-
-### Chat Panel
-
-The chat panel is a dedicated window inside Neovim that lets you hold a persistent conversation with the opencode AI agent. It displays your previous messages and responses, and automatically uses your current workspace and editor state as context so you can iterate on code without leaving Neovim. You can type prompts, review answers, and navigate back to your code buffer while keeping the ongoing chat session open.
-
 <div align="center">
-  <img src="https://github.com/user-attachments/assets/197d69ba-6db9-4989-97ff-557c89000cf5">
-</div>
-
-### Quick buffer chat (<leader>o/) EXPERIMENTAL
-
-This is an experimental feature that allows you to chat with the AI using the current buffer context. In visual mode, it captures the selected text as context, while in normal mode, it uses the current line. The AI will respond with quick edits to the files that are applied by the plugin.
-
-Don't hesitate to give it a try and provide feedback!
 
-Refer to the [Quick Chat](#-quick-chat) section for more details.
-
-<div align="center">
-  <img src="https://i.imgur.com/5JNlFZn.png">
+![OpenCode chat panel beside a code buffer](https://github.com/user-attachments/assets/42da57f3-86b6-4409-b612-12c31fb1873f)
 </div>
 
-## 📑 Table of Contents
-
-- [⚠️Caution](#caution)
-- [Requirements](#-requirements)
-- [Installation](#-installation)
-- [Configuration](#️-configuration)
-- [Usage](#-usage)
-- [Permissions](#-permissions)
-- [Context](#-context)
-- [Agents](#-agents)
-- [Custom/External Server Configuration](#-customexternal-server-configuration)
-- [User Commands and Slash Commands](#user-commands-and-slash-commands)
-- [Contextual Actions for Snapshots](#-contextual-actions-for-snapshots)
-- [Contextual Restore points](#-contextual-restore-points)
-- [Highlight Groups](#highlight-groups)
-- [Prompt Guard](#️-prompt-guard)
-- [Custom user hooks](#-custom-user-hooks)
-- [Server-Sent Events (SSE) autocmds](#-server-sent-events-sse-autocmds)
-- [Quick Chat](#quick-chat)
-- [Setting up Opencode](#-setting-up-opencode)
-- [Recipes](./docs/recipes)
-- [Development](#development)
-
-## ⚠️Caution
-
-This plugin is in early development and may have bugs and breaking changes. It is not recommended for production use yet. Please report any issues you encounter on the [GitHub repository](https://github.com/sudo-tee/opencode.nvim/issues).
-
-[Opencode](https://github.com/sst/opencode) is also in early development and may have breaking changes. Ensure you are using a compatible version of the Opencode CLI (v0.6.3+ or more).
-
-If your upgrade breaks the plugin, please open an issue or downgrade to the last working version.
+## Features
 
-## 📋 Requirements
+- [Chat panel](docs/usage.md#move-between-code-and-conversation) with separate
+  input and output buffers, [prompt history](docs/usage.md#prompt-history), and
+  [Markdown rendering](docs/usage.md#markdown-rendering).
+- [Context](docs/context.md) from the current file,
+  [visual selections](docs/context.md#add-a-selection),
+  [`@` file mentions](docs/context.md#mention-files-and-agents), diagnostics,
+  and [clipboard images](docs/context.md#attach-an-image).
+- [Multiple sessions](docs/usage.md#sessions-and-panel-tabs), each in its own
+  panel tab, plus a session picker and
+  [timeline](docs/usage.md#timeline-and-session-tree) with undo and fork.
+- [Session diff review](docs/review.md) with
+  [inline comments](docs/review.md#leave-inline-feedback) that go into your next
+  prompt (OpenCode V2).
+- [Quick chat](docs/quick-chat.md) for one-off edits on the
+  current line or selection (experimental).
 
-- Opencode (v0.6.3+ or more) CLI installed and available (see [Setting up opencode](#-setting-up-opencode) below)
+Works with OpenCode V1 and V2 servers; the protocol is detected automatically.
+The `v1` branch keeps the old plugin code and is not needed for a V1 server.
+See [Compatibility](docs/compatibility.md).
 
-## 🚀 Installation
+## Install
 
-Install the plugin with your favorite package manager. See the [Configuration](#️-configuration) section below for customization options.
+Requires Neovim 0.10.3 or later and the `opencode` CLI on your `PATH`, with a
+provider already connected (run `opencode` and use `/connect`).
 
-To keep using the legacy implementation instead, add `branch = "v1"` to your plugin specification.
-
-### With lazy.nvim
+With [lazy.nvim](https://github.com/folke/lazy.nvim):
 
 ```lua
-{
-  "sudo-tee/opencode.nvim",
-  config = function()
-    require("opencode").setup({})
-  end,
+return {
+  'sudo-tee/opencode.nvim',
   dependencies = {
+    -- Optional: choose a picker you already use, or keep vim.ui.select.
+    -- 'folke/snacks.nvim',
+    -- 'nvim-telescope/telescope.nvim',
+    -- 'ibhagwan/fzf-lua',
+    -- 'nvim-mini/mini.pick',
+    -- Optional: use your configured completion engine, or built-in completion.
+    -- 'saghen/blink.cmp',
+    -- 'hrsh7th/nvim-cmp',
     {
-      "MeanderingProgrammer/render-markdown.nvim",
+      'MeanderingProgrammer/render-markdown.nvim',
       opts = {
         anti_conceal = { enabled = false },
         file_types = { 'markdown', 'opencode_output' },
       },
-      ft = { 'markdown', 'Avante', 'copilot-chat', 'opencode_output' },
-    },
-    -- Optional, for file mentions and commands completion, pick only one
-    'saghen/blink.cmp',
-    -- 'hrsh7th/nvim-cmp',
-
-    -- Optional, for file mentions picker, pick only one
-    'folke/snacks.nvim',
-    -- 'nvim-telescope/telescope.nvim',
-    -- 'ibhagwan/fzf-lua',
-    -- 'nvim_mini/mini.nvim',
-  },
-}
-```
-
-## ⚙️ Configuration
-
-```lua
--- Default configuration with all available options
-require('opencode').setup({
-  preferred_picker = nil, -- 'telescope'/'telescope.nvim', 'fzf'/'fzf-lua', 'mini.pick', 'snacks'/'snacks.nvim', 'select', if nil, it will use the best available picker. Note mini.pick does not support multiple selections
-  preferred_completion = nil, -- 'blink', 'nvim-cmp','vim_complete' if nil, it will use the best available completion
-  default_global_keymaps = true, -- If false, disables all default global keymaps
-  default_mode = 'build', -- 'build' or 'plan' or any custom configured. @see [OpenCode Agents](https://opencode.ai/docs/modes/)
-  default_system_prompt = nil, -- Custom system prompt to use for all sessions. If nil, uses the default built-in system prompt
-  keymap_prefix = '<leader>o', -- Default keymap prefix for global keymaps change to your preferred prefix and it will be applied to all keymaps starting with <leader>o
-  opencode_executable = 'opencode', -- Name of your opencode binary
-  snapshot_path = nil, -- Override base path for the snapshot git directory (default: $XDG_DATA_HOME/opencode). Appends /snapshot/<project_id>/<worktree_hash>
-
-  -- Server configuration for custom/external opencode servers
-  server = {
-    url = nil,             -- URL/hostname (e.g., 'http://192.168.1.100', 'localhost', 'https://myserver.com')
-    port = nil,            -- Port number (e.g., 8080), 'auto' for random port
-    timeout = 5,           -- Health check timeout in seconds when connecting
-    spawn_command = nil,   -- Optional function to start the server: function(port, url) ... end
-    auto_kill = true,      -- Kill spawned servers when last nvim instance exits (default: true) Only applies to servers spawned by the plugin with spawn_command/kill_command
-    path_map = nil,        -- Map host paths to server paths: string ('/app') or function(path) -> string
-    username = nil,        -- Username for Basic auth. Falls back to OPENCODE_SERVER_USERNAME env var, then "opencode"
-    password = nil,        -- Password for Basic auth. Falls back to OPENCODE_SERVER_PASSWORD env var
-    password_file = nil,   -- Shared V1 password file; fixed ports default to an owner-only per-port state file
-  },
-
-  keymap = {
-    -- Session diff mappings are buffer-local. g? opens help showing active mappings.
-    -- Set old keys to false when remapping.
-    session_diff = {
-      list = { ['p'] = false, ['v'] = { 'toggle_view' }, ['g?'] = false, ['?'] = { 'toggle_help' } },
-      messages = { ['f'] = false, ['s'] = { 'mark_from' } },
-      preview = { ['p'] = false, ['v'] = { 'toggle_view' } },
-      comment = { ['<C-s>'] = { 'submit_comment', mode = { 'n', 'i' } } },
-      message_preview = { ['q'] = false, ['x'] = { 'hide_message_preview' } },
-    },
-    editor = {
-      ['<leader>og'] = { 'toggle' }, -- Open opencode. Close if opened
-      ['<leader>oi'] = { 'open_input' }, -- Opens and focuses on input window on insert mode
-      ['<leader>oI'] = { 'open_input_new_session' }, -- Opens and focuses on input window on insert mode. Creates a new session
-      ['<leader>oo'] = { 'open_output' }, -- Opens and focuses on output window
-      ['<leader>ot'] = { 'toggle_focus' }, -- Toggle focus between opencode and last window
-      ['<leader>oT'] = { 'timeline' }, -- Display timeline picker to navigate/undo/redo/fork messages
-      ['<leader>oq'] = { 'close' }, -- Close UI windows
-      ['<leader>os'] = { 'select_session' }, -- Select and load a opencode session
-      ['<leader>oR'] = { 'rename_session' }, -- Rename current session
-      ['<leader>op'] = { 'configure_provider' }, -- Quick provider and model switch from predefined list
-      ['<leader>oV'] = { 'configure_variant' }, -- Switch model variant for the current model
-      ['<leader>oy'] = { 'add_visual_selection', mode = {'v'} },
-      ['<leader>oY'] = { 'add_visual_selection_inline', mode = {'v'} }, -- Insert visual selection as inline code block in the input buffer
-      ['<leader>oz'] = { 'toggle_zoom' }, -- Zoom in/out on the Opencode windows
-      ['<leader>ov'] = { 'paste_image'}, -- Paste image from clipboard into current session
-      ['<leader>od'] = { 'diff_open' }, -- Opens a diff tab of a modified file since the last opencode prompt
-      ['<leader>o]'] = { 'diff_next' }, -- Navigate to next file diff
-      ['<leader>o['] = { 'diff_prev' }, -- Navigate to previous file diff
-      ['<leader>oc'] = { 'diff_close' }, -- Close diff view tab and return to normal editing
-      ['<leader>ora'] = { 'diff_revert_all_last_prompt' }, -- Revert all file changes since the last opencode prompt
-      ['<leader>ort'] = { 'diff_revert_this_last_prompt' }, -- Revert current file changes since the last opencode prompt
-      ['<leader>orA'] = { 'diff_revert_all' }, -- Revert all file changes since the last opencode session
-      ['<leader>orT'] = { 'diff_revert_this' }, -- Revert current file changes since the last opencode session
-      ['<leader>orr'] = { 'diff_restore_snapshot_file' }, -- Restore a file to a restore point
-      ['<leader>orR'] = { 'diff_restore_snapshot_all' }, -- Restore all files to a restore point
-      ['<leader>ox'] = { 'swap_position' }, -- Swap Opencode pane left/right
-      ['<leader>ott'] = { 'toggle_tool_output' }, -- Toggle tools output (diffs, cmd output, etc.)
-      ['<leader>otr'] = { 'toggle_reasoning_output' }, -- Toggle reasoning output (thinking steps)
-      ['<leader>o/'] = { 'quick_chat', mode = { 'n', 'x' } }, -- Open quick chat input with selection context in visual mode or current line context in normal mode
-    },
-    input_window = {
-      ['<S-cr>'] = { 'submit_input_prompt', mode = { 'n', 'i' } }, -- Submit prompt (normal mode and insert mode)
-      ['<esc>'] = { 'close', defer_to_completion = true }, -- Close UI windows
-      ['<C-c>'] = { 'cancel', defer_to_completion = true }, -- Cancel opencode request while it is running
-      ['~'] = { 'mention_file', mode = 'i' }, -- Pick a file and add to context. See File Mentions section
-      ['@'] = { 'mention', mode = 'i' }, -- Insert mention (file/agent)
-      ['/'] = { 'slash_commands', mode = 'i' }, -- Pick a command to run in the input window
-      ['#'] = { 'context_items', mode = 'i' }, -- Manage context items (current file, selection, diagnostics, mentioned files)
-      ['<M-v>'] = { 'paste_image', mode = 'i' }, -- Paste image from clipboard as attachment
-      ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' }, defer_to_completion = true }, -- Toggle between input and output panes
-      ['<up>'] = { 'prev_prompt_history', mode = { 'n', 'i' }, defer_to_completion = true }, -- Navigate to previous prompt in history
-      ['<down>'] = { 'next_prompt_history', mode = { 'n', 'i' }, defer_to_completion = true }, -- Navigate to next prompt in history
-      ['<M-m>'] = { 'switch_mode' }, -- Switch between modes (build/plan)
-      ['<M-r>'] = { 'cycle_variant', mode = { 'n', 'i' } }, -- Cycle through available model variants
-    },
-    output_window = {
-      ['<esc>'] = { 'close' }, -- Close UI windows
-      ['<C-c>'] = { 'cancel' }, -- Cancel opencode request while it is running
-      [']]'] = { 'next_message' }, -- Navigate to next message in the conversation
-      ['[['] = { 'prev_message' }, -- Navigate to previous message in the conversation
-      ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' } }, -- Toggle between input and output panes
-      ['i'] = { 'focus_input', 'n' }, -- Focus on input window and enter insert mode at the end of the input from the output window
-      ['gf'] = { 'jump_to_file', mode = { 'n' } }, -- Jump to file at cursor in output window
-      ['<M-r>'] = { 'cycle_variant', mode = { 'n' } }, -- Cycle through available model variants
-      ['<leader>oS'] = { 'select_child_session' }, -- Select and load a child session
-      ['<leader>oP'] = { 'select_parent_session' }, -- Go to parent session
-      ['<leader>oB'] = { 'select_sibling_session' }, -- Select sibling session (children of same parent)
-      ['<leader>oD'] = { 'debug_message' }, -- Open raw message in new buffer for debugging
-      ['<leader>oO'] = { 'debug_output' }, -- Open raw output in new buffer for debugging
-      ['<leader>ods'] = { 'debug_session' }, -- Open raw session in new buffer for debugging
-    },
-    session_picker = {
-      rename_session = { '<C-r>' }, -- Rename selected session in the session picker
-      delete_session = { '<C-d>' }, -- Delete selected session in the session picker
-      new_session = { '<C-s>' }, -- Create and switch to a new session in the session picker
-    },
-    timeline_picker = {
-      undo = { '<C-u>', mode = { 'i', 'n' } }, -- Undo to selected message in timeline picker
-      fork = { '<C-f>', mode = { 'i', 'n' } }, -- Fork from selected message in timeline picker
-    },
-    history_picker = {
-      delete_entry = { '<C-d>', mode = { 'i', 'n' } }, -- Delete selected entry in the history picker
-      clear_all = { '<C-X>', mode = { 'i', 'n' } }, -- Clear all entries in the history picker
-    },
-    model_picker = {
-      toggle_favorite = { '<C-f>', mode = { 'i', 'n' } },
-    },
-    mcp_picker = {
-      toggle_connection = { '<C-t>', mode = { 'i', 'n' } }, -- Toggle MCP server connection in the MCP picker
-    },
-  },
-  ui = {
-    enable_treesitter_markdown = true, -- Use Treesitter for markdown rendering in the output window (default: true).
-    position = 'right', -- 'right' (default), 'left' or 'current'. Position of the UI split. 'current' uses the current window for the output.
-    input_position = 'bottom', -- 'bottom' (default) or 'top'. Position of the input window
-    window_width = 0.40, -- Width as percentage of editor width
-    zoom_width = 0.8, -- Zoom width as percentage of editor width
-    display_model = true, -- Display model name on top winbar
-    display_context_size = true, -- Display context size in the footer
-    display_cost = true, -- Display cost in the footer
-    hide_single_tab = true, -- Hide the panel tab strip when only one session tab exists
-    notify_on_background_prompt = true, -- Notify when an unfocused session needs a question or permission response
-    window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder', -- Highlight group for the opencode window
-    persist_state = true, -- Keep buffers when toggling/closing UI so window state restores quickly
-    icons = {
-      preset = 'nerdfonts', -- 'nerdfonts' | 'text'. Choose UI icon style (default: 'nerdfonts')
-      overrides = {}, -- Optional per-key overrides, see section below
-    },
-    questions = {
-      use_vim_ui_select = false, -- If true, render questions/prompts with vim.ui.select instead of showing them inline in the output buffer.
-      inline_other_input = true, -- If true, show an inline floating input for "Other" instead of vim.ui.input.
-    },
-    output = {
-      filetype = 'opencode_output', -- Filetype assigned to the output buffer (default: 'opencode_output')
-      actions = {
-        open_in_new_tab = false, -- Open inline child-session and fork actions in a new panel tab
-      },
-      compact_assistant_headers = false, -- 'full' (default), 'minimal' (compact if same mode), or 'hidden' (no headers for assistant)
-      tools = {
-        show_output = true, -- Show tools output [diffs, cmd output, etc.] (default: true)
-        show_reasoning_output = true, -- Show reasoning/thinking steps output (default: true)
-        use_folds = true, -- Use folds for tool output (default: true)
-        folding_threshold = 25, -- Number of lines to show before folding when show_output is true (default: 25)
-        fold_exclude = { -- Tools that should never be folded (default: sequential-thinking)
-          'bash', -- built-in tool name (exact match)
-          { server = 'sequential-thinking', tool = 'sequentialthinking' }, -- MCP tool (server + tool match)
-        },
-      },
-      rendering = {
-        markdown_debounce_ms = 250, -- Debounce time for markdown rendering on new data (default: 250ms)
-        on_data_rendered = nil, -- Called when new data is rendered; set to false to disable default RenderMarkdown/Markview behavior
-      },
-      max_messages = nil, -- Initial output limit; older messages can be loaded by scrolling up, [[, or gg (default: nil, no limit)
-    },
-    input = {
-      min_height = 0.10, -- min height of prompt input as percentage of window height
-      max_height = 0.25, -- max height of prompt input as percentage of window height
-      text = {
-        wrap = false, -- Wraps text inside input window
-      },
-      -- Auto-hide input window when prompt is submitted or focus switches to output window
-      auto_hide = false,
-    },
-    picker = {
-      snacks_layout = nil -- `layout` opts to pass to Snacks.picker.pick({ layout = ... })
-    },
-    completion = {
-      file_sources = {
-        enabled = true,
-        preferred_cli_tool = 'server', -- 'fd','fdfind','rg','git','server' if nil, it will use the best available tool, 'server' uses opencode cli to get file list (works cross platform) and supports folders
-        ignore_patterns = {
-          '^%.git/',
-          '^%.svn/',
-          '^%.hg/',
-          'node_modules/',
-          '%.pyc$',
-          '%.o$',
-          '%.obj$',
-          '%.exe$',
-          '%.dll$',
-          '%.so$',
-          '%.dylib$',
-          '%.class$',
-          '%.jar$',
-          '%.war$',
-          '%.ear$',
-          'target/',
-          'build/',
-          'dist/',
-          'out/',
-          'deps/',
-          '%.tmp$',
-          '%.temp$',
-          '%.log$',
-          '%.cache$',
-        },
-        max_files = 10,
-        max_display_length = 50, -- Maximum length for file path display in completion, truncates from left with "..."
-      },
-    },
-  },
-  context = {
-    enabled = true, -- Enable automatic context capturing
-    cursor_data = {
-      enabled = false, -- Include cursor position and line content in the context
-      context_lines = 5, -- Number of lines before and after cursor to include in context
-    },
-    diagnostics = {
-      info = false, -- Include diagnostics info in the context (default to false
-      warning = true, -- Include diagnostics warnings in the context
-      error = true, -- Include diagnostics errors in the context
-      only_closest = true, -- Only diagnostics for cursor/selection; disable to include the whole buffer
-    },
-    current_file = {
-      enabled = true, -- Include current file path and content in the context
-      show_full_path = true,
-    },
-    files = {
-      enabled = true,
-      show_full_path = true,
-    },
-    selection = {
-      enabled = true, -- Include selected text in the context
-    },
-    review_comments = {
-      enabled = true, -- Include pending session-diff review comments in the context
-    },
-    buffer = {
-      enabled = false, -- Disable entire buffer context by default, only used in quick chat
-    },
-    git_diff = {
-      enabled = false,
-    },
-  },
-  logging = {
-    enabled = false,
-    level = 'warn', -- debug, info, warn, error
-    outfile = nil,
-  },
-  debug = {
-    enabled = false, -- Enable debug messages in the output window
-    capture_streamed_events = false,
-    show_ids = true,
-    quick_chat = {
-      keep_session = false, -- Keep quick_chat sessions for inspection, this can pollute your sessions list
-      set_active_session = false,
-    },
-  },
-  prompt_guard = nil, -- Optional function that returns boolean to control when prompts can be sent (see Prompt Guard section)
-  child_readonly = true, -- When true (default), child sessions are read-only: messaging is blocked and input window is hidden on switch
-
-  -- User Hooks for custom behavior at certain events
-  hooks = {
-    on_file_edited = nil, -- Called after a file is edited by opencode.
-    on_session_loaded = nil, -- Called after a session is loaded.
-    on_done_thinking = nil, -- Called when a session becomes idle, including sessions started outside Neovim.
-    on_permission_requested = nil, -- Called when a permission request is issued.
-    on_question_asked = nil, -- Called when a question is asked.
-    on_topbar_render = nil, -- Transform topbar segments; return nil to clear topbar.
-    on_footer_render = nil, -- Transform footer segments; return nil to clear footer.
-  },
-  quick_chat = {
-    default_model = nil,   -- works better with a fast model like gpt-4.1
-    default_agent = nil, -- Uses the current mode when nil
-    instructions = nil, -- Use built-in instructions if nil
-  },
-})
-```
-
-### Keymap Configuration
-
-The keymap configuration has been restructured for better organization and clarity:
-
-- **`editor`**: Global keymaps that are available throughout Neovim
-- **`input_window`**: Keymaps specific to the input window
-- **`output_window`**: Keymaps specific to the output window
-- **`permission`**: Special keymaps for responding to permission requests (available in input/output windows when there's a pending permission)
-
-Configure keymaps with the current nested tables directly: `keymap.editor`, `keymap.input_window`, and `keymap.output_window`.
-
-Each keymap entry is a table consising of:
-
-- The string name of an api function = `{ 'toggle' }`
-- Or a custom function: `{ function() ... end }`
-- An optional mode: `{ 'toggle', mode = { 'n', 'i' } }`
-- An optional desc: `{'toggle', desc = 'Toggle Opencode' }`
-- An optional defer_to_completion: `{'toggle', defer_to_completion = true }` if true, when completion menu is open, it will defer to the completion keymaps instead of triggering the action
-
-#### Disabling Specific Keymaps
-
-You can disable specific default keymaps by setting them to `false` in your configuration:
-
-```lua
-require('opencode').setup({
-  keymap = {
-    input_window = {
-      ['<cr>'] = false, -- Disable Enter key for submitting prompts
-      -- Other keymaps not specified will keep their default bindings
-    }
-  }
-})
-```
-
-### Model Sorting and Favorites
-
-The provider/model picker supports intelligent sorting based on your favorites and usage history:
-
-#### Sorting Priority
-
-When you open the model picker (`<leader>op`), models are sorted in the following order:
-
-1. **Favorite models** - shown with a ⭐ icon and sorted by the order they were favorited
-2. **Recently accessed models** - sorted by most recent usage
-3. **Other models** - sorted alphabetically
-
-#### Managing Favorites
-
-In the model picker, press **`<C-f>`** to toggle the currently selected model as a favorite. Favorite models will:
-
-- Display with a ⭐ star icon prefix
-- Always appear at the top of the list
-- Persist across Neovim sessions
-
-No configuration is needed - the plugin respects and updates the OpenCode CLI format automatically.
-
-### Model Variants
-
-Some models support multiple variants (e.g., different context window sizes or optimization modes). The plugin provides convenient ways to switch between available variants for the currently active model.
-
-#### Switching Variants
-
-- **Via picker**: Press `<leader>oV` to open the variant picker showing all available variants for the current model
-- **Via cycling**: Press `<M-r>` (Alt+R) in the input or output window to cycle through available variants
-- **Via slash command**: Type `/variant` in the input window
-
-When you switch variants, the plugin remembers your selection per model, so the next time you use that model, it will automatically use the last selected variant.
-
-### Avoid automatic blink.cmp menus while writing prompts
-
-If blink.cmp opens completion menus while you are writing ordinary text in an OpenCode prompt, scope its automatic presentation to the `opencode` filetype. This keeps every configured source available, including buffer, path, environment, and AI sources; it only stops them from automatically interrupting ordinary prompt text. Explicit blink.cmp trigger characters and your existing manual completion keymap continue to work.
-
-This Lazy.nvim recipe wraps your existing blink.cmp settings. Outside `opencode` buffers, it preserves your current `auto_show` and ghost-text behavior. In an OpenCode prompt, ghost text remains disabled unless you had enabled it already and the completion menu is open.
-
-```lua
-return {
-  {
-    "saghen/blink.cmp",
-    optional = true,
-    opts = function(_, opts)
-      opts.completion = opts.completion or {}
-      opts.completion.menu = opts.completion.menu or {}
-      opts.completion.ghost_text = opts.completion.ghost_text or {}
-
-      local inherited_auto_show = opts.completion.menu.auto_show
-      local inherited_ghost_text_enabled = opts.completion.ghost_text.enabled
-
-      opts.completion.menu.auto_show = function(ctx, items)
-        if vim.bo[ctx.bufnr].filetype == "opencode" then
-          -- Do not auto-open while writing prose; explicit Blink triggers still open it.
-          return ctx.trigger.kind == "trigger_character"
-        end
-
-        if type(inherited_auto_show) == "function" then
-          return inherited_auto_show(ctx, items)
-        end
-        return inherited_auto_show ~= false
-      end
-
-      opts.completion.ghost_text.enabled = function()
-        local ghost_text_enabled = type(inherited_ghost_text_enabled) == "function"
-            and inherited_ghost_text_enabled()
-          or inherited_ghost_text_enabled == true
-
-        if vim.bo.filetype == "opencode" then
-          return ghost_text_enabled and require("blink.cmp").is_menu_visible()
-        end
-        return ghost_text_enabled
-      end
-
-      return opts
-    end,
-  },
-}
-```
-
-### UI icons (disable emojis or customize)
-
-By default, opencode.nvim uses emojis for icons in the UI. If you prefer a plain, emoji-free interface, you can switch to the `text` preset or override icons individually.
-
-Minimal config to disable emojis everywhere:
-
-```lua
-require('opencode').setup({
-  ui = {
-    icons = {
-      preset = 'text', -- switch all icons to text
-    },
-  },
-})
-```
-
-Override specific icons while keeping the preset:
-
-```lua
-require('opencode').setup({
-  ui = {
-    icons = {
-      preset = 'emoji',
-      overrides = {
-        header_user = '> U',
-        header_assistant = 'AI',
-        search = 'FIND',
-        border = '|',
-      },
-    },
-  },
-})
-```
-
-Available icon keys (see implementation at lua/opencode/ui/icons.lua lines 7-29):
-
-- header_user, header_assistant
-- run, task, read, edit, write
-- plan, search, web, list, tool
-- snapshot, restore_point, restore_count, file
-- status_on, status_off
-- border, bullet
-
-### Window Persistence Behavior
-
-`ui.persist_state` controls how `toggle` and `close` behave:
-
-- `persist_state = true` (default): `toggle()` hides/restores the UI and keeps buffers/session view in memory for fast restore.
-- `persist_state = false`: `toggle()` fully tears down UI buffers and recreates them on next open.
-
-Directory-bound sessions can be opened in logical panel tabs without changing
-Neovim's cwd:
-
-```lua
-require('opencode.api').open_session({
-  directory = '/path/to/repo/.worktrees/feature',
-  new = true,
-  title = 'Feature work',
-})
-```
-
-Returns a Promise resolving to the session; failures reject. The directory must
-exist locally (normal path mapping still applies). Omit `new` to reopen the most
-recent root session created in that exact directory, or create one if absent.
-Pass `session_id` to open a specific session; `new` and `session_id` are mutually
-exclusive. Already-open sessions reuse their logical tab. Completion and new
-sessions use the bound directory, including after tab switches. Explicit
-directory changes still follow `lock_session_to_directory`; locked bound tabs
-keep their directory.
-
-For worktree or other per-project workflows, `lock_session_to_directory` also
-accepts a function. It is called on each directory change with
-`{ from, to, session }` and returns `true` to keep the active session or `false`
-to load the target directory's last session. `from` is the bound directory (or
-the directory the session was loaded from) and `to` is the new directory. An
-error in the function is reported and falls back to following the cwd. Manual
-lock toggles still override the policy per logical tab.
-
-```lua
-require('opencode').setup({
-  lock_session_to_directory = function(change)
-    local function common_dir(dir)
-      local r = vim.system({ 'git', '-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir' }, { text = true }):wait()
-      return r.code == 0 and vim.trim(r.stdout) or nil
-    end
-    local repo = common_dir(change.from)
-    return repo ~= nil and repo == common_dir(change.to)
-  end,
-})
-```
-
-That example keeps a session across the main checkout and linked worktrees of
-the same repository.
-
-Related APIs:
-
-- `require('opencode.api').toggle()` follows the `persist_state` behavior above.
-- `require('opencode.api').close()` preserves buffers when `persist_state = true`; otherwise it fully closes.
-- `require('opencode.api').hide()` preserves buffers only when `persist_state = true`; otherwise it behaves like close.
-
-### Picker Layout
-
-You can customize the layout of the picker used for history, session, references, and timeline
-
-#### Snacks Picker Integration with Opencode
-
-You can configure a custom action in Snacks pickers to send selected files directly to opencode as context. This works with any file-based picker (files, git_files, buffers, git_status, etc.).
-
-```lua
--- In your snacks.nvim configuration
-{
-  "folke/snacks.nvim",
-  opts = {
-    picker = {
-      actions = {
-        opencode_send = function(picker)
-          local selected = picker:selected({ fallback = true })
-          if selected and #selected > 0 then
-            local files = {}
-            for _, item in ipairs(selected) do
-              if item.file then
-                table.insert(files, item.file)
-              end
-            end
-            picker:close()
-
-            require("opencode.core").open({
-              new_session = false,
-              focus = "input",
-              start_insert = true,
-            })
-
-            local context = require("opencode.context")
-            for _, file in ipairs(files) do
-              context.add_file(file)
-            end
-          end
-        end,
-      },
-      win = {
-        input = {
-          keys = {
-            -- Use <localleader>o or any preferred key to send files to opencode
-            ["<localleader>o"] = { "opencode_send", mode = { "n", "i" } },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-This allows you to:
-
-1. Open any Snacks file picker (`:Snacks picker files`, `:Snacks picker git_files`, etc.)
-2. Select one or more files using multi-select
-3. Press `<localleader>o` to send those files to opencode as context
-
-#### Snacks Picker Layout
-
-There's 3 main ways on how to change the snacks picker layout
-
-1. Don't specify the new options -> it'll just default to the user's snack picker layout preset from their snacks config
-2. Specify the new options for opencode, e.g.
-
-   ```lua
-   require("opencode").setup({
-     ui = {
-       picker = {
-        ---@module "snacks"
-        ---@type snacks.picker.layout.Config | nil
-         snacks_layout = {
-           layout = { border = "none", box = "vertical", ... }
-         },
-       },
-     },
-   })
-   ```
-
-3. Specify a [builtin layout preset](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#%EF%B8%8F-layouts) for snacks picker OR a custom layout defined in your snacks config's `opts.picker.layouts`
-
-   ```lua
-   -- opencode.lua
-   require("opencode").setup({
-     ui = {
-       picker = {
-         ---@module "snacks"
-         ---@type snacks.picker.layout.Config | nil
-         snacks_layout = {
-           preset = "custom_layout" -- or builtin snacks, like "select", "default", etc
-         },
-       },
-     },
-   })
-   ```
-
-   ```lua
-   -- snacks.lua
-   {
-     "folke/snacks.nvim",
-     opts = {
-       picker = {
-         layouts = {
-           custom_layout  = {
-             layout = { border = "none", box = "vertical", ... }
-             -- ...
-   }
-   ```
-
-## 🧰 Usage
-
-### Available Actions
-
-The plugin provides the following actions that can be triggered via keymaps, commands, slash commands (typed in the input window), or the Lua API:
-
-Panel tabs are logical tabs inside the Opencode UI. They do not create or switch Neovim tabpages. Each tab keeps its own session state, input buffer, output buffer, and model/context state while reusing the current panel layout.
-
-| Action                                                      | Default keymap                        | Command                                     | API Function                                                           |
-| ----------------------------------------------------------- | ------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
-| Open opencode. Close if opened                              | `<leader>og`                          | `:Opencode`                                 | `require('opencode.api').toggle()`                                     |
-| Open input window (current session)                         | `<leader>oi`                          | `:Opencode open input`                      | `require('opencode.api').open_input()`                                 |
-| Open input window (new session)                             | `<leader>oI`                          | `:Opencode open input_new_session`          | `require('opencode.api').open_input_new_session()`                     |
-| Open a new session in a panel tab                           | `<leader>oN`                          | `:Opencode tab new [name]`                  | `require('opencode.api').open_session_tab([name])`                     |
-| Select a panel tab                                          | `<leader>o?`                          | `:Opencode tab select`                      | `require('opencode.api').select_session_tab()`                         |
-| Select panel tab by index                                   | `<leader>o1` ... `<leader>o9`         | `:Opencode tab select [index]`              | `require('opencode.api').select_session_tab(index)`                    |
-| Switch panel tabs                                           | `<leader>o<` / `<leader>o>`           | `:Opencode tab previous` / `next`           | `require('opencode.api').prev_session_tab()` / `next_session_tab()`    |
-| Close the current panel tab                                 | `<leader>oQ`                          | `:Opencode tab close`                       | `require('opencode.api').close_session_tab()`                          |
-| Open output window                                          | `<leader>oo`                          | `:Opencode open output`                     | `require('opencode.api').open_output()`                                |
-| Create and switch to a named session                        | -                                     | `:Opencode session new <name>`              | `:Opencode session new <name>` (user command)                          |
-| Open the selected session in a new panel tab                | `<C-t>` (session picker)              | -                                           | -                                                                      |
-| Rename current session                                      | `<leader>oR`                          | `:Opencode session rename <name>`           | `:Opencode session rename <name>` (user command)                       |
-| Toggle focus opencode / last window                         | `<leader>ot`                          | `:Opencode toggle focus`                    | `require('opencode.api').toggle_focus()`                               |
-| Close UI windows                                            | `<leader>oq`                          | `:Opencode close`                           | `require('opencode.api').close()`                                      |
-| Select and load session                                     | `<leader>os`                          | `:Opencode session select`                  | `require('opencode.api').select_session()`                             |
-| **Select and load child session**                           | `<leader>oS`                          | `:Opencode session child`                   | `require('opencode.api').select_child_session()`                       |
-| **Select sibling session**                                  | `<leader>oB`                          | `:Opencode session sibling`                 | `require('opencode.api').select_sibling_session()`                     |
-| **Go to parent session**                                    | `<leader>oP`                          | `:Opencode session parent`                  | `require('opencode.api').select_parent_session()`                      |
-| Open timeline picker (navigate/undo/redo/fork to message)   | `<leader>oT`                          | `:Opencode timeline`                        | `require('opencode.api').timeline()`                                   |
-| Browse code references from conversation                    | `gr` (window)                         | `:Opencode references` / `/references`      | `require('opencode.api').references()`                                 |
-| Jump to file referenced at cursor in output window          | `gf` (window)                         | `:Opencode jump_to_file` / `/jump_to_file`  | `require('opencode.api').jump_to_file()`                               |
-| Configure provider and model                                | `<leader>op`                          | `:Opencode configure provider`              | `require('opencode.api').configure_provider()`                         |
-| Configure model variant                                     | `<leader>oV`                          | `:Opencode variant` / `/variant`            | `require('opencode.api').configure_variant()`                          |
-| Cycle through model variants                                | `<M-r>` (window)                      | -                                           | `require('opencode.api').cycle_variant()`                              |
-| Open diff view of changes                                   | `<leader>od`                          | `:Opencode diff open`                       | `require('opencode.api').diff_open()`                                  |
-| Navigate to next file diff                                  | `<leader>o]`                          | `:Opencode diff next`                       | `require('opencode.api').diff_next()`                                  |
-| Navigate to previous file diff                              | `<leader>o[`                          | `:Opencode diff prev`                       | `require('opencode.api').diff_prev()`                                  |
-| Close diff view tab                                         | `<leader>oc`                          | `:Opencode diff close`                      | `require('opencode.api').diff_close()`                                 |
-| Revert all file changes since last prompt                   | `<leader>ora`                         | `:Opencode revert all prompt`               | `require('opencode.api').diff_revert_all_last_prompt()`                |
-| Revert current file changes last prompt                     | `<leader>ort`                         | `:Opencode revert this prompt`              | `require('opencode.api').diff_revert_this_last_prompt()`               |
-| Revert all file changes since last session                  | `<leader>orA`                         | `:Opencode revert all session`              | `require('opencode.api').diff_revert_all_session()`                    |
-| Revert current file changes last session                    | `<leader>orT`                         | `:Opencode revert this session`             | `require('opencode.api').diff_revert_this_session()`                   |
-| Revert all files to a specific snapshot                     | -                                     | `:Opencode revert all_to_snapshot`          | `require('opencode.api').diff_revert_all(snapshot_id)`                 |
-| Revert current file to a specific snapshot                  | -                                     | `:Opencode revert this_to_snapshot`         | `require('opencode.api').diff_revert_this(snapshot_id)`                |
-| Restore a file to a restore point                           | -                                     | `:Opencode restore snapshot_file`           | `require('opencode.api').diff_restore_snapshot_file(restore_point_id)` |
-| Restore all files to a restore point                        | -                                     | `:Opencode restore snapshot_all`            | `require('opencode.api').diff_restore_snapshot_all(restore_point_id)`  |
-| Initialize/update AGENTS.md file                            | -                                     | `:Opencode session agents_init`             | `require('opencode.api').initialize()`                                 |
-| Run prompt (continue session) [Run opts](#run-opts)         | -                                     | `:Opencode run <prompt> <opts>`             | `require('opencode.api').run("prompt", opts)`                          |
-| Run prompt (new session) [Run opts](#run-opts)              | -                                     | `:Opencode run new_session <prompt> <opts>` | `require('opencode.api').run_new_session("prompt", opts)`              |
-| Cancel opencode while it is running                         | `<C-c>`                               | `:Opencode cancel`                          | `require('opencode.api').cancel()`                                     |
-| Set mode to Build                                           | -                                     | `:Opencode agent build`                     | `require('opencode.api').agent_build()`                                |
-| Set mode to Plan                                            | -                                     | `:Opencode agent plan`                      | `require('opencode.api').agent_plan()`                                 |
-| Select and switch mode/agent                                | -                                     | `:Opencode agent select`                    | `require('opencode.api').select_agent()`                               |
-| Browse and select available skills                          | -                                     | `:Opencode skills` / `/skills`              | -                                                                      |
-| Display list of available mcp servers                       | -                                     | `:Opencode mcp`                             | `require('opencode.api').mcp()`                                        |
-| Run user commands                                           | -                                     | `:Opencode run user_command`                | `require('opencode.api').run_user_command()`                           |
-| Share current session and get a link                        | -                                     | `:Opencode session share` / `/share`        | `require('opencode.api').share()`                                      |
-| Unshare current session (disable link)                      | -                                     | `:Opencode session unshare` / `/unshare`    | `require('opencode.api').unshare()`                                    |
-| Compact current session (summarize)                         | -                                     | `:Opencode session compact` / `/compact`    | `require('opencode.api').compact_session()`                            |
-| Undo last opencode action                                   | -                                     | `:Opencode undo` / `/undo`                  | `require('opencode.api').undo()`                                       |
-| Redo last opencode action                                   | -                                     | `:Opencode redo` / `/redo`                  | `require('opencode.api').redo()`                                       |
-| Respond to permission requests (accept once)                | `a` (window) / `<leader>opa` (global) | `:Opencode permission accept`               | `require('opencode.api').permission_accept()`                          |
-| Respond to permission requests (accept all)                 | `A` (window) / `<leader>opA` (global) | `:Opencode permission accept_all`           | `require('opencode.api').permission_accept_all()`                      |
-| Respond to permission requests (deny)                       | `d` (window) / `<leader>opd` (global) | `:Opencode permission deny`                 | `require('opencode.api').permission_deny()`                            |
-| Insert mention (file/ agent)                                | `@`                                   | -                                           | -                                                                      |
-| [Pick a file and add to context](#file-mentions)            | `~`                                   | -                                           | -                                                                      |
-| Navigate to next message                                    | `]]`                                  | -                                           | -                                                                      |
-| Navigate to previous message                                | `[[`                                  | -                                           | -                                                                      |
-| Navigate to previous prompt in history                      | `<up>`                                | -                                           | `require('opencode.api').prev_history()`                               |
-| Navigate to next prompt in history                          | `<down>`                              | -                                           | `require('opencode.api').next_history()`                               |
-| Toggle input/output panes                                   | `<tab>`                               | -                                           | -                                                                      |
-| Swap Opencode pane left/right                               | `<leader>ox`                          | `:Opencode swap position`                   | `require('opencode.api').swap_position()`                              |
-| Toggle tools output (diffs, cmd output, etc.)               | `<leader>ott`                         | `:Opencode toggle_tool_output`              | `require('opencode.api').toggle_tool_output()`                         |
-| Toggle reasoning output (thinking steps)                    | `<leader>otr`                         | `:Opencode toggle_reasoning_output`         | `require('opencode.api').toggle_reasoning_output()`                    |
-| Open a quick chat input with selection/current line context | `<leader>o/`                          | `:Opencode quick_chat`                      | `require('opencode.api').quick_chat()`                                 |
-| Add visual selection to context                             | `<leader>oy`                          | `:Opencode add_visual_selection`            | `require('opencode.api').add_visual_selection(opts?)`                  |
-| Insert visual selection inline into input                   | `<leader>oY`                          | `:Opencode add_visual_selection_inline`     | `require('opencode.api').add_visual_selection_inline(opts?)`           |
-
-**add_visual_selection opts:**
-
-- `open_input` (boolean, default: `true`): Whether to open the input window after adding the selection. Set to `false` to add selection silently without changing focus.
-
-Example keymap for silent add:
-
-```lua
-['<leader>oy'] = { 'add_visual_selection', { open_input = false }, mode = {'v'} }
-```
-
-**add_visual_selection_inline** inserts the visually selected code directly into the input buffer as a Markdown code block, prefixed with the file path:
-
-````
-**`path/to/file.lua`**
-
-```lua
-<selected text>
-````
-
-````
-
-The cursor is left in normal mode in the input buffer so you can type your prompt around the inserted snippet.
-
-### Run opts
-
-You can pass additional options when running a prompt via command or API:
-
-- `agent=<agent_name>`: Specify the agent to use for this prompt (overrides current agent)
-- `model=<provider/model_name>`: Specify the model to use for this prompt (overrides current model) e.g. `model=github-copilot/gpt-4.1`
-- `context.<context_type>.enabled=<true|false>`: Enable/disable specific context types for this prompt only. Available context types:
-  - `current_file`
-  - `selection`
-  - `diagnostics.info`
-  - `diagnostics.warning`
-  - `diagnostics.error`
-  - `cursor_data`
-
-#### Example
-
-Run a prompt in a new session using the Plan agent and disabling current file context:
-
-```vim
-:Opencode run new_session "Please help me plan a new feature" agent=plan context.current_file.enabled=false
-:Opencode run "Fix the bug in the current file" model=github-copilot/claude-sonnet-4
-````
-
-## 👮 Permissions
-
-Opencode can issue permission requests for potentially destructive operations (file edits, reverting files, running shell commands, or enabling persistent tool access). Permission requests appear inline in the output and must be responded to before the agent performs the action. Visit [Opencode Permissions Documentation](https://opencode.ai/docs/permissions/) for more details.
-
-<div align="center">
-  <img src="https://i.imgur.com/LkZDta5.png" alt="Opencode permission request" width="90%" />
-  <img src="https://i.imgur.com/4mJH1Xg.png" alt="Opencode permission request input window" width="90%" />
-</div>
-
-### Responding to Permission Requests
-
-- **Respond via the dialog:** Focus the Opencode window, move with `j`/`k` or arrow keys, then confirm with `<CR>`. Number shortcuts `1-3` also work for the visible options.
-- **Command:** Use `:Opencode permission accept`, `:Opencode permission accept_all`, or `:Opencode permission deny`. You can pass an index to target a specific queued permission.
-- **API:** Programmatic responses are available: `require('opencode.api').permission_accept()`, `require('opencode.api').permission_accept_all()`, `require('opencode.api').permission_deny()` which map to responses `"once"`, `"always"`, and `"reject"` respectively.
-- **Behavior:** `accept once` allows the single requested action, `accept all` grants persistent permission for similar requests in the current session, and `deny` rejects the request.
-
----
-
-## 📝 Context
-
-The following editor context is automatically captured and included in your conversations.
-
-Unchanged automatic payloads (diagnostics, buffer, cursor data, and staged diff) are sent once per session, then sent again only after their content changes. Explicit file mentions and selections are always sent.
-
-When a selection targets the current file, the automatic current-file attachment is skipped. The selected lines provide focused context; the agent can read more of the file when needed. An explicit file mention is still honored.
-
-| Context Type    | Description                                          |
-| --------------- | ---------------------------------------------------- |
-| Current file    | Path to the focused file before entering opencode    |
-| Selected text   | Text and lines currently selected in visual mode     |
-| Mentioned files | File info added through [mentions](#file-mentions)   |
-| Diagnostics     | Diagnostics from the current file (if any)           |
-| Cursor position | Current cursor position and line content in the file |
-| Review comments | Saved session-diff feedback, included when enabled   |
-
-<a id="file-mentions"></a>
-
-### Adding more files to context through file mentions
-
-You can reference files in your project directly in your conversations with Opencode. This is useful when you want to ask about or provide context about specific files. Type `@` in the input window to trigger the file picker.
-Supported pickers include [`fzf-lua`](https://github.com/ibhagwan/fzf-lua), [`telescope`](https://github.com/nvim-telescope/telescope.nvim), [`mini.pick`](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-pick.md), [`snacks`](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md)
-
-### Context bar
-
-You can quickly see the current context items in the context bar at the top of the input window:
-
-<div align="center">
-  <img src="https://i.imgur.com/vGgu6br.png" alt="Opencode.nvim context bar" width="90%" />
-</div>
-
-For `Current file`, the color indicates whether it will be sent with the next prompt:
-
-- Regular highlight: file is pending and will be included.
-- Dimmed/gray highlight: file was already sent and has not changed, so it will be skipped (delta behavior).
-
-If the file content changes, it becomes pending again and will be sent on the next prompt.
-
-### Context Items Completion
-
-You can quickly reference available context items by typing `#` in the input window. This will show a completion menu with all available context items:
-
-- **Current File** - The currently focused file in the editor
-- **Selection** - Currently selected text in visual mode
-- **Diagnostics** - LSP diagnostics from the current file
-- **Cursor Data** - Current cursor position and line content
-- **Review comments** - Pending comments added to session diffs; select the group to toggle it or select a comment to remove it
-- **[filename]** - Files that have been mentioned in the conversation
-- **Agents** - Available agents to switch to
-- **Selections** - Previously made selections in visual mode
-
-Context items that are not currently available will be shown as disabled in the completion menu.
-
-You should also see the list of files agents and selections in the menu, selecting them in the menu will remove them from the context.
-
-<div align="center">
-  <img src="https://i.imgur.com/UqQKW33.png" alt="Opencode.nvim context items completion" width="90%" />
-</div>
-
-## 🔄 Agents
-
-Opencode provides two built-in agents and supports custom ones:
-
-### Built-in Agents
-
-- **Build** (default): Full development agent with all tools enabled for making code changes
-- **Plan**: Restricted agent for planning and analysis without making file changes. Useful for code review and understanding code without modifications
-
-### Switching Agent
-
-Press `<M-m>` (Alt+M) in the input window to switch between agents during a session.
-
-### Custom Agents
-
-You can create custom agents through your opencode config file. Each agent can have its own:
-
-- Agent configuration
-- Custom prompt
-- Enabled/disabled tools
-- And more
-
-See [Opencode Agents Documentation](https://opencode.ai/docs/agents/) for full configuration options.
-
-## 🔌 Custom/External Server Configuration
-
-By default, opencode.nvim spawns a local `opencode serve` process. You can instead connect to an external or containerized opencode server by configuring the `server` table.
-
-### Basic Connection
-
-Connect to an existing server:
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'localhost',     -- or 'http://192.168.1.100'
-    port = 8080,
-    timeout = 5,
-  },
-})
-```
-
-### Authentication
-
-If your opencode server requires authentication, or if you would like the server that `opencode.nvim` starts to be behind authentication, you have a few options on how to provide the username and password.
-
-If Neovim has the `OPENCODE_SERVER_PASSWORD` environment variable set the plugin will automatically use them for authentication. The username is optional (will default to `opencode`), but can also be set with `OPENCODE_SERVER_USERNAME`.
-
-You can also supply the username and password directly in the config:
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'localhost',
-    port = 8080,
-    username = 'your_username_here', -- Optional, defaults to 'opencode' if not provided.
-    password = 'your_password_here',
-  }
-})
-```
-
-Both the `username` and `password` fields accept a `function` that returns a string. The results will be cached for the session, and are only called when first attempting to start or connect to a server:
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'localhost',
-    port = 8080,
-    username = function()
-      local keyfile = vim.fn.expand('~/.config/opencode/server-username')
-      if vim.fn.filereadable(keyfile) == 1 then
-        return vim.fn.trim(vim.fn.readfile(keyfile)[1])
-      end
-    end,
-    password = function()
-      local keyfile = vim.fn.expand('~/.config/opencode/server-password')
-      if vim.fn.filereadable(keyfile) == 1 then
-        return vim.fn.trim(vim.fn.readfile(keyfile)[1])
-      end
-    end,
-  }
-})
-```
-
-### Auto-Spawning with Docker
-
-Use `spawn_command` to automatically start your server and `kill_command` to stop it:
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'https://localhost',
-    port = 'auto',  -- Random port for project isolation
-    -- Path mapping: translate host paths to container paths
-    path_map = function(host_path)
-      local cwd = vim.fn.getcwd()
-      -- Replace host project directory with container mount point
-      return host_path:gsub(vim.pesc(cwd), '/app')
-    end,
-    -- Spawn command: start Docker container with opencode server
-    spawn_command = function(port, url)
-      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
-      local cwd = vim.fn.getcwd()
-      local container_name = string.format('opencode-%s', dir_name)
-
-      -- Check if container is already running
-      local check_cmd = string.format('docker ps --filter "name=%s" --format "{{.Names}}"', container_name)
-      local handle = io.popen(check_cmd)
-      local result = handle:read("*a")
-      handle:close()
-
-      if result and result:match(container_name) then
-        print(string.format("[opencode.nvim] Container %s is already running, skipping start", container_name))
-        return true
-      end
-
-      -- First, try to stop any existing container with the same name
-      os.execute(string.format('docker stop %s 2>/dev/null || true', container_name))
-
-      local cmd = string.format([[
-docker run -d --rm \
---name %s \
--p %d:4096 \
--v ~/.local/state/opencode:/home/node/.local/state/opencode \
--v ~/.local/share/opencode:/home/node/.local/share/opencode \
--v ~/.config/opencode:/home/node/.config/opencode \
--v "%s":/app:rw \
-ghcr.io/anomalyco/opencode:latest serve --port 4096 --hostname '0.0.0.0']],
-        container_name,
-        port,
-        cwd
-      )
-
-      print(string.format("[opencode.nvim] Starting OpenCode container: %s on port %d", container_name, port))
-      return os.execute(cmd)
-    end,
-    -- Kill command: stop Docker container when auto_kill is triggered
-    kill_command = function(port, url)
-      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
-      local container_name = string.format('opencode-%s', dir_name)
-
-      print(string.format("[opencode.nvim] Stopping OpenCode container: %s", container_name))
-      return os.execute(string.format('docker stop %s 2>/dev/null', container_name))
-    end,
-    auto_kill = true,  -- Enable automatic cleanup when last nvim exits
-  },
-})
-```
-
-### Path Mapping for Containers/WSL
-
-When paths on the server differ from your host (e.g., `/app` in container vs `/home/user/project` on host):
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'localhost',
-    port = 8080,
-    path_map = '/app',  -- Simple string replacement
-  },
-})
-```
-
-### Auto-Spawning with WSL
-
-Run opencode server inside WSL while using Neovim on Windows:
-
-```lua
-require('opencode').setup({
-  server = {
-    url = 'localhost',
-    port = 'auto',  -- Random port for project isolation
-
-    -- Spawn opencode server inside WSL
-    spawn_command = function(port, url)
-      local cmd = string.format(
-        'wsl.exe -e bash -c "opencode serve --hostname 127.0.0.1 --port %d"',
-        port
-      )
-      print(string.format('[opencode.nvim] Starting WSL server on port %d', port))
-      return vim.fn.jobstart(cmd, { detach = 1 })
-    end,
-
-    -- Kill WSL opencode process
-    kill_command = function(port, url)
-      print(string.format('[opencode.nvim] Stopping WSL server on port %d', port))
-      vim.fn.jobstart('wsl.exe -e pkill -f "opencode serve.*--port ' .. port .. '"')
-    end,
-
-    -- Windows → WSL path translation (for requests)
-    path_map = function(host_path)
-      if vim.fn.has('win32') == 1 then
-        -- Convert C:\Users\... → /mnt/c/Users/...
-        local drive, rest = host_path:match('^([A-Za-z]):(.*)$')
-        if drive then
-          local wsl_path = '/mnt/' .. drive:lower() .. rest:gsub('\\', '/')
-          return wsl_path
-        end
-      end
-      return host_path
-    end,
-
-    -- WSL → Windows path translation (for responses)
-    reverse_path_map = function(server_path)
-      -- Convert /mnt/c/Users/... → C:\Users\...
-      local drive, rest = server_path:match('^/mnt/([a-z])(.*)$')
-      if drive then
-        local windows_path = drive:upper() .. ':' .. rest:gsub('/', '\\')
-        return windows_path
-      end
-      return server_path
-    end,
-
-    auto_kill = true,  -- Kill server when last nvim instance exits
-  },
-})
-```
-
-### Configuration Options
-
-- `url` (string | nil): Server hostname/URL (e.g., 'localhost', 'http://192.168.1.100')
-- `port` (number | 'auto' | nil): Port number, `'auto'` for random port, or nil for default (4096)
-- `timeout` (number): Health check timeout in seconds (default: 5)
-- `spawn_command` (function | nil): Optional function to start server: `function(port, url) ... end`
-- `kill_command` (function | nil): Optional function to stop server when `auto_kill` triggers: `function(port, url) ... end`
-- `auto_kill` (boolean): Kill spawned servers when last nvim instance exits (default: true)
-- `path_map` (string | function | nil): Transform host paths to server paths (for outgoing requests)
-- `reverse_path_map` (function | nil): Transform server paths back to host paths (for incoming responses/events)
-
-### Multi-Instance Support
-
-When `port = 'auto'` is used, opencode.nvim:
-
-- Tracks which nvim instances are using each port
-- Only kills the server when the last nvim instance exits (if `auto_kill = true`). Only applies to servers spawned by the plugin with `spawn_command`/`kill_command`.
-- Locally spawned servers will be killed automatically regardless of the auto_kill setting if they are the last nvim instance using them
-
-## 🎯 Skills
-
-Skills are reusable, installable instruction packs that enhance opencode.nvim with domain-specific workflows. Each skill provides its own behavior, prompts, and tool configurations.
-
-### Browsing Skills
-
-- **Via command:** Run `:Opencode skills` to open the skills picker
-- **Via slash command:** Type `/skills` in the input window to open the skills picker
-- **Via completion:** Type `/` in the input window and select a skill from the completion menu
-
-The skills picker displays each skill with its name, description, and full content rendered as markdown in the preview pane. Selecting a skill inserts `/skill-name` into the input window.
-
-On V2, submitting `/skill-name` activates the native server-managed skill. Add instructions, such as `/skill-name review current changes`, to send a prompt with a native skill attachment instead. Servers without these capabilities report an error; update the OpenCode CLI to enable them. V1 continues sending the skill's content as an ordinary prompt.
-
-The same behavior is available through `:Opencode skill <name> [instructions]` and `require('opencode.api').run_skill(name, instructions)`. V2 API callers can also pass `skills = { { id = skill_id } }` in `run` options. Optional `mention = { start_byte = ..., end_byte = ... }` ranges use zero-based UTF-8 byte offsets relative to the prompt text, with an exclusive end.
-
-### Installing Skills
-
-See the [Opencode Skills Documentation](https://opencode.ai/docs/skills/) for how to discover and install community skills.
-
-## User Commands and Slash Commands
-
-You can run predefined user commands and built-in slash commands from the input window by typing `/`. This opens a command picker where you can select a command to execute. The output of the command will be included in your prompt context.
-
-Local Lua commands can be registered without modifying internal tables:
-
-```lua
-require('opencode').register_slash_command({
-  name = 'worktree',
-  desc = 'Open a worktree session',
-  args = true,
-  fn = function(args)
-    -- args is a string array, empty when no arguments were supplied.
-    print(vim.inspect(args))
-  end,
-})
-```
-
-Registration works before or after `setup`. Commands appear in completion and
-the picker, and execute through command lifecycle hooks (filter by `/worktree`).
-Names use letters, digits, underscores, or hyphens, without a leading slash.
-Builtin and registered name collisions throw; local commands take precedence
-over same-named server commands and skills. Use
-`require('opencode').unregister_slash_command('worktree')` to remove one (returns
-whether it existed). Callback errors use the normal command error handling.
-
-**Built-in slash commands** include:
-
-- `/share` — Share the current session and get a link
-- `/unshare` — Unshare the current session
-- `/compact` — Compact (summarize) the current session
-- `/undo` — Undo the last opencode action
-- `/redo` — Redo the last undone action
-- `/agents_init` — Initialize/update AGENTS.md
-- `/help` — Show help
-- `/mcp` — Show MCP servers
-- `/skills` — Browse and select available skills
-- `/models` — Switch provider/model
-- `/variant` — Switch model variant
-- `/sessions` — Switch session
-- `/child-sessions` — Switch to a child session
-- `/agent` — Switch agent/mode
-- ...and more
-
-**User commands** are custom scripts you define. They are loaded from:
-
-- `.opencode/command/` (project-specific)
-- `command/` (global, in config directory)
-
-You can also run user commands by name with `:Opencode command <name>`.
-
-<img src="https://i.imgur.com/YQhhoPS.png" alt="Opencode.nvim contextual actions" width="90%" />
-
-See [User Commands Documentation](https://opencode.ai/docs/commands/) for more details.
-
-## Session diffs (OpenCode V2)
-
-`:Opencode diff open` opens a review tab for the latest session turn, with a session-labeled, collapsible changed-file tree and side-by-side before/after revisions. Move through files with `j`/`k`, and press `<CR>` on a directory to expand or collapse it.
-
-![Changed-file tree with side-by-side before and after revisions](https://github.com/user-attachments/assets/e62aa9df-848a-47fc-9bb5-dabce0422f03)
-
-Press `p` to switch to a unified patch for the selected file.
-
-![Changed-file tree with a unified patch preview](https://github.com/user-attachments/assets/ee061cfd-8d12-4fc5-9ebb-ff8889d1f49c)
-
-Press `r` to select a range of turns/messages: move through user prompts, mark the start with `f` and end with `t`, then press `<CR>` to review the range; `r` returns to the file tree.
-
-![Turn-range picker with start and end markers](https://github.com/user-attachments/assets/7b28dbe7-9769-4144-bad7-6ca49ecbeb2d)
-
-Press `q` to close the review tab. `:Opencode diff next` and `:Opencode diff prev` also select files in the open review tab.
-
-Press `gf` in the file list or diff preview to open the selected working-tree file in a new tab, keeping the snapshot review intact. From a preview, it targets the corresponding post-change line (deleted lines use the next surviving line, or the last one), clamped to the current file's length. This is best-effort if the working tree has changed since the snapshot. Diff panes show absolute line numbers. If the file no longer exists on disk, a warning is shown instead. Remap this using the `open_file` action.
-
-### Customize session-diff keymaps
-
-Like panel mappings, `keymap.session_diff` binds keys to `{ action, { arguments }, mode = ..., desc = ..., nowait = ... }` entries, using the same keymap utility. Actions can be local diff action names, panel command names, or Lua callbacks; local diff actions take precedence. Set a default key to `false` to disable it. `<Tab>` / `<S-Tab>` select the next / previous file in the list and diff panes.
-
-```lua
-keymap = {
-  session_diff = {
-    preview = {
-      [']f'] = { 'next_file', desc = 'Next file' },
-      ['[f'] = { 'prev_file', desc = 'Previous file' },
-      ['<M-e>'] = { function() vim.cmd('wincmd h') end, desc = 'Focus file list' },
-    },
-    list = {
-      ['<M-e>'] = { function() vim.cmd('wincmd l') end, desc = 'Focus diff' },
+      ft = { 'markdown', 'opencode_output' },
     },
   },
+  opts = {},
 }
 ```
 
-Dedicated filetypes are `opencode_diff_list`, `opencode_diff_messages`, `opencode_diff_help`, and `opencode_diff_comment`. Preview buffers use composite filetypes such as `lua.opencode_diff_preview`, `diff.opencode_diff_preview`, and `markdown.opencode_diff_message_preview`, keeping source syntax highlighting. Use `FileType` patterns `*.opencode_diff_preview` or `*.opencode_diff_message_preview` to attach your own buffer-local mappings; configured mappings are installed before these hooks run.
-
-### Comment on a session diff
-
-In a diff preview, press `c` on a line or visual selection to add or edit a review comment. Use `dc` to remove one; `]r` and `[r` move between comments. In the comment editor, `<C-s>` or `:w` saves, while `q` or `<Esc>` cancels. Comments appear as signs and in the file tree; closing the review focuses the input when comments are pending. Comments are sent with the next prompt and include the reviewed snapshot and a best-effort current-file status.
-
-![Review comment editor open on a changed line](https://github.com/user-attachments/assets/aa4348f1-7075-4449-a0cd-e3322d3c6a77)
+With another plugin manager, install the plugin and call
+`require('opencode').setup({})`. Then run `:checkhealth opencode`.
 
-![Saved review comment shown beside its changed line in a session diff](https://github.com/user-attachments/assets/e7f1794e-57d5-4757-b7c5-ce2e1fdf102a)
+See the [full default configuration](docs/configuration.md#full-default-configuration)
+for all available options, and
+[optional integrations](docs/getting-started.md#optional-integrations) for
+picker and completion setup.
 
-The context bar shows a review-comment icon and count while comments are pending. Type `#` in the input to toggle the **Review comments** context group or remove individual comments. Set `context.review_comments.enabled = false` to disable sending review comments by default. See the [session diff review recipe](docs/recipes/review-session-diff.md) for the step-by-step workflow.
+## Quick start
 
-![Review comments context item and individual comment in the input completion menu](https://github.com/user-attachments/assets/c4280eca-4480-4c17-a4d1-d4a9b8fb5e4a)
+1. Open a file and press `<leader>oi`. The prompt opens in insert mode.
+2. Type a request, for example "Add a test for the empty-list case".
+3. Press `<Esc>`, then `<CR>` to send.
+4. On V2, press `<leader>od` to review what the agent changed.
 
-Diffs come from OpenCode's session diff API; side-by-side buffers display the recorded revisions, not current files on disk.
+[Getting started](docs/getting-started.md) covers the same steps in more
+detail, plus pickers and completion. Inside Neovim, see `:help opencode.nvim`.
 
-In V2 output, press `D` anywhere in an edit, patch, or apply-patch file block to open its turn's diff with that file selected. Repeat from the same block to close the review tab; selecting another file focuses it in the existing review.
+## Where to go next
 
-## 📸 Contextual Actions for Snapshots (V1 only)
-
-> [!WARNING]
-> Snapshots are experimental and were never an official OpenCode V1 feature. This implementation relies on Git worktree snapshots, which are being replaced in V2 by the more robust [session diffs](#session-diffs-opencode-v2).
-
-Opencode.nvim automatically creates **snapshots** of your workspace at key moments (such as after running prompts or making changes). These snapshots are like lightweight git commits, allowing you to review, compare, and restore your project state at any time.
-
-**Contextual actions** for snapshots are available directly in the output window. When a snapshot is referenced in the conversation, you can trigger actions on it via keymaps displayed by the UI.
-
-### Available Snapshot Actions
-
-- **Diff:** View the differences between the current state and the snapshot.
-- **Revert file:** Revert the selected file to the state it was in at the snapshot.
-- **Revert all files:** Revert all files in the workspace to the state they were
-
-### How to Use
-
-- When a message in the output references a snapshot (look for 📸 **Created Snapshot** or similar), move your cursor to that line and a little menu will be displayed above.
-
-### Example
-
-When you see a snapshot in the output:
-
-<img src="https://i.imgur.com/eKOjhTN.png" alt="Opencode.nvim contextual actions" width="90%" />
-
-> **Tip:** Reverting a snapshot will restore all files to the state they were in at that snapshot, so use it with caution!
-
-## 🕛 Contextual Restore points
-
-Opencode.nvim automatically creates restore points before a revet operation. This allows you to undo a revert if needed.
-
-You will see restore points under the Snapshot line like so:
-<img src="https://i.imgur.com/DKCOdt0.png" alt="Opencode.nvim restore points" width="90%" />
-
-### Available Restore Actions
-
-- **Restore file:** Restore the selected file to the state it was in before the last revert operation.
-- **Restore all :** Restore all files in the workspace to the state they were in before the revert action
-
-## Highlight Groups
-
-The plugin defines several highlight groups that can be customized to match your colorscheme:
-
-- `OpencodeBorder`: Border color for Opencode windows (default: #616161)
-- `OpencodeBackground`: Background color for Opencode windows (linked to `Normal`)
-- `OpencodeSessionDescription`: Session description text color (linked to `Comment`)
-- `OpencodeMention`: Highlight for @file mentions (linked to `Special`)
-- `OpencodeToolBorder`: Border color for tool execution blocks (default: #3b4261)
-- `OpencodeMessageRoleAssistant`: Assistant message highlight (linked to `Added`)
-- `OpencodeMessageRoleUser`: User message highlight (linked to `Question`)
-- `OpencodeDiffAdd`: Highlight for added line in diffs (default: #2B3328)
-- `OpencodeDiffDelete`: Highlight for deleted line in diffs (default: #43242B)
-- `OpencodeAgentPlan`: Agent indicator in winbar for Plan mode (default: #61AFEF background)
-- `OpencodeAgentBuild`: Agent indicator in winbar for Build mode (default: #616161 background)
-- `OpencodeAgentCustom`: Agent indicator in winbar for custom modes (default: #3b4261 background)
-- `OpencodeContestualAction`: Highlight for contextual actions in the output window (default: #3b4261 background)
-- `OpencodeInputLegend`: Highlight for input window legend (default: #CCCCCC background)
-- `OpencodeHint`: Highlight for hinting messages in input window and token info in output window footer (linked to `Comment`)
-
-## 🛡️ Prompt Guard
-
-The `prompt_guard` configuration option allows you to control when prompts can be sent to Opencode. This is useful for preventing accidental or unauthorized AI interactions in certain contexts.
-
-### Configuration
-
-Set `prompt_guard` to a function that returns a boolean:
-
-```lua
-require('opencode').setup({
-  prompt_guard = function()
-    -- Your custom logic here
-    -- Return true to allow, false to deny
-    return true
-  end,
-})
-
-```
-
-## 🪝 Custom user hooks
-
-You can define custom functions to be called at specific events in Opencode:
-
-- `on_file_edited`: Called after a file is edited by Opencode.
-- `on_session_loaded`: Called after a session is loaded.
-- `on_done_thinking`: Called when a session becomes idle, including sessions started outside Neovim.
-- `on_permission_requested`: Called when a permission request is issued.
-- `on_question_asked`: Called when a question is asked.
-- `on_topbar_render`: Receives topbar segments on each render and returns updated segments.
-- `on_footer_render`: Receives footer segments on each render and returns updated segments.
-
-Segments use `{ 'text', 'HighlightGroup', align = 'left'|'right' }`; highlight and alignment are optional, and alignment defaults to `'left'`. Right-aligned segments render after the bar's spacer. Return `nil` to clear that bar. If a hook errors, built-in segments render unchanged.
-
-```lua
-require('opencode').setup({
-  hooks = {
-    on_file_edited = function(file_path, edit_type)
-      -- Custom logic after a file is edited
-      print("File edited: " .. file_path .. " Type: " .. edit_type)
-    end,
-    on_session_loaded = function(session_name)
-      -- Custom logic after a session is loaded
-      print("Session loaded: " .. session_name)
-    end,
-    on_done_thinking = function(session)
-      -- Custom logic when thinking is done; skip subagent sessions
-      if not session.parentID then
-        print("Done thinking in session " .. session.id)
-      end
-    end,
-    on_permission_requested = function()
-      -- Custom logic when a permission is requested
-      print("Permission requested!")
-    end,
-    on_question_asked = function(session)
-      -- Custom logic when a question is asked
-      print("Question asked in session " .. session.id)
-    end,
-    on_footer_render = function(segments)
-      -- Add project context to the footer's left side.
-      table.insert(segments, 1, { 'repo:branch ', 'OpencodeHint' })
-      return segments
-    end,
-  },
-})
-```
-
-### Behavior
-
-- **Before sending prompts**: The guard is checked before any prompt is sent to the AI. If denied, an ERROR notification is shown and the prompt is not sent.
-- **Before opening UI**: The guard is checked when opening the Opencode buffer for the first time. If denied, a WARN notification is shown and the UI is not opened.
-- **No parameters**: The guard function receives no parameters. Access vim state directly (e.g., `vim.fn.getcwd()`, `vim.bo.filetype`).
-- **Error handling**: If the guard function throws an error or returns a non-boolean value, the prompt is denied with an appropriate error message.
-
-## 📡 Server-Sent Events (SSE) autocmds
-
-Opencode.nvim forwards all server-sent events as Neovim User autocmds, allowing you to react to events and automate workflows. All events are fired with the pattern `OpencodeEvent:<event.type>`.
-
-### Event Data Structure
-
-The autocmd receives event data in `args.data.event`:
-
-```lua
-{
-  type = "event.name",  -- Opencode event type
-  properties = { ... }  -- Event-specific properties
-}
-```
-
-### Wildcard Patterns
-
-You can use wildcards to match multiple event types:
-
-- `OpencodeEvent:*` - All events
-- `OpencodeEvent:session.*` - All session events
-- `OpencodeEvent:permission.*` - All permission events
-
-### Example
-
-```lua
-vim.api.nvim_create_autocmd('User', {
-  pattern = 'OpencodeEvent:permission.asked',
-  callback = function(args)
-    local event = args.data.event
-    vim.notify(vim.inspect(event))
-    -- trigger custom logic
-  end,
-})
-```
-
-## Quick chat
-
-Quick chat allows you to start a temporary opencode session with context from the current line or selection.
-This is optimized for narrow code edits or insertion. When the request is complex it will and require more context, it is recommended to use the full opencode UI.
-
-Due to the narrow context the resulting may be less accurate and edits may sometime fails. For best results, try to keep the request focused and simple.
-
-### Starting a quick chat
-
-Press `<leader>o/` in normal mode to open a quick chat input window.
-
-<div align="center">
-  <img src="https://i.imgur.com/5JNlFZn.png">
-</div>
-<div align="center">
-  <img src="https://i.imgur.com/ScRgqfC.png">
-</div>
-
-### Example chat prompts
-
-- Transform to a lua array
-- Add lua annotations
-- Write a conventional commit message for my changes #diff
-- Fix these warnings #warn
-- complete this function
-
-## 🔧 Setting up Opencode
-
-If you're new to opencode:
-
-1. **What is Opencode?**
-   - Opencode is an AI coding agent built for the terminal
-   - It offers powerful AI assistance with extensible configurations such as LLMs and MCP servers
-
-2. **Installation:**
-   - Visit [Install Opencode](https://opencode.ai/docs/#install) for installation and configuration instructions
-   - Ensure the `opencode` command is available after installation
-
-3. **Configuration:**
-   - Run `opencode auth login` to set up your LLM provider
-   - Configure your preferred LLM provider and model in the `~/.config/opencode/config.json` or `~/.config/opencode/opencode.json` file
-
-## Development
-
-Run development commands through the Makefile from the repository root. Use `make help` to list all targets and examples.
-
-| Command | Purpose |
-| ------- | ------- |
-| `make check` | Run formatting checks, Lua type checks, and all tests |
-| `make format-check` | Check Lua formatting without modifying files |
-| `make format` | Format Lua files in place |
-| `make typecheck` | Check Lua types |
-| `make test` | Run all tests |
-| `make test-minimal` | Run minimal tests |
-| `make test-unit` | Run unit tests |
-| `make test-replay` | Run V1/V2 JSON snapshot replays only, with each fixture named in the output |
-| `make replay` | Launch the interactive replay tester |
-| `make replay-regenerate` | Regenerate expected replay snapshots with confirmation |
-| `make topology` | Scan dependency topology |
-| `make topology-diff` | Compare dependency topology snapshots |
-
-Use `TEST` to select a test suite or file, `FILTER` to filter tests, and `ARGS` to pass additional options to the underlying tool:
-
-```sh
-make test TEST=tests/unit/formatter_spec.lua
-make test TEST=unit FILTER="Timer"
-make typecheck ARGS="-f github"
-make replay ARGS="-c ReplayAll"
-make replay-regenerate FILE=v2/formatters.json
-make topology ARGS="--json"
-make topology-diff ARGS="--from main --to HEAD --json"
-```
+| I want to…                            | Read                                                                              |
+| ------------------------------------- | --------------------------------------------------------------------------------- |
+| Learn the everyday workflow           | [Usage](docs/usage.md)                                                            |
+| Control what the agent sees           | [Context](docs/context.md)                                                        |
+| Review changes and send feedback      | [Reviewing changes](docs/review.md)                                               |
+| Adjust windows, keys, or integrations | [Configuration](docs/configuration.md)                                            |
+| Connect to another server             | [Servers](docs/servers.md)                                                        |
+| Browse user recipes                   | [Recipes](docs/recipes/README.md)                                                 |
+| Write mappings or automation          | [Commands and Lua API](docs/reference.md), [Hooks and events](docs/extensions.md) |
+| Fix a setup problem                   | [Troubleshooting](docs/troubleshooting.md)                                        |
+| Contribute code or documentation      | [Contributing](CONTRIBUTING.md)                                                   |
 
-For snapshot regeneration, `FILE` is relative to `tests/data`. See the [dependency topology documentation](./scripts/dependency-topology/README.md) for scanner options and policy details.
+## Credits
 
-## 🙏 Acknowledgements
+Based on [goose.nvim](https://github.com/azorng/goose.nvim) by
+[azorng](https://github.com/azorng). The original code was copied to preserve
+its Git history rather than using a GitHub fork.
 
-This plugin is a fork of the original [goose.nvim](https://github.com/azorng/goose.nvim) plugin by [azorng](https://github.com/azorng/)
-For git history purposes the original code is copied instead of just forked.
+If you find the plugin useful, you can [support its development](https://www.buymeacoffee.com/sudo.tee).
diff --git a/doc/opencode.txt b/doc/opencode.txt
new file mode 100644
index 000000000..b3be49e36
--- /dev/null
+++ b/doc/opencode.txt
@@ -0,0 +1,106 @@
+*opencode.txt*             OpenCode conversations inside Neovim
+
+==============================================================================
+CONTENTS                                                  *opencode.nvim*
+
+    Start here ........................................... |opencode-start|
+    Everyday keys ........................................ |opencode-keys|
+    Configuration ........................................ |opencode-config|
+    Documentation ........................................ |opencode-docs|
+
+==============================================================================
+START HERE                                                *opencode-start*
+
+Install the OpenCode CLI and connect a provider in OpenCode first. Install this
+plugin with your plugin manager, then call setup once: >lua
+
+    require('opencode').setup({})
+<
+With lazy.nvim, `opts = {}` calls setup for you. Run `:checkhealth opencode`
+afterwards. Markdown rendering, pickers, and completion are covered in
+docs/getting-started.md.
+
+Open a project file, press <leader>oi, and type a small request. Leave insert
+mode with <Esc>, then press <CR> to submit. <S-CR> also submits in insert
+mode when your terminal supports it. <Esc> closes the panel in normal mode.
+
+The current file is context by default. Type # in input insert mode to inspect
+context before sending. OpenCode permissions control tool access; review edits
+and keep important work committed or backed up.
+
+The current plugin supports OpenCode V1 and V2. The v1 plugin branch preserves
+the old implementation; it is not needed to connect to a V1 server.
+
+==============================================================================
+EVERYDAY KEYS                                             *opencode-keys*
+
+Global defaults: >
+    <leader>og    Hide or restore panel
+    <leader>oi    Focus input in insert mode
+    <leader>oo    Focus output
+    <leader>ot    Switch panel/editor focus
+    <leader>oy    Add visual selection as context (visual mode)
+    <leader>oY    Insert selected code inline (visual mode)
+    <leader>os    Resume a session
+    <leader>oI    Start a new session
+    <leader>oN    Start a new session in a panel tab
+    <leader>op    Choose provider/model
+    <leader>od    Review session diff (V2)
+    <leader>o/    Quick chat (experimental)
+<
+In the panel: >
+    <Tab>         Switch input/output (normal mode)
+    <C-c>         Cancel running request
+    ]] / [[       Next/previous message (output, normal mode)
+    gf            Jump to referenced file (output, normal mode)
+    @ / ~         Mention completion / file picker (input, insert mode)
+    #             Inspect context (input, insert mode)
+    /             Browse slash commands (input, insert mode)
+<
+Use :Opencode help for available actions and :Opencode with command-line
+completion to explore subcommands. Keys above assume the default prefix.
+
+==============================================================================
+CONFIGURATION                                            *opencode-config*
+
+Override only what you need: >lua
+
+    require('opencode').setup({
+      keymap_prefix = '<leader>a',
+      ui = { window_width = 0.35, icons = { preset = 'text' } },
+    })
+<
+Every option and default keymap is listed in docs/configuration.md. To print
+the options in effect: >vim
+
+    :lua =require('opencode.config').values
+<
+The output can include server credentials; check it before sharing.
+
+For a local V2 install, leave `server` unset: the plugin finds OpenCode's
+background service. Quitting Neovim does not stop that service. See
+docs/servers.md for remote servers, containers, and WSL.
+
+Lua API: require('opencode.api'). Signatures are in lua/opencode/types.lua.
+
+==============================================================================
+DOCUMENTATION                                              *opencode-docs*
+
+The full documentation is in the docs/ directory of the plugin checkout, and
+online at:
+
+    https://github.com/sudo-tee/opencode.nvim/blob/main/docs/README.md
+
+The copy in your checkout matches the version you have installed.
+
+    docs/getting-started.md    Installation and first prompt
+    docs/usage.md              Sessions, tabs, permissions, quick chat
+    docs/context.md            What gets sent with a prompt
+    docs/review.md             V2 diffs and inline comments
+    docs/configuration.md      All options and default keymaps
+    docs/reference.md          Commands and Lua API
+    docs/extensions.md         Hooks, User autocmds, highlights
+    docs/servers.md            Remote servers and authentication
+    docs/troubleshooting.md    Diagnosis and bug reports
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/docs/README.md b/docs/README.md
index 08d276cd1..2a5e284a6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,23 +1,28 @@
-# Opencode.nvim Documentation
+# Documentation
 
-## Recipes
+New to the plugin? Start with [Getting started](getting-started.md). Inside
+Neovim, `:help opencode.nvim` has a short summary.
 
-Community-contributed configurations and workflows for opencode.nvim.
+## Guides
 
-### Available Recipes
+- [Getting started](getting-started.md): install, check the setup, and send a first prompt.
+- [Usage](usage.md): models, sessions and panel tabs, agents, the panel, permissions, prompt history.
+- [Quick chat](quick-chat.md): in-place edits, commit messages, and custom ad-hoc commands.
+- [Context](context.md): what is sent with a prompt and how to change it.
+- [Reviewing changes](review.md): V2 session diffs and inline review comments.
+- [Servers](servers.md): remote servers, authentication, containers, WSL.
+- [Troubleshooting](troubleshooting.md): connection, keymap, and rendering problems; bug reports.
 
-- [Bidirectional TUI/nvim Sync](./recipes/bidirectional-sync/README.md) - Share sessions between TUI and nvim plugin seamlessly
-- [Three-State Layout Toggle](./recipes/three-state-layout/README.md) - Instantly switch between code/split/dialog viewing modes
-- [Change-by-Change Review](./recipes/change-by-change-review/README.md) - Review Opencode edits using diffview+ and gitsigns
-- [Review a Session Diff](./recipes/review-session-diff.md) - Comment on changed lines and send review comments as prompt context
+## Reference
 
-### Contributing a Recipe
+- [Configuration](configuration.md): common options and the full defaults.
+- [Commands and Lua API](reference.md): `:Opencode` commands, Lua calls, slash commands, skills.
+- [Hooks and events](extensions.md): callbacks, prompt guard, User autocmds, highlights.
+- [Compatibility](compatibility.md): V1 and V2 differences, V1 snapshots.
 
-Want to share your setup? Use the [Recipe Template](./recipes/TEMPLATE.md) to ensure consistency:
+## Recipes
 
-- Start with the problem you're solving
-- Include a GIF demonstration
-- Provide step-by-step setup instructions
-- Cross-reference related recipes
+[Recipes](recipes/README.md) are optional setups for particular workflows, such
+as sharing a session with the TUI or a three-way layout toggle.
 
-Recipes should be self-contained and solve a specific workflow need.
+To contribute, see [CONTRIBUTING.md](../CONTRIBUTING.md).
diff --git a/docs/compatibility.md b/docs/compatibility.md
new file mode 100644
index 000000000..4f93c53f1
--- /dev/null
+++ b/docs/compatibility.md
@@ -0,0 +1,54 @@
+# Compatibility
+
+[Documentation](README.md) / Compatibility
+
+The plugin works with both OpenCode V1 and V2. It detects the protocol from the
+server's health response; there is nothing to configure.
+
+| Area | V2 | V1 |
+| --- | --- | --- |
+| Local startup | Native background service when supported by the CLI | Local `serve` process |
+| Chat, context, sessions | Supported | Supported |
+| Change review | Session diff API and inline review comments | Experimental Git-worktree snapshots |
+| Skills | Native activation or skill attachment when the server supports it | Skill content sent as a prompt |
+| Service shutdown | Owned by OpenCode | Plugin-managed process cleanup |
+
+Some features depend on what your server version supports. If one is missing,
+update OpenCode.
+
+## The legacy plugin branch
+
+To stay on the old plugin implementation:
+
+```lua
+return { 'sudo-tee/opencode.nvim', branch = 'v1' }
+```
+
+You don't need this to talk to a V1 server. These docs cover the current
+branch; the `v1` branch has its own README.
+
+## V1 snapshots and restore points
+
+> [!WARNING]
+> V1 snapshots are experimental and were never an official OpenCode feature.
+> Reverting overwrites files, so commit first. V2 uses
+> [session diffs](review.md) instead.
+
+On V1 the plugin keeps Git-worktree snapshots of the workspace. Put the cursor
+on a snapshot in the output to get these actions:
+
+- Diff: compare the current files with the snapshot.
+- Revert file: restore one file from the snapshot.
+- Revert all: restore every file from the snapshot.
+
+`<leader>ora` / `<leader>ort` revert all/current-file changes since the last
+prompt; `<leader>orA` / `<leader>orT` target the session snapshot. Snapshot-specific
+commands are listed in the [reference](reference.md#legacy-snapshot-actions-v1).
+
+Each revert first saves a restore point. Its Restore file and Restore all
+actions undo the revert. `<leader>orr` and `<leader>orR` do the same from the
+keyboard.
+
+`snapshot_path` sets where snapshots are stored. The default is OpenCode's data
+directory (`$XDG_DATA_HOME/opencode`), and the plugin appends
+`/snapshot/<project_id>/<worktree_hash>`. It only affects V1.
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 000000000..99e52ed32
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,643 @@
+# Configuration
+
+[Documentation](README.md) / Configuration
+
+Start with `setup({})` and set only what you want to change. Every option and
+keymap is in the [full default configuration](#full-default-configuration);
+types are in [`lua/opencode/types.lua`](../lua/opencode/types.lua).
+
+To see the settings in effect:
+
+```vim
+:lua print(vim.inspect(require('opencode.config').values))
+```
+
+Server credentials show up in this output, so check it before sharing.
+
+## Full default configuration
+
+Optional callbacks and values are shown as `nil`.
+
+<details open>
+<summary>Show all default options</summary>
+
+```lua
+require('opencode').setup({
+  preferred_picker = nil,
+  default_global_keymaps = true,
+  default_mode = 'build',
+  default_system_prompt = nil,
+  keymap_prefix = '<leader>o',
+  opencode_executable = 'opencode',
+  lock_session_to_directory = false,
+  server = {
+    url = nil,
+    port = nil,
+    timeout = 5,
+    retry_delay = 2000,
+    health_check_ttl_ms = 5000,
+    spawn_command = nil,
+    kill_command = nil,
+    auto_kill = true,
+    path_map = nil,
+    reverse_path_map = nil,
+    username = nil,
+    password = nil,
+    password_file = nil,
+  },
+  -- stylua: ignore
+  keymap = {
+    session_diff = {
+      list = {
+        ['<CR>'] = { 'activate', desc = 'Open file or toggle folder' },
+        ['gf'] = { 'open_file', desc = 'Open working-tree file in a new tab' },
+        ['<Tab>'] = { 'next_file', desc = 'Next file' },
+        ['<S-Tab>'] = { 'prev_file', desc = 'Previous file' },
+        ['r'] = { 'toggle_range', desc = 'Choose message range', nowait = true },
+        ['p'] = { 'toggle_view', desc = 'Toggle diff layout' },
+        ['q'] = { 'close', desc = 'Close diff', nowait = true },
+        ['g?'] = { 'toggle_help', desc = 'Toggle keymap help' },
+      },
+      messages = {
+        ['<CR>'] = { 'activate', desc = 'Review selected range' },
+        ['r'] = { 'toggle_range', desc = 'Return to files' },
+        ['f'] = { 'mark_from', desc = 'Mark range start' },
+        ['t'] = { 'mark_to', desc = 'Mark range end' },
+        ['K'] = { 'show_message_preview', desc = 'Preview message' },
+        ['<Esc>'] = { 'toggle_range', desc = 'Return to files' },
+        ['q'] = { 'toggle_range', desc = 'Return to files', nowait = true },
+        ['g?'] = { 'toggle_help', desc = 'Toggle keymap help' },
+      },
+      preview = {
+        ['gf'] = { 'open_file', desc = 'Open working-tree file in a new tab' },
+        ['<Tab>'] = { 'next_file', desc = 'Next file' },
+        ['<S-Tab>'] = { 'prev_file', desc = 'Previous file' },
+        ['q'] = { 'close', desc = 'Close diff', nowait = true },
+        ['p'] = { 'toggle_view', desc = 'Toggle diff layout' },
+        ['g?'] = { 'toggle_help', desc = 'Toggle keymap help' },
+        ['c'] = { 'add_comment', mode = { 'n', 'x' },  desc = 'Add or edit review comment', nowait = true  },
+        ['dc'] = { 'delete_comment', desc = 'Delete review comment' },
+        [']r'] = { 'next_comment', desc = 'Next review comment' },
+        ['[r'] = { 'prev_comment', desc = 'Previous review comment' },
+      },
+      comment = {
+        ['<CR>'] = { 'submit_comment', mode = 'n', desc = 'Save review comment' },
+        ['<C-s>'] = { 'submit_comment', mode = { 'n', 'i' }, desc = 'Save review comment' },
+        ['q'] = { 'cancel_comment', desc = 'Cancel review comment', nowait = true },
+        ['<Esc>'] = { 'cancel_comment', desc = 'Cancel review comment' },
+      },
+      message_preview = {
+        ['q'] = { 'hide_message_preview', desc = 'Close message preview', nowait = true },
+        ['<Esc>'] = { 'hide_message_preview', desc = 'Close message preview' },
+        ['g?'] = { 'toggle_help', desc = 'Toggle keymap help' },
+      },
+      help = {
+        ['g?'] = { 'toggle_help' },
+        ['q'] = { 'toggle_help', nowait = true },
+        ['<Esc>'] = { 'toggle_help' },
+      },
+    },
+    editor = {
+      ['<leader>og'] =  { 'toggle',                                            desc = 'Toggle Opencode window' },
+      ['<leader>oi'] =  { 'open_input',                                        desc = 'Open input window' },
+      ['<leader>oI'] =  { 'open_input_new_session',                            desc = 'Open input (new session)' },
+      ['<leader>oN'] =  { 'open_session_tab',                                  desc = 'Open new Opencode session tab' },
+      ['<leader>o<'] =  { 'prev_session_tab',                                  desc = 'Previous Opencode session tab' },
+      ['<leader>o>'] =  { 'next_session_tab',                                  desc = 'Next Opencode session tab' },
+      ['<leader>o?'] =  { 'select_session_tab',                                desc = 'Select Opencode session tab' },
+      ['<leader>o1'] =  { 'select_session_tab', { 1 },                          desc = 'Select Opencode session tab 1' },
+      ['<leader>o2'] =  { 'select_session_tab', { 2 },                          desc = 'Select Opencode session tab 2' },
+      ['<leader>o3'] =  { 'select_session_tab', { 3 },                          desc = 'Select Opencode session tab 3' },
+      ['<leader>o4'] =  { 'select_session_tab', { 4 },                          desc = 'Select Opencode session tab 4' },
+      ['<leader>o5'] =  { 'select_session_tab', { 5 },                          desc = 'Select Opencode session tab 5' },
+      ['<leader>o6'] =  { 'select_session_tab', { 6 },                          desc = 'Select Opencode session tab 6' },
+      ['<leader>o7'] =  { 'select_session_tab', { 7 },                          desc = 'Select Opencode session tab 7' },
+      ['<leader>o8'] =  { 'select_session_tab', { 8 },                          desc = 'Select Opencode session tab 8' },
+      ['<leader>o9'] =  { 'select_session_tab', { 9 },                          desc = 'Select Opencode session tab 9' },
+      ['<leader>oh'] =  { 'select_history',                                    desc = 'Select from history' },
+      ['<leader>oo'] =  { 'open_output',                                       desc = 'Open output window' },
+      ['<leader>ot'] =  { 'toggle_focus',                                      desc = 'Toggle focus' },
+      ['<leader>oT'] =  { 'timeline',                                          desc = 'Session timeline' },
+      ['<leader>oq'] =  { 'close',                                             desc = 'Close Opencode window' },
+      ['<leader>oQ'] =  { 'close_session_tab',                                 desc = 'Close current Opencode session tab' },
+      ['<leader>os'] =  { 'select_session',                                    desc = 'Select session' },
+      ['<leader>oS'] =  { 'navigate_session_tree', { 'child', 'picker' },     desc = 'Select child session' },
+      ['<leader>oP'] =  { 'navigate_session_tree', { 'parent' },              desc = 'Go to parent session' },
+      ['<leader>oB'] =  { 'navigate_session_tree', { 'sibling', 'picker' },   desc = 'Select sibling session' },
+      ['<leader>oR'] =  { 'rename_session',                                    desc = 'Rename session' },
+      ['<leader>op'] =  { 'configure_provider',                                desc = 'Configure provider' },
+      ['<leader>oV'] =  { 'configure_variant',                                 desc = 'Configure model variant' },
+      ['<leader>oy'] =  { 'add_visual_selection',         mode = { 'v' },      desc = 'Add visual selection to context' },
+      ['<leader>oY'] =  { 'add_visual_selection_inline',  mode = { 'v' },      desc = 'Insert visual selection inline into input' },
+      ['<leader>oz'] =  { 'toggle_zoom',                                       desc = 'Toggle zoom' },
+      ['<leader>ov'] =  { 'paste_image',                                       desc = 'Paste image from clipboard' },
+      ['<leader>od'] =  { 'diff_open',                                         desc = 'Open diff view' },
+      ['<leader>o]'] =  { 'diff_next',                                         desc = 'Next diff' },
+      ['<leader>o['] =  { 'diff_prev',                                         desc = 'Previous diff' },
+      ['<leader>oc'] =  { 'diff_close',                                        desc = 'Close diff view' },
+      ['<leader>ora'] = { 'diff_revert_all_last_prompt',                       desc = 'Revert all (last prompt)' },
+      ['<leader>ort'] = { 'diff_revert_this_last_prompt',                      desc = 'Revert this (last prompt)' },
+      ['<leader>orA'] = { 'diff_revert_all',                                   desc = 'Revert all changes' },
+      ['<leader>orT'] = { 'diff_revert_this',                                  desc = 'Revert this change' },
+      ['<leader>orr'] = { 'diff_restore_snapshot_file',                        desc = 'Restore file snapshot' },
+      ['<leader>orR'] = { 'diff_restore_snapshot_all',                         desc = 'Restore all snapshots' },
+      ['<leader>ox'] =  { 'swap_position',                                     desc = 'Swap window position' },
+      ['<leader>otr'] = { 'toggle_reasoning_output',                           desc = 'Toggle reasoning output' },
+      ['<leader>ott'] = { 'toggle_tool_output',                                desc = 'Toggle tool output' },
+      ['<leader>otm'] = { 'toggle_max_messages',                               desc = 'Toggle max messages' },
+      ['<leader>o/'] =  { 'quick_chat',                   mode = { 'n', 'x' }, desc = 'Quick chat with current context' },
+      ['<leader>oDu'] = { 'copy_server_url',                                   desc = 'Copy server url' },
+
+    },
+    output_window = {
+      ['gg'] =         { 'first_message',                                     desc = 'Load history and go to the first message' },
+      ['<esc>'] =       { 'close',                                             desc = 'Close Opencode windows' },
+      ['<C-c>'] =       { 'cancel',                                            desc = 'Cancel running request' },
+      [']]']   =        { 'next_message',                                      desc = 'Go to next message' },
+      ['[[']   =        { 'prev_message',                                      desc = 'Go to previous message' },
+      [']u']   =        { 'next_user_message',                                 desc = 'Go to next user message' },
+      ['[u']   =        { 'prev_user_message',                                 desc = 'Go to previous user message' },
+      ['<tab>'] =       { 'toggle_pane',                  mode = { 'n' },      desc = 'Toggle input/output panes' },
+      ['i']     =       { 'focus_input',                                       desc = 'Focus input window' },
+      ['gr']    =       { 'references',                                        desc = 'Browse code references' },
+      ['gf']    =       { 'jump_to_file',                                       desc = 'Jump to file at cursor' },
+      ['<CR>']  =       { 'jump_to_target_at_cursor',                          desc = 'Jump to target at cursor' },
+      ['gd']    =       { 'jump_to_target_at_cursor',                          desc = 'Jump to target at cursor' },
+      ['<M-i>'] =       { 'toggle_input',                 mode = { 'n' },      desc = 'Toggle input window' },
+      ['<M-r>'] =       { 'cycle_variant',                mode = { 'n' },      desc = 'Cycle model variants' },
+      ['<leader>oS'] =  { 'navigate_session_tree', { 'child', 'picker' },     desc = 'Select child session' },
+      ['<leader>oP'] =  { 'navigate_session_tree', { 'parent' },              desc = 'Go to parent session' },
+      ['<leader>oB'] =  { 'navigate_session_tree', { 'sibling', 'picker' },   desc = 'Select sibling session' },
+      ['<leader>oD'] =  { 'debug_message',                                     desc = 'Open raw message debug view' },
+      ['<leader>oO'] =  { 'debug_output',                                      desc = 'Open raw output debug view' },
+      ['<leader>oDs'] = { 'debug_session',                                     desc = 'Open raw session debug view' },
+    },
+    tab_strip_window = {
+      ['<LeftMouse>'] =   { 'select_session_tab_target', { 'mouse' },  nowait = true, desc = 'Select tab under mouse' },
+      ['<2-LeftMouse>'] = { 'select_session_tab_target', { 'mouse' },  nowait = true, desc = 'Select tab under mouse' },
+      ['<CR>'] =          { 'select_session_tab_target', { 'cursor' }, nowait = true, desc = 'Select tab under cursor' },
+    },
+    input_window = {
+      ['<cr>']   =      { 'submit_input_prompt',          mode = { 'n' },      desc = 'Submit prompt'                                            },
+      ['<S-cr>'] =      { 'submit_input_prompt',          mode = { 'n', 'i' }, desc = 'Submit prompt'                                            },
+      ['<esc>']  =      { 'close',                                             desc = 'Close Opencode windows',       defer_to_completion = true },
+      ['<C-c>']  =      { 'cancel',                                            desc = 'Cancel running request' ,      defer_to_completion = true },
+      ['~']      =      { 'mention_file',                 mode = 'i',          desc = 'Mention file in context'                                  },
+      ['@']      =      { 'mention',                      mode = 'i',          desc = 'Open mention picker'                                      },
+      ['/']      =      { 'slash_commands',               mode = 'i',          desc = 'Open slash commands picker'                               },
+      ['#']      =      { 'context_items',                mode = 'i',          desc = 'Open context items picker'                                },
+      ['<M-v>']  =      { 'paste_image',                  mode = 'i',          desc = 'Paste image from clipboard'                               },
+      ['<tab>']  =      { 'toggle_pane',                  mode = { 'n' },      desc = 'Toggle input/output panes',    defer_to_completion = true },
+      ['<up>']   =      { 'prev_prompt_history',          mode = { 'n', 'i' }, desc = 'Previous prompt history item', defer_to_completion = true },
+      ['<down>'] =      { 'next_prompt_history',          mode = { 'n', 'i' }, desc = 'Next prompt history item' ,    defer_to_completion = true },
+      ['<M-m>']  =      { 'switch_mode',                  mode = { 'n', 'i' }, desc = 'Switch agent mode'                                        },
+      ['<M-r>']  =      { 'cycle_variant',                mode = { 'n', 'i' }, desc = 'Cycle model variants'                                     },
+      ['<M-i>']  =      { 'toggle_input',                 mode = { 'n', 'i' }, desc = 'Toggle input window'                                      },
+      ['gr']     =      { 'references',                                        desc = 'Browse code references'                                   },
+      ['<leader>oS'] =  { 'navigate_session_tree', { 'child', 'picker' },     desc = 'Select child session' },
+      ['<leader>oP'] =  { 'navigate_session_tree', { 'parent' },              desc = 'Go to parent session' },
+      ['<leader>oB'] =  { 'navigate_session_tree', { 'sibling', 'picker' },   desc = 'Select sibling session' },
+      ['<leader>oD'] =  { 'debug_message',                                     desc = 'Open raw message debug view'                              },
+      ['<leader>oO'] =  { 'debug_output',                                      desc = 'Open raw output debug view'                               },
+      ['<leader>oDs'] = { 'debug_session',                                     desc = 'Open raw session debug view'                              },
+    },
+    session_picker = {
+      rename_session = { '<C-r>',                                              desc = 'Rename selected session' },
+      delete_session = { '<C-d>',                                              desc = 'Delete selected sessions' },
+      new_session =    { '<C-s>',                                              desc = 'Create a new session' },
+      open_in_tab =    { '<C-t>',                                              desc = 'Open selected session in a new panel tab' },
+      fork_session =  { '<C-f>',                                              desc = 'Fork selected session' },
+      toggle_scope =  { '<C-g>',                                              desc = 'Toggle between project/global scope' },
+    },
+    session_tab_picker = {
+      new_tab =   { '<C-s>', desc = 'Create a new panel tab' },
+      close_tab = { '<C-d>', desc = 'Close selected panel tab' },
+    },
+    timeline_picker = {
+      undo = { '<C-u>',                                   mode = { 'i', 'n' }, desc = 'Undo to selected message' },
+      fork = { '<C-f>',                                   mode = { 'i', 'n' }, desc = 'Fork from selected message' },
+    },
+    history_picker = {
+      delete_entry = { '<C-d>',                           mode = { 'i', 'n' }, desc = 'Delete selected history entries' },
+      clear_all =    { '<C-X>',                           mode = { 'i', 'n' }, desc = 'Clear all history entries' },
+    },
+    model_picker = {
+      toggle_favorite = { '<C-f>',                        mode = { 'i', 'n' }, desc = 'Toggle model favorite' },
+    },
+    mcp_picker = {
+      toggle_connection = { '<C-t>',                      mode = { 'i', 'n' }, desc = 'Toggle MCP server connection' },
+    },
+    quick_chat = {
+      cancel = { '<C-c>',                                 mode = { 'i', 'n' }, desc = 'Cancel active quick chat requests' },
+    },
+  },
+  ui = {
+    enable_treesitter_markdown = true,
+    position = 'right',
+    input_position = 'bottom',
+    window_width = 0.40,
+    zoom_width = 0.8,
+    float = {
+      width = 0.95,
+      height = 0.9,
+      row = nil,
+      col = nil,
+      border = 'rounded',
+      gap = 1,
+      zindex = 40,
+      opts = {
+        winblend = 0,
+      },
+    },
+    picker_width = 100,
+    display_model = true,
+    display_context_size = true,
+    display_cost = true,
+    hide_single_tab = true,
+    notify_on_background_prompt = true,
+    window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder',
+    persist_state = true,
+    icons = {
+      preset = 'nerdfonts',
+      overrides = {},
+    },
+    loading_animation = {
+      frames = { '⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏' },
+    },
+    output = {
+      filetype = 'opencode_output',
+      time_format = nil,
+      compact_assistant_headers = false,
+      actions = {
+        open_in_new_tab = false,
+      },
+      rendering = {
+        markdown_debounce_ms = 250,
+        on_data_rendered = nil,
+        markdown_on_idle = false,
+        -- If set to a number, markdown rendering will be deferred while
+        -- `state.user_message_count[session_id]` is greater than this value.
+        -- If `nil`, the existing behavior is used (defer while > 0).
+        markdown_on_idle_threshold = nil,
+        event_throttle_ms = 40,
+        event_collapsing = true,
+      },
+      tools = {
+        show_output = true,
+        show_reasoning_output = true,
+        use_folds = true,
+        fold_exclude = { { server = 'sequential-thinking', tool = 'sequentialthinking' } },
+        -- Reduced default threshold to make small tool outputs foldable by default.
+        -- Users can override this in their config if they prefer the previous value.
+        folding_threshold = 25,
+      },
+
+      max_messages = nil,
+      always_scroll_to_bottom = false,
+    },
+    questions = {
+      use_vim_ui_select = false, -- If true, render questions with vim.ui.select instead of in the output buffer
+      inline_other_input = true, -- If true, show an inline floating input for "Other" instead of cmdline prompt
+    },
+    input = {
+      min_height = 0.10,
+      max_height = 0.25,
+      text = {
+        wrap = false,
+      },
+      -- Auto-hide input window when prompt is submitted or focus switches to output window
+      auto_hide = false,
+      -- Window-local options applied to the input window.
+      -- Any valid Neovim window option can be added here.
+      -- Users can override these and add any extra option, e.g.:
+      --   win_options = { signcolumn = 'no', cursorline = true, conceallevel = 2 }
+      win_options = {
+        signcolumn = 'yes',
+        cursorline = false,
+        number = false,
+        relativenumber = false,
+      },
+    },
+    picker = {
+      snacks_layout = nil,
+    },
+    completion = {
+      file_sources = {
+        enabled = true,
+        preferred_cli_tool = 'server',
+        ignore_patterns = {
+          '^%.git/',
+          '^%.svn/',
+          '^%.hg/',
+          '^%.jj/',
+          'node_modules/',
+          '%.pyc$',
+          '%.o$',
+          '%.obj$',
+          '%.exe$',
+          '%.dll$',
+          '%.so$',
+          '%.dylib$',
+          '%.class$',
+          '%.jar$',
+          '%.war$',
+          '%.ear$',
+          'target/',
+          'build/',
+          'dist/',
+          'out/',
+          'deps/',
+          '%.tmp$',
+          '%.temp$',
+          '%.log$',
+          '%.cache$',
+        },
+        max_files = 10,
+        max_display_length = 50,
+      },
+    },
+  },
+  context = {
+    enabled = true,
+    cursor_data = {
+      enabled = false,
+      context_lines = 5, -- Number of lines before and after cursor to include in context
+    },
+    diagnostics = {
+      enabled = true,
+      info = false,
+      warning = true,
+      error = true,
+      only_closest = true, -- Only diagnostics for cursor/selection; disable to include the whole buffer
+    },
+    current_file = {
+      enabled = true,
+      show_full_path = true,
+    },
+    files = {
+      enabled = true,
+      show_full_path = true,
+    },
+    selection = {
+      enabled = true,
+    },
+    review_comments = {
+      enabled = true,
+    },
+    agents = {
+      enabled = true,
+    },
+    buffer = {
+      enabled = false, -- Disable entire buffer context by default, only used in quick chat
+    },
+    git_diff = {
+      enabled = false,
+    },
+  },
+  logging = {
+    enabled = false,
+    level = 'info', -- debug, info, warn, error
+    outfile = nil,
+  },
+  debug = {
+    enabled = false,
+    capture_streamed_events = false,
+    show_ids = true,
+    highlight_changed_lines = false,
+    highlight_changed_lines_timeout_ms = 120,
+    quick_chat = {
+      keep_session = false,
+      set_active_session = false,
+    },
+  },
+  prompt_guard = nil,
+  child_readonly = true,
+  snapshot_path = nil,
+  hooks = {
+    on_file_edited = nil,
+    on_session_loaded = nil,
+    on_done_thinking = nil,
+    on_permission_requested = nil,
+    on_question_asked = nil,
+    on_topbar_render = nil,
+    on_footer_render = nil,
+  },
+  quick_chat = {
+    default_model = nil,
+    default_agent = nil,
+    instructions = nil, -- Use instructions prompt by default
+  },
+})
+```
+
+</details>
+
+## Keymaps
+
+Mappings are grouped by where they apply:
+
+- `editor`: global mappings.
+- `input_window`, `output_window`, `tab_strip_window`: panel-local mappings.
+- `session_diff`: review-local mappings, split into `list`, `messages`,
+  `preview`, `comment`, `message_preview`, and `help`.
+- Picker tables such as `session_picker`, `timeline_picker`, `history_picker`,
+  `model_picker`, and `mcp_picker`: action names mapped to keys.
+
+A panel mapping entry accepts an action name or callback, an optional argument
+table, and options including `mode`, `desc`, and `defer_to_completion`.
+Unspecified mappings keep their defaults; `false` disables a key.
+
+```lua
+require('opencode').setup({
+  keymap = {
+    input_window = {
+      ['<S-cr>'] = false,
+      ['<C-s>'] = {
+        'submit_input_prompt',
+        mode = { 'n', 'i' },
+        desc = 'Send prompt',
+      },
+    },
+    editor = {
+      ['<leader>oy'] = {
+        'add_visual_selection', { open_input = false }, mode = { 'v' },
+      },
+    },
+  },
+})
+```
+
+`defer_to_completion = true` lets an open completion menu handle the key before
+the plugin action. It is useful for keys such as `<Tab>`, `<Up>`, and `<Down>`.
+
+To own all global mappings, disable defaults and define only your keys:
+
+```lua
+require('opencode').setup({
+  default_global_keymaps = false,
+  keymap = {
+    editor = {
+      ['<leader>ai'] = { 'open_input', desc = 'Ask OpenCode' },
+      ['<leader>ad'] = { 'diff_open', desc = 'Review OpenCode changes' },
+    },
+  },
+})
+```
+
+This does not disable panel-local mappings. The full current bindings are in
+[`config.lua`](../lua/opencode/config.lua); the [usage guide](usage.md) lists
+the everyday ones. Session diff remapping has its own [example](review.md#customize-review-keys).
+
+## Window layout
+
+| Option                               | Default         | Meaning                                              |
+| ------------------------------------ | --------------- | ---------------------------------------------------- |
+| `ui.position`                        | `'right'`       | `right`, `left`, `current`, or `float`               |
+| `ui.input_position`                  | `'bottom'`      | `bottom` or `top`                                    |
+| `ui.window_width`                    | `0.40`          | Split width as a fraction of editor width            |
+| `ui.zoom_width`                      | `0.8`           | Zoomed split width                                   |
+| `ui.persist_state`                   | `true`          | Preserve UI buffers when closing/hiding              |
+| `ui.input.min_height` / `max_height` | `0.10` / `0.25` | Input height bounds as window-height fractions       |
+| `ui.input.text.wrap`                 | `false`         | Wrap prompt text                                     |
+| `ui.input.auto_hide`                 | `false`         | Hide input after submission or focus moves to output |
+| `ui.hide_single_tab`                 | `true`          | Hide the strip with one panel tab                    |
+| `ui.notify_on_background_prompt`     | `true`          | Notify about background questions/permissions        |
+
+Floating windows use `ui.float`, with width `0.95`, height `0.9`, rounded border,
+gap `1`, and z-index `40` by default. Optional `row` and `col` control position.
+
+Apply window-local input options with `ui.input.win_options`:
+
+```lua
+require('opencode').setup({
+  ui = {
+    input = {
+      text = { wrap = true },
+      win_options = { signcolumn = 'no', cursorline = true },
+    },
+  },
+})
+```
+
+For a more involved layout toggle, see the
+[three-state recipe](recipes/three-state-layout/README.md).
+
+## Output and rendering
+
+- `ui.display_model`, `display_context_size`, and `display_cost` are on by default.
+- `ui.output.compact_assistant_headers` accepts `false`/`'full'`,
+  `true`/`'minimal'`, or `'hidden'`. Minimal headers collapse repeated agent
+  information.
+- `ui.output.max_messages = nil` means no initial limit. With a limit, scrolling
+  up, `[[`, or `gg` loads older messages. `<leader>otm` toggles the limit.
+- `ui.output.always_scroll_to_bottom = false` allows reading older output.
+- `ui.output.time_format` accepts an `os.date` format or `nil` for the default.
+- `ui.output.actions.open_in_new_tab = false` makes inline child/fork actions
+  replace the active session. Set it to `true` to open them in a new panel tab.
+
+Tool output and reasoning are shown by default. Foldable output uses a threshold
+of 25 lines. Customize with:
+
+```lua
+require('opencode').setup({
+  ui = {
+    output = {
+      tools = {
+        show_reasoning_output = false,
+        folding_threshold = 40,
+        fold_exclude = {
+          'bash',
+          { server = 'sequential-thinking', tool = 'sequentialthinking' },
+        },
+      },
+    },
+  },
+})
+```
+
+`fold_exclude` accepts exact built-in tool names or MCP server/tool pairs.
+`<leader>ott` and `<leader>otr` toggle tool and reasoning output at runtime.
+
+Markdown Treesitter support is enabled by `ui.enable_treesitter_markdown`.
+Rendering settings live under `ui.output.rendering`: debounce is `250` ms,
+stream-event throttle is `40` ms, and event collapsing is on. Set
+`on_data_rendered` to a callback `(buf, win)` to customize post-render behavior,
+or `false` to disable the default RenderMarkdown/Markview behavior.
+For slower setups, `markdown_on_idle = true` defers Markdown rendering while
+prompts are active; `markdown_on_idle_threshold` adjusts that threshold.
+
+## Icons
+
+The default preset is `nerdfonts`. For a plain-text UI:
+
+```lua
+require('opencode').setup({
+  ui = { icons = { preset = 'text' } },
+})
+```
+
+Override individual keys without replacing the preset:
+
+```lua
+require('opencode').setup({
+  ui = {
+    icons = {
+      preset = 'text',
+      overrides = { header_user = '> ', header_assistant = 'AI ', search = 'FIND ' },
+    },
+  },
+})
+```
+
+All supported keys are listed in [`ui/icons.lua`](../lua/opencode/ui/icons.lua).
+Highlight customization is covered in [Hooks and events](extensions.md#highlights).
+
+## Context
+
+Read [Context](context.md) for what gets sent and when. A focused setup might
+disable automatic current-file attachment while keeping selections:
+
+```lua
+require('opencode').setup({
+  context = {
+    current_file = { enabled = false },
+    selection = { enabled = true },
+    diagnostics = { only_closest = false, info = false, warning = true, error = true },
+  },
+})
+```
+
+Cursor context is off by default; enable it with
+`context.cursor_data = { enabled = true, context_lines = 5 }`.
+Current and mentioned file display paths are controlled by
+`context.current_file.show_full_path` and `context.files.show_full_path`.
+
+## Pickers and completion
+
+File completion asks the server for files by default. To use a local tool,
+set `ui.completion.file_sources.preferred_cli_tool` to `fd`, `fdfind`, `rg`, or
+`git`; `nil` is the same as `'server'`. Whichever tool is chosen, the others
+are tried in turn if it fails. Results are capped at 10 files and displayed
+paths at 50 characters. `ignore_patterns` takes Lua patterns, not shell globs;
+check the defaults before overriding it.
+
+Snacks pickers inherit your Snacks layout unless you set an override:
+
+```lua
+require('opencode').setup({
+  ui = { picker = { snacks_layout = { preset = 'select' } } },
+})
+```
+
+The same field accepts a complete Snacks layout configuration or one of your
+custom presets. See [Snacks picker layouts](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md)
+for that schema.
+
+Related recipe: [quiet Blink completion](recipes/quiet-blink.md).
+Use `~` in input insert mode to add files with your preferred picker.
+
+## Hooks, guards, and diagnostics
+
+[Hooks and events](extensions.md) covers `hooks` and `prompt_guard`.
+[Troubleshooting](troubleshooting.md#enable-plugin-logging) covers `logging` and
+debug buffers. Logging is off by default; its configured level defaults to `info`.
diff --git a/docs/context.md b/docs/context.md
new file mode 100644
index 000000000..47c4acaaa
--- /dev/null
+++ b/docs/context.md
@@ -0,0 +1,94 @@
+# Context
+
+[Documentation](README.md) / Context
+
+Along with your prompt, the plugin sends editor context: the current file,
+your selection, diagnostics, and so on. The context bar above the input shows
+what will be sent. Type `#` in insert mode to toggle or remove items.
+
+## What is included by default?
+
+| Context | Default | Notes |
+| --- | --- | --- |
+| Current file | On | The last code buffer you were in before the panel |
+| Visual selection | On | Added with `<leader>oy`, with file and line numbers |
+| Mentioned files | On | Files added with `@` or `~` |
+| Diagnostics | Warnings and errors | Only those at the cursor or selection |
+| Review comments | On | Comments saved in a [session diff](review.md) |
+| Cursor data | Off | Cursor line and 5 lines either side |
+| Entire buffer | Off | Contents of the current buffer |
+| Git diff | Off | Staged changes (`git diff --cached`) |
+
+Each row has a setting under `context`; see
+[Configuration](configuration.md#context). `context.enabled = false` turns off
+all automatic context.
+
+## Add a selection
+
+Select code in visual mode and press `<leader>oy`. The selection is added to
+the context and the input opens.
+
+`<leader>oY` pastes the selection into the prompt itself, as a code block under
+its file path, and leaves you in normal mode. Use it when you want to refer to
+the code in the middle of your sentence.
+
+To add several selections without jumping to the input each time:
+
+```lua
+require('opencode').setup({
+  keymap = {
+    editor = {
+      ['<leader>oy'] = {
+        'add_visual_selection', { open_input = false }, mode = { 'v' },
+      },
+    },
+  },
+})
+```
+
+If the selection is in the current file, the plugin sends just the selection
+and not the whole file. The agent can still read the file if it needs to.
+Mentioning the file with `@` sends it anyway.
+
+## Mention files and agents
+
+In insert mode in the input, `@` opens completion for files and agents, and `~`
+opens your file picker.
+
+![Mention completion menu showing file and agent suggestions after typing @](https://github.com/user-attachments/assets/5a98226e-c784-4ebf-a563-90dde5cc4e2a)
+
+`#` lists everything in the context. From there you can remove a file or
+selection, turn a whole group such as diagnostics on or off, or drop a single
+review comment.
+
+## What gets re-sent
+
+The plugin avoids sending the same thing twice in a session:
+
+- The current file is sent once, then again only after it changes on disk. In
+  the context bar it is dimmed while it is up to date, and highlighted when it
+  will be sent with the next prompt.
+- Diagnostics, cursor data, buffer, and git diff are re-sent only when their
+  contents change.
+- Mentioned files and selections are sent with every prompt they are in.
+
+![Context completion menu with current file, diagnostics, and a selection](https://github.com/user-attachments/assets/1f36af7e-3ddd-4419-999e-0bff4941b3a0)
+
+![Review comments context group and individual comment in the completion menu](https://github.com/user-attachments/assets/9d129d2e-0aeb-4304-8919-b7d564117469)
+
+## Attach an image
+
+Press `<leader>ov`, or `<M-v>` in insert mode in the input, to attach the image
+on your clipboard. The model you use has to accept images.
+
+## Sensitive files
+
+Check the context bar before sending from a buffer that holds secrets or code
+you may not share with your provider.
+
+These settings only control what the plugin attaches. The agent can still read
+files through its tools; limit that with OpenCode's permissions. To block
+prompts entirely in some projects, use a
+[prompt guard](extensions.md#prompt-guard).
+
+Next: [Reviewing changes](review.md) or [Configuration](configuration.md).
diff --git a/docs/extensions.md b/docs/extensions.md
new file mode 100644
index 000000000..92bd031b1
--- /dev/null
+++ b/docs/extensions.md
@@ -0,0 +1,152 @@
+# Hooks and events
+
+[Documentation](README.md) / Hooks and events
+
+Hooks cover plugin-level moments like a finished response or an edited file.
+For raw server events, use a User autocmd. Events can belong to any session,
+not only the one shown in the panel.
+
+## User hooks
+
+Configure callbacks under `hooks`:
+
+| Hook | Input / behavior |
+| --- | --- |
+| `on_file_edited` | File path after an OpenCode edit |
+| `on_session_loaded` | Loaded session object |
+| `on_done_thinking` | Session when it becomes idle, including work started outside Neovim |
+| `on_permission_requested` | Session with a permission request |
+| `on_question_asked` | Session with a question |
+| `on_topbar_render` | Bar segments; return replacement segments or `nil` to clear |
+| `on_footer_render` | Bar segments; return replacement segments or `nil` to clear |
+
+```lua
+require('opencode').setup({
+  hooks = {
+    on_file_edited = function(path)
+      vim.notify('OpenCode edited ' .. path)
+    end,
+    on_session_loaded = function(session)
+      vim.notify('Loaded ' .. session.id)
+    end,
+    on_done_thinking = function(session)
+      if not session.parentID then
+        vim.notify('OpenCode finished in ' .. session.id)
+      end
+    end,
+    on_footer_render = function(segments)
+      table.insert(segments, 1, { vim.fn.fnamemodify(vim.fn.getcwd(), ':t') .. ' ', 'OpencodeHint' })
+      return segments
+    end,
+  },
+})
+```
+
+A bar segment is `{ 'text', 'HighlightGroup', align = 'left'|'right' }`.
+Highlight and alignment are optional; alignment defaults to left. If a bar hook
+throws, the built-in segments are used.
+
+The command dispatcher also supports `on_command_before`, `on_command_after`,
+`on_command_error`, and `on_command_finally`. These receive an
+`OpencodeCommandDispatchContext`; see [`types.lua`](../lua/opencode/types.lua)
+and [`dispatch.lua`](../lua/opencode/commands/dispatch.lua) for the lifecycle
+contract. They fire for every command, whether it came from a key, an API
+call, an Ex command, or a slash command.
+
+## Local slash commands
+
+Register a Lua callback before or after `setup()`:
+
+```lua
+require('opencode').register_slash_command({
+  name = 'hello',
+  desc = 'Show supplied arguments',
+  args = true,
+  fn = function(args)
+    vim.notify(table.concat(args, ' '))
+  end,
+})
+```
+
+`fn` receives a string array, empty when no arguments were supplied. `args = true`
+lets completion leave room for arguments. Commands appear in completion and the
+picker, and execute through command lifecycle hooks; filter by `/hello`.
+
+Names contain letters, digits, underscores, or hyphens, without a leading slash.
+Builtin and registered name collisions throw. Local commands take precedence
+over same-named server commands and skills. Callback errors use normal command
+error handling. `require('opencode').unregister_slash_command('hello')` removes
+the command and returns whether it existed.
+
+See [Worktree sessions](recipes/worktree.md) for a practical command.
+
+## Prompt guard
+
+`prompt_guard(mentioned_files)` must return a boolean. It receives a list of
+mentioned file paths and can also inspect Neovim state:
+
+```lua
+require('opencode').setup({
+  prompt_guard = function(mentioned_files)
+    local blocked = vim.fn.expand('~/work/private-project')
+    return vim.fn.getcwd() ~= blocked
+  end,
+})
+```
+
+The guard runs before each prompt is sent and when a session opens. `false`
+blocks the action. An error or a non-boolean result also blocks it and reports
+why. The context bar shows when the guard has blocked something.
+
+The example only matches that exact directory, not its subdirectories. The
+guard only controls what Neovim sends; it does not limit what the agent can
+read. Use OpenCode permissions for that.
+
+## Server events as User autocmds
+
+Forwarded server events use the pattern `OpencodeEvent:<event.type>`. The
+event is in `args.data.event`:
+
+```lua
+vim.api.nvim_create_autocmd('User', {
+  pattern = 'OpencodeEvent:permission.*',
+  callback = function(args)
+    vim.notify(vim.inspect(args.data.event))
+  end,
+})
+```
+
+Use `OpencodeEvent:*` for everything or a family like
+`OpencodeEvent:session.*`. Event names and payloads differ between V1 and V2,
+so inspect an event before relying on its fields. Payloads can contain prompt
+and file contents.
+
+## Highlights
+
+Default highlights cover light and dark backgrounds. Override them with
+`nvim_set_hl`, typically in a `ColorScheme` autocmd:
+
+```lua
+vim.api.nvim_create_autocmd('ColorScheme', {
+  callback = function()
+    vim.api.nvim_set_hl(0, 'OpencodeBackground', { link = 'NormalFloat' })
+    vim.api.nvim_set_hl(0, 'OpencodeHint', { link = 'Comment' })
+  end,
+})
+```
+
+Common groups:
+
+| Area | Groups |
+| --- | --- |
+| Panel | `OpencodeBackground`, `OpencodeBorder`, `OpencodeHint`, `OpencodeInputLegend` |
+| Messages | `OpencodeMessageRoleUser`, `OpencodeMessageRoleAssistant`, `OpencodeToolBorder`, `OpencodeReasoningText` |
+| Agent/model | `OpencodeAgentBuild`, `OpencodeAgentPlan`, `OpencodeAgentCustom`, `OpencodeVariant` |
+| Context | `OpencodeMention`, `OpencodeContextCurrentFile`, `OpencodeContextCurrentFileNotUpdated`, `OpencodeContextSelection`, `OpencodeContextReviewComment` |
+| Review | `OpencodeDiffAdd`, `OpencodeDiffDelete`, `OpencodeReviewComment`, `OpencodeReviewCommentSign`, `OpencodeReviewCommentStale` |
+| Tabs | `OpencodeSessionTabActive`, `OpencodeSessionTabInactive`, `OpencodeSessionTabPendingPermission`, `OpencodeSessionTabPendingQuestion` |
+| Actions | `OpencodeContextualActions`, `OpencodeGuardDenied`, `OpencodeReference`, `OpencodeSymbolReference` |
+
+The complete list and default links/colors are in
+[`ui/highlight.lua`](../lua/opencode/ui/highlight.lua). `ui.window_highlight`
+controls the panel's window highlight mapping.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 000000000..cb8001552
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,127 @@
+# Getting started
+
+[Documentation](README.md) / Getting started
+
+This page gets you from install to a first answer. Customization comes later.
+
+## Before installing
+
+- **Neovim** 0.10.3 or later. CI runs 0.10.3, 0.11.4, and nightly.
+- **OpenCode CLI:** install from the [OpenCode V2 guide](https://opencode.ai/v2/docs/)
+  and make sure `opencode` is on the `PATH` Neovim sees. V1 also works; see
+  [Compatibility](compatibility.md).
+- **A connected provider:** run `opencode` in your project, use `/connect`, and
+  send one prompt there. Providers, models, and agents are configured in
+  OpenCode, not in this plugin.
+
+Inside Neovim, check that the executable is visible:
+
+```vim
+:echo executable('opencode')
+```
+
+The result should be `1`. If your binary has another name or location, set
+`opencode_executable` in the [plugin configuration](configuration.md).
+
+## Install with lazy.nvim
+
+```lua
+return {
+  'sudo-tee/opencode.nvim',
+  dependencies = {
+    -- Optional: choose a picker you already use, or keep vim.ui.select.
+    -- 'folke/snacks.nvim',
+    -- 'nvim-telescope/telescope.nvim',
+    -- 'ibhagwan/fzf-lua',
+    -- 'nvim-mini/mini.pick',
+    -- Optional: use your configured completion engine, or built-in completion.
+    -- 'saghen/blink.cmp',
+    -- 'hrsh7th/nvim-cmp',
+    {
+      'MeanderingProgrammer/render-markdown.nvim',
+      opts = {
+        anti_conceal = { enabled = false },
+        file_types = { 'markdown', 'opencode_output' },
+      },
+      ft = { 'markdown', 'opencode_output' },
+    },
+  },
+  opts = {},
+}
+```
+
+`opts = {}` calls the plugin's setup function. With another manager, install
+the plugin and call this once from your configuration:
+
+```lua
+require('opencode').setup({})
+```
+
+The commented dependencies are alternatives, not a list to install in full.
+Uncomment the picker and completion engine you use, and configure them through
+their own plugin specs. Listing a dependency alone does not configure it.
+Prompt completion uses the plugin's in-process LSP server: enable your engine's
+LSP source (`lsp` in blink.cmp, or `nvim_lsp` with `cmp-nvim-lsp` in nvim-cmp).
+No separate OpenCode completion source is needed. See
+[optional integrations](#optional-integrations) and the
+[full default configuration](configuration.md#full-default-configuration).
+
+## Check your installation
+
+After installing and loading the plugin, run:
+
+```vim
+:checkhealth opencode
+```
+
+It checks the CLI, the server connection and credentials, your configuration,
+optional integrations, and file finder tools. Fix any errors before going on.
+Warnings about missing optional plugins are fine; the plugin falls back to
+built-in pickers and completion.
+
+![OpenCode health report showing CLI, server, configuration, and integration checks](https://github.com/user-attachments/assets/72eaf1a1-5d66-4932-a1ae-ecc91872e99d)
+
+## Optional integrations
+
+None of these are required. The plugin uses whichever ones you already have.
+
+| Purpose | Choices |
+| --- | --- |
+| Prompt completion | [blink.cmp](https://github.com/saghen/blink.cmp), [nvim-cmp](https://github.com/hrsh7th/nvim-cmp), built-in completion |
+| File and session pickers | [Snacks](https://github.com/folke/snacks.nvim), [Telescope](https://github.com/nvim-telescope/telescope.nvim), [fzf-lua](https://github.com/ibhagwan/fzf-lua), [mini.pick](https://github.com/nvim-mini/mini.pick), `vim.ui.select` |
+| UI glyphs | A [Nerd Font](https://www.nerdfonts.com/), or the `text` icon preset |
+
+If you have more than one picker installed, choose one with `preferred_picker`.
+With `mini.pick` you cannot select several items at once, for example when
+deleting sessions.
+
+## Send your first prompt
+
+1. Open Neovim in your project and focus a code buffer.
+2. Press `<leader>oi`. The input opens in insert mode.
+3. Type “Explain this function and suggest a test for its edge cases.”
+4. Press `<Esc>` to enter normal mode, then `<CR>` to submit.
+5. Read the response. `<Tab>` in normal mode moves between input and output;
+   `<leader>ot` moves between the panel and your last editor window.
+
+`<Esc>` in normal mode closes the panel. `<S-CR>` sends straight from insert
+mode, but some terminals send it as plain `<CR>`.
+
+The current file is sent with the prompt by default. Type `#` in insert mode to
+see and toggle what will be sent. If you work with files that must not leave
+your machine, read [Context](context.md) first.
+
+![Input context completion menu with current file, diagnostics, and a selection](https://github.com/user-attachments/assets/1f36af7e-3ddd-4419-999e-0bff4941b3a0)
+
+## Try a selection next
+
+Select a few lines in visual mode and press `<leader>oy`, then ask about that
+code. `<leader>oY` pastes the selection into the prompt as a code block
+instead.
+
+After the agent edits a file on V2, `<leader>od` opens the diff.
+[Reviewing changes](review.md) shows how to comment on a line and send the
+comments back.
+
+Next: [Usage](usage.md), [Configuration](configuration.md), or
+[Troubleshooting](troubleshooting.md) if something did not work.
diff --git a/docs/quick-chat.md b/docs/quick-chat.md
new file mode 100644
index 000000000..d2da42d72
--- /dev/null
+++ b/docs/quick-chat.md
@@ -0,0 +1,93 @@
+# Quick chat (experimental)
+
+[Documentation](README.md) / Quick chat
+
+Quick chat replaces text in your current buffer without opening the panel.
+Press `<leader>o/` in normal mode to send the cursor line and 10 lines on
+either side, or in visual mode to send the selection. Enter your instructions
+in the prompt. It runs in a temporary session that is deleted afterwards.
+
+![Quick chat running on a selected function, with a spinner and a cancel hint](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/quick-chat-running.png)
+
+In normal mode, the reply replaces only the cursor line, not the surrounding
+context. With a selection, it replaces the selected lines. Review the result
+before saving; `u` undoes the replacement. `<C-c>` cancels a running quick chat.
+
+Use it for narrow requests such as "Add type annotations to this function"
+or "Turn this list into a table". By default it sends nearby or selected text
+and the closest error/warning diagnostics, not your whole project. Use the
+[panel](usage.md) for broader conversations.
+
+## Ad-hoc commands
+
+Pass instructions directly instead of opening the prompt:
+
+```vim
+:Opencode quick_chat Add a Lua type annotation above this line
+:'<,'>Opencode quick_chat Add type annotations to this function
+:'<,'>Opencode quick_chat Fix the errors and warnings in this selection #errors #warnings
+:'<,'>Opencode quick_chat Turn this list into a Markdown table
+:'<,'>Opencode quick_chat Rewrite this paragraph for clarity
+```
+
+The `'<,'>` range comes from a visual selection. The default instructions
+already request replacement output without explanations or code fences.
+
+`#errors` and `#warnings` include the closest error and warning diagnostics.
+Select the lines needed for the fix so the replacement covers the affected code.
+
+Context tags in the instructions add information: `#buffer` sends the current
+buffer, `#file` the current file, and `#git_diff` the Git diff. These augment
+the default context; they do not change which lines the reply replaces.
+See [Context](context.md) for context configuration.
+
+## Generate a commit message
+
+In your Git commit-message buffer, place the cursor on an empty subject line:
+
+```vim
+:Opencode quick_chat Generate a conventional commit message from #git_diff
+```
+
+Stage the changes you want described first: `#git_diff` sends
+`git diff --cached --minimal`, not unstaged changes. The reply replaces that
+line with the generated message. Review and edit it before completing the
+commit.
+
+To reuse this request, add a Neovim command after your plugin setup:
+
+```lua
+vim.api.nvim_create_user_command('AICommitMessage', function()
+  require('opencode.api').quick_chat('Generate a conventional commit message from #git_diff')
+end, { desc = 'Generate a commit message on the current line' })
+```
+
+Run `:AICommitMessage` from the commit-message buffer. It generates text only;
+it does not stage files or create a commit.
+
+## Reusable selection commands
+
+Define a range-aware command to avoid typing the same instruction each time:
+
+```lua
+vim.api.nvim_create_user_command('AIAnnotate', function(opts)
+  require('opencode.api').quick_chat('Add type annotations', {
+    start = opts.line1,
+    stop = opts.line2,
+  })
+end, { range = true, desc = 'Annotate the selected lines' })
+```
+
+Select a function and run `:'<,'>AIAnnotate`. Without a range, this command
+replaces only the current line.
+
+## Model, agent, and instructions
+
+Options under `quick_chat` set the model (`default_model`), agent
+(`default_agent`), and change system instructions (`instructions`). The default
+instructions handle output format and indentation; no override is needed to
+repeat those rules. Custom instructions replace the defaults rather than
+append to them.
+
+To inspect what happened, set `debug.quick_chat.keep_session = true`; the
+temporary sessions then stay in your session list.
diff --git a/docs/recipes/README.md b/docs/recipes/README.md
new file mode 100644
index 000000000..d7e7e9a75
--- /dev/null
+++ b/docs/recipes/README.md
@@ -0,0 +1,21 @@
+# Recipes
+
+[Documentation](../README.md) / Recipes
+
+Optional setups for specific workflows. None of them are needed to use the
+plugin; read [Usage](../usage.md) first if you are new.
+
+| Recipe | Use it when… |
+| --- | --- |
+| [TUI/Neovim sync](bidirectional-sync/README.md) | You want both frontends to resume the same conversation |
+| [Worktree sessions](worktree.md) | You want one panel tab per worktree without changing Neovim's directory |
+| [Three-state layout toggle](three-state-layout/README.md) | You move between code-only, split, and conversation-focused layouts |
+| [Change-by-change review](change-by-change-review/README.md) | You use V1 snapshots and prefer diffview-plus and gitsigns |
+| [Review a session diff](review-session-diff.md) | You want to comment on V2 changes and send the comments with your next prompt |
+| [Quiet Blink completion](quiet-blink.md) | The completion menu pops up while you type a prompt |
+
+## Share a recipe
+
+Copy the [template](TEMPLATE.md). Say what problem it solves, what it needs
+(plugins, V1 or V2), the full setup, and how to try it. See the
+[documentation conventions](../../CONTRIBUTING.md#documentation).
diff --git a/docs/recipes/TEMPLATE.md b/docs/recipes/TEMPLATE.md
index eff989adf..35d6df47c 100644
--- a/docs/recipes/TEMPLATE.md
+++ b/docs/recipes/TEMPLATE.md
@@ -1,43 +1,39 @@
-# Recipe Template
+# Recipe title
 
-One-line description of what this recipe enables.
+[Recipes](README.md) / Recipe title
 
-![Demo animation](./demo.gif)
+One sentence explaining the task this makes easier.
 
-## Problem
+## When to use it
 
-What workflow pain does this solve? 2-3 specific scenarios.
+Describe a concrete workflow problem. Mention simpler built-in alternatives
+and why this recipe needs more configuration.
 
-## Solution
+## Prerequisites
 
-Brief description of the approach.
+- Plugin/tool dependencies and relevant versions.
+- OpenCode V1/V2 assumptions.
 
-## Quick Start
+## Setup
 
-### Prerequisites
+Say exactly where the following configuration belongs. Provide a complete,
+copyable example; do not use `...` inside executable code.
 
-- Required tools/versions
+## Try it
 
-### Setup
+1. Start from a specific editor state.
+2. Perform the action, including keys/commands.
+3. Describe the expected result.
 
-```bash
-# Installation steps
-```
+Add a short recording here if it helps; otherwise leave it out.
 
-### Usage
+## Caveats and undo
 
-```lua
--- Configuration snippet
-```
+Explain limitations, any destructive behavior, and how to remove the setup.
+Link to relevant guides or API contracts rather than repeating them.
 
-## How It Works
+## Related
 
-Key technical details. Link to relevant APIs if needed.
+Link to a real existing guide or recipe, if useful.
 
-## Integration
-
-- Combine with [other-recipe](../other-recipe/README.md) for more capabilities
-
----
-
-Contributed by @[username](https://github.com/username)
+Contributed by: your GitHub handle (optional).
diff --git a/docs/recipes/bidirectional-sync/README.md b/docs/recipes/bidirectional-sync/README.md
index cc69c16ae..a570d4336 100644
--- a/docs/recipes/bidirectional-sync/README.md
+++ b/docs/recipes/bidirectional-sync/README.md
@@ -1,126 +1,101 @@
-# Bidirectional TUI/nvim Sync
+# TUI/Neovim sync
 
-Switch seamlessly between opencode TUI and nvim plugin without losing context.
+[Recipes](../README.md) / TUI/Neovim sync
 
-![Bidirectional sync demo](./bidirectional-sync.gif)
+Work on the same OpenCode session from the terminal TUI and from Neovim.
 
-## Problem
+![Bidirectional sync demo](./bidirectional-sync.gif)
 
-Switching between opencode TUI and nvim plugin feels like using two separate tools:
+## How it works
 
-1. **Session isolation** - Start a conversation in TUI, switch to nvim, your context is lost
-2. **Double initialization** - Each interface spawns its own server, wasting 15-20s on MCP loading every time
-3. **Mental overhead** - You have to remember which interface you were using for what task
+Both frontends connect to one OpenCode server, so messages, tool output,
+questions, and permission requests show up in both. Each frontend still has its
+own windows, cursor, and unsent draft.
 
-You want TUI for complex workflows and nvim for quick code edits, seamlessly.
+Connecting to the same server does not open the same session. You pick the
+session in each frontend yourself, usually by passing its ID to the TUI.
 
-## Solution
+To find the session ID in Neovim, set `debug.enabled = true` and press
+`<leader>oDs` in the output window.
 
-Use a single shared HTTP server that both TUI and nvim connect to:
+## OpenCode V2
 
-- Start server once, use from any interface
-- Session state persists across TUI/nvim switches  
-- Zero context loss when changing tools
+No setup is needed. The V2 TUI and the plugin both use OpenCode's background
+service by default.
 
-## State Flow
+```bash
+# Open the TUI in the project
+opencode /path/to/project
 
-```mermaid
-flowchart LR
-    A[Terminal: native opencode --server] -->|connects| B[Shared Server]
-    C[nvim] -->|connects| B
-    D[TUI] -->|connects| B
-    B -->|shares session| C
-    B -->|shares session| D
+# Or resume the session that Neovim is showing
+opencode --session ses_XXXX /path/to/project
 ```
 
-## Quick Start
-
-### V2 native service
-
-V2 2.0.x 的 TUI 默认连接 OpenCode 自己管理的后台 service。Neovim 默认也使用这个 service，无需 wrapper、固定端口、额外 password_file 或用户填写 ownership。下面的 V2 路径已在 2.0.3 实测。
+If the service is slow to start on your machine, raise the timeout in
+`setup()`:
 
 ```lua
-require("opencode").setup({
-    server = { timeout = 30 },
+require('opencode').setup({
+  server = { timeout = 30 },
 })
 ```
 
-```bash
-# 普通 TUI 使用原生后台 service
-opencode /path/to/project
-# 继续 Neovim 正在显示的同一 session
-opencode --session ses_... /path/to/project
-```
+Quitting Neovim leaves the service running, so the TUI keeps working.
 
-插件用 CLI 的 `service status` 获取地址、`service get password` 获取凭据；仅当状态明确为 `stopped` 时调用 `service start`。HTTP health 决定 V1/V2 协议。Neovim 退出不关闭原生 service。CLI 能力检查只选择启动入口，不代替 server health 的协议判定。
+For a V2 server at an explicit address, use
+`opencode --server <endpoint> --session ses_XXXX <directory>` and set
+`OPENCODE_PASSWORD` if the server requires it. Configure the plugin with the
+same endpoint; see [Servers](../../servers.md).
 
-同一目录不代表两端自动选中同一 session；在另一端显式 resume 同一 session。两端共享消息、工具、question 与 permission 状态，各自保留窗口、光标和未提交输入。
+## OpenCode V1
 
-### V1 and explicit servers
+V1 has no background service, so start one shared server and point both
+frontends at it.
 
-旧 V1 CLI 没有 service 命令，插件保留原有本地 `serve` 路径。已有 `server.url`、`port`、`spawn_command` 的配置继续按显式连接处理。
+```bash
+opencode attach http://127.0.0.1:4096 --dir /path/to/project --session ses_XXXX
+```
 
-V1 的共享服务需要两端使用同一 endpoint 和凭据，TUI 原生命令是：
+Configure Neovim with the same endpoint and credentials:
 
-```bash
-opencode attach http://127.0.0.1:4096 --dir /path/to/project --session ses_...
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 4096,
+    password_file = vim.fn.stdpath('state') .. '/opencode/server-password',
+  },
+})
 ```
 
-V2 的显式远端连接可使用 `opencode --server <endpoint> --session ses_... <directory>`，并按服务要求提供 `OPENCODE_PASSWORD`。只有该显式场景需要双方约定地址。以下 legacy helper 配置仅适用于 V1；V2 无需安装或调用 `oc-sync.sh`。
+The password file must contain the password on its first line and be readable
+only by you (`chmod 600`). If you start the shared server yourself, do not pass
+`--shutdown-after-last-client`, or it stops when the first frontend exits.
 
-## V1 legacy helper configuration
+### Helper script
 
-Environment variables:
+[`oc-sync.sh`](oc-sync.sh) starts the shared V1 server if it is not running,
+then attaches the TUI to it. It reuses the plugin's password file, creating it
+if needed. It refuses to run against a V2 CLI.
 
 | Variable | Default | Description |
-|----------|---------|-------------|
-| `OPENCODE_SYNC_PORT` | 4096 | HTTP server port |
-| `OPENCODE_SYNC_HOST` | 127.0.0.1 | Server bind address |
-| `OPENCODE_SYNC_WAIT_TIMEOUT_SEC` | 20 | Startup timeout |
-| `OPENCODE_SYNC_PASSWORD_FILE` | `$XDG_STATE_HOME/nvim/opencode/server-password` or `~/.local/state/nvim/opencode/server-password` | Shared credential file |
+| --- | --- | --- |
+| `OPENCODE_SYNC_PORT` | `4096` | Server port |
+| `OPENCODE_SYNC_HOST` | `127.0.0.1` | Server address |
+| `OPENCODE_SYNC_WAIT_TIMEOUT_SEC` | `20` | Seconds to wait for startup |
+| `OPENCODE_SYNC_PASSWORD_FILE` | `$XDG_STATE_HOME/nvim/opencode/server-password` | Shared password file |
 
 ## Troubleshooting
 
-V2 先用原生命令检查服务状态和真实 health：
+On V2, check the service before debugging the plugin:
 
 ```bash
 opencode service status
-opencode api GET /api/health
+opencode api get /api/info
 ```
 
-插件错误与 CLI 错误应分别检查。401/403 不会触发私有 server 启动或 V1 回退。无需查找并杀掉某个约定端口的进程。
-
-The nvim client and TUI share the HTTP server and session data. Selecting a
-session in one frontend does not select it in the other frontend. Pass
-`--session ses_...` when both clients must display the same conversation. Each
-frontend still owns its windows, cursor, input draft, and current selection.
-Native V2 service lifecycle belongs to OpenCode. For an explicitly managed shared server, do not use
-`--shutdown-after-last-client` when starting it.
-
-Server ownership controls shutdown and port cleanup only. Prompt completion uses
-the admission ID returned to nvim and the matching inbox events from the shared
-server. The server runs one serial execution horizon per session, so messages
-delivered by another client during that horizon are included in the same next
-terminal event. The plugin keeps one local prompt in flight per session. A lost
-event stream, or evidence that the server started overlapping execution horizons,
-resolves that local completion as `unknown`; messages already stored by the server
-remain visible to both frontends after a snapshot refresh.
-
-For a V1 explicit launcher shared with the TUI, set `server.password_file` to a state-directory path. Fixed-port
-V1 servers otherwise use an owner-only per-port file under Neovim's state directory so later nvim clients reuse
-the same credential. On a launcher path, the plugin persists the selected password before
-starting its local server, so a later nvim process and, when explicitly configured, the TUI read the same value.
-Plugin credential selection is deterministic: `server.password`, then the
-configured password file, then `OPENCODE_PASSWORD`, then
-`OPENCODE_SERVER_PASSWORD`. This recipe leaves `server.password` unset and uses
-the password file as the shared source. When the file is absent, the V1 helper
-persists the environment password or generates one; an existing invalid file
-fails immediately instead of being replaced.
-
-The legacy helper rejects a CLI with the native service command before creating credentials or starting a process. Its health endpoint is `/global/health`, where a healthy V1 JSON response is required; the liveness check does not depend on the server version. HTML 200 and authentication errors are failures. V2 never enters this script's launcher path.
-
-## Integration Ideas
-
-- Combine with [three-state-layout](../three-state-layout/README.md) to also control how you view opencode within nvim
-- Use terminal multiplexers (tmux/zellij) to manage both TUI and nvim in one window
-- Add shell aliases for common project paths
+A `401` or `403` means the credentials do not match; starting another server
+will not fix it. If both frontends are connected but show different
+conversations, they are on different sessions. Pass `--session` to the TUI.
+
+Related: [Three-state layout toggle](../three-state-layout/README.md).
diff --git a/docs/recipes/change-by-change-review/README.md b/docs/recipes/change-by-change-review/README.md
index 3bb8ef036..69c77584d 100644
--- a/docs/recipes/change-by-change-review/README.md
+++ b/docs/recipes/change-by-change-review/README.md
@@ -1,118 +1,95 @@
-# Change-By-Change Review
+# Change-by-change review
 
-Review changes Opencode made using [diffview-plus](https://github.com/dlyongemallo/diffview-plus.nvim)
-and (optionally) [gitsigns](https://github.com/lewis6991/gitsigns.nvim)
+[Recipes](../README.md) / Change-by-change review
 
-![Change-By-Change-Demo](./change-by-change.gif)
+Review legacy V1 snapshot changes through
+[diffview-plus](https://github.com/dlyongemallo/diffview-plus.nvim), with optional
+[gitsigns](https://github.com/lewis6991/gitsigns.nvim) hunk navigation.
 
-## Problem
+![Change-by-change review in diffview-plus](change-by-change.gif)
 
-Opencode.nvim already provides a way to see changes after running a prompt.
-It can be opened using `:Opencode diff_open`, `:Opencode diff open`, hovering the `Created Snapshot` output 
-and pressing `D`, or the default keymap `<leader>od`.
+## When to use it
 
-Diffview+ gives the user a few more features: layout customization, a tree to navigate changed files from,
-a way to mark what you've already reviewed, accepting/rejecting changes,
-familiar keymaps if you're already using it, and a bunch more configuration options.
+Use this if you already prefer diffview-plus and are working with **OpenCode V1
+snapshots**. For V2, use the built-in [session diff review](../../review.md): it
+has a file tree, range selection, and inline comments without this integration.
 
-Gitsigns can be used to fill context when asking the AI to revise an edit.
+V1 snapshots are experimental. This recipe relies on plugin internals, not a
+stable external snapshot API, so check it again after upgrades.
 
-## Solution
+## Prerequisites
 
-This integration can be made by adding a few lines to diffview+'s and gitsigns' configs. Really just adding 
-a couple of keymaps.
+- OpenCode V1 and an active session with at least one snapshot.
+- diffview-plus installed and configured.
+- gitsigns, if you want the optional hunk mappings.
 
-## Quick Start
+## Setup
 
-### Prerequisites
+Add this mapping after configuring opencode.nvim and diffview-plus:
 
-- [diffview+](https://github.com/dlyongemallo/diffview-plus.nvim)
-- [gitsigns](https://github.com/lewis6991/gitsigns.nvim) (optional)
-
-### Setup
-
-#### Diffview/Diffview-plus
-
-**`Lazy keys spec (if you lazy load opencode.nvim):`**
-```lua
-keys = {
-        { "<leader>odv", function ()
-            local path = require("opencode.config_file").get_workspace_snapshot_path():wait()
-            local first_snapshot = require("opencode.git_review").get_first_snapshot()
-            vim.cmd("DiffviewOpen \"-C=" .. path .. "\"" .. " " .. first_snapshot)
-        end, desc = "diff against start of session"},
-}
-```
-
-**`Or vim.keymap.set:`**
 ```lua
-vim.keymap.set("n", "<leader>odv", function()
-    local path = require("opencode.config_file").get_workspace_snapshot_path():wait()
-    local first_snapshot = require("opencode.git_review").get_first_snapshot()
-    vim.cmd("DiffviewOpen \"-C=" .. path .. "\"" .. " " .. first_snapshot)
-end, { desc = "open session changes in diffview"})
+vim.keymap.set('n', '<leader>odv', function()
+  local path = require('opencode.config_file').get_workspace_snapshot_path():wait()
+  local first_snapshot = require('opencode.git_review').get_first_snapshot()
+  vim.cmd('DiffviewOpen "-C=' .. path .. '" ' .. first_snapshot)
+end, { desc = 'Review V1 session in diffview-plus' })
 ```
 
-#### Gitsigns
+For optional hunk navigation and sending a hunk as context, merge this
+`on_attach` into your gitsigns setup. This is a lazy.nvim spec; keep any existing
+`on_attach` behavior when combining it with your own configuration.
 
-This is from the [gitsigns recommended keymaps](https://github.com/lewis6991/gitsigns.nvim#-keymaps). 
-This will give you the "hunk x of y" output, but is not necessary. `]c` and `[c` are defined in a diff 
-buffer by NeoVim, you'd just have to select them manually without the gitsigns shorthand.
-
-**`gitsigns configuration`** (straight from `gitsigns`'s recommended setup)
 ```lua
-opts = {
-    on_attach = {
-        local gs = require("gitsigns")
-        map('n', ']c', function()
-          if vim.wo.diff then
-            vim.cmd.normal({']c', bang = true})
-          else
-            gs.nav_hunk('next')
-          end
-        end, "next change")
-        map('n', '[c', function()
-          if vim.wo.diff then
-            vim.cmd.normal({'[c', bang = true})
-          else
-            gs.nav_hunk('prev')
-          end
-        end, "prev change")
-    }
+return {
+  'lewis6991/gitsigns.nvim',
+  opts = {
+    on_attach = function(bufnr)
+      local gs = require('gitsigns')
+      local function map(lhs, callback, desc)
+        vim.keymap.set('n', lhs, callback, { buffer = bufnr, desc = desc })
+      end
+      map(']c', function()
+        if vim.wo.diff then
+          vim.cmd.normal({ ']c', bang = true })
+        else
+          gs.nav_hunk('next')
+        end
+      end, 'Next change')
+      map('[c', function()
+        if vim.wo.diff then
+          vim.cmd.normal({ '[c', bang = true })
+        else
+          gs.nav_hunk('prev')
+        end
+      end, 'Previous change')
+      map('<leader>oyh', function()
+        gs.select_hunk()
+        require('opencode.api').add_visual_selection({ open_input = false })
+      end, 'Send hunk to OpenCode')
+    end,
+  },
 }
 ```
 
-Add this new mapping in the `on_attach` after your other mappings to send a hunk to context:
-
-**`gitsigns.opts.on_attach`**
-```lua
-    map("n", "<leader>oyh", function()
-        vim.cmd("Gitsigns select_hunk")
-        require("opencode.context").add_visual_selection()
-    end, "send hunk to opencode context")
-```
-
-
-### Usage
-
-Once Opencode has created a snapshot and made some edits, you can review the edits since the start of 
-the session by pressing `<leader>odv`.
+## Try it
 
-Inside diffview+:
+1. Let a V1 session create a snapshot and make an edit.
+2. Press `<leader>odv` to review changes since the first session snapshot.
+3. In diffview-plus, use `<Tab>` / `<S-Tab>` for files and `]c` / `[c` for hunks.
+4. In a working file with gitsigns attached, `<leader>oyh` selects the hunk and
+   adds it to OpenCode context. Inspect it before sending a follow-up.
+5. Close the review tab with `:tabclose`.
 
-- `<tab>` and `<s-tab>` jump between changed files 
-- `]c` and `[c` jump between changes
-- use `do` to "use other diff" (delete a change) and `dp` if you're in the `old` buffer to "put diff" 
-into the `LOCAL` buffer
-- if you're in the `LOCAL` buffer, `<leader>oyh` will send the hunk to Opencode context.
-- `:tabc` to exit diffview+
+## Caveats and undo
 
-## How It Works
+diffview-plus uses `-C` to run Git against the snapshot directory. This does not
+turn V2 session revisions into a Git repository.
 
-Diffview+ can start with a different path to git. That's specified with the `-C` argument.
-Git itself can give you a diff against these snapshots. This causes Diffview+ to use the path 
-provided by `-C` as its git command execution base.
+In diff windows, `do` takes the other side's change; `dp` puts the current side's
+change into the other buffer. These edit buffers, so inspect the target side and
+save or back up work before using them. Follow diffview-plus's own documentation
+for accepting/rejecting changes.
 
----
+Remove `<leader>odv` and the optional gitsigns mappings to undo this recipe.
 
-Contributed by @[Kortantic](https://github.com/kortantic)
+Contributed by [Kortantic](https://github.com/Kortantic).
diff --git a/docs/recipes/quiet-blink.md b/docs/recipes/quiet-blink.md
new file mode 100644
index 000000000..457f29c5c
--- /dev/null
+++ b/docs/recipes/quiet-blink.md
@@ -0,0 +1,58 @@
+# Quiet Blink completion
+
+[Recipes](README.md) / Quiet Blink completion
+
+Keep automatic completion useful for mentions without opening a menu for every
+word of a prompt. This recipe requires lazy.nvim and an existing blink.cmp setup.
+
+It changes automatic presentation only for the `opencode` input filetype. All
+configured sources stay available; explicit trigger characters and manual
+completion still work. Other buffers keep their existing behavior.
+
+Add this to your lazy.nvim specs:
+
+```lua
+return {
+  {
+    'saghen/blink.cmp',
+    optional = true,
+    opts = function(_, opts)
+      opts.completion = opts.completion or {}
+      opts.completion.menu = opts.completion.menu or {}
+      opts.completion.ghost_text = opts.completion.ghost_text or {}
+
+      local inherited_auto_show = opts.completion.menu.auto_show
+      local inherited_ghost_text_enabled = opts.completion.ghost_text.enabled
+
+      opts.completion.menu.auto_show = function(ctx, items)
+        if vim.bo[ctx.bufnr].filetype == 'opencode' then
+          return ctx.trigger.kind == 'trigger_character'
+        end
+        if type(inherited_auto_show) == 'function' then
+          return inherited_auto_show(ctx, items)
+        end
+        return inherited_auto_show ~= false
+      end
+
+      opts.completion.ghost_text.enabled = function()
+        local ghost_text_enabled = type(inherited_ghost_text_enabled) == 'function'
+            and inherited_ghost_text_enabled()
+          or inherited_ghost_text_enabled == true
+        if vim.bo.filetype == 'opencode' then
+          return ghost_text_enabled and require('blink.cmp').is_menu_visible()
+        end
+        return ghost_text_enabled
+      end
+
+      return opts
+    end,
+  },
+}
+```
+
+Open input and type a sentence: no automatic menu should interrupt it. Type a
+mention trigger or invoke manual completion to confirm completion still works.
+Ghost text remains off unless you enabled it already and the menu is open.
+
+This uses Blink's completion-context API; check your installed Blink version if
+the recipe does not match its settings. To undo it, remove this spec extension.
diff --git a/docs/recipes/review-session-diff.md b/docs/recipes/review-session-diff.md
index 762b01de9..d0f8dd8cb 100644
--- a/docs/recipes/review-session-diff.md
+++ b/docs/recipes/review-session-diff.md
@@ -1,12 +1,30 @@
 # Review a session diff
 
-Add inline feedback to changes from an OpenCode V2 session diff, then include that feedback as context in your next prompt.
+[Recipes](README.md) / Review a session diff
 
-1. Run `:Opencode diff open`, select a file, and move into its preview.
-2. Place cursor on a line or visually select lines, then press `c`. Type feedback and press `<C-s>` (or `:w`).
-3. Use `]r` / `[r` to revisit comments, `c` to edit, or `dc` to remove. A comment can refer to either side or to a deleted file.
-4. Press `q` to close the diff. Input receives focus with pending comments. Write a prompt and send it; comments are attached automatically.
+Comment on the agent's changes line by line, then send the comments with your
+next prompt. Requires OpenCode V2. For layouts, message ranges, and remapping,
+see [Reviewing changes](../review.md).
 
-The input context bar shows the new **Review comments** context item and count. Type `#` to toggle the whole group or select a comment to remove it individually. Disable automatic inclusion with `context.review_comments.enabled = false`.
+1. Run `:Opencode diff open` (or `<leader>od`), pick a file, and move into its
+   preview.
+2. Put the cursor on a line, or select several lines, and press `c`. Type your
+   comment and press `<C-s>` or `:w`.
+3. Use `]r` / `[r` to jump between comments, `c` to edit one, and `dc` to
+   delete it. You can comment on either side of the diff, including on a
+   deleted file.
+4. Press `q` in the file list or preview. The prompt opens with your comments
+   attached. Write a follow-up, such as "Fix these, keep the public API the
+   same", and send it.
 
-Line numbers refer to the reviewed session snapshot. Comments on the same file share one attachment and one locating instruction; each keeps its own feedback and original snippet. Neighboring lines and diff range stay local to resolve drift. Before sending, it checks current file contents, including unsaved edits. Only changed, moved, removed, or missing code adds current-file details to the payload.
+![Saved review comment beside its changed line](https://github.com/user-attachments/assets/af202f79-8980-4f46-a967-638563555967)
+
+The context bar shows a **Review comments** item with a count. Type `#` to turn
+the group off or remove a single comment. To stop attaching comments
+automatically, set `context.review_comments.enabled = false`.
+
+![Review comments in the input context completion menu](https://github.com/user-attachments/assets/9d129d2e-0aeb-4304-8919-b7d564117469)
+
+Line numbers in a comment refer to the reviewed snapshot. If the file has
+changed since then, including unsaved edits, the plugin also sends the current
+code around each comment so the agent can find the right place.
diff --git a/docs/recipes/three-state-layout/README.md b/docs/recipes/three-state-layout/README.md
index 9c991d698..56722c5fc 100644
--- a/docs/recipes/three-state-layout/README.md
+++ b/docs/recipes/three-state-layout/README.md
@@ -1,58 +1,50 @@
-# Three-State Layout Toggle
+# Three-state layout toggle
 
-Instantly switch how you view opencode.
+[Recipes](../README.md) / Three-state layout toggle
 
-## Problem
+Two keys to move between three layouts: code only, panel beside the code, and
+panel filling the window.
 
-Real workflows need three distinct ways to interact with AI:
+![Three-state layout toggle demo](./three-state-toggle.gif)
 
-1. **Focused coding** - opencode hidden, full attention on your code
-2. **Side-by-side** - opencode visible alongside code, quick reference and iteration
-3. **Deep conversation** - opencode fullscreen for complex AI interactions requiring full context
+## When to use it
 
-The default `toggle()` only provides binary visible/hidden control. Switching between these three modes requires multiple keypresses and interrupts flow.
+`<leader>og` only hides and restores the panel, always in the same position.
+If you sometimes want the conversation to take over the whole window, for
+example to read a long answer, this recipe adds a key for that. If a wider
+split is enough, try `<leader>oz` (zoom) first.
 
-## State Transitions
+The three layouts:
 
-```mermaid
-stateDiagram-v2
-    [*] --> focused : start
-    
-    focused --> side_by_side : zl
-    side_by_side --> focused : zl
-    side_by_side --> deep : zL
-    deep --> side_by_side : zl
-    deep --> focused : zL
-```
+| Layout | Panel |
+| --- | --- |
+| Focused | Hidden |
+| Side by side | Split on the right (`ui.position = 'right'`) |
+| Full window | Replaces the current window (`ui.position = 'current'`) |
 
-## Demo
+## Try it
 
-Run the standalone demo:
+From a checkout of the plugin, read [`demo.lua`](demo.lua), then run:
 
 ```vim
 :luafile docs/recipes/three-state-layout/demo.lua
 ```
 
-Then press `zl` or `zL` to toggle between modes.
-
-![Three-state layout toggle demo](./three-state-toggle.gif)
-
-## Keybindings
+The script maps `zl` and `zL` in normal mode, overriding Neovim's built-in
+horizontal scroll keys:
 
-| Key | Focused coding | Side-by-side | Deep conversation |
-|-----|----------------|--------------|-------------------|
-| `zl` | Enter side-by-side | Return to focused | Exit to side-by-side |
-| `zL` | Enter deep conversation | Switch to deep | Return to focused |
+| Key | From focused | From side by side | From full window |
+| --- | --- | --- | --- |
+| `zl` | Side by side | Focused | Side by side |
+| `zL` | Full window | Full window | Focused |
 
-## Implementation Notes
+To keep it, copy the contents of `demo.lua` into your config, and change the
+keys if you use `zl`/`zL` for scrolling.
 
-The demo uses `config.ui.position` to switch between window layouts:
-- `position = 'right'` for side-by-side mode
-- `position = 'current'` for deep conversation mode
+## Caveats and undo
 
-## Integration Ideas
+The script changes `ui.position` at runtime, so the panel opens in the last
+layout you chose until you restart Neovim. To undo, remove the mappings (or
+restart Neovim if you only ran the demo).
 
-- Combine with [bidirectional-sync](../bidirectional-sync/README.md) to also share sessions between TUI and nvim
-- Add autocmds to automatically enter deep conversation mode on long AI responses
-- Map to leader keys for easier access
-- Use with tmux/zellij for managing multiple opencode instances
+Related: [TUI/Neovim sync](../bidirectional-sync/README.md).
diff --git a/docs/recipes/worktree.md b/docs/recipes/worktree.md
new file mode 100644
index 000000000..0bb7ca467
--- /dev/null
+++ b/docs/recipes/worktree.md
@@ -0,0 +1,102 @@
+# Worktree sessions
+
+[Recipes](README.md) / Worktree sessions
+
+Keep a conversation for each Git worktree in a separate panel tab without
+changing Neovim's working directory.
+
+## When to use it
+
+Use this when an agent works in a feature worktree while you keep editing the
+main checkout. If you already open a separate Neovim instance in each worktree,
+the normal session picker is enough; no extra setup is needed.
+
+## Prerequisites
+
+- Git and Neovim 0.10.3 or later.
+- A current opencode.nvim with `open_session` and `register_slash_command`.
+- OpenCode V1 or V2. No worktree plugin is required.
+- The worktree must exist locally and be accessible to the OpenCode server.
+  For a container or remote server, see [Servers](../servers.md#translate-paths).
+
+## Setup
+
+First create a worktree from your repository root. This example assumes your
+base branch is `main` and creates a new branch named `feature-login`:
+
+```sh
+git worktree add -b feature-login ../feature-login main
+```
+
+Add the following after your existing `require('opencode').setup(...)` call.
+With lazy.nvim, put it in the plugin's `config` function after
+`require('opencode').setup(opts)`:
+
+```lua
+require('opencode').register_slash_command({
+  name = 'worktree',
+  desc = 'Resume a session in an existing worktree',
+  args = true,
+  fn = function(args)
+    local directory = table.concat(args, ' ')
+    assert(directory ~= '', 'Usage: /worktree /absolute/path/to/worktree')
+    return require('opencode.api').open_session({ directory = directory })
+  end,
+})
+```
+
+The command resumes the most recent root session created in that exact
+directory, or creates one if none exists. An already-open session reuses its
+panel tab. Errors are reported through the command lifecycle.
+
+## Try it
+
+1. Run `git worktree list` to find the absolute path of `feature-login`.
+2. In Neovim, open the panel with `<leader>oi`.
+3. Type `/worktree /absolute/path/to/feature-login`, then press `<Esc>` and
+   `<CR>`. Replace the example path with the path from step 1; do not quote it,
+   even if it contains spaces.
+4. Send a prompt about the feature. The session and file completion use the
+   worktree, while `:pwd` still shows your original editor directory.
+5. Use `<leader>o<` / `<leader>o>` to switch panel tabs. Each bound tab keeps
+   its own session directory.
+
+For a fresh conversation instead of resuming, call the API directly:
+
+```lua
+require('opencode.api').open_session({
+  directory = '/absolute/path/to/feature-login',
+  new = true,
+  title = 'Feature login',
+}):catch(function(err)
+  vim.notify(tostring(err), vim.log.levels.ERROR)
+end)
+```
+
+## Caveats and undo
+
+- This opens a session, not a Git worktree or an editor tabpage. It does not
+  move an existing conversation to another directory.
+- Automatic current-file context still comes from your editor. When editing
+  the main checkout, disable `context.current_file.enabled` for worktree
+  prompts or open the worktree file first. See [Context](../context.md).
+- An explicit `:cd`, `:lcd`, or `:tcd` follows
+  `lock_session_to_directory`. To keep bound tabs in their worktrees across
+  editor directory changes, set it to `true` in your existing `setup()` options.
+  Manual `:Opencode session toggle_lock` overrides the policy for the active
+  panel tab. See [Directory changes](../configuration.md#directory-changes).
+- Register the command once. To remove it, delete the setup snippet and run
+  `:lua require('opencode').unregister_slash_command('worktree')` or restart
+  Neovim. Close its panel tab with `<leader>oQ`; this does not delete the session.
+
+Before removing a worktree, stop its agent and save or commit your changes.
+From the main checkout, run `git worktree remove ../feature-login`. Git refuses
+to remove a dirty worktree; do not use `--force` to bypass that protection.
+The branch and conversation remain, but the session's directory no longer
+exists. Recreate the worktree before reopening that session.
+
+## Related
+
+- [Directory-bound sessions](../reference.md#directory-bound-sessions)
+- [Local slash commands](../extensions.md#local-slash-commands)
+- [Sessions and panel tabs](../usage.md#sessions-and-panel-tabs)
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 000000000..09b91aa7a
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,346 @@
+# Commands and Lua API
+
+[Documentation](README.md) / Commands and Lua API
+
+`:Opencode` toggles the panel. Subcommands have command-line completion; use
+`:Opencode help` for in-editor help. The workflow tables explain common actions; the
+[complete command list](#complete-command-list) includes every registered alias.
+
+Lua examples use:
+
+```lua
+local api = require('opencode.api')
+```
+
+Commands, keymaps, slash commands, and API calls all go through the same
+dispatcher. Some actions return a Promise, so a session or response may not
+exist yet when the call returns. See
+[`api.lua`](../lua/opencode/api.lua) for all exports and
+[`types.lua`](../lua/opencode/types.lua) for signatures.
+
+## Panel and navigation
+
+| Command | Lua call | Default key |
+| --- | --- | --- |
+| `:Opencode` | `api.toggle()` | `<leader>og` |
+| `:Opencode open input` | `api.open_input()` | `<leader>oi` |
+| `:Opencode open output` | `api.open_output()` | `<leader>oo` |
+| `:Opencode toggle_focus` | `api.toggle_focus()` | `<leader>ot` |
+| `:Opencode close` | `api.close()` | `<leader>oq` |
+| `:Opencode swap` | `api.swap_position()` | `<leader>ox` |
+| `:Opencode toggle_zoom` | `api.toggle_zoom()` | `<leader>oz` |
+| `:Opencode cancel` | `api.cancel()` | `<C-c>` in panel |
+| `:Opencode references` | `api.references()` | `gr` in panel |
+| `:Opencode jump_to_file` | `api.jump_to_file()` | `gf` in output |
+| `:Opencode history` | `api.select_history()` | `<leader>oh` |
+
+`api.hide()` follows `ui.persist_state`, like `close()`.
+`api.navigate_to_location(path, line, col)` opens a specific file location.
+`api.next_message()`, `prev_message()`, `next_user_message()`, and
+`prev_user_message()` navigate output; `prev_history()` / `next_history()`
+browse saved prompts.
+
+## Sessions and tabs
+
+| Command | Lua call | Default key |
+| --- | --- | --- |
+| `:Opencode session new` | `api.open_input_new_session()` | `<leader>oI` |
+| `:Opencode session new <name>` | `api.open_input_new_session_with_title(name)` | — |
+| `:Opencode session select` | `api.select_session()` | `<leader>os` |
+| `:Opencode session rename <name>` | `api.rename_session(nil, name)` | `<leader>oR` opens rename input |
+| `:Opencode tab new [name]` | `api.open_session_tab(name)` | `<leader>oN` |
+| `:Opencode tab select [index]` | `api.select_session_tab(index)` | `<leader>o?` / `<leader>o1`…`o9` |
+| `:Opencode tab previous` / `next` | `api.prev_session_tab()` / `next_session_tab()` | `<leader>o<` / `<leader>o>` |
+| `:Opencode tab close` | `api.close_session_tab()` | `<leader>oQ` |
+| `:Opencode timeline` | `api.timeline()` | `<leader>oT` |
+| `:Opencode session navigate child picker` | `api.navigate_session_tree('child', 'picker')` | `<leader>oS` |
+| `:Opencode session navigate parent` | `api.navigate_session_tree('parent')` | `<leader>oP` |
+| `:Opencode session navigate sibling picker` | `api.navigate_session_tree('sibling', 'picker')` | `<leader>oB` |
+| `:Opencode session share` / `unshare` | `api.share()` / `unshare()` | — |
+| `:Opencode session compact` | `api.compact_session()` | — |
+| `:Opencode session agents_init` | `api.initialize()` | — |
+| `:Opencode undo` / `redo` | `api.undo()` / `redo()` | — |
+
+Sharing publishes the conversation at a public link. Undo can change files on
+disk. Panel tabs and the session tree are covered in
+[Usage](usage.md#sessions-and-panel-tabs).
+
+### Directory-bound sessions
+
+`api.open_session(opts)` opens a session in a logical panel tab without changing
+Neovim's cwd. There is no equivalent built-in Ex or slash command.
+
+| Option | Meaning |
+| --- | --- |
+| `directory` | Required existing local directory; relative paths resolve against Neovim's cwd |
+| `new` | Create a fresh session instead of resuming; incompatible with `session_id` |
+| `session_id` | Open a specific session belonging to the supplied directory |
+| `title` | Title for a newly created session |
+
+Without `new` or `session_id`, it resumes the most recent root session in that
+exact directory, or creates one if absent. Already-open sessions reuse their
+panel tab. The Promise resolves to the session and rejects on invalid options,
+server startup, lookup, creation, or panel failure. Normal path mapping applies.
+
+Completion and new sessions use the bound directory, including after tab
+switches. Explicit editor directory changes follow
+[`lock_session_to_directory`](configuration.md#directory-changes).
+See [Worktree sessions](recipes/worktree.md) for a complete example.
+
+## Models, agents, and permissions
+
+| Command | Lua call | Default key |
+| --- | --- | --- |
+| `:Opencode models` | `api.configure_provider()` | `<leader>op` |
+| `:Opencode variant` | `api.configure_variant()` | `<leader>oV` |
+| — | `api.cycle_variant()` | `<M-r>` in panel |
+| `:Opencode agent build` / `plan` | `api.agent_build()` / `agent_plan()` | — |
+| `:Opencode agent select` | `api.select_agent()` | `<M-m>` cycles in input |
+| `:Opencode permission accept` | `api.permission_accept()` | Dialog choices |
+| `:Opencode permission accept_all` | `api.permission_accept_all()` | Dialog choices |
+| `:Opencode permission deny` | `api.permission_deny()` | Dialog choices |
+| `:Opencode mcp` | `api.mcp()` | — |
+
+## Prompts and context
+
+```lua
+api.run('Explain the edge cases in this function', {
+  agent = 'plan',
+  context = { current_file = { enabled = false } },
+})
+
+api.run_new_session('Suggest tests for this module', {
+  model = 'provider/model-id',
+})
+```
+
+Command equivalents:
+
+```vim
+:Opencode run agent=plan Explain this function
+:Opencode run_new context=current_file.enabled=false Suggest tests for this module
+```
+
+Options go before the prompt: `agent=`, `model=` (`provider/model-id`),
+`variant=`, and `context=`. Separate multiple context overrides with commas,
+for example `context=selection.enabled=false,diagnostics.warning=false`.
+
+| Action | Command / Lua call |
+| --- | --- |
+| Submit input | `:Opencode submit_input_prompt` / `api.submit_input_prompt()` |
+| Add visual selection | `:Opencode add_visual_selection` / `api.add_visual_selection(opts, range)` |
+| Insert selection inline | `:Opencode add_visual_selection_inline` / `api.add_visual_selection_inline(opts, range)` |
+| Paste clipboard image | `:Opencode paste_image` / `api.paste_image()` |
+| Quick chat | `:Opencode quick_chat [instructions]` / `api.quick_chat()` |
+| Toggle tool output | `:Opencode toggle_tool_output` / `api.toggle_tool_output()` |
+| Toggle reasoning | `:Opencode toggle_reasoning_output` / `api.toggle_reasoning_output()` |
+| Toggle message limit | `:Opencode toggle_max_messages` / `api.toggle_max_messages()` |
+| Clear selection context | `:Opencode clear_selections` |
+| Clear mentioned files | `:Opencode clear_files` |
+
+Visual-selection commands accept an Ex range. Lua callers can supply
+`range = { start = first_line, stop = last_line }` as the second argument
+(1-based lines). `opts.open_input` defaults to `true`. Configured visual
+keymaps capture the range for you. See [Context](context.md#add-a-selection).
+
+## Debugging
+
+| Command | Lua call | Purpose |
+| --- | --- | --- |
+| `:Opencode debug events [filename]` | `api.debug_events(filename?)` | Export captured streamed events (`data.json` by default) |
+| `:Opencode debug log` | `api.debug_log()` | Open the plugin log file in the current window |
+
+## Change review
+
+| Command | Lua call | Default key |
+| --- | --- | --- |
+| `:Opencode diff open` | `api.diff_open()` | `<leader>od` |
+| `:Opencode diff next` / `prev` | `api.diff_next()` / `diff_prev()` | `<leader>o]` / `<leader>o[` |
+| `:Opencode diff close` | `api.diff_close()` | `<leader>oc` |
+
+Keys inside the V2 review view are listed in [Reviewing changes](review.md).
+`:Opencode review [arguments]` and `api.review(args)` are different: they run
+OpenCode's `review` command in a new session.
+
+## Complete command list
+
+Every registered `:Opencode` command, including the aliases keymaps use.
+
+| Command | Purpose | Subcommands |
+| --- | --- | --- |
+| `:Opencode add_visual_selection` | Add current visual selection to context | — |
+| `:Opencode add_visual_selection_inline` | Insert visual selection as inline code block in the input buffer | — |
+| `:Opencode agent` | Manage agents (plan/build/select) | `plan`, `build`, `select` |
+| `:Opencode breakpoint` | Take a V1 snapshot for later diff and revert actions | — |
+| `:Opencode cancel` | Cancel running request | — |
+| `:Opencode clear_files` | Clear only mentioned files from context | — |
+| `:Opencode clear_selections` | Clear only selections from context | — |
+| `:Opencode close` | Close opencode windows | — |
+| `:Opencode close_session_tab` | Close the current Opencode panel tab | — |
+| `:Opencode command` | Run user-defined command | — |
+| `:Opencode commands_list` | Show user-defined commands | — |
+| `:Opencode configure_provider` | Configure provider | — |
+| `:Opencode configure_variant` | Configure model variant | — |
+| `:Opencode context_items` | Open context items picker in input window | — |
+| `:Opencode copy_server_url` | Copy server URL to clipboard | — |
+| `:Opencode cycle_variant` | Cycle model variant | — |
+| `:Opencode debug` | Export captured events or open plugin log | `events [filename]`, `log` |
+| `:Opencode debug_message` | Open raw message debug view | — |
+| `:Opencode debug_output` | Open raw output debug view | — |
+| `:Opencode debug_session` | Open raw session debug view | — |
+| `:Opencode diff` | View file diffs (open/next/prev/close) | `open`, `next`, `prev`, `close` |
+| `:Opencode diff_close` | Close diff view | — |
+| `:Opencode diff_next` | Next diff | — |
+| `:Opencode diff_open` | Open diff view | — |
+| `:Opencode diff_prev` | Previous diff | — |
+| `:Opencode diff_restore_snapshot_all` | Restore all files from snapshot (optional snapshot_id) | — |
+| `:Opencode diff_restore_snapshot_file` | Restore file from snapshot (optional snapshot_id) | — |
+| `:Opencode diff_revert_all` | Revert all tracked changes (optional snapshot_id) | — |
+| `:Opencode diff_revert_all_last_prompt` | Revert all (last prompt) | — |
+| `:Opencode diff_revert_this` | Revert current change (optional snapshot_id) | — |
+| `:Opencode diff_revert_this_last_prompt` | Revert this (last prompt) | — |
+| `:Opencode diff_toggle_file` | Toggle diff for tool file | — |
+| `:Opencode first_message` | Load history and go to the first message | — |
+| `:Opencode focus_input` | Focus input window | — |
+| `:Opencode fork_session` | Fork the session from a user message | — |
+| `:Opencode help` | Show command help | — |
+| `:Opencode hide` | Hide opencode windows (preserve buffers for fast restore) | — |
+| `:Opencode history` | Select from prompt history | — |
+| `:Opencode jump_to_file` | Jump to file at cursor in output window | — |
+| `:Opencode jump_to_target_at_cursor` | Jump to target at cursor in output window | — |
+| `:Opencode mcp` | Show MCP server configuration | — |
+| `:Opencode mention` | Open mention picker in input window | — |
+| `:Opencode mention_file` | Mention file in current input context | — |
+| `:Opencode models` | Switch provider/model | — |
+| `:Opencode navigate_session_tree` | Navigate session tree (parent/child/sibling/forward/backward) or switch to a session by ID | — |
+| `:Opencode next_message` | Navigate to next message in output window | — |
+| `:Opencode next_prompt_history` | Navigate to next prompt history item | — |
+| `:Opencode next_session_tab` | Switch to the next Opencode panel tab | — |
+| `:Opencode next_user_message` | Navigate to next user message in output window | — |
+| `:Opencode open` | Open opencode window (input/output) | `input`, `output` |
+| `:Opencode open_input` | Open input window | — |
+| `:Opencode open_input_new_session` | Open input (new session) | — |
+| `:Opencode open_output` | Open output window | — |
+| `:Opencode open_session_tab` | Open a new session in an Opencode panel tab | — |
+| `:Opencode paste_image` | Paste image from clipboard and add to context | — |
+| `:Opencode permission` | Respond to permissions (accept/accept_all/deny) | `accept`, `accept_all`, `deny` |
+| `:Opencode prev_message` | Navigate to previous message in output window | — |
+| `:Opencode prev_prompt_history` | Navigate to previous prompt history item | — |
+| `:Opencode prev_session_tab` | Switch to the previous Opencode panel tab | — |
+| `:Opencode prev_user_message` | Navigate to previous user message in output window | — |
+| `:Opencode quick_chat` | Quick chat about the cursor line (±10 lines) or visual selection | — |
+| `:Opencode redo` | Redo last action | — |
+| `:Opencode references` | Browse code references from conversation | — |
+| `:Opencode rename_session` | Rename session | — |
+| `:Opencode restore` | Restore from snapshot (file/all) | `file`, `all` |
+| `:Opencode revert` | Revert changes (all/this, prompt/session) | `all`, `this`; targets: `prompt`, `session`, snapshot ID |
+| `:Opencode review` | Review changes (commit/branch/pr), defaults to uncommitted changes | — |
+| `:Opencode run` | Run prompt in current session | — |
+| `:Opencode run_new` | Run prompt in new session | — |
+| `:Opencode select_history` | Select from history | — |
+| `:Opencode select_session` | Select session | — |
+| `:Opencode select_session_tab` | Select an Opencode panel tab | — |
+| `:Opencode select_session_tab_target` | Select the tab at the cursor or mouse position | — |
+| `:Opencode session` | Manage sessions and Opencode panel tabs | `new`, `tab`, `tabs`, `next_tab`, `prev_tab`, `close_tab`, `select`, `navigate`, `compact`, `share`, `unshare`, `agents_init`, `rename`, `toggle_lock` |
+| `:Opencode skill` | Activate a skill or run it with user instructions | — |
+| `:Opencode skills` | Browse and select available skills | — |
+| `:Opencode slash_commands` | Open slash commands picker in input window | — |
+| `:Opencode submit_input_prompt` | Submit current input prompt | — |
+| `:Opencode swap` | Swap pane position left/right | — |
+| `:Opencode swap_position` | Swap window position | — |
+| `:Opencode switch_mode` | Cycle agent mode | — |
+| `:Opencode tab` | Manage Opencode panel tabs | `next`, `new`, `previous`, `select`, `close` |
+| `:Opencode timeline` | Open timeline picker to navigate/undo/redo/fork to message | — |
+| `:Opencode toggle` | Toggle opencode windows | — |
+| `:Opencode toggle_focus` | Toggle focus between opencode and code | — |
+| `:Opencode toggle_input` | Toggle input window visibility | — |
+| `:Opencode toggle_max_messages` | Toggle maximum number of rendered messages | — |
+| `:Opencode toggle_pane` | Toggle between input/output panes | — |
+| `:Opencode toggle_reasoning_output` | Toggle reasoning output visibility in the output window | — |
+| `:Opencode toggle_session_lock` | Toggle session lock (preserve active session across cwd changes) | — |
+| `:Opencode toggle_tool_output` | Toggle tool output visibility in the output window | — |
+| `:Opencode toggle_zoom` | Toggle window zoom | — |
+| `:Opencode undo` | Undo last action | — |
+| `:Opencode variant` | Switch model variant | — |
+
+## Slash commands and user commands
+
+Type `/` in the input window (insert mode) to browse commands. Built-ins:
+
+| Slash command | Equivalent command | Purpose |
+| --- | --- | --- |
+| `/agent` | `:Opencode agent select` | Manage agents (plan/build/select) |
+| `/agents_init` | `:Opencode session agents_init` | New session that runs `init` to create or update AGENTS.md |
+| `/child-sessions` | `:Opencode session navigate child picker` | Pick a child session |
+| `/clear_files` | `:Opencode clear_files` | Clear only mentioned files from context |
+| `/clear_selections` | `:Opencode clear_selections` | Clear only selections from context |
+| `/command-list` | `:Opencode commands_list` | Show user-defined commands |
+| `/compact` | `:Opencode session compact` | Summarize the session |
+| `/help` | `:Opencode help` | Show command help |
+| `/history` | `:Opencode history` | Select from prompt history |
+| `/mcp` | `:Opencode mcp` | Show MCP server configuration |
+| `/models` | `:Opencode models` | Switch provider/model |
+| `/new` | `:Opencode session new` | Open input in a new session |
+| `/reasoning` | `:Opencode toggle_reasoning_output` | Toggle reasoning output visibility in the output window |
+| `/redo` | `:Opencode redo` | Redo last action |
+| `/references` | `:Opencode references` | Browse code references from conversation |
+| `/rename` | `:Opencode session rename` | Rename the current session |
+| `/review` | `:Opencode review` | Review changes (commit/branch/pr), defaults to uncommitted changes |
+| `/sessions` | `:Opencode session select` | Pick a session |
+| `/share` | `:Opencode session share` | Share the session and copy the link |
+| `/skills` | `:Opencode skills` | Browse and select available skills |
+| `/thinking` | `:Opencode toggle_reasoning_output` | Toggle reasoning output visibility in the output window |
+| `/timeline` | `:Opencode timeline` | Open timeline picker to navigate/undo/redo/fork to message |
+| `/undo` | `:Opencode undo` | Undo last action |
+| `/unshare` | `:Opencode session unshare` | Disable the share link |
+| `/variant` | `:Opencode variant` | Switch model variant |
+
+User commands and skills from your OpenCode configuration also show up in the
+menu.
+
+Run a user command with `:Opencode command <name> [arguments]` or
+`api.run_user_command(name, args)`. Commands are defined in OpenCode's
+configuration, not in the plugin. V1 definitions can
+live in `.opencode/command/` or the global `command/` directory. For V2, follow
+the [OpenCode configuration guide](https://opencode.ai/v2/docs/config).
+
+## Skills
+
+`:Opencode skills` or `/skills` opens a picker with names, descriptions, and
+Markdown previews. Selecting one inserts `/skill-name` into input.
+
+- On V2, submitting `/skill-name` activates the native server-managed skill.
+- `/skill-name review current changes` sends instructions with a native skill
+  attachment instead.
+- Older servers without skill support return an error; update OpenCode.
+- V1 sends the skill's content as an ordinary prompt.
+
+The same behavior is available through:
+
+```vim
+:Opencode skill <name> [instructions]
+```
+
+```lua
+api.run_skill(name, instructions)
+```
+
+V2 API callers can pass `skills = { { id = skill_id } }` in run options.
+Optional `mention = { start_byte = ..., end_byte = ... }` ranges are zero-based
+UTF-8 byte offsets into the prompt, with an exclusive end.
+
+## Legacy snapshot actions (V1)
+
+These overwrite files. See [Compatibility](compatibility.md#v1-snapshots-and-restore-points)
+before using them. V2 uses the [review view](review.md) instead.
+
+| Command | Lua call |
+| --- | --- |
+| `:Opencode revert all prompt` | `api.diff_revert_all_last_prompt()` |
+| `:Opencode revert this prompt` | `api.diff_revert_this_last_prompt()` |
+| `:Opencode revert all session` | `api.diff_revert_all()` |
+| `:Opencode revert this session` | `api.diff_revert_this()` |
+| `:Opencode revert all <snapshot_id>` | `api.diff_revert_all(snapshot_id)` |
+| `:Opencode revert this <snapshot_id>` | `api.diff_revert_this(snapshot_id)` |
+| `:Opencode restore file <restore_point_id>` | `api.diff_restore_snapshot_file(restore_point_id)` |
+| `:Opencode restore all <restore_point_id>` | `api.diff_restore_snapshot_all(restore_point_id)` |
diff --git a/docs/review.md b/docs/review.md
new file mode 100644
index 000000000..c236a7783
--- /dev/null
+++ b/docs/review.md
@@ -0,0 +1,110 @@
+# Reviewing changes
+
+[Documentation](README.md) / Reviewing changes
+
+Session diffs show what the agent changed, file by file. You can leave
+comments on lines and send them back with your next prompt. This needs OpenCode
+V2; on V1, see [snapshots](compatibility.md#v1-snapshots-and-restore-points).
+
+## Open a session diff
+
+After the agent edits files, press `<leader>od` or run `:Opencode diff open`.
+A new Neovim tab opens with the changed files on the left and a before/after
+view of the selected file.
+
+![Changed-file tree and side-by-side revisions](https://github.com/user-attachments/assets/e1e0e95c-c32a-4a10-9829-88bd7100d688)
+
+In the file list, `<CR>` opens a file or folds a directory. `<Tab>` and
+`<S-Tab>` go to the next and previous file from either the list or the preview.
+Press `p` to switch between side by side and a unified patch.
+
+![Unified patch preview](https://github.com/user-attachments/assets/f014f4b5-f672-4878-a581-0856894a7cb6)
+
+Both sides come from snapshots OpenCode recorded during the session. If you
+have edited a file since, the diff does not show those edits.
+
+## Choose a range of messages
+
+By default the diff covers your last prompt. To see the changes from several
+prompts:
+
+1. Press `r` to list your prompts.
+2. Press `f` on the first prompt and `t` on the last.
+3. Press `<CR>` to show the changes across that range.
+
+`K` previews a prompt, and `r`, `q`, or `<Esc>` go back to the file list
+without changing the range. `g?` shows the keys in any review pane.
+
+![Message-range picker with start and end markers](https://github.com/user-attachments/assets/6933e4b5-34d0-4004-9328-7030297fe058)
+
+## Leave inline feedback
+
+In the preview, press `c` on a line or a visual selection. Write the comment
+and save with `<C-s>`, `:w`, or `<CR>` in normal mode. `q` or `<Esc>` cancels.
+
+![Review comment editor](https://github.com/user-attachments/assets/889b16fd-5e24-4c23-a073-62eb5e1199f9)
+
+![Saved review comment beside its changed line](https://github.com/user-attachments/assets/af202f79-8980-4f46-a967-638563555967)
+
+Saved comments show as signs in the preview and are marked in the file list.
+`]r` / `[r` jump between them; `c` on a comment edits it and `dc` deletes it.
+You can comment on either side, including on a deleted file.
+
+Press `q` in the list or preview to close the review. If you left comments,
+the prompt opens with them attached. Write the follow-up, for example "Fix
+these, keep the public API the same", and send it.
+
+The context bar shows how many comments are attached. Use `#` to detach all of
+them or remove one. To never attach them automatically, set
+`context.review_comments.enabled = false`.
+
+Comment line numbers refer to the snapshot you reviewed. If the file has
+changed since, including unsaved edits, the plugin also sends the current code
+around each comment so the agent can find the right place.
+
+The [session review recipe](recipes/review-session-diff.md) has the same steps
+as a checklist.
+
+## Jump to the working file
+
+`gf` opens the real file in another tab and leaves the review open. From the
+preview, the cursor lands on the matching line of the new version; on a deleted
+line, it goes to the next line that still exists. If the file has changed since
+the snapshot, the line may be off.
+
+From the conversation, press `D` on an edit or patch tool block to open the
+diff for that prompt with the file selected. Press `D` on the same block again
+to close it.
+
+## Customize review keys
+
+Review keys are set under `keymap.session_diff`, one table per pane. Set the
+old key to `false` when you move an action:
+
+```lua
+require('opencode').setup({
+  keymap = {
+    session_diff = {
+      list = { ['p'] = false, ['v'] = { 'toggle_view' } },
+      preview = {
+        ['p'] = false,
+        ['v'] = { 'toggle_view' },
+        [']f'] = { 'next_file', desc = 'Next file' },
+        ['[f'] = { 'prev_file', desc = 'Previous file' },
+      },
+    },
+  },
+})
+```
+
+An action can be a review action (the names in the
+[defaults](configuration.md#full-default-configuration)), any `:Opencode`
+command name, or a Lua function. Entries take `mode`, `desc`, and `nowait` like
+[other keymaps](configuration.md#keymaps).
+
+For your own `FileType` autocmds, the panes use these filetypes:
+`opencode_diff_list`, `opencode_diff_messages`, `opencode_diff_comment`, and
+`opencode_diff_help`. Previews combine the file's language with a suffix, such
+as `lua.opencode_diff_preview`, so match `*.opencode_diff_preview` or
+`*.opencode_diff_message_preview`. The plugin's mappings are already set when
+your autocmd runs.
diff --git a/docs/servers.md b/docs/servers.md
new file mode 100644
index 000000000..e3078a0c9
--- /dev/null
+++ b/docs/servers.md
@@ -0,0 +1,168 @@
+# Servers
+
+[Documentation](README.md) / Servers
+
+With a local OpenCode V2 install, leave `server` unset. Read on if OpenCode runs
+somewhere else (another host, a container, WSL) or you start it yourself.
+
+## How the plugin finds a server
+
+- **V2 CLI:** the plugin asks `opencode service status` for the address and
+  credentials of OpenCode's background service, and starts the service if it
+  is stopped. Quitting Neovim leaves it running.
+- **V1 CLI:** the plugin starts `opencode serve` locally and stops it when the
+  last Neovim instance using it exits.
+- **`server.url` or `server.spawn_command` set:** the plugin connects to that
+  server instead, as described below.
+
+In every case the plugin checks the server's health endpoint to tell V1 from V2.
+
+Several frontends can share one server, but each picks its own session. To
+work on the same session from the TUI, see
+[TUI/Neovim sync](recipes/bidirectional-sync/README.md).
+
+## Connect to a running server
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 8080,
+    timeout = 10,
+  },
+})
+```
+
+Put the host in `url` and the port in `port`; do not add the port to the URL.
+For a server on another machine, use HTTPS or an SSH tunnel. The server must
+see the project at the same path as Neovim, or you need a
+[path map](#translate-paths).
+
+## Authentication
+
+The password is taken from the first of these that is set:
+
+1. `server.password`
+2. the file at `server.password_file`
+3. `$OPENCODE_PASSWORD`
+4. `$OPENCODE_SERVER_PASSWORD`
+
+The username is `server.username`, then `$OPENCODE_SERVER_USERNAME`, then
+`opencode`. The V2 background service supplies its own credentials, so none of
+this applies to it.
+
+A password file holds the password on its first line and must be readable only
+by you (`chmod 600`); otherwise connecting fails. Prefer a file or environment
+variable to a password written in your config.
+
+`username` and `password` can also be functions, called when connecting:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 8080,
+    password = function()
+      return vim.fn.readfile(vim.fn.expand('~/.config/opencode/server-password'))[1]
+    end,
+  },
+})
+```
+
+## Translate paths
+
+If the server sees the project at a different path, map between the two. For a
+project mounted at `/app` in a container:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 8080,
+    path_map = '/app',
+  },
+})
+```
+
+`path_map` is either a base path on the server or a function that turns a local
+path into a server path. `reverse_path_map` does the opposite, for paths the
+server sends back. For Neovim on Windows with OpenCode in WSL:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 8080,
+    path_map = function(path)
+      local drive, rest = path:match('^([A-Za-z]):(.*)$')
+      if drive then
+        return '/mnt/' .. drive:lower() .. rest:gsub('\\', '/')
+      end
+      return path
+    end,
+    reverse_path_map = function(path)
+      local drive, rest = path:match('^/mnt/([a-z])(.*)$')
+      if drive then
+        return drive:upper() .. ':' .. rest:gsub('/', '\\')
+      end
+      return path
+    end,
+  },
+})
+```
+
+Start the server in WSL first. Before asking for edits, check that `@`
+mentions and `gf` in the output both open the right files.
+
+## Start the server yourself
+
+`spawn_command(port, url, env)` is called when nothing answers at the
+configured address. Start the server there, passing `env` to the process: it
+holds the credentials the plugin will use. `kill_command(port, url)` is called
+to stop it.
+
+A V1 example:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'http://127.0.0.1',
+    port = 'auto',
+    spawn_command = function(port, url, env)
+      return vim.fn.jobstart({
+        'opencode', 'serve', '--hostname', '127.0.0.1', '--port', tostring(port),
+      }, { env = env, detach = true })
+    end,
+  },
+})
+```
+
+`port = 'auto'` picks a free port. Do not use this with V2, which has its own
+service. For Docker or WSL launchers, run the command by hand first, pass
+arguments as a list rather than a shell string, and expose only the port you
+need.
+
+With `auto_kill = true` (the default), a server started by `spawn_command` is
+stopped when the last Neovim instance using it exits. Servers you started
+outside Neovim are never stopped by the plugin.
+
+## Settings
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `url`, `port` | `nil` | Server address; `port` is a number or `'auto'` |
+| `timeout` | `5` | Seconds to wait for the server to respond |
+| `retry_delay` | `2000` | Milliseconds between connection attempts |
+| `health_check_ttl_ms` | `5000` | How long a successful health check is reused |
+| `spawn_command`, `kill_command` | `nil` | Start and stop a server yourself |
+| `auto_kill` | `true` | Stop a spawned server when the last Neovim exits |
+| `path_map`, `reverse_path_map` | `nil` | Translate paths to and from the server |
+| `username`, `password` | `nil` | Credentials, as strings or functions |
+| `password_file` | `nil` | File holding the password |
+
+For a V1 server on a fixed port, the plugin keeps a generated password in
+Neovim's state directory, so later Neovim instances can reuse the server. The
+[sync recipe](recipes/bidirectional-sync/README.md#opencode-v1) shows how to
+share it with the TUI.
+
+If the connection fails, see [Troubleshooting](troubleshooting.md).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 000000000..53869b7ed
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,122 @@
+# Troubleshooting
+
+[Documentation](README.md) / Troubleshooting
+
+Start by checking whether the problem is in the plugin or in OpenCode: send the
+same small request from the OpenCode CLI, in the same project, with the same
+model.
+
+## Neovim cannot find OpenCode
+
+```vim
+:echo executable('opencode')
+:echo exepath('opencode')
+```
+
+`0` means the CLI is not on Neovim's `PATH`. GUI launchers often get a different
+`PATH` than your shell. Fix `PATH` or set `opencode_executable` to the full path,
+then restart Neovim.
+
+## The panel cannot connect
+
+For the default V2 service:
+
+```sh
+opencode service status
+opencode api get /api/info
+```
+
+If the service is unhealthy, run `opencode service restart`. This interrupts
+every connected client. See
+[OpenCode troubleshooting](https://opencode.ai/v2/docs/troubleshooting) for
+more.
+
+For an explicit server, check `server.url`, `port`, credentials, and that the
+host is reachable from the machine running Neovim. `401`/`403` means the
+credentials are wrong. `url` should not include the port. Raise
+`server.timeout` only if the server really is slow to start.
+
+## Completion
+
+If completion pops up too often, see the
+[quiet Blink recipe](recipes/quiet-blink.md).
+
+## Output looks wrong or rendering is slow
+
+Check that your Markdown renderer is enabled for the `opencode_output`
+filetype and that the Treesitter Markdown parsers are installed. Missing glyphs
+mean the font has no Nerd Font icons; set `ui.icons.preset = 'text'`.
+
+To rule out the renderer, set `ui.output.rendering.on_data_rendered = false`
+(any boolean turns off the renderer integration). For long conversations,
+`ui.output.max_messages` limits how many messages render at first.
+
+## A file jump uses the wrong path
+
+With containers, remote hosts, or WSL, check `path_map` and
+`reverse_path_map`; both directions must map to the same project files. Jumps
+from a session diff land on the current file, so lines may be off if the file
+changed since.
+
+## Capture and export streamed events
+
+Event capture is off by default. Captured events stay in memory until you
+export them:
+
+```lua
+require('opencode').setup({
+  debug = { capture_streamed_events = true },
+})
+```
+
+Restart Neovim, reproduce the issue, then export:
+
+```vim
+:Opencode debug events
+:Opencode debug events /tmp/opencode-events.json
+```
+
+Or from Lua: `require('opencode.api').debug_events('/tmp/opencode-events.json')`.
+
+Without a filename the file is `data.json` in the current working directory.
+Export before quitting; the capture is lost on exit. The JSON can be replayed
+with the tools in [`tests/manual/README.md`](../tests/manual/README.md).
+Captures include prompts and file contents, so redact them before sharing.
+
+## Enable plugin logging
+
+```lua
+require('opencode').setup({
+  logging = { enabled = true, level = 'debug' },
+})
+```
+
+Restart Neovim and reproduce the issue. The log goes to
+`vim.fn.stdpath('log') .. '/opencode.log'` unless `logging.outfile` is set.
+`:Opencode debug log` (or `require('opencode.api').debug_log()`) opens it in the
+current window. To print the path:
+
+```vim
+:lua print(require('opencode.log').get_path())
+```
+
+This prints `nil` when logging is disabled.
+
+With `debug.enabled = true`, these keys work in the output window: `<leader>oD`
+for raw message data, `<leader>oO` for raw output, and `<leader>oDs` for raw
+session data.
+
+## Reporting a bug
+
+Open an [issue](https://github.com/sudo-tee/opencode.nvim/issues) with:
+
+- Neovim version, OpenCode version, and plugin commit/branch.
+- OS, terminal, plugin manager, and relevant picker/completion/renderer.
+- How you connect: native service, explicit `server.url`, or a launcher.
+- A minimal configuration and exact steps, expected result, and actual result.
+- Whether the same request works in the CLI.
+- Relevant redacted logs or a small screenshot/recording.
+
+Remove passwords, authorization headers, URLs with credentials, private
+prompts, and file contents from anything you attach. `<leader>oDu` copies the
+server URL, which can include credentials.
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 000000000..d57a35ea6
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,175 @@
+# Usage
+
+[Documentation](README.md) / Usage
+
+## Models
+
+`<leader>op` opens the provider and model picker. `<C-f>` marks a favorite.
+The list shows favorites, then recently used models, then everything else.
+
+![Model picker showing providers, favorite models, and recently used models](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/model-picker.png)
+
+`<leader>oV` (or `/variant`) picks a model variant, and `<M-r>` cycles
+through them. Each model remembers its last variant.
+
+## Sessions and panel tabs
+
+`<leader>os` opens the session picker. In it:
+
+| Key | Action |
+| --- | --- |
+| `<CR>` | Open the session |
+| `<C-t>` | Open it in a new panel tab |
+| `<C-s>` | Start a new session |
+| `<C-r>` | Rename |
+| `<C-f>` | Fork |
+| `<C-g>` | Switch between this project's sessions and all sessions |
+| `<C-d>` | Delete the selected sessions |
+
+![Session picker with three sessions and a preview of the selected conversation](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/session-picker.png)
+
+For a fresh conversation in the current panel tab, press `<leader>oI`. For a
+fresh conversation in another panel tab, press `<leader>oN`.
+
+Panel tabs live inside the panel and are separate from Neovim's tabpages. Each
+one has its own session, draft, model, and context.
+
+| Default key | Action |
+| --- | --- |
+| `<leader>o<` / `<leader>o>` | Previous / next panel tab |
+| `<leader>o1` … `<leader>o9` | Select a panel tab by index |
+| `<leader>o?` | Pick a panel tab |
+| `<leader>oQ` | Close the current panel tab |
+
+![Panel with three panel tabs in the tab strip above the conversation](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/panel-tabs.png)
+
+The tab strip is hidden while there is only one tab; set
+`ui.hide_single_tab = false` to always show it. When a session in another tab
+asks a question or needs a permission, you get a notification. Turn that off
+with `ui.notify_on_background_prompt = false`.
+
+To open a session in another worktree without changing your editor directory,
+see [Worktree sessions](recipes/worktree.md).
+
+## Agents
+
+`<M-m>` in the input cycles agents. `:Opencode agent select` opens a picker
+that includes your custom agents.
+
+![Agent picker showing build, plan, and custom agents](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/agent-picker.png)
+
+New sessions start with the `build` agent; change that with `default_mode`.
+`plan` is meant for reading and planning, but what each agent may do is decided
+by its permissions in OpenCode. Agents are defined in the
+[OpenCode config](https://opencode.ai/v2/docs/), not in `setup()`.
+
+## Move between code and conversation
+
+The panel has two buffers: input, where you write the prompt, and output, where
+the conversation appears. Input is a normal buffer, so multiline editing,
+registers, and motions all work.
+
+| Default key | Action |
+| --- | --- |
+| `<leader>og` | Hide or restore the panel |
+| `<leader>oi` | Focus input in insert mode |
+| `<leader>oo` | Focus output |
+| `<leader>ot` | Switch between the panel and your last editor window |
+| `<leader>oz` | Zoom the panel |
+| `<leader>ox` | Swap the panel's side |
+| `<leader>oq` | Close the panel |
+
+Within the panel:
+
+| Default key | Where / mode | Action |
+| --- | --- | --- |
+| `<CR>` | Input, normal | Send prompt |
+| `<S-CR>` | Input, normal or insert | Send prompt |
+| `<Tab>` | Input or output, normal | Switch panes |
+| `<C-c>` | Input or output | Cancel a running request |
+| `<Esc>` | Input or output, normal | Close the panel |
+| `<Up>` / `<Down>` | Input, normal or insert | Browse prompt history |
+| `i` | Output, normal | Focus input |
+| `]]` / `[[` | Output, normal | Next / previous message |
+| `]u` / `[u` | Output, normal | Next / previous user prompt |
+| `gf` | Output, normal | Open the file referenced at the cursor |
+| `gr` | Panel, normal | Browse code references |
+
+While a completion menu is open, `<Tab>`, `<Up>`, `<Down>`, `<Esc>`, and
+`<C-c>` act on the menu first. To change any of these keys, see
+[Configuration](configuration.md#keymaps).
+
+Closing the panel only hides it: your draft and scroll position are still there
+when you reopen it. Set `ui.persist_state = false` to discard the buffers on
+close instead. Either way the session itself is kept by OpenCode.
+
+## Markdown rendering
+
+The output buffer uses the `opencode_output` filetype with Markdown
+Treesitter highlighting. If
+[render-markdown.nvim](https://github.com/MeanderingProgrammer/render-markdown.nvim)
+or [markview.nvim](https://github.com/OXY2DEV/markview.nvim) is installed, the
+output is rendered with it after each update. For render-markdown.nvim, add
+`opencode_output` to its `file_types`, as in the
+[install example](../README.md#install).
+
+Rendering is debounced while the agent streams. To hook in your own renderer
+or turn rendering off, see
+[Output and rendering](configuration.md#output-and-rendering).
+
+## Permissions and questions
+
+Permission requests appear in the output. Move between the choices with `j`/`k`
+or the arrow keys and press `<CR>`, or press `1`, `2`, or `3`. The same choices
+are available as commands:
+
+![Permission request for a shell command with Allow once, Reject, and Allow always choices](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/permission-prompt.png)
+
+```vim
+:Opencode permission accept
+:Opencode permission accept_all
+:Opencode permission deny
+```
+
+`accept` allows this one request, `accept_all` allows every future request of
+the same kind, and `deny` rejects it. With several requests waiting, add an
+index, for example `:Opencode permission accept 2`. How long an `accept_all`
+lasts is up to the OpenCode server.
+
+Questions from the agent also appear in the output. Set
+`ui.questions.use_vim_ui_select = true` to answer them through `vim.ui.select`
+instead. Answering "Other" opens a small floating input; set
+`ui.questions.inline_other_input = false` to use `vim.ui.input`.
+
+## Timeline and session tree
+
+`<leader>oT` opens the timeline of your prompts in this session. `<CR>` jumps
+to a message, `<C-u>` undoes back to it, and `<C-f>` forks a new session from
+it. Undo can also revert files the agent changed, so commit anything you want
+to keep first.
+
+![Timeline picker listing the session's prompts with timestamps](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/timeline-picker.png)
+
+When the agent starts subagents, each runs in a child session. `<leader>oS`
+picks a child, `<leader>oP` goes to the parent, and `<leader>oB` picks a
+sibling. Child sessions are read-only: the input is hidden and prompts are not
+sent. Set `child_readonly = false` to write to them.
+
+For small edits without opening the panel, see [Quick chat](quick-chat.md),
+including commit-message generation and custom ad-hoc commands.
+
+Next: [Context](context.md), [Reviewing changes](review.md), or the
+[command reference](reference.md).
+
+## Prompt history
+
+Every prompt you send is saved to
+`stdpath('data')/opencode/history.jsonl`. History is shared across projects
+and sessions.
+
+In the input, `<Up>` and `<Down>` step through earlier prompts. Your unsent
+draft comes back when you step past the newest entry. For a searchable list,
+press `<leader>oh` (or `/history`). `<CR>` puts the chosen prompt in the input,
+`<C-d>` deletes the selected entries, and `<C-X>` clears the whole history.
+
+![Prompt history picker listing earlier prompts, newest first](https://raw.githubusercontent.com/sudo-tee/opencode.nvim/docs-assets/usage/history-picker.png)
diff --git a/lua/opencode/api.lua b/lua/opencode/api.lua
index b6498af7e..ca1031537 100644
--- a/lua/opencode/api.lua
+++ b/lua/opencode/api.lua
@@ -23,6 +23,7 @@ end
 ---@type OpencodeCommandApi
 local M = {}
 
+---@type table<string, table<string, fun(...): any>>
 local action_groups = {
   window = {
     swap_position = window.swap_position,
@@ -115,6 +116,15 @@ local action_groups = {
     add_visual_selection_inline = workflow.add_visual_selection_inline,
   },
 
+  debug = {
+    debug_events = function(filename)
+      return require('opencode.ui.debug_helper').save_captured_events(filename)
+    end,
+    debug_log = function()
+      return require('opencode.ui.debug_helper').open_log()
+    end,
+  },
+
   surface = {
     help = surface.help,
     mcp = surface.mcp,
diff --git a/lua/opencode/commands/handlers/workflow.lua b/lua/opencode/commands/handlers/workflow.lua
index bbef7c69c..282c6ab27 100644
--- a/lua/opencode/commands/handlers/workflow.lua
+++ b/lua/opencode/commands/handlers/workflow.lua
@@ -235,6 +235,27 @@ for _, action_name in ipairs({ 'debug_output', 'debug_message', 'debug_session'
   end
 end
 
+---@param args string[]
+function M.actions.debug(args)
+  local debug_helper = require('opencode.ui.debug_helper')
+  local subcommand = args[1]
+  if subcommand == 'events' then
+    if #args > 2 then
+      error({ code = 'invalid_arguments', message = 'Usage: :Opencode debug events [filename]' }, 0)
+    end
+    return debug_helper.save_captured_events(args[2])
+  end
+
+  if subcommand == 'log' then
+    if #args > 1 then
+      error({ code = 'invalid_arguments', message = 'Usage: :Opencode debug log' }, 0)
+    end
+    return debug_helper.open_log()
+  end
+
+  error({ code = 'invalid_arguments', message = 'Invalid debug subcommand. Use: events, log' }, 0)
+end
+
 function M.actions.paste_image()
   local image_path = require('opencode.image_handler').save_clipboard_image()
   if not image_path then
@@ -550,7 +571,7 @@ M.actions.add_visual_selection_inline = Promise.async(
 
 M.command_defs = {
   quick_chat = {
-    desc = 'Quick chat with current buffer or visual selection',
+    desc = 'Quick chat about the cursor line (±10 lines) or visual selection',
     range = true,
     nargs = '+',
     complete = false,
@@ -689,6 +710,12 @@ M.command_defs = {
     desc = 'Open raw session debug view',
     execute = M.actions.debug_session,
   },
+  debug = {
+    desc = 'Export captured events or open plugin log',
+    completions = { 'events', 'log' },
+    nested_subcommand = { allow_empty = false },
+    execute = M.actions.debug,
+  },
   toggle_tool_output = {
     desc = 'Toggle tool output visibility in the output window',
     execute = M.actions.toggle_tool_output,
diff --git a/lua/opencode/config.lua b/lua/opencode/config.lua
index bd195bcb7..3cb6d0c27 100644
--- a/lua/opencode/config.lua
+++ b/lua/opencode/config.lua
@@ -6,7 +6,6 @@ local M = {}
 ---@type OpencodeConfig
 M.defaults = {
   preferred_picker = nil,
-  preferred_completion = nil,
   default_global_keymaps = true,
   default_mode = 'build',
   default_system_prompt = nil,
diff --git a/lua/opencode/ui/debug_helper.lua b/lua/opencode/ui/debug_helper.lua
index cc15cfaf9..77a64f955 100644
--- a/lua/opencode/ui/debug_helper.lua
+++ b/lua/opencode/ui/debug_helper.lua
@@ -4,6 +4,7 @@
 ---@field debug_message fun()
 ---@field debug_session fun()
 ---@field save_captured_events fun(filename?: string): integer|nil
+---@field open_log fun()
 local M = {}
 
 local event_capture = require('opencode.event_capture')
@@ -66,4 +67,19 @@ function M.save_captured_events(filename)
   return event_capture.save(filename)
 end
 
+function M.open_log()
+  local log = require('opencode.log')
+  local filename = log.get_path()
+  if not filename then
+    vim.notify('Plugin logging is disabled; enable logging.enabled to create a log file', vim.log.levels.WARN)
+    return
+  end
+  if vim.fn.filereadable(filename) ~= 1 then
+    vim.notify('Plugin log file does not exist yet: ' .. filename, vim.log.levels.WARN)
+    return
+  end
+
+  vim.cmd('edit ' .. vim.fn.fnameescape(filename))
+end
+
 return M
diff --git a/tests/manual/README.md b/tests/manual/README.md
index 82f7957f8..58c9ca6f0 100644
--- a/tests/manual/README.md
+++ b/tests/manual/README.md
@@ -50,7 +50,7 @@ To capture new event data for testing:
 
 1. Set `capture_streamed_events = true` in your config
 2. Use OpenCode normally to generate the events you want to capture
-3. Use `:lua require('opencode.ui.debug_helper').save_captured_events('data.json')` to save the captured events
+3. Use `:Opencode debug events data.json` to save the captured events
 4. That data can then be loaded with `:ReplayLoad`
 
 V1 captures store `type` and `properties`; V2 captures preserve native event fields, including timestamps, and replay through the V2 Observation. Keep each capture file to one protocol.
diff --git a/tests/unit/api_spec.lua b/tests/unit/api_spec.lua
index cd9add6c9..4854fab4f 100644
--- a/tests/unit/api_spec.lua
+++ b/tests/unit/api_spec.lua
@@ -351,6 +351,20 @@ describe('opencode.api', function()
       assert_send_message_called_with('test prompt new', true)
     end)
 
+    it('exposes event export and log viewing helpers', function()
+      local debug_helper = require('opencode.ui.debug_helper')
+      local save_events_stub = stub(debug_helper, 'save_captured_events')
+      local open_log_stub = stub(debug_helper, 'open_log')
+
+      api.debug_events('/tmp/events.json')
+      api.debug_log()
+
+      assert.stub(save_events_stub).was_called_with('/tmp/events.json')
+      assert.stub(open_log_stub).was_called()
+      save_events_stub:revert()
+      open_log_stub:revert()
+    end)
+
     it('routes submit_input_prompt through take_input, send_message, and after_run', function()
       with_session_snapshot(function()
         with_model_runtime_snapshot(function()
diff --git a/tests/unit/commands_handlers_spec.lua b/tests/unit/commands_handlers_spec.lua
index ca91e1836..d17670bc0 100644
--- a/tests/unit/commands_handlers_spec.lua
+++ b/tests/unit/commands_handlers_spec.lua
@@ -140,9 +140,30 @@ describe('opencode.commands.handlers', function()
     assert.same({ allow_empty = false }, defs.tab.nested_subcommand)
 
     assert.same({ 'input', 'output' }, defs.open.completions)
+    assert.same({ 'events', 'log' }, defs.debug.completions)
+    assert.same({ allow_empty = false }, defs.debug.nested_subcommand)
     assert.equal('user_commands', defs.command.completion_provider_id)
   end)
 
+  it('routes debug events and log commands to the debug helper', function()
+    local workflow = require('opencode.commands.handlers.workflow')
+    local debug_helper = require('opencode.ui.debug_helper')
+    local save_events = stub(debug_helper, 'save_captured_events')
+    local open_log = stub(debug_helper, 'open_log')
+
+    workflow.command_defs.debug.execute({ 'events', '/tmp/events.json' })
+    workflow.command_defs.debug.execute({ 'log' })
+
+    assert.stub(save_events).was_called_with('/tmp/events.json')
+    assert.stub(open_log).was_called()
+
+    local ok, err = pcall(workflow.command_defs.debug.execute, { 'events', 'a.json', 'extra' })
+    save_events:revert()
+    open_log:revert()
+    assert.is_false(ok)
+    assert.same({ code = 'invalid_arguments', message = 'Usage: :Opencode debug events [filename]' }, err)
+  end)
+
   it('keeps command semantic validation in window handler (open target)', function()
     local window = require('opencode.commands.handlers.window')
     local ok, err = pcall(window.command_defs.open.execute, { 'sideways' })