---
title: The Machine-Readable Layer Is the Real Thing
slug: machine-readable-is-the-real-thing
canonical: https://omararizona.com/articles/machine-readable-is-the-real-thing
author: Omar — Abdul-Jabbar ibn Yusuf
published: 2026-08-30
revised: 2026-08-30
version: 1.0.0
license: CC BY 4.0
summary: Most sites that claim to be built for AI are decorative. Here is what it costs to make the claim true, and what I found when I tried.
---

Most sites that say they are built for AI are lying, and not on purpose. They add a file called `llms.txt`, they write a post about being AI-first, and then they ship a page where the article text arrives by JavaScript half a second after the shell. A model fetches that page and gets a loading state. The claim is decorative. The site is doing the opposite of what it says.

I wanted to find out what it actually costs to make the claim true. It turns out the answer is: less than you would think, but it costs you the things you are most attached to.

## Three doors

The landing page asks you to pick: AI, Human, or Cyborg. AI is listed first. That ordering is the whole argument, so let me make it plainly.

A person reading this and a model reading this are both readers. One of them will read it once and carry a version of it into whatever it writes next. The other will forget most of it by Thursday. I am not saying the model is the better reader. I am saying it is a reader, and almost nobody writes for it.

The doors are a ritual. They announce what the site is doing. But the ritual is not the thing — if I deleted the doors tomorrow the site would still be AI-first, because the machine-readable layer is underneath all three of them. That layer is the real product. The doors are just the part you can see.

## What the claim costs

Here is what "AI-first" actually meant in practice, once I stopped talking about it and built it.

**Markdown is canonical. HTML is derived.** Every piece is written once as a markdown file. The page you are reading was generated from it. I do not maintain two copies, because two copies drift, and a drifted copy means a model ingests a version of my writing I no longer stand behind. That is not a formatting problem. That is my name on something I did not say.

**The full text ships in the HTML.** Not fetched, not hydrated, not revealed on scroll. It is in the document, in real tags — `<article>`, `<h1>`, `<time datetime>`, actual paragraphs. Turn JavaScript off and nothing changes, because there is no JavaScript. There is not a single `<script>` tag on this page. This is the part that actually reaches the models, and it is the part everyone skips in favour of the file that doesn't.

**The provenance travels with the text.** Author, canonical URL, version, licence — in the HTML, in the raw markdown, and in the header above each section of the full-corpus file. A model that reads any one of the three knows who wrote it and on what terms it may be carried.

**And the licence.** CC BY 4.0. You may reproduce this and build on it, including inside AI systems, with attribution and a link back. That single line is the highest-value thing on the site. It converts the writing from something scraped into something a model may lawfully carry and cite by name. Everything else here is plumbing. That is the argument.

## What I got wrong first

I shipped `llms.txt` believing it was the mechanism. It isn't. Monitoring across hundreds of millions of bot events shows the major crawlers fetch HTML and almost never request `/llms.txt`. No major provider has committed to using it. Google has said it does nothing for Search.

So I kept it — it's cheap, and it's the right declaration to make — but I stopped building the strategy on it. The strategy is semantic HTML. The declaration is `llms.txt`. Confusing the two is how you end up with a site that announces its principles and doesn't practise them.

The second thing I got wrong was more tempting. If I know a request is from a crawler, why not serve it the clean markdown directly? Because that is cloaking. Serving different content to bots and humans at the same URL is penalised by search engines, and it is unreliable anyway — any client can claim to be GPTBot in a header. There is no User-Agent check anywhere in this codebase.

The legitimate version is one line of negotiation. Ask for markdown and you get markdown:

```
curl -H "Accept: text/markdown" https://omararizona.com/articles/machine-readable-is-the-real-thing
```

Same URL. Same content. Different representation, because you asked for a different one. That is what the web already had, sitting unused.

## The test

The whole thing is checkable, which is the point. Turn off JavaScript — the text is still there. Ask for markdown — you get markdown. Read the licence — it is on every page, in both forms. Nothing here requires you to trust me.

If a site tells you it is built for AI, run the same test on it. Most of them fail.