docs: update website

10 files changed, 236 insertions, 192 deletions

diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
index fc4f0589..af7fa7bf 100644
--- a/docs/next/website/src/content/docs/agent-skill.mdx
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -7,6 +7,8 @@ Herdr ships a reusable agent skill file at [`SKILL.md`](https://github.com/ogulc
 
 Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control Herdr from inside a Herdr pane.
 
+Herdr also serves a separate guide at [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md) for a different job: an agent helping a human learn, set up, or troubleshoot Herdr. The skill is for an agent operating Herdr; the guide is for an agent teaching a human.
+
 ## What the skill does
 
 The skill tells an agent to use the `herdr` CLI when `HERDR_ENV=1` is set. That means the agent is running inside a Herdr-managed pane and can safely talk to the local Herdr socket.
diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx
index 49f64881..ae45d26b 100644
--- a/docs/next/website/src/content/docs/agents.mdx
+++ b/docs/next/website/src/content/docs/agents.mdx
@@ -85,34 +85,14 @@ This is the main Herdr workflow: start several agents, let them work in parallel
 
 ## Direct integrations
 
-Install integrations for agents that expose hooks or plugins:
+Install the integration for each agent you use; it gives Herdr hook or plugin reports instead of screen detection alone:
 
 ```bash
-herdr integration install pi
-herdr integration install omp
 herdr integration install claude
-herdr integration install codex
-herdr integration install copilot
-herdr integration install cursor
-herdr integration install droid
-herdr integration install kimi
-herdr integration install opencode
-herdr integration install kilo
-herdr integration install hermes
-herdr integration install qodercli
-```
-
-Check installed integration versions:
-
-```bash
 herdr integration status
 ```
 
-Show only outdated integrations:
-
-```bash
-herdr integration status --outdated-only
-```
+Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list.
 
 ## Custom agent labels
 
diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx
index 3c3d7849..2ac32cc9 100644
--- a/docs/next/website/src/content/docs/concepts.mdx
+++ b/docs/next/website/src/content/docs/concepts.mdx
@@ -23,6 +23,17 @@ A pane is a real terminal. Herdr renders the terminal output, sends input back t
 
 Panes can be split right or down. They can be renamed manually, read from the CLI, sent input, and closed.
 
+## Mouse UI
+
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents. You can drag split borders, select text, and use right-click menus. Everything below is also reachable by mouse; keyboard bindings are an optional layer.
+
+If you prefer keyboard-only control, or you want Herdr to stop capturing mouse input, disable mouse capture:
+
+```toml
+[ui]
+mouse_capture = false
+```
+
 ## Agent
 
 An agent is a process Herdr recognizes inside a pane. Herdr detects agents from foreground processes, screen manifests, and optional integrations.
@@ -71,15 +82,4 @@ Herdr has terminal mode, prefix mode, and navigate mode.
 
 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`, then an action key such as `c` for a new tab or `w` for workspace navigation.
-
-## Mouse UI
-
-Herdr is mouse-native. You can click panes, tabs, workspaces, and agents. You can drag split borders, select text, and use right-click menus.
-
-If you prefer keyboard-only control, or you want Herdr to stop capturing mouse input, disable mouse capture:
-
-```toml
-[ui]
-mouse_capture = false
-```
+Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. New to the prefix idea? See [Keyboard](/docs/keyboard/).
diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
index e9fa2d02..c22e0107 100644
--- a/docs/next/website/src/content/docs/configuration.mdx
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -115,6 +115,8 @@ When enabled, `herdr --remote` writes a private temporary SSH config that includ
 
 ## Keybindings
 
+For a guided introduction to the prefix and a vetted prefix-free setup, see [Keyboard](/docs/keyboard/).
+
 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:
diff --git a/docs/next/website/src/content/docs/index.mdx b/docs/next/website/src/content/docs/index.mdx
index eadb3920..68e1d869 100644
--- a/docs/next/website/src/content/docs/index.mdx
+++ b/docs/next/website/src/content/docs/index.mdx
@@ -1,9 +1,9 @@
 ---
 title: Herdr documentation
-description: Terminal-native agent runtime and multiplexer.
+description: Terminal workspace manager for AI coding agents.
 template: splash
 hero:
-  tagline: "One terminal for the whole herd: real panes, persistent sessions, SSH attach, state awareness, and CLI/socket orchestration."
+  tagline: "Install, learn, and configure Herdr. Start on the path that matches you — no multiplexer experience required."
   image:
     file: ../../../public/assets/logo.svg
   actions:
@@ -16,38 +16,34 @@ hero:
 
 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.
+## Pick your path
 
-```bash
-curl -fsSL https://herdr.dev/install.sh | sh
-herdr
-```
+<CardGrid>
+  <Card title="New to terminal multiplexers?">
+    You don't need to learn shortcuts to start. Herdr is mouse-first: click panes, drag borders, split and switch from right-click menus.
 
-On Windows preview beta:
+    [Quick start →](/docs/quick-start/)
+  </Card>
+  <Card title="Coming from tmux or zellij?">
+    You already know the model. The prefix is `ctrl+b`, panes persist, detach and reattach work the way you expect.
 
-```powershell
-powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
-herdr
-```
+    [Concepts →](/docs/concepts/) · [Keybindings →](/docs/configuration/#keybindings)
+  </Card>
+</CardGrid>
 
-## Start here
+## Or let your agent introduce you
 
-<CardGrid>
-  <Card title="Install">
-    Install stable Herdr on Linux/macOS or the Windows preview beta, update it later, and verify the binary.
+Already running an AI coding agent? Let it do the onboarding. Paste this prompt:
 
-    [Install Herdr →](/docs/install/)
-  </Card>
-  <Card title="Quick start">
-    Create your first workspace, run an agent, split panes, and detach safely.
+```text
+Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
+```
 
-    [Start using Herdr →](/docs/quick-start/)
-  </Card>
-  <Card title="Local, SSH, and mobile">
-    Run Herdr locally, inside SSH, from your phone, or through `herdr --remote`.
+The guide teaches your agent Herdr's concepts, setup, configuration, and common fixes, so its answers stay accurate instead of improvised.
 
-    [Pick a workflow →](/docs/how-to-work/)
-  </Card>
+## Core guides
+
+<CardGrid>
   <Card title="Agents">
     See supported agents, detection behavior, integrations, custom labels, and direct attach.
 
diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
index e64e9c7d..1518e362 100644
--- a/docs/next/website/src/content/docs/install.mdx
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -39,54 +39,6 @@ mise use -g herdr
 
 If mise reports `herdr not found in mise tool registry`, update mise and retry. Older mise versions predate the Herdr registry entry; `mise use -g github:ogulcancelik/herdr` works as a temporary fallback.
 
-## Verify
-
-Start Herdr:
-
-```bash
-herdr
-```
-
-If your shell cannot find `herdr`, restart the terminal or check that the install directory is on your PATH.
-
-## Update
-
-Herdr checks for new releases and notifies you in the app. You can update manually:
-
-```bash
-herdr update
-```
-
-`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs are updated through those package managers instead.
-
-On Linux and macOS, Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
-
-```bash
-herdr channel set preview
-```
-
-Switch Linux and macOS direct installs back to stable the same way:
-
-```bash
-herdr channel set stable
-```
-
-For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
-
-Preview builds are GitHub prereleases published from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
-
-Windows beta builds are preview-only for now. `herdr channel set stable` is rejected on Windows until stable Windows releases are available.
-
-By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
-
-To opt into experimental live server handoff for supported running sessions, run:
-
-```bash
-herdr update --handoff
-```
-
-Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then restart that Herdr session when you are ready to use the new server. If a running session still uses the old server, stop it with `herdr server stop` or `herdr session stop <name>`, then run Herdr again.
-
 ## Install with Nix
 
 If you already use Nix, Herdr provides a flake that builds Herdr from source:
@@ -146,6 +98,54 @@ Windows binaries are published only on preview releases while native Windows sup
 | --- | --- |
 | Windows x86_64 beta | `herdr-windows-x86_64.exe` |
 
+## Verify
+
+Start Herdr:
+
+```bash
+herdr
+```
+
+If your shell cannot find `herdr`, restart the terminal or check that the install directory is on your PATH.
+
+## Update
+
+Herdr checks for new releases and notifies you in the app. You can update manually:
+
+```bash
+herdr update
+```
+
+`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs are updated through those package managers instead.
+
+On Linux and macOS, Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
+
+```bash
+herdr channel set preview
+```
+
+Switch Linux and macOS direct installs back to stable the same way:
+
+```bash
+herdr channel set stable
+```
+
+For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
+
+Preview builds are GitHub prereleases published from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
+
+Windows beta builds are preview-only for now. `herdr channel set stable` is rejected on Windows until stable Windows releases are available.
+
+By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
+
+To opt into experimental live server handoff for supported running sessions, run:
+
+```bash
+herdr update --handoff
+```
+
+Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then restart that Herdr session when you are ready to use the new server. If a running session still uses the old server, stop it with `herdr server stop` or `herdr session stop <name>`, then run Herdr again.
+
 ## Requirements
 
 Stable Herdr releases support Linux and macOS. Native Windows builds are preview-only beta releases; see [Windows beta](/docs/windows-beta/) for supported workflows and known limitations.
diff --git a/docs/next/website/src/content/docs/keyboard.mdx b/docs/next/website/src/content/docs/keyboard.mdx
new file mode 100644
index 00000000..07f11362
--- /dev/null
+++ b/docs/next/website/src/content/docs/keyboard.mdx
@@ -0,0 +1,112 @@
+---
+title: Keyboard
+description: What the prefix is, which bindings to learn first, and how to go prefix-free.
+---
+
+:::tip[Coming from tmux or zellij?]
+You already know this model. Jump to the [keybinding reference](/docs/configuration/#keybindings) for the full default keymap and config syntax.
+:::
+
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is an optional layer, not a requirement.
+
+## What the prefix is
+
+A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: `ctrl+c` interrupts, `ctrl+r` searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
+
+The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. One reserved key instead of dozens.
+
+Press `prefix+?` at any time to see every active binding.
+
+## Learn these five first
+
+| Action | Key |
+| --- | --- |
+| New tab | `prefix+c` |
+| Split right / down | `prefix+v` / `prefix+minus` |
+| Move between panes | `prefix+h/j/k/l` |
+| Workspace navigation | `prefix+w` |
+| Detach, leave everything running | `prefix+q` |
+
+These cover most daily movement. Everything else can stay on the mouse.
+
+## The rest, by task
+
+Panes:
+
+| Action | Key |
+| --- | --- |
+| Zoom the focused pane | `prefix+z` |
+| Close pane | `prefix+x` |
+| Swap panes | `prefix+shift+h/j/k/l` |
+| Resize mode | `prefix+r` |
+| Copy mode | `prefix+[` |
+
+Tabs:
+
+| Action | Key |
+| --- | --- |
+| Next / previous tab | `prefix+n` / `prefix+p` |
+| Jump to tab 1–9 | `prefix+1..9` |
+| Rename tab | `prefix+shift+t` |
+| Close tab | `prefix+shift+x` |
+
+Workspaces and session:
+
+| Action | Key |
+| --- | --- |
+| New workspace | `prefix+shift+n` |
+| Rename workspace | `prefix+shift+w` |
+| Close workspace | `prefix+shift+d` |
+| Goto picker | `prefix+g` |
+| Toggle sidebar | `prefix+b` |
+
+The full keymap and the binding syntax live in the [keybinding reference](/docs/configuration/#keybindings).
+
+## Copy mode
+
+Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, and `{`/`}` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. Mouse drag-select copies without entering copy mode at all.
+
+## Change anything
+
+Every binding is configurable, including the prefix itself:
+
+```toml
+[keys]
+prefix = "ctrl+a"
+```
+
+## Going prefix-free
+
+You can bind Herdr actions to direct chords that need no prefix at all. The hard part is knowing which chords are safe, because terminals, shells, and desktop environments already own most of the keyboard.
+
+Any chord works as a binding: `ctrl+j`, `alt+k`, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. `ctrl+j` reaches Herdr fine, but shells and editors treat it as enter. `alt+k` is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
+
+We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is the safe default recommendation; the choice stays yours.
+
+This setup keeps the prefix bindings working and adds direct chords on top:
+
+```toml
+[keys]
+focus_pane_left = ["prefix+h", "ctrl+alt+h"]
+focus_pane_down = ["prefix+j", "ctrl+alt+j"]
+focus_pane_up = ["prefix+k", "ctrl+alt+k"]
+focus_pane_right = ["prefix+l", "ctrl+alt+l"]
+previous_tab = ["prefix+p", "ctrl+alt+["]
+next_tab = ["prefix+n", "ctrl+alt+]"]
+new_tab = ["prefix+c", "ctrl+alt+c"]
+split_vertical = ["prefix+v", "ctrl+alt+d"]
+split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"]
+zoom = ["prefix+z", "ctrl+alt+z"]
+```
+
+A few `ctrl+alt` chords are taken elsewhere. Avoid these:
+
+| Chord | Owned by |
+| --- | --- |
+| `ctrl+alt+arrows` | GNOME workspace switching, Ghostty and Konsole defaults |
+| `ctrl+alt+t` | "Launch terminal" on Ubuntu and Fedora |
+| `ctrl+alt+l` / `ctrl+alt+a` | KDE lock screen / attention window |
+| `ctrl+alt+s` / `ctrl+alt+u` | Konsole |
+| `ctrl+alt+f1..f12` | Linux virtual console switching |
+
+If a direct chord does nothing, your terminal or desktop environment consumed it before Herdr could see it. Rebind either side: free the chord in the terminal's settings, or pick another chord in Herdr.
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index 1f60f964..80cf19d3 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -9,25 +9,7 @@ For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr]
 
 ## Detach and reattach
 
-Start Herdr:
-
-```bash
-herdr
-```
-
-Detach the client with `ctrl+b q`.
-
-Your panes and agents keep running. Reattach by running Herdr again:
-
-```bash
-herdr
-```
-
-If you want to end the session and stop its panes, stop the default server:
-
-```bash
-herdr server stop
-```
+Detach the client with `ctrl+b q`; panes and agents keep running. Reattach by running `herdr` again. Stop the session and its panes with `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/).
 
@@ -55,16 +37,7 @@ herdr session delete side-project --json
 
 ## Remote attach over SSH
 
-Run Herdr on a server and attach from any SSH client:
-
-```bash
-ssh you@server
-herdr
-```
-
-In this mode your shell is remote, Herdr runs on the remote host, and panes keep running there after you detach.
-
-You can also attach through SSH from your local machine:
+There are two remote modes; [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path. Or attach through SSH from your local machine:
 
 ```bash
 herdr --remote workbox
diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx
index b6869add..26eaa9aa 100644
--- a/docs/next/website/src/content/docs/quick-start.mdx
+++ b/docs/next/website/src/content/docs/quick-start.mdx
@@ -3,7 +3,7 @@ title: Quick start
 description: Create your first Herdr workspace and run agents in persistent terminal panes.
 ---
 
-Start Herdr from any project directory:
+If Herdr is not installed yet, see [Install](/docs/install/). Then start Herdr from any project directory:
 
 ```bash
 herdr
@@ -11,27 +11,31 @@ herdr
 
 Herdr launches or attaches to your default background session. You do not manage sockets. If you detach, agents keep running.
 
-For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr](/docs/how-to-work/).
-
 ## Create a workspace
 
-When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Press `prefix+shift+n` to create another workspace.
+When a session has no workspaces, Herdr opens one automatically. 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.
+
+## Use the mouse
+
+Herdr is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
 
-Give each active project its own workspace. This keeps agent state readable in the sidebar.
+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.
+
+If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps.
 
 ## Run an agent
 
-Start your agent in the root pane.
+Start your coding agent in a pane:
 
 ```bash
-pi
+claude
 ```
 
-Herdr detects supported agents automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`.
+Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle` — across every workspace, so you always know which project needs you.
 
 ## Keyboard control
 
-Press `ctrl+b` to enter prefix mode, then press an action key.
+Keyboard control is optional; the mouse covers everything. Press `ctrl+b` to enter prefix mode, then press an action key.
 
 Common actions:
 
@@ -45,48 +49,21 @@ Common actions:
 | New workspace | `prefix+shift+n` |
 | Detach client | `prefix+q` |
 
-After detaching, run `herdr` again to reattach to the same session.
+New to the prefix idea? [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
 
-## Use the mouse
-
-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.
-
-If you configure `ui.right_click_passthrough_modifier`, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps.
-
-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.
+## Detach and come back
 
-## Copy from the keyboard
+Press `prefix+q` or simply close your terminal window. The Herdr server and every agent keep running. Run `herdr` again to reattach to the same session.
 
-Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, and `{`/`}` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying.
-
-## Manage named sessions
-
-Named sessions are separate Herdr server namespaces. Use them when you want fully separate runtime state.
-
-```bash
-herdr session list
-herdr session attach work
-herdr session attach side-project
-herdr session stop work
-herdr session delete side-project
-```
-
-Workspaces are usually enough. Use named sessions when you need isolation between sets of panes, sockets, and persistent state.
-
-## Attach from another machine
-
-Run Herdr where the work lives. If the code and credentials are on a server, either SSH there and run Herdr like a terminal multiplexer:
+To actually end the session and stop its panes:
 
 ```bash
-ssh you@server
-herdr
+herdr server stop
 ```
 
-Or attach from your local terminal through SSH:
-
-```bash
-herdr --remote workbox
-herdr --remote ssh://you@server:2222
-```
+## Where next
 
-For repeat targets, put the host in your SSH config. See [How to work with Herdr](/docs/how-to-work/) for the full model.
+- [Concepts](/docs/concepts/) — the workspace, tab, pane, and agent model in two minutes.
+- [How to work with Herdr](/docs/how-to-work/) — local, SSH, phone, and `herdr --remote` workflows.
+- [Agents](/docs/agents/) — supported agents, detection, and integrations that improve state accuracy.
+- [Configuration](/docs/configuration/) — keybindings, themes, notifications, and everything else.
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index e317caad..6e627d67 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -5,6 +5,17 @@ description: Understand what Herdr keeps live, restores after restart, replays f
 
 Herdr has several state paths. They solve different problems.
 
+## 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 |
+
+The sections below explain each path.
+
 ## Live persistence
 
 Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
@@ -91,12 +102,3 @@ 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, mise, 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 |