docs: matrix MCP per-agent option + tool surface (follow-up to #603)

docs/turn-loop.md

@@ -284,6 +284,28 @@ Identity = socket: anything that can connect to
 which is fine because the bind-mount is the agent's own
 container only.
 
+### Built-in matrix MCP (`mcp__matrix__*`)
+
+When `hyperhive.matrix.enable = true` (default) and the host-level
+matrix tuwunel is configured, the harness auto-injects `hive-matrix-mcp`
+as a second stdio MCP server. Tools land as `mcp__matrix__<name>`:
+
+- `send_message(room_id, body, format?)` — send a plain or markdown message
+- `send_dm(user_id, body, format?)` — send a direct message to a matrix user
+- `send_reaction(room_id, event_id, key)` — react to a message
+- `send_reply(room_id, event_id, body, format?)` — threaded reply
+- `mark_read(room_id, event_id)` — advance the read receipt
+- `list_rooms()` — enumerate joined rooms (id + name + unread count)
+- `list_room_members(room_id)` — members of a room
+- `read_room(room_id, limit?)` — recent timeline events
+
+The daemon (`hive-matrix-daemon`) holds the long-running matrix-sdk
+`Client` + sync loop; the stdio bridge (`hive-matrix-mcp`) is spawned
+per turn and forwards tool calls over `/run/hive-matrix.sock`. Both
+silently exit when `<state>/matrix-token` is absent (account not yet
+provisioned). Incoming room events wake the agent via `AgentRequest::Wake`
+with `from: "matrix"` and a teaser body (`[matrix] @sender in #room: …`).
+
 ### Extra MCP servers (per-agent)
 
 Each agent's NixOS config can declare additional MCP servers via