Interaction Effects

Part of the Web Documentation Delivery Spec. The Checks Summary lists all checks with links to their definitions.

Individual checks measure discrete properties, but agent experience can degrade non-linearly when certain failures combine. A site might pass most checks individually while still being effectively inaccessible to agents because of how the failures interact. This section describes known interaction patterns that implementations should detect and surface. Implementations should evaluate these after all individual checks have completed.

Undiscoverable Markdown #

Checks involved: markdown-url-support, content-negotiation, llms-txt-directive-html, llms-txt-directive-md, llms-txt-links-markdown

Observed behavior: A site serves markdown at .md URLs, but agents have no way to discover this capability. Without content negotiation, a directive on pages pointing to llms.txt, or .md links in llms.txt, agents default to the HTML path and never benefit from the markdown support the site provides.

This matters because markdown availability is one of the highest-impact improvements a site can make, but only if agents can find it. A site in this state has done the hard work of generating markdown but gets none of the benefit.

Truncated Index #

Checks involved: llms-txt-exists, llms-txt-size

Observed behavior: A site provides llms.txt, but the file exceeds agent context limits. Agents see the first portion of the file and lose everything after the truncation point: links, structure, and entire sections become invisible. Quality assessments of the truncated portion (link resolution, coverage, markdown links) don’t reflect what agents actually experience.

Sites with large documentation sets are most likely to hit this. The spec’s progressive disclosure recommendation (splitting into a root index linking to section-level files) directly addresses this pattern.

Client-Rendered Pages #

Checks involved: rendering-strategy, page-size-html, content-start-position

Observed behavior: Pages that rely on client-side JavaScript rendering return an empty shell to agents instead of documentation content. When this affects a portion of a site’s pages, HTML-path measurements (page size, content start position) for those pages are measuring the shell, not the actual content. Results from those checks become unreliable for affected pages.

This does not mean the site is entirely inaccessible. If the site also serves markdown and agents can discover it, the markdown path still works. But agents on the HTML path receive no usable content from affected pages.

No Viable Content Path #

Checks involved: llms-txt-exists, rendering-strategy, markdown-url-support, plus the undiscoverable markdown pattern above

Observed behavior: Agents have no effective way to access the site’s documentation. There is no llms.txt for navigation, no discoverable markdown path, and HTML responses either don’t contain rendered content or weren’t tested. This is the lowest possible agent accessibility state.

This pattern represents a complete access failure rather than a degraded experience. The single highest-impact action is creating an llms.txt at the site root. If the site uses client-side rendering, enabling server-side rendering is the second priority.

Authenticated Docs Without Alternatives #

Checks involved: auth-gate-detection, auth-alternative-access

Observed behavior: The site’s documentation requires authentication, and no alternative access paths were detected. Agents that encounter the docs fall back on training data or seek secondary sources that may be inaccurate or outdated.

Authentication is a legitimate choice for many documentation sites. This pattern is notable because it means agents have no path to current content at all. Even partial alternatives (a public llms.txt as a navigational index, ungated API references, docs shipped with the SDK/package) significantly improve the agent experience compared to a complete access barrier.

Bot Protection Degrading Scan Reliability #

Checks involved: bot-protection-interference, plus every multi-page check

Observed behavior: Behavioral bot enforcement engages partway through a scan. Requests that would have succeeded in isolation begin to stall, get challenged, or fail, and every check still running is now scoring whatever sample survives. The site’s scores can look reasonable while being computed from a fraction of the intended pages.

This pattern has two victims. Agents doing multi-page reading sessions lose access mid-session, which is the site-side problem the check exists to surface. And the assessment itself degrades: per-check “failed to fetch” counts are scattered and easy to miss, so implementations should aggregate fetch failures at run level and flag results prominently when the failure rate is high (for example, above 20% of page fetches). A flagged run is still useful evidence; it just measures a smaller sample than it appears to.

Oversized Pages Without Markdown Escape #

Checks involved: page-size-html, markdown-url-support, plus the undiscoverable markdown pattern above

Observed behavior: Pages exceed agent context limits on the HTML path, and there is no discoverable markdown path for agents to get smaller representations. Agents receive truncated content on these pages with no warning and no alternative available.

When pages are large but markdown is available and discoverable, agents that support content negotiation or follow llms.txt directives can access smaller representations. Without that escape hatch, truncation is unavoidable.

Dynamic Content Rendered Statically #

Checks involved: markdown-content-parity, single-fetch-completeness, markdown-link-portability, embedded-data-serialization, plus the Category 3 size checks

Observed behavior: A page whose content is dynamic (a filterable catalog, a data-driven matrix, a widget-rendered listing) is flattened into static markdown for agents, and the flattening fails in several ways at once. There are four characteristic failure directions: too much (widget data dumped wholesale into the content), too little (UI pagination inherited into a format that didn’t need it), inconsistent (default filters or staleness making representations disagree), and unnavigable (generated links that assume a browser context, or that are broken wholesale by the generation pipeline).

One observed production catalog page exhibited all four simultaneously: the HTML showed 98 items under a default filter while the markdown listed 102, the markdown was paginated with a trailing note and a continuation URL that returned an empty body, and every entry link pointed into a wrong generated path prefix that soft-404ed. Each individual check would flag one symptom; the underlying cause is shared. The markdown variant is a second rendering pipeline, and it needs the same QA the HTML pipeline gets. Implementations that detect several of these failures on the same generated page should present them as one pipeline problem rather than four independent findings.