Test your documentation site against the Agent-Friendly Documentation Spec.

Agents don't use docs like humans. They hit truncation limits, get walls of CSS instead of content, can't follow cross-host redirects, and don't know about quality-of-life improvements like llms.txt or .md docs pages that would make life swell. Maybe this is because the industry has lacked guidance - until now.

afdocs runs 22 checks across 8 categories to evaluate how well your docs serve agent consumers.

Status: Early development (0.x) This project is under active development. Check IDs, CLI flags, and output formats may change between minor versions. Feel free to try it out, but don't build automation against specific output until 1.0.

Implements spec v0.2.1 (2026-03-15).

Quick start

npx afdocs check https://docs.example.com

Example output:

Agent-Friendly Docs Check: https://react.dev

llms-txt
  ✓ llms-txt-exists: llms.txt found at 1 location(s)
  ✓ llms-txt-valid: llms.txt follows the proposed structure
  ✓ llms-txt-size: llms.txt is 14,347 characters (under 50,000 threshold)
  ✓ llms-txt-links-resolve: All 50 tested links resolve (177 total links)
  ✓ llms-txt-links-markdown: 50/50 links point to markdown content (100%)

Markdown Availability
  ✗ content-negotiation: Server ignores Accept: text/markdown header (0/50 sampled pages return markdown)
  ✗ markdown-url-support: No sampled pages support .md URLs (0/50 tested)

URL Stability
  ✓ http-status-codes: All 50 sampled pages return proper error codes for bad URLs

Authentication
  ✓ auth-gate-detection: All 50 sampled pages are publicly accessible

Summary
  9 passed, 3 failed, 10 skipped (22 total)

Install

CLI usage

# Run all checks
afdocs check https://docs.example.com

# Run specific checks
afdocs check https://docs.example.com --checks llms-txt-exists,llms-txt-valid,llms-txt-size

# JSON output
afdocs check https://docs.example.com --format json

# Adjust thresholds
afdocs check https://docs.example.com --pass-threshold 30000 --fail-threshold 80000

Options

Sampling strategies

By default, afdocs discovers pages from your site (via llms.txt, sitemap, or both) and randomly samples up to --max-links pages to check. The --sampling flag gives you control over how that sample is selected.

# Reproducible runs for CI or iteration (same pages every time)
afdocs check https://docs.example.com --sampling deterministic

# Check a single page without any discovery
afdocs check https://docs.example.com/api/auth --sampling none

# Check a single page with specific checks
afdocs check https://docs.example.com/api/auth --sampling none --checks page-size-html,redirect-behavior

Exit codes

• 0 if all checks pass or warn
• 1 if any check fails

Programmatic API

import { runChecks, createContext, getCheck } from 'afdocs';

// Run all checks
const report = await runChecks('https://docs.example.com');

// Run a single check
const ctx = createContext('https://docs.example.com');
const check = getCheck('llms-txt-exists')!;
const result = await check.run(ctx);

Test helpers

afdocs includes vitest helpers so you can add agent-friendliness checks to your docs site's test suite.

Config-driven

Create agent-docs.config.yml:

url: https://docs.example.com
checks:
  - llms-txt-exists
  - llms-txt-valid
  - llms-txt-size

Then in your test file:

import { describeAgentDocs } from 'afdocs/helpers';

describeAgentDocs();

This reads the config and generates one test assertion covering all specified checks.

Direct imports

import { createContext, getCheck } from 'afdocs';
import { describe, it, expect } from 'vitest';

describe('agent-friendliness', () => {
  it('has a valid llms.txt', async () => {
    const ctx = createContext('https://docs.example.com');
    const check = getCheck('llms-txt-exists')!;
    const result = await check.run(ctx);
    expect(result.status).toBe('pass');
  });
});

Checks

22 checks across 8 categories.

Category 1: llms.txt

Category 2: Markdown Availability

Category 3: Page Size and Truncation Risk

Category 4: Content Structure

Category 5: URL Stability and Redirects

Category 6: Agent Discoverability Directives

Category 7: Observability and Content Health

Category 8: Authentication and Access

Check dependencies

Some checks depend on others. If a dependency doesn't pass, the dependent check is skipped automatically.

• llms-txt-valid, llms-txt-size, llms-txt-links-resolve, llms-txt-links-markdown require llms-txt-exists
• page-size-markdown requires markdown-url-support or content-negotiation
• section-header-quality requires tabbed-content-serialization
• markdown-code-fence-validity requires markdown-url-support or content-negotiation
• llms-txt-freshness requires llms-txt-exists
• markdown-content-parity requires markdown-url-support or content-negotiation
• auth-alternative-access requires auth-gate-detection (warn or fail)

Responsible use

afdocs makes HTTP requests to the sites it checks. It enforces delays between requests (200ms default), caps concurrent connections, and honors Retry-After headers. The goal is to help documentation teams improve agent accessibility, not to load-test their infrastructure.

License

MIT