diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index ce68fd72..818e2bdb 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -46,8 +46,19 @@ silently exit when `/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] in : …`). +`from: "matrix"`. The wake body format depends on the unread state: + +- **Single room, one message**: `[matrix] in : — + use read_room to view, mark_read to clear` +- **Single room, multiple messages**: `[matrix] N unread in — + use read_room to view, mark_read to clear` +- **Multiple rooms**: `[matrix] unread messages:` followed by a + bulleted list (`- : : ` or `- : N unread` + per room) + +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. See [`docs/matrix.md`](../matrix.md) for the homeserver setup, provisioning flow, and federation config.