diff --git a/AGENTS.md b/AGENTS.md
index 674ff4307..a9e3e2404 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,8 +6,8 @@
 -   **Build**: `npm run build`
 -   **Dev**: `npm run dev`
 -   **Lint**: `npm run lint`
--   **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm run build` runs them first, so any finding fails a deploy
--   **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; the build runs it without flags, so only dead page links fail a deploy). When moving a page or renaming a heading, update every link to it; a 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: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)`
+-   **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm run build` runs filenames and images first, so a finding from those fails a deploy. Links is not in the build: it runs as its own PR check (`.github/workflows/check-links.yml`)
+-   **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links and fails the `Broken links introduced by this PR` check; see `dev/check-links.mjs`). When moving a page or renaming a heading, update every link to it; a 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: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)`
 -   **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a Markdown table for the PR description
 -   **Vercel build failures**: Vercel shows build logs only to its team members, so `.github/workflows/vercel-build-report.yml` comments the log tail on the PR (see `dev/report-vercel-build.mjs`). It reads Vercel with the `VERCEL_TOKEN` repo secret, a token scoped to the `sourcegraph-docs` project that expires 2026-12-10; mint a new one with `POST /v3/user/tokens?teamId=<team>` and `projectId` in the body. It also attaches the full log to the Vercel Slack app's "failed to deploy" post in `#alerts-vercel-doc-site`, using the `SLACK_BOT_TOKEN` repo secret and `SLACK_CHANNEL_ID` repo variable. The bot is the Slack app in `dev/slack-app-vercel-build-report.json`; to recreate it, paste that manifest at <https://api.slack.com/apps?new_app=1> (From a manifest), install it, copy its Bot User OAuth Token into the secret, and `/invite @Vercel build log` to the channel
 
diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index 3bb48936e..ce15368e3 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -16,8 +16,8 @@
  *   should be relative links; the finding proposes one, following src/data/redirects.ts
  * - With --check-external, external links on added lines that return 404 or 410
  *
- * next.config.js runs this with no flags on every build, so only dead page links
- * can fail a deploy; the flags below are for the pull request workflow.
+ * The pull request workflow (.github/workflows/check-links.yml) runs this with
+ * the flags below; `npm run build` does not run it, so findings never fail a deploy.
  *
  * Usage: node dev/check-links.mjs [options]
  *   --check-anchors        Also validate #anchors against headings
diff --git a/dev/checks.mjs b/dev/checks.mjs
index c947a9521..d2e3ffe4e 100644
--- a/dev/checks.mjs
+++ b/dev/checks.mjs
@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * Runs the docs checks in dev/check-*.mjs. `npm run build` runs them all
- * before `next build`.
+ * Runs the docs checks in dev/check-*.mjs. `npm run build` runs filenames and
+ * images before `next build`; links has its own pull request check
+ * (.github/workflows/check-links.yml), so a dead link does not fail a deploy.
  *
  * Usage: node dev/checks.mjs [check ...] [flags]
  *   node dev/checks.mjs                                 every check
diff --git a/package.json b/package.json
index ac7909acf..2dd5709c3 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,7 @@
 	},
 	"scripts": {
 		"dev": "next dev",
-		"build": "node dev/checks.mjs && node dev/generate-mermaid-icons.mjs && next build",
+		"build": "node dev/checks.mjs filenames images && node dev/generate-mermaid-icons.mjs && next build",
 		"start": "next start",
 		"lint": "next lint",
 		"check": "node dev/checks.mjs",