One source, two documentation surfaces

A documentation build can succeed while dropping the sentence that matters most.

Imagine a human-facing page that says, “Never cache authenticated responses.” Its agent-facing Markdown mirror keeps the title, configuration key, and recovery link—but loses the warning. Both pages exist. Both look structurally complete. A route check, heading comparison, or successful build can still pass. The two surfaces are not semantically equivalent.

Treat human and agent documentation as deliberately different projections of one reviewed source. The goal is not identical markup. It is preservation of the claims, constraints, literals, and destinations that readers need to act safely.

This is a hand-authored method, not a product evaluation. Blume or another documentation generator was not installed or run. No page was generated, no agent consumed an llms.txt file, and no accessibility, comprehension, or production result is claimed.

Declare claims before comparing outputs

Start with a small claim ledger. Give each required meaning a stable ID and state what may differ between surfaces.

The claim IDs are review handles, not text that must be shown to readers. They make omissions discussable without pretending a script understands natural-language equivalence.

Walk through a fictional projection

The invented package in this example is Northstar Cache. Its reviewed source says it caches public catalog responses for five minutes, configures that duration with cache.publicTtlSeconds, never caches authenticated responses, links to /operations/cache-bypass/, and does not perform write-through caching.

A human projection might use navigation, heading hierarchy, a colored warning callout, a formatted configuration block, and a “Bypass the cache” link. An agent projection might be plain Markdown with the warning as ordinary prose and the same configuration literal and link target. Those presentation differences are allowed because the declared meanings survive.

Now remove CACHE-01 from the agent projection. The title, headings, code literal, and recovery URL still match. A structural comparison reports success, but the parity ledger reports a missing required claim. That is the useful failure: semantic review catches what shape comparison cannot.

This example was deliberately written, not generated or evaluated. “Missing” is the stipulated teaching result of the illustration, not output from a parser, model, documentation tool, or agent.

Review parity in six passes

1. Inventory the surfaces. Name the reviewed source revision, human URL, agent-readable URL, and any index that points to them.
2. Declare required claims. Include warnings, scope limits, configuration literals, link targets, version qualifications, and recovery paths—not only headings.
3. State allowed differences. Navigation, decoration, link labels, and whitespace may differ when the ledger explicitly permits it.
4. Compare each claim. Record present, missing, contradictory, or not reviewed for both surfaces. Do not turn a blank cell into a pass.
5. Inspect discoverability separately. Confirm that intended links exist, but do not confuse discoverability with semantic parity or access control.
6. Require human judgment. A mechanical check can find exact literals and URLs. A qualified reviewer must decide whether changed prose preserves meaning.

Download the blank documentation parity worksheet. Its default state is Not reviewed; it contains no approval or evidence that either surface exists.

Keep discovery claims narrow

The /llms.txt project describes itself as a proposal. Its current text proposes a curated Markdown index, Markdown counterparts for pages, and link relations such as rel="alternate" for a page’s Markdown version and rel="describedby" for the covering index. These mechanisms can make a surface discoverable. They do not grant permission, replace authentication, prove that an agent fetched the page, or establish that an agent understood it.

The Blume repository currently describes Markdown/MDX input, static HTML output, raw Markdown page mirrors, and generated llms.txt/llms-full.txt surfaces. Those are attributed project capabilities only. This article does not claim the capabilities were reproduced or that Blume is required for the method.

Parity is also not accessibility conformance. A human page may need semantic structure, keyboard behavior, contrast, alternative text, and other review that a claim ledger does not test. An agent-readable page may require its own formatting and size constraints. One reviewed source can support both surfaces without making either automatically correct.

Primary sources:

• Blume official repository
• /llms.txt proposal
• /llms.txt v2 changes

The claim-ledger method, Northstar Cache example, six-pass review, and blank worksheet are original. The linked sources support only the attributed discovery and project-capability statements.