Collapse doc/ and docs/

doc/claude-code-transcript-format.md

@@ -0,0 +1,97 @@
+# Claude Code Transcript Format
+
+Claude Code stores session transcripts as JSONL files (one JSON object per
+line) in `~/.claude/projects/<project-slug>/<session-uuid>.jsonl`.
+
+## Common fields
+
+Every line has:
+- `type` — message type (see below)
+- `uuid` — unique ID for this message
+- `parentUuid` — links to preceding message (forms a chain)
+- `sessionId` — session UUID (matches the filename stem)
+- `timestamp` — ISO 8601
+- `cwd`, `version`, `gitBranch` — session context
+
+## Message types
+
+### `user`
+
+User input or tool results. `message.content` is either:
+- A string (plain user text)
+- An array of content blocks, each with `type`:
+  - `"tool_result"` — result of a tool call, with `tool_use_id`, `content`
+    (string or array of text/image blocks), `is_error`
+
+User messages that start a compaction segment begin with:
+```
+This session is being continued from a previous conversation that ran out of context.
+```
+These are injected by Claude Code when context is compacted.
+
+Additional fields on user messages:
+- `userType` — `"external"` for human input, may differ for system-injected
+- `todos` — task list state
+- `permissionMode` — permission level for the session
+
+### `assistant`
+
+Model responses. `message` contains the full API response:
+- `model` — model ID (e.g. `"claude-opus-4-6"`)
+- `role` — `"assistant"`
+- `content` — array of content blocks:
+  - `{"type": "text", "text": "..."}` — text output
+  - `{"type": "tool_use", "id": "...", "name": "Bash", "input": {...}}` — tool call
+- `stop_reason` — why generation stopped
+- `usage` — token counts (input, output, cache hits)
+
+Additional fields:
+- `requestId` — API request ID
+
+### `system`
+
+System events. Has `subtype` field:
+- `"stop_hook_summary"` — hook execution results at end of turn
+  - `hookCount`, `hookInfos` (command + duration), `hookErrors`
+  - `preventedContinuation`, `stopReason`
+
+### `progress`
+
+Hook execution progress. `data` contains:
+- `type` — e.g. `"hook_progress"`
+- `hookEvent` — trigger event (e.g. `"PostToolUse"`)
+- `hookName` — specific hook (e.g. `"PostToolUse:Bash"`)
+- `command` — hook command path
+
+### `queue-operation`
+
+User input queued while assistant is working:
+- `operation` — `"enqueue"`
+- `content` — the queued text
+
+### `file-history-snapshot`
+
+File state snapshots for undo/redo:
+- `snapshot.trackedFileBackups` — map of file paths to backup state
+
+## Compaction segments
+
+Long-running sessions hit context limits and get compacted. Each compaction
+injects a user message starting with the marker text (see above), containing
+a summary of the preceding conversation. This splits the transcript into
+segments:
+
+- Segment 0: original conversation start through first compaction
+- Segment 1: first compaction summary through second compaction
+- Segment N: Nth compaction through next (or end of file)
+
+Segments are append-only — new compactions add higher-indexed segments.
+Existing segment indices are stable and never shift.
+
+## File lifecycle
+
+- Created when a session starts
+- Grows as messages are exchanged
+- Grows further when compaction happens (summary injected, conversation continues)
+- Never truncated or rewritten
+- Becomes stale when the session ends (no process has the file open)