diff --git a/CLAUDE.md b/CLAUDE.md
index adb63e4..6266282 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,6 +35,17 @@ The channel boundary between `tui` and `core` is critical — never bypass it. T
 - Async functions should be cancel-safe where possible
 - Use `tracing` for structured logging, not `println!` or `log`
 
+## Documentation
+
+Prefer a literate style: doc comments should explain *why* and *how*, not just restate the signature.
+
+When a function or type implements an external protocol or spec:
+- Document the relevant portion of the protocol inline (packet shapes, event sequences, state machines)
+- Link to the authoritative external source — API reference, RFC, WHATWG spec, etc.
+- Include a mapping table or lifecycle diagram when there are multiple cases to distinguish
+
+For example, `run_stream` in `src/provider/claude.rs` documents the full SSE event sequence in a text diagram and links to both the Anthropic streaming reference and the WHATWG SSE spec. Aim for that level of context in any code that speaks a wire format or external API.
+
 ## Conversation Data Model
 
 Events use parent IDs forming a tree (not a flat list). This enables future branching. Every event has: id, parent_id, timestamp, event_type, token_usage. A "turn" is all events between two user messages — this is the unit for token tracking.