# presentation
`index.html` explains loop-claude, in 22 pages, to developers who have never seen an agent loop. It is published as a claude.ai artifact and printed to an A4 landscape PDF.
## Rebuild the PDF
```sh
presentation/build-pdf.py
```
It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker, network access to Google Fonts, and the `playwright-for-claude` image. Build the image once with `~/.claude/bin/run-heavy docker build -t playwright-for-claude ~/code/playwright-for-agents`. When a font fails to load, the build stops without printing: fallback fonts would push pages onto a second sheet.
## Publish the page
The page lives at https://claude.ai/artifact/RJJwgRAke3viuqTYEgu1a9. To update it, ask Claude Code to publish `presentation/index.html` to that URL with its Artifact tool; the tool reads the live version first.
`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.py` wraps it the way the artifact host does.
## Who it is for
People in tech who want to build software factories, work with AI tools more efficiently, and stop fighting their agents. They know git, pull requests and the shell, and don't know anything about agent loops. Write for a tired reader on a Monday morning without coffee: one fact per sentence, each term explained before it is used, and no filler.
## How the pages are built
- **Page 1 engages.** It states the problem, what loop-claude does, what it aims for, who it is for, and three real figures.
- **Pages 2 and 3 share one layout.** Page 2 is the simple chart, page 3 the full one. The section frames, the human boxes, the colours and the return arrows sit in the same places on both. Each big box on page 2 is the group of steps at the same place on page 3, so a reader translates by position. Keep it that way.
- **The full chart shows every piece.** A simpler view may group pieces, never drop them.
- **Three sections:**
- **A · Start, deterministic, no AI:** Rank the plan, Prepare, Pick the work, Pick model.
- **B · Work, the worker:** Build, Review, Gate, Goals check, Readability, Merge. The release review sits on top, and new items flow back into the plan.
- **C · Check, the judge:** its verdicts, and where each one returns.
- **The human stands outside the sections,** since the human is not a step the loop runs. Planning a release is a chunk in B: the worker drafts it, and the human approves it.
- **Zoom pages break one section down, one page each,** with the same step names. They never cut the flow another way.
- **Colours mean roles:** amber the human, blue the worker, violet the judge, teal the reviewers, green the merge.
- **Each page fits one landscape A4 sheet.** After an edit, rebuild the PDF and check the page count: a page that spills shows up as an extra page.
- **Draw arrows after the section backgrounds,** or a section box hides them.
- **Pages 2 to 15 and 17 each carry a "Why: sources …" line,** linking to the numbered rows of the "Why it works this way" pages. Each row is tagged Research, Book, Vendor docs, Benchmark, Own measurement, Experience or Reasoning.
## Where the figures come from
The figures were current on 2026-11-09. Refresh them before presenting again.
- **Finished chunks, 466 since 2026-10-03,** in loop-claude's archive:
```sh
find ~/.claude/loop-claude-transcripts -name '*.outcomes.md' -exec grep -l 'Verdict: finished' {} + | wc -l
```
The first stamp in any outcomes file gives the start date.
- **Projects that finished a chunk, 12.** Each archive folder holding `.outcomes.md` files is a project key. Count the keys with a finished chunk, and count `claude-config` and `home/lilleman/.claude` as one project: the second is this repo's release checkout.
- **Commits, 2,538:** `git log --oneline | wc -l` in this repo.
- **The readability bars:** the latest scoring run in `docs/comprehension-history.md`, the rerun on PR #397.
- **The two plan rows:** items 281 and 286 of `todo.md`.
- **Every other figure:** `docs/decisions.md`, `docs/scoring-and-goals-research.md` and `reviewer-merge-trials/README.md`.
Two sources in row 1 are cited nowhere else in the repo, as reading in support of a fresh context per chunk: Liu et al., "Lost in the Middle", TACL 2024; and Hong et al., "Context Rot", Chroma Research, 2025.
## Checking it
After a larger edit, fact-check the page against the repo again: the setup changes under it.