docs: finalize next release docs

10 files changed, 281 insertions, 27 deletions

diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx
index d6b3f7f2..57a0848f 100644
--- a/website/src/content/docs/agents.mdx
+++ b/website/src/content/docs/agents.mdx
@@ -24,6 +24,7 @@ Automatic detection works out of the box for common coding agents.
 | Kimi Code CLI | yes | yes | yes |
 | Kiro CLI | yes | yes | no |
 | GitHub Copilot CLI | yes | yes | yes |
+| Qoder CLI | yes | yes | yes |
 
 Detected but less thoroughly tested: Gemini CLI and Cline.
 
@@ -58,6 +59,7 @@ herdr integration install claude
 herdr integration install codex
 herdr integration install opencode
 herdr integration install hermes
+herdr integration install qodercli
 ```
 
 Check installed integration versions:
@@ -125,6 +127,8 @@ herdr agent attach reviewer
 
 Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.
 
+Scroll with the mouse wheel or plain page up/page down. Normal input jumps back to the bottom.
+
 Use `--takeover` if another direct attach client already owns input:
 
 ```bash
diff --git a/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx
index 2038ec6f..ed51ce1e 100644
--- a/website/src/content/docs/cli-reference.mdx
+++ b/website/src/content/docs/cli-reference.mdx
@@ -14,9 +14,11 @@ herdr                         # launch or attach to the default session
 herdr --session work          # launch or attach to a named session
 herdr --remote workbox        # attach through SSH, using local keybindings
 herdr --remote workbox --remote-keybindings server
+herdr --remote workbox --handoff
 herdr --no-session            # single-process escape hatch
 herdr --default-config        # print default config
 herdr update                  # download and install the latest version
+herdr update --handoff        # opt into live handoff for supported running servers
 herdr --version               # print version
 ```
 
@@ -130,6 +132,24 @@ herdr pane report-agent <pane_id> \
   [--seq N]
 ```
 
+Report display-only pane metadata without taking over semantic state:
+
+```bash
+herdr pane report-metadata <pane_id> \
+  --source ID \
+  [--agent LABEL] \
+  [--applies-to-source ID] \
+  [--title TEXT|--clear-title] \
+  [--display-agent TEXT|--clear-display-agent] \
+  [--custom-status TEXT|--clear-custom-status] \
+  [--state-label STATUS=TEXT] \
+  [--clear-state-labels] \
+  [--seq N] \
+  [--ttl-ms N]
+```
+
+`STATUS` is one of `idle`, `working`, `blocked`, `done`, or `unknown`. `--agent` is a guard for the authoritative agent label. `--applies-to-source` is a guard for the active lifecycle authority source. Use `--display-agent` to change the visible name.
+
 ## Agents
 
 ```bash
@@ -183,12 +203,14 @@ herdr integration install claude
 herdr integration install codex
 herdr integration install opencode
 herdr integration install hermes
+herdr integration install qodercli
 herdr integration uninstall pi
 herdr integration uninstall omp
 herdr integration uninstall claude
 herdr integration uninstall codex
 herdr integration uninstall opencode
 herdr integration uninstall hermes
+herdr integration uninstall qodercli
 herdr integration status [--outdated-only]
 ```
 
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx
index 2fe30027..765a0b0f 100644
--- a/website/src/content/docs/configuration.mdx
+++ b/website/src/content/docs/configuration.mdx
@@ -91,10 +91,13 @@ A small keybinding override looks like this:
 ```toml
 [keys]
 prefix = "ctrl+b"
+goto = "prefix+g"
 new_tab = "prefix+c"
 next_tab = "prefix+n"
 previous_tab = "prefix+p"
 focus_pane_left = "prefix+h"
+navigate_workspace_down = "j"
+navigate_pane_down = "ctrl+j"
 split_horizontal = "prefix+minus"
 ```
 
@@ -104,10 +107,17 @@ The default keymap is prefix-first and avoids direct shortcuts that can steal in
 [keys]
 detach = "prefix+q"
 workspace_picker = "prefix+w"
+goto = "prefix+g"
 new_workspace = "prefix+shift+n"
 new_worktree = "prefix+shift+g"
 rename_workspace = "prefix+shift+w"
 close_workspace = "prefix+shift+d"
+navigate_workspace_up = "up"
+navigate_workspace_down = "down"
+navigate_pane_left = "h"
+navigate_pane_down = "j"
+navigate_pane_up = "k"
+navigate_pane_right = "l"
 new_tab = "prefix+c"
 previous_tab = "prefix+p"
 next_tab = "prefix+n"
@@ -118,6 +128,9 @@ focus_pane_left = "prefix+h"
 focus_pane_down = "prefix+j"
 focus_pane_up = "prefix+k"
 focus_pane_right = "prefix+l"
+cycle_pane_next = "prefix+tab"
+cycle_pane_previous = "prefix+shift+tab"
+last_pane = ""
 split_vertical = "prefix+v"
 split_horizontal = "prefix+minus"
 close_pane = "prefix+x"
@@ -132,12 +145,15 @@ Optional actions are unset by default. Bind them with `prefix+` for prefix-mode
 [keys]
 previous_workspace = "prefix+shift+left"
 next_workspace = "prefix+shift+right"
+last_pane = "prefix+tab"
 open_worktree = "prefix+shift+o"
 remove_worktree = "prefix+alt+d"
 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.
+`last_pane` switches back to the last focused pane across workspaces and tabs. It is unset by default because the tmux-style pane binding `prefix+l` is already used for pane-right focus.
+
+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. The `navigate_workspace_*` and `navigate_pane_*` fields are navigate-mode-only and may use plain keys such as `j` or `k`; they must not use `prefix+`, `esc`, `enter`, `tab`, `shift+tab`, `left`, `right`, or unmodified `1` through `9`. Left and right arrows are permanent aliases for pane-left and pane-right navigation. These navigate-mode shortcuts are independent from general action bindings such as `focus_pane_down = "prefix+j"`; when both use the same key, the navigate-mode shortcut wins while navigate mode is open. 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`.
 
@@ -160,7 +176,7 @@ Custom commands use the same keybinding syntax.
 
 ```toml
 [[keys.command]]
-key = "prefix+g"
+key = "prefix+alt+g"
 type = "pane"
 command = "lazygit"
 ```
@@ -211,7 +227,9 @@ Common options:
 sidebar_width = 32
 sidebar_min_width = 18
 sidebar_max_width = 36
+mobile_width_threshold = 64
 mouse_capture = true
+redraw_on_focus_gained = true
 mouse_scroll_lines = 3
 confirm_close = true
 prompt_new_tab_name = true
@@ -222,11 +240,15 @@ accent = "cyan"
 
 `sidebar_min_width` and `sidebar_max_width` control the expanded sidebar's resize bounds in columns. The defaults are 18 and 36.
 
+`mobile_width_threshold` controls the terminal width at or below which Herdr uses the mobile single-column layout. The default is 64 columns; increase it for foldables, tablets, or wide phone terminals.
+
 `agent_panel_scope` can be `all` or `current`. Use `current` if you only want the agent panel to show agents in the active workspace.
 
 `confirm_close` controls whether closing a workspace asks for confirmation. `prompt_new_tab_name` controls whether new tabs ask for a label first.
 
-Set `mouse_capture = false` if you want your terminal to handle normal clicks, such as command-clicking URLs.
+Set `mouse_capture = false` if you want your terminal to handle normal clicks, such as command-clicking URLs. With mouse capture enabled, Ctrl-click opens pane links when your terminal sends that modified click to Herdr; use Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS for the terminal-native bypass path.
+
+Set `redraw_on_focus_gained = false` to avoid the visible full-screen refresh when switching back to Herdr. The default is `true` because a full redraw recovers from rare stale or dirty host terminal surfaces.
 
 Set `mouse_scroll_lines` to change how many pane scrollback lines each mouse wheel notch scrolls. The default is 3. Pane apps that request mouse reporting still receive wheel events directly.
 
@@ -262,7 +284,7 @@ enabled = true
 
 Herdr plays a done sound when an agent finishes and an attention sound when an agent needs input. Set `enabled = false` on shared machines or remote servers unless you explicitly want audio.
 
-On macOS, Herdr uses `afplay`. On Linux, Herdr tries `paplay`, then `aplay`. If no player is available, sound playback is skipped and Herdr logs a warning.
+On macOS, Herdr uses `afplay`. On Linux, Herdr tries mp3-capable players in order: `paplay`, `pw-play`, `ffplay`, `mpg123`, then `mpv`. If no player is available, sound playback is skipped and Herdr logs a warning.
 
 Custom sounds must be mp3 files. Relative paths are resolved from the config file's directory.
 
@@ -294,6 +316,23 @@ scrollback_limit_bytes = 10485760
 
 Existing panes keep their current buffer until they are recreated.
 
+## Pane screen history
+
+By default, full session restart restores workspaces, tabs, panes, cwd, layout, and focus without saving pane contents.
+
+Pane screen history is off by default. Pane output can include secrets, tokens, prompts, and command output, so enable it only when you want Herdr to save recent pane contents across full server restarts:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+You can also toggle it from Settings > Experiments > pane screen history.
+
+When enabled, Herdr stores saved pane history in `session-history.json` next to `session.json`.
+
+For how pane screen history differs from live persistence, snapshot restore, native agent session restore, and live handoff, see [Session state and restore](/docs/session-state/).
+
 ## Nested launches
 
 Herdr normally protects you from launching Herdr inside Herdr.
@@ -316,6 +355,21 @@ kitty_graphics = false
 
 Leave this off unless you are testing terminal image behavior.
 
+## Agent session restore
+
+Herdr can restart supported agent panes in their native conversation sessions after a Herdr server restart.
+
+```toml
+[session]
+resume_agents_on_restore = false
+```
+
+When enabled, Herdr only resumes panes that reported a native session reference through an official Herdr integration. Supported resume targets are Claude Code, Codex, Pi, Hermes Agent, and OpenCode. Unsupported, missing, invalid, duplicated, or stale session references restore as a normal shell in the saved pane directory.
+
+Session references are stored in the local Herdr session snapshot. They are not shown in normal pane, agent, status, or event output.
+
+For how native agent session restore differs from pane screen history and live handoff, see [Session state and restore](/docs/session-state/).
+
 ## IME cursor tracking
 
 When the focused pane hides its cursor and paints its own — common in AI-agent TUIs like Claude Code, pi, and codex — macOS native input methods stop tracking the candidate window position because the outer terminal stops reporting the cursor.
@@ -331,7 +385,7 @@ cjk_ime_cursor_shape = "steady_block"
 
 When enabled, the cursor stays visible at the focused pane's reported position. If the pane reports no cursor position, the anchor falls back to the pane's top-left so a stable IME hint is always available.
 
-`cjk_ime_agents` is an optional allow-list. When empty, the reveal applies to any focused pane. When non-empty, the reveal only applies if the focused pane's detected agent matches one of the listed names — useful to enable the reveal only for AI-agent TUIs that paint their own cursor while leaving plain shells untouched. Accepted names: `pi`, `claude`, `codex`, `gemini`, `cursor`, `agy`, `cline`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`. Unknown names are ignored; if the list contains no valid names, the reveal does not apply.
+`cjk_ime_agents` is an optional allow-list. When empty, the reveal applies to any focused pane. When non-empty, the reveal only applies if the focused pane's detected agent matches one of the listed names — useful to enable the reveal only for AI-agent TUIs that paint their own cursor while leaving plain shells untouched. Accepted names: `pi`, `claude`, `codex`, `gemini`, `cursor`, `agy`, `cline`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `qodercli`, and `qoder`. Unknown names are ignored; if the list contains no valid names, the reveal does not apply.
 
 `cjk_ime_cursor_shape` controls the DECSCUSR shape rendered for the IME anchor. Accepted values: `block`, `steady_block` (default), `underline`, `steady_underline`, `bar`, `steady_bar`.
 
diff --git a/website/src/content/docs/index.mdx b/website/src/content/docs/index.mdx
index 20ea24af..f21ec902 100644
--- a/website/src/content/docs/index.mdx
+++ b/website/src/content/docs/index.mdx
@@ -5,7 +5,7 @@ template: splash
 hero:
   tagline: "One terminal for the whole herd: real panes, persistent sessions, SSH attach, state awareness, and CLI/socket orchestration."
   image:
-    html: '<span class="docs-hero-logo" aria-hidden="true"></span>'
+    file: ../../../public/assets/logo.svg
   actions:
     - text: Install Herdr
       link: /docs/install/
@@ -19,11 +19,6 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 Herdr is a terminal-native agent runtime and multiplexer. It gives the whole herd persistent terminal workspaces with panes, tabs, mouse control, state awareness, and an API that agents can use themselves.
 
 ```bash
-brew install herdr
-herdr
-```
-
-```bash
 curl -fsSL https://herdr.dev/install.sh | sh
 herdr
 ```
@@ -51,6 +46,11 @@ herdr
 
     [Understand agents →](/docs/agents/)
   </Card>
+  <Card title="Session state">
+    Understand detach, restart restore, pane history replay, native agent resume, and live handoff.
+
+    [Compare state paths →](/docs/session-state/)
+  </Card>
   <Card title="Configuration">
     Configure keybindings, themes, sidebar behavior, notifications, scrollback, and advanced options.
 
diff --git a/website/src/content/docs/install.mdx b/website/src/content/docs/install.mdx
index 533d9890..6d80180c 100644
--- a/website/src/content/docs/install.mdx
+++ b/website/src/content/docs/install.mdx
@@ -7,20 +7,22 @@ Herdr ships as a single binary for Linux and macOS.
 
 ## Install
 
-Install with Homebrew:
+Run the installer:
 
 ```bash
-brew install herdr
+curl -fsSL https://herdr.dev/install.sh | sh
 ```
 
-Or run the installer:
+The installer downloads the right release binary for your platform and places it on your PATH.
+
+## Install with Homebrew
+
+If you already use Homebrew:
 
 ```bash
-curl -fsSL https://herdr.dev/install.sh | sh
+brew install herdr
 ```
 
-The installer downloads the right release binary for your platform and places it on your PATH.
-
 ## Verify
 
 Start Herdr:
@@ -33,13 +35,21 @@ If your shell cannot find `herdr`, restart the terminal or check that the instal
 
 ## Update
 
-Herdr checks for new releases and notifies you in the app. Direct installs can update manually:
+Herdr checks for new releases and notifies you in the app. You can update manually:
 
 ```bash
 herdr update
 ```
 
-`herdr update` is disabled for Homebrew and Nix installs. Update those through `brew upgrade herdr` or your Nix workflow.
+`herdr update` is for installs managed by Herdr's own installer. Homebrew and Nix installs are updated through those package managers instead.
+
+By default, `herdr update` installs the new binary and leaves compatible running sessions alone, or asks before stopping sessions that must restart. To opt into live server handoff for supported running sessions, run:
+
+```bash
+herdr update --handoff
+```
+
+Live handoff does not apply to Homebrew or Nix package-manager updates. For those installs, update with the package manager, then restart any running Herdr servers that need the new binary.
 
 ## Install with Nix
 
diff --git a/website/src/content/docs/integrations.mdx b/website/src/content/docs/integrations.mdx
index 8c6443b8..aba9b046 100644
--- a/website/src/content/docs/integrations.mdx
+++ b/website/src/content/docs/integrations.mdx
@@ -1,6 +1,6 @@
 ---
 title: Integrations
-description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, OpenCode, and Hermes Agent.
+description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, OpenCode, Hermes Agent, and Qoder CLI.
 ---
 
 Herdr detects supported agents automatically. Integrations make that detection more precise by reporting semantic state directly to Herdr.
@@ -18,6 +18,7 @@ herdr integration install claude
 herdr integration install codex
 herdr integration install opencode
 herdr integration install hermes
+herdr integration install qodercli
 ```
 
 ## Uninstall integrations
@@ -29,6 +30,7 @@ herdr integration uninstall claude
 herdr integration uninstall codex
 herdr integration uninstall opencode
 herdr integration uninstall hermes
+herdr integration uninstall qodercli
 ```
 
 ## How Herdr uses integrations
@@ -43,6 +45,10 @@ Herdr combines three signals:
 
 Integrations enrich state reporting. They do not replace process detection.
 
+Some integrations also report native agent session references. If `[session] resume_agents_on_restore = true` is enabled, Herdr uses official session references to resume Claude Code, Codex, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart.
+
+Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `4`, Codex version `4`, OpenCode version `2`, or Hermes Agent version `2`. OMP integration version `2` reports agent state only. Check installed versions with `herdr integration status`.
+
 ## Pi
 
 Install the Pi integration:
@@ -111,7 +117,7 @@ herdr integration install opencode
 
 Herdr writes the plugin to `~/.config/opencode/plugins/herdr-agent-state.js`. The OpenCode config directory must already exist. Uninstall removes only that plugin file.
 
-The plugin reports semantic state while OpenCode runs inside a Herdr pane.
+The plugin reports semantic state while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`.
 
 ## Hermes Agent
 
@@ -123,7 +129,21 @@ herdr integration install hermes
 
 Herdr writes `~/.hermes/plugins/herdr-agent-state/` and enables `herdr-agent-state` in `~/.hermes/config.yaml`. The Hermes config directory must already exist. Restart Hermes after installing so the plugin loads. Uninstall removes the plugin directory and removes `herdr-agent-state` from `plugins.enabled`.
 
-The plugin reports lifecycle, tool, and approval state while Hermes runs inside a Herdr pane. Native screen heuristics remain available when the plugin is not installed.
+The plugin reports lifecycle, tool, approval state, and session id while Hermes runs inside a Herdr pane. Herdr can use the reported session id to resume the pane with `hermes --resume <id>`. Native screen heuristics remain available when the plugin is not installed.
+
+## Qoder CLI
+
+Install the Qoder CLI hook:
+
+```bash
+herdr integration install qodercli
+```
+
+The hook reports semantic state to Herdr when Qoder CLI emits lifecycle events.
+
+Herdr uses `~/.qoder` by default, or `QODER_CONFIG_DIR` when set. The Qoder config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.
+
+Native screen heuristics remain available when the hook is not installed.
 
 ## Custom status labels
 
@@ -139,7 +159,21 @@ herdr pane report-agent 1-1 \
   --custom-status indexing
 ```
 
-Custom status is visual-only. Waits, notifications, and workspace rollups still use the semantic state.
+User hooks that run next to a Herdr-managed integration should use metadata instead of `report-agent`. Metadata changes presentation without taking over the integration's `idle`, `working`, `blocked`, or session restore authority. `--agent` guards the report so it only applies while that authoritative agent is active. `--applies-to-source` guards the report so it only applies while that lifecycle authority source is active. `--display-agent` changes the visible name.
+
+```bash
+herdr pane report-metadata "$HERDR_PANE_ID" \
+  --source user:claude-title \
+  --agent claude \
+  --applies-to-source herdr:claude \
+  --title "Refactor auth middleware" \
+  --display-agent "Claude: auth" \
+  --custom-status "refactor auth" \
+  --state-label working="refactoring auth" \
+  --ttl-ms 3600000
+```
+
+Custom status and state labels are visual-only. Waits, notifications, and workspace rollups still use the semantic state.
 
 ## Debug integration state
 
diff --git a/website/src/content/docs/persistence-remote.mdx b/website/src/content/docs/persistence-remote.mdx
index d6c02f0a..f83da309 100644
--- a/website/src/content/docs/persistence-remote.mdx
+++ b/website/src/content/docs/persistence-remote.mdx
@@ -29,6 +29,8 @@ If you want to end the session and stop its panes, stop the default server:
 herdr server stop
 ```
 
+When Herdr starts again after a full server stop, it restores the saved session shape. For what survives detach, server restart, screen history replay, native agent session restore, and live handoff, see [Session state and restore](/docs/session-state/).
+
 ## Named sessions
 
 Use named sessions when you want independent Herdr servers.
@@ -90,9 +92,15 @@ herdr --remote workbox
 
 Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks `~/.local/bin/herdr`. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install.
 
+By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into live handoff for a supported running remote server, pass `--handoff`:
+
+```bash
+herdr --remote workbox --handoff
+```
+
 If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.
 
-When your local and remote platforms match, Herdr can copy the current local binary. Otherwise it downloads the matching release asset from `https://herdr.dev/latest.json`.
+When your local and remote platforms match, Herdr can copy the current local binary for direct installs. For Homebrew and Nix installs, or when the platforms differ, it downloads the matching release asset for the current client version from `https://herdr.dev/latest.json`.
 
 For local builds or custom binaries, set `HERDR_REMOTE_BINARY` to a local file path before running remote attach.
 
diff --git a/website/src/content/docs/quick-start.mdx b/website/src/content/docs/quick-start.mdx
index f56048b9..7dc6e019 100644
--- a/website/src/content/docs/quick-start.mdx
+++ b/website/src/content/docs/quick-start.mdx
@@ -15,7 +15,7 @@ For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr]
 
 ## Create a workspace
 
-Press `n` to create a workspace. A workspace is a project-level container for tabs, panes, and agents.
+Press `prefix+shift+n` to create a workspace. A workspace is a project-level container for tabs, panes, and agents.
 
 Give each active project its own workspace. This keeps agent state readable in the sidebar.
 
@@ -49,7 +49,9 @@ After detaching, run `herdr` again to reattach to the same session.
 
 ## Use the mouse
 
-Herdr is mouse-native. You can click panes, tabs, workspaces, and agents; drag borders; select text; and use right-click menus.
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents; drag borders; drag-select text to copy it to your clipboard; double-click a token to copy it directly; and use right-click menus. Copying does not require Ctrl+C.
+
+Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. The portable terminal-native fallback is Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS.
 
 ## Manage named sessions
 
diff --git a/website/src/content/docs/session-state.mdx b/website/src/content/docs/session-state.mdx
new file mode 100644
index 00000000..efe0cb01
--- /dev/null
+++ b/website/src/content/docs/session-state.mdx
@@ -0,0 +1,94 @@
+---
+title: Session state and restore
+description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
+---
+
+Herdr has several state paths. They solve different problems.
+
+## Live persistence
+
+Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
+
+Detach the client with `ctrl+b q`. Reattach later:
+
+```bash
+herdr
+```
+
+This is the strongest persistence path because the original processes never stop.
+
+## Snapshot restore
+
+If the Herdr server stops and starts again, the original pane processes are gone. Herdr restores the saved session shape: workspaces, tabs, panes, cwd, layout, and focus.
+
+Snapshot restore does not preserve running shells, servers, tests, or arbitrary processes. Panes that cannot use a stronger restore path come back as new shells in their saved directories.
+
+## Pane screen history replay
+
+Pane screen history restores recent terminal contents after a full server restart. It restores what Herdr can show, not the old process.
+
+This is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it from Settings > Experiments > pane screen history or with:
+
+```toml
+[experimental]
+pane_history = true
+```
+
+When enabled, Herdr stores saved pane history in `session-history.json` next to `session.json`. Treat the Herdr config/session directory like terminal history.
+
+## Native agent session restore
+
+Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
+
+Enable it with:
+
+```toml
+[session]
+resume_agents_on_restore = true
+```
+
+When enabled, Herdr only resumes panes that reported a native session reference through a current official Herdr integration.
+
+Native session restore requires these Herdr integration versions or newer:
+
+| Agent | Minimum Herdr integration version | Resume command |
+| --- | --- | --- |
+| Pi | `2` | `pi --session <path-or-id>` |
+| Claude Code | `4` | `claude --resume <id>` |
+| Codex | `4` | `codex resume <id>` |
+| OpenCode | `2` | `opencode --session <id>` |
+| Hermes Agent | `2` | `hermes --resume <id>` |
+
+OMP integration version `2` reports agent state, but does not report native session references for restore.
+
+Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.
+
+Unsupported, missing, invalid, duplicated, or stale session references restore as normal shells in the saved pane directory.
+
+If native agent session restore applies to a pane, Herdr resumes the agent session instead of replaying saved pane history for that pane.
+
+## Live handoff
+
+Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.
+
+This is different from snapshot restore, pane history replay, and native agent session restore. Handoff tries to keep the current processes alive. The others reconstruct state after the old server has already stopped.
+
+Live handoff is opt-in:
+
+```bash
+herdr update --handoff
+herdr --remote workbox --handoff
+```
+
+Plain `herdr update` and plain `herdr --remote workbox` use the normal restart/stop flow by default.
+
+`herdr update --handoff` only applies to installs managed by Herdr's own updater. Homebrew and Nix installs are updated through their package managers, so `herdr update` is disabled there and cannot perform live handoff.
+
+## What Survives
+
+| Case | Processes keep running | Layout returns | Recent screen returns | Agent conversation resumes |
+| --- | --- | --- | --- | --- |
+| Detach and reattach | Yes | Yes | Yes, from the live terminal | Yes, because the process never stopped |
+| Server restart | No | Yes | Only with pane screen history | Only with native agent session restore |
+| Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
+| Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
diff --git a/website/src/content/docs/socket-api.mdx b/website/src/content/docs/socket-api.mdx
index 4d32817e..3b12d928 100644
--- a/website/src/content/docs/socket-api.mdx
+++ b/website/src/content/docs/socket-api.mdx
@@ -73,7 +73,7 @@ Raw socket method names use dot notation:
 | Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` |
 | Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
 | Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.close` |
-| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
+| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
 | Agent | `agent.list`, `agent.get`, `agent.read`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
 | Events | `events.subscribe`, `events.wait` |
 | Integrations | `integration.install`, `integration.uninstall` |
@@ -163,6 +163,32 @@ Integrations report agent state with `pane.report_agent`.
 
 `custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior.
 
+Use `pane.report_metadata` when a user hook wants to customize presentation without taking over lifecycle state from a Herdr integration.
+
+```json
+{
+  "id": "req_2",
+  "method": "pane.report_metadata",
+  "params": {
+    "pane_id": "1-1",
+    "source": "user:claude-title",
+    "agent": "claude",
+    "applies_to_source": "herdr:claude",
+    "title": "Refactor auth middleware",
+    "display_agent": "Claude: auth",
+    "custom_status": "refactor auth",
+    "state_labels": {
+      "working": "refactoring auth",
+      "idle": "ready",
+      "done": "review ready"
+    },
+    "ttl_ms": 3600000
+  }
+}
+```
+
+Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, compact custom status, and visible state labels. `working`, `blocked`, `idle`, waits, notifications, session restore, and rollups still come from the active agent state report. `agent` is an optional guard for the authoritative agent label; `applies_to_source` is an optional guard for the active lifecycle authority source. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`. Use clear fields such as `clear_custom_status: true` with the same `source` to remove one presentation override.
+
 ## Event subscriptions
 
 Subscribe to events when you need a long-lived stream: