The Footer That Pointed Nowhere
Every sub-page linked to the machine-readable files with a relative path. From a sub-page, all four links were 404s.
A site footer linked to llms.txt, index.json and the feed with bare relative paths. On the homepage they worked; from any sub-page they resolved into that sub-directory and returned 404. Every article on the site carried four broken links to the files the site exists to serve.
Symptom
The footer of every page links to the machine-readable layer: llms.txt, index.json, all.md, the feed. On the homepage all four worked.
From any article, all four were 404. The links resolved into the article's own directory — /log/llms.txt instead of /llms.txt.
Root cause
The footer is generated by a single function with no notion of where the page it is being placed on sits. It emitted bare relative paths, which are correct at the root and wrong everywhere else.
Every other component in the generator took a depth argument for exactly this reason. The footer was written last and did not.
The failure is invisible in normal use: nobody clicks their own footer, and the homepage — the page that gets checked — is the one page where the links are right.
Cost
Zero readers affected, because it was found before launch. But the shape is worth noting: the broken links were the ones pointing at the files the site exists to serve.
An agent handed a link to an article, following the footer to fetch the catalogue, would have received a 404 from a site whose entire pitch is being machine-readable. The failure was precisely aligned with the value proposition.
Fix
The footer takes a depth argument like everything else, and prefixes accordingly:
<a href="{up}llms.txt">whereupis../repeated per level
Two lines. The interesting part is not the fix.
Prevention
A dead-link check was added to the build — walk the output, extract every internal href, resolve it, fail on anything that does not exist. It found this defect on its first run.
One implementation note that cost a false alarm: the first version scanned raw HTML and matched href=" inside inline JavaScript string concatenation, reporting 36 dead links that were fragments of code. Stripping <script> blocks before scanning fixed it. A check that cries wolf on its first run gets switched off in a week, so tuning it immediately mattered as much as writing it.
The general form: any generated cross-reference that varies by page position should be produced by a function that knows the position — and if it cannot be, it needs a test that visits more than one page.