README.md

README.md is the plain-text-plus-Markdown file that lives at the root of a code repository and serves as its front door. Hosting platforms like GitHub and GitLab automatically render it on the repository landing page, so it is the first thing a human — or increasingly an agent — reads when they arrive at a project. There is no formal specification, but decades of convention have made it the de facto standard for telling people what a project is, how to install it, and how to use it.

• Root-level convention - Placed at the repository root and auto-detected by every major Git host, no configuration required.
• Markdown by default - The .md extension signals GitHub-Flavored Markdown, giving you headings, code blocks, badges, and links that render cleanly on the web.
• Project overview and setup - Answers the essentials fast: what this is, how to install it, how to run it, and where to get help.
• The first onboarding surface - For an API repository it sits alongside the OpenAPI and APIs.json artifacts as the human-readable entry point.

In real API operations the README.md is where onboarding actually begins, and it is one of the cheapest signals of a healthy project — a current, well-structured README usually means the rest of the repo is cared for too. As agents start reading repositories directly, a clear README does double duty: it orients the human integrator and gives an LLM the context it needs to understand what the code does and how the API is meant to be consumed. Pairing a good README with machine-readable definitions is how you make a repository legible to both audiences at once.