README First

Treat the repository's main README as its front door. Optimize for a new visitor understanding what the project is, why it matters, and how to reach a first useful result in about 60 seconds. Prefer evidence, reader value, and a short happy path over a complete-looking template.

Choose the mode

• Create when the repository has no useful main README.
• Improve when a README exists but needs correction, simplification, reorganization, or stronger onboarding.
• Review when the user wants an audit or recommendations without edits.

In every mode, target the repository's main user-facing README (normally the root README.md). Do not silently turn the task into general Markdown, architecture, API, contributor, branding, or project-marketing work.

Operate in this order