Write the README

Write or update this project's README.md so a newcomer can go from clone to running in minutes, with every command verified against the actual project config.

Investigate first

• Detect the stack from real files: package.json, pyproject.toml/requirements.txt, go.mod, Cargo.toml, composer.json, Gemfile, Makefile, Dockerfile, docker-compose.yml, CI workflows in .github/.
• Read the manifest's scripts/entrypoints. The quickstart commands MUST come from what exists there (e.g. real package.json scripts keys, Makefile targets), never invented or assumed.
• Find config surface: .env.example, config/, settings files, and every env var the code reads. Grep with the patterns for the languages present: JS/TS process.env., Python os.getenv/os.environ, Go os.Getenv/viper, Ruby ENV[, Rust std::env::var/env::var, PHP getenv(/$_ENV[, plus any dotenv loader in use (dotenv, dotenv-flow, godotenv, python-dotenv) since those imply an .env the README must document.
• Detect package manager from lockfile: package-lock.json→npm, pnpm-lock.yaml→pnpm, yarn.lock→yarn, bun.lockb→bun, poetry.lock→poetry, uv.lock→uv. Use it consistently.
• Detect monorepo/workspaces: npm/yarn/pnpm workspaces field or pnpm-workspace.yaml, turbo.json, nx.json, Cargo [workspace], Poetry path deps, Go multi-module. If present, quickstart commands must be run from the repo root and target a specific package (e.g. pnpm --filter <pkg> build, turbo run build --filter=<pkg>, cargo build -p <pkg>), not bare per-directory commands.
• If a README.md exists, preserve its accurate content, correct what drifted, and keep its heading structure and voice where sound.

Verify the commands work

• For each install/build/run/test command you write, confirm the underlying script or target actually exists in the manifest. Do not document a test step if no test script/framework is present.
• Where safe and cheap, run the install, build, and test commands and fix the README to match real output (correct flags, correct Node/Python version, actual dev-server URL and port). Run the test command especially — its exact invocation and flags are the ones most likely to be wrong if guessed.
• If a command needs a running service (DB, Redis) or secrets, say so explicitly and show the setup step before it.

README structure

1. Project name + one-sentence description of what it is and who it's for. If unclear, infer from code and entrypoints — do not leave a placeholder.
2. Prerequisites: exact runtime versions (read engines, .nvmrc, .python-version, go.mod), package manager, and required services.
3. Quickstart: a copy-paste block runnable in order from a fresh clone, then a second block for tests. Pick the shape from what the project actually is: for a runnable app/service, clone → install → configure env → run (real start command, real port/URL); for a library/SDK with no entrypoint, drop the run step and instead show install-as-a-dependency (published package name from the manifest) plus a minimal import/usage snippet in the project's language; if a Dockerfile/docker-compose.yml is the intended run path, give the container quickstart (docker compose up, or docker build + docker run with the real image/ports) instead of or alongside the native commands.
4. Configuration: a table of env vars (name, required?, default, purpose) sourced from .env.example and the code. Tell them to copy .env.example to .env.
5. Common tasks: lint, format, build, migrate, seed, deploy — only those that exist as scripts/targets, each with the exact command.
6. Project structure: a short annotated tree of the top-level dirs that matter, if the layout isn't obvious.
7. Contributing: branch/PR flow, how to run the test and lint gates locally before pushing, and any commit convention the repo already uses (check for CONTRIBUTING.md, commitlint, husky hooks).
8. License: state the license from the LICENSE/LICENSE.md/COPYING file or the manifest's license field. If none exists, write that the license is unspecified — never invent one.

Rules

• Never invent commands, scripts, env vars, ports, or URLs. Every one traces to a file you read or a command you ran.
• Always use the project's actual package manager and language version; do not default to npm if the lockfile says otherwise.
• Show real, minimal examples over prose. Prefer fenced ```bash blocks for commands, a Markdown table for env vars.
• No badges unless the underlying service is already configured. No "TODO" placeholders — resolve them or omit the section.
• No emoji. Keep it scannable: short sections, imperative headings, no marketing filler.
• After writing, re-read the quickstart top to bottom as a newcomer and confirm nothing is missing between steps.