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

hive-agent/Cargo.toml

@@ -2,6 +2,7 @@
 name = "hive-agent"
 edition.workspace = true
 version.workspace = true
+readme = "README.md"
 
 [lints]
 workspace = true

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).