Skip to content

Update spec URLs for the /spec/web/ restructure #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dacharyc merged 1 commit into from
Sep 13, 2026
Merged

Update spec URLs for the /spec/web/ restructure #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@
<a href="https://www.npmjs.com/package/afdocs"><img src="https://img.shields.io/npm/v/afdocs" alt="npm"></a>
</p>

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

Expand Down
74 changes: 37 additions & 37 deletions SCORING.md
View file
Open in desktop

Large diffs are not rendered by default.

22 changes: 11 additions & 11 deletions docs/checks/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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.
66 changes: 33 additions & 33 deletions docs/checks/content-discoverability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -231,11 +231,11 @@ Add a visually-hidden element near the top of each page (e.g., a `<div>` 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

Expand Down
28 changes: 14 additions & 14 deletions docs/checks/content-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/checks/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down
16 changes: 8 additions & 8 deletions docs/checks/markdown-availability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
Loading