docs: finalize release docs

8 files changed, 128 insertions, 67 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e60a2e2..e69217b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+### Added
+- Added keybinding v2 with explicit `prefix+...` syntax, array bindings per action, configurable prefix-mode pane focus, tab switching, and direct modified chords for users who opt in. (#154, #201, #202, #219)
+- Added `herdr config reset-keys` to back up `config.toml` and remove custom keybindings so built-in v2 defaults apply on restart or config reload. (#154)
+- Added an integrations tab in settings and first-run onboarding so users can install recommended agent integrations from inside Herdr.
+- Added update badges on the sidebar menu, settings menu item, and integrations settings tab when installed integrations are outdated.
+- Added `terminal.default_shell` to choose the executable used for new interactive panes. When unset, Herdr still falls back to `$SHELL`, then `/bin/sh`. (#196)
+- Added native Kiro CLI detection with idle and working state heuristics. (#185)
+
+### Fixed
+- Keybinding conflict warnings now stay visible and show one readable yellow row per conflicting binding.
+- Update prompts that need to stop a running server now default Enter to yes and show `[Y/n]`.
+- Pending release notes no longer open automatically on startup; the latest notes remain available from the menu.
+- Running `herdr server` directly now prints socket and log paths and explains that normal TUI users should run `herdr`.
+- Kitty graphics virtual Unicode placeholders now render image placements instead of leaving placeholder cells behind. (#136)
+- Clipboard image reads are now capped to Herdr's image payload limit, preventing oversized local clipboard images from being read into memory.
+- The install script now reads Herdr's public latest-release manifest, so fresh installs use the same binary URLs as `herdr update`.
+- The Claude Code integration no longer lets subagent completion hooks report durable `working`, preventing delayed recap or subagent completion events from reviving an idle pane. (#198)
+- Remote clients now bridge local clipboard images into the remote pane by staging them as temporary image files and pasting the remote path, so Claude Code image paste works over `herdr --remote`. (#205)
+
+### Breaking Changes
+- Removed the separate `keys.quit` binding. Use `keys.detach`, which detaches in server mode and exits in `--no-session` mode. The default detach binding is now `prefix+q`.
+- Keybindings now use explicit trigger syntax: `prefix+c` means prefix mode, while `ctrl+alt+c` is direct. Bare printable direct bindings such as `new_tab = "c"` are rejected with diagnostics because they intercept normal typing. The default keymap now gives tmux-style tab actions to `prefix+c`, `prefix+n`/`prefix+p`, and `prefix+1..9`, uses `prefix+w` for workspace navigation, and moves pane focus to `prefix+h/j/k/l`. (#154)
+- The client/server protocol is now version 8. Stop and restart any running v0.5.12 server before attaching with this release.
+
 ## [0.5.12] - 2026-05-19
 
 ### Fixed
diff --git a/README.md b/README.md
index 68f2f112..2e659930 100644
--- a/README.md
+++ b/README.md
@@ -53,10 +53,10 @@ herdr session stop work
 herdr session delete side-project
 ```
 
-1. press `n` to create a workspace
+1. press `ctrl+b`, then `shift+n` to create a workspace
 2. run an agent in the root pane
-3. press `ctrl+b` to enter navigate mode
-4. use `v` or `-` to split panes, or `c` to create a new tab
+3. press `ctrl+b`, then `w` to open workspace navigation
+4. use `ctrl+b`, then `v` or `minus` to split panes, or `ctrl+b`, then `c` to create a new tab
 5. watch the sidebar for blocked, working, and done states
 
 on first run herdr opens a short onboarding flow. after that, restored sessions land in terminal mode; fresh sessions start in **navigate mode**.
@@ -179,6 +179,7 @@ automatic detection works out of the box. process name matching plus terminal ou
 | [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
 | [grok cli](https://x.ai/grok) | ✓ | ✓ | ✓ |
 | [hermes agent](https://github.com/NousResearch/hermes-agent) | ✓ | ✓ | ✓ |
+| [kiro cli](https://kiro.dev/docs/cli/) | ✓ | ✓ | — |
 
 detected but not fully tested: gemini cli, cursor agent, cline, kimi, github copilot cli.
 
@@ -200,32 +201,38 @@ see the [integrations docs](https://herdr.dev/docs/integrations/) for setup deta
 
 ## keybindings
 
-press `ctrl+b` to enter navigate mode.
+press `ctrl+b` to enter prefix mode. default actions are prefix-first and tmux-like:
 
 | key | action |
 |-----|--------|
-| `n` | new workspace |
-| `shift+n` | rename workspace |
-| `shift+d` | close workspace |
-| `c` | new tab |
-| `v` / `-` | split pane |
-| `x` | close pane |
-| `b` | toggle sidebar |
-| `f` | zoom pane |
-| `r` | resize mode |
-| `q` | detach (quit client) |
+| `prefix+c` | new tab |
+| `prefix+n` / `prefix+p` | next / previous tab |
+| `prefix+1..9` | switch tab |
+| `prefix+w` | workspace navigation |
+| `prefix+shift+n` | new workspace |
+| `prefix+shift+w` | rename workspace |
+| `prefix+shift+d` | close workspace |
+| `prefix+h/j/k/l` | focus pane |
+| `prefix+v` / `prefix+minus` | split pane |
+| `prefix+x` | close pane |
+| `prefix+b` | toggle sidebar |
+| `prefix+z` | zoom pane |
+| `prefix+r` | resize mode |
+| `prefix+q` | detach |
 
 resize mode: `h`/`l` resize width, `j`/`k` resize height, `esc` exit.
 
-custom command keybindings can launch detached shell helpers or temporary panes from prefix mode:
+custom command keybindings can launch detached shell helpers or temporary panes:
 
 ```toml
 [[keys.command]]
-key = "g"
+key = "prefix+g"
 type = "pane" # "shell" or "pane"
 command = "lazygit"
 ```
 
+if you have old custom keybindings and want the new defaults, run `herdr config reset-keys`. herdr backs up `config.toml`, removes only keybinding config, and uses built-in v2 defaults after restart or config reload.
+
 mouse is supported throughout. full reference: [configuration docs](https://herdr.dev/docs/configuration/).
 
 ## configuration
diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index 6b25d5c3..e69217b1 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -3,7 +3,7 @@
 ## Unreleased
 
 ### Added
-- Added keybinding v2 with explicit `prefix+...` syntax, array bindings per action, configurable prefix-mode pane focus, tab switching, and direct modified chords for users who opt in. (#154)
+- Added keybinding v2 with explicit `prefix+...` syntax, array bindings per action, configurable prefix-mode pane focus, tab switching, and direct modified chords for users who opt in. (#154, #201, #202, #219)
 - Added `herdr config reset-keys` to back up `config.toml` and remove custom keybindings so built-in v2 defaults apply on restart or config reload. (#154)
 - Added an integrations tab in settings and first-run onboarding so users can install recommended agent integrations from inside Herdr.
 - Added update badges on the sidebar menu, settings menu item, and integrations settings tab when installed integrations are outdated.
@@ -12,6 +12,12 @@
 
 ### Fixed
 - Keybinding conflict warnings now stay visible and show one readable yellow row per conflicting binding.
+- Update prompts that need to stop a running server now default Enter to yes and show `[Y/n]`.
+- Pending release notes no longer open automatically on startup; the latest notes remain available from the menu.
+- Running `herdr server` directly now prints socket and log paths and explains that normal TUI users should run `herdr`.
+- Kitty graphics virtual Unicode placeholders now render image placements instead of leaving placeholder cells behind. (#136)
+- Clipboard image reads are now capped to Herdr's image payload limit, preventing oversized local clipboard images from being read into memory.
+- The install script now reads Herdr's public latest-release manifest, so fresh installs use the same binary URLs as `herdr update`.
 - The Claude Code integration no longer lets subagent completion hooks report durable `working`, preventing delayed recap or subagent completion events from reviving an idle pane. (#198)
 - Remote clients now bridge local clipboard images into the remote pane by staging them as temporary image files and pasting the remote path, so Claude Code image paste works over `herdr --remote`. (#205)
 
diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx
index dfa2f204..f1499021 100644
--- a/website/src/content/docs/agents.mdx
+++ b/website/src/content/docs/agents.mdx
@@ -19,6 +19,7 @@ Automatic detection works out of the box for common coding agents.
 | OpenCode | yes | yes | yes |
 | Grok CLI | yes | yes | yes |
 | Hermes Agent | yes | yes | yes |
+| Kiro CLI | yes | yes | no |
 | GitHub Copilot CLI | yes | yes | yes |
 
 Detected but less thoroughly tested: Gemini CLI, Cursor Agent, Cline, and Kimi.
diff --git a/website/src/content/docs/concepts.mdx b/website/src/content/docs/concepts.mdx
index ea77ac20..b1a7908f 100644
--- a/website/src/content/docs/concepts.mdx
+++ b/website/src/content/docs/concepts.mdx
@@ -67,11 +67,11 @@ herdr server stop
 
 ## Modes
 
-Herdr has terminal mode and navigate mode.
+Herdr has terminal mode, prefix mode, and navigate mode.
 
-Terminal mode sends keys to the focused pane. Navigate mode sends keys to Herdr.
+Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface.
 
-Press the prefix key, default `ctrl+b`, to enter navigate mode. Use navigate mode to create workspaces, split panes, switch tabs, resize, open menus, or detach.
+Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation.
 
 ## Mouse UI
 
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx
index 558f01f1..9df7e41d 100644
--- a/website/src/content/docs/configuration.mdx
+++ b/website/src/content/docs/configuration.mdx
@@ -27,7 +27,7 @@ herdr --default-config > ~/.config/herdr/config.toml
 
 If a config value is invalid, Herdr falls back to a safe default and shows a startup warning.
 
-Herdr shows first-run notification setup when `onboarding` is missing or true. Set it when you want to skip that flow after choosing your notification settings.
+Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set it when you want to skip that flow after setup.
 
 ```toml
 onboarding = false
@@ -45,74 +45,93 @@ You can also open the global menu in Herdr and choose `reload config`.
 
 Reload applies most UI settings without restarting panes. Startup-only settings still need a restart.
 
+## Default shell
+
+Set the executable Herdr uses for newly created interactive panes:
+
+```toml
+[terminal]
+default_shell = "nu"
+```
+
+When unset or empty, Herdr uses `$SHELL`, then `/bin/sh`. This is an executable name or path, not a shell command line. Existing panes keep their current shell until they are recreated. Command panes still run through `/bin/sh -c`; detached custom command keybindings use Herdr's existing `/bin/sh -lc` path.
+
 ## Keybindings
 
-Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`.
+Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`. Keybinding strings are explicit: `prefix+n` means press the configured prefix and then `n`; `ctrl+alt+n` is a direct terminal-mode shortcut.
 
 A small keybinding override looks like this:
 
 ```toml
 [keys]
 prefix = "ctrl+b"
-new_workspace = "n"
-rename_workspace = "shift+n"
-close_workspace = "shift+d"
-new_tab = "c"
-split_vertical = "v"
-split_horizontal = "-"
-close_pane = "x"
-zoom = "f"
-resize_mode = "r"
-toggle_sidebar = "b"
+new_tab = "prefix+c"
+next_tab = "prefix+n"
+previous_tab = "prefix+p"
+focus_pane_left = "prefix+h"
+split_horizontal = "prefix+minus"
 ```
 
-Optional actions are unset by default. Bind them when you want direct shortcuts:
+The default keymap is prefix-first and avoids direct shortcuts that can steal input from shells, editors, tmux, or terminal apps. Common defaults include:
 
 ```toml
 [keys]
-detach = "q"
-reload_config = "R"
-open_notification_target = "o"
-previous_workspace = "H"
-next_workspace = "L"
-previous_agent = "A"
-next_agent = "D"
-previous_tab = "J"
-next_tab = "K"
-rename_tab = "T"
-close_tab = "W"
-rename_pane = "p"
-edit_scrollback = "e"
-focus_pane_left = "h"
-focus_pane_down = "j"
-focus_pane_up = "k"
-focus_pane_right = "l"
+detach = "prefix+q"
+workspace_picker = "prefix+w"
+new_workspace = "prefix+shift+n"
+rename_workspace = "prefix+shift+w"
+close_workspace = "prefix+shift+d"
+new_tab = "prefix+c"
+previous_tab = "prefix+p"
+next_tab = "prefix+n"
+switch_tab = "prefix+1..9"
+rename_tab = "prefix+shift+t"
+close_tab = "prefix+shift+x"
+focus_pane_left = "prefix+h"
+focus_pane_down = "prefix+j"
+focus_pane_up = "prefix+k"
+focus_pane_right = "prefix+l"
+split_vertical = "prefix+v"
+split_horizontal = "prefix+minus"
+close_pane = "prefix+x"
+zoom = "prefix+z"
+resize_mode = "prefix+r"
+toggle_sidebar = "prefix+b"
 ```
 
-Use the full default config to see every available action.
+Optional actions are unset by default. Bind them with `prefix+` for prefix-mode behavior, or with an explicit modified chord when you intentionally want a direct shortcut:
 
-Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Plain keys, `ctrl+letter`, Escape, Tab, Enter, and function keys are the most reliable. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings.
+```toml
+[keys]
+previous_workspace = "prefix+shift+left"
+next_workspace = "prefix+shift+right"
+next_tab = ["prefix+n", "ctrl+alt+]"]
+```
+
+Key strings accept plain keys, modifier combinations such as `ctrl+a`, `shift+n`, `alt+1`, `cmd+k`, and special keys such as `enter`, `tab`, `esc`, `left`, `right`, `up`, and `down`. Named punctuation such as `minus`, `comma`, `ampersand`, `plus`, and `backtick` is also accepted. Plain direct printable keys such as `n` are unsafe because they intercept typing; use `prefix+n` unless you intentionally want a direct binding. Alt, Cmd/Super, and punctuation with modifiers depend on your terminal and tmux settings.
+
+If you have old custom keybindings and want the new defaults, run `herdr config reset-keys`. Herdr backs up `config.toml`, removes `[keys]` and `[[keys.command]]`, and uses built-in v2 defaults after restart or `herdr server reload-config`.
 
 ## Indexed jumps
 
-Indexed keybindings let you jump directly to visible positions.
+Indexed keybindings use `1..9` in normal keybinding fields:
 
 ```toml
-[keys.indexed]
-workspaces = "ctrl+shift"
-tabs = "ctrl"
-agents = "alt"
+[keys]
+switch_tab = "prefix+1..9"
+switch_workspace = "prefix+shift+1..9"
+focus_agent = "prefix+alt+1..9"
 ```
 
-These expand over number keys 1 through 9. For example, `tabs = "ctrl"` makes `ctrl+1` through `ctrl+9` switch tabs.
+The legacy `[keys.indexed]` table is still parsed for compatibility, but new configs should prefer the explicit action fields.
 
 ## Custom command keybindings
 
-Custom prefix-mode commands can run shell helpers from inside Herdr.
+Custom commands use the same keybinding syntax.
 
 ```toml
 [[keys.command]]
-key = "g"
+key = "prefix+g"
 type = "pane"
 command = "lazygit"
 ```
diff --git a/website/src/content/docs/integrations.mdx b/website/src/content/docs/integrations.mdx
index 8303d142..18b759bc 100644
--- a/website/src/content/docs/integrations.mdx
+++ b/website/src/content/docs/integrations.mdx
@@ -9,6 +9,8 @@ Use integrations when you want reliable `working`, `blocked`, `idle`, and `done`
 
 ## Install integrations
 
+Open settings inside Herdr and use the integrations tab to install recommended integrations for agents found on your `PATH`, or run commands manually:
+
 ```bash
 herdr integration install pi
 herdr integration install claude
diff --git a/website/src/content/docs/quick-start.mdx b/website/src/content/docs/quick-start.mdx
index fddef6b8..f56048b9 100644
--- a/website/src/content/docs/quick-start.mdx
+++ b/website/src/content/docs/quick-start.mdx
@@ -29,19 +29,21 @@ pi
 
 Herdr detects supported agents automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`.
 
-## Navigate
+## Keyboard control
 
-Press `ctrl+b` to enter navigate mode.
+Press `ctrl+b` to enter prefix mode, then press an action key.
 
 Common actions:
 
 | Action | Key |
 | --- | --- |
-| Split right | `v` |
-| Split down | `-` |
-| New tab | `c` |
-| New workspace | `n` |
-| Detach client | `q` |
+| Split right | `prefix+v` |
+| Split down | `prefix+minus` |
+| New tab | `prefix+c` |
+| Next / previous tab | `prefix+n` / `prefix+p` |
+| Workspace navigation | `prefix+w` |
+| New workspace | `prefix+shift+n` |
+| Detach client | `prefix+q` |
 
 After detaching, run `herdr` again to reattach to the same session.