Skeleton for the Coding Agent. (#1)

Reviewed-on: #1
Co-authored-by: Drew Galbraith <drew@tiramisu.one>
Co-committed-by: Drew Galbraith <drew@tiramisu.one>

CLAUDE.md

@@ -16,28 +16,46 @@ Rust TUI coding agent. Ratatui + Crossterm + Tokio. See DESIGN.md for architectu
 
 Six modules with strict boundaries:
 
-- `src/app/` — Wiring, lifecycle, tokio runtime setup
-- `src/tui/` — Ratatui rendering, input handling, vim modes. Communicates with core ONLY via channels (`UserAction` → core, `UIEvent` ← core). Never touches conversation state directly.
-- `src/core/` — Conversation tree, orchestrator loop, sub-agent lifecycle
-- `src/provider/` — `ModelProvider` trait + Claude implementation. Leaf module, no internal dependencies.
-- `src/tools/` — `Tool` trait, registry, built-in tools. Depends only on `sandbox`.
-- `src/sandbox/` — Landlock policy, path validation, command execution. Leaf module.
-- `src/session/` — JSONL logging, session read/write. Leaf module.
+- `src/app/` -- Wiring, lifecycle, tokio runtime setup
+- `src/tui/` -- Ratatui rendering, input handling, vim modes. Communicates with core ONLY via channels (`UserAction` -> core, `UIEvent` <- core). Never touches conversation state directly.
+- `src/core/` -- Conversation tree, orchestrator loop, sub-agent lifecycle
+- `src/provider/` -- `ModelProvider` trait + Claude implementation. Leaf module, no internal dependencies.
+- `src/tools/` -- `Tool` trait, registry, built-in tools. Depends only on `sandbox`.
+- `src/sandbox/` -- Landlock policy, path validation, command execution. Leaf module.
+- `src/session/` -- JSONL logging, session read/write. Leaf module.
 
-The channel boundary between `tui` and `core` is critical — never bypass it. The TUI is a frontend; core is the engine. This separation enables headless mode for benchmarking.
+The channel boundary between `tui` and `core` is critical -- never bypass it. The TUI is a frontend; core is the engine. This separation enables headless mode for benchmarking.
 
 ## Code Style
 
 - Use `thiserror` for error types, not `anyhow` in library code (`anyhow` only in `main.rs`/`app`)
 - Prefer `impl Trait` return types over boxing when possible
 - All public types need doc comments
-- No `unwrap()` in non-test code — use `?` or explicit error handling
+- No `unwrap()` in non-test code -- use `?` or explicit error handling
 - 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.
+
+Use only characters available on a standard US QWERTY keyboard in all doc comments and inline comments. Specifically:
+- Use `->` and `<-` instead of Unicode arrow glyphs
+- Use `--` instead of em dashes or en dashes
+- Use `+`, `-`, `|` for ASCII box diagrams instead of Unicode box-drawing characters
+- Use `...` instead of the ellipsis character
+- Spell out "Section N.N" instead of the section-sign glyph
+
+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.
+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.
 
 ## Testing
 
@@ -50,8 +68,8 @@ Events use parent IDs forming a tree (not a flat list). This enables future bran
 
 ## Key Constraints
 
-- All file I/O and process spawning in tools MUST go through `Sandbox` — never use `std::fs` or `std::process::Command` directly in tool implementations
-- The `ModelProvider` trait must remain provider-agnostic — no Claude-specific types in the trait interface
+- All file I/O and process spawning in tools MUST go through `Sandbox` -- never use `std::fs` or `std::process::Command` directly in tool implementations
+- The `ModelProvider` trait must remain provider-agnostic -- no Claude-specific types in the trait interface
 - Session JSONL is append-only. Never rewrite history. Branching works by writing new events with different parent IDs.
 - Token usage must be tracked per-event and aggregatable per-turn