docs(graphs): add generated documentation atlas

docs/graphs/agent-lifecycle.md

@@ -0,0 +1,41 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.
+
+This sequence is the visual companion to [architecture.md](../architecture.md#loop-lifecycle-session--turn--step). It shows the durable session event path separately from live `agent/*` notifications.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Loop
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant Persistence
+  User->>Agent: send(content)
+  Agent->>Loop: queued work wakes driver
+  Loop->>Session: turn/start + user/message
+  Loop-->>User: agent/turn-start
+  Loop->>Prompt: system-prompt/assemble waterfall
+  Loop-->>Loop: agent/pre-step serial checkpoint
+  Loop->>Session: step/start
+  Loop->>LLM: agent/request waterfall, then llm/stream waterfall
+  LLM-->>Loop: StreamChunk*
+  Loop->>Session: assistant/chunk*
+  Loop-->>User: agent/stream-chunk* (master live mirror)
+  Loop->>Session: assistant/message
+  Loop->>Tools: tools/execute waterfall for each tool-call
+  Tools-->>Session: tool-owned events when applicable
+  Loop->>Session: tool/result
+  Loop-->>Loop: agent/turn-continuation waterfall
+  Loop->>Session: turn/end
+  Loop->>Persistence: session/flush parallel checkpoint
+  Loop-->>User: agent/status idle
+```
+
+Future pressure from the hooks stack: PR #129 removes the live `agent/stream-chunk` mirror and leaves durable `assistant/chunk` on `session/event` as the authoritative token stream. Consumers that need replayable transcript data should already treat `session/event` as the load-bearing path.