docs: refresh readme and socket api positioning

1 files changed, 44 insertions, 52 deletions

diff --git a/SKILL.md b/SKILL.md
index c0ba3061..e3d528aa 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,84 +1,78 @@
 # herdr — agent skill
 
-you are running inside herdr, a terminal workspace manager. herdr gives you workspaces (tabs) and panes (splits) — each pane is a full terminal with its own shell or agent. you can control all of it from the CLI.
+you are running inside herdr, a terminal-native agent multiplexer. herdr gives you workspaces and panes — each pane is a real terminal with its own shell, agent, server, or log stream — and you can control all of it from the cli.
 
 this means you can:
-- see what other agents/panes are doing
+
+- see what other panes and agents are doing
 - split panes and run commands in them
-- start servers, watch logs, run tests — in separate panes
+- start servers, watch logs, and run tests in sibling panes
 - wait for specific output before continuing
 - wait for another agent to finish
-- spawn new agent instances
+- spawn more agent instances
+
+the `herdr` binary is available in your PATH. its workspace, pane, and wait commands talk to the running herdr instance over a local unix socket.
 
-the `herdr` binary is available in your PATH. all commands talk to the running herdr instance over a local unix socket.
+if you need the raw protocol or full api reference, read [`SOCKET_API.md`](./SOCKET_API.md).
 
 ## concepts
 
-**workspaces** are like tabs. each workspace has one or more panes. you switch between workspaces in the sidebar.
+**workspaces** are project contexts. each workspace has one or more panes.
 
 **panes** are terminal splits inside a workspace. each pane runs its own process — a shell, an agent, a server, anything.
 
 **agent state** is detected automatically by herdr. each pane can be:
-- `idle` — agent finished, user has seen it
-- `busy` — agent is working
-- `waiting` — agent needs user input
+
+- `idle` — agent finished and the state is calm
+- `working` — agent is actively working
+- `blocked` — agent needs input or approval
 - `unknown` — no recognized agent, or just a shell
 
-**ids** — workspace ids look like `1`, `2`. pane ids look like `1-1`, `1-2`, `2-1`. these are the public ids you should use.
+**ids** — workspace ids look like `1`, `2`. pane ids look like `1-1`, `1-2`, `2-1`. these are compact public ids for the current live session.
+
+important: ids can compact when panes or workspaces are closed. do not treat them as durable ids.
 
 ## discover yourself
 
-find out which pane you're in and what else is running:
+see what panes exist and which one is focused:
 
 ```bash
 herdr pane list
 ```
 
-```json
-{"id":"cli:pane:list","result":{"panes":[
-  {"agent":"claude","agent_state":"waiting","cwd":"/home/user/project","focused":true,"pane_id":"1-2","workspace_id":"1"},
-  {"agent":"pi","agent_state":"idle","cwd":"/home/user/project","focused":false,"pane_id":"1-1","workspace_id":"1"}
-],"type":"pane_list"}}
-```
-
 the focused pane is yours. other panes are your neighbors.
 
+list workspaces:
+
 ```bash
 herdr workspace list
 ```
 
-```json
-{"id":"cli:workspace:list","result":{"type":"workspace_list","workspaces":[
-  {"workspace_id":"1","number":1,"label":"project","focused":true,"pane_count":2,"agent_state":"waiting"}
-]}}
-```
-
 ## read another pane
 
-see what's on another pane's screen:
+see what is on another pane's screen:
 
 ```bash
 herdr pane read 1-1 --source recent --lines 50
 ```
 
-`--source visible` shows the current viewport. `--source recent` shows recent scrollback (default).
+- `--source visible` = current viewport
+- `--source recent` = recent scrollback
 
 ## split a pane and run a command
 
-split your pane to the right and run a dev server:
+split your pane to the right and keep focus on your current pane:
 
 ```bash
 herdr pane split 1-2 --direction right --no-focus
 ```
 
-this returns the new pane's id. then run a command in it:
+that prints json with the new pane id. read the returned `pane_id`, then run a command in that pane:
 
 ```bash
 herdr pane run 1-3 "npm run dev"
 ```
 
-`pane run` sends the text and presses Enter. use `--no-focus` on split to keep focus on your pane.
-
 split downward instead:
 
 ```bash
@@ -87,7 +81,7 @@ herdr pane split 1-2 --direction down --no-focus
 
 ## wait for output
 
-block until specific text appears in a pane. useful for waiting on servers, builds, tests:
+block until specific text appears in a pane. useful for waiting on servers, builds, and tests:
 
 ```bash
 herdr wait output 1-3 --match "ready on port 3000" --timeout 30000
@@ -99,9 +93,9 @@ with regex:
 herdr wait output 1-3 --match "server.*ready" --regex --timeout 30000
 ```
 
-timeout is in milliseconds. if it times out, exit code is 1.
+if it times out, exit code is `1`.
 
-## wait for an agent to finish
+## wait for an agent state
 
 block until another agent reaches a specific state:
 
@@ -119,13 +113,13 @@ send text without pressing Enter:
 herdr pane send-text 1-1 "hello from claude"
 ```
 
-press Enter (or other keys):
+press Enter or other keys:
 
 ```bash
 herdr pane send-keys 1-1 Enter
 ```
 
-`pane run` combines both — sends text then Enter:
+`pane run` combines both — sends text, then presses Enter:
 
 ```bash
 herdr pane run 1-1 "echo hello"
@@ -139,6 +133,8 @@ create a new workspace:
 herdr workspace create --cwd /path/to/project
 ```
 
+create one without focusing it:
+
 ```bash
 herdr workspace create --no-focus
 ```
@@ -169,30 +165,30 @@ herdr pane close 1-3
 
 ## recipes
 
-### run a server and watch for ready
+### run a server and wait until it is ready
 
 ```bash
 # split a pane for the server
 herdr pane split 1-2 --direction right --no-focus
-# assume new pane is 1-3 from the response
+# read the returned JSON to get the new pane_id, for example 1-3
 
 # start the server
 herdr pane run 1-3 "npm run dev"
 
-# wait until it's ready
+# wait until it is ready
 herdr wait output 1-3 --match "ready" --timeout 30000
 
-# now read the output to confirm
-herdr pane read p_1_7 --source recent --lines 20
+# read the output to confirm
+herdr pane read 1-3 --source recent --lines 20
 ```
 
-### run tests in a separate pane and check results
+### run tests in a separate pane and inspect the result
 
 ```bash
 herdr pane split 1-2 --direction down --no-focus
 herdr pane run 1-3 "cargo test"
 herdr wait output 1-3 --match "test result" --timeout 60000
-herdr pane read p_1_7 --source recent --lines 30
+herdr pane read 1-3 --source recent --lines 30
 ```
 
 ### check what another agent is working on
@@ -207,26 +203,22 @@ herdr pane read 1-1 --source recent --lines 80
 ```bash
 herdr pane split 1-2 --direction right --no-focus
 herdr pane run 1-3 "claude"
-# wait for it to start
 herdr wait output 1-3 --match ">" --timeout 15000
-# send it a task
 herdr pane run 1-3 "review the test coverage in src/api/"
 ```
 
 ### coordinate with another agent
 
 ```bash
-# wait for the other agent to finish its current work
 herdr wait agent-state 1-1 --state idle --timeout 120000
-
-# read what it produced
 herdr pane read 1-1 --source recent --lines 100
 ```
 
 ## notes
 
-- all commands return JSON. parse the response to get pane ids from splits, workspace ids from creates, etc.
-- `pane run` = `pane send-text` + `pane send-keys Enter`. use the separate commands when you need finer control.
-- pane ids from split responses are the source of truth — don't guess pane ids, read them from the response.
-- `--no-focus` on split keeps your terminal focused. without it, herdr focuses the new pane.
-- if you're running inside herdr, the `HERDR_ENV` environment variable is set to `1`. ids are compact and can change when panes/workspaces are closed.
+- `workspace list`, `pane list`, `workspace create`, `pane split`, `wait output`, and `wait agent-state` print json on success.
+- `pane read` prints text, not json.
+- `pane send-text`, `pane send-keys`, and `pane run` print nothing on success.
+- parse ids from `workspace create` and `pane split` responses when you need the new ids. do not guess.
+- `--no-focus` on split and workspace create keeps your current terminal context focused.
+- if you are running inside herdr, the `HERDR_ENV` environment variable is set to `1`.