.

Author: Kasper Junge

.ralph/checks/mkdocs-build/CHECK.md

@@ -0,0 +1,5 @@
+---
+command: uv run mkdocs build --strict
+timeout: 60
+enabled: true
+---

PROMPT.md

@@ -1,12 +1,79 @@
 # Prompt
 
-You are an autonomous coding agent running in a loop. Each iteration
+You are an autonomous documentation agent running in a loop. Each iteration
 starts with a fresh context. Your progress lives in the code and git.
 
-- Implement one thing per iteration
+## Rules
+- Do one meaningful documentation improvement per iteration
 - Search before creating anything new
-- No placeholder code — full implementations only
-- Run tests and fix failures before committing
-- Commit with a descriptive message
+- No placeholder content — full, accurate, useful writing only
+- Verify any code examples actually run before committing
+- Commit with a descriptive message like `docs: explain X for users who want to Y` and push
 
-Improve the codebase without adding or removing any features, but keeping all funcitonality the same.
+---
+
+## Your north star: jobs to be done
+
+Before writing anything, ask: **who is trying to do what, and what's blocking them?**
+
+Every piece of documentation should serve a specific user goal — getting started, understanding how to extend the project, debugging a failure, or evaluating fit. If you can't identify which job a doc page serves, rewrite it until you can.
+
+---
+
+## What to work on (priority order)
+
+### 1. Find the biggest gap first
+Read the codebase and existing docs, then identify:
+- What can this project do that isn't documented?
+- What would a new user try first, and would they succeed?
+- What does the code do differently from what the docs claim?
+
+Pick the most important gap and fix it this iteration.
+
+### 2. README.md
+The README is the front door — optimise it for someone who just landed on the repo and is deciding whether to install it.
+- Lead with what it does and who it's for, not how it works
+- The fastest path from "never heard of this" to "it's running and I got value" should be obvious
+- Every install step must work on a clean machine
+- Cut anything that doesn't help someone get started or decide if it's right for them
+
+### 3. MkDocs site (`/docs`)
+- Every public-facing feature should have a page
+- Write from the user's perspective ("How to X") not the code's ("The X module")
+- Include working, copy-pasteable examples for any described behavior
+- Navigation should reflect a user's journey, not the repo's folder structure
+- Research how other make great docs for dev tools and take inspiration from that.
+
+### 4. Inline code documentation
+- Add or improve docstrings on any public function or class missing them
+- Focus on **why** and **when to use**, not just **what** — the code already shows what
+- Document non-obvious behavior, edge cases, and gotchas
+
+### 5. Agent docs (`/agent_docs`)
+- Write for an AI coding agent trying to work in this project
+- Explain where things are and why they're structured that way
+- Call out traps: "if you change X you must also update Y"
+- Keep a `CODEBASE_MAP.md` current as a fast orientation guide
+
+---
+
+## Verify before committing
+- All code examples must run and produce the documented output
+- Run `mkdocs build` — zero warnings is the target
+- Confirm any cross-links between pages resolve
+- Confirm behavior docs match the actual code
+
+---
+
+## What good looks like
+
+A user who has never seen this project should be able to:
+1. Understand what it does and whether it fits their need — in 60 seconds
+2. Get it running with their own data — without asking anyone
+3. Know where to look when something goes wrong
+4. Know how to extend it for their specific use case
+
+If the docs don't achieve all four, there's more to do.
+
+
+Also the MkDocs should be hosted on Github Pages

ralph_logs/001_20260311-063814.log

@@ -0,0 +1,13 @@
+Done. Here's what I did this iteration:
+
+**Gap identified:** The MkDocs site was entirely boilerplate (default template), and the primitives system (checks, contexts, instructions) — the project's most powerful feature — was completely undocumented.
+
+**What I created:**
+
+- **`docs/index.md`** — proper landing page with install, quickstart, and the technique explanation, linking to deeper docs
+- **`docs/primitives.md`** — comprehensive guide to checks, contexts, and instructions with creation commands, frontmatter reference tables, placeholder syntax, and examples of how each integrates with the prompt
+- **`docs/cli.md`** — reference for all commands (`init`, `run`, `status`, `new`) with options tables
+- **`mkdocs.yml`** — proper site config with nav structure
+- **`.gitignore`** — added `site/` to ignore MkDocs build output
+
+Build passes clean with `mkdocs build --strict` (zero warnings).

ralph_logs/001_20260311-073449.log

@@ -0,0 +1,6 @@
+Done. Added docstrings to all 10 source modules and 5 dataclasses:
+
+- **Module docstrings**: Each module now explains its purpose, what it does, and key behaviors (e.g., `_runner.py` notes that commands run from the project root, `_frontmatter.py` documents HTML comment stripping)
+- **Dataclass docstrings**: `Check`, `CheckResult`, `Context`, `ContextResult`, and `Instruction` now document their fields, defaults, and non-obvious behaviors (e.g., exit code -1 for timeouts, empty instructions being silently excluded)
+
+All 197 tests pass, MkDocs builds clean.

ralph_logs/002_20260311-064011.log

@@ -0,0 +1,9 @@
+Done. Created `.github/workflows/docs.yml` — a GitHub Actions workflow that:
+
+- **Triggers** on pushes to `main` that change `docs/` or `mkdocs.yml`, plus manual dispatch
+- **Builds** the MkDocs site with `--strict` (zero warnings required)
+- **Deploys** to GitHub Pages using the modern `actions/deploy-pages@v4` approach with OIDC permissions
+
+**One manual step required:** In the GitHub repo settings, go to **Settings > Pages** and set the source to **"GitHub Actions"** (not "Deploy from a branch"). This is a one-time setting that can't be automated via a workflow file.
+
+After pushing and enabling that setting, the docs will be live at `https://computerlovetech.github.io/ralphify/` and auto-update on every docs change to `main`.

ralph_logs/002_20260311-073828.log

@@ -0,0 +1,7 @@
+Done. The README now showcases the three primitives with concrete examples:
+
+- **Checks** — shows the self-healing feedback loop with a visual diagram of how iterations self-correct
+- **Contexts** — shows dynamic data injection with a git-log example
+- **Instructions** — shows reusable rules with toggle-on/off
+
+This was the biggest gap: someone landing on the repo would previously think ralphify is just a `while True` wrapper. Now the killer feature (self-healing checks) is visible from the front door, answering "why use this instead of a bash loop?"

ralph_logs/003_20260311-064341.log

@@ -0,0 +1,9 @@
+Done. Committed `5dbde75` — added a **"Writing Your Prompt" guide** (`docs/prompts.md`) to the MkDocs site.
+
+**What was the gap:** The prompt is the single most important file in a ralphify project, yet the docs only had a few bullet points in the README about customizing it. A new user would install ralphify, see `PROMPT.md`, and have no idea how to write one that actually produces useful work.
+
+**What was added:**
+- New `docs/prompts.md` covering: how prompts work in the loop, anatomy of a good prompt (role/task/constraints/process), placeholder system, check feedback loop, three ready-to-use prompt patterns (feature dev, bug fixing, docs), and practical tips
+- Linked from the index page's "Next steps" section
+- Added to MkDocs nav between Home and Primitives
+- `mkdocs build --strict` passes with zero warnings

ralph_logs/003_20260311-074406.log

@@ -0,0 +1,13 @@
+Done. Here's what I did this iteration:
+
+**Gap identified:** The how-it-works page explained context resolution, instruction resolution, and check failure injection in separate sections, but never showed a complete assembled prompt. A user trying to debug or understand what their agent actually receives had to mentally combine three separate explanations.
+
+**Changes made:**
+
+1. **`docs/how-it-works.md`** — Added a "Full example: what the agent receives" section showing the complete transformation: raw PROMPT.md with placeholders + context file + instruction file (with HTML comment) + previous check failure → final assembled prompt. This makes the system click at a glance.
+
+2. **`docs/primitives.md`** — Documented two previously undocumented behaviors:
+   - HTML comments in primitive files are stripped before injection (users can leave internal notes that won't leak to the agent)
+   - Scripts and commands run with the project root as working directory (not the primitive's directory)
+
+Build passes with zero warnings. Push triggers GitHub Pages deployment.

ralph_logs/004_20260311-064653.log

@@ -0,0 +1,13 @@
+Done. Here's what this iteration accomplished:
+
+**Upgraded the MkDocs docs site from the bare default theme to Material for MkDocs.** The docs site now has:
+
+- **Dark/light mode toggle** — respects system preference, user can switch
+- **Code copy buttons** — one-click copy on all code blocks
+- **Syntax highlighting** — proper highlighting for bash, toml, markdown, etc.
+- **Search with suggestions and highlighting** — fast client-side search
+- **Navigation improvements** — instant page loads, back-to-top button, footer navigation, sticky TOC
+- **GitHub repo link** — visible in the header
+- **Admonitions and details** — markdown extensions ready for tip/warning/note boxes in future docs
+
+The build passes with `mkdocs build --strict` (zero warnings), and the GitHub Actions workflow needs no changes since it already runs `uv sync --group dev`.

ralph_logs/004_20260311-075153.log

@@ -0,0 +1,11 @@
+The docs site is live at **https://computerlovetech.github.io/ralphify/**.
+
+Here's what I did this iteration:
+
+1. **Enabled GitHub Pages** — The workflow existed but Pages was never activated in the repo settings. Previous workflow runs were failing with "Not Found" errors. I enabled Pages via the GitHub API with `build_type=workflow`.
+
+2. **Added `--dangerously-skip-permissions` explanation** in `docs/getting-started.md` — New users see this flag in every config example but had no explanation of what it does or why it's safe. Added an info box explaining both `-p` and `--dangerously-skip-permissions`, and why checks serve as the safety guardrail.
+
+3. **Fixed project detection table order** in `docs/how-it-works.md` — The table listed `pyproject.toml` first but the code checks `package.json` first. Fixed the order and added a note about first-match-wins behavior.
+
+4. **Deployed** — Pushed to main, the docs workflow ran successfully, and the site is now live.