From 76040407b67f93931266ba7cba464d6d9cf482eb Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 16:09:25 +0200 Subject: [PATCH] docs(tools/matrix): update wake body format to reflect rich unread summary The matrix wake body description said '[matrix] in : ...' (old single-line teaser). After feat(#1137) it's now a richer format: - Single room, 1 message: terse one-liner with sender + body - Single room, N messages: count + room name - Multi-room: bulleted list with per-room summaries Also note that the same breakdown appears in get_loose_ends via the UnreadMatrix entry. --- docs/tools/matrix.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) 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.