docs: point agents at the files humans already read

AGENTS.md

@@ -0,0 +1,17 @@
+# Working in this repo
+
+These are **teaching examples**. Each one exists to make a single mechanism legible, so
+it is read at least as often as it is run — clarity beats cleverness, and the smallest
+change that makes the point is the right one.
+
+Two files hold everything you need, and neither is loaded automatically, so read them
+rather than inferring the conventions from the code:
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — what belongs here and what doesn't, commit
+  format, the formatting hooks, and the rule that every example must run **offchain end
+  to end** before it ships.
+- [README.md](./README.md) — what the examples are, and the axis table that decides
+  whether a new one belongs at all. Most proposed examples don't.
+
+This file deliberately holds no rules of its own. If something is worth knowing, it goes
+in one of the two above, where human contributors see it too.

CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](./AGENTS.md).

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for considering contributing to the live runner example apps. These ar
 
 ## Scope: a minimal, curated set
 
-This repo covers each value of the example axes (registration, mode, transport, pricing) once — it is not a collection of apps built on the runner.
+This repo covers each value of the [axis table](./README.md#examples) once — it is not a collection of apps built on the runner. The table is the source of truth for what counts as a gap.
 
 - **In scope** — bug fixes, doc improvements, and new examples that fill a gap in the README's axis table. Open an issue first to agree on the gap.
 - **Out of scope** — new app examples that don't add axis coverage. Publish those in your own repo (name it `<app>-livepeer-runner`, add the `livepeer-runner` GitHub topic, mention Livepeer in the description) and open a PR that adds one row to the README's [External examples](./README.md#external-examples) table.
@@ -38,6 +38,11 @@ uvx pre-commit run --all-files
 
 Local hooks are optional — CI runs the same checks either way.
 
+Two conventions the tooling can't enforce:
+
+- **Keep the `# Livepeer:` markers accurate.** They number the SDK calls in each `runner.py` / `client.py` in the order they happen, and the README sends readers to them as the way to see an example's whole Livepeer surface. A change that adds or removes a call should renumber them and update the file's docstring.
+- **Never commit media or model weights.** Each example gitignores them (`*.wav`, `*.mp4`, model directories); sample clips are generated by the commands in its README. Check `git status` before `git add -A`.
+
 ### Pull Requests
 
 - Keep PRs **small and focused** — one example or one concern per PR.

README.md

@@ -90,7 +90,7 @@ The client side depends on the runner's mode:
 - **Single-shot** — **discover → call**: find the app via `runner_selector`, then one `call_runner`. The orchestrator reserves a session for the call and releases it when the response returns; on the paid path `call_runner` answers the 402 payment challenge inline. (`hello-world`, `tiles`, `api-proxy`, `vllm`, `ollama`)
 - **Persistent** — **discover → reserve → call → release**: reserve a session (`reserve_session`), call it — `call_runner`, streamed frames, or a WebSocket, depending on transport — then release it (`stop_runner_session`), which settles payment on-chain. (`echo`, `realtime-transcription`)
 
-Each example's `client.py` shows its exact calls — grep `# Livepeer:` to find them.
+Each example's `client.py` shows its exact calls, numbered in the order they happen — grep `# Livepeer:` to find them.
 
 ## Not covered here