docs: add LLM-executable INSTALL.md following Mintlify standard

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

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