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 so the whole portfolio reads 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.
SectionContent
Title + one-linerRepo name as the H1, then a single sentence: what it is and who it’s for.
BadgesA standard row — CI status and license at minimum. Release/language badges optional.
InstallationThe shortest path to running it: prerequisites, then commands.
UsageThe common operations, with copy-pasteable examples.
Repo-specificConfiguration · Layout · Testing · Roles · whatever this repo needs. As many as it warrants.
ContributingA link to CONTRIBUTING.md or the public conventions — don’t restate them.
LicenseSPDX identifier and a link.
FooterThe single ecosystem link (below). Nothing else cross-repo.

​
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 — “reads an inventory matching <schema>”, “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: 
---

> Part of a [larger ecosystem of ~40 repos](https://docs.jacobpevans.com) — see how it all fits together.
Private repo: 
---

> Part of the [dryvist homelab](https://docs.dryvist.com) — how the private repos and infrastructure connect (gated).
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 above 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.