docs: clarify live docs agent cli

3 files changed, 17 insertions, 6 deletions

diff --git a/website/src/content/docs/agents.mdx b/website/src/content/docs/agents.mdx
index c01e97d1..ae21defe 100644
--- a/website/src/content/docs/agents.mdx
+++ b/website/src/content/docs/agents.mdx
@@ -18,8 +18,9 @@ Automatic detection works out of the box for common coding agents.
 | Amp | yes | yes | yes |
 | OpenCode | yes | yes | yes |
 | Grok CLI | yes | yes | yes |
+| GitHub Copilot CLI | yes | yes | yes |
 
-Detected but less thoroughly tested: Gemini CLI, Cursor Agent, Cline, Kimi, and GitHub Copilot CLI.
+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.
 
@@ -73,7 +74,7 @@ herdr agent rename 1-1 reviewer
 herdr agent rename reviewer --clear
 ```
 
-Targets accept terminal IDs, unique agent names, and legacy pane IDs.
+Targets accept terminal IDs, unique agent names, detected or reported agent labels, and legacy pane IDs.
 
 ## Custom status labels
 
@@ -91,18 +92,22 @@ herdr pane report-agent 1-1 \
 
 ## 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 target a workspace or tab:
+You can place that agent in a specific workspace or tab:
 
 ```bash
-herdr agent start tests --workspace 1 --tab 1-1 -- cargo test
+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:
@@ -118,3 +123,5 @@ 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/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx
index 7e42ebf9..78487b6a 100644
--- a/website/src/content/docs/cli-reference.mdx
+++ b/website/src/content/docs/cli-reference.mdx
@@ -128,7 +128,11 @@ herdr agent attach <target> [--takeover]
 herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--focus|--no-focus] -- <argv...>
 ```
 
-Targets accept terminal IDs, unique agent names, and legacy pane IDs.
+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
 
diff --git a/website/src/content/docs/concepts.mdx b/website/src/content/docs/concepts.mdx
index 7497b3c3..a4229123 100644
--- a/website/src/content/docs/concepts.mdx
+++ b/website/src/content/docs/concepts.mdx
@@ -77,7 +77,7 @@ Press the prefix key, default `ctrl+b`, to enter navigate mode. Use navigate mod
 
 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 your terminal needs normal mouse behavior for URL clicks, disable Herdr mouse capture:
+If you prefer keyboard-only control, or you want Herdr to stop capturing mouse input, disable mouse capture:
 
 ```toml
 [ui]