From 40439a8f9eedb281715348d192bc87563b682e12 Mon Sep 17 00:00:00 2001 From: Rick Staa Date: Sun, 9 Aug 2026 08:48:18 +0200 Subject: [PATCH] docs: point agents at the files humans already read Nothing auto-loads README or CONTRIBUTING, so an agent works from the code and misses conventions that are written down. AGENTS.md is a pointer to both, and CLAUDE.md points at AGENTS.md so Claude Code's auto-load reaches the same file other tools read. It holds no rules of its own, which is what stops it becoming a second README that drifts. The two conventions the tooling cannot enforce move into CONTRIBUTING, where human contributors see them too: keeping the `# Livepeer:` markers accurate, and never committing media or weights. CONTRIBUTING also stops restating the axis list and links the table instead. It already disagreed with the README, which had gained a fifth axis, and a rule stated in two places is a rule that will disagree again. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 17 +++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 7 ++++++- README.md | 2 +- 4 files changed, 25 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4cf0eaa --- /dev/null +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fded5dc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See [AGENTS.md](./AGENTS.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7bdbe4a..382a65a 100644 --- a/CONTRIBUTING.md +++ b/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 `-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. diff --git a/README.md b/README.md index c80d06f..159705e 100644 --- a/README.md +++ b/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