ci: check documentation links on PRs and nightly with a shared cache

[rwgk]

Description

Related to #2652. Depends on #2994's standalone Linux/Windows pre-commit
workflow. This PR contains the operational link checker; migration tooling
and the live-cutover procedure are reviewed separately in #3002.

Run lychee in one dedicated Linux workflow on direct PR updates and from the
existing nightly workflow. Check tracked Markdown/reStructuredText outside
qa/ and all four assembled documentation trees, including HTML fragments.
Build the checked-out sources independently of wheel/GPU CI and set
documentation source links to that revision. Require nonempty inputs and
explicit successful checker results.

Nightly checks links afresh and publishes immutable successful-check cache
snapshots. PRs restore the newest matching baseline, with a one-day TTL and
separate authored/rendered version-and-policy namespaces. Manual refresh and
restore modes support branch testing before merge. The nightly workflow's
documentation-links-only manual mode exercises its reusable-workflow call,
CI-tool tests, and status gate while keeping wheel/GPU jobs skipped.

Remove the old Windows pre-commit job from heavyweight CI and lychee/cache
steps from copied-ref docs builds. Wire the independent nightly link result
into its status gate. Add source-docs/input helpers, input-selection tests,
and contributor/workflow-testing guidance. Correct the guide to describe
monthly Dependabot updates with no automatic assignee or milestone and remove
the deleted custom updater's dispatch instructions. Keep existing
pre-commit.ci requirements/service active during review. Local per-host lychee
caching remains deferred until a stable release has --cache-location.

Split validation through PATH Pixi with Python 3.14: all six input-selection
tests pass on this layer; repository pre-commit checks pass with the workflow's
existing lychee and local hook-installation reminder skips. Workflow files,
source-docs/input helper code, Pixi tasks, and lychee policy are unchanged by
the split.

Existing hosted validation before the split: the
direct PR checker,
nightly documentation-only run,
and cache reader
pass, including the status gates and skipped GPU jobs. The rendered sweep
checks 1,115 HTML pages. Default-branch cache warming and cross-PR restoration
wait until merge.

Hosted split validation on b687fa46f766d8547a76e04e51dfb3a986c51760: the
pre-commit workflow
passes on Linux and Windows, and the
documentation workflow
passes authored links, rendered HTML, and the aggregate gate.
The CPU source-build/import smoke
also passes; its round-trip and GPU jobs remain skipped.

The lockfile freshness check
fails on the known benchmarks/cuda_core/pixi.lock drift (cuda-pathfinder
1.8.2 to 1.8.3). Its hosted base comparison reproduces identical original and
refreshed lockfile blobs on this head and the PR base, classifying it as base
maintenance. The lockfile refresh remains separate from this work.

This PR stays draft. Heavyweight CI remains under /ok to test <full-SHA>
control. Live ruleset/App changes wait until the replacements are merged.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

I asked codex to guide me through reviewing this PR myself. Sharing what it gave me (in part because I want to click the links here myself):

Review Files changed against #2994; that isolates this layer. I’d use six passes, each with one question to answer before moving on.

1. When does it run, and what does it check?
   Start with lychee.yml’s triggers and checkout. Trace a PR update, nightly call, and manual run. There is no push trigger, so copy-pr-bot’s branch pushes do not add another run. Checkout selects the PR’s head SHA.

2. Are we selecting the intended documentation?
   Read the input selector, then its tests. Authored inputs are tracked Markdown/reST outside qa/; rendered inputs are HTML outside _static. Pay particular attention to skipping README symlinks: checking the same content from another directory can misinterpret relative links. Empty inputs must fail.

3. Does rendered checking use this PR’s sources?
   Follow the build helper. The important safeguards are verifying that all three libraries import from the checkout and match their installed metadata. Installing metapackage metadata with --no-deps preserves those local packages.

4. Does caching preserve the checking policy?
   Read cache preparation through publication. Trace both values of refresh-cache: PRs restore; nightly checks afresh and publishes. Version, policy, and authored/rendered kind separate the namespaces; successful URL checks expire after one day. Shared visibility relies on publishing from main, under GitHub’s cache scope rules.

5. Can failures accidentally produce a green check?
   Examine the checker and aggregate gate, then the nightly gate. Think through a failed docs build, one failed matrix leg, cancellation, and documentation-only mode. That mode requires successful link/tool checks and skipped wheel/GPU jobs.

6. Do the deletions have complete replacements?
   Finish with build-docs.yml, ci.yml, and the documentation changes. The dedicated workflow replaces inline lychee; [no-ci] ci: run pre-commit on Linux and Windows with Dependabot hook updates #2994 replaces Windows pre-commit. Live required-check migration belongs to ci: add required-check migration tooling and cutover guide #3002.