docs: position ralphify as the loop engineering runtime

README.md

@@ -11,6 +11,8 @@
 
 **Ralphify runs ralph loops.**
 
+Designing autonomous agent loops — *loop engineering* — is becoming how people get real work out of coding agents. The [ralph loops format](https://ralphloops.io/) is how you write one. Ralphify is how you run it.
+
 A **ralph loop** is a portable directory that defines an autonomous agent loop — a prompt, the commands to run between iterations, and any files the agent needs. It's an open format ([ralphloops.io](https://ralphloops.io/)): one required file, `RALPH.md`. Ralphify is the CLI that runs it.
 
 ```
@@ -138,20 +140,20 @@ 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 and install ralphs
+### 5. Share a ralph
 
-A ralph is just a directory in the [ralph loops format](https://ralphloops.io/), so it's portable — version it in git, share it, install it. Use [agr](https://github.com/computerlovetech/agr) to install one from GitHub:
+A ralph is just a directory in the [ralph loops format](https://ralphloops.io/), so it's portable. Commit it to git, push it, and anyone can clone the repo and run it by name:
 
 ```bash
-agr add owner/repo/grow-coverage   # install a ralph
-ralph run grow-coverage            # run it by name
+git clone https://github.com/owner/repo   # grab a shared ralph
+ralph run grow-coverage                   # run it by name
 ```
 
 ---
 
-## Why loops
+## Why loop engineering works
 
-A single agent run can fix a bug or write 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.
+Instead of prompting an agent turn by turn, you write the loop once and let it drive the agent for you. A single agent run can fix a bug or write 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.
 
 - **Fresh context every iteration.** No context-window bloat. The agent starts clean and reads the current state of the codebase.
 - **Commands as feedback.** Live data feeds back into the prompt each loop, so the agent self-corrects.

docs/agents.md

@@ -1,7 +1,7 @@
 ---
 title: How to Run Claude Code, Aider, or Codex in an Autonomous Loop
 description: Set up Claude Code, Aider, Codex CLI, or any AI coding agent to run autonomously in a loop with ralphify. Copy-pasteable configs, wrapper scripts, and a comparison table.
-keywords: run claude code in loop, aider autonomous mode, codex cli automation, AI coding agent loop, autonomous claude code, aider loop setup, run AI agent automatically, pipe prompt to coding agent, claude code non-interactive, aider no-interactive mode, codex exec stdin, automate AI coding agent
+keywords: loop engineering, run claude code in loop, aider autonomous mode, codex cli automation, AI coding agent loop, autonomous claude code, aider loop setup, run AI agent automatically, pipe prompt to coding agent, claude code non-interactive, aider no-interactive mode, codex exec stdin, automate AI coding agent
 ---
 
 # Using with Different Agents

docs/cookbook.md

@@ -1,7 +1,7 @@
 ---
 title: Ralph Loop Recipes
 description: Copy-pasteable ralph loop setups for autonomous ML research, test coverage, code migration, security scanning, deep research, documentation, bug fixing, and codebase improvement.
-keywords: ralphify cookbook, autonomous coding recipes, RALPH.md examples, documentation loop, bug fixing loop, codebase improvement, deep research agent, code migration loop, security scanning agent, test coverage automation, autoresearch, autonomous ML research
+keywords: loop engineering examples, ralphify cookbook, autonomous coding recipes, RALPH.md examples, documentation loop, bug fixing loop, codebase improvement, deep research agent, code migration loop, security scanning agent, test coverage automation, autoresearch, autonomous ML research
 ---
 
 # Cookbook

docs/getting-started.md

@@ -1,15 +1,15 @@
 ---
 title: Getting Started with Ralph Loops — Ralphify Tutorial
 description: Install ralphify, write your first ralph loop, feed it live data with commands, run it, and steer it while it runs — step-by-step in 10 minutes.
-keywords: ralph loops tutorial, install ralphify, write a ralph, ralphloops.io, self-healing loop, run agent loop, ralph loop setup, RALPH.md
+keywords: loop engineering, loop engineering tutorial, ralph loops tutorial, install ralphify, write a ralph, ralphloops.io, self-healing loop, run agent loop, ralph loop setup, RALPH.md
 ---
 
 # 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.
 
-This tutorial walks through the five things you do with ralphify — **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. Ralphify implements the open [ralph loops format](https://ralphloops.io/).
+What you're about to build is a loop: you write it in the [ralph loops format](https://ralphloops.io/), and ralphify runs it. This tutorial walks through the five things you do with ralphify — **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
 
@@ -56,15 +56,14 @@ This creates `my-ralph/RALPH.md` with a ready-to-customize template including an
 
 Or create the file manually as shown below.
 
-!!! tip "Installing an existing ralph?"
-    Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub:
+!!! 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:
 
     ```bash
-    agr add owner/repo
+    git clone https://github.com/owner/repo
+    ralph run my-ralph
     ```
 
-    This installs to `.agents/ralphs/` so you can run it by name with `ralph run <name>`.
-
 ### Manual setup
 
 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:

docs/how-it-works.md

@@ -1,15 +1,15 @@
 ---
-title: How Autonomous AI Coding Loops Work — The Ralph Loop Lifecycle
-description: Step-by-step breakdown of what happens inside each ralph loop iteration — command execution, prompt assembly, agent piping, and the self-healing feedback cycle that auto-fixes broken code.
-keywords: autonomous coding loop lifecycle, how AI coding agents work, self-healing code loop, AI agent feedback cycle, prompt assembly pipeline, ralph loop architecture, agentic coding workflow
+title: How Loop Engineering Works — The Ralph Loop Lifecycle
+description: Step-by-step breakdown of loop engineering — what happens inside each ralph loop iteration — command execution, prompt assembly, agent piping, and the self-healing feedback cycle that auto-fixes broken code.
+keywords: loop engineering, how loop engineering works, autonomous coding loop lifecycle, how AI coding agents work, self-healing code loop, AI agent feedback cycle, prompt assembly pipeline, ralph loop architecture, agentic coding workflow
 ---
 
 # How the ralph loop works
 
 !!! tldr "TL;DR"
     Each iteration: re-read `RALPH.md` from disk → run commands → replace `{{ placeholders }}` with output → pipe the assembled prompt to the agent → agent works and exits → repeat. The prompt body is re-read every iteration (so you can edit it live), but frontmatter is parsed once at startup. Failed commands still capture output — that's what makes the loop self-healing.
 
-What happens inside each iteration of an autonomous coding loop? This page breaks down the lifecycle — from command execution to prompt assembly to agent piping — so you can write better prompts, debug unexpected behavior, and understand the self-healing feedback cycle.
+Writing a loop is becoming a discipline of its own — *loop engineering*. This page shows what one iteration of a ralph loop actually does: the format you write, and the runtime that runs it. It breaks down the lifecycle — from command execution to prompt assembly to agent piping — so you can write better prompts, debug unexpected behavior, and understand the self-healing feedback cycle.
 
 ## The six steps of each iteration
 

docs/index.md

@@ -1,7 +1,7 @@
 ---
 title: Ralphify — the runtime for ralph loops
-description: Ralphify runs ralph loops — an open format for autonomous agent loops (ralphloops.io). A ralph loop is a directory with a RALPH.md file. Ralphify runs it.
-keywords: ralphify, ralph loops, ralph loops format, RALPH.md, ralphloops.io, agent loop runtime, autonomous agent loop
+description: Ralphify runs ralph loops — the open format for loop engineering and autonomous agent loops (ralphloops.io). The ralph loops format is how you write a loop; ralphify is the runtime that runs it.
+keywords: ralphify, loop engineering, ralph loops, ralph loops format, RALPH.md, ralphloops.io, agent loop runtime, autonomous agent loop
 hide:
   - toc
 ---
@@ -14,6 +14,8 @@ hide:
 <strong>Ralphify runs ralph loops.</strong>
 </p>
 
+Designing autonomous agent loops — *loop engineering* — is becoming how people get real work out of coding agents. The [ralph loops format](https://ralphloops.io/) is how you write one. Ralphify is how you run it.
+
 A **ralph loop** is a portable directory that defines an autonomous agent loop — a prompt, the commands to run between iterations, and any files the agent needs. It's an open format ([ralphloops.io](https://ralphloops.io/)): a directory whose one required file is `RALPH.md`. **Ralphify** is the CLI that runs it.
 
 ```
@@ -118,14 +120,15 @@ Everything in ralphify is one of these five jobs. That's the whole tool.
 
     [Getting Started →](getting-started.md#step-7-steer-while-it-runs)
 
--   :material-share-variant-outline:{ .lg .middle } **5. Share and install ralphs**
+-   :material-share-variant-outline:{ .lg .middle } **5. Share a ralph**
 
     ---
 
-    A ralph is a portable directory in the [ralph loops format](https://ralphloops.io/). Version it in git, share it, install it from GitHub with [agr](https://github.com/computerlovetech/agr).
+    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.
 
     ```bash
-    agr add owner/repo/my-ralph
+    git clone https://github.com/owner/repo
+    ralph run my-ralph
     ```
 
 </div>

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: Ralphify
-site_description: A minimal CLI harness for autonomous AI coding loops — run commands, assemble a prompt, pipe it to an agent, and repeat with fresh context each iteration.
+site_description: The runtime for loop engineering — write a loop in the ralph loops format, and ralphify runs it. Run commands, assemble a prompt, pipe it to an agent, and repeat with fresh context each iteration.
 site_url: https://ralphify.co/docs/
 repo_url: https://github.com/computerlovetech/ralphify
 repo_name: computerlovetech/ralphify

website/index.html

@@ -3,16 +3,16 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Ralphify — Stop stressing. Ralph is always running.</title>
-  <meta name="description" content="Stop stressing over not having an agent running. Ralphify puts your AI coding agent in an autonomous loop. Write a prompt. Walk away. Wake up to commits.">
-  <meta name="keywords" content="AI coding agent, autonomous coding loop, CLI agent harness, AI agent loop, coding automation, ralphify, ralph loop, agentic engineering, AI pair programming, while true loop, agent FOMO">
+  <title>Ralphify — The Loop Engineering Runtime for AI Coding Agents</title>
+  <meta name="description" content="Ralphify is the runtime for loop engineering — write a loop in the ralph loops format and run your AI coding agent autonomously. Write a prompt. Walk away. Wake up to commits.">
+  <meta name="keywords" content="loop engineering, loop engineering framework, ralph loops, ralph loops format, AI coding agent, autonomous coding loop, run claude code in a loop, agent loop runtime, CLI agent harness, AI agent loop, ralphify, ralph loop, RALPH.md, agentic engineering, autonomous AI agent overnight">
   <meta name="author" content="Computerlove Technologies">
   <meta name="robots" content="index, follow">
 
   <!-- Open Graph -->
   <meta property="og:type" content="website">
-  <meta property="og:title" content="Ralphify — Stop stressing. Ralph is always running.">
-  <meta property="og:description" content="Stop stressing over not having an agent running. Ralphify puts your AI coding agent in an autonomous loop. Write a prompt. Walk away. Ralph keeps shipping.">
+  <meta property="og:title" content="Ralphify — The Loop Engineering Runtime for AI Coding Agents">
+  <meta property="og:description" content="The runtime for loop engineering. Write a loop in the ralph loops format and run your AI coding agent autonomously. Write a prompt. Walk away. Ralph keeps shipping.">
   <meta property="og:url" content="https://ralphify.co/">
   <meta property="og:site_name" content="Ralphify">
   <meta property="og:image" content="https://ralphify.co/docs/assets/cli-banner.png">
@@ -23,8 +23,8 @@
 
   <!-- Twitter Card -->
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Ralphify — Stop stressing. Ralph is always running.">
-  <meta name="twitter:description" content="Stop stressing over not having an agent running. Ralphify puts your AI coding agent in an autonomous loop. Write a prompt. Walk away. Ralph keeps shipping.">
+  <meta name="twitter:title" content="Ralphify — The Loop Engineering Runtime for AI Coding Agents">
+  <meta name="twitter:description" content="The runtime for loop engineering. Write a loop in the ralph loops format and run your AI coding agent autonomously. Write a prompt. Walk away. Ralph keeps shipping.">
   <meta name="twitter:image" content="https://ralphify.co/docs/assets/cli-banner.png">
   <meta name="twitter:image:alt" content="Ralphify CLI showing an autonomous AI coding loop with three iterations">
 
@@ -212,7 +212,7 @@
       <div class="hero-content">
         <div class="hero-badge">
           <span class="status-dot"></span>
-          Open-source &middot; Agent-agnostic &middot; CLI-native
+          Loop engineering &middot; Open-source &middot; Agent-agnostic
         </div>
 
         <h1 class="hero-headline">
@@ -225,7 +225,7 @@ <h1 class="hero-headline">
         </h1>
 
         <p class="hero-sub">
-          Put your AI coding agent in a <code>while True</code> loop.<br>
+          Ralphify is the runtime for <strong>loop engineering</strong> — write a loop, run your AI coding agent autonomously.<br>
           Write a prompt. Walk away. Wake up to commits.
         </p>
 
@@ -443,7 +443,7 @@ <h2 id="ralph-heading" class="section-heading left">A ralph is just<br>a Markdow
     <section class="why" aria-labelledby="why-heading">
       <div class="section-inner">
         <p class="section-eyebrow fade-up">Why loops beat single runs</p>
-        <h2 id="why-heading" class="section-heading fade-up">Single runs decay.<br>Loops compound.</h2>
+        <h2 id="why-heading" class="section-heading fade-up">Why loop engineering wins:<br>single runs decay, loops compound.</h2>
         <p class="section-sub fade-up">A single agent conversation fills up, slows down, and loses the plot. Loops don't.</p>
         <div class="card-grid fade-up">
           <div class="card">
@@ -550,6 +550,10 @@ <h2 id="install-heading" class="section-heading fade-up">Get Ralph running</h2>
       <div class="section-inner section-inner-narrow">
         <h2 id="faq-heading" class="section-heading fade-up">FAQ</h2>
         <div class="faq-list fade-up">
+          <details class="faq-item">
+            <summary>What is loop engineering?</summary>
+            <p>Loop engineering is the practice of designing autonomous loops that prompt your AI coding agent for you, instead of prompting it by hand turn by turn. You write the loop once &mdash; the task, the feedback commands, the stopping rules &mdash; and it drives the agent through iteration after iteration. Ralphify is the runtime for loop engineering: you write the loop in the open <a href="https://ralphloops.io/">ralph loops format</a>, and Ralphify runs it.</p>
+          </details>
           <details class="faq-item">
             <summary>What AI coding agents work with Ralphify?</summary>
             <p>Any agent that accepts prompts via stdin or CLI arguments &mdash; Claude Code, Aider, Codex CLI, and others. Ralphify is agent-agnostic by design. See <a href="docs/agents/">supported agents</a>.</p>