ci(links): tolerate auth walls and anti-bot 403s in link checker

.github/workflows/validate.yml

@@ -38,13 +38,11 @@ jobs:
       - name: Lychee link checker
         uses: lycheeverse/lychee-action@1d97d84f0bc547f7b25f4c2170d87d810dc2fb2c # v2.6.1
         with:
-          # Check every committed markdown file. Skip mailto: and localhost.
-          # `--no-progress` makes the log readable. `--max-redirects` allows
-          # githubusercontent and short-link hops.
+          # Configuration lives in lychee.toml at the repo root. Args here
+          # only point lychee at the markdown files to check; everything
+          # else (accepted status codes, retries, user agent, exclude list)
+          # is driven by the config so it stays auditable in one place.
           args: >-
             --no-progress
-            --max-redirects 5
-            --exclude-mail
-            --exclude '^https?://(localhost|127\.0\.0\.1)'
             './**/*.md'
           fail: true

lychee.toml

@@ -0,0 +1,41 @@
+# Lychee link-checker configuration.
+#
+# CI runs `lychee './**/*.md'` against every committed markdown file. Most
+# defaults are fine; the overrides below stop lychee from flagging links
+# that are correct but answer with non-200 status codes for legitimate
+# reasons (authentication walls, anti-bot 403s, transient rate limits).
+
+# Status codes treated as success. Defaults are 200-299; we add common
+# redirect codes (handled by --max-redirects but listed explicitly for
+# clarity) and 403/429 which mean "the link works but lychee is not
+# allowed to fetch it." Both are normal for GitHub security pages and
+# CDN-fronted sites.
+accept = ["200..=299", "301..=308", "403", "429"]
+
+# Follow redirects (e.g. lowercase repo aliases, shortened URLs).
+max_redirects = 5
+
+# Be polite, retry once with a small backoff on transient errors.
+max_retries = 2
+retry_wait_time = 2
+
+# Send a real browser UA — some hosts (Cloudflare, Squarespace, etc.)
+# 403 anything that looks like a bot.
+user_agent = "Mozilla/5.0 (compatible; lychee-link-checker)"
+
+# Per-link timeout in seconds.
+timeout = 20
+
+# Skip mail addresses and any link that would resolve to the local host.
+exclude_mail = true
+exclude = [
+  # localhost / loopback
+  "^https?://(localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0)",
+  # The PVR URL 302-redirects to a GitHub login wall, which lychee
+  # cannot follow. The URL itself is correct.
+  "^https://github\\.com/bigwellaadmin-dev/verify/security/advisories/new$",
+]
+
+# Tell lychee where to look. The workflow also passes this on the
+# command line as a safety net.
+include_verbatim = false