feat: refresh docs and agent schema

docs/universal-api.mdx

@@ -0,0 +1,30 @@
+---
+title: "Universal API"
+description: "Feature checklist and normalization rules."
+---
+
+## Feature checklist
+
+- [x] Session creation and lifecycle events
+- [x] Message streaming (assistant and tool messages)
+- [x] Tool call and tool result normalization
+- [x] File and image parts
+- [x] Human-in-the-loop questions
+- [x] Permission prompts and replies
+- [x] Plan approval normalization (Claude -> question)
+- [x] Event streaming over SSE
+- [ ] Persistent storage (out of scope)
+
+## Normalization rules
+
+- **Session ID** is always the client-provided ID.
+- **Agent session ID** is surfaced in events but never replaces the primary session ID.
+- **Tool calls** map to `UniversalMessagePart::ToolCall` and results to `ToolResult`.
+- **File and image parts** map to `AttachmentSource` with `Path`, `Url`, or base64 `Data`.
+
+## Agent mode vs permission mode
+
+- **agentMode**: behavior or system prompt strategy (build/plan/custom).
+- **permissionMode**: capability restrictions (default/plan/bypass).
+
+These are separate concepts and must be configured independently.