docs: remove deprecated pages and streamline site navigation

Remove when-to-use.md and writing-prompts.md (content folded into other
pages), update nav in mkdocs.yml, and clean up stale sitemap entries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

.gitignore

@@ -13,4 +13,5 @@ node_modules/
 mess/
 .agents/
 .DS_Store
-.coverage
+.coverage
+.ralphify/

docs/cli.md

@@ -61,7 +61,7 @@ ralph run my-ralph --dir ./src             # Pass user args to the ralph
 
 ### User arguments
 
-User arguments are passed as named flags after the ralph path. Use `{{ args.<name> }}` [placeholders](writing-prompts.md#ralph-context-placeholders) in your RALPH.md to reference them.
+User arguments are passed as named flags after the ralph path. Use `{{ args.<name> }}` [placeholders](how-it-works.md#3-resolve-placeholders-with-command-output) in your RALPH.md to reference them.
 
 Named flags (`--name value`) work without any frontmatter declaration. The `args` field is only required when you want to pass **positional** arguments — it tells ralphify which names to map them to:
 
@@ -114,6 +114,16 @@ The loop also stops automatically when:
 - All `-n` iterations have completed
 - `--stop-on-error` is set and the agent exits non-zero or times out
 
+### Peeking at live agent output
+
+When you run `ralph run` in an interactive terminal, the agent's stdout and stderr stream live to the console by default. Press `p` to silence the stream (useful for quieter loops) and press `p` again to resume it. The default is off whenever the output is not a real terminal (piped, redirected, or captured in CI), so `ralph run ... | cat` is unaffected.
+
+Live streaming works with line-buffered agents such as Claude Code, OpenAI Codex, Aider, and any other process that writes one line at a time. For Claude running in stream-json mode you'll see the raw JSON events; for other agents you'll see the agent's plain output. Agents that repaint their own terminal UI (full-screen curses or TUI apps) are not supported — ralphify pipes their stdio, so they detect a non-TTY and fall back to plain output.
+
+When `--log-dir` is set, output is captured to the log file and also echoed after each iteration completes; live peek still works the same way in that mode.
+
+Some runtimes block-buffer their stdout when it is piped, which can make lines appear in bursts rather than as they are produced. If you notice stuttering, set `PYTHONUNBUFFERED=1` (or the equivalent for your agent) in the environment where you launch `ralph`.
+
 ---
 
 ## `ralph scaffold`
@@ -137,7 +147,7 @@ Errors if `RALPH.md` already exists at the target location.
 
 ## RALPH.md format
 
-The `RALPH.md` file is the single configuration and prompt file for a ralph. It uses YAML frontmatter for settings and the body for the prompt text. See [Writing Prompts](writing-prompts.md) for detailed guidance on crafting effective prompts.
+The `RALPH.md` file is the single configuration and prompt file for a ralph. It uses YAML frontmatter for settings and the body for the prompt text.
 
 ```markdown
 ---
@@ -200,6 +210,6 @@ Unmatched placeholders resolve to an empty string.
 
 ## Next steps
 
-- [Writing Prompts](writing-prompts.md) — learn how to craft effective RALPH.md prompts
+- [How it Works](how-it-works.md) — what happens inside each iteration
 - [Quick Reference](quick-reference.md) — condensed cheat sheet for daily use
 - [Python API](api.md) — run loops programmatically instead of via the CLI

docs/cookbook.md

@@ -20,7 +20,7 @@ All recipes use **Claude Code** as the agent. To use a different agent, swap the
 
 ## Run autonomous ML experiments {: #autoresearch }
 
-An autonomous ML research loop inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch). The agent runs experiments on a training script to minimize validation loss — modifying code, training for 5 minutes, keeping improvements and reverting failures. This recipe uses [helper scripts](writing-prompts.md#shell-features-in-commands) as commands to surface experiment state each iteration.
+An autonomous ML research loop inspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch). The agent runs experiments on a training script to minimize validation loss — modifying code, training for 5 minutes, keeping improvements and reverting failures. This recipe uses helper scripts as commands to surface experiment state each iteration.
 
 **`autoresearch/RALPH.md`**
 
@@ -150,7 +150,7 @@ ralph run bug-hunter -n 5 --focus "focus on input validation" --log-dir ralph_lo
 
 A structured research loop that builds up a report over many iterations. Uses shell scripts as commands to track maturity, show the question tree, and even run an editorial review agent that gives feedback between iterations.
 
-This is a more advanced ralph — it uses [`args`](writing-prompts.md#parameterized-ralphs) for the research topic, helper scripts (run with `./` [relative to the ralph directory](how-it-works.md#2-run-commands-and-capture-output)), and a [`timeout`](writing-prompts.md#command-timeouts) on the review command.
+This is a more advanced ralph — it uses [`args`](cli.md#user-arguments) for the research topic, helper scripts (run with `./` [relative to the ralph directory](how-it-works.md#2-run-commands-and-capture-output)), and a [`timeout`](how-it-works.md#2-run-commands-and-capture-output) on the review command.
 
 **`research/RALPH.md`**
 
@@ -174,7 +174,7 @@ ralph run research --workspace ai-safety --focus "current approaches to AI align
 ✓ Iteration 1 completed (185.6s)
 ```
 
-This recipe shows several advanced patterns: commands that call scripts relative to the ralph directory (`./show-focus.sh`), a command with a `timeout`, a command that itself calls an AI agent (`review.sh` pipes to `claude -p`), and `args` used in the prompt body via [`{{ args.workspace }}` placeholders](writing-prompts.md#ralph-context-placeholders).
+This recipe shows several advanced patterns: commands that call scripts relative to the ralph directory (`./show-focus.sh`), a command with a `timeout`, a command that itself calls an AI agent (`review.sh` pipes to `claude -p`), and `args` used in the prompt body via [`{{ args.workspace }}` placeholders](how-it-works.md#3-resolve-placeholders-with-command-output).
 
 ---
 
@@ -243,7 +243,7 @@ Swap `bandit` for your scanner of choice — `semgrep`, `npm audit`, `cargo audi
 
 ## Increase test coverage automatically {: #test-coverage }
 
-A loop that systematically increases test coverage. The agent sees the current coverage percentage and a list of uncovered functions, then writes tests for one module per iteration. The coverage command output feeds into the prompt via [`{{ commands.coverage }}`](writing-prompts.md#using-commands-for-dynamic-data) so the agent always knows where to focus.
+A loop that systematically increases test coverage. The agent sees the current coverage percentage and a list of uncovered functions, then writes tests for one module per iteration. The coverage command output feeds into the prompt via [`{{ commands.coverage }}`](how-it-works.md#3-resolve-placeholders-with-command-output) so the agent always knows where to focus.
 
 **`test-coverage/RALPH.md`**
 
@@ -271,6 +271,5 @@ The coverage report gives the agent a clear metric to improve and shows exactly
 
 ## Next steps
 
-- [Writing Prompts](writing-prompts.md) — customize your recipe's prompt with patterns for task sources, constraints, and live editing
 - [CLI Reference](cli.md) — all `ralph run` options (`--timeout`, `--stop-on-error`, `--delay`, user args)
 - [Troubleshooting](troubleshooting.md) — when the agent hangs, commands fail, or output looks wrong

docs/how-it-works.md

@@ -13,21 +13,7 @@ What happens inside each iteration of an autonomous coding loop? This page break
 
 ## The six steps of each iteration
 
-Every iteration follows the same sequence:
-
-```mermaid
-flowchart TD
-    A[Start iteration] --> B[Re-read RALPH.md from disk]
-    B --> C[Run commands]
-    C --> D[Resolve placeholders]
-    D --> E[Assemble prompt]
-    E --> F[Pipe prompt to agent]
-    F --> G{Agent exits}
-    G --> H[Next iteration]
-    H --> A
-```
-
-Here's what happens at each step.
+Every iteration follows the same sequence. Here's what happens at each step.
 
 ### 1. Re-read the prompt from disk
 
@@ -70,7 +56,7 @@ Unmatched placeholders resolve to an empty string — you won't see raw `{{ }}`
 
 The prompt body (everything below the YAML frontmatter in `RALPH.md`) with all placeholders resolved becomes the fully assembled prompt — a single text string ready for the agent.
 
-HTML comments (`<!-- ... -->`) are stripped during assembly — they never reach the agent. Use them for notes to yourself, like why a rule exists or what to change next. See [Annotate your prompt with HTML comments](writing-prompts.md#annotate-your-prompt-with-html-comments) for examples.
+HTML comments (`<!-- ... -->`) are stripped during assembly — they never reach the agent. Use them for notes to yourself, like why a rule exists or what to change next.
 
 By default, ralphify appends a **co-author trailer instruction** to the end of the prompt, asking the agent to include `Co-authored-by: Ralphify <noreply@ralphify.co>` in its commit messages. This gives visibility into which commits were produced by a ralph loop. To disable it, set `credit: false` in the frontmatter.
 
@@ -199,6 +185,5 @@ The loop continues until one of these happens:
 ## Next steps
 
 - [Getting Started](getting-started.md) — set up your first loop
-- [Writing Prompts](writing-prompts.md) — patterns for effective autonomous loop prompts
 - [CLI Reference](cli.md) — all commands and options
 - [Troubleshooting](troubleshooting.md) — when things don't work as expected

docs/index.md

@@ -1,7 +1,7 @@
 ---
-title: Autonomous AI Coding Loops
-description: Ralphify is a minimal CLI harness for autonomous AI coding loops. Run commands, assemble a prompt, pipe it to an AI agent, and repeat.
-keywords: ralphify, AI coding agent, autonomous coding loop, CLI agent harness, while true loop, agent FOMO, agentic engineering
+title: Ralphify — a runtime for the ralph format
+description: Ralphify is the runtime for the ralph format — a skill-like spec for autonomous agent loops. A ralph is a directory with a RALPH.md file. Ralphify runs it.
+keywords: ralphify, ralph format, RALPH.md, autonomous agent loop, agent runtime, harness engineering, skill-like format, ralph spec
 hide:
   - toc
 ---
@@ -11,19 +11,48 @@ hide:
 </p>
 
 <p align="center" style="font-size: 1.3em; margin-top: -0.5em;">
-<strong>Put your AI coding agent in a <code>while True</code> loop and let it ship.</strong>
+<strong>A ralph is a directory that defines an autonomous agent loop. Ralphify runs it.</strong>
 </p>
 
-Ralphify is a minimal CLI harness for autonomous AI coding loops, inspired by the [Ralph Wiggum technique](https://ghuntley.com/ralph/). The core idea fits in one line:
+A **ralph** is a directory with a `RALPH.md` file — a skill-like format that bundles a prompt, the commands to run between iterations, and any files the agent needs. **Ralphify** is the CLI runtime that executes them.
+
+See [The Ralph Format](blog/posts/the-ralph-format.md) for the full spec.
+
+```
+grow-coverage/
+├── RALPH.md               # the loop definition (required)
+├── check-coverage.sh      # command that runs each iteration
+└── testing-conventions.md # context for the agent
+```
+
+```markdown
+---
+agent: claude -p --dangerously-skip-permissions
+commands:
+  - name: coverage
+    run: ./check-coverage.sh
+---
+
+You are an autonomous coding agent working in a loop.
+Each iteration, write tests for one untested module, then stop.
+
+Follow the conventions in testing-conventions.md.
+
+## Current coverage
+
+{{ commands.coverage }}
+```
 
 ```bash
-while :; do cat RALPH.md | claude -p ; done
+ralph run grow-coverage     # loops until Ctrl+C
 ```
 
-Ralphify wraps this into a proper tool — running commands that feed test results and context into each iteration, tracking progress, and handling clean shutdown.
+One directory. One command. Each iteration starts with fresh context and current data — ralphify runs the commands, fills in `{{ placeholders }}`, pipes the prompt to your agent, and loops.
+
+*Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.*
 
 [Get Started](getting-started.md){ .md-button .md-button--primary }
-[View Cookbook](cookbook.md){ .md-button }
+[Read the Format Spec](blog/posts/the-ralph-format.md){ .md-button }
 
 ---
 
@@ -47,102 +76,39 @@ Ralphify wraps this into a proper tool — running commands that feed test resul
     pip install ralphify
     ```
 
-## Create a ralph and run it
+## Scaffold a ralph and run it
 
 ```bash
-ralph init my-ralph
+ralph scaffold my-ralph
 ```
 
-This creates a directory with a `RALPH.md` template. Edit it to fit your project:
-
-**`my-ralph/RALPH.md`**
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
-commands:
-  - name: tests
-    run: uv run pytest -x
-  - name: git-log
-    run: git log --oneline -10
----
-
-# Prompt
-
-## Recent commits
-
-{{ commands.git-log }}
-
-## Test results
-
-{{ commands.tests }}
-
-You are an autonomous coding agent running in a loop. Each iteration
-starts with a fresh context. Your progress lives in the code and git.
-
-Read TODO.md for the current task list. Pick the top uncompleted task,
-implement it fully, then mark it done.
-
-If tests are failing, fix them before starting new work.
-
-## Rules
-
-- One task per iteration
-- No placeholder code — full, working implementations only
-- Commit with a descriptive message like `feat: add X` or `fix: resolve Y`
-- Mark the completed task in TODO.md
-```
+This creates a directory with a `RALPH.md` template. Edit it, then run:
 
 ```bash
-ralph run my-ralph         # Start the loop (Ctrl+C to stop)
-ralph run my-ralph -n 3    # Run 3 iterations
-```
-
-### What it looks like
-
-```text
-$ ralph run my-ralph -n 3 --log-dir ralph_logs
-
-▶ Running: my-ralph
-  2 commands · max 3 iterations
-
-── Iteration 1 ──
-  Commands: 2 ran
-✓ Iteration 1 completed (52.3s)
-  → ralph_logs/001_20250115-142301.log
-
-── Iteration 2 ──
-  Commands: 2 ran
-✗ Iteration 2 failed with exit code 1 (23.1s)
-  → ralph_logs/002_20250115-142512.log
-
-── Iteration 3 ──
-  Commands: 2 ran
-✓ Iteration 3 completed (41.7s)
-  → ralph_logs/003_20250115-143012.log
-
-──────────────────────
-Done: 3 iterations — 2 succeeded, 1 failed
+ralph run my-ralph         # loop until Ctrl+C
+ralph run my-ralph -n 3    # run 3 iterations
 ```
 
 Edit `RALPH.md` while the loop is running — changes take effect on the next iteration.
 
 ## Or install one with agr
 
-Install a pre-built ralph from any GitHub repo using [agr](https://github.com/computerlovetech/agr) and run it immediately:
+Ralphs are just directories, so you can share them via any git repo. Install a pre-built ralph from GitHub with [agr](https://github.com/computerlovetech/agr):
 
 ```bash
-agr add owner/repo/my-ralph     # Install a ralph from GitHub
-ralph run my-ralph               # Run it
+agr add owner/repo/my-ralph     # install a ralph from GitHub
+ralph run my-ralph              # run it by name
 ```
 
-agr installs ralphs to `.agents/ralphs/` so you can run them by name.
+agr installs ralphs to `.agents/ralphs/` so they're automatically discovered by `ralph run`.
 
 ---
 
-## Why ralph loops?
+## Why a format
+
+Everyone writing ralph loops ends up with the same scaffolding: a markdown prompt, a few shell commands that surface state between iterations, a while-loop that ties them together. Turning that into a format makes ralphs **shareable**, **versionable**, and **installable** — the same way skills made inner-loop workflows shareable.
 
-A single agent conversation fills up its context window, slows down, and eventually loses the plot. ralph loops solve this by resetting every iteration — the agent always starts fresh.
+Ralphs are to the outer loop what [skills](https://agentskills.io/) are to the inner loop. A skill guides an agent inside a session. A ralph defines what runs *between* sessions.
 
 <div class="grid cards" markdown>
 
@@ -183,8 +149,8 @@ A single agent conversation fills up its context window, slows down, and eventua
 
 ## Next steps
 
-- **[When to Use](when-to-use.md)** — figure out if a ralph loop fits your task
+- **[The Ralph Format](blog/posts/the-ralph-format.md)** — the full spec
 - **[Getting Started](getting-started.md)** — from install to a running loop in 10 minutes
-- **[Writing Prompts](writing-prompts.md)** — patterns for effective autonomous loop prompts
-- **[Cookbook](cookbook.md)** — copy-pasteable setups for coding, docs, research, and more
+- **[How it Works](how-it-works.md)** — what happens inside each iteration
+- **[Cookbook](cookbook.md)** — copy-pasteable ralphs for coding, docs, research, and more
 - **[Python API](api.md)** — embed the loop in your own automation

docs/quick-reference.md

@@ -88,7 +88,7 @@ Your instructions here. Use {{ args.dir }} for user arguments. <!-- (6) -->
 | `timeout` | number | `60` | Max seconds before the command is killed |
 
 !!! warning "No shell features in commands"
-    Commands are run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Use a script instead: `run: ./my-script.sh` (scripts starting with `./` run from the ralph directory). See [Writing Prompts → Shell features](writing-prompts.md#shell-features-in-commands) for details.
+    Commands are run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Use a script instead: `run: ./my-script.sh` (scripts starting with `./` run from the ralph directory).
 
 ## Placeholders
 
@@ -105,7 +105,7 @@ Your instructions here. Use {{ args.dir }} for user arguments. <!-- (6) -->
 - Unmatched placeholders resolve to empty string
 - Must be `commands` (plural)
 
-For details on writing effective prompts with placeholders, see [Writing Prompts](writing-prompts.md).
+For details on placeholder resolution, see [How it Works](how-it-works.md#3-resolve-placeholders-with-command-output).
 
 ### User argument placeholders
 
@@ -156,6 +156,7 @@ Each iteration:
 |---|---|
 | `Ctrl+C` (once) | Finishes the current iteration gracefully, then stops |
 | `Ctrl+C` (twice) | Force-kills the agent process and exits immediately |
+| `p` | Toggle live peek of the agent's stdout (on by default in an interactive terminal — press to silence, press again to resume) |
 | `-n` limit reached | Stops after the specified number of iterations |
 | `--stop-on-error` | Stops if agent exits non-zero or times out |
 
@@ -164,8 +165,6 @@ Each iteration:
 - The prompt body is re-read from disk every iteration — edit the prompt while the loop runs (frontmatter is parsed once at startup)
 - HTML comments (`<!-- ... -->`) are stripped from the prompt — use them for notes to yourself
 
-Tips on structuring prompts for different tasks → [Writing Prompts](writing-prompts.md)
-
 ## Common patterns
 
 ### Minimal ralph
@@ -228,6 +227,6 @@ More patterns and real-world examples → [Cookbook](cookbook.md)
 ## Next steps
 
 - [Getting Started](getting-started.md) — set up your first ralph end-to-end
-- [Writing Prompts](writing-prompts.md) — prompt structure, shell limitations, and advanced patterns
+- [How it Works](how-it-works.md) — what happens inside each iteration
 - [Cookbook](cookbook.md) — copy-pasteable ralphs for common tasks
 - [Troubleshooting](troubleshooting.md) — common issues and how to fix them