Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499

Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499

Workflow file for this run

.github/workflows/check-links.yml at 47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
- main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
--offline
--root-dir ${{ github.workspace }}/content
--fallback-extensions mdx,md
--config lychee.toml
'content/**/*.md'
'content/**/*.mdx'
'README.md'
'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
- name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
- name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
- name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
- name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
- name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
- name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
{
echo "## ⚠️ The link check did not run"
echo
echo "\`lychee\` was never executed, so **no link in this repository was"
echo "examined** — this red says nothing about the documentation links,"
echo "and nothing about the files this PR touches."
echo
echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
echo "re-running the job is the expected remedy."
echo
echo "The gate remains fail-closed on purpose: a link check that could"
echo "not run must not report success."
} >> "$GITHUB_STEP_SUMMARY"
echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
# Fail-closed, asserted here rather than inherited. The retry step has
# already failed the job, so this `exit 1` is redundant today -- and
# deliberately so: if anyone ever adds `continue-on-error` to the
# retry, the "did not run" case must still be red, not a vacuous
# green (#4690).
exit 1
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
 Check Links

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)
#6499
Sign in to view logs

docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7)


docs(permissions): re-anchor the platform-admin pages on the landed config derivation, and give OS_PLATFORM_OWNER_EMAIL an operator runbook (L7) #6499
Workflow file for this run

.github/workflows/check-links.yml
 at
47983e1
name: Check Links
# Repo-internal link gate (#6028).
#
# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
# unrelated commit, with no rationale recorded; the gate then sat dormant for
# six months while `lychee.toml` and `fail: true` kept it looking alive.
# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
# only, and land it advisory-first (NOT in the required set) until it has shown
# a stable green streak.
#
# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
# advisory gate does not get to consume merge-queue capacity. If it is ever
# promoted into the required set, `merge_group` MUST be added in the same
# change or the queue stalls on a required check that never reports (#6121).
#
# ⚠️ This job checks a link's FILE, never its `#anchor` — `lychee.toml` sets
# `include_fragments = "none"`, and a link to a heading that does not exist is
# reported `[200] OK` here (measured, #7484). Do NOT read a green run as
# "the anchors are fine". The fragment half is owned by `pnpm check:doc-anchors`
# in `lint.yml`, which is REQUIRED where this lane is advisory; `lychee.toml`'s
# `include_fragments` comment records why the enum is not the fix.
on:
workflow_dispatch:
pull_request:
branches:
 - main
jobs:
link-checker:
name: Check Documentation Links
runs-on: ubuntu-latest
# Least privilege: the job only reads the tree and runs lychee offline.
# There is no issue-filing step, and `--offline` makes zero network
# requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
permissions:
contents: read
# The lychee argv lives here, not inline on the step, because the step is
# invoked TWICE (attempt + retry, see #8238 below) and two copies of a
# 9-line argv is a drift hazard: an edit to one copy silently changes what
# the retry checks relative to the first attempt. One definition, two
# readers. `github.workspace` is available in a job-level `env`.
env:
# `--offline` is the internal-only mechanism, and it lives HERE rather
# than in lychee.toml on purpose: the equivalent `offline = true`
# config key is silently ignored by older lychee (measured: ignored on
# 0.19.1, honoured on the 0.24.2 pinned below). A determinism guarantee
# must not depend on which lychee the action happens to install, so it is
# asserted at the invocation site.
#
# Offline means only `file://` targets are resolved -- every http(s)
# link is reported EXCLUDED, never requested. That is what makes this
# gate deterministic and free of external-network flake.
#
# --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
# links in content/** are site routes (`/docs/permissions`), and lychee
# hard-errors on those unless it is told which directory `/` means.
# The Fumadocs content root is `content/`, so `/docs/x` resolves to
# content/docs/x -- and --fallback-extensions supplies the .mdx/.md
# suffix that a site route omits. Without this pair the gate cannot go
# green at all: 1286 root-relative links fail as "Cannot resolve
# root-relative link ... provide a root dir".
#
# ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
# for #6592 and it is not: measured on the pinned lychee 0.24.2, that
# glob reports 8 broken links today, every one a pre-existing ADR →
# source-tree link whose target moved out of this repo. This job would
# be red on every PR from the moment it merged, which is how an
# advisory lane becomes a lane nobody reads (#6028 landed it
# advisory-first specifically to earn a green streak). `docs/adr/` is
# checked by the `Check ADR cross-links` step below instead, which can
# freeze those 8 on a shrink-only baseline and fail on a NEW one --
# something neither `exclude` nor `.lycheeignore` can express, because
# neither ever tells you an entry stopped being needed.
# `ARCHITECTURE.md` joined this glob in #6867: unlike `docs/adr/**`, it
# carried no pre-existing rot once its 10 dead links + 2 stale path
# references were fixed in the same PR, so -- unlike the ADR directory
# above -- it needs no KNOWN_DEAD_TARGETS-style baseline to land clean.
LYCHEE_ARGS: >-
 --offline
 --root-dir ${{ github.workspace }}/content
 --fallback-extensions mdx,md
 --config lychee.toml
 'content/**/*.md'
 'content/**/*.mdx'
 'README.md'
 'ARCHITECTURE.md'
# ⛔ Pin the lychee binary explicitly rather than inheriting the action's
# default (#8238). Three comments in this file already reason about "the
# pinned lychee 0.24.2" -- the `--offline` argument above turns on which
# version runs -- but nothing here pinned it: the version came from
# `lycheeverse/lychee-action@v2`'s own `lycheeVersion` default, which
# moves whenever the `v2` tag moves. The determinism claim was true only
# by coincidence. Asserting it at the invocation site is the same rule
# `--offline` is held to, applied to the thing `--offline` depends on.
LYCHEE_VERSION: v0.24.2
steps:
 - name: Checkout repository
uses: actions/checkout@v7
# ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
# lychee globs below -- see the ⛔ note there for why -- so the decision
# registry gets its own resolver, in the same advisory lane.
#
# Deliberately `node` and not `pnpm`: the script has zero dependencies, so
# this lane needs no setup-node / corepack / `pnpm install`, and the whole
# advisory job stays a checkout plus two checks. It is also why an author
# can run it locally in any container (`pnpm check:adr-links` when a
# workspace install exists, `node scripts/check-adr-links.mjs` when it does
# not) -- which lychee, installed by the action at CI time, cannot offer.
 - name: Check ADR cross-links
run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
# ── #8238: the action's binary download is a single-shot curl ───────────
#
# `lychee-action@v2`'s `lychee-setup` step fetches the release tarball
# with a bare `curl -sfLO` -- no `--retry`, no cache, and a `rm -rf` of
# its download dir on every run, so `actions/cache` cannot reach it (the
# action re-downloads unconditionally whatever is already on disk; a
# cache step here would read as coverage while doing nothing).
#
# When that one curl loses, `curl` exits 22 ("HTTP page not retrieved"),
# the action's `Install lychee` and `Run Lychee` steps both report
# `skipped`, and this job goes red having examined ZERO links. Measured
# on three unrelated PRs in one afternoon (2026-08-12), all three job
# logs read directly and byte-identical in shape:
#
# #8128 17:23:49Z run 31622391000 job 94200196323 exit 22, 497ms
# #8205 20:08:47Z run 31636151516 job 94246838620 exit 22, 177ms
# #8225 21:21:28Z run 31642129140 job 94266966755 exit 22
#
# Transient, not systemic: every one cleared on the next attempt, and
# PR #8227 went green at 21:27:53Z, six minutes after #8225's failure.
#
# ⛔ This is NOT gate weakening and must not become it. `fail: true`
# stays on both attempts and neither is allowed to fail open: a retry
# that exhausts still fails the job -- it just now says WHY.
 - name: Check links with lychee
id: lychee
# Attempt 1 only. `continue-on-error` here hands the verdict to the
# retry below; it does NOT let a failure through, because the retry
# step carries no such escape and its failure fails the job.
continue-on-error: true
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
# Fail the job if broken links are found
fail: true
# A back-to-back retry is not obviously enough. Every observed recovery
# was tens of seconds to tens of minutes later, so retrying within the
# same second would be retrying inside the same blip. 15s is a judgement,
# not a measurement -- the retry is the part the evidence supports. Costs
# nothing on a green run: this step is `skipped` when attempt 1 passes.
 - name: Wait before retrying the lychee setup
if: steps.lychee.outcome == 'failure'
run: sleep 15
 - name: Check links with lychee (retry)
id: lychee-retry
if: steps.lychee.outcome == 'failure'
uses: lycheeverse/lychee-action@v2
with:
lycheeVersion: ${{ env.LYCHEE_VERSION }}
args: ${{ env.LYCHEE_ARGS }}
fail: true
# ── #8238, the legibility half: distinguish "links are broken" from ────
# "the link check never ran"
#
# Both outcomes were the same red before this step, and telling them
# apart cost every reader a job-log read. `exit_code` is the
# discriminator, and it is exact rather than heuristic: the action's
# `entrypoint.sh` writes `exit_code=$LYCHEE_EXIT_CODE` to `$GITHUB_OUTPUT`
# BEFORE it exits, so a genuine broken-link failure carries a value (2)
# while a setup failure skips `Run Lychee` entirely and leaves the output
# unset. Empty ⇒ lychee never executed ⇒ nothing about the links was
# examined, whatever the check's name suggests.
#
# `$GITHUB_STEP_SUMMARY` is safe to append to here: the only writer of
# that file in this job is `entrypoint.sh`, which never ran in the one
# case this step fires.
 - name: Report a setup failure as "the link check did not run"
if: always() && steps.lychee-retry.outcome == 'failure' && steps.lychee-retry.outputs.exit_code == ''
run: |
 {
 echo "## ⚠️ The link check did not run"
 echo
 echo "\`lychee\` was never executed, so **no link in this repository was"
 echo "examined** — this red says nothing about the documentation links,"
 echo "and nothing about the files this PR touches."
 echo
 echo "Both attempts failed while \`lycheeverse/lychee-action@v2\` was"
 echo "downloading the \`${LYCHEE_VERSION}\` binary from the GitHub releases"
 echo "CDN (\`curl\` exit 22). This is a known transient failure (#8238);"
 echo "re-running the job is the expected remedy."
 echo
 echo "The gate remains fail-closed on purpose: a link check that could"
 echo "not run must not report success."
 } >> "$GITHUB_STEP_SUMMARY"
 echo "::error title=Link check did not run::lychee setup failed twice (binary download, curl exit 22). No links were checked — see #8238. Re-run the job."
 # Fail-closed, asserted here rather than inherited. The retry step has
 # already failed the job, so this `exit 1` is redundant today -- and
 # deliberately so: if anyone ever adds `continue-on-error` to the
 # retry, the "did not run" case must still be red, not a vacuous
 # green (#4690).
 exit 1