From b6d6d9e41e1e60efa45405505d1054e998dbe94d Mon Sep 17 00:00:00 2001
From: Levi Neely <lneely@pascom.net>
Date: Tue, 6 Oct 2026 12:45:18 +0200
Subject: [PATCH] doc: add event topics reference

---
 doc/event-topics.md | 73 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 doc/event-topics.md

diff --git a/doc/event-topics.md b/doc/event-topics.md
new file mode 100644
index 0000000..5aabb80
--- /dev/null
+++ b/doc/event-topics.md
@@ -0,0 +1,73 @@
+# Event Topics Reference
+
+All events published to the `event` stream follow hierarchical topic naming.
+
+## Topic Format
+
+```
+session.{sessionId}.{type}
+session.{sessionId}.agent.{agentId}.{type}
+```
+
+## Session Events
+
+| Topic | Payload | Description |
+|-------|---------|-------------|
+| `session.{sid}.new` | `{name}` | Session created |
+| `session.{sid}.kill` | — | Session destroyed |
+| `session.{sid}.rename` | `{oldName} {newName}` | Session renamed |
+| `session.{sid}.pause` | — | Session paused |
+| `session.{sid}.resume` | — | Session resumed |
+| `session.{sid}.bypass.request` | `{id}\t{cmd}\t{cwd}` | Bypass approval requested |
+
+## Agent Events
+
+| Topic | Payload | Description |
+|-------|---------|-------------|
+| `session.{sid}.agent.{aid}.new` | — | Agent created |
+| `session.{sid}.agent.{aid}.kill` | — | Agent destroyed |
+| `session.{sid}.agent.{aid}.state` | `{state}` | State changed (idle, calling, thinking, paused) |
+
+## Filter Patterns
+
+Subscribe to specific events using the streaming rdwr pattern:
+
+```bash
+# All events
+ollie-9p read event
+
+# All session events
+echo "session.*" | ollie-9p rdwrs event
+
+# State changes for all agents
+echo "session.*.agent.*.state" | ollie-9p rdwrs event
+
+# All events for one session
+echo "session.abc123.>" | ollie-9p rdwrs event
+
+# Bypass requests only
+echo "session.*.bypass.>" | ollie-9p rdwrs event
+```
+
+## Filter Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `*` | Exactly one segment |
+| `>` | One or more segments (must be last) |
+| `literal` | Exact match |
+
+## Hierarchical Publishing
+
+Events are published to their topic and all parent wildcards:
+
+```
+session.abc.agent.xyz.state
+  → session.abc.agent.xyz.*
+  → session.abc.agent.*
+  → session.abc.*
+  → session.*
+  → *
+```
+
+This allows subscribing at any level of granularity.