diff --git a/hive-agent-mcp/Cargo.toml b/hive-agent-mcp/Cargo.toml
index fda57a7c..376b77fd 100644
--- a/hive-agent-mcp/Cargo.toml
+++ b/hive-agent-mcp/Cargo.toml
@@ -2,6 +2,7 @@
 name = "hive-agent-mcp"
 version.workspace = true
 edition.workspace = true
+readme = "README.md"
 
 [[bin]]
 name = "hive-agent-mcp"
diff --git a/hive-agent-mcp/README.md b/hive-agent-mcp/README.md
new file mode 100644
index 00000000..3e97f78f
--- /dev/null
+++ b/hive-agent-mcp/README.md
@@ -0,0 +1,37 @@
+# hive-agent-mcp
+
+The built-in hyperhive MCP server every agent gets by default. Runs a
+long-lived streamable-http listener (the `hive-mcp-http` systemd unit)
+that claude reconnects to each turn via `--mcp-config` — this avoids
+the per-turn stdio re-registration race that a spawned-per-turn server
+would hit. HTTP is the sole transport; there is no stdio mode here.
+
+## When to use it
+
+This is where the core hyperhive tool surface lives: `send`, `recv`,
+`ask`/`answer`, `remind`, `get_loose_ends`, `set_status`,
+`get_agent_meta`, lifecycle (`kill`/`start`/`restart`/`update` on
+direct children), scheduling, and the approval-request tools. Reach
+for this crate when you're adding or changing a built-in tool rather
+than an `extraMcpServers` add-on — those are separate stdio bridges
+(see `hive-bash-mcp`, `hive-matrix-mcp`) that dial the harness socket
+or their own daemon instead of living here.
+
+## Shape
+
+- **`mcp/`** — the tool surface itself: one handler per tool, dispatch
+  through `client.rs` back into the hyperhive broker
+  (`/run/hive/mcp.sock`) or, for loose-ends v2 (todos/reminders), the
+  in-agent socket the `hive-agent` harness serves.
+- **`client.rs`** — socket client to the hyperhive broker.
+- **`send_allow.rs`** — enforces the per-agent
+  `hyperhive.allowedRecipients` allow-list on `send`/`ask`.
+- **`paths.rs`** — socket + state path resolution shared with the
+  harness's own `paths.rs` conventions.
+
+Sibling of `hive-agent` (the serve loop that renders the
+`--mcp-config` blob pointing here) and `hive-agent-wake` (the small
+CLI extra MCP daemons use to nudge claude on external events, since
+they don't have a tool surface of their own to call `remind`/`send`
+through). Standalone bin crate so the always-on MCP server doesn't
+need to link the whole turn-loop lib.
diff --git a/hive-agent-wake/Cargo.toml b/hive-agent-wake/Cargo.toml
index 2fa7aa0b..4ca8125f 100644
--- a/hive-agent-wake/Cargo.toml
+++ b/hive-agent-wake/Cargo.toml
@@ -2,6 +2,7 @@
 name = "hive-agent-wake"
 version.workspace = true
 edition.workspace = true
+readme = "README.md"
 
 [[bin]]
 name = "hive-agent-wake"
diff --git a/hive-agent-wake/README.md b/hive-agent-wake/README.md
new file mode 100644
index 00000000..3aae7618
--- /dev/null
+++ b/hive-agent-wake/README.md
@@ -0,0 +1,25 @@
+# hive-agent-wake
+
+A tiny CLI that injects a wake-up event into an agent's own harness
+inbox, so the next turn fires with a given `--from`/`--body`. That's
+the whole crate.
+
+## When to use it
+
+Reach for this when you're wiring up an `extraMcpServers` daemon
+(scraper, webhook listener, custom integration) that needs to nudge
+claude on some external event — a new item arrived, a long job
+finished, whatever. The built-in daemons (matrix, bash) don't use
+this: they talk to the per-agent MCP socket directly instead. This CLI
+exists so a helper author only needs one small, dependency-light crate
+to get the same effect without linking `hive-agent-mcp` or the full
+`hive-agent` harness lib.
+
+## Shape
+
+One binary, `src/main.rs`: parses `--socket` (defaults to
+`/run/hive/mcp.sock`, the per-agent MCP socket bind-mounted from the
+host), `--from`, and `--body` (pass `-` to read the body from stdin),
+dials the socket with `hive-core-agent-sock`'s `Request`/`Response`
+wire types, sends a `Wake` request, and exits. It carries its own copy
+of the retrying request client rather than depending on `hive-agent-mcp`'s.
diff --git a/hive-agent/Cargo.toml b/hive-agent/Cargo.toml
index e09c6da8..9a062408 100644
--- a/hive-agent/Cargo.toml
+++ b/hive-agent/Cargo.toml
@@ -2,6 +2,7 @@
 name = "hive-agent"
 edition.workspace = true
 version.workspace = true
+readme = "README.md"
 
 [lints]
 workspace = true
diff --git a/hive-agent/README.md b/hive-agent/README.md
new file mode 100644
index 00000000..49416e8f
--- /dev/null
+++ b/hive-agent/README.md
@@ -0,0 +1,52 @@
+# hive-agent
+
+The in-container harness serve-loop binary — one instance per agent.
+Long-polls the broker inbox and drives one `claude --print` turn per
+inbox message, over the `hive-claude` driver. There is one role here
+(agent); the `Surface` trait + `AgentSurface` zero-sized type tag keep
+the turn loop generic and testable for future roles without a
+parallel copy of the loop.
+
+## When to use it
+
+You don't call into this crate from elsewhere — it's the top-level
+binary systemd starts per agent container. Look here when you need to
+understand or change: what happens between "a message lands in the
+inbox" and "claude produces a reply", how login/auth is bootstrapped,
+how the per-agent web UI is served, or how turn/event stats get
+recorded. Architecture detail lives in
+[`docs/turn-loop.md`](../docs/turn-loop.md); this README is just the
+map of the module tree.
+
+## Shape
+
+- **`turn.rs`** — the turn-loop policy layer: renders the system
+  prompt + MCP config, invokes `hive-claude`, classifies the outcome,
+  and feeds the event/turn-stats sinks.
+- **`client.rs`** — broker client (inbox poll, ack, send) speaking the
+  `hive-sh4re` wire protocol.
+- **`login.rs` / `login_session.rs`** — first-run and session-resume
+  auth flow for the `claude` CLI.
+- **`mcp_config.rs`** — renders the per-turn `--mcp-config` /
+  `--allowedTools` blob from tool groups + capabilities.
+- **`todos.rs` / `reminders.rs` / `todo_server.rs`** — the harness-local
+  loose-ends v2 stores (sqlite-backed) and the in-agent socket server
+  extra MCP daemons + `hive-agent-mcp` dial into for todo/reminder ops.
+- **`vacuum.rs`** — periodic sqlite vacuum sweep for the harness-local
+  stores.
+- **`events.rs` / `turn_stats.rs` / `stats.rs`** — append-only event
+  sink and per-turn telemetry recording (context usage, cost, tool
+  favorites) under `harness/`.
+- **`forge_notify.rs`** — subscribes to forge notifications and wakes
+  the harness on new activity.
+- **`prompt.rs`** — system-prompt renderer (persona + tool docs +
+  environment facts).
+- **`web_ui/`** — the per-agent dashboard (terminal pane, status,
+  schedules) served over the built-in `hive-agent` web port.
+- **`paths.rs`** — canonical path resolution for state/harness dirs and
+  the harness-local sqlite files.
+
+Siblings: **`hive-agent-mcp`** (the MCP server this loop points claude
+at every turn) and **`hive-agent-wake`** (external wake CLI for extra
+MCP daemons). All three are described together in
+[`docs/turn-loop.md::Harness binary shape`](../docs/turn-loop.md).
diff --git a/hive-bash-mcp/Cargo.toml b/hive-bash-mcp/Cargo.toml
index e1f2a766..77b995b0 100644
--- a/hive-bash-mcp/Cargo.toml
+++ b/hive-bash-mcp/Cargo.toml
@@ -2,6 +2,7 @@
 name = "hive-bash-mcp"
 edition.workspace = true
 version.workspace = true
+readme = "README.md"
 
 [lints]
 workspace = true
diff --git a/hive-bash-mcp/README.md b/hive-bash-mcp/README.md
new file mode 100644
index 00000000..843a90ac
--- /dev/null
+++ b/hive-bash-mcp/README.md
@@ -0,0 +1,36 @@
+# hive-bash-mcp
+
+Per-agent background bash-task runner: a long-running daemon
+(`hive-bash-daemon`) plus the thin stdio MCP bridge
+(`hive-bash-mcp`) claude spawns each turn to talk to it. This is what
+backs the `bash_run` / `bash_status` tools agents use to kick off
+long-lived shell commands (builds, test suites, anything that
+shouldn't block a turn) and check on them later.
+
+## When to use it
+
+Look here when changing how background bash tasks are spawned,
+tracked, or surfaced. The daemon owns all subprocess lifecycle
+(`sh -c` spawn, completion monitoring, task state files under
+`harness/bash-tasks/`) and pushes task-completion todos onto the
+harness's in-agent socket so they show up in `get_loose_ends`. The
+bridge binary is deliberately dumb: no subprocess management, just a
+unix-socket round-trip per tool call, so it cold-starts in
+milliseconds every turn.
+
+## Shape
+
+Two bins from one shared lib (`src/lib.rs`):
+
+- **`hive-bash-daemon`** (`src/main.rs`) — the long-running daemon.
+  `runner.rs` is the spawn/monitor loop and pushes todos on task
+  transitions; `socket.rs` serves the daemon's own unix socket for
+  tool-call requests from the bridge.
+- **`hive-bash-mcp`** (`src/bin/mcp.rs`) — the stdio MCP server claude
+  spawns per turn. Forwards every tool call to the daemon over the
+  socket via `protocol.rs`'s `DaemonRequest`/`DaemonResponse` and
+  returns the result.
+
+Supporting modules: **`paths.rs`** (daemon socket + agent-socket
+resolution), **`stats.rs`** (the `bash_commands` favorite-tool stat
+recorded into turn-stats.sqlite).