docs: clarify herdr workflows and agent skill

8 files changed, 279 insertions, 142 deletions

diff --git a/website/src/components/SiteTitle.astro b/website/src/components/SiteTitle.astro
new file mode 100644
index 00000000..04839c38
--- /dev/null
+++ b/website/src/components/SiteTitle.astro
@@ -0,0 +1,102 @@
+---
+import { logos } from 'virtual:starlight/user-images';
+import config from 'virtual:starlight/user-config';
+
+const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute;
+---
+
+<div class="title-row sl-flex">
+  <a href={siteTitleHref} class="site-title sl-flex">
+    {
+      config.logo && logos.dark && (
+        <>
+          <img
+            class:list={{ 'light:sl-hidden print:hidden': !('src' in config.logo) }}
+            alt={config.logo.alt}
+            src={logos.dark.src}
+            width={logos.dark.width}
+            height={logos.dark.height}
+          />
+          {!('src' in config.logo) && (
+            <img
+              class="dark:sl-hidden print:block"
+              alt={config.logo.alt}
+              src={logos.light?.src}
+              width={logos.light?.width}
+              height={logos.light?.height}
+            />
+          )}
+        </>
+      )
+    }
+    <span class:list={{ 'sr-only': config.logo?.replacesTitle }} translate="no">
+      {siteTitle}
+    </span>
+  </a>
+  <nav class="title-nav" aria-label="Primary">
+    <a href="/docs/">Docs</a>
+  </nav>
+</div>
+
+<style>
+  @layer starlight.core {
+    .title-row {
+      align-items: baseline;
+      gap: 1rem;
+      min-width: 0;
+    }
+
+    .site-title {
+      align-items: baseline;
+      gap: var(--sl-nav-gap);
+      font-size: var(--sl-text-h4);
+      font-weight: 600;
+      color: var(--sl-color-text-accent);
+      text-decoration: none;
+      white-space: nowrap;
+      min-width: 0;
+    }
+
+    span {
+      overflow: hidden;
+    }
+
+    img {
+      height: calc(var(--sl-nav-height) - 2 * var(--sl-nav-pad-y));
+      width: auto;
+      max-width: 100%;
+      object-fit: contain;
+      object-position: 0 50%;
+    }
+
+    .title-nav {
+      display: flex;
+      align-items: baseline;
+      gap: 0.75rem;
+      font-size: var(--sl-text-sm);
+      font-weight: 600;
+      line-height: 1;
+    }
+
+    .title-nav a {
+      color: var(--sl-color-text-accent);
+      text-decoration: none;
+      transition: color 120ms ease;
+    }
+
+    .site-title {
+      transition: color 120ms ease;
+    }
+
+    .site-title:hover,
+    .title-nav a:hover {
+      color: var(--sl-color-accent-high);
+    }
+
+    @media (max-width: 35rem) {
+      .title-nav {
+        display: none;
+      }
+    }
+  }
+</style>
diff --git a/website/src/content/docs/agent-skill.mdx b/website/src/content/docs/agent-skill.mdx
index 65327c33..fc4f0589 100644
--- a/website/src/content/docs/agent-skill.mdx
+++ b/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/website/src/content/docs/concepts.mdx b/website/src/content/docs/concepts.mdx
index a4229123..ea77ac20 100644
--- a/website/src/content/docs/concepts.mdx
+++ b/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/website/src/content/docs/how-to-work.mdx b/website/src/content/docs/how-to-work.mdx
new file mode 100644
index 00000000..cd37969b
--- /dev/null
+++ b/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/website/src/content/docs/index.mdx b/website/src/content/docs/index.mdx
index 9cdf9273..065145d1 100644
--- a/website/src/content/docs/index.mdx
+++ b/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/website/src/content/docs/persistence-remote.mdx b/website/src/content/docs/persistence-remote.mdx
index e943fd4c..f3c53dec 100644
--- a/website/src/content/docs/persistence-remote.mdx
+++ b/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/website/src/content/docs/quick-start.mdx b/website/src/content/docs/quick-start.mdx
index 08d815f3..fddef6b8 100644
--- a/website/src/content/docs/quick-start.mdx
+++ b/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.
diff --git a/website/src/styles/starlight.css b/website/src/styles/starlight.css
index 21518c63..1120e31b 100644
--- a/website/src/styles/starlight.css
+++ b/website/src/styles/starlight.css
@@ -86,14 +86,6 @@
   color: var(--sl-color-gray-1);
 }
 
-.header a[href="/"]::after {
-  content: "home";
-  margin-left: 0.75rem;
-  color: var(--sl-color-gray-3);
-  font-size: 0.8rem;
-  font-weight: 500;
-}
-
 #starlight__sidebar a[aria-current="page"] {
   background: color-mix(in srgb, var(--sl-color-accent) 13%, transparent);
   color: var(--sl-color-accent-high);
@@ -104,6 +96,31 @@
   color: var(--sl-color-accent-high);
 }
 
+.mobile-doc-shots {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+  gap: 1rem;
+  margin: 1.25rem 0;
+}
+
+.mobile-doc-shots figure {
+  margin: 0;
+}
+
+.mobile-doc-shots img {
+  display: block;
+  width: 100%;
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 1rem;
+}
+
+.mobile-doc-shots figcaption {
+  margin-top: 0.45rem;
+  color: var(--sl-color-gray-3);
+  font-size: var(--sl-text-sm);
+  text-align: center;
+}
+
 .sl-markdown-content a:not(:where(.not-content *)) {
   text-decoration-thickness: 1px;
   text-underline-offset: 0.18em;