Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

README: short, the selling points first, the detail in docs/

dee0ddcad74727e
diff --git a/.github/assets/screenshots/marp.png b/.github/assets/screenshots/marp.png
new file mode 100644
index 000000000..c8af4d576
Binary files /dev/null and b/.github/assets/screenshots/marp.png differ
diff --git a/.github/assets/screenshots/new-agent.png b/.github/assets/screenshots/new-agent.png
new file mode 100644
index 000000000..e67d539bd
Binary files /dev/null and b/.github/assets/screenshots/new-agent.png differ
diff --git a/.github/assets/screenshots/solid.png b/.github/assets/screenshots/solid.png
new file mode 100644
index 000000000..51c05ce30
Binary files /dev/null and b/.github/assets/screenshots/solid.png differ
diff --git a/README.md b/README.md
index a0011e638..42323674a 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,33 @@ https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c
# Harness
-Harness is a desktop app for agents that build things. Code, with Claude Code, Codex, Cursor and
-eleven more. PCBs, with Copper. 3D parts, with Solid. Keynotes, with Marp. One window, every machine
-you own. Each agent is a persistent terminal on the machine it runs on, and for the domains beyond
-code, a viewer beside it shows the work as it is made.
+Agents that build things, in one window. Code with Claude Code, Codex, Cursor and eleven more. PCBs
+with Copper. 3D parts with Solid. Keynotes with Marp. Every agent runs in a persistent terminal on
+any machine you own, and the domains beyond code get a viewer beside it that shows the work as it
+is made.
+
+<p align="center">
+ <img src=".github/assets/screenshots/marp.png" width="960" alt="A Marp tab: the keynote in the viewer on the left, the Claude Code agent that wrote it on the right, ten slides and Ready in the header">
+</p>
+
+## Why Harness
+
+- **More than code.** Copper (PCB), Solid (3D design) and Marp (Slides) sit beside the coding
+ agents. One prompt, and the pane fills with the board, the part, the keynote while the agent works.
+- **Your agents, unwrapped.** Fourteen engines. Harness reads the transcript each one already writes
+ and installs the vendor's own hooks; it never wraps a CLI. Credentials stay in your `~/.claude`,
+ `~/.codex`, and so on.
+- **Sessions that outlive the laptop.** Every agent is a tmux pane on its machine, kept by a small
+ daemon. Close the lid, open it on the train: same pane, same scrollback. After a reboot the daemon
+ brings each one back with the engine's own `--resume`.
+- **Every machine, no SSH.** Laptop, the Mac mini at home, the box in the rack, side by side. Each
+ machine dials out; nothing to open; encrypted end to end through a relay that holds no keys.
+- **Built for the keyboard.** ⌘N for a new agent, ⌘O to find anything, ⌘B to say what you want and
+ have it land on the right agent. Every key remappable in one file.
+- **A device for the desk.** A round USB display with your agents as tiles, their questions
+ answerable with a tap, and a voice turn a double-tap away.
+
+## Harnesses
| Harness | You say | You get | You watch |
|---|---|---|---|
@@ -13,18 +36,19 @@ code, a viewer beside it shows the work as it is made.
| **Copper** · PCB | "a USB-C powered ESP32 sensor board" | a fab-ready board, ordered in a click | the board, its checks, the fab |
| **Solid** · 3D design | "an iPhone case with a lanyard loop" | a printable STEP part | the model: Build, Fit, Print, Review |
| **Marp** · Slides | "a launch keynote for 200 engineers" | a keynote with art and speaker notes | the slides filling in, then Present |
-| **Yours** | | anything an agent can build in a folder | [add a domain harness](#add-a-domain-harness) |
+| **Yours** | | anything an agent can build in a folder | [build a harness](#extend-harness) |
-Every harness is the same thing to the app: a tile in New Agent, and a tab with the agent's terminal
-on the right, the domain's viewer on the left, and the pane header saying where the work is. The
-domain lives in its own git repository, installed on first use, never in Harness itself.
+<p align="center">
+ <img src=".github/assets/screenshots/solid.png" width="960" alt="A Solid tab: the 3D part in the viewer, the Codex agent that made it beside it, Ready in the header">
+</p>
-Each terminal is a tmux pane on the machine it runs on, kept there by a small daemon (`harness`).
-The window attaches to those panes, from this computer or from any other, with everything between
-machines encrypted end to end. Close the laptop, open it on the train: same pane, same scrollback.
-An optional USB device puts the same agents on your desk.
+Every harness is the same thing to the app: a tile in New Agent, a tab with the terminal on the
+right and the domain's viewer on the left, and a header that says where the work is. The domain
+lives in its own git repository, installed on first use, never in Harness itself.
-It drives the agents you already run:
+<p align="center">
+ <img src=".github/assets/screenshots/new-agent.png" width="720" alt="New Agent: choose a harness — Codex, Claude Code, OpenCode, and under More: Copper PCB, Solid 3D design, Marp Slides, Cursor, Pi, Hermes…">
+</p>
<p align="center">
<img src=".github/assets/engines/claude.png" height="72" alt="Claude Code" title="Claude Code">
@@ -66,33 +90,6 @@ And the harnesses for the domains beyond code, each on one of those agents:
<img src=".github/assets/engines/marp.png" height="72" alt="Marp · Slides" title="Marp · Slides, on Claude Code">
</p>
-## What you get
-
-- **Harnesses for more than code.** Copper (PCB), Solid (3D design) and Marp (Slides) sit beside the
- coding agents in New Agent. Pick one and the tab opens with the domain's viewer next to the
- terminal, the domain's skills in the agent, and its toolchain installed on the machine. Build your
- own from the starter in an afternoon: [Add a domain harness](#add-a-domain-harness).
-- **One window, N machines.** Panes from your laptop, the Mac mini at home and the box in the rack,
- side by side. Create sessions, make splits, move panes, change focus, zoom, pin, pick a layout.
-- **Remote persistent sessions.** Agents run in tmux on the machine. Disconnect, reconnect, same
- session. After a reboot the daemon recreates each pane with the engine's own `--resume` and the same
- agent id, so the window comes back exactly as it was.
-- **No SSH, no VPN, no open ports.** Every machine dials out to the relay over a WebSocket. A terminal
- is promoted to a direct WebRTC data channel between the two ends when ICE succeeds, and stays on the
- relay when it doesn't. The relay holds no key material and forwards ciphertext.
-- **Remote directory lists and clone.** Start a session on another machine by browsing its filesystem
- from the New Agent dialog, or clone a repository into a folder there first.
-- **Keyboard first.** A full default keymap, one-to-four-stroke sequences, a JSONC keymap file that
- live-reloads, and a command palette over every action. Native macOS menus follow the same keymap.
-- **Agent-aware terminals.** Turn boundaries, the agent's own questions (`AskUserQuestion` and the
- engines' equivalents) surfaced and answerable from the window or the device, per-turn recaps,
- model and effort, subscription usage windows.
-- **Boss mode (⌘B).** Type or say what you want. A router picks the agent already on it from the
- agents' names and their last recaps, and the text lands in that pane.
-- **Fourteen engines, one rule.** Harness never wraps an agent. It reads the transcript the agent
- already writes and installs the vendor's own hooks or plugin to learn when a turn starts and ends.
- Your credentials stay in your `~/.claude`, `~/.codex`, and so on.
-
## Install
**macOS 12+ (Apple Silicon and Intel), Linux (Ubuntu 22.04+).** Download the app from
@@ -117,489 +114,64 @@ One thing to know from the start: **the daemon only knows about panes it created
from the app or the web are tmux sessions named `harness-*`, owned by the daemon. A `claude` you launch
by hand in your own tmux is not picked up.
-## The app
-
-### Sessions
-
-An agent is one engine process in one tmux pane on one machine. The app calls it a harness. A tab
-holds any number of panes, from any mix of machines; the app remembers tabs, pane placement, sizes,
-pinned slots, focus and zoom across restarts, in `~/.harness/desktop-app-v2/state.json`.
-
-**New Harness (⌘N)** asks for four things: the machine, the working folder, the engine, and,
-under Advanced, two settings most people never touch. The folder picker is the native panel on this
-computer and a remote directory list on any other machine, served over the daemon's `fs_list_dir`.
-**Clone repository** clones a GitHub URL into a parent folder first. The engine row shows every engine
-the machine has, probes availability live, and marks the ones the daemon would install on first
-launch. Advanced holds the engine's permission-bypass flag (`--dangerously-skip-permissions`,
-`--dangerously-bypass-approvals-and-sandbox`, `--force`, `--auto`, whichever the engine has) and,
-for Codex, a profile: a `CODEX_HOME` folder to launch under instead of `~/.codex`, each with its own
-hooks.
-
-Creation carries a receipt. If the reply is lost, the button turns into **Check status** rather than
-creating a second session.
-
-Closing a pane is a view operation; the agent keeps running. **Stop Harness** ends the engine process
-and asks first. **Restart Harness** relaunches it in the same pane with the same id, resuming the
-conversation where the engine supports it.
-
-**Open Harness (⌘O)** is the search: agents, tabs, projects, machines, history and commands, fuzzy
-matched, with a session preview on the right built from cached recent turns. Type `>` for commands
-only (also ⇧⌘P).
-
-### Panes and layouts
-
-Hover the right or bottom edge of a pane for a split control, or ⌘R and ⌘D to split right and down;
-both open the same picker at that position. Drag a pane's header onto another pane to swap them.
-Resize grips live in the gaps and appear on hover or keyboard focus; sizes are remembered per pane
-count.
-
-**Layout (⌘S)** opens a palette of drawn shapes rather than names: Split, Columns, Rows, Main
-left/right/top/bottom, Grid, 2 to 5 columns, Middle + sides, Two over three, Auto. Press ⌘S again to
-cycle, a digit to pick directly, Enter to apply. A pinned pane keeps its slot when other panes close
-around it.
-
-### Keyboard
-
-The defaults, in the workspace:
-
-| Keys | Action |
-|---|---|
-| ⌘N | New Harness |
-| ⌘O | Open Harness — search sessions, tabs, machines, history; `>` for commands |
-| ⇧⌘P | Command palette |
-| ⌘B | Boss mode: describe a task, it picks the agent |
-| ⌘T · ⌘W · ⇧⌘T · ⇧⌘R | New tab · close tab · reopen last closed · rename tab |
-| ⌘1 … ⌘9 | Select tab by position |
-| ⇧⌘] · ⇧⌘[ · ⌃Tab · ⌃⇧Tab | Next · previous tab |
-| ⌘] · ⌘[ · ⌘Y | Forward · back through visited harnesses · full history |
-| ⌘H ⌘J ⌘K ⌘L · ⌘arrows | Focus the pane left · below · above · right |
-| ⇧⌘arrows | Move the focused pane |
-| ⌘R · ⌘D | Split right · split down |
-| ⌘⏎ · ⌘; · ⇧⌘W | Zoom or restore · last pane · close pane |
-| ⌘S | Layout palette |
-| ⌘F · ⌘G · ⇧⌘G | Find in terminal · next · previous match |
-| ⇧⌘I | Harnesses needing input |
-| ⌘, · ⌘/ | Settings · keyboard shortcuts |
-
-In a picker: ↓ ⌃N ⌃J and ↑ ⌃P ⌃K move, ⏎ opens, ⌘⏎ adds the result as a pane here, Esc or ⌃G closes.
-The terminal keeps ⌘C, ⌘V, ⌘A, Esc, ⌥⏎ and ⌃C for itself. `pane.pin`, `pane.focus_1…9`,
-`pane.resize`, `pane.reset_sizes`, `machine.link` and a few others ship unbound and are in the palette.
-
-Remap anything in `~/.config/harness/keybindings.jsonc` (`$XDG_CONFIG_HOME` respected). The file is
-JSONC: `{ "version": 1, "bindings": [{ "keys": "cmd+k cmd+l", "command": "pane.focus_right",
-"when": "workspace" }] }`. Sequences are one to four strokes; `"command": null` unbinds a key or a
-whole prefix; `when` is `workspace`, `terminal` or `picker`. The file is watched and reloaded on save;
-a bad edit keeps the last good keymap and says what was wrong. **Keyboard shortcuts (⌘/)** lists the
-effective bindings and **Open keyboard config** writes a commented template with every command id.
-
-### Terminal
-
-The renderer is a vendored, patched [xterm](desktop/third_party/xterm). Each pane has its own find bar
-(⌘F). ⌘-click opens links; an image or video path in the output opens in a preview, downloaded from
-the remote machine over the existing encrypted connection with progress and cancel (up to 512 MiB).
-Paste or drop an image onto a pane to send it to the agent. On a remote machine a composer box under
-the pane batches a message instead of paying a round trip per keystroke. Scrollback is restored from
-the daemon's snapshots on attach, resize, zoom and reconnect. Font, size (⌘0, ⌘+, ⌘-), terminal
-colours and six app palettes are in Settings.
-
-### Attention, models, usage
-
-When an agent asks a question the pane gets an amber ring, the titlebar bell lights, and ⇧⌘I lists
-every harness waiting on you. Answers go back into the engine's own dialog; there is no side channel.
-
-The **Models** menu shows each engine's subscription usage window, refreshed once a minute, for local
-and remote machines alike. Settings ▸ Usage is a separate token ledger read from Claude's and Codex's
-transcripts and OpenCode's database, off per provider until you switch it on.
-
-### Machines
-
-The app talks to the daemon on this computer over a loopback socket and never dials the relay itself.
-Other machines are reached through that daemon: it links to them with a per-machine remote password,
-terminates the encryption locally, and hands the app plaintext. Machines ▸ Link Machine… runs the
-link flow; the CLI equivalent is under [The daemon and CLI](#the-daemon-and-cli).
-
-## How it works
-
-```
- ( ◉ ) Harness device (USB)
- │
- ┌─────────── this computer ───────────┐
- │ Harness app ── loopback ──▶ harness daemon ──▶ tmux ──▶ claude · codex · … │
- └──────────────────────────────┬──────┘
- │ WebSocket (E2EE)
- ╔═════════╧═════════╗
- ║ Harness Relay ║ store and forward, no keys
- ╚═════════╤═════════╝
- ┌───────────────────────┼───────────────────────┐
- your server your platform harness.autonomous.ai
- harness daemon your HTTP API the web client
- tmux · hermes · muse (provider) (paired browser)
- ▲
- └── terminal traffic goes direct over WebRTC when ICE succeeds
-```
+## First five minutes
-**The daemon** runs detached under your account. Every five seconds it reconciles the `harness-*`
-tmux sessions with its registry; a pane has to be missing on two scans before its agent is marked
-gone. It tails each agent's transcript with a byte offset (JSONL for most engines, SQLite for
-OpenCode, Kilo, Hermes and Devin) and turns lines into a normalized event stream: turn started,
-tool call, sub-agent, question, turn ended. Hooks it installs into the vendor CLI tell it about
-session start, prompt submit and stop. Every five minutes it re-reads engine configs and pane
-footers to keep model and effort right. On start it restores panes that died with the tmux server,
-and it self-updates from a signed manifest, swapping the bundle atomically.
-
-**The session model.** The registry (`~/.harness/cli/data/registry.json`, mode 0600) is the source of
-truth for agents: engine, working directory, tmux pane, bound transcript, process identity. Layouts
-belong to the app. The relay stores machine records, agent names and daily counters, never a
-transcript, a recap or a keystroke.
-
-**Transport.** Each daemon holds one WebSocket to the relay, authenticated with its SSO token.
-Terminal bytes ride a binary channel on that socket until a WebRTC data channel negotiates, then move
-to it. Encryption is on for every path and has no switch:
-
-- **Ed25519** identity keys, pinned at first pairing and signing every ephemeral after it.
-- A **CPace-style PAKE** over ristretto255 — the six-character pairing code bootstraps a shared secret
- across the untrusted relay, and an attacker gets one online guess.
-- **X25519** ephemeral Diffie–Hellman per connection, through HKDF to pairwise session keys.
-- A **per-process group key** so one event encrypts once for many readers.
-- **ChaCha20-Poly1305** on every frame, with the associated data binding frame type and session.
-
-The crypto core lives in [`cli/src/lib/e2ee/`](cli/src/lib/e2ee/) and is a byte-identical twin of the
-browser's copy, with a drift-guard test and committed self-vectors.
-
-## The daemon and CLI
-
-`harness` is one pure-JS bundle run by the managed Node under `~/.harness/cli`. Everything below
-works the same on a headless Linux server; the app is not required on a machine, only the daemon.
-
-| Command | What it does |
-|---|---|
-| `harness login [--force] [--json]` | Browser SSO; save this computer's session. `--force` signs in as a different account. `--json` emits NDJSON for GUI clients. |
-| `harness start [-f] [--repair]` | Start the daemon from the saved session. `-f` runs in the foreground for a supervisor. `--repair` re-verifies the managed Node runtime. |
-| `harness stop` · `harness logout` · `harness reset` | Stop the daemon · stop and clear the SSO session · stop and clear all local state. |
-| `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. |
-| `harness machines [list] [--json]` · `harness machines delete <id>` | This account's machines · remove another machine (never this one). |
-| `harness pair <code>` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. |
-| `harness browser-link` | Print a reusable seven-day setup link for browsers. |
-| `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. |
-| `harness link connect <id> [--name=<label>]` · `harness link list` · `harness link unlink <id>` | Let this machine reach another of yours, terminating E2EE here; list; unlink. |
-| `harness grid login [--force] [--json]` · `harness grid logout` | Sign the `grid` CLI in with this computer's account, no second browser. |
-| `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. |
-| `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |
-
-Interactive prompts read one line from stdin with `--stdin`; `--json` switches any of them to NDJSON.
-
-The daemon also serves a loopback dashboard at `http://127.0.0.1:18473`: health, this machine's
-fingerprint, paired clients, stop. It never renders a transcript. Configuration is environment
-variables (`BACKEND_WS_URL`, `WEB_URL`, `ADAPTER_DATA_DIR`, `ADAPTER_COMPUTER_ID`, `PORT`, and the
-per-engine home directories); [`cli/README.md`](cli/README.md) has the full table and the
-`.env.example`.
-
-## Automation
-
-The app is one client of the daemon. Anything on the same computer can be another: the loopback
-WebSocket at `ws://127.0.0.1:18473/api/local-ws` takes a `machine_select` frame first
-(`{ machineId, localProtocolVersion: 1 }`, no `Origin` header), then request frames with a `requestId`
-and answers them with `<type>_result`. Selecting one of your other machines proxies the request
-through this daemon's link to it.
-
-What it answers: `agents_list`, `agent_create`, `agent_restart`, `agent_retarget`, `agent_delete`,
-`agent_update`, `agent_recent`, `agent_files`, `agent_read_file` (text, or media in 128 KiB chunks),
-`fs_list_dir`, `engines_probe`, `codex_profiles_list`, `codex_profile_link`, `models_list`,
-`usage_read`, `question_response`, `voice_route`, `message`, `cancel`, and `terminal_open` for a
-binary terminal channel with scroll, resync and paste. The same frames travel from the web client
-over the relay.
-
-Engines report in over HTTP on the same port: `POST /api/hook/session-start`, `session-end`,
-`turn-start`, `turn-stop`, `tool-start`, authenticated by a per-install token the daemon writes into
-the hook it installs.
-
-There is no `harness new` or `harness split` today. Sessions are created and arranged through the app,
-the web client, or this socket.
-
-## Engines
-
-| Engine | Binary | How Harness follows it | Resume | Permission bypass | Grid |
-|---|---|---|---|---|---|
-| Claude Code | `claude` | hooks in `~/.claude/settings.json` + JSONL transcript | `--resume` | `--dangerously-skip-permissions` | yes |
-| Codex | `codex` | `hooks.json` per `CODEX_HOME` + JSONL rollouts | `resume` | `--dangerously-bypass-approvals-and-sandbox` | yes |
-| Cursor | `cursor-agent` | `~/.cursor/hooks.json` + transcript | `--resume` | `--force` | — |
-| OpenCode | `opencode` | plugin + SQLite | `--session` | `--auto` | yes |
-| Pi | `pi` | extension + transcript | `--session` | — | yes |
-| Hermes | `hermes` | hooks + SQLite | `--resume` | — | yes |
-| Command Code | `cmd` | hooks + transcript | `--resume` | — | — |
-| Devin | `devin` | hooks + SQLite | — | — | — |
-| Muse Code | `muse` | transcript | `resume` | — | — |
-| Amp | `amp` | plugin writes the transcript Harness tails | `threads continue` | — | — |
-| Kilo | `kilo` | plugin + SQLite | `--session` | — | — |
-| Grok Build | `grok` | hooks + `updates.jsonl` | `--resume` | — | yes |
-| Antigravity | `agy` | hooks + transcript | `--conversation` | — | — |
-| GitHub Copilot | `copilot` | hooks + transcript | `--resume` | — | yes |
-
-A launcher that hands the pane to one of these is that engine: `ori claude` is a Claude Code agent,
-and the daemon reads the gateway off the live process so recaps and routing go through it too.
-
-**Grids.** An agent can be pointed at an [Autonomous Grid](https://www.autonomous.ai/grid) relay
-instead of the engine's own login, at creation or later with **Retarget**, which respawns the same
-pane with the grid's environment and `--resume`. The engines marked above support it; the key travels
-in the tmux session environment, never in argv or a file. Needs tmux ≥ 3.2.
-
-## The Harness device
-
-A round 466×466 AMOLED with touch and a far-field microphone, USB-C on the bottom edge. It has no
-WiFi and holds no credential. It is served entirely over the cable by the daemon on the computer it is
-plugged into; plugging it in is the authorization. The wire is one USB serial device (`303a:1001`),
-framed as `A5 5A | ver | type | len | payload | crc16` with a JSON vocabulary, a five-second ping,
-and a hard 8 KiB frame ceiling, specified in [`docs/specs/cable-protocol.md`](docs/specs/cable-protocol.md).
-
-What it shows: your agents as tiles in the order of the window's panes, with what each is doing and
-for how long; a wheel of your machines; the agent's own question when it asks one, answerable with a
-tap; the recap when a turn finishes, with one quiet tone. Scroll the face to scroll the terminal.
-Double-tap and speak to send a task: the audio goes to the daemon as PCM, comes back as a transcript,
-and Boss mode routes it. A voice turn can carry a mode — `/goal` runs an instruction to done,
-`/loop` on a schedule — adapted per engine; `/loop` is Claude Code only today.
-
-Firmware updates travel over the same cable in 16 KB credit windows, offered from the published
-metadata and never for a dev build. `harness flash` re-flashes a device from a USB port. The firmware
-is ESP-IDF ≥ 5.5 under [`device/esp32-circle/`](device/esp32-circle/) (`idf.py set-target esp32s3 &&
-idf.py build`); `make device-test` runs the host-side tests with no board attached.
+**⌘N** New Agent: a harness, a machine, a folder, Create. **⌘O** finds any agent, tab, project or
+machine, and `>` runs a command. **⌘B** takes a task in plain words and routes it to the agent
+already on it. **⌘R** and **⌘D** split, **⌘S** picks a layout, **⌘⏎** zooms a pane, **⇧⌘I** lists
+the agents waiting on you. The full keymap, and how to remap it: [docs/keyboard.md](docs/keyboard.md).
+The window in detail: [docs/app.md](docs/app.md).
## Extend Harness
-### Add your agent
+Every layer has a contract, a starter and a check.
-Two paths. Both are first-class and both are in this repo.
-
-| | **CLI engine** | **API provider** |
+| Add | Start at | The bar |
|---|---|---|
-| Your agent is | a command you run, anywhere `harness login` runs | a service on your own infrastructure |
-| You write | a normalizer in TypeScript, here | an HTTP endpoint, in any language |
-| You ship it | as a pull request to this repo | by deploying it yourself |
-| Start at | [`cli/src/engines/README.md`](cli/src/engines/README.md) | [`provider/`](provider/README.md) |
-
-A CLI engine touches about twenty shared files, and the engines README is that list in dependency
-order. The one rule: every field name, event kind and tool name comes from a real recorded session of
-the real binary, never inferred from another engine. If your agent writes nothing to disk, look at Amp:
-its plugin writes the transcript, and from there it is an ordinary engine.
-
-```bash
-cd cli && npm install && npm run typecheck && npm test # replay the recorded-session fixtures
-```
-
-An API provider implements eight JSON-RPC 2.0 methods over HTTPS with SSE for the one that streams:
-`agent.list`, `agent.send`, `agent.history`, `turn.cancel`, `agent.create`, `agent.rename`,
-`agent.delete`, `agent.recap`. No SDK, no discovery, no capability negotiation. The reference
-implementation ships the conformance runner; zero failures is the bar.
-
-```bash
-cd provider/reference-provider && npm install && npm run dev # http://127.0.0.1:4319
-npm run conformance -- --url https://your-endpoint --key <credential>
-```
-
-### Add a terminal multiplexer
-
-Harness watches tmux with nothing to configure. A second multiplexer is added beside tmux, not in
-place of it. Before writing code, confirm two things: a process inside a pane can identify that pane
-with a stable, multiplexer-namespaced id, and your tool's presence is detectable without running it,
-so a machine that lacks it pays nothing. Then implement: list panes with PID and working directory,
-send literal text and keys, capture a pane, display a message, create and kill sessions. Carry the new
-pane identity through process discovery, registry persistence and hooks, and scrub it from recap
-workers so they cannot register as phantom agents. The retired Herdr backend is still in the tree
-(`cli/src/lib/herdrBackend.ts`) as the worked example of the contract; see
-[Adding a multiplexer](CONTRIBUTING.md#adding-a-multiplexer).
-
-```bash
-cd cli && npm run test:tmux-real # the real multiplexer discovery suite
-```
-
-### Add a domain harness
-
-A domain harness turns Harness into a product for one domain. Copper makes PCBs, Solid makes 3D
-parts, Marp makes keynotes; yours can make anything an agent can build in a folder. To the user it
-is one more tile in New Agent, with a category under the name. Pick it and you get a tab of its own:
-the domain's viewer on the left, the engine's terminal on the right, the engine started with the
-domain's skills in a workspace the harness laid out, and the pane header reporting where the work is.
-
-Nothing about the domain lives in this repo. A harness is a git repository that Harness installs on
-a machine on first use. Harness reads one manifest, copies files into the workspace, runs the commands
-the manifest names, and watches one JSON file. That is the whole coupling.
-
-| In the repo | What it is |
-|---|---|
-| `harness.json` | the manifest: id, name, category, base engine, workspace, skills, toolchain, viewer, verdict path |
-| `AGENTS.md` | what the engine is told in every workspace; a `claude` base gets a `CLAUDE.md` that imports it |
-| `skills/` | the domain's craft as `SKILL.md` bundles, symlinked into the workspace so edits are live |
-| `template/` | a fresh workspace, copied once into an empty folder, plus an optional `init` script |
-| `toolchain/setup`, `doctor` | install the domain's tools at install time; say what is missing, one line per check |
-| `viewer` | a loopback web server Harness runs beside the terminal; the pane is a webview on it |
-| `.harness/verdict.json` | the one file the domain writes and Harness reads: ready or not, findings, phases |
-
-#### Build one
-
-1. **Copy the starter.** [`dsh/starter-dsh/`](dsh/starter-dsh/) is a complete tier-0 harness: a
- manifest, an `AGENTS.md`, one skill, a template, a toolchain that installs nothing.
-
- ```bash
- cp -r dsh/starter-dsh ~/code/my-harness && cd ~/code/my-harness && git init
- ```
-
- In `harness.json` set `id` (`owner/name`, the install directory and the wire id), `name` (the
- tile), `category` (the tile's second line), `engine` (`claude` or `codex`), and
- `workspace.marker` (a file whose presence means the workspace is already laid out).
-
-2. **Tell the agent its job.** `AGENTS.md` says what the workspace is, where things go, what to do
- first, and how to work so the pane moves: first save within a minute, then build up, check after
- every pass. The craft itself goes in `skills/<name>/SKILL.md`: the dialect, the patterns, the
- commands. Skills are symlinked, so a change in your checkout is live in every workspace.
-
-3. **Lay out the workspace.** `template/` is copied into an empty folder once; then
- `workspace.init` runs with the workspace as its working directory and `HARNESS_DSH_DIR` pointing
- at the install. Seed the first verdict here so the header has a state before the first prompt.
-
-4. **Ship the toolchain with the harness.** `toolchain/setup.sh` runs once at install, in the
- install directory: pin versions and vendor them there (a `node_modules`, a `.venv`), never into
- the user's machine. `toolchain/doctor.sh` exits 0 when the machine can run the harness and prints
- one line per check; Harness shows those lines. Point the agent at the tools through `agent.env`
- (`"MARP_TOOLCHAIN": "${dsh}/toolchain"`); `${dsh}`, `${workspace}` and `${home}` expand.
-
-5. **Write the verdict as a feed.** `.harness/verdict.json` is written at every check and every
- phase change, not at the end. `ready` is the one machine truth; `summary` is the header's line;
- `phases` is how the header says "you are here".
-
- ```json
- { "spec": 1, "ready": false, "summary": "10 slides so far · 1 warning",
- "findings": [{ "severity": "warning", "kind": "dense", "message": "slide 4 has 61 words" }],
- "artifact": "deck.md",
- "phases": [{ "id": "outline", "name": "Outline", "state": "done" },
- { "id": "draft", "name": "Draft", "state": "active" },
- { "id": "polish", "name": "Polish", "state": "pending" }],
- "updatedAt": "2026-09-15T23:33:00Z" }
- ```
-
-6. **Add the viewer.** `viewer.command` is a long-running process. Harness starts it with
- `HARNESS_VIEWER_PORT`, `HARNESS_WORKSPACE`, `HARNESS_DSH_DIR` and `HARNESS_DSH` in its
- environment, waits for the port to open on `127.0.0.1`, then loads `viewer.url` in the pane
- (`${port}` and `${artifact}` expand; the artifact is what the verdict names, or the newest file
- matching `artifactExtensions`). Serve files from the workspace and nothing outside it, watch the
- workspace, push a reload on every change, and re-run your check on every change so the header
- moves while the agent writes without the agent running anything. Marp's viewer does all of this
- in about 110 lines of Node with no dependencies beyond its renderer.
-
-7. **Check it, install it, run it.**
-
- ```bash
- harness dsh check . # conformance: the manifest, the scripts, the schemas
- harness dsh install . --link # this checkout as the installed harness (a symlink)
- harness dsh doctor owner/name # what the machine is missing, if anything
- harness dsh list # installed here, and what the registry offers
- ```
-
- Then New Agent, your tile, a folder, a prompt. For a check without the app,
- [`dsh/tools/dsh-e2e.mjs`](dsh/tools/) creates an agent over the daemon's loopback socket and
- reports the materialized workspace, the viewer URL, the pane's environment and the first verdict.
- The viewer process reads its own files when it starts; after you edit it, kill it and the daemon
- respawns it on the new code.
-
-8. **Publish.** Add `dsh/registry/<owner>/<name>.json` in a pull request:
-
- ```json
- { "id": "owner/name", "name": "Name", "category": "Thing", "description": "One line.",
- "repo": "https://github.com/owner/name", "ref": "main", "engine": "claude",
- "tier": 2, "verified": false }
- ```
-
- CI clones the repo at that ref and runs the conformance check. Once merged, the app offers the
- tile before the harness is installed and installs it on Create; `verified: true` is for
- first-party entries, everything else shows its git URL on install.
-
-#### Tiers
-
-| Tier | Ships | Harness shows |
-|---|---|---|
-| 0 | manifest, `AGENTS.md`, skills, template | the tile, a terminal with the skills loaded |
-| 1 | + a check that writes `.harness/verdict.json` | + ready or not, findings and phases in the pane header |
-| 2 | + a viewer server | + the viewer pane beside the terminal, following the artifact |
-
-#### Worked examples
-
-| Harness | Base | What it shows |
-|---|---|---|
-| [Marp](https://github.com/autonomous-ai/autonomous-marp) (Slides) | Claude Code | the smallest complete tier 2: a 110-line viewer with live reload and a present mode, two themes, an offline art generator, a check that writes the verdict, node tests. Start here. |
-| [Copper](https://github.com/autonomous-ai/autonomous-circuit) (PCB) | Claude Code | a Python toolchain vendored by `setup.sh`, a board viewer, phases Build / Checks / Fab written by the generation pipeline |
-| [Solid](https://github.com/autonomous-ai/autonomous-workshop) (3D design) | Codex | a Codex base, CAD scripts as skills, a STEP viewer found through `artifactExtensions`, phases Build / Fit / Print / Motion / Review |
-
-Two rules hold across all of them. The pane is progressive: a harness that only produces a final
-file is not one. And the domain stays in the harness: if adding yours needs a change in this repo,
-that is a spec change, and [`dsh/spec/README.md`](dsh/spec/README.md) with its schemas is where the
-contract lives. Changes to it are appended to `dsh/spec/CHANGES.md`.
-
-## Providers, relay, web
-
-- **`provider/`** — the spec ([`spec/README.md`](provider/spec/README.md)), the deterministic
- [`reference-provider`](provider/reference-provider/) with the conformance runner on port 4319, and
- [`example-provider`](provider/example-provider/), a real one backed by the local `claude` CLI on
- port 4502 (read its README before running it; it skips permissions). `provider/e2e` runs both.
-- **`backend/`** — the relay: Node, MongoDB via Prisma, Redis. It terminates four WebSocket paths
- (`/api/adapter-ws` for daemons, `/api/web-ws`, `/api/device-ws`, `/api/manager-ws`), signals WebRTC
- and hands out STUN/TURN, and persists machines, agent names and counters. `npm install && npm run
- dev` on `:8085`; [`backend/README.md`](backend/README.md) and `.env.example` for the rest.
- `harness-api.autonomous.ai` is the hosted instance.
-- **The web client** at [harness.autonomous.ai](https://harness.autonomous.ai) reaches the same
- machines from a browser after `harness pair <code>` or a `harness browser-link`. It is not in this
- repository; it also hosts the CLI installer and the desktop downloads.
-
-## Repository layout
-
-```
-desktop/ the app (Flutter; macOS and Linux). third_party/xterm is the patched terminal core
-cli/ the harness daemon and CLI (TypeScript, one bundle). src/engines/ is one folder per engine
-backend/ the relay (Node, Prisma/MongoDB, Redis)
-provider/ the API-provider spec, reference and example providers, conformance runner
-device/ firmware for the Harness device (ESP-IDF, esp32-circle)
-dsh/ domain harnesses: the contract and schemas, the registry, the starter, daemon-level tools
-```
-
-## Development
-
-```bash
-# cli
-cd cli && npm install && npm run typecheck && npm test
-make install-cli # bundle this tree into ~/.harness/cli and restart the daemon on it
-
-# desktop (Flutter ≥ 3.47 / Dart ≥ 3.13; SPM on for macOS)
-cd desktop && flutter pub get && flutter analyze && flutter test
-flutter run -d macos # or -d linux
-
-# backend
-cd backend && npm install && npm run typecheck && npm test
-
-# provider
-cd provider/e2e && npm install && npm test
-
-# device
-make device-test
-```
-
-Each product releases on its own tag and the suffix routes the workflow: `vX.Y.Z_cli` bundles and
-publishes the daemon (running daemons pick it up within a minute), `vX.Y.Z_backend` builds the image,
-`vX.Y.Z_desktop` builds, signs and publishes both macOS bundles and both Linux architectures.
-`make release-cli|release-backend|release-desktop` cut them; `make upload-circle` publishes device
-firmware over the air. `ci.yml` runs the CLI suite on demand (Actions -> CI -> Run workflow) and holds
-no secrets, which is what lets it run on a fork's branch; see [`docs/cicd.md`](docs/cicd.md).
-`make remote-machine`
-brings up a second machine in Docker so the remote path can be exercised from one laptop.
+| a **domain harness**: PCB, CAD, slides, yours | [`dsh/README.md`](dsh/README.md), [`dsh/starter-dsh/`](dsh/starter-dsh/) | `harness dsh check .` |
+| an **agent** as a CLI engine | [`cli/src/engines/README.md`](cli/src/engines/README.md) | the recorded-session fixtures pass |
+| an **agent** as an API provider | [`provider/README.md`](provider/README.md) | the conformance runner, zero failures |
+| a **terminal multiplexer** | [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-multiplexer) | `npm run test:tmux-real` |
+| a **palette** or terminal theme | [`docs/extending.md`](docs/extending.md#palettes-and-appearance) | `flutter test` |
+| a **keymap** | `~/.config/harness/keybindings.jsonc`, no code | it reloads on save |
+| **automation** over the daemon | [`docs/cli.md`](docs/cli.md#automation) | the loopback socket answers |
+
+**A domain harness** is a git repository: a manifest, an `AGENTS.md`, skills, a workspace template,
+a toolchain that installs itself, and for the pane a viewer server and a verdict file. Harness reads
+the manifest and nothing else about its code. Copy the starter, `harness dsh check .`,
+`harness dsh install . --link`, and your tile is in New Agent. One registry file in a pull request
+lists it for everyone. [Marp](https://github.com/autonomous-ai/autonomous-marp) is the smallest
+complete one and the place to start; [Copper](https://github.com/autonomous-ai/autonomous-circuit)
+and [Solid](https://github.com/autonomous-ai/autonomous-workshop) are the big ones.
+
+**An agent** is a CLI engine, a normalizer in this repo written from a recorded session of the real
+binary, or an API provider, eight JSON-RPC methods on your own infrastructure. Both are first-class:
+[docs/extending.md](docs/extending.md).
+
+## Contribute
+
+Harness gets better in more ways than pull requests here.
+
+- **Build a harness for your domain** and list it in [`dsh/registry/`](dsh/registry/). It is a
+ product on its own, and it never touches this code.
+- **Bring your agent** as an engine or a provider.
+- **Record a session.** An engine bug is fixed from a real recorded session of the real binary.
+ Attach one to the issue and it is half done.
+- **A palette, a terminal theme, a keymap** you are proud of.
+- **Docs.** What confused you in the first five minutes is the next fix.
+
+Open an issue before writing an engine or a multiplexer so the shape and the software a maintainer
+needs to reproduce it are agreed first. [CONTRIBUTING.md](CONTRIBUTING.md) has the workflow,
+[SECURITY.md](SECURITY.md) takes security reports, and the licence is [MIT](LICENSE).
## Docs
-- [`docs/specs/cable-protocol.md`](docs/specs/cable-protocol.md) — the device wire, the only thing the firmware and the daemon share.
-- [`docs/cicd.md`](docs/cicd.md) — workflows, tags, credentials, dry runs.
-- [`docs/harness-v2-handoff.md`](docs/harness-v2-handoff.md) — the current state of the app, superseding the other `harness-v2-*` notes; [`docs/harness-v2-keyboard-system.md`](docs/harness-v2-keyboard-system.md) for the keymap design.
-- [`docs/harness-agent-creation.md`](docs/harness-agent-creation.md), [`docs/harness-agent-lifecycle.md`](docs/harness-agent-lifecycle.md), [`docs/harness-agent-first-tabs.md`](docs/harness-agent-first-tabs.md) — how sessions are created, kept and shown.
-- [`docs/autonomous-device-integration.md`](docs/autonomous-device-integration.md) — direct LAN pairing with Autonomous OS devices.
-- [`cli/README.md`](cli/README.md), [`desktop/README.md`](desktop/README.md), [`backend/README.md`](backend/README.md), [`provider/README.md`](provider/README.md) — per-package detail.
-
-## Contributing, security, licence
-
-Open an issue before writing an engine or a multiplexer so the integration shape and the real software
-a maintainer needs to reproduce it are agreed first; the review and pull-request workflow is in
-[CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to [SECURITY.md](SECURITY.md), not the issue
-tracker. [MIT](LICENSE).
+- [docs/app.md](docs/app.md) — sessions, panes, layouts, terminal, attention, machines
+- [docs/keyboard.md](docs/keyboard.md) — the full keymap and the keymap file
+- [docs/engines.md](docs/engines.md) — the fourteen engines: how each is followed, resume, bypass, grids
+- [docs/architecture.md](docs/architecture.md) — daemon, session model, transport and encryption, relay, providers, the device
+- [docs/cli.md](docs/cli.md) — every `harness` command, the dashboard, the loopback socket
+- [docs/extending.md](docs/extending.md) — agents, multiplexers, palettes, keys, automation
+- [docs/development.md](docs/development.md) — repository layout, build, test, release
+- [dsh/README.md](dsh/README.md) — build a domain harness; [dsh/spec/](dsh/spec/README.md) is the contract
+- [cli/](cli/README.md), [desktop/](desktop/README.md), [backend/](backend/README.md), [provider/](provider/README.md) — per-package detail
diff --git a/docs/app.md b/docs/app.md
new file mode 100644
index 000000000..566296b15
--- /dev/null
+++ b/docs/app.md
@@ -0,0 +1,68 @@
+# The app
+
+What the window does, pane by pane. The keys are in [keyboard.md](keyboard.md).
+
+## Sessions
+
+An agent is one engine process in one tmux pane on one machine. The app calls it an agent. A tab
+holds any number of panes, from any mix of machines; the app remembers tabs, pane placement, sizes,
+pinned slots, focus and zoom across restarts, in `~/.harness/desktop-app-v2/state.json`.
+
+**New Agent (⌘N)** asks for four things: the machine, the working folder, the engine, and,
+under Advanced, two settings most people never touch. The folder picker is the native panel on this
+computer and a remote directory list on any other machine, served over the daemon's `fs_list_dir`.
+**Clone repository** clones a GitHub URL into a parent folder first. The engine row shows every engine
+the machine has, probes availability live, and marks the ones the daemon would install on first
+launch. Advanced holds the engine's permission-bypass flag (`--dangerously-skip-permissions`,
+`--dangerously-bypass-approvals-and-sandbox`, `--force`, `--auto`, whichever the engine has) and,
+for Codex, a profile: a `CODEX_HOME` folder to launch under instead of `~/.codex`, each with its own
+hooks.
+
+Creation carries a receipt. If the reply is lost, the button turns into **Check status** rather than
+creating a second session.
+
+Closing a pane is a view operation; the agent keeps running. **Stop Agent** ends the engine process
+and asks first. **Restart Agent** relaunches it in the same pane with the same id, resuming the
+conversation where the engine supports it.
+
+**Open Agent (⌘O)** is the search: agents, tabs, projects, machines, history and commands, fuzzy
+matched, with a session preview on the right built from cached recent turns. Type `>` for commands
+only (also ⇧⌘P).
+
+## Panes and layouts
+
+Hover the right or bottom edge of a pane for a split control, or ⌘R and ⌘D to split right and down;
+both open the same picker at that position. Drag a pane's header onto another pane to swap them.
+Resize grips live in the gaps and appear on hover or keyboard focus; sizes are remembered per pane
+count.
+
+**Layout (⌘S)** opens a palette of drawn shapes rather than names: Split, Columns, Rows, Main
+left/right/top/bottom, Grid, 2 to 5 columns, Middle + sides, Two over three, Auto. Press ⌘S again to
+cycle, a digit to pick directly, Enter to apply. A pinned pane keeps its slot when other panes close
+around it.
+
+## Terminal
+
+The renderer is a vendored, patched [xterm](desktop/third_party/xterm). Each pane has its own find bar
+(⌘F). ⌘-click opens links; an image or video path in the output opens in a preview, downloaded from
+the remote machine over the existing encrypted connection with progress and cancel (up to 512 MiB).
+Paste or drop an image onto a pane to send it to the agent. On a remote machine a composer box under
+the pane batches a message instead of paying a round trip per keystroke. Scrollback is restored from
+the daemon's snapshots on attach, resize, zoom and reconnect. Font, size (⌘0, ⌘+, ⌘-), terminal
+colours and six app palettes are in Settings.
+
+## Attention, models, usage
+
+When an agent asks a question the pane gets an amber ring, the titlebar bell lights, and ⇧⌘I lists
+every agent waiting on you. Answers go back into the engine's own dialog; there is no side channel.
+
+The **Models** menu shows each engine's subscription usage window, refreshed once a minute, for local
+and remote machines alike. Settings ▸ Usage is a separate token ledger read from Claude's and Codex's
+transcripts and OpenCode's database, off per provider until you switch it on.
+
+## Machines
+
+The app talks to the daemon on this computer over a loopback socket and never dials the relay itself.
+Other machines are reached through that daemon: it links to them with a per-machine remote password,
+terminates the encryption locally, and hands the app plaintext. Machines ▸ Link Machine… runs the
+link flow; the CLI equivalent is under [The daemon and CLI](#the-daemon-and-cli).
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 000000000..8ffecfdaa
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,82 @@
+# How it works
+
+```
+ ( ◉ ) Harness device (USB)
+ │
+ ┌─────────── this computer ───────────┐
+ │ Harness app ── loopback ──▶ harness daemon ──▶ tmux ──▶ claude · codex · … │
+ └──────────────────────────────┬──────┘
+ │ WebSocket (E2EE)
+ ╔═════════╧═════════╗
+ ║ Harness Relay ║ store and forward, no keys
+ ╚═════════╤═════════╝
+ ┌───────────────────────┼───────────────────────┐
+ your server your platform harness.autonomous.ai
+ harness daemon your HTTP API the web client
+ tmux · hermes · muse (provider) (paired browser)
+ ▲
+ └── terminal traffic goes direct over WebRTC when ICE succeeds
+```
+
+**The daemon** runs detached under your account. Every five seconds it reconciles the `harness-*`
+tmux sessions with its registry; a pane has to be missing on two scans before its agent is marked
+gone. It tails each agent's transcript with a byte offset (JSONL for most engines, SQLite for
+OpenCode, Kilo, Hermes and Devin) and turns lines into a normalized event stream: turn started,
+tool call, sub-agent, question, turn ended. Hooks it installs into the vendor CLI tell it about
+session start, prompt submit and stop. Every five minutes it re-reads engine configs and pane
+footers to keep model and effort right. On start it restores panes that died with the tmux server,
+and it self-updates from a signed manifest, swapping the bundle atomically.
+
+**The session model.** The registry (`~/.harness/cli/data/registry.json`, mode 0600) is the source of
+truth for agents: engine, working directory, tmux pane, bound transcript, process identity. Layouts
+belong to the app. The relay stores machine records, agent names and daily counters, never a
+transcript, a recap or a keystroke.
+
+**Transport.** Each daemon holds one WebSocket to the relay, authenticated with its SSO token.
+Terminal bytes ride a binary channel on that socket until a WebRTC data channel negotiates, then move
+to it. Encryption is on for every path and has no switch:
+
+- **Ed25519** identity keys, pinned at first pairing and signing every ephemeral after it.
+- A **CPace-style PAKE** over ristretto255 — the six-character pairing code bootstraps a shared secret
+ across the untrusted relay, and an attacker gets one online guess.
+- **X25519** ephemeral Diffie–Hellman per connection, through HKDF to pairwise session keys.
+- A **per-process group key** so one event encrypts once for many readers.
+- **ChaCha20-Poly1305** on every frame, with the associated data binding frame type and session.
+
+The crypto core lives in [`cli/src/lib/e2ee/`](cli/src/lib/e2ee/) and is a byte-identical twin of the
+browser's copy, with a drift-guard test and committed self-vectors.
+
+## Providers, relay, web
+
+- **`provider/`** — the spec ([`spec/README.md`](provider/spec/README.md)), the deterministic
+ [`reference-provider`](provider/reference-provider/) with the conformance runner on port 4319, and
+ [`example-provider`](provider/example-provider/), a real one backed by the local `claude` CLI on
+ port 4502 (read its README before running it; it skips permissions). `provider/e2e` runs both.
+- **`backend/`** — the relay: Node, MongoDB via Prisma, Redis. It terminates four WebSocket paths
+ (`/api/adapter-ws` for daemons, `/api/web-ws`, `/api/device-ws`, `/api/manager-ws`), signals WebRTC
+ and hands out STUN/TURN, and persists machines, agent names and counters. `npm install && npm run
+ dev` on `:8085`; [`backend/README.md`](backend/README.md) and `.env.example` for the rest.
+ `harness-api.autonomous.ai` is the hosted instance.
+- **The web client** at [harness.autonomous.ai](https://harness.autonomous.ai) reaches the same
+ machines from a browser after `harness pair <code>` or a `harness browser-link`. It is not in this
+ repository; it also hosts the CLI installer and the desktop downloads.
+
+## The Harness device
+
+A round 466×466 AMOLED with touch and a far-field microphone, USB-C on the bottom edge. It has no
+WiFi and holds no credential. It is served entirely over the cable by the daemon on the computer it is
+plugged into; plugging it in is the authorization. The wire is one USB serial device (`303a:1001`),
+framed as `A5 5A | ver | type | len | payload | crc16` with a JSON vocabulary, a five-second ping,
+and a hard 8 KiB frame ceiling.
+
+What it shows: your agents as tiles in the order of the window's panes, with what each is doing and
+for how long; a wheel of your machines; the agent's own question when it asks one, answerable with a
+tap; the recap when a turn finishes, with one quiet tone. Scroll the face to scroll the terminal.
+Double-tap and speak to send a task: the audio goes to the daemon as PCM, comes back as a transcript,
+and Boss mode routes it. A voice turn can carry a mode — `/goal` runs an instruction to done,
+`/loop` on a schedule — adapted per engine; `/loop` is Claude Code only today.
+
+Firmware updates travel over the same cable in 16 KB credit windows, offered from the published
+metadata and never for a dev build. `harness flash` re-flashes a device from a USB port. The firmware
+is ESP-IDF ≥ 5.5 under [`device/esp32-circle/`](device/esp32-circle/) (`idf.py set-target esp32s3 &&
+idf.py build`); `make device-test` runs the host-side tests with no board attached.
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 000000000..993b80b86
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,49 @@
+# The daemon and CLI
+
+`harness` is one pure-JS bundle run by the managed Node under `~/.harness/cli`. Everything below
+works the same on a headless Linux server; the app is not required on a machine, only the daemon.
+
+| Command | What it does |
+|---|---|
+| `harness login [--force] [--json]` | Browser SSO; save this computer's session. `--force` signs in as a different account. `--json` emits NDJSON for GUI clients. |
+| `harness start [-f] [--repair]` | Start the daemon from the saved session. `-f` runs in the foreground for a supervisor. `--repair` re-verifies the managed Node runtime. |
+| `harness stop` · `harness logout` · `harness reset` | Stop the daemon · stop and clear the SSO session · stop and clear all local state. |
+| `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. |
+| `harness machines [list] [--json]` · `harness machines delete <id>` | This account's machines · remove another machine (never this one). |
+| `harness pair <code>` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. |
+| `harness browser-link` | Print a reusable seven-day setup link for browsers. |
+| `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. |
+| `harness link connect <id> [--name=<label>]` · `harness link list` · `harness link unlink <id>` | Let this machine reach another of yours, terminating E2EE here; list; unlink. |
+| `harness grid login [--force] [--json]` · `harness grid logout` | Sign the `grid` CLI in with this computer's account, no second browser. |
+| `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. |
+| `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |
+
+Interactive prompts read one line from stdin with `--stdin`; `--json` switches any of them to NDJSON.
+
+The daemon also serves a loopback dashboard at `http://127.0.0.1:18473`: health, this machine's
+fingerprint, paired clients, stop. It never renders a transcript. Configuration is environment
+variables (`BACKEND_WS_URL`, `WEB_URL`, `ADAPTER_DATA_DIR`, `ADAPTER_COMPUTER_ID`, `PORT`, and the
+per-engine home directories); [`cli/README.md`](cli/README.md) has the full table and the
+`.env.example`.
+
+## Automation
+
+The app is one client of the daemon. Anything on the same computer can be another: the loopback
+WebSocket at `ws://127.0.0.1:18473/api/local-ws` takes a `machine_select` frame first
+(`{ machineId, localProtocolVersion: 1 }`, no `Origin` header), then request frames with a `requestId`
+and answers them with `<type>_result`. Selecting one of your other machines proxies the request
+through this daemon's link to it.
+
+What it answers: `agents_list`, `agent_create`, `agent_restart`, `agent_retarget`, `agent_delete`,
+`agent_update`, `agent_recent`, `agent_files`, `agent_read_file` (text, or media in 128 KiB chunks),
+`fs_list_dir`, `engines_probe`, `codex_profiles_list`, `codex_profile_link`, `models_list`,
+`usage_read`, `question_response`, `voice_route`, `message`, `cancel`, and `terminal_open` for a
+binary terminal channel with scroll, resync and paste. The same frames travel from the web client
+over the relay.
+
+Engines report in over HTTP on the same port: `POST /api/hook/session-start`, `session-end`,
+`turn-start`, `turn-stop`, `tool-start`, authenticated by a per-install token the daemon writes into
+the hook it installs.
+
+There is no `harness new` or `harness split` today. Sessions are created and arranged through the app,
+the web client, or this socket.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 000000000..ffcbd3593
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,42 @@
+# Development
+
+## Repository layout
+
+```
+desktop/ the app (Flutter; macOS and Linux). third_party/xterm is the patched terminal core
+cli/ the harness daemon and CLI (TypeScript, one bundle). src/engines/ is one folder per engine
+backend/ the relay (Node, Prisma/MongoDB, Redis)
+provider/ the API-provider spec, reference and example providers, conformance runner
+device/ firmware for the Harness device (ESP-IDF, esp32-circle)
+dsh/ domain harnesses: the contract and schemas, the registry, the starter, daemon-level tools
+```
+
+## Build and test
+
+```bash
+# cli
+cd cli && npm install && npm run typecheck && npm test
+make install-cli # bundle this tree into ~/.harness/cli and restart the daemon on it
+
+# desktop (Flutter ≥ 3.47 / Dart ≥ 3.13; SPM on for macOS)
+cd desktop && flutter pub get && flutter analyze && flutter test
+flutter run -d macos # or -d linux
+
+# backend
+cd backend && npm install && npm run typecheck && npm test
+
+# provider
+cd provider/e2e && npm install && npm test
+
+# device
+make device-test
+```
+
+Each product releases on its own tag and the suffix routes the workflow: `vX.Y.Z_cli` bundles and
+publishes the daemon (running daemons pick it up within a minute), `vX.Y.Z_backend` builds the image,
+`vX.Y.Z_desktop` builds, signs and publishes both macOS bundles and both Linux architectures.
+`make release-cli|release-backend|release-desktop` cut them; `make upload-circle` publishes device
+firmware over the air. `ci.yml` runs the CLI suite on demand (Actions -> CI -> Run workflow) and holds
+no secrets, which is what lets it run on a fork's branch.
+`make remote-machine`
+brings up a second machine in Docker so the remote path can be exercised from one laptop.
diff --git a/docs/engines.md b/docs/engines.md
new file mode 100644
index 000000000..ae34215e8
--- /dev/null
+++ b/docs/engines.md
@@ -0,0 +1,30 @@
+# Engines
+
+Harness never wraps an agent. It reads the transcript the agent already writes and installs the
+vendor's own hooks or plugin to learn when a turn starts and ends. Your credentials stay in your
+`~/.claude`, `~/.codex`, and so on.
+
+| Engine | Binary | How Harness follows it | Resume | Permission bypass | Grid |
+|---|---|---|---|---|---|
+| Claude Code | `claude` | hooks in `~/.claude/settings.json` + JSONL transcript | `--resume` | `--dangerously-skip-permissions` | yes |
+| Codex | `codex` | `hooks.json` per `CODEX_HOME` + JSONL rollouts | `resume` | `--dangerously-bypass-approvals-and-sandbox` | yes |
+| Cursor | `cursor-agent` | `~/.cursor/hooks.json` + transcript | `--resume` | `--force` | — |
+| OpenCode | `opencode` | plugin + SQLite | `--session` | `--auto` | yes |
+| Pi | `pi` | extension + transcript | `--session` | — | yes |
+| Hermes | `hermes` | hooks + SQLite | `--resume` | — | yes |
+| Command Code | `cmd` | hooks + transcript | `--resume` | — | — |
+| Devin | `devin` | hooks + SQLite | — | — | — |
+| Muse Code | `muse` | transcript | `resume` | — | — |
+| Amp | `amp` | plugin writes the transcript Harness tails | `threads continue` | — | — |
+| Kilo | `kilo` | plugin + SQLite | `--session` | — | — |
+| Grok Build | `grok` | hooks + `updates.jsonl` | `--resume` | — | yes |
+| Antigravity | `agy` | hooks + transcript | `--conversation` | — | — |
+| GitHub Copilot | `copilot` | hooks + transcript | `--resume` | — | yes |
+
+A launcher that hands the pane to one of these is that engine: `ori claude` is a Claude Code agent,
+and the daemon reads the gateway off the live process so recaps and routing go through it too.
+
+**Grids.** An agent can be pointed at an [Autonomous Grid](https://www.autonomous.ai/grid) relay
+instead of the engine's own login, at creation or later with **Retarget**, which respawns the same
+pane with the grid's environment and `--resume`. The engines marked above support it; the key travels
+in the tmux session environment, never in argv or a file. Needs tmux ≥ 3.2.
diff --git a/docs/extending.md b/docs/extending.md
new file mode 100644
index 000000000..8c85a513c
--- /dev/null
+++ b/docs/extending.md
@@ -0,0 +1,70 @@
+# Extending Harness
+
+Every layer has a contract, a starter and a check. Domain harnesses have their own guide:
+[`dsh/README.md`](../dsh/README.md).
+
+## Add your agent
+
+Two paths. Both are first-class and both are in this repo.
+
+| | **CLI engine** | **API provider** |
+|---|---|---|
+| Your agent is | a command you run, anywhere `harness login` runs | a service on your own infrastructure |
+| You write | a normalizer in TypeScript, here | an HTTP endpoint, in any language |
+| You ship it | as a pull request to this repo | by deploying it yourself |
+| Start at | [`cli/src/engines/README.md`](cli/src/engines/README.md) | [`provider/`](provider/README.md) |
+
+A CLI engine touches about twenty shared files, and the engines README is that list in dependency
+order. The one rule: every field name, event kind and tool name comes from a real recorded session of
+the real binary, never inferred from another engine. If your agent writes nothing to disk, look at Amp:
+its plugin writes the transcript, and from there it is an ordinary engine.
+
+```bash
+cd cli && npm install && npm run typecheck && npm test # replay the recorded-session fixtures
+```
+
+An API provider implements eight JSON-RPC 2.0 methods over HTTPS with SSE for the one that streams:
+`agent.list`, `agent.send`, `agent.history`, `turn.cancel`, `agent.create`, `agent.rename`,
+`agent.delete`, `agent.recap`. No SDK, no discovery, no capability negotiation. The reference
+implementation ships the conformance runner; zero failures is the bar.
+
+```bash
+cd provider/reference-provider && npm install && npm run dev # http://127.0.0.1:4319
+npm run conformance -- --url https://your-endpoint --key <credential>
+```
+
+## Add a terminal multiplexer
+
+Harness watches tmux with nothing to configure. A second multiplexer is added beside tmux, not in
+place of it. Before writing code, confirm two things: a process inside a pane can identify that pane
+with a stable, multiplexer-namespaced id, and your tool's presence is detectable without running it,
+so a machine that lacks it pays nothing. Then implement: list panes with PID and working directory,
+send literal text and keys, capture a pane, display a message, create and kill sessions. Carry the new
+pane identity through process discovery, registry persistence and hooks, and scrub it from recap
+workers so they cannot register as phantom agents. The retired Herdr backend is still in the tree
+(`cli/src/lib/herdrBackend.ts`) as the worked example of the contract; see
+[Adding a multiplexer](CONTRIBUTING.md#adding-a-multiplexer).
+
+```bash
+cd cli && npm run test:tmux-real # the real multiplexer discovery suite
+```
+
+## Palettes and appearance
+
+Six palettes ship — graphite, dusk, midnight, slate, forest, ember — and each coordinates the
+workspace chrome with the terminal defaults. They are values of `HarnessPalette` in
+[`desktop/lib/shared/theme/color_palette.dart`](../desktop/lib/shared/theme/color_palette.dart); a
+new one is one more value there, and it appears in Settings ▸ Appearance on its own. Terminal
+colour schemes are `TerminalTheme` values in
+[`desktop/lib/terminal/terminal_theme.dart`](../desktop/lib/terminal/terminal_theme.dart). Fonts and
+sizes are settings, not code. `cd desktop && flutter test` is the bar.
+
+## Keys
+
+No code: `~/.config/harness/keybindings.jsonc`, watched and reloaded on save. [keyboard.md](keyboard.md)
+has the format and the command ids.
+
+## Automation
+
+Anything on the same computer can drive the daemon over its loopback socket, with the same frames the
+app and the web client use. [cli.md](cli.md#automation) lists them.
diff --git a/docs/keyboard.md b/docs/keyboard.md
new file mode 100644
index 000000000..4ccb0270c
--- /dev/null
+++ b/docs/keyboard.md
@@ -0,0 +1,35 @@
+# Keyboard
+
+Every action has a key or a palette entry, and every key can be remapped.
+
+The defaults, in the workspace:
+
+| Keys | Action |
+|---|---|
+| ⌘N | New Agent |
+| ⌘O | Open Agent — search sessions, tabs, machines, history; `>` for commands |
+| ⇧⌘P | Command palette |
+| ⌘B | Boss mode: describe a task, it picks the agent |
+| ⌘T · ⌘W · ⇧⌘T · ⇧⌘R | New tab · close tab · reopen last closed · rename tab |
+| ⌘1 … ⌘9 | Select tab by position |
+| ⇧⌘] · ⇧⌘[ · ⌃Tab · ⌃⇧Tab | Next · previous tab |
+| ⌘] · ⌘[ · ⌘Y | Forward · back through visited agents · full history |
+| ⌘H ⌘J ⌘K ⌘L · ⌘arrows | Focus the pane left · below · above · right |
+| ⇧⌘arrows | Move the focused pane |
+| ⌘R · ⌘D | Split right · split down |
+| ⌘⏎ · ⌘; · ⇧⌘W | Zoom or restore · last pane · close pane |
+| ⌘S | Layout palette |
+| ⌘F · ⌘G · ⇧⌘G | Find in terminal · next · previous match |
+| ⇧⌘I | Agents needing input |
+| ⌘, · ⌘/ | Settings · keyboard shortcuts |
+
+In a picker: ↓ ⌃N ⌃J and ↑ ⌃P ⌃K move, ⏎ opens, ⌘⏎ adds the result as a pane here, Esc or ⌃G closes.
+The terminal keeps ⌘C, ⌘V, ⌘A, Esc, ⌥⏎ and ⌃C for itself. `pane.pin`, `pane.focus_1…9`,
+`pane.resize`, `pane.reset_sizes`, `machine.link` and a few others ship unbound and are in the palette.
+
+Remap anything in `~/.config/harness/keybindings.jsonc` (`$XDG_CONFIG_HOME` respected). The file is
+JSONC: `{ "version": 1, "bindings": [{ "keys": "cmd+k cmd+l", "command": "pane.focus_right",
+"when": "workspace" }] }`. Sequences are one to four strokes; `"command": null` unbinds a key or a
+whole prefix; `when` is `workspace`, `terminal` or `picker`. The file is watched and reloaded on save;
+a bad edit keeps the last good keymap and says what was wrong. **Keyboard shortcuts (⌘/)** lists the
+effective bindings and **Open keyboard config** writes a commented template with every command id.
diff --git a/dsh/README.md b/dsh/README.md
index ab9306231..771db7452 100644
--- a/dsh/README.md
+++ b/dsh/README.md
@@ -12,48 +12,111 @@ is what lets hundreds of DSHs exist without any of them touching this repo.
## Anatomy
-```
-harness.json manifest: id, name, base engine, workspace, agent, toolchain, viewer, verdict
-AGENTS.md appended to the agent's instructions in every workspace
-skills/ SKILL.md bundles, linked into the workspace
-template/ copied into an empty workspace
-toolchain/ setup.sh (once, at install) · doctor.sh (exit 0 = ready) · viewer.sh (optional)
-viewer/ optional: whatever viewer.sh serves
-```
+| In the repo | What it is |
+|---|---|
+| `harness.json` | the manifest: id, name, category, base engine, workspace, skills, toolchain, viewer, verdict path |
+| `AGENTS.md` | what the engine is told in every workspace; a `claude` base gets a `CLAUDE.md` that imports it |
+| `skills/` | the domain's craft as `SKILL.md` bundles, symlinked into the workspace so edits are live |
+| `template/` | a fresh workspace, copied once into an empty folder, plus an optional `init` script |
+| `toolchain/setup`, `doctor` | install the domain's tools at install time; say what is missing, one line per check |
+| `viewer` | a loopback web server Harness runs beside the terminal; the pane is a webview on it |
+| `.harness/verdict.json` | the one file the domain writes and Harness reads: ready or not, findings, phases |
-## Tiers
+## Build one
-| Tier | Ships | Harness shows |
-|---|---|---|
-| 0 | manifest, AGENTS.md, skills | the tile, the terminal |
-| 1 | + scripts that write `.harness/verdict.json` | + a ready chip and findings in the pane header |
-| 2 | + a viewer server | + a web pane next to the terminal |
+1. **Copy the starter.** [`dsh/starter-dsh/`](starter-dsh/) is a complete tier-0 harness: a
+ manifest, an `AGENTS.md`, one skill, a template, a toolchain that installs nothing.
+
+ ```bash
+ cp -r dsh/starter-dsh ~/code/my-harness && cd ~/code/my-harness && git init
+ ```
+
+ In `harness.json` set `id` (`owner/name`, the install directory and the wire id), `name` (the
+ tile), `category` (the tile's second line), `engine` (`claude` or `codex`), and
+ `workspace.marker` (a file whose presence means the workspace is already laid out).
+
+2. **Tell the agent its job.** `AGENTS.md` says what the workspace is, where things go, what to do
+ first, and how to work so the pane moves: first save within a minute, then build up, check after
+ every pass. The craft itself goes in `skills/<name>/SKILL.md`: the dialect, the patterns, the
+ commands. Skills are symlinked, so a change in your checkout is live in every workspace.
+
+3. **Lay out the workspace.** `template/` is copied into an empty folder once; then
+ `workspace.init` runs with the workspace as its working directory and `HARNESS_DSH_DIR` pointing
+ at the install. Seed the first verdict here so the header has a state before the first prompt.
+
+4. **Ship the toolchain with the harness.** `toolchain/setup.sh` runs once at install, in the
+ install directory: pin versions and vendor them there (a `node_modules`, a `.venv`), never into
+ the user's machine. `toolchain/doctor.sh` exits 0 when the machine can run the harness and prints
+ one line per check; Harness shows those lines. Point the agent at the tools through `agent.env`
+ (`"MARP_TOOLCHAIN": "${dsh}/toolchain"`); `${dsh}`, `${workspace}` and `${home}` expand.
+
+5. **Write the verdict as a feed.** `.harness/verdict.json` is written at every check and every
+ phase change, not at the end. `ready` is the one machine truth; `summary` is the header's line;
+ `phases` is how the header says "you are here".
-[`starter-dsh/`](starter-dsh/) is tier 0 and the copy-me template. Copper, Solid and Marp are tier 2.
+ ```json
+ { "spec": 1, "ready": false, "summary": "10 slides so far · 1 warning",
+ "findings": [{ "severity": "warning", "kind": "dense", "message": "slide 4 has 61 words" }],
+ "artifact": "deck.md",
+ "phases": [{ "id": "outline", "name": "Outline", "state": "done" },
+ { "id": "draft", "name": "Draft", "state": "active" },
+ { "id": "polish", "name": "Polish", "state": "pending" }],
+ "updatedAt": "2026-09-15T23:33:00Z" }
+ ```
-## The contract
+6. **Add the viewer.** `viewer.command` is a long-running process. Harness starts it with
+ `HARNESS_VIEWER_PORT`, `HARNESS_WORKSPACE`, `HARNESS_DSH_DIR` and `HARNESS_DSH` in its
+ environment, waits for the port to open on `127.0.0.1`, then loads `viewer.url` in the pane
+ (`${port}` and `${artifact}` expand; the artifact is what the verdict names, or the newest file
+ matching `artifactExtensions`). Serve files from the workspace and nothing outside it, watch the
+ workspace, push a reload on every change, and re-run your check on every change so the header
+ moves while the agent writes without the agent running anything. Marp's viewer does all of this
+ in about 110 lines of Node with no dependencies beyond its renderer.
-[`spec/README.md`](spec/README.md) is the whole contract: the manifest, the verdict file, what
-Harness does at create time, and what it sets in the engine's environment. The JSON Schemas in
-[`spec/schema/`](spec/schema/) are normative. The spec is frozen; changes are appended to
-[`spec/CHANGES.md`](spec/CHANGES.md).
+7. **Check it, install it, run it.**
-## Installing
+ ```bash
+ harness dsh check . # conformance: the manifest, the scripts, the schemas
+ harness dsh install . --link # this checkout as the installed harness (a symlink)
+ harness dsh doctor owner/name # what the machine is missing, if anything
+ harness dsh list # installed here, and what the registry offers
+ ```
-```bash
-harness dsh install autonomous/copper # by registry id
-harness dsh install https://github.com/autonomous-ai/autonomous-circuit # by git URL
-harness dsh install /path/to/checkout --link # symlink, for development
-harness dsh list
-harness dsh doctor autonomous/copper
-harness dsh check /path/to/checkout # conformance, before publishing
-```
+ Then New Agent, your tile, a folder, a prompt. For a check without the app,
+ [`dsh/tools/dsh-e2e.mjs`](tools/) creates an agent over the daemon's loopback socket and
+ reports the materialized workspace, the viewer URL, the pane's environment and the first verdict.
+ The viewer process reads its own files when it starts; after you edit it, kill it and the daemon
+ respawns it on the new code.
-The desktop app offers the same install from New Agent: a harness the machine does not have yet is
-installed on Create.
+8. **Publish.** Add `dsh/registry/<owner>/<name>.json` in a pull request:
-## Publishing
+ ```json
+ { "id": "owner/name", "name": "Name", "category": "Thing", "description": "One line.",
+ "repo": "https://github.com/owner/name", "ref": "main", "engine": "claude",
+ "tier": 2, "verified": false }
+ ```
+
+ CI clones the repo at that ref and runs the conformance check. Once merged, the app offers the
+ tile before the harness is installed and installs it on Create; `verified: true` is for
+ first-party entries, everything else shows its git URL on install.
+
+## Tiers
+
+| Tier | Ships | Harness shows |
+|---|---|---|
+| 0 | manifest, `AGENTS.md`, skills, template | the tile, a terminal with the skills loaded |
+| 1 | + a check that writes `.harness/verdict.json` | + ready or not, findings and phases in the pane header |
+| 2 | + a viewer server | + the viewer pane beside the terminal, following the artifact |
+
+## Worked examples
+
+| Harness | Base | What it shows |
+|---|---|---|
+| [Marp](https://github.com/autonomous-ai/autonomous-marp) (Slides) | Claude Code | the smallest complete tier 2: a 110-line viewer with live reload and a present mode, two themes, an offline art generator, a check that writes the verdict, node tests. Start here. |
+| [Copper](https://github.com/autonomous-ai/autonomous-circuit) (PCB) | Claude Code | a Python toolchain vendored by `setup.sh`, a board viewer, phases Build / Checks / Fab written by the generation pipeline |
+| [Solid](https://github.com/autonomous-ai/autonomous-workshop) (3D design) | Codex | a Codex base, CAD scripts as skills, a STEP viewer found through `artifactExtensions`, phases Build / Fit / Print / Motion / Review |
-Add one file under [`registry/<owner>/<name>.json`](registry/) with the repo URL and pinned ref. CI
-clones it and runs the conformance check; green merges. First-party entries carry `verified: true`;
-everything else shows its git URL and an unverified note on install.
+Two rules hold across all of them. The pane is progressive: a harness that only produces a final
+file is not one. And the domain stays in the harness: if adding yours needs a change in this repo,
+that is a spec change, and [`spec/README.md`](spec/README.md) with its schemas is where the
+contract lives. Changes to it are appended to [`spec/CHANGES.md`](spec/CHANGES.md).