AskTinNguyen · Jan 15, 2026 · Jan 15, 2026
diff --git a/README.md b/README.md
@@ -2,7 +2,9 @@
 
 ![Ralph](assets/diagrams/ralph.webp)
 
-Ralph is a minimal, file-based agent loop for autonomous coding. Each iteration starts fresh, reads on-disk state, and commits work for one story at a time.
+> **Ship while you sleep.** Define what you want built, then walk away. Return to completed, committed, working code.
+
+Ralph is a minimal, file-based agent loop for autonomous coding. Each iteration starts fresh, reads on-disk state, and commits work for one story at a time. Ralph works tirelessly on features and stories while you focus on what matters most.
 
 ## Quick Start (5 minutes)
 
@@ -366,8 +368,9 @@ Set environment variables and Ralph agents automatically gain access to these to
 
 ## Documentation
 
+- **[Vision](VISION.md)** - Philosophy and long-term vision for autonomous development
+- **[Roadmap](ROADMAP.md)** - Current progress and planned features
 - **[Testing Guide](TESTING.md)** - Comprehensive testing documentation
-- **[Roadmap](ROADMAP.md)** - Future plans and features
 - **[Agent Guide (CLAUDE.md)](CLAUDE.md)** - For AI agents working with Ralph
 - **[Additional Documentation](documentation/)** - Deployment guides, design system, and more
 - **[Web Documentation](https://asktinnguyen.github.io/ralph-cli/)** - Interactive guides and tutorials

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,8 +1,12 @@
 # Ralph CLI Roadmap: Q1 2026
 
+> **For the full vision, see [VISION.md](VISION.md)** — Ralph's philosophy of autonomous development that lets you ship while you sleep.
+
 ## Vision Statement
 
-Transform Ralph from a minimal agent loop into the **premier autonomous development platform** - enabling developers and teams to ship production code at unprecedented velocity while maintaining full cost visibility and control.
+Transform Ralph from a minimal agent loop into the **premier autonomous development platform** — a tireless AI partner that executes features autonomously while developers focus on architecture, strategy, and life outside of code.
+
+**Core Promise:** Define what you want, walk away, return to working code.
 
 ---
 
@@ -16,20 +20,53 @@ Transform Ralph from a minimal agent loop into the **premier autonomous developm
 
 ---
 
+## Autonomy Milestones
+
+Progress toward **fully unattended operation** — the ability to run Ralph for hours or days without human intervention.
+
+| Milestone | Target Runtime | Key Features | Status |
+|-----------|----------------|--------------|--------|
+| **Level 1: Supervised** | 30 minutes | Basic retry, manual recovery | ✅ Complete |
+| **Level 2: Semi-Autonomous** | 2-4 hours | Checkpoint/resume, agent switching | 🔄 In Progress |
+| **Level 3: Autonomous** | 8-12 hours | Watchdog, self-healing, notifications | 📋 Planned |
+| **Level 4: Overnight** | 24+ hours | Full recovery, pattern learning | 📋 Planned |
+| **Level 5: Continuous** | Unlimited | Cloud infrastructure, queue management | 📋 Planned |
+
+### Current State: Level 1-2 Transition
+
+**What works today:**
+- ✅ Basic retry with exponential backoff
+- ✅ Agent fallback chain on failures
+- ✅ Parallel streams in isolated worktrees
+- ✅ Budget limits prevent runaway costs
+- ✅ Risk assessment flags dangerous changes
+
+**Blocking full autonomy:**
+- ⏳ Checkpoint system (resume after crash)
+- ⏳ Graceful shutdown (clean state on interrupt)
+- ⏳ Watchdog process (restart stalled builds)
+- ⏳ Complete notification system (alert on completion)
+
+---
+
 ## Month 1: Stability, Polish & Developer Experience
 
 ### Theme: Production-Ready Foundation
 
 **Goal**: Make Ralph reliable enough for daily production use with excellent developer experience.
 
-### 1.1 Core Reliability
+### 1.1 Core Reliability (Autonomy-Critical)
+
+These features are **essential for unattended operation**. Without them, Ralph requires human supervision.
 
-| Feature               | Description                                                        | Status      |
-| --------------------- | ------------------------------------------------------------------ | ----------- |
-| **Retry & Recovery**  | Automatic retry with exponential backoff on agent failures         | PARTIAL     |
-| **Checkpoint System** | Save/restore loop state for resumable builds                       | NOT STARTED |
-| **Graceful Shutdown** | Handle SIGINT/SIGTERM, save progress, clean up worktrees           | PARTIAL     |
-| **Health Checks**     | Pre-flight validation of agent availability, git state, disk space | PARTIAL     |
+| Feature | Description | Autonomy Impact | Status |
+| ------- | ----------- | --------------- | ------ |
+| **Retry & Recovery** | Automatic retry with exponential backoff on agent failures | Handles transient failures | PARTIAL |
+| **Checkpoint System** | Save/restore loop state for resumable builds | **CRITICAL:** Resume after crash/restart | NOT STARTED |
+| **Graceful Shutdown** | Handle SIGINT/SIGTERM, save progress, clean up worktrees | **CRITICAL:** Clean state on interrupt | PARTIAL |
+| **Watchdog Process** | Monitor builds, restart stalled executions | Recover from hangs | NOT STARTED |
+| **Health Checks** | Pre-flight validation of agent availability, git state, disk space | Fail fast, not mid-build | PARTIAL |
+| **Heartbeat System** | Periodic health signals, detect unresponsive builds | Identify hung processes | NOT STARTED |
 
 ### 1.2 Developer Experience
 
@@ -187,3 +224,72 @@ Priority areas for community contribution:
 - UI themes and components
 - Documentation and tutorials
 - Integration plugins (Jira, Linear, etc.)
+
+---
+
+## Future: Day in the Life
+
+What autonomous development looks like when this roadmap is complete:
+
+### Morning (15 minutes)
+
+```bash
+# Review PRs from overnight builds
+gh pr list --author=ralph-bot
+
+# Merge completed features
+ralph stream merge 1
+ralph stream merge 2
+
+# Define today's features
+ralph prd "Add user analytics dashboard"
+ralph prd "Implement webhook system"
+ralph plan
+```
+
+### Workday (Focus on other things)
+
+```bash
+# Start parallel builds and walk away
+ralph stream build 1 50 &
+ralph stream build 2 50 &
+
+# Notifications arrive via Slack:
+# ✅ PRD-1: US-001 completed (commit abc123)
+# ✅ PRD-1: US-002 completed (commit def456)
+# ⚠️ PRD-2: US-003 flagged for review (high risk)
+```
+
+### Evening (10 minutes)
+
+```bash
+# Check status
+ralph stream status
+
+# Review flagged changes
+git diff main..ralph/PRD-2 -- src/payments/
+
+# Approve and continue
+ralph stream build 2 --continue
+
+# Start overnight run
+ralph build 100 --notify-on-complete
+```
+
+### Results
+
+- **Features shipped:** 2-3 per day
+- **Developer time:** < 1 hour
+- **Build time:** 8-12 hours (parallel)
+- **Cost:** $20-50 per day (optimized routing)
+
+**Ralph does the work. You do the thinking.**
+
+---
+
+## Quick Links
+
+- [VISION.md](VISION.md) — Philosophy and long-term vision
+- [CLAUDE.md](CLAUDE.md) — Complete reference for AI agents
+- [documentation/](documentation/) — Detailed guides
+- [ui/public/docs/](ui/public/docs/) — Web documentation