docs: rewrite README focused on core capabilities

- Persistent Screen Sessions
- Respawn Controller (autonomous work while you sleep)
- Ralph Wiggum Loop Tracking
- Smart Token Management
- Multi-Session Dashboard

Removed problem/solution framing, now focused purely on features.

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

README.md

@@ -1,13 +1,11 @@
 <h1 align="center">
-  <br>
   🤖 Claudeman
-  <br>
 </h1>
 
 <h3 align="center">Track Claude Code Sessions Better Than Ever</h3>
 
 <p align="center">
-  <em>Run 20 agents in parallel. Track them in real-time. The Respawn Controller keeps them working while you sleep.</em>
+  <em>Persistent sessions. Ralph Loop tracking. Respawn agents. Autonomous work while you sleep.</em>
 </p>
 
 <p align="center">
@@ -18,15 +16,6 @@
   <img src="https://img.shields.io/badge/Tests-258%20passing-22c55e?style=flat-square" alt="Tests">
 </p>
 
-<p align="center">
-  <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>
-
 ---
 
 <p align="center">
@@ -35,250 +24,43 @@
 
 ---
 
-## 🚨 The Problem
+## What Claudeman Does
 
-You're running Claude Code on a complex refactor. **Three hours in:**
+### 💾 Persistent Screen Sessions
 
-| Issue | Impact |
+Every Claude session runs inside **GNU Screen** — sessions survive server restarts, network drops, and machine sleep.
-|-------|--------|
-| 💥 **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
+# Your sessions are always recoverable
-npm install && npm run build
-claudeman web
-```
-
-**Open http://localhost:3000** and you get:
-
-<table>
-<tr>
-<td width="50%">
-
-### 🖥️ 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>
-
----
-
-## 🚀 Quick Start
-
-### 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`) |
-
-### Installation
-
-```bash
-# Clone and install
-git clone https://github.com/Ark0N/claudeman.git
-cd claudeman
-npm install
-npm run build
-
-# Make 'claudeman' available globally (optional)
-npm link
-```
-
-### Launch
-
-```bash
-# Production
-claudeman web
-
-# Development (no build required)
-npx tsx src/index.ts web
-
-# Custom port
-claudeman web -p 8080
-```
-
-### Your First Session
-
-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
-
-### Real-Time Terminal Streaming
-
-<p align="center">
-  <img src="docs/screenshots/session-running.png" alt="Terminal Streaming" width="800">
-</p>
-
-- **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
-
-### 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
-# Inside every Claudeman session:
 CLAUDEMAN_SCREEN=1
 CLAUDEMAN_SESSION_ID=abc-123-def
 CLAUDEMAN_SCREEN_NAME=claudeman-myproject
 ```
 
-**Why this matters:**
+- Sessions auto-recover on startup
-- Claude knows it's in a managed session
+- Ghost session discovery finds orphaned screens
-- Won't accidentally kill its own screen
+- Claude knows it's managed (won't kill its own screen)
-- The default CLAUDE.md template includes safety instructions
-
-### Resource Monitoring
-
-The dashboard shows real-time resource usage:
-
-| 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 Wiggum Loops
+### 🔄 Respawn Controller
 
-The **Ralph Loop** is Claudeman's killer feature: **run Claude autonomously for 24+ hours**.
+**The core of autonomous work.** When Claude becomes idle, the Respawn Controller kicks in:
-
-<p align="center">
-  <img src="docs/images/ralph-tracker-16tasks.png" alt="Ralph Loop Tracking" width="800">
-</p>
-
-### How It Works
 
 ```
-┌──────────────────────────────────────────────────────────────┐
+WATCHING → IDLE DETECTED → SEND UPDATE → CLEAR → INIT → CONTINUE
-│                    RALPH LOOP CYCLE                          │
+    ↑                                                      │
-├──────────────────────────────────────────────────────────────┤
+    └──────────────────────────────────────────────────────┘
-│                                                              │
-│  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐ │
-│  │  WATCH  │───►│  DETECT  │───►│ RESPAWN │───►│ CONTINUE│ │
-│  │  (idle) │    │ complete │    │  cycle  │    │  work   │ │
-│  └─────────┘    └──────────┘    └─────────┘    └────┬────┘ │
-│       ▲                                              │      │
-│       └──────────────────────────────────────────────┘      │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
 ```
 
-### Detection Patterns
+- Detects idle state via prompt indicators (`↵ send`, `❯`)
+- Sends configurable update prompts to continue work
+- Auto-cycles `/clear` → `/init` for fresh context
+- **Keeps working even when Ralph Wiggum loops stop**
+- Run for **24+ hours** completely unattended
 
-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
+# Enable respawn with 8-hour timer
-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 '{
@@ -290,99 +72,135 @@ curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
   }'
 ```
 
-### Time-Aware Loops
+---
 
-When you specify a minimum duration, Claudeman:
+### 🎯 Ralph Wiggum Loop Tracking
 
-1. Completes all primary tasks
+Claudeman detects and tracks Ralph loops running inside Claude Code:
-2. Checks elapsed time
+
-3. **If minimum not reached:** Generates follow-up tasks
+<p align="center">
-   - Code optimization
+  <img src="docs/images/ralph-tracker-16tasks.png" alt="Ralph Loop Tracking" width="800">
-   - Test coverage improvements
+</p>
-   - Security hardening
+
-   - Documentation gaps
+**Auto-detects:**
-4. Only outputs completion phrase when time is met
+| Pattern | Example |
+|---------|---------|
+| Promise tags | `<promise>COMPLETE</promise>` |
+| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` |
+| TodoWrite | `- [ ] Task`, `- [x] Done` |
+| Iterations | `[5/50]`, `Iteration 5 of 50` |
+
+**Tracks in real-time:**
+- Completion phrase detection
+- Todo progress (`8/12 complete`)
+- Iteration count
+- Elapsed time
 
 ---
 
-## ⌨️ Keyboard Shortcuts
+### 📊 Smart Token Management
+
+Never hit token limits unexpectedly:
+
+| Threshold | Action | Result |
+|-----------|--------|--------|
+| **110k tokens** | Auto `/compact` | Context summarized, work continues |
+| **140k tokens** | Auto `/clear` | Fresh start with `/init` |
+
+```bash
+# Configure per-session
+curl -X POST localhost:3000/api/sessions/:id/auto-compact \
+  -d '{"enabled": true, "threshold": 100000}'
+```
+
+---
+
+### 🖥️ Multi-Session Dashboard
+
+Run **20 parallel sessions** with full visibility:
+
+- Real-time xterm.js terminals (60fps streaming)
+- Per-session token and cost tracking
+- Tab-based navigation
+- One-click session management
+
+<p align="center">
+  <img src="docs/screenshots/session-running.png" alt="Session Running" width="800">
+</p>
+
+---
+
+## Quick Start
+
+```bash
+# Clone and build
+git clone https://github.com/Ark0N/claudeman.git
+cd claudeman
+npm install && npm run build
+
+# Start the web interface
+claudeman web
+
+# Open http://localhost:3000
+# Press Ctrl+Enter to start your first session
+```
+
+**Requirements:**
+- Node.js 18+
+- Claude CLI in PATH
+- GNU Screen (`apt install screen` / `brew install screen`)
+
+---
+
+## Keyboard Shortcuts
 
 | Shortcut | Action |
 |----------|--------|
-| `Ctrl+Enter` | Quick-start: Create case + start session |
+| `Ctrl+Enter` | Quick-start session |
-| `Ctrl+W` | Close current session |
+| `Ctrl+W` | Close session |
-| `Ctrl+Tab` | Switch to next session |
+| `Ctrl+Tab` | Next session |
-| `Ctrl+Shift+Tab` | Switch to previous session |
 | `Ctrl+K` | Kill all sessions |
 | `Ctrl+L` | Clear terminal |
-| `Ctrl++` / `Ctrl+-` | Increase/decrease font size |
-| `Ctrl+?` | Show help overlay |
-| `Escape` | Close panels and modals |
 
 ---
 
-## 📡 API Reference
+## API
-
-### Session Management
 
+### Sessions
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/sessions` | List all sessions |
+| `GET` | `/api/sessions` | List all |
-| `POST` | `/api/sessions` | Create new session |
+| `POST` | `/api/quick-start` | Create case + start 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/input` | Send input |
-| `POST` | `/api/sessions/:id/resize` | Resize terminal |
-| `POST` | `/api/sessions/:id/interactive` | Start interactive mode |
-
-### Respawn Control
 
+### Respawn
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `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 |
+| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
-
+| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
-### Token Management
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/api/sessions/:id/auto-compact` | Configure auto-compact |
-| `POST` | `/api/sessions/:id/auto-clear` | Configure auto-clear |
-
-### Ralph Loop Tracking
 
+### Ralph Tracking
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `GET` | `/api/sessions/:id/inner-state` | Get loop state + todos |
 | `POST` | `/api/sessions/:id/inner-config` | Configure tracking |
 
-### Real-Time Events
+### Real-Time
-
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/events` | SSE stream for all updates |
+| `GET` | `/api/events` | SSE stream |
-| `GET` | `/api/status` | Full application state |
+| `GET` | `/api/status` | Full app 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 |
 
 ---
 
-## 🏗️ Architecture
+## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                         CLAUDEMAN                               │
 ├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
 │  │   Web UI     │  │   REST API   │  │   SSE Events         │  │
 │  │  (xterm.js)  │◄─┤   (Fastify)  │──┤  (/api/events)       │  │
@@ -390,144 +208,55 @@ When you specify a minimum duration, Claudeman:
 │                           │                                     │
 │  ┌────────────────────────┴─────────────────────────────────┐  │
 │  │                    Session Manager                        │  │
-│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │  │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────────────────┐ │  │
-│  │  │Session 1│ │Session 2│ │Session N│ │ RespawnController│ │  │
+│  │  │ Session │ │ Session │ │ RespawnController            │ │  │
-│  │  │  (PTY)  │ │  (PTY)  │ │  (PTY)  │ │  (per-session)   │ │  │
+│  │  │  (PTY)  │ │  (PTY)  │ │ (per-session autonomous)    │ │  │
-│  │  └────┬────┘ └────┬────┘ └────┬────┘ └─────────────────┘ │  │
+│  │  └────┬────┘ └────┬────┘ └─────────────────────────────┘ │  │
-│  └───────┼───────────┼───────────┼──────────────────────────┘  │
+│  └───────┼───────────┼──────────────────────────────────────┘  │
-│          │           │           │                              │
+│          │           │                                          │
-│  ┌───────┴───────────┴───────────┴──────────────────────────┐  │
+│  ┌───────┴───────────┴──────────────────────────────────────┐  │
-│  │                   GNU Screen Manager                      │  │
+│  │              GNU Screen Manager (Persistence)             │  │
-│  │     claudeman-abc    claudeman-def    claudeman-xyz       │  │
+│  └──────────────────────────┬───────────────────────────────┘  │
-│  └───────────────────────────────────────────────────────────┘  │
 │                              │                                  │
 │  ┌───────────────────────────┴──────────────────────────────┐  │
 │  │                     Claude CLI                            │  │
-│  │            claude --dangerously-skip-permissions          │  │
 │  └───────────────────────────────────────────────────────────┘  │
-│                                                                 │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-### Key Components
+---
 
-| Component | File | Purpose |
+## Performance
-|-----------|------|---------|
+
-| **Session** | `src/session.ts` | PTY wrapper for Claude CLI |
+Optimized for long-running autonomous sessions:
-| **RespawnController** | `src/respawn-controller.ts` | Autonomous cycling state machine |
+
-| **ScreenManager** | `src/screen-manager.ts` | GNU Screen lifecycle management |
+| Feature | Implementation |
-| **InnerLoopTracker** | `src/inner-loop-tracker.ts` | Ralph loop detection |
+|---------|----------------|
-| **TaskTracker** | `src/task-tracker.ts` | Background task parsing |
+| **60fps terminal** | 16ms server batching, `requestAnimationFrame` client |
-| **WebServer** | `src/web/server.ts` | Fastify REST + SSE |
+| **Memory management** | Auto-trimming buffers (5MB max) |
-| **StateStore** | `src/state-store.ts` | JSON persistence |
+| **Event debouncing** | 50-500ms on rapid state changes |
 
 ---
 
-## 🧪 Development
+## Development
 
 ```bash
-# Install dependencies
 npm install
-
+npx tsx src/index.ts web    # Dev mode
-# Run in development mode (no build needed)
+npm run build               # Production build
-npx tsx src/index.ts web
+npm test                    # Run tests
-
-# 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
+See [CLAUDE.md](./CLAUDE.md) for full documentation.
-
-```
-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
+## License
 
-Built for **24+ hour autonomous runs** with multiple sessions:
+MIT — see [LICENSE](LICENSE)
-
-| 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 | 1MB | 512KB |
-
----
-
-## ❓ FAQ
-
-**Q: How long can sessions run?**
-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.
-
-**Q: What if the server restarts?**
-A: Screen sessions persist. Claudeman auto-discovers them on startup.
-
-**Q: Can I use custom completion phrases?**
-A: Yes! Use `<promise>YOUR_PHRASE</promise>` in your prompts.
-
-**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.
-
----
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create feature branch (`git checkout -b feature/amazing`)
-3. Write tests for new functionality
-4. Ensure tests pass (`npm test`)
-5. Commit with conventional commits (`feat:`, `fix:`, `docs:`)
-6. Open Pull Request
-
-See [CLAUDE.md](./CLAUDE.md) for detailed development documentation.
-
----
-
-## 📄 License
-
-MIT License — see [LICENSE](LICENSE) for details.
 
 ---
 
 <p align="center">
   <strong>Track sessions. Control respawn. Ship while you sleep.</strong>
-  <br>
-  <sub>Built for developers running serious autonomous Claude Code sessions.</sub>
 </p>