From cca87bd55f34e5d9f86f2299ebeb7d593b1002e5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 18 Jan 2026 02:38:51 +0000
Subject: [PATCH] docs: add LLM-executable INSTALL.md following Mintlify
 standard

Add INSTALL.md with structured, autonomous installation instructions
that AI agents can execute directly via pipe. Simplify README.md
installation sections to reference the new file.

The install.md standard includes:
- Clear OBJECTIVE and DONE WHEN sections
- TODO checklist for agents to track progress
- Detailed step-by-step commands
- Success verification criteria
---
 INSTALL.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |  96 +++++++-----------------------------
 2 files changed, 161 insertions(+), 77 deletions(-)
 create mode 100644 INSTALL.md

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..e4ecfd6
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,142 @@
+# ralph-cli
+
+> Autonomous coding agent loop. Define what you want built, walk away, return to committed, working code.
+
+I want you to install Ralph CLI for me. Execute all the steps below autonomously.
+
+## OBJECTIVE
+
+Install Ralph CLI globally and configure it in the current project so the user can run autonomous build iterations with `ralph build`.
+
+## DONE WHEN
+
+- `ralph --version` outputs a version number
+- `ralph install` has been run in the target project
+- `.agents/ralph/` directory exists in the project
+- Running `ralph doctor` shows all checks passing
+
+## TODO
+
+- [ ] Check prerequisites (Node.js 18+, Git, AI agent CLI)
+- [ ] Install Ralph CLI globally
+- [ ] Navigate to the target project
+- [ ] Run `ralph install` to set up project templates
+- [ ] Verify installation with `ralph doctor`
+
+## DETAILED STEPS
+
+### Step 1: Verify Prerequisites
+
+You need Node.js 18+ and Git installed. Check with:
+
+```bash
+node --version   # Must be v18.0.0 or higher
+git --version    # Any recent version
+```
+
+You also need at least one AI agent CLI installed. Check for any of these:
+
+```bash
+claude --version    # Claude Code (recommended)
+codex --version     # OpenAI Codex
+droid --version     # Factory.ai Droid
+```
+
+If Claude Code is missing, install it:
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+### Step 2: Install Ralph CLI
+
+**Option A: One-Command Install (Recommended)**
+
+macOS/Linux:
+```bash
+curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.sh | bash
+```
+
+Windows PowerShell:
+```powershell
+iwr -useb https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.ps1 | iex
+```
+
+**Option B: Manual Install**
+
+```bash
+git clone https://github.com/AskTinNguyen/ralph-cli.git
+cd ralph-cli
+npm install && npm link
+```
+
+### Step 3: Verify Global Installation
+
+```bash
+ralph --version
+```
+
+This must output a version number. If the command is not found, ensure `~/.npm-global/bin` is in your PATH.
+
+### Step 4: Initialize Ralph in Your Project
+
+Navigate to your target project and run:
+
+```bash
+cd /path/to/your/project
+ralph install
+```
+
+This creates the `.agents/ralph/` directory with customizable templates and loop configuration.
+
+When prompted about skills, select the ones you need (commit, dev-browser, prd) or skip for a minimal setup.
+
+### Step 5: Verify Project Setup
+
+Run the health check:
+
+```bash
+ralph doctor
+```
+
+All checks should pass. If any fail, address the reported issues.
+
+### Step 6: Quick Test (Optional)
+
+Test that Ralph works by running a dry build:
+
+```bash
+ralph prd "Add a hello world endpoint"  # Generate a simple PRD
+ralph plan                               # Create implementation plan
+ralph build 1 --no-commit                # Dry run (no git commits)
+```
+
+## SUCCESS VERIFICATION
+
+Run these commands to confirm installation is complete:
+
+```bash
+ralph --version          # Should output version
+ls .agents/ralph/        # Should list: loop.sh, config.sh, PROMPT_*.md
+ralph doctor             # All checks should pass
+```
+
+## TROUBLESHOOTING
+
+If you encounter issues, consult the full documentation:
+
+- **Agent Guide**: See `CLAUDE.md` in the repository
+- **Web Docs**: Start UI with `cd ui && npm run dev`, then visit http://localhost:3000/docs/
+
+Common issues:
+- **Command not found**: Add npm global bin to PATH (`export PATH="$HOME/.npm-global/bin:$PATH"`)
+- **Permission denied**: Use `sudo npm link` or configure npm for global installs without sudo
+- **Agent not found**: Install Claude Code, Codex, or Droid before running builds
+
+---
+
+**EXECUTE NOW**: Complete the above TODO list to achieve: `ralph --version` outputs a version, `ralph doctor` passes, and `.agents/ralph/` exists in the project.
+
+---
+
+For additional context and full documentation, see: https://github.com/AskTinNguyen/ralph-cli/blob/main/CLAUDE.md
diff --git a/README.md b/README.md
index 260f7c8..a81de93 100644
--- a/README.md
+++ b/README.md
@@ -6,50 +6,26 @@
 
 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)
+## Quick Start
 
-### One-Command Install
-
-**macOS / Linux:**
 ```bash
+# Install Ralph CLI (macOS/Linux)
 curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.sh | bash
-```
-
-**Windows (PowerShell):**
-```powershell
-iwr -useb https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.ps1 | iex
-```
-
-The installer automatically:
-- Checks for Node.js (v18+), npm, and Git
-- Installs missing dependencies (via Homebrew, apt, winget, or Chocolatey)
-- Clones and sets up ralph-cli globally
-
-### Prerequisites (if installing manually)
-
-- Node.js 18+
-- Git
-- An AI agent: [Claude Code](https://claude.ai/download), [Codex](https://github.com/openai/codex), or [Droid](https://factory.ai)
-
-### Manual Install
-
-```bash
-git clone https://github.com/AskTinNguyen/ralph-cli.git
-cd ralph-cli
-npm install && npm link
-```
-
-### Use in Your Project
 
-```bash
+# Set up in your project
 cd your-project
 ralph install          # Install templates
-ralph prd              # Generate requirements (interactive)
+ralph prd              # Generate requirements
 ralph plan             # Create implementation plan
 ralph build 5          # Run 5 build iterations
 ```
 
-That's it! Ralph will execute your plan one story at a time.
+**For AI agents**: Pipe the install instructions directly:
+```bash
+curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/INSTALL.md | claude
+```
+
+See **[INSTALL.md](INSTALL.md)** for complete installation instructions, prerequisites, and troubleshooting.
 
 ## How It Works
 
@@ -64,53 +40,18 @@ Ralph treats **files and git** as memory, not the model context:
 
 ## Installation
 
-### One-Command Install (Recommended)
-
-**macOS / Linux:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.sh | bash
-```
-
-**Windows (PowerShell):**
-```powershell
-iwr -useb https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.ps1 | iex
-```
-
-**Custom install directory:**
-```bash
-RALPH_INSTALL_DIR=/opt/ralph curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/install.sh | bash
-```
-
-### From GitHub (Manual)
-
-```bash
-git clone https://github.com/AskTinNguyen/ralph-cli.git
-cd ralph-cli
-npm install && npm link
-```
-
-### From npm (Alternative)
+See **[INSTALL.md](INSTALL.md)** for complete installation instructions including:
+- Prerequisites (Node.js 18+, Git, AI agent CLI)
+- One-command install for macOS/Linux/Windows
+- Manual installation from GitHub
+- Project setup with `ralph install`
+- Verification with `ralph doctor`
 
+**LLM-executable install** (pipe directly to your AI agent):
 ```bash
-npm install -g github:AskTinNguyen/ralph-cli
+curl -fsSL https://raw.githubusercontent.com/AskTinNguyen/ralph-cli/main/INSTALL.md | claude
 ```
 
-### Install Templates to Your Project
-
-```bash
-ralph install
-```
-
-This creates `.agents/ralph/` in your project so you can customize prompts and loop behavior. You'll be asked if you want to add optional skills.
-
-### Install Skills (Optional)
-
-```bash
-ralph install --skills
-```
-
-You'll be prompted for agent (codex/claude/droid) and scope (local/global). Skills installed: **commit**, **dev-browser**, **prd**.
-
 ## Basic Workflow
 
 ### 1. Generate PRD
@@ -385,6 +326,7 @@ Set environment variables and Ralph agents automatically gain access to these to
 
 ## Documentation
 
+- **[Install Guide (INSTALL.md)](INSTALL.md)** - LLM-executable installation instructions
 - **[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