Skip to main content
A README describes one repo. How the repos connect lives here, not duplicated across fifty READMEs that drift.
A repo’s README.md is its front door: install and usage for that repo alone. The ecosystem story, which repo feeds which, what depends on what, lives on this site, maintained in one place. A README that re-explains its neighbors copies that story dozens of times, and every copy rots the moment a sibling changes. So the rule is simple: READMEs are standalone; one footer link points back here. This formalizes what the introduction already says: per-repo READMEs cover install; this site covers how it all fits together.

​
Required shape

Use these sections, in this order. Omit one only if it genuinely doesn’t apply to the repo; never reorder, never rename. The Installation and Usage headings are used verbatim in every repo. Uniform names keep the whole portfolio reading the same, even for libraries and Nix modules. There, “Installation” is how you add it as a dependency and “Usage” is how you consume it. A repo’s .readme-validator.yaml, if present, enforces exactly this set; legacy configs that required other headings are deleted or updated to match.

​
The standalone rule

A README names exactly one repo: this one. Concretely:
  • No “Related Repos” table, no sibling list, no repo-relationship diagram. That map lives on how it fits together and in the repository catalog, maintained once.
  • Don’t describe what another repo does. If you must reference a sibling, link to its hub page or GitHub, don’t summarize it. The summary drifts the instant the sibling changes.
  • Dependencies are contracts, not names. When this repo consumes another’s output, describe the shape it expects, such as “reads an inventory matching <schema>” or “expects NETWORK_CIDR_* in the environment,” not “run the provisioning repo first.” The contract is what you actually depend on, and it’s stable; the sibling that satisfies it today might be replaced tomorrow. Pin the contract; link the map.
End every README with exactly one ecosystem pointer, chosen by the repo’s visibility: Public repo:
Private repo:
A public README never points readers at the gated site. That’s a login wall for outsiders. A private README points at the gated hub, which is allowed to describe the private picture. That one line is the only cross-cutting reference a README carries.

​
Template

Scaffolding a repo? Copy README.template.md from the org .github repo. It ships the shape described in the preceding table, with the footer pre-filled for a public repo.

​
Why it lives here

This site is the architecture map: how things connect, why decisions were made, what to read next. It isn’t the install walkthrough; that’s each repo’s README. Keeping the connective tissue here, and only here, is what lets every README stay short, current, and about one thing.