docs(#2627): crate READMEs for the harness column (hive-agent, hive-agent-mcp, hive-agent-wake, hive-bash-mcp)

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"

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.