docs: revamp README with improved structure and visuals

- Complete README rewrite with better visual hierarchy
- New tagline: "Track Claude Code Sessions Better Than Ever"
- Emphasize Respawn Controller as key feature for autonomous work
- Add ASCII art diagrams for architecture and token lifecycle
- Add feature comparison tables
- Include Ralph Wiggum loop screenshot
- Add comprehensive API reference section
- Improve Quick Start section with clear prerequisites
- Add FAQ section
- Remove TUI references (feature not ready)
- Update GitHub clone URL

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

README.md

@@ -1,393 +1,494 @@
-<h1 align="center">🤖 Claudeman</h1>
+<h1 align="center">
+  <br>
+  🤖 Claudeman
+  <br>
+</h1>
+
+<h3 align="center">Track Claude Code Sessions Better Than Ever</h3>
 
 <p align="center">
-  <strong>The missing control plane for Claude Code.</strong><br>
-  Run 20 autonomous agents. Track them in real-time. Never lose work again.
+  <em>Run 20 agents in parallel. Track them in real-time. The Respawn Controller keeps them working while you sleep.</em>
 </p>
 
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-blue" alt="TypeScript"></a>
-  <a href="./test"><img src="https://img.shields.io/badge/tests-355%20passing-brightgreen" alt="Tests"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js 18+"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-blue" alt="TypeScript 5.5"></a>
+  <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-black" alt="Fastify"></a>
+  <img src="https://img.shields.io/badge/tests-258%20passing-brightgreen" alt="Tests">
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#features">Features</a> •
-  <a href="#ralph-loop">Ralph Loops</a> •
-  <a href="#api-reference">API</a> •
-  <a href="./CLAUDE.md">Full Docs</a>
+  <a href="#-the-problem">Problem</a> •
+  <a href="#-the-solution">Solution</a> •
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-features">Features</a> •
+  <a href="#-ralph-wiggum-loops">Ralph Loops</a> •
+  <a href="#-api">API</a>
 </p>
 
 ---
 
-## The Problem
-
-You're running Claude Code for a complex refactor. 3 hours in:
-
-- 💥 **Session crashes** — your context is gone
-- 🔄 **Token limit hit** — manual `/clear` interrupts flow
-- 😴 **You went to sleep** — Claude finished at 2am and sat idle for 6 hours
-- 🤯 **5 parallel sessions** — which one had the auth fix again?
-
-**Claude Code is powerful. Managing it shouldn't be painful.**
+<p align="center">
+  <img src="docs/screenshots/main-interface.png" alt="Claudeman Dashboard" width="900">
+</p>
 
 ---
 
-## The Solution
+## 🚨 The Problem
+
+You're running Claude Code on a complex refactor. **Three hours in:**
+
+| Issue | Impact |
+|-------|--------|
+| 💥 **Session crashes** | All your context is gone. Start over. |
+| 🔄 **Token limit hit** | Forced to manually `/clear` — breaks your flow |
+| 😴 **You went to sleep** | Claude finished at 2am, sat idle for 6 hours |
+| 🤯 **5 parallel sessions** | Which one had the auth fix? Where's the API changes? |
+| 💸 **Surprise costs** | No visibility into token usage until the bill arrives |
+
+**Claude Code is incredibly powerful.**
+**Now you can track and manage it like never before.**
+
+---
+
+## ✨ The Solution
 
 ```bash
+git clone https://github.com/Ark0N/claudeman.git && cd claudeman
 npm install && npm run build
 claudeman web
-# → http://localhost:3000
 ```
 
-<p align="center">
-  <img src="docs/screenshots/main-interface.png" alt="Claudeman Interface" width="800" />
-</p>
+**Open http://localhost:3000** and you get:
 
-**Claudeman gives you:**
+<table>
+<tr>
+<td width="50%">
 
-✨ **20 parallel sessions** with independent terminals and state
-🔄 **Autonomous respawn** — sessions restart automatically when idle
-📊 **Real-time monitoring** — tokens, costs, memory, all at a glance
-💾 **GNU Screen persistence** — survives crashes, restarts, network failures
-🎯 **Ralph Loop tracking** — detect `<promise>COMPLETE</promise>` and todos automatically
+### 🖥️ Multi-Session Dashboard
+- **20 parallel sessions** with real-time terminals
+- Tab-based navigation with keyboard shortcuts
+- Per-session token tracking and cost monitoring
+- One-click bulk operations
+
+</td>
+<td width="50%">
+
+### 💾 Crash-Proof Persistence
+- Every session runs in **GNU Screen**
+- Survives server restarts, network drops, machine sleep
+- Auto-discovery of orphaned sessions on startup
+- Never lose work again
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🔄 Respawn Controller
+- **The key to autonomous work while you sleep**
+- Detects when Claude becomes idle and restarts work
+- Auto-cycles `/clear` → `/init` to continue fresh
+- Keeps going even if Ralph Wiggum loops stop
+- Run for **24+ hours** completely unattended
+
+</td>
+<td width="50%">
+
+### 🎯 Ralph Loop Tracking
+- Detects `<promise>COMPLETE</promise>` patterns
+- Tracks TodoWrite progress (`- [x]`, `- [ ]`)
+- Shows iteration count (`[5/50]`)
+- Real-time progress visualization
+
+</td>
+</tr>
+</table>
 
 ---
 
-## Requirements
+## 🚀 Quick Start
 
-- **Node.js 18+** — ES2022 features required
-- **Claude CLI** — `claude` command must be in PATH ([Install guide](https://claude.ai/code))
-- **GNU Screen** — for session persistence (`apt install screen` or `brew install screen`)
+### Prerequisites
 
----
+| Requirement | Why |
+|-------------|-----|
+| **Node.js 18+** | ES2022 module syntax |
+| **Claude CLI** | `claude` command in PATH ([Install](https://claude.ai/code)) |
+| **GNU Screen** | Session persistence (`apt install screen` / `brew install screen`) |
 
-## Quick Start
-
-### 1. Install
+### Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/yourusername/claudeman.git
+# Clone and install
+git clone https://github.com/Ark0N/claudeman.git
 cd claudeman
-
-# Install dependencies and build
 npm install
 npm run build
 
-# Optional: make 'claudeman' available globally
+# Make 'claudeman' available globally (optional)
 npm link
 ```
 
-### 2. Launch
+### Launch
 
 ```bash
+# Production
 claudeman web
-# Or for development: npx tsx src/index.ts web
+
+# Development (no build required)
+npx tsx src/index.ts web
+
+# Custom port
+claudeman web -p 8080
 ```
 
-### 3. Create Your First Session
+### Your First Session
 
-1. Open http://localhost:3000
-2. Press `Ctrl+Enter` or click **"Run Claude"**
-3. Start coding — your session is now persistent and monitored
+1. Open **http://localhost:3000**
+2. Press **`Ctrl+Enter`** or click **"Run Claude"**
+3. Your session is now:
+   - ✅ Running in GNU Screen (persistent)
+   - ✅ Tracking tokens and costs
+   - ✅ Ready for Ralph Loop detection
 
 ---
 
-## Features
+## 🎮 Features
 
-### 🖥️ Multi-Session Management
+### Real-Time Terminal Streaming
 
-Spawn up to **20 parallel Claude sessions**, each with:
-- Full xterm.js terminal with resize support
-- Independent token tracking and cost monitoring
-- One-click kill or bulk session management
-- Tab-based navigation with keyboard shortcuts
+<p align="center">
+  <img src="docs/screenshots/session-running.png" alt="Terminal Streaming" width="800">
+</p>
 
-### 💾 Session Persistence
+- **60fps rendering** — Server batches at 16ms, client uses `requestAnimationFrame`
+- **Full xterm.js** — Colors, cursor, resize, selection, everything works
+- **No polling** — Real-time SSE for instant updates
 
-**Never lose work again.** Every session runs in GNU Screen:
+### Smart Token Management
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TOKEN LIFECYCLE                          │
+├─────────────────────────────────────────────────────────────┤
+│  0k ─────────── 110k ─────────── 140k ─────────── 200k     │
+│                   │                │                        │
+│                   ▼                ▼                        │
+│              Auto-Compact     Auto-Clear                    │
+│              (/compact)       (/clear)                      │
+│                   │                │                        │
+│                   └── Summarize ───┴── Reset & Continue ─► │
+└─────────────────────────────────────────────────────────────┘
+```
+
+| Threshold | Action | What Happens |
+|-----------|--------|--------------|
+| **110k tokens** | Auto `/compact` | Context is summarized, work continues |
+| **140k tokens** | Auto `/clear` | Full reset with `/init`, fresh start |
+
+**Configure per-session:**
+```bash
+curl -X POST localhost:3000/api/sessions/:id/auto-compact \
+  -d '{"enabled": true, "threshold": 100000}'
+```
+
+### Session Persistence
+
+Every Claude session runs inside GNU Screen with environment awareness:
 
 ```bash
-# Your session survives:
-- Server restarts
-- Browser crashes
-- Network disconnects
-- Machine sleep/wake
-
-# Sessions know they're managed:
+# Inside every Claudeman session:
 CLAUDEMAN_SCREEN=1
-CLAUDEMAN_SESSION_ID=abc-123
+CLAUDEMAN_SESSION_ID=abc-123-def
 CLAUDEMAN_SCREEN_NAME=claudeman-myproject
 ```
 
-### 🔄 Autonomous Respawn
+**Why this matters:**
+- Claude knows it's in a managed session
+- Won't accidentally kill its own screen
+- The default CLAUDE.md template includes safety instructions
 
-The **Respawn Controller** keeps Claude productive while you're away:
+### Resource Monitoring
 
-```
-WATCHING → SENDING_UPDATE → WAITING → SENDING_CLEAR → SENDING_INIT → repeat
-```
+The dashboard shows real-time resource usage:
 
-Configure it once, let it run for hours:
-
-```bash
-curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
-  -d '{"config": {"updatePrompt": "continue improving the code"}, "durationMinutes": 480}'
-```
-
-### 📊 Smart Token Management
-
-| Threshold | Action | Why |
-|-----------|--------|-----|
-| 110k tokens | Auto `/compact` | Summarize context before limit |
-| 140k tokens | Auto `/clear` | Reset to prevent hard-stop |
-
-No more surprise context exhaustion. No more manual intervention.
-
-### 🎯 Ralph Loop Integration
-
-Claudeman **natively tracks Ralph Wiggum loops** running inside Claude:
-
-```
-Detected: <promise>REFACTOR_COMPLETE</promise>
-Loop: REFACTOR_COMPLETE (4.2h elapsed)
-Tasks: 8/12 complete
-```
-
-Auto-enables when it detects:
-- `<promise>PHRASE</promise>` completion patterns
-- TodoWrite usage (`- [ ]`, `- [x]`)
-- Iteration patterns (`[5/50]`, `Iteration 5 of 50`)
-- `/ralph-loop:ralph-loop` commands
-
-### ⚡ 60fps Terminal Streaming
-
-- Server batches at 16ms intervals
-- Client uses `requestAnimationFrame` for smooth rendering
-- No polling — real-time SSE for instant updates
-
-### 🚀 Performance Optimized
-
-Built for smooth operation even with multiple long-running sessions:
-
-- **CSS containment** — isolated paint operations for each component
-- **Incremental DOM updates** — only changed elements re-render
-- **Input batching** — keystrokes coalesced at 60fps
-- **Event debouncing** — reduced server load from rapid state changes
-- **Memory management** — automatic buffer trimming prevents leaks
+| Metric | Location | Warning Threshold |
+|--------|----------|-------------------|
+| Memory per session | Monitor panel | Yellow at 500MB, Red at 1GB |
+| Total screen count | Status bar | Shown with uptime |
+| Token usage | Per-session | Color-coded by threshold |
+| Cost tracking | Per-session | Running USD total |
 
 ---
 
-## Ralph Loop
+## 🔁 Ralph Wiggum Loops
 
-The **Ralph Loop** is Claudeman's killer feature — run Claude autonomously for 24+ hours.
+The **Ralph Loop** is Claudeman's killer feature: **run Claude autonomously for 24+ hours**.
+
+<p align="center">
+  <img src="docs/images/ralph-tracker-16tasks.png" alt="Ralph Loop Tracking" width="800">
+</p>
 
 ### How It Works
 
-1. **Assign task** → Claude starts working
-2. **Monitor output** → Detect completion signals
-3. **Auto-cycle** → Clear context, re-init, continue
-4. **Time-aware** → Generate follow-up tasks if minimum duration not reached
-
-### Example: Overnight Code Review
-
-```bash
-# Queue your tasks
-claudeman task add "Review all code in src/ for bugs"
-claudeman task add "Add missing test coverage"
-claudeman task add "Update documentation"
-
-# Start the loop (run for at least 8 hours)
-claudeman ralph start --min-hours 8
-
-# Go to sleep. Wake up to:
-# - All tasks completed
-# - Auto-generated follow-ups (optimizations, security checks)
-# - Full git history of changes
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    RALPH LOOP CYCLE                          │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐ │
+│  │  WATCH  │───►│  DETECT  │───►│ RESPAWN │───►│ CONTINUE│ │
+│  │  (idle) │    │ complete │    │  cycle  │    │  work   │ │
+│  └─────────┘    └──────────┘    └─────────┘    └────┬────┘ │
+│       ▲                                              │      │
+│       └──────────────────────────────────────────────┘      │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-### Completion Detection
+### Detection Patterns
 
-| Pattern | Example |
-|---------|---------|
-| Promise tags | `<promise>COMPLETE</promise>` |
-| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` |
-| Common indicators | "All tasks completed", "✓ Done" |
+Claudeman automatically detects Ralph loops when it sees:
+
+| Pattern | Example | Auto-Enables |
+|---------|---------|--------------|
+| Promise tags | `<promise>COMPLETE</promise>` | ✅ |
+| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` | ✅ |
+| TodoWrite | `- [ ] Task`, `- [x] Done` | ✅ |
+| Iterations | `[5/50]`, `Iteration 5 of 50` | ✅ |
+| Skill command | `/ralph-loop:ralph-loop` | ✅ |
+
+### Running a Ralph Loop
+
+**Via CLI:**
+```bash
+# Queue tasks
+claudeman task add "Review all files in src/ for security issues"
+claudeman task add "Add comprehensive test coverage"
+claudeman task add "Update all documentation"
+
+# Start loop (minimum 8 hours)
+claudeman ralph start --min-hours 8
+
+# Check status
+claudeman ralph status
+```
+
+**Via API:**
+```bash
+# Enable respawn with timer
+curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
+  -H "Content-Type: application/json" \
+  -d '{
+    "config": {
+      "updatePrompt": "continue improving the codebase",
+      "idleTimeoutMs": 5000
+    },
+    "durationMinutes": 480
+  }'
+```
+
+### Time-Aware Loops
+
+When you specify a minimum duration, Claudeman:
+
+1. Completes all primary tasks
+2. Checks elapsed time
+3. **If minimum not reached:** Generates follow-up tasks
+   - Code optimization
+   - Test coverage improvements
+   - Security hardening
+   - Documentation gaps
+4. Only outputs completion phrase when time is met
 
 ---
 
-## Web Interface
-
-### Keyboard Shortcuts
+## ⌨️ Keyboard Shortcuts
 
 | Shortcut | Action |
 |----------|--------|
-| `Ctrl+Enter` | Create case + start session |
+| `Ctrl+Enter` | Quick-start: Create case + start session |
 | `Ctrl+W` | Close current session |
-| `Ctrl+Tab` | Next session |
+| `Ctrl+Tab` | Switch to next session |
+| `Ctrl+Shift+Tab` | Switch to previous session |
 | `Ctrl+K` | Kill all sessions |
 | `Ctrl+L` | Clear terminal |
-| `Ctrl++/-` | Adjust font size |
-
-### Monitor Panel
-
-Real-time visibility into:
-- **Screen sessions** — status, uptime, mode
-- **Background tasks** — Claude's spawned agents in tree view
-- **Resource usage** — memory with color-coded warnings
+| `Ctrl++` / `Ctrl+-` | Increase/decrease font size |
+| `Ctrl+?` | Show help overlay |
+| `Escape` | Close panels and modals |
 
 ---
 
-## CLI Commands
+## 📡 API Reference
 
-```bash
-# Sessions
-claudeman start [--dir <path>]     # Start new session
-claudeman list                      # List all sessions
-claudeman session stop <id>         # Stop specific session
-
-# Tasks
-claudeman task add "prompt"         # Add to queue
-claudeman task list                 # Show queue
-claudeman task clear                # Clear completed
-
-# Ralph Loop
-claudeman ralph start [--min-hours 8]
-claudeman ralph stop
-claudeman ralph status
-
-# Server
-claudeman web [-p 8080]             # Start web interface
-claudeman status                    # Show overall status
-```
-
-### Screen Manager Script
-
-Interactive bash script for direct screen management:
-
-```bash
-./scripts/screen-manager.sh         # Launch interactive mode
-```
-
-| Key | Action |
-|-----|--------|
-| `↑`/`↓` | Navigate |
-| `Enter` | Attach to session |
-| `d` | Delete session |
-| `D` | Delete ALL |
-| `q` | Quit |
-
----
-
-## API Reference
-
-### Sessions
+### Session Management
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/sessions` | List all |
-| `POST` | `/api/sessions` | Create new |
-| `DELETE` | `/api/sessions/:id` | Delete |
-| `POST` | `/api/sessions/:id/input` | Send input |
+| `GET` | `/api/sessions` | List all sessions |
+| `POST` | `/api/sessions` | Create new session |
+| `GET` | `/api/sessions/:id` | Get session details |
+| `DELETE` | `/api/sessions/:id` | Delete session |
+| `POST` | `/api/sessions/:id/input` | Send terminal input |
 | `POST` | `/api/sessions/:id/resize` | Resize terminal |
+| `POST` | `/api/sessions/:id/interactive` | Start interactive mode |
 
 ### Respawn Control
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `POST` | `/api/sessions/:id/respawn/start` | Start controller |
-| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
-| `POST` | `/api/sessions/:id/respawn/enable` | Enable with timer |
-| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
+| `POST` | `/api/sessions/:id/respawn/start` | Start respawn controller |
+| `POST` | `/api/sessions/:id/respawn/stop` | Stop respawn controller |
+| `POST` | `/api/sessions/:id/respawn/enable` | Enable with config + timer |
+| `PUT` | `/api/sessions/:id/respawn/config` | Update running config |
 
 ### Token Management
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `POST` | `/api/sessions/:id/auto-compact` | Set compact threshold |
-| `POST` | `/api/sessions/:id/auto-clear` | Set clear threshold |
+| `POST` | `/api/sessions/:id/auto-compact` | Configure auto-compact |
+| `POST` | `/api/sessions/:id/auto-clear` | Configure auto-clear |
 
-### Monitoring
+### Ralph Loop Tracking
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/events` | SSE stream (real-time) |
-| `GET` | `/api/status` | Full app state |
-| `GET` | `/api/screens` | Screen sessions |
+| `GET` | `/api/sessions/:id/inner-state` | Get loop state + todos |
+| `POST` | `/api/sessions/:id/inner-config` | Configure tracking |
+
+### Real-Time Events
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/events` | SSE stream for all updates |
+| `GET` | `/api/status` | Full application state |
+| `GET` | `/api/screens` | Screen session list |
+
+### Quick Start
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/quick-start` | Create case + start session |
+| `GET` | `/api/cases` | List available cases |
+| `POST` | `/api/cases` | Create new case |
 
 ---
 
-## Long-Running Sessions
+## 🏗️ Architecture
 
-Claudeman is built for **12-24+ hour autonomous runs**.
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLAUDEMAN                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
+│  │   Web UI     │  │   REST API   │  │   SSE Events         │  │
+│  │  (xterm.js)  │◄─┤   (Fastify)  │──┤  (/api/events)       │  │
+│  └──────────────┘  └──────┬───────┘  └──────────────────────┘  │
+│                           │                                     │
+│  ┌────────────────────────┴─────────────────────────────────┐  │
+│  │                    Session Manager                        │  │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │  │
+│  │  │Session 1│ │Session 2│ │Session N│ │ RespawnController│ │  │
+│  │  │  (PTY)  │ │  (PTY)  │ │  (PTY)  │ │  (per-session)   │ │  │
+│  │  └────┬────┘ └────┬────┘ └────┬────┘ └─────────────────┘ │  │
+│  └───────┼───────────┼───────────┼──────────────────────────┘  │
+│          │           │           │                              │
+│  ┌───────┴───────────┴───────────┴──────────────────────────┐  │
+│  │                   GNU Screen Manager                      │  │
+│  │     claudeman-abc    claudeman-def    claudeman-xyz       │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                              │                                  │
+│  ┌───────────────────────────┴──────────────────────────────┐  │
+│  │                     Claude CLI                            │  │
+│  │            claude --dangerously-skip-permissions          │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-### Memory Management
+### Key Components
 
-| Buffer | Max Size | Auto-Trim To |
-|--------|----------|--------------|
+| Component | File | Purpose |
+|-----------|------|---------|
+| **Session** | `src/session.ts` | PTY wrapper for Claude CLI |
+| **RespawnController** | `src/respawn-controller.ts` | Autonomous cycling state machine |
+| **ScreenManager** | `src/screen-manager.ts` | GNU Screen lifecycle management |
+| **InnerLoopTracker** | `src/inner-loop-tracker.ts` | Ralph loop detection |
+| **TaskTracker** | `src/task-tracker.ts` | Background task parsing |
+| **WebServer** | `src/web/server.ts` | Fastify REST + SSE |
+| **StateStore** | `src/state-store.ts` | JSON persistence |
+
+---
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode (no build needed)
+npx tsx src/index.ts web
+
+# Type checking
+npm run typecheck
+
+# Run tests
+npm test                          # All tests
+npm run test:watch               # Watch mode
+npx vitest run test/session.test.ts  # Single file
+
+# Build for production
+npm run build
+```
+
+### Test Structure
+
+```
+test/
+├── unit/
+│   ├── respawn-controller.test.ts
+│   ├── inner-loop-tracker.test.ts
+│   ├── ralph-loop.test.ts
+│   ├── session-manager.test.ts
+│   └── ...
+└── integration/
+    ├── session.test.ts
+    ├── quick-start.test.ts
+    └── ...
+```
+
+---
+
+## 📊 Performance
+
+Built for **24+ hour autonomous runs** with multiple sessions:
+
+| Optimization | Implementation |
+|--------------|----------------|
+| **60fps streaming** | 16ms server batching, `requestAnimationFrame` client |
+| **Memory management** | Auto-trimming buffers (5MB → 4MB on overflow) |
+| **Event debouncing** | 50-500ms debounce on rapid state changes |
+| **CSS containment** | Isolated paint operations per component |
+| **Incremental DOM** | Only changed elements re-render |
+
+### Buffer Limits
+
+| Buffer | Max Size | Trim To |
+|--------|----------|---------|
 | Terminal | 5MB | 4MB |
 | Text output | 2MB | 1.5MB |
 | Messages | 1000 | 800 |
-| Respawn buffer | 1MB | 512KB |
-
-### Best Practices
-
-1. **Enable auto-compact** at 110k tokens
-2. **Enable auto-clear** at 140k tokens
-3. **Use screen sessions** for persistence
-4. **Commit frequently** in Ralph loops
-5. **Monitor resource indicators** in the UI
+| Respawn | 1MB | 512KB |
 
 ---
 
-## Why Claudeman?
-
-| Challenge | Without Claudeman | With Claudeman |
-|-----------|-------------------|----------------|
-| Session crashes | Lost context, manual restart | GNU Screen auto-recovery |
-| Token limits | Surprise hard-stops | Auto-compact/clear at thresholds |
-| Overnight runs | Claude sits idle | Respawn controller keeps working |
-| 5+ parallel sessions | Tab hell, lost track | Web UI with real-time monitoring |
-| Ralph loop tracking | Manual checking | Automatic detection + UI |
-| Cost tracking | Surprise bills | Real-time per-session costs |
-
----
-
-## Troubleshooting
-
-### Session Won't Start
-
-```bash
-which claude              # Is Claude CLI installed?
-claude --version          # Check version
-screen -ls               # Check for stuck screens
-pkill -f "SCREEN.*claudeman"  # Kill all claudeman screens
-```
-
-### High Memory Usage
-
-```bash
-# Lower the auto-clear threshold
-curl -X POST localhost:3000/api/sessions/:id/auto-clear \
-  -d '{"enabled": true, "threshold": 100000}'
-```
-
-### Respawn Not Working
-
-1. Check session is idle (look for `↵ send` indicator)
-2. Verify respawn is enabled via API
-3. Increase `idleTimeoutMs` if detection is too aggressive
-
----
-
-## FAQ
+## ❓ FAQ
 
 **Q: How long can sessions run?**
-A: 24+ hours. Buffer management keeps memory stable.
+A: 24+ hours. Automatic buffer management keeps memory stable.
 
 **Q: Does it work with Claude Code hooks?**
 A: Yes! Claudeman spawns real Claude CLI processes with full hook support.
@@ -395,29 +496,18 @@ A: Yes! Claudeman spawns real Claude CLI processes with full hook support.
 **Q: What if the server restarts?**
 A: Screen sessions persist. Claudeman auto-discovers them on startup.
 
-**Q: Custom completion phrases?**
-A: Yes! Use `<promise>YOUR_PHRASE</promise>` in prompts.
+**Q: Can I use custom completion phrases?**
+A: Yes! Use `<promise>YOUR_PHRASE</promise>` in your prompts.
 
-**Q: How many parallel sessions?**
-A: Up to 20 in the UI, 50 via API.
+**Q: Maximum parallel sessions?**
+A: 20 in the UI, 50 via API.
+
+**Q: Does it work on macOS/Linux/Windows?**
+A: macOS and Linux fully supported. Windows requires WSL2.
 
 ---
 
-## Development
-
-```bash
-npm install
-npx tsx src/index.ts web    # Dev mode (no build needed)
-npm run build               # Production build
-npm test                    # Run test suite
-npx tsc --noEmit           # Type check
-```
-
-See [CLAUDE.md](./CLAUDE.md) for full development documentation.
-
----
-
-## Contributing
+## 🤝 Contributing
 
 1. Fork the repository
 2. Create feature branch (`git checkout -b feature/amazing`)
@@ -426,15 +516,18 @@ See [CLAUDE.md](./CLAUDE.md) for full development documentation.
 5. Commit with conventional commits (`feat:`, `fix:`, `docs:`)
 6. Open Pull Request
 
+See [CLAUDE.md](./CLAUDE.md) for detailed development documentation.
+
 ---
 
-## License
+## 📄 License
 
 MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
 <p align="center">
-  <strong>Stop babysitting Claude. Start shipping.</strong><br>
-  <sub>Built for developers who want Claude Code to work while they sleep.</sub>
+  <strong>Track sessions. Control respawn. Ship while you sleep.</strong>
+  <br>
+  <sub>Built for developers running serious autonomous Claude Code sessions.</sub>
 </p>