docs: refresh configuration docs

4 files changed, 74 insertions, 9 deletions

diff --git a/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx
index 57f495c1..14c36a76 100644
--- a/website/src/content/docs/cli-reference.mdx
+++ b/website/src/content/docs/cli-reference.mdx
@@ -15,6 +15,7 @@ herdr --session work          # launch or attach to a named session
 herdr --remote workbox        # attach through SSH
 herdr --no-session            # single-process escape hatch
 herdr --default-config        # print default config
+herdr update                  # download and install the latest version
 herdr --version               # print version
 ```
 
@@ -29,11 +30,12 @@ herdr status client
 ## Server
 
 ```bash
+herdr server
 herdr server stop
 herdr server reload-config
 ```
 
-`reload-config` applies reloadable settings without restarting panes.
+`herdr server` runs the headless server explicitly. Use it for supervised or service-style setups. `reload-config` applies reloadable settings without restarting panes.
 
 ## Sessions
 
@@ -190,3 +192,4 @@ herdr integration status [--outdated-only]
 | `HERDR_SESSION` | Select a named session for CLI commands. |
 | `HERDR_SOCKET_PATH` | Low-level socket path override. |
 | `HERDR_LOG` | Set log filter, for example `HERDR_LOG=herdr=debug`. |
+| `HERDR_DISABLE_SOUND` | Disable sound playback even when sound notifications are enabled. |
diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx
index 6d654310..558f01f1 100644
--- a/website/src/content/docs/configuration.mdx
+++ b/website/src/content/docs/configuration.mdx
@@ -27,6 +27,12 @@ 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.
+
+```toml
+onboarding = false
+```
+
 ## Reload config
 
 Reload a running server after editing `config.toml`:
@@ -69,8 +75,12 @@ 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"
@@ -81,6 +91,8 @@ focus_pane_right = "l"
 
 Use the full default config to see every available action.
 
+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.
+
 ## Indexed jumps
 
 Indexed keybindings let you jump directly to visible positions.
@@ -109,6 +121,8 @@ command = "lazygit"
 
 `type = "shell"` runs detached in the background.
 
+Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
+
 ## Theme
 
 Choose a built-in theme:
@@ -161,31 +175,62 @@ accent = "cyan"
 
 `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 `show_agent_labels_on_pane_borders = true` if you want detected agent labels in split pane borders when no manual pane label is set.
 
 ## Notifications
 
-Herdr can show toast notifications when agents finish or need input.
+Herdr can show popup notifications when agents finish or need input.
 
 ```toml
 [ui.toast]
-delivery = "auto"
+delivery = "off"
 ```
 
-On macOS, Herdr can use system notifications when supported by the foreground client.
+`delivery = "off"` disables popup notifications. This is the default.
+
+`delivery = "herdr"` shows a top-right toast inside the Herdr UI. Click the toast, or bind `keys.open_notification_target`, to focus the target workspace, tab, and pane.
+
+`delivery = "terminal"` asks the outer terminal to show a desktop notification. Herdr sends terminal notification escape sequences for Ghostty, iTerm2, Kitty, and WezTerm. This is useful over SSH because the local terminal owns the notification.
+
+`delivery = "system"` asks the local operating system directly. On macOS, Herdr uses `terminal-notifier` when available, then falls back to `/usr/bin/osascript`. `terminal-notifier` can activate the hosting terminal when you click the notification. On Linux, Herdr uses `notify-send` and requires `DISPLAY` or `WAYLAND_DISPLAY`.
+
+Popup notifications are for background attention. Herdr suppresses popups for the active tab.
 
 ## Sound
 
-Sound is optional and server-owned.
+Sound notifications are enabled by default and are played by the local Herdr client.
 
 ```toml
 [ui.sound]
-enabled = false
+enabled = true
 ```
 
-Keep sound off on shared machines or remote servers unless you explicitly want it.
+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.
+
+Custom sounds must be mp3 files. Relative paths are resolved from the config file's directory.
+
+```toml
+[ui.sound]
+path = "sounds/notification.mp3"
+done_path = "sounds/done.mp3"
+request_path = "sounds/request.mp3"
+```
+
+`path` sets one sound for all sound notifications. `done_path` and `request_path` override only the finished and needs-input sounds.
+
+Per-agent sound overrides accept `default`, `on`, or `off`. Droid is muted by default.
+
+```toml
+[ui.sound.agents]
+droid = "off"
+claude = "on"
+```
 
 ## Scrollback
 
@@ -228,6 +273,7 @@ Leave this off unless you are testing terminal image behavior.
 | `HERDR_SESSION` | Select a named session for CLI commands. |
 | `HERDR_SOCKET_PATH` | Low-level socket path override. |
 | `HERDR_LOG` | Set log filtering, for example `HERDR_LOG=herdr=debug`. |
+| `HERDR_DISABLE_SOUND` | Disable sound playback even when `[ui.sound] enabled = true`. |
 
 ## Logs
 
diff --git a/website/src/content/docs/integrations.mdx b/website/src/content/docs/integrations.mdx
index 01e72e16..8303d142 100644
--- a/website/src/content/docs/integrations.mdx
+++ b/website/src/content/docs/integrations.mdx
@@ -53,7 +53,7 @@ Herdr writes the bundled extension to:
 ~/.pi/agent/extensions/herdr-agent-state.ts
 ```
 
-If `PI_CODING_AGENT_DIR` is set, Herdr writes to that agent directory instead.
+If `PI_CODING_AGENT_DIR` is set, Herdr writes to `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts` instead. The extensions directory must already exist. Uninstall removes only that extension file.
 
 ## Claude Code
 
@@ -65,6 +65,8 @@ herdr integration install claude
 
 The hook reports agent state to the local Herdr socket when Claude Code exposes hook events.
 
+Herdr uses `~/.claude` by default, or `CLAUDE_CONFIG_DIR` when set. The Claude 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.
+
 ## Codex
 
 Install the Codex hook:
@@ -75,6 +77,8 @@ herdr integration install codex
 
 Codex state is reported through the same local socket API used by other integrations.
 
+Herdr uses `~/.codex` by default, or `CODEX_HOME` when set. The Codex config directory must already exist. Install writes `herdr-agent-state.sh`, updates `hooks.json`, and ensures `[features] hooks = true` in `config.toml`. It also removes the deprecated top-level `codex_hooks` flag when present. Uninstall removes Herdr entries from `hooks.json` and deletes the hook script, but leaves `config.toml` unchanged.
+
 ## OpenCode
 
 Install the OpenCode plugin:
@@ -83,6 +87,8 @@ Install the OpenCode plugin:
 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.
 
 ## Hermes Agent
@@ -93,7 +99,7 @@ Install the Hermes Agent plugin:
 herdr integration install hermes
 ```
 
-Herdr writes `~/.hermes/plugins/herdr-agent-state/` and enables `herdr-agent-state` in `~/.hermes/config.yaml`. Restart Hermes after installing so the plugin loads.
+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.
 
diff --git a/website/src/content/docs/persistence-remote.mdx b/website/src/content/docs/persistence-remote.mdx
index 2c157b4e..e943fd4c 100644
--- a/website/src/content/docs/persistence-remote.mdx
+++ b/website/src/content/docs/persistence-remote.mdx
@@ -80,6 +80,16 @@ Then attach with:
 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.
+
+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`.
+
+For local builds or custom binaries, set `HERDR_REMOTE_BINARY` to a local file path before running remote attach.
+
+```bash
+HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox
+```
+
 ## Remote named sessions
 
 Use `--session` with `--remote` to attach to a named session on the remote host: