feat(site): version supernav.js everywhere and flag docs sites that lag

[imran-siddique]

agentrust-io.com serves supernav.js and design-system.css with Cache-Control: max-age=14400. Every hub page loaded /supernav.js with no query string, and so did the seven MkDocs sites. On 2026-09-14, after #72 deployed the nine-link top bar, wcm.agentrust-io.com still showed the old fourteen-link bar with AGT in a browser that had visited within the previous four hours. The server was already serving the new file; the browser had no reason to ask for it.

What changes

• tools/build-header.py now stamps /supernav.js?v={CSS_VERSION} on the 11 hub pages that load the top bar, next to the design-system.css?v= it already stamps, and --check fails when either lags. The static catalog must still load no script, and the check enforces that too.
• tools/build-controls.py emits the versioned URL in the /go/ footer, so /go/ and the 30 control permalinks match.
• tools/site_header.py keeps the one constant, CSS_VERSION (still 21), and now documents that it versions both files on every AgenTrust site.
• tools/check-availability.py, the scheduled six-hourly check, reads the home page of each MkDocs host (trace, manifest, cmcp, ca2a, governance, tests, wcm) and fails, naming the host, when its design-system.css or supernav.js URL is not at the current CSS_VERSION. It imports the number from site_header.py and adds the per-host result to availability-results.json.
• tools/DISCOVERY.md says how to bump from now on.

Bumping from now on: change CSS_VERSION in tools/site_header.py, run build-header.py, build-controls.py and build-discovery.py, and set the same number in the mkdocs.yml of weight-custody-manifest, agent-manifest, cmcp, ca2a, trace-spec, trace-tests and awesome-ai-governance. The availability check names any host that has not caught up.

Merge order: after the Get started PR this branch is based on, and after the seven docs PRs that set ?v=21 in mkdocs.yml have deployed. Until they deploy, the scheduled availability run reports those hosts as lagging.

Checked

• build-header.py --check (12 pages), build-controls.py --check, build-discovery.py --check, check-site.py, check-discovery.py, check-dashes.js, marketplace.test.js, check-tdx-verifier.mjs, render-adoption.mjs --check and wcm/redirect.test.js pass. No hub page loads an unversioned supernav.js; 41 pages load it at v=21.
• build-header.py --check exits 1 when one page's top bar URL is set back to unversioned, and build-controls.py and build-header.py both exit 1 when /go/ is set to v=20.
• Live run of check-availability.py: all 43 HTTP probes pass, and all seven docs hosts are reported as lagging, with both files unversioned on each, because their mkdocs.yml PRs have not merged. The run exits 1, as it should until they deploy.
• The version matcher, run on minified and quoted HTML snippets: a minified page and a quoted page at v=21 pass; an unversioned page, a stylesheet left at v=20, and a page with no top bar each fail and name what they found.

Generated with Claude Code

https://claude.ai/code/session_013aK3gVWzNdcM3hZ2o2awK2