ax-audit 3.1.0 → 3.6.0

package/dist/types.d.ts

@@ -65,6 +65,12 @@ export interface AuditOptions {
     checks?: string[];
     timeout?: number;
     verbose?: boolean;
+    /** Retry attempts for transient fetch failures (timeouts, 5xx, network errors). Default 2. */
+    retries?: number;
+}
+export interface BatchOptions extends Omit<AuditOptions, 'url'> {
+    /** Maximum number of URLs audited in parallel. Default 1 (sequential). */
+    concurrency?: number;
 }
 export interface BatchAuditReport {
     reports: AuditReport[];
@@ -82,7 +88,7 @@ export interface SecurityHeader {
     label: string;
     critical: boolean;
 }
-export type OutputFormat = 'terminal' | 'json' | 'html';
+export type OutputFormat = 'terminal' | 'json' | 'html' | 'markdown';
 /** Minimal snapshot of an audit run stored as the baseline file. */
 export interface BaselineData {
     url: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC;IAC7D,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,KAAK,CAAC;KACd,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAIrE,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,6BAA6B;AAC7B,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,YAAY,EAAE,SAAS,EAAE,CAAC;CAC3B"}

package/docs/api.md

@@ -0,0 +1,200 @@
+# Programmatic API
+
+Full TypeScript support; every public type is exported from the package root.
+
+```typescript
+import { audit, batchAudit } from 'ax-audit';
+import type { AuditReport, BatchAuditReport } from 'ax-audit';
+```
+
+The package is ESM-only (`"type": "module"`), targets Node 18+ (built-in `fetch`), and ships type declarations at `dist/index.d.ts`.
+
+## `audit(options): Promise<AuditReport>`
+
+Runs all (or selected) checks against one URL.
+
+```typescript
+function audit(options: AuditOptions): Promise<AuditReport>;
+
+interface AuditOptions {
+  url: string;          // required, fully qualified (scheme included)
+  checks?: string[];    // default: all. Unknown IDs are silently ignored here
+                        // (the CLI validates them; the API does not)
+  timeout?: number;     // ms per request, default 10000
+  retries?: number;     // transient-failure retries, default 2
+  verbose?: boolean;    // log to stderr, default false
+}
+```
+
+Behavior:
+
+- Checks execute in parallel via `Promise.allSettled`. A check that **throws** becomes a score-0 `CheckResult` whose findings contain the error — `audit` itself never rejects for a check failure.
+- All HTTP requests in a run share an in-memory cache keyed on URL + normalized request headers (`Vary`-aware).
+- The homepage is fetched once and passed to every check as `ctx.html` / `ctx.headers`.
+
+```typescript
+const report = await audit({ url: 'https://example.com' });
+report.overallScore; // number 0–100, weighted
+report.grade;        // { min, label, color }
+report.results;      // CheckResult[]
+report.duration;     // ms
+```
+
+`audit` **rejects** only for an unrecoverable setup error (e.g. an invalid `url` that can't be parsed). Network failure on the homepage fetch does not reject — it surfaces as failing checks.
+
+## `batchAudit(urls, options?): Promise<BatchAuditReport>`
+
+```typescript
+function batchAudit(urls: string[], options?: BatchOptions): Promise<BatchAuditReport>;
+
+interface BatchOptions extends Omit<AuditOptions, 'url'> {
+  concurrency?: number; // max parallel audits, default 1 (sequential)
+}
+```
+
+Report order always matches input order, regardless of `concurrency`. `concurrency < 1` is treated as 1.
+
+```typescript
+const batch = await batchAudit(urls, { concurrency: 4, retries: 2 });
+batch.reports;            // AuditReport[], input order
+batch.summary.total;     // number
+batch.summary.passed;    // count scoring >= 70
+batch.summary.failed;    // count scoring < 70
+batch.summary.averageScore;
+batch.summary.grade;     // Grade for the average
+```
+
+## Result shapes
+
+```typescript
+interface AuditReport {
+  url: string;
+  timestamp: string;        // ISO 8601
+  overallScore: number;     // 0–100
+  grade: Grade;
+  results: CheckResult[];
+  duration: number;         // ms
+}
+
+interface CheckResult {
+  id: string;               // e.g. 'llms-txt'
+  name: string;             // e.g. 'LLMs.txt'
+  description: string;
+  score: number;            // 0–100, clamped
+  findings: Finding[];
+  duration: number;         // ms
+}
+
+interface Finding {
+  status: 'pass' | 'warn' | 'fail';
+  message: string;
+  detail?: string;
+  hint?: string;            // remediation advice (warn/fail)
+  learnMoreUrl?: string;    // link to the matching remediation guide
+}
+
+interface Grade { min: number; label: string; color: string; }
+```
+
+## Scoring
+
+```typescript
+function calculateOverallScore(results: CheckResult[], metas: CheckMeta[]): number;
+function getGrade(score: number): Grade;
+```
+
+`calculateOverallScore` computes the weighted average; it falls back to a plain average when all selected checks have weight 0, and returns 0 for empty input. `getGrade` maps a score to its `Grade`.
+
+## Baselines
+
+```typescript
+function toBaselineData(report: AuditReport): BaselineData;
+function saveBaseline(path: string, report: AuditReport): void;   // writes JSON
+function loadBaseline(path: string): BaselineData;                 // throws on missing/invalid file
+function diffBaseline(baseline: BaselineData, report: AuditReport): BaselineDiff;
+
+interface BaselineData {
+  url: string;
+  timestamp: string;
+  overallScore: number;
+  checks: Record<string, number>; // checkId → score
+}
+
+interface BaselineDiff {
+  url: string;
+  baselineTimestamp: string;
+  currentTimestamp: string;
+  overallPrevious: number;
+  overallCurrent: number;
+  overallDelta: number;
+  checks: CheckDiff[];
+  regressions: CheckDiff[];   // delta < 0
+  improvements: CheckDiff[];  // delta > 0
+}
+```
+
+`loadBaseline` throws (does not return null) on a missing file or invalid JSON — wrap it in try/catch. Checks present now but absent from the baseline appear as new (no delta); checks removed since are ignored.
+
+## Reporters
+
+```typescript
+function renderMarkdown(report: AuditReport, diff?: BaselineDiff): string;
+function renderBatchMarkdown(batch: BatchAuditReport): string;
+```
+
+Both return a Markdown string (summary table + findings with status emoji; baseline deltas when a diff is passed). Terminal and HTML rendering are CLI-internal; for other formats, consume the `AuditReport` JSON directly.
+
+## Checks registry
+
+```typescript
+import { checks } from 'ax-audit';
+
+interface CheckModule {
+  run: (ctx: CheckContext) => Promise<CheckResult>;
+  meta: CheckMeta; // { id, name, description, weight }
+}
+```
+
+Run an individual check with a custom context:
+
+```typescript
+const llms = checks.find((c) => c.meta.id === 'llms-txt')!;
+const result = await llms.run({
+  url: 'https://example.com',   // no trailing slash
+  html: homepageHtml,
+  headers: homepageHeaders,     // lowercased keys
+  fetch: myFetchImpl,
+});
+
+interface CheckContext {
+  url: string;
+  html: string;
+  headers: Record<string, string>;
+  fetch: (url: string, options?: FetchOptions) => Promise<FetchResponse>;
+}
+
+interface FetchOptions { headers?: Record<string, string>; }
+
+interface FetchResponse {
+  status: number;   // 0 on network error
+  headers: Record<string, string>; // lowercased keys
+  body: string;
+  ok: boolean;
+  url: string;      // final URL after redirects
+  error?: string;   // set when status === 0
+}
+```
+
+`ctx.fetch` custom headers merge case-insensitively over the defaults (a custom `Accept` or `User-Agent` replaces the default), and responses are cached per URL + normalized headers — mirroring HTTP `Vary`. Your `fetch` implementation should never throw; model failures as `{ status: 0, ok: false, error }`.
+
+## API stability
+
+Within a major version, the exported function signatures and the `AuditReport` JSON shape are stable. Specifically:
+
+- **Stable:** `audit`, `batchAudit`, `calculateOverallScore`, `getGrade`, the baseline functions, the reporter functions, and all exported type *shapes*.
+- **May change in minor versions:** the *set* of checks (new checks are added), individual check `score`/`findings` content, and check `weight` values (new checks start at 0; reweighting is reserved for majors). Treat `results` as a list to iterate, not a fixed-length tuple.
+- **Internal:** anything not exported from `src/index.ts`, including terminal/HTML reporters and individual check modules' internals.
+
+## Exported types
+
+`AuditOptions`, `BatchOptions`, `AuditReport`, `BatchAuditReport`, `CheckResult`, `CheckMeta`, `CheckContext`, `CheckModule`, `Finding`, `FindingStatus`, `FetchOptions`, `FetchResponse`, `Grade`, `OutputFormat`, `BaselineData`, `BaselineDiff`, `CheckDiff`.

package/docs/architecture.md

@@ -0,0 +1,88 @@
+# Architecture
+
+ax-audit is a dependency-light TypeScript codebase: two runtime dependencies (`chalk`, `commander`), Node 18+ built-in `fetch`, no HTTP libraries, no XML/HTML parser dependencies (regex-based primitives), and the built-in `node:test` runner.
+
+## Pipeline
+
+```
+cli.ts ──► orchestrator.ts ──► checks/* (Promise.allSettled, parallel)
+              │                     │
+              ▼                     ▼
+          fetcher.ts            scorer.ts ──► reporter/{terminal,json,html,markdown}
+        (cache + retries)                          │
+              ▲                                baseline.ts (save / load / diff)
+              └── shared by every check via CheckContext.fetch
+```
+
+1. **cli.ts** parses and validates flags, loads the baseline if requested, and dispatches to single or batch mode.
+2. **orchestrator.ts** (`audit`) creates one fetcher per run, fetches the homepage once, builds the `CheckContext` (`url`, `html`, `headers`, `fetch`), and runs all selected checks in parallel. A check that throws is converted into a score-0 result with the error as a finding — one bad check never kills the audit. `batchAudit` runs `audit` per URL through an order-preserving work queue with configurable `concurrency`.
+3. **fetcher.ts** wraps `fetch` with: per-run in-memory caching keyed on URL + normalized (lowercased, sorted) custom headers — mirroring HTTP `Vary` semantics so a `text/markdown` probe never collides with the HTML fetch; case-insensitive header merging over defaults; timeouts via `AbortController`; and retries with exponential backoff for transient failures (status 0, 408, 425, 429, 5xx). Errors never throw — they become `{ status: 0, ok: false, error }` results, also cached.
+4. **checks/** — one module per check (18). Each exports `default` (async check function) and `meta` (`{ id, name, description, weight }`).
+5. **scorer.ts** computes the weighted average; when all selected checks have weight 0 it falls back to a plain average.
+6. **reporter/** renders to terminal (chalk), JSON, self-contained HTML, or Markdown.
+7. **baseline.ts** persists minimal score snapshots and computes per-check diffs for regression gating.
+
+## Anatomy of a check
+
+```typescript
+import { guideUrl } from '../guide-urls.js';
+import type { CheckContext, CheckResult, CheckMeta, Finding } from '../types.js';
+import { buildResult } from './utils.js';
+
+export const meta: CheckMeta = {
+  id: 'my-check',
+  name: 'My Check',
+  description: 'One-line description shown in reports',
+  weight: 0, // new checks start informational in 3.x
+};
+
+export default async function check(ctx: CheckContext): Promise<CheckResult> {
+  const start = performance.now();
+  const findings: Finding[] = [];
+  let score = 100;
+
+  const res = await ctx.fetch(`${ctx.url}/something`, { headers: { Accept: 'application/json' } });
+  if (!res.ok) {
+    findings.push({
+      status: 'fail',
+      message: '/something not found',
+      hint: 'Actionable, copy-pasteable advice.',
+      learnMoreUrl: guideUrl(meta.id, 'not-found'),
+    });
+    return buildResult(meta, 0, findings, start);
+  }
+
+  // ... validations, each pushing a pass/warn/fail Finding and adjusting score
+
+  return buildResult(meta, score, findings, start);
+}
+```
+
+Conventions:
+
+- **Findings are actionable.** Every `warn`/`fail` carries a `hint` with concrete remediation and a `learnMoreUrl` pointing to `lucioduran.com/projects/ax-audit/guides/<check-id>#<anchor>`. Every anchor must have a section in that guide.
+- **Scores are clamped** to [0, 100] by `buildResult`.
+- **Shared HTML primitives** live in `checks/html-utils.ts` (`getMetaContent`, `findLinkTags`, `getAttribute`, `extractVisibleText`, …) — no per-check regex duplication.
+- **Content-Type validation** uses `checkContentType` from `checks/utils.ts` (−5 convention for mismatches).
+- **Network goes through `ctx.fetch`** — never raw `fetch` — so caching, retries, timeouts, and `--verbose` logging apply uniformly.
+
+## Adding a new check
+
+1. Create `src/checks/your-check.ts` exporting `default` + `meta` (weight 0 — see scoring policy below).
+2. Register it in `src/checks/index.ts`.
+3. Add its weight to `CHECK_WEIGHTS` in `src/constants.ts`.
+4. Add a test suite in `test/checks/your-check.test.js` using `mockContext` / `mockResponse` from `test/helpers.js`. Route values can be functions `(url, fetchOptions) => response` when the response must vary by request headers.
+5. Document it in `docs/checks.md` and the README table.
+6. Write the remediation guide covering every `learnMoreUrl` anchor you emit.
+
+## Scoring policy (3.x)
+
+Score deltas on the same site are treated as **breaking** (see CHANGELOG 3.0.0). Therefore in 3.x:
+
+- New checks ship with **weight 0** (informational): full findings, no effect on the overall score or baselines.
+- New findings inside weighted checks must be informational (no score deduction) — see the Content Signals findings in `robots-txt`.
+- Weight redistribution happens in major versions (v4.0).
+
+## Testing
+
+`npm test` builds (`tsc`) and runs `node --test`. The suite (301 tests) covers every check, the scorer, baseline logic, the Markdown reporter, plus integration tests that spin up real local HTTP servers for the fetcher (per-header caching, retries) and the batch orchestrator (ordering, concurrency caps). No test dependencies beyond Node.

package/docs/checks.md

@@ -0,0 +1,322 @@
+# Checks Reference
+
+ax-audit runs 18 checks. Fourteen are **weighted** (summing to 100% of the overall score); four are **informational** in 3.x — they run and report findings but carry weight 0 until v4.0, because score-affecting changes are treated as breaking (see [CHANGELOG 3.0.0](../CHANGELOG.md)).
+
+This page documents the **exact scoring** of every check: each deduction, bonus, and formula, extracted from the source. Every finding links to a step-by-step remediation guide at `lucioduran.com/projects/ax-audit/guides/<check-id>`.
+
+**Reading the tables:** each check starts at 100 unless noted. Deductions stack additively; `buildResult` clamps the final score to [0, 100]. "Hard fail" rows short-circuit the check.
+
+---
+
+## Weighted checks
+
+### `llms-txt` — 11%
+
+`/llms.txt` presence and [llmstxt.org](https://llmstxt.org) spec compliance.
+
+| Condition | Points |
+| --- | --- |
+| `/llms.txt` not found | **hard fail → 0** |
+| Wrong Content-Type (expected `text/plain` or `text/markdown`) | −5 |
+| First line is not an H1 (`# `) | −15 |
+| No blockquote description (`> `) | −10 |
+| No `##` section headings | −10 |
+| No Markdown links | −10 |
+| Content under 100 characters | −10 |
+| `/llms-full.txt` also available | **+10** (capped at 100) |
+
+### `robots-txt` — 11%
+
+AI-crawler configuration. Core crawlers: GPTBot, ClaudeBot, ChatGPT-User, Claude-SearchBot, Google-Extended, PerplexityBot, OAI-SearchBot, CCBot.
+
+| Condition | Points |
+| --- | --- |
+| `/robots.txt` not found | **hard fail → 0** |
+| No core AI crawler explicitly configured | −40 |
+| Some core crawlers missing | −`round(missing/8 × 30)` |
+| Core crawler(s) blocked only via `User-agent: *` + `Disallow: /` | −5 per crawler |
+| Known AI crawler(s) explicitly blocked (`Disallow: /`) | −3 per crawler |
+| No `Sitemap:` directive | −5 |
+| Partial path restrictions on AI crawlers | warn only, 0 |
+| [Content Signals](https://contentsignals.org) findings (declared / malformed / unknown / missing) | informational, 0 in 3.x |
+
+### `html-rendering` — 9%
+
+Whether the static HTML contains content — most AI crawlers do not execute JavaScript. Thresholds: 500 chars / 80 words of visible text, 5% text-to-markup ratio.
+
+| Condition | Points |
+| --- | --- |
+| No HTML body returned | **hard fail → 0** |
+| Zero visible text in static HTML | −50 |
+| Sparse content (< 500 chars or < 80 words) | −25 |
+| Text-to-markup ratio < 5% | −10 |
+| Empty SPA mount point (`#root`, `#__next`, `#__nuxt`, `#app`, `#svelte`, `#gatsby`) | −20 |
+| 0 semantic landmarks (`<main>`, `<article>`, `<header>`, `<footer>`, `<nav>`) | −15 |
+| 1–2 semantic landmarks | −10 |
+| No `<h1>` | −10 |
+| Multiple or empty `<h1>` | −5 |
+| > 15 executable scripts without `<noscript>` fallback | −5 |
+| `<img alt>` coverage < 90% | −5 |
+
+### `structured-data` — 9%
+
+JSON-LD on the homepage. Key entity types: Person, Organization, WebSite, WebPage, ProfilePage.
+
+| Condition | Points |
+| --- | --- |
+| No JSON-LD blocks | **hard fail → 0** |
+| Every JSON-LD block has invalid JSON | **→ 10** |
+| Invalid JSON in a block | −10 per block |
+| No schema.org `@context` | −15 |
+| No key entity types found | −15 |
+| Only one key entity type | −10 |
+| No `@graph` array | −5 |
+| No `BreadcrumbList` | −5 |
+
+### `http-headers` — 9%
+
+Security headers, AI discovery `Link` headers (RFC 5988-parsed), CORS on `.well-known`.
+
+| Condition | Points |
+| --- | --- |
+| No headers retrievable | **hard fail → 0** |
+| Missing critical security header (HSTS, X-Content-Type-Options) | −10 each |
+| Only 1–3 of the 7 tracked security headers present | −5 |
+| `Link` header missing both llms.txt and agent.json references | −15 |
+| `Link` header missing one of the two | −5 |
+| No CORS on `/.well-known/agent.json` | −10 |
+
+### `agent-json` — 7%
+
+`/.well-known/agent.json` [A2A Agent Card](https://a2a-protocol.org). Required fields: `name`, `description`, `url`, `skills`.
+
+| Condition | Points |
+| --- | --- |
+| Not found | **hard fail → 0** |
+| Invalid JSON | **→ 10** |
+| Wrong Content-Type (expected `application/json`) | −5 |
+| Missing required field | −15 per field |
+| `url` on a different origin | −5 |
+| `url` not an absolute URL | −5 |
+| `skills` empty | −10 |
+| `skills` entries missing `id` or `description` | −5 |
+| No `protocolVersion` | −5 |
+| No optional fields (`capabilities`, `authentication`, `documentationUrl`) | −5 |
+
+### `mcp` — 7%
+
+`/.well-known/mcp.json` [Model Context Protocol](https://modelcontextprotocol.io) server configuration.
+
+| Condition | Points |
+| --- | --- |
+| Not found | **hard fail → 0** |
+| Invalid JSON | **→ 10** |
+| Wrong Content-Type | −5 |
+| Missing `name` | −10 |
+| Missing `description` | −5 |
+| No `tools` array, or empty | −15 |
+| No tool has a description | −10 |
+| Some tools missing descriptions | −5 |
+| No `resources` | −5 |
+| No protocol version | −5 |
+| No CORS headers | −10 |
+
+### `seo-basics` — 7%
+
+Head-tag fundamentals. Bounds: title 20–70 chars, description 70–160.
+
+| Condition | Points |
+| --- | --- |
+| Homepage HTML unavailable | **hard fail → 0** |
+| `<title>` missing or empty | −25 |
+| Title too short / too long | −10 / −5 |
+| Meta description missing | −20 |
+| Description too short / too long | −8 / −5 |
+| Description duplicates the title | −5 |
+| No canonical link | −10 |
+| Multiple canonicals / missing href / relative href | −5 each |
+| `<html lang>` missing / invalid BCP 47 | −10 / −5 |
+| No UTF-8 charset | −5 |
+| Missing viewport | −5 |
+| hreflang present without `x-default` | −3 |
+
+### `security-txt` — 6%
+
+`/.well-known/security.txt` per [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116).
+
+| Condition | Points |
+| --- | --- |
+| Not found | **hard fail → 0** |
+| Missing `Contact` or `Expires` | −25 per field |
+| `Expires` in the past | −20 |
+| No optional fields (Canonical, Preferred-Languages, Policy, Encryption, Hiring) | −5 |
+
+### `meta-tags` — 6%
+
+AI meta tags (`ai:summary`, `ai:content_type`, `ai:author`, `ai:api`, `ai:agent_card`), discovery links, Open Graph, Twitter Card.
+
+| Condition | Points |
+| --- | --- |
+| Homepage HTML unavailable | **hard fail → 0** |
+| 0 AI meta tags | −18 |
+| Only 1–2 AI meta tags | −12 |
+| No `rel="alternate"` → llms.txt | −12 |
+| No `rel="alternate"` → agent.json | −8 |
+| No `rel="me"` identity links | −8 |
+| No Open Graph tags at all | −12 |
+| OG required incomplete (`og:title`, `og:description`, `og:url`, `og:type`) | −8 |
+| OG recommended incomplete (`og:image`, `og:site_name`) | −3 |
+| No Twitter Card tags at all | −6 |
+| Twitter required incomplete (`twitter:card`, `twitter:title`, `twitter:description`) | −5 |
+| Twitter recommended incomplete (`twitter:image`) | −2 |
+
+### `openapi` — 6%
+
+`/.well-known/openapi.json`.
+
+| Condition | Points |
+| --- | --- |
+| Not found | **hard fail → 0** |
+| Invalid JSON | **→ 10** |
+| Wrong Content-Type | −5 |
+| No `openapi`/`swagger` version field | −20 |
+| Swagger 2.x instead of OpenAPI 3.x | −10 |
+| Missing `info.title` | −10 |
+| Missing `info.description` | −5 |
+| No `paths` documented | −15 |
+| No `servers` | −5 |
+
+### `tls-https` — 5%
+
+HTTPS, redirect, HSTS. Thresholds: max-age ≥ 15,768,000s (~6 months), preload ≥ 31,536,000s (1 year).
+
+| Condition | Points |
+| --- | --- |
+| Invalid URL | **hard fail → 0** |
+| Served over plain HTTP | −50 |
+| HTTP does not redirect to HTTPS | −15 |
+| Redirect unverifiable | −5 |
+| No HSTS header | −15 |
+| HSTS without `max-age` | −10 |
+| `max-age` < 6 months | −5 |
+| No `includeSubDomains` | −5 |
+| `preload` present but ineligible | −5 |
+| No `preload` directive | −3 |
+
+### `sitemap` — 4%
+
+Located via robots.txt `Sitemap:` or `/sitemap.xml`. Limits: 50,000 URLs / 50 MB / 365-day freshness.
+
+| Condition | Points |
+| --- | --- |
+| No sitemap found | **hard fail → 0** |
+| Response is not XML | **→ 20** |
+| Over 50 MB | −10 |
+| Unexpected Content-Type | −5 |
+| Sitemap index with no `<sitemap>` entries | −20, stop |
+| Some sampled child sitemaps unreachable | −10 |
+| `<urlset>` with no `<url>` entries | −30 |
+| Over 50,000 URLs declared | −10 |
+| `<lastmod>` coverage < 50% | −5 |
+| Newest `<lastmod>` older than 365 days | −5 |
+
+### `well-known-ai` — 3%
+
+Emerging AI discovery files. **Purely proportional** — no deductions:
+
+```
+score = round(present / 5 × 100)
+```
+
+over `/.well-known/ai.txt` (Spawning), `/.well-known/genai.txt`, `/ai-plugin.json`, `/agents.json`, `/.well-known/nlweb.json`. Files with invalid content produce warnings without counting as present.
+
+---
+
+## Informational checks (weight 0 in 3.x)
+
+These run on every audit and report full findings, but do not affect the overall score or baselines. They gain weight in v4.0.
+
+### `content-negotiation` — Markdown for Agents
+
+Probes the homepage with `Accept: text/markdown` — the pattern served by Cloudflare and Vercel and requested by Claude Code, Cursor, and OpenCode (~80% token reduction vs HTML).
+
+| Condition | Points |
+| --- | --- |
+| Probe request fails (network) | **hard fail → 0** |
+| No Markdown served, no fallback | **→ 0** |
+| No Markdown served, but `<link rel="alternate" type="text/markdown">` present | **→ 40** |
+| Markdown served (correct Content-Type, 2xx) | base 100 |
+| Body is empty | −30 |
+| Body is a relabeled HTML document | −25 |
+| `Vary` does not include `Accept` | −15 |
+| Markdown not smaller than HTML | warn only, 0 |
+
+### `rsl` — Really Simple Licensing
+
+[RSL 1.0](https://rslstandard.org/rsl) discovery (robots.txt `License:`, `Link: rel="license"` header, `<link rel="license" type="application/rsl+xml">`) and document validation. Plain CC-style license links without the RSL media type are ignored.
+
+| Condition | Points |
+| --- | --- |
+| No discovery mechanism found | **hard fail → 0** |
+| License document unreachable | **→ 25** (cap) |
+| Root `<rsl>` element missing | −40, stop |
+| No `<content>` elements | −20, stop |
+| Wrong or missing `https://rslstandard.org/rsl` namespace | −15 |
+| `<license>` elements missing | −15 |
+| robots.txt `License:` not an absolute URI | −10 |
+| `<content>` missing required `url` attribute | −10 |
+| Wrong Content-Type (expected `application/rsl+xml`) | −5 |
+| `permits`/`prohibits` with invalid `type` | −5 |
+| Tokens outside the RSL 1.0 vocabulary (incl. pre-1.0 draft tokens) | −5 |
+| Invalid `payment` type | −5 |
+
+### `agent-access` — Cloaking detection
+
+Probes the homepage with realistic UAs for the 8 core AI crawlers and compares status + visible text against the default-UA baseline. **Credit-ratio formula:**
+
+```
+score = round(credit / 8 × 100)
+```
+
+| Outcome per crawler | Credit |
+| --- | --- |
+| Equivalent response | 1 |
+| Blocked, consistent with robots.txt `Disallow` (explicit or wildcard) | 1 |
+| 200 but < 50% of baseline visible text (baseline ≥ 200 chars) | 0.5 |
+| Blocked while robots.txt allows (or doesn't restrict) it | 0 |
+| Baseline request itself fails | **hard fail → 0** |
+
+Caveat: WAFs using Web Bot Auth / IP verification may pass the real crawler while rejecting this unverified probe — confirm against WAF logs before changing rules.
+
+### `crawl-efficiency`
+
+| Condition | Points |
+| --- | --- |
+| Homepage request fails | **hard fail → 0** |
+| Uncompressed response | −30 |
+| gzip/deflate/zstd instead of Brotli | pass with suggestion, 0 |
+| No `ETag` / `Last-Modified` validator | −30 |
+| Validator present but conditional request not answered with `304` | −15 |
+| Page > 2 MB decompressed | −10 |
+| Page > 500 KB decompressed | −5 |
+
+---
+
+## Overall scoring model
+
+Each check returns 0–100. The overall score is the weighted average across the checks that ran:
+
+```
+overall = round( Σ (score_i / 100 × weight_i) / Σ weight_i × 100 )
+```
+
+When every selected check has weight 0 (e.g. `--checks rsl`), the overall falls back to a plain average of check scores.
+
+| Grade | Score | Exit code |
+| --- | --- | --- |
+| Excellent | 90–100 | 0 |
+| Good | 70–89 | 0 |
+| Fair | 50–69 | 1 |
+| Poor | 0–49 | 1 |
+
+Weights live in `src/constants.ts` (`CHECK_WEIGHTS`); a check's own `meta.weight` takes precedence. The scoring policy for 3.x — why new checks ship at weight 0 — is documented in [architecture.md](./architecture.md).