v3.1.0 — Markdown for Agents: content-negotiation check (15 checks)

Added — content-negotiation check (informational)

• content-negotiation (weight 0 in 3.x): probes the homepage with Accept: text/markdown to detect Markdown for Agents support — the content-negotiation pattern implemented by Cloudflare and Vercel and requested by Claude Code, Cursor, and OpenCode. Markdown cuts token usage by ~80% vs HTML for the same content.
  • Validates the negotiated Content-Type (text/markdown).
  • Detects relabeled HTML documents masquerading as Markdown (−25).
  • Validates Vary: Accept so shared caches and CDNs keep the HTML and Markdown representations apart (−15 when missing; accepts Vary: *).
  • Reports the size reduction vs the HTML representation (informational).
  • Partial credit (40) when negotiation is unsupported but a <link rel="alternate" type="text/markdown"> fallback is advertised.
  • Distinguishes HTTP 406 from plain "ignores Accept" in the failure detail.

Added — per-request fetch headers

• CheckContext.fetch now accepts an optional { headers } argument (new exported type: FetchOptions). Custom headers merge case-insensitively over the defaults, so a custom Accept replaces the default instead of being sent alongside it.
• The in-memory request cache now keys on URL + normalized (lowercased, sorted) headers — mirroring Vary semantics on the wire, so the HTML and Markdown probes of the same URL never collide.

Fixed

• Scorer division by zero: calculateOverallScore returned NaN when every selected check had weight 0 (e.g. --checks content-negotiation). It now falls back to a plain average, and returns 0 for empty input.

Scoring

• The new check is informational in 3.x: it runs and reports findings but does not affect the overall score, so existing scores and baselines are unchanged. It will gain weight in v4.0, consistent with treating score-affecting changes as breaking (see v3.0.0).

Tests

• 229 tests total (31 new): content-negotiation (19), fetcher integration against a real local HTTP server (9), and scorer coverage for weight-0 checks (3).

Try it:

npx ax-audit@3.1.0 https://your-site.com --checks content-negotiation