feat: add VHS terminal demo tape files

.gitignore

@@ -20,6 +20,10 @@ docs/node_modules/
 docs/build/
 docs/.docusaurus/
 
+# VHS demo output (generated GIF/MP4)
+demos/output/*
+!demos/output/.gitkeep
+
 # Reference projects (not part of ralph-starter)
 projects/
 

README.md

@@ -31,6 +31,10 @@
   <a href="https://ralphstarter.ai">Docs</a>
 </p>
 
+<p align="center">
+  <img src="https://ralphstarter.ai/img/demos/figma-demo.gif" alt="ralph-starter Figma demo" width="700" />
+</p>
+
 ---
 
 

demos/README.md

@@ -0,0 +1,63 @@
+# Terminal Demos
+
+Terminal demo recordings generated with [VHS](https://github.com/charmbracelet/vhs) by Charm.
+
+## Prerequisites
+
+1. **Install VHS**:
+
+```bash
+# macOS
+brew install charmbracelet/tap/vhs
+
+# or with Go
+go install github.com/charmbracelet/vhs@latest
+```
+
+VHS also requires [ffmpeg](https://ffmpeg.org/) and [ttyd](https://github.com/tsl0922/ttyd):
+
+```bash
+brew install ffmpeg ttyd
+```
+
+2. **Install ralph-starter** (tapes use `Require ralph-starter`):
+
+```bash
+npm install -g ralph-starter
+# or build locally: pnpm build && npm link
+```
+
+## Generate demos
+
+```bash
+# Generate a single demo
+vhs demos/figma.tape
+
+# Generate all demos
+for tape in demos/*.tape; do vhs "$tape"; done
+```
+
+## Output
+
+Generated files go to `demos/output/` (gitignored except for `.gitkeep`).
+
+Each tape produces:
+- `.gif` — for embedding in blog posts, README, landing page, and social media
+- `.mp4` — for website embedding and higher quality sharing
+
+## Tapes
+
+| Tape | Description |
+|------|-------------|
+| `figma.tape` | Figma wizard: paste URL → select stack → visual validation → done |
+| `github.tape` | GitHub issue to code: fetch issue → AI loop → PR created |
+| `linear.tape` | Linear tickets: fetch sprint → implement → commits |
+| `notion.tape` | Notion spec to code: parse pages → scaffold → tests |
+
+## Embedding
+
+GIFs are referenced from:
+- **README.md** — project root, shows the Figma demo
+- **Landing page** — `docs/src/components/HeroSection/` can optionally embed a demo
+- **Blog posts** — inline with `![Demo](../demos/output/figma-demo.gif)`
+- **Social media** — attach GIFs directly to tweets/LinkedIn posts

demos/figma.tape

@@ -0,0 +1,26 @@
+# Figma Wizard Demo
+# ralph-starter figma — interactive design-to-code workflow
+
+Output demos/output/figma-demo.gif
+Output demos/output/figma-demo.mp4
+
+Require echo
+
+Set Shell "bash"
+Set FontSize 18
+Set Width 1000
+Set Height 700
+Set Theme "Catppuccin Mocha"
+Set FontFamily "JetBrains Mono"
+Set Padding 24
+Set TypingSpeed 0
+
+# Run the colored simulation (includes command display)
+Hide
+Type "clear && bash demos/scripts/figma-sim.sh"
+Enter
+Sleep 200ms
+Show
+
+# Wait for script to finish (script has ~12s of internal sleeps)
+Sleep 16s

demos/github.tape

@@ -0,0 +1,26 @@
+# GitHub Issue-to-Code Demo
+# ralph-starter run --from github — fetch issue and build autonomously
+
+Output demos/output/github-demo.gif
+Output demos/output/github-demo.mp4
+
+Require echo
+
+Set Shell "bash"
+Set FontSize 18
+Set Width 1000
+Set Height 700
+Set Theme "Catppuccin Mocha"
+Set FontFamily "JetBrains Mono"
+Set Padding 24
+Set TypingSpeed 0
+
+# Run the colored simulation (includes command display)
+Hide
+Type "clear && bash demos/scripts/github-sim.sh"
+Enter
+Sleep 200ms
+Show
+
+# Wait for script to finish (script has ~11s of internal sleeps)
+Sleep 14s

demos/linear.tape

@@ -0,0 +1,26 @@
+# Linear Ticket Processing Demo
+# ralph-starter run --from linear — fetch sprint tickets and implement
+
+Output demos/output/linear-demo.gif
+Output demos/output/linear-demo.mp4
+
+Require echo
+
+Set Shell "bash"
+Set FontSize 18
+Set Width 1000
+Set Height 700
+Set Theme "Catppuccin Mocha"
+Set FontFamily "JetBrains Mono"
+Set Padding 24
+Set TypingSpeed 0
+
+# Run the colored simulation (includes command display)
+Hide
+Type "clear && bash demos/scripts/linear-sim.sh"
+Enter
+Sleep 200ms
+Show
+
+# Wait for script to finish (script has ~10s of internal sleeps)
+Sleep 13s

demos/notion.tape

@@ -0,0 +1,26 @@
+# Notion Spec-to-Code Demo
+# ralph-starter run --from notion — parse Notion page and build
+
+Output demos/output/notion-demo.gif
+Output demos/output/notion-demo.mp4
+
+Require echo
+
+Set Shell "bash"
+Set FontSize 18
+Set Width 1000
+Set Height 700
+Set Theme "Catppuccin Mocha"
+Set FontFamily "JetBrains Mono"
+Set Padding 24
+Set TypingSpeed 0
+
+# Run the colored simulation (includes command display)
+Hide
+Type "clear && bash demos/scripts/notion-sim.sh"
+Enter
+Sleep 200ms
+Show
+
+# Wait for script to finish (script has ~10s of internal sleeps)
+Sleep 13s

demos/scripts/figma-sim.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Simulates ralph-starter figma wizard output with real CLI styling
+C='\033[36m'   # Cyan
+G='\033[32m'   # Green
+Y='\033[33m'   # Yellow
+B='\033[1m'    # Bold
+D='\033[2m'    # Dim
+R='\033[0m'    # Reset
+
+# Show the command that was "run"
+echo -e "${D}\$${R} ralph-starter figma"
+sleep 0.3
+
+# Banner
+echo ""
+echo -e "${C}┌──────────────────────────────────────────────────┐${R}"
+echo -e "${C}│${R}  ${B}ralph-starter${R} ${D}v0.4.0${R}                          ${C}│${R}"
+echo -e "${C}│${R}  ${D}AI-powered project generator${R}                   ${C}│${R}"
+echo -e "${C}└──────────────────────────────────────────────────┘${R}"
+echo ""
+sleep 0.5
+
+# Wizard title
+echo -e "  ${C}${B}Figma to Code${R}"
+echo -e "  ${D}Design to code in one command${R}"
+echo ""
+sleep 0.8
+
+# Step 1: URL
+echo -e "${G}?${R} Figma design URL:"
+echo -e "  ${D}(paste the full Figma file or frame URL)${R}"
+sleep 0.4
+echo -e "  ${C}>${R} https://figma.com/design/ABC123/MNTN-Landing-Page"
+sleep 0.8
+
+# Step 2: Description
+echo ""
+echo -e "${G}?${R} What would you like to build?"
+sleep 0.4
+echo -e "  ${C}>${R} responsive landing page with hero parallax and animated sections"
+sleep 0.8
+
+# Step 3: Stack
+echo ""
+echo -e "${G}?${R} Tech stack? ${B}Next.js + TypeScript + Tailwind CSS${R} ${D}(Detected)${R}"
+sleep 0.8
+
+# Step 4: Model
+echo ""
+echo -e "  ${B}Which model?${R}"
+echo ""
+echo -e "  ${D}1)${R} Claude Opus 4.6 — maximum quality ${G}(Recommended)${R}"
+echo -e "  ${D}2)${R} Claude Sonnet 4.5 — fast + cost-effective"
+echo -e "  ${D}3)${R} Custom model ID"
+echo ""
+echo -e "${G}?${R} Select model: ${C}1${R}"
+sleep 0.4
+echo -e "  ${D}Using:${R} Claude Opus 4.6 — maximum quality"
+echo ""
+sleep 0.8
+
+# Fetching
+echo -e "${C}→${R} Fetching from Figma API... ${B}8 frames, 21 components${R}"
+sleep 1.2
+
+# Loop iteration 1
+echo ""
+echo -e "${C}┌─────────────────────────────────────────────────┐${R}"
+echo -e "${C}│${R}  ◆ Figma │ Iter 1/10 │ \$0.00                   ${C}│${R}"
+echo -e "${C}└─────────────────────────────────────────────────┘${R}"
+echo -e "  ${C}◐${R} Generating components..."
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 1 complete (23s) ~\$0.31"
+
+# Loop iteration 2
+echo ""
+echo -e "${C}→${R} Loop 2/10: Running visual validation..."
+echo -e "  Pixel diff: ${Y}4.2%${R} — analyzing with LLM vision..."
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 2 complete (18s) ~\$0.28"
+
+# Loop iteration 3
+echo ""
+echo -e "${C}→${R} Loop 3/10: Fixing spacing and font issues..."
+echo -e "  Pixel diff: ${G}0.9%${R} — strict check passed ${G}✓${R}"
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 3 complete (14s) ~\$0.35"
+
+# Done
+echo ""
+echo -e "${G}✓ Done in 3m 42s${R} | Cost: \$0.94 | 3 commits"
+sleep 2

demos/scripts/github-sim.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Simulates ralph-starter run --from github output with real CLI styling
+C='\033[36m'   # Cyan
+G='\033[32m'   # Green
+Y='\033[33m'   # Yellow
+B='\033[1m'    # Bold
+D='\033[2m'    # Dim
+R='\033[0m'    # Reset
+
+# Show the command that was "run"
+echo -e "${D}\$${R} ralph-starter run --from github --project acme/webapp --issue 42 --commit"
+sleep 0.3
+
+# Banner
+echo ""
+echo -e "${C}┌──────────────────────────────────────────────────┐${R}"
+echo -e "${C}│${R}  ${B}ralph-starter${R} ${D}v0.4.0${R}                          ${C}│${R}"
+echo -e "${C}│${R}  ${D}AI-powered project generator${R}                   ${C}│${R}"
+echo -e "${C}└──────────────────────────────────────────────────┘${R}"
+echo ""
+sleep 0.5
+
+# Fetching
+echo -e "${C}→${R} Fetching GitHub issue ${B}#42${R}..."
+sleep 0.8
+echo -e "  Found: ${B}Add user authentication${R}"
+echo -e "  Labels: ${C}feature${R}, ${C}auth${R}"
+echo -e "  ${D}3 linked files loaded${R}"
+sleep 1
+
+# Loop iteration 1
+echo ""
+echo -e "${C}┌─────────────────────────────────────────────────┐${R}"
+echo -e "${C}│${R}   acme/webapp#42 │ Iter 1/5 │ \$0.00           ${C}│${R}"
+echo -e "${C}└─────────────────────────────────────────────────┘${R}"
+echo -e "  ${C}◐${R} Analyzing requirements..."
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 1 complete (19s) ~\$0.12"
+
+# Loop iteration 2
+echo ""
+echo -e "${C}→${R} Loop 2/5: Generating auth module..."
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 2 complete (31s) ~\$0.14"
+
+# Loop iteration 3
+echo ""
+echo -e "${C}→${R} Loop 3/5: Adding tests and validation..."
+sleep 1.2
+echo -e "  ${G}✓${R} Iteration 3 complete (18s) ~\$0.08"
+
+# Validation
+echo ""
+echo -e "${C}→${R} Validation passed: ${G}12 tests${R}, lint clean ${G}✓${R}"
+sleep 0.8
+
+# PR
+echo -e "${C}→${R} Creating pull request..."
+sleep 0.8
+echo -e "  ${G}✓${R} PR ${B}#87${R} created"
+
+# Done
+echo ""
+echo -e "${G}✓ Done in 4m 18s${R} | Cost: \$0.38 | PR #87 created"
+sleep 2