Making a Surface Agent-Legible

The list is short and boring, which is the good news

Agent legibility is whether a machine reading your surface can recover its structure, claims, and boundaries as well as a human reader can. It is the second of the four dimensions of agent readiness — discoverability, legibility, trust, callability — and it is the one with the most settled answer.

Independent efforts converged on close to the same list, which is usually a sign the list is right:

• An index that survives a single request. One small file an agent can fetch first to learn what exists, with a route back to it from every page. Small matters: an index that inlines every page becomes something an agent truncates rather than reads.
• Markdown parity. A plain rendering of each page that says what the HTML says. Not a summary, not a subset — the same content without the layout.
• Links that resolve from anywhere. An agent may arrive at any page from any direction. Relative links that only work from one entry point are dead ends it cannot recover from.
• Metadata at the paths agents check. Structured data where the conventions say to put it, so meaning does not have to be inferred from prose.

None of this requires rebuilding a site. Most of it is emitting a second representation of what you already publish.

What each item actually buys

The list is easy to implement and easy to implement without understanding, which produces surfaces that pass a checker and still fail an agent.

The index buys orientation. Without it, an agent's first move is a guess. With it, the first request returns a map. The failure mode is an index so complete it stops being an index.

Markdown parity buys token economy and fidelity at once. An agent fetching a modern HTML page spends most of its budget on layout scaffolding, then reconstructs your content from what survives. Parity removes the reconstruction step — and with it the reconstruction errors, which are invisible to you because they happen after the response leaves your server.

Resolvable links buy traversal. An agent that cannot follow a reference treats the referenced thing as absent. Your carefully linked cluster becomes a set of unrelated pages.

Metadata buys unambiguous meaning. Prose is inferable; structure is readable. The distinction matters most for the things you would least like guessed — what an entity is, what a page is for, what a claim's scope is.

Where the list stops

Every item above concerns access: can the agent get the bytes, and can it turn the bytes into structure. That is genuinely the hard part of the first two dimensions, and a surface that fails it will not be acted on correctly no matter how true its contents are.

But notice what none of the items touch. A fully legible surface has told an agent exactly what it claims. It has given the agent nothing with which to evaluate the claim. Legibility and warrant are different properties, and only one of them is on the list — which is the subject of agent readability is not agent trust.

The practical consequence: treat the legibility list as necessary and completed, not as the whole of readiness. A surface that stops here is readable and unverifiable, which is a better position than illegible and unverifiable, and not the same as ready.

Where this sits

Agent legibility is one dimension of agent readiness, which is the precondition for the Verse's larger concern: AI acting under human authority with legibility, bounded delegation, reviewable memory, and inspectable action. Legibility is where that chain starts. It is not where it ends.