docs: improve documentation coverage (#52)

docs/runner/claude/claude-takopi-events.md

@@ -1,16 +1,10 @@
 # Claude Code -> Takopi event mapping (spec)
 
-This document specifies how the Claude Code runner (implemented in Takopi v0.3.0)
-translates Claude CLI `--output-format stream-json` JSONL events into Takopi events.
-It is based on the reverse-engineered schema in `humanlayer/claudecode-go`:
+This document describes how the Claude Code runner translates Claude CLI JSONL events into Takopi events.
 
-- `claudecode-go/types.go` (StreamEvent, Message, Content, Result)
-- `claudecode-go/client.go` (CLI flags, stream parsing)
-- `claudecode-go/client_test.go` (schema validation + permission_denials)
+> **Authoritative source:** The schema definitions are in `src/takopi/schemas/claude.py` and the translation logic is in `src/takopi/runners/claude.py`. When in doubt, refer to the code.
 
-The goal is to make a Claude runner feel identical to the Codex runner from the
-bridge/renderer point of view while preserving Takopi invariants (stable action
-ids, per-session serialization, single completed event).
+The goal is to make a Claude runner feel identical to the Codex runner from the bridge/renderer point of view while preserving Takopi invariants (stable action ids, per-session serialization, single completed event).
 
 ---
 

docs/runner/codex/codex-takopi-events.md

@@ -1,8 +1,12 @@
-Here’s a clean way to make “Takopi events” just **3 shapes** while still covering **every `codex exec --json` line type** and preserving the invariants you care about (stable IDs, resume/thread ownership, final answer delivery).  
+# Codex -> Takopi event mapping
+
+This document describes how Codex exec --json events are translated to Takopi's normalized event model.
+
+> **Authoritative source:** The schema definitions are in `src/takopi/schemas/codex.py` and the translation logic is in `src/takopi/runners/codex.py`. When in doubt, refer to the code.
 
 ## The 3-event Takopi schema
 
-I’d model it like this (JSON-ish). The important trick is: **your single `action` event needs a `phase`**, otherwise you can’t represent started/updated/completed lifecycles.
+The Takopi event model uses 3 event types. The `action` event includes a `phase` field to represent started/updated/completed lifecycles.
 
 ### 1) `started`
 
@@ -28,7 +32,7 @@ Emitted for **everything that is progress / updates / warnings / per-item lifecy
   "engine": "codex",
   "action": {
     "id": "item_5",
-    "kind": "tool",               // command | tool | file_change | web_search | note | turn | warning | telemetry
+    "kind": "tool",               // command | tool | file_change | web_search | subagent | note | turn | warning | telemetry
     "title": "docs.search",       // short label for renderer
     "detail": { ... }             // structured payload (freeform)
   },

docs/runner/opencode/opencode-takopi-events.md

@@ -1,7 +1,8 @@
 # OpenCode to Takopi Event Mapping
 
 This document describes how OpenCode JSON events are translated to Takopi's normalized event model.
-The OpenCode runner shipped in Takopi v0.5.0.
+
+> **Authoritative source:** The schema definitions are in `src/takopi/schemas/opencode.py` and the translation logic is in `src/takopi/runners/opencode.py`. When in doubt, refer to the code.
 
 ## Event Translation
 

docs/runner/pi/pi-runner.md

@@ -54,7 +54,7 @@ Takopi config lives at `~/.takopi/takopi.toml`.
 
 Add a new optional `[pi]` section.
 
-Recommended v1 schema:
+Recommended schema:
 
 ```toml
 # ~/.takopi/takopi.toml
@@ -62,18 +62,15 @@ Recommended v1 schema:
 default_engine = "pi"
 
 [pi]
-cmd = "pi"                 # optional; defaults to "pi"
-extra_args = []             # optional list of strings, appended verbatim
 model = "..."               # optional; passed as --model
 provider = "..."            # optional; passed as --provider
-session_dir = "..."         # optional; directory for session files
-session_title = "pi"        # optional; defaults to model or "pi"
+extra_args = []             # optional list of strings, appended verbatim
 ```
 
 Notes:
 
 * `extra_args` lets you pass new Pi flags without changing Takopi.
-* If `session_dir` is omitted, Takopi uses Pi's default session dir:
+* Session files are stored under Pi's default session dir:
   `~/.pi/agent/sessions/--<cwd>--` (with path separators replaced by `-`).
 
 ---

docs/runner/pi/pi-takopi-events.md

@@ -1,12 +1,10 @@
 # Pi -> Takopi event mapping (spec)
 
-This document specifies how the Pi runner shipped in Takopi v0.5.0 translates
-Pi CLI `--mode json` JSONL events into Takopi events. The Pi JSONL stream is
-`AgentSessionEvent` from `@mariozechner/pi-agent-core`.
+This document describes how the Pi runner translates Pi CLI `--mode json` JSONL events into Takopi events.
 
-The goal is to make Pi feel identical to the Codex/Claude runners from the
-bridge/renderer point of view while preserving Takopi invariants (stable action
-ids, per-session serialization, single completed event).
+> **Authoritative source:** The schema definitions are in `src/takopi/schemas/pi.py` and the translation logic is in `src/takopi/runners/pi.py`. When in doubt, refer to the code.
+
+The goal is to make Pi feel identical to the Codex/Claude runners from the bridge/renderer point of view while preserving Takopi invariants (stable action ids, per-session serialization, single completed event).
 
 ---
 
@@ -145,10 +143,9 @@ A minimal TOML config for Pi:
 
 ```toml
 [pi]
-cmd = "pi"
 model = "..."
 provider = "..."
 extra_args = []
 ```
 
-Use `extra_args` for any newer Pi CLI flags not explicitly mapped.
+Use `extra_args` for any Pi CLI flags not explicitly mapped.