docs: stage website docs for next release

11 files changed, 1468 insertions, 0 deletions

diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
new file mode 100644
index 00000000..65327c33
--- /dev/null
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -0,0 +1,103 @@
+---
+title: Agent skill
+description: A concise guide for coding agents running inside Herdr.
+---
+
+This page teaches coding agents how to use Herdr while they are running inside a Herdr pane.
+
+Use Herdr to organize parallel work instead of stacking everything in one terminal.
+
+## Core model
+
+Herdr has four levels:
+
+| Level | Meaning |
+| --- | --- |
+| Workspace | A project or task context. |
+| Tab | A view inside a workspace. |
+| Pane | A terminal area inside a tab. |
+| Agent | A detected coding agent running in a pane. |
+
+Use workspace and tab actions for layout. Use pane actions for commands and output.
+
+## Read the current layout
+
+```bash
+herdr pane list
+```
+
+Use the pane IDs returned by Herdr for later commands.
+
+## Create a helper pane
+
+Split a pane and run a command:
+
+```bash
+herdr pane split 1-1 --direction right
+herdr pane run 1-2 "just test"
+```
+
+Prefer `pane run` over sending raw keys when you want to submit a full command line.
+
+## Read output
+
+```bash
+herdr pane read 1-2 --source recent --lines 80
+```
+
+Use `recent-unwrapped` when reading logs or matching long lines.
+
+```bash
+herdr pane read 1-2 --source recent-unwrapped --lines 120
+```
+
+## Wait for agents
+
+Wait for another agent to finish or become blocked:
+
+```bash
+herdr wait agent-status 1-3 --status done
+herdr wait agent-status 1-3 --status blocked
+```
+
+Use agent waits for recognized coding agents. Use normal output matching for ordinary commands, servers, and tests.
+
+## Preserve focus
+
+Do not steal visible focus unless the user asked for it. Create panes, submit commands, and read output without changing the user’s active view when possible.
+
+## Use clear pane aliases
+
+When your tool supports aliases, use names like `server`, `tests`, `reviewer`, or `docs`. This makes later pane operations easier to audit.
+
+## Good patterns
+
+Run long work in a separate pane:
+
+```bash
+herdr pane split 1-1 --direction right
+herdr pane run 1-2 "just check"
+```
+
+Watch a server until it is ready:
+
+```bash
+herdr pane read 1-2 --source recent-unwrapped --lines 80
+```
+
+Ask a reviewer agent to inspect a change:
+
+```bash
+herdr pane split 1-1 --direction right
+herdr pane run 1-2 "pi --model <review-model>"
+```
+
+## Avoid these patterns
+
+Do not pile every command into the current pane.
+
+Do not use raw key injection for command submission when `pane run` is available.
+
+Do not wait for `agent-status` on a normal process that is not a coding agent.
+
+Do not change implementation direction without telling the user.
diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx
new file mode 100644
index 00000000..e3d2bc0c
--- /dev/null
+++ b/docs/next/website/src/content/docs/agents.mdx
@@ -0,0 +1,129 @@
+---
+title: Agents
+description: See what Herdr can detect, how agent state works, and how integrations improve it.
+---
+
+Herdr is useful because it knows when agents are working, blocked, done, or idle. You can scan the sidebar instead of checking every pane manually.
+
+## Supported agents
+
+Automatic detection works out of the box for common coding agents.
+
+| Agent | Idle / done | Working | Blocked |
+| --- | --- | --- | --- |
+| Pi | yes | yes | partial |
+| Claude Code | yes | yes | yes |
+| Codex | yes | yes | yes |
+| Droid | yes | yes | yes |
+| Amp | yes | yes | yes |
+| OpenCode | yes | yes | yes |
+| Grok CLI | yes | yes | yes |
+| Hermes Agent | yes | yes | yes |
+| GitHub Copilot CLI | yes | yes | yes |
+
+Detected but less thoroughly tested: Gemini CLI, Cursor Agent, Cline, and Kimi.
+
+Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API.
+
+## How detection works
+
+Herdr combines three signals:
+
+1. foreground process detection
+2. terminal output heuristics
+3. integration state reports
+
+Process detection tells Herdr which pane owns an agent. Heuristics infer state when no hook is available. Integrations provide the most precise semantic state.
+
+## State rollups
+
+The sidebar rolls state upward.
+
+A blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it.
+
+This lets you scan many projects quickly.
+
+## Direct integrations
+
+Install integrations for agents that expose hooks or plugins:
+
+```bash
+herdr integration install pi
+herdr integration install claude
+herdr integration install codex
+herdr integration install opencode
+herdr integration install hermes
+```
+
+Check installed integration versions:
+
+```bash
+herdr integration status
+```
+
+Show only outdated integrations:
+
+```bash
+herdr integration status --outdated-only
+```
+
+## Custom agent labels
+
+You can rename an agent target for display:
+
+```bash
+herdr agent rename 1-1 reviewer
+herdr agent rename reviewer --clear
+```
+
+Targets accept terminal IDs, unique agent names, detected or reported agent labels, and legacy pane IDs.
+
+## Custom status labels
+
+Integrations can report a visual status label without changing semantic state.
+
+```bash
+herdr pane report-agent 1-1 \
+  --source custom:indexer \
+  --agent docs-bot \
+  --state working \
+  --custom-status indexing
+```
+
+`state` controls waits, notifications, and rollups. `custom-status` is only display text.
+
+## Start agents from the CLI
+
+Use `herdr agent ...` commands when you want a terminal to be treated as an agent target. Agent targets show up in `agent list`, can be read or sent input by agent name, can be waited on by agent state, and can be directly attached.
+
+Spawn an agent into Herdr from a script:
+
+```bash
+herdr agent start reviewer --cwd ~/project --split right -- pi
+```
+
+You can place that agent in a specific workspace or tab:
+
+```bash
+herdr agent start docs --workspace 1 --tab 1-1 -- claude
+```
+
+Use `herdr pane ...` commands for ordinary terminals, servers, tests, shells, and low-level terminal input. For example, use `pane split` and `pane run` for `cargo test`, not `agent start`, unless that terminal is intentionally being treated as an agent target.
+
+## Attach directly to an agent
+
+Attach your current terminal to one agent terminal instead of the full Herdr UI:
+
+```bash
+herdr agent attach reviewer
+```
+
+Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.
+
+Use `--takeover` if another direct attach client already owns input:
+
+```bash
+herdr agent attach reviewer --takeover
+```
+
+Use `herdr terminal attach <terminal_id>` when you want the same direct attach behavior for a non-agent terminal.
diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx
new file mode 100644
index 00000000..57f495c1
--- /dev/null
+++ b/docs/next/website/src/content/docs/cli-reference.mdx
@@ -0,0 +1,192 @@
+---
+title: CLI reference
+description: Herdr commands for sessions, workspaces, tabs, panes, agents, waits, integrations, and status.
+---
+
+Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents.
+
+Most commands print JSON responses. Use them from scripts when you want deterministic automation.
+
+## Launch and status
+
+```bash
+herdr                         # launch or attach to the default session
+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 --version               # print version
+```
+
+Status commands:
+
+```bash
+herdr status
+herdr status server
+herdr status client
+```
+
+## Server
+
+```bash
+herdr server stop
+herdr server reload-config
+```
+
+`reload-config` applies reloadable settings without restarting panes.
+
+## Sessions
+
+```bash
+herdr session list [--json]
+herdr session attach <name>
+herdr session stop <name> [--json]
+herdr session delete <name> [--json]
+```
+
+Use `default` as the session name when you need to stop the default session explicitly.
+
+## Workspaces
+
+```bash
+herdr workspace list
+herdr workspace create [--cwd PATH] [--label TEXT] [--focus] [--no-focus]
+herdr workspace get <workspace_id>
+herdr workspace focus <workspace_id>
+herdr workspace rename <workspace_id> <label>
+herdr workspace close <workspace_id>
+```
+
+Create a workspace without stealing focus:
+
+```bash
+herdr workspace create --cwd ~/project --label api --no-focus
+```
+
+## Tabs
+
+```bash
+herdr tab list [--workspace <workspace_id>]
+herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--focus] [--no-focus]
+herdr tab get <tab_id>
+herdr tab focus <tab_id>
+herdr tab rename <tab_id> <label>
+herdr tab close <tab_id>
+```
+
+## Panes
+
+```bash
+herdr pane list [--workspace <workspace_id>]
+herdr pane get <pane_id>
+herdr pane rename <pane_id> <label>|--clear
+herdr pane split <pane_id> --direction right|down [--cwd PATH] [--focus] [--no-focus]
+herdr pane close <pane_id>
+```
+
+Read output:
+
+```bash
+herdr pane read <pane_id> [--source visible|recent|recent-unwrapped] [--lines N]
+herdr pane read <pane_id> --source visible --ansi
+herdr pane read <pane_id> --source recent-unwrapped --lines 120
+```
+
+Send input:
+
+```bash
+herdr pane send-text <pane_id> <text>
+herdr pane send-keys <pane_id> <key> [key ...]
+herdr pane run <pane_id> <command>
+```
+
+`pane run` submits text plus Enter atomically. Prefer it over `send-text` plus `send-keys Enter` for commands.
+
+Report agent state from custom hooks:
+
+```bash
+herdr pane report-agent <pane_id> \
+  --source ID \
+  --agent LABEL \
+  --state idle|working|blocked|unknown \
+  [--message TEXT] \
+  [--custom-status TEXT] \
+  [--seq N]
+```
+
+## Agents
+
+```bash
+herdr agent list
+herdr agent get <target>
+herdr agent read <target> [--source visible|recent|recent-unwrapped] [--lines N] [--format text|ansi] [--ansi]
+herdr agent send <target> <text>
+herdr agent rename <target> <name>|--clear
+herdr agent focus <target>
+herdr agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
+herdr agent attach <target> [--takeover]
+herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--focus|--no-focus] -- <argv...>
+```
+
+Agent targets can be terminal IDs, unique agent names, detected or reported agent labels, or legacy pane IDs. Names and labels are agent identities. Terminal IDs and legacy pane IDs are low-level escape hatches.
+
+`agent read` reads the resolved terminal stream. `agent send` writes literal text to that stream. `agent get`, `agent focus`, `agent wait`, and `agent attach` require the resolved terminal to have agent identity. `agent rename` can assign that identity.
+
+Use `pane send-text`, `pane send-keys`, `pane run`, and `terminal attach` for ordinary terminals, servers, tests, shells, or low-level terminal control. Use `pane run` when you want to submit a command with Enter.
+
+## Direct terminal attach
+
+```bash
+herdr terminal attach <terminal_id> [--takeover]
+```
+
+Detach from direct attach with `ctrl+b q`. Send literal `ctrl+b` with `ctrl+b ctrl+b`.
+
+## Waits
+
+Wait for output in a pane:
+
+```bash
+herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
+```
+
+Wait for pane agent state:
+
+```bash
+herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
+```
+
+Use `wait output` for normal commands and servers. Use `wait agent-status` for coding agents.
+
+## Integrations
+
+```bash
+herdr integration install pi
+herdr integration install claude
+herdr integration install codex
+herdr integration install opencode
+herdr integration install hermes
+herdr integration uninstall pi
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall opencode
+herdr integration uninstall hermes
+herdr integration status [--outdated-only]
+```
+
+## Read sources
+
+| Source | Meaning |
+| --- | --- |
+| `visible` | Current rendered screen. Best for UI feedback loops. |
+| `recent` | Recent scrollback with terminal wrapping. |
+| `recent-unwrapped` | Recent scrollback without soft wrapping. Best for logs. |
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | Override the config file path. |
+| `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`. |
diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx
new file mode 100644
index 00000000..a4229123
--- /dev/null
+++ b/docs/next/website/src/content/docs/concepts.mdx
@@ -0,0 +1,85 @@
+---
+title: Concepts
+description: Understand Herdr workspaces, tabs, panes, agents, sessions, and modes.
+---
+
+Herdr is a terminal workspace manager. It keeps real terminal processes running and adds structure around them.
+
+## Workspace
+
+A workspace is the top-level project container. Use one workspace per repo, task, or investigation.
+
+A workspace owns tabs and panes. Its sidebar state rolls up from the agents inside it, so you can see which project needs attention.
+
+## Tab
+
+A tab is a layout inside a workspace. Use tabs to separate views like `agents`, `logs`, `server`, or `review`.
+
+Tabs are addressable from the CLI and socket API.
+
+## Pane
+
+A pane is a real terminal. Herdr renders the terminal output, sends input back to the process, and preserves the pane across client detach.
+
+Panes can be split right or down. They can be renamed manually, read from the CLI, sent input, and closed.
+
+## Agent
+
+An agent is a process Herdr recognizes inside a pane. Herdr detects agents from foreground processes, screen heuristics, and optional integrations.
+
+Agent states are:
+
+| State | Meaning |
+| --- | --- |
+| `blocked` | The agent needs input, approval, or a decision. |
+| `working` | The agent is actively running. |
+| `done` | The agent finished and you have not looked at it yet. |
+| `idle` | The agent is finished or waiting and has been seen. |
+| `unknown` | Herdr cannot confidently classify the state. |
+
+## Session
+
+A session is a persistent Herdr server namespace. The default `herdr` command attaches to the default session.
+
+Named sessions are separate runtime namespaces:
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+```
+
+Use workspaces first. Use named sessions when you need completely separate panes, sockets, and persisted runtime state.
+
+## Client and server
+
+By default, Herdr runs as a background server plus one or more attached clients.
+
+The server owns panes and process state. The client is the terminal UI attached to that server.
+
+Detach the client with `ctrl+b q`. The server and agents continue running.
+
+Stop the server when you are done:
+
+```bash
+herdr server stop
+```
+
+## Modes
+
+Herdr has terminal mode and navigate mode.
+
+Terminal mode sends keys to the focused pane. Navigate mode sends keys to Herdr.
+
+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.
+
+## 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
+```
diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
new file mode 100644
index 00000000..2f639be4
--- /dev/null
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -0,0 +1,238 @@
+---
+title: Configuration
+description: Configure Herdr keybindings, themes, sidebar behavior, notifications, and advanced options.
+---
+
+Herdr works without a config file. Add one when you want custom keys, themes, sidebar settings, notifications, or advanced behavior.
+
+## Config file
+
+Herdr reads config from:
+
+```text
+~/.config/herdr/config.toml
+```
+
+Print the full default config:
+
+```bash
+herdr --default-config
+```
+
+Save it as your config if you want a complete starting point:
+
+```bash
+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.
+
+## Reload config
+
+Reload a running server after editing `config.toml`:
+
+```bash
+herdr server reload-config
+```
+
+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.
+
+## Keybindings
+
+Herdr has a prefix mode similar to tmux. The default prefix is `ctrl+b`.
+
+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"
+```
+
+Optional actions are unset by default. Bind them when you want direct shortcuts:
+
+```toml
+[keys]
+detach = "q"
+reload_config = "R"
+open_notification_target = "o"
+previous_workspace = "H"
+next_workspace = "L"
+previous_tab = "J"
+next_tab = "K"
+rename_pane = "p"
+edit_scrollback = "e"
+focus_pane_left = "h"
+focus_pane_down = "j"
+focus_pane_up = "k"
+focus_pane_right = "l"
+```
+
+Use the full default config to see every available action.
+
+## Indexed jumps
+
+Indexed keybindings let you jump directly to visible positions.
+
+```toml
+[keys.indexed]
+workspaces = "ctrl+shift"
+tabs = "ctrl"
+agents = "alt"
+```
+
+These expand over number keys 1 through 9. For example, `tabs = "ctrl"` makes `ctrl+1` through `ctrl+9` switch tabs.
+
+## Custom command keybindings
+
+Custom prefix-mode commands can run shell helpers from inside Herdr.
+
+```toml
+[[keys.command]]
+key = "g"
+type = "pane"
+command = "lazygit"
+```
+
+`type = "pane"` opens a temporary pane and closes it when the command exits.
+
+`type = "shell"` runs detached in the background.
+
+## Theme
+
+Choose a built-in theme:
+
+```toml
+[theme]
+name = "catppuccin"
+```
+
+Built-in themes:
+
+`catppuccin`, `catppuccin-latte`, `tokyo-night`, `tokyo-night-day`, `dracula`, `nord`, `gruvbox`, `gruvbox-light`, `one-dark`, `one-light`, `solarized`, `solarized-light`, `kanagawa`, `kanagawa-lotus`, `rose-pine`, `rose-pine-dawn`, `vesper`.
+
+You can override individual colors:
+
+```toml
+[theme.custom]
+panel_bg = "reset"
+accent = "#a6e3a1"
+green = "#a6e3a1"
+blue = "#89b4fa"
+red = "#f38ba8"
+yellow = "#f9e2af"
+```
+
+Color values accept hex, named colors, `rgb(r,g,b)`, or reset aliases like `reset`, `default`, `none`, and `transparent`.
+
+## UI and sidebar
+
+The sidebar is the main Herdr dashboard. It shows workspaces, tabs, panes, and agent state.
+
+Common options:
+
+```toml
+[ui]
+sidebar_width = 32
+mouse_capture = true
+confirm_close = true
+prompt_new_tab_name = true
+show_agent_labels_on_pane_borders = false
+agent_panel_scope = "all"
+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.
+
+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.
+
+```toml
+[ui.toast]
+delivery = "auto"
+```
+
+On macOS, Herdr can use system notifications when supported by the foreground client.
+
+## Sound
+
+Sound is optional and server-owned.
+
+```toml
+[ui.sound]
+enabled = false
+```
+
+Keep sound off on shared machines or remote servers unless you explicitly want it.
+
+## Scrollback
+
+Set the scrollback buffer size for newly created panes:
+
+```toml
+[advanced]
+scrollback_limit_bytes = 10485760
+```
+
+Existing panes keep their current buffer until they are recreated.
+
+## Nested launches
+
+Herdr normally protects you from launching Herdr inside Herdr.
+
+```toml
+[experimental]
+allow_nested = false
+```
+
+Only enable nested launches for testing.
+
+## Kitty graphics
+
+Kitty graphics support is experimental.
+
+```toml
+[experimental]
+kitty_graphics = false
+```
+
+Leave this off unless you are testing terminal image behavior.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HERDR_CONFIG_PATH` | Override the config file path. |
+| `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`. |
+
+## Logs
+
+Logs are useful when diagnosing startup warnings, integration state, or socket API behavior.
+
+Common log files:
+
+```text
+~/.config/herdr/herdr.log
+~/.config/herdr/herdr-client.log
+~/.config/herdr/herdr-server.log
+```
+
+Logs rotate automatically. Include the current log and rotated siblings when reporting issues.
diff --git a/docs/next/website/src/content/docs/index.mdx b/docs/next/website/src/content/docs/index.mdx
new file mode 100644
index 00000000..9cdf9273
--- /dev/null
+++ b/docs/next/website/src/content/docs/index.mdx
@@ -0,0 +1,104 @@
+---
+title: Herdr documentation
+description: Terminal-native agent runtime and multiplexer.
+template: splash
+hero:
+  tagline: "One terminal for the whole herd: real panes, persistent sessions, SSH attach, state awareness, and CLI/socket orchestration."
+  image:
+    file: ../../../public/assets/logo.svg
+  actions:
+    - text: Install Herdr
+      link: /docs/install/
+    - text: Quick start
+      link: /docs/quick-start/
+      variant: secondary
+---
+
+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
+curl -fsSL https://herdr.dev/install.sh | sh
+herdr
+```
+
+## Core runtime
+
+<CardGrid>
+  <Card title="Detach and reattach">
+    Herdr runs panes in a background session server, so agents keep running after the UI client detaches.
+
+    [Use persistence →](/docs/persistence-remote/)
+  </Card>
+  <Card title="Attach over SSH">
+    Run Herdr where the code and credentials live. Attach from any SSH client or use `herdr --remote` from your local terminal.
+
+    [Use remote access →](/docs/persistence-remote/#remote-attach-over-ssh)
+  </Card>
+  <Card title="Real terminal panes">
+    Every pane is a real terminal. Split layouts, click panes, drag borders, select text, and use right-click menus.
+
+    [Learn concepts →](/docs/concepts/)
+  </Card>
+  <Card title="Runtime API">
+    See agent status in the sidebar and drive workspaces, tabs, panes, waits, and output reads through the CLI or socket API.
+
+    [Read the API guide →](/docs/socket-api/)
+  </Card>
+</CardGrid>
+
+## Start here
+
+<CardGrid>
+  <Card title="Install">
+    Install Herdr on Linux or macOS, update it later, and verify the binary.
+
+    [Install Herdr →](/docs/install/)
+  </Card>
+  <Card title="Quick start">
+    Create your first workspace, run agents in panes, split the layout, and detach safely.
+
+    [Start using Herdr →](/docs/quick-start/)
+  </Card>
+  <Card title="Concepts">
+    Understand workspaces, tabs, panes, agents, sessions, modes, and state rollups.
+
+    [Learn the model →](/docs/concepts/)
+  </Card>
+</CardGrid>
+
+## Guides and reference
+
+<CardGrid>
+  <Card title="Agents">
+    See supported agents, detection behavior, integrations, custom labels, and direct attach.
+
+    [Understand agents →](/docs/agents/)
+  </Card>
+  <Card title="Configuration">
+    Configure keybindings, themes, sidebar behavior, notifications, scrollback, and advanced options.
+
+    [Configure Herdr →](/docs/configuration/)
+  </Card>
+  <Card title="Integrations">
+    Install agent integrations for Pi, Claude Code, Codex, and OpenCode.
+
+    [Set up integrations →](/docs/integrations/)
+  </Card>
+  <Card title="CLI reference">
+    Use every Herdr command for sessions, workspaces, tabs, panes, agents, waits, and integrations.
+
+    [Browse commands →](/docs/cli-reference/)
+  </Card>
+  <Card title="Socket API">
+    Control Herdr from scripts, tools, and agents through the local socket API.
+
+    [Read the API guide →](/docs/socket-api/)
+  </Card>
+  <Card title="Agent skill">
+    Teach an agent running inside Herdr how to create panes, read output, and wait for neighboring agents.
+
+    [Use the skill →](/docs/agent-skill/)
+  </Card>
+</CardGrid>
diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
new file mode 100644
index 00000000..dda2dc27
--- /dev/null
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -0,0 +1,58 @@
+---
+title: Install Herdr
+description: Install, update, and verify Herdr on Linux and macOS.
+---
+
+Herdr ships as a single binary for Linux and macOS.
+
+## Install
+
+Run the installer:
+
+```bash
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+The installer downloads the right release binary for your platform and places it on your PATH.
+
+## 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
+```
+
+## Download manually
+
+You can also download a binary from [GitHub releases](https://github.com/ogulcancelik/herdr/releases).
+
+Choose the asset that matches your system:
+
+| System | Asset |
+| --- | --- |
+| Linux x86_64 | `herdr-linux-x86_64` |
+| Linux aarch64 | `herdr-linux-aarch64` |
+| macOS Intel | `herdr-macos-x86_64` |
+| macOS Apple silicon | `herdr-macos-aarch64` |
+
+Make it executable and move it somewhere on your PATH.
+
+```bash
+chmod +x herdr-linux-x86_64
+mv herdr-linux-x86_64 ~/.local/bin/herdr
+```
+
+## Requirements
+
+Herdr supports Linux and macOS. Native Windows support is not available yet; use Herdr inside WSL for now.
diff --git a/docs/next/website/src/content/docs/integrations.mdx b/docs/next/website/src/content/docs/integrations.mdx
new file mode 100644
index 00000000..01e72e16
--- /dev/null
+++ b/docs/next/website/src/content/docs/integrations.mdx
@@ -0,0 +1,130 @@
+---
+title: Integrations
+description: Install Herdr integrations for Pi, Claude Code, Codex, OpenCode, and Hermes Agent.
+---
+
+Herdr detects supported agents automatically. Integrations make that detection more precise by reporting semantic state directly to Herdr.
+
+Use integrations when you want reliable `working`, `blocked`, `idle`, and `done` state from agent hooks or plugins.
+
+## Install integrations
+
+```bash
+herdr integration install pi
+herdr integration install claude
+herdr integration install codex
+herdr integration install opencode
+herdr integration install hermes
+```
+
+## Uninstall integrations
+
+```bash
+herdr integration uninstall pi
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall opencode
+herdr integration uninstall hermes
+```
+
+## How Herdr uses integrations
+
+Herdr combines three signals:
+
+| Signal | Purpose |
+| --- | --- |
+| Process detection | Identifies which pane owns which running process. |
+| Agent integration events | Reports semantic state such as `working` or `blocked`. |
+| Screen heuristics | Fills gaps when hooks are unavailable or incomplete. |
+
+Integrations enrich state reporting. They do not replace process detection.
+
+## Pi
+
+Install the Pi integration:
+
+```bash
+herdr integration install pi
+```
+
+Herdr writes the bundled extension to:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+If `PI_CODING_AGENT_DIR` is set, Herdr writes to that agent directory instead.
+
+## Claude Code
+
+Install the Claude Code hook:
+
+```bash
+herdr integration install claude
+```
+
+The hook reports agent state to the local Herdr socket when Claude Code exposes hook events.
+
+## Codex
+
+Install the Codex hook:
+
+```bash
+herdr integration install codex
+```
+
+Codex state is reported through the same local socket API used by other integrations.
+
+## OpenCode
+
+Install the OpenCode plugin:
+
+```bash
+herdr integration install opencode
+```
+
+The plugin reports semantic state while OpenCode runs inside a Herdr pane.
+
+## Hermes Agent
+
+Install the Hermes Agent plugin:
+
+```bash
+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.
+
+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.
+
+## Custom status labels
+
+Integrations can report a short visual label without changing the semantic state.
+
+For example, an agent can remain semantically `working` while showing `indexing` in the UI.
+
+```bash
+herdr pane report-agent 1-1 \
+  --source custom:docs \
+  --agent docs-bot \
+  --state working \
+  --custom-status indexing
+```
+
+Custom status is visual-only. Waits, notifications, and workspace rollups still use the semantic state.
+
+## Debug integration state
+
+List known agents:
+
+```bash
+herdr agent list
+```
+
+Read a pane when you need to verify what Herdr can see:
+
+```bash
+herdr pane read 1-1 --source recent --lines 50
+```
+
+If integration state looks wrong, first confirm the agent is running inside Herdr and that the relevant hook or plugin was installed for the same user account.
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
new file mode 100644
index 00000000..2c157b4e
--- /dev/null
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -0,0 +1,125 @@
+---
+title: Persistence and remote access
+description: Detach from Herdr, reattach later, use named sessions, and connect over SSH.
+---
+
+Herdr keeps panes running in a background server. Your terminal client can detach and reconnect later.
+
+## 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
+```
+
+Stop the default server when you want to end the session:
+
+```bash
+herdr server stop
+```
+
+## Named sessions
+
+Use named sessions when you want independent Herdr servers.
+
+```bash
+herdr session list
+herdr session attach work
+herdr session attach side-project
+herdr session stop work
+herdr session delete side-project
+```
+
+A named session has its own panes, tabs, workspaces, sockets, and runtime state. It still shares the same global config file.
+
+Use `--json` for scripts:
+
+```bash
+herdr session list --json
+herdr session stop work --json
+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
+```
+
+You can also attach through SSH from your local machine:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+For repeat targets, use your SSH config:
+
+```text
+Host workbox
+  HostName server.example.com
+  User you
+  Port 2222
+```
+
+Then attach with:
+
+```bash
+herdr --remote workbox
+```
+
+## Remote named sessions
+
+Use `--session` with `--remote` to attach to a named session on the remote host:
+
+```bash
+herdr --remote workbox --session agents
+```
+
+## Direct terminal attach
+
+Full Herdr attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.
+
+Attach by agent target:
+
+```bash
+herdr agent attach reviewer
+```
+
+Attach by terminal ID:
+
+```bash
+herdr terminal attach term_abc123
+```
+
+Direct attach streams the current rendered terminal state, then live ANSI frames. Input goes straight to that terminal.
+
+Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`.
+
+Only one writable direct attach client owns input and resize for a terminal. Use `--takeover` to replace an existing owner:
+
+```bash
+herdr terminal attach term_abc123 --takeover
+```
+
+## Single-process escape hatch
+
+Use `--no-session` to run Herdr without the background server/client split:
+
+```bash
+herdr --no-session
+```
+
+This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.
diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx
new file mode 100644
index 00000000..08d815f3
--- /dev/null
+++ b/docs/next/website/src/content/docs/quick-start.mdx
@@ -0,0 +1,80 @@
+---
+title: Quick start
+description: Create your first Herdr workspace and run agents in persistent terminal panes.
+---
+
+Start Herdr from any project directory:
+
+```bash
+herdr
+```
+
+Herdr launches or attaches to your default background session. If you detach, agents keep running.
+
+## Create a workspace
+
+Press `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.
+
+## Run an agent
+
+Start your agent in the root pane.
+
+```bash
+pi
+```
+
+Herdr detects supported agents automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`.
+
+## Navigate
+
+Press `ctrl+b` to enter navigate mode.
+
+Common actions:
+
+| Action | Key |
+| --- | --- |
+| Split right | `v` |
+| Split down | `-` |
+| New tab | `c` |
+| New workspace | `n` |
+| Detach client | `q` |
+
+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.
+
+## 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
+
+Start Herdr on a server, detach, and come back over SSH later.
+
+```bash
+ssh you@server
+herdr
+```
+
+You can also attach through SSH from your local terminal:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+For repeat targets, put the host in your SSH config.
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
new file mode 100644
index 00000000..c4de1b3d
--- /dev/null
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -0,0 +1,224 @@
+---
+title: Socket API
+description: Control a running Herdr server from scripts, tools, and coding agents.
+---
+
+Herdr exposes a local socket API for scripts and agents that need to inspect or control a running session.
+
+Most automation should start with the CLI wrappers. Use the raw socket API only when you need direct request/response control or long-lived event subscriptions.
+
+## Choose an integration layer
+
+| Layer | Use it for |
+| --- | --- |
+| Agent skill | Teaching a coding agent how to use Herdr from inside a pane. |
+| CLI wrappers | Shell scripts, simple orchestration, and human debugging. |
+| Raw socket API | Custom tools, protocol clients, and event subscribers. |
+
+The layers share the same control surface.
+
+## What you can control
+
+The socket API can:
+
+- create, list, focus, rename, and close workspaces
+- create, list, focus, rename, and close tabs
+- list, inspect, split, rename, read, close, and send input to panes
+- list, inspect, read, send to, rename, focus, start, and attach agents through CLI helpers
+- report custom agent state from hooks and plugins
+- subscribe to events and wait for output or state changes
+- install and uninstall built-in integrations
+- stop the server and reload config
+
+## CLI examples
+
+Create a workspace:
+
+```bash
+herdr workspace create --cwd ~/project --label api
+```
+
+Create a tab:
+
+```bash
+herdr tab create --label logs
+```
+
+Split a pane and run a command:
+
+```bash
+herdr pane split 1-1 --direction right
+herdr pane run 1-2 "npm test"
+```
+
+Wait for an agent:
+
+```bash
+herdr wait agent-status 1-1 --status done
+```
+
+Read pane output:
+
+```bash
+herdr pane read 1-2 --source recent --lines 50
+```
+
+## Raw methods
+
+Raw socket method names use dot notation:
+
+| Area | Methods |
+| --- | --- |
+| Server | `ping`, `server.stop`, `server.reload_config` |
+| Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` |
+| 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` |
+| 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` |
+
+Some CLI commands are conveniences around these methods. For example, `herdr agent wait` resolves an agent target and then subscribes to pane agent state events.
+
+## Socket transport
+
+Herdr uses newline-delimited JSON over a Unix domain socket.
+
+Send one request per line:
+
+```json
+{"id":"req_1","method":"ping","params":{}}
+```
+
+A successful response includes the same `id`:
+
+```json
+{"id":"req_1","result":{"type":"pong"}}
+```
+
+Event subscriptions keep the connection open after the initial response.
+
+## Socket paths
+
+The default socket lives under your Herdr config directory.
+
+Named sessions have separate sockets:
+
+```text
+~/.config/herdr/herdr.sock
+~/.config/herdr/sessions/<name>/herdr.sock
+```
+
+Resolution order:
+
+1. explicit CLI `--session <name>`
+2. `HERDR_SOCKET_PATH`
+3. `HERDR_SESSION=<name>`
+4. default session socket
+
+Use `HERDR_SOCKET_PATH` only for low-level overrides.
+
+## Agent state reporting
+
+Integrations report agent state with `pane.report_agent`.
+
+```json
+{
+  "id": "req_1",
+  "method": "pane.report_agent",
+  "params": {
+    "pane_id": "1-1",
+    "source": "custom:docs",
+    "agent": "docs-bot",
+    "state": "working",
+    "message": "building docs",
+    "custom_status": "indexing"
+  }
+}
+```
+
+`state` is semantic. It affects waits, notifications, and rollups.
+
+`custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior.
+
+## Event subscriptions
+
+Subscribe to events when you need a long-lived stream:
+
+```json
+{
+  "id": "sub_1",
+  "method": "events.subscribe",
+  "params": {
+    "subscriptions": [
+      { "type": "pane.agent_status_changed", "pane_id": "1-1", "agent_status": "blocked" }
+    ]
+  }
+}
+```
+
+The first response acknowledges the subscription. Later lines are pushed events.
+
+Use `events.wait` when you want one matching event and then a response.
+
+## Reading panes
+
+Use `pane.read` through the CLI unless you are writing a protocol client.
+
+```bash
+herdr pane read 1-1 --source visible --lines 80
+herdr pane read 1-1 --source recent --lines 120
+herdr pane read 1-1 --source recent-unwrapped --lines 120
+```
+
+`recent-unwrapped` is useful for logs because it ignores soft wrapping.
+
+## Waiting for state
+
+Use waits to coordinate agents and scripts.
+
+```bash
+herdr wait agent-status 1-1 --status done
+herdr wait agent-status 1-1 --status blocked
+```
+
+Agent waits observe semantic state, not arbitrary command completion.
+
+## Response shapes
+
+Successful responses look like this:
+
+```json
+{
+  "id": "req_1",
+  "result": {
+    "type": "pane_info",
+    "pane": {
+      "pane_id": "1-1",
+      "terminal_id": "term_abc123",
+      "workspace_id": "1",
+      "tab_id": "1-1",
+      "focused": true,
+      "agent_status": "working",
+      "revision": 42
+    }
+  }
+}
+```
+
+Errors look like this:
+
+```json
+{
+  "id": "req_1",
+  "error": {
+    "code": "not_found",
+    "message": "pane not found"
+  }
+}
+```
+
+## Protocol stability
+
+Herdr has a protocol version for client/server compatibility. Protocol changes are reviewed with release compatibility in mind.
+
+Check the server protocol with `ping` or `herdr status` before depending on new behavior. Handle unknown fields gracefully.