Breaking v0.17.0 release - update for Agent-Friendly Docs Spec 0.5.0

[dacharyc]

Summary

Brings afdocs from spec v0.3.0 (22 checks) to v0.5.0 (23 checks) across 5 sub-PRs. This is a breaking release: check IDs renamed, check split, JSON output schema changed, scoring behavior changed.

PR 1: Strip <script> and <style> in htmlToMarkdown (#61)

Foundation change. Strips script/style elements before HTML-to-markdown conversion, fixing inflated page sizes and content-start-position measurements to match updates in Claude Code.

PR 2: Rename llms-txt-freshness → llms-txt-coverage + curation + omitted subtrees (#62)

Renames check ID. Adds configurable thresholds (--coverage-pass-threshold, --coverage-warn-threshold), exclusion patterns (--coverage-exclusions), and omitted subtree handling for progressive disclosure sites.

PR 3: Split llms-txt-directive → llms-txt-directive-html + llms-txt-directive-md (#63)

Splits one check into two. HTML check searches the DOM (stripping nav/script/style); markdown check probes .md endpoints. New markdown-partially-discoverable diagnostic. Check count 22 → 23, max raw score 126 → 130.

PR 4: Single-page scoring reliability (#64)

Adds scoreDisplayMode (numeric | notApplicable) to check scores. Page-level checks get N/A when fewer than 5 pages discovered. Null category scores. Four new diagnostics: single-page-sample, cross-origin-llms-txt, gzipped-sitemap-skipped, rate-limiting-severe.

PR 5: markdown-content-parity audience segmentation (#65)

Adds data-markdown-ignore HTML attribute convention, configurable parity thresholds (--parity-pass-threshold, --parity-warn-threshold), custom CSS exclusion selectors (--parity-exclusions). Config validation for YAML exclusion arrays.

Breaking changes for consumers

Check IDs:

• llms-txt-freshness → llms-txt-coverage
• llms-txt-directive → llms-txt-directive-html + llms-txt-directive-md

JSON output schema:

• CheckScore has new required field scoreDisplayMode
• CategoryScore.score and grade can be null
• ReportResult has new optional fields testedPages and samplingStrategy
• markdown-content-parity details has new optional fields: segmentationElementsStripped, parityPassThreshold, parityWarnThreshold
• llms-txt-coverage details shape changed (new fields for thresholds, exclusions, omitted subtrees)
• llms-txt-links-resolve details crossOrigin has new dominantOrigin field
• New diagnostic IDs: markdown-partially-discoverable, single-page-sample, cross-origin-llms-txt, gzipped-sitemap-skipped, rate-limiting-severe

Scoring:

• Max raw score: 126 → 130
• evaluateDiagnostics requires second argument (ReportResult)
• rendering-strategy and auth-gate-detection score caps skip N/A checks

Resolution text:

• Multiple checks have updated resolution strings (dynamic thresholds, segmentation mentions)

New CheckOptions fields (non-breaking, all optional with defaults):

• coveragePassThreshold, coverageWarnThreshold, coverageExclusions
• parityPassThreshold, parityWarnThreshold, parityExclusions
• llmsTxtUrl

954 tests, lint clean, build clean.

---

Outstanding items before merge to main

Release prep:

• Update src/constants.ts spec URL/version reference (v0.3.0 → v0.5.0)
• Update README.md spec version and check count (22 → 23)
• Write a migration document for downstream consumers who are coming from a pre-v0.17.0 release

Smoke tests:

• npx afdocs check https://docs.anthropic.com -- scorecard output, 23 checks, correct IDs
• npx afdocs check https://docs.anthropic.com --format json --score -- verify new check IDs present, old IDs absent
• npx afdocs check <mintlify-site> -- verify llms-txt-directive-html and llms-txt-directive-md report independently
• npx afdocs check <site> --coverage-pass-threshold 0 --coverage-warn-threshold 0 -- verify informational mode
• npx afdocs check <site> --parity-pass-threshold 0 --parity-warn-threshold 0 -- verify informational mode
• npx afdocs check <site> --sampling none -- verify single-page N/A behavior for page-level checks
• Test with a config file containing parityExclusions and coverageExclusions

Docs site:

• Build and verify docs site renders correctly (check for broken internal links from renamed check IDs)
• Verify llms.txt regeneration picks up new check IDs