feat: add hud event schema v1

docs/API.md

@@ -0,0 +1,36 @@
+# API Contracts
+
+## HUD Event Schema (v1)
+
+All events written to the HUD FIFO must include `schemaVersion: 1`. The HUD
+will ignore events with an unknown schema version.
+
+### Required fields
+- `schemaVersion`: number (current: `1`)
+- `event`: string (e.g., `PreToolUse`, `PostToolUse`, `Stop`)
+- `session`: string
+- `ts`: number (epoch seconds)
+
+### Optional fields
+- `tool`: string or null
+- `toolUseId`: string
+- `input`: object or null
+- `response`: object or null
+- `permissionMode`: string
+- `transcriptPath`: string
+- `cwd`: string
+- `prompt`: string
+
+### Example
+```json
+{
+  "schemaVersion": 1,
+  "event": "PostToolUse",
+  "tool": "Read",
+  "toolUseId": "tool-1",
+  "input": { "file_path": "README.md" },
+  "response": { "duration_ms": 120 },
+  "session": "abc123",
+  "ts": 1700000000
+}
+```