docs(#1251): split MCP tool docs into docs/tools/ sub-mds by feature

docs/tools/matrix.md

@@ -0,0 +1,62 @@
+# Matrix MCP tools and extra MCP servers
+
+## Built-in matrix MCP (`mcp__matrix__*`)
+
+When `hyperhive.matrix.enable = true` 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>`:
+
+### Messaging
+
+- `send_message(room, body)` — send a markdown message; `room`
+  accepts `!id:server` or `#alias:server`, daemon resolves either
+- `send_dm(user_id, body)` — send a direct message to a matrix user
+- `send_reply(room, event_id, body)` — threaded reply to a specific
+  event
+- `send_reaction(room, event_id, key)` — react to a message with an
+  emoji key
+
+### Reading
+
+- `read_room(room, limit?)` — recent timeline events
+- `list_rooms()` — enumerate joined rooms
+  (`{ id, canonical_alias, name, member_count }` per room)
+- `list_room_members(room)` — members of a room
+
+### Receipts
+
+- `mark_read(room, event_id)` — advance the read receipt
+
+## Architecture
+
+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>: <first-100c>…`).
+
+See [`docs/matrix.md`](../matrix.md) for the homeserver setup,
+provisioning flow, and federation config.
+
+## Extra MCP servers (per-agent)
+
+Each agent's NixOS config can declare additional MCP servers via
+`hyperhive.extraMcpServers.<key> = { command, args, env,
+allowedTools }`. The module writes the map to
+`/etc/hyperhive/extra-mcp.json`; the harness reads it at boot and
+merges every entry into `--mcp-config` (under `mcpServers.<key>`)
+and `--allowedTools` (as `mcp__<key>__<pattern>`).
+
+The agent's `flake.nix` forwards every flake input to `agent.nix` as
+the `flakeInputs` module arg, so external MCP-server flakes are pulled
+in by adding them to `inputs.*` and referenced as
+`flakeInputs.<name>.packages.${pkgs.system}.default` — the resolved
+sha lands in the agent's own `flake.lock` and rolls up to meta's.
+
+`allowedTools` defaults to `["*"]`, which expands to
+`mcp__<key>__*` (every tool from that server auto-approved). Restrict
+to specific tool names when you want finer control.