README Proof

Prove your README still matches your repo before users copy broken commands.

README Proof is a local-first Codex skill and CLI that checks README claims against the actual files, project metadata, and optional quick-start commands in a repository.

It is for maintainers who do not need another README generator. They need a fast way to catch stale links, missing demo files, outdated install commands, and docs drift before publishing.

In one run, README Proof can tell you:

• whether local README links are broken
• whether referenced files and folders actually exist
• whether install instructions match the project metadata
• whether quick-start commands still work when you explicitly choose to run them

The positioning is deliberate: this is a verification tool, not a content generator. It is meant to help maintainers ship trustworthy docs, not longer docs.

Why This Exists

READMEs are often the first thing users trust and the last thing maintainers verify. A stale quick start can cost a project its first contributor, its first issue reporter, or its first serious user.

README Proof takes a verification-first approach:

• Check local Markdown links.
• Check inline file and folder references.
• Check install command claims against project metadata.
• Optionally execute README shell commands after safety screening.
• Produce a small, evidence-based report that Codex or a maintainer can fix.

If you already know tools that lint Markdown or check links, the difference here is scope: README Proof focuses on README reality, not just README syntax.

Who It Is For

• Open-source maintainers preparing a release.
• Developers polishing a GitHub repo before sharing it.
• Codex users who want an agent to verify docs before editing them.
• Teams with README examples that drift as code changes.

Demo

The fixture in examples/broken-python-app intentionally contains stale README claims:

python skill/readme-proof/scripts/readme_proof.py audit \
  --project examples/broken-python-app \
  --format markdown \
  --execute \
  --timeout 10 \
  --fail-level none \
  --portable

Output excerpt:

Result: FAIL
Findings: 4 errors, 3 warnings, 0 info

ERROR RDP004
README documents an editable Python install, but no Python project metadata was found.

ERROR RDP001
README links to a local file that does not exist.
Evidence: CONTRIBUTING.md

Full generated report: examples/output/demo-report.md

Installation

Recommended first run, no installation:

python skill/readme-proof/scripts/readme_proof.py audit --project .

Optional editable CLI install:

python -m pip install -e .
readme-proof audit --project .

If your Python environment waits on package indexes, this project has no third-party runtime dependencies, so local editable install can also be run as:

python -m pip install -e . --no-build-isolation --no-index

No API key, server, browser login, or GitHub token is required.

Quick Start

Audit your current repository without executing README commands:

readme-proof audit --project . --format markdown

Write a portable report:

readme-proof audit --project . --format markdown --portable --output readme-proof-report.md

Execute README shell commands only when you intentionally want that verification:

readme-proof audit --project . --execute --timeout 20

Package installation commands are skipped during --execute unless you pass --allow-install.

Example Input

## Installation

```bash
pip install -e .
```

## Quick Start

```bash
python examples/missing_demo.py
```

[Contributing](CONTRIBUTING.md)

Example Output

[ERROR] RDP004 README.md
  README documents an editable Python install, but no Python project metadata was found.

[ERROR] RDP009 README.md:13
  README command failed when executed.

[ERROR] RDP001 README.md:22
  README links to a local file that does not exist.

Common Use Cases

• Run before publishing a new open-source repo.
• Run before cutting a release.
• Run after renaming files or moving examples.
• Give Codex a concrete report before asking it to fix README drift.
• Add a future CI check that blocks broken quick-start docs.

How It Works

README Proof parses the README and checks:

• Local Markdown links such as [Demo report](examples/output/demo-report.md).
• Inline path references such as examples/output/demo-report.md.
• Common README sections: installation, usage, examples, license.
• Python editable install commands when no Python project metadata exists.
• Node package commands when no Node project manifest exists.
• Shell code fences when --execute is explicitly enabled.

The Codex skill in skill/readme-proof/SKILL.md tells an agent how to run the audit, inspect findings, make minimal fixes, and re-run verification.

Finding details are documented in docs/finding-codes.md.

Project Structure

.
|-- skill/readme-proof/
|   |-- SKILL.md
|   |-- agents/openai.yaml
|   `-- scripts/readme_proof.py
|-- examples/
|   |-- broken-python-app/
|   `-- output/demo-report.md
|-- tests/
|-- docs/
|-- pyproject.toml
`-- README.md

Test

python -m unittest discover -s tests

Roadmap

• Add SARIF output for GitHub code scanning.
• Add CI recipe examples.
• Add npm, pnpm, uv, cargo, and Go fixtures.
• Add a fix-plan mode that groups findings by safest repair.
• Add optional external link checking behind an explicit network flag.
• Package the skill for easier Codex installation.

FAQ

Is this a README generator?

No. It checks whether existing README claims are still true. You can use Codex to fix the findings after the audit.

Does it run arbitrary commands?

Not by default. It only scans README content unless --execute is passed. Even then, it screens known destructive patterns and skips install commands unless --allow-install is set.

Does it require GitHub access?

No. It works on local files and does not need GitHub CLI, tokens, cookies, or login.

Can this be used in CI?

Yes. The CLI exits with code 1 when blocking findings are present. Use --fail-level warning if warnings should fail CI too.

Contributing

See CONTRIBUTING.md. Small, deterministic checks with tests are preferred.

License

MIT. See LICENSE.