Repository navigation
docs: link to pages that exist - #10
Merged
Merged
Conversation
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>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every documentation link this console emitted was a 404.
They carried a version segment —
docs.fold.run/1.10/configuration/— on thereasoning 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,policyandobservabilityfrom the console's own section namesrather than reading the docs.
Verified against the live site this time, rather than assumed:
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/#policyrather than thetop of a reference that opens on
upstreams. Anchors are checked againstidattributes on the live pages.
federationbecomesupstreams, pointing at theblock an operator on that page is actually asking about.
The version parameter is gone, and
minorLinewith it — it existed only tobuild 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.tsfetches every URL the console can produce andasserts 200. For anchored links it also asserts the
idexists — a wronganchor 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:81 tests pass, 4 skip without a gateway. 244,365 bytes.
🤖 Generated with Claude Code