diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md
index 818e2bdb..a6ea36ac 100644
--- a/docs/tools/matrix.md
+++ b/docs/tools/matrix.md
@@ -60,6 +60,18 @@ The same per-room breakdown is included in the `UnreadMatrix` entry
 returned by `get_loose_ends` so unread rooms surface in the
 loose-ends list between turns.
 
+**Invite wakes**: when the daemon's sync loop receives an
+`m.room.member` invite event, it writes the invite to
+`mcp-loose-ends/matrix.json` and fires a hyperhive wake. The daemon
+does **not** auto-join — the agent calls `list_invites` to see pending
+invites and `join_room` to accept (or ignore).
+
+**Pending invites as loose ends**: pending invites are written to
+`mcp-loose-ends/matrix.json` and appear in `get_loose_ends` output as
+`[matrix] pending invite: <room> — use list_invites to see, join_room
+to accept`. The file is updated atomically after each invite event
+and after each `join_room` call clears the entry.
+
 See [`docs/matrix.md`](../matrix.md) for the homeserver setup,
 provisioning flow, and federation config.