From d8a791fbdb3b1a3ba1aaf1e84c1411f633ddc349 Mon Sep 17 00:00:00 2001
From: Paul Mulligan <paul@pmds.pull-list.net>
Date: Thu, 9 Apr 2026 15:39:15 -0400
Subject: [PATCH 1/2] feat: add markdown link validation to CI workflow

Add lychee-based link checking as a parallel CI job to catch broken
internal and external links in documentation files. Includes a
.lychee.toml config with retry/timeout settings and exclusions for
URLs known to block automated checks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 17 +++++++++++++++++
 .lychee.toml             | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 .lychee.toml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index da2cee0..c6f4cd3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -177,3 +177,20 @@ jobs:
 
           echo "$errors template validation failures"
           exit $errors
+
+  check-links:
+    name: Check Markdown Links
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check markdown links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            '*.md'
+            'docs/**/*.md'
+          fail: true
diff --git a/.lychee.toml b/.lychee.toml
new file mode 100644
index 0000000..72a7968
--- /dev/null
+++ b/.lychee.toml
@@ -0,0 +1,40 @@
+# Lychee link checker configuration
+# https://lychee.cli.rs/usage/config/
+
+# Directories and files to exclude from checking
+exclude_path = [
+  "node_modules",
+  ".git",
+  "pnpm-lock.yaml",
+  ".claude"
+]
+
+# Max number of retries per request (handles transient failures)
+max_retries = 3
+
+# Timeout per request in seconds
+timeout = 30
+
+# Max concurrent requests (avoid rate limiting)
+max_concurrency = 5
+
+# Accept 200..=299 status codes
+accept = [200, 201, 202, 203, 204, 206, 429]
+
+# Exclude URLs that are known to block automated checks or are placeholders
+exclude = [
+  # Patreon blocks automated requests
+  "https://www.patreon.com/.*",
+  # Shield badge images (always valid if the URL format is correct)
+  "https://img.shields.io/.*",
+  # Contributor Covenant version-specific URLs may redirect
+  "https://www.contributor-covenant.org/version/.*",
+  # Example/placeholder URLs
+  "https://example.com.*"
+]
+
+# Don't fail on URLs behind authentication or known to be flaky
+exclude_all_private = true
+
+# Skip checking mail addresses
+include_mail = false

From 0d8dc08cdb5dcb72e5ed0637d5066485d5c2c98f Mon Sep 17 00:00:00 2001
From: Paul Mulligan <paul@pmds.pull-list.net>
Date: Thu, 9 Apr 2026 15:45:20 -0400
Subject: [PATCH 2/2] fix: explicitly pass lychee config path in CI workflow

The lychee-action was not automatically picking up .lychee.toml,
causing Patreon URLs (which return 403 to automated checks) to
fail the build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c6f4cd3..2cf5e09 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -191,6 +191,7 @@ jobs:
           args: >-
             --verbose
             --no-progress
+            --config .lychee.toml
             '*.md'
             'docs/**/*.md'
           fail: true