diff --git a/.github/AGENTS.d/readme-badges.md b/.github/AGENTS.d/readme-badges.md
new file mode 100644
index 0000000000..9b18bf27cd
--- /dev/null
+++ b/.github/AGENTS.d/readme-badges.md
@@ -0,0 +1,28 @@
+---
+paths:
+  - .github/workflows/readme-badges.yml
+invariant: Render job on master only; both checkouts at github.sha; publish job contents: write only; no workflow_run trigger.
+---
+# README badges workflow (ADR-3519)
+
+`.github/workflows/readme-badges.yml` renders + publishes README status
+badges onto `badges` branch. Script rules, design check, carry:
+[scripts/ci/AGENTS.d/readme-badges.md](../../scripts/ci/AGENTS.d/readme-badges.md).
+Human guide: `docs/development/readme-badges.md`.
+
+- Guard: render job `if:` = policy repository + `https://github.com` +
+  `github.ref == 'refs/heads/master'`. Publish job `needs: render`, so
+  skipped render skips publish. Manual run on other branch -> nothing runs;
+  publish token never meets branch copy of workflow. Names come from
+  `.github/repository-security-policy.json`; `test_readme_badges.py` keeps
+  them equal.
+- Checkout: both jobs `ref: ${{ github.sha }}`, `persist-credentials: false`.
+  Never `ref: master`: master push between jobs hands publisher other code
+  than renderer ran.
+- Rights: top level `permissions: {}`; render job `actions: read` +
+  `contents: read`; publish job `contents: write` only. No other write scope.
+- Trigger: `schedule` (minutes 7, 22, 37, 52) + `workflow_dispatch`. No
+  `workflow_run` (zizmor dangerous trigger; fork branch named `master`
+  matches `branches` filter).
+- Ref: publish writes `refs/heads/badges` only, `force: false`;
+  GitHub-signed commit required.
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index 2caba47c6b..27de45844c 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -39,6 +39,7 @@ broken `.c` file).
 | `workflows/libvmaf-build-matrix.yml`, `/scripts/ci/run_meson_test.py`, `/core/test/test_meson_secret_env_sanitization.py` | [meson-sanitization](AGENTS.d/meson-sanitization.md) | Every workflow step running Meson/Ninja test invokes run_meson_test.py; resolve Python before sudo. |
 | `workflows/lint-and-format.yml`, `/scripts/sync-pelorus-interop.sh` | [pelorus-mirror](AGENTS.d/pelorus-mirror.md) | Pre-Commit job verifies exact declared commit of VMAFx/pelorus before pre-commit; no moving branch or tag. |
 | `/pyproject.toml`, `/renovate.json` | [python-requirement](AGENTS.d/python-requirement.md) | Root pyproject.toml keeps requires-python >=3.14 without patch component; renovate excludes root requires-python. |
+| `workflows/readme-badges.yml` | [readme-badges](AGENTS.d/readme-badges.md) | Render job on master only; both checkouts at github.sha; publish job contents: write only; no workflow_run trigger. |
 | `workflows/release-please.yml`, `workflows/supply-chain.yml`, `/scripts/release/verify-release-version.sh`, `/dev/Containerfile` | [release-fan-out](AGENTS.d/release-fan-out.md) | Single root package draft release; release-publish environment; native release-build stage; tag-bound recovery. |
 | `/renovate.json`, `/scripts/ci/tests/test_renovate_file_patterns.py`, `/docs/development/dependency-bot.md` | [renovate-bot](AGENTS.d/renovate-bot.md) | Mend Renovate config in renovate.json; dependabot.yml disabled; RENOVATE_TOKEN repository secret. |
 | `workflows/required-aggregator.yml`, `/scripts/ci/check-aggregator-names.sh`, `/scripts/ci/plan-ci-impact.py` | [required-aggregator](AGENTS.d/required-aggregator.md) | Aggregator runs on drafts; gates route in-job without paths filters; display names <=30 chars and match aggregator. |
diff --git a/.github/workflows/readme-badges.yml b/.github/workflows/readme-badges.yml
new file mode 100644
index 0000000000..0ff767b493
--- /dev/null
+++ b/.github/workflows/readme-badges.yml
@@ -0,0 +1,122 @@
+name: README Badges
+
+# Render the README status badges in one style (docs/development/readme-badges.md).
+# scripts/ci/readme_badges.py reads the latest decisive push run of every badged
+# workflow on master plus the OpenSSF Scorecard, OpenSSF Best Practices and
+# Codacy public APIs; tools/badges/render.mjs draws the SVGs with the pinned
+# shields.io renderer; the publish job commits them to the badges branch the
+# README links. A source that fails keeps its last value for six hours, then
+# reads "stale", and this run turns red so the failure is seen.
+
+on:
+  # Every 15 minutes: a badge lags a master run by at most that. A
+  # workflow_run trigger would be faster, but zizmor rates it a dangerous
+  # trigger, and its branch filter would also match a fork's branch named
+  # master.
+  schedule:
+    - cron: "7,22,37,52 * * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: readme-badges
+  cancel-in-progress: false
+
+jobs:
+  render:
+    name: Read the sources and render
+    # github.com only: the job reads and the publish job writes through the
+    # GitHub API, which a mirror's token cannot reach (as in supply-chain.yml).
+    # Default branch only: a manual run picked on another branch runs nothing,
+    # so the publish token never meets a branch's own copy of this file.
+    # .github/repository-security-policy.json holds both names; a test keeps
+    # these in step with it.
+    if: >-
+      github.repository == 'VMAFx/vmafx'
+      && github.server_url == 'https://github.com'
+      && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-26.04
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # The commit this run started from, in both jobs: a master push
+          # between them cannot hand the publisher other code than the
+          # renderer ran.
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.14.10"
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: "26.12.1"
+      - name: Install the pinned badge renderer
+        working-directory: tools/badges
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Read the badge sources
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          python3 scripts/ci/readme_badges.py spec
+          --spec build/badges-spec.json --state build/badges/state.json
+      - name: Render the SVGs
+        run: node tools/badges/render.mjs build/badges-spec.json build/badges
+      - if: ${{ env.GITEA_ACTIONS != 'true' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: readme-badges
+          path: build/badges/
+          retention-days: 1
+          if-no-files-found: error
+      - name: Upload artifact (Gitea)
+        if: ${{ env.GITEA_ACTIONS == 'true' }}
+        uses: actions/upload-artifact@c6a366c94c3e0affe28c06c8df20a878f24da3cf  # v3.2.2
+        with:
+          name: readme-badges
+          path: build/badges/
+          retention-days: 1
+          if-no-files-found: error
+
+  publish:
+    name: Publish to the badges branch
+    needs: render
+    runs-on: ubuntu-26.04
+    timeout-minutes: 5
+    # contents: write is the narrowest token right that can create a commit;
+    # the job writes refs/heads/badges only, and the master ruleset refuses
+    # this token on master.
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # The commit this run started from, in both jobs: a master push
+          # between them cannot hand the publisher other code than the
+          # renderer ran.
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - if: ${{ env.GITEA_ACTIONS != 'true' }}
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: readme-badges
+          path: build/badges
+      - name: Download artifact (Gitea)
+        if: ${{ env.GITEA_ACTIONS == 'true' }}
+        uses: actions/download-artifact@a9bc5e6ef2cb54c177f32aa5726adaa15e7e2d59  # v3.1.0
+        with:
+          name: readme-badges
+          path: build/badges
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.14.10"
+      - name: Commit the badges
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 scripts/ci/readme_badges.py publish --dir build/badges
+      - name: Fail the run when a source failed
+        run: python3 scripts/ci/readme_badges.py verdict --state build/badges/state.json
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f7ee76802f..244af4319d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -808,6 +808,22 @@ repos:
         files: '^(scripts/ci/(check-workflow-size\.py|tests/test_check_workflow_size\.py)|\.pre-commit-config\.yaml)$'
         pass_filenames: false
 
+      - id: readme-badge-design
+        name: Every README image keeps the one badge design (ADR-3519)
+        entry: python3 -B scripts/ci/readme_badges.py check-readme --readme README.md
+        language: system
+        files: '^(README\.md|scripts/ci/readme_badges\.py)$'
+        pass_filenames: false
+        stages: [pre-commit, pre-push]
+
+      - id: test-readme-badges
+        name: README badge renderer and design check keep positive, negative and boundary cases (ADR-3519)
+        entry: bash -c 'python3 -B scripts/ci/tests/test_readme_badges.py && python3 -B scripts/ci/tests/test_ci_tier.py'
+        language: system
+        files: '^(README\.md|scripts/ci/(readme_badges|ci_tier|tests/test_readme_badges|tests/test_ci_tier)\.py|tools/badges/.*|\.github/workflows/.*\.yml|\.pre-commit-config\.yaml)$'
+        pass_filenames: false
+        stages: [pre-commit, pre-push]
+
       - id: check-hosted-runner-labels
         name: Workflow jobs name an explicit hosted Ubuntu image, an older one only with a dated fallback
         entry: python3 scripts/ci/check_hosted_runner_labels.py
diff --git a/README.md b/README.md
index 662bab473b..4f2bdd28a3 100644
--- a/README.md
+++ b/README.md
@@ -11,17 +11,17 @@
   <!-- 1 release/version -->
   [![Release](https://img.shields.io/static/v1?label=release&message=v1.0.0-rc.3&style=for-the-badge&color=3b82f6&labelColor=111a35)](https://github.com/VMAFx/vmafx/releases) <!-- x-release-please-version -->
   <!-- 2 CI/build -->
-  [![Tests](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml)
-  [![Builds](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml)
-  [![Lint](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml)
-  [![FFmpeg](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml)
-  [![Go](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml)
-  [![Rust](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml)
+  [![Tests](https://raw.githubusercontent.com/VMAFx/vmafx/badges/tests.svg)](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml)
+  [![Builds](https://raw.githubusercontent.com/VMAFx/vmafx/badges/builds.svg)](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml)
+  [![Lint](https://raw.githubusercontent.com/VMAFx/vmafx/badges/lint.svg)](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml)
+  [![FFmpeg](https://raw.githubusercontent.com/VMAFx/vmafx/badges/ffmpeg.svg)](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml)
+  [![Go](https://raw.githubusercontent.com/VMAFx/vmafx/badges/go.svg)](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml)
+  [![Rust](https://raw.githubusercontent.com/VMAFx/vmafx/badges/rust.svg)](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml)
   <!-- 3 security/scorecard -->
-  [![Security](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml)
-  [![OpenSSF Scorecard](https://img.shields.io/badge/OpenSSF-Scorecard-06b6d4?style=for-the-badge&labelColor=111a35)](https://scorecard.dev/viewer/?uri=github.com/VMAFx/vmafx)
-  [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14549/badge)](https://www.bestpractices.dev/projects/14549)
-  [![Codacy](https://app.codacy.com/project/badge/Grade/ca74eb98b9b94cfc8d60d965b836b55d)](https://app.codacy.com/gh/VMAFx/vmafx/dashboard)
+  [![Security](https://raw.githubusercontent.com/VMAFx/vmafx/badges/security.svg)](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml)
+  [![OpenSSF Scorecard](https://raw.githubusercontent.com/VMAFx/vmafx/badges/scorecard.svg)](https://scorecard.dev/viewer/?uri=github.com/VMAFx/vmafx)
+  [![OpenSSF Best Practices](https://raw.githubusercontent.com/VMAFx/vmafx/badges/best-practices.svg)](https://www.bestpractices.dev/projects/14549)
+  [![Codacy](https://raw.githubusercontent.com/VMAFx/vmafx/badges/codacy.svg)](https://app.codacy.com/gh/VMAFx/vmafx/dashboard)
   [![CodeRabbit](https://img.shields.io/badge/Reviews-CodeRabbit-8b5cf6?style=for-the-badge&logo=coderabbit&logoColor=white&labelColor=111a35)](https://coderabbit.ai)
   <!-- 4 standards -->
   [![HISS-21](https://img.shields.io/badge/Standards-HISS--21-06b6d4?style=for-the-badge&logo=nasa&labelColor=111a35)](AGENTS.md)
@@ -105,16 +105,16 @@ and output options. For compressed inputs such as MP4, use
 
 ## 🧩 Backends at a glance
 
-[![C23](https://img.shields.io/badge/C-23-3b82f6?style=flat-square&labelColor=111a35)](docs/principles.md)
-[![C++23](https://img.shields.io/badge/C%2B%2B-23-3b82f6?style=flat-square&labelColor=111a35)](docs/principles.md)
-[![Go](https://img.shields.io/badge/Go-1.27-06b6d4?style=flat-square&labelColor=111a35)](go.mod)
-[![Rust](https://img.shields.io/badge/Rust-2024-8b5cf6?style=flat-square&labelColor=111a35)](bindings/rust/vmafx-sys/Cargo.toml)
-[![Python](https://img.shields.io/badge/Python-3.14%2B-3b82f6?style=flat-square&labelColor=111a35)](pyproject.toml)
-[![CUDA](https://img.shields.io/badge/CUDA-13.4-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/cuda/overview.md)
-[![ROCm](https://img.shields.io/badge/ROCm-10.1-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/hip/overview.md)
-[![SYCL](https://img.shields.io/badge/SYCL-oneAPI-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/sycl/overview.md)
-[![Metal](https://img.shields.io/badge/Metal-Apple_Silicon-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/metal/index.md)
-[![FFmpeg](https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=flat-square&labelColor=111a35)](docs/usage/ffmpeg.md)
+[![C23](https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35)](docs/principles.md)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-3b82f6?style=for-the-badge&labelColor=111a35)](docs/principles.md)
+[![Go](https://img.shields.io/badge/Go-1.27-06b6d4?style=for-the-badge&labelColor=111a35)](go.mod)
+[![Rust](https://img.shields.io/badge/Rust-2024-8b5cf6?style=for-the-badge&labelColor=111a35)](bindings/rust/vmafx-sys/Cargo.toml)
+[![Python](https://img.shields.io/badge/Python-3.14%2B-3b82f6?style=for-the-badge&labelColor=111a35)](pyproject.toml)
+[![CUDA](https://img.shields.io/badge/CUDA-13.4-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/cuda/overview.md)
+[![ROCm](https://img.shields.io/badge/ROCm-10.1-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/hip/overview.md)
+[![SYCL](https://img.shields.io/badge/SYCL-oneAPI-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/sycl/overview.md)
+[![Metal](https://img.shields.io/badge/Metal-Apple_Silicon-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/metal/index.md)
+[![FFmpeg](https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=for-the-badge&labelColor=111a35)](docs/usage/ffmpeg.md)
 
 Every GPU-backed feature extractor has at least one device twin, and each twin
 is held to the CPU reference by the cross-backend parity gate. The coverage
diff --git a/changelog.d/changed/readme-badges-uniform.md b/changelog.d/changed/readme-badges-uniform.md
new file mode 100644
index 0000000000..dd0c81a314
--- /dev/null
+++ b/changelog.d/changed/readme-badges-uniform.md
@@ -0,0 +1,5 @@
+- **Every README badge but the Praetor-managed governance badge now has the same `for-the-badge` design, and the status badges come from this project's own render.**
+  `.github/workflows/readme-badges.yml` draws the seven workflow badges and the OpenSSF Scorecard,
+  OpenSSF Best Practices and Codacy badges every 15 minutes onto the `badges` branch: a workflow badge
+  shows the newest finished master push run, so a run in progress never hides a red one, and the
+  Scorecard badge now shows the score. See `docs/development/readme-badges.md` (ADR-3519).
diff --git a/docs/README-STANDARD.md b/docs/README-STANDARD.md
index 8e2cef2195..59b407710e 100644
--- a/docs/README-STANDARD.md
+++ b/docs/README-STANDARD.md
@@ -39,10 +39,11 @@ the VMAFx banner and documentation site.
 | `text` | `#e2e8f0` | light text on dark fills |
 | `muted` | `#94a3b8` | secondary text in the banner |
 
-The static badge messages use the three accent colours and set
-`labelColor=111a35` so the block reads as one band. Workflow-status badges are
-GitHub's own and keep its green, red or grey colour, because that colour is the
-status.
+Every badge uses `style=for-the-badge` and `labelColor=111a35`, so the page
+shows one badge design. Static badges take their message colour from the three
+accents. Status badges (workflow, Scorecard, Best Practices, Codacy) keep a
+status colour, because that colour is the status: green `#1f883d`, amber
+`#9a6700`, red `#cf222e`, grey `#6e7781` for unknown or stale.
 
 ## Hero banner
 
@@ -58,15 +59,15 @@ status.
 ## Badge block
 
 All badges at the top sit in one block directly under the banner, inside the
-centred header; static badges use `style=for-the-badge`. The groups always
+centred header; every badge uses `style=for-the-badge`. The groups always
 come in this order; a repository leaves out a group it has nothing for, but
 never reorders them:
 
 1. **Release / version**: the current release as a static badge that
    release-please keeps up to date (see "Badge sources").
-2. **CI / build**: one workflow-status badge per main workflow, with
-   `branch=<default>&event=push`. The badge label is the workflow name, so a
-   red badge points at the workflow of the same name.
+2. **CI / build**: one status badge per main workflow, showing its latest
+   decisive push run on the default branch. The badge label is the workflow
+   name, so a red badge points at the workflow of the same name.
 3. **Security / scorecard**: the security workflow, the OpenSSF Scorecard, the
    OpenSSF Best Practices level and the review bots that check every pull
    request (Codacy, CodeRabbit), where the project has them.
@@ -80,9 +81,16 @@ reviewer can check the order without rendering the page.
 
 Version badges for languages, toolchains, backends and integrations (C, Go,
 Rust, Python, CUDA, ROCm and the like) are not part of the top block. Where
-they help, they go in one compact row (`style=flat-square`) inside the section
-they describe; for VMAFx that is "Backends at a glance". No `for-the-badge`
-badge appears below the header.
+they help, they go in one row inside the section they describe, in the same
+`for-the-badge` style as the header; for VMAFx that is "Backends at a glance".
+
+One badge keeps another design: the governance badge inside the
+`praetor:readme-governance` block, which the Praetor tool writes and checks.
+That block is not edited by hand.
+
+`python3 scripts/ci/readme_badges.py check-readme` enforces the one design on
+every commit that touches `README.md`; see
+[README status badges](development/readme-badges.md#checks).
 
 A static badge is built from shields.io's path form,
 `https://img.shields.io/badge/<label>-<message>-<colour>`, where `-` inside a
@@ -101,11 +109,8 @@ that answers well inside that limit:
 
 | Badge | Source |
 | --- | --- |
-| Workflow status | GitHub's own `https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg?branch=<default>&event=push`; GitHub serves it directly, not through the proxy. |
+| Workflow status, OpenSSF Scorecard, OpenSSF Best Practices, Codacy | An SVG on the `badges` branch, `https://raw.githubusercontent.com/<owner>/<repo>/badges/<slug>.svg`, linked to the workflow, the Scorecard viewer, the Best Practices project and the Codacy dashboard. The README Badges workflow reads the values and draws the SVGs with the pinned shields.io renderer; see [README status badges](development/readme-badges.md). GitHub's own workflow badge and the badges Best Practices and Codacy serve each have a design of their own, so they are not used. |
 | Release | A static shields.io badge in query form, `https://img.shields.io/static/v1?label=release&message=v<version>&...`, on a line that ends with `<!-- x-release-please-version -->`. `README.md` is a generic extra file in `release-please-config.json`, so each release PR rewrites the version, and `scripts/release/verify-release-version.sh` checks the marker against the tag. |
-| OpenSSF Best Practices | `https://www.bestpractices.dev/projects/<id>/badge`, served by the project itself. |
-| OpenSSF Scorecard | A static link badge to the Scorecard viewer. The score badge (`api.scorecard.dev/.../badge`) redirects to a computed shields.io badge and is too slow for the proxy. |
-| Codacy | The grade badge Codacy serves itself, `https://app.codacy.com/project/badge/Grade/<project token>`, linked to the repository dashboard; the token is `badges.grade` of `GET https://app.codacy.com/api/v3/organizations/gh/<owner>/repositories/<repo>`. |
 | CodeRabbit | A static link badge. shields.io's computed `coderabbit/prs` badge counts only part of the reviews (it showed 13 for VMAFx on 2026-11-01) and is not served from a cache. |
 
 Measure a new badge source before adding it: `curl -o /dev/null -w '%{time_total}'`
diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..7503fc006c
--- /dev/null
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -0,0 +1,103 @@
+<!-- markdownlint-disable MD013 MD041 MD060 -->
+# ADR-3519: Render the README status badges in one style onto a `badges` branch
+
+- **Status**: Accepted
+- **Date**: 2026-11-10
+- **Deciders**: Lusoris
+- **Tags**: `ci`, `docs`, `readme`, `supply-chain`
+
+## Context
+
+[ADR-3366](3366-readme-presentation-standard.md) puts one `for-the-badge`
+badge block under the README banner. The header still mixed four designs:
+the seven workflow badges were GitHub's own `badge.svg` images, which come in
+one fixed design; the Best Practices and Codacy badges came from their
+services in their own designs; the OpenSSF Scorecard badge was a static
+shields.io image that showed no score at all; and the backends row used
+`flat-square`. GitHub's `badge.svg` cannot be restyled, and the shields.io
+workflow badge reads that same image
+(`services/github/github-actions-workflow-status.service.js` in the shields
+repository, read 2026-11-10), so neither gives this project a say in which run
+a badge reports.
+
+## Decision
+
+We render the ten status badges ourselves.
+`.github/workflows/readme-badges.yml` is scheduled every 15 minutes and runs
+on demand: its render job (`actions: read`, `contents: read`) runs
+`scripts/ci/readme_badges.py spec`, which reads the newest decisive push run of
+each badged workflow on the default branch and the public Scorecard, Best
+Practices and Codacy APIs, and `tools/badges/render.mjs` draws the SVGs with
+`badge-maker` 6.0.0, the shields.io renderer, pinned in
+`tools/badges/package-lock.json`. Its publish job (`contents: write`) commits
+the SVGs and `state.json` to the `badges` branch through the GitHub API, and
+the README links `https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
+Both jobs run only on the default branch and check out the commit the run
+started from. A source that fails turns the run red at once; its badge keeps
+the last value for six hours, then reads `stale`. Every other README badge,
+the backends row included, uses `for-the-badge`; the one exception is the
+Praetor governance badge, which Praetor writes. The full rules are in
+[docs/development/readme-badges.md](../development/readme-badges.md).
+
+## Alternatives considered
+
+| Option | Pros | Cons | Why not chosen |
+|---|---|---|---|
+| Rendered badges on a `badges` branch, schedule trigger (chosen) | One design; the project decides which run a badge shows; Scorecard shows its score; no third-party request per page view | About 15 minutes of lag, more when GitHub delays a scheduled run; a job with `contents: write`; a branch that grows by about one commit an hour | Chosen |
+| Same, triggered by `workflow_run` | Badge within a minute of a master run | zizmor rates `workflow_run` a dangerous trigger; its `branches: [master]` filter matches a fork's branch named `master` too | The 15-minute lag is the smaller cost |
+| shields.io dynamic URLs with `style=for-the-badge` | No workflow or branch; one design | Each page view depends on shields.io; the workflow badge scrapes GitHub's `badge.svg`, so run selection stays GitHub's; Scorecard and Codacy would need per-service shields routes | Keeps a third party on every page view and leaves run selection out of reach |
+| Keep each service's own badge | Nothing to build | Four designs in one block, against ADR-3366; the Scorecard badge shows no score | It is the defect this decision fixes |
+| Badges as GitHub Pages files | Same rendering | Pages deploys the documentation site; a second deploy path for ten files | The branch needs no Pages change |
+
+## Consequences
+
+- **Positive**: one badge design on the README; a run in progress or
+  cancelled never hides a red one; the Scorecard badge shows the score; a
+  failed source turns the run red the same day. `readme_badges.py
+  check-readme`, run as a pre-commit and pre-push hook, refuses any README
+  image outside the one design, so the mix cannot come back unnoticed.
+- **Negative**: the publish job holds `contents: write`, which GitHub cannot
+  limit to one branch. The script writes only `refs/heads/badges` and never
+  forces, and the master ruleset requires a pull request, so the token cannot
+  move `master`. An SVG cannot age by itself: if the workflow stops, the
+  badges keep their last values until someone sees the missing run. The six
+  hours count from the read time `state.json` records. A run with unchanged
+  SVGs commits once a badge's new read time is an hour or more newer than the
+  recorded one, so the recorded time trails the last successful read by less
+  than an hour and `stale` can come up to an hour early; committing on every
+  run would quadruple the branch's growth.
+- **Neutral / follow-ups**: issue 3394 tracks publishing with a dedicated
+  GitHub App token instead of the workflow token, plus a second ruleset on
+  `refs/heads/badges`, managed by `scripts/dev/check_repository_security.py`,
+  that lets only that App write the branch. A ruleset that only refuses
+  deletion and non-fast-forward updates would still let any writer add
+  commits, so it is not a follow-up on its own. The Praetor governance badge
+  in the `praetor:readme-governance` block keeps GitHub's design until
+  Praetor offers the style (Praetor issue 1893), and `check-readme` then
+  drops its one exception. This style is the reference for the ecosystem
+  README badge audit.
+
+## References
+
+- Source: `req` (operator order `vmafx-readme-badges-and-lint-red-20261110`,
+  2026-11-10, paraphrased): every README badge in one design, and no red
+  default branch anywhere in the fleet.
+- [Research-3519](../research/3519-readme-badges-rendered-branch.md): the
+  sources, measurements and alternatives behind this decision.
+- Controller answer `vmafx-readme-badge-style-r1` (2026-11-10, option b,
+  paraphrased): one `for-the-badge` design everywhere, a workflow rendering the
+  dynamic badges with a pinned `badge-maker` onto a `badges` branch with the
+  least rights, a stale marker after six hours; it answers the operator order
+  `vmafx-readme-badges-and-lint-red-20261110` (paraphrased: the README badge
+  row mixes designs).
+- Operator answer `vmafx-badges-app-token-ruleset` (2026-11-10, option a,
+  paraphrased): land on the workflow token now, and harden the `badges`
+  branch with a GitHub App token and its own ruleset as a follow-up
+  (issue 3394).
+- [ADR-3366](3366-readme-presentation-standard.md): the README presentation
+  standard.
+- shields.io GitHub Actions workflow status service:
+  <https://github.com/badges/shields/blob/master/services/github/github-actions-workflow-status.service.js>.
+- `badge-maker` package: <https://www.npmjs.com/package/badge-maker>.
+- GitHub Actions `workflow_run` event:
+  <https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_run>.
diff --git a/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..094005da48
--- /dev/null
+++ b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
@@ -0,0 +1 @@
+| [ADR-3519](3519-readme-badges-rendered-branch.md) | The ten README status badges are rendered with the pinned shields.io renderer by `.github/workflows/readme-badges.yml` every 15 minutes onto the `badges` branch, from the newest decisive master push run of each workflow and the Scorecard, Best Practices and Codacy APIs; a failed source carries six hours then reads `stale`; every README badge but the Praetor-managed governance badge uses `for-the-badge` | Accepted | ci, docs, readme, supply-chain |
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
new file mode 100644
index 0000000000..cc517afda0
--- /dev/null
+++ b/docs/development/readme-badges.md
@@ -0,0 +1,160 @@
+# README status badges
+
+The README header shows ten status badges: seven workflows (Tests, Builds,
+Lint, FFmpeg, Go, Rust, Security), the OpenSSF Scorecard score, the OpenSSF
+Best Practices level and the Codacy grade. They are SVG files on the `badges`
+branch, drawn in the same `for-the-badge` style as every other badge on the
+page ([README standard](../README-STANDARD.md#badge-block)). The README links
+each one with
+`https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
+
+## Where a badge value comes from
+
+The README Badges workflow (`.github/workflows/readme-badges.yml`) is
+scheduled every 15 minutes, at minutes 7, 22, 37 and 52, and runs on demand.
+GitHub can start a scheduled run late, or drop it, when Actions is under load,
+so 15 minutes is the intended step, not a promise:
+
+```bash
+gh workflow run readme-badges.yml -R VMAFx/vmafx
+```
+
+Its first job runs `scripts/ci/readme_badges.py spec`, which asks each source
+for the current value:
+
+| Badge | Source | Message and colour |
+| --- | --- | --- |
+| Tests, Builds, Lint, FFmpeg, Go, Rust, Security | GitHub API: the newest push run of the workflow on the default branch, among the last 30, that has a conclusion and was not cancelled or skipped. Runs in progress, cancelled and skipped are passed over, so a run in progress never hides a red one. | `passing` green for `success`; `failing` red for `failure`, `timed_out` or `startup_failure`; `unknown` grey for any other conclusion (`action_required`, `neutral`, `stale`) and when no run qualifies. An older run's value never stands in. |
+| OpenSSF Scorecard | `https://api.scorecard.dev/projects/github.com/VMAFx/vmafx` | the score with one decimal, `8.5 / 10`; green from an unrounded 8.5, the master requirement in [the principles](../principles.md) ([ADR-1247](../adr/1247-scorecard-exact-head-gates.md)), amber from 4.0, red below. The colour follows the unrounded score, so 8.46 reads `8.5 / 10` in amber. |
+| OpenSSF Best Practices | `https://www.bestpractices.dev/projects.json?url=https://github.com/VMAFx/vmafx` | `in progress` amber, `passing`, `silver` or `gold` green. |
+| Codacy | `https://app.codacy.com/api/v3/analysis/organizations/gh/VMAFx/repositories/vmafx` | the grade letter; A and B green, C amber, D to F red. |
+
+Only the GitHub API call carries the workflow token. The three public
+sources get a plain request with no token. Every request goes over https
+only, and a redirect is not followed: it fails as an error, so the token
+never travels to another address.
+
+The workflow writes the list to `build/badges-spec.json`, and
+`tools/badges/render.mjs` draws one SVG per entry with `badge-maker`, the
+renderer shields.io uses, at the version pinned in
+`tools/badges/package-lock.json`. The renderer accepts only the four keys
+`slug`, `label`, `message` and `color`, printable ASCII text up to 40
+characters and a `#rrggbb` colour, so a source cannot put markup into the SVG.
+
+## When a source fails
+
+A source that times out or answers something unexpected keeps its last value
+for six hours. After that its badge reads `stale` in grey. Either way the run
+turns red at its last step (`readme_badges.py verdict`), so the failure shows
+in the Actions tab the same day, not when someone notices an old badge.
+
+The last values live in `state.json` on the `badges` branch, next to the SVGs,
+with the time each one was read. A time without a UTC offset, or one that
+cannot be read, counts as stale.
+
+The six hours run from the read time `state.json` holds. A run whose SVGs are
+all unchanged still commits once a badge's new read time is an hour or more
+newer than the one on the branch (see below), so that time trails the last
+successful read by less than an hour, also right after a source recovers with
+its old value. A badge can therefore turn `stale` up to an hour before six
+hours have passed since its last successful read, and one schedule step after,
+plus any delay GitHub adds to a scheduled run.
+Committing `state.json` on every run would close that gap at the cost of
+about four commits an hour instead of one.
+
+When `state.json` itself cannot be read (any answer but 404, which means the
+branch is new), the run stops before it renders anything. The badges keep
+their values instead of all turning `stale` at once.
+
+## How the badges branch is written
+
+The second job runs `scripts/ci/readme_badges.py publish`, which writes the
+ten SVGs and `state.json` as the whole tree of one new commit through the
+GitHub API:
+
+- GitHub signs the commit. A commit that comes back unverified is not
+  published, and the branch stays where it was.
+- The branch only moves forward (`force: false`).
+- When every SVG is unchanged, the last commit is less than an hour old, and
+  `state.json` on the branch holds each badge's read time less than an hour
+  before this run's, nothing is committed, so the branch grows by about one
+  commit an hour. A badge whose source has never answered has no read time in
+  either file; that counts as recorded, since there is nothing to record. A
+  missing state file or badge entry, a different set of badges, or a read time
+  that is unreadable, in the future or on one side only means a commit.
+- A commit made with the workflow token starts no other workflow.
+
+The job's token has `contents: write`, the narrowest right that can make a
+commit. GitHub cannot limit that right to one branch; the script writes only
+`refs/heads/badges`, and the master ruleset requires a pull request, so the
+token cannot move `master`. No ruleset guards `badges` yet, so any other
+token with `contents: write` (another workflow, an installed app, a person
+with write access) can push to it too. Issue 3394 tracks a dedicated GitHub
+App as the only publisher, with a `badges` ruleset that refuses every other
+writer.
+
+Both jobs run only on the default branch (`github.ref` is
+`refs/heads/master`): a manual run started on another branch does nothing, so
+the publish token never runs a branch's own copy of the workflow. Both jobs
+check out `github.sha`, the commit the run started from, so a master push
+between the two jobs cannot hand the publisher other code than the renderer
+ran.
+
+## Why a schedule and not `workflow_run`
+
+A `workflow_run` trigger would refresh a badge within a minute of each master
+run. zizmor rates `workflow_run` a dangerous trigger, and its
+`branches: [master]` filter matches the branch name only, so a pull request
+from a fork's branch named `master` would start it too. The schedule costs up
+to 15 minutes of lag, more when GitHub delays a run, and has neither problem.
+
+## Limits
+
+- An SVG cannot age by itself. When the workflow itself stops (disabled, or
+  scheduled runs paused after 60 days without repository activity), no run
+  starts, so none turns red, and the badges keep showing the last values,
+  green ones included. The signal is a missing run: the newest README Badges
+  run is more than an hour old (a single scheduled run can start late or be
+  dropped). Check it, then re-enable the workflow:
+
+  ```bash
+  gh run list -R VMAFx/vmafx --workflow readme-badges.yml --limit 1 --json createdAt,conclusion
+  gh workflow enable readme-badges.yml -R VMAFx/vmafx
+  ```
+
+- The Praetor governance badge in the `praetor:readme-governance` block is
+  written by Praetor and keeps GitHub's design.
+
+## Checks
+
+```bash
+python3 scripts/ci/readme_badges.py check-readme --readme README.md
+python3 -m pytest scripts/ci/tests/test_readme_badges.py
+```
+
+`check-readme` fails when any image in the README breaks the one design. An
+image passes only when it is one of the rendered SVGs on this repository's
+`badges` branch, a shields.io badge with both `style=for-the-badge` and
+`labelColor=111a35`, or a file that exists inside the repository (the
+banner). The repository name comes from
+`.github/repository-security-policy.json`; a badge rendered for any other
+repository or a fork fails. A local path fails when it names no file or
+resolves outside the README's directory, through a symbolic link included.
+Images inside code fences and code spans are ignored. The one exception is
+the Praetor governance badge inside the `praetor:readme-governance` block;
+it goes once Praetor can draw that badge in the same style (Praetor issue
+1893). Each fault names the line:
+
+```text
+README.md:117: https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=flat-square&labelColor=111a35: a shields.io badge needs style=for-the-badge
+```
+
+The `readme-badge-design` pre-commit hook runs the check whenever `README.md`
+or the script changes, at commit and at push, and the `test-readme-badges`
+hook runs both test files.
+
+The tests cover every value rule above, the six-hour carry, the publish rules,
+the design check and the README itself: the badge order and alt texts in
+`README.md` must match `BADGES` in `scripts/ci/readme_badges.py`, each
+workflow badge's label must be that workflow's `name:`, and the text and
+colour patterns of `render.mjs` must equal the Python ones.
diff --git a/docs/research/3519-readme-badges-rendered-branch.md b/docs/research/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..3d0a8246b5
--- /dev/null
+++ b/docs/research/3519-readme-badges-rendered-branch.md
@@ -0,0 +1,62 @@
+<!-- markdownlint-disable MD013 MD060 -->
+# Research-3519: README status badges rendered in one style onto a `badges` branch
+
+- **Status**: Completed
+- **Workstream**: [ADR-3519](../adr/3519-readme-badges-rendered-branch.md), [ADR-3366](../adr/3366-readme-presentation-standard.md)
+- **Last updated**: 2026-11-10
+
+## Question
+
+How can the ten README status badges (seven workflow badges, OpenSSF Scorecard, OpenSSF Best Practices and Codacy) share the one `for-the-badge` design that [ADR-3366](../adr/3366-readme-presentation-standard.md) sets, report the run this project chooses, and be published with the fewest rights a workflow can hold?
+
+## Sources
+
+- [`services/github/github-actions-workflow-status.service.js`](https://github.com/badges/shields/blob/master/services/github/github-actions-workflow-status.service.js) in the shields repository (read 2026-11-10): the shields.io workflow badge fetches GitHub's own `badge.svg` and reads its text.
+- GitHub REST API, ["List workflow runs for a workflow"](https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow) (`GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`): `branch`, `event`, `status` and `per_page` filters; default page size 30.
+- Ruleset bypass actors, from ["Creating rulesets for a repository"](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset), section "Granting bypass permissions for your branch or tag ruleset" (GitHub Docs, read 2026-11-10): the eligible bypass actors are repository admins and owners, the maintain or write role, teams, GitHub Apps and Dependabot.
+- Bot commit signing, from ["About commit signature verification"](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#signature-verification-for-bots), section "Signature verification for bots" (GitHub Docs): GitHub signs commits a GitHub App or the workflow token creates through the API when no custom author or committer is set.
+- Commit [`e3d3cbcb602af571f93a1cc72e71ed71fad14b38`](https://github.com/VMAFx/vmafx/commit/e3d3cbcb602af571f93a1cc72e71ed71fad14b38) in this repository (an API commit by a GitHub App bot): committer `web-flow`, signature verified.
+- [gh-aw issue 73207](https://github.com/github/gh-aw/issues/73207) (opened 2026-10-30) and the [Codex Review Gate marketplace page](https://github.com/marketplace/actions/codex-review-gate) (read 2026-11-10): the workflow token cannot be added as a ruleset bypass actor on its own; integration id 15368 names the whole GitHub Actions App, not one workflow.
+- Scheduled runs, from ["Events that trigger workflows", section `schedule`](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule) (GitHub Docs, read 2026-11-10): a scheduled run can start late when Actions is under load, most often at the start of an hour, and queued jobs can be dropped; scheduled workflows in a public repository are disabled after 60 days without activity.
+- zizmor audit [`dangerous-triggers`](https://docs.zizmor.sh/audits/#dangerous-triggers): rates `workflow_run` and `pull_request_target` as dangerous triggers.
+- [docs/principles.md](../principles.md) section 6 and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md): unrounded Scorecard ≥ 8.5 required on master.
+- [`badge-maker` 6.0.0](https://www.npmjs.com/package/badge-maker/v/6.0.0), the shields.io renderer, pinned in `tools/badges/package-lock.json`.
+- `scripts/ci/readme_badges.py`, `.github/workflows/readme-badges.yml`, `scripts/ci/check_repository_security.py` and `.github/repository-security-policy.json` on the pull request 3393 branch.
+
+## Findings
+
+1. **GitHub's badge has one fixed design, and shields.io reads it.** `badge.svg` cannot be restyled. The shields.io workflow badge takes its text from that same image, so a `for-the-badge` shields URL changes the look but not which run the badge reports. Rendering the SVGs from the API is the only path that gives the project both the design and the run choice.
+
+2. **Run choice.** GitHub's badge shows the latest run, so a cancelled or skipped run hides a failed one. `readme_badges.py` lists completed push runs on the default branch (`per_page` = `RUNS_PER_PAGE` = 30) and takes the newest one with a conclusion other than cancelled or skipped (`PASSED_OVER`). `success` reads passing; `failure`, `timed_out` and `startup_failure` read failing; any other conclusion reads `unknown`. An older run never stands in for a newer decisive one. When all 30 runs are passed over, the badge reads `unknown` rather than paging further back.
+
+3. **Trigger.** A `workflow_run` trigger would refresh a badge within a minute of a master run, but zizmor rates it a dangerous trigger, and its `branches: [master]` filter also matches a fork's branch named `master`. A schedule (`7,22,37,52 * * * *`) with a default-branch guard on the render job and checkouts at `github.sha` has no outside input. Fifteen minutes is the intended step, not a bound on a badge's age: GitHub can start a scheduled run late or drop it when Actions is under load, and the minutes 7, 22, 37 and 52 stay clear of the busy start of the hour.
+
+4. **Rights.** `contents: write` cannot be limited to one branch. The master ruleset requires a pull request and the workflow token holds no bypass, so the token cannot move `master`. The token also cannot be named as a ruleset bypass actor: the eligible actors are roles, teams, GitHub Apps and Dependabot, and the GitHub Actions App (integration 15368) covers every workflow in the repository. A `badges` ruleset that refuses deletion and non-fast-forward pushes therefore still lets any workflow with `contents: write` add forward commits; refusing every other writer needs a dedicated GitHub App as the only bypass actor.
+
+5. **Signed commits.** Commits the workflow token creates through the Git data API with no custom author or committer are signed by GitHub and show as verified (committer `web-flow`). The publish job sets no author or committer and moves the branch only to a commit GitHub reports as verified, so every commit the publish job adds is verified without any signing key in the workflow. That covers the publish job's commits, not the whole branch: until issue 3394 lands, another writer with `contents: write` can add commits of its own (finding 4).
+
+6. **Staleness.** A source that fails turns that run red at once: its `verdict` step exits 1. The badge itself keeps the last value for `STALE_AFTER` = 6 hours and then reads `stale`. The publish job skips the commit only while every SVG matches the branch, the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, and the branch's `state.json` holds each badge's read time less than an hour before this run's. The read time `state.json` records therefore lags the last successful read by less than an hour, also when a source recovers with its old value: `stale` can come up to an hour early, and one schedule step late plus any delay GitHub adds to a scheduled run. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
+
+7. **Scorecard threshold.** The badge is green from an unrounded 8.5, the gate [docs/principles.md](../principles.md) and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md) set for master. A score of 8.46 shows `8.5 / 10` in amber, so the rounded text never hides a miss.
+
+8. **Pinned renderer.** `badge-maker` 6.0.0 draws the same SVG shields.io serves, without a request to shields.io per page view. The lock file pins it with its integrity hash.
+
+## Alternatives explored
+
+- **`workflow_run` trigger**: Rejected. Faster badges, but a dangerous trigger with a branch filter that fork branches can match.
+- **shields.io dynamic URLs with `style=for-the-badge`**: Rejected. Every page view depends on shields.io, and the workflow badge keeps GitHub's run choice.
+- **Each service's own badge**: Rejected. Four designs in one block and a Scorecard badge without a score.
+- **GitHub Pages files**: Rejected. Pages deploys the documentation site; a second deploy path for ten files is not worth it.
+- **Commit `state.json` on every run**: Rejected. Removes the up to one hour early `stale`, but quadruples the branch's growth.
+- **Rendered SVGs on a `badges` branch, schedule trigger, workflow token**: Chosen.
+
+## Open questions
+
+- Publishing with a dedicated GitHub App token plus a second managed ruleset on `badges`, so that no other workflow can write the branch. `check_repository_security.py` manages one ruleset today; a second one needs a policy change and an App installation. Tracked in issue 3394.
+- The Praetor governance badge keeps GitHub's design until Praetor offers the style (Praetor issue 1893).
+
+## Related
+
+- [ADR-3519](../adr/3519-readme-badges-rendered-branch.md) — Render the README status badges in one style onto a `badges` branch
+- [ADR-3366](../adr/3366-readme-presentation-standard.md) — README presentation standard
+- [README badges](../development/readme-badges.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index ecc466f167..a1944b4f59 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -545,6 +545,7 @@ nav:
       - PR body validator: development/pr-body-validator.md
       - mkdocs strict pre-push hook: development/pre-push-mkdocs-strict.md
       - Documentation site design: development/docs-site-design.md
+      - README status badges: development/readme-badges.md
       - Dev MCP container: development/dev-mcp.md
       - Kubernetes deployment: development/k8s-deployment.md
       - Operator: development/operator.md
diff --git a/scripts/ci/AGENTS-gates.md b/scripts/ci/AGENTS-gates.md
index 910504e03b..88b72afd68 100644
--- a/scripts/ci/AGENTS-gates.md
+++ b/scripts/ci/AGENTS-gates.md
@@ -35,6 +35,7 @@ file of this directory. `Touching` paths: relative to this directory, leading
 | `pr-diff-base.sh`, `classify-dependency-pr.sh`, `release-pr-exempt.sh`, `tests/test_pr_gates_merge_base.py` | [pr-diff-base](AGENTS.d/pr-diff-base.md) | PR gates diff from merge base of BASE_SHA and HEAD_SHA, never from BASE_SHA; no merge base -> fail closed. |
 | `/.pre-commit-config.yaml` | [pre-commit-hygiene](AGENTS.d/pre-commit-hygiene.md) | Third-party code enters through Meson wraps or `ffmpeg-patches/`, never a submodule; verify hook revision bumps. |
 | `precommit_scope.py`, `tests/test_precommit_scope.py`, `/.github/workflows/lint-and-format.yml` | [precommit-scope](AGENTS.d/precommit-scope.md) | PR Pre-Commit = diff only if no hook input changed; input change or unreadable diff -> whole tree. |
+| `readme_badges.py`, `tests/test_readme_badges.py`, `/tools/badges/*`, `/.github/workflows/readme-badges.yml`, `/README.md` | [readme-badges](AGENTS.d/readme-badges.md) | README badge order = `BADGES`; README images pass `check-readme`; publish moves `refs/heads/badges` only, unforced. |
 | `check-aggregator-names.sh`, `tests/test-check-aggregator-names.sh`, `required_aggregator_harness.py`, `test_go_workflow_contract.py`, `tests/test_required_release_legs.py`, `tests/test_aggregator_absent_fails.py` | [required-aggregator](AGENTS.d/required-aggregator.md) | `required` list = `# required-aggregator` markers; one reporter per required name; contract suites share one harness. |
 | `*research-digest-id*`, `tests/test_research_digest_ids.py`, `/docs/research/*.md` | [research-digest-ids](AGENTS.d/research-digest-ids.md) | New digest: unique numeric prefix + H1 `# Research-NNNN`; baseline debt only shrinks; no `--bootstrap-from-ref` in CI. |
 | `/REUSE.toml`, `tests/test_reuse_compliance.py`, `/.github/workflows/reuse.yml` | [reuse-provenance](AGENTS.d/reuse-provenance.md) | `reuse lint` green is not provenance: keep exact overrides for inherited, ported, no-CLA and FFmpeg-patch files. |
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
new file mode 100644
index 0000000000..22544184e6
--- /dev/null
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -0,0 +1,26 @@
+---
+paths:
+  - scripts/ci/readme_badges.py
+  - scripts/ci/tests/test_readme_badges.py
+  - tools/badges/*
+  - .github/workflows/readme-badges.yml
+  - README.md
+invariant: README badge order = `BADGES`; README images pass `check-readme`; publish moves `refs/heads/badges` only, unforced.
+area: gates
+---
+<!-- markdownlint-disable MD013 MD060 -->
+# README status badges (ADR-3519)
+
+`scripts/ci/readme_badges.py` reads badge values; `tools/badges/render.mjs` draws SVGs; `.github/workflows/readme-badges.yml` publishes SVGs to `badges` branch. Human guide: `docs/development/readme-badges.md`.
+
+- Order + labels: README header badges, alt texts, order = `BADGES` tuple; workflow badge label = that workflow's `name:`. `test_readme_badges.py` reads `README.md`; new badge changes both.
+- Run choice: workflow badge = newest push run on default branch with conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
+- Scorecard: green from unrounded `SCORE_GREEN` = 8.5 (master requirement, `docs/principles.md`, ADR-1247); shown value rounded to 1 decimal, colour from unrounded score.
+- Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails last successful read < `QUIET_WINDOW` (`reads_recorded`), recovery with same value included (regression test pins case); `stale` <= 1 h early, <= 1 step late; accepted trade-off vs 4 commits/h. GitHub delays or drops scheduled runs at times: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
+- State read: `previous_state` 404 = new branch, empty; any other failure -> `BadgeError`, run stops, nothing rendered or published. Never return empty state on failed read.
+- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit only when SVGs unchanged, head < `QUIET_WINDOW` = 1 h old, and branch `state.json` holds each badge read time 0 to < `QUIET_WINDOW` before this run's (`reads_recorded`). No read time on both sides (source never answered) = nothing to record, counts as recorded (`read_lag` 0; `test_no_read_time_on_both_sides_commits_nothing`). Missing state file or entry, other badge set, unreadable, future or one-sided time -> commit.
+- Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
+- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. `HTTPS_OPENER` = no redirect handler: 3xx = `HTTPError`, `Authorization` never resent elsewhere. JSON answers read with `field()`, never bare indexing.
+- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file that exists. Rendered + governance badges -> home repository required (`home_repository()` from `.github/repository-security-policy.json`, case-insensitive); other repo or fork fails. Local path: `missing_file` resolves symlinks, fails outside README dir or no file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`governance_badge()`) until Praetor issue 1893 lands; then drop exception.
+- Rights: render job `actions: read` + `contents: read`; publish job `contents: write` only; workflow top level `permissions: {}`. No `workflow_run` trigger (zizmor dangerous trigger; fork branch named `master` matches). Workflow guard + checkout rules: `.github/AGENTS.d/readme-badges.md`.
diff --git a/scripts/ci/ci_tier.py b/scripts/ci/ci_tier.py
index 23f3740cb3..ed51f5aa17 100644
--- a/scripts/ci/ci_tier.py
+++ b/scripts/ci/ci_tier.py
@@ -36,6 +36,7 @@
 from __future__ import annotations
 
 import argparse
+import http.client
 import json
 import os
 import shutil
@@ -57,12 +58,38 @@
 DEFAULT_CONFIG = REPO_ROOT / ".github" / "ci-tier.json"
 EXEMPT_SCRIPT = REPO_ROOT / "scripts" / "ci" / "release-pr-exempt.sh"
 API_TIMEOUT_S = 30
+API_MAX_BYTES = 32 << 20  # a 100-entry API page is well under 1 MiB
 PAGE_SIZE = 100
 MAX_PAGES = 30
 PULL_REQUEST_EVENTS = frozenset({"pull_request", "pull_request_target"})
 _BASH_PATH = shutil.which("bash")
 BASH = str(Path(_BASH_PATH).resolve(strict=True)) if _BASH_PATH is not None else None
 
+
+def _https_opener() -> urllib.request.OpenerDirector:
+    """An opener that speaks https only and follows no redirect.
+
+    ``urlopen`` also opens ``file:``, ``ftp:``, ``data:`` and plain ``http:``
+    addresses. This opener has no handler for them, so a caller cannot reach
+    one: the address fails as an unknown URL type. It has no redirect handler
+    either, so a 3xx answer is an ``HTTPError``: urllib's redirect handler
+    would resend the ``Authorization`` header to whichever host the
+    ``Location`` names, and every API these scripts call answers 200 directly.
+    """
+    opener = urllib.request.OpenerDirector()
+    for handler in (
+        urllib.request.ProxyHandler(),
+        urllib.request.UnknownHandler(),
+        urllib.request.HTTPSHandler(),
+        urllib.request.HTTPDefaultErrorHandler(),
+        urllib.request.HTTPErrorProcessor(),
+    ):
+        opener.add_handler(handler)
+    return opener
+
+
+HTTPS_OPENER = _https_opener()
+
 FULL = "full"
 LIGHT = "light"
 RELEASE_LIGHT = "release-light"
@@ -163,23 +190,54 @@ def decide(
     return Decision(LIGHT, "pull request from this repository")
 
 
-def api_request(method: str, url: str, token: str) -> object:
-    """One bounded GitHub API call; the only network access of the tier scripts."""
+def api_request(method: str, url: str, token: str, payload: object | None = None) -> object:
+    """One bounded GitHub API call; the only network access of the tier scripts.
+
+    ``payload`` goes out as the JSON request body; without one a POST sends
+    an empty body.
+    """
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    data = b"" if method == "POST" else None
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    return https_json(method, url, headers, data, API_TIMEOUT_S, API_MAX_BYTES)
+
+
+def https_json(
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    data: bytes | None,
+    timeout_s: float,
+    limit: int,
+) -> object:
+    """One https request whose answer is JSON, bounded in time and in size.
+
+    The scheme check and the size cap live here so every caller gets them; an
+    empty answer reads as an empty object. A broken answer (cut off, a bad
+    status line, an overlong header) raises ``http.client.HTTPException``,
+    which is no ``OSError``; it becomes a ``TierError`` here so every caller
+    treats it as the failed request it is. An error status stays an
+    ``HTTPError`` for the caller to read its code.
+    """
     if urllib.parse.urlsplit(url).scheme != "https":
         raise TierError(f"refusing a non-https API URL: {url}")
     request = urllib.request.Request(  # noqa: S310 - the scheme is checked above
-        url,
-        method=method,
-        data=b"" if method == "POST" else None,
-        headers={
-            "Authorization": f"Bearer {token}",
-            "Accept": "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        },
+        url, method=method, data=data, headers=dict(headers)
     )
-    with urllib.request.urlopen(request, timeout=API_TIMEOUT_S) as response:  # noqa: S310
-        body = response.read().decode("utf-8")
-    return json.loads(body) if body else {}
+    try:
+        with HTTPS_OPENER.open(request, timeout=timeout_s) as response:
+            body = response.read(limit + 1)
+    except http.client.HTTPException as exc:
+        raise TierError(f"{url}: broken answer ({type(exc).__name__}: {exc})") from exc
+    if len(body) > limit:
+        raise TierError(f"{url}: answer larger than {limit} bytes")
+    return json.loads(body.decode("utf-8")) if body else {}
 
 
 def _paged(fetch: Fetcher, path: str) -> list[object]:
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
new file mode 100644
index 0000000000..c646c8d7a5
--- /dev/null
+++ b/scripts/ci/readme_badges.py
@@ -0,0 +1,791 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: EUPL-1.2
+"""Read, publish and judge the README status badges (docs/development/readme-badges.md).
+
+    readme_badges.py spec --spec SPEC.json --state DIR/state.json
+        Read every badge source and write the render list for
+        tools/badges/render.mjs plus the state file. Exit 0 once both exist.
+    readme_badges.py publish --dir DIR
+        Commit DIR/<slug>.svg and DIR/state.json to the badges branch.
+    readme_badges.py verdict --state DIR/state.json
+        Exit 1 when a source failed this run, so the run turns red.
+    readme_badges.py check-readme [--readme README.md]
+        Exit 1 when a README image is not a badge rendered onto this
+        repository's badges branch, a shields.io badge in for-the-badge with
+        the dark label, or a file in the repository. Offline; pre-commit runs
+        it on every README change.
+
+Sources: the latest decisive completed push run of each workflow on the
+default branch (GitHub API with GITHUB_TOKEN), and the OpenSSF Scorecard
+score, OpenSSF Best Practices level and Codacy grade (public APIs, sent no
+token). A source that fails keeps its last value for six hours; after that
+the badge reads "stale". The repository comes from GITHUB_REPOSITORY.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import functools
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from http import HTTPStatus
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from scripts.ci import ci_tier
+from scripts.dev.check_repository_security import POLICY as SECURITY_POLICY
+from scripts.lib.safe_subprocess import (
+    CommandOutputLimitExceeded,
+    CommandTimedOut,
+    CommandValidationError,
+)
+from scripts.lib.safe_subprocess import run as run_command
+
+API = "https://api.github.com"
+BRANCH = "badges"
+STATE = "state.json"
+STALE_AFTER = timedelta(hours=6)
+GIT_TIMEOUT_S = 30
+OBJECT_ID = re.compile(r"[0-9a-f]{40}")
+QUIET_WINDOW = timedelta(hours=1)
+RUNS_PER_PAGE = 30
+PUBLIC_TIMEOUT_S = 20
+MAX_RESPONSE_BYTES = 1 << 20
+MAX_FILE_BYTES = 64 << 10
+
+GREEN = "#1f883d"
+RED = "#cf222e"
+AMBER = "#9a6700"
+GREY = "#6e7781"
+SCORE_MAX = 10  # OpenSSF Scorecard scores run from 0 to 10
+# The unrounded score from which the badge is green: the master requirement in
+# docs/principles.md (ADR-1247). The badge colours the public score only; the
+# exact-head check stays the Scorecard workflow's job.
+SCORE_GREEN = 8.5
+SCORE_AMBER = 4.0  # unrounded score from which it is amber; red below
+TEXT = re.compile(r"[\x20-\x7e]{1,40}")
+COLOR = re.compile(r"#[0-9a-f]{6}")
+
+PASSING = ("passing", GREEN)
+FAILING = ("failing", RED)
+DECISIVE = {
+    "success": PASSING,
+    "failure": FAILING,
+    "timed_out": FAILING,
+    "startup_failure": FAILING,
+}
+# Runs that say nothing about the code: no conclusion yet, cancelled or
+# skipped. The badge looks past them. Any other conclusion of the newest run
+# (action_required, neutral, stale) reads "unknown", never an older run's value.
+# A tuple, not a set: membership then compares and never hashes the API value.
+PASSED_OVER = (None, "cancelled", "skipped")
+UNKNOWN = ("unknown", GREY)
+BEST_PRACTICES = {
+    "in_progress": ("in progress", AMBER),
+    "passing": PASSING,
+    "silver": ("silver", GREEN),
+    "gold": ("gold", GREEN),
+}
+CODACY = {"A": GREEN, "B": GREEN, "C": AMBER, "D": RED, "E": RED, "F": RED}
+
+Value = tuple[str, str]
+GitHub = Callable[[str], object]
+Public = Callable[[str], object]
+Call = Callable[[str, str, object | None], object]
+
+
+class BadgeError(Exception):
+    """A badge source answered something the renderer cannot show."""
+
+
+@dataclass(frozen=True)
+class Badge:
+    """One README badge: its file name, label and where its value comes from."""
+
+    slug: str
+    label: str
+    kind: str
+    workflow: str = ""
+
+
+BADGES = (
+    Badge("tests", "Tests", "workflow", "tests-and-quality-gates.yml"),
+    Badge("builds", "Builds", "workflow", "libvmaf-build-matrix.yml"),
+    Badge("lint", "Lint", "workflow", "lint-and-format.yml"),
+    Badge("ffmpeg", "FFmpeg", "workflow", "ffmpeg-integration.yml"),
+    Badge("go", "Go", "workflow", "go-ci.yml"),
+    Badge("rust", "Rust", "workflow", "rust-ci.yml"),
+    Badge("security", "Security", "workflow", "security-scans.yml"),
+    Badge("scorecard", "OpenSSF Scorecard", "scorecard"),
+    Badge("best-practices", "OpenSSF Best Practices", "best-practices"),
+    Badge("codacy", "Codacy", "codacy"),
+)
+
+
+def stamp(moment: datetime) -> str:
+    """UTC time as the state file stores it."""
+    return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def workflow_value(runs: object) -> Value:
+    """Value of the newest run that has a conclusion and was not cancelled or skipped.
+
+    That run reads "passing" or "failing" when it passed or failed, "unknown"
+    otherwise; so does an answer with no such run.
+    """
+    rows = runs.get("workflow_runs") if isinstance(runs, dict) else None
+    if not isinstance(rows, list):
+        raise BadgeError("the runs answer has no workflow_runs list")
+    for row in rows:
+        conclusion = row.get("conclusion") if isinstance(row, dict) else None
+        if conclusion not in PASSED_OVER:
+            return DECISIVE.get(conclusion, UNKNOWN) if isinstance(conclusion, str) else UNKNOWN
+    return UNKNOWN
+
+
+def scorecard_value(doc: object) -> Value:
+    """OpenSSF Scorecard score out of 10: green from 8.5, amber from 4, red below.
+
+    The colour follows the unrounded score, as the master requirement does, so
+    8.46 reads "8.5 / 10" in amber.
+    """
+    score = doc.get("score") if isinstance(doc, dict) else None
+    if isinstance(score, bool) or not isinstance(score, int | float) or not 0 <= score <= SCORE_MAX:
+        raise BadgeError(f"Scorecard score {score!r} is not a number from 0 to 10")
+    color = GREEN if score >= SCORE_GREEN else AMBER if score >= SCORE_AMBER else RED
+    return (f"{float(score):.1f} / 10", color)
+
+
+def best_practices_value(rows: object, repo_url: str) -> Value:
+    """Badge level of the Best Practices project registered for ``repo_url``."""
+    matches = (
+        [r for r in rows if isinstance(r, dict) and r.get("repo_url") == repo_url]
+        if isinstance(rows, list)
+        else []
+    )
+    if len(matches) != 1:
+        raise BadgeError(f"{len(matches)} Best Practices projects list {repo_url}")
+    level = matches[0].get("badge_level")
+    if level not in BEST_PRACTICES:
+        raise BadgeError(f"Best Practices level {level!r} is not one this badge knows")
+    return BEST_PRACTICES[level]
+
+
+def codacy_value(doc: object) -> Value:
+    """Codacy grade letter: A and B green, C amber, D to F red."""
+    data = doc.get("data") if isinstance(doc, dict) else None
+    letter = data.get("gradeLetter") if isinstance(data, dict) else None
+    if letter not in CODACY:
+        raise BadgeError(f"Codacy grade {letter!r} is not a letter from A to F")
+    return (str(letter), CODACY[letter])
+
+
+def default_branch(github: GitHub, repository: str) -> str:
+    """Name of the repository's default branch, whose push runs the workflow badges show."""
+    doc = github(f"/repos/{repository}")
+    branch = doc.get("default_branch") if isinstance(doc, dict) else None
+    if not isinstance(branch, str) or not branch:
+        raise BadgeError(f"{repository}: the API names no default branch")
+    return branch
+
+
+def read_value(badge: Badge, repository: str, github: GitHub, public: Public) -> Value:
+    """Ask the badge's source for its current value."""
+    if badge.kind == "workflow":
+        branch = default_branch(github, repository)
+        query = urllib.parse.urlencode(
+            {"branch": branch, "event": "push", "status": "completed", "per_page": RUNS_PER_PAGE}
+        )
+        return workflow_value(
+            github(f"/repos/{repository}/actions/workflows/{badge.workflow}/runs?{query}")
+        )
+    owner, name = repository.split("/", 1)
+    if badge.kind == "scorecard":
+        return scorecard_value(
+            public(f"https://api.scorecard.dev/projects/github.com/{repository}")
+        )
+    if badge.kind == "best-practices":
+        repo_url = f"https://github.com/{repository}"
+        query = urllib.parse.urlencode({"url": repo_url})
+        return best_practices_value(
+            public(f"https://www.bestpractices.dev/projects.json?{query}"), repo_url
+        )
+    if badge.kind == "codacy":
+        path = f"organizations/gh/{owner}/repositories/{name}"
+        return codacy_value(public(f"https://app.codacy.com/api/v3/analysis/{path}"))
+    raise BadgeError(f"{badge.slug}: unknown source kind {badge.kind!r}")
+
+
+def usable(entry: object) -> dict[str, str | None] | None:
+    """A previous state entry when its shape is one this script writes, else ``None``."""
+    if not isinstance(entry, dict):
+        return None
+    message, color, fetched = entry.get("message"), entry.get("color"), entry.get("fetched_at")
+    if not (isinstance(message, str) and TEXT.fullmatch(message)):
+        return None
+    if not (isinstance(color, str) and COLOR.fullmatch(color)):
+        return None
+    if fetched is not None and not isinstance(fetched, str):
+        return None
+    return {"message": message, "color": color, "fetched_at": fetched}
+
+
+def read_time(text: str) -> datetime | None:
+    """The time ``text`` names in ISO 8601 with a UTC offset; ``None`` when unreadable or naive."""
+    try:
+        value = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return value if value.utcoffset() is not None else None
+
+
+def carried(previous: Mapping[str, str | None] | None, now: datetime) -> dict[str, str | None]:
+    """Keep the last value up to STALE_AFTER after it was read; then show "stale".
+
+    A read time that is unreadable, names no UTC offset or lies in the future
+    counts as stale.
+    """
+    fetched = previous.get("fetched_at") if previous else None
+    read_at = read_time(fetched) if previous and fetched else None
+    if previous and read_at is not None and timedelta(0) <= now - read_at <= STALE_AFTER:
+        return dict(previous)
+    return {"message": "stale", "color": GREY, "fetched_at": fetched}
+
+
+def refresh(
+    badges: tuple[Badge, ...],
+    previous: Mapping[str, object],
+    now: datetime,
+    read: Callable[[Badge], Value],
+) -> tuple[dict[str, dict[str, str | None]], list[str]]:
+    """New state entries for every badge, and one line per source that failed."""
+    entries: dict[str, dict[str, str | None]] = {}
+    failures: list[str] = []
+    for badge in badges:
+        try:
+            message, color = read(badge)
+        except (BadgeError, ci_tier.TierError, OSError, ValueError, KeyError, TypeError) as error:
+            entries[badge.slug] = carried(usable(previous.get(badge.slug)), now)
+            failures.append(f"{badge.slug}: {error}")
+            continue
+        entries[badge.slug] = {"message": message, "color": color, "fetched_at": stamp(now)}
+    return entries, failures
+
+
+def render_list(
+    badges: tuple[Badge, ...], entries: Mapping[str, Mapping[str, str | None]]
+) -> list[dict[str, str]]:
+    """The list tools/badges/render.mjs takes, in README order."""
+    return [
+        {
+            "slug": b.slug,
+            "label": b.label,
+            "message": str(entries[b.slug]["message"]),
+            "color": str(entries[b.slug]["color"]),
+        }
+        for b in badges
+    ]
+
+
+def public_json(url: str) -> object:
+    """GET a public JSON API without credentials; https only, bounded in time and size."""
+    return ci_tier.https_json(
+        "GET", url, {"Accept": "application/json"}, None, PUBLIC_TIMEOUT_S, MAX_RESPONSE_BYTES
+    )
+
+
+def field(doc: object, *keys: str) -> object:
+    """``doc[key][key]...`` of a JSON answer; BadgeError when a level is missing or no object."""
+    value = doc
+    for key in keys:
+        if not isinstance(value, dict) or key not in value:
+            raise BadgeError(f"the answer has no {'.'.join(keys)}")
+        value = value[key]
+    return value
+
+
+def previous_state(github: GitHub, repository: str) -> tuple[dict[str, object], str | None]:
+    """Badge entries of the badges branch's state file; none when the branch is new.
+
+    A failed read other than a 404 raises BadgeError: refreshing without the
+    last values would turn every failing source "stale" at once, so the run
+    stops and the branch keeps what it has. A file that was read but cannot be
+    parsed holds no value worth keeping; it reads as empty, with a failure line.
+    """
+    try:
+        doc = github(f"/repos/{repository}/contents/{STATE}?ref={BRANCH}")
+    except urllib.error.HTTPError as error:
+        error.close()  # it holds the answer body; the 404 and the raise below end here
+        if error.code == HTTPStatus.NOT_FOUND:
+            return {}, None
+        raise BadgeError(f"{STATE}: {error}; the badges keep their values") from error
+    except (ci_tier.TierError, OSError, ValueError) as error:
+        raise BadgeError(f"{STATE}: {error}; the badges keep their values") from error
+    try:
+        text = base64.b64decode(str(field(doc, "content"))).decode("utf-8")
+        badges = json.loads(text).get("badges")
+    except (BadgeError, TypeError, ValueError, AttributeError) as error:
+        return {}, f"{STATE}: unreadable ({error})"
+    return (badges if isinstance(badges, dict) else {}), None
+
+
+def blob_sha(data: bytes) -> str:
+    """Git object id of a blob holding ``data``, as git computes it (stdin skips filters)."""
+    try:
+        result = run_command(
+            ["git", "hash-object", "--stdin"],
+            allowed_executables=("git",),
+            input_data=data,
+            capture_output=True,
+            timeout_seconds=GIT_TIMEOUT_S,
+        )
+    except (CommandValidationError, CommandTimedOut, CommandOutputLimitExceeded, OSError) as error:
+        raise BadgeError(f"git hash-object: {error}") from error
+    sha = result.stdout.decode("ascii", "replace").strip()
+    if result.returncode or not OBJECT_ID.fullmatch(sha):
+        detail = result.stderr.decode("utf-8", "replace").strip()
+        raise BadgeError(f"git hash-object exited {result.returncode}: {sha or detail}")
+    return sha
+
+
+def collect(directory: Path, badges: tuple[Badge, ...]) -> dict[str, bytes]:
+    """The files to publish: exactly one SVG per badge plus the state file, nothing else."""
+    wanted = {f"{b.slug}.svg" for b in badges} | {STATE}
+    found = {p.name for p in directory.iterdir()}
+    if found != wanted:
+        raise BadgeError(
+            f"{directory}: missing {sorted(wanted - found)}, unexpected {sorted(found - wanted)}"
+        )
+    files: dict[str, bytes] = {}
+    for name in sorted(wanted):
+        path = directory / name
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_FILE_BYTES:
+            raise BadgeError(f"{path}: not a regular file of at most {MAX_FILE_BYTES} bytes")
+        data = path.read_bytes()
+        text = data.decode("utf-8")
+        if name == STATE:
+            json.loads(text)
+        elif not text.startswith("<svg "):
+            raise BadgeError(f"{path}: not an SVG document")
+        files[name] = data
+    return files
+
+
+def branch_head(call: Call, repository: str) -> dict[str, str] | None:
+    """Commit id, tree id and commit time of the badges branch; ``None`` when it does not exist."""
+    try:
+        ref = call("GET", f"/repos/{repository}/git/ref/heads/{BRANCH}", None)
+    except urllib.error.HTTPError as error:
+        if error.code == HTTPStatus.NOT_FOUND:
+            error.close()  # it holds the answer body; the caller never sees this one
+            return None
+        raise
+    sha = str(field(ref, "object", "sha"))
+    commit = call("GET", f"/repos/{repository}/git/commits/{sha}", None)
+    return {
+        "sha": sha,
+        "tree": str(field(commit, "tree", "sha")),
+        "date": str(field(commit, "committer", "date")),
+    }
+
+
+def read_lag(recorded: object, fresh: object) -> timedelta | None:
+    """How far a recorded state entry's read time trails a fresh one's; ``None`` if incomparable.
+
+    Two entries that both lack a read time trail by nothing. An entry this
+    script would not write, or a read time on one side only or unreadable,
+    cannot be compared.
+    """
+    old, new = usable(recorded), usable(fresh)
+    if old is None or new is None:
+        return None
+    old_at, new_at = old["fetched_at"], new["fetched_at"]
+    if old_at is None or new_at is None:
+        return timedelta(0) if old_at == new_at else None
+    then, latest = read_time(old_at), read_time(new_at)
+    return latest - then if then is not None and latest is not None else None
+
+
+def reads_recorded(call: Call, repository: str, files: Mapping[str, bytes]) -> bool:
+    """True when the branch's state file holds every badge's read time well enough.
+
+    Well enough: for the same badges, each recorded read time lies less than
+    QUIET_WINDOW before the one about to be published, and not after it. A
+    source that recovers with its old value thus gets its new read time
+    committed, so a later failure carries that time, not the one from before
+    the outage. An unreadable state on either side means commit.
+    """
+    recorded, problem = previous_state(lambda path: call("GET", path, None), repository)
+    doc = json.loads(files[STATE].decode("utf-8"))
+    fresh = doc.get("badges") if isinstance(doc, dict) else None
+    if problem or not isinstance(fresh, dict) or set(recorded) != set(fresh):
+        return False
+    lags = (read_lag(recorded[slug], entry) for slug, entry in fresh.items())
+    return all(lag is not None and timedelta(0) <= lag < QUIET_WINDOW for lag in lags)
+
+
+def unchanged(
+    call: Call, repository: str, head: Mapping[str, str], files: Mapping[str, bytes], now: datetime
+) -> bool:
+    """True when a commit would add nothing the branch needs.
+
+    That is: the branch's last commit is younger than QUIET_WINDOW, every SVG
+    matches the branch, and the branch's state file already holds each
+    badge's read time to within QUIET_WINDOW (``reads_recorded``). The state
+    file's bytes are not compared, since its run time changes every run. So a
+    carried value's read time trails the newest successful read by less than
+    QUIET_WINDOW, and the commit-age rule keeps the branch's run time and
+    failure list from aging past it either.
+    """
+    committed = read_time(head["date"])
+    if committed is None or now - committed >= QUIET_WINDOW:
+        return False
+    rows = field(call("GET", f"/repos/{repository}/git/trees/{head['tree']}", None), "tree")
+    if not isinstance(rows, list):
+        raise BadgeError("the tree answer has no tree list")
+    current = {str(field(e, "path")): str(field(e, "sha")) for e in rows}
+    if set(current) != set(files):
+        return False
+    svgs = (current[name] == blob_sha(data) for name, data in files.items() if name != STATE)
+    return all(svgs) and reads_recorded(call, repository, files)
+
+
+def publish(call: Call, repository: str, files: Mapping[str, bytes], now: datetime) -> str:
+    """Commit ``files`` as the whole badges tree.
+
+    GitHub signs the commit, and the ref moves only forward.
+    """
+    head = branch_head(call, repository)
+    if head and unchanged(call, repository, head, files, now):
+        return f"unchanged at {head['sha']}"
+    entries = [
+        {"path": name, "mode": "100644", "type": "blob", "content": data.decode("utf-8")}
+        for name, data in sorted(files.items())
+    ]
+    tree = call("POST", f"/repos/{repository}/git/trees", {"tree": entries})
+    message = f"chore(badges): render the README badges at {stamp(now)}"
+    parents = [head["sha"]] if head else []
+    payload = {"message": message, "tree": field(tree, "sha"), "parents": parents}
+    commit = call("POST", f"/repos/{repository}/git/commits", payload)
+    sha = str(field(commit, "sha"))
+    verification = commit.get("verification") if isinstance(commit, dict) else None
+    if not isinstance(verification, dict) or verification.get("verified") is not True:
+        raise BadgeError(f"commit {sha} is not signed by GitHub; the branch stays put")
+    if head:
+        call("PATCH", f"/repos/{repository}/git/refs/heads/{BRANCH}", {"sha": sha, "force": False})
+    else:
+        call("POST", f"/repos/{repository}/git/refs", {"ref": f"refs/heads/{BRANCH}", "sha": sha})
+    return sha
+
+
+# The one README badge design, as an allow-list: a badge rendered onto this
+# repository's badges branch, a shields.io badge in for-the-badge with the dark
+# label, or a file in the repository. Anything else, a reference-style image
+# whose address this check cannot see included, is a fault. The Praetor-managed
+# governance block may also hold this repository's own GitHub workflow badge
+# until Praetor issue 1893 offers the style; then governance_badge() goes.
+FENCE = re.compile(r"^(?P<mark>`{3,}|~{3,})[^\n]*\n.*?^(?P=mark)[ \t]*$", re.M | re.S)
+CODE_SPAN = re.compile(r"`[^`\n]+`")
+MANAGED_BLOCK = re.compile(
+    r"<!-- praetor:readme-governance:start -->.*?<!-- praetor:readme-governance:end -->", re.S
+)
+IMAGE_START = re.compile(r"!\[")
+INLINE_IMAGE = re.compile(r'!\[[^\]\n]*\]\((?P<url>[^)\s]+)(?:[ \t]+"[^"\n]*")?\)')
+REFERENCE_IMAGE = re.compile(r"!\[(?P<alt>[^\]\n]*)\](?:\[(?P<ref>[^\]\n]*)\])?")
+REFERENCE_DEF = re.compile(r"^ {0,3}\[(?P<ref>[^\]\n]+)\]:[ \t]*<?(?P<url>[^\s>]+)>?", re.M)
+HTML_IMAGE = re.compile(r"<(?:img|source)\b[^>]*>", re.I)
+HTML_SOURCE = re.compile(r'\b(?:src|srcset)[ \t]*=[ \t]*"(?P<url>[^"]*)"', re.I)
+REPOSITORY_PART = re.compile(r"[A-Za-z0-9_.-]+")
+LOCAL_IMAGE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_./-]*")
+SHIELDS_HOST = "img.shields.io"
+SHIELDS_DESIGN = {"style": "for-the-badge", "labelColor": "111a35"}
+
+
+@functools.cache
+def home_repository() -> str:
+    """``owner/name`` of this repository, as its security policy file declares it."""
+    try:
+        name = json.loads(SECURITY_POLICY.read_text(encoding="utf-8"))["repository"]
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        raise BadgeError(f"{SECURITY_POLICY}: no repository name ({error})") from error
+    if not isinstance(name, str):
+        raise BadgeError(f"{SECURITY_POLICY}: repository {name!r} is not owner/name")
+    owner, slash, repo = name.partition("/")
+    if not (slash and REPOSITORY_PART.fullmatch(owner) and REPOSITORY_PART.fullmatch(repo)):
+        raise BadgeError(f"{SECURITY_POLICY}: repository {name!r} is not owner/name")
+    return name
+
+
+def repository_pattern() -> str:
+    """This repository's ``owner/name`` as a regex; GitHub matches both case-insensitively."""
+    return f"(?i:{re.escape(home_repository())})"
+
+
+@functools.cache
+def rendered_badge() -> re.Pattern[str]:
+    """A badge rendered onto this repository's badges branch, with its slug."""
+    return re.compile(
+        rf"https://raw\.githubusercontent\.com/{repository_pattern()}/{re.escape(BRANCH)}"
+        r"/(?P<slug>[a-z0-9-]+)\.svg"
+    )
+
+
+@functools.cache
+def governance_badge() -> re.Pattern[str]:
+    """This repository's own Praetor docs workflow badge; only the governance block may show it."""
+    return re.compile(
+        rf"https://github\.com/{repository_pattern()}"
+        r"/actions/workflows/praetor-docs\.yml/badge\.svg"
+    )
+
+
+def blanked(match: re.Match[str]) -> str:
+    """The matched text as spaces, newlines kept, so positions and line numbers stay."""
+    return re.sub(r"[^\n]", " ", match[0])
+
+
+def local_image(url: str) -> bool:
+    """True for a relative path inside the repository: no scheme, no leading slash, no ``..``."""
+    return LOCAL_IMAGE.fullmatch(url) is not None and ".." not in url.split("/")
+
+
+def missing_file(url: str, root: Path) -> str | None:
+    """Why the local image ``url`` shows nothing from ``root``; ``None`` when it is a file there.
+
+    The path is resolved with its symbolic links, so a link that leaves
+    ``root`` is a fault as well.
+    """
+    base = root.resolve()
+    target = (base / url).resolve()
+    if not target.is_relative_to(base):
+        return f"{url}: resolves outside {base}"
+    if not target.is_file():
+        return f"{url}: no such file next to the README"
+    return None
+
+
+def image_fault(url: str, root: Path) -> str | None:
+    """Why the image at ``url`` breaks the one badge design; ``None`` when it keeps it.
+
+    ``root`` is the directory of the README, which relative paths start from.
+    """
+    rendered = rendered_badge().fullmatch(url)
+    if rendered:
+        if rendered["slug"] in {badge.slug for badge in BADGES}:
+            return None
+        return f"{url}: no rendered badge is named {rendered['slug']!r}"
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme == "https" and parts.netloc == SHIELDS_HOST:
+        query = urllib.parse.parse_qs(parts.query, keep_blank_values=True)
+        wrong = [
+            f"{key}={value}" for key, value in SHIELDS_DESIGN.items() if query.get(key) != [value]
+        ]
+        return f"{url}: a shields.io badge needs {' and '.join(wrong)}" if wrong else None
+    if local_image(url):
+        return missing_file(url, root)
+    return f"{url}: not a rendered badge, a for-the-badge shields.io badge or a local image"
+
+
+def image_url(text: str, start: int, refs: Mapping[str, str]) -> str | None:
+    """Address of the Markdown image at ``start``; ``None`` when it names no known reference."""
+    inline = INLINE_IMAGE.match(text, start)
+    if inline:
+        return inline["url"]
+    reference = REFERENCE_IMAGE.match(text, start)
+    if reference is None:
+        return None
+    key = reference["ref"] or reference["alt"]
+    return refs.get(key.strip().lower())
+
+
+def markdown_faults(
+    text: str,
+    span: tuple[int, int],
+    refs: Mapping[str, str],
+    extra: re.Pattern[str] | None,
+    root: Path,
+) -> list[str]:
+    """One line per Markdown image in ``text[span]`` that breaks the design.
+
+    An image whose address ``extra`` matches passes as well.
+    """
+    faults: list[str] = []
+    for found in IMAGE_START.finditer(text, *span):
+        line = text.count("\n", 0, found.start()) + 1
+        url = image_url(text, found.start(), refs)
+        if url is None:
+            faults.append(f"{line}: an image without an inline address this check can read")
+        elif not (extra and extra.fullmatch(url)) and (fault := image_fault(url, root)):
+            faults.append(f"{line}: {fault}")
+    return faults
+
+
+def html_faults(text: str, root: Path) -> list[str]:
+    """One line per HTML ``<img>`` or ``<source>`` that shows anything but a local file."""
+    faults: list[str] = []
+    for tag in HTML_IMAGE.finditer(text):
+        line = text.count("\n", 0, tag.start()) + 1
+        urls = [
+            candidate.split()[0]
+            for source in HTML_SOURCE.finditer(tag[0])
+            for candidate in source["url"].split(",")
+            if candidate.strip()
+        ]
+        if not urls:
+            faults.append(f"{line}: an HTML image without a double-quoted src or srcset")
+        for url in urls:
+            if not local_image(url):
+                faults.append(f"{line}: {url}: an HTML image must be a local file")
+            elif fault := missing_file(url, root):
+                faults.append(f"{line}: {fault}")
+    return faults
+
+
+def design_faults(readme: str, root: Path) -> list[str]:
+    """Every image in ``readme`` that breaks the one badge design, as ``line: reason``.
+
+    ``root`` is the directory of the README, which relative paths start from.
+    """
+    text = CODE_SPAN.sub(blanked, FENCE.sub(blanked, readme))
+    faults: list[str] = []
+    for block in MANAGED_BLOCK.finditer(text):
+        refs = {
+            d["ref"].strip().lower(): d["url"]
+            for d in REFERENCE_DEF.finditer(text, block.start(), block.end())
+        }
+        faults += markdown_faults(text, block.span(), refs, governance_badge(), root)
+    outside = MANAGED_BLOCK.sub(blanked, text)
+    faults += markdown_faults(outside, (0, len(outside)), {}, None, root)
+    faults += html_faults(text, root)
+    return sorted(faults, key=lambda fault: int(fault.split(":", 1)[0]))
+
+
+def cmd_check_readme(args: argparse.Namespace) -> int:
+    """Print every design fault of the README; 1 when there is one."""
+    readme = args.readme.resolve()
+    faults = design_faults(readme.read_text(encoding="utf-8"), readme.parent)
+    for fault in faults:
+        print(f"{args.readme}:{fault}", file=sys.stderr)
+    if faults:
+        print(
+            f"{len(faults)} README images break the one badge design"
+            " (docs/development/readme-badges.md)",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"{args.readme}: every badge has the one design")
+    return 0
+
+
+def write_json(path: Path, doc: object) -> None:
+    """Write ``doc`` as sorted, indented JSON, creating the parent directory."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def cmd_spec(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    """Read every source, then write the render list and the new state."""
+    repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
+
+    @functools.cache
+    def github(path: str) -> object:
+        """GET ``path`` from the GitHub API with the workflow token, once per run."""
+        return ci_tier.api_request("GET", API + path, token)
+
+    previous, problem = previous_state(github, repository)
+    entries, failures = refresh(
+        BADGES, previous, now, lambda b: read_value(b, repository, github, public_json)
+    )
+    failures = ([problem] if problem else []) + failures
+    write_json(args.spec, render_list(BADGES, entries))
+    write_json(
+        args.state,
+        {"version": 1, "generated_at": stamp(now), "failures": failures, "badges": entries},
+    )
+    for line in failures:
+        print(f"::warning title=Badge source failed::{line}")
+    print(
+        f"{len(BADGES) - len(failures)} of {len(BADGES)} badge sources read; state in {args.state}"
+    )
+    return 0
+
+
+def cmd_publish(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    """Commit the rendered SVGs and the state file to the badges branch."""
+    repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
+
+    def call(method: str, path: str, payload: object | None) -> object:
+        """Send one GitHub API request with the workflow token."""
+        return ci_tier.api_request(method, API + path, token, payload)
+
+    print(f"{BRANCH}: {publish(call, repository, collect(args.dir, BADGES), now)}")
+    return 0
+
+
+def cmd_verdict(args: argparse.Namespace) -> int:
+    """Turn the run red, with one annotation per line, when a source failed."""
+    failures = json.loads(args.state.read_text(encoding="utf-8")).get("failures")
+    if not isinstance(failures, list):
+        raise BadgeError(f"{args.state}: no failures list")
+    for line in failures:
+        print(f"::error title=Badge source failed::{line}")
+    if failures:
+        print(
+            f"{len(failures)} badge sources failed;"
+            f" the badges keep their last value up to {STALE_AFTER}"
+        )
+        return 1
+    print("every badge source answered")
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse the four subcommands and their paths."""
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    spec = sub.add_parser("spec", help="read the sources, write the render list and state")
+    spec.add_argument("--spec", type=Path, required=True)
+    spec.add_argument("--state", type=Path, required=True)
+    pub = sub.add_parser("publish", help="commit the rendered badges to the badges branch")
+    pub.add_argument("--dir", type=Path, required=True)
+    verdict = sub.add_parser("verdict", help="fail when a source failed this run")
+    verdict.add_argument("--state", type=Path, required=True)
+    check = sub.add_parser("check-readme", help="fail when a README image breaks the badge design")
+    check.add_argument("--readme", type=Path, default=Path("README.md"))
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None, env: Mapping[str, str] | None = None) -> int:
+    """Run one subcommand; 2 for a missing input or a handled error."""
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    env = os.environ if env is None else env
+    now = datetime.now(UTC)
+    try:
+        if args.command == "verdict":
+            return cmd_verdict(args)
+        if args.command == "check-readme":
+            return cmd_check_readme(args)
+        missing = [k for k in ("GITHUB_REPOSITORY", "GITHUB_TOKEN") if not env.get(k)]
+        if missing:
+            raise BadgeError(f"set {', '.join(missing)}")
+        handler = cmd_spec if args.command == "spec" else cmd_publish
+        return handler(args, env, now)
+    except (BadgeError, ci_tier.TierError, OSError, ValueError, KeyError, TypeError) as error:
+        print(f"readme_badges.py {args.command}: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index b1d838368a..6cc5b3ef3c 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -5,14 +5,18 @@
 
 from __future__ import annotations
 
+import http.client
 import io
 import json
 import os
 import sys
 import tempfile
 import unittest
+import urllib.error
+import urllib.request
 from contextlib import redirect_stderr, redirect_stdout
 from pathlib import Path
+from typing import Any
 from unittest import mock
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
@@ -151,11 +155,184 @@ def test_a_null_payload_means_no_labels(self) -> None:
 
 
 class Api(unittest.TestCase):
+    """``api_request`` sends GitHub API calls over the https-only opener."""
+
     def test_a_non_https_url_is_refused(self) -> None:
         for url in ("http://api.github.com/x", "file:///etc/passwd", "ftp://h/x"):
             with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
                 ci_tier.api_request("GET", url, "t")
 
+    def sent(
+        self, method: str, payload: object | None = None, answer: bytes = b"{}"
+    ) -> tuple[urllib.request.Request, Any]:
+        """The request api_request hands to the https opener, and what it returned."""
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.return_value = answer
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened) as sent:
+            result = ci_tier.api_request(method, "https://api.github.com/x", "t", payload)
+        return sent.call_args.args[0], result
+
+    def test_a_payload_goes_out_as_a_json_body(self) -> None:
+        """A payload goes out as a JSON body with its content type and method."""
+        request, _ = self.sent("PATCH", {"sha": "c1", "force": False})
+        data = request.data
+        if not isinstance(data, bytes):
+            self.fail(f"request body is {type(data).__name__}, not bytes")
+        self.assertEqual(json.loads(data), {"sha": "c1", "force": False})
+        self.assertEqual(request.get_header("Content-type"), "application/json")
+        self.assertEqual(request.get_method(), "PATCH")
+
+    def test_a_post_without_payload_sends_an_empty_body(self) -> None:
+        """A POST without payload sends an empty body and no content type."""
+        request, _ = self.sent("POST")
+        self.assertEqual(request.data, b"")
+        self.assertIsNone(request.get_header("Content-type"))
+
+    def test_a_get_sends_no_body(self) -> None:
+        """A GET sends no body and carries the bearer token."""
+        request, _ = self.sent("GET")
+        self.assertIsNone(request.data)
+        self.assertEqual(request.get_header("Authorization"), "Bearer t")
+
+    def test_an_empty_answer_reads_as_an_empty_object(self) -> None:
+        """An empty answer reads as an empty object."""
+        self.assertEqual(self.sent("GET", answer=b"")[1], {})
+
+
+class HttpsJson(unittest.TestCase):
+    """``https_json`` sends the caller's headers and bounds the answer size."""
+
+    def answer(
+        self, body: bytes, limit: int, headers: dict[str, str] | None = None
+    ) -> tuple[Any, Any, Any]:
+        """https_json's result for ``body`` and the request and read size it used."""
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.return_value = body
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened) as sent:
+            result = ci_tier.https_json("GET", "https://h/x", headers or {}, None, 5, limit)
+        read = opened.__enter__.return_value.read
+        return result, sent.call_args, read.call_args
+
+    def test_an_answer_of_exactly_the_limit_is_read(self) -> None:
+        """An answer of exactly the limit is read, with one byte more requested."""
+        result, opened, read = self.answer(b'{"a":1}', 7)
+        self.assertEqual(result, {"a": 1})
+        self.assertEqual(read.args, (8,))
+        self.assertEqual(opened.kwargs["timeout"], 5)
+
+    def test_an_answer_one_byte_over_the_limit_is_refused(self) -> None:
+        """An answer one byte over the limit is refused."""
+        with self.assertRaisesRegex(ci_tier.TierError, "larger than 6 bytes"):
+            self.answer(b'{"a":1}', 6)
+
+    def test_the_caller_headers_go_out_and_nothing_else(self) -> None:
+        """Only the caller's headers go out; no Authorization is added."""
+        _, opened, _ = self.answer(b"{}", 10, {"Accept": "application/json"})
+        request = opened.args[0]
+        self.assertEqual(request.get_header("Accept"), "application/json")
+        self.assertIsNone(request.get_header("Authorization"))
+
+    def test_a_broken_answer_is_a_tier_error(self) -> None:
+        """A cut-off body or a broken status line on open or read is a TierError."""
+        for where, error in (
+            ("read", http.client.IncompleteRead(b"par")),
+            ("read", http.client.LineTooLong("header line")),
+            ("open", http.client.BadStatusLine("x")),
+            ("open", http.client.RemoteDisconnected("closed")),
+        ):
+            with self.subTest(where=where, error=type(error).__name__):
+                opened = mock.MagicMock()
+                opened.__enter__.return_value.read.side_effect = error
+                kind = {"return_value": opened} if where == "read" else {"side_effect": error}
+                with (
+                    mock.patch.object(ci_tier.HTTPS_OPENER, "open", **kind),
+                    self.assertRaisesRegex(ci_tier.TierError, type(error).__name__),
+                ):
+                    ci_tier.https_json("GET", "https://h/x", {}, None, 5, 10)
+
+    def test_an_error_status_stays_an_http_error(self) -> None:
+        """An error status is not turned into a TierError; callers read its code."""
+        error = urllib.error.HTTPError("https://h/x", 404, "Not Found", None, None)  # type: ignore[arg-type]
+        with (
+            mock.patch.object(ci_tier.HTTPS_OPENER, "open", side_effect=error),
+            self.assertRaises(urllib.error.HTTPError) as raised,
+        ):
+            ci_tier.https_json("GET", "https://h/x", {}, None, 5, 10)
+        self.assertEqual(raised.exception.code, 404)
+        raised.exception.close()
+
+    def test_a_non_https_url_is_refused_before_any_request(self) -> None:
+        """A non-https URL is refused before the opener is called."""
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
+            for url in ("http://h/x", "file:///etc/passwd"):
+                with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
+                    ci_tier.https_json("GET", url, {}, None, 5, 10)
+        sent.assert_not_called()
+
+
+class HttpsOpener(unittest.TestCase):
+    """The shared opener speaks https only and follows no redirect."""
+
+    @staticmethod
+    def response(code: int, location: str | None = None) -> mock.Mock:
+        """A stand-in for an https answer with ``code`` and an optional Location."""
+        headers = http.client.HTTPMessage()
+        if location is not None:
+            headers["Location"] = location
+        answer = mock.Mock(code=code, msg="status")
+        answer.info.return_value = headers
+        return answer
+
+    def test_an_https_address_reaches_the_https_handler(self) -> None:
+        """An https address reaches the https handler unchanged."""
+        answer = self.response(200)
+        with mock.patch.object(
+            urllib.request.HTTPSHandler, "https_open", return_value=answer
+        ) as https_open:
+            self.assertIs(ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1), answer)
+        self.assertEqual(https_open.call_args.args[0].full_url, "https://h/x")
+
+    def test_a_non_https_address_fails_without_being_opened(self) -> None:
+        """Every other scheme fails as an unknown url type."""
+        for url in ("file:///etc/passwd", "data:text/plain,x", "ftp://h/x", "http://h/x"):
+            with (
+                self.subTest(url=url),
+                self.assertRaisesRegex(urllib.error.URLError, "unknown url type"),
+            ):
+                ci_tier.HTTPS_OPENER.open(url, timeout=1)
+
+    def test_a_redirect_is_not_followed(self) -> None:
+        """Every 3xx answer is an HTTPError after exactly one request."""
+        # An https target too: following it would resend the Authorization header.
+        targets = ("https://other.example/y", "http://h/y", "ftp://h/y", "file:///etc/passwd")
+        for code in (301, 302, 307, 308):
+            for target in targets:
+                with (
+                    self.subTest(code=code, target=target),
+                    mock.patch.object(
+                        urllib.request.HTTPSHandler,
+                        "https_open",
+                        return_value=self.response(code, target),
+                    ) as https_open,
+                ):
+                    with self.assertRaises(urllib.error.HTTPError) as raised:
+                        ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
+                    raised.exception.close()
+                    self.assertEqual(raised.exception.code, code)
+                    self.assertEqual(https_open.call_count, 1)
+
+    def test_an_error_answer_is_an_http_error(self) -> None:
+        """A 404 answer is an HTTPError."""
+        with (
+            mock.patch.object(
+                urllib.request.HTTPSHandler, "https_open", return_value=self.response(404)
+            ),
+            self.assertRaises(urllib.error.HTTPError) as raised,
+        ):
+            ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
+        raised.exception.close()
+        self.assertEqual(raised.exception.code, 404)
+
 
 class Config(unittest.TestCase):
     def write(self, text: str) -> Path:
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
new file mode 100644
index 0000000000..558e690ac9
--- /dev/null
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -0,0 +1,1270 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: EUPL-1.2
+"""Positive, negative and boundary cases for scripts/ci/readme_badges.py."""
+
+from __future__ import annotations
+
+import base64
+import email.message
+import http.client
+import io
+import json
+import re
+import secrets
+import sys
+import tempfile
+import unittest
+import urllib.error
+from collections.abc import Callable
+from contextlib import redirect_stderr, redirect_stdout
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any, ClassVar
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from scripts.ci import ci_tier
+from scripts.ci import readme_badges as rb
+from scripts.lib.safe_subprocess import CommandValidationError
+
+ROOT = Path(__file__).resolve().parents[3]
+NOW = datetime(2026, 11, 10, 12, 0, tzinfo=UTC)
+REPO = "VMAFx/vmafx"
+RAW = re.compile(
+    r"\[!\[(?P<alt>[^\]]+)\]\(https://raw\.githubusercontent\.com/VMAFx/vmafx/badges/"
+    r"(?P<slug>[a-z0-9-]+)\.svg\)\]"
+)
+
+
+def runs(*conclusions: object) -> dict[str, object]:
+    """A workflow-runs answer with one run per conclusion, newest first."""
+    return {"workflow_runs": [{"conclusion": c} for c in conclusions]}
+
+
+def commit_answering(answer: object, call: rb.Call) -> rb.Call:
+    """``call``, except that creating a commit answers ``answer``."""
+
+    def answered(method: str, path: str, payload: object) -> object:
+        """Answer ``answer`` to the commit request; pass every other call on."""
+        if path.endswith("/git/commits"):
+            return answer
+        return call(method, path, payload)
+
+    return answered
+
+
+def state_file(fetched_at: str | None, slug: str = "go") -> bytes:
+    """A state file holding one passing badge read at ``fetched_at``."""
+    entry = {"message": "passing", "color": rb.GREEN, "fetched_at": fetched_at}
+    return json.dumps({"version": 1, "badges": {slug: entry}}).encode("utf-8")
+
+
+def http_error(code: int) -> urllib.error.HTTPError:
+    """An HTTPError with ``code`` and an empty body, as urllib raises it."""
+    return urllib.error.HTTPError(
+        "https://api.github.com/x", code, "x", email.message.Message(), None
+    )
+
+
+def entry(
+    message: str = "passing", color: str = rb.GREEN, fetched: str | None = None
+) -> dict[str, str | None]:
+    """A state entry as ``refresh`` writes it, read at ``NOW`` unless ``fetched`` is set."""
+    return {"message": message, "color": color, "fetched_at": fetched or rb.stamp(NOW)}
+
+
+class WorkflowValue(unittest.TestCase):
+    """A workflow badge reads the newest decisive run."""
+
+    def test_success_is_passing(self) -> None:
+        """A successful newest run reads passing."""
+        self.assertEqual(rb.workflow_value(runs("success")), rb.PASSING)
+
+    def test_every_failing_conclusion_is_failing(self) -> None:
+        """failure, timed_out and startup_failure all read failing."""
+        for conclusion in ("failure", "timed_out", "startup_failure"):
+            with self.subTest(conclusion=conclusion):
+                self.assertEqual(rb.workflow_value(runs(conclusion, "success")), rb.FAILING)
+
+    def test_an_unfinished_or_cancelled_run_does_not_mask_a_failure(self) -> None:
+        """Runs without a conclusion, cancelled and skipped runs are passed over."""
+        # Planted case of the red-reader miss: the newest run had no conclusion yet.
+        answer = runs(None, "cancelled", "skipped", "failure", "success")
+        self.assertEqual(rb.workflow_value(answer), rb.FAILING)
+
+    def test_any_other_newest_conclusion_is_unknown_not_an_older_value(self) -> None:
+        """Any other conclusion reads unknown; an older success never stands in."""
+        # Planted case from the pull request 3393 review: action_required read
+        # as the older success behind it.
+        conclusions: tuple[object, ...] = (
+            "action_required",
+            "neutral",
+            "stale",
+            "new_kind",
+            7,
+            ["x"],
+            {},
+        )
+        for conclusion in conclusions:
+            with self.subTest(conclusion=conclusion):
+                answer = runs("cancelled", conclusion, "success")
+                self.assertEqual(rb.workflow_value(answer), ("unknown", rb.GREY))
+
+    def test_no_decisive_run_is_unknown(self) -> None:
+        """No run, or only passed-over runs, reads unknown."""
+        self.assertEqual(rb.workflow_value(runs()), ("unknown", rb.GREY))
+        self.assertEqual(rb.workflow_value(runs("cancelled", None)), ("unknown", rb.GREY))
+
+    def test_a_row_that_is_not_an_object_is_skipped(self) -> None:
+        """A run row that is not an object is passed over."""
+        answer = {"workflow_runs": ["x", 3, {"conclusion": "success"}]}
+        self.assertEqual(rb.workflow_value(answer), rb.PASSING)
+
+    def test_an_answer_without_a_run_list_is_refused(self) -> None:
+        """An answer without a ``workflow_runs`` list is a badge error."""
+        answers: tuple[object, ...] = ({}, [], None, {"workflow_runs": {}})
+        for answer in answers:
+            with self.subTest(answer=answer), self.assertRaises(rb.BadgeError):
+                rb.workflow_value(answer)
+
+
+class ScorecardValue(unittest.TestCase):
+    """The Scorecard badge shows the score with one decimal and the master colour."""
+
+    def test_colour_boundaries(self) -> None:
+        """The colour follows the unrounded score, green from 8.5, amber from 4.0."""
+        # Green from the unrounded 8.5 of docs/principles.md (ADR-1247), so a
+        # score shown as "8.5" can still be amber.
+        cases = {
+            10: ("10.0 / 10", rb.GREEN),
+            8.5: ("8.5 / 10", rb.GREEN),
+            8.46: ("8.5 / 10", rb.AMBER),
+            7.0: ("7.0 / 10", rb.AMBER),
+            6.96: ("7.0 / 10", rb.AMBER),
+            4: ("4.0 / 10", rb.AMBER),
+            3.96: ("4.0 / 10", rb.RED),
+            3.9: ("3.9 / 10", rb.RED),
+            0: ("0.0 / 10", rb.RED),
+        }
+        for score, want in cases.items():
+            with self.subTest(score=score):
+                self.assertEqual(rb.scorecard_value({"score": score}), want)
+
+    def test_a_score_outside_zero_to_ten_or_not_a_number_is_refused(self) -> None:
+        """A score that is not a finite number from 0 to 10 is refused."""
+        for score in (True, False, "8.9", None, -0.1, 10.01, float("nan"), float("inf")):
+            with self.subTest(score=score), self.assertRaises(rb.BadgeError):
+                rb.scorecard_value({"score": score})
+
+    def test_an_answer_that_is_not_an_object_is_refused(self) -> None:
+        """An answer that is not an object is refused."""
+        with self.assertRaises(rb.BadgeError):
+            rb.scorecard_value([8.9])
+
+    def test_green_starts_at_the_master_requirement(self) -> None:
+        """The green threshold is the score docs/principles.md requires."""
+        principles = (ROOT / "docs/principles.md").read_text(encoding="utf-8")
+        self.assertIn(f"{rb.SCORE_GREEN}", principles)
+
+
+class BestPracticesValue(unittest.TestCase):
+    """The Best Practices badge shows the level of the one listed project."""
+
+    URL = "https://github.com/VMAFx/vmafx"
+
+    def rows(self, *levels: str) -> list[dict[str, str]]:
+        """One Best Practices row for this repository per level."""
+        return [{"repo_url": self.URL, "badge_level": level} for level in levels]
+
+    def test_every_known_level(self) -> None:
+        """Every known level maps to its message and colour."""
+        for level, want in rb.BEST_PRACTICES.items():
+            with self.subTest(level=level):
+                self.assertEqual(rb.best_practices_value(self.rows(level), self.URL), want)
+
+    def test_exactly_one_project_must_list_the_repository(self) -> None:
+        """No match, another repository or two matches are refused."""
+        other = [{"repo_url": "https://github.com/Netflix/vmaf", "badge_level": "passing"}]
+        for rows in ([], other, self.rows("passing", "gold"), {"repo_url": self.URL}, None):
+            with self.subTest(rows=rows), self.assertRaises(rb.BadgeError):
+                rb.best_practices_value(rows, self.URL)
+
+    def test_an_unknown_level_is_refused(self) -> None:
+        """A level outside the known ones is refused."""
+        for level in ("platinum", None, ""):
+            with self.subTest(level=level), self.assertRaises(rb.BadgeError):
+                rb.best_practices_value([{"repo_url": self.URL, "badge_level": level}], self.URL)
+
+
+class CodacyValue(unittest.TestCase):
+    """The Codacy badge shows the grade letter."""
+
+    def test_every_grade_letter(self) -> None:
+        """Every letter from A to F maps to its colour."""
+        for letter, color in rb.CODACY.items():
+            with self.subTest(letter=letter):
+                want = (letter, color)
+                self.assertEqual(rb.codacy_value({"data": {"gradeLetter": letter}}), want)
+        self.assertEqual(rb.CODACY["B"], rb.GREEN)
+        self.assertEqual(rb.CODACY["C"], rb.AMBER)
+        self.assertEqual(rb.CODACY["D"], rb.RED)
+
+    def test_anything_but_a_letter_from_a_to_f_is_refused(self) -> None:
+        """Anything but an upper-case letter from A to F is refused."""
+        docs: tuple[object, ...] = (
+            {"data": {"gradeLetter": "G"}},
+            {"data": {"gradeLetter": "a"}},
+            {"data": {}},
+            {},
+            [],
+        )
+        for doc in docs:
+            with self.subTest(doc=doc), self.assertRaises(rb.BadgeError):
+                rb.codacy_value(doc)
+
+
+class ReadValue(unittest.TestCase):
+    """``read_value`` asks the right source for each badge kind."""
+
+    def github(self, paths: list[str], branch: object = "master") -> rb.GitHub:
+        """A GitHub stub that records each path and answers one successful run."""
+
+        def fetch(path: str) -> object:
+            """Record ``path``; answer the repository or the run list."""
+            paths.append(path)
+            return {"default_branch": branch} if path == f"/repos/{REPO}" else runs("success")
+
+        return fetch
+
+    def test_a_workflow_badge_reads_completed_push_runs_on_the_default_branch(self) -> None:
+        """The run query names the default branch, push, completed and 30 runs."""
+        paths: list[str] = []
+        badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
+        value = rb.read_value(badge, REPO, self.github(paths), self.fail)
+        self.assertEqual(value, rb.PASSING)
+        query = paths[1].split("?", 1)[1]
+        self.assertIn("/actions/workflows/lint-and-format.yml/runs?", paths[1])
+        self.assertEqual(query, "branch=master&event=push&status=completed&per_page=30")
+
+    def test_a_repository_without_a_default_branch_is_refused(self) -> None:
+        """A missing or non-string default branch is a badge error."""
+        badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
+        for branch in ("", None, 3):
+            with self.subTest(branch=branch), self.assertRaises(rb.BadgeError):
+                rb.read_value(badge, REPO, self.github([], branch), lambda url: {})
+
+    def test_public_sources_get_their_own_urls_and_no_github_call(self) -> None:
+        """Scorecard, Best Practices and Codacy are read from their own URLs only."""
+        answers = {
+            "https://api.scorecard.dev/projects/github.com/VMAFx/vmafx": {"score": 8.9},
+            "https://www.bestpractices.dev/projects.json?url=https%3A%2F%2Fgithub.com%2FVMAFx%2Fvmafx": [
+                {"repo_url": "https://github.com/VMAFx/vmafx", "badge_level": "passing"}
+            ],
+            "https://app.codacy.com/api/v3/analysis/organizations/gh/VMAFx/repositories/vmafx": {
+                "data": {"gradeLetter": "A"}
+            },
+        }
+        public = answers.__getitem__
+        for badge in rb.BADGES:
+            if badge.kind != "workflow":
+                with self.subTest(badge=badge.slug):
+                    rb.read_value(badge, REPO, self.fail, public)
+
+    def test_an_unknown_kind_is_refused(self) -> None:
+        """A badge kind the script does not know is refused."""
+        with self.assertRaises(rb.BadgeError):
+            rb.read_value(rb.Badge("x", "X", "rss"), REPO, lambda p: {}, lambda u: {})
+
+
+class Usable(unittest.TestCase):
+    """``usable`` accepts only entries this script could have written."""
+
+    def test_an_entry_this_script_writes_is_usable(self) -> None:
+        """A written entry passes, and a missing read time becomes None."""
+        self.assertEqual(rb.usable(entry()), entry())
+        self.assertEqual(
+            rb.usable({"message": "x" * 40, "color": rb.RED}),
+            {"message": "x" * 40, "color": rb.RED, "fetched_at": None},
+        )
+
+    def test_a_malformed_entry_is_not(self) -> None:
+        """Bad text, colour, time type or shape gives None."""
+        for bad in (
+            entry(message=""),
+            entry(message="x" * 41),
+            entry(message="café"),
+            entry(color="red"),
+            entry(color="#1F883D"),
+            {**entry(), "fetched_at": 3},
+            "passing",
+            None,
+        ):
+            with self.subTest(bad=bad):
+                self.assertIsNone(rb.usable(bad))
+
+
+class Carried(unittest.TestCase):
+    """A failed source keeps its last value for six hours, then reads stale."""
+
+    def test_a_value_is_kept_up_to_exactly_six_hours(self) -> None:
+        """A value read exactly six hours ago is still shown."""
+        fetched = rb.stamp(NOW - rb.STALE_AFTER)
+        self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
+
+    def test_one_second_past_six_hours_reads_stale(self) -> None:
+        """One second past six hours reads stale in grey and keeps the read time."""
+        fetched = rb.stamp(NOW - rb.STALE_AFTER - timedelta(seconds=1))
+        got = rb.carried(entry(fetched=fetched), NOW)
+        self.assertEqual(got, {"message": "stale", "color": rb.GREY, "fetched_at": fetched})
+
+    def test_a_future_or_unreadable_time_reads_stale(self) -> None:
+        """A future, unreadable or naive read time reads stale."""
+        # The naive times are planted cases from the pull request 3393 review:
+        # they raised TypeError and stopped the run.
+        naive = ("2026-11-10T12:00:00", "2026-11-10")
+        for fetched in (rb.stamp(NOW + timedelta(seconds=1)), "yesterday", *naive):
+            with self.subTest(fetched=fetched):
+                self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "stale")
+
+    def test_a_time_with_any_utc_offset_is_read(self) -> None:
+        """A read time with any UTC offset counts."""
+        for fetched in ("2026-11-10T13:00:00+01:00", "2026-11-10T12:00:00+00:00"):
+            with self.subTest(fetched=fetched):
+                self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
+
+    def test_read_time_needs_an_offset(self) -> None:
+        """``read_time`` returns None for a time without an offset."""
+        self.assertEqual(rb.read_time(rb.stamp(NOW)), NOW)
+        for text in ("2026-11-10T12:00:00", "2026-11-10", "", "noon"):
+            with self.subTest(text=text):
+                self.assertIsNone(rb.read_time(text))
+
+    def test_no_previous_value_reads_stale(self) -> None:
+        """No previous entry, or one without a read time, reads stale."""
+        self.assertEqual(rb.carried(None, NOW)["message"], "stale")
+        self.assertEqual(
+            rb.carried({"message": "passing", "fetched_at": None}, NOW)["message"], "stale"
+        )
+
+
+class Refresh(unittest.TestCase):
+    """``refresh`` reads every badge and carries the ones whose source failed."""
+
+    BADGE = (rb.Badge("go", "Go", "workflow", "go-ci.yml"),)
+
+    def test_a_source_that_answers_gets_a_new_time(self) -> None:
+        """An answering source is stored with the current read time."""
+        entries, failures = rb.refresh(self.BADGE, {}, NOW, lambda b: rb.FAILING)
+        self.assertEqual(
+            entries["go"], {"message": "failing", "color": rb.RED, "fetched_at": rb.stamp(NOW)}
+        )
+        self.assertEqual(failures, [])
+
+    def test_a_failing_source_keeps_its_last_value_and_is_reported(self) -> None:
+        """Each expected error keeps the last value and adds one failure line."""
+        previous = {"go": entry(fetched=rb.stamp(NOW - timedelta(hours=1)))}
+        for error in (
+            rb.BadgeError("b"),
+            OSError("o"),
+            ValueError("v"),
+            KeyError("k"),
+            TypeError("t"),
+            ci_tier.TierError("too large"),
+        ):
+            with self.subTest(error=type(error).__name__):
+
+                def read(badge: rb.Badge, error: Exception = error) -> rb.Value:
+                    """Raise the planted ``error``."""
+                    raise error
+
+                entries, failures = rb.refresh(self.BADGE, previous, NOW, read)
+                self.assertEqual(entries["go"]["message"], "passing")
+                self.assertEqual(len(failures), 1)
+                self.assertTrue(failures[0].startswith("go: "))
+
+    def test_a_cut_off_answer_keeps_the_last_value(self) -> None:
+        """A source whose answer breaks off mid-body keeps its last value."""
+        previous = {"go": entry(fetched=rb.stamp(NOW - timedelta(hours=1)))}
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.side_effect = http.client.IncompleteRead(b"par")
+
+        def read(badge: rb.Badge) -> rb.Value:
+            """Read a public source the way the real readers do."""
+            rb.public_json("https://h/x")
+            return rb.PASSING
+
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened):
+            entries, failures = rb.refresh(self.BADGE, previous, NOW, read)
+        self.assertEqual(entries["go"]["message"], "passing")
+        self.assertEqual(len(failures), 1)
+        self.assertIn("IncompleteRead", failures[0])
+
+    def test_an_unexpected_error_is_not_swallowed(self) -> None:
+        """An error outside the expected kinds propagates."""
+
+        def read(badge: rb.Badge) -> rb.Value:
+            """Raise an error the script does not expect."""
+            raise RuntimeError("bug")
+
+        with self.assertRaises(RuntimeError):
+            rb.refresh(self.BADGE, {}, NOW, read)
+
+    def test_the_render_list_keeps_readme_order(self) -> None:
+        """The render list follows BADGES and holds only the four render keys."""
+        entries = {b.slug: entry() for b in rb.BADGES}
+        rendered = rb.render_list(rb.BADGES, entries)
+        self.assertEqual([r["slug"] for r in rendered], [b.slug for b in rb.BADGES])
+        self.assertEqual(set(rendered[0]), {"slug", "label", "message", "color"})
+
+
+class PreviousState(unittest.TestCase):
+    """``previous_state`` reads state.json from the badges branch or stops the run."""
+
+    def fetch(self, answer: object) -> rb.GitHub:
+        """A GitHub stub that checks the state path and answers or raises ``answer``."""
+
+        def github(path: str) -> object:
+            """Check the state path, then raise or return the planted answer."""
+            self.assertEqual(path, f"/repos/{REPO}/contents/state.json?ref=badges")
+            if isinstance(answer, Exception):
+                raise answer
+            return answer
+
+        return github
+
+    def test_a_new_branch_has_no_state_and_no_problem(self) -> None:
+        """A 404 means a new branch: empty state and no problem."""
+        self.assertEqual(rb.previous_state(self.fetch(http_error(404)), REPO), ({}, None))
+
+    def test_a_handled_error_is_closed(self) -> None:
+        """Both the 404 and the failing 500 answer are closed."""
+        missing = http_error(404)
+        rb.previous_state(self.fetch(missing), REPO)
+        self.assertTrue(missing.fp.closed)
+        failed = http_error(500)
+        with self.assertRaises(rb.BadgeError):
+            rb.previous_state(self.fetch(failed), REPO)
+        self.assertTrue(failed.fp.closed)
+
+    def test_a_broken_state_answer_stops_the_run(self) -> None:
+        """A state.json answer with a broken status line stops the run, not a crash."""
+
+        def github(path: str) -> object:
+            """Read the state file through the real API helper."""
+            return ci_tier.api_request("GET", "https://api.github.com" + path, "t")
+
+        with (
+            mock.patch.object(
+                ci_tier.HTTPS_OPENER, "open", side_effect=http.client.BadStatusLine("x")
+            ),
+            self.assertRaisesRegex(rb.BadgeError, "BadStatusLine"),
+        ):
+            rb.previous_state(github, REPO)
+
+    def test_the_badges_of_the_state_file_are_read(self) -> None:
+        """The badges object of state.json is returned."""
+        text = json.dumps({"badges": {"go": entry()}}).encode()
+        doc = {"content": base64.b64encode(text).decode()}
+        self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({"go": entry()}, None))
+
+    def test_a_failed_read_stops_the_run(self) -> None:
+        """Any read failure but 404 raises, so nothing is published."""
+        # Planted case from the pull request 3393 review: a failed read returned
+        # no state, so every failing source turned "stale" at once.
+        failed = (http_error(500), OSError("down"), ci_tier.TierError("too large"), ValueError("x"))
+        for answer in failed:
+            with (
+                self.subTest(answer=type(answer).__name__),
+                self.assertRaisesRegex(rb.BadgeError, "the badges keep their values"),
+            ):
+                rb.previous_state(self.fetch(answer), REPO)
+
+    def test_an_unreadable_state_is_a_problem_not_a_crash(self) -> None:
+        """Content that cannot be decoded gives empty state and a problem."""
+        for answer in ({}, {"content": "!!"}, {"content": ""}, {"content": 7}):
+            with self.subTest(answer=answer):
+                badges, problem = rb.previous_state(self.fetch(answer), REPO)
+                self.assertEqual(badges, {})
+                self.assertIsNotNone(problem)
+
+    def test_a_badges_field_that_is_not_an_object_is_empty(self) -> None:
+        """A badges field that is not an object reads as empty."""
+        doc = {"content": base64.b64encode(b'{"badges": []}').decode()}
+        self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({}, None))
+
+
+class Field(unittest.TestCase):
+    """``field`` walks nested objects or names the missing key."""
+
+    def test_a_nested_value_is_returned(self) -> None:
+        """Each key goes one level down."""
+        self.assertEqual(rb.field({"a": {"b": "c"}}, "a", "b"), "c")
+
+    def test_no_keys_returns_the_document(self) -> None:
+        """Without keys the document itself is returned."""
+        self.assertEqual(rb.field([1], *()), [1])
+
+    def test_a_missing_or_non_object_level_is_refused(self) -> None:
+        """A missing key or a non-object level names the dotted path."""
+        docs: tuple[object, ...] = ({}, {"a": {}}, {"a": "b"}, {"a": None}, [], None)
+        for doc in docs:
+            with self.subTest(doc=doc), self.assertRaisesRegex(rb.BadgeError, "no a.b"):
+                rb.field(doc, "a", "b")
+
+
+class PublicJson(unittest.TestCase):
+    """Public sources get an https request with no token."""
+
+    def test_a_public_source_gets_no_token_and_the_badge_bounds(self) -> None:
+        """Only an Accept header goes out, with the badge timeout and size limit."""
+        with mock.patch.object(ci_tier, "https_json", return_value={"score": 7}) as sent:
+            self.assertEqual(rb.public_json("https://api.scorecard.dev/x"), {"score": 7})
+        method, url, headers, data, timeout, limit = sent.call_args.args
+        self.assertEqual((method, url, data), ("GET", "https://api.scorecard.dev/x", None))
+        self.assertEqual(headers, {"Accept": "application/json"})
+        self.assertEqual((timeout, limit), (rb.PUBLIC_TIMEOUT_S, rb.MAX_RESPONSE_BYTES))
+
+    def test_a_non_https_source_is_refused_before_any_request(self) -> None:
+        """An http URL is refused before the opener is called."""
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
+            with self.assertRaises(ci_tier.TierError):
+                rb.public_json("http://api.scorecard.dev/x")
+        sent.assert_not_called()
+
+
+class Collect(unittest.TestCase):
+    """``collect`` takes exactly the rendered SVGs and the state file."""
+
+    def setUp(self) -> None:
+        """Write one SVG per badge and an empty state file."""
+        self.dir = Path(self.enterContext(tempfile.TemporaryDirectory()))
+        for badge in rb.BADGES:
+            (self.dir / f"{badge.slug}.svg").write_text('<svg xmlns="x"></svg>\n', encoding="utf-8")
+        (self.dir / "state.json").write_text("{}\n", encoding="utf-8")
+
+    def test_one_svg_per_badge_and_the_state_file(self) -> None:
+        """The collected tree holds every SVG and state.json."""
+        self.assertEqual(len(rb.collect(self.dir, rb.BADGES)), len(rb.BADGES) + 1)
+
+    def test_a_missing_or_unexpected_file_is_refused(self) -> None:
+        """An extra file or a missing SVG is refused."""
+        (self.dir / "extra.svg").write_text("<svg ></svg>", encoding="utf-8")
+        with self.assertRaisesRegex(rb.BadgeError, "unexpected"):
+            rb.collect(self.dir, rb.BADGES)
+        (self.dir / "extra.svg").unlink()
+        (self.dir / "go.svg").unlink()
+        with self.assertRaisesRegex(rb.BadgeError, "missing"):
+            rb.collect(self.dir, rb.BADGES)
+
+    def test_a_symlink_a_large_file_or_a_non_svg_is_refused(self) -> None:
+        """A symbolic link, an oversized file or a non-SVG file is refused."""
+        target = self.dir / "go.svg"
+
+        def relink() -> None:
+            """Replace go.svg with a link to lint.svg."""
+            target.unlink()
+            target.symlink_to(self.dir / "lint.svg")
+
+        cases: tuple[Callable[[], object], ...] = (
+            relink,
+            lambda: target.write_text("<svg " + "x" * rb.MAX_FILE_BYTES, encoding="utf-8"),
+            lambda: target.write_text("<html></html>", encoding="utf-8"),
+        )
+        for plant in cases:
+            with self.subTest(plant=plant):
+                target.unlink()
+                target.write_text("<svg ></svg>", encoding="utf-8")
+                plant()
+                with self.assertRaises(rb.BadgeError):
+                    rb.collect(self.dir, rb.BADGES)
+
+    def test_a_state_file_that_is_not_json_is_refused(self) -> None:
+        """A state.json that is not JSON is refused."""
+        (self.dir / "state.json").write_text("{", encoding="utf-8")
+        with self.assertRaises(ValueError):
+            rb.collect(self.dir, rb.BADGES)
+
+
+class Publish(unittest.TestCase):
+    """``publish`` writes one signed commit and moves the badges branch forward only."""
+
+    FILES: ClassVar[dict[str, bytes]] = {
+        "go.svg": b"<svg >go</svg>",
+        "state.json": state_file(rb.stamp(NOW)),
+    }
+    OLD = rb.stamp(NOW - rb.QUIET_WINDOW)
+
+    def fake(
+        self,
+        head: str | None,
+        date: str = OLD,
+        verified: bool = True,
+        tree_files: dict[str, bytes] | None = None,
+        state: bytes | None = None,
+    ) -> tuple[rb.Call, list[tuple[str, str, Any]]]:
+        """A GitHub stub for ``publish`` that records each call; no ``head`` means no branch.
+
+        ``state`` is the branch's state file, by default the one in ``FILES``.
+        """
+        calls: list[tuple[str, str, Any]] = []
+        tree_files = self.FILES if tree_files is None else tree_files
+        state = self.FILES["state.json"] if state is None else state
+
+        def call(method: str, path: str, payload: object) -> object:
+            """Record the call; answer the state file read like the contents API."""
+            calls.append((method, path, payload))
+            if path == f"/repos/{REPO}/contents/state.json?ref=badges":
+                return {"content": base64.b64encode(state).decode("ascii")}
+            return git(path)
+
+        def git(path: str) -> object:
+            """Answer like the Git data API."""
+            if path.endswith("/git/ref/heads/badges"):
+                if head is None:
+                    raise http_error(404)
+                return {"object": {"sha": head}}
+            if "/git/commits/" in path:
+                return {"tree": {"sha": "t0"}, "committer": {"date": date}}
+            if "/git/trees/" in path:
+                return {"tree": [{"path": n, "sha": rb.blob_sha(d)} for n, d in tree_files.items()]}
+            if path.endswith("/git/trees"):
+                return {"sha": "t1"}
+            if path.endswith("/git/commits"):
+                return {"sha": "c1", "verification": {"verified": verified}}
+            return {}
+
+        return call, calls
+
+    def test_the_first_publish_creates_the_branch(self) -> None:
+        """Without a branch the commit has no parent and the ref is created."""
+        call, calls = self.fake(None)
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+        self.assertEqual(calls[2][2]["parents"], [])
+        self.assertEqual(
+            calls[-1],
+            ("POST", f"/repos/{REPO}/git/refs", {"ref": "refs/heads/badges", "sha": "c1"}),
+        )
+
+    def test_an_old_head_gets_a_new_commit_moved_forward_only(self) -> None:
+        """An old head becomes the parent, and the ref moves with force false."""
+        call, calls = self.fake("c0")
+        rb.publish(call, REPO, self.FILES, NOW)
+        commit = next(c for c in calls if c[1].endswith("/git/commits"))
+        self.assertEqual(commit[2]["parents"], ["c0"])
+        self.assertEqual(
+            calls[-1],
+            ("PATCH", f"/repos/{REPO}/git/refs/heads/badges", {"sha": "c1", "force": False}),
+        )
+
+    def test_an_unsigned_commit_leaves_the_branch_alone(self) -> None:
+        """An unverified commit raises before any ref call."""
+        call, calls = self.fake("c0", verified=False)
+        with self.assertRaisesRegex(rb.BadgeError, "not signed"):
+            rb.publish(call, REPO, self.FILES, NOW)
+        self.assertFalse([c for c in calls if "/git/refs" in c[1]])
+
+    def test_a_commit_without_a_true_verification_is_not_signed(self) -> None:
+        """A missing or non-boolean verification counts as unsigned."""
+        for answer in ({"sha": "c1"}, {"sha": "c1", "verification": {"verified": "true"}}):
+            with self.subTest(answer=answer):
+                call, calls = self.fake("c0")
+                with self.assertRaisesRegex(rb.BadgeError, "c1 is not signed"):
+                    rb.publish(commit_answering(answer, call), REPO, self.FILES, NOW)
+                self.assertFalse([c for c in calls if "/git/refs" in c[1]])
+
+    def test_a_tree_answer_without_a_list_is_refused(self) -> None:
+        """A head tree answer without a list raises."""
+        young = rb.stamp(NOW - timedelta(minutes=5))
+        call, _ = self.fake("c0", date=young)
+
+        def answered(method: str, path: str, payload: object) -> object:
+            """Answer the head tree without a list; pass every other call on."""
+            return {"tree": {}} if "/git/trees/" in path else call(method, path, payload)
+
+        with self.assertRaisesRegex(rb.BadgeError, "no tree list"):
+            rb.publish(answered, REPO, self.FILES, NOW)
+
+    def test_same_svgs_inside_the_quiet_window_commit_nothing(self) -> None:
+        """Same SVGs and a head younger than an hour make only GET calls."""
+        young = rb.stamp(NOW - rb.QUIET_WINDOW + timedelta(seconds=1))
+        call, calls = self.fake("c0", date=young)
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "unchanged at c0")
+        self.assertFalse([c for c in calls if c[0] != "GET"])
+
+    def test_a_naive_or_unreadable_head_date_commits(self) -> None:
+        """A head date without an offset, or unreadable, counts as old."""
+        for date in ("2026-11-10T11:59:00", "2026-11-10", "soon"):
+            with self.subTest(date=date):
+                call, _ = self.fake("c0", date=date)
+                self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+
+    def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
+        """A changed SVG is committed even inside the quiet window."""
+        young = rb.stamp(NOW - timedelta(minutes=5))
+        call, _ = self.fake(
+            "c0", date=young, tree_files={"go.svg": b"<svg >old</svg>", "state.json": b"{}"}
+        )
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+
+    def young_publish(self, state: bytes, files: dict[str, bytes] | None = None) -> str:
+        """``publish`` against a head five minutes old with the same SVG and ``state`` on it."""
+        call, _ = self.fake("c0", date=rb.stamp(NOW - timedelta(minutes=5)), state=state)
+        return rb.publish(call, REPO, self.FILES if files is None else files, NOW)
+
+    def test_read_times_inside_the_quiet_window_commit_nothing(self) -> None:
+        """A recorded read time up to just under an hour before this run's commits nothing."""
+        for lag in (timedelta(0), rb.QUIET_WINDOW - timedelta(seconds=1)):
+            with self.subTest(lag=lag):
+                self.assertEqual(
+                    self.young_publish(state_file(rb.stamp(NOW - lag))), "unchanged at c0"
+                )
+
+    def test_a_recovered_read_time_is_committed_inside_the_quiet_window(self) -> None:
+        """A read time an hour or more newer than the branch's is committed, SVGs unchanged."""
+        for lag in (rb.QUIET_WINDOW, timedelta(hours=5)):
+            with self.subTest(lag=lag):
+                self.assertEqual(self.young_publish(state_file(rb.stamp(NOW - lag))), "c1")
+
+    def test_a_recorded_read_time_that_cannot_be_compared_is_committed(self) -> None:
+        """A future, unreadable, one-sided or missing recorded read time, or bad state, commits."""
+        cases = {
+            "future": state_file(rb.stamp(NOW + timedelta(seconds=1))),
+            "naive": state_file("2026-11-10T12:00:00"),
+            "none on the branch": state_file(None),
+            "other badge": state_file(rb.stamp(NOW), slug="lint"),
+            "extra badge": json.dumps(
+                {"badges": {**json.loads(state_file(rb.stamp(NOW)))["badges"], "lint": {}}}
+            ).encode(),
+            "entry not an object": b'{"badges": {"go": "passing"}}',
+            "no badges": b"{}",
+            "not json": b"{",
+        }
+        for name, state in cases.items():
+            with self.subTest(case=name):
+                self.assertEqual(self.young_publish(state), "c1")
+
+    def test_a_fresh_state_that_cannot_be_compared_is_committed(self) -> None:
+        """A run's own state without a read time, or without a badges object, commits."""
+        for state in (state_file(None), b"[]", b'{"badges": []}', b'{"badges": ["go"]}'):
+            with self.subTest(state=state):
+                files = {**self.FILES, "state.json": state}
+                self.assertEqual(self.young_publish(self.FILES["state.json"], files), "c1")
+
+    def test_an_unreadable_branch_state_is_committed_with_nothing_to_compare(self) -> None:
+        """A branch state.json that cannot be parsed is replaced even when no badge is listed."""
+        files = {**self.FILES, "state.json": b'{"badges": {}}'}
+        self.assertEqual(self.young_publish(b'{"badges": {}}', files), "unchanged at c0")
+        self.assertEqual(self.young_publish(b"{", files), "c1")
+
+    def test_no_read_time_on_both_sides_commits_nothing(self) -> None:
+        """A badge never read, on the branch and in this run, needs no commit."""
+        files = {**self.FILES, "state.json": state_file(None)}
+        self.assertEqual(self.young_publish(state_file(None), files), "unchanged at c0")
+
+    def test_a_missing_branch_state_file_is_committed(self) -> None:
+        """A branch without state.json (404) commits."""
+        call, _ = self.fake("c0", date=rb.stamp(NOW - timedelta(minutes=5)))
+
+        def answered(method: str, path: str, payload: object) -> object:
+            """Answer the state file read with 404; pass every other call on."""
+            if "/contents/" in path:
+                raise http_error(404)
+            return call(method, path, payload)
+
+        self.assertEqual(rb.publish(answered, REPO, self.FILES, NOW), "c1")
+
+    def test_a_failure_after_an_unchanged_recovery_carries_the_recovered_time(self) -> None:
+        """Outage, recovery with the same value, then a new failure: the badge stays current.
+
+        The branch holds the read time from before a five-hour outage and a
+        commit five minutes old. The source answers again with its old value,
+        so the SVG is unchanged; the publish still commits the new read time,
+        and a failure 75 minutes later keeps "passing" instead of "stale".
+        """
+        go = rb.Badge("go", "Go", "workflow", "go-ci.yml")
+        before = rb.stamp(NOW - timedelta(hours=5))
+        recovered, _ = rb.refresh((go,), {}, NOW, lambda b: rb.PASSING)
+        files = {**self.FILES, "state.json": json.dumps({"badges": recovered}).encode()}
+        call, calls = self.fake(
+            "c0", date=rb.stamp(NOW - timedelta(minutes=5)), state=state_file(before)
+        )
+        self.assertEqual(rb.publish(call, REPO, files, NOW), "c1")
+        tree = next(c[2]["tree"] for c in calls if c[1].endswith("/git/trees"))
+        branch = json.loads(next(e["content"] for e in tree if e["path"] == "state.json"))
+        later = NOW + timedelta(minutes=75)
+
+        def fails(badge: rb.Badge) -> rb.Value:
+            """The source fails again."""
+            raise rb.BadgeError(f"{badge.slug}: timed out")
+
+        entries, _ = rb.refresh((go,), branch["badges"], later, fails)
+        self.assertEqual(entries["go"]["message"], "passing")
+        self.assertEqual(entries["go"]["fetched_at"], rb.stamp(NOW))
+
+    def test_a_ref_lookup_error_other_than_404_is_raised(self) -> None:
+        """A failing ref lookup other than 404 propagates."""
+
+        def call(method: str, path: str, payload: object) -> object:
+            """Fail every call with a 500."""
+            raise http_error(500)
+
+        with self.assertRaises(urllib.error.HTTPError) as raised:
+            rb.publish(call, REPO, self.FILES, NOW)
+        raised.exception.close()
+
+    def test_a_missing_branch_closes_its_404(self) -> None:
+        """``branch_head`` returns None for a 404 and closes it."""
+        error = http_error(404)
+
+        def call(method: str, path: str, payload: object) -> object:
+            """Fail every call with the planted 404."""
+            raise error
+
+        self.assertIsNone(rb.branch_head(call, REPO))
+        self.assertTrue(error.fp.closed)
+
+    def test_blob_sha_is_the_git_object_id(self) -> None:
+        """``blob_sha`` matches ``git hash-object`` for a known blob."""
+        # `printf 'hi\n' | git hash-object --stdin`
+        self.assertEqual(rb.blob_sha(b"hi\n"), "45b983be36b73c0788dc9cbcb76cbb80fc7bb057")
+
+    def test_the_empty_blob_has_the_well_known_id(self) -> None:
+        """The empty blob has git's well-known id."""
+        # `git hash-object --stdin </dev/null`
+        self.assertEqual(rb.blob_sha(b""), "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391")
+
+    def test_a_failing_or_garbled_git_is_refused(self) -> None:
+        """A non-zero exit or an output that is not a SHA-1 id is refused."""
+        answers = (
+            mock.Mock(returncode=128, stdout=b"", stderr=b"fatal: no"),
+            mock.Mock(
+                returncode=1, stdout=b"45b983be36b73c0788dc9cbcb76cbb80fc7bb057\n", stderr=b""
+            ),
+            mock.Mock(returncode=0, stdout=b"not-an-id\n", stderr=b""),
+            mock.Mock(returncode=0, stdout=b"a" * 64 + b"\n", stderr=b""),
+        )
+        for answer in answers:
+            with (
+                self.subTest(stdout=answer.stdout),
+                mock.patch.object(rb, "run_command", return_value=answer),
+                self.assertRaisesRegex(rb.BadgeError, "git hash-object exited"),
+            ):
+                rb.blob_sha(b"hi\n")
+
+    def test_a_missing_git_is_a_badge_error(self) -> None:
+        """A missing git executable becomes a badge error."""
+        missing = CommandValidationError("required executable not found: git")
+        with mock.patch.object(rb, "run_command", side_effect=missing):
+            with self.assertRaisesRegex(rb.BadgeError, "not found: git"):
+                rb.blob_sha(b"hi\n")
+
+
+class Verdict(unittest.TestCase):
+    """``verdict`` turns the run red when a source failed."""
+
+    def verdict(self, doc: object) -> tuple[int, str]:
+        """Run ``verdict`` on a state file holding ``doc``; return the code and stdout."""
+        with tempfile.TemporaryDirectory() as tmp:
+            state = Path(tmp) / "state.json"
+            state.write_text(json.dumps(doc), encoding="utf-8")
+            out = io.StringIO()
+            with redirect_stdout(out), redirect_stderr(io.StringIO()):
+                rc = rb.main(["verdict", "--state", str(state)], env={})
+        return rc, out.getvalue()
+
+    def test_no_failure_passes(self) -> None:
+        """An empty failures list exits 0."""
+        self.assertEqual(self.verdict({"failures": []})[0], 0)
+
+    def test_a_failure_fails_the_run_with_an_annotation(self) -> None:
+        """A failure exits 1 with a GitHub error annotation."""
+        rc, out = self.verdict({"failures": ["codacy: down"]})
+        self.assertEqual(rc, 1)
+        self.assertIn("::error title=Badge source failed::codacy: down", out)
+
+    def test_a_state_without_a_failures_list_is_an_error(self) -> None:
+        """A failures field that is not a list exits 2."""
+        self.assertEqual(self.verdict({"failures": "none"})[0], 2)
+
+
+class Main(unittest.TestCase):
+    """The command line refuses to run without its inputs."""
+
+    def test_spec_and_publish_need_the_repository_and_a_token(self) -> None:
+        """spec and publish exit 2 without GITHUB_TOKEN."""
+        for argv in (["spec", "--spec", "s", "--state", "t"], ["publish", "--dir", "d"]):
+            err = io.StringIO()
+            with self.subTest(argv=argv[0]), redirect_stderr(err):
+                self.assertEqual(rb.main(argv, env={"GITHUB_REPOSITORY": REPO}), 2)
+            self.assertIn("set GITHUB_TOKEN", err.getvalue())
+
+    def test_a_failed_state_read_writes_nothing_to_publish(self) -> None:
+        """A failed state read exits 2 before the spec or state file is written."""
+
+        def fail(*_args: object) -> object:
+            """Fail every API request with a 503."""
+            raise http_error(503)
+
+        env = {"GITHUB_REPOSITORY": REPO, "GITHUB_TOKEN": secrets.token_urlsafe(8)}
+        with tempfile.TemporaryDirectory() as tmp:
+            spec, state = Path(tmp) / "spec.json", Path(tmp) / "badges/state.json"
+            err = io.StringIO()
+            with mock.patch.object(ci_tier, "api_request", side_effect=fail), redirect_stderr(err):
+                argv = ["spec", "--spec", str(spec), "--state", str(state)]
+                self.assertEqual(rb.main(argv, env=env), 2)
+            self.assertFalse(spec.exists() or state.exists())
+        self.assertIn("the badges keep their values", err.getvalue())
+
+
+SHIELDS = "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35"
+GOVERNANCE = "https://github.com/vmafx/vmafx/actions/workflows/praetor-docs.yml/badge.svg"
+BLOCK = (
+    "<!-- praetor:readme-governance:start -->\n"
+    "[![Documentation Governance][docs-badge]][docs-runs]\n"
+    "\n"
+    f"[docs-badge]: {GOVERNANCE}\n"
+    "[docs-runs]: https://github.com/vmafx/vmafx/actions/workflows/praetor-docs.yml\n"
+    "<!-- praetor:readme-governance:end -->\n"
+)
+
+
+def image(url: str) -> str:
+    """A linked Markdown image of ``url`` on its own line."""
+    return f"[![x]({url})](https://example.org)\n"
+
+
+class ImageFault(unittest.TestCase):
+    """``image_fault`` accepts only the one badge design."""
+
+    def test_the_one_design_passes(self) -> None:
+        """Rendered badges, for-the-badge shields and repository files pass."""
+        allowed = [
+            f"https://raw.githubusercontent.com/{REPO}/badges/{b.slug}.svg" for b in rb.BADGES
+        ]
+        allowed += [
+            SHIELDS,
+            "https://img.shields.io/static/v1?label=release&message=v1&style=for-the-badge&color=3b82f6&labelColor=111a35",
+            "docs/assets/vmafx-readme-banner.svg",
+        ]
+        allowed.append("https://raw.githubusercontent.com/vmafx/VMAFX/badges/tests.svg")
+        for url in allowed:
+            with self.subTest(url=url):
+                self.assertIsNone(rb.image_fault(url, ROOT))
+
+    def test_another_design_or_host_is_a_fault(self) -> None:
+        """Every other style, host, repository or path names its reason."""
+        refused = {
+            "https://img.shields.io/badge/C-23-3b82f6?style=flat-square&labelColor=111a35": "style=for-the-badge",
+            "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge": "labelColor=111a35",
+            "https://img.shields.io/badge/C-23-3b82f6": "style=for-the-badge and labelColor=111a35",
+            f"https://github.com/{REPO}/actions/workflows/lint-and-format.yml/badge.svg": "not a rendered",
+            "https://www.bestpractices.dev/projects/14549/badge": "not a rendered",
+            "http://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35": "not a rendered",
+            f"https://raw.githubusercontent.com/{REPO}/badges/coverage.svg": "no rendered badge is named 'coverage'",
+            f"https://raw.githubusercontent.com/{REPO}/master/tests.svg": "not a rendered",
+            # Planted cases from the pull request 3393 review: other repositories.
+            "https://raw.githubusercontent.com/someone/vmafx/badges/tests.svg": "not a rendered",
+            "https://raw.githubusercontent.com/VMAFx/vmafx-fork/badges/tests.svg": "not a rendered",
+            "https://raw.githubusercontent.com/VMAFx/vmafx/badges/x/tests.svg": "not a rendered",
+            # Planted cases from the pull request 3393 review: missing files.
+            "docs/assets/no-such-banner.svg": "no such file next to the README",
+            "docs/assets": "no such file next to the README",
+            "/docs/assets/banner.svg": "not a rendered",
+            "../banner.svg": "not a rendered",
+            "docs/../../banner.svg": "not a rendered",
+            "docs/assets/..": "not a rendered",
+            "//cdn.example.org/badge.svg": "not a rendered",
+        }
+        for url, reason in refused.items():
+            with self.subTest(url=url):
+                self.assertIn(reason, rb.image_fault(url, ROOT) or "")
+
+    def test_a_link_out_of_the_readme_directory_is_a_fault(self) -> None:
+        """A link out of the README directory fails; a link inside passes."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root, outside = Path(tmp) / "repo", Path(tmp) / "outside.svg"
+            root.mkdir()
+            outside.write_text("<svg/>", encoding="utf-8")
+            (root / "inside.svg").write_text("<svg/>", encoding="utf-8")
+            (root / "link.svg").symlink_to(outside)
+            (root / "local-link.svg").symlink_to(root / "inside.svg")
+            self.assertIn("resolves outside", rb.image_fault("link.svg", root) or "")
+            self.assertIsNone(rb.image_fault("inside.svg", root))
+            self.assertIsNone(rb.image_fault("local-link.svg", root))
+
+    def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
+        """A repeated, empty or differently cased design parameter fails."""
+        for query in (
+            "style=for-the-badge&style=flat&labelColor=111a35",
+            "style=for-the-badge&labelColor=",
+            "style=FOR-THE-BADGE&labelColor=111a35",
+            "style=for-the-badge&labelcolor=111a35",
+        ):
+            with self.subTest(query=query):
+                self.assertIsNotNone(
+                    rb.image_fault(f"https://img.shields.io/badge/C-23-3b82f6?{query}", ROOT)
+                )
+
+
+class HomeRepository(unittest.TestCase):
+    """The repository name comes from the security policy file."""
+
+    def setUp(self) -> None:
+        """Start and end every test with empty caches."""
+        self.clear()
+        self.addCleanup(self.clear)
+
+    @staticmethod
+    def clear() -> None:
+        """Clear the cached policy reads."""
+        for cached in (rb.home_repository, rb.rendered_badge, rb.governance_badge):
+            cached.cache_clear()
+
+    def test_the_policy_names_this_repository(self) -> None:
+        """The checked-in policy names VMAFx/vmafx."""
+        self.assertEqual(rb.home_repository(), REPO)
+
+    def test_a_missing_or_malformed_policy_is_a_badge_error(self) -> None:
+        """A missing file, or a repository that is not owner/name, is refused."""
+        for text in (
+            None,
+            "{",
+            "[]",
+            "{}",
+            '{"repository": 7}',
+            '{"repository": "vmafx"}',
+            '{"repository": "a/b/c"}',
+            '{"repository": "a b/c"}',
+            '{"repository": "/c"}',
+        ):
+            with self.subTest(text=text), tempfile.TemporaryDirectory() as tmp:
+                policy = Path(tmp) / "policy.json"
+                if text is not None:
+                    policy.write_text(text, encoding="utf-8")
+                with mock.patch.object(rb, "SECURITY_POLICY", policy):
+                    self.clear()
+                    with self.assertRaises(rb.BadgeError):
+                        rb.home_repository()
+                    self.clear()
+
+    def test_the_rendered_badge_follows_the_policy(self) -> None:
+        """A fork's policy accepts its own badges and refuses this repository's."""
+        with tempfile.TemporaryDirectory() as tmp:
+            policy = Path(tmp) / "policy.json"
+            policy.write_text('{"repository": "adopter/fork"}', encoding="utf-8")
+            with mock.patch.object(rb, "SECURITY_POLICY", policy):
+                self.clear()
+                ours = "https://raw.githubusercontent.com/adopter/fork/badges/tests.svg"
+                self.assertIsNone(rb.image_fault(ours, ROOT))
+                theirs = f"https://raw.githubusercontent.com/{REPO}/badges/tests.svg"
+                self.assertIn("not a rendered", rb.image_fault(theirs, ROOT) or "")
+                self.clear()
+
+
+class DesignFaults(unittest.TestCase):
+    """``design_faults`` checks every image in a README."""
+
+    def test_the_readme_has_the_one_design(self) -> None:
+        """The checked-in README has no fault."""
+        self.assertEqual(
+            rb.design_faults((ROOT / "README.md").read_text(encoding="utf-8"), ROOT), []
+        )
+
+    def test_an_empty_readme_has_no_fault(self) -> None:
+        """An empty README has no fault."""
+        self.assertEqual(rb.design_faults("", ROOT), [])
+
+    def test_a_fault_names_its_line(self) -> None:
+        """A fault starts with its line number."""
+        readme = "# Title\n\n" + image(SHIELDS.replace("for-the-badge", "flat-square"))
+        self.assertEqual(
+            rb.design_faults(readme, ROOT),
+            [
+                f"3: {SHIELDS.replace('for-the-badge', 'flat-square')}: a shields.io badge needs style=for-the-badge"
+            ],
+        )
+
+    def test_the_governance_block_may_hold_its_own_badge(self) -> None:
+        """The Praetor governance block may keep GitHub's badge."""
+        self.assertEqual(rb.design_faults("# Title\n\n" + BLOCK, ROOT), [])
+
+    def test_the_block_exception_covers_only_the_governance_badge(self) -> None:
+        """Another image in the block, or an unresolved reference, is a fault."""
+        flat = BLOCK.replace(GOVERNANCE, SHIELDS.replace("for-the-badge", "flat-square"))
+        self.assertEqual(len(rb.design_faults(flat, ROOT)), 1)
+        unresolved = BLOCK.replace("[docs-badge]:", "[other]:")
+        self.assertIn("without an inline address", rb.design_faults(unresolved, ROOT)[0])
+
+    def test_another_repository_governance_badge_is_a_fault(self) -> None:
+        """A governance badge of another repository is a fault."""
+        other = GOVERNANCE.replace("vmafx/vmafx", "someone/vmafx")
+        self.assertEqual(len(rb.design_faults(BLOCK.replace(GOVERNANCE, other), ROOT)), 1)
+
+    def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
+        """The governance badge outside a complete block is a fault."""
+        for readme in (
+            image(GOVERNANCE),
+            BLOCK.replace("<!-- praetor:readme-governance:end -->\n", ""),
+            BLOCK.replace("<!-- praetor:readme-governance:start -->\n", ""),
+        ):
+            with self.subTest(readme=readme[:40]):
+                self.assertNotEqual(rb.design_faults(readme, ROOT), [])
+
+    def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
+        """Every reference-style image form outside the block is a fault."""
+        for readme in (
+            f"![C][c]\n\n[c]: {SHIELDS}\n",
+            f"![c][]\n\n[c]: {SHIELDS}\n",
+            f"![c]\n\n[c]: {SHIELDS}\n",
+        ):
+            with self.subTest(readme=readme.splitlines()[0]):
+                self.assertEqual(
+                    rb.design_faults(readme, ROOT),
+                    ["1: an image without an inline address this check can read"],
+                )
+
+    def test_code_is_not_an_image(self) -> None:
+        """Images inside fences or code spans are not checked."""
+        flat = SHIELDS.replace("for-the-badge", "flat-square")
+        for readme in (
+            f"```markdown\n![x]({flat})\n```\n",
+            f'~~~\n<img src="{flat}">\n~~~\n',
+            f"Write `![x]({flat})` for a badge.\n",
+        ):
+            with self.subTest(readme=readme.splitlines()[0]):
+                self.assertEqual(rb.design_faults(readme, ROOT), [])
+
+    def test_an_unclosed_fence_hides_nothing(self) -> None:
+        """An unclosed fence does not hide the image after it."""
+        flat = SHIELDS.replace("for-the-badge", "flat-square")
+        self.assertEqual(len(rb.design_faults(f"```\n![x]({flat})\n", ROOT)), 1)
+
+    def test_an_html_image_must_be_a_local_file(self) -> None:
+        """img and source tags pass only for existing local files."""
+        passing = (
+            '<img src="docs/a.svg" alt="VMAFx" height="120" />\n',
+            '<picture><source media="(prefers-color-scheme: dark)" srcset="docs/a.svg 2x, docs/b.svg"></picture>\n',
+        )
+        failing = (
+            f'<img src="{SHIELDS}">\n',
+            f'<IMG SRC="{GOVERNANCE}">\n',
+            f'<source srcset="docs/a.svg 1x, {SHIELDS} 2x">\n',
+            '<img alt="no source">\n',
+            f"<img src='{SHIELDS}'>\n",
+            '<img src="docs/c.svg">\n',
+            '<source srcset="docs/a.svg 1x, docs/c.svg 2x">\n',
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "docs").mkdir()
+            for name in ("a.svg", "b.svg"):
+                (root / "docs" / name).write_text("<svg/>", encoding="utf-8")
+            for readme in passing:
+                with self.subTest(readme=readme):
+                    self.assertEqual(rb.design_faults(readme, root), [])
+            for readme in failing:
+                with self.subTest(readme=readme):
+                    self.assertEqual(len(rb.design_faults(readme, root)), 1)
+
+    def test_faults_come_in_line_order(self) -> None:
+        """Faults are listed by line, whatever their kind."""
+        readme = f'<img src="{SHIELDS}">\n' + image(GOVERNANCE) + f'<img src="{SHIELDS}">\n'
+        lines = [int(fault.split(":", 1)[0]) for fault in rb.design_faults(readme, ROOT)]
+        self.assertEqual(lines, [1, 2, 3])
+
+
+class CheckReadme(unittest.TestCase):
+    """The ``check-readme`` command fails on any image outside the one design."""
+
+    def check(self, text: str | None, files: tuple[str, ...] = ()) -> tuple[int, str, str]:
+        """Run ``check-readme`` on a temporary README; return code, stdout and stderr."""
+        with tempfile.TemporaryDirectory() as tmp:
+            readme = Path(tmp) / "README.md"
+            if text is not None:
+                readme.write_text(text, encoding="utf-8")
+            for name in files:
+                (Path(tmp) / name).write_text("<svg/>", encoding="utf-8")
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = rb.main(["check-readme", "--readme", str(readme)], env={})
+        return rc, out.getvalue(), err.getvalue()
+
+    def test_the_one_design_passes_without_a_token(self) -> None:
+        """A passing README exits 0 without any token."""
+        rc, out, _ = self.check(image(SHIELDS))
+        self.assertEqual(rc, 0)
+        self.assertIn("every badge has the one design", out)
+
+    def test_a_fault_fails_with_file_and_line(self) -> None:
+        """A fault exits 1 and names README.md and the line."""
+        rc, _, err = self.check("\n" + image(GOVERNANCE))
+        self.assertEqual(rc, 1)
+        self.assertRegex(err, r"README\.md:2: https://github\.com/")
+        self.assertIn("1 README images break the one badge design", err)
+
+    def test_a_missing_readme_is_an_error(self) -> None:
+        """A missing README exits 2."""
+        self.assertEqual(self.check(None)[0], 2)
+
+    def test_a_local_image_is_looked_up_next_to_the_readme(self) -> None:
+        """A local image passes only when the file is next to the README."""
+        self.assertEqual(self.check(image("banner.svg"), files=("banner.svg",))[0], 0)
+        rc, _, err = self.check(image("banner.svg"))
+        self.assertEqual(rc, 1)
+        self.assertIn("banner.svg: no such file next to the README", err)
+
+
+class Consistency(unittest.TestCase):
+    """The README, the workflow and render.mjs agree with the script."""
+
+    def test_render_mjs_allows_the_same_text_and_colours(self) -> None:
+        """render.mjs uses the same text and colour patterns as the script."""
+        source = (ROOT / "tools/badges/render.mjs").read_text(encoding="utf-8")
+        self.assertIn(f"const TEXT = /^{rb.TEXT.pattern}$/", source)
+        self.assertIn(f"const COLOR = /^{rb.COLOR.pattern}$/", source)
+
+    def test_every_workflow_badge_names_a_workflow_by_its_name(self) -> None:
+        """Each workflow badge label is that workflow's ``name:``."""
+        for badge in (b for b in rb.BADGES if b.kind == "workflow"):
+            path = ROOT / ".github/workflows" / badge.workflow
+            with self.subTest(badge=badge.slug):
+                first = re.search(r"^name: (.+)$", path.read_text(encoding="utf-8"), re.M)
+                self.assertEqual(first.group(1).strip() if first else None, badge.label)
+
+    def test_the_workflow_runs_only_on_the_policy_repository_and_branch(self) -> None:
+        """The guard names the policy repository and branch; both jobs check out github.sha."""
+        policy = json.loads(
+            (ROOT / ".github/repository-security-policy.json").read_text(encoding="utf-8")
+        )
+        workflow = (ROOT / ".github/workflows/readme-badges.yml").read_text(encoding="utf-8")
+        self.assertIn(f"github.repository == '{policy['repository']}'", workflow)
+        self.assertIn(f"github.ref == 'refs/heads/{policy['default_branch']}'", workflow)
+        # Both jobs check out the commit the run started from, so a master push
+        # between them cannot change the code the publisher runs.
+        self.assertEqual(workflow.count("ref: ${{ github.sha }}"), 2)
+        self.assertNotRegex(workflow, r"ref: (?!\$\{\{ github\.sha \}\})")
+
+    def test_a_carried_read_time_trails_by_less_than_the_stale_bound(self) -> None:
+        """The quiet window plus the largest schedule gap stays under a quarter of six hours."""
+        # The branch's state file holds each read time to within QUIET_WINDOW
+        # (reads_recorded), so `stale` comes at most that early and one
+        # schedule gap late; together they must stay well inside STALE_AFTER.
+        workflow = (ROOT / ".github/workflows/readme-badges.yml").read_text(encoding="utf-8")
+        cron = re.search(r'cron: "(?P<minutes>[0-9,]+) \* \* \* \*"', workflow)
+        self.assertIsNotNone(cron)
+        minutes = sorted(int(m) for m in cron["minutes"].split(",")) if cron else []
+        gaps = [b - a for a, b in zip(minutes, [*minutes[1:], minutes[0] + 60], strict=True)]
+        lag = rb.QUIET_WINDOW + timedelta(minutes=max(gaps))
+        self.assertLess(lag, rb.STALE_AFTER / 4)
+
+    def test_the_readme_shows_every_badge_once_with_its_label(self) -> None:
+        """The README shows each badge of BADGES once, in order, with its label as alt text."""
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+        shown = [(m["slug"], m["alt"]) for m in RAW.finditer(readme)]
+        self.assertEqual(shown, [(b.slug, b.label) for b in rb.BADGES])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/badges/package-lock.json b/tools/badges/package-lock.json
new file mode 100644
index 0000000000..6149e4f010
--- /dev/null
+++ b/tools/badges/package-lock.json
@@ -0,0 +1,87 @@
+{
+  "name": "@vmafx/readme-badges",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@vmafx/readme-badges",
+      "version": "1.0.0",
+      "license": "EUPL-1.2",
+      "dependencies": {
+        "badge-maker": "6.0.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/anafanafo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/anafanafo/-/anafanafo-2.0.0.tgz",
+      "integrity": "sha512-Nlfq7NC4AOkTJerWRIZcOAiMNtIDVIGWGvQ98O7Jl6Kr2Dk0dX5u4MqN778kSRTy5KRqchpLdF2RtLFEz9FVkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "char-width-table-consumer": "^1.0.0"
+      }
+    },
+    "node_modules/badge-maker": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/badge-maker/-/badge-maker-6.0.0.tgz",
+      "integrity": "sha512-+P5EsfmFWAR2cA9M0q20pa4OVOgnOXZkfRYUkQYHanECXCIg10ZnSBzelfBtEjt03b4Vac/yC1h55/wJPLmaOg==",
+      "license": "(MIT OR Apache-2.0)",
+      "dependencies": {
+        "anafanafo": "2.0.0",
+        "css-color-converter": "^2.0.0"
+      },
+      "bin": {
+        "badge": "lib/badge-cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/binary-search": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/binary-search/-/binary-search-1.3.6.tgz",
+      "integrity": "sha512-nbE1WxOTTrUWIfsfZ4aHGYu5DOuNkbxGokjV6Z2kxfJK3uaAb8zNK1muzOeipoLHZjInT4Br88BHpzevc681xA==",
+      "license": "CC0-1.0"
+    },
+    "node_modules/char-width-table-consumer": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/char-width-table-consumer/-/char-width-table-consumer-1.0.0.tgz",
+      "integrity": "sha512-Fz4UD0LBpxPgL9i29CJ5O4KANwaMnX/OhhbxzvNa332h+9+nRKyeuLw4wA51lt/ex67+/AdsoBQJF3kgX2feYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "binary-search": "^1.3.5"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-0.5.3.tgz",
+      "integrity": "sha512-RwBeO/B/vZR3dfKL1ye/vx8MHZ40ugzpyfeVG5GsiuGnrlMWe2o8wxBbLCpw9CsxV+wHuzYlCiWnybrIA0ling=="
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
+    "node_modules/css-color-converter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/css-color-converter/-/css-color-converter-2.0.0.tgz",
+      "integrity": "sha512-oLIG2soZz3wcC3aAl/7Us5RS8Hvvc6I8G8LniF/qfMmrm7fIKQ8RIDDRZeKyGL2SrWfNqYspuLShbnjBMVWm8g==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^0.5.2",
+        "color-name": "^1.1.4",
+        "css-unit-converter": "^1.1.2"
+      }
+    },
+    "node_modules/css-unit-converter": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/css-unit-converter/-/css-unit-converter-1.1.2.tgz",
+      "integrity": "sha512-IiJwMC8rdZE0+xiEZHeru6YoONC4rfPMqGm2W85jMIbkFvv5nFTwJVFHam2eFrN6txmoUYFAFXiv8ICVeTO0MA==",
+      "license": "MIT"
+    }
+  }
+}
diff --git a/tools/badges/package.json b/tools/badges/package.json
new file mode 100644
index 0000000000..77ff4a142f
--- /dev/null
+++ b/tools/badges/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@vmafx/readme-badges",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Renders the README status badges (scripts/ci/readme_badges.py) with the shields.io badge renderer",
+  "license": "EUPL-1.2",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "badge-maker": "6.0.0"
+  }
+}
diff --git a/tools/badges/render.mjs b/tools/badges/render.mjs
new file mode 100644
index 0000000000..f0f4b49da0
--- /dev/null
+++ b/tools/badges/render.mjs
@@ -0,0 +1,76 @@
+// Copyright 2026 Lusoris
+// SPDX-License-Identifier: EUPL-1.2
+//
+// Render README status badges as SVG with badge-maker, the shields.io
+// renderer (MIT OR Apache-2.0, https://github.com/badges/shields).
+//
+// Usage: node tools/badges/render.mjs <spec.json> <out-dir>
+//
+// <spec.json> is written by `scripts/ci/readme_badges.py spec`: a list of
+// {"slug", "label", "message", "color"} objects. Each entry becomes
+// <out-dir>/<slug>.svg in the for-the-badge style the README header uses
+// (docs/README-STANDARD.md). The script reads no network and no
+// environment; it fails on any entry outside the allow-listed shape.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { makeBadge } from 'badge-maker'
+
+const LABEL_COLOR = '#111a35'
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const COLOR = /^#[0-9a-f]{6}$/
+const TEXT = /^[\x20-\x7e]{1,40}$/
+const MAX_BADGES = 32
+
+/**
+ * Return a render-list entry when it has exactly the four keys and each
+ * value matches its pattern; throw naming the entry otherwise.
+ *
+ * @param {unknown} entry one object of the render list
+ * @param {number} index its position, for the error text
+ * @returns {{slug: string, label: string, message: string, color: string}}
+ */
+function checked(entry, index) {
+  const keys = Object.keys(entry ?? {}).sort().join(',')
+  if (keys !== 'color,label,message,slug') {
+    throw new Error(`entry ${index}: keys ${keys}, want color,label,message,slug`)
+  }
+  const { slug, label, message, color } = entry
+  if (!SLUG.test(slug)) throw new Error(`entry ${index}: bad slug ${JSON.stringify(slug)}`)
+  if (!TEXT.test(label)) throw new Error(`${slug}: bad label ${JSON.stringify(label)}`)
+  if (!TEXT.test(message)) throw new Error(`${slug}: bad message ${JSON.stringify(message)}`)
+  if (!COLOR.test(color)) throw new Error(`${slug}: bad color ${JSON.stringify(color)}`)
+  return entry
+}
+
+/**
+ * Write one for-the-badge SVG per render-list entry into the output
+ * directory; throw on a malformed list or a slug listed twice.
+ *
+ * @param {string[]} argv the spec path and the output directory
+ */
+function main(argv) {
+  if (argv.length !== 2) {
+    throw new Error('usage: node tools/badges/render.mjs <spec.json> <out-dir>')
+  }
+  const [specPath, outDir] = argv
+  const spec = JSON.parse(readFileSync(specPath, 'utf8'))
+  if (!Array.isArray(spec) || spec.length === 0 || spec.length > MAX_BADGES) {
+    throw new Error(`${specPath}: want a list of 1 to ${MAX_BADGES} badges`)
+  }
+  const seen = new Set()
+  spec.map(checked).forEach(({ slug, label, message, color }) => {
+    if (seen.has(slug)) throw new Error(`${slug}: listed twice`)
+    seen.add(slug)
+    const svg = makeBadge({ label, message, color, labelColor: LABEL_COLOR, style: 'for-the-badge' })
+    writeFileSync(join(outDir, `${slug}.svg`), `${svg}\n`, 'utf8')
+  })
+  process.stdout.write(`rendered ${seen.size} badges into ${outDir}\n`)
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (error) {
+  process.stderr.write(`render.mjs: ${error.message}\n`)
+  process.exitCode = 1
+}