From 39d70d208cc4480e2a392a6cf3f33c00bbadf84e Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:28:52 -0600
Subject: [PATCH] AGENTS.md: fix the check-links recipe and document --baseline

The documented command piped the diff with process substitution
(--diff <(git diff ...)), which fails with EBADF through
`pnpm run check`: dev/checks.mjs spawns the check with only
stdin/stdout/stderr, so the substitution descriptor is gone. Pipe to
--diff /dev/stdin instead.

Also document --baseline as the way to see only the findings a branch
adds, the way CI does, since --diff never filters findings.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1130b-3f95-71cb-bbbc-b0e2da2593c9
Co-authored-by: Amp <amp@ampcode.com>
---
 AGENTS.md             | 18 +++++++++++++++---
 cspell-allow-list.txt |  1 +
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fe88818e4..99031fe40 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,13 +74,25 @@
   redirect in `src/data/redirects.ts` does not satisfy the check.
 - Link to this site with relative paths (`/admin/config/site-config`), never
   `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`.
-- To also probe the external links you added:
+- main has hundreds of pre-existing findings. To see only the ones your
+  branch adds, as CI does, record the merge base with `--format json` and
+  pass it as `--baseline`; `--diff` does not filter findings, it only scopes
+  `--check-external` and the review comments to added lines:
 
 ```sh
-pnpm run check links --check-anchors --check-self-links \
-  --check-external --diff <(git diff -U0 origin/main)
+base=$(git merge-base origin/main HEAD)
+git worktree add --detach /tmp/docs-base "$base"
+node dev/check-links.mjs --check-anchors --check-self-links --format json \
+  --root /tmp/docs-base > /tmp/docs-base-links.json
+git worktree remove /tmp/docs-base
+git diff -U0 "$base" | pnpm run check links --check-anchors --check-self-links \
+  --check-external --baseline /tmp/docs-base-links.json --diff /dev/stdin
 ```
 
+- Pipe the diff to `--diff /dev/stdin`, not `--diff <(git diff ...)`:
+  `dev/checks.mjs` spawns the check with only stdin/stdout/stderr, so the
+  process-substitution descriptor is gone and the check fails with `EBADF`
+
 ### PR check comments
 
 The spelling, links, redirects, and example hostnames checks comment on the
diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index d700988ac..4fdce36b5 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -182,6 +182,7 @@ drwxr
 dshm
 dumpall
 eastus
+EBADF
 eksctl
 ELEC
 elif