The README standard

GitHub scores every public repository against a community profile: a list of standard files, and a health percentage counting how many are present. It answers one narrow question, which is whether the files exist. It says nothing about whether the README is any use.

The checklist, and the current score

Numbers below come from the community profile of the eleven repositories under github.com/nerln, synced on 2026-08-04.

Item	Repositories with it
Description	11 of 11
README	11 of 11
Licence	11 of 11
Contributing guide	2 of 11
Code of conduct	1 of 11
Pull request template	1 of 11
Issue templates	0 of 11

One repository scores 100: molo. claude-codex-bridge scores 71. The other nine sit at 42, which is what you get with a README, a licence and a description and nothing else. That gap is the honest state of things, and issue templates at zero is the next thing to fix.

The rest of the metadata: eight repositories are MIT, three are GPL-3.0 (plancia, rada, varo). Ten of eleven carry topics; rada has none. Seven declare a homepage. Every one of them is at zero stars.

What the score cannot see

A repository can pass every check and still leave a reader guessing. The questions a README has to answer are different ones: what does this do, what does it refuse to do, can I run it in the next five minutes, and is there a number I can verify myself.

The house rule

Every repository says what it does not do, under a heading of its own. When a claim can be checked, the check ships with it.

That heading is in the real files. molo has “What it will not do” and states that there is no circumvention code in the repository, no CDM and no keys, so an encrypted stream fails because the code cannot do it. rada has “What it does not do” and lists that it never kills a running job, that work which never becomes a Bash command is invisible to it, and that it has only been run on macOS on Apple Silicon. argano uses the same heading. varo says it has no servers, no databases and no build system of its own, and that its auditor reads and never writes.

Limits get a second heading when they are about what has not been done yet. molo says its builds are unsigned, and that the Windows executable and the Android APK compile in CI with nobody having run them on real hardware. claude-codex-bridge keeps a “Known limitations” section for the same reason.

The checkable claims ship as tests, with the count in the README: 29 checks in varo, 70 in rada, 96 in plancia. rada goes further and publishes a result that is unflattering: of six prompt injection attacks put through its judge, one worked, and the README says so along with why the bound on damage makes it tolerable.

The structure these repositories use

Read molo, rada and varo side by side and the same order comes out.

1. Name, then one line in the words somebody would use to ask for the tool.
2. Why this exists. The concrete situation that produced it, and the projects that already solve part of the problem. molo names five and tells Android-only users to install Seal instead.
3. What it does. One capability per paragraph, described as behaviour.
4. What it does not do. Refusals and hard limits, separated from each other.
5. Install. Copy-pasteable, with the unbundled dependencies named.
6. Using it. The few commands that cover most of the work.
7. How it works. File layout, one line each, plus the decisions a reader would otherwise reverse engineer.
8. Known limitations. What has not been run, signed, or tested anywhere but one machine.
9. Tests. The command, the count, and what they cover.
10. Licence.

Template

# name

One line saying what it is.

## Why this exists

The situation that produced it. Name the projects that already solve
part of the problem, and say plainly when one of them is the better
choice for a given reader.

## What it does

One capability per paragraph. Describe behaviour.

## What it does not do

The refusals and the limits. Separate the things that are choices
from the things the code cannot do at all.

## Install

Commands that can be pasted. Name the dependencies that are not
bundled and say what happens without them.

## Using it

The three or four commands that cover most of the work.

## How it works

The file layout, one line each, and the decisions a reader would
otherwise have to reverse engineer.

## Known limitations

What has not been run, what has not been signed, what has been tested
on one machine only.

## Tests

The command, the count, and what they cover. If a test exists because
it caught a real defect, say so.

## Licence