docs: kkt is retired, occidata is the sole GPU runner; document the GPU docs-build pass

[ocots]

Two things converge in this PR: WORKFLOWS.md's runner-fleet description had drifted well past what the fleet actually does, and control-toolbox/OptimalControl.jl#885 part 2 adds a new pattern (documentation.yml's optional build-gpu pass) worth documenting from day one.

The fleet is not what this document said

Measured 2026-09-02 by checking every CI.yml directly (not inferred from labels, which lag behind actual jobs) plus gh api orgs/control-toolbox/actions/runners:

• kkt is retired, not "the other half of a split alongside occidata". The org registers only occidata-runner and pinwheel — no kkt. Every package with GPU-relevant code (CTParser.jl, CTDirect.jl, CTFlows.jl, CTSolvers, CTLie) calls ci.yml exactly twice: github-runner + occidata-runner. No repo has a third job. A three-way split, which this document described for CTFlows.jl, doesn't exist anywhere.
• CTLie has already joined the split, not "planned" (test: add GPU test suite and split CI, closes #21).
• CTDirect.jl has already migrated off its older, separate GPU.yml onto the same two-way split as everyone else — its own CI.yml comment says so directly ("Replaces the retired kkt runner").
• The kkt-runner label survives as an inert leftover in three repos (OptimalControl, CTFlows.jl, CTLie) — defined, consumed by nothing.

All corrected: the trigger-labels table (§2, kkt-runner now marked retired), the naming-convention paragraph right after it, the reusable-workflows table and split-CI paragraphs (§3.1), the fleet adoption table (§4), the walkthrough example (§3.1), and the new-repo checklist (§8) — which, uncorrected, would have told someone bootstrapping a repo to create a label for a runner that doesn't exist.

A third self-hosted GPU box, pinwheel, exists and was undocumented. Found while probing occidata's org runner listing for the same task. It's AMD, not CUDA — not a candidate for any :gpu CI in this ecosystem, since the whole stack (ExaModels → MadNLPGPU → CUDSS) is CUDA-only. Recorded so nobody points a CUDA job at it by accident.

New: documentation.yml's optional GPU upgrade pass

CTActions#71 adds build-gpu, gated by a new gpu_runner input, for control-toolbox/OptimalControl.jl#885 part 2. Documented here as a distinct shape from ci.yml's split, not the same pattern: publish then upgrade, not attempt then fall back. A docs build's single job both builds and deploys (deploydocs runs inside docs/make.jl), so there's no room to attempt-GPU-then-fall-back-to-CPU within one job the way ci.yml's split can. build-gpu instead runs only once the existing GitHub-hosted build job has already published, and can never fail the workflow (continue-on-error: true) — on success it redeploys with real GPU numbers, on failure or a long queue the already-published site is simply left as is.

documentation.yml's row in §3.1's reusable-workflows table gains its new gpu_runner/gpu_timeout_minutes inputs; §3.2 gains occidata's new role as a docs-build target, plus two operational quirks worth knowing before blaming a slow or retried job on the runner itself — its /tmp is wiped hourly at HH:01, and this workflow's own Monday 02:30 UTC maintenance purges the compiled-code cache.

Also

Fixed one incidental markdownlint MD028 (two adjacent blockquotes separated by a blank line) introduced while drafting the pinwheel note.

🤖 Generated with Claude Code