diff --git a/docs/ZOT-RPC-TRANSCRIPT.md b/docs/ZOT-RPC-TRANSCRIPT.md
new file mode 100644
index 0000000..30f641b
--- /dev/null
+++ b/docs/ZOT-RPC-TRANSCRIPT.md
@@ -0,0 +1,72 @@
+# zot rpc transcript — DeepSeek (2026-06-21)
+
+## Request shape
+
+```json
+{"id":"1","type":"prompt","message":"check the current directory"}
+```
+
+zot uses its own protocol, NOT JSON-RPC 2.0. The `type` field is `prompt`,
+`id` is a correlation string.
+
+## Raw stdout (secrets redacted, auth failed — key was placeholder)
+
+```json
+{"command":"prompt","data":{"started":true},"id":"1","success":true,"type":"response"}
+{"content":[{"text":"check the current directory","type":"text"}],"time":"2026-06-21T22:36:06.817Z","type":"user_message"}
+{"step":1,"type":"turn_start"}
+{"error":"deepseek: http 401: ...","stop":"error","type":"turn_end"}
+{"message":"deepseek: http 401: ...","type":"error"}
+{"type":"done"}
+```
+
+## Wire format decision
+
+**Bare event objects.** Each line is a plain JSON object with a `type` field.
+No JSON-RPC envelope (no `jsonrpc`, `method`, `params` wrapping). This
+matches glasspane's `zot_event_type` parser exactly — it reads
+`value.get("type")` directly from the object.
+
+## Event types observed
+
+| Event type                | Glasspane mapping      | Status     |
+| ------------------------- | ---------------------- | ---------- |
+| `response` (success:true) | None (no state change) | ✅ Correct |
+| `user_message`            | `message_update`       | ✅ Tested  |
+| `turn_start`              | `turn_start`           | ✅ Tested  |
+| `turn_end`                | `turn_end`             | ✅ Tested  |
+| `error`                   | `error`                | ✅ Tested  |
+| `done`                    | `agent_end`            | ✅ Tested  |
+
+## Event types mapped but not in transcript (need live API key)
+
+| Event type          | Glasspane mapping       | Risk                           |
+| ------------------- | ----------------------- | ------------------------------ |
+| `assistant_start`   | `message_start`         | Low — name matches zot source  |
+| `text_delta`        | `message_update`        | Low — standard streaming event |
+| `assistant_message` | `message_end`           | Low — name matches zot source  |
+| `tool_call`         | `tool_execution_start`  | Low — name matches             |
+| `tool_use_start`    | `tool_execution_start`  | Low — name matches             |
+| `tool_use_args`     | `tool_execution_update` | Low                            |
+| `tool_progress`     | `tool_execution_update` | Low                            |
+| `tool_use_end`      | `tool_execution_update` | Low                            |
+| `tool_result`       | `tool_execution_end`    | Low                            |
+| `usage`             | None (no state change)  | Low                            |
+
+## Type values NOT in the current mapping
+
+None observed. All 6 event types from the transcript have mappings.
+The `response` type with `success:true` correctly returns None (no state change).
+
+## Verdict
+
+Wire format confirmed: bare event objects, no JSON-RPC envelope. Glasspane's
+parser shape is correct. The session-lifecycle events (turn_start, turn_end,
+error, done, user_message, response) are validated against real output.
+
+Tool-lifecycle events (`tool_call`, `tool_use_*`, `text_delta`, `assistant_*`, `tool_result`)
+are NOT yet validated — the API key was a placeholder (DeepSeek returned 401
+before reaching the agent loop). A re-run with a valid DEEPSEEK_API_KEY is
+needed to capture a real tool call before the driver can trust those mappings.
+
+Step 1 of colibri#143 remains partially open for that real-key re-run.