From e61e2354bdf37bd1894bdea339c4342db519ef35 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Sun, 31 May 2026 12:48:28 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs(agents):=20require=20lychee=20local-ru?= =?UTF-8?q?n=20on=20every=20PR=20=E2=80=94=20added=20to=20Before=20submitt?= =?UTF-8?q?ing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Caught a Fragment-not-found regression in PR #410 only when CI flagged it. The check is cheap to run locally (offline file + fragment lookups; only the external-URL subset hits the network) and catching it before the push avoids a round-trip. Add to the Before-submitting checklist: - the canonical invocation (lychee --config .lychee.toml .) - guidance on the most common breakage class (Fragment not found) which is what bites on doc refactors that move sections between files or rename headings - a one-liner for v0.24+ local lychee installations (since .lychee.toml pins the v0.23 schema) The rule is enforce-via-CI either way (the lychee workflow blocks the merge on any failure); this is just a documentation reminder so agents add it to their pre-push routine and avoid the round-trip. --- AGENTS.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7eb849fa..cb471fb4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1681,6 +1681,32 @@ that does not change what the model is asked to produce — - Re-read the diff and check that every change is intentional. - Check that any renamed headings have matching TOC updates. +- **Run lychee against every changed `.md` / `.rst` / `.md.j2` file.** + CI runs the same check on every PR and a single broken link blocks + the merge; catching it locally avoids a round-trip. The canonical + recipe — same as + [`.github/workflows/doc-validation.yml`](.github/workflows/doc-validation.yml) + invokes: + + ```bash + lychee --config .lychee.toml . + ``` + + Run on the whole repo (cheap — most checks are offline file + + fragment lookups; only the external-URL subset hits the network). + Pay attention to **`Fragment not found in document`** errors — + those are anchor-style links (`other.md#section`) whose target + heading no longer exists. They are the most common breakage after + any refactor that moved a section between files or renamed a + heading. Re-write the link to point at the new location; do not + silence it with an ignore-pattern. + + If your local lychee is v0.24+ (the example config in + `.lychee.toml` pins the v0.23 schema), replace + `include_fragments = true` with `include_fragments = "anchor-only"` + before running, or invoke directly: + `lychee --include-fragments=anchor-only --no-progress `. + - Verify that links to the project's Security Model use an anchor that exists on the current stable version (adopting project's anchors: [`/security-model.md`](/security-model.md)). From e707f7495a6cb7846945f6c848de45d03d7c6b0e Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Sun, 31 May 2026 12:52:34 +0200 Subject: [PATCH 2/2] fix(AGENTS.md): link to link-check.yml, not the made-up doc-validation.yml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Before submitting" lychee guidance pointed at `.github/workflows/doc-validation.yml`, which does not exist — this repo's link-check workflow is `link-check.yml`. Caught by running lychee on the same file the PR added (which is what the new rule itself prescribes). --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cb471fb4..e5de3a53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1685,7 +1685,7 @@ that does not change what the model is asked to produce — CI runs the same check on every PR and a single broken link blocks the merge; catching it locally avoids a round-trip. The canonical recipe — same as - [`.github/workflows/doc-validation.yml`](.github/workflows/doc-validation.yml) + [`.github/workflows/link-check.yml`](.github/workflows/link-check.yml) invokes: ```bash