From 2479d2522fc25e348dbbdf6ed9b3c1d55162bd31 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Sun, 13 Sep 2026 17:37:30 -0400 Subject: [PATCH] Update spec URLs for the /spec/web/ restructure The Agent-Friendly Documentation Spec site now serves the spec as per-category pages under /spec/web/ (agent-docs-spec#33). Check definitions live at /spec/web//#; category ids in this codebase already match the site's page slugs, so specCheckUrl() derives the page from the result's category. Co-Authored-By: Claude Fable 5 --- README.md | 4 +- SCORING.md | 74 +++++++++++++------------- docs/checks/authentication.md | 22 ++++---- docs/checks/content-discoverability.md | 66 +++++++++++------------ docs/checks/content-structure.md | 28 +++++----- docs/checks/index.md | 2 +- docs/checks/markdown-availability.md | 16 +++--- docs/checks/observability.md | 30 +++++------ docs/checks/page-size.md | 34 ++++++------ docs/checks/url-stability.md | 16 +++--- src/cli/formatters/text.ts | 4 +- src/constants.ts | 12 ++++- test/unit/scoring/diagnostics.test.ts | 2 +- test/unit/scoring/score.test.ts | 2 +- test/unit/scoring/tag-scores.test.ts | 2 +- 15 files changed, 161 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 16402c6..8ebf3b2 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ npm

-Test your documentation site against the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). AFDocs runs 23 checks across 7 categories to measure how well AI coding agents can discover, navigate, and consume your docs. +Test your documentation site against the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). AFDocs runs checks across 7 categories to measure how well AI coding agents can discover, navigate, and consume your docs. Powering [Agent Score](https://buildwithfern.com/agent-score) by Fern. > **Status: Early development (0.x)** > Check IDs, CLI flags, and output formats may change between minor versions. -> Implements [spec v0.5.0](https://agentdocsspec.com/spec) (2026-04-25). +> Implements [spec v0.6.0](https://agentdocsspec.com/spec/web/) (2026-08-24). The `bot-protection-interference` check is not yet scored; stalled responses currently surface as body-timeout fetch errors, with the run-level diagnostic tracked in [#104](https://github.com/agent-ecosystem/afdocs/issues/104). ## Quick start diff --git a/SCORING.md b/SCORING.md index cce8354..d4a179f 100644 --- a/SCORING.md +++ b/SCORING.md @@ -34,73 +34,73 @@ The 23 checks are grouped into seven categories. Each check is assigned a **weig How agents find and navigate your documentation. -| Check | Weight | What it measures | -| ---------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ | -| [llms-txt-exists](https://agentdocsspec.com/spec/#llms-txt-exists) | Critical (10) | Whether your site has an llms.txt file. The primary navigation mechanism for agents. | -| [llms-txt-valid](https://agentdocsspec.com/spec/#llms-txt-valid) | Medium (4) | Whether your llms.txt follows standard structure so agents can parse it reliably. | -| [llms-txt-size](https://agentdocsspec.com/spec/#llms-txt-size) | High (7) | Whether your llms.txt fits within agent context windows. Truncated indexes defeat their purpose. | -| [llms-txt-links-resolve](https://agentdocsspec.com/spec/#llms-txt-links-resolve) | High (7) | Whether links in your llms.txt actually work. Broken links send agents down dead ends with high confidence. | -| [llms-txt-links-markdown](https://agentdocsspec.com/spec/#llms-txt-links-markdown) | High (7) | Whether llms.txt links point to markdown rather than HTML. Agents work significantly less effectively with HTML content. | -| [llms-txt-directive-html](https://agentdocsspec.com/spec/#llms-txt-directive-html) | High (7) | Whether your HTML pages tell agents where to find llms.txt. Without this, agents won't know it exists. | -| [llms-txt-directive-md](https://agentdocsspec.com/spec/#llms-txt-directive-md) | Medium (4) | Whether your markdown pages tell agents where to find llms.txt. | +| Check | Weight | What it measures | +| -------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ | +| [llms-txt-exists](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-exists) | Critical (10) | Whether your site has an llms.txt file. The primary navigation mechanism for agents. | +| [llms-txt-valid](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-valid) | Medium (4) | Whether your llms.txt follows standard structure so agents can parse it reliably. | +| [llms-txt-size](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-size) | High (7) | Whether your llms.txt fits within agent context windows. Truncated indexes defeat their purpose. | +| [llms-txt-links-resolve](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-links-resolve) | High (7) | Whether links in your llms.txt actually work. Broken links send agents down dead ends with high confidence. | +| [llms-txt-links-markdown](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-links-markdown) | High (7) | Whether llms.txt links point to markdown rather than HTML. Agents work significantly less effectively with HTML content. | +| [llms-txt-directive-html](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-directive-html) | High (7) | Whether your HTML pages tell agents where to find llms.txt. Without this, agents won't know it exists. | +| [llms-txt-directive-md](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-directive-md) | Medium (4) | Whether your markdown pages tell agents where to find llms.txt. | ### Markdown Availability Whether agents can get documentation in their preferred format. -| Check | Weight | What it measures | -| ---------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| [markdown-url-support](https://agentdocsspec.com/spec/#markdown-url-support) | High (7) | Whether appending .md to a URL returns markdown. This is the core format capability agents look for. | -| [content-negotiation](https://agentdocsspec.com/spec/#content-negotiation) | Medium (4) | Whether your server returns markdown when agents request it via `Accept: text/markdown`. | +| Check | Weight | What it measures | +| ------------------------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | +| [markdown-url-support](https://agentdocsspec.com/spec/web/markdown-availability/#markdown-url-support) | High (7) | Whether appending .md to a URL returns markdown. This is the core format capability agents look for. | +| [content-negotiation](https://agentdocsspec.com/spec/web/markdown-availability/#content-negotiation) | Medium (4) | Whether your server returns markdown when agents request it via `Accept: text/markdown`. | ### Page Size and Truncation Risk Whether agents can process your pages without losing content. -| Check | Weight | What it measures | -| -------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- | -| [rendering-strategy](https://agentdocsspec.com/spec/#rendering-strategy) | Critical (10) | Whether pages are fully server-rendered, server-rendered but sparse, or empty SPA shells. | -| [page-size-markdown](https://agentdocsspec.com/spec/#page-size-markdown) | High (7) | Whether markdown pages fit within agent processing limits (~100K characters). | -| [page-size-html](https://agentdocsspec.com/spec/#page-size-html) | High (7) | Whether HTML pages, once converted to text, fit within agent processing limits. | -| [content-start-position](https://agentdocsspec.com/spec/#content-start-position) | Medium (4) | Whether documentation content starts near the top of the page, or is buried under boilerplate CSS/JS. | +| Check | Weight | What it measures | +| ---------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- | +| [rendering-strategy](https://agentdocsspec.com/spec/web/page-size/#rendering-strategy) | Critical (10) | Whether pages are fully server-rendered, server-rendered but sparse, or empty SPA shells. | +| [page-size-markdown](https://agentdocsspec.com/spec/web/page-size/#page-size-markdown) | High (7) | Whether markdown pages fit within agent processing limits (~100K characters). | +| [page-size-html](https://agentdocsspec.com/spec/web/page-size/#page-size-html) | High (7) | Whether HTML pages, once converted to text, fit within agent processing limits. | +| [content-start-position](https://agentdocsspec.com/spec/web/page-size/#content-start-position) | Medium (4) | Whether documentation content starts near the top of the page, or is buried under boilerplate CSS/JS. | ### Content Structure Whether page content is structured in ways agents can consume. -| Check | Weight | What it measures | -| -------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | -| [tabbed-content-serialization](https://agentdocsspec.com/spec/#tabbed-content-serialization) | Medium (4) | Whether tabbed UI components serialize to a reasonable size. Tabs can multiply page size dramatically. | -| [section-header-quality](https://agentdocsspec.com/spec/#section-header-quality) | Low (2) | Whether headers in tabbed sections include variant context (e.g., "Step 1 (Python)" vs. just "Step 1"). | -| [markdown-code-fence-validity](https://agentdocsspec.com/spec/#markdown-code-fence-validity) | Medium (4) | Whether code fences are properly closed. An unclosed fence corrupts all content after the break point. | +| Check | Weight | What it measures | +| ------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- | +| [tabbed-content-serialization](https://agentdocsspec.com/spec/web/content-structure/#tabbed-content-serialization) | Medium (4) | Whether tabbed UI components serialize to a reasonable size. Tabs can multiply page size dramatically. | +| [section-header-quality](https://agentdocsspec.com/spec/web/content-structure/#section-header-quality) | Low (2) | Whether headers in tabbed sections include variant context (e.g., "Step 1 (Python)" vs. just "Step 1"). | +| [markdown-code-fence-validity](https://agentdocsspec.com/spec/web/content-structure/#markdown-code-fence-validity) | Medium (4) | Whether code fences are properly closed. An unclosed fence corrupts all content after the break point. | ### URL Stability and Redirects Whether documentation URLs behave predictably for agents. -| Check | Weight | What it measures | -| ---------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | -| [http-status-codes](https://agentdocsspec.com/spec/#http-status-codes) | High (7) | Whether missing pages return 404. Soft 404s (returning 200 with error content) actively mislead agents. | -| [redirect-behavior](https://agentdocsspec.com/spec/#redirect-behavior) | Medium (4) | Whether redirects use standard HTTP methods. Cross-host and JavaScript redirects break many agents. | +| Check | Weight | What it measures | +| ---------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | +| [http-status-codes](https://agentdocsspec.com/spec/web/url-stability/#http-status-codes) | High (7) | Whether missing pages return 404. Soft 404s (returning 200 with error content) actively mislead agents. | +| [redirect-behavior](https://agentdocsspec.com/spec/web/url-stability/#redirect-behavior) | Medium (4) | Whether redirects use standard HTTP methods. Cross-host and JavaScript redirects break many agents. | ### Observability and Content Health Whether agent-facing resources stay accurate over time. -| Check | Weight | What it measures | -| ---------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | -| [llms-txt-coverage](https://agentdocsspec.com/spec/#llms-txt-coverage) | Medium (4) | Whether your llms.txt reflects your current site. A stale index sends agents to outdated or missing pages. | -| [markdown-content-parity](https://agentdocsspec.com/spec/#markdown-content-parity) | Medium (4) | Whether markdown and HTML versions of pages contain the same content. | -| [cache-header-hygiene](https://agentdocsspec.com/spec/#cache-header-hygiene) | Low (2) | Whether cache lifetimes allow content updates to reach agents in a reasonable timeframe. | +| Check | Weight | What it measures | +| ---------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | +| [llms-txt-coverage](https://agentdocsspec.com/spec/web/observability/#llms-txt-coverage) | Medium (4) | Whether your llms.txt reflects your current site. A stale index sends agents to outdated or missing pages. | +| [markdown-content-parity](https://agentdocsspec.com/spec/web/observability/#markdown-content-parity) | Medium (4) | Whether markdown and HTML versions of pages contain the same content. | +| [cache-header-hygiene](https://agentdocsspec.com/spec/web/observability/#cache-header-hygiene) | Low (2) | Whether cache lifetimes allow content updates to reach agents in a reasonable timeframe. | ### Authentication and Access Whether agents can reach your documentation at all. -| Check | Weight | What it measures | -| ---------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------- | -| [auth-gate-detection](https://agentdocsspec.com/spec/#auth-gate-detection) | Critical (10) | Whether documentation requires authentication. Auth-gated docs are invisible to agents. | -| [auth-alternative-access](https://agentdocsspec.com/spec/#auth-alternative-access) | Medium (4) | Whether auth-gated sites provide alternative access paths (public llms.txt, SDK-bundled docs, etc.). | +| Check | Weight | What it measures | +| ----------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------- | +| [auth-gate-detection](https://agentdocsspec.com/spec/web/authentication/#auth-gate-detection) | Critical (10) | Whether documentation requires authentication. Auth-gated docs are invisible to agents. | +| [auth-alternative-access](https://agentdocsspec.com/spec/web/authentication/#auth-alternative-access) | Medium (4) | Whether auth-gated sites provide alternative access paths (public llms.txt, SDK-bundled docs, etc.). | ## How the score is calculated diff --git a/docs/checks/authentication.md b/docs/checks/authentication.md index bee0bb0..f84c583 100644 --- a/docs/checks/authentication.md +++ b/docs/checks/authentication.md @@ -6,10 +6,10 @@ Whether agents can reach your documentation at all. Documentation that returns l Whether documentation pages require authentication to access content. -| | | -| ---------- | -------------------------------------------------------------------------- | -| **Weight** | Critical (10) | -| **Spec** | [auth-gate-detection](https://agentdocsspec.com/spec/#auth-gate-detection) | +| | | +| ---------- | --------------------------------------------------------------------------------------------- | +| **Weight** | Critical (10) | +| **Spec** | [auth-gate-detection](https://agentdocsspec.com/spec/web/authentication/#auth-gate-detection) | ### Why it matters @@ -40,7 +40,7 @@ AFDocs detects several forms of auth gating: - Shipping documentation with your SDK - Providing an MCP server for authenticated access -The [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec) covers options for making private docs agent-accessible, ordered by implementation effort. +The [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec/web/) covers options for making private docs agent-accessible, ordered by implementation effort. ### Score impact @@ -55,11 +55,11 @@ This is a Critical check with two score caps: Whether auth-gated sites provide alternative access paths agents can use. -| | | -| -------------- | ---------------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Depends on** | `auth-gate-detection` (warn or fail) | -| **Spec** | [auth-alternative-access](https://agentdocsspec.com/spec/#auth-alternative-access) | +| | | +| -------------- | ----------------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Depends on** | `auth-gate-detection` (warn or fail) | +| **Spec** | [auth-alternative-access](https://agentdocsspec.com/spec/web/authentication/#auth-alternative-access) | ### Why it matters @@ -97,6 +97,6 @@ Because AFDocs can't detect these manual paths, you won't get score credit for t ### How to fix -**If this check fails**, no alternative access paths were detected for your auth-gated content. The lowest-effort option is usually providing a public `llms.txt` that lists whatever documentation can be made available without authentication. See the [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec) for the full range of options. +**If this check fails**, no alternative access paths were detected for your auth-gated content. The lowest-effort option is usually providing a public `llms.txt` that lists whatever documentation can be made available without authentication. See the [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec/web/) for the full range of options. **If this check warns**, you have partial alternative access. Expand coverage to include more of the gated documentation, or add additional access paths. diff --git a/docs/checks/content-discoverability.md b/docs/checks/content-discoverability.md index a5dd8dd..8578f09 100644 --- a/docs/checks/content-discoverability.md +++ b/docs/checks/content-discoverability.md @@ -8,10 +8,10 @@ These seven checks carry the most combined weight of any category. Without disco Whether your site has an `llms.txt` file at a discoverable location. -| | | -| ---------- | ------------------------------------------------------------------ | -| **Weight** | Critical (10) | -| **Spec** | [llms-txt-exists](https://agentdocsspec.com/spec/#llms-txt-exists) | +| | | +| ---------- | ---------------------------------------------------------------------------------------------- | +| **Weight** | Critical (10) | +| **Spec** | [llms-txt-exists](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-exists) | ### Why it matters @@ -74,11 +74,11 @@ If this check fails, the score is [capped at D (59)](/agent-score-calculation#sc Whether your `llms.txt` follows the [llmstxt.org](https://llmstxt.org/) structure so agents can parse it reliably. -| | | -| -------------- | ---------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Depends on** | `llms-txt-exists` | -| **Spec** | [llms-txt-valid](https://agentdocsspec.com/spec/#llms-txt-valid) | +| | | +| -------------- | -------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Depends on** | `llms-txt-exists` | +| **Spec** | [llms-txt-valid](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-valid) | ### Why it matters @@ -104,11 +104,11 @@ A well-structured `llms.txt` gives agents a reliable map of the documentation. I Whether your `llms.txt` fits within agent context windows. -| | | -| -------------- | -------------------------------------------------------------- | -| **Weight** | High (7) | -| **Depends on** | `llms-txt-exists` | -| **Spec** | [llms-txt-size](https://agentdocsspec.com/spec/#llms-txt-size) | +| | | +| -------------- | ------------------------------------------------------------------------------------------ | +| **Weight** | High (7) | +| **Depends on** | `llms-txt-exists` | +| **Spec** | [llms-txt-size](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-size) | ### Why it matters @@ -138,11 +138,11 @@ When `llms.txt` is oversized, the [index truncation coefficient](/agent-score-ca Whether the URLs listed in your `llms.txt` actually work. -| | | -| -------------- | -------------------------------------------------------------------------------- | -| **Weight** | High (7) | -| **Depends on** | `llms-txt-exists` | -| **Spec** | [llms-txt-links-resolve](https://agentdocsspec.com/spec/#llms-txt-links-resolve) | +| | | +| -------------- | ------------------------------------------------------------------------------------------------------------ | +| **Weight** | High (7) | +| **Depends on** | `llms-txt-exists` | +| **Spec** | [llms-txt-links-resolve](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-links-resolve) | ### Why it matters @@ -168,11 +168,11 @@ The best long-term fix is generating `llms.txt` at build time so it stays in syn Whether the URLs in your `llms.txt` point to markdown content rather than HTML. -| | | -| -------------- | ---------------------------------------------------------------------------------- | -| **Weight** | High (7) | -| **Depends on** | `llms-txt-exists` | -| **Spec** | [llms-txt-links-markdown](https://agentdocsspec.com/spec/#llms-txt-links-markdown) | +| | | +| -------------- | -------------------------------------------------------------------------------------------------------------- | +| **Weight** | High (7) | +| **Depends on** | `llms-txt-exists` | +| **Spec** | [llms-txt-links-markdown](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-links-markdown) | ### Why it matters @@ -202,10 +202,10 @@ A warning on this check carries a bigger penalty in scoring because it means mar Whether the HTML version of your documentation pages tells agents where to find `llms.txt`. -| | | -| ---------- | ---------------------------------------------------------------------------------- | -| **Weight** | High (7) | -| **Spec** | [llms-txt-directive-html](https://agentdocsspec.com/spec/#llms-txt-directive-html) | +| | | +| ---------- | -------------------------------------------------------------------------------------------------------------- | +| **Weight** | High (7) | +| **Spec** | [llms-txt-directive-html](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-directive-html) | ### Why it matters @@ -231,11 +231,11 @@ Add a visually-hidden element near the top of each page (e.g., a `
` with CS Whether the markdown version of your documentation pages tells agents where to find `llms.txt`. -| | | -| -------------- | ------------------------------------------------------------------------------ | -| **Weight** | Medium (4) | -| **Depends on** | `markdown-url-support` or `content-negotiation` | -| **Spec** | [llms-txt-directive-md](https://agentdocsspec.com/spec/#llms-txt-directive-md) | +| | | +| -------------- | ---------------------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Depends on** | `markdown-url-support` or `content-negotiation` | +| **Spec** | [llms-txt-directive-md](https://agentdocsspec.com/spec/web/content-discoverability/#llms-txt-directive-md) | ### Why it matters diff --git a/docs/checks/content-structure.md b/docs/checks/content-structure.md index c6ba684..7305b4b 100644 --- a/docs/checks/content-structure.md +++ b/docs/checks/content-structure.md @@ -8,10 +8,10 @@ The checks in this section focus on structural patterns that have measurable imp Whether tabbed UI components create oversized output when serialized. -| | | -| ---------- | -------------------------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Spec** | [tabbed-content-serialization](https://agentdocsspec.com/spec/#tabbed-content-serialization) | +| | | +| ---------- | ------------------------------------------------------------------------------------------------------------------ | +| **Weight** | Medium (4) | +| **Spec** | [tabbed-content-serialization](https://agentdocsspec.com/spec/web/content-structure/#tabbed-content-serialization) | ### Why it matters @@ -38,11 +38,11 @@ If tabbed content creates oversized output, consider these approaches: Whether headers in tabbed sections include enough context to be meaningful without the surrounding UI. -| | | -| -------------- | -------------------------------------------------------------------------------- | -| **Weight** | Low (2) | -| **Depends on** | `tabbed-content-serialization` | -| **Spec** | [section-header-quality](https://agentdocsspec.com/spec/#section-header-quality) | +| | | +| -------------- | ------------------------------------------------------------------------------------------------------ | +| **Weight** | Low (2) | +| **Depends on** | `tabbed-content-serialization` | +| **Spec** | [section-header-quality](https://agentdocsspec.com/spec/web/content-structure/#section-header-quality) | ### Why it matters @@ -66,11 +66,11 @@ Add variant context to headers in tabbed sections. For example, change "Step 1" Whether markdown content has properly closed code fences. -| | | -| -------------- | -------------------------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Depends on** | `markdown-url-support` or `content-negotiation` | -| **Spec** | [markdown-code-fence-validity](https://agentdocsspec.com/spec/#markdown-code-fence-validity) | +| | | +| -------------- | ------------------------------------------------------------------------------------------------------------------ | +| **Weight** | Medium (4) | +| **Depends on** | `markdown-url-support` or `content-negotiation` | +| **Spec** | [markdown-code-fence-validity](https://agentdocsspec.com/spec/web/content-structure/#markdown-code-fence-validity) | ### Why it matters diff --git a/docs/checks/index.md b/docs/checks/index.md index cd5c4ca..14bc42a 100644 --- a/docs/checks/index.md +++ b/docs/checks/index.md @@ -1,6 +1,6 @@ # Checks Reference -AFDocs runs 23 checks across 7 categories. Each check implements a section of the [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec), which documents the observed agent behaviors and failure modes that motivated the check. +AFDocs runs 23 checks across 7 categories. Each check implements a section of the [Agent-Friendly Documentation Spec](https://agentdocsspec.com/spec/web/), which documents the observed agent behaviors and failure modes that motivated the check. ## Categories diff --git a/docs/checks/markdown-availability.md b/docs/checks/markdown-availability.md index a7302a1..b44f048 100644 --- a/docs/checks/markdown-availability.md +++ b/docs/checks/markdown-availability.md @@ -6,10 +6,10 @@ Whether agents can get documentation as markdown instead of HTML. Agents work mo Whether appending `.md` to a documentation URL returns valid markdown. -| | | -| ---------- | ---------------------------------------------------------------------------- | -| **Weight** | High (7) | -| **Spec** | [markdown-url-support](https://agentdocsspec.com/spec/#markdown-url-support) | +| | | +| ---------- | ------------------------------------------------------------------------------------------------------ | +| **Weight** | High (7) | +| **Spec** | [markdown-url-support](https://agentdocsspec.com/spec/web/markdown-availability/#markdown-url-support) | ### Why it matters @@ -43,10 +43,10 @@ Configure your docs platform to serve `.md` variants for all documentation pages Whether your server returns markdown when agents send `Accept: text/markdown`. -| | | -| ---------- | -------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Spec** | [content-negotiation](https://agentdocsspec.com/spec/#content-negotiation) | +| | | +| ---------- | ---------------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Spec** | [content-negotiation](https://agentdocsspec.com/spec/web/markdown-availability/#content-negotiation) | ### Why it matters diff --git a/docs/checks/observability.md b/docs/checks/observability.md index 8357d19..b71b233 100644 --- a/docs/checks/observability.md +++ b/docs/checks/observability.md @@ -6,11 +6,11 @@ Whether agent-facing resources stay accurate over time. Getting `llms.txt` and m How much of your site's documentation is represented in `llms.txt`. -| | | -| -------------- | ---------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Depends on** | `llms-txt-exists` | -| **Spec** | [llms-txt-coverage](https://agentdocsspec.com/spec/#llms-txt-coverage) | +| | | +| -------------- | ---------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Depends on** | `llms-txt-exists` | +| **Spec** | [llms-txt-coverage](https://agentdocsspec.com/spec/web/observability/#llms-txt-coverage) | ### Why it matters @@ -80,7 +80,7 @@ Paths like `/changelog`, `/releases`, and `/security` are **not** excluded becau ### Omitted subtrees -When your `llms.txt` uses [progressive disclosure](https://agentdocsspec.com/spec/#progressive-disclosure-for-large-documentation-sets) (nested `llms.txt` files), the walker descends one level into linked `.txt` files. Any `.txt` files found at that depth (which the walker does not descend into) are treated as "omitted subtrees." Sitemap pages under those subtree prefixes are excluded from the coverage denominator rather than counted as missing. +When your `llms.txt` uses [progressive disclosure](https://agentdocsspec.com/spec/web/content-discoverability/#progressive-disclosure-for-large-documentation-sets) (nested `llms.txt` files), the walker descends one level into linked `.txt` files. Any `.txt` files found at that depth (which the walker does not descend into) are treated as "omitted subtrees." Sitemap pages under those subtree prefixes are excluded from the coverage denominator rather than counted as missing. This means deeply nested `llms.txt` structures aren't penalized. The output distinguishes directly-verified pages from omitted subtrees. @@ -106,11 +106,11 @@ Each per-product run picks up that section's `llms.txt` as canonical. For the si Whether markdown and HTML versions of pages contain the same content. -| | | -| -------------- | ---------------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Depends on** | `markdown-url-support` or `content-negotiation` | -| **Spec** | [markdown-content-parity](https://agentdocsspec.com/spec/#markdown-content-parity) | +| | | +| -------------- | ---------------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Depends on** | `markdown-url-support` or `content-negotiation` | +| **Spec** | [markdown-content-parity](https://agentdocsspec.com/spec/web/observability/#markdown-content-parity) | ### Why it matters @@ -183,10 +183,10 @@ Note: `data-markdown-ignore` is built in and does not need to be listed in `pari Whether cache headers on `llms.txt` and markdown endpoints allow timely updates. -| | | -| ---------- | ---------------------------------------------------------------------------- | -| **Weight** | Low (2) | -| **Spec** | [cache-header-hygiene](https://agentdocsspec.com/spec/#cache-header-hygiene) | +| | | +| ---------- | ---------------------------------------------------------------------------------------------- | +| **Weight** | Low (2) | +| **Spec** | [cache-header-hygiene](https://agentdocsspec.com/spec/web/observability/#cache-header-hygiene) | ### Why it matters diff --git a/docs/checks/page-size.md b/docs/checks/page-size.md index f46c22f..a372f63 100644 --- a/docs/checks/page-size.md +++ b/docs/checks/page-size.md @@ -8,10 +8,10 @@ This category also covers the related problem of pages that technically fit with Whether pages contain server-rendered content or are empty client-side application shells. -| | | -| ---------- | ------------------------------------------------------------------------ | -| **Weight** | Critical (10) | -| **Spec** | [rendering-strategy](https://agentdocsspec.com/spec/#rendering-strategy) | +| | | +| ---------- | -------------------------------------------------------------------------------------- | +| **Weight** | Critical (10) | +| **Spec** | [rendering-strategy](https://agentdocsspec.com/spec/web/page-size/#rendering-strategy) | ### Why it matters @@ -50,11 +50,11 @@ The same proportion drives the [HTML path coefficient](/agent-score-calculation# Character count when documentation is served as markdown. -| | | -| -------------- | ------------------------------------------------------------------------ | -| **Weight** | High (7) | -| **Depends on** | `markdown-url-support` or `content-negotiation` | -| **Spec** | [page-size-markdown](https://agentdocsspec.com/spec/#page-size-markdown) | +| | | +| -------------- | -------------------------------------------------------------------------------------- | +| **Weight** | High (7) | +| **Depends on** | `markdown-url-support` or `content-negotiation` | +| **Spec** | [page-size-markdown](https://agentdocsspec.com/spec/web/page-size/#page-size-markdown) | ### Why it matters @@ -78,10 +78,10 @@ This is the best-case scenario for agent consumption. Markdown size directly cor Character count of the HTML response and the post-conversion size when converted to markdown. -| | | -| ---------- | ---------------------------------------------------------------- | -| **Weight** | High (7) | -| **Spec** | [page-size-html](https://agentdocsspec.com/spec/#page-size-html) | +| | | +| ---------- | ------------------------------------------------------------------------------ | +| **Weight** | High (7) | +| **Spec** | [page-size-html](https://agentdocsspec.com/spec/web/page-size/#page-size-html) | ### Why it matters @@ -118,10 +118,10 @@ Markdown availability helps agents that request it, but most agents still fetch How far into the response actual documentation content begins. -| | | -| ---------- | -------------------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Spec** | [content-start-position](https://agentdocsspec.com/spec/#content-start-position) | +| | | +| ---------- | ---------------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Spec** | [content-start-position](https://agentdocsspec.com/spec/web/page-size/#content-start-position) | ### Why it matters diff --git a/docs/checks/url-stability.md b/docs/checks/url-stability.md index 251be5c..b42100d 100644 --- a/docs/checks/url-stability.md +++ b/docs/checks/url-stability.md @@ -6,10 +6,10 @@ Whether documentation URLs behave predictably for agents. Agents retrieve URLs f Whether error pages return correct HTTP status codes. -| | | -| ---------- | ---------------------------------------------------------------------- | -| **Weight** | High (7) | -| **Spec** | [http-status-codes](https://agentdocsspec.com/spec/#http-status-codes) | +| | | +| ---------- | ---------------------------------------------------------------------------------------- | +| **Weight** | High (7) | +| **Spec** | [http-status-codes](https://agentdocsspec.com/spec/web/url-stability/#http-status-codes) | ### Why it matters @@ -56,10 +56,10 @@ A more interesting long-term approach: if you notice agents consistently request Whether redirects use standard HTTP methods and stay on the same host. -| | | -| ---------- | ---------------------------------------------------------------------- | -| **Weight** | Medium (4) | -| **Spec** | [redirect-behavior](https://agentdocsspec.com/spec/#redirect-behavior) | +| | | +| ---------- | ---------------------------------------------------------------------------------------- | +| **Weight** | Medium (4) | +| **Spec** | [redirect-behavior](https://agentdocsspec.com/spec/web/url-stability/#redirect-behavior) | ### Why it matters diff --git a/src/cli/formatters/text.ts b/src/cli/formatters/text.ts index cd8ef13..affcec0 100644 --- a/src/cli/formatters/text.ts +++ b/src/cli/formatters/text.ts @@ -1,6 +1,6 @@ import chalk from 'chalk'; import type { ReportResult, CheckResult } from '../../types.js'; -import { SPEC_BASE_URL } from '../../constants.js'; +import { SPEC_BASE_URL, specCheckUrl } from '../../constants.js'; import { getResolution } from '../../scoring/resolutions.js'; const STATUS_ICONS: Record = { @@ -364,7 +364,7 @@ function formatResult(result: CheckResult, allResults?: CheckResult[]): string { // Add spec link for warn/fail/error results if (result.status === 'warn' || result.status === 'fail' || result.status === 'error') { - line += `\n ${chalk.dim(`Learn more: ${SPEC_BASE_URL}#${result.id}`)}`; + line += `\n ${chalk.dim(`Learn more: ${specCheckUrl(result.category, result.id)}`)}`; } return line; diff --git a/src/constants.ts b/src/constants.ts index cffea30..de4b2a9 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -58,8 +58,16 @@ export const DEFAULT_PARITY_WARN_THRESHOLD = 20; /** Minimum discovered pages before page-level scores are considered meaningful. */ export const MIN_PAGES_FOR_SCORING = 5; -/** Base URL for the Agent-Friendly Documentation Spec. */ -export const SPEC_BASE_URL = 'https://agentdocsspec.com/spec/'; +/** Base URL for the Web Documentation Delivery Spec. */ +export const SPEC_BASE_URL = 'https://agentdocsspec.com/spec/web/'; + +/** + * URL of a check's definition in the spec. Checks are documented on + * per-category pages (category ids match the spec site's page slugs). + */ +export function specCheckUrl(category: string, checkId: string): string { + return `${SPEC_BASE_URL}${category}/#${checkId}`; +} /** Version of the Agent-Friendly Documentation Spec implemented by this release. */ export const SPEC_VERSION = 'v0.5.0'; diff --git a/test/unit/scoring/diagnostics.test.ts b/test/unit/scoring/diagnostics.test.ts index 592baa3..6babb19 100644 --- a/test/unit/scoring/diagnostics.test.ts +++ b/test/unit/scoring/diagnostics.test.ts @@ -18,7 +18,7 @@ function defaultReport(): ReportResult { return { url: 'https://example.com', timestamp: new Date().toISOString(), - specUrl: 'https://agentdocsspec.com/spec/', + specUrl: 'https://agentdocsspec.com/spec/web/', results: [], summary: { total: 0, pass: 0, warn: 0, fail: 0, skip: 0, error: 0 }, samplingStrategy: 'random', diff --git a/test/unit/scoring/score.test.ts b/test/unit/scoring/score.test.ts index f61f30a..f313188 100644 --- a/test/unit/scoring/score.test.ts +++ b/test/unit/scoring/score.test.ts @@ -22,7 +22,7 @@ function makeReport( return { url: 'https://example.com', timestamp: new Date().toISOString(), - specUrl: 'https://agentdocsspec.com/spec/', + specUrl: 'https://agentdocsspec.com/spec/web/', results, summary, ...overrides, diff --git a/test/unit/scoring/tag-scores.test.ts b/test/unit/scoring/tag-scores.test.ts index fa0250c..9fc3113 100644 --- a/test/unit/scoring/tag-scores.test.ts +++ b/test/unit/scoring/tag-scores.test.ts @@ -20,7 +20,7 @@ function makeReport(results: CheckResult[], urlTags?: Record): R return { url: 'https://example.com', timestamp: new Date().toISOString(), - specUrl: 'https://agentdocsspec.com/spec/', + specUrl: 'https://agentdocsspec.com/spec/web/', results, summary, urlTags,