From 7e52e010fd4d0ccea13f4df8f35f751d7eae73d1 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Tue, 28 Jul 2026 21:35:49 +0200
Subject: [PATCH 1/4] refactor(scripts): extract the shared badge SVG renderer

Behavior-preserving. A second generator (generate_repo_badges.py, next
commit) needs the same shields-style geometry the MCP Toplist refresher
already had, so the geometry moves to a sibling module rather than being
copied. What stays in the refresher is what makes that badge THAT badge:
the bar icon, the banner palette, and the wording of its claim.

Path-based sibling import, following the launcher.py/launcher_deps*.py
idiom already in scripts/: it resolves identically whether the file runs as
a script (script dir already on sys.path) or is loaded through
importlib.util.spec_from_file_location by a test, which is how tests_py
loads every script gate.

XML escaping moves INTO the renderer rather than staying at each call site.
The one bug this code has ever shipped was an unescaped '<' from the
"Top <0.1%" tier making the badge unparseable XML; centralising the escape
means a new generator cannot reintroduce it by forgetting.

Proof of preservation: render_badge(964/81919, 2026-07-28) is byte-identical
to the committed assets/badge-mcp-toplist.svg, and the existing 51 tests pass
unchanged (51 passed in 0.82s).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BJt9KN23rUNQzwoJv4jRWw
---
 scripts/badge_render.py              | 169 +++++++++++++++++++++++++++
 scripts/refresh_mcp_toplist_badge.py | 115 +++++++-----------
 2 files changed, 208 insertions(+), 76 deletions(-)
 create mode 100644 scripts/badge_render.py

diff --git a/scripts/badge_render.py b/scripts/badge_render.py
new file mode 100644
index 00000000..c2318a51
--- /dev/null
+++ b/scripts/badge_render.py
@@ -0,0 +1,169 @@
+"""Shields-style two-panel badge SVG rendering, shared by the badge generators.
+
+Extracted from refresh_mcp_toplist_badge.py when a second generator
+(generate_repo_badges.py) needed the same geometry. Both emit the same
+anatomy — a dark label panel, a coloured message panel, a drop-shadowed
+text run in each — and differ only in their data and provenance.
+
+Two constraints shape every choice here, and neither is negotiable on the
+one surface these badges exist for (a README rendered by GitHub):
+
+  * No <style> block and no external font. GitHub's SVG sanitizer strips
+    both, so a badge depending on either renders unstyled in production
+    while looking correct in every local preview.
+  * Every <text> carries textLength + lengthAdjust. That makes width
+    estimation a cosmetic concern rather than a correctness one: a bad
+    estimate costs letter-spacing, never overflow past the panel edge.
+
+Text and attributes are XML-escaped here rather than at each call site.
+A top-of-field MCP Toplist rank renders its tier as "Top <0.1%", and that
+unescaped '<' made the badge unparseable XML — caught by a test before it
+shipped. Centralising the escape means a new generator cannot reintroduce
+that bug by forgetting it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from xml.sax.saxutils import escape
+
+# source: measured 2026-07-28 — the 19-character string "Top 1.2% · Jul 2026"
+# renders correctly at textLength=110 in Verdana/DejaVu Sans, i.e.
+# 5.79 px/char across this badge set's glyphs (digits, letters, '%', '·',
+# '+', '.', '<'). The set is narrow and fixed, so a per-character mean is
+# adequate; see the module docstring on why accuracy is cosmetic here.
+_PX_PER_CHAR = 5.79
+
+# 7px of padding on each side of the message text, matching the shields.io
+# proportions the surrounding badge row already uses.
+_SIDE_PADDING = 7
+
+_BADGE_HEIGHT = 20
+_FONT_STACK = "Verdana,DejaVu Sans,Geneva,sans-serif"
+_FONT_SIZE = 11
+
+
+def text_width(text: str) -> int:
+    """Nominal px width of badge text at font-size 11.
+
+    Never returns 0: a textLength of 0 collapses the glyphs into a point
+    rather than rendering nothing, which is harder to spot than a wrong width.
+    """
+    return max(1, round(_PX_PER_CHAR * len(text)))
+
+
+@dataclass(frozen=True)
+class Panel:
+    """One side of a badge: its text, its fill, and where the text sits.
+
+    Geometry is explicit rather than derived because the label panel of a
+    badge carrying an icon is not centred on its own midpoint — the icon
+    displaces the text. Deriving it would silently move the MCP Toplist
+    label when this module changed.
+    """
+
+    text: str
+    fill: str
+    text_fill: str
+    width: int
+    text_width: int
+    text_x: float
+
+
+def label_panel(text: str, fill: str, text_fill: str) -> Panel:
+    """A label panel with no icon, sized to its text and centred in itself."""
+    inner = text_width(text)
+    width = inner + _SIDE_PADDING * 2
+    return Panel(
+        text=text,
+        fill=fill,
+        text_fill=text_fill,
+        width=width,
+        text_width=inner,
+        text_x=width / 2,
+    )
+
+
+@dataclass(frozen=True)
+class BadgeSpec:
+    """Everything one badge needs, as a parameter object.
+
+    A dataclass rather than a long parameter list: the renderer would
+    otherwise take eight arguments, past the four-parameter limit, and the
+    call sites would be unreadable positional soup.
+    """
+
+    label: Panel
+    message: str
+    message_fill: str
+    message_text_fill: str
+    alt: str
+    provenance: tuple[str, ...]
+    icon: tuple[str, ...] = field(default_factory=tuple)
+
+
+def _text_pair(x: float, width: int, text: str, fill: str) -> list[str]:
+    """The drop-shadow run and the face run for one label.
+
+    Emitted as a pair because they always occur together: the faint offset
+    copy is what keeps light text legible on the panel fill.
+    """
+    shared = (
+        f'text-anchor="middle" textLength="{width}" lengthAdjust="spacingAndGlyphs"'
+    )
+    return [
+        (
+            f'    <text x="{x:g}" y="15" fill="#000" fill-opacity="0.25" '
+            f"{shared}>{text}</text>"
+        ),
+        f'    <text x="{x:g}" y="14" fill="{fill}" {shared}>{text}</text>',
+    ]
+
+
+def render(spec: BadgeSpec) -> str:
+    """Render a badge to SVG source, newline-terminated.
+
+    The caller supplies the provenance comment: every badge in this repo is
+    a committed file rather than a hotlinked image, so the file has to carry
+    enough for the next maintainer to re-derive its claim without network
+    access. A badge with nothing to say for itself is not one of ours.
+    """
+    message_w = text_width(spec.message)
+    right_w = message_w + _SIDE_PADDING * 2
+    total_w = spec.label.width + right_w
+    message_x = spec.label.width + right_w / 2
+    # Escaped once, here, so no generator can forget it: see module docstring.
+    message_xml = escape(spec.message)
+    label_xml = escape(spec.label.text)
+    alt_xml = escape(spec.alt, {'"': "&quot;"})
+    lines = [
+        (
+            f'<svg xmlns="http://www.w3.org/2000/svg" width="{total_w}"'
+            f' height="{_BADGE_HEIGHT}" viewBox="0 0 {total_w} {_BADGE_HEIGHT}"'
+            f' role="img" aria-label="{alt_xml}">'
+        ),
+        f"  <title>{alt_xml}</title>",
+        *spec.provenance,
+        '  <clipPath id="r">',
+        f'    <rect width="{total_w}" height="{_BADGE_HEIGHT}" rx="3" fill="#fff"/>',
+        "  </clipPath>",
+        '  <g clip-path="url(#r)">',
+        f'    <rect width="{spec.label.width}" height="{_BADGE_HEIGHT}"'
+        f' fill="{spec.label.fill}"/>',
+        f'    <rect x="{spec.label.width}" width="{right_w}"'
+        f' height="{_BADGE_HEIGHT}" fill="{spec.message_fill}"/>',
+        "  </g>",
+        *spec.icon,
+        f'  <g font-family="{_FONT_STACK}" font-size="{_FONT_SIZE}">',
+        *_text_pair(
+            spec.label.text_x,
+            spec.label.text_width,
+            label_xml,
+            spec.label.text_fill,
+        ),
+        *_text_pair(message_x, message_w, message_xml, spec.message_text_fill),
+        "  </g>",
+        "</svg>",
+        "",
+    ]
+    return "\n".join(lines)
diff --git a/scripts/refresh_mcp_toplist_badge.py b/scripts/refresh_mcp_toplist_badge.py
index 6dd3d692..77b756eb 100644
--- a/scripts/refresh_mcp_toplist_badge.py
+++ b/scripts/refresh_mcp_toplist_badge.py
@@ -44,7 +44,17 @@
 from datetime import date, timezone, datetime
 from pathlib import Path
 from typing import Callable, Iterable
-from xml.sax.saxutils import escape
+
+# badge_render.py is a stdlib-only sibling module (the shields-style SVG
+# geometry, shared with generate_repo_badges.py). Path-based import for the
+# same reason the launcher family path-imports its siblings: resolves
+# identically whether this file is run as a script (script dir already on
+# sys.path) or loaded directly via importlib.util.spec_from_file_location
+# from a test.
+_SCRIPTS_DIR = str(Path(__file__).resolve().parent)
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+import badge_render  # noqa: E402
 
 SERVER_ID = "io.github.cdeust/hypermnesia-mcp"
 LEADERBOARD_URL = "https://mcptoplist.com/data/leaderboard.json"
@@ -199,41 +209,6 @@ def parse_server_page(html: str) -> Ranking:
     return validate(match.group(1), match.group(2), "server page")
 
 
-def _text_width(text: str) -> int:
-    """Nominal px width of badge text at font-size 11.
-
-    source: measured 2026-07-28 — the 19-character string
-    "Top 1.2% · Jul 2026" renders correctly at textLength=110 in
-    Verdana/DejaVu Sans, i.e. 5.79 px/char across this badge's glyph set
-    (digits, lowercase, '%', '·', '<'). The set is narrow and fixed, so a
-    per-character mean is adequate here.
-
-    Correctness does not depend on this estimate: every <text> is emitted
-    with textLength + lengthAdjust, which SCALES the glyphs into the width
-    given. An inaccurate estimate therefore costs letter-spacing, never
-    overflow past the panel edge.
-    """
-    return max(1, round(5.79 * len(text)))
-
-
-def _text_pair(x: float, width: int, text: str, fill: str) -> list[str]:
-    """The drop-shadow run and the face run for one label.
-
-    Emitted as a pair because they always occur together: the faint offset
-    copy is what keeps light text legible on the panel fill.
-    """
-    shared = (
-        f'text-anchor="middle" textLength="{width}" lengthAdjust="spacingAndGlyphs"'
-    )
-    return [
-        (
-            f'    <text x="{x:g}" y="15" fill="#000" fill-opacity="0.25" '
-            f"{shared}>{text}</text>"
-        ),
-        f'    <text x="{x:g}" y="14" fill="{fill}" {shared}>{text}</text>',
-    ]
-
-
 def _provenance_comment(ranking: Ranking, as_of: date) -> list[str]:
     """The audit trail the badge carries in its own source.
 
@@ -260,51 +235,39 @@ def _provenance_comment(ranking: Ranking, as_of: date) -> list[str]:
 def render_badge(ranking: Ranking, as_of: date) -> str:
     """Render the badge SVG.
 
-    No <style> block and no external font: GitHub's SVG sanitizer strips
-    both, so a badge depending on either renders unstyled on the one
-    surface it exists for. Palette is assets/banner.svg's.
+    Geometry, escaping and the no-<style>/no-external-font constraints live
+    in badge_render; what stays here is what makes this badge THIS badge —
+    the bar icon, the banner palette, and the wording of the claim.
     """
     tier = ranking.tier_text()
     stamp = f"{_MONTHS[as_of.month - 1]} {as_of.year}"
-    message = f"{tier} · {stamp}"
-    msg_w = _text_width(message)
-    right_w = msg_w + 14  # 7px padding each side
-    label_w = _LABEL_PANEL_W
-    total_w = label_w + right_w
-    msg_mid = label_w + right_w / 2
     alt = f"MCP Toplist: {tier} of {ranking.total:,} tracked MCP servers, {stamp}"
-    # A top-of-field rank renders the tier as "Top <0.1%"; that '<' must not
-    # reach markup unescaped or the badge stops being parseable XML.
-    message_xml = escape(message)
-    alt_xml = escape(alt, {'"': "&quot;"})
-    lines = [
-        (
-            f'<svg xmlns="http://www.w3.org/2000/svg" width="{total_w}"'
-            f' height="20" viewBox="0 0 {total_w} 20" role="img"'
-            f' aria-label="{alt_xml}">'
+    label = badge_render.Panel(
+        text="MCP Toplist",
+        fill="#3b3129",
+        text_fill="#f8f7f2",
+        # Explicit, not derived: the bar icon displaces the label text, so
+        # this panel is not centred on its own midpoint.
+        width=_LABEL_PANEL_W,
+        text_width=_LABEL_TEXT_W,
+        text_x=54,
+    )
+    spec = badge_render.BadgeSpec(
+        label=label,
+        message=f"{tier} · {stamp}",
+        message_fill="#a53e00",
+        message_text_fill="#fff",
+        alt=alt,
+        provenance=tuple(_provenance_comment(ranking, as_of)),
+        icon=(
+            '  <g fill="#f1eee7">',
+            '    <rect x="7" y="10" width="2.6" height="5" rx="0.6"/>',
+            '    <rect x="11.2" y="6.5" width="2.6" height="8.5" rx="0.6"/>',
+            '    <rect x="15.4" y="8.4" width="2.6" height="6.6" rx="0.6"/>',
+            "  </g>",
         ),
-        f"  <title>{alt_xml}</title>",
-        *_provenance_comment(ranking, as_of),
-        '  <clipPath id="r">',
-        f'    <rect width="{total_w}" height="20" rx="3" fill="#fff"/>',
-        "  </clipPath>",
-        '  <g clip-path="url(#r)">',
-        f'    <rect width="{label_w}" height="20" fill="#3b3129"/>',
-        f'    <rect x="{label_w}" width="{right_w}" height="20" fill="#a53e00"/>',
-        "  </g>",
-        '  <g fill="#f1eee7">',
-        '    <rect x="7" y="10" width="2.6" height="5" rx="0.6"/>',
-        '    <rect x="11.2" y="6.5" width="2.6" height="8.5" rx="0.6"/>',
-        '    <rect x="15.4" y="8.4" width="2.6" height="6.6" rx="0.6"/>',
-        "  </g>",
-        '  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">',
-        *_text_pair(54, _LABEL_TEXT_W, "MCP Toplist", "#f8f7f2"),
-        *_text_pair(msg_mid, msg_w, message_xml, "#fff"),
-        "  </g>",
-        "</svg>",
-        "",
-    ]
-    return "\n".join(lines)
+    )
+    return badge_render.render(spec)
 
 
 def fetch(url: str, opener: Callable = urllib.request.urlopen) -> bytes:

From 18d4505d58bb812797739d1b7918611c43a45769 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Tue, 28 Jul 2026 22:05:35 +0200
Subject: [PATCH 2/4] feat(docs): self-host the repo-derived README badges
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's five repo-derived badges were remote images: a third-party
request fired on every view, and a claim about this repository that its
host could restate at any time with no commit here. Each of those five
figures is determined by the working tree, so a committed SVG can always
be made true again by regenerating it, with no network at all.

scripts/generate_repo_badges.py renders them from the canonical readers
already used by the doc-claims gate — not reimplementations of them, since
a badge that disagreed with the gate is the exact drift this prevents. It
runs as a blocking check on every push and PR: `--check` in the static
job for the four file-derived badges, and `--check --test-count` in the
test job, where the collected count is known.

Converting the badges alone would have silently disabled two gates.
check_doc_claims.py matched the version and test figures by regex over
the shields.io URLs; against the new README those patterns find nothing
and both checks pass quietly. They now read each figure from the
committed SVG's <title> via check_badge(), which fails closed on a
missing file and on a title it cannot match, and check_no_hotlinked_badges()
rejects any reintroduced img.shields.io so the reversion is loud.

Two badges are deliberately left live. The CI status badge reflects the
last run on main; a committed copy would assert "passing" while main was
broken, which is false by construction rather than merely stale, and it
is GitHub-hosted so it is not a third-party beacon. The OpenSSF badge is
an external body's live assessment that can be downgraded without a
commit here, and .bestpractices.json justifies displaying their image.

badge_render.render() now parses its own output and raises
BadgeMarkupError on anything not well-formed: a provenance comment
containing "--" is illegal inside an XML comment and produced five
unparseable badges during this work. The guard sits on the finished
artifact rather than on any one way to break it.

Also syncs the advertised suite size 6348 -> 6373 across 11 sites in 6
files, the count the 51 new tests move it to.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BJt9KN23rUNQzwoJv4jRWw
---
 .bestpractices.json                           |   8 +-
 .github/workflows/ci.yml                      |  13 +
 CHANGELOG.md                                  |   3 +-
 CLAUDE.md                                     |   2 +-
 CONTRIBUTING.md                               |   4 +-
 README.md                                     |  12 +-
 assets/badge-license.svg                      |  21 ++
 assets/badge-python.svg                       |  21 ++
 assets/badge-references.svg                   |  21 ++
 assets/badge-tests.svg                        |  21 ++
 assets/badge-version.svg                      |  21 ++
 docs/ASSURANCE-CASE.md                        |   2 +-
 scripts/badge_render.py                       |  20 +-
 scripts/check_doc_claims.py                   |  69 ++++-
 scripts/generate_repo_badges.py               | 261 +++++++++++++++++
 tests_py/scripts/test_check_doc_claims.py     |  84 ++++--
 tests_py/scripts/test_generate_repo_badges.py | 264 ++++++++++++++++++
 17 files changed, 803 insertions(+), 44 deletions(-)
 create mode 100644 assets/badge-license.svg
 create mode 100644 assets/badge-python.svg
 create mode 100644 assets/badge-references.svg
 create mode 100644 assets/badge-tests.svg
 create mode 100644 assets/badge-version.svg
 create mode 100644 scripts/generate_repo_badges.py
 create mode 100644 tests_py/scripts/test_generate_repo_badges.py

diff --git a/.bestpractices.json b/.bestpractices.json
index dce3b9aa..ebabe673 100644
--- a/.bestpractices.json
+++ b/.bestpractices.json
@@ -99,7 +99,7 @@
   "build_floss_tools_justification": "pip, uv, hatchling, pytest, ruff and pyright are all FLOSS, and the build runs on ubuntu-latest and windows-latest GitHub runners.",
 
   "test_status": "Met",
-  "test_justification": "An automated test suite of 6348 tests lives under tests_py/ (measured 2026-07-28 with 'pytest --collect-only -q'), covering core, handlers, infrastructure, integration, invariants and architecture: https://github.com/cdeust/Cortex/tree/main/tests_py",
+  "test_justification": "An automated test suite of 6373 tests lives under tests_py/ (measured 2026-07-28 with 'pytest --collect-only -q'), covering core, handlers, infrastructure, integration, invariants and architecture: https://github.com/cdeust/Cortex/tree/main/tests_py",
 
   "test_invocation_status": "Met",
   "test_invocation_justification": "The whole suite runs with a single 'pytest' command, documented in CONTRIBUTING.md under Testing along with per-layer subsets: https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md",
@@ -114,7 +114,7 @@
   "test_policy_justification": "CONTRIBUTING.md carries an explicit, mandatory testing policy: new functionality ships with tests in the automated suite, a bug fix carries a regression test that fails on the pre-fix code, and each failure path asserts its observable effect including the signal it emits \u2014 https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory. The per-tool checklist ('Add a unit test', 'Add an integration test if the tool touches the database') and the five-element mechanism checklist restate it per change type.",
 
   "tests_are_added_status": "Met",
-  "tests_are_added_justification": "New functionality ships with its tests; the suite has grown to 6348 tests alongside the v4.x feature series, and CI runs it on every pull request.",
+  "tests_are_added_justification": "New functionality ships with its tests; the suite has grown to 6373 tests alongside the v4.x feature series, and CI runs it on every pull request.",
 
   "tests_documented_added_status": "Met",
   "tests_documented_added_justification": "The requirement is written into the documented instructions for change proposals: https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory states that every change adding or altering observable behaviour must arrive with tests in the same PR, the per-tool and per-mechanism checklists repeat it as a concrete step, and .github/PULL_REQUEST_TEMPLATE.md requires a Test plan section in every pull request.",
@@ -189,7 +189,7 @@
   "static_analysis_often_justification": "CodeQL default setup analyses each push and pull request and additionally runs on a weekly schedule, so analysis happens per change rather than per release.",
 
   "dynamic_analysis_status": "Unmet",
-  "dynamic_analysis_justification": "No dynamic analysis tool in the badge's sense (fuzzer, sanitizer, or scanner) is applied. The project runs a 6348-test suite with coverage on every change, but a test suite is not a dynamic analysis tool and is not claimed as one here.",
+  "dynamic_analysis_justification": "No dynamic analysis tool in the badge's sense (fuzzer, sanitizer, or scanner) is applied. The project runs a 6373-test suite with coverage on every change, but a test suite is not a dynamic analysis tool and is not claimed as one here.",
 
   "dynamic_analysis_unsafe_status": "N/A",
   "dynamic_analysis_unsafe_justification": "Cortex is written in Python, a memory-safe language, so the memory-safety tooling this criterion asks about (ASan, Valgrind) does not apply.",
@@ -297,7 +297,7 @@
   "interfaces_current_justification": "The stack targets currently supported runtimes and APIs: Python 3.10 through 3.13, all four in the CI matrix, with pgvector 0.3+/PostgreSQL 17 and current major versions of FastMCP, Pydantic v2, numpy and sentence-transformers. Deprecated interfaces are removed rather than wrapped \u2014 the standing rule is one-shot migrations with no back-compat shims (CLAUDE.md), and CI runs on the newest released Python so a deprecation surfaces as a warning in the build rather than as a surprise at end of life.",
 
   "automated_integration_testing_status": "Met",
-  "automated_integration_testing_justification": "The full suite runs on every push and pull request to main via .github/workflows/ci.yml and reports success or failure per job: 6348 tests on Python 3.10-3.13 against PostgreSQL + pgvector, the same suite against the SQLite backend, the suite on Windows, and a Docker smoke job that boots the bare container and exercises the DB-less contract. tests_py/integration/ holds the database-backed integration tests specifically.",
+  "automated_integration_testing_justification": "The full suite runs on every push and pull request to main via .github/workflows/ci.yml and reports success or failure per job: 6373 tests on Python 3.10-3.13 against PostgreSQL + pgvector, the same suite against the SQLite backend, the suite on Windows, and a Docker smoke job that boots the bare container and exercises the DB-less contract. tests_py/integration/ holds the database-backed integration tests specifically.",
 
   "regression_tests_added50_status": "Met",
   "regression_tests_added50_justification": "Measured on 2026-07-27 over the merged pull requests titled as fixes in the preceding six months (2026-01-27 onward): 23 of 30 \u2014 76.7% \u2014 changed the test tree in the same PR, against the 50% this criterion asks for. (The measure counts a PR as carrying tests when it touches tests_py/ or tests_js/, which is a proxy for 'added a regression test'; the policy behind it is written down at https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory \u2014 a bug fix carries a regression test that fails on the pre-fix code.)",
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 902b4f31..7bde5aa8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -173,6 +173,10 @@ jobs:
           fi
           echo "collected ${collected} tests"
           python scripts/check_doc_claims.py --test-count "${collected}"
+          # The tests badge is a committed SVG carrying this same number, so
+          # it is checked where the number is known. The other repo-derived
+          # badges are checked in the static job, which needs no suite.
+          python scripts/generate_repo_badges.py --check --test-count "${collected}"
 
       - name: Upload coverage
         if: matrix.python-version == '3.12'
@@ -395,6 +399,15 @@ jobs:
       - name: Check documentation claims
         run: python scripts/check_doc_claims.py
 
+      # The README's repo-derived badges are committed SVGs, not hotlinked
+      # images, so nothing regenerates them on view: a figure that moves
+      # leaves the badge asserting the old one. Checked here, on every push
+      # and PR, because that drift is introduced at commit time. Static only
+      # (no network, no suite) — the tests badge needs a collected count and
+      # is checked in the test job instead.
+      - name: Check committed badges
+        run: python scripts/generate_repo_badges.py --check
+
   typecheck:
     name: Type Check
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c74cb08..34637085 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,8 @@ adheres to [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
-- **MCP Toplist rank badge, self-hosted and refreshed on a cron** — `assets/badge-mcp-toplist.svg`, `scripts/refresh_mcp_toplist_badge.py`, `.github/workflows/mcp-toplist-badge.yml`. The badge records that Cortex ranks in the top 1.2% of MCP servers tracked by MCP Toplist (#964 of 81,919, read 2026-07-28). It is a **committed file, not a hotlinked remote image**: a remote badge URL is a third-party beacon fired on every README view, and it lets its host restate the claim at any time with no commit in this repository. The arriving PR (#241, closed) proposed exactly that. The cost of the static choice is that the badge cannot self-update — the date it carries is part of the claim and goes stale by INACTION, and inaction never opens a PR — so a monthly workflow regenerates it and proposes the diff. Monthly is deliberate: the badge stamps a month, so it is the least frequent cadence that keeps the date honest and the most frequent one that does not churn a PR proposing an identical file. Wording is **attributive throughout** (`RANKED in this tier by MCP Toplist`, never `is a top-1.2% server`), because upstream's own methodology page states the score "is a popularity and activity signal, not a quality assessment" and keeps ~25% of its weighting (organic reach, package downloads) undisclosed — the figure is attributable, not reproducible. Every generated SVG carries its own audit trail in a comment: source path, raw rank and field size, the percentile arithmetic, and the verify URL, so the next maintainer can re-derive the claim from the file alone. **Two extraction paths, fail-closed:** the structured export at `/data/leaderboard.json` is tried first but returns HTTP 503 (measured 2026-07-28: 3/3 attempts, 8–14s each under a browser UA, i.e. a server-side generation timeout, not UA gating or rate limiting), so its schema has never been observed and the parser accepts only a narrow set of documented candidate shapes under strict validation rather than guessing at one; the fallback is the server page's prose sentence `ranks #N of M servers tracked`, the ONLY construct on that page carrying both numbers (the `<title>`, og/twitter meta tags and all four JSON-LD blocks carry the rank without the total, so none can yield a percentile). Both paths feed one validator that refuses a non-numeric, zero, negative, or beyond-the-field figure — guarding the division in `percentile()` and the semantics of the claim — and a figure that fails validation is **never written**: the script exits non-zero, the badge keeps its last good value, and the run goes red. A fallback is never silent; the path that failed is reported even when a later one succeeds. No `pull_request` trigger, so a required check never depends on a third party's uptime; the 51 unit tests cover the logic with no network at all. Caught by those tests before shipping: a top-of-field rank renders the tier as `Top <0.1%`, whose unescaped `<` **made the badge invalid XML** — text and attributes are now XML-escaped, verified across the rank-1, mid-field and last-place boundaries. Note that PRs opened with the default `GITHUB_TOKEN` do not trigger workflows, so `main`'s required checks will not start on them; the workflow prefers an optional `BADGE_REFRESH_TOKEN` secret when present. Suite grows 6297 → 6348.
+- **The README's repo-derived badges are now self-hosted SVGs, gated in CI** — `assets/badge-{license,python,tests,references,version}.svg`, `scripts/generate_repo_badges.py`, `scripts/badge_render.py`. Five hotlinked `img.shields.io` images became committed files, for the reason the MCP Toplist badge already was one: a remote badge URL is a third-party request fired on every README view, and it lets its host restate our claim with no commit in this repository. **Only repo-derived figures were converted**, and the line is deliberate — every one of these (licence, Python floor, collected test count, bibliography size, package version) is determined BY THIS REPOSITORY, so a committed copy can always be made true again from the working tree with no network access. That is why they are kept honest by a **blocking `--check` gate on every push and PR** rather than by a cron: drift is caught where it is introduced. **Two badges were deliberately NOT converted and must not be:** the CI status badge reports the LIVE result of the last run on main, so a committed copy would assert "passing" while main was broken — a static build-status badge is a false claim by construction, not merely a stale one — and it is GitHub-hosted, so it is not a third-party beacon in the first place; the OpenSSF Best Practices badge reflects an external body's live assessment that can be downgraded without any commit here, and `.bestpractices.json` separately justifies displaying THEIR badge image. The MCP Toplist badge sits between the two and stays committed because it carries an explicit "as of <month>" stamp, which keeps a stale copy a true statement about a point in time. **The conversion had to rewire the gate it would otherwise have silenced:** `check_doc_claims.py` enforced the version and test-count claims by regex over the shields.io URLs (`badge/version-(\d+\.\d+\.\d+)`, `badge/tests-(\d+)_passing`), so self-hosting alone would have left both patterns matching nothing while the gate still reported success. They now read the figure out of the committed SVG's own `<title>` and **fail closed** on a missing file or an unmatched title — the predecessor's `if badge and ...` passed silently the moment its subject disappeared. A new check also fails any reintroduced `img.shields.io` hotlink in the README, so reverting this is loud rather than quiet. Found by the new tests before shipping: `--` is illegal inside an XML comment, and the first cut described its own gate as `--check` and its source as `pytest --collect-only` in the provenance comment, leaving **all five badges unparseable**; the renderer now parses every badge it produces and refuses to return one that is not well-formed, so no future wording can reintroduce the class. The shared renderer was extracted from the MCP Toplist refresher first, as a separate behavior-preserving commit whose proof is that `assets/badge-mcp-toplist.svg` is byte-identical and its 51 tests pass unchanged. Suite grows 6348 → 6373.
+- **MCP Toplist rank badge, self-hosted and refreshed on a cron** — `assets/badge-mcp-toplist.svg`, `scripts/refresh_mcp_toplist_badge.py`, `.github/workflows/mcp-toplist-badge.yml`. The badge records that Cortex ranks in the top 1.2% of MCP servers tracked by MCP Toplist (#964 of 81,919, read 2026-07-28). It is a **committed file, not a hotlinked remote image**: a remote badge URL is a third-party beacon fired on every README view, and it lets its host restate the claim at any time with no commit in this repository. The arriving PR (#241, closed) proposed exactly that. The cost of the static choice is that the badge cannot self-update — the date it carries is part of the claim and goes stale by INACTION, and inaction never opens a PR — so a monthly workflow regenerates it and proposes the diff. Monthly is deliberate: the badge stamps a month, so it is the least frequent cadence that keeps the date honest and the most frequent one that does not churn a PR proposing an identical file. Wording is **attributive throughout** (`RANKED in this tier by MCP Toplist`, never `is a top-1.2% server`), because upstream's own methodology page states the score "is a popularity and activity signal, not a quality assessment" and keeps ~25% of its weighting (organic reach, package downloads) undisclosed — the figure is attributable, not reproducible. Every generated SVG carries its own audit trail in a comment: source path, raw rank and field size, the percentile arithmetic, and the verify URL, so the next maintainer can re-derive the claim from the file alone. **Two extraction paths, fail-closed:** the structured export at `/data/leaderboard.json` is tried first but returns HTTP 503 (measured 2026-07-28: 3/3 attempts, 8–14s each under a browser UA, i.e. a server-side generation timeout, not UA gating or rate limiting), so its schema has never been observed and the parser accepts only a narrow set of documented candidate shapes under strict validation rather than guessing at one; the fallback is the server page's prose sentence `ranks #N of M servers tracked`, the ONLY construct on that page carrying both numbers (the `<title>`, og/twitter meta tags and all four JSON-LD blocks carry the rank without the total, so none can yield a percentile). Both paths feed one validator that refuses a non-numeric, zero, negative, or beyond-the-field figure — guarding the division in `percentile()` and the semantics of the claim — and a figure that fails validation is **never written**: the script exits non-zero, the badge keeps its last good value, and the run goes red. A fallback is never silent; the path that failed is reported even when a later one succeeds. No `pull_request` trigger, so a required check never depends on a third party's uptime; the 51 unit tests cover the logic with no network at all. Caught by those tests before shipping: a top-of-field rank renders the tier as `Top <0.1%`, whose unescaped `<` **made the badge invalid XML** — text and attributes are now XML-escaped, verified across the rank-1, mid-field and last-place boundaries. Note that PRs opened with the default `GITHUB_TOKEN` do not trigger workflows, so `main`'s required checks will not start on them; the workflow prefers an optional `BADGE_REFRESH_TOKEN` secret when present. Suite grows 6297 → 6373.
 - **Pyright is now a zero-diagnostic blocking gate** (#197, final family of the maximal-strictness program). The 568-diagnostic per-rule ratchet backlog was burned to **zero** at `typeCheckingMode: "standard"` (pyright 1.1.410, measured 2026-07-28): no rule disabled, no floor raised; the single per-site suppression is the unpublished optional `cortex_beam_abstain` import whose `except ImportError` arm is the documented degraded mode. The ratchet machinery (`typecheck-baseline.json` + `scripts/check_pyright_ratchet.py`) is retired — CI fails on ANY diagnostic via pyright's own exit code, and the CI type-check env installs the `[otel]` extra so the exporter imports resolve. The burn-down was fixes, not annotations-to-match: a typed host contract for the eight `PgMemoryStore` mixins (`pg_store_host.PgStoreHost` + `MaterializedCursor`, whose honest `DictRow` typing surfaced ten unchecked `INSERT..RETURNING` sites, now `one()` with a real error), a cross-backend `StoreConnection` union for the 16 shared query modules (the psycopg-only annotation had switched checking off for every SQLite call path), and **SQLite store parity for eight methods callers already used unconditionally** — `acquire_interactive`/`acquire_batch`, `_execute`, `search_newer_neighbors`, `update_forgetting_pressure_accum`, `get_memories_by_tag`, `iter_memories_for_decay`, `find_co_accessed_pairs` — each of which previously raised `AttributeError` on the SQLite backend and was swallowed into silent degradation by broad stage boundaries. Latent bugs fixed en route, each with a regression test: the compat cursor lacked `executemany` (SQLite wiki page-sources writes crashed), `lastrowid` honesty (insert paths now raise on a broken row-id contract instead of masking it with a stale `type: ignore`), the pipeline installer accepted a success result carrying no cargo path (None flowed into the build argv), `update_style_ema(None, None)` returned `None` against a `dict` signature, `encode_session` died with a bare `TypeError` on a direction-less feature (now refuses loudly, naming it), `get_causal_chain` could return `reason=None`, and active forgetting sent a `None` timestamp into the store. `.bestpractices.json` flips `warnings_strict` to **Met**, citing the ruff select list, the pyright mode, and the measured zero. Suite grows 6275 → 6297.
 - **ruff `PLC0415` (import-outside-top-level) and `S608` (string-built SQL) are now blocking lint gates** (#197, fourth rule family of the maximal-strictness program). All 520 production `PLC0415` findings (407 `mcp_server/`, 57 `benchmarks/`, 56 `scripts/`) were triaged one by one: **360 lazy imports moved to module top** — so the import graph is static and a broken module fails at boot, not mid-operation — and the 160 that remain each carry a per-site `# noqa: PLC0415 — <reason>` naming one of six sanctioned justifications: an optional dependency behind an extra, an internal module whose top-level closure hard-imports one (hoisting would break `[sqlite]`-only installs at import time), an ImportError-probe boundary where the except arm IS the degraded mode, an import cycle (partner named; the pre-existing #233 family), the hook latency boundary (per-event hook processes boot in ~0.05 s vs ~0.6 s for the registry closure, measured 2026-07-28 — hoisting the handler/store stack into a hook would multiply every hook event's cost), or a deferral the module itself documents. The hoist is behavior-preserving: the per-module import sweep matches the pre-change baseline exactly (515 modules, the same 6 pre-existing cycle failures), and warm import timings are unchanged. All 44 production `S608` sites carry a per-site `# noqa: S608 — <mechanism>` naming the exact reason the interpolation is safe (two-literal ternaries, generated placeholder lists, module-level `WHERE` literals, or allowlist-gated identifiers per `docs/ASSURANCE-CASE.md` §5), so any NEW string-built SQL fails CI until it states its mechanism. `tests_py/**` adds both rules to its written per-file ignore (function-level imports in tests are the fixture mechanism; SQL built in tests is fixture setup against a throwaway database).
 - **ruff `PLR2004` (magic-value comparison) and `E501` (line-too-long) are now blocking lint gates** (#197, third rule family of the maximal-strictness program). All 420 production `PLR2004` findings (339 `mcp_server/`, 57 `benchmarks/`, 14 `scripts/`, 10 `video/`) were fixed with **zero `# noqa: PLR2004`**: every compared literal became a named constant carrying a `# source:` comment — a real citation where the module documents one (Frey & Morris 1997 / Kandel 2001 / Tse 2007 cascade thresholds, RFC 9110 status bands, FIPS 180-4 digest lengths, issue-quoted gates), a structural rationale for arities (split-parts, tuple lengths), and an explicit `pre-existing tuned value, extracted unchanged; provenance not recorded at introduction` where none is discoverable — never an invented source. `tests_py/**` carries a written per-file ignore (the compared literal in an assertion IS the expected value under test — the spec itself). All 470 `E501` findings (263 `mcp_server/`, 121 `tests_py/`, 48 `benchmarks/`, 37 `scripts/`, 1 `_pipeline`) were fixed by **rewrapping at the unchanged 88-column formatter limit** — string content kept byte-identical via implicit concatenation at existing whitespace (SQL and regex literals machine-verified byte-for-byte) — with exactly two per-site `# noqa: E501 — <reason>` for unsplittable absolute-path tokens; E501 has **no** tests ignore. Two drift risks were closed at the source: `handlers/consolidation/transfer.py` re-declared as bare literals the canonical constants of `core/two_stage_transfer.py` (whose own comment forbids redefinition) and now imports them; `benchmarks/beam/ablation.py`'s copies are named per-module without value drift.
diff --git a/CLAUDE.md b/CLAUDE.md
index daf9be1b..ed5cb271 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ coding write gates, causal graphs, and intent-aware retrieval.
 
 - Install (dev): `uv pip install -e ".[dev]"` — SQLite backend: `".[dev,sqlite]"`
 - Environment preflight: `python -m mcp_server.doctor` (backend-aware check list, fix message per check)
-- Tests: `pytest` (full suite, 6348 tests) · `pytest tests_py/core/` (one layer) · `pytest --cov=mcp_server --cov-report=term-missing`
+- Tests: `pytest` (full suite, 6373 tests) · `pytest tests_py/core/` (one layer) · `pytest --cov=mcp_server --cov-report=term-missing`
 - Lint BEFORE every commit: `ruff check && ruff format --check` — the CI enforces **both**; passing only `ruff check` is not enough.
 - Release gate benchmarks (isolated, ephemeral container — the only source
   of truth for pre-tag/floor decisions): `benchmarks/reproduce.sh`. Do NOT
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ec9e3e0d..2e521e73 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,7 +46,7 @@ bash scripts/setup.sh        # macOS / Linux
 # Verify everything is wired
 uvx --python 3.13 --from "hypermnesia-mcp[postgresql]" cortex-doctor
 
-# Run tests (6348 tests under tests_py/)
+# Run tests (6373 tests under tests_py/)
 pytest
 
 # Run a benchmark
@@ -134,7 +134,7 @@ The full standard lives in
 ## Testing
 
 ```bash
-pytest                              # full suite (6348 tests)
+pytest                              # full suite (6373 tests)
 pytest tests_py/core                # core (pure business logic) only
 pytest tests_py/integration         # PostgreSQL-backed integration
 pytest tests_py/benchmarks -k locomo # subset
diff --git a/README.md b/README.md
index 75e02af2..a81fe014 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,11 @@
 
 <p align="center">
   <a href="https://github.com/cdeust/Cortex/actions/workflows/ci.yml"><img src="https://github.com/cdeust/Cortex/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
-  <img src="https://img.shields.io/badge/tests-6348_passing-brightgreen.svg" alt="6348 passing">
-  <img src="https://img.shields.io/badge/references-97_papers-orange.svg" alt="References">
-  <img src="https://img.shields.io/badge/version-4.16.0-brightgreen.svg" alt="Version 4.16.0">
+  <a href="LICENSE"><img src="assets/badge-license.svg" alt="License: MIT"></a>
+  <img src="assets/badge-python.svg" alt="Python 3.10+">
+  <img src="assets/badge-tests.svg" alt="6373 tests passing">
+  <img src="assets/badge-references.svg" alt="97 referenced papers">
+  <img src="assets/badge-version.svg" alt="Version 4.16.0">
   <a href="https://www.bestpractices.dev/projects/13836"><img src="https://www.bestpractices.dev/projects/13836/badge" alt="OpenSSF Best Practices"></a>
   <a href="https://mcptoplist.com/server/io.github.cdeust%2Fhypermnesia-mcp"><img src="assets/badge-mcp-toplist.svg" alt="MCP Toplist: Top 1.2% of 81,919 tracked MCP servers, July 2026"></a>
 </p>
@@ -526,7 +526,7 @@ Cortex is **local-first**: your memories, conversations, and profiles stay on yo
 ## Development
 
 ```bash
-pytest                    # 6348 tests
+pytest                    # 6373 tests
 ruff check .              # Lint
 ruff format --check .     # Format
 python scripts/check_doc_claims.py   # advertised counts must match the repo
diff --git a/assets/badge-license.svg b/assets/badge-license.svg
new file mode 100644
index 00000000..2e3f7c37
--- /dev/null
+++ b/assets/badge-license.svg
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="86" height="20" viewBox="0 0 86 20" role="img" aria-label="License: MIT">
+  <title>License: MIT</title>
+  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.
+       Source: [project].license in pyproject.toml.
+       Committed rather than hotlinked so the claim cannot be
+       restated by a third party without a commit here; kept true
+       by the generate_repo_badges check, a blocking CI gate. -->
+  <clipPath id="r">
+    <rect width="86" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="55" height="20" fill="#3b3129"/>
+    <rect x="55" width="31" height="20" fill="#31708f"/>
+  </g>
+  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+    <text x="27.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="41" lengthAdjust="spacingAndGlyphs">license</text>
+    <text x="27.5" y="14" fill="#f8f7f2" text-anchor="middle" textLength="41" lengthAdjust="spacingAndGlyphs">license</text>
+    <text x="70.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="17" lengthAdjust="spacingAndGlyphs">MIT</text>
+    <text x="70.5" y="14" fill="#fff" text-anchor="middle" textLength="17" lengthAdjust="spacingAndGlyphs">MIT</text>
+  </g>
+</svg>
diff --git a/assets/badge-python.svg b/assets/badge-python.svg
new file mode 100644
index 00000000..6da8f2e8
--- /dev/null
+++ b/assets/badge-python.svg
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="92" height="20" viewBox="0 0 92 20" role="img" aria-label="Python 3.10+">
+  <title>Python 3.10+</title>
+  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.
+       Source: [project].requires-python in pyproject.toml.
+       Committed rather than hotlinked so the claim cannot be
+       restated by a third party without a commit here; kept true
+       by the generate_repo_badges check, a blocking CI gate. -->
+  <clipPath id="r">
+    <rect width="92" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="49" height="20" fill="#3b3129"/>
+    <rect x="49" width="43" height="20" fill="#31708f"/>
+  </g>
+  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+    <text x="24.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="35" lengthAdjust="spacingAndGlyphs">python</text>
+    <text x="24.5" y="14" fill="#f8f7f2" text-anchor="middle" textLength="35" lengthAdjust="spacingAndGlyphs">python</text>
+    <text x="70.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="29" lengthAdjust="spacingAndGlyphs">3.10+</text>
+    <text x="70.5" y="14" fill="#fff" text-anchor="middle" textLength="29" lengthAdjust="spacingAndGlyphs">3.10+</text>
+  </g>
+</svg>
diff --git a/assets/badge-references.svg b/assets/badge-references.svg
new file mode 100644
index 00000000..35f80e14
--- /dev/null
+++ b/assets/badge-references.svg
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="138" height="20" viewBox="0 0 138 20" role="img" aria-label="97 referenced papers">
+  <title>97 referenced papers</title>
+  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.
+       Source: entries under '## References' in docs/papers/bibliography.md.
+       Committed rather than hotlinked so the claim cannot be
+       restated by a third party without a commit here; kept true
+       by the generate_repo_badges check, a blocking CI gate. -->
+  <clipPath id="r">
+    <rect width="138" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="72" height="20" fill="#3b3129"/>
+    <rect x="72" width="66" height="20" fill="#a53e00"/>
+  </g>
+  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+    <text x="36" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="58" lengthAdjust="spacingAndGlyphs">references</text>
+    <text x="36" y="14" fill="#f8f7f2" text-anchor="middle" textLength="58" lengthAdjust="spacingAndGlyphs">references</text>
+    <text x="105" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="52" lengthAdjust="spacingAndGlyphs">97 papers</text>
+    <text x="105" y="14" fill="#fff" text-anchor="middle" textLength="52" lengthAdjust="spacingAndGlyphs">97 papers</text>
+  </g>
+</svg>
diff --git a/assets/badge-tests.svg b/assets/badge-tests.svg
new file mode 100644
index 00000000..df2f7d2b
--- /dev/null
+++ b/assets/badge-tests.svg
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="126" height="20" viewBox="0 0 126 20" role="img" aria-label="6373 tests passing">
+  <title>6373 tests passing</title>
+  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.
+       Source: the count pytest collects on this tree.
+       Committed rather than hotlinked so the claim cannot be
+       restated by a third party without a commit here; kept true
+       by the generate_repo_badges check, a blocking CI gate. -->
+  <clipPath id="r">
+    <rect width="126" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="43" height="20" fill="#3b3129"/>
+    <rect x="43" width="83" height="20" fill="#2f6f3e"/>
+  </g>
+  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+    <text x="21.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="29" lengthAdjust="spacingAndGlyphs">tests</text>
+    <text x="21.5" y="14" fill="#f8f7f2" text-anchor="middle" textLength="29" lengthAdjust="spacingAndGlyphs">tests</text>
+    <text x="84.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="69" lengthAdjust="spacingAndGlyphs">6373 passing</text>
+    <text x="84.5" y="14" fill="#fff" text-anchor="middle" textLength="69" lengthAdjust="spacingAndGlyphs">6373 passing</text>
+  </g>
+</svg>
diff --git a/assets/badge-version.svg b/assets/badge-version.svg
new file mode 100644
index 00000000..1e2e8b3f
--- /dev/null
+++ b/assets/badge-version.svg
@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="104" height="20" viewBox="0 0 104 20" role="img" aria-label="Version 4.16.0">
+  <title>Version 4.16.0</title>
+  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.
+       Source: [project].version in pyproject.toml.
+       Committed rather than hotlinked so the claim cannot be
+       restated by a third party without a commit here; kept true
+       by the generate_repo_badges check, a blocking CI gate. -->
+  <clipPath id="r">
+    <rect width="104" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="55" height="20" fill="#3b3129"/>
+    <rect x="55" width="49" height="20" fill="#2f6f3e"/>
+  </g>
+  <g font-family="Verdana,DejaVu Sans,Geneva,sans-serif" font-size="11">
+    <text x="27.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="41" lengthAdjust="spacingAndGlyphs">version</text>
+    <text x="27.5" y="14" fill="#f8f7f2" text-anchor="middle" textLength="41" lengthAdjust="spacingAndGlyphs">version</text>
+    <text x="79.5" y="15" fill="#000" fill-opacity="0.25" text-anchor="middle" textLength="35" lengthAdjust="spacingAndGlyphs">4.16.0</text>
+    <text x="79.5" y="14" fill="#fff" text-anchor="middle" textLength="35" lengthAdjust="spacingAndGlyphs">4.16.0</text>
+  </g>
+</svg>
diff --git a/docs/ASSURANCE-CASE.md b/docs/ASSURANCE-CASE.md
index 9c1ce20b..646c1f04 100644
--- a/docs/ASSURANCE-CASE.md
+++ b/docs/ASSURANCE-CASE.md
@@ -128,7 +128,7 @@ decoratively:
 
 Standing analysis: CodeQL default setup (Python, JavaScript/TypeScript,
 Actions) on every push and pull request plus weekly, currently 0 open alerts;
-OpenSSF Scorecard via `.github/workflows/scorecard.yml`; and 6348 tests run on
+OpenSSF Scorecard via `.github/workflows/scorecard.yml`; and 6373 tests run on
 four Python versions, two backends and Windows.
 
 ## 6. What this assurance case does NOT claim
diff --git a/scripts/badge_render.py b/scripts/badge_render.py
index c2318a51..6b1ea815 100644
--- a/scripts/badge_render.py
+++ b/scripts/badge_render.py
@@ -25,8 +25,14 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from xml.etree import ElementTree
 from xml.sax.saxutils import escape
 
+
+class BadgeMarkupError(RuntimeError):
+    """The rendered badge is not well-formed XML."""
+
+
 # source: measured 2026-07-28 — the 19-character string "Top 1.2% · Jul 2026"
 # renders correctly at textLength=110 in Verdana/DejaVu Sans, i.e.
 # 5.79 px/char across this badge set's glyphs (digits, letters, '%', '·',
@@ -166,4 +172,16 @@ def render(spec: BadgeSpec) -> str:
         "</svg>",
         "",
     ]
-    return "\n".join(lines)
+    svg = "\n".join(lines)
+    # Parse what we just built, and refuse to return anything that is not
+    # well-formed. Escaping the text runs is not sufficient on its own: a
+    # provenance comment containing "--" (as "--check" or "--collect-only"
+    # readily does) is illegal inside an XML comment and produces a badge
+    # that no strict renderer will draw. Both defects have been introduced
+    # here in practice, so the guard is on the finished artifact rather than
+    # on any one of the ways to break it.
+    try:
+        ElementTree.fromstring(svg)
+    except ElementTree.ParseError as error:
+        raise BadgeMarkupError(f"rendered badge is not well-formed XML: {error}")
+    return svg
diff --git a/scripts/check_doc_claims.py b/scripts/check_doc_claims.py
index 9bce14a5..bf8411b2 100644
--- a/scripts/check_doc_claims.py
+++ b/scripts/check_doc_claims.py
@@ -95,7 +95,20 @@
 # Both the "N tests" and the "N-test suite" phrasings state the count; matching
 # only the first let a stale number sit unread in .bestpractices.json.
 TEST_CLAIM = re.compile(r"(\d+)(?:\s+tests|-test suite)\b")
-VERSION_BADGE = re.compile(r"badge/version-(\d+\.\d+\.\d+)")
+
+# The version and test badges are COMMITTED SVGs under assets/, not hotlinked
+# shields.io URLs, so their figures are read out of the files' own <title>.
+# These patterns replaced URL-shaped ones when the badges were self-hosted:
+# had they been left matching "badge/version-X.Y.Z", they would have found
+# nothing in the new README and both gates would have gone quiet while still
+# reporting success. A gate that cannot find its subject must fail, not pass.
+VERSION_BADGE = re.compile(r"<title>Version (\d+\.\d+\.\d+)</title>")
+TESTS_BADGE = re.compile(r"<title>(\d+) tests passing</title>")
+
+# Self-hosting the badges is only durable if reverting it is loud. Any
+# reintroduced shields.io hotlink in the README is a third-party beacon AND
+# silently detaches whichever claim it carries from the checks below.
+SHIELDS_HOTLINK = re.compile(r"img\.shields\.io")
 
 # source: structural — str.split(marker, 1) yields exactly (before, after)
 # when the marker is present
@@ -246,10 +259,48 @@ def check_versions(expected: str) -> list[str]:
             failures.append(
                 f"{relative_path}: version {actual!r}, pyproject says {expected!r}"
             )
-    for match in VERSION_BADGE.finditer(read("README.md")):
-        if match.group(1) != expected:
+    failures += check_badge(
+        "assets/badge-version.svg", VERSION_BADGE, expected, "version"
+    )
+    return failures
+
+
+def check_badge(
+    relative_path: str, pattern: re.Pattern[str], expected: str, label: str
+) -> list[str]:
+    """One committed badge SVG states one figure, and it must be the right one.
+
+    Fails closed on an unreadable or unmatched badge. The predecessor of this
+    check was `if badge and ...` against a regex over the README, which passed
+    silently the moment the badge stopped matching — the failure mode that
+    makes a gate worse than no gate, because it still reports success.
+    """
+    try:
+        body = read(relative_path)
+    except FileNotFoundError:
+        return [f"{relative_path}: missing — run scripts/generate_repo_badges.py"]
+    match = pattern.search(body)
+    if match is None:
+        return [
+            f"{relative_path}: no {label} figure in its <title>; the badge and"
+            " this gate have diverged"
+        ]
+    if match.group(1) != expected:
+        return [
+            f"{relative_path}: {label} badge says {match.group(1)},"
+            f" canonical is {expected}"
+        ]
+    return []
+
+
+def check_no_hotlinked_badges() -> list[str]:
+    """The README's repo-derived badges stay self-hosted."""
+    failures = []
+    for number, line in enumerate(read("README.md").splitlines(), start=1):
+        if SHIELDS_HOTLINK.search(line):
             failures.append(
-                f"README.md: version badge {match.group(1)}, pyproject says {expected}"
+                f"README.md:{number}: hotlinked shields.io badge — these are"
+                " committed under assets/ (scripts/generate_repo_badges.py)"
             )
     return failures
 
@@ -261,14 +312,12 @@ def collect_failures(test_count: int | None) -> list[str]:
     failures += check_counts(REFERENCE_CLAIM, canonical_reference_count(), "references")
     failures += check_counts(MECHANISM_CLAIM, canonical_mechanism_count(), "mechanisms")
     failures += check_versions(canonical_version())
+    failures += check_no_hotlinked_badges()
     if test_count is not None:
         failures += check_counts(TEST_CLAIM, test_count, "tests")
-        badge = re.search(r"badge/tests-(\d+)_passing", read("README.md"))
-        if badge and int(badge.group(1)) != test_count:
-            failures.append(
-                f"README.md: test badge says {badge.group(1)}, "
-                f"the suite collects {test_count}"
-            )
+        failures += check_badge(
+            "assets/badge-tests.svg", TESTS_BADGE, str(test_count), "tests"
+        )
     return failures
 
 
diff --git a/scripts/generate_repo_badges.py b/scripts/generate_repo_badges.py
new file mode 100644
index 00000000..c8155007
--- /dev/null
+++ b/scripts/generate_repo_badges.py
@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Generate the README's repo-derived badges as committed SVG files.
+
+Why these badges are committed files and not hotlinked images
+-------------------------------------------------------------
+A remote badge URL (img.shields.io/...) is a third-party request fired on
+every README view, and it lets its host restate our claim at any time with
+no commit in this repository. A committed file cannot drift and cannot be
+restated by anyone else.
+
+Why only THESE badges
+---------------------
+Every figure below is determined BY THIS REPOSITORY: the licence, the
+Python floor, the collected test count, the bibliography size, the package
+version. So a committed copy can always be made true again by regenerating
+it from the working tree, with no network access at all — which is why this
+runs as a blocking CI check on every push and PR (`--check`) rather than on
+a cron. Drift is caught where it is introduced.
+
+Two README badges are deliberately NOT converted, and must not be:
+
+  * The CI status badge reflects the LIVE result of the last run on main.
+    A committed copy would assert "passing" while main was broken — a
+    static build-status badge is a false claim by construction, not a stale
+    one. It is also GitHub-hosted, so it is not a third-party beacon: the
+    reader has already loaded the page from that same origin.
+  * The OpenSSF Best Practices badge reflects an external body's live
+    assessment, which can be downgraded without any commit here. Freezing
+    it could over-claim a standing we no longer hold. .bestpractices.json
+    additionally justifies displaying THEIR badge image, so replacing it
+    with our own rendering would undercut that criterion.
+
+The MCP Toplist badge sits between the two and IS committed, because it
+carries an explicit "as of <month>" stamp: a stale copy remains a true
+statement about a point in time. See refresh_mcp_toplist_badge.py.
+
+Usage:
+    python3 scripts/generate_repo_badges.py           # rewrite if changed
+    python3 scripts/generate_repo_badges.py --check   # exit 1 if stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+# Sibling modules, path-imported for the same reason the launcher family
+# does it: resolves identically whether this runs as a script or is loaded
+# via importlib.util.spec_from_file_location from a test.
+_SCRIPTS_DIR = str(Path(__file__).resolve().parent)
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+import badge_render  # noqa: E402
+import check_doc_claims  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ASSETS_DIR = Path("assets")
+
+# The palette is assets/banner.svg's, shared with the MCP Toplist badge so
+# the README's badge row reads as one set rather than as a pile of styles.
+_LABEL_FILL = "#3b3129"
+_LABEL_TEXT = "#f8f7f2"
+_MESSAGE_TEXT = "#fff"
+
+# Message-panel fills. Distinct hues carry the same meaning the shields.io
+# originals did (blue = neutral fact, green = healthy, orange = corpus), so
+# the row's reading does not change with its hosting.
+_NEUTRAL = "#31708f"
+_HEALTHY = "#2f6f3e"
+_CORPUS = "#a53e00"
+
+
+@dataclass(frozen=True)
+class RepoBadge:
+    """One generated badge: its file, its two panels, and its alt text."""
+
+    filename: str
+    label: str
+    message: str
+    fill: str
+    alt: str
+    derivation: str
+
+    def path(self) -> Path:
+        return ASSETS_DIR / self.filename
+
+    def render(self) -> str:
+        provenance = (
+            "  <!-- GENERATED by scripts/generate_repo_badges.py — do not hand-edit.",
+            f"       {self.derivation}",
+            "       Committed rather than hotlinked so the claim cannot be",
+            "       restated by a third party without a commit here; kept true",
+            "       by the generate_repo_badges check, a blocking CI gate. -->",
+        )
+        spec = badge_render.BadgeSpec(
+            label=badge_render.label_panel(self.label, _LABEL_FILL, _LABEL_TEXT),
+            message=self.message,
+            message_fill=self.fill,
+            message_text_fill=_MESSAGE_TEXT,
+            alt=self.alt,
+            provenance=provenance,
+        )
+        return badge_render.render(spec)
+
+
+def canonical_licence() -> str:
+    """The licence name, from the packaging metadata that governs it."""
+    text = check_doc_claims.read("pyproject.toml")
+    for pattern in ('license = "', 'license = {text = "'):
+        head, sep, tail = text.partition(pattern)
+        if sep:
+            return tail.split('"', 1)[0]
+    raise check_doc_claims.ClaimError("pyproject.toml: [project].license not found")
+
+
+def canonical_python_floor() -> str:
+    """The minimum supported Python, from requires-python."""
+    text = check_doc_claims.read("pyproject.toml")
+    head, sep, tail = text.partition('requires-python = ">=')
+    if not sep:
+        raise check_doc_claims.ClaimError(
+            'pyproject.toml: requires-python ">=X.Y" not found'
+        )
+    return tail.split('"', 1)[0]
+
+
+def build_badges(test_count: int | None) -> list[RepoBadge]:
+    """Every repo-derived badge, resolved against the working tree.
+
+    The canonical readers are check_doc_claims's own, not reimplementations:
+    a badge that disagreed with the gate would be the exact drift this file
+    exists to prevent.
+    """
+    version = check_doc_claims.canonical_version()
+    references = check_doc_claims.canonical_reference_count()
+    licence = canonical_licence()
+    floor = canonical_python_floor()
+    badges = [
+        RepoBadge(
+            filename="badge-license.svg",
+            label="license",
+            message=licence,
+            fill=_NEUTRAL,
+            alt=f"License: {licence}",
+            derivation="Source: [project].license in pyproject.toml.",
+        ),
+        RepoBadge(
+            filename="badge-python.svg",
+            label="python",
+            message=f"{floor}+",
+            fill=_NEUTRAL,
+            alt=f"Python {floor}+",
+            derivation="Source: [project].requires-python in pyproject.toml.",
+        ),
+        RepoBadge(
+            filename="badge-references.svg",
+            label="references",
+            message=f"{references} papers",
+            fill=_CORPUS,
+            alt=f"{references} referenced papers",
+            derivation=(
+                "Source: entries under '## References' in docs/papers/bibliography.md."
+            ),
+        ),
+        RepoBadge(
+            filename="badge-version.svg",
+            label="version",
+            message=version,
+            fill=_HEALTHY,
+            alt=f"Version {version}",
+            derivation="Source: [project].version in pyproject.toml.",
+        ),
+    ]
+    # The test count is the one figure that cannot be read off a file: it is
+    # whatever the suite collects right now. Omitted rather than guessed when
+    # the caller has not measured it, so a stale badge is never written from
+    # an assumption.
+    if test_count is not None:
+        badges.append(
+            RepoBadge(
+                filename="badge-tests.svg",
+                label="tests",
+                message=f"{test_count} passing",
+                fill=_HEALTHY,
+                alt=f"{test_count} tests passing",
+                derivation="Source: the count pytest collects on this tree.",
+            )
+        )
+    return badges
+
+
+def write(badge: RepoBadge) -> bool:
+    """Write the badge; True when the file changed."""
+    target = REPO_ROOT / badge.path()
+    rendered = badge.render()
+    if target.exists() and target.read_text(encoding="utf-8") == rendered:
+        return False
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(rendered, encoding="utf-8")
+    return True
+
+
+def stale(badge: RepoBadge) -> str | None:
+    """The reason this badge is out of date, or None when it is current."""
+    target = REPO_ROOT / badge.path()
+    if not target.exists():
+        return f"{badge.path()}: missing — run scripts/generate_repo_badges.py"
+    if target.read_text(encoding="utf-8") != badge.render():
+        return (
+            f"{badge.path()}: stale ({badge.label} is now {badge.message!r})"
+            " — run scripts/generate_repo_badges.py"
+        )
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="do not write; exit 1 if any badge is missing or stale",
+    )
+    parser.add_argument(
+        "--test-count",
+        type=int,
+        default=None,
+        help="live test count (from `pytest --collect-only -q`); badge skipped"
+        " when absent",
+    )
+    args = parser.parse_args(argv)
+
+    # A gate that cannot READ its inputs is a different outcome from a gate
+    # that read them and found drift: exit 2 keeps "could not run" from being
+    # mistaken for "found a stale badge" by whatever reads this exit code.
+    try:
+        badges = build_badges(args.test_count)
+    except (check_doc_claims.ClaimError, FileNotFoundError) as error:
+        print(f"badge generation could not run: {error}", file=sys.stderr)
+        return 2
+
+    if args.check:
+        failures = [reason for badge in badges if (reason := stale(badge))]
+        if failures:
+            print("Committed badges disagree with the repository:", file=sys.stderr)
+            for failure in failures:
+                print(f"  {failure}", file=sys.stderr)
+            return 1
+        print(f"badges OK ({len(badges)} checked)")
+        return 0
+
+    changed = [badge.path() for badge in badges if write(badge)]
+    for path in changed:
+        print(f"wrote {path}")
+    print(f"{len(changed)} of {len(badges)} badge(s) changed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests_py/scripts/test_check_doc_claims.py b/tests_py/scripts/test_check_doc_claims.py
index 2043d342..d1dbe9b5 100644
--- a/tests_py/scripts/test_check_doc_claims.py
+++ b/tests_py/scripts/test_check_doc_claims.py
@@ -44,7 +44,14 @@ def __init__(self, **files: str):
         self.files = files
 
     def read(self, relative_path: str) -> str:
-        return self.files[relative_path]
+        # FileNotFoundError, not KeyError: the real read() is a Path.read_text,
+        # and the gate's missing-badge arm is written against what the real
+        # one raises. A double that raised KeyError would let that arm pass
+        # its tests while failing on the actual tree.
+        try:
+            return self.files[relative_path]
+        except KeyError:
+            raise FileNotFoundError(relative_path) from None
 
 
 class CanonicalSourceTests(unittest.TestCase):
@@ -272,15 +279,15 @@ def setUp(self):
     def tearDown(self):
         gate.read = self._real_read
 
-    def _install(self, manifest: str, badge: str):
-        gate.read = _FakeRepo(
-            **{
-                "manifest.json": '{"version": "%s"}' % manifest,
-                "server.json": '{"version": "4.16.0"}',
-                "package.json": '{"version": "4.16.0"}',
-                "README.md": f"badge/version-{badge}-brightgreen.svg",
-            }
-        ).read
+    def _install(self, manifest: str, badge: str | None):
+        files = {
+            "manifest.json": '{"version": "%s"}' % manifest,
+            "server.json": '{"version": "4.16.0"}',
+            "package.json": '{"version": "4.16.0"}',
+        }
+        if badge is not None:
+            files["assets/badge-version.svg"] = f"<title>Version {badge}</title>"
+        gate.read = _FakeRepo(**files).read
 
     def test_manifest_and_badge_must_match_pyproject(self):
         self._install(manifest="4.16.0", badge="4.16.0")
@@ -292,11 +299,37 @@ def test_stale_manifest_version_is_reported(self):
         self.assertEqual(len(failures), 1)
         self.assertIn("manifest.json", failures[0])
 
-    def test_stale_readme_badge_is_reported(self):
+    def test_stale_committed_badge_is_reported(self):
         self._install(manifest="4.16.0", badge="4.15.0")
         failures = gate.check_versions("4.16.0")
         self.assertEqual(len(failures), 1)
-        self.assertIn("version badge 4.15.0", failures[0])
+        self.assertIn("version badge says 4.15.0", failures[0])
+
+    def test_a_missing_badge_file_fails_closed(self):
+        """Self-hosting moved the figure into a file that can be deleted.
+
+        The URL-shaped predecessor of this check silently passed when its
+        pattern stopped matching, so a gate that cannot find its subject must
+        report rather than shrug.
+        """
+        self._install(manifest="4.16.0", badge=None)
+        failures = gate.check_versions("4.16.0")
+        self.assertEqual(len(failures), 1)
+        self.assertIn("missing", failures[0])
+
+    def test_a_badge_without_a_version_title_fails_closed(self):
+        self._install(manifest="4.16.0", badge="4.16.0")
+        gate.read = _FakeRepo(
+            **{
+                "manifest.json": '{"version": "4.16.0"}',
+                "server.json": '{"version": "4.16.0"}',
+                "package.json": '{"version": "4.16.0"}',
+                "assets/badge-version.svg": "<svg><title>something else</title></svg>",
+            }
+        ).read
+        failures = gate.check_versions("4.16.0")
+        self.assertEqual(len(failures), 1)
+        self.assertIn("diverged", failures[0])
 
 
 class CollectFailuresTests(unittest.TestCase):
@@ -321,7 +354,7 @@ def tearDown(self):
         gate.read = self._real_read
         gate.SCANNED_FILES = self._real_files
 
-    def _install(self, doc: str, badge: str = "6260"):
+    def _install(self, doc: str, badge: str = "6260", readme: str | None = None):
         gate.read = _FakeRepo(
             **{
                 "DOC.md": doc,
@@ -332,10 +365,10 @@ def _install(self, doc: str, badge: str = "6260"):
                 "manifest.json": '{"version": "4.16.0"}',
                 "server.json": '{"version": "4.16.0"}',
                 "package.json": '{"version": "4.16.0"}',
-                "README.md": (
-                    "badge/version-4.16.0-brightgreen.svg\n"
-                    f"badge/tests-{badge}_passing-brightgreen.svg\n"
-                ),
+                "README.md": readme
+                or '<img src="assets/badge-tests.svg" alt="tests">\n',
+                "assets/badge-version.svg": "<title>Version 4.16.0</title>",
+                "assets/badge-tests.svg": f"<title>{badge} tests passing</title>",
             }
         ).read
         gate.SCANNED_FILES = ("DOC.md",)
@@ -363,7 +396,22 @@ def test_the_test_badge_is_checked_against_the_live_count(self):
         self._install(self.CONSISTENT, badge="6259")
         failures = gate.collect_failures(test_count=6260)
         self.assertEqual(len(failures), 1, failures)
-        self.assertIn("test badge says 6259", failures[0])
+        self.assertIn("tests badge says 6259", failures[0])
+
+    def test_a_reintroduced_shields_hotlink_is_reported(self):
+        """Self-hosting is only durable if reverting it is loud.
+
+        A hotlinked badge is both a third-party beacon and a silent detachment
+        of the claim from the checks above — the URL carries the figure, so the
+        committed file stops being what the README shows.
+        """
+        self._install(
+            self.CONSISTENT,
+            readme='<img src="https://img.shields.io/badge/tests-1_passing.svg">\n',
+        )
+        failures = gate.collect_failures(test_count=6260)
+        self.assertEqual(len(failures), 1, failures)
+        self.assertIn("hotlinked shields.io badge", failures[0])
 
     def test_without_a_live_count_the_test_family_is_not_checked(self):
         """The documented skip — and the reason it needs its own guard.
diff --git a/tests_py/scripts/test_generate_repo_badges.py b/tests_py/scripts/test_generate_repo_badges.py
new file mode 100644
index 00000000..ed6df457
--- /dev/null
+++ b/tests_py/scripts/test_generate_repo_badges.py
@@ -0,0 +1,264 @@
+"""Tests for scripts/generate_repo_badges.py — the self-hosted badge gate.
+
+Written unittest-style to match the sibling script gates; Cortex's pytest
+collects unittest classes natively.
+
+The property under test throughout is that a committed badge cannot quietly
+disagree with the repository. The badges exist as files precisely so no third
+party can restate the claim; that only holds if a file drifting from its
+source is a RED CI run rather than a silent inaccuracy, so every path below
+asserts the drift is reported.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+from xml.etree import ElementTree
+
+_SCRIPTS = Path(__file__).resolve().parents[2] / "scripts"
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+_spec = importlib.util.spec_from_file_location(
+    "generate_repo_badges", _SCRIPTS / "generate_repo_badges.py"
+)
+gen = importlib.util.module_from_spec(_spec)
+# Register before exec: @dataclass resolves its owning module through
+# sys.modules, and RepoBadge is defined at import time.
+sys.modules["generate_repo_badges"] = gen
+_spec.loader.exec_module(gen)
+
+import badge_render  # noqa: E402
+
+PYPROJECT = (
+    '[project]\nversion = "4.16.0"\nlicense = "MIT"\nrequires-python = ">=3.10"\n'
+)
+
+BIBLIOGRAPHY = "## References\n\n- Author, A. (2020). One.\n- Author, B. (2021). Two.\n"
+
+
+class _FakeRepo:
+    """Minimal stand-in for the repository files the generator reads."""
+
+    def __init__(self, **files: str):
+        self.files = files
+
+    def read(self, relative_path: str) -> str:
+        try:
+            return self.files[relative_path]
+        except KeyError:
+            raise FileNotFoundError(relative_path) from None
+
+
+class _CanonicalSourceTestCase(unittest.TestCase):
+    """Shared fixture: the generator reads canonical values through the gate."""
+
+    def setUp(self):
+        self._real_read = gen.check_doc_claims.read
+        gen.check_doc_claims.read = _FakeRepo(
+            **{
+                "pyproject.toml": PYPROJECT,
+                "docs/papers/bibliography.md": BIBLIOGRAPHY,
+            }
+        ).read
+
+    def tearDown(self):
+        gen.check_doc_claims.read = self._real_read
+
+
+class CanonicalReaderTests(_CanonicalSourceTestCase):
+    def test_licence_comes_from_the_packaging_metadata(self):
+        self.assertEqual(gen.canonical_licence(), "MIT")
+
+    def test_python_floor_comes_from_requires_python(self):
+        self.assertEqual(gen.canonical_python_floor(), "3.10")
+
+    def test_a_missing_licence_is_an_error_not_a_guess(self):
+        gen.check_doc_claims.read = _FakeRepo(
+            **{"pyproject.toml": '[project]\nversion = "4.16.0"\n'}
+        ).read
+        with self.assertRaises(gen.check_doc_claims.ClaimError):
+            gen.canonical_licence()
+
+    def test_a_missing_python_floor_is_an_error_not_a_guess(self):
+        gen.check_doc_claims.read = _FakeRepo(
+            **{"pyproject.toml": '[project]\nversion = "4.16.0"\n'}
+        ).read
+        with self.assertRaises(gen.check_doc_claims.ClaimError):
+            gen.canonical_python_floor()
+
+
+class BuildTests(_CanonicalSourceTestCase):
+    def test_every_badge_states_its_canonical_value(self):
+        by_name = {b.filename: b for b in gen.build_badges(test_count=42)}
+        self.assertEqual(by_name["badge-license.svg"].message, "MIT")
+        self.assertEqual(by_name["badge-python.svg"].message, "3.10+")
+        self.assertEqual(by_name["badge-version.svg"].message, "4.16.0")
+        self.assertEqual(by_name["badge-references.svg"].message, "2 papers")
+        self.assertEqual(by_name["badge-tests.svg"].message, "42 passing")
+
+    def test_without_a_live_count_no_test_badge_is_built(self):
+        """A test count cannot be read off a file, so it is never assumed.
+
+        Writing one from an assumption is how a committed badge becomes a
+        confident false claim — the failure mode self-hosting exists to avoid.
+        """
+        names = {b.filename for b in gen.build_badges(test_count=None)}
+        self.assertNotIn("badge-tests.svg", names)
+        self.assertIn("badge-version.svg", names)
+
+    def test_every_badge_carries_its_derivation_in_the_file(self):
+        for badge in gen.build_badges(test_count=42):
+            with self.subTest(badge=badge.filename):
+                self.assertIn("GENERATED by", badge.render())
+                self.assertIn("Source:", badge.render())
+
+
+class RenderTests(_CanonicalSourceTestCase):
+    def test_every_badge_is_well_formed_xml(self):
+        for badge in gen.build_badges(test_count=42):
+            with self.subTest(badge=badge.filename):
+                ElementTree.fromstring(badge.render())
+
+    def test_the_title_states_the_claim_for_screen_readers(self):
+        by_name = {b.filename: b for b in gen.build_badges(test_count=42)}
+        root = ElementTree.fromstring(by_name["badge-tests.svg"].render())
+        title = root.find("{http://www.w3.org/2000/svg}title")
+        self.assertEqual(title.text, "42 tests passing")
+        self.assertEqual(root.get("aria-label"), "42 tests passing")
+
+    def test_markup_bearing_text_is_escaped(self):
+        """The one bug this badge family has shipped was an unescaped '<'.
+
+        It reached the markup from a rendered value, not from a literal, so the
+        guard belongs on a value that contains markup rather than on any
+        particular caller.
+        """
+        spec = badge_render.BadgeSpec(
+            label=badge_render.label_panel("a<b", "#000", "#fff"),
+            message='x>y & "z"',
+            message_fill="#111",
+            message_text_fill="#fff",
+            alt='alt<>&"',
+            provenance=(),
+        )
+        rendered = badge_render.render(spec)
+        ElementTree.fromstring(rendered)
+        self.assertNotIn("<b", rendered.split("<title>")[1].split("</title>")[0])
+
+    def test_a_double_hyphen_in_provenance_is_refused(self):
+        """Regression: "--" is illegal inside an XML comment.
+
+        The first cut of this generator described its own gate as
+        ``--check`` and its source as ``pytest --collect-only``. Both landed
+        inside the provenance comment and made all five badges unparseable —
+        escaping the TEXT runs does not help, because the defect is in the
+        comment. The renderer now validates the finished artifact, so any
+        future wording that breaks it fails loudly here instead of shipping.
+        """
+        spec = badge_render.BadgeSpec(
+            label=badge_render.label_panel("x", "#000", "#fff"),
+            message="y",
+            message_fill="#111",
+            message_text_fill="#fff",
+            alt="x y",
+            provenance=("  <!-- run with --check -->",),
+        )
+        with self.assertRaises(badge_render.BadgeMarkupError):
+            badge_render.render(spec)
+
+    def test_every_committed_badge_on_disk_is_well_formed(self):
+        """The guard above protects generation; this protects what shipped."""
+        for path in sorted((Path(gen.REPO_ROOT) / "assets").glob("badge-*.svg")):
+            with self.subTest(badge=path.name):
+                ElementTree.parse(path)
+
+
+class CheckModeTests(_CanonicalSourceTestCase):
+    """--check is the blocking CI gate; it must never write, and must fail."""
+
+    def setUp(self):
+        super().setUp()
+        self._tmp = TemporaryDirectory()
+        self._root = Path(self._tmp.name)
+        self._patch = mock.patch.object(gen, "REPO_ROOT", self._root)
+        self._patch.start()
+
+    def tearDown(self):
+        self._patch.stop()
+        self._tmp.cleanup()
+        super().tearDown()
+
+    def _written(self) -> set[str]:
+        return {p.name for p in (self._root / "assets").glob("*.svg")}
+
+    def test_a_missing_badge_is_reported_and_nothing_is_written(self):
+        self.assertEqual(gen.main(["--check", "--test-count", "42"]), 1)
+        self.assertEqual(self._written(), set())
+
+    def test_generation_then_check_is_clean(self):
+        self.assertEqual(gen.main(["--test-count", "42"]), 0)
+        self.assertEqual(gen.main(["--check", "--test-count", "42"]), 0)
+
+    def test_a_hand_edited_badge_is_reported_as_stale(self):
+        gen.main(["--test-count", "42"])
+        target = self._root / "assets" / "badge-version.svg"
+        target.write_text(target.read_text().replace("4.16.0", "9.9.9"))
+        self.assertEqual(gen.main(["--check", "--test-count", "42"]), 1)
+
+    def test_check_does_not_repair_the_file_it_rejects(self):
+        """--check reports; only a real run writes.
+
+        A check that silently fixed the tree would turn a CI failure into a
+        no-op on a developer's machine and let the drift ship.
+        """
+        gen.main(["--test-count", "42"])
+        target = self._root / "assets" / "badge-version.svg"
+        tampered = target.read_text().replace("4.16.0", "9.9.9")
+        target.write_text(tampered)
+        gen.main(["--check", "--test-count", "42"])
+        self.assertEqual(target.read_text(), tampered)
+
+    def test_a_drifted_count_is_rewritten_on_a_real_run(self):
+        gen.main(["--test-count", "42"])
+        self.assertEqual(gen.main(["--test-count", "43"]), 0)
+        body = (self._root / "assets" / "badge-tests.svg").read_text()
+        self.assertIn("43 tests passing", body)
+
+    def test_an_unreadable_canonical_source_exits_two_not_one(self):
+        """A gate that cannot run is distinct from a gate that found drift."""
+        gen.check_doc_claims.read = _FakeRepo().read
+        self.assertEqual(gen.main(["--check", "--test-count", "42"]), 2)
+
+
+class RepositoryTests(unittest.TestCase):
+    """The committed badges must match the tree they ship with."""
+
+    def test_committed_badges_agree_with_the_repository(self):
+        self.assertEqual(gen.main(["--check"]), 0)
+
+    def test_the_readme_shows_the_committed_files(self):
+        readme = (Path(gen.REPO_ROOT) / "README.md").read_text()
+        for badge in gen.build_badges(test_count=None):
+            with self.subTest(badge=badge.filename):
+                self.assertIn(f"assets/{badge.filename}", readme)
+
+    def test_the_readme_hotlinks_no_shields_badge(self):
+        readme = (Path(gen.REPO_ROOT) / "README.md").read_text()
+        self.assertNotIn("img.shields.io", readme)
+
+    def test_the_live_status_badges_stay_live(self):
+        """CI status and OpenSSF are NOT converted, and that is load-bearing.
+
+        Both report an external system's current verdict. A committed copy
+        would assert a standing we might no longer hold — stale is tolerable
+        for a dated claim, false is not for a live one.
+        """
+        readme = (Path(gen.REPO_ROOT) / "README.md").read_text()
+        self.assertIn("actions/workflows/ci.yml/badge.svg", readme)
+        self.assertIn("bestpractices.dev/projects/13836/badge", readme)

From aa0bc154ded3a9bd358b3671f0531769ead89d2f Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Wed, 29 Jul 2026 08:49:18 +0200
Subject: [PATCH 3/4] fix(ci): send a valid MCP notification in the docker
 smoke test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Docker Smoke gate was intermittent, not broken. Same commit 18d4505
failed at 21:52Z and passed at 22:12Z with no code change between them.

Root cause, in the frame this script sends:

    {"jsonrpc":"2.0","id":2,"method":"notifications/initialized"}

JSON-RPC 2.0 §4.1 — "A Notification is a Request object without an 'id'
member". The id is the ONLY thing distinguishing the two, so with it
present the server routed the frame to `ClientRequest`. Verified against
mcp.types: `notifications/initialized` appears only in ClientNotification
(5 members); ClientRequest's 17 members are ping / initialize /
completion/complete / logging/setLevel / prompts:2 / resources:5 /
tools:2 / tasks:4 — none of them a notification. Hence the observed
"28 validation errors for ClientRequest" and the -32602 answer on id=2.

Why that made it FLAKY rather than red: the rejected frame put the server
on an error path mid-handshake, and whether it still answered id=3 before
stdin EOF shut it down was a race. The script only ever looked for id=3,
so it silently tolerated the error whenever the race went its way — which
is precisely why a malformed handshake survived in a BLOCKING gate.

Two changes, cause and detection:

1. Drop the id — the notification is now a notification. A correct
   handshake has no error path for the race to hinge on.
2. Any JSON-RPC error frame now fails the run, whatever id it carries.
   Previously a broken handshake surfaced as "no valid tools/list
   response (id=3)", pointing the investigation at the wrong end of the
   exchange.

Also fixed while here (§14): the two fixed /tmp diagnostic paths are now
per-run mktemp files with a cleanup trap — concurrent runs on one runner
could read each other's output, and a stale file could be mistaken for
this run's — and shellcheck SC2188 on the truncation redirect.

Verified without Docker (the image build needs ~200MB and this disk is
full) by driving the script against a fake `docker` on PATH replaying
recorded container output, all four paths asserted:

    good             exit=0  PASS — returned 52 tools (>= 49)
    handshake_error  exit=1  FAIL — container returned JSON-RPC error frames
    low              exit=1  FAIL — returned 1 tools, expected >= 49
    empty            exit=1  FAIL — empty stdout from container

`handshake_error` is the regression test: that fixture is the exact
exchange observed at 21:52Z, and it now fails deterministically instead
of depending on a race. shellcheck clean; bash -n clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Yu6EnWspTfqHoGkExyS6u
---
 scripts/docker_smoke.sh | 68 +++++++++++++++++++++++++++++++++--------
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/scripts/docker_smoke.sh b/scripts/docker_smoke.sh
index c18ebded..c6a7b9ef 100755
--- a/scripts/docker_smoke.sh
+++ b/scripts/docker_smoke.sh
@@ -55,10 +55,32 @@ fi
 # Bare contract: no -e flags, no --link, no compose network. The container
 # must self-select the SQLite fallback (CORTEX_RUNTIME=cowork, set in the
 # Dockerfile itself) with zero external services.
-REQUESTS=$'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"docker-smoke","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}\n'
+# `notifications/initialized` carries NO "id". JSON-RPC 2.0 §4.1: "A
+# Notification is a Request object without an 'id' member" — the presence of
+# an id is the ONLY thing that distinguishes the two, so an id here made the
+# server route the message to `ClientRequest`, whose method union does not
+# contain any `notifications/*` member (verified against mcp.types:
+# ClientRequest = ping|initialize|completion/complete|logging/setLevel|
+# prompts/*|resources/*|tools/*|tasks/*; `notifications/initialized` lives
+# only in ClientNotification). The server answered id=2 with -32602 and
+# logged "28 validation errors for ClientRequest", one per union member.
+#
+# That is what made this gate FLAKY rather than simply broken: the malformed
+# frame put the server on an error path mid-handshake, and whether it still
+# answered id=3 before stdin EOF shut it down was a race. Same commit
+# 18d4505 failed at 21:52Z and passed at 22:12Z. A correct handshake has no
+# such error path.
+REQUESTS=$'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"docker-smoke","version":"0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}\n'
 
 echo "docker_smoke: running ${IMAGE} with zero env vars, sending initialize + tools/list over stdio ..." >&2
 
+# Unique per run: two smoke runs on one runner must not read each other's
+# diagnostics, and a stale file from a previous run must not be mistaken for
+# this run's output.
+STDERR_LOG="$(mktemp -t docker_smoke_stderr)"
+PROTOCOL_ERRORS="$(mktemp -t docker_smoke_protocol_errors)"
+trap 'rm -f "$STDERR_LOG" "$PROTOCOL_ERRORS"' EXIT
+
 # Portable timeout: GNU coreutils `timeout` ships on ubuntu-latest (GitHub
 # Actions runner) but not on macOS by default (`gtimeout` from `brew install
 # coreutils` is the local-dev equivalent). Fall back to no timeout wrapper
@@ -72,11 +94,11 @@ elif command -v gtimeout >/dev/null 2>&1; then
   TIMEOUT_CMD="gtimeout 60"
 fi
 
-RAW_OUTPUT="$(printf '%s' "$REQUESTS" | $TIMEOUT_CMD docker run --rm -i "$IMAGE" 2>/tmp/docker_smoke_stderr.log || true)"
+RAW_OUTPUT="$(printf '%s' "$REQUESTS" | $TIMEOUT_CMD docker run --rm -i "$IMAGE" 2>"$STDERR_LOG" || true)"
 
 if [[ -z "$RAW_OUTPUT" ]]; then
   echo "docker_smoke: FAIL — empty stdout from container. stderr:" >&2
-  cat /tmp/docker_smoke_stderr.log >&2 || true
+  cat "$STDERR_LOG" >&2 || true
   exit 1
 fi
 
@@ -84,7 +106,12 @@ TOOL_COUNT="$(printf '%s' "$RAW_OUTPUT" | python3 -c '
 import json
 import sys
 
+# Any JSON-RPC error frame is reported, not just a missing id=3: a broken
+# handshake shows up as an error on id=1/id=2, and blaming "no tools/list
+# response" for it sent the last investigation to the wrong end of the
+# exchange. Errors go to a side file so the caller can quote them.
 count = None
+errors = []
 for line in sys.stdin:
     line = line.strip()
     if not line:
@@ -93,23 +120,40 @@ for line in sys.stdin:
         msg = json.loads(line)
     except json.JSONDecodeError:
         continue
+    if "error" in msg:
+        errors.append(
+            "  id={} code={} message={}".format(
+                msg.get("id"),
+                msg["error"].get("code"),
+                msg["error"].get("message"),
+            )
+        )
     if msg.get("id") == 3 and "result" in msg:
-        tools = msg["result"].get("tools", [])
-        count = len(tools)
-        break
+        count = len(msg["result"].get("tools", []))
+
+with open(sys.argv[1], "w") as fh:
+    fh.write("\n".join(errors))
 
-if count is None:
-    print("NONE")
-else:
-    print(count)
-')"
+print("NONE" if count is None else count)
+' "$PROTOCOL_ERRORS")"
+
+# A protocol error is a failure even when tools/list happens to answer: it
+# means the container rejected a frame this script sent, and the last time
+# that was tolerated it made the gate intermittent rather than red.
+if [[ -s "$PROTOCOL_ERRORS" ]]; then
+  echo "docker_smoke: FAIL — the container returned JSON-RPC error frames:" >&2
+  cat "$PROTOCOL_ERRORS" >&2
+  echo "--- container stderr ---" >&2
+  cat "$STDERR_LOG" >&2 || true
+  exit 1
+fi
 
 if [[ "$TOOL_COUNT" == "NONE" || -z "$TOOL_COUNT" ]]; then
   echo "docker_smoke: FAIL — no valid tools/list response (id=3) found in container stdout." >&2
   echo "--- raw stdout ---" >&2
   printf '%s\n' "$RAW_OUTPUT" >&2
   echo "--- stderr ---" >&2
-  cat /tmp/docker_smoke_stderr.log >&2 || true
+  cat "$STDERR_LOG" >&2 || true
   exit 1
 fi
 

From 191732633403422aece1ebfaf047dc78173406a5 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Wed, 29 Jul 2026 09:08:49 +0200
Subject: [PATCH 4/4] fix(ci): use an explicit mktemp template so the smoke
 test runs on GNU
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-inflicted, from the previous commit's §14 cleanup. `mktemp -t
docker_smoke_stderr` is a BSD/macOS form where -t's argument is a PREFIX
and mktemp appends its own suffix. GNU coreutils mktemp — the
ubuntu-latest runner — requires the template's last component to contain
at least three consecutive X's and aborts:

    mktemp: too few X's in template 'docker_smoke_stderr'

So the smoke test exited 1 before starting the container at all. It
passed my local fixture run precisely because that run was on macOS: a
platform-divergent form cannot be validated on one platform, which is the
same class of blind spot as validating a gate against only one backend.

An explicit `"${TMPDIR:-/tmp}/<name>.XXXXXX"` template is accepted by
both implementations. Verified on BSD/macOS locally; GNU is verified by
this CI run itself, which is the GNU environment — noted rather than
claimed, since I have no GNU mktemp on this machine and no disk left to
run a container that would provide one.

Four-path fixture suite re-run after the change, unchanged:

    good             exit=0  PASS — returned 52 tools (>= 49)
    handshake_error  exit=1  FAIL — container returned JSON-RPC error frames
    low              exit=1  FAIL — returned 1 tools, expected >= 49
    empty            exit=1  FAIL — empty stdout from container

shellcheck clean; bash -n clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Yu6EnWspTfqHoGkExyS6u
---
 scripts/docker_smoke.sh | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/scripts/docker_smoke.sh b/scripts/docker_smoke.sh
index c6a7b9ef..6fdd7c8d 100755
--- a/scripts/docker_smoke.sh
+++ b/scripts/docker_smoke.sh
@@ -77,8 +77,14 @@ echo "docker_smoke: running ${IMAGE} with zero env vars, sending initialize + to
 # Unique per run: two smoke runs on one runner must not read each other's
 # diagnostics, and a stale file from a previous run must not be mistaken for
 # this run's output.
-STDERR_LOG="$(mktemp -t docker_smoke_stderr)"
-PROTOCOL_ERRORS="$(mktemp -t docker_smoke_protocol_errors)"
+#
+# Explicit XXXXXX template, not `mktemp -t <prefix>`: GNU coreutils mktemp
+# (the ubuntu-latest runner) requires the template to end in at least three
+# X's and errors "too few X's in template" otherwise, while BSD/macOS mktemp
+# treats -t's argument as a prefix and appends its own suffix. The bare -t
+# form therefore passes locally on macOS and fails only on CI.
+STDERR_LOG="$(mktemp "${TMPDIR:-/tmp}/docker_smoke_stderr.XXXXXX")"
+PROTOCOL_ERRORS="$(mktemp "${TMPDIR:-/tmp}/docker_smoke_protocol_errors.XXXXXX")"
 trap 'rm -f "$STDERR_LOG" "$PROTOCOL_ERRORS"' EXIT
 
 # Portable timeout: GNU coreutils `timeout` ships on ubuntu-latest (GitHub