Agent Ready HTML

How to test readability in CI

In short

Turn the four plain requests into a script that fails the build: the page returns 200 with an H1, a missing path returns 404, a markdown request returns text/markdown, and llms.txt parses. Docs sites can add AFDocs or the is-agentic command. This site runs its own checks on every build.

A readability regression is easy to ship: a client-side rewrite, a catch-all rewrite, a removed footer link. A build step catches it before an agent does.

What the evidence says

  • AFDocs runs 28 checks in 7 categories and ships a vitest helper for CI. [primary source] source, read 4 November 2026.
  • is-agentic exposes reports through npx is-agentic <domain> and a GET API at /api/v1/report. [primary source] source, read 4 November 2026.
  • Lighthouse flags a server error on /llms.txt and marks a 404 as not applicable. [primary source] source, read 4 November 2026.
  • ReadMe scores a sample of published pages against the Agent-Friendly Docs spec in its dashboard. [primary source] source, read 4 November 2026.
  • A curl with Accept: text/markdown should return Content-Type text/markdown; anything else means no negotiation. [primary source] source, read 4 November 2026.
  • Ora's Access layer runs 42 checks worth 30 points. [vendor claim] source, read 4 November 2026.

Steps

  1. Run the build and serve the output locally, or point the script at a preview URL.
  2. Assert the status codes and content types with curl, as in the script below.
  3. Read the first line of llms.txt and fail if it is not an H1.
  4. For documentation, add a scanner that already encodes the checks: AFDocs ships a vitest helper, and is-agentic exposes npx is-agentic with a report API.
  5. Fail the pipeline on any assertion, and keep the assertions in the repository next to the content.

A shell test that exits non-zero on failure

set -eu
URL=${1:-https://example.com}
test "$(curl -s -o /dev/null -w '%{http_code}' "$URL/agent-ready-html-missing-path-check")" = 404
curl -sL "$URL/" | grep -qi '<h1'
curl -sI -H 'Accept: text/markdown' "$URL/" | grep -qi '^content-type: text/markdown'
curl -s "$URL/llms.txt" | head -1 | grep -q '^# '
echo ok

Check the result

This site runs fixture tests on the viewer flags and the llms.txt grader, then verify and gate scripts over the built pages, and fails the build if any fails. Open the viewer to run it on your own URL.

Related: all guides, initial HTML, llms.txt, checking the initial HTML like an agent.

Sources

  1. AFDocs: Agent-Friendly Documentation spec https://afdocs.dev/, read 4 November 2026
  2. Vercel and Ora: Make your site readable by AI agents https://vercel.com/kb/guide/make-your-site-readable-by-ai-agents, read 4 November 2026
  3. Chrome Lighthouse: llms.txt audit https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt, read 4 November 2026
  4. ReadMe docs: AI Discoverability https://docs.readme.com/main/docs/ai-discoverability, read 4 November 2026
  5. Ora methodology https://ora.ai/methodology, read 4 November 2026

Last reviewed 4 November 2026