docs(jsonl): add comprehensive Claude JSONL session log reference

Create authoritative documentation suite for Claude Code JSONL session
log processing, synthesized from codebase analysis, official Anthropic
documentation, and community tooling research.

Documentation structure (docs/claude-jsonl-reference/):

01-format-specification.md (214 lines):
- Complete message envelope structure with all fields
- Content block types (text, thinking, tool_use, tool_result)
- Usage object for token reporting
- Model identifiers and version history
- Conversation DAG structure via parentUuid

02-message-types.md (346 lines):
- Every message type with concrete JSON examples
- User messages (string content vs array for tool results)
- Assistant messages with all content block variants
- Progress events (hooks, bash, MCP)
- System, summary, and file-history-snapshot types
- Codex format differences (response_item, function_call)

03-tool-lifecycle.md (341 lines):
- Complete tool invocation to result flow
- Hook input/output formats (PreToolUse, PostToolUse)
- Parallel tool call handling
- Tool-to-result pairing algorithm
- Missing result edge cases
- Codex tool format differences

04-subagent-teams.md (363 lines):
- Task tool invocation and input fields
- Subagent transcript locations and format
- Team coordination (TeamCreate, SendMessage)
- Hook events (SubagentStart, SubagentStop)
- AMC spawn tracking with pending spawn registry
- Worktree isolation for subagents

05-edge-cases.md (475 lines):
- Parsing edge cases (invalid JSON, type ambiguity)
- Type coercion gotchas (bool vs int in Python)
- Session state edge cases (orphans, dead detection)
- Tool call edge cases (missing results, parallel ordering)
- Codex-specific quirks (content injection, buffering)
- File system safety (path traversal, permissions)
- Cache invalidation strategies

06-quick-reference.md (238 lines):
- File locations cheat sheet
- jq recipes for common queries
- Python parsing snippets
- Common gotchas table
- Useful constants
- Debugging commands

Also adds CLAUDE.md at project root linking to documentation and
providing project overview for agents working on AMC.

Sources include Claude Code hooks.md, headless.md, Anthropic Messages
API reference, and community tools (claude-code-log, claude-JSONL-browser).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,68 @@
+# AMC (Agent Management Console)
+
+A dashboard and management system for monitoring and controlling Claude Code and Codex agent sessions.
+
+## Key Documentation
+
+### Claude JSONL Session Log Reference
+
+**Location:** `docs/claude-jsonl-reference/`
+
+Comprehensive documentation for parsing and processing Claude Code JSONL session logs. **Always consult this before implementing JSONL parsing logic.**
+
+| Document | Purpose |
+|----------|---------|
+| [01-format-specification](docs/claude-jsonl-reference/01-format-specification.md) | Complete JSONL format spec with all fields |
+| [02-message-types](docs/claude-jsonl-reference/02-message-types.md) | Every message type with concrete examples |
+| [03-tool-lifecycle](docs/claude-jsonl-reference/03-tool-lifecycle.md) | Tool call flow from invocation to result |
+| [04-subagent-teams](docs/claude-jsonl-reference/04-subagent-teams.md) | Subagent and team message formats |
+| [05-edge-cases](docs/claude-jsonl-reference/05-edge-cases.md) | Error handling, malformed input, recovery |
+| [06-quick-reference](docs/claude-jsonl-reference/06-quick-reference.md) | Cheat sheet for common operations |
+
+## Architecture
+
+### Server (Python)
+
+The server uses a mixin-based architecture in `amc_server/`:
+
+| Module | Purpose |
+|--------|---------|
+| `server.py` | Main AMC server class combining all mixins |
+| `mixins/parsing.py` | JSONL reading and token extraction |
+| `mixins/conversation.py` | Claude/Codex conversation parsing |
+| `mixins/state.py` | Session state management |
+| `mixins/discovery.py` | Codex session auto-discovery |
+| `mixins/spawn.py` | Agent spawning via Zellij |
+| `mixins/control.py` | Session control (focus, dismiss) |
+| `mixins/skills.py` | Skill enumeration |
+| `mixins/http.py` | HTTP routing |
+
+### Dashboard (React)
+
+Single-page app in `dashboard/` served via HTTP.
+
+## File Locations
+
+| Content | Location |
+|---------|----------|
+| Claude sessions | `~/.claude/projects/<encoded-path>/<session-id>.jsonl` |
+| Codex sessions | `~/.codex/sessions/**/<session-id>.jsonl` |
+| AMC session state | `~/.local/share/amc/sessions/<session-id>.json` |
+| AMC event logs | `~/.local/share/amc/events/<session-id>.jsonl` |
+| Pending spawns | `~/.local/share/amc/pending_spawns/<spawn-id>.json` |
+
+## Critical Parsing Notes
+
+1. **Content type ambiguity** — User message `content` can be string (user input) OR array (tool results)
+2. **Missing fields** — Always use `.get()` with defaults for optional fields
+3. **Boolean vs int** — Python's `isinstance(True, int)` is True; check bool first
+4. **Partial reads** — When seeking to file end, first line may be truncated
+5. **Codex differences** — Uses `response_item` type, `function_call` for tools
+
+## Testing
+
+```bash
+pytest tests/
+```
+
+All parsing edge cases are covered in `tests/test_parsing.py` and `tests/test_conversation.py`.