Keep a README in sync with the code: describe, never duplicate

Setup steps go first: a renamed script, a bumped runtime version, a new required environment variable, and the quickstart fails for the next clone. Screenshots and architecture diagrams go next, because they are frozen pixels describing a moving system, and nobody re-exports an image for a routine refactor. Badges quietly break third when a CI provider or coverage service changes URL schemes. Links to moved docs round it out.

Notice the pattern: everything on that list is a copy. The setup steps copy what CI already does, the diagram copies what the code already is, the badge copies a status that lives elsewhere. Copies drift; references do not. The rest of this page converts each copy into a reference or puts a test on it.

Two CI checks cover most README rot. A link checker such as lychee fetches every URL in the file and fails on 404s, which catches moved docs and dead badges. And the quickstart can be executed literally: run the exact install and build commands from the README in a clean container on a schedule. If the quickstart only works on machines that already have the project set up, that is a bug, and this job finds it before a new contributor does.

# .github/workflows/readme-check.yml
name: readme-check
on:
  pull_request:
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"   # weekly: READMEs rot without commits too
jobs:
  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress README.md
  quickstart:
    runs-on: ubuntu-latest
    container: node:22   # a machine with nothing preinstalled
    steps:
      - uses: actions/checkout@v4
      - name: Run the README setup steps verbatim
        run: |
          npm install
          npm run build

The architecture image is the copy you cannot test, so replace it with a reference. A Datadef project shared public serves a permanent image URL, and standard Markdown embeds it like any image. When the diagram is edited, the URL serves the new render; the README commit that pasted it never needs to change. Sizing parameters exist when the default 1600x1000 render does not fit.

One GitHub-specific mechanic makes this work better than people expect. GitHub does not load external images directly in rendered Markdown: it rewrites them through its Camo proxy at camo.githubusercontent.com, and Camo is documented to respect the cache headers of the origin. Datadef serves the embed with a five minute cache lifetime, so the README picture normally updates within minutes of an edit. If a copy ever looks stuck, send an HTTP PURGE request to the camo.githubusercontent.com URL of the rendered image to clear it. The first render after an edit takes a few seconds while a headless browser redraws it; after that it is cached and fast.

## Architecture

![System overview](https://datadef.io/api/embed/my-platform-a1b2c3d4)

<!-- The image is served live: editing the diagram updates this
     README within minutes. GitHub proxies it through Camo, which
     honors the five minute cache lifetime upstream. -->

What remains for prose is the part only humans know: what the project is for, what it deliberately does not do, where to ask questions. That content ages in years, not weeks. Everything operational should be a pointer: "run make dev" instead of an inlined command list that will drift from the Makefile, a link to the CI workflow instead of a described one, an injected table from a docs generator instead of a hand-maintained one.

A README built this way is shorter and more honest. The broader failure mode it avoids has its own write-up in README rot, and the general CI patterns are collected in docs checks in CI.

The live diagram URL only exists for Datadef projects shared public, which fits open source and most internal-but-not-secret repos. Flip the project private and the image 404s, including through Camo. For a genuinely confidential architecture, a committed export that you consciously re-export on change is the honest alternative.

GitHub also strips iframes from rendered Markdown, so the interactive pan-and-zoom embed form does not work in a README; the image URL is the right form there. And the update loop is about propagation, not authorship: someone or some agent still has to edit the diagram when the system changes. Datadef ships an MCP server so a repo-connected agent can do that edit, but nothing watches the repository on its own.

• README rot
• Embed diagrams in a GitHub README
• Embed diagrams in Markdown
• Docs checks in CI