computerlovetech · kasperjunge · Jun 8, 2026 · Jun 8, 2026
diff --git a/README.md b/README.md
@@ -49,20 +49,18 @@ That's loop engineering in three lines: a prompt, a command for live data, and t
 ## Install
 
 ```bash
-uv tool install ralphify    # recommended
-pipx install ralphify       # or pipx
-pip install ralphify        # or pip (use a virtualenv)
+uv tool install ralphify
 ```
 
-Any of these gives you the `ralph` command.
+This gives you the `ralph` command.
 
 ---
 
-## The five jobs of loop engineering
+## What you do with ralphify
 
-Loop engineering with ralphify is one of these five jobs — write, feed, run, steer, share. That's the whole tool.
+Working with ralphify comes down to a few things — write a ralph, feed it live data, run the loop, steer it while it runs, and share it. That's the whole tool.
 
-### 1. Write a ralph
+### Write a ralph
 
 A ralph is a *directory* containing a `RALPH.md` file — that file is the only requirement, and its shape is defined by the open [ralph loops format](https://ralphloops.io/). Scaffold one:
 
@@ -102,7 +100,7 @@ Refactor the code under {{ args.focus }}. Keep tests green.
 ralph run my-ralph --focus src/auth     # {{ args.focus }} → src/auth
 ```
 
-### 2. Feed it live data
+### Feed it live data
 
 `commands` run before each iteration. Their output replaces `{{ commands.<name> }}` in the prompt, so the agent always sees the current state — test results, coverage, git log, lint output:
 
@@ -123,7 +121,7 @@ If tests are failing, fix them before starting new work.
 
 When the agent breaks a test, the next iteration sees the failure and fixes it. That's the self-healing feedback loop.
 
-### 3. Run the loop
+### Run the loop
 
 ```bash
 ralph run my-ralph           # loops until Ctrl+C
@@ -132,7 +130,7 @@ ralph run my-ralph -n 5      # run 5 iterations then stop
 
 Each iteration: run commands → assemble the prompt → pipe it to the agent → repeat with fresh context.
 
-### 4. Steer it while it runs
+### Steer it while it runs
 
 The prompt body is re-read from disk every iteration. Edit `RALPH.md` while the loop runs and the agent follows your new rules on the next cycle. When it does something dumb, add a sign:
 
@@ -142,7 +140,7 @@ The prompt body is re-read from disk every iteration. Edit `RALPH.md` while the
 - Do NOT delete failing tests — fix the underlying code instead.
 ```
 
-### 5. Share a ralph
+### Share a ralph
 
 This is what the standard format buys you. Because a ralph is just a directory in the open [ralph loops format](https://ralphloops.io/), it's portable — and anyone with ralphify can run it. Commit it to git, push it, and your loop engineering becomes someone else's starting point:
 

diff --git a/docs/404.md b/docs/404.md
@@ -15,7 +15,7 @@ This page doesn't exist — it may have been moved or the URL might have a typo.
 
 **Try one of these instead:**
 
-- [**Home**](index.md) — overview, install, and the five jobs
+- [**Home**](index.md) — overview, install, and what ralphify does
 - [**Getting Started**](getting-started.md) — from install to a running loop
 - [**Reference**](cli.md) — the CLI, RALPH.md format, how the loop works, agents, and troubleshooting
 

diff --git a/docs/cli.md b/docs/cli.md
@@ -6,10 +6,9 @@ keywords: loop engineering, ralph CLI reference, RALPH.md format, ralph run, ral
 
 # Reference
 
-Everything beyond [the five jobs](index.md#the-five-jobs-of-loop-engineering) lives here: the CLI, the `RALPH.md` format, how a loop iteration works under the hood, how to wire up different agents, troubleshooting, and the Python API.
+Everything beyond [the basics](index.md#what-you-do-with-ralphify) lives here: the CLI, the `RALPH.md` format, how a loop iteration works under the hood, how to wire up different agents, troubleshooting, and the Python API.
 
-!!! tldr "TL;DR"
-    **`ralph run <path> -n 5`** runs the loop. **`ralph scaffold <name>`** creates a ralph from a template. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter.
+`ralph run <path> -n 5` runs the loop. `ralph scaffold <name>` creates a ralph from a template. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter.
 
 ---
 
@@ -177,8 +176,7 @@ Your instructions here. Reference args with {{ args.dir }}.
 
 Commands run in order. Output (stdout + stderr) is captured regardless of exit code.
 
-!!! warning "No shell features in commands"
-    Commands are parsed with `shlex.split()` and run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Point the `run` field at a script instead: `run: ./my-script.sh`.
+Commands are parsed with `shlex.split()` and run directly, not through a shell — pipes (`|`), redirections (`>`), and chaining (`&&`) won't work in the `run` field. Point the `run` field at a script instead: `run: ./my-script.sh`.
 
 ### Placeholders
 
@@ -309,11 +307,12 @@ The [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/example
 
 ## 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
+A quick checklist before digging in:
+
+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
 
 ### Setup
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -6,38 +6,15 @@ keywords: loop engineering, loop engineering tutorial, ralph loops tutorial, ins
 
 # Getting Started
 
-!!! tldr "TL;DR"
-    `uv tool install ralphify` → `ralph scaffold my-ralph` → edit the RALPH.md → `ralph run my-ralph -n 1 --log-dir ralph_logs` to test → add a `commands` entry for your test suite → `ralph run my-ralph` to loop. The agent sees fresh command output each iteration and fixes what it breaks.
-
-What you're about to do is loop engineering: you write a loop in the open [ralph loops format](https://ralphloops.io/), and ralphify — the runtime — runs it. This tutorial walks through the five jobs — **write** a ralph, **feed** it live data, **run** the loop, **steer** it while it runs, and **share** it. By the end you'll have a self-healing loop that validates its own work.
-
-## Prerequisites
-
-- **Python 3.11+**
-- **An AI coding agent CLI** — this tutorial uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Install it with `npm install -g @anthropic-ai/claude-code`. Ralphify also works with [other agents](cli.md#using-different-agents).
-- **A project with a test suite** (we'll use this for the feedback loop)
+What you're about to do is loop engineering: you write a loop in the open [ralph loops format](https://ralphloops.io/), and ralphify — the runtime — runs it. This tutorial walks you through writing a ralph, feeding it live data, running the loop, steering it while it runs, and sharing it. By the end you'll have a self-healing loop that validates its own work.
 
 ## Step 1: Install ralphify
 
 ```bash
 uv tool install ralphify
 ```
 
-??? note "Alternative install methods"
-    ```bash
-    pip install ralphify   # pip works too
-    pipx install ralphify  # or pipx
-    ```
-
-Verify it's working:
-
-```bash
-ralph --version
-```
-
-```text
-ralphify 0.3.0
-```
+This gives you the `ralph` command.
 
 ## Step 2: Create a ralph
 
@@ -56,17 +33,16 @@ This creates `my-ralph/RALPH.md` with a ready-to-customize template including an
 
 Or create the file manually as shown below.
 
-!!! tip "Running a shared ralph?"
-    A ralph is just a directory, so a shared one lives in a git repo. Clone it and run it by name:
+### Manual setup
 
-    ```bash
-    git clone https://github.com/owner/repo
-    ralph run my-ralph
-    ```
+A ralph is a *directory* — not a single file. It contains a `RALPH.md` (the loop definition) plus any scripts or files the loop needs. `RALPH.md` is the only requirement; its shape is defined by the open [ralph loops format](https://ralphloops.io/):
 
-### Manual setup
+```text
+my-ralph/
+└── RALPH.md          # the loop definition (required)
+```
 
-A ralph is a *directory* containing a `RALPH.md` file — the file's shape is defined by the open [ralph loops format](https://ralphloops.io/). Create the directory and a `RALPH.md` with the agent field — this is the only required frontmatter:
+Create the directory and a `RALPH.md` with the `agent` field — this is the only required frontmatter:
 
 ```markdown
 ---
@@ -88,27 +64,27 @@ implement it fully, then mark it done.
 - Mark the completed task in TODO.md
 ```
 
-!!! tip "Parameterize a ralph with `args`"
-    Declare `args` in the frontmatter to make one ralph reusable with different inputs. Each name becomes a `{{ args.<name> }}` placeholder filled from the CLI:
+### Parameterize with args
+
+To make one ralph reusable with different inputs, declare `args` in the frontmatter. Each name becomes a `{{ args.<name> }}` placeholder in the prompt body, filled from the CLI at run time:
 
-    ```markdown
-    ---
-    agent: claude -p --dangerously-skip-permissions
-    args:
-      - focus
-    ---
+```markdown
+---
+agent: claude -p --dangerously-skip-permissions
+args:
+  - focus
+---
 
-    Refactor the code under {{ args.focus }}. One module per iteration.
-    ```
+Refactor the code under {{ args.focus }}. One module per iteration.
+```
 
-    ```bash
-    ralph run my-ralph --focus src/auth
-    ```
+Pass the value with a matching flag:
 
-    See the [CLI reference](cli.md#user-arguments) for named vs. positional args.
+```bash
+ralph run my-ralph --focus src/auth     # {{ args.focus }} → src/auth
+```
 
-!!! info "What does `--dangerously-skip-permissions` do?"
-    Claude Code normally asks for your approval before running shell commands, editing files, or making git commits. The `--dangerously-skip-permissions` flag disables these interactive prompts so the agent can work autonomously without waiting for input. The `-p` flag enables non-interactive ("print") mode, which reads the prompt from stdin instead of opening a chat session.
+The same ralph now runs against any path you give it. See the [CLI reference](cli.md#user-arguments) for named vs. positional args.
 
 ## Step 3: Do a test run
 
@@ -132,17 +108,9 @@ ls ralph_logs/
 cat ralph_logs/001_*.log
 ```
 
-!!! tip "Add `ralph_logs/` to `.gitignore`"
-    Log files are useful for debugging but shouldn't be committed:
-
-    ```bash
-    echo "ralph_logs/" >> .gitignore
-    ```
-
-If the agent produced useful work, you're ready to add test feedback.
+Log files are useful for debugging but shouldn't be committed — add `echo "ralph_logs/" >> .gitignore`.
 
-!!! info "Something not working?"
-    If the agent errored or didn't do anything useful, check [Troubleshooting](cli.md#troubleshooting) for common issues — agent hangs, missing commands, and frontmatter mistakes are all covered there.
+If the agent produced useful work, you're ready to add test feedback. If it errored or didn't do anything useful, check [Troubleshooting](cli.md#troubleshooting).
 
 ## Step 4: Add a test command
 
@@ -291,8 +259,7 @@ Read TODO.md and focus only on the API module.
 
 This is the most powerful part of ralph loops — you're steering a running agent with a text file.
 
-!!! warning "Frontmatter changes need a restart"
-    Only the **prompt body** is re-read each iteration. Frontmatter fields (`agent`, `commands`, `args`) are parsed once at startup. If you add a new command or change the agent, stop the loop with `Ctrl+C` and restart it.
+Note that only the **prompt body** is re-read each iteration. Frontmatter fields (`agent`, `commands`, `args`) are parsed once at startup, so if you add a command or change the agent, stop the loop with `Ctrl+C` and restart it.
 
 ## Next steps
 

diff --git a/docs/index.md b/docs/index.md
@@ -69,33 +69,19 @@ Write the loop once in the standard format, and ralphify runs it for as long as
 
 ## Install
 
-=== "uv (recommended)"
-
-    ```bash
-    uv tool install ralphify
-    ```
-
-=== "pipx"
-
-    ```bash
-    pipx install ralphify
-    ```
-
-=== "pip"
-
-    ```bash
-    pip install ralphify
-    ```
+```bash
+uv tool install ralphify
+```
 
 ---
 
-## The five jobs of loop engineering
+## What you do with ralphify
 
-Loop engineering with ralphify is one of these five jobs — write, feed, run, steer, share. That's the whole tool.
+Working with ralphify comes down to a few things — write a ralph, feed it live data, run the loop, steer it while it runs, and share it. That's the whole tool.
 
 <div class="grid cards" markdown>
 
--   :material-file-document-edit-outline:{ .lg .middle } **1. Write a ralph**
+-   :material-file-document-edit-outline:{ .lg .middle } **Write a ralph**
 
     ---
 
@@ -107,15 +93,15 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s
 
     [Getting Started →](getting-started.md)
 
--   :material-database-arrow-down-outline:{ .lg .middle } **2. Feed it live data**
+-   :material-database-arrow-down-outline:{ .lg .middle } **Feed it live data**
 
     ---
 
     `commands` run each iteration; their output fills `{{ commands.<name> }}` in the prompt. The agent always sees current test results, coverage, and git log — a self-healing feedback loop.
 
     [How it works →](cli.md#how-the-loop-works)
 
--   :material-play-circle-outline:{ .lg .middle } **3. Run the loop**
+-   :material-play-circle-outline:{ .lg .middle } **Run the loop**
 
     ---
 
@@ -127,15 +113,15 @@ Loop engineering with ralphify is one of these five jobs — write, feed, run, s
 
     [CLI reference →](cli.md)
 
--   :material-pencil-outline:{ .lg .middle } **4. Steer it while it runs**
+-   :material-pencil-outline:{ .lg .middle } **Steer it while it runs**
 
     ---
 
     The prompt is re-read every iteration. Edit `RALPH.md` mid-run and the agent follows your new rules next cycle. When it does something dumb, add a sign.
 
     [Getting Started →](getting-started.md#step-7-steer-while-it-runs)
 
--   :material-share-variant-outline:{ .lg .middle } **5. Share a ralph**
+-   :material-share-variant-outline:{ .lg .middle } **Share a ralph**
 
     ---