docs: move public references to website docs

1 files changed, 0 insertions, 1112 deletions

diff --git a/docs/next/SOCKET_API.md b/docs/next/SOCKET_API.md
deleted file mode 100644
index 7ffb276e..00000000
--- a/docs/next/SOCKET_API.md
+++ /dev/null
@@ -1,1112 +0,0 @@
-# herdr socket api
-
-herdr exposes a local unix socket api for scripts, tools, and coding agents that want to control a running herdr instance or subscribe to events.
-
-if you are teaching an agent that is already running inside herdr, start with [`SKILL.md`](./SKILL.md). use this document when you want the direct protocol, or when you want the cli wrapper reference for the commands that sit on top of it.
-
-## choose your integration layer
-
-there are three practical ways to integrate with herdr:
-
-- **agent skill** — [`SKILL.md`](./SKILL.md). best when an agent inside herdr just needs to learn the workflow quickly.
-- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr agent ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration.
-- **raw socket api** — best when you want direct request/response control or long-lived event subscriptions.
-
-these layers are intentionally stacked on top of the same control surface.
-
-important difference: `pane.run` and `wait agent-status` are **cli conveniences**, not raw socket methods.
-
-## transport
-
-- transport: unix domain socket
-- encoding: newline-delimited json
-- request/response: send one json request per line, read one json response per line
-- subscriptions: send `events.subscribe`, receive an ack, then keep the same connection open and continue reading pushed events
-
-named sessions are runtime/socket namespaces, not replacements for herdr workspaces. each named session has its own server sockets and persistent runtime state while config remains global.
-
-socket path resolution order:
-
-1. explicit `herdr --session <name>`:
-   `$XDG_CONFIG_HOME/herdr/sessions/<name>/herdr.sock` or `$HOME/.config/herdr/sessions/<name>/herdr.sock`
-2. `HERDR_SOCKET_PATH`
-3. `HERDR_SESSION=<name>`:
-   `$XDG_CONFIG_HOME/herdr/sessions/<name>/herdr.sock` or `$HOME/.config/herdr/sessions/<name>/herdr.sock`
-4. default session path:
-   `$XDG_CONFIG_HOME/herdr/herdr.sock` or `$HOME/.config/herdr/herdr.sock`
-
-this means `HERDR_SOCKET_PATH` remains an exact low-level socket override, but an explicit cli `--session <name>` still wins when a command runs inside a pane that inherited `HERDR_SOCKET_PATH`.
-
-session names may contain ASCII letters, numbers, `.`, `_`, and `-`. `default` is reserved for the default session. use `herdr session list`, `herdr session attach <name>`, `herdr session stop <name>`, and `herdr session delete <name>` to inspect and manage session namespaces. session commands print human-readable output by default; pass `--json` for machine-readable output. `session delete` refuses running sessions and does not delete the default session.
-
-## request and response envelopes
-
-all socket requests use this envelope:
-
-```json
-{
-  "id": "req_1",
-  "method": "ping",
-  "params": {}
-}
-```
-
-successful responses look like:
-
-```json
-{
-  "id": "req_1",
-  "result": {
-    "type": "pong",
-    "version": "0.1.2",
-    "protocol": 2
-  }
-}
-```
-
-errors look like:
-
-```json
-{
-  "id": "req_1",
-  "error": {
-    "code": "pane_not_found",
-    "message": "pane 1-99 not found"
-  }
-}
-```
-
-## ids and numbering
-
-workspace ids are opaque, stable ids like:
-
-- `w64e95948145ed1`
-- `w64e95948146a82`
-
-pane ids are workspace-scoped and stable across workspace reorder:
-
-- `w64e95948145ed1-1`
-- `w64e95948145ed1-2`
-- `w64e95948146a82-1`
-
-that means:
-
-- workspace id = stable workspace identity
-- pane number = compact pane number within that workspace
-
-workspace ids are durable for the life of the workspace and survive display reordering. pane numbers are still compact public numbers, so if a pane closes, higher pane numbers in that same workspace compact down.
-
-tabs are first-class socket api objects now.
-
-- tab ids look like `w64e95948145ed1:1`, `w64e95948145ed1:2`
-- workspace id = stable workspace identity
-- tab number = tab number within that workspace
-- pane ids still stay workspace-scoped like `w64e95948145ed1-2` rather than becoming `workspace-tab-pane` triples
-
-for backward compatibility, requests also accept the older positional forms like `1`, `1:2`, and `1-2` as shorthand for the current session order. responses use the stable ids.
-
-## core objects
-
-`workspace_info` responses contain objects like:
-
-```json
-{
-  "workspace_id": "w64e95948145ed1",
-  "number": 1,
-  "label": "herdr",
-  "focused": true,
-  "pane_count": 1,
-  "tab_count": 1,
-  "active_tab_id": "w64e95948145ed1:1",
-  "agent_status": "unknown"
-}
-```
-
-`tab_info` responses contain objects like:
-
-```json
-{
-  "tab_id": "w64e95948145ed1:1",
-  "workspace_id": "w64e95948145ed1",
-  "number": 1,
-  "label": "1",
-  "focused": true,
-  "pane_count": 1,
-  "agent_status": "unknown"
-}
-```
-
-`pane_info` responses contain objects like:
-
-```json
-{
-  "pane_id": "w64e95948145ed1-1",
-  "terminal_id": "term_64e95948145ed1",
-  "workspace_id": "w64e95948145ed1",
-  "tab_id": "w64e95948145ed1:1",
-  "focused": true,
-  "cwd": "/home/can/Projects/herdr",
-  "label": "reviewer",
-  "agent": "pi",
-  "agent_status": "working",
-  "custom_status": "indexing",
-  "revision": 0
-}
-```
-
-`terminal_id` is an opaque terminal identity. during the pane-backed transition each pane has one terminal id, but clients should not derive it from the pane id.
-
-`label` is an optional manual pane name set through `pane.rename`.
-
-`agent_info` responses contain a terminal-facing view of a live agent terminal:
-
-```json
-{
-  "terminal_id": "term_64e95948145ed1",
-  "name": "reviewer",
-  "agent": "pi",
-  "agent_status": "working",
-  "workspace_id": "w64e95948145ed1",
-  "tab_id": "w64e95948145ed1:1",
-  "pane_id": "w64e95948145ed1-1",
-  "focused": true,
-  "cwd": "/home/can/Projects/herdr",
-  "revision": 0
-}
-```
-
-`name` is an optional unique agent alias set by `agent.start` or `agent.rename`. it is separate from the pane `label`: `pane.rename` names a terminal/pane for UI purposes, while `agent.rename` declares or changes the agent-facing name and rejects duplicate active agent names.
-
-`agent` is an optional display label string.
-
-- when herdr detects a built-in agent, this is that built-in name like `pi` or `claude`
-- when a hook or plugin reports a custom agent through `pane.report_agent`, this can be any non-empty label like `hermes`
-- when no agent identity is known, it is omitted
-
-`custom_status` on `pane_info` and agent-status events is an optional hook-owned display label. It is present only while hook authority is active. It does not change `agent_status`, `done` semantics, waits, notifications, or workspace/tab rollup priority.
-
-`pane_read` responses contain objects like:
-
-```json
-{
-  "pane_id": "w64e95948145ed1-1",
-  "workspace_id": "w64e95948145ed1",
-  "tab_id": "w64e95948145ed1:1",
-  "source": "recent",
-  "format": "text",
-  "text": "...",
-  "revision": 0,
-  "truncated": false
-}
-```
-
-`agent_status` is the public agent field:
-
-- `idle`
-- `working`
-- `blocked`
-- `done`
-- `unknown`
-
-`done` means the agent has finished, but you have not looked at that finished pane yet.
-
-## methods at a glance
-
-| method | purpose | success result type |
-|---|---|---|
-| `ping` | health check / version | `pong` |
-| `server.stop` | gracefully stop the running background server | `ok` |
-| `workspace.list` | list workspaces | `workspace_list` |
-| `workspace.get` | inspect one workspace | `workspace_info` |
-| `workspace.create` | create a workspace | `workspace_info` |
-| `workspace.focus` | focus a workspace | `workspace_info` |
-| `workspace.rename` | rename a workspace | `workspace_info` |
-| `workspace.close` | close a workspace | `ok` |
-| `tab.list` | list tabs, optionally filtered by workspace | `tab_list` |
-| `tab.get` | inspect one tab | `tab_info` |
-| `tab.create` | create a tab in a workspace | `tab_info` |
-| `tab.focus` | focus a tab | `tab_info` |
-| `tab.rename` | rename a tab | `tab_info` |
-| `tab.close` | close a tab | `ok` |
-| `agent.list` | list terminal-backed agents | `agent_list` |
-| `agent.get` | inspect one agent by terminal id, unique agent name, detected agent label, or pane id | `agent_info` |
-| `agent.read` | read output from one agent terminal | `pane_read` |
-| `agent.send` | send literal text to one agent terminal | `ok` |
-| `agent.rename` | set or clear the unique agent name | `agent_info` |
-| `agent.focus` | show the agent terminal in the TUI | `agent_info` |
-| `agent.start` | start a named agent terminal from argv | `agent_started` |
-| `pane.list` | list panes, optionally filtered by workspace | `pane_list` |
-| `pane.get` | inspect one pane | `pane_info` |
-| `pane.rename` | set or clear a manual pane label | `pane_info` |
-| `pane.read` | read pane output | `pane_read` |
-| `pane.split` | split a pane and create a sibling pane | `pane_info` |
-| `pane.send_text` | send literal text without Enter | `ok` |
-| `pane.send_keys` | send keypresses like `Enter` | `ok` |
-| `pane.send_input` | send literal text plus keypresses in order | `ok` |
-| `pane.report_agent` | report hook-authoritative agent label and state for a pane | `ok` |
-| `pane.clear_agent_authority` | clear hook-authoritative agent state for a pane | `ok` |
-| `pane.release_agent` | release a pane from the reported agent back to shell state | `ok` |
-| `pane.close` | close a pane | `ok` |
-| `pane.wait_for_output` | one-shot blocking wait for text | `output_matched` |
-| `events.subscribe` | start a long-lived subscription stream | `subscription_started` ack |
-
-### `server.stop`
-
-request:
-
-```json
-{
-  "id": "req_stop",
-  "method": "server.stop",
-  "params": {}
-}
-```
-
-returns `ok` and asks the running background server to shut down cleanly.
-
-this is the explicit server-level shutdown path for persistence mode. normal in-app quit actions detach the current client instead of sending this request.
-
-## workspace methods
-
-### `workspace.list`
-
-request:
-
-```json
-{
-  "id": "req_list",
-  "method": "workspace.list",
-  "params": {}
-}
-```
-
-returns `workspace_list` with zero or more workspace objects.
-
-### `workspace.get`
-
-params:
-
-```json
-{
-  "workspace_id": "1"
-}
-```
-
-returns `workspace_info` for one workspace.
-
-### `workspace.create`
-
-params:
-
-```json
-{
-  "cwd": "/home/can/Projects/herdr",
-  "focus": true
-}
-```
-
-notes:
-
-- `cwd` is optional
-- if `cwd` is omitted, herdr uses its current working directory and falls back to `/` if needed
-- `focus` is optional in raw socket requests and defaults to `false`
-- the cli wrapper also defaults to no focus; pass `--focus` to switch to the new workspace
-
-example response:
-
-```json
-{
-  "id": "req_create",
-  "result": {
-    "type": "workspace_info",
-    "workspace": {
-      "workspace_id": "1",
-      "number": 1,
-      "label": "herdr",
-      "focused": true,
-      "pane_count": 1,
-      "tab_count": 1,
-      "active_tab_id": "1:1",
-      "agent_status": "unknown"
-    }
-  }
-}
-```
-
-### `workspace.focus`
-
-params:
-
-```json
-{
-  "workspace_id": "1"
-}
-```
-
-returns the focused workspace as `workspace_info`.
-
-### `workspace.rename`
-
-params:
-
-```json
-{
-  "workspace_id": "1",
-  "label": "api"
-}
-```
-
-returns updated `workspace_info`.
-
-### `workspace.close`
-
-params:
-
-```json
-{
-  "workspace_id": "1"
-}
-```
-
-returns:
-
-```json
-{
-  "id": "req_close",
-  "result": {
-    "type": "ok"
-  }
-}
-```
-
-## tab methods
-
-### `tab.list`
-
-request with no filter:
-
-```json
-{
-  "id": "req_tabs",
-  "method": "tab.list",
-  "params": {}
-}
-```
-
-request filtered to one workspace:
-
-```json
-{
-  "id": "req_tabs_ws",
-  "method": "tab.list",
-  "params": {
-    "workspace_id": "1"
-  }
-}
-```
-
-returns `tab_list`.
-
-### `tab.get`
-
-params:
-
-```json
-{
-  "tab_id": "1:2"
-}
-```
-
-returns `tab_info`.
-
-### `tab.create`
-
-params:
-
-```json
-{
-  "workspace_id": "1",
-  "cwd": "/home/can/Projects/herdr",
-  "focus": true
-}
-```
-
-notes:
-
-- `workspace_id` is optional and defaults to the active workspace
-- `cwd` is optional; if omitted, herdr uses the focused pane cwd in that workspace when available
-- `focus` is optional in raw socket requests and defaults to `false`
-- the cli wrapper also defaults to no focus; pass `--focus` to switch to the new tab
-
-returns `tab_info` for the new tab.
-
-### `tab.focus`
-
-params:
-
-```json
-{
-  "tab_id": "1:2"
-}
-```
-
-returns focused `tab_info`.
-
-### `tab.rename`
-
-params:
-
-```json
-{
-  "tab_id": "1:2",
-  "label": "logs"
-}
-```
-
-returns updated `tab_info`.
-
-### `tab.close`
-
-params:
-
-```json
-{
-  "tab_id": "1:2"
-}
-```
-
-returns `ok`. the last tab in a workspace cannot be closed.
-
-## pane methods
-
-### `pane.list`
-
-request with no filter:
-
-```json
-{
-  "id": "req_panes",
-  "method": "pane.list",
-  "params": {}
-}
-```
-
-request filtered to one workspace:
-
-```json
-{
-  "id": "req_panes_ws",
-  "method": "pane.list",
-  "params": {
-    "workspace_id": "1"
-  }
-}
-```
-
-returns `pane_list`.
-
-### `pane.get`
-
-params:
-
-```json
-{
-  "pane_id": "1-1"
-}
-```
-
-returns `pane_info`.
-
-### `pane.rename`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "label": "reviewer"
-}
-```
-
-send `label: null` or omit `label` to clear the manual pane label.
-
-returns `pane_info`.
-
-### `pane.read`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "source": "recent",
-  "lines": 80,
-  "format": "text",
-  "strip_ansi": true
-}
-```
-
-notes:
-
-- `source` is required and must be `visible`, `recent`, or `recent_unwrapped`
-- `lines` is optional
-- current implementation defaults to `80` lines when `lines` is omitted and caps reads at `1000`
-- `format` defaults to `text`; use `ansi` for a rendered VT/ANSI snapshot with styles preserved
-- `strip_ansi` defaults to `true` and is kept for compatibility
-
-`source` meanings:
-
-- `visible` — current viewport
-- `recent` — recent scrollback text
-- `recent_unwrapped` — recent scrollback text with soft wraps joined
-
-example response:
-
-```json
-{
-  "id": "req_read",
-  "result": {
-    "type": "pane_read",
-    "read": {
-      "pane_id": "1-1",
-      "workspace_id": "1",
-      "tab_id": "1:1",
-      "source": "recent",
-      "format": "text",
-      "text": "...",
-      "revision": 0,
-      "truncated": false
-    }
-  }
-}
-```
-
-### `pane.split`
-
-params:
-
-```json
-{
-  "target_pane_id": "1-1",
-  "direction": "right",
-  "focus": true
-}
-```
-
-notes:
-
-- `direction` must be `right` or `down`
-- `cwd` is optional
-- `focus` is optional in raw socket requests and defaults to `false`
-- the cli wrapper also defaults to no focus; pass `--focus` to switch to the new pane
-
-returns `pane_info` for the new pane.
-
-### `pane.send_text`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "text": "bun run dev"
-}
-```
-
-this sends literal text only. it does **not** press Enter.
-
-### `pane.send_keys`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "keys": ["Enter"]
-}
-```
-
-use this after `pane.send_text` when you want to submit a command.
-
-### `pane.send_input`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "text": "bun run dev",
-  "keys": ["Enter"]
-}
-```
-
-this sends text plus encoded keypresses in order within one request. when bracketed paste is enabled in the pane, the text portion is sent as a paste payload before the keys. use this when you need `text + Enter` to behave more like a real keypress sequence than `pane.send_text` with a literal trailing `\r`.
-
-`text` and `keys` are both optional, but at least one should usually be present.
-
-### `pane.report_agent`
-
-use this when an agent hook or plugin wants to report a semantic state directly over the socket api.
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "source": "custom:hermes",
-  "agent": "hermes",
-  "state": "working",
-  "message": "running tools",
-  "custom_status": "indexing"
-}
-```
-
-notes:
-
-- `source` is required and identifies the reporting integration instance
-- `agent` is required and may be any non-empty label string
-- built-in names like `pi` are normalized to their public label form
-- custom labels like `hermes` are accepted as-is
-- while this authority is active, the reported `agent` and `state` override heuristic display for that pane
-- process detection still owns pane liveness and fallback when hook authority is cleared or released
-- `message` is optional metadata for the reporting integration
-- `custom_status` is an optional short display label such as `scheduled`, `indexing`, or `stuck`
-- `custom_status` is visual-only; use `state` for semantic behavior like working or blocked
-- omitting `custom_status` clears any previous custom status from this reporting source
-
-returns `ok`.
-
-### `pane.clear_agent_authority`
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "source": "custom:hermes"
-}
-```
-
-notes:
-
-- `source` is optional
-- when `source` is omitted, any hook authority for that pane is cleared
-- when `source` is present, only that reporting source is cleared
-
-returns `ok`.
-
-### `pane.release_agent`
-
-use this when the reported agent is exiting cleanly and wants herdr to drop agent identity immediately instead of waiting for fallback detection.
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "source": "custom:hermes",
-  "agent": "hermes"
-}
-```
-
-notes:
-
-- `agent` uses the same non-empty label rules as `pane.report_agent`
-- this clears the pane's effective agent identity immediately when the source and label match the active authority
-- for built-in detected agents, herdr also applies its normal short reacquire suppression during graceful release
-
-returns `ok`.
-
-### `pane.close`
-
-params:
-
-```json
-{
-  "pane_id": "1-2"
-}
-```
-
-returns `ok`.
-
-## waits
-
-### `pane.wait_for_output`
-
-this is the direct socket-side one-shot blocking wait.
-
-params:
-
-```json
-{
-  "pane_id": "1-1",
-  "source": "recent",
-  "lines": 200,
-  "match": { "type": "substring", "value": "ready" },
-  "timeout_ms": 30000,
-  "strip_ansi": true
-}
-```
-
-matcher forms:
-
-```json
-{ "type": "substring", "value": "ready" }
-```
-
-```json
-{ "type": "regex", "value": "server.*ready" }
-```
-
-notes:
-
-- `source` must be `visible`, `recent`, or `recent_unwrapped`
-- `lines` is optional
-- `timeout_ms` is optional
-- `strip_ansi` defaults to `true`
-- for `source = "recent"`, output matching uses unwrapped recent terminal text so soft wraps do not break matches
-- `source = "recent_unwrapped"` is also available on `pane.read` when you want to inspect the same unwrapped transcript directly
-- on success you get `output_matched`
-- on timeout you get an error response with code `timeout`
-
-example success response:
-
-```json
-{
-  "id": "req_wait",
-  "result": {
-    "type": "output_matched",
-    "pane_id": "1-1",
-    "revision": 0,
-    "matched_line": "server ready",
-    "read": {
-      "pane_id": "1-1",
-      "workspace_id": "1",
-      "tab_id": "1:1",
-      "source": "recent_unwrapped",
-      "text": "...server ready...",
-      "revision": 0,
-      "truncated": false
-    }
-  }
-}
-```
-
-## subscriptions
-
-`events.subscribe` is the long-lived pubsub entrypoint.
-
-you send a subscribe request once, get an ack on the same connection, and then keep reading newline-delimited json events from that same socket.
-
-### subscription ack
-
-```json
-{
-  "id": "sub_1",
-  "result": {
-    "type": "subscription_started"
-  }
-}
-```
-
-### supported subscriptions
-
-base lifecycle subscriptions:
-
-- `workspace.created`
-- `workspace.closed`
-- `workspace.focused`
-- `tab.created`
-- `tab.closed`
-- `tab.focused`
-- `tab.renamed`
-- `pane.created`
-- `pane.closed`
-- `pane.focused`
-- `pane.exited`
-- `pane.agent_detected`
-
-parameterized subscriptions:
-
-- `pane.output_matched`
-- `pane.agent_status_changed`
-
-### event naming rule
-
-this part matters because the pushed event names are **not all shaped the same**.
-
-- when you subscribe to a **base lifecycle event**, the pushed `event` value uses snake_case with underscores:
-  - subscribe with `workspace.created`
-  - receive `workspace_created`
-- when you subscribe to a **parameterized subscription**, the pushed `event` value keeps the dotted name:
-  - subscribe with `pane.output_matched`
-  - receive `pane.output_matched`
-
-examples below show both forms.
-
-### example: subscribe to lifecycle events
-
-request:
-
-```json
-{
-  "id": "sub_life",
-  "method": "events.subscribe",
-  "params": {
-    "subscriptions": [
-      { "type": "workspace.created" },
-      { "type": "workspace.focused" },
-      { "type": "tab.created" },
-      { "type": "tab.focused" },
-      { "type": "tab.renamed" },
-      { "type": "tab.closed" },
-      { "type": "pane.created" },
-      { "type": "pane.focused" },
-      { "type": "pane.agent_detected" },
-      { "type": "pane.closed" },
-      { "type": "workspace.closed" }
-    ]
-  }
-}
-```
-
-example pushed event:
-
-```json
-{
-  "event": "workspace_created",
-  "data": {
-    "workspace": {
-      "workspace_id": "1",
-      "number": 1,
-      "label": "herdr",
-      "focused": true,
-      "pane_count": 1,
-      "tab_count": 1,
-      "active_tab_id": "1:1",
-      "agent_status": "unknown"
-    }
-  }
-}
-```
-
-### example: subscribe to output matches and agent status changes
-
-request:
-
-```json
-{
-  "id": "sub_1",
-  "method": "events.subscribe",
-  "params": {
-    "subscriptions": [
-      {
-        "type": "pane.output_matched",
-        "pane_id": "1-1",
-        "source": "recent",
-        "lines": 200,
-        "match": { "type": "substring", "value": "ready" }
-      },
-      {
-        "type": "pane.agent_status_changed",
-        "pane_id": "1-1",
-        "agent_status": "done"
-      }
-    ]
-  }
-}
-```
-
-notes:
-
-- `pane.output_matched` supports `source`, optional `lines`, matcher config, and optional `strip_ansi`
-- `pane.agent_status_changed` accepts an optional `agent_status` filter; if omitted, any status transition for that pane can match
-
-example pushed `pane.output_matched` event:
-
-```json
-{
-  "event": "pane.output_matched",
-  "data": {
-    "pane_id": "1-1",
-    "matched_line": "server ready",
-    "read": {
-      "pane_id": "1-1",
-      "workspace_id": "1",
-      "tab_id": "1:1",
-      "source": "recent_unwrapped",
-      "text": "...server ready...",
-      "revision": 0,
-      "truncated": false
-    }
-  }
-}
-```
-
-example pushed `pane.agent_status_changed` event:
-
-```json
-{
-  "event": "pane.agent_status_changed",
-  "data": {
-    "pane_id": "1-1",
-    "workspace_id": "1",
-    "agent_status": "done",
-    "agent": "pi",
-    "custom_status": "scheduled"
-  }
-}
-```
-
-`agent` in pushed events follows the same rules as `pane_info.agent`: it may be a built-in detected name, a custom hook-reported label, or omitted. `custom_status` may be included when the pane has hook-owned custom status metadata at the time of the semantic status transition.
-## cli wrappers
-
-these commands provide the shell-facing control surface. most command groups talk to the local socket; `status client` only inspects the local executable.
-
-### command groups
-
-status commands:
-
-```text
-herdr status
-herdr status server
-herdr status client
-```
-
-`herdr -V` and `herdr --version` print the local executable version without contacting the server. `herdr status` compares that local executable with the running server when one is reachable.
-
-workspace commands:
-
-```text
-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>
-```
-
-tab commands:
-
-```text
-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>
-```
-
-agent commands:
-
-```text
-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 accept terminal ids, unique agent names, detected/reported agent labels, and legacy pane ids. `agent list` shows terminals with explicit agent identity, detected/reported agent identity, or `agent.start` launch metadata. `pane.rename` does not make a plain terminal appear in `agent list`; use `agent.rename` for agent identity.
-
-terminal commands:
-
-```text
-herdr terminal attach <terminal_id> [--takeover]
-```
-
-`terminal attach` is the low-level direct attach primitive. it streams the current rendered terminal state first, then live ANSI frames. direct attach has one writable input/resize owner; a second direct attach fails unless you pass `--takeover`. detach with `ctrl+b q`; send a literal `ctrl+b` with `ctrl+b ctrl+b`.
-
-pane commands:
-
-```text
-herdr pane list [--workspace <workspace_id>]
-herdr pane get <pane_id>
-herdr pane rename <pane_id> <label>|--clear
-herdr pane read <pane_id> [--source visible|recent|recent-unwrapped] [--lines N] [--format text|ansi] [--ansi]
-herdr pane split <pane_id> --direction right|down [--cwd PATH] [--focus] [--no-focus]
-herdr pane close <pane_id>
-herdr pane send-text <pane_id> <text>
-herdr pane send-keys <pane_id> <key> [key ...]
-herdr pane report-agent <pane_id> --source ID --agent LABEL --state idle|working|blocked|unknown [--message TEXT] [--custom-status TEXT] [--seq N]
-herdr pane run <pane_id> <command>
-```
-
-wait commands:
-
-```text
-herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
-herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
-```
-
-### cli behavior notes
-
-- `status` prints local client version/protocol, running server version/protocol when reachable, socket path, compatibility, and whether a restart is needed
-- `status server` prints only the running server side; if no server is reachable it exits successfully and prints `status: not running`
-- `status client` prints only the local executable version/protocol and binary path without contacting the server
-- `workspace create` keeps focus where it is by default; pass `--focus` to switch to the new workspace
-- `workspace create` without `--label` keeps the default cwd-based workspace naming
-- `workspace create --label` applies the custom workspace name immediately
-- `workspace create` returns `result.workspace`, `result.tab`, and `result.root_pane`
-- `tab create` keeps focus where it is by default; pass `--focus` to switch to the new tab
-- `tab create` without `--label` keeps the default numbered tab naming
-- `tab create --label` applies the custom tab name immediately
-- `tab create` returns `result.tab` and `result.root_pane`
-- `agent list` shows agent terminals, not arbitrary named panes
-- `agent wait --status idle` is the CLI completion wait; it treats the UI-only `done` attention state as satisfying idle
-- `agent focus` switches the TUI workspace/tab/pane focus; it is not direct terminal attach
-- `agent attach` attaches the current terminal directly to the agent terminal stream
-- `agent start <name> -- <argv...>` starts a named agent terminal and returns `result.agent` plus `result.argv`
-- `pane split` keeps focus where it is by default; pass `--focus` to switch to the new pane
-- `pane read` prints **text**, not json
-- `pane read --format ansi` and `pane read --ansi` print a rendered ANSI snapshot with colors/styles preserved
-- `pane read --source recent-unwrapped` returns recent terminal text with soft wraps joined back together
-- `pane send-text`, `pane send-keys`, `pane report-agent`, and `pane run` print nothing on success
-- list/get/create/split/wait commands print json on success
-- `pane run` is a convenience wrapper for `pane.send_input` with the command text followed by a real `Enter` keypress
-- `wait agent-status` is a cli convenience built on top of event subscriptions
-- use it when you want the same `done` / `idle` distinction the UI shows
-- `--raw` is a legacy alias for ANSI formatted `pane read` output and still disables ansi stripping for `wait output`
-- `wait output --source recent` matches against unwrapped recent terminal text by default, so pane width and soft wrapping do not break matches
-
-### cli examples
-
-create a workspace, split a pane, run a server, and wait for readiness:
-
-```bash
-herdr workspace create --cwd /path/to/project --label "api server"
-herdr pane split 1-1 --direction right --no-focus
-herdr pane run 1-2 "npm run dev"
-herdr wait output 1-2 --match "ready" --timeout 30000
-```
-
-wait for an agent by name to become idle for CLI automation:
-
-```bash
-herdr agent wait reviewer --status idle --timeout 60000
-```
-
-wait for a pane-level UI attention state:
-
-```bash
-herdr wait agent-status 1-1 --status done --timeout 60000
-```
-
-inspect another pane's output:
-
-```bash
-herdr pane read 1-1 --source recent --lines 80
-```
-
-## behavior notes and gotchas
-
-- `pane.send_text` sends literal text only. if you want to execute a command, follow it with `pane.send_keys` and `Enter`, use `pane.send_input` for ordered `text + keypress` input, or use cli `pane run`, which sends the text and then a real Enter key in one request.
-- `pane.read` and `pane.wait_for_output` strip ansi by default.
-- `pane.output_matched` subscriptions fire on transitions into a matching state; they do not repeatedly spam the same still-visible match on every poll.
-- closing the socket connection ends the subscription.
-- there is no separate event transport.
-- the same herdr process can serve regular request/response calls and long-lived subscription connections at the same time.