docs: add demo GIFs and improve README

- Add INSTALLATION.md with detailed install instructions
- Simplify README installation section (just Homebrew)
- Reorder README: Installation first, then Quick Start
- Add 3 storytelling GIFs showing the full workflow:
  - gif-2-build.gif: Build loop in action (shown first as hook)
  - gif-1-init.gif: Initialize and create PRD
  - gif-3-done.gif: Project complete with results
- Include recording scripts for future GIF updates

Author: matheus3301

INSTALLATION.md

@@ -0,0 +1,87 @@
+# Installation
+
+## Homebrew (Recommended)
+
+The easiest way to install LoopForge on macOS or Linux:
+
+```bash
+brew install matheus3301/tap/loopforge
+```
+
+## Go Install
+
+If you have Go 1.22+ installed:
+
+```bash
+go install github.com/matheus3301/loopforge/cmd/loopforge@latest
+```
+
+Make sure `$GOPATH/bin` is in your `PATH`.
+
+## Binary Download
+
+Download pre-built binaries from the [releases page](https://github.com/matheus3301/loopforge/releases).
+
+### macOS (Apple Silicon)
+```bash
+curl -LO https://github.com/matheus3301/loopforge/releases/latest/download/loopforge_darwin_arm64.tar.gz
+tar -xzf loopforge_darwin_arm64.tar.gz
+sudo mv loopforge /usr/local/bin/
+```
+
+### macOS (Intel)
+```bash
+curl -LO https://github.com/matheus3301/loopforge/releases/latest/download/loopforge_darwin_amd64.tar.gz
+tar -xzf loopforge_darwin_amd64.tar.gz
+sudo mv loopforge /usr/local/bin/
+```
+
+### Linux (x64)
+```bash
+curl -LO https://github.com/matheus3301/loopforge/releases/latest/download/loopforge_linux_amd64.tar.gz
+tar -xzf loopforge_linux_amd64.tar.gz
+sudo mv loopforge /usr/local/bin/
+```
+
+### Linux (ARM64)
+```bash
+curl -LO https://github.com/matheus3301/loopforge/releases/latest/download/loopforge_linux_arm64.tar.gz
+tar -xzf loopforge_linux_arm64.tar.gz
+sudo mv loopforge /usr/local/bin/
+```
+
+### Windows
+```powershell
+# Download from releases page and add to PATH
+```
+
+## Build from Source
+
+Requires Go 1.22+:
+
+```bash
+git clone https://github.com/matheus3301/loopforge.git
+cd loopforge
+go build -o loopforge ./cmd/loopforge
+
+# Optional: install to GOPATH/bin
+go install ./cmd/loopforge
+```
+
+## Verify Installation
+
+```bash
+loopforge version
+```
+
+## Uninstall
+
+### Homebrew
+```bash
+brew uninstall loopforge
+```
+
+### Manual
+```bash
+rm $(which loopforge)
+```

README.md

@@ -13,18 +13,46 @@
     <a href="https://github.com/matheus3301/loopforge/blob/master/LICENSE"><img src="https://img.shields.io/github/license/matheus3301/loopforge?style=flat-square" alt="License"></a>
     <a href="https://github.com/matheus3301/loopforge/actions"><img src="https://img.shields.io/github/actions/workflow/status/matheus3301/loopforge/ci.yml?style=flat-square&label=CI" alt="CI"></a>
   </p>
-
-  <p>
-    <a href="#installation">Installation</a> •
-    <a href="#quick-start">Quick Start</a> •
-    <a href="#how-it-works">How It Works</a> •
-    <a href="#documentation">Docs</a>
-  </p>
 </div>
 
 <br>
 
-## Why LoopForge?
+## Installation
+
+```bash
+brew install matheus3301/tap/loopforge
+```
+
+> 📦 Other methods (Go install, binary download, build from source): [INSTALLATION.md](INSTALLATION.md)
+
+## See It In Action 🔨
+
+<img src="assets/gif-2-build.gif" alt="Build with LoopForge" width="650" />
+
+## Quick Start
+
+### 1. Initialize & Create PRD 📝
+
+```bash
+loopforge init
+loopforge prd generate "Build a REST API with user authentication"
+```
+
+<img src="assets/gif-1-init.gif" alt="Initialize LoopForge" width="600" />
+
+### 2. Run the Build Loop
+
+```bash
+loopforge build
+```
+
+### 3. Done! ✨
+
+<img src="assets/gif-3-done.gif" alt="Project Complete" width="600" />
+
+<br>
+
+## Features
 
 AI coding agents like Claude Code, Codex, and OpenCode are powerful, but they work best with **focused, single-task prompts**. LoopForge orchestrates these agents in structured, iterative loops — one story at a time.
 
@@ -61,44 +89,6 @@ Each iteration:
 4. **Commits** on success, or resets and logs on failure
 5. **Repeats** until all stories are done
 
-## Installation
-
-### Homebrew (macOS/Linux)
-
-```bash
-brew install matheus3301/tap/loopforge
-```
-
-### Go Install
-
-```bash
-go install github.com/matheus3301/loopforge/cmd/loopforge@latest
-```
-
-### Binary Download
-
-Download from the [releases page](https://github.com/matheus3301/loopforge/releases) for your platform.
-
-### Build from Source
-
-```bash
-git clone https://github.com/matheus3301/loopforge.git
-cd loopforge && go build -o loopforge ./cmd/loopforge
-```
-
-## Quick Start
-
-```bash
-# Initialize in your project
-loopforge init
-
-# Generate a PRD from a description
-loopforge prd generate "Build a REST API with user authentication"
-
-# Run the build loop
-loopforge build
-```
-
 ## Core Concepts
 
 ### PRD (Product Requirements Document)

assets/demo.gif

@@ -0,0 +1,17 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1769218311,"command":"./scripts/demo-full.sh","env":{"SHELL":"/bin/bash"}}
+[0.003, "o", "$ loopforge init\r\n"]
+[0.507, "o", "✓ Initialized LoopForge in .loopforge/\r\n\r\n→ Next steps:\r\n    1. Create a PRD: loopforge prd generate 'your project description'\r\n    2. Or add an existing PRD to .loopforge/prd.json\r\n    3. Run the build loop: loopforge build\r\n"]
+[1.506, "o", "\r\n→ PRD created with 3 stories\r\n"]
+[1.003, "o", "\r\n$ loopforge build\r\n"]
+[0.506, "o", "→ PRD: hello-cli\r\nTotal:       3\r\nOpen:        3\r\nIn Progress:  0\r\nDone:        0\r\nBlocked:     0\r\n\r\n"]
+[0.000, "o", "→ Starting build loop (Run ID: 20260123-223155)\r\n\r\n"]
+[32.696, "o", "✓ Iteration 1: US-001 - Initialize Go module (completed, 33s)\r\n"]
+[21.431, "o", "✓ Iteration 2: US-002 - Create main.go (completed, 21s)\r\n"]
+[24.235, "o", "✓ Iteration 3: US-003 - Add --name flag (completed, 24s)\r\n\r\n"]
+[0.001, "o", "Build Summary (Run: 20260123-223155)\r\n╭────────────────────────╮\r\n│ Status:      completed │\r\n│ Iterations:  3         │\r\n│ Completed:   3         │\r\n│ Failed:      0         │\r\n│ Duration:    1m18s     │\r\n╰────────────────────────╯\r\n"]
+[1.003, "o", "\r\n$ go run main.go\r\n"]
+[0.546, "o", "Hello, World!\r\n"]
+[0.503, "o", "\r\n$ go run main.go --name=LoopForge\r\n"]
+[0.545, "o", "Hello, LoopForge!\r\n"]
+[1.003, "o", "\r\n✨ Built autonomously with LoopForge!\r\n"]
+[2.003, "x", "0"]

assets/gif-1-init.gif

@@ -0,0 +1,113 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1769217802,"command":"./demo.sh","env":{"SHELL":"/bin/bash"}}
+[0.011, "o", "TERM environment variable not set.\r\n"]
+[0.000, "o", "$ "]
+[0.000, "o", "c"]
+[0.052, "o", "d"]
+[0.052, "o", " "]
+[0.052, "o", "~"]
+[0.052, "o", "/"]
+[0.051, "o", "w"]
+[0.052, "o", "w"]
+[0.051, "o", "w"]
+[0.052, "o", "/"]
+[0.052, "o", "s"]
+[0.052, "o", "n"]
+[0.052, "o", "a"]
+[0.052, "o", "k"]
+[0.051, "o", "e"]
+[0.052, "o", "-"]
+[0.052, "o", "g"]
+[0.052, "o", "a"]
+[0.052, "o", "m"]
+[0.051, "o", "e"]
+[0.052, "o", "-"]
+[0.052, "o", "d"]
+[0.052, "o", "e"]
+[0.052, "o", "m"]
+[0.053, "o", "o"]
+[0.051, "o", "\r\n"]
+[0.804, "o", "$ l"]
+[0.052, "o", "o"]
+[0.052, "o", "o"]
+[0.053, "o", "p"]
+[0.052, "o", "f"]
+[0.052, "o", "o"]
+[0.052, "o", "r"]
+[0.053, "o", "g"]
+[0.052, "o", "e"]
+[0.053, "o", " "]
+[0.052, "o", "i"]
+[0.052, "o", "n"]
+[0.052, "o", "i"]
+[0.052, "o", "t"]
+[0.053, "o", "\r\n"]
+[0.383, "o", "✓ Initialized LoopForge in .loopforge/\r\n\r\n→ Next steps:\r\n    1. Create a PRD: loopforge prd generate 'your project description'\r\n    2. Or add an existing PRD to .loopforge/prd.json\r\n    3. Run the build loop: loopforge build\r\n"]
+[1.003, "o", "$ "]
+[0.000, "o", "l"]
+[0.052, "o", "s"]
+[0.051, "o", " "]
+[0.052, "o", "-"]
+[0.052, "o", "l"]
+[0.051, "o", "a"]
+[0.052, "o", " "]
+[0.052, "o", "."]
+[0.052, "o", "l"]
+[0.052, "o", "o"]
+[0.051, "o", "o"]
+[0.052, "o", "p"]
+[0.053, "o", "f"]
+[0.051, "o", "o"]
+[0.052, "o", "r"]
+[0.053, "o", "g"]
+[0.052, "o", "e"]
+[0.051, "o", "/"]
+[0.052, "o", "\r\n"]
+[0.303, "o", "total 24\r\ndrwxr-xr-x 3 javazap javazap 4096 Jan 23 22:23 .\r\ndrwxrwxr-x 4 javazap javazap 4096 Jan 23 22:23 ..\r\n-rw-r--r-- 1 javazap javazap    0 Jan 23 22:23 activity.log\r\n-rw-r--r-- 1 javazap javazap  360 Jan 23 22:23 config.yaml\r\n-rw-r--r-- 1 javazap javazap    0 Jan 23 22:23 errors.log\r\n-rw-r--r-- 1 javazap javazap  923 Jan 23 22:23 guardrails.md\r\n-rw-r--r-- 1 javazap javazap   81 Jan 23 22:23 progress.md\r\ndrwxr-xr-x 2 javazap javazap 4096 Jan 23 22:23 runs\r\n"]
+[1.003, "o", "$ l"]
+[0.052, "o", "o"]
+[0.052, "o", "o"]
+[0.052, "o", "p"]
+[0.052, "o", "f"]
+[0.052, "o", "o"]
+[0.052, "o", "r"]
+[0.052, "o", "g"]
+[0.053, "o", "e"]
+[0.052, "o", " "]
+[0.052, "o", "v"]
+[0.052, "o", "e"]
+[0.052, "o", "r"]
+[0.052, "o", "s"]
+[0.052, "o", "i"]
+[0.052, "o", "o"]
+[0.051, "o", "n"]
+[0.051, "o", "\r\n"]
+[0.306, "o", "LoopForge 0.1.0\r\n"]
+[1.003, "o", "$ l"]
+[0.052, "o", "o"]
+[0.052, "o", "o"]
+[0.052, "o", "p"]
+[0.052, "o", "f"]
+[0.052, "o", "o"]
+[0.052, "o", "r"]
+[0.052, "o", "g"]
+[0.052, "o", "e"]
+[0.053, "o", " "]
+[0.052, "o", "b"]
+[0.052, "o", "u"]
+[0.052, "o", "i"]
+[0.052, "o", "l"]
+[0.052, "o", "d"]
+[0.052, "o", " "]
+[0.052, "o", "-"]
+[0.052, "o", "-"]
+[0.052, "o", "d"]
+[0.053, "o", "r"]
+[0.052, "o", "y"]
+[0.052, "o", "-"]
+[0.052, "o", "r"]
+[0.052, "o", "u"]
+[0.052, "o", "n"]
+[0.052, "o", "\r\n"]
+[0.306, "o", "No PRD found (expected in demo)\r\n"]
+[1.002, "o", "\r\n✨ LoopForge initialized!\r\n"]
+[2.003, "x", "0"]

assets/gif-2-build.gif

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Demo script for LoopForge
+
+# Simulate typing
+type_slow() {
+    echo -n "$ "
+    for ((i=0; i<${#1}; i++)); do
+        echo -n "${1:$i:1}"
+        sleep 0.05
+    done
+    echo
+    sleep 0.3
+}
+
+clear
+
+# Navigate to demo project
+type_slow "cd ~/www/snake-game-demo"
+cd ~/www/snake-game-demo
+sleep 0.5
+
+# Initialize LoopForge
+type_slow "loopforge init"
+loopforge init
+sleep 1
+
+# Show structure
+type_slow "ls -la .loopforge/"
+ls -la .loopforge/
+sleep 1
+
+# Show version
+type_slow "loopforge version"
+loopforge version
+sleep 1
+
+# Run dry-run build
+type_slow "loopforge build --dry-run"
+loopforge build --dry-run 2>/dev/null || echo "No PRD found (expected in demo)"
+sleep 1
+
+echo
+echo "✨ LoopForge initialized!"
+sleep 2