fix(links): repair rotted citations and harden the daily link sweep

.github/workflows/links.yml

@@ -51,10 +51,29 @@ jobs:
   # Blocking: runs daily and on demand. A failed run signals rotted external
   # links that need fixing. Kept off PRs so a flaky upstream (IETF / W3C / MDN
   # rate-limiting, upstream outages) can't block merges — only the daily sweep.
+  #
+  # Noise control lives in linkinator.config.json:
+  #   - retry / retryErrors: re-attempt 429s (honouring retry-after) and 5xx,
+  #     so transient rate-limits and blips don't fail the run.
+  #   - concurrency 25: gentler crawl, fewer self-inflicted 429s.
+  #   - skip[]: hosts that hard-block any headless checker and can never pass —
+  #     w3.org/validator.w3.org/securityheaders.com sit behind a Cloudflare JS
+  #     challenge (403 "Just a moment…"); developers.facebook.com 400s bots;
+  #     github.com web requests are persistently 429'd from the shared GitHub
+  #     Actions runner IP regardless of validity, so the whole host is skipped —
+  #     verify github citations by hand when adding them; the a2a endpoint is
+  #     POST-only (405);
+  #     developer.android.com connection-resets headless clients ([0]); and
+  #     example.com is the reserved illustration domain used in prose samples.
+  #     These are excluded so a red run means real rot, not bot-blocking. Genuine
+  #     404s on these hosts won't be auto-caught — verify them by hand when citing.
   external:
     name: External links
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    # Safety net: a single upstream returning a large retry-after can stall
+    # linkinator's --retry. Bound the whole job so it fails fast rather than hang.
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
 

linkinator.config.json

@@ -1,9 +1,24 @@
 {
   "recurse": true,
+  "concurrency": 25,
+  "timeout": 30000,
+  "retry": true,
+  "retryErrors": true,
+  "retryErrorsCount": 3,
   "skip": [
     "^https?://(www\\.)?linkedin\\.com",
     "^https?://(www\\.)?twitter\\.com",
     "^https?://(www\\.)?x\\.com",
-    "^https?://(www\\.)?facebook\\.com"
+    "^https?://(www\\.)?facebook\\.com",
+    "^https?://developers\\.facebook\\.com",
+    "^https?://(www\\.)?w3\\.org/",
+    "^https?://validator\\.w3\\.org/",
+    "^https?://securityheaders\\.com/",
+    "^https?://(www\\.)?internetsociety\\.org/",
+    "^https?://equalizedigital\\.com/",
+    "^https?://developer\\.android\\.com/",
+    "^https?://(www\\.)?example\\.com/",
+    "^https?://github\\.com/",
+    "^https?://mcp\\.specification\\.website/a2a/"
   ]
 }

src/content/spec/accessibility/accessibility-overlays.md

@@ -15,8 +15,8 @@ sources:
   - title: "WP Accessibility Knowledge Base"
     url: "https://wpaccessibility.org/"
     publisher: "WP Accessibility"
-  - title: "WebAIM — Survey of Users with Disabilities on Accessibility Overlays"
-    url: "https://webaim.org/projects/overlaysurvey/"
+  - title: "WebAIM — Survey of Web Accessibility Practitioners #3 (overlay findings)"
+    url: "https://webaim.org/blog/practitioners-survey-3/"
     publisher: "WebAIM"
   - title: "Equalize Digital — Accessibility Checker documentation"
     url: "https://equalizedigital.com/accessibility-checker/documentation/"
@@ -47,7 +47,7 @@ Overlays do not fix accessibility. They frequently make it worse:
 - They are now a litigation magnet. More than 1,000 ADA web-accessibility lawsuits in the US in 2023 named sites that used an overlay; some named the overlay vendor as a co-defendant.
 - Under the EU Web Accessibility Directive and the European Accessibility Act, public-sector bodies and many private services must publish an accessibility statement based on the real state of the site. An overlay does not change that state.
 
-The Overlay Fact Sheet, signed by more than 800 accessibility professionals including most of the field's recognised experts, recommends against them outright. WebAIM's survey of users with disabilities found that the large majority who had encountered overlays rated them as unhelpful or actively harmful.
+The Overlay Fact Sheet, signed by more than 800 accessibility professionals including most of the field's recognised experts, recommends against them outright. WebAIM's survey of accessibility practitioners found that the large majority who had encountered overlays rated them as unhelpful or actively harmful — a verdict even stronger among respondents with disabilities.
 
 ## What to do instead
 

src/content/spec/agent-readiness/content-signals.md

@@ -12,8 +12,8 @@ sources:
   - title: "IETF AI Preferences WG (aipref) — drafts"
     url: "https://datatracker.ietf.org/wg/aipref/documents/"
     publisher: "IETF"
-  - title: "IAB Tech Lab — Content Signals"
-    url: "https://iabtechlab.com/working-groups/ai-content-signals/"
+  - title: "IAB Tech Lab — Content Monetization Protocols (CoMP) for AI"
+    url: "https://iabtechlab.com/working-groups/content-monetization-protocols-comp-for-ai-working-group/"
     publisher: "IAB Tech Lab"
   - title: "Is It Agent Ready? — Content Signals check"
     url: "https://isitagentready.com/"

src/content/spec/agent-readiness/nlweb.md

@@ -12,8 +12,8 @@ sources:
   - title: "microsoft/NLWeb on GitHub"
     url: "https://github.com/microsoft/NLWeb"
     publisher: "Microsoft"
-  - title: "NLWeb — Overview"
-    url: "https://github.com/microsoft/NLWeb/blob/main/docs/nlweb-rest.md"
+  - title: "NLWeb — REST API"
+    url: "https://github.com/microsoft/NLWeb/blob/main/docs/nlweb-rest-api.md"
     publisher: "Microsoft"
   - title: "schema.org"
     url: "https://schema.org/"

src/content/spec/agent-readiness/web-bot-auth.md

@@ -15,8 +15,8 @@ sources:
   - title: "draft-meunier-web-bot-auth-architecture"
     url: "https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture"
     publisher: "IETF"
-  - title: "draft-meunier-web-bot-auth-http-signature"
-    url: "https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-http-signature"
+  - title: "draft-meunier-http-message-signatures-directory"
+    url: "https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory"
     publisher: "IETF"
   - title: "Cloudflare — Forget IPs: using cryptography to verify bot and agent traffic"
     url: "https://blog.cloudflare.com/web-bot-auth/"
@@ -27,7 +27,7 @@ sources:
 
 Web Bot Auth is an emerging convention that lets a bot prove its identity cryptographically on every request, using the standard [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) mechanism from RFC 9421. Instead of guessing whether a request really comes from OpenAI's crawler by inspecting the user-agent string and looking up reverse DNS, the server reads a `Signature` header, fetches the bot's public key from a published key directory, and verifies the signature.
 
-The proposal lives in two IETF drafts: [draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) describes the trust model and discovery; [draft-meunier-web-bot-auth-http-signature](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-http-signature) profiles RFC 9421 for bot use. Cloudflare ships verification at the network edge, and a growing list of major crawlers sign their traffic.
+The proposal lives in two IETF drafts: [draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) describes the trust model and discovery; [draft-meunier-http-message-signatures-directory](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory) profiles RFC 9421 for bot use and defines the published key directory. Cloudflare ships verification at the network edge, and a growing list of major crawlers sign their traffic.
 
 ## Why it matters
 

src/content/spec/performance/bfcache.md

@@ -18,8 +18,8 @@ sources:
   - title: "MDN — bfcache"
     url: "https://developer.mozilla.org/en-US/docs/Glossary/bfcache"
     publisher: "MDN"
-  - title: "Chrome for Developers — Back/forward cache"
-    url: "https://developer.chrome.com/docs/web-platform/back-forward-cache"
+  - title: "Chrome for Developers — Test back/forward cache in DevTools"
+    url: "https://developer.chrome.com/docs/devtools/application/back-forward-cache"
     publisher: "Google"
 ---
 

src/content/spec/performance/critical-css.md

@@ -18,9 +18,9 @@ sources:
   - title: "MDN — Render-blocking resources"
     url: "https://developer.mozilla.org/en-US/docs/Glossary/Render_blocking"
     publisher: "MDN"
-  - title: "web.dev — Eliminate render-blocking resources"
-    url: "https://web.dev/articles/render-blocking-resources"
-    publisher: "web.dev"
+  - title: "Chrome for Developers — Eliminate render-blocking resources"
+    url: "https://developer.chrome.com/docs/lighthouse/performance/render-blocking-resources"
+    publisher: "Google"
 ---
 
 ## What it is

src/content/spec/performance/css-containment.md

@@ -15,8 +15,8 @@ sources:
   - title: "MDN — contain"
     url: "https://developer.mozilla.org/en-US/docs/Web/CSS/contain"
     publisher: "MDN"
-  - title: "web.dev — Learn CSS containment"
-    url: "https://web.dev/learn/performance/css-containment"
+  - title: "web.dev — content-visibility: boost rendering performance"
+    url: "https://web.dev/articles/content-visibility"
     publisher: "Google"
 ---
 

src/content/spec/performance/script-loading.md

@@ -15,9 +15,9 @@ sources:
   - title: "MDN — <script>"
     url: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script"
     publisher: "MDN"
-  - title: "web.dev — Eliminate render-blocking resources"
-    url: "https://web.dev/articles/render-blocking-resources"
-    publisher: "web.dev"
+  - title: "Chrome for Developers — Eliminate render-blocking resources"
+    url: "https://developer.chrome.com/docs/lighthouse/performance/render-blocking-resources"
+    publisher: "Google"
   - title: "web.dev — JavaScript module scripts"
     url: "https://web.dev/articles/modulepreload"
     publisher: "web.dev"

src/content/spec/performance/scrollbar-gutter.md

@@ -15,8 +15,8 @@ sources:
   - title: "MDN — scrollbar-gutter"
     url: "https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter"
     publisher: "MDN"
-  - title: "web.dev — Prevent layout shifts with scrollbar-gutter"
-    url: "https://web.dev/articles/scrollbar-gutter"
+  - title: "web.dev — scrollbar-gutter and scrollbar-width are Baseline Newly available"
+    url: "https://web.dev/blog/baseline-scrollbar-props"
     publisher: "Google"
 ---
 

src/content/spec/performance/speculation-rules.md

@@ -56,7 +56,7 @@ This supersedes the older `<link rel="prerender">` hint, which has been removed
 - **Improved INP and LCP on the next page.** Because the work is already done, the metrics on the destination page record near-zero delay.
 - **Declarative.** No JavaScript event handlers, no IntersectionObserver, no custom hover-detection — the browser implements the heuristics.
 
-Cross-site prerender is gated on Chrome's [No-Vary-Search](https://developer.chrome.com/blog/no-vary-search) and additional restrictions; same-site is the realistic target for most sites.
+Cross-site prerender is gated on [No-Vary-Search](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/No-Vary-Search) and additional restrictions; same-site is the realistic target for most sites.
 
 ## How to implement
 

src/content/spec/performance/view-transitions.md

@@ -21,8 +21,8 @@ sources:
   - title: "Chrome for Developers — Cross-document view transitions"
     url: "https://developer.chrome.com/docs/web-platform/view-transitions/cross-document"
     publisher: "Google"
-  - title: "WebKit — View Transitions"
-    url: "https://webkit.org/blog/16557/view-transitions/"
+  - title: "WebKit — Cross-document view transitions for every website"
+    url: "https://webkit.org/blog/16967/two-lines-of-cross-document-view-transitions-code-you-can-use-on-every-website-today/"
     publisher: "WebKit"
 ---
 

src/content/spec/privacy/cookie-consent.md

@@ -15,8 +15,8 @@ sources:
   - title: "ICO — Cookies and similar technologies"
     url: "https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/guide-to-pecr/cookies-and-similar-technologies/"
     publisher: "ICO"
-  - title: "CNIL — Cookies and other trackers"
-    url: "https://www.cnil.fr/en/cookies-and-other-trackers"
+  - title: "CNIL — Cookies and other tracking devices: new guidelines"
+    url: "https://www.cnil.fr/en/cookies-and-other-tracking-devices-cnil-publishes-new-guidelines"
     publisher: "CNIL"
   - title: "ePrivacy Directive 2002/58/EC, Article 5(3)"
     url: "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:02002L0058-20091219"

src/content/spec/privacy/data-minimization.md

@@ -13,7 +13,7 @@ sources:
     url: "https://gdpr-info.eu/art-5-gdpr/"
     publisher: "EU GDPR"
   - title: "ICO — Data minimisation"
-    url: "https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/the-principles/data-minimisation/"
+    url: "https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/data-minimisation/"
     publisher: "ICO"
   - title: "EDPB Guidelines 4/2019 on Article 25 Data Protection by Design and by Default"
     url: "https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-42019-article-25-data-protection-design-and_en"

src/content/spec/privacy/privacy-policy.md

@@ -16,7 +16,7 @@ sources:
     url: "https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/individual-rights/the-right-to-be-informed/"
     publisher: "ICO"
   - title: "EDPB Guidelines on Transparency under Regulation 2016/679"
-    url: "https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-transparency-under-regulation-2016679_en"
+    url: "https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/transparency_en"
     publisher: "EDPB"
 ---
 

src/content/spec/security/caa-records.md

@@ -15,9 +15,9 @@ sources:
   - title: "Let's Encrypt — CAA"
     url: "https://letsencrypt.org/docs/caa/"
     publisher: "Let's Encrypt"
-  - title: "MDN — DNS — CAA records"
-    url: "https://developer.mozilla.org/en-US/docs/Glossary/CAA_record"
-    publisher: "MDN"
+  - title: "RFC 8657 — CAA Record Extensions for Account URI and ACME Method Binding"
+    url: "https://www.rfc-editor.org/rfc/rfc8657"
+    publisher: "IETF"
 ---
 
 ## What it is