From 25ca189e49944cc1ba95f59e098802a47ec6d2b4 Mon Sep 17 00:00:00 2001
From: Guillaume ARM <trapcodien@gmail.com>
Date: Tue, 9 Jun 2026 02:34:40 +0200
Subject: [PATCH] chore(dev): validate markdown links

---
 CLAUDE.md      |  2 +-
 DEVELOPMENT.md |  2 +-
 Justfile       | 18 +++++++++++++++---
 lychee.toml    |  4 ++++
 4 files changed, 21 insertions(+), 5 deletions(-)
 create mode 100644 lychee.toml

diff --git a/CLAUDE.md b/CLAUDE.md
index 53b84b9..053fe2b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peri
 - Use `/apis/libtest.lua` for test scripts under `tests/`; `/programs/runtest.lua` prints `__TRAPOS_TEST_OK__` only after the suite passes.
 - `libtest` cancels each case after `3`s (`--timeout <s>` / `--no-timeout` to override); never commit a hanging test to `tests/`. Slow harness fixtures go in `tests/harness/` behind dedicated recipes. See `docs/adrs/adr-0009-layered-test-timeouts.md`.
 - Git hooks own commit/push verification: pre-commit runs `just check test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`.
-- After editing Lua, run `just check` and fix all `luacheck` warnings.
+- After editing Lua or Markdown, run `just check` and fix all `luacheck` warnings and `lychee` broken-link reports (markdown link validation is offline-only via `just lint-markdown`).
 - Use 2-space indent, semicolons, and `local function`.
 - `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`.
 - Most API modules return factories; call the required module once before use.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 439f29e..069f450 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -2,7 +2,7 @@
 
 ## Installation
 
-Install `just`, `jq`, `luacheck`, `openssl`, and [CraftOS-PC v2.8.3+](docs/install-craftos-pc.md), then run:
+Install `just`, `jq`, `luacheck`, `openssl`, `lychee` (`brew install lychee`, or `cargo install lychee` if you already have a Rust toolchain), and [CraftOS-PC v2.8.3+](docs/install-craftos-pc.md), then run:
 
 ```sh
 just install trapos-install && echo ok
diff --git a/Justfile b/Justfile
index 1c77d44..53a5941 100644
--- a/Justfile
+++ b/Justfile
@@ -82,8 +82,15 @@ check-openssl:
         exit 1; \
     }
 
+# Verify lychee is installed.
+check-lychee:
+    @command -v lychee >/dev/null 2>&1 || { \
+        printf '%s\n' 'lychee not found on $PATH. See DEVELOPMENT.md.' >&2; \
+        exit 1; \
+    }
+
 # Verify tools needed for local installation and CraftOS-PC launch recipes.
-check-install: check-craftos check-jq check-luacheck check-openssl
+check-install: check-craftos check-jq check-luacheck check-openssl check-lychee
 
 # Generate local secrets on first install.
 generate-env:
@@ -356,6 +363,11 @@ test-timeout-shell: (_timeout-fixture "/tests/harness/slow-case.lua" "${TRAP_CCL
 # Fast regression guard for both timeout layers. Wired into `ci`.
 test-timeout: test-timeout-lua test-timeout-shell
 
-# Lint all Lua source with luacheck.
-check: check-luacheck
+# Lint all Lua source with luacheck and validate markdown links.
+check: check-luacheck check-lychee
     luacheck --quiet .
+    @just lint-markdown
+
+# Validate local markdown links and heading anchors with lychee.
+lint-markdown: check-lychee
+    lychee --config lychee.toml .
diff --git a/lychee.toml b/lychee.toml
new file mode 100644
index 0000000..2338ca2
--- /dev/null
+++ b/lychee.toml
@@ -0,0 +1,4 @@
+offline = true
+include_fragments = "full"
+include_verbatim = false
+extensions = ["md"]