ax-audit 3.1.0 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,204 @@
 
 All notable changes to ax-audit are documented here.
 
+## [4.0.0] - 2026-09-04
+
+**Scores change on every site.** This release redistributes the weights, makes protocol checks conditional, and retires a check whose premise did not survive verification. Baselines written by earlier versions are read normally, but regression gating is suspended across the change — a rescore is not something the site did.
+
+### Breaking
+
+- **Weights redistributed by what actually stops an agent.** Content leads at 33, because the failure that breaks the most agents is a page with nothing in its HTML: most crawlers do not run JavaScript, so content that appears only after hydration is invisible no matter how many discovery files a site publishes. `html-rendering` is the highest-weighted check at 11. Access is second at 24, because a firewall rule or a `nosnippet` directive silently undoes everything else. Discovery drops to 21, with llms.txt demoted from 11 to 5 on the evidence that most published files are never fetched by an AI search crawler.
+- **Protocol checks are conditional.** A blog has no API to describe and is not an agent; scoring it zero said something false and made the overall number unreadable. Each protocol check now detects whether the site has the corresponding surface, reports **n/a** when it does not, and leaves the denominator. When the surface *is* present, a missing description is a stronger finding than before, and the wording says so: not "no MCP server discovery found" but "MCP server present but not discoverable".
+- **`well-known-ai` retired.** Three of its five scored files had no consumer: `nlweb.json` appears in no NLWeb release, `genai.txt` has no specification, and `ai-plugin.json` described a product shut down in 2024. Its useful probes moved into the checks that own them in 3.8.
+- **The 3.x scoring freezes are gone.** `robots-txt` scores against all twelve current core crawlers rather than the frozen eight, so the configuration that scored 100 in 3.6 now scores 90. Blocking a crawler deducts by purpose: 5 for a search crawler, whose absence removes the site from that assistant's answers, and 2 for a training crawler, where blocking is a defensible policy choice.
+- **`CheckMeta.weight` is now optional** and nothing uses it. Weights live in `CHECK_WEIGHTS` alone. Having them in two places is what let them drift.
+
+### Added
+
+- **`--profile api|mcp|agent|docs|commerce|all`** forces conditional checks applicable, for auditing against what a site intends to build rather than what it already has.
+- **`--category content|discovery|access|policy|protocols`** runs one area. It narrows an explicit `--checks` selection rather than replacing it.
+- **`--fail-on-category access:70,content:80`** gates CI per area. An overall score hides an area that is entirely broken: a site can score 80 while every access check fails because the other four carry it. Areas with nothing applicable are reported as not evaluated rather than failed.
+- **Versioned baselines.** `schemaVersion` records which scoring model produced a baseline; a mismatch shows the deltas but suspends gating and says how to resume it. Baselines also record which checks were N/A, so gaining or losing a surface is not read as a regression or an improvement.
+
+### Migration
+
+1. Expect a different score. Sites with no API or MCP surface generally rise, because they are no longer marked down for lacking things they do not have. A bare page rose from 20 to 50 in testing; a documentation site with real infrastructure rose from 64 to 77.
+2. Re-save your baseline: `ax-audit <url> --save-baseline .ax-baseline.json`. Until you do, `--fail-on-regression` reports but does not gate.
+3. `--checks agent-json`, `--checks mcp` and `--checks openapi` still work; the ids were renamed in 3.7 and the old names remain aliases.
+4. If you relied on `well-known-ai`, its live probes are now in `usage-policy` (TDMRep) and the checks that own each file.
+
+### Fixed
+
+- **JSON-LD was missed when `type` was not the first attribute** on the script tag. Next.js and several other frameworks emit `<script id="…" type="application/ld+json">`, so a large class of well-marked-up sites scored 0 on a 6-weight check and were told to add markup they already had. Three copies of the pattern now share one order-independent extractor.
+
+### Tests
+
+873 total. New coverage for surface detection, the weight distribution (sums to 100, no check declares its own, content outweighs every area), the CLI end to end via a subprocess, and baseline versioning in both directions.
+
+## [3.9.0] - 2026-09-04
+
+Depth rather than breadth. One new check, and the existing readability checks extended to cover what agents actually do with a page once they reach it. Everything added is informational; scores are unchanged.
+
+### Added
+
+- **agent-operability**: whether a browser agent can work the page or only look at it. Every major browser agent reads the accessibility tree, so a `<div onclick>` styled as a button does not appear at all — the agent does not see a button it cannot press, it sees nothing. Checks accessible names on buttons and links, labels on form controls, elements dressed as controls, dead links, table headers, iframe titles, `<time datetime>`, heading skips, unsized media, `<html lang>`, and entry-page obstacles. Reports proportions with a 90% threshold, and states on every run that it reads markup rather than a rendered tree.
+
+### Changed
+
+- **llms.txt** gained the 2026 specification revision's additions — subpath scoping via `rel="describedby"`, per-page `.md` mirrors — plus link-health sampling. An llms.txt is written once and never revalidated while the site moves underneath it, so an index of dead links is its characteristic failure, and it wastes exactly the budget the file exists to save. Dead links are reported separately from redirecting ones. Every report now states who actually reads this file.
+- **content-negotiation** stopped probing with a header no client sends. A bare `Accept: text/markdown` would pass against an implementation that fails every real request; the probe now sends what Claude Code, Cursor and OpenCode send. Added: origin-reported token counts preferred over a byte ratio, frontmatter validation (stripping the HTML also strips the canonical link, leaving an agent unable to attribute what it quotes), and probes for user-agent negotiation and `.md` suffix URLs before concluding a site has no Markdown.
+- **structured-data** now reads provenance and freshness — `author`, `sameAs`, `publisher`, `dateModified` — and compares `headline` and `name` against the visible text, which is Google's one explicit requirement for structured data and AI features.
+- **crawl-efficiency** reports a page's cost in tokens rather than bytes, naming the markup share an agent pays to receive and then discards, plus response time in agent terms.
+
+### Tests
+
+828 total, up from 777.
+
+## [3.8.0] - 2026-09-04
+
+Eight new checks, all weight 0, plus the reporting machinery they need. Where 3.7 corrected what ax-audit was looking for, 3.8 covers the signals it was not looking at.
+
+### Added — reporting
+
+- **Not-applicable checks.** A commerce-protocol check scoring zero on a personal blog says the blog is badly built; the honest answer is that the question does not arise. `CheckResult.applicable: false` excludes a check from both numerator and denominator, and reports render it as `n/a`. Everything counted against a site is now something the site could have done. A check whose meta exists but produced no result — because it crashed — still counts at full weight, so a broken check cannot inflate a score.
+- **Category grouping.** Terminal, Markdown and HTML output group checks under content, discovery, access, policy and protocols. Twenty-six scores in a flat list do not tell a reader where the problem is.
+- **`renderHtml` / `renderBatchHtml`**, returning the document as a string the way `renderMarkdown` already did. The HTML reporter could previously only print to stdout, which made it untestable and unusable from the programmatic API.
+
+### Added — checks
+
+- **ai-directives**: the page-level controls Google and Microsoft document that they honor — `nosnippet` and `max-snippet` for AI Overviews and AI Mode, `noarchive` and `nocache` for Copilot grounding, `data-nosnippet` judged by what it wraps. The finding it exists for: a site that disallows `Google-Extended` expecting to leave AI Overviews has done no such thing, because that token governs Gemini training and grounding while AI Overviews follow Googlebot and the snippet directives.
+- **usage-policy**: normalises Content Signals, AIPREF, RSL, TDMRep and `noai` onto three questions — train, ground, index — and reports where they disagree. A site whose robots.txt permits training while its RSL licence prohibits it has published two contradictory positions, and which one applies depends on which file a crawler read. Every report states that only robots.txt access rules are documented as honored by major operators.
+- **http-hygiene**: status-code honesty. An agent cannot see that the 200 it received is a "page not found" screen; it stores the apology as the answer. Also redirect depth, `HEAD` support, `Retry-After` on 429, charset, and `<html lang>` against `Content-Language`.
+- **ai-catalog**: the emerging single index of everything callable on a site, discovered the four ways Lighthouse's own audit accepts. Both specifications are drafts, so absence never scores — but a catalog whose entries point at documents that 404 does, because an agent trusts it before it fetches.
+- **agent-skills**: installable procedures (SKILL.md) across all three competing discovery paths, validating the index and fetching a sample of the documents. Conditional on the site having a developer-facing surface.
+- **webmcp**: forms declared as callable tools. Never asks for WebMCP, which is a Community Group draft in a Chrome origin trial; catches the mistakes static analysis can catch with certainty on pages that adopted it.
+- **commerce-discovery**: the Universal Commerce Protocol profile, the one agentic-commerce specification with published site-side discovery. Validates the profile and resolves the schema URLs it promises. The alternatives define no manifest, and the report says so rather than inventing paths.
+- **auth-discovery**: the RFC 9728 chain from `WWW-Authenticate` to the authorization server's metadata. A human hitting a 401 reads the documentation; an agent cannot.
+
+### Added — infrastructure
+
+- `checks/frontmatter.ts`: a focused YAML frontmatter reader for SKILL.md and Markdown mirrors. ax-audit has two runtime dependencies and will not grow a YAML parser, so the reader handles the flat `key: value` block these documents use and records anything more elaborate as skipped rather than guessing.
+
+### Fixed
+
+- **A lone `Offer` is a price, not a storefront.** Found by running commerce-discovery against a real SaaS site, which was told to build a commerce integration because it prices its plans with structured data. A bare `Offer` now counts only alongside a second signal such as a cart link.
+- `buildResult` falls back to `CHECK_CATEGORIES`, so every result carries its category in JSON output too. Previously only checks setting `meta.category` explicitly did, leaving JSON consumers to reimplement the fallback the other reporters already had.
+
+### Scoring
+
+Unchanged. All eight checks carry weight 0 and gain weight in 4.0.
+
+### Tests
+
+755 total, up from 553. New suites: ai-directives, usage-policy, http-hygiene, ai-catalog, agent-skills, webmcp, commerce-discovery, auth-discovery, frontmatter, and the N/A arithmetic including the crashed-check case.
+
+## [3.7.0] - 2026-09-04
+
+A correction release. Three checks were probing paths that are no longer, or never were, the standard, and the crawler catalogue had drifted far enough to contain tokens that do not exist. Everything here was re-verified against vendor documentation, IANA, IETF datatracker and the relevant specification repositories on 2026-09-04.
+
+**No score goes down.** Every correction that would have lowered an existing score is frozen behind a constant that is removed in 4.0, and tests assert it.
+
+### Fixed — wrong paths
+
+- **A2A Agent Card moved.** The check probed `/.well-known/agent.json`. A2A relocated the card to `/.well-known/agent-card.json` in v0.3.0 (2025-07-30), and that path is IANA-registered. Both are probed, the registered one first; a card served only from the old path is validated and flagged. The check also handles both spec generations: A2A 1.0 (2026-03-12) folded `url`, `protocolVersion`, `preferredTransport` and `additionalInterfaces` into `supportedInterfaces[]`, and the generation is detected from the card's own structure rather than a version field. `authentication`, removed in 0.2.x in favour of `securitySchemes`, is now flagged. Renamed `agent-json` → `agent-card`.
+- **`/.well-known/mcp.json` was never an MCP convention.** ax-audit recommended it before the ecosystem settled. Discovery now walks the real chain: `/.well-known/ai-catalog.json`, `/.well-known/mcp/server-card.json`, `<endpoint>/server-card`, then the legacy manifest. Server cards deliberately carry no `tools[]` — tool lists come from a live `tools/list` call. Protocol versions are checked against the five released revisions, with `2026-07-28` current. Renamed `mcp` → `mcp-discovery`.
+- **`/.well-known/openapi.json` is a folk convention**, so a site publishing at `/openapi.json` scored zero. Discovery now runs in order of authority: RFC 9727's registered `/.well-known/api-catalog`, then RFC 8631 `service-desc` relations in headers and HTML, then ten conventional paths. YAML descriptions are recognised and reported as surface-validated only, since ax-audit ships no YAML parser. Renamed `openapi` → `api-discovery`.
+- **`agent-access` was probing with `Google-Extended`.** That string is a robots.txt control token governing how an already-crawled page may be used; no request carries it, so the probe tested nothing. Token-only controls are excluded, leaving 10 real crawlers.
+- **`http-headers` and `meta-tags` penalised correct behaviour**, requiring a discovery link to `agent.json` specifically. Either card path now counts.
+- **An SPA catch-all page is absence, not corruption.** Found by running the new checks against a real site: probing `/mcp/server-card` returned HTTP 200 with the application's index shell, and the check reported a malformed server card on a site with no MCP server. `isHtmlDocument` now gates the speculative probes in `agent-card`, `mcp-discovery` and `api-discovery`.
+
+### Fixed — crawler catalogue
+
+Verified against vendor documentation on 2026-09-04. Removed tokens that were never real user agents (`Gemini`, `GeminiBot`, `DeepSeek-AI`), whose products were discontinued (`NeevaBot`, `Operator`, `GoogleAgent-Mariner`), whose vendor operates no crawlers (Cohere), or that are not AI crawlers at all (the Awario social-listening family). Reclassified five user-triggered fetchers that were listed as training crawlers. Added `meta-webindexer`, `Amzn-SearchBot`, `Amzn-User`, `MistralAI-Index`, `MistralAI-Training`, `Google-GeminiNotebook`, `Applebot`, `ExaSearchBot`, `TikTokSpider`, `OAI-AdsBot`, `YandexAdditional`.
+
+The catalogue is now organised by what a client does with a page — training, search, user-fetch, agent — because that determines the cost of blocking it. `CRAWLER_META` carries per token the vendor, whether robots.txt is honored, the published IP list, whether requests are signed with Web Bot Auth, and one sentence on what blocking costs. Findings quote it: "blocking OAI-SearchBot removes you from ChatGPT search answers", not "1 AI crawler blocked".
+
+### Added
+
+- **Response classification.** `checks/waf.ts` distinguishes a deliberate block from a JavaScript challenge from anti-spoofing, because the remedies are completely different. Signatures verified 2026-09-04: `cf-mitigated: challenge`, `x-vercel-mitigated`, AWS WAF's 202 with `x-amzn-waf-action`, Cloudflare pay-per-crawl's `crawler-price`, x402's `payment-signature`, Web Bot Auth's `Accept-Signature`, RSL's `WWW-Authenticate: License`, plus thirteen body markers. Outcomes an unsigned probe cannot settle are scored at 0.75 and labelled inconclusive with the header observed — never as "blocks AI crawlers".
+- **IETF AIPREF `Content-Usage:`** in robots.txt (draft-ietf-aipref-attach-05), with an optional path scope and a Structured Fields dictionary. The loudest finding is a vocabulary mix-up: AIPREF spells the training token `train-ai` with `y`/`n` while Content Signals and RSL spell it `ai-train` with `yes`/`no`, so `Content-Usage: ai-train=no` looks correct and does nothing.
+- **Content Signals `use=immediate|reference|full`**, the fourth field Cloudflare added on 2026-07-01 and now serves from managed robots.txt. Cloudflare-managed blocks are detected and named.
+- **Discovery link relations** in `http-headers`: `describedby` (llms.txt v2), `api-catalog` (RFC 9727), `service-desc` and `service-doc` (RFC 8631), `ai-catalog`, `c2pa-manifest`, `license`, markdown alternates, and the `X-Llms-Txt` header.
+- **Content parity** in `agent-access` now fingerprints title, h1 and JSON-LD block count, catching cloaking that preserves word count.
+- **Current well-known files** reported but never scored: the Web Bot Auth key directory, TDMRep, the OpenAI Apps verification token, `AGENTS.md`.
+- **Fetcher transport options**: `method: 'HEAD'` and `redirect: 'manual'`, with `elapsedMs`, `redirected` and `redirectLocation` on every response.
+- **Check categories** (content / discovery / access / policy / protocols) and `CheckResult.applicable` for N/A reporting, both consumed by reporters in 3.8.
+- **`docs/roadmap.md`**: the research behind this release and the plan through 4.0.
+
+### Changed
+
+- **robots.txt is parsed once.** `checks/robots-parser.ts` replaces three separate parsers that disagreed about what closes a User-agent group. Two parsing bugs fell out: `Disallow:` with an empty value now correctly means "allow all" per RFC 9309 §2.2.2 instead of being ignored, and a bot named in two groups is merged so a later `Disallow: /` is no longer hidden by an earlier `Allow: /`.
+- **`well-known-ai` tells the truth.** Re-verification found three of its five scored files have no consumer: `/.well-known/nlweb.json` **does not exist** in any NLWeb release, document or commit (NLWeb exposes `/ask` and `/mcp`); `genai.txt` has no specification; `/ai-plugin.json` described ChatGPT plugins, shut down 2024-04-09. Omitting a retired format now reads as a pass with the evidence attached. The formula stays frozen for score stability; the check loses its weight and its retired probes in 4.0.
+- **Renamed check ids keep working.** `CheckMeta.aliases` plus `src/check-ids.ts` resolve former ids in `--checks` selection and in baseline diffing, so a rename does not read as one check removed at a full regression and one added at zero.
+
+### Scoring
+
+Unchanged. `robots-txt` deducts against the frozen eight-token core set and the token list 3.6 recognised; a site whose only MCP document is the legacy manifest is validated with the pre-3.7 rules reproduced exactly; `well-known-ai` keeps its five-file formula; every finding added inside a weighted check is informational. Broadened discovery can only raise a score, never lower one. Both freezes are removed in 4.0.
+
+### Tests
+
+553 total, up from 301. New suites: robots parser, structured fields, crawler catalogue, WAF classification, check-id aliasing, well-known registry, SPA-shell guard, fetcher transport. Two classes of test exist specifically to hold the no-regression promise: score-stability tests asserting a 3.6 perfect configuration still scores 100, and informational-finding tests asserting new findings leave scores untouched.
+
+## [3.6.0] - 2026-06-06
+
+### Added
+
+- **Fetcher retries with exponential backoff**: transient failures (network errors, timeouts, and 408/425/429/500/502/503/504) are retried automatically. Configurable via `--retries <n>` (CLI, default 2) and `retries` (programmatic `AuditOptions`); backoff doubles from a 250ms base. Non-retryable responses (e.g. 404) short-circuit immediately. Previously a single transient timeout scored a check 0.
+- **Parallel batch auditing**: `--concurrency <n>` (CLI) and `concurrency` on the new `BatchOptions` type run multiple URL audits in parallel via an order-preserving work queue. Default remains sequential (1).
+- **Markdown reporter**: `--output markdown` emits a self-contained Markdown report (score, summary table, per-check findings with status emoji, baseline deltas) — ideal for CI logs and PR comments. Supported for single and batch audits. New exports: `renderMarkdown`, `renderBatchMarkdown`.
+- **Crawler list refresh**: added Google's official signed AI-agent user-agent `Google-Agent` (identity `https://agent.bot.goog`) to the known-crawlers list.
+- **CLI validation**: `--retries`, `--concurrency`, and `--output` now reject invalid values with a clear error.
+- **17 new tests** (301 total): fetcher retry behavior (against a flaky local server), batch ordering/concurrency, and the Markdown reporter.
+
+### Notes
+
+- No scoring changes. Retries can raise scores on flaky endpoints that previously timed out, but the scoring model itself is unchanged.
+
+## [3.5.0] - 2026-06-06
+
+### Added
+
+- **crawl-efficiency check (informational)**: measures the cost of crawling your pages across three dimensions. Compression — rewards Brotli, accepts gzip/deflate/zstd (suggesting br), warns when uncompressed (−30). Conditional GET — checks for an `ETag` or `Last-Modified` validator, then issues a follow-up request with `If-None-Match` / `If-Modified-Since` and verifies the server returns `304 Not Modified` (−30 for no validator, −15 when 304 is not honored). Response size — warns on pages over 500 KB (−5) and 2 MB (−10) of decompressed HTML. The probe advertises `Accept-Encoding: br, gzip, deflate`; the conditional request reuses the per-request header support added in 3.1.0.
+- **12 new tests** (284 total).
+
+### Scoring
+
+- The new check carries **weight 0 in 3.x** (informational), consistent with 3.1.0–3.4.0.
+
+## [3.4.0] - 2026-06-06
+
+### Added
+
+- **agent-access check (informational)**: cloaking and blocking detection. Probes the homepage with realistic user-agents for each of the 8 core AI crawlers (GPTBot, ClaudeBot, ChatGPT-User, Claude-SearchBot, Google-Extended, PerplexityBot, OAI-SearchBot, CCBot) and compares status and visible-text volume against the default-UA baseline. Flags the failure mode invisible to operators: robots.txt allows a crawler while the WAF returns 403 to its user-agent (Cloudflare's "Block AI Crawlers" toggle produces exactly this). Blocks consistent with an explicit robots.txt `Disallow` (or wildcard block) are reported as intentional and not penalized. Responses with under 50% of baseline visible text count as reduced content (half credit); content comparison is skipped for baselines under 200 chars to avoid SPA-shell noise. Hints note the verified-bots caveat: WAFs using Web Bot Auth / IP verification may pass the real crawler while rejecting this unverified probe.
+- `parseUserAgents` and `BotEntry` are now exported from the robots-txt check for reuse.
+- **12 new tests** (272 total).
+
+### Scoring
+
+- Internal score is the credit ratio across the 8 probes; the check carries **weight 0 in 3.x** (informational), consistent with 3.1.0–3.3.0.
+
+## [3.3.0] - 2026-06-06
+
+### Added
+
+- **rsl check (informational)**: validates [Really Simple Licensing 1.0](https://rslstandard.org/rsl) — the machine-readable content-licensing standard endorsed by 1,500+ publishers (Reddit, Yahoo, Medium, O'Reilly) with infrastructure support from Cloudflare and Fastly. Discovery via all three spec mechanisms: robots.txt `License:` directive (absolute-URI enforcement per §4.4.1), HTTP `Link: rel="license"; type="application/rsl+xml"` header, and `<link rel="license" type="application/rsl+xml">` (plain CC-style license links without the RSL media type are ignored). Document validation: `application/rsl+xml` Content-Type (−5), `<rsl>` root + `https://rslstandard.org/rsl` namespace, required `url` attribute on every `<content>` (empty value allowed per §3.3), `<license>` presence, `permits`/`prohibits` type and token vocabulary (`usage`: all/ai-all/ai-train/ai-input/ai-index/search; `user`; `geo` as ISO 3166-1 alpha-2), and `payment` types.
+- **21 new tests** (260 total) covering the three discovery mechanisms, vocabulary enforcement, namespace/root/structure validation, XML-comment stripping, and score caps.
+
+### Scoring
+
+- The new check carries **weight 0 in 3.x** (informational), consistent with 3.1.0/3.2.0: no impact on existing scores or baselines until v4.0.
+
+## [3.2.0] - 2026-06-06
+
+### Added
+
+- **Content Signals Policy support in robots-txt** ([contentsignals.org](https://contentsignals.org), CC0): the check now parses `Content-Signal:` directives — the machine-readable `search` / `ai-input` / `ai-train` preferences that Cloudflare serves by default on its 3.8M+ managed robots.txt domains. Declared signals are reported per User-agent group; malformed segments, unknown signal names, and directives placed outside a User-agent group produce warnings. Absence of the directive produces an informational nudge. The group parser now also treats `Content-Signal` as a group-closing directive, fixing potential User-agent group leakage.
+- **10 new tests** (239 total) covering declaration reporting, malformed/unknown signals, shared User-agent groups, case-insensitivity, out-of-group placement, and score neutrality.
+
+### Scoring
+
+- All Content Signals findings are **informational in 3.x**: they never alter the robots-txt score, so existing scores and baselines are unchanged.
+
 ## [3.1.0] - 2026-06-06
 
 ### Added

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 Lucio Duran
+   Copyright 2026 Durani Technologies
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -4,9 +4,9 @@
 
 <h1 align="center">ax-audit</h1>
 
-[![CI](https://github.com/lucioduran/ax-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/lucioduran/ax-audit/actions/workflows/ci.yml)
+[![CI](https://github.com/duranitech/ax-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/duranitech/ax-audit/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ax-audit.svg)](https://www.npmjs.com/package/ax-audit)
-[![license](https://img.shields.io/npm/l/ax-audit.svg)](https://github.com/lucioduran/ax-audit/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/ax-audit.svg)](https://github.com/duranitech/ax-audit/blob/main/LICENSE)
 [![node](https://img.shields.io/node/v/ax-audit.svg)](https://nodejs.org)
 
 **Lighthouse for AI Agents.** Audit any website's AI Agent Experience (AX) readiness in seconds.
@@ -17,281 +17,139 @@ npx ax-audit https://your-site.com
 
 ```
   AX Audit Report
-  https://lucioduran.com
-
-  ███████████████████████████████████░░░░░  88/100  Good
-
-  LLMs.txt (100/100)
-    PASS  /llms.txt exists
-    PASS  /llms.txt Content-Type OK (text/plain)
-    PASS  H1 heading: "Lucio Duran — Personal Portfolio"
-    PASS  /llms-full.txt also available (bonus)
-
-  Robots.txt (100/100)
-    PASS  All 8 core AI crawlers explicitly configured
-    PASS  32/47 known AI crawlers have explicit rules
-
-  HTML Rendering (90/100)
-    PASS  Server-rendered content detected (473 words)
-    PASS  Semantic landmarks present (main, article, header, footer, nav)
-    PASS  Single <h1> heading
-    PASS  3/3 <img> tags have alt attributes
-
-  TLS / HTTPS (100/100)
-    PASS  Site is served over HTTPS
-    PASS  HTTP requests redirect to HTTPS
-    PASS  HSTS preload-eligible
-  ...
-```
-
-## Why
-
-AI agents and LLMs are increasingly crawling, indexing, and interacting with websites. Just like Lighthouse audits web performance and axe-core audits accessibility, **ax-audit** tells you how ready your site is for the AI agent ecosystem.
-
-## What it checks
-
-| Check | What it audits | Weight |
-|---|---|---|
-| **LLMs.txt** | `/llms.txt` presence, [llmstxt.org](https://llmstxt.org) spec, Content-Type | 11% |
-| **Robots.txt** | AI crawler configuration (40+ known crawlers), wildcard detection, partial path restrictions | 11% |
-| **HTML Rendering** | Server-rendered content, semantic landmarks, SPA-shell detection, alt coverage | 9% |
-| **Structured Data** | JSON-LD on homepage (schema.org, `@graph`, entity types) | 9% |
-| **HTTP Headers** | Security headers + AI discovery `Link` headers + CORS on `.well-known` | 9% |
-| **Agent Card** | `/.well-known/agent.json` [A2A protocol](https://a2a-protocol.org) + same-origin url + skill quality | 7% |
-| **MCP** | `/.well-known/mcp.json` [Model Context Protocol](https://modelcontextprotocol.io) server config | 7% |
-| **SEO Basics** | `<title>`, meta description, canonical, `<html lang>`, charset, viewport, hreflang | 7% |
-| **Security.txt** | `/.well-known/security.txt` [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116) compliance | 6% |
-| **Meta Tags** | AI meta tags (`ai:*`), `rel="alternate"`, `rel="me"`, OpenGraph + Twitter Card completeness | 6% |
-| **OpenAPI** | `/.well-known/openapi.json` presence, schema validity, Content-Type | 6% |
-| **TLS / HTTPS** | HTTPS, HTTP→HTTPS redirect, HSTS with `preload` + `includeSubDomains` | 5% |
-| **Sitemap** | `sitemap.xml` (or `Sitemap:` from robots.txt) — XML validity, `<lastmod>` coverage, freshness, sitemap-index handling | 4% |
-| **AI Well-Known** | Emerging files: `/.well-known/ai.txt`, `genai.txt`, `ai-plugin.json`, `agents.json`, `nlweb.json` | 3% |
-| **Content Negotiation** | Markdown for agents — `Accept: text/markdown` negotiation, `Vary: Accept`, `rel="alternate"` fallback | 0%* |
-
-\* **Content Negotiation** is informational in 3.x: it runs and reports findings but does not affect the overall score. It will gain weight in v4.0.
-
-## Install
-
-```bash
-npm install -g ax-audit
-```
-
-Or run directly without installing:
-
-```bash
-npx ax-audit https://your-site.com
-```
-
-## Usage
-
-```bash
-# Full audit with colored terminal output
-ax-audit https://example.com
-
-# Batch audit — audit multiple URLs in a single run
-ax-audit https://example.com https://other-site.com https://third.dev
-
-# HTML report — self-contained, dark mode, shareable
-ax-audit https://example.com --output html > report.html
-
-# JSON output for CI/CD pipelines
-ax-audit https://example.com --json
-
-# Run only specific checks (validates IDs, errors on unknown)
-ax-audit https://example.com --checks llms-txt,robots-txt,agent-json
-
-# Custom timeout per request (default: 10s)
-ax-audit https://example.com --timeout 15000
-
-# Verbose mode — see every HTTP request, cache hit, and check score
-ax-audit https://example.com --verbose
-
-# Only show failures and warnings (hide passing findings)
-ax-audit https://example.com --only-failures
-
-# Save a baseline for future comparison
-ax-audit https://example.com --save-baseline baseline.json
-
-# Compare against a baseline — shows per-check score deltas
-ax-audit https://example.com --baseline baseline.json
+  https://example.com
 
-# Fail CI if any check regresses by more than 5 points
-ax-audit https://example.com --baseline baseline.json --fail-on-regression 5
-```
+  █████████████████████████████████░░░░░░░  83/100  Good
 
-### Baseline Comparison
+  ── Content — is there substance an agent can read?
 
-Track score changes over time by saving a baseline and comparing against it in subsequent runs:
+  Structured Data (90/100)
+  PASS  3 JSON-LD block(s) found
+  WARN  1 structured-data value(s) do not appear in the visible text
+         💡 Google's one explicit requirement for structured data and AI
+            features is that it match what a reader sees.
 
-```bash
-# First run — save the baseline
-ax-audit https://example.com --save-baseline .ax-baseline.json
+  ── Access — can an agent actually retrieve it?
 
-# Later — compare against the baseline
-ax-audit https://example.com --baseline .ax-baseline.json
-```
+  Agent Access (100/100)
+  PASS  All 10 core AI crawler user-agents receive the same page as a regular client
 
-```
-  AX Audit Report
-  https://example.com
-  Baseline: 2026-04-15T12:00:00.000Z
+  AI Directives (100/100)
+  PASS  Homepage is indexable
+  PASS  No directive restricts how AI assistants may use this page
 
-  ████████████████████████████████░░░░░░░░  82/100  Good  ▲7
+  ── Protocols — what can an agent call?
 
-  LLMs.txt (100/100)  ▲20
-  Robots.txt (70/100)  ▼10
+  MCP Discovery (n/a)
+  PASS  No MCP server — MCP discovery does not apply to this site
   ...
-
-  Regressions
-    Robots.txt: 80 → 70 (▼10)
-
-  Improvements
-    LLMs.txt: 80 → 100 (▲20)
 ```
 
-Works with all output formats (terminal, JSON, HTML). In JSON mode, a `baselineDiff` object is included with per-check deltas.
+## Why
 
-Use `--fail-on-regression <points>` in CI to fail the build if any individual check drops by more than the specified threshold.
+AI agents crawl, cite and act on websites. Lighthouse audits performance, axe-core audits accessibility, and **ax-audit** tells you how ready your site is for agents — discovery files, crawler policy, usage rights, content negotiation, and the failures that are invisible from the inside:
 
-### Batch Mode
+- Your robots.txt allows GPTBot and your firewall returns 403 to it.
+- You blocked `Google-Extended` expecting to leave AI Overviews. It does not do that.
+- Your robots.txt permits AI training while your RSL licence prohibits it, so which terms apply depends on which file a crawler read.
+- Your content only exists after hydration, so the crawlers that do not run JavaScript see an empty page.
+- A missing page answers `200 OK`, so an agent stores the apology as the answer.
 
-Pass multiple URLs to audit them sequentially. Each gets its own full report, followed by a summary table:
+## What it checks
 
-```
-  ═══ Batch Summary ═══
+26 checks across five areas. Full reference: **[docs/checks.md](docs/checks.md)**.
 
-  URL                                     Score       Grade
-  ────────────────────────────────────────────────────────────
-  https://example.com                     92/100    Excellent
-  https://other-site.com                  45/100         Poor
+| Area | Weight | Checks |
+|---|---|---|
+| **Content** — is there substance an agent can read? | 33% | HTML Rendering · Agent Operability · Structured Data · SEO Basics · Content Negotiation |
+| **Access** — can an agent actually retrieve it? | 24% | Agent Access · AI Directives · HTTP Hygiene · TLS/HTTPS · Crawl Efficiency |
+| **Discovery** — can an agent find your machine-readable files? | 21% | Robots.txt · LLMs.txt · HTTP Headers · Sitemap · Meta Tags |
+| **Protocols** — what can an agent call? | 13% | API Discovery · Agent Card · MCP Discovery · Agent Skills · Auth Discovery |
+| **Policy** — what usage rights do you declare? | 9% | Usage Policy · Security.txt · RSL License |
+| Draft specifications, reported but never scored | 0% | AI Catalog · WebMCP · Commerce Discovery |
 
-  2 URLs audited: 1 passed, 1 failed
-  ████████████████████████████░░░░░░░░░░░░  69/100 avg  Fair
-```
+Content leads because the failure that breaks the most agents is a page with nothing in its HTML. Most crawlers do not run JavaScript, so a site whose content appears only after hydration is invisible to them no matter how many discovery files it publishes.
 
-Exit code: `0` if all URLs score >= 70, `1` if any fails.
+Protocol checks are **conditional**: a blog has no API to describe, so those report `n/a` and are excluded from the score rather than counted as failures. Use `--profile` to audit against what a site intends to build.
 
-### HTML Report
+Every finding links to a step-by-step **[remediation guide](https://axrush.com/guides)**.
 
-Generate a self-contained HTML report you can open in any browser or share with your team:
+## Usage
 
 ```bash
-ax-audit https://example.com --output html > report.html
+ax-audit https://example.com                          # full audit, terminal output
+ax-audit https://a.com https://b.com --concurrency 2  # batch, in parallel
+ax-audit https://example.com --output markdown        # also: json, html
+ax-audit https://example.com --checks llms-txt,rsl    # subset of checks
+ax-audit https://example.com --only-failures          # hide passing findings
+ax-audit https://example.com --category access                 # one area only
+ax-audit https://example.com --profile api                     # audit as though it had an API
+ax-audit https://example.com --fail-on-category access:70      # per-area CI gate
+ax-audit https://example.com --baseline .ax-baseline.json --fail-on-regression 5
 ```
 
-Features: circular score gauge, dark/light mode, collapsible check sections, responsive design. Works for both single and batch audits.
+Exit codes gate CI: `0` for score ≥ 70, `1` below. Full flag reference: **[docs/cli.md](docs/cli.md)** · CI recipes (PR comments, regression gates, scheduled audits): **[docs/ci.md](docs/ci.md)**.
 
 ## Programmatic API
 
-Full TypeScript support with all types exported.
-
 ```typescript
 import { audit, batchAudit } from 'ax-audit';
-import type { AuditReport, BatchAuditReport } from 'ax-audit';
-
-// Single URL
-const report: AuditReport = await audit({ url: 'https://example.com' });
-console.log(report.overallScore); // 0-100
-console.log(report.grade.label);  // 'Excellent' | 'Good' | 'Fair' | 'Poor'
-console.log(report.results);      // Individual check results with findings
-
-// Batch audit
-const batch: BatchAuditReport = await batchAudit(
-  ['https://example.com', 'https://other.com'],
-  { timeout: 10000 }
-);
-console.log(batch.summary.averageScore); // Average across all URLs
-console.log(batch.summary.passed);       // Number of URLs scoring >= 70
-```
-
-Also exports `calculateOverallScore`, `getGrade`, `checks`, `saveBaseline`, `loadBaseline`, `diffBaseline`, and `toBaselineData` for advanced usage.
-
-## Scoring
-
-Each check returns a score from 0 to 100. The overall score is a weighted average across all checks.
 
-| Grade | Score | Exit Code |
-|---|---|---|
-| Excellent | 90 - 100 | `0` |
-| Good | 70 - 89 | `0` |
-| Fair | 50 - 69 | `1` |
-| Poor | 0 - 49 | `1` |
-
-Exit codes make it easy to gate CI/CD deployments on AX readiness.
+const report = await audit({ url: 'https://example.com' });
+report.overallScore; // 0–100
+report.results;      // per-check findings
+```
 
-## CI Integration
+Full API and types: **[docs/api.md](docs/api.md)**.
 
-### GitHub Actions
+## Documentation
 
-```yaml
-- name: AX Audit
-  run: npx ax-audit https://your-site.com
-  # Fails the step if score < 70
-```
+Start here:
 
-Save the report as an artifact:
+| Document | Contents |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | First audit, reading the report, fixing in impact order |
+| [docs/concepts.md](docs/concepts.md) | The AX standards landscape — llms.txt, A2A, MCP, RSL, Content Signals, Web Bot Auth |
 
-```yaml
-- name: AX Audit (JSON)
-  run: npx ax-audit https://your-site.com --json > ax-report.json
+Reference:
 
-- uses: actions/upload-artifact@v4
-  with:
-    name: ax-audit-report
-    path: ax-report.json
-```
+| Document | Contents |
+|---|---|
+| [docs/checks.md](docs/checks.md) | All 26 checks with **exact scoring** per finding, the weight table, and the conditional-check rule |
+| [docs/cli.md](docs/cli.md) | Every flag, profiles, area filters, per-area CI gates, baseline workflow |
+| [docs/api.md](docs/api.md) | `audit`, `batchAudit`, baselines, reporters, types, API-stability policy |
+| [docs/ci.md](docs/ci.md) | GitHub Actions recipes: gates, PR comments, scheduled drift detection |
+| [docs/architecture.md](docs/architecture.md) | Pipeline design, check anatomy, how to add a check, scoring policy |
+| [docs/faq.md](docs/faq.md) | Troubleshooting, false positives, the `agent-access` verified-bots caveat |
+| [Remediation guides](https://axrush.com/guides) | Step-by-step fixes for every finding |
 
-Fail on regressions using a committed baseline:
+The same documentation is browsable at [axrush.com/docs](https://axrush.com/docs), rendered from these files. Contributors: see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
 
-```yaml
-- name: AX Audit (regression gate)
-  run: npx ax-audit https://your-site.com --baseline .ax-baseline.json --fail-on-regression 5
-```
-
-## Available Checks
+## Scoring
 
-| Check ID | Use with `--checks` |
-|---|---|
-| `llms-txt` | LLMs.txt spec + Content-Type |
-| `robots-txt` | AI crawler configuration (40+ crawlers) |
-| `html-rendering` | SSR / SPA-shell detection + semantic HTML |
-| `structured-data` | JSON-LD structured data |
-| `http-headers` | Security + AI discovery headers |
-| `agent-json` | A2A Agent Card + same-origin validation |
-| `mcp` | MCP server configuration |
-| `seo-basics` | title / description / canonical / lang / hreflang |
-| `security-txt` | RFC 9116 Security.txt |
-| `meta-tags` | AI meta tags + OpenGraph + Twitter Card |
-| `openapi` | OpenAPI specification |
-| `tls-https` | HTTPS + HTTP→HTTPS redirect + HSTS preload |
-| `sitemap` | sitemap.xml validation + freshness |
-| `well-known-ai` | Emerging AI discovery files |
-| `content-negotiation` | Markdown via `Accept: text/markdown` (informational) |
-
-## Testing
+| Grade | Score | Exit Code |
+|---|---|---|
+| Excellent | 90–100 | `0` |
+| Good | 70–89 | `0` |
+| Fair | 50–69 | `1` |
+| Poor | 0–49 | `1` |
 
-```bash
-npm test
-```
+Checks that do not apply to a site report **n/a** and leave the denominator entirely, rather than scoring 0. A blog is not marked down for having no API to describe. Everything counted against a site is something the site could have done — which is what makes a low score worth acting on.
 
-229 tests covering all 15 checks, the scorer, the HTTP fetcher (against a real local server), baseline comparison, HTML parsing utilities, and edge cases. Uses Node.js built-in test runner (`node:test`), no extra test dependencies.
+`--fail-on-category access:70` gates CI per area, because an overall score can hide an area that is entirely broken while the other four carry it.
 
-## Tech Stack
+## Tech
 
-- **TypeScript** with strict mode
-- **2 runtime dependencies**: `chalk` + `commander`
-- **Node.js 18+** built-in `fetch` (zero HTTP libraries)
-- Parallel check execution via `Promise.allSettled`
-- In-memory request caching per audit run
+TypeScript strict mode · 2 runtime dependencies (`chalk`, `commander`) · Node 18+ built-in `fetch` · no HTML, XML or YAML parser dependencies · parallel checks via `Promise.allSettled` · per-run request cache with `Vary`-aware keys · transient-failure retries with backoff · 873 tests on `node:test` with zero test dependencies.
 
 ## Contributing
 
-Contributions are welcome. To add a new check:
+Contributions are welcome — see **[docs/architecture.md](docs/architecture.md)** for the pipeline design, check anatomy, and the steps (code, tests, docs, remediation guide) a new check requires.
+
+## Related
 
-1. Create `src/checks/your-check.ts` exporting `default` (async check function) and `meta` (CheckMeta)
-2. Use `buildResult(meta, score, findings, start)` from `./utils.js` to return results
-3. Register it in `src/checks/index.ts`
-4. Add its weight to `CHECK_WEIGHTS` in `src/constants.ts`
+- **[ax-init](https://github.com/duranitech/ax-init)** — generate the AX files this tool audits
+- **[ax-cite](https://github.com/duranitech/ax-cite)** — embed AI-extractable structured data in your pages
 
 ## License
 
@@ -299,4 +157,4 @@ Contributions are welcome. To add a new check:
 
 ---
 
-Built by [Lucio Duran](https://lucioduran.com)
+**[AX Rush](https://axrush.com)** — the agent-experience toolkit, by [Durani Technologies](https://github.com/duranitech).

package/dist/baseline.d.ts

@@ -3,6 +3,8 @@ import type { AuditReport, BaselineData, BaselineDiff } from './types.js';
  * Extract a minimal, stable snapshot from an AuditReport suitable for
  * persistence and future comparison.
  */
+/** Scoring model this build produces. Bumped whenever weights or the scoring rules change. */
+export declare const BASELINE_SCHEMA_VERSION = 2;
 export declare function toBaselineData(report: AuditReport): BaselineData;
 /**
  * Persist a baseline to disk as pretty-printed JSON.

package/dist/baseline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAa,MAAM,YAAY,CAAC;AAErF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAWhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAwBvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAsCtF"}
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAa,MAAM,YAAY,CAAC;AAErF;;;GAGG;AACH,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAiBhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAwBvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAkEtF"}