Skip to content

docs: link to pages that exist - #10

Merged
blakebauman merged 3 commits into
mainfrom
docs-links
Aug 15, 2026
Merged

blakebauman merged 3 commits into
mainfrom
docs-links

Conversation

@blakebauman

Copy link
Copy Markdown
Member

Every documentation link this console emitted was a 404.

They carried a version segment — docs.fold.run/1.10/configuration/ — on the
reasoning that the docs an operator opens from a running gateway should be the
docs for that gateway. That is a good idea, and it is one I borrowed from
tools whose documentation is published per release. fold's is a single
unversioned Starlight site, so the prefix matched nothing.

Three of the topic slugs did not exist under any prefix either. I had invented
federation, policy and observability from the console's own section names
rather than reading the docs.

Verified against the live site this time, rather than assumed:

/configuration/        200      /1.10/configuration/   404
/operations/           200      /federation/           404
/discovery/            200      /policy/               404
/tenancy/              200      /observability/        404
/security/             200

The fix

Topics map to real pages, with anchors where the page is broad and the question
is narrow — the Governance cards go to configuration/#policy rather than the
top of a reference that opens on upstreams. Anchors are checked against id
attributes on the live pages. federation becomes upstreams, pointing at the
block an operator on that page is actually asking about.

The version parameter is gone, and minorLine with it — it existed only to
build the segment.

Why nothing caught it

These are external navigations. The CSP never sees them, no unit test renders
an href it did not itself supply, and a plausible-looking URL reads as correct
until somebody clicks it. There is exactly one check with power here: the one
that asks the internet.

tests/docs-links.spec.ts fetches every URL the console can produce and
asserts 200. For anchored links it also asserts the id exists — a wrong
anchor does not 404
, it silently lands at the top of the page, which is the
failure mode that looks like success.

It runs under the contract config alongside the gateway contract: both talk to
something outside this repo, and neither belongs in an e2e run that has to stay
answerable to the code in the pull request. Pull requests and the Monday
schedule.

Verified the check can fail

Not trusted on a green first run. With the version prefix restored on one topic
and an anchor changed to #policies:

✘ observability points at a page that exists
    https://docs.fold.run/1.10/operations/ should exist
✘ anchors point at headings that exist
    policy: https://docs.fold.run/configuration/ has no id="policies"

81 tests pass, 4 skip without a gateway. 244,365 bytes.

🤖 Generated with Claude Code

Every documentation link this console emitted was a 404.

They carried a version segment — docs.fold.run/1.10/configuration/ — on the
reasoning that the docs an operator opens from a running gateway should be the
docs for that gateway. That is a good idea, and it is borrowed from tools whose
documentation is published per release. fold's is one unversioned Starlight
site, so the prefix matched nothing. Three of the topic slugs (federation,
policy, observability) did not exist under any prefix either; I had invented
them from the console's own section names rather than reading the docs.

Verified against the live site rather than assumed this time:

  /configuration/          200      /1.10/configuration/   404
  /operations/             200      /federation/           404
  /discovery/ /tenancy/    200      /policy/               404
  /security/               200      /observability/        404

Topics now map to real pages, with anchors where the page is broad and the
question is narrow — the Governance cards go to configuration#policy rather
than the top of a reference that opens on upstreams. The anchors are checked
against ids on the live pages. `federation` becomes `upstreams`, pointing at
the block an operator on that page is actually asking about.

The version parameter is gone, along with minorLine, which existed only to
build the segment.

WHY NOTHING CAUGHT IT

They are external navigations. The CSP never sees them, no unit test renders an
href it did not itself supply, and a plausible URL reads as correct until
somebody clicks it. The only check with power here is the one that asks the
internet, so tests/docs-links.spec.ts fetches every URL the console can produce
and asserts 200 — plus, for anchored links, that the id exists, because a wrong
anchor does not 404. It silently lands at the top of the page, which is the
failure mode that looks like success.

It runs under the contract config, with the gateway contract: both talk to
something outside this repo, and neither belongs in an e2e run that has to stay
answerable to the code in the pull request.

Verified the check fails on both shapes — a restored version prefix, and an
anchor changed to #policies — rather than trusting a green first run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
blakebauman and others added 2 commits August 15, 2026 07:17
Only dist/app.js conflicted, and build output is never hand-merged: the source
merged cleanly, so this is a rebuild of it.

Both sides survived and are independent. #11's attention banner and palette
live on Overview; this branch's change is which URL a DocsLink points at. The
one place they touch — overview.tsx — took both without either side losing
anything: the banner leads the page, the docs link still sits in the header
action, and it no longer carries a version prop that does not exist.

91 e2e tests and 8 docs-link checks pass on the merged tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The merge commit shipped a stale dist/app.js. Resolving the conflict, I ran
`git checkout --ours` on it after the rebuild, which put the pre-merge build
back over the correct one — so the committed bytes were missing everything #11
added.

Worse than the slip was the check: `git diff --quiet -- dist` compares the
working tree to the index, and both held the same stale file, so it reported
agreement. CI's check is `git diff --exit-code -- dist` *after* a build, which
is the only form that means anything, and it is what caught this.

Build output has no "ours" side. The resolution for a conflict in dist/ is
always to fix the source and rebuild.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@blakebauman
blakebauman merged commit aae1a87 into main Aug 15, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant