diff --git a/README.md b/README.md
index ff542931..83aa3084 100644
--- a/README.md
+++ b/README.md
@@ -151,7 +151,8 @@ the container as environment variables. Common options:
   auto-injects `hive-matrix-mcp` as a stdio MCP server so claude can
   call the matrix tools (`mcp__matrix__send_message`, `send_dm`,
   `send_reaction`, `send_reply`, `mark_read`, `list_rooms`,
-  `list_room_members`, `read_room`). Silently no-ops when
+  `list_room_members`, `read_room`; `room` args accept both
+  `!id:server` and `#alias:server` forms). Silently no-ops when
   `<state>/matrix-token` is absent (i.e., the host-level
   `hyperhive.matrix` tuwunel container hasn't provisioned the account
   yet). Set to `false` to opt a specific agent out of matrix.
diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index d19d3546..de3c3297 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -290,21 +290,26 @@ 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
+- `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_reaction(room, event_id, key)` — react to a message
+- `send_reply(room, event_id, body)` — threaded reply
+- `mark_read(room, event_id)` — advance the read receipt
+- `list_rooms()` — enumerate joined rooms
+  (`{ id, canonical_alias, name, member_count }` per room)
+- `list_room_members(room)` — members of a room
+- `read_room(room, 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: …`).
+with `from: "matrix"` and a teaser body
+(`[matrix] <sender> in <room>: <first-100c>…` where `<sender>` is
+the matrix user id and `<room>` is the alias or id as reported by
+the SDK).
 
 ### Extra MCP servers (per-agent)