README Authoring

Write READMEs that answer the reader’s next question — grounded in what the repo actually does.

Principles

Audience first — OSS users ≠ new hires ≠ future-you in a config folder.
Evidence over invention — claims, commands, flags, and APIs must match files or the user’s stated surface. Do not invent short aliases (e.g. -y) unless evidenced.
Shortest path to working — one happy-path command early; flags and alternate installs below.
Quick Start first viewport — prefer ## Quick Start; interactive/zero-flag path first; Non-interactive second (see references/quick-start-patterns.md for npm/CLI packages).
Link, don’t duplicate — deeper docs stay linked.
Human prose — direct, active voice; no promotional or inflated AI tone.