afdocs

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 21 checks across 8 categories to evaluate how well your docs serve agent consumers. 16 are fully implemented; the rest return skip until completed.

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.1.0 (2026-02-22).

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, 9 skipped (21 total)

Install

npm install afdocs

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

| Option | Default | Description | | ----------------------- | -------- | -------------------------------------------- | | --format <format> | text | Output format: text or json | | -v, --verbose | | Show per-page details for checks with issues | | --checks <ids> | all | Comma-separated list of check IDs | | --max-concurrency <n> | 3 | Maximum concurrent HTTP requests | | --request-delay <ms> | 200 | Delay between requests | | --max-links <n> | 50 | Maximum links to test in link checks | | --pass-threshold <n> | 50000 | Size pass threshold (characters) | | --fail-threshold <n> | 100000 | Size fail threshold (characters) |

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

21 checks across 8 categories. Checks marked with * are not yet implemented and return skip.

Category 1: llms.txt

| Check | Description | | ------------------------- | --------------------------------------------------------- | | llms-txt-exists | Whether llms.txt is discoverable at candidate locations | | llms-txt-valid | Whether llms.txt follows the llmstxt.org structure | | llms-txt-size | Whether llms.txt fits within agent truncation limits | | llms-txt-links-resolve | Whether URLs in llms.txt return 200 | | llms-txt-links-markdown | Whether URLs in llms.txt point to markdown content |

Category 2: Markdown Availability

| Check | Description | | ---------------------- | ------------------------------------------------- | | markdown-url-support | Whether .md URL variants return markdown | | content-negotiation | Whether the server honors Accept: text/markdown |

Category 3: Page Size and Truncation Risk

| Check | Description | | ------------------------ | ------------------------------------------------ | | page-size-markdown | Character count when served as markdown | | page-size-html | Character count of HTML and post-conversion size | | content-start-position | How far into the response actual content begins |

Category 4: Content Structure

| Check | Description | | --------------------------------- | -------------------------------------------------- | | tabbed-content-serialization * | Whether tabbed content creates oversized output | | section-header-quality * | Whether headers in tabbed sections include context | | markdown-code-fence-validity | Whether markdown has unclosed code fences |

Category 5: URL Stability and Redirects

| Check | Description | | ------------------- | ----------------------------------------------- | | http-status-codes | Whether error pages return correct status codes | | redirect-behavior | Whether redirects are same-host HTTP redirects |

Category 6: Agent Discoverability Directives

| Check | Description | | -------------------- | -------------------------------------------------------- | | llms-txt-directive | Whether pages include a directive pointing to llms.txt |

Category 7: Observability and Content Health

| Check | Description | | ---------------------------- | ---------------------------------------------- | | llms-txt-freshness * | Whether llms.txt reflects current site state | | markdown-content-parity * | Whether markdown and HTML versions match | | cache-header-hygiene | Whether cache headers allow timely updates |

Category 8: Authentication and Access

| Check | Description | | ---------------------------- | -------------------------------------------------------------------- | | auth-gate-detection | Whether documentation pages require authentication to access content | | auth-alternative-access * | Whether auth-gated sites provide alternative access paths for agents |

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