@@ -98,7 +113,7 @@ Everything in ralphify is one of these five jobs. That's the whole tool.
`commands` run each iteration; their output fills `{{ commands.
}}` in the prompt. The agent always sees current test results, coverage, and git log — a self-healing feedback loop.
- [How it works →](how-it-works.md)
+ [How it works →](cli.md#how-the-loop-works)
- :material-play-circle-outline:{ .lg .middle } **3. Run the loop**
@@ -124,7 +139,7 @@ Everything in ralphify is one of these five jobs. That's the whole tool.
---
- A ralph is a portable directory in the [ralph loops format](https://ralphloops.io/). Commit it to git and push — anyone can clone the repo and run it by name.
+ This is what the standard format buys you. A ralph is a portable directory in the open [ralph loops format](https://ralphloops.io/) — commit it, push it, and anyone with ralphify can run it.
```bash
git clone https://github.com/owner/repo
@@ -135,9 +150,9 @@ Everything in ralphify is one of these five jobs. That's the whole tool.
---
-## Why loops
+## Why loop engineering works
-A single agent run fixes a bug or writes a function. The leverage of a ralph loop is **sustained, autonomous work** — running for hours, one commit at a time, while you do something else.
+A single agent run fixes a bug or writes a function. The leverage of loop engineering is **sustained, autonomous work** — a ralph loop runs for hours, one commit at a time, while you do something else.
- **Fresh context, no decay.** Each iteration starts with a clean context window. The agent reads the current state of the codebase every loop — no conversation bloat, no degradation.
- **Commands as feedback.** Command output feeds into the prompt each iteration. When tests fail, the agent sees the failure and fixes it next cycle.
@@ -149,13 +164,12 @@ A single agent run fixes a bug or writes a function. The leverage of a ralph loo
## Requirements
- Python 3.11+
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (or [any agent CLI](agents.md) that accepts piped input)
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (or [any agent CLI](cli.md#using-different-agents) that accepts piped input)
---
## Next steps
- **[Getting Started](getting-started.md)** — from install to a running loop in 10 minutes
-- **[How it Works](how-it-works.md)** — what happens inside each iteration
-- **[Cookbook](cookbook.md)** — copy-pasteable ralph loops to start from
-- **[The ralph loops format](https://ralphloops.io/)** — the open spec ralphify implements
+- **[Reference](cli.md)** — the CLI, RALPH.md format, how the loop works, agents, troubleshooting, and the Python API
+- **[The ralph loops format](https://ralphloops.io/)** — the open, standard spec ralphify implements
diff --git a/docs/quick-reference.md b/docs/quick-reference.md
deleted file mode 100644
index 479c0ea..0000000
--- a/docs/quick-reference.md
+++ /dev/null
@@ -1,233 +0,0 @@
----
-title: "RALPH.md Syntax and CLI Cheat Sheet — Ralphify Quick Reference"
-description: "Cheat sheet for ralphify — RALPH.md frontmatter format, CLI flags for ralph run/scaffold, placeholder syntax for commands and args, and common loop patterns you can copy-paste."
-keywords: RALPH.md format, RALPH.md frontmatter syntax, ralph run CLI flags, ralphify cheat sheet, AI coding agent loop syntax, ralph commands placeholder, ralph args placeholder, ralph scaffold, autonomous agent loop reference, ralphify quick reference
----
-
-# Quick Reference
-
-Everything you need at a glance. Bookmark this page.
-
-## CLI commands
-
-```bash
-ralph run my-ralph # Run loop forever (Ctrl+C to stop)
-ralph run my-ralph/RALPH.md # Can also pass the file path directly
-ralph run my-ralph -n 5 # Run 5 iterations
-ralph run my-ralph -n 1 --log-dir logs # Single iteration with output capture
-ralph run my-ralph --stop-on-error # Stop if agent exits non-zero or times out
-ralph run my-ralph --delay 10 # Wait 10s between iterations
-ralph run my-ralph --timeout 300 # Kill agent after 5 min per iteration
-ralph run my-ralph --dir ./src # Pass user args to the ralph
-
-ralph scaffold my-task # Scaffold a ralph from template
-ralph scaffold # Scaffold in current directory
-
-ralph --version # Show version
-```
-
-Full flag descriptions and examples → [CLI reference](cli.md)
-
-## Directory structure
-
-```text
-my-ralph/
-└── RALPH.md # Prompt + configuration (required)
-```
-
-That's it. A ralph is a directory with a `RALPH.md` file. See [Getting Started](getting-started.md) to create your first one.
-
-## RALPH.md format
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions # (1)!
-commands: # (2)!
- - name: tests
- run: uv run pytest -x
- - name: lint
- run: uv run ruff check .
- - name: git-log
- run: git log --oneline -10
-args: [dir, focus] # (3)!
----
-
-# Prompt body
-
-{{ commands.git-log }}
-
-{{ commands.tests }}
-
-{{ commands.lint }}
-
-Your instructions here. Use {{ args.dir }} for user arguments.
-```
-
-1. **Required.** The full shell command to pipe the prompt to. `-p` enables non-interactive mode, `--dangerously-skip-permissions` lets the agent work autonomously.
-2. **Optional.** Each command runs every iteration and its output fills the matching `{{ commands. }}` placeholder.
-3. **Optional.** Declares positional argument names. Named flags (`--dir`, `--focus`) work without this — `args` is only needed for positional usage.
-4. Everything below the `---` frontmatter is the prompt body. It's re-read from disk every iteration, so you can edit it while the loop runs.
-5. Replaced with the command's stdout + stderr. Only commands with a matching placeholder appear in the assembled prompt.
-6. Replaced with the `--dir` value from the CLI. Missing args resolve to an empty string.
-
-### Frontmatter fields
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `agent` | string | yes | Full agent command (piped via stdin). See [agent configuration](agents.md) for supported agents. |
-| `commands` | list | no | Commands to run each iteration |
-| `args` | list | no | User argument names. Letters, digits, hyphens, and underscores only. |
-| `credit` | bool | no | Append co-author trailer instruction to prompt (default: `true`) |
-
-### Command fields
-
-| Field | Type | Default | Description |
-|---|---|---|---|
-| `name` | string | (required) | Identifier for `{{ commands. }}`. Letters, digits, hyphens, and underscores only. |
-| `run` | string | (required) | Shell command to execute (supports `{{ args. }}` placeholders). Commands starting with `./` run from the ralph directory; others run from the project root. |
-| `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).
-
-## Placeholders
-
-### Command placeholders
-
-```markdown
-{{ commands.tests }}
-{{ commands.git-log }}
-```
-
-1. Replaced with the `tests` command's stdout + stderr, regardless of exit code.
-2. Replaced with the `git-log` command's output. Only commands referenced by a placeholder appear in the assembled prompt — unreferenced commands still run but their output is excluded.
-
-- Unmatched placeholders resolve to empty string
-- Must be `commands` (plural)
-
-For details on placeholder resolution, see [How it Works](how-it-works.md#3-resolve-placeholders-with-command-output).
-
-### User argument placeholders
-
-```markdown
-{{ args.dir }}
-{{ args.focus }}
-```
-
-1. Replaced with the `--dir` value from the CLI. Missing args resolve to empty string.
-2. Replaced with the `--focus` value from the CLI.
-
-- Pass via `ralph run my-ralph --dir ./src --focus "perf"` or `--dir=./src` (named flags)
-- Or positionally: `ralph run my-ralph ./src "perf"` (requires `args:` in frontmatter)
-- Mixed: `ralph run my-ralph --focus "perf" ./src` — positional args skip names already provided via flags
-- `--` ends flag parsing: `ralph run my-ralph -- --verbose ./src` treats `--verbose` as a positional value
-- See [CLI reference → User arguments](cli.md#user-arguments) for full details on flag and positional parsing
-
-### ralph placeholders
-
-```markdown
-{{ ralph.name }}
-{{ ralph.iteration }}
-{{ ralph.max_iterations }}
-```
-
-1. Ralph directory name (e.g. `my-ralph`).
-2. Current iteration number (1-based).
-3. Total iterations if `-n` was set, empty otherwise.
-
-- Automatically available — no frontmatter configuration needed
-- Useful for progress tracking, naming logs, or adjusting behavior near the end of a run
-- See [How it Works](how-it-works.md) for more on the loop lifecycle
-
-## The loop
-
-Each iteration:
-
-1. Re-read `RALPH.md` from disk
-2. Run all commands in order, capture output
-3. Resolve `{{ commands.* }}`, `{{ args.* }}`, and `{{ ralph.* }}` placeholders
-4. Pipe assembled prompt to agent via stdin
-5. Wait for agent to exit
-6. Repeat
-
-### Stopping the loop
-
-| Action | What happens |
-|---|---|
-| `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) |
-| `P` (shift+p) | Open full-screen peek — scroll the buffer and browse iterations. `j/k` line, `space/b` page, `g/G` top/bottom, `[/]` prev/next iteration, `q` or `P` exits |
-| `-n` limit reached | Stops after the specified number of iterations |
-| `--stop-on-error` | Stops if agent exits non-zero or times out |
-
-## Live editing
-
-- 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
-
-## Common patterns
-
-### Minimal ralph
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
----
-
-Read TODO.md and implement the next task. Commit when done.
-```
-
-### Self-healing with test feedback
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
-commands:
- - name: tests
- run: uv run pytest -x
----
-
-{{ commands.tests }}
-
-Fix failing tests before starting new work.
-Read TODO.md and implement the next task.
-```
-
-### Parameterized ralph
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
-args: [dir, focus]
----
-
-Research the codebase at {{ args.dir }}.
-Focus area: {{ args.focus }}.
-```
-
-```bash
-ralph run research --dir ./api --focus "error handling"
-```
-
-### Debug a single iteration
-
-```bash
-ralph run my-ralph -n 1 --log-dir ralph_logs
-cat ralph_logs/001_*.log
-```
-
-### Run on a branch
-
-```bash
-git checkout -b feature && ralph run my-ralph
-```
-
-More patterns and real-world examples → [Cookbook](cookbook.md)
-
-## Next steps
-
-- [Getting Started](getting-started.md) — set up your first ralph end-to-end
-- [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
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
deleted file mode 100644
index a981fdd..0000000
--- a/docs/troubleshooting.md
+++ /dev/null
@@ -1,571 +0,0 @@
----
-title: "Fix Agent Hangs, Command Failures, and RALPH.md Errors — Ralphify Troubleshooting"
-description: "Solve common ralphify issues: agent hangs or produces no output, RALPH.md frontmatter syntax errors, commands with pipes not working, missing placeholders, argument parsing failures, and iteration timeouts."
-keywords: ralphify troubleshooting, fix agent hang, agent produces no output, RALPH.md frontmatter error, invalid YAML frontmatter, command timeout ralphify, command pipes not working shlex, ralph run error, agent command not found, debug ralph loop, fix autonomous coding agent, placeholder not resolving, ralph argument parsing
----
-
-# Troubleshooting
-
-!!! tldr "Quick checklist"
- 1. Run `ralph run my-ralph -n 1` — it validates your setup and shows clear errors
- 2. Test the agent outside ralphify: `echo "Say hello" | claude -p`
- 3. Use `--log-dir ralph_logs` to capture output for debugging
- 4. Commands don't support shell features (pipes, `&&`) — use a wrapper script instead
-
-Common issues and how to fix them. If your problem isn't listed here, run [`ralph run`](cli.md#ralph-run) with `-n 1` — it validates your setup and shows clear errors.
-
-## Setup issues
-
-### "is not a directory, RALPH.md file, or installed ralph"
-
-The path you passed to [`ralph run`](cli.md#ralph-run) doesn't resolve to a valid ralph. The command accepts a **directory** containing `RALPH.md`, a **direct path** to a `RALPH.md` file, or the **name of an installed ralph** in `.agents/ralphs/`:
-
-```bash
-ralph run my-ralph # directory containing RALPH.md
-ralph run my-ralph/RALPH.md # direct path to the file
-ralph run my-ralph # installed ralph in .agents/ralphs/my-ralph/
-```
-
-If you're getting this error, check that the path exists and points to the right place:
-
-```bash
-ls my-ralph/RALPH.md # local ralph
-ls .agents/ralphs/my-ralph/RALPH.md # installed ralph
-```
-
-### "Missing or empty 'agent' field in RALPH.md frontmatter"
-
-Your `RALPH.md` frontmatter is missing the `agent` field or it's an empty string. Add it:
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
----
-```
-
-### "Agent command 'claude' not found on PATH"
-
-The agent CLI isn't installed or isn't in your shell's PATH. Verify by running `claude --version` directly. If it's installed but not found, check your PATH. See [supported agents](agents.md) for setup instructions.
-
-## Loop issues
-
-### Agent produces no output or seems to hang
-
-Try running the [agent command](agents.md) directly to see if it works outside of ralphify:
-
-```bash
-echo "Say hello" | claude -p
-```
-
-If it hangs there too, the issue is with the agent CLI, not ralphify. If it works standalone but hangs via ralphify, try adding `--timeout` to kill stalled iterations:
-
-```bash
-ralph run my-ralph --timeout 300
-```
-
-### Agent exits non-zero every iteration
-
-Check the agent's output to understand why. Use `--log-dir` to capture output:
-
-```bash
-ralph run my-ralph -n 1 --log-dir ralph_logs
-cat ralph_logs/001_*.log
-```
-
-Common causes:
-
-- The agent CLI requires authentication that hasn't been set up
-- The prompt asks the agent to run a command that fails
-- The agent's context window is being exceeded by a very large prompt
-
-If you want the loop to stop on errors instead of continuing, use `--stop-on-error`:
-
-```bash
-ralph run my-ralph --stop-on-error --log-dir ralph_logs
-```
-
-### Agent runs but doesn't commit
-
-Ralphify doesn't commit for the agent — committing is the agent's responsibility. Make sure your prompt includes explicit commit instructions:
-
-```markdown
-## Process
-- Run tests before committing
-- Commit with a descriptive message like `feat: add X`
-```
-
-Also ensure the agent has permission to run git commands. With Claude Code, the `--dangerously-skip-permissions` flag handles this.
-
-### Loop runs too fast / agent not doing anything useful
-
-If iterations finish in seconds with no meaningful work, the agent may be exiting without taking action. Check the logs with [`--log-dir`](cli.md#ralph-run):
-
-```bash
-ralph run my-ralph -n 1 --log-dir ralph_logs
-cat ralph_logs/001_*.log
-```
-
-Common causes:
-
-- The prompt is too vague — tell the agent it's in a loop with no memory between iterations, and give it a specific task
-- There's no concrete task source — point the prompt at something like `TODO.md`, `PLAN.md`, or failing tests
-- The agent can't find what it's supposed to work on
-
-### Agent output not streaming to the terminal
-
-In an interactive terminal, agent output streams live by default. If you don't see any output between the iteration markers:
-
-- **Check the peek toggle** — press `p` to toggle live output on or off. You may have silenced it in a previous iteration.
-- **Non-TTY environments** — live streaming is disabled when output is piped, redirected, or running in CI. This is intentional — use `--log-dir` to capture output instead.
-- **Output appears in bursts** — some runtimes block-buffer stdout when piped. Set `PYTHONUNBUFFERED=1` in your environment to force line-buffered output.
-- **Full-screen TUI agents** — agents that repaint their own terminal (curses-based tools) are not supported for live streaming. They detect a non-TTY and fall back to plain output, which may be minimal.
-
-## Frontmatter issues
-
-### "Invalid YAML in frontmatter"
-
-Your YAML frontmatter has a syntax error — usually a missing colon, bad indentation, or an unquoted special character. The error message includes the YAML parser's details:
-
-```text
-Invalid YAML in frontmatter: while parsing a block mapping ...
-```
-
-Common fixes:
-
-```yaml
-# ✗ Wrong — missing colon, bad indentation
-agent claude -p
-commands:
-- name: tests
-run: uv run pytest
-
-# ✓ Correct
-agent: claude -p
-commands:
- - name: tests
- run: uv run pytest
-```
-
-If your value contains special YAML characters (`:`, `#`, `{`, `[`), wrap it in quotes:
-
-```yaml
-agent: "claude -p --dangerously-skip-permissions"
-```
-
-### "Frontmatter must be a YAML mapping"
-
-The frontmatter parsed as valid YAML but isn't a key-value mapping. This usually happens when the frontmatter is a plain string or a list instead of a mapping:
-
-```yaml
-# ✗ Wrong — this is a plain string, not a mapping
----
-claude -p --dangerously-skip-permissions
----
-
-# ✓ Correct — key: value pairs
----
-agent: claude -p --dangerously-skip-permissions
----
-```
-
-### "Each command must have 'name' and 'run' fields"
-
-A command entry in `commands` is missing a required key. Every command needs both `name` and `run`:
-
-```yaml
-# ✗ Wrong — missing 'run'
-commands:
- - name: tests
-
-# ✗ Wrong — missing 'name'
-commands:
- - run: uv run pytest -x
-
-# ✓ Correct
-commands:
- - name: tests
- run: uv run pytest -x
-```
-
-The related error **"Command '...' must be a non-empty string"** means a `name` or `run` value is empty or not a string.
-
-### "Malformed 'agent' field in RALPH.md frontmatter"
-
-The `agent` value couldn't be parsed as a shell command — usually an unmatched quote:
-
-```yaml
-# ✗ Wrong — unclosed quote
-agent: claude -p "dangerously-skip-permissions
-
-# ✓ Correct
-agent: claude -p --dangerously-skip-permissions
-```
-
-### "'credit' must be true or false"
-
-The `credit` field only accepts boolean values. YAML bare words `true`/`false` work, but quoted strings don't:
-
-```yaml
-# ✗ Wrong
-credit: "yes"
-credit: 0
-
-# ✓ Correct
-credit: false
-credit: true
-```
-
-### "Command name contains invalid characters" / "Arg name contains invalid characters"
-
-Command names and arg names may only contain letters, digits, hyphens, and underscores (`a-z`, `A-Z`, `0-9`, `-`, `_`). Names with dots, spaces, or special characters are rejected because they can't be used in [`{{ commands. }}` or `{{ args. }}` placeholders](how-it-works.md#3-resolve-placeholders-with-command-output).
-
-```yaml
-# ✗ Wrong — dots and spaces aren't allowed
-args: [my.focus, test subject]
-commands:
- - name: my.tests
- run: uv run pytest -x
- - name: test suite
- run: uv run pytest -x
-
-# ✓ Correct — use hyphens or underscores
-args: [my-focus, test_subject]
-commands:
- - name: my-tests
- run: uv run pytest -x
- - name: test_suite
- run: uv run pytest -x
-```
-
-### "Duplicate arg name" / "Duplicate command name"
-
-Arg names and command names must be unique within a single `RALPH.md`. Duplicates are rejected at startup:
-
-```yaml
-# ✗ Wrong — "tests" appears twice
-commands:
- - name: tests
- run: uv run pytest -x
- - name: tests
- run: uv run pytest tests/integration
-
-# ✓ Correct — use distinct names
-commands:
- - name: unit-tests
- run: uv run pytest -x
- - name: integration-tests
- run: uv run pytest tests/integration
-```
-
-The same applies to `args` — each name must appear only once.
-
-### "'commands' must be a list" or "'args' must be a list of strings"
-
-YAML scalars and lists look similar. A common mistake is writing a plain string where a list is expected:
-
-```yaml
-# ✗ Wrong — this is a string, not a list
-args: focus
-commands: uv run pytest -x
-
-# ✓ Correct — use list syntax
-args: [focus]
-commands:
- - name: tests
- run: uv run pytest -x
-```
-
-`args` must be a list of strings (`[focus]` or `- focus`). `commands` must be a list of `{name, run}` mappings.
-
-### "'args' items must be strings, got non-string value"
-
-Every item in the `args` list must be a string. YAML can silently coerce bare values into numbers or booleans:
-
-```yaml
-# ✗ Wrong — YAML reads 42 as an integer, true as a boolean
-args: [focus, 42, true]
-
-# ✓ Correct — quote non-string-looking values, or just use plain names
-args: [focus, count, enabled]
-```
-
-### "Command '...' has invalid timeout"
-
-The `timeout` field on a command must be a positive number (in seconds). Strings, zero, and negative values are rejected:
-
-```yaml
-# ✗ Wrong
-commands:
- - name: tests
- run: uv run pytest -x
- timeout: "five minutes"
-
-# ✓ Correct
-commands:
- - name: tests
- run: uv run pytest -x
- timeout: 300
-```
-
-## Argument issues
-
-### "Positional argument '...' requires args declared in RALPH.md frontmatter"
-
-You passed a bare value (not a `--name value` flag) to [`ralph run`](cli.md#ralph-run), but your RALPH.md doesn't have an `args` field. Either declare the args or use the `--name value` syntax:
-
-```bash
-# ✗ Fails — no args declared, so positional values aren't allowed
-ralph run my-ralph "error handling"
-
-# ✓ Option A — declare args in RALPH.md, then pass positionally
-# (add `args: [focus]` to frontmatter)
-ralph run my-ralph "error handling"
-
-# ✓ Option B — use flag syntax (works even without args declared)
-ralph run my-ralph --focus "error handling"
-```
-
-### "Too many positional arguments"
-
-You passed more positional values than the `args` field declares:
-
-```bash
-# RALPH.md has: args: [focus]
-# ✗ Fails — only 1 arg declared, but 2 values given
-ralph run my-ralph "error handling" "api module"
-
-# ✓ Correct — one positional value per declared arg
-ralph run my-ralph "error handling"
-```
-
-### "Flag '--...' requires a value"
-
-A `--name` flag was passed without a value:
-
-```bash
-# ✗ Fails — --focus has no value
-ralph run my-ralph --focus
-
-# ✓ Correct
-ralph run my-ralph --focus "error handling"
-```
-
-## Command issues
-
-### "Command '...' has invalid syntax"
-
-A command's `run` string has malformed shell syntax — usually an unmatched quote. The error message tells you which command failed:
-
-```text
-Command 'tests' has invalid syntax: 'uv run pytest -x "unclosed'. Check the 'commands' field in your RALPH.md frontmatter.
-```
-
-Fix the quoting in the `run` value. If your command needs complex quoting, point it at a script instead — see [Command with pipes or redirections not working](#command-with-pipes-or-redirections-not-working).
-
-### "Command '...' binary not found"
-
-A command in your `commands` field references a binary that isn't installed or isn't on your PATH. The error message tells you which command failed:
-
-```text
-Command 'lint' binary not found: 'mypy src/'. Check the 'commands' field in your RALPH.md frontmatter.
-```
-
-Verify the binary exists by running it directly:
-
-```bash
-mypy --version
-```
-
-If it's installed in a virtual environment, prefix the command with `uv run` or the appropriate runner:
-
-```yaml
-commands:
- - name: lint
- run: uv run mypy src/
-```
-
-### Command with pipes or redirections not working
-
-Commands in the `run` field are parsed with `shlex` and run **directly** — not through a shell. Shell features like pipes (`|`), redirections (`2>&1`), chaining (`&&`), and variable expansion (`$VAR`) silently fail or produce unexpected results. The escape hatch is a script — wrap the shell features inside a `.sh` file and point the command at it.
-
-**Won't work:**
-
-```yaml
-commands:
- - name: tests
- run: pytest --tb=line -q 2>&1 | tail -20
-```
-
-**Fix:** Point the command at a script instead:
-
-```bash
-#!/bin/bash
-# scripts/run-tests.sh
-pytest --tb=line -q 2>&1 | tail -20
-```
-
-```bash
-chmod +x scripts/run-tests.sh
-```
-
-```yaml
-commands:
- - name: tests
- run: scripts/run-tests.sh
-```
-
-Commands without a `./` prefix run from the project root, so `scripts/run-tests.sh` resolves to `/scripts/run-tests.sh`. If you want to bundle the script next to your `RALPH.md`, use the `./` prefix instead — see [Working directory](how-it-works.md#2-run-commands-and-capture-output) for details.
-
-### Command always failing
-
-Run the command manually to see if it works:
-
-```bash
-uv run pytest -x
-```
-
-If the command fails manually, the issue isn't with ralphify — fix the underlying test/lint failures first.
-
-Note that command output is included in the prompt **regardless of exit code**. A failing test command is often exactly what you want — the agent sees the failure and fixes it.
-
-### Command output looks truncated
-
-Each command has a default timeout of **60 seconds** (see [Run commands and capture output](how-it-works.md#2-run-commands-and-capture-output)). If your command takes longer (a large test suite, a slow build), it's killed at the timeout and only the output captured so far is used. The agent sees a notice appended to the output:
-
-```text
-[Command 'tests' timed out after 60s — output may be incomplete]
-```
-
-**Fix:** Increase the timeout for slow commands:
-
-```yaml
-commands:
- - name: tests
- run: uv run pytest -x
- timeout: 300 # 5 minutes
-```
-
-You can also speed up the command itself — for example, running a subset of tests or filtering output via a [wrapper script](#command-with-pipes-or-redirections-not-working).
-
-### Command output missing from prompt
-
-If a `{{ commands.my-command }}` placeholder produces nothing in the prompt:
-
-1. Check the command name matches exactly: `{{ commands.my-command }}` requires a command with `name: my-command`
-2. Verify the command produces output by running it manually
-3. Must be `commands` (plural) — `{{ command.name }}` won't resolve
-
-??? note "No output visible during iteration"
- Agent output streams live to the terminal by default — press `p` to toggle it on or off. If you're using `--log-dir`, output is also echoed after each iteration completes. See [Agent output not streaming](#agent-output-not-streaming-to-the-terminal) for more details.
-
-??? note "CLI flag validation errors"
- ### "'-n' must be a positive integer"
-
- The `-n` flag sets how many iterations to run. It must be at least 1:
-
- ```bash
- # ✗ Wrong
- ralph run my-ralph -n 0
-
- # ✓ Correct
- ralph run my-ralph -n 1
- ```
-
- ### "'--delay' must be non-negative"
-
- The `--delay` flag sets seconds to wait between iterations. It can be zero but not negative:
-
- ```bash
- # ✗ Wrong
- ralph run my-ralph --delay -5
-
- # ✓ Correct
- ralph run my-ralph --delay 0
- ralph run my-ralph --delay 30
- ```
-
- ### "'--timeout' must be a positive number"
-
- The `--timeout` flag sets the per-iteration time limit in seconds. It must be greater than zero:
-
- ```bash
- # ✗ Wrong
- ralph run my-ralph --timeout 0
-
- # ✓ Correct
- ralph run my-ralph --timeout 300
- ```
-
-## Common questions
-
-### Can I run multiple loops in parallel?
-
-Yes, but they should work on **separate branches** to avoid git conflicts:
-
-```bash
-# Terminal 1
-git checkout -b feature-a && ralph run feature-a-ralph
-
-# Terminal 2
-git checkout -b feature-b && ralph run feature-b-ralph
-```
-
-For programmatic control over concurrent runs, use the [Python API's `RunManager`](api.md#concurrent-runs-with-runmanager).
-
-### What files should I commit?
-
-| File / directory | Commit? | Why |
-|---|---|---|
-| `my-ralph/RALPH.md` | **Yes** | The ralph definition |
-| `my-ralph/*.sh` | **Yes** | Helper scripts referenced by commands |
-| `ralph_logs/` | **No** | Iteration logs — add to `.gitignore` |
-
-### Can I edit RALPH.md while the loop runs?
-
-Yes. The prompt body (everything below the frontmatter) is re-read every iteration — edit the prompt text and changes take effect on the next cycle. Frontmatter fields (`agent`, `commands`, `args`) are parsed once at startup, so changing those requires restarting the loop.
-
-### How do I disable the co-author credit in commits?
-
-By default, ralphify appends an instruction asking the agent to add `Co-authored-by: Ralphify ` to commit messages. To disable it, set `credit: false` in your RALPH.md frontmatter:
-
-```yaml
----
-agent: claude -p --dangerously-skip-permissions
-credit: false
----
-```
-
-### How do I make a ralph reusable across projects?
-
-Use `args` to parameterize your ralph instead of hardcoding project-specific values:
-
-```markdown
----
-agent: claude -p --dangerously-skip-permissions
-args: [dir, focus]
-commands:
- - name: tests
- run: uv run pytest {{ args.dir }}
----
-
-Focus on {{ args.dir }}. Priority: {{ args.focus }}
-```
-
-```bash
-ralph run my-ralph --dir ./api --focus "error handling"
-ralph run my-ralph --dir ./frontend --focus "accessibility"
-```
-
-See [User arguments](cli.md#user-arguments) for more on parameterizing ralphs.
-
-## Getting more help
-
-1. Run `ralph run my-ralph -n 1` to validate your setup — it shows clear errors
-2. Use `ralph run my-ralph -n 1 --log-dir ralph_logs` to capture a single iteration for debugging
-3. Check the [CLI reference](cli.md) for all available options
-4. File an issue at [github.com/computerlovetech/ralphify](https://github.com/computerlovetech/ralphify/issues)
-
-## Next steps
-
-- [How it works](how-it-works.md) — understand the iteration lifecycle to debug more effectively
-- [Cookbook](cookbook.md) — working examples you can adapt for your project
diff --git a/mkdocs.yml b/mkdocs.yml
index 9f4365a..5a77d82 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -108,18 +108,9 @@ extra:
nav:
- Home: index.md
- - Guide:
- - Getting Started: getting-started.md
- - How it Works: how-it-works.md
- - Using with Different Agents: agents.md
- - Cookbook: cookbook.md
- - Reference:
- - Quick Reference: quick-reference.md
- - CLI: cli.md
- - Python API: api.md
- - Help:
- - Troubleshooting: troubleshooting.md
- - Changelog: changelog.md
+ - Getting Started: getting-started.md
+ - Reference: cli.md
+ - Changelog: changelog.md
- Contributing:
- contributing/index.md
- Codebase Map: contributing/codebase-map.md
