From 3968530d55b39bf161ae24104ab4ad1e4fa096be Mon Sep 17 00:00:00 2001
From: Hiroshi Shinaoka <h.shinaoka@gmail.com>
Date: Thu, 29 Oct 2026 20:11:32 +0900
Subject: [PATCH 1/3] docs: guide to running a two-level agent fleet

Add docs/agent-fleet with a figure and a step-by-step guide to the
maintainer's setup: one orchestrator Claude Code session (also reachable
from a phone) driving herdr agents on several machines over Tailscale,
the orchestrator operating rules, the recovery state layout, the
structure of the maintainer's rule set, and security notes. Link it
from the README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                        |   5 +
 docs/agent-fleet/README.md       | 251 +++++++++++++++++++++++++++++++
 docs/agent-fleet/agent-fleet.svg | 125 +++++++++++++++
 3 files changed, 381 insertions(+)
 create mode 100644 docs/agent-fleet/README.md
 create mode 100644 docs/agent-fleet/agent-fleet.svg

diff --git a/README.md b/README.md
index 0f839d1..a947c1c 100644
--- a/README.md
+++ b/README.md
@@ -33,3 +33,8 @@ skills/
 
 Skills are thin trigger and workflow layers; the rule files are the source of
 truth.
+
+## Guides
+
+- [`docs/agent-fleet`](docs/agent-fleet/README.md): how to run many coding
+  agents on several machines from one orchestrator session.
diff --git a/docs/agent-fleet/README.md b/docs/agent-fleet/README.md
new file mode 100644
index 0000000..8ba56a1
--- /dev/null
+++ b/docs/agent-fleet/README.md
@@ -0,0 +1,251 @@
+# Running a Two-Level Agent Fleet
+
+This page describes how the maintainer runs many coding agents at once, and
+how to reproduce the setup. It is a guide, not a rule. Adapt it to your own
+machines and budget.
+
+![Two-level agent fleet](agent-fleet.svg)
+
+## Architecture
+
+The fleet has three levels.
+
+- **Level 0: the human.** The maintainer decides, approves releases and gives
+  instructions in plain language. They talk only to the orchestrator. The
+  orchestrator session can also be continued from Claude Code on a phone, so
+  the maintainer can steer the fleet while away from the laptop. It is the same
+  session, not a second one.
+- **Level 1: the orchestrator.** One Claude Code session on a laptop. It runs
+  rounds on a cron schedule, reads each agent's screen, dispatches tasks by
+  prompt, reviews and merges pull requests, and escalates decisions it should
+  not take.
+- **Level 2: the machines.** Each remote machine runs
+  herdr, a terminal multiplexer for
+  coding agents, with several agents in its panes. Agents are Claude Code
+  sessions (Opus or Sonnet) or pi agents on cheaper models such as DeepSeek.
+
+Two shared services tie the levels together.
+
+- **GitHub.** Agents push branches and open pull requests. Issues are assigned
+  to the maintainer when work starts. Only the orchestrator merges.
+- **A private state repository.** A small git repository holds the recovery
+  state, so a new orchestrator session can take over at any time. See
+  [Recovery state](#recovery-state).
+
+Each machine has a role. In the maintainer's fleet these are a quiet benchmark
+host, an implementation host with a GPU, and a many-core scaling host. Adding a
+machine adds a whole team of agents.
+
+## Reproduce the setup
+
+### 1. Network
+
+Install [Tailscale](https://tailscale.com/) on the laptop and on every machine.
+The machines then reach each other on a private network and need no open ports
+on the public internet.
+
+### 2. SSH key
+
+Create one dedicated ed25519 key without a passphrase. The orchestrator works
+unattended, so it cannot type a passphrase.
+
+```sh
+ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519_fleet -C fleet
+```
+
+Add the public key to `~/.ssh/authorized_keys` on each machine. Use this key
+only for the tailnet. Give each machine a Host alias in `~/.ssh/config` on the
+laptop:
+
+```sshconfig
+Host host-a_vpn
+    HostName host-a.your-tailnet.ts.net
+    User you
+    IdentityFile ~/.ssh/id_ed25519_fleet
+    IdentitiesOnly yes
+```
+
+Check that `ssh host-a_vpn true` works without any prompt.
+
+### 3. herdr
+
+Install herdr on each machine and start it there. On the laptop, register each
+machine once:
+
+```sh
+herdr machine add host-a_vpn
+herdr machine list
+```
+
+Adding and removing machines is the human's job. The orchestrator only uses
+machines that are already registered.
+
+### 4. Orchestrator commands
+
+The orchestrator drives every machine with `herdr --machine <label> ...`. The
+commands it needs are few.
+
+| Command | Use |
+|---|---|
+| `herdr --machine host-a_vpn agent list` | List the agents and their state. |
+| `herdr --machine host-a_vpn agent get <name>` | Show one agent's details. |
+| `herdr --machine host-a_vpn agent read <name>` | Read the agent's screen. |
+| `herdr --machine host-a_vpn agent prompt <name> "..."` | Send a task or an answer. |
+| `herdr --machine host-a_vpn agent send-keys <name> ...` | Send raw keys (Esc, Enter, Shift+Tab). |
+| `herdr --machine host-a_vpn agent start ...` | Start a new agent in a pane. |
+| `herdr --machine host-a_vpn agent rename <pane> <name>` | Name an agent. |
+| `herdr --machine host-a_vpn pane split ...` | Make room for another agent. |
+
+Run `herdr --help` on your version for the exact arguments.
+
+A failed connection does not mean that a prompt was not delivered. Read the
+agent's screen before you send it again.
+
+### 5. Agent names
+
+Name every agent `<machine>-<repo>-<role>[-<model>]`, for example
+`host-b-tenferro-impl` or `host-c-t4a-review-dsv4f`. Use lowercase letters,
+digits, `-` and `_`, and at most 32 characters. Claude agents may omit the
+model suffix. Names disappear when an agent exits, so check them on every
+round. Refer to agents by name, never by pane id.
+
+### 6. Claude Code agents
+
+Start Claude agents with:
+
+```sh
+claude --allow-dangerously-skip-permissions --model opus    # or sonnet
+```
+
+herdr does not apply your shell aliases, so pass the flags in full. When the
+agent starts, accept the bypass dialog, then press Shift+Tab until the status
+line shows that bypass permissions is on.
+
+### 7. pi agents
+
+[pi](https://github.com/badlogic/pi-mono) runs agents on cheaper models. Two
+things differ from Claude Code.
+
+- A prompt sent while the agent is in a long tool call is queued. It runs only
+  after the tool call ends. For an urgent prompt, send Esc first, then the
+  prompt and Enter.
+- The screen shows little history. Read the session log instead, in
+  `~/.pi/agent/sessions/*/*.jsonl` on that machine.
+
+### 8. Model policy
+
+Use Sonnet or a cheap model for simple work: docs, mechanical edits, running
+benchmarks, collecting logs. Use Opus for complex coding, reviews and
+judgment calls. The orchestrator itself runs on the strongest model you have.
+
+## Orchestrator operating rules
+
+These are the rules the maintainer's orchestrator follows. Write your own
+version into the orchestrator's instructions.
+
+- **Rounds.** Run a round every 10 minutes: read every agent, unblock or
+  redirect, merge what is ready. Twice an hour, check overall progress against
+  the TODO queue.
+- **Issue patrol.** Once an hour, scan the tracked repositories for new issues
+  and comments.
+- **Daily checks.** Update the tools (Claude Code, pi, herdr and build caches)
+  on every machine. Read the issue trackers of upstream projects you depend on.
+- **Approval dialogs.** Never answer an agent's approval dialog on its behalf.
+  Report it to the human instead. The only exceptions are dialogs agreed in
+  advance, such as folder trust, a model switch, or accepting bypass
+  permissions at startup.
+- **Releases.** Publish to crates.io only after the maintainer approves that
+  release explicitly in the conversation.
+- **GPU work.** Validate tenferro GPU changes on a local GPU and mark the PR
+  with a label, instead of running paid GPU CI.
+- **Issue assignment.** When an agent starts on an issue, assign it to the
+  maintainer. This avoids duplicate work with outside contributors.
+- **Merging.** Use a merge commit when the branch contains other people's
+  commits, so their authorship is kept.
+- **Benchmarks.** Measure on a quiet host with CPU boost off. See
+  [`rules/benchmark`](../../rules/benchmark/index.md).
+- **Approvals.** Record every approval verbatim, with its date, in the
+  handoff file.
+
+## Recovery state
+
+A long orchestrator session dies or fills its context sooner or later. The
+recovery state lets a fresh session take over in a few minutes. Keep it in a
+private git repository that every machine can push to.
+
+```text
+state/<project>/
+  handoff.md            written only by the orchestrator
+  monitoring.md         the exact cron prompts and schedules
+  agents/<name>.md      each agent writes only its own file
+  worklog/<date>.md     append-only, anyone
+```
+
+- `handoff.md` is rewritten, not appended, on every change. It lists the
+  machines, the agents and their tasks, in-flight PRs, tracked issues, pending
+  decisions, approvals (verbatim, with dates), standing rules, and the ordered
+  TODO queue.
+- `agents/<name>.md` holds one agent's task, branch and worktree, last step,
+  next step and blockers. One writer per file means agents on different
+  machines never conflict.
+- `worklog/<date>.md` records dated events: merges, releases, decisions with
+  their source, incidents.
+- `monitoring.md` holds the exact cron prompts, so a new session can recreate
+  the loops without guessing.
+
+To resume after a crash or a full context:
+
+1. Read `handoff.md`, then every `agents/*.md`, then the last two worklog
+   files.
+2. Check each listed agent with `agent get` and `agent read`, and each listed
+   PR, before acting. The files can be one update behind.
+3. Recreate the cron loops from `monitoring.md`.
+
+## How the maintainer's rule set is built
+
+The maintainer's own rules are private, but their structure is easy to copy.
+There are four layers.
+
+1. **Global instructions** in `~/.claude/CLAUDE.md`. Personal preferences that
+   hold in every project: the response language, preferred tools (for example
+   CodeGraph before grep), and limits on remote control (which herdr commands
+   the session may run, and that it never answers another agent's approval
+   dialog).
+2. **Per-repository `AGENTS.md`.** Each tensor4all repository keeps a short
+   `AGENTS.md` that points to this repository for shared rules and adds only
+   repository-specific ones.
+3. **Claude Code auto-memory.** A memory directory with one fact per file and
+   an index file that lists them all, one line each. Each fact has a type:
+   user, feedback, project or reference. Feedback and project entries carry a
+   "Why" line and a "How to apply" line, so the rule can be judged later
+   rather than followed blindly.
+4. **A private advisor repository.** It holds:
+   - **Skills.** An `autopilot` skill runs one issue or phase alone. It plans
+     the phase, drives cheap workers through pi with helper scripts (a
+     supervisor such as `supervise.sh` and a worker launcher such as
+     `pi_worker.sh`), gets an independent review from a different model, opens
+     one PR and fixes CI until it is green. A `build-profile` skill builds the
+     decision profile below.
+   - **A decision profile.** `profile/rules.md` holds rules, and a precedents
+     file holds short past decisions with a pointer to their source. The
+     `build-profile` skill mines past transcripts and worklogs for decisions
+     that recur, and turns them into rules. Rules that came from the
+     maintainer directly are never weakened by a rebuild.
+   - **Proxy logs.** Every decision the autopilot takes on the maintainer's
+     behalf is logged. The maintainer reviews and corrects them, and the
+     corrections feed the next profile update.
+   - **The `state/` directory** described in [Recovery state](#recovery-state).
+
+Start small. A global `CLAUDE.md`, an `AGENTS.md` per repository and the state
+directory are enough for a fleet of a few agents. Add the profile when you
+notice that you answer the same questions again and again.
+
+## Security notes
+
+- A passphrase-less key and bypass permissions are acceptable only on machines
+  you control, inside the tailnet. Do not reuse the key elsewhere.
+- Keep secrets out of every file an agent can read: the state repository,
+  worklogs, memory and prompts. Agents copy what they see into logs and PRs.
+- On a shared machine, other users' jobs come first. Check the load before
+  starting builds or benchmarks, limit the cores your agents use, and never
+  kill processes you do not own.
diff --git a/docs/agent-fleet/agent-fleet.svg b/docs/agent-fleet/agent-fleet.svg
new file mode 100644
index 0000000..e7a248c
--- /dev/null
+++ b/docs/agent-fleet/agent-fleet.svg
@@ -0,0 +1,125 @@
+<svg viewBox="0 0 1180 660" width="1180" height="660" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Two-level agent fleet: a maintainer, on a laptop or a phone, talks to one orchestrator session; the orchestrator controls herdr on remote machines over Tailscale and SSH; each machine runs several agents that open pull requests on GitHub; shared state lives in a git repository.">
+  <title>Two-level agent fleet</title>
+  <defs>
+    <marker id="ar" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#5b6575"/></marker>
+    <marker id="arn" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#7a4cc2"/></marker>
+    <style>
+      text { font-family: "Helvetica Neue", Helvetica, Arial, "Liberation Sans", sans-serif; fill: #1d2430; }
+      .mono { font-family: Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", monospace; font-size: 12px; fill: #5b6575; }
+      .muted { fill: #5b6575; }
+      .h { font-weight: 600; font-size: 15px; }
+      .lab { font-size: 11px; letter-spacing: 0.08em; font-weight: 600; }
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="1180" height="660" rx="14" fill="#ffffff"/>
+
+  <!-- Level 0 -->
+  <text x="24" y="34" class="lab" fill="#2f6fdb" style="fill:#2f6fdb">LEVEL 0: HUMAN</text>
+  <rect x="24" y="46" width="250" height="92" rx="9" fill="#eef2f8" stroke="#2f6fdb" stroke-width="1.6"/>
+  <text x="40" y="74" class="h">Maintainer</text>
+  <text x="40" y="96" class="muted" font-size="13">Decides, approves releases,</text>
+  <text x="40" y="114" class="muted" font-size="13">chats in plain language</text>
+
+  <!-- phone -->
+  <rect x="300" y="46" width="92" height="92" rx="9" fill="#eef2f8" stroke="#2f6fdb" stroke-width="1.4" stroke-dasharray="5 4"/>
+  <rect x="333" y="56" width="26" height="42" rx="5" fill="#ffffff" stroke="#2f6fdb" stroke-width="1.4"/>
+  <line x1="342" y1="93" x2="350" y2="93" stroke="#2f6fdb" stroke-width="1.4"/>
+  <text x="346" y="116" text-anchor="middle" font-size="12">Phone</text>
+  <text x="346" y="131" text-anchor="middle" font-size="11" class="muted">same session</text>
+  <path d="M274 92 H298" stroke="#2f6fdb" stroke-width="1.4" fill="none"/>
+  <path d="M346 140 C346 170 220 168 200 190" stroke="#2f6fdb" stroke-width="1.4" stroke-dasharray="5 4" fill="none" marker-end="url(#ar)"/>
+  <text x="290" y="176" class="muted" font-size="11">remote control</text>
+
+  <!-- Level 1 -->
+  <text x="24" y="182" class="lab" style="fill:#0f8a6b">LEVEL 1: LAPTOP</text>
+  <rect x="24" y="194" width="250" height="250" rx="9" fill="#ffffff" stroke="#0f8a6b" stroke-width="1.6"/>
+  <text x="40" y="222" class="h">Orchestrator session</text>
+  <text x="40" y="242" class="muted" font-size="13">Claude Code on the laptop</text>
+  <text x="40" y="270" font-size="13">- Rounds every 10 min (cron)</text>
+  <text x="40" y="290" font-size="13">- Reads each agent's screen</text>
+  <text x="40" y="310" font-size="13">- Dispatches tasks by prompt</text>
+  <text x="40" y="330" font-size="13">- Reviews and merges PRs</text>
+  <text x="40" y="350" font-size="13">- Escalates decisions upward</text>
+  <text x="40" y="378" class="mono">herdr --machine host-a_vpn \</text>
+  <text x="40" y="396" class="mono">  agent read|prompt NAME</text>
+  <text x="40" y="424" class="mono">ssh host-c_vpn ...</text>
+
+  <path d="M149 138 V192" stroke="#5b6575" stroke-width="1.5" fill="none" marker-end="url(#ar)" marker-start="url(#ar)"/>
+
+  <!-- network band -->
+  <rect x="300" y="194" width="92" height="250" rx="9" fill="#f3eefb" stroke="#7a4cc2" stroke-width="1.4" stroke-dasharray="5 4"/>
+  <text x="346" y="292" text-anchor="middle" class="h" style="fill:#7a4cc2">Tailscale</text>
+  <text x="346" y="312" text-anchor="middle" font-size="12.5" class="muted">private</text>
+  <text x="346" y="328" text-anchor="middle" font-size="12.5" class="muted">network</text>
+  <text x="346" y="356" text-anchor="middle" font-size="12.5" class="muted">+ SSH key,</text>
+  <text x="346" y="372" text-anchor="middle" font-size="12.5" class="muted">no passphrase</text>
+  <path d="M274 319 H298" stroke="#7a4cc2" stroke-width="1.6" fill="none" marker-end="url(#arn)"/>
+
+  <!-- Level 2 hosts -->
+  <text x="420" y="34" class="lab" style="fill:#b4581c">LEVEL 2: REMOTE MACHINES, EACH RUNNING HERDR</text>
+
+  <!-- host a -->
+  <rect x="420" y="46" width="236" height="250" rx="9" fill="#ffffff" stroke="#b4581c" stroke-width="1.6"/>
+  <text x="436" y="74" class="h">host-a</text>
+  <text x="436" y="94" class="muted" font-size="12.5">quiet benchmark host</text>
+  <rect x="436" y="108" width="204" height="40" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="448" y="133" font-size="13">pi agent: cheap model</text>
+  <rect x="436" y="156" width="204" height="40" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="448" y="181" font-size="13">Claude Code: bench</text>
+  <text x="436" y="226" class="muted" font-size="12.5">boost off, pinned cores,</text>
+  <text x="436" y="244" class="muted" font-size="12.5">regression gates</text>
+
+  <!-- host b -->
+  <rect x="676" y="46" width="236" height="250" rx="9" fill="#ffffff" stroke="#b4581c" stroke-width="1.6"/>
+  <text x="692" y="74" class="h">host-b</text>
+  <text x="692" y="94" class="muted" font-size="12.5">implementation host with a GPU</text>
+  <rect x="692" y="108" width="204" height="30" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="704" y="128" font-size="13">Claude Opus: repo 1 impl</text>
+  <rect x="692" y="144" width="204" height="30" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="704" y="164" font-size="13">Claude Opus: repo 2 impl</text>
+  <rect x="692" y="180" width="204" height="30" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="704" y="200" font-size="13">Claude Sonnet: docs</text>
+  <rect x="692" y="216" width="204" height="30" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="704" y="236" font-size="13">pi agent: cheap model ...</text>
+  <text x="692" y="274" class="muted" font-size="12.5">local GPU gate, no paid CI</text>
+
+  <!-- host c -->
+  <rect x="932" y="46" width="224" height="250" rx="9" fill="#ffffff" stroke="#b4581c" stroke-width="1.6"/>
+  <text x="948" y="74" class="h">host-c</text>
+  <text x="948" y="94" class="muted" font-size="12.5">many-core scaling host</text>
+  <rect x="948" y="108" width="192" height="40" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="960" y="133" font-size="13">pi agent: bench</text>
+  <rect x="948" y="156" width="192" height="40" rx="6" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="960" y="181" font-size="13">Claude Opus: review</text>
+  <text x="948" y="226" class="muted" font-size="12.5">thread scaling and</text>
+  <text x="948" y="244" class="muted" font-size="12.5">library comparisons</text>
+
+  <path d="M392 260 C405 260 405 171 418 171" stroke="#7a4cc2" stroke-width="1.6" fill="none" marker-end="url(#arn)"/>
+  <path d="M392 300 C520 300 640 300 674 250" stroke="#7a4cc2" stroke-width="1.6" fill="none" marker-end="url(#arn)"/>
+  <path d="M392 330 C700 330 900 330 930 260" stroke="#7a4cc2" stroke-width="1.6" fill="none" marker-end="url(#arn)"/>
+
+  <!-- inside each agent -->
+  <rect x="420" y="352" width="736" height="92" rx="9" fill="#eef2f8" stroke="#c9d0db"/>
+  <text x="436" y="378" class="h">Inside one agent (autopilot skill)</text>
+  <text x="436" y="402" font-size="13">plans a phase, drives cheap workers (pi + a cheap model), gets an independent review from</text>
+  <text x="436" y="422" font-size="13">another model, runs local tests and gates, opens one PR, fixes CI until green, stops and reports</text>
+
+  <!-- shared services -->
+  <rect x="24" y="500" width="520" height="130" rx="9" fill="#ffffff" stroke="#c9d0db"/>
+  <text x="40" y="528" class="h">GitHub: tensor4all/*</text>
+  <text x="40" y="552" font-size="13">Agents push branches and open PRs; issues are assigned to the</text>
+  <text x="40" y="572" font-size="13">maintainer when work starts. Only the orchestrator merges, and</text>
+  <text x="40" y="592" font-size="13">crates.io releases need the maintainer's explicit approval.</text>
+
+  <rect x="568" y="500" width="588" height="130" rx="9" fill="#ffffff" stroke="#c9d0db"/>
+  <text x="584" y="528" class="h">Shared state: a private git repository</text>
+  <text x="584" y="552" font-size="13">handoff.md (current state, approvals verbatim), one file per agent,</text>
+  <text x="584" y="572" font-size="13">a daily append-only worklog, the cron prompts. A new orchestrator</text>
+  <text x="584" y="592" font-size="13">session resumes from it after a crash or a full context.</text>
+
+  <path d="M788 446 V496" stroke="#5b6575" stroke-width="1.5" fill="none" marker-end="url(#ar)"/>
+  <text x="796" y="476" class="muted" font-size="12">PRs, state</text>
+  <path d="M149 446 V496" stroke="#5b6575" stroke-width="1.5" fill="none" marker-end="url(#ar)" marker-start="url(#ar)"/>
+  <text x="157" y="476" class="muted" font-size="12">review, merge</text>
+</svg>

From a225f7c6f61be37c6b007d1b4ecf2a37032c4f33 Mon Sep 17 00:00:00 2001
From: Hiroshi Shinaoka <shinaoka@mail.saitama-u.ac.jp>
Date: Thu, 29 Oct 2026 20:14:31 +0900
Subject: [PATCH 2/3] docs(agent-fleet): verified links for herdr and pi

The pi repository moved from badlogic/pi-mono to earendil-works/pi; herdr is herdrdev/herdr (herdr.dev).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/agent-fleet/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/agent-fleet/README.md b/docs/agent-fleet/README.md
index 8ba56a1..59e998d 100644
--- a/docs/agent-fleet/README.md
+++ b/docs/agent-fleet/README.md
@@ -20,7 +20,7 @@ The fleet has three levels.
   prompt, reviews and merges pull requests, and escalates decisions it should
   not take.
 - **Level 2: the machines.** Each remote machine runs
-  herdr, a terminal multiplexer for
+  [herdr](https://github.com/herdrdev/herdr), a terminal multiplexer for
   coding agents, with several agents in its panes. Agents are Claude Code
   sessions (Opus or Sonnet) or pi agents on cheaper models such as DeepSeek.
 
@@ -69,7 +69,7 @@ Check that `ssh host-a_vpn true` works without any prompt.
 
 ### 3. herdr
 
-Install herdr on each machine and start it there. On the laptop, register each
+Install [herdr](https://herdr.dev) (0.9.5 when this page was written) on each machine and start it there. On the laptop, register each
 machine once:
 
 ```sh
@@ -123,7 +123,7 @@ line shows that bypass permissions is on.
 
 ### 7. pi agents
 
-[pi](https://github.com/badlogic/pi-mono) runs agents on cheaper models. Two
+[pi](https://github.com/earendil-works/pi) runs agents on cheaper models. Two
 things differ from Claude Code.
 
 - A prompt sent while the agent is in a long tool call is queued. It runs only

From e2b81abcdbf4c8c2d116a35a22f6758a7e4d5b41 Mon Sep 17 00:00:00 2001
From: Hiroshi Shinaoka <shinaoka@mail.saitama-u.ac.jp>
Date: Thu, 29 Oct 2026 20:23:53 +0900
Subject: [PATCH 3/3] docs(agent-fleet): apply audit fixes and verify against
 tool docs

- SSH: passphrase key in ssh-agent/keychain, passphrase-less fallback,
  from="100.64.0.0/10" restriction, password login off.
- herdr: real install command, machine add behavior and labels, server
  lifecycle with an optional systemd user unit, documented command forms,
  pane split plus agent start example.
- GitHub: gh auth per machine, ruleset to enforce orchestrator-only merges,
  separate agent account, no crates.io token on agent hosts.
- pi: install, Node.js requirement, login, skill and session paths.
- Scheduled rounds (/loop, CronCreate) and their limits, Remote Control
  steps and requirements, cost and limits note.
- Skeleton handoff.md, monitoring.md entry, first orchestrator prompt.
- Consistent "a human plus two levels of agents" wording; SVG updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/agent-fleet/README.md       | 538 +++++++++++++++++++++++--------
 docs/agent-fleet/agent-fleet.svg |  28 +-
 2 files changed, 424 insertions(+), 142 deletions(-)

diff --git a/docs/agent-fleet/README.md b/docs/agent-fleet/README.md
index 59e998d..ca5c839 100644
--- a/docs/agent-fleet/README.md
+++ b/docs/agent-fleet/README.md
@@ -8,244 +8,526 @@ machines and budget.
 
 ## Architecture
 
-The fleet has three levels.
+The fleet is a human plus two levels of agents.
 
-- **Level 0: the human.** The maintainer decides, approves releases and gives
-  instructions in plain language. They talk only to the orchestrator. The
-  orchestrator session can also be continued from Claude Code on a phone, so
-  the maintainer can steer the fleet while away from the laptop. It is the same
-  session, not a second one.
+- **Level 0: the human.** You decide, approve releases and give instructions
+  in plain language. You talk only to the orchestrator. With Claude Code
+  [Remote Control](#remote-control-from-a-phone) you can also steer the same
+  orchestrator session from a phone. It is the same session, not a second
+  one.
 - **Level 1: the orchestrator.** One Claude Code session on a laptop. It runs
-  rounds on a cron schedule, reads each agent's screen, dispatches tasks by
+  rounds on a schedule, reads each agent's screen, dispatches tasks by
   prompt, reviews and merges pull requests, and escalates decisions it should
   not take.
-- **Level 2: the machines.** Each remote machine runs
-  [herdr](https://github.com/herdrdev/herdr), a terminal multiplexer for
-  coding agents, with several agents in its panes. Agents are Claude Code
-  sessions (Opus or Sonnet) or pi agents on cheaper models such as DeepSeek.
+- **Level 2: the machine agents.** Each remote machine runs
+  [herdr](https://herdr.dev/docs/), a terminal multiplexer for coding agents,
+  with several agents in its panes. Agents are Claude Code sessions (Opus or
+  Sonnet) or [pi](https://pi.dev) agents on cheaper models such as DeepSeek.
 
 Two shared services tie the levels together.
 
-- **GitHub.** Agents push branches and open pull requests. Issues are assigned
-  to the maintainer when work starts. Only the orchestrator merges.
+- **GitHub.** Agents push branches and open pull requests. When work on an
+  issue starts, the issue is assigned to yourself (the person running the
+  fleet). Only the orchestrator merges. See
+  [GitHub access](#5-github-access) for how to enforce this.
 - **A private state repository.** A small git repository holds the recovery
   state, so a new orchestrator session can take over at any time. See
   [Recovery state](#recovery-state).
 
 Each machine has a role. In the maintainer's fleet these are a quiet benchmark
-host, an implementation host with a GPU, and a many-core scaling host. Adding a
-machine adds a whole team of agents.
+host, an implementation host with a GPU, and a many-core scaling host. Adding
+a machine adds a whole team of agents.
 
 ## Reproduce the setup
 
 ### 1. Network
 
-Install [Tailscale](https://tailscale.com/) on the laptop and on every machine.
-The machines then reach each other on a private network and need no open ports
-on the public internet.
+Install [Tailscale](https://tailscale.com/) on the laptop and on every
+machine. The machines then reach each other on a private network and need no
+open ports on the public internet.
 
 ### 2. SSH key
 
-Create one dedicated ed25519 key without a passphrase. The orchestrator works
-unattended, so it cannot type a passphrase.
+The orchestrator connects without a human at the keyboard. A passphrase does
+not prevent this. Protect the key with a passphrase and load it into
+ssh-agent once. After that, every connection uses the loaded key without a
+prompt. herdr's own docs give the same advice for its background
+connections (see
+[Connecting machines](https://herdr.dev/docs/connecting-machines/)).
 
 ```sh
-ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519_fleet -C fleet
+ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_fleet -C fleet
 ```
 
-Add the public key to `~/.ssh/authorized_keys` on each machine. Use this key
-only for the tailnet. Give each machine a Host alias in `~/.ssh/config` on the
+On macOS, let the keychain hold the passphrase, so the key is loaded again
+after a reboot. Give each machine a Host alias in `~/.ssh/config` on the
 laptop:
 
 ```sshconfig
-Host host-a_vpn
+Host host-a
     HostName host-a.your-tailnet.ts.net
     User you
     IdentityFile ~/.ssh/id_ed25519_fleet
     IdentitiesOnly yes
+    AddKeysToAgent yes
+    UseKeychain yes
 ```
 
-Check that `ssh host-a_vpn true` works without any prompt.
+Then load the key once with `ssh-add --apple-use-keychain
+~/.ssh/id_ed25519_fleet`. `UseKeychain` exists only on macOS (see Apple's
+[TN2449][tn2449]);
+on Linux, drop that line and run `ssh-add` once per login.
+[`AddKeysToAgent`](https://man.openbsd.org/ssh_config.5) is standard
+OpenSSH.
+
+Fallback: a dedicated key without a passphrase (`ssh-keygen -N ""`). It
+needs no agent, but anyone who copies the file can log in to every machine.
+Use it only if the agent setup does not work for you, and restrict it as
+below.
+
+Restrict the key to the tailnet. Tailscale gives every device an address in
+[`100.64.0.0/10`](https://tailscale.com/kb/1015/100.x-addresses). In
+`~/.ssh/authorized_keys` on each machine, put the
+[`from=`](https://man.openbsd.org/sshd.8#from=) option before the key:
+
+```text
+from="100.64.0.0/10" ssh-ed25519 AAAA... fleet
+```
+
+Also turn off password login in `/etc/ssh/sshd_config`
+(`PasswordAuthentication no` and `KbdInteractiveAuthentication no`, see
+[sshd_config](https://man.openbsd.org/sshd_config.5)). Optionally, use
+[Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh) and
+[access rules](https://tailscale.com/kb/1018/acls) to decide which devices
+may connect to which machines.
+
+Check that `ssh host-a true` works without any prompt.
 
 ### 3. herdr
 
-Install [herdr](https://herdr.dev) (0.9.5 when this page was written) on each machine and start it there. On the laptop, register each
-machine once:
+Install herdr on the laptop
+([install docs](https://herdr.dev/docs/install/)):
 
 ```sh
-herdr machine add host-a_vpn
+curl -fsSL https://herdr.dev/install.sh | sh
+```
+
+Then register each machine once, in an interactive terminal on the laptop:
+
+```sh
+herdr machine add host-a
 herdr machine list
 ```
 
+`machine add` takes an SSH target, normally the Host alias from
+`~/.ssh/config`. It must run in an interactive terminal, because it may ask
+before it installs or replaces anything. If herdr is missing on the machine,
+it offers to install it there. It then starts the remote background server
+and saves a profile. The profile's label defaults to the SSH host without
+any `user@` prefix, here `host-a`. That label (or the profile id) is what
+`--machine` accepts. An arbitrary hostname does not work. Add
+`--label <name>` to choose another label. See
+[Connecting machines](https://herdr.dev/docs/connecting-machines/).
+
+The remote server ignores SIGHUP, so it keeps running after your SSH session
+ends ([Persistence](https://herdr.dev/docs/persistence-remote/)). Nothing
+restarts it after a reboot. A reboot also ends the agents in its panes;
+herdr restores the saved layout, not the running processes
+([Session state](https://herdr.dev/docs/session-state/)). If a machine
+reboots often, run the server under systemd. The CLI reference provides
+`herdr server` for this: it "runs the headless server explicitly" for
+supervised setups. A minimal user unit, `~/.config/systemd/user/herdr.service`
+on the machine:
+
+```ini
+[Unit]
+Description=herdr server
+
+[Service]
+ExecStart=%h/.local/bin/herdr server
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+Adjust the path to the output of `command -v herdr`. Enable it with
+`systemctl --user enable --now herdr.service`, and run
+[`loginctl enable-linger`][loginctl]
+once so the user manager starts at boot. Panes inherit the service
+environment, so add `Environment=` lines if tools are missing from `PATH`.
+Enable the unit before `machine add`, or stop the server that `machine add`
+started (`herdr server stop` on the machine) before you enable it. herdr's
+docs do not ship such a unit. Treat it as a starting point.
+
 Adding and removing machines is the human's job. The orchestrator only uses
 machines that are already registered.
 
 ### 4. Orchestrator commands
 
-The orchestrator drives every machine with `herdr --machine <label> ...`. The
-commands it needs are few.
+The orchestrator drives every machine with `herdr --machine <label> ...`.
+These are the forms it needs, from the
+[CLI reference](https://herdr.dev/docs/cli-reference/). Put
+`herdr --machine <label>` in front of each one, except `machine status`. A
+target is an agent name or a pane id such as `w1:p2`.
 
 | Command | Use |
 |---|---|
-| `herdr --machine host-a_vpn agent list` | List the agents and their state. |
-| `herdr --machine host-a_vpn agent get <name>` | Show one agent's details. |
-| `herdr --machine host-a_vpn agent read <name>` | Read the agent's screen. |
-| `herdr --machine host-a_vpn agent prompt <name> "..."` | Send a task or an answer. |
-| `herdr --machine host-a_vpn agent send-keys <name> ...` | Send raw keys (Esc, Enter, Shift+Tab). |
-| `herdr --machine host-a_vpn agent start ...` | Start a new agent in a pane. |
-| `herdr --machine host-a_vpn agent rename <pane> <name>` | Name an agent. |
-| `herdr --machine host-a_vpn pane split ...` | Make room for another agent. |
+| `herdr machine status [<label>]` | Check SSH and the remote server. |
+| `agent list` | List the agents and their state. |
+| `agent get <target>` | Show one agent's details. |
+| `agent read <target> [--source recent-unwrapped] [--lines N]` | Read the agent's screen. |
+| `agent prompt <target> <text> [--wait] [--timeout MS]` | Send a task or an answer. |
+| `agent send-keys <target> <key> [key ...]` | Send keys such as `esc`, `enter`, `shift+tab`. |
+| `agent wait <target> [--until STATUS] [--timeout MS]` | Wait for `idle`, `done` or `blocked`. |
+| `agent rename <target> <name>` | Name an agent. |
+| `pane list` | List panes and their ids. |
+| `pane split <pane_id> --direction right\|down [--cwd PATH] [--no-focus]` | Make a pane for another agent. |
+| `agent start <name> --kind KIND --pane <pane_id> [-- <agent-args...>]` | Start an agent in an empty shell pane. |
+
+To start a new agent, first make a pane, then start the agent in it.
+`agent start` never creates panes. Use an absolute path for `--cwd`:
 
-Run `herdr --help` on your version for the exact arguments.
-
-A failed connection does not mean that a prompt was not delivered. Read the
-agent's screen before you send it again.
+```sh
+herdr --machine host-a pane list
+herdr --machine host-a pane split w1:p1 --direction right \
+  --cwd /home/you/src/tenferro-rs --no-focus
+# The JSON reply holds the new pane id in .result.pane.pane_id, say w1:p2.
+herdr --machine host-a agent start host-a-tenferro-impl --kind claude \
+  --pane w1:p2 -- --allow-dangerously-skip-permissions --model opus
+```
 
-### 5. Agent names
+For a pi agent, use `--kind pi` and pass pi's flags after `--`, for example
+`-- --model <provider>/<model-id>`.
+
+A failed connection or a timeout does not prove that a prompt was not
+delivered. herdr does not retry it either. Read the agent's screen before you
+send it again.
+
+### 5. GitHub access
+
+The agents need GitHub access on each machine. Run
+[`gh auth login`](https://cli.github.com/manual/gh_auth_login) there, or set
+`GH_TOKEN` to a
+[fine-grained token][gh-pat]
+(gh's docs prefer `GH_TOKEN` for fine-grained tokens). Then run
+[`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git) so
+`git push` uses the same credentials. herdr also documents SSH agent
+forwarding (`ForwardAgent yes`) for git inside remote panes. It lends your
+laptop's keys to every agent on that machine, so prefer a token.
+
+Enforce "only the orchestrator merges" on GitHub, not only in prompts.
+Merging a pull request needs the same "Contents: write" permission as
+pushing a branch
+([permissions table][gh-pat-perms]),
+so a token alone cannot allow pushes and forbid merges. Instead:
+
+- Give the agents a separate GitHub account with the Write role, and give
+  their tokens access to the needed repositories only. Never give them the
+  Admin role.
+- On each default branch, add a
+  [ruleset][gh-ruleset]
+  with "Restrict updates" and "Require a pull request before merging"
+  ([rules][gh-rules]).
+  Put only the role your own account holds, such as Maintain or Admin, on
+  the bypass list, set to "For pull requests only".
+- The orchestrator merges with your own account on the laptop.
+- Never run [`cargo login`][cargo-login]
+  on an agent machine. Keep the crates.io token on the laptop only.
+
+### 6. Agent names
 
 Name every agent `<machine>-<repo>-<role>[-<model>]`, for example
 `host-b-tenferro-impl` or `host-c-t4a-review-dsv4f`. Use lowercase letters,
-digits, `-` and `_`, and at most 32 characters. Claude agents may omit the
-model suffix. Names disappear when an agent exits, so check them on every
-round. Refer to agents by name, never by pane id.
+digits, `-` and `_`, start with a letter, and use at most 32 characters.
+Claude agents may omit the model suffix. Names disappear when an agent
+exits, so check them on every round. Refer to agents by name, never by pane
+id.
+
+### 7. Claude Code agents
+
+Start Claude agents with `agent start --kind claude`, as in
+[section 4](#4-orchestrator-commands), and pass Claude's flags after `--`:
+
+```sh
+-- --allow-dangerously-skip-permissions --model opus    # or sonnet
+```
+
+`--kind` runs herdr's own `claude` executable, so your shell aliases do not
+apply. Pass the flags in full.
+[`--allow-dangerously-skip-permissions`][cc-cli]
+adds bypass mode to the Shift+Tab cycle without starting in it. When the
+agent starts, accept any startup dialog, then send `shift+tab` until the
+status line shows that bypass permissions is on. Read the
+[permission modes](https://code.claude.com/docs/en/permission-modes) page
+first, and use bypass mode only on machines you control.
 
-### 6. Claude Code agents
+### 8. pi agents
 
-Start Claude agents with:
+[pi](https://github.com/earendil-works/pi) runs agents on cheaper models.
+Install it on each machine
+([quickstart][pi-quickstart]):
 
 ```sh
-claude --allow-dangerously-skip-permissions --model opus    # or sonnet
+curl -fsSL https://pi.dev/install.sh | sh
 ```
 
-herdr does not apply your shell aliases, so pass the flags in full. When the
-agent starts, accept the bypass dialog, then press Shift+Tab until the status
-line shows that bypass permissions is on.
+pi needs Node.js 22.19 or newer. The installer can install Node.js if it is
+missing. Update later with `pi update`.
 
-### 7. pi agents
+Log in once: start `pi` and run `/login`, or export the provider's key, for
+example `DEEPSEEK_API_KEY`
+([providers][pi-providers]).
+`/login` saves credentials in `~/.pi/agent/auth.json`. Keep that file
+private.
 
-[pi](https://github.com/earendil-works/pi) runs agents on cheaper models. Two
-things differ from Claude Code.
+pi loads skills from `~/.pi/agent/skills/`, from `.pi/skills/` in the
+project, and from the shared `~/.agents/skills/` and `.agents/skills/`
+([skills][pi-skills]).
 
-- A prompt sent while the agent is in a long tool call is queued. It runs only
-  after the tool call ends. For an urgent prompt, send Esc first, then the
-  prompt and Enter.
+Two things differ from Claude Code.
+
+- A prompt sent while the agent is in a tool call waits until that tool call
+  ends. For an urgent prompt, send `esc` first (it aborts the run), then the
+  prompt.
 - The screen shows little history. Read the session log instead, in
-  `~/.pi/agent/sessions/*/*.jsonl` on that machine.
+  `~/.pi/agent/sessions/*/*.jsonl` on that machine
+  ([sessions][pi-sessions]).
 
-### 8. Model policy
+### 9. Model policy
 
 Use Sonnet or a cheap model for simple work: docs, mechanical edits, running
 benchmarks, collecting logs. Use Opus for complex coding, reviews and
-judgment calls. The orchestrator itself runs on the strongest model you have.
+judgment calls. The orchestrator itself runs on the strongest model you
+have.
+
+### 10. Scheduled rounds
+
+The orchestrator's rounds are Claude Code
+[scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks). Start
+one with `/loop`, for example `/loop 30m <round prompt>`, or ask Claude to
+schedule it; Claude then uses the `CronCreate` tool. Know the limits:
+
+- The tasks belong to that one session. They fire only while that `claude`
+  process runs and is idle.
+- Recurring tasks expire 7 days after creation.
+- The laptop must stay awake. On macOS, `caffeinate -i` keeps it from
+  sleeping while it runs.
+- `claude --resume` restores unexpired tasks, but not a self-paced `/loop`.
+
+Keep every round prompt and its schedule in `monitoring.md` (see
+[Recovery state](#recovery-state)). After a new session, after a resume, or
+before the 7 days are up, recreate the tasks from that file.
+
+### 11. Remote Control from a phone
+
+To steer the orchestrator from a phone, use Claude Code
+[Remote Control](https://code.claude.com/docs/en/remote-control).
+
+1. In the orchestrator session, run `/remote-control`. Or start the session
+   with `claude --remote-control`.
+2. On the phone, open the Claude app, tap Code, and pick the session. Or
+   open `claude.ai/code` in a browser.
+
+Remote Control needs a Pro, Max, Team or Enterprise plan and a claude.ai
+login. API keys do not work. On Team and Enterprise, an Owner must turn it
+on first. The session still runs on the laptop, so the laptop and the
+`claude` process must keep running.
+
+### 12. Cost and limits
+
+An Opus orchestrator on a 10-minute round, plus several Claude agents, uses
+up subscription limits quickly. pi agents bill per token through the
+provider's API key. Start with 2 or 3 agents and a 30-minute round. Shorten
+the round and add agents once you know your usage.
 
 ## Orchestrator operating rules
 
 These are the rules the maintainer's orchestrator follows. Write your own
 version into the orchestrator's instructions.
 
-- **Rounds.** Run a round every 10 minutes: read every agent, unblock or
-  redirect, merge what is ready. Twice an hour, check overall progress against
-  the TODO queue.
-- **Issue patrol.** Once an hour, scan the tracked repositories for new issues
-  and comments.
-- **Daily checks.** Update the tools (Claude Code, pi, herdr and build caches)
-  on every machine. Read the issue trackers of upstream projects you depend on.
-- **Approval dialogs.** Never answer an agent's approval dialog on its behalf.
-  Report it to the human instead. The only exceptions are dialogs agreed in
-  advance, such as folder trust, a model switch, or accepting bypass
-  permissions at startup.
-- **Releases.** Publish to crates.io only after the maintainer approves that
-  release explicitly in the conversation.
-- **GPU work.** Validate tenferro GPU changes on a local GPU and mark the PR
-  with a label, instead of running paid GPU CI.
-- **Issue assignment.** When an agent starts on an issue, assign it to the
-  maintainer. This avoids duplicate work with outside contributors.
+- **Rounds.** In each round, read every agent, unblock or redirect, and merge
+  what is ready. The maintainer uses a 10-minute round; see
+  [Cost and limits](#12-cost-and-limits) before you copy that. Twice an
+  hour, check overall progress against the TODO queue.
+- **Issue patrol.** Once an hour, scan the tracked repositories for new
+  issues and comments.
+- **Daily checks.** Update Claude Code (`claude update`), pi (`pi update`)
+  and herdr (`herdr update`) on every machine. Read the issue trackers of
+  upstream projects you depend on.
+- **Approval dialogs.** Never answer an agent's approval dialog on its
+  behalf. Report it to the human instead. The only exceptions are dialogs
+  agreed in advance, such as folder trust, a model switch, or accepting
+  bypass permissions at startup.
+- **Releases.** Publish to crates.io only after you approve that release
+  explicitly in the conversation.
+- **GPU work.** Validate GPU changes on a local GPU instead of running paid
+  GPU CI.
+- **Issue assignment.** When an agent starts on an issue, assign the issue to
+  yourself (the person running the fleet). This avoids duplicate work with
+  outside contributors.
 - **Merging.** Use a merge commit when the branch contains other people's
   commits, so their authorship is kept.
 - **Benchmarks.** Measure on a quiet host with CPU boost off. See
   [`rules/benchmark`](../../rules/benchmark/index.md).
-- **Approvals.** Record every approval verbatim, with its date, in the
+- **Approvals.** Record every approval word for word, with its date, in the
   handoff file.
 
 ## Recovery state
 
 A long orchestrator session dies or fills its context sooner or later. The
-recovery state lets a fresh session take over in a few minutes. Keep it in a
-private git repository that every machine can push to.
+recovery state lets a fresh session take over in a few minutes. Keep it in
+a private git repository that every machine can push to.
 
 ```text
 state/<project>/
   handoff.md            written only by the orchestrator
-  monitoring.md         the exact cron prompts and schedules
+  monitoring.md         round prompts and their schedules
   agents/<name>.md      each agent writes only its own file
   worklog/<date>.md     append-only, anyone
 ```
 
-- `handoff.md` is rewritten, not appended, on every change. It lists the
-  machines, the agents and their tasks, in-flight PRs, tracked issues, pending
-  decisions, approvals (verbatim, with dates), standing rules, and the ordered
-  TODO queue.
-- `agents/<name>.md` holds one agent's task, branch and worktree, last step,
-  next step and blockers. One writer per file means agents on different
-  machines never conflict.
-- `worklog/<date>.md` records dated events: merges, releases, decisions with
-  their source, incidents.
-- `monitoring.md` holds the exact cron prompts, so a new session can recreate
-  the loops without guessing.
-
-To resume after a crash or a full context:
-
-1. Read `handoff.md`, then every `agents/*.md`, then the last two worklog
-   files.
-2. Check each listed agent with `agent get` and `agent read`, and each listed
-   PR, before acting. The files can be one update behind.
-3. Recreate the cron loops from `monitoring.md`.
+- `handoff.md` is the current picture of the fleet. The orchestrator
+  replaces its content whenever something changes, instead of adding to the
+  end. See the skeleton below.
+- `agents/<name>.md` belongs to one agent. It says what the agent works on,
+  where (branch and worktree), what it did last, what it does next, and what
+  blocks it. Only that agent writes the file, so agents on different
+  machines never edit the same file.
+- `worklog/<date>.md` is a dated diary. Anyone may add a line about a merge,
+  a release, an incident, or a decision and who made it. Nobody edits old
+  lines.
+- `monitoring.md` keeps each scheduled prompt word for word, with its
+  schedule, so a new session can set up the same rounds.
+
+A skeleton `handoff.md`:
+
+```markdown
+# Handoff
+
+## Machines
+- host-a: benchmark host, quiet, boost off
+
+## Agents
+- host-a-tenferro-bench: running the einsum benchmark for PR #123
+
+## Open PRs
+- tenferro-rs#123: CI green, waiting for benchmark numbers
+
+## Tracked issues
+- tenferro-rs#100: next after #123 merges
+
+## Waiting for the human
+- Whether to drop the old API in the next minor release
+
+## Approvals
+- 2026-01-15: "Release 0.3.0 to crates.io." (approved in chat)
+
+## Standing rules
+- Never run paid GPU CI.
+
+## TODO queue
+1. Merge #123 after the benchmark.
+```
+
+An example `monitoring.md` entry:
+
+```markdown
+## Round (every 30 minutes)
+/loop 30m Read state/myproject/handoff.md. For each agent listed there, run
+`herdr --machine <label> agent read <name> --lines 80`.
+Unblock or redirect agents, merge PRs that are ready, then update handoff.md.
+```
+
+A short first prompt for a new orchestrator session:
+
+```text
+You are the orchestrator for this fleet. Read state/myproject/handoff.md,
+every file in state/myproject/agents/, and the last two worklog files. Check
+each agent with herdr agent get and agent read, and each open PR with gh,
+before you act. Then recreate the rounds in state/myproject/monitoring.md
+and report what you found.
+```
+
+To take over after a crash or a full context:
+
+1. Read the handoff file first. Then read each agent's file, then the two
+   most recent worklogs.
+2. Before you act, check the real state: each agent with `agent get` and
+   `agent read`, and each open PR on GitHub. The files may miss the latest
+   change.
+3. Set up the scheduled rounds again from `monitoring.md`.
 
 ## How the maintainer's rule set is built
 
 The maintainer's own rules are private, but their structure is easy to copy.
 There are four layers.
 
-1. **Global instructions** in `~/.claude/CLAUDE.md`. Personal preferences that
-   hold in every project: the response language, preferred tools (for example
-   CodeGraph before grep), and limits on remote control (which herdr commands
-   the session may run, and that it never answers another agent's approval
-   dialog).
+1. **Global instructions** in `~/.claude/CLAUDE.md`. Personal preferences
+   that hold in every project: the response language, preferred tools (for
+   example CodeGraph before grep), and limits on remote control (which herdr
+   commands the session may run, and that it never answers another agent's
+   approval dialog).
 2. **Per-repository `AGENTS.md`.** Each tensor4all repository keeps a short
    `AGENTS.md` that points to this repository for shared rules and adds only
    repository-specific ones.
-3. **Claude Code auto-memory.** A memory directory with one fact per file and
-   an index file that lists them all, one line each. Each fact has a type:
-   user, feedback, project or reference. Feedback and project entries carry a
-   "Why" line and a "How to apply" line, so the rule can be judged later
-   rather than followed blindly.
+3. **Claude Code auto-memory.** A memory directory with one fact per file
+   and an index file that lists them all, one line each. Each fact has a
+   type: user, feedback, project or reference. Feedback and project entries
+   carry a "Why" line and a "How to apply" line, so the rule can be judged
+   later rather than followed blindly.
 4. **A private advisor repository.** It holds:
-   - **Skills.** An `autopilot` skill runs one issue or phase alone. It plans
-     the phase, drives cheap workers through pi with helper scripts (a
-     supervisor such as `supervise.sh` and a worker launcher such as
-     `pi_worker.sh`), gets an independent review from a different model, opens
-     one PR and fixes CI until it is green. A `build-profile` skill builds the
-     decision profile below.
-   - **A decision profile.** `profile/rules.md` holds rules, and a precedents
-     file holds short past decisions with a pointer to their source. The
-     `build-profile` skill mines past transcripts and worklogs for decisions
-     that recur, and turns them into rules. Rules that came from the
-     maintainer directly are never weakened by a rebuild.
+   - **Skills.** Claude Code loads personal skills from
+     `~/.claude/skills/<name>/SKILL.md` and project skills from
+     `.claude/skills/<name>/SKILL.md`
+     ([skills](https://code.claude.com/docs/en/skills)). An `autopilot`
+     skill runs one issue or phase alone. It plans the phase, drives cheap
+     workers through pi with a supervisor script and a worker launcher, gets
+     an independent review from a different model, opens one PR and fixes CI
+     until it is green. A worker launcher can run pi without its UI, for
+     example `pi --print --model <provider>/<model-id> "<task>"`, or
+     `pi --mode json` for an event stream
+     ([pi CLI][pi-cli]).
+     A `build-profile` skill builds the decision profile below. These skills
+     are not published, so this page shows their shape, not their code.
+   - **A decision profile.** `profile/rules.md` holds rules, and a
+     precedents file holds short past decisions with a pointer to their
+     source. The `build-profile` skill mines past transcripts and worklogs
+     for decisions that recur, and turns them into rules. Rules that came
+     from the maintainer directly are never weakened by a rebuild.
    - **Proxy logs.** Every decision the autopilot takes on the maintainer's
      behalf is logged. The maintainer reviews and corrects them, and the
      corrections feed the next profile update.
-   - **The `state/` directory** described in [Recovery state](#recovery-state).
+   - **The `state/` directory** described in
+     [Recovery state](#recovery-state).
 
-Start small. A global `CLAUDE.md`, an `AGENTS.md` per repository and the state
-directory are enough for a fleet of a few agents. Add the profile when you
-notice that you answer the same questions again and again.
+Start small. A global `CLAUDE.md`, an `AGENTS.md` per repository and the
+state directory are enough for a fleet of a few agents. Add the profile when
+you notice that you answer the same questions again and again.
 
 ## Security notes
 
-- A passphrase-less key and bypass permissions are acceptable only on machines
-  you control, inside the tailnet. Do not reuse the key elsewhere.
+- Bypass permissions are acceptable only on machines you control, inside
+  the tailnet. Restrict the SSH key with `from=` as shown above, and do not
+  reuse it elsewhere.
+- Agent machines hold only a limited GitHub token and no crates.io token.
+  See [GitHub access](#5-github-access).
 - Keep secrets out of every file an agent can read: the state repository,
   worklogs, memory and prompts. Agents copy what they see into logs and PRs.
 - On a shared machine, other users' jobs come first. Check the load before
   starting builds or benchmarks, limit the cores your agents use, and never
   kill processes you do not own.
+
+[tn2449]: https://developer.apple.com/library/archive/technotes/tn2449/_index.html
+[loginctl]: https://www.freedesktop.org/software/systemd/man/latest/loginctl.html
+[gh-pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+[gh-pat-perms]: https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens
+[gh-ruleset]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository
+[gh-rules]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets
+[cargo-login]: https://doc.rust-lang.org/cargo/commands/cargo-login.html
+[cc-cli]: https://code.claude.com/docs/en/cli-reference
+[pi-quickstart]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md
+[pi-providers]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md
+[pi-skills]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md
+[pi-sessions]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/sessions.md
+[pi-cli]: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md
diff --git a/docs/agent-fleet/agent-fleet.svg b/docs/agent-fleet/agent-fleet.svg
index e7a248c..ccc7f74 100644
--- a/docs/agent-fleet/agent-fleet.svg
+++ b/docs/agent-fleet/agent-fleet.svg
@@ -1,4 +1,4 @@
-<svg viewBox="0 0 1180 660" width="1180" height="660" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Two-level agent fleet: a maintainer, on a laptop or a phone, talks to one orchestrator session; the orchestrator controls herdr on remote machines over Tailscale and SSH; each machine runs several agents that open pull requests on GitHub; shared state lives in a git repository.">
+<svg viewBox="0 0 1180 660" width="1180" height="660" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Two-level agent fleet: a human plus two levels of agents. The human talks to one orchestrator session on a laptop, or to the same session from a phone through Claude Code Remote Control. The orchestrator controls herdr on remote machines over Tailscale and SSH. Each machine runs several agents that open pull requests on GitHub. Shared state lives in a git repository.">
   <title>Two-level agent fleet</title>
   <defs>
     <marker id="ar" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#5b6575"/></marker>
@@ -17,7 +17,7 @@
   <!-- Level 0 -->
   <text x="24" y="34" class="lab" fill="#2f6fdb" style="fill:#2f6fdb">LEVEL 0: HUMAN</text>
   <rect x="24" y="46" width="250" height="92" rx="9" fill="#eef2f8" stroke="#2f6fdb" stroke-width="1.6"/>
-  <text x="40" y="74" class="h">Maintainer</text>
+  <text x="40" y="74" class="h">You (the human)</text>
   <text x="40" y="96" class="muted" font-size="13">Decides, approves releases,</text>
   <text x="40" y="114" class="muted" font-size="13">chats in plain language</text>
 
@@ -25,25 +25,25 @@
   <rect x="300" y="46" width="92" height="92" rx="9" fill="#eef2f8" stroke="#2f6fdb" stroke-width="1.4" stroke-dasharray="5 4"/>
   <rect x="333" y="56" width="26" height="42" rx="5" fill="#ffffff" stroke="#2f6fdb" stroke-width="1.4"/>
   <line x1="342" y1="93" x2="350" y2="93" stroke="#2f6fdb" stroke-width="1.4"/>
-  <text x="346" y="116" text-anchor="middle" font-size="12">Phone</text>
+  <text x="346" y="116" text-anchor="middle" font-size="11">Remote Control</text>
   <text x="346" y="131" text-anchor="middle" font-size="11" class="muted">same session</text>
   <path d="M274 92 H298" stroke="#2f6fdb" stroke-width="1.4" fill="none"/>
   <path d="M346 140 C346 170 220 168 200 190" stroke="#2f6fdb" stroke-width="1.4" stroke-dasharray="5 4" fill="none" marker-end="url(#ar)"/>
-  <text x="290" y="176" class="muted" font-size="11">remote control</text>
+  <text x="290" y="176" class="muted" font-size="11">from a phone</text>
 
   <!-- Level 1 -->
-  <text x="24" y="182" class="lab" style="fill:#0f8a6b">LEVEL 1: LAPTOP</text>
+  <text x="24" y="182" class="lab" style="fill:#0f8a6b">LEVEL 1: ORCHESTRATOR</text>
   <rect x="24" y="194" width="250" height="250" rx="9" fill="#ffffff" stroke="#0f8a6b" stroke-width="1.6"/>
   <text x="40" y="222" class="h">Orchestrator session</text>
   <text x="40" y="242" class="muted" font-size="13">Claude Code on the laptop</text>
-  <text x="40" y="270" font-size="13">- Rounds every 10 min (cron)</text>
+  <text x="40" y="270" font-size="13">- Rounds on a schedule (/loop)</text>
   <text x="40" y="290" font-size="13">- Reads each agent's screen</text>
   <text x="40" y="310" font-size="13">- Dispatches tasks by prompt</text>
   <text x="40" y="330" font-size="13">- Reviews and merges PRs</text>
   <text x="40" y="350" font-size="13">- Escalates decisions upward</text>
-  <text x="40" y="378" class="mono">herdr --machine host-a_vpn \</text>
+  <text x="40" y="378" class="mono">herdr --machine host-a \</text>
   <text x="40" y="396" class="mono">  agent read|prompt NAME</text>
-  <text x="40" y="424" class="mono">ssh host-c_vpn ...</text>
+  <text x="40" y="424" class="mono">ssh host-c ...</text>
 
   <path d="M149 138 V192" stroke="#5b6575" stroke-width="1.5" fill="none" marker-end="url(#ar)" marker-start="url(#ar)"/>
 
@@ -53,11 +53,11 @@
   <text x="346" y="312" text-anchor="middle" font-size="12.5" class="muted">private</text>
   <text x="346" y="328" text-anchor="middle" font-size="12.5" class="muted">network</text>
   <text x="346" y="356" text-anchor="middle" font-size="12.5" class="muted">+ SSH key,</text>
-  <text x="346" y="372" text-anchor="middle" font-size="12.5" class="muted">no passphrase</text>
+  <text x="346" y="372" text-anchor="middle" font-size="12.5" class="muted">in ssh-agent</text>
   <path d="M274 319 H298" stroke="#7a4cc2" stroke-width="1.6" fill="none" marker-end="url(#arn)"/>
 
   <!-- Level 2 hosts -->
-  <text x="420" y="34" class="lab" style="fill:#b4581c">LEVEL 2: REMOTE MACHINES, EACH RUNNING HERDR</text>
+  <text x="420" y="34" class="lab" style="fill:#b4581c">LEVEL 2: MACHINE AGENTS, ONE HERDR PER MACHINE</text>
 
   <!-- host a -->
   <rect x="420" y="46" width="236" height="250" rx="9" fill="#ffffff" stroke="#b4581c" stroke-width="1.6"/>
@@ -108,14 +108,14 @@
   <!-- shared services -->
   <rect x="24" y="500" width="520" height="130" rx="9" fill="#ffffff" stroke="#c9d0db"/>
   <text x="40" y="528" class="h">GitHub: tensor4all/*</text>
-  <text x="40" y="552" font-size="13">Agents push branches and open PRs; issues are assigned to the</text>
-  <text x="40" y="572" font-size="13">maintainer when work starts. Only the orchestrator merges, and</text>
-  <text x="40" y="592" font-size="13">crates.io releases need the maintainer's explicit approval.</text>
+  <text x="40" y="552" font-size="13">Agents push branches and open PRs; issues are assigned to you</text>
+  <text x="40" y="572" font-size="13">when work starts. Only the orchestrator merges (a ruleset</text>
+  <text x="40" y="592" font-size="13">enforces it), and crates.io releases need your explicit approval.</text>
 
   <rect x="568" y="500" width="588" height="130" rx="9" fill="#ffffff" stroke="#c9d0db"/>
   <text x="584" y="528" class="h">Shared state: a private git repository</text>
   <text x="584" y="552" font-size="13">handoff.md (current state, approvals verbatim), one file per agent,</text>
-  <text x="584" y="572" font-size="13">a daily append-only worklog, the cron prompts. A new orchestrator</text>
+  <text x="584" y="572" font-size="13">a daily append-only worklog, the round prompts. A new orchestrator</text>
   <text x="584" y="592" font-size="13">session resumes from it after a crash or a full context.</text>
 
   <path d="M788 446 V496" stroke="#5b6575" stroke-width="1.5" fill="none" marker-end="url(#ar)"/>