docs: clarify herdr workflows and agent skill

7 files changed, 155 insertions, 137 deletions

diff --git a/docs/next/README.md b/docs/next/README.md
index f9d07248..68f2f112 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -79,18 +79,18 @@ tmux gives you persistence and panes, but it was built before agents existed. gu
 
 ## persistence
 
-start herdr on your desktop or server. run your agents, split panes, do your work. press `ctrl+b q` to detach. close your terminal, close your laptop; your agents keep running. open a new terminal, run `herdr`, you're back. same session, same panes, same agents.
+start herdr where the work lives. locally, run `herdr`. it starts or attaches to the background session automatically, with no socket setup. run your agents, split panes, do your work. press `ctrl+b q` to detach. close your terminal, close your laptop; your agents keep running. open a new terminal, run `herdr`, you're back. same session, same panes, same agents.
 
 ### from anywhere
 
-need to check on your agents from your phone? just ssh in and run herdr. any ssh client works. no app to download, no account to create.
+need to check on your agents from your phone? just ssh in and run herdr. your shell is remote, herdr runs there, and the panes keep running there after detach. any ssh client works. no app to download, no account to create.
 
 ```
 ssh you@yourserver
 herdr
 ```
 
-or attach from your local terminal through ssh:
+or attach from your local terminal through ssh without opening a shell first. your local herdr acts as a thin client, connects over ssh, starts or attaches to the remote herdr server, and streams the ui back to your terminal.
 
 ```bash
 herdr --remote workbox
diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
index 65327c33..fc4f0589 100644
--- a/docs/next/website/src/content/docs/agent-skill.mdx
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -1,103 +1,55 @@
 ---
-title: Agent skill
-description: A concise guide for coding agents running inside Herdr.
+title: Agent skill file
+description: Install Herdr instructions for Claude Code or another coding agent.
 ---
 
-This page teaches coding agents how to use Herdr while they are running inside a Herdr pane.
+Herdr ships a reusable agent skill file at [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md).
 
-Use Herdr to organize parallel work instead of stacking everything in one terminal.
+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.
 
-## Core model
+## What the skill does
 
-Herdr has four levels:
+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.
 
-| 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. |
+With the skill installed, an agent can:
 
-Use workspace and tab actions for layout. Use pane actions for commands and output.
+- inspect workspaces, tabs, panes, and neighboring agents
+- split panes and run commands without stealing focus
+- read pane output and recent logs
+- wait for servers, tests, or another agent to finish
+- start helper agents in sibling panes
 
-## Read the current layout
+The skill is not a separate app or service. It is a markdown instruction file for agents.
 
-```bash
-herdr pane list
-```
-
-Use the pane IDs returned by Herdr for later commands.
-
-## Create a helper pane
+## Install it
 
-Split a pane and run a command:
+Use the repository copy as the source of truth:
 
-```bash
-herdr pane split 1-1 --direction right
-herdr pane run 1-2 "just test"
+```text
+https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
 ```
 
-Prefer `pane run` over sending raw keys when you want to submit a full command line.
+For agents with a skill system, install that file as a skill named `herdr`. For agents without a skill system, paste the file into the agent's project or user instructions.
 
-## Read output
+After installation, start the agent inside Herdr:
 
 ```bash
-herdr pane read 1-2 --source recent --lines 80
+herdr
+claude
 ```
 
-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
+Or use any other coding agent in a Herdr pane. The important part is that the agent process runs inside Herdr, so `HERDR_ENV=1` is available.
 
-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.
+## Safety rule
 
-## 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>"
-```
+The skill starts with one guardrail: if `HERDR_ENV=1` is not set, the agent should stop and say it is not running inside a Herdr-managed pane.
 
-## Avoid these patterns
+This prevents an agent outside Herdr from trying to control a session it does not own.
 
-Do not pile every command into the current pane.
+## Agent-facing reference
 
-Do not use raw key injection for command submission when `pane run` is available.
+The full command guide lives in the skill file itself. It covers pane IDs, `pane split`, `pane run`, `pane read`, `wait output`, `wait agent-status`, workspace and tab commands, and coordination recipes.
 
-Do not wait for `agent-status` on a normal process that is not a coding agent.
+Read the source file here:
 
-Do not change implementation direction without telling the user.
+[Open `SKILL.md` on GitHub →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx
index a4229123..ea77ac20 100644
--- a/docs/next/website/src/content/docs/concepts.mdx
+++ b/docs/next/website/src/content/docs/concepts.mdx
@@ -59,7 +59,7 @@ The server owns panes and process state. The client is the terminal UI attached
 
 Detach the client with `ctrl+b q`. The server and agents continue running.
 
-Stop the server when you are done:
+If you want to end the session and stop its panes, stop the server:
 
 ```bash
 herdr server stop
diff --git a/docs/next/website/src/content/docs/how-to-work.mdx b/docs/next/website/src/content/docs/how-to-work.mdx
new file mode 100644
index 00000000..cd37969b
--- /dev/null
+++ b/docs/next/website/src/content/docs/how-to-work.mdx
@@ -0,0 +1,103 @@
+---
+title: How to work with Herdr
+description: Run Herdr locally, inside SSH, or through remote attach.
+---
+
+Run Herdr where the work lives. Attach from wherever you are.
+
+Herdr is a background session server plus one or more terminal clients. Panes keep running in the server. Clients attach, detach, and render the session.
+
+## Local work
+
+Start Herdr from the project directory:
+
+```bash
+herdr
+```
+
+Herdr starts or attaches to your local background session automatically. You do not manage sockets. Run shells, servers, tests, and agents normally inside panes.
+
+Detach the client with `ctrl+b q`. Your panes keep running.
+
+Reattach later:
+
+```bash
+herdr
+```
+
+If you want to end the session and stop its panes, stop the server:
+
+```bash
+herdr server stop
+```
+
+## Remote work through normal SSH
+
+SSH to the machine that has the code and credentials, then run Herdr there:
+
+```bash
+ssh you@server
+herdr
+```
+
+This works like a terminal multiplexer. Your shell is remote. The Herdr server is remote. The agents and panes run on the remote machine. Detach with `ctrl+b q`, disconnect, then SSH back and run `herdr` again.
+
+Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest possible setup.
+
+## Work from your phone
+
+You do not need a Herdr mobile app or a web dashboard. Install any SSH client on your phone, connect to the machine where your agents run, and start Herdr there:
+
+```bash
+ssh you@server
+herdr
+```
+
+The same persistent Herdr session opens in your phone terminal. The TUI adapts to narrow screens, so you can inspect agents, switch workspaces, and check panes without leaving SSH.
+
+On iPhone, apps like [moshi](https://getmoshi.app/) work well.
+
+<div class="mobile-doc-shots">
+  <figure>
+    <img src="/assets/mobile-terminal.jpeg" alt="Herdr terminal view over SSH on a phone" loading="lazy" />
+    <figcaption>terminal over SSH</figcaption>
+  </figure>
+  <figure>
+    <img src="/assets/mobile-switcher.jpeg" alt="Herdr responsive switcher on a phone" loading="lazy" />
+    <figcaption>responsive switcher</figcaption>
+  </figure>
+</div>
+
+## Remote work from your local terminal
+
+Attach through SSH without opening a shell first:
+
+```bash
+herdr --remote workbox
+herdr --remote ssh://you@server:2222
+```
+
+Your local Herdr acts as a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal.
+
+Use this path when you want one local command that opens the remote Herdr session directly.
+
+For repeat targets, put the host in your SSH config:
+
+```text
+Host workbox
+  HostName server.example.com
+  User you
+  Port 2222
+```
+
+Then attach with:
+
+```bash
+herdr --remote workbox
+```
+
+## Which path to use
+
+Use `herdr` for local work. Use `ssh you@server` then `herdr` when you want Herdr to behave like tmux on that remote shell. Use `herdr --remote <host>` when you want your local terminal to attach directly to the remote Herdr session over SSH.
+
+For remote bootstrap details, named remote sessions, custom binaries, direct terminal attach, and `--no-session`, see [Persistence and remote access](/docs/persistence-remote/).
diff --git a/docs/next/website/src/content/docs/index.mdx b/docs/next/website/src/content/docs/index.mdx
index 9cdf9273..065145d1 100644
--- a/docs/next/website/src/content/docs/index.mdx
+++ b/docs/next/website/src/content/docs/index.mdx
@@ -23,31 +23,6 @@ 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>
@@ -57,20 +32,15 @@ herdr
     [Install Herdr →](/docs/install/)
   </Card>
   <Card title="Quick start">
-    Create your first workspace, run agents in panes, split the layout, and detach safely.
+    Create your first workspace, run an agent, split panes, and detach safely.
 
     [Start using Herdr →](/docs/quick-start/)
   </Card>
-  <Card title="Concepts">
-    Understand workspaces, tabs, panes, agents, sessions, modes, and state rollups.
+  <Card title="Local, SSH, and mobile">
+    Run Herdr locally, inside SSH, from your phone, or through `herdr --remote`.
 
-    [Learn the model →](/docs/concepts/)
+    [Pick a workflow →](/docs/how-to-work/)
   </Card>
-</CardGrid>
-
-## Guides and reference
-
-<CardGrid>
   <Card title="Agents">
     See supported agents, detection behavior, integrations, custom labels, and direct attach.
 
@@ -81,24 +51,9 @@ herdr
 
     [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.
+  <Card title="API">
+    Control Herdr from scripts, tools, and agents through the CLI and 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/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index e943fd4c..f3c53dec 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -5,6 +5,8 @@ description: Detach from Herdr, reattach later, use named sessions, and connect
 
 Herdr keeps panes running in a background server. Your terminal client can detach and reconnect later.
 
+For the local, SSH, and `herdr --remote` workflows, see [How to work with Herdr](/docs/how-to-work/).
+
 ## Detach and reattach
 
 Start Herdr:
@@ -21,7 +23,7 @@ Your panes and agents keep running. Reattach by running Herdr again:
 herdr
 ```
 
-Stop the default server when you want to end the session:
+If you want to end the session and stop its panes, stop the default server:
 
 ```bash
 herdr server stop
@@ -58,6 +60,8 @@ 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:
 
 ```bash
@@ -65,6 +69,8 @@ herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```
 
+In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal.
+
 For repeat targets, use your SSH config:
 
 ```text
diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx
index 08d815f3..fddef6b8 100644
--- a/docs/next/website/src/content/docs/quick-start.mdx
+++ b/docs/next/website/src/content/docs/quick-start.mdx
@@ -9,7 +9,9 @@ Start Herdr from any project directory:
 herdr
 ```
 
-Herdr launches or attaches to your default background session. If you detach, agents keep running.
+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
 
@@ -63,18 +65,18 @@ Workspaces are usually enough. Use named sessions when you need isolation betwee
 
 ## Attach from another machine
 
-Start Herdr on a server, detach, and come back over SSH later.
+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:
 
 ```bash
 ssh you@server
 herdr
 ```
 
-You can also attach through SSH from your local terminal:
+Or attach from your local terminal through SSH:
 
 ```bash
 herdr --remote workbox
 herdr --remote ssh://you@server:2222
 ```
 
-For repeat targets, put the host in your SSH config.
+For repeat targets, put the host in your SSH config. See [How to work with Herdr](/docs/how-to-work/) for the full model.