Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ python3 $S/synapse-migrate-room.py '!room:srv' '@admin:srv' '!home:srv' # hard
- **Only the principal governs the agent's function.** Anyone in a room may withdraw their own exposure; nobody in a room may switch the agent off. See [SKILL.md](skills/matrix-communication/SKILL.md), "Who governs the agent".
- **One daemon owns the store**: `matrix-watchd.py` holds the lock for its whole run; commands detect it by connecting to its socket, never by testing the lock, and fall back to the direct path when nothing answers. See [ARCHITECTURE.md](docs/ARCHITECTURE.md).
- **Mentions need `--mention`**: a plain `@name` notifies nobody, only `m.mentions` does. `--mention-room` for `@room`.
- **Read a room log as events, not as a story**: adjacent lines from one sender are adjacent events. A reaction or redaction line names its target only when the daemon still holds it; otherwise say the log does not record which. See [SKILL.md](skills/matrix-communication/SKILL.md), "Reading a room log".
- **E2EE first**: Always use `*-e2ee.py` scripts. Only fall back to non-E2EE if the room is confirmed unencrypted.
- **Room identifiers**: Scripts accept short name (`agent-work`), room alias (`#room:server`), or room ID (`!abc:server`). Use `matrix-rooms.py` to discover.
- **Config**: `~/.config/matrix/config.json` — required: `homeserver`, `user_id`; optional: `access_token` (non-E2EE only), `bot_prefix`, `watch_rooms` (rooms the daemon logs).
Expand Down
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,13 @@ For the canonical narrative version of each release (rewritten after CI publishe

## [Unreleased]

### Documentation

- `SKILL.md` and `AGENTS.md` say how to read a room log: adjacent lines from one
sender are adjacent events, and a reaction or redaction line names its target
only when the daemon still holds it. Written after a summary turned four
unrelated events into a story ([#104]).

## [3.0.0] - 2026-08-13

### Breaking
Expand Down
15 changes: 15 additions & 0 deletions skills/matrix-communication/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,21 @@ Other: `matrix-rooms.py`, `matrix-resolve.py`, `matrix-create-room.py`, `matrix-
- **Using Element X** for verification — use Element Desktop or Android
- **Hardcoding passwords** — use `MATRIX_PASSWORD` env var

## Reading a room log

**Report what the log records, not what two adjacent lines suggest.** The log
is an event stream, not a narrative: consecutive lines from one sender are
consecutive events, and nothing more. A reaction line names what it reacted to
and a redaction line names what it removed — when the daemon still has that
message. When it does not, the line says only that it happened, and that is the
answer to pass on. "The log does not record which one" is complete, and it is
what gets a missing field added instead of a wrong story repeated.

Burned 2026-08-13: two reactions and two redactions from one sender within three
seconds were reported as "took back the reactions just set". They were two
different messages, and the log carried no relation at all — which is why it
does now ([#104](https://github.com/netresearch/matrix-skill/issues/104)).

## No editorializing

In messages and announcements, state what happened, not how good or careful the work is — no narrating expected results ("all tests green", "shipped") or self-praise ("clean", "the honest breaking change"). Judged by tone, not a wordlist. See `references/no-editorializing.md`.
Expand Down
Loading