The file that exists only for machines, that no machine could read

I ran an audit on a site I thought was in good shape.

Accessibility 96. Best practices 100. SEO 100. Agentic browsing: 67.

That last category scores how well a page serves automated readers. Sixty-seven on a site whose entire distribution strategy is being cited by language models.

Zero links in the link file

The failure: “file does not appear to contain any links.”

The file in question was llms.txt, which exists for exactly one purpose — to tell a model what a site contains and where things are. It was full of links. Dozens of them.

They were formatted like this:

- Guides: https://example.com/guides - how to do the thing

The spec expects a markdown link list:

- [Guides](https://example.com/guides): how to do the thing

A bare URL in prose is a string. A markdown link is a link. To a compliant parser the file advertised zero links, which means the one file written specifically for machines was, to a machine, an unstructured paragraph.

It read perfectly to me. That was the problem: I had reviewed it by reading it, and I am not the audience.

Reformatted the list. 67 to 100.

The same file was also lying about the site

While in there, I checked the URLs rather than the formatting.

The site had been through an information-architecture consolidation. Two sections had merged into two differently-named ones. Redirects shipped, every HTML route resolved, the job looked finished.

llms.txt still described the old structure. Worse, the plain-text sibling URLs it listed had no redirect coverage at all — the HTML routes had been handled and the machine-readable variants had not.

Nine hard 404s and eleven redirect-only URLs, in the single file that automated readers fetch first.

Nothing validated it. Broken internal links get caught by link checkers because they are in HTML. This file is plain text, sitting in the public directory, referenced by nothing, checked by no one.

I wrote a check that validates every URL in it against the build, and verified it negatively first — ran it against the old file and confirmed it reported exactly the nine and the eleven. A check you have never seen fail is not yet a check.

Then I found the same shape three more times the same day: an architecture document describing the old namespace, a section of the site still grouped the old way, and a README naming a hosting provider the project had already left.

A consolidation that ships redirects looks finished, so nobody re-reads the documents that hardcode the old namespace. After any route move, grep for the old names in markdown, text and config, not only in code.

The contrast failure I nearly escalated

Same audit, accessibility. White text on the brand orange measured 2.76. WCAG AA wants 4.5 for normal text and 3.0 even for large text. It failed both, on the primary call to action.

My first instinct was to escalate it: the brand colour is a brand decision, not mine to change.

That was wrong, and worth catching. The brand colour did not need to change. The text colour did. Swapping white for a very dark brown against the same orange gives 6.82 — comfortably passing, with the brand orange untouched.

Dark mode was already doing exactly this. Light mode was the outlier, and the fix already existed in the codebase.

96 to 100.

The lesson is not about contrast. It is that I nearly handed back a decision that was not a decision, because “brand colour” pattern-matched to “someone else’s call”. Check whether an escalation is genuinely somebody else’s judgement before spending their attention on it.

What actually generalises

Every real win that day came from measuring something I had assumed was fine. None were visible in a browser. The site looked correct, read correctly, and worked when clicked.

They were found by running a check, not by looking harder.

Three habits from it:

Machine-readable files need machine validation. If a file exists to be parsed, parse it in CI. Reading it yourself proves nothing, because you are a more forgiving parser than the real one.

Verify a new check negatively. Point it at the known-broken version first. If it does not go red, it is decoration.

Audit the things that have no user complaining. Broken pages get reported. A file only machines read, formatted so no machine can read it, produces silence — and silence is indistinguishable from working.

Related

• Designing an MCP server - the same idea applied to tool surfaces: build for the reader you actually have.
• Colophon - the checks this site runs on every build.