readiness-audit 1.2.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.1.0 (2026-10-23)
4
+
5
+ From a project's agent that checked pages in Google's Rich Results Test by hand. The standard asked for it ("accepts a sample") without saying which pages, and the scorecard never mentioned it. No scoring changes.
6
+
7
+ - **The scorecard lists the pages to run through Google's Rich Results Test,** each with a link that opens it in the test: the homepage, one page of each template with rich-result markup, and any other page that adds a rich-result feature. Pages from one template share their markup, so one tests them all. The CLI prints them under W4 in "check these yourself", the JSON report has `rich_results_test`, and the status page has a section for them. The rich-result types are those in Google's search gallery (updated 2026-10-16).
8
+ - **STANDARD.md:** W4 says which pages to test and when (after a change to a template's markup), when to use the Schema Markup Validator instead, and that valid means eligible, not shown. Its done-when is no errors on the listed pages. T6's monthly review checks Search Console's rich result reports, which cover every indexed page. §16 cites the search gallery, both testing tools, the reports and the URL Inspection API.
9
+
10
+ ## 2.0.0 (2026-10-21)
11
+
12
+ From an adopting agent's review: a full score showed a site was set up correctly, not that agents did better on it, and the default run graded content sites on an API they don't have. This release makes the score fit the site, checks more of what agents and link previews actually read, and gives T5 and the traffic numbers a recorded form. Pin `readiness-audit@2`.
13
+
14
+ **Checks that can newly fail** (why this is a major version):
15
+ - **W1 to W6 sample by page type.** URLs are grouped by template (the first path segment plus the depth): every static page is read (groups of 20 or fewer), and three pages of each generated template, up to 40 pages. Each W line says what it read, and when the cap left static pages out. A sample spread evenly through the sitemap had read under one static page on sites that are mostly generated pages, and the static pages are where layouts leak metadata. Any existing W rule can now fail on them. At animalhouse this found 11 descriptions over 160 characters and 11 pages showing the homepage's X card that 1.2.1 had passed. W3's missing-item probe goes under each template, and W4's breadcrumbs are judged on template pages.
16
+ - **D2 reads the pages' dates on a sitemap index.** It counted the sub-sitemaps' own `lastmod` dates. The sitemap is now read once, every sub-sitemap up to ten (the W checks read three), and D2 and the W checks share it.
17
+ - **W5 fails when a page's share card shows another page's text.** It reads what each platform shows: on X, `twitter:title` and `twitter:description`, falling back to `og:`; on Facebook and LinkedIn, `og:`. Shared text counts against a page when it isn't the page's own (its `<title>` or meta description), and belongs to the homepage when it matches no page. Next.js merges metadata shallowly, so a page that sets `openGraph` but not `twitter` keeps the root layout's Twitter title and description. animalhouse found this by sharing links, after W5 had passed; inbed.ai has it too.
18
+ - **The API checks run whenever a site has or declares an API,** and `--no-api` is gone. They run when `/openapi.json` or `/api` answers, or a `service-desc` link, an API catalog or llms.txt names an API; a declared API that doesn't answer fails A1. A site with neither skips them, as a site with no hosted MCP endpoint skips the MCP checks. Drop `--no-api` from your commands; an unknown flag is ignored.
19
+ - **Node 26 or later.** Node 20 reached end of life on 2026-04-30, and Node's 2026-10-21 security release fixed a Brotli decoder bug that could run code (CVE-2026-111497) and two TLS hostname bypasses. Use 26.12.1 or later. The CLI exits with a message on an older major, since `engines` only warns.
20
+
21
+ **New warnings:**
22
+ - **W6** warns when heading levels skip going down (an `h1` followed by an `h3`).
23
+ - **D4** reports llms.txt links that redirect: link the destination.
24
+ - **D5 asks for `service-desc` and `api-catalog` only on a site with an API.** A site with none needs only `describedby`, since a `service-desc` naming an OpenAPI document would declare one.
25
+ - **D8** compares the first page llms.txt links that serves markdown with its markdown copy, and warns about sections the copy lacks; the pass line says when no linked page serves markdown. The homepage's markdown may be llms.txt, so it isn't compared.
26
+
27
+ **New:**
28
+ - **`--logs <file>`** counts requests for the discovery files in an exported access log (combined log format, or JSON lines from Cloudflare Logpush, Vercel or Railway), by client family, and how many readers of each file also called the API. It prints counts, never addresses, and names the audit's own requests as their own family. Its paths are the audit's own list, so the two can't drift.
29
+ - **The report and status page** say whether a site has a public API (`has_api`, a "Public API" row), and the report gives the sampled pages' median HTML size (`html_kb_median`, also in W6's line). Size isn't scored.
30
+ - **T5 is recorded as fields:** `attempts`, `first_try`, `model`, `max_turns`, `median_calls`, `stops`, `cost_usd`, `date`. Convert a free-text T5 `result`.
31
+ - **The T5 runner** ends with each attempt's `RESULT`, turns and cost, and a T5 entry to finish by hand. It also no longer exits silently before the first attempt: under `pipefail`, the random test name's `tr` ended on SIGPIPE, which stopped the script.
32
+ - **Every request goes through `node:http(s)`, not `fetch`.** `fetch` decodes a Brotli body even when the request didn't ask for one, so an audited site could hand any body to the decoder. The audit asks for gzip or deflate, decodes those itself, and refuses any other encoding. W3 fails a sampled page whose body it refused, once, rather than every W check reporting its tags missing. One function now sends every request, with one user agent and one 15-second timeout.
33
+ - **Releases run CI first,** on Node 26, and npm is pinned to major 12 in the publish step. Dependabot watches the GitHub Actions weekly.
34
+
35
+ **STANDARD.md:**
36
+ - W3: retiring a page (a permanent redirect to what replaced it, out of every discovery file in the same change, a test that it keeps redirecting).
37
+ - W4: a visible date matches the structured one (Google's publication-dates guidance).
38
+ - W5: every page's card shows its own title and description; the homepage's copy belongs on the homepage, not the root layout. §12's `twitter:title` gotcha names the Next.js cause.
39
+ - W6: heading levels don't skip (W3C's headings tutorial); the median HTML size, reported and not scored.
40
+ - D8: a page's markdown copy has the page's sections.
41
+ - §11: guard tests for the sitemap against the routes ([recipe](docs/recipes.md#the-sitemap-equals-the-routes-t4-w3)), markdown copies against their pages, retired URLs, and every page's own metadata; "No stale claims" covers page copy and skill files, and S1 points to it.
42
+ - T6: record the top queries with their landing pages (`queries` in `recorded.json`), reviewed by hand, not scored.
43
+ - §12: inline elements with no space between them fuse into one word.
44
+ - T3: classify traffic before counting it; a browser, headless or unidentified client counts as an agent only when something backs it up, such as calling the API.
45
+ - W7: anchors say what the target is in searched-for words, not the brand name alone, with the brand in plain text beside them, and are true of the page they open. From animalhouse, where an agent linked sibling sites by brand name.
46
+ - E6: link siblings in context with W7's anchors; never sitewide or on a partner page, which Google's spam policies call link schemes.
47
+ - Considered and left out: in-page anchors, favicon versioning, prerendering and view transitions.
48
+ - §12: the SDK v1 gotcha was re-checked on 1.32.1. §16: N6 cites the 2026-07-28 spec.
49
+ - §16: Next.js metadata merging, Google on redirects and on publication dates.
50
+
3
51
  ## 1.2.1 (2026-10-06)
4
52
 
5
53
  Principle 7 told skills to have the agent confirm with its person before registering, publishing or rotating a key, and S1 required it of every skill that publishes. That gates the core loop: an agent following it can't finish on its own, and a skill limited to explicit requests isn't used when it would help. No scoring changes.
package/README.md CHANGED
@@ -15,27 +15,30 @@ AI agents find a site through discovery files, MCP registries, skills and search
15
15
  npx readiness-audit example.com
16
16
  ```
17
17
 
18
- It needs Node 20 or later and has no dependencies. It only reads: GET requests, plus a few POSTs that create nothing (an MCP `initialize`, `server/discover` and `tools/list`, and an empty POST to `/`). It keeps to about six requests at a time, and it won't follow a link the site supplies (in its sitemap, share images, skills, catalog or DNS record) to a private or local address, at any redirect. It prints a pass, warning or failure for each check, with the reason, and exits with code 1 when a required check fails, so it can gate a deploy.
18
+ It needs Node 26 or later, with current security releases, and has no dependencies. It only reads: GET requests, plus a few POSTs that create nothing (an MCP `initialize`, `server/discover` and `tools/list`, and an empty POST to `/`). It keeps to about six requests at a time, and it won't follow a link the site supplies (in its sitemap, share images, skills, catalog or DNS record) to a private or local address, at any redirect. It asks for gzip and decodes it itself; a body in an encoding it didn't ask for, such as Brotli, is reported rather than read, so a site can't reach a decoder bug on the machine running the audit. It prints a pass, warning or failure for each check, with the reason, and exits with code 1 when a required check fails, so it can gate a deploy.
19
19
 
20
20
  ```
21
- readiness-audit <domain> [--mcp /path] [--no-mcp] [--no-api] [--json] [--compare previous] [--base url]
21
+ readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
22
22
  readiness-audit --matrix <domain> <domain> ... [--recorded results.json]
23
+ readiness-audit --logs <access-log> [--json]
23
24
  ```
24
25
 
25
26
  | Option | What it does |
26
27
  |---|---|
27
28
  | `--mcp /path` | where your hosted MCP endpoint lives (default `/mcp`) |
28
29
  | `--no-mcp` | skip the hosted MCP checks |
29
- | `--no-api` | skip the API checks, for a site with no public API |
30
30
  | `--json` | print the results as JSON |
31
31
  | `--compare file` | list what changed since a previous run: a status page from `--matrix` or a saved `--json` report |
32
32
  | `--base url` | score a local or preview build as the domain before you deploy (`--base http://localhost:3000`); DNS and host redirects are skipped |
33
33
  | `--matrix` | score several sites and print a markdown status page |
34
34
  | `--recorded file` | with `--matrix`, add your recorded T5 and T6 results (format: [examples/recorded.json](examples/recorded.json)) |
35
+ | `--logs file` | count requests for the discovery files in an exported access log (combined log format, or JSON lines from Cloudflare, Vercel or Railway), by client family. It prints counts, never addresses |
36
+
37
+ The API checks run when `/openapi.json` or `/api` answers, or when the site declares an API (a `service-desc` link, an API catalog, an API link in llms.txt). A declared API that doesn't answer fails them. A site with neither skips them, the way a site with no hosted MCP endpoint skips the MCP checks.
35
38
 
36
39
  From a clone, run `node bin/readiness-audit.mjs example.com`.
37
40
 
38
- To check fixes before they ship, score a local build: `npx readiness-audit@1 example.com --base http://localhost:3000`. The site's own URLs (from its sitemap, llms.txt, skills and catalog) are requested from the base and reported under the domain. A private address is allowed for `--base` because you chose it; anything else the site links to still has to be public.
41
+ To check fixes before they ship, score a local build: `npx readiness-audit@2 example.com --base http://localhost:3000`. The site's own URLs (from its sitemap, llms.txt, skills and catalog) are requested from the base and reported under the domain. A private address is allowed for `--base` because you chose it; anything else the site links to still has to be public.
39
42
 
40
43
  ## What it checks, and what it can't
41
44
 
@@ -43,17 +46,19 @@ The scorecard covers what's visible from outside. It checks:
43
46
  - robots.txt, the sitemap and llms.txt;
44
47
  - security.txt and the honesty of the A2A path;
45
48
  - false declarations;
46
- - a sample of up to 20 pages for titles, canonical URLs, indexability, structured data, link previews and page structure;
49
+ - up to 40 pages for titles, canonical URLs, indexability, structured data, link previews and page structure: every static page, and three pages of each generated template (a group of more than 20 URLs with the same first segment and depth);
47
50
  - the OpenAPI document and the API's error answers;
48
51
  - the hosted MCP edge and the MCP tools;
49
52
  - a sample of skill files: spec names and descriptions, and links to llms.txt and the API reference;
50
53
  - markdown negotiation, the AI catalog, the DNS AID record, the API catalog, auth.md and the skills index.
51
54
 
55
+ It also lists the pages to run through Google's Rich Results Test (W4), with a link that opens each one in the test: the homepage, one page of each template with rich-result markup, and any page that adds a rich-result feature. The scorecard checks that markup parses; Google's test checks each rich result's required properties.
56
+
52
57
  It can't see whether `next_steps` guide well, whether input is forgiving, whether an agent can follow your skills through the core loop, or whether you have tests. The standard marks those items "review" or "test". The agent usability test (T5) measures what all of it is for: whether a fresh agent, given only your domain and a goal, succeeds. [docs/usability-test.md](docs/usability-test.md) has the procedure and a runner. A high score is not the goal.
53
58
 
54
59
  ## Use it in your project
55
60
 
56
- Point to [STANDARD.md](STANDARD.md) from your repo instead of copying it (§14 has a short stub), and pin the scorecard to a major version: `npx readiness-audit@1 <domain>`. To run it on a schedule in GitHub Actions, see [examples/github-action.yml](examples/github-action.yml).
61
+ Point to [STANDARD.md](STANDARD.md) from your repo instead of copying it (§14 has a short stub), and pin the scorecard to a major version: `npx readiness-audit@2 <domain>`. To run it on a schedule in GitHub Actions, see [examples/github-action.yml](examples/github-action.yml).
57
62
 
58
63
  To switch a project over, point its coding agent at [docs/adopting.md](docs/adopting.md): step-by-step instructions, with lessons from the first project that did it.
59
64
 
package/STANDARD.md CHANGED
@@ -5,7 +5,7 @@
5
5
  **Last verified:** 2026-10-05
6
6
 
7
7
  > **Start here**
8
- > 1. Score your site: `npx readiness-audit <domain>`. It needs Node 20 or later and no dependencies.
8
+ > 1. Score your site: `npx readiness-audit <domain>`. It needs Node 26 or later, with current security releases, and no dependencies.
9
9
  > 2. Check [§3](#3-decide-what-applies) for the items that apply to your project.
10
10
  > 3. Fix required failures first. Each line the scorecard prints names an ID and the reason.
11
11
  > 4. Then the recommended items. Build a next-level item when your own traffic shows the problem it solves.
@@ -184,6 +184,7 @@ Each item says what it is, why it's at its level, and how you know it's done. Se
184
184
  </llms.txt>; rel="describedby"; type="text/plain",
185
185
  </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"
186
186
  ```
187
+ - A site with no API sends only `describedby`. A `service-desc` naming an OpenAPI document declares an API, and the scorecard then runs the API checks.
187
188
  - Give each link the type your server actually sends for that URL. llms.txt is usually `text/plain`.
188
189
  - `service-desc` is the machine-readable description (your OpenAPI). `service-doc` is the human documentation (RFC 8631). Five of the six projects fail D5: two send no `Link` header, one points `service-desc` at its skills index, and two are missing a rel.
189
190
  - Registered relations are `describedby`, `service-desc`, `service-doc`, `service-meta` and `api-catalog`. `ard`, `ai-catalog`, `llms-txt`, `mcp`, `agent-card` and `agent-skills` aren't registered: fine to use, but generic clients won't know them.
@@ -316,6 +317,7 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
316
317
  - Not indexable: test and template accounts ([recipe](docs/recipes.md#test-accounts-out-of-public-pages-t5-w3)), empty profiles, unfinished or ephemeral items, filtered views, sign-in pages, and thin pages (inbed: chats with fewer than five messages). They still render, with `noindex`, and stay out of the sitemap. Google has no `follow` rule (following links is the default), so don't count on `noindex` pages to get other pages found: link those from indexable pages (W7).
317
318
  - Missing items return a real 404 (or 410; Google treats them the same), never a 200 page that says "not found". Google calls that a soft 404 and drops it (achurch fixed a silent fallback). Empty filter combinations and page numbers past the end get a 404 too.
318
319
  - In Next.js, a `loading.tsx` above a detail page streams a 200 before `notFound()` runs, so every missing item answers 200. inbed moved its root `loading.tsx` off the profile routes, and missing profiles went from 200 to 404 in production. Keep loading boundaries off the routes of detail pages; the scorecard's missing-page probe shows whether it worked.
320
+ - **Retiring a page:** a permanent server-side redirect (301 or 308) to the page that replaced it, or a 404 or 410 when nothing did. Take it out of the sitemap, llms.txt and every other discovery file in the same change, and keep a test that it still redirects. *Harm prevented:* links and rankings to the old URL lost to a 404, and discovery files that send agents through a redirect. The scorecard fails W3 for sitemap URLs that redirect and warns in D4 for llms.txt links that do.
319
321
  - The sitemap lists only indexable canonical URLs that answer 200 without a redirect. Google and Bing both ignore `changefreq` and `priority`, and both use `lastmod` only when it's the real date of a meaningful change (D2). Bing asks for ISO 8601 with a time. Leave `lastmod` off where it would churn: drifts omits it on profiles, whose activity changes every few minutes.
320
322
  - **Done when** the scorecard passes W3.
321
323
 
@@ -323,10 +325,13 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
323
325
  - `Organization` (with your logo) and `WebSite` on the homepage, with stable `@id`s in one `@graph` (magnifica).
324
326
  - `BreadcrumbList` on pages below the top level.
325
327
  - One type per page that fits: `Article` or `TechArticle`, `ProfilePage`, `CollectionPage` or `ItemList`, `SoftwareApplication`. `datePublished` and `dateModified` on articles.
328
+ - A date shown on the page matches the structured one: Google asks that visible and structured dates agree. Read both, and the sitemap's `lastmod`, from one source, and test that they agree.
326
329
  - **Honest types for agents.** schema.org has no type for AI agents. Google's `ProfilePage` requires `Person` or `Organization` and says to default to `Person` when an account's type is unknown, and schema.org's `Person` isn't limited to humans. So `Person` fits a profile the page clearly labels as an AI agent (inbed), and markup that implies a human doesn't. botsmatter uses `Thing` and gives up profile rich results. Either is honest; say on the page what the agent is.
327
330
  - **Don't chase retired rich results.** Google ended HowTo rich results in 2023, the sitelinks search box (`WebSite` with a `SearchAction`) in November 2024, and FAQ rich results for every site in May 2026. Leftover markup does no harm and does nothing in Google; Bing says structured data may help it ground answers. Keep `FAQPage` or `HowTo` only where the page really is one.
328
331
  - **Escape JSON-LD.** User content containing `<`, `>`, U+2028 or U+2029 can break out of the script tag (achurch, magnifica).
329
- - **Done when** the scorecard passes W4 and Google's Rich Results Test accepts a sample.
332
+ - **Test in Google's tools, one page per kind of markup.** The scorecard checks that markup parses and has the expected types; Google's Rich Results Test checks each rich result's required properties. The scorecard lists the pages to test, each with a link that opens it in the test: the homepage, one page of each template with rich-result markup (pages from one template share it, and each template is its own code), and any other page that adds a rich-result feature. Retest after deploying a change to a template's markup. For types Google shows no rich result for, use the Schema Markup Validator. A valid result means a page is eligible, not that Google will show it.
333
+ - **Search Console's rich result reports cover every indexed page,** one report per feature, with valid and invalid items. Check them in the monthly review (T6).
334
+ - **Done when** the scorecard passes W4 and the Rich Results Test finds no errors on the pages the scorecard lists.
330
335
 
331
336
  **W5 Link previews.** *Why: a shared link is how many people, and some agents, first see a page.*
332
337
  - Open Graph (`og:type`, `og:url`, `og:title`, `og:description`, `og:image`) and `twitter:card` set to `summary_large_image` on every page.
@@ -334,21 +339,26 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
334
339
  - A rendered 1200×630 card for every entity (all six do this), drawn only for pages that exist: achurch's card 404s wherever its page would. The alt text repeats the card's words.
335
340
  - Version the card URL (`/og/v1/`). Platforms cache images for weeks, and a new URL is the only reliable way to show a new design (achurch, botsmatter).
336
341
  - Set `twitter:card` explicitly: X doesn't infer the card type, and without it a link may get the small card. Leave `twitter:title`, `twitter:description` and `twitter:image` out unless they differ: X falls back to the page's `og:` tags, and a site-wide value overrides every page (magnifica).
342
+ - **Every page's card shows its own title and description:** on X, `twitter:title` (else `og:title`) and the same for the description; on Facebook and LinkedIn, `og:title` and `og:description`. Put the homepage's copy on the homepage, and keep only shared fields in the root layout: the image, `twitter:card`, the site name. A framework that merges metadata shallowly, as Next.js does, gives a page that sets `openGraph` but not `twitter` the layout's whole Twitter block, and a page that sets neither the layout's whole card. In October 2026, pages at animalhouse and inbed shared on X as their homepage this way. The scorecard fails W5 when a sampled page shows another page's text, and a metadata test sees every page (§11).
337
343
  - 1200×630 works for Meta, LinkedIn and X. X's large card needs a 2:1 image under 5 MB, and not SVG.
338
344
  - Don't customize Open Graph tags without the title and description too: search reads those (achurch).
339
345
  - **Done when** the scorecard passes W5.
340
346
 
341
347
  **W6 Page structure.** *Why: headings, language and alt text are how readers, screen readers and machines parse a page.*
342
348
  - One `h1` per page, with sections as `h2`.
349
+ - Heading levels don't skip going down (an `h1` followed by an `h3`). Screen readers and parsers read the levels as the page's outline, and W3C's headings tutorial says to avoid skipping ranks. Going back up to close a section is fine. Google doesn't rank on heading order, so the scorecard warns rather than fails.
343
350
  - `html lang` on every page. Screen readers need it; Google detects language from the text and ignores the attribute.
344
351
  - Descriptive alt text on content images. Google calls alt text the most important image metadata; file names give it only light clues.
345
352
  - On generated entity pages, a unique narrative paragraph (botsmatter, animalhouse), and excerpts rather than full copies of text that has its own page, so the detail page ranks for its own words (botsmatter).
353
+ - The scorecard reports the sampled pages' median HTML size, which is what an agent pays to read a page. It isn't scored: no T5 result yet shows that lighter pages help agents succeed. Compare it with your T5 results.
346
354
  - **Done when** the scorecard passes W6.
347
355
 
348
356
  **W7 Internal links** (checked in review).
349
357
  - Every entity name links to its page, and detail pages end with related links ("More from {username}", botsmatter).
350
358
  - Recommendation lists draw from many pages, not the same few (inbed's pool of about 150 indexable agents).
351
- - Anchor text describes the target ("Catholic AI ethics compass", not "click here" or a bare domain), including links between sibling projects (achurch).
359
+ - **Anchor text says what the target is, in the words people search for:** "Catholic AI ethics compass", not "click here", a bare domain or the brand name alone. Google's test is whether the anchor makes sense read by itself, and a brand name means nothing to someone who doesn't know the brand yet. Put the brand in plain text beside the anchor: `[Brand] has [what it is, in searched-for words]`. This holds for links between sibling projects too (achurch). At animalhouse in October 2026, an agent linking two sibling sites used their brand names until asked to use keywords.
360
+ - **The anchor is true of the page it opens.** Link the most specific page that delivers what the words name (a file the anchor names, a tool the anchor describes), and don't name a feature the target doesn't have. The same agent's first keyword choice ("generate soul files") described a generator its target didn't have. *Harm prevented:* a reader who clicks and doesn't find what the link promised stops trusting your links.
361
+ - Keep anchors concise and on one topic. Google counts packing every related keyword into a link as keyword stuffing, a spam policy violation.
352
362
  - Every sitemap URL is linked from at least one page.
353
363
 
354
364
  ### Recommended
@@ -393,6 +403,9 @@ The test is whether most of the six projects should do it. These came from one o
393
403
  - **`changefreq` and `priority` in the sitemap** (achurch): Google and Bing ignore both.
394
404
  - **Question-shaped headings written for AI** (magnifica): Google's May 2026 guide for AI features says chunking or rewriting content for AI doesn't help. Write headings for people.
395
405
  - **A meta keywords tag** (achurch's batch rewrote one): Google and Bing ignore it.
406
+ - **In-page anchors that resolve** (a `#section` link to a missing id): cheap to test, but a broken anchor still lands on the right page, so the harm is small.
407
+ - **Versioned favicon links and a mark legible at 16 px:** D3 already asks for a favicon set; legibility is a design call.
408
+ - **Prerendering, view transitions and theme switches:** they make a site feel modern, and neither search nor agents read them.
396
409
  - **A brand name another site owns** (achurch competes with an "Achurch" consultancy): real, but particular to one name. Check your own brand query in Search Console.
397
410
 
398
411
  ---
@@ -477,6 +490,7 @@ The test is whether most of the six projects should do it. These came from one o
477
490
  - **Trigger on the job, and say what lasting actions do.** The description names the job specifically enough that an unrelated request can't match it, and it applies to any request that fits the job. The body says what becomes public, what's saved on the machine and what can't be undone, and an agent can follow it through the core loop on its own (principle 10). Keep "only when the user asks" for actions that destroy something, like deleting data or rotating a key.
478
491
  - **Check it:** could a request that has nothing to do with your product match the description? Could an agent with no person present finish the core loop by following the skill?
479
492
  - **What ClawHub's scan did:** it rated drifts' first plugin suspicious for broad triggers: general activities that unrelated requests also match. animalhouse's plugin can do the same things (register a persistent account, save a key, create public pages); its triggers name its job, it states the consequences, and an agent runs the core loop without stopping. It scanned clean. That's one case each, so if a scan flags you, make the smallest change that passes and record what it was.
493
+ - **State facts the code can keep true.** A count or a timing in a skill ("hatches in five minutes") comes from the code or data it describes, or isn't stated: agents act on it. §11's "No stale claims" test covers skill files.
480
494
  - **Link the map.** Every skill links llms.txt and the API or MCP reference (`/docs/api.md`, `/openapi.json` or your MCP docs), because an agent's fetch tool only reads what it's pointed at (D4). The scorecard checks this on a sample of skills from your index. At animalhouse, the core skill and both plugin skills linked neither.
481
495
  - **Serve the raw file** at a stable URL so an agent can install it with one fetch (`/.well-known/agent-skills/<name>/SKILL.md` keeps the folder name in the URL), plus a `/skills` page. Index them in S2, with each digest computed from the bytes you serve.
482
496
  - **Index the skills the site serves, not every listing.** inbed lists about 95 skills on ClawHub and indexes the 6 its site serves; animalhouse indexes 93 of 176, leaving out keyword variants of its core guide. Publishing an index makes S1 apply, so the required count goes up by one. Editing skills to pass it means republishing them and syncing any plugin copies, which is the owner's call.
@@ -609,6 +623,8 @@ The test is whether most of the six projects should do it. These came from one o
609
623
  ### E6 Point to the sibling projects
610
624
 
611
625
  *Recommended when you run related sites for the same audience.* List them in llms.txt and the `/for-agents` page; for some projects (achurch.ai) that's enough. In API responses, mention a sibling only where it's relevant to what the agent just did. inbed links one in about 30% of responses; at that rate a link can read as an ad.
626
+ - **On pages, link a sibling in context,** where it answers what the reader is doing there, with W7's anchors: what the sibling is, in searched-for words, with the brand beside it in plain text.
627
+ - **Not sitewide, and not as a partner page.** Don't put sibling links in a footer or template on every page, and don't build a page that exists to list them. *Harm prevented:* Google's spam policies name both, links in the footers or templates of various sites and partner pages made for cross-linking, as link schemes, and a network of sites linking each other that way can lose rankings for all of them.
612
628
 
613
629
  ---
614
630
 
@@ -621,6 +637,7 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
621
637
  - No CDN plan is needed: a `.md` route and a few lines of middleware do it ([recipe](docs/recipes.md#markdown-for-agents-without-a-cdn-plan-d8)). Cloudflare's Markdown for Agents feature (Pro and up) converts pages for you, but it's optional.
622
638
  - Send `Vary: Accept` on both representations (RFC 9110 §12.5.5). Otherwise a cache can hand HTML readers the markdown, or the reverse.
623
639
  - Next.js drops a `Vary` set in middleware, proxy or `next.config` on App Router pages, static or dynamic, while it keeps the other headers (tested on 14.2 and 16.3). So `Accept` has to reach the HTML from the edge (a CDN response header rule), or decline that half in writing. Send it from the markdown route yourself (animalhouse.ai).
640
+ - A page's markdown copy has the page's sections. The homepage's can be llms.txt instead. *Harm prevented:* agents reading the markdown get a different site than people do. The scorecard compares the headings of one page llms.txt links, when that page serves markdown, and a guard test can compare them all (§11).
624
641
  - Make links absolute, and link back to the HTML page as canonical.
625
642
  - Add `x-markdown-tokens` so an agent can budget before reading. It's Cloudflare's header, with no spec behind it.
626
643
  - Negotiate in front of prerendered pages too, or they ignore it (magnifica).
@@ -660,13 +677,14 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
660
677
  - Logs that outlive a deploy. Logs written inside the container vanish with it: after one deploy, drifts had five minutes of history. Keep them on a volume, ship them out, or use the platform's own HTTP logs.
661
678
  - **T2 Attribution and one come-back measure** (required; per-agent tracking may be declined). Record `source` plus User-Agent per entry point, and judge entry points by who comes back, not just who signs up. A come-back measure is the share of agents who return to the core action a day or more after their first success: at animalhouse, the share of adoptions that get care again 24 hours or more after hatching (about 12%). An aggregate measure works for projects that rule out per-agent analytics.
662
679
  - **T3 Reviews** (required):
663
- - A monthly log review, paged so no window is truncated (platform log commands often return only the newest window): requested well-known paths, 404s, refusals, crawler user agents.
680
+ - A monthly log review, paged so no window is truncated (platform log commands often return only the newest window): requested well-known paths, 404s, refusals, crawler user agents. `readiness-audit --logs <file>` counts the discovery requests in an exported log by client family.
681
+ - **Classify traffic before counting it.** Set known junk crawlers aside first, and trust a crawler's name only where the operator verifies it. Count a browser, headless or unidentified client as an agent only when something backs it up, such as the same address calling the API: agent tools often send a browser's user agent (§2), so their user agent alone proves nothing either way. *Harm prevented:* readiness decisions made on noise.
664
682
  - After each deploy, run the scorecard, lint the OpenAPI spec, and diff generated files against the previous production output. About 24 hours later, review the logs and database query performance.
665
683
  - **T5 The agent usability test** (required).
666
684
  - **Why:** it's the only check that measures what the whole standard is for, and without it the scorecard becomes the target.
667
685
  - **How:** give a fresh agent nothing but your domain and a goal: your core loop, as a person would ask for it ([examples](docs/usability-test.md#setup)). Choose a goal it can finish alone: one that needs someone else to act (a match on a dating site needs the other side to like back) can't be completed in one run. Run it headless, for example `claude -p` with only web fetch and curl allowed. Record whether it succeeds, how many calls it takes, every error it hits, and every point where it couldn't go on by itself (principle 10).
668
686
  - **When:** monthly, and after big API changes.
669
- - **Report** its first-try success rate next to your score.
687
+ - **Report** its first-try success rate next to your score, with the model, turn limit, calls, stops and cost as fields (format: [examples/recorded.json](examples/recorded.json)).
670
688
  - **Rules:** run it only against your own site, with a test username so analytics filter it out.
671
689
  - **Keep test accounts out of public pages:** one helper recognizes the test prefix; leave those accounts out of public listings, search and counts; `noindex` their pages and keep them out of the sitemap; and guard it with a test ([recipe](docs/recipes.md#test-accounts-out-of-public-pages-t5-w3)).
672
690
  - **Keep the agent fresh,** with none of the operator's memory, settings or account details. drifts' test agent named itself after the operator, taken from its environment.
@@ -677,6 +695,8 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
677
695
  - Verify the site in Google Search Console and Bing Webmaster Tools, and submit the sitemap to both.
678
696
  - Review them monthly: coverage (including "crawled, not indexed"), queries, clicks and click-through rate. Re-check about two weeks after an SEO change (inbed).
679
697
  - Record the numbers next to the score as fields, not prose, so months compare: the period, clicks, impressions, click-through rate, average position, pages indexed and not indexed, and "crawled, not indexed", for Google and Bing (format: [examples/recorded.json](examples/recorded.json)). They're the outcome the W items are for.
698
+ - Check the rich result reports: invalid items first, since a critical issue keeps an item out of rich results (W4). The URL Inspection API returns the same findings for one URL (`richResultsResult`), for scripts with the owner's access.
699
+ - Record the top queries with the page each lands on (`queries`), and ask in the review whether each page answers its query in its title, `h1` and opening text. animalhouse's homepage ranked for "tamagotchi ai" without those words on the page. It isn't scored: the data is entered by hand, and matching query words against a title invites keyword stuffing.
680
700
  - It takes a person, or a browser session, with access to Search Console and Bing Webmaster Tools. There's no unattended way to read them.
681
701
  - In analytics, watch referrals from AI answer engines (chatgpt.com, perplexity.ai, copilot.microsoft.com, gemini.google.com, claude.ai).
682
702
  - Search Console gained a setting on 2026-08-31 that keeps a site out of Google's AI features. It's on by default, so leave it alone unless you mean to opt out.
@@ -692,10 +712,14 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
692
712
  - **Contract** (once you have response schemas, N7): the OpenAPI spec is validated against real responses (achurch.ai).
693
713
  - **Parity:** each MCP tool returns what its REST twin returns, in both protocol eras (achurch.ai). The tool list matches the OpenAPI operations (animalhouse's `npm run smoke`).
694
714
  - **Versions agree:** `package.json`, `server.json`, the server card and the plugin pin (magnifica, achurch.ai).
695
- - **No stale claims:** discovery files don't advertise parameters the API rejects, retired numbers, or features you don't run (magnifica's `well-known-surfaces.test.ts`).
715
+ - **No stale claims:** discovery files, page copy and skill files don't advertise parameters the API rejects, retired numbers, or features you don't run (magnifica's `well-known-surfaces.test.ts`). A count or a timing ("167 skills", "hatches in five minutes") comes from the code or data it describes, or isn't stated. *Harm prevented:* copy that contradicts the product, which agents act on (animalhouse's skills kept a timing the game had changed).
716
+ - **Every page's own metadata:** walk every route and check each has its own title, description and share card, with descriptions within W1's lengths. It's the only check that sees every page, and it catches copy a page inherits from a layout before it ships (animalhouse's `metadata.test.ts`).
696
717
  - **Schemas:** each card and index validates against its published schema (the skills index, the server card, the AI catalog).
697
718
  - **Generated files are current:** a `--check` mode for generated manifests and tool tables, run in CI (animalhouse, drifts, inbed).
698
719
  - **Skills only call tools that exist** (achurch.ai, drifts).
720
+ - **The sitemap equals the route registry:** every routed, indexable page is in the sitemap, and every sitemap URL is routed. The scorecard samples the sitemap, so it can't see a page the sitemap leaves out ([recipe](docs/recipes.md#the-sitemap-equals-the-routes-t4-w3)).
721
+ - **Markdown copies keep their pages' sections** (D8): each copy has the headings its HTML page has.
722
+ - **Retired URLs keep redirecting** (W3).
699
723
  - **Every operation and field has a description** (animalhouse's `registry.test.ts`).
700
724
  - **One module for shared policy:** security headers and the `Link` value come from one module, with a drift test (magnifica).
701
725
  - **The scorecard in CI:** run it against the deployed site and fail on a required regression.
@@ -724,14 +748,15 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
724
748
  - **Supabase silently caps a select at 1,000 rows,** and its client has no default timeout.
725
749
  - **Next.js 14.2's `force-dynamic` alone leaves fetches cached.** Use `revalidate = 0` for live pages (inbed). Route segment config can't be re-exported either.
726
750
  - **A timestamp set when a job notices an event records the detection, not the event** (animalhouse's `died_at`).
727
- - **MCP SDK v1 can't speak 2026-07-28.** SDK v2's legacy fallback speaks only SSE and is strict about `Accept` (M4).
751
+ - **MCP SDK v1 can't speak 2026-07-28** (checked on 1.32.1, whose newest protocol is 2025-11-25). SDK v2's legacy fallback speaks only SSE and is strict about `Accept` (M4).
728
752
  - **A redirect from `/sse` doesn't make the old SSE transport work.** 2024-11-05 clients GET `/sse` and expect an `endpoint` event.
729
753
  - **Claude Code ignores AGENTS.md when CLAUDE.md exists,** unless CLAUDE.md imports it.
730
754
  - **An AID record and DNS-AID are different specs** at different names (`_agent` TXT and `_agents` SVCB). Scanners check only DNS-AID.
731
755
  - **A second `_agent` TXT record** makes AID clients fail on ambiguity.
732
756
  - **A catalog entry's type is a claim.** Typing `mcp.json` as a server card is a false declaration even when `mcp.json` itself is honest.
733
757
  - **A client-side `document.title`** overwrites the server's title after load, so people and crawlers see different titles.
734
- - **A site-wide `twitter:title`** overrides every page's own `og:title` on X.
758
+ - **Inline elements with no space between them fuse into one word** for crawlers and screen readers: a link made of "Drifts Bot" and "Travel" in two spans reads "Drifts BotTravel". Check the rendered text, not the markup.
759
+ - **A site-wide `twitter:title`** overrides every page's own `og:title` on X. Next.js adds one unasked: metadata merges shallowly, so a page that sets `openGraph` but not `twitter` keeps the layout's `twitter` title and description.
735
760
  - **Two items with the same name can share one URL.** animalhouse's creature page 404'd when an agent reused a name, while the sitemap still listed the URL; the lookup now picks the item the URL means (a living one first, then one with a gravestone). W3's sitemap sample catches it.
736
761
  - **`og:locale` and JSON-LD `inLanguage` use different formats:** `en_US` and `en-US`, `zh_CN` and `zh-Hans`.
737
762
  - **Retired rich results still get added.** FAQ, HowTo and the sitelinks search box no longer show in Google for any site.
@@ -747,12 +772,12 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
747
772
  Score each site monthly and after big releases, and keep the results where the project's agents can read them:
748
773
 
749
774
  ```
750
- npx readiness-audit@1 --matrix site-one.com site-two.com --recorded docs/readiness-recorded.json > docs/readiness-status.md
775
+ npx readiness-audit@2 --matrix site-one.com site-two.com --recorded docs/readiness-recorded.json > docs/readiness-status.md
751
776
  ```
752
777
 
753
778
  The page lists every check for every site, the scores at each level, and each failure or warning with its reason. Keep it in the project's private repo when there is one (for example, a private repo that holds the docs, with the public repo as a submodule). A project with only a public repo keeps it there: the page shows only what anyone can see from outside.
754
779
 
755
- Score a local or preview build before you deploy: `npx readiness-audit@1 example.com --base http://localhost:3000` requests the site's URLs from the base and reports them under the domain, skipping DNS and host redirects. To see what changed since the last run, compare against that page: `npx readiness-audit@1 <domain> --compare docs/readiness-status.md` lists what was fixed, what newly fails and what newly applies. Scores alone mislead here, because the denominator grows as items start to apply.
780
+ Score a local or preview build before you deploy: `npx readiness-audit@2 example.com --base http://localhost:3000` requests the site's URLs from the base and reports them under the domain, skipping DNS and host redirects. To see what changed since the last run, compare against that page: `npx readiness-audit@2 <domain> --compare docs/readiness-status.md` lists what was fixed, what newly fails and what newly applies. Scores alone mislead here, because the denominator grows as items start to apply.
756
781
 
757
782
  Read it with three caveats:
758
783
  - **It covers only what's visible from outside.** One of our projects scored well with no test suite, and the score couldn't show it.
@@ -772,7 +797,7 @@ Step-by-step instructions for a project's coding agent: [docs/adopting.md](docs/
772
797
  This project follows the Agent and Search Readiness Standard:
773
798
  https://github.com/geeks-accelerator/agent-and-search-readiness/blob/main/STANDARD.md
774
799
 
775
- Score this site: `npx readiness-audit@1 <domain>`. Current status: docs/readiness-status.md
800
+ Score this site: `npx readiness-audit@2 <domain>`. Current status: docs/readiness-status.md
776
801
 
777
802
  Declined items (principle 9), with reasons:
778
803
  - (none yet)
@@ -780,7 +805,7 @@ Step-by-step instructions for a project's coding agent: [docs/adopting.md](docs/
780
805
  Project-specific notes:
781
806
  - (anything the standard doesn't cover)
782
807
  ```
783
- - **Pin the scorecard to a major version** (`npx readiness-audit@1 <domain>`), so a new release can't fail your build without warning.
808
+ - **Pin the scorecard to a major version** (`npx readiness-audit@2 <domain>`), so a new release can't fail your build without warning.
784
809
  - **Run it in CI** after each deploy or on a schedule, and fail on a required regression. `examples/github-action.yml` is a starting point.
785
810
  - **Record declined items** (principle 9) in your CLAUDE.md or AGENTS.md, with the reason.
786
811
  - **Send improvements back** as an issue or pull request. When a project finds a better practice, it goes into the standard (principle 8).
@@ -811,10 +836,10 @@ Level: **R** required where it applies, **Rec** recommended, **N** next level. W
811
836
  | W1 | Titles and descriptions: one helper, unique, searched-for words, 140 to 160 character descriptions | R | traffic | score |
812
837
  | W2 | Self-referencing canonicals, one host in one redirect | R | discovery | score |
813
838
  | W3 | One indexability rule; sitemap of 200 canonical URLs; real 404s | R | discovery, honesty | score |
814
- | W4 | True structured data: Organization and WebSite, breadcrumbs, honest types, escaped | R | honesty | score |
815
- | W5 | Link previews: Open Graph, `twitter:card`, declared images, versioned cards | R | discovery | score |
839
+ | W4 | True structured data: Organization and WebSite, breadcrumbs, honest types, escaped, tested in Google's Rich Results Test | R | honesty | score, review |
840
+ | W5 | Link previews: Open Graph, `twitter:card`, each page's own card text, declared images, versioned cards | R | discovery | score |
816
841
  | W6 | One h1, `html lang`, alt text, unique paragraph on generated pages | R | discovery | score |
817
- | W7 | Internal links with descriptive anchors, no orphan pages | R | discovery | review |
842
+ | W7 | Internal links with descriptive, searched-for anchors true to the target, no orphan pages | R | discovery | review |
818
843
  | W8 | Core Web Vitals on the main pages | Rec | discovery | review |
819
844
  | W9 | Listed in the directories your audience uses | Rec | discovery | review |
820
845
  | W10 | IndexNow for content that changes | Rec | discovery | review |
@@ -894,7 +919,7 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
894
919
  | auth.md | WorkOS open protocol, 2026 | https://workos.com/blog/agent-registration-with-auth-md |
895
920
  | MCP authorization | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery |
896
921
  | MCP Streamable HTTP | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http |
897
- | MCP structured tool output | spec 2025-06-18 | https://modelcontextprotocol.io/specification/2025-06-18/server/tools |
922
+ | MCP structured tool output | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/server/tools |
898
923
  | SDK v2 legacy clients | TypeScript SDK docs | https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/serving/legacy-clients.md |
899
924
  | MCP server card | experimental extension, not accepted; location and media type in `docs/discovery.md` | https://github.com/modelcontextprotocol/ext-server-card |
900
925
  | AID | v2.1.1 | https://aid.agentcommunity.org/docs/specification |
@@ -918,6 +943,12 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
918
943
  | Google AI features | Search Central | https://developers.google.com/search/docs/appearance/ai-features |
919
944
  | Google's AI optimization guide | Search Central, May 2026 | https://developers.google.com/search/docs/fundamentals/ai-optimization-guide |
920
945
  | Title links and snippets | Search Central | https://developers.google.com/search/docs/appearance/title-link · https://developers.google.com/search/docs/appearance/snippet |
946
+ | Redirects | Search Central, read 2026-10-21 | https://developers.google.com/search/docs/crawling-indexing/301-redirects |
947
+ | Google rich results | Search Central search gallery (updated 2026-10-16), read 2026-10-21 | https://developers.google.com/search/docs/appearance/structured-data/search-gallery |
948
+ | Testing structured data | Search Central: the Rich Results Test and the Schema Markup Validator, read 2026-10-21 | https://developers.google.com/search/docs/appearance/structured-data · https://search.google.com/test/rich-results · https://validator.schema.org/ |
949
+ | Rich result reports, URL Inspection API | Search Console Help and API reference, read 2026-10-21 | https://support.google.com/webmasters/answer/7552505 · https://developers.google.com/webmaster-tools/v1/urlInspection.index/UrlInspectionResult |
950
+ | Headings | W3C WAI tutorial, read 2026-10-21 | https://www.w3.org/WAI/tutorials/page-structure/headings/ |
951
+ | Publication dates | Search Central, read 2026-10-21 | https://developers.google.com/search/docs/appearance/publication-dates |
921
952
  | Canonicalization | Search Central | https://developers.google.com/search/docs/crawling-indexing/canonicalization |
922
953
  | Pagination and faceted navigation | Search Central | https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading · https://developers.google.com/crawling/docs/faceted-navigation |
923
954
  | Sitemaps (Google) | Search Central | https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap |
@@ -929,9 +960,11 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
929
960
  | Core Web Vitals | web.dev, Search Central | https://web.dev/articles/vitals · https://developers.google.com/search/docs/appearance/page-experience |
930
961
  | hreflang | Search Central | https://developers.google.com/search/docs/specialty/international/localized-versions |
931
962
  | Images and alt text | Search Central | https://developers.google.com/search/docs/appearance/google-images |
963
+ | Link spam | Search Central spam policies, read 2026-10-21 | https://developers.google.com/search/docs/essentials/spam-policies |
932
964
  | Crawlable links | Search Central | https://developers.google.com/search/docs/crawling-indexing/links-crawlable |
933
965
  | Open Graph | ogp.me | https://ogp.me/ |
934
966
  | Share images (Meta, LinkedIn) | platform docs | https://developers.facebook.com/docs/sharing/webmasters/images · https://www.linkedin.com/help/linkedin/answer/a521928 |
967
+ | Next.js metadata merging | Next.js docs, read 2026-10-21 | https://nextjs.org/docs/app/api-reference/functions/generate-metadata#merging |
935
968
  | X cards | archived X developer docs | https://web.archive.org/web/20260204074639/https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image |
936
969
  | Bing webmaster guidelines | Bing | https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a |
937
970
  | IndexNow | protocol FAQ | https://www.indexnow.org/faq |
@@ -1,14 +1,24 @@
1
1
  #!/usr/bin/env node
2
2
  // readiness-audit: score a live site against the Agent and Search Readiness Standard.
3
3
  //
4
- // readiness-audit <domain> [--mcp /path] [--no-mcp] [--no-api] [--json] [--compare previous] [--base url]
4
+ // readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
5
5
  // readiness-audit --matrix <domain> <domain> ... [--recorded results.json] (a markdown status page)
6
+ // readiness-audit --logs <access-log> [--json] (who requests the discovery files)
6
7
  //
7
8
  // Exits 1 when a required check fails, so it can gate a deploy.
8
9
 
9
- import { readFileSync } from 'node:fs';
10
+ import { readFileSync, createReadStream } from 'node:fs';
11
+ import { createInterface } from 'node:readline';
10
12
  import { audit, matrix, score, LEVELS, REVIEW, VERSION } from '../src/audit.mjs';
11
13
  import { parsePrevious, compareResults, formatComparison } from '../src/helpers.mjs';
14
+ import { logTally, formatLogs } from '../src/logs.mjs';
15
+
16
+ // engines in package.json only warns, so say it plainly before anything fails oddly.
17
+ const NODE_MAJOR = 26;
18
+ if (Number(process.versions.node.split('.')[0]) < NODE_MAJOR) {
19
+ console.error(`readiness-audit needs Node ${NODE_MAJOR} or later, with current security releases (this is ${process.versions.node}).`);
20
+ process.exit(2);
21
+ }
12
22
 
13
23
  const args = process.argv.slice(2);
14
24
  const flag = (n) => args.includes(n);
@@ -21,26 +31,37 @@ const mcpOpt = valueOf('--mcp');
21
31
  const recordedPath = valueOf('--recorded');
22
32
  const comparePath = valueOf('--compare');
23
33
  const base = valueOf('--base');
24
- const domains = args.filter((a, i) => !a.startsWith('-') && !['--mcp', '--recorded', '--compare', '--base'].includes(args[i - 1]))
34
+ const logsPath = valueOf('--logs');
35
+ const domains = args.filter((a, i) => !a.startsWith('-') && !['--mcp', '--recorded', '--compare', '--base', '--logs'].includes(args[i - 1]))
25
36
  .map((d) => d.replace(/^https?:\/\//, '').replace(/\/.*$/, ''));
26
- const opts = { hasApi: !flag('--no-api'), mcpPath: flag('--no-mcp') ? null : (mcpOpt ?? '/mcp'), base: base ?? null };
37
+ const opts = { mcpPath: flag('--no-mcp') ? null : (mcpOpt ?? '/mcp'), base: base ?? null };
27
38
  if (base) {
28
39
  let u;
29
40
  try { u = new URL(base); } catch { u = null; }
30
41
  if (!u || !['http:', 'https:'].includes(u.protocol)) { console.error(`--base needs an http(s) URL, like http://localhost:3000 (got ${base})`); process.exit(2); }
31
42
  }
32
43
 
44
+ if (logsPath) {
45
+ const tally = logTally();
46
+ try {
47
+ for await (const line of createInterface({ input: createReadStream(logsPath), crlfDelay: Infinity })) tally.add(line);
48
+ } catch (e) { console.error(`Couldn't read ${logsPath}: ${e.message}`); process.exit(2); }
49
+ const rep = tally.result();
50
+ console.log(flag('--json') ? JSON.stringify(rep, null, 2) : formatLogs(rep).join('\n'));
51
+ process.exit(0);
52
+ }
53
+
33
54
  if (!domains.length || flag('--help') || flag('-h')) {
34
55
  console.error(`readiness-audit ${VERSION}
35
56
 
36
57
  Usage:
37
- readiness-audit <domain> [--mcp /path] [--no-mcp] [--no-api] [--json] [--compare previous] [--base url]
58
+ readiness-audit <domain> [--mcp /path] [--no-mcp] [--json] [--compare previous] [--base url]
38
59
  readiness-audit --matrix <domain> <domain> ... [--recorded results.json]
60
+ readiness-audit --logs <access-log> [--json]
39
61
 
40
62
  Options:
41
63
  --mcp /path where your hosted MCP endpoint lives (default /mcp)
42
64
  --no-mcp skip the hosted MCP checks
43
- --no-api skip the API checks, for a site with no public API
44
65
  --json print the results as JSON
45
66
  --matrix score several sites and print a markdown status page
46
67
  --recorded f with --matrix: add recorded T5 and T6 results from a JSON file
@@ -48,7 +69,13 @@ Options:
48
69
  --matrix (docs/readiness-status.md) or a saved --json report
49
70
  --base url score a local or preview build as the domain, before you
50
71
  deploy (http://localhost:3000); DNS and host redirects are
51
- skipped`);
72
+ skipped
73
+ --logs f count requests for the discovery files in an exported access
74
+ log (combined log format or JSON lines), by client family;
75
+ prints counts, never addresses
76
+
77
+ The API checks run when /openapi.json or /api answers, or the site declares
78
+ an API (a service-desc link, an API catalog, an API link in llms.txt).`);
52
79
  process.exit(domains.length ? 0 : 2);
53
80
  }
54
81
 
@@ -88,7 +115,10 @@ if (flag('--matrix')) {
88
115
  console.log(`\nScore on ${rep.checked_at.slice(0, 10)}: required ${score(rep.results, 'required')}, recommended ${score(rep.results, 'recommended')}, next level ${score(rep.results, 'next')}`);
89
116
  if (changes) console.log(`\n${formatComparison(changes, since).join('\n')}`);
90
117
  console.log('\nNot scored, so check these yourself:');
91
- for (const [id, what] of REVIEW) console.log(` ${id.padEnd(6)} ${what}`);
118
+ for (const [id, what] of REVIEW) {
119
+ console.log(` ${id.padEnd(6)} ${what}`);
120
+ if (id === 'W4') for (const p of rep.rich_results_test ?? []) console.log(` ${p.url} (${p.features.join(', ')})\n ${p.test}`);
121
+ }
92
122
  }
93
123
  process.exitCode = rep.results.some((r) => r.level === 'required' && r.status === 'fail') ? 1 : 0;
94
124
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "readiness-audit",
3
- "version": "1.2.1",
3
+ "version": "2.1.0",
4
4
  "description": "Score a live site against the Agent and Search Readiness Standard: discovery files, search, API, MCP and skills, for AI agents and search engines.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,7 +19,7 @@
19
19
  "test": "node --test"
20
20
  },
21
21
  "engines": {
22
- "node": ">=20"
22
+ "node": ">=26"
23
23
  },
24
24
  "keywords": [
25
25
  "ai-agents",