readme-forgelisted

# readme-forge A README is the single highest-leverage file in a repo: it's what a visitor reads before deciding whether to try, star, or contribute. Most READMEs fail not because they're badly written but because they're *ungrounded* — written from a vague idea of the project instead of what the code actually does. Your job is to write one that's accurate because you read the source, and compelling because you led with why anyone should care. ## The method: read first, write second Never draft a README from the project name and a guess. Investigate, then write. ### 1. Learn what the project actually is - **Entry points:** `main`, `index`, `cli`, `app`, `server` — what runs when you run it? - **Manifest:** `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` — name, description, scripts, dependencies, binaries, version. - **How it's run and built:** the real commands from scripts, `Makefile`, `Dockerfile`, CI workflows. Use *these*, not invented ones — a README whose install command doesn't work is worse than no README. - **Config & env:** `.env.example`, config files — what does a user have to set up? - **Existing docs:** an old README, `docs/`, code comments, tests (tests reveal intended usage better than anything). If something's ambiguous (license, the one-line purpose, the target audience), ask the user one or two sharp questions rather than inventing an answer. ### 2. Find the hook Before writing a word of structure, answer: **what does this do, for whom,