readiness-audit 1.2.0 → 2.0.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,60 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.0.0 (2026-10-21)
4
+
5
+ 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`.
6
+
7
+ **Checks that can newly fail** (why this is a major version):
8
+ - **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.
9
+ - **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.
10
+ - **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.
11
+ - **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.
12
+ - **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.
13
+
14
+ **New warnings:**
15
+ - **W6** warns when heading levels skip going down (an `h1` followed by an `h3`).
16
+ - **D4** reports llms.txt links that redirect: link the destination.
17
+ - **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.
18
+ - **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.
19
+
20
+ **New:**
21
+ - **`--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.
22
+ - **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.
23
+ - **T5 is recorded as fields:** `attempts`, `first_try`, `model`, `max_turns`, `median_calls`, `stops`, `cost_usd`, `date`. Convert a free-text T5 `result`.
24
+ - **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.
25
+ - **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.
26
+ - **Releases run CI first,** on Node 26, and npm is pinned to major 12 in the publish step. Dependabot watches the GitHub Actions weekly.
27
+
28
+ **STANDARD.md:**
29
+ - 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).
30
+ - W4: a visible date matches the structured one (Google's publication-dates guidance).
31
+ - 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.
32
+ - W6: heading levels don't skip (W3C's headings tutorial); the median HTML size, reported and not scored.
33
+ - D8: a page's markdown copy has the page's sections.
34
+ - §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.
35
+ - T6: record the top queries with their landing pages (`queries` in `recorded.json`), reviewed by hand, not scored.
36
+ - §12: inline elements with no space between them fuse into one word.
37
+ - 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.
38
+ - 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.
39
+ - E6: link siblings in context with W7's anchors; never sitewide or on a partner page, which Google's spam policies call link schemes.
40
+ - Considered and left out: in-page anchors, favicon versioning, prerendering and view transitions.
41
+ - §12: the SDK v1 gotcha was re-checked on 1.32.1. §16: N6 cites the 2026-07-28 spec.
42
+ - §16: Next.js metadata merging, Google on redirects and on publication dates.
43
+
44
+ ## 1.2.1 (2026-10-06)
45
+
46
+ 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.
47
+
48
+ - **Principle 7 is now "Tell agents the consequences, then let them act."** Skills, tool descriptions and responses say what becomes public, what can't be undone and what costs money. MCP annotations carry the same facts, and approval policy belongs to the client and whoever runs the agent.
49
+ - **New principle 10, "Caution has a cost, so count it."** Confirmation steps, ask-first lines, narrow triggers and disclaimers cost installs, engagement and organic discovery. Name the harm before adding a restriction, keep "only when asked" for destructive actions, and undo a change that lowers T5 or the come-back measure. Principles 8 and 9 keep their numbers.
50
+ - **S1:** trigger on the job, specifically enough not to fire on unrelated requests, and say what lasting actions do, with no ask-first gates on the core loop. ClawHub's scan flagged drifts' first plugin for broad triggers ("explore, travel"); animalhouse's plugin, with job-specific triggers and no gates on the core loop, scanned clean. The scorecard's S1 review line says the same. botsmatter had already declined the old rule. If your skills have ask-first lines or explicit-only triggers from the old wording, take them out of the core loop; republishing is the owner's call.
51
+ - **T5:** record every point where the agent couldn't go on by itself (`STOPS` in the runner's report). The runner's prompt no longer tells the agent to read the docs and the API, since finding them is part of what T5 measures, so earlier results aren't directly comparable. Record the full model ID: an alias like `sonnet` moves to each new release.
52
+ - **Fewer examples to copy.** Agents adopting the standard turn its examples into their own skills and copy, so rules teach with a generic example, a `[placeholder]` template or a check question, and name a project only as evidence: W1's title pattern, T2's come-back measure, the T5 goal, A8's placeholders (taken from your own docs, not a fixed list), A11, E2's mechanics (now attributed), E6 (applies when you run related sites), S3 (no skill counts; ClawHub flags near-identical skills as template spam) and §12's timestamp gotcha. S1 gains two check questions. README and §13 no longer list skills that act without asking as a gap. ClawHub observations get a dated row in §16.
53
+ - **docs/recipes.md:** route handlers take `params` as a promise (Next.js 15 and later), and Next.js 16 calls middleware `proxy.ts`.
54
+ - **AGENTS.md:** examples get copied; every restriction names the harm it prevents; the standard describes the current rule, and history goes here and in commits.
55
+ - **Examples that fit any project:** the T5 goal, A7, A8's aliases, N2 and W3 no longer use one project's terms. The principles list now says the first six (not seven) came from all six projects.
56
+ - **docs/adopting.md:** a third switch-over rule, that every restriction names the harm it prevents; step 5 says why it asks first; the intro no longer leads with a score.
57
+
3
58
  ## 1.2.0 (2026-10-06)
4
59
 
5
60
  From drifts.bot's switch-over, the third project to adopt the standard. One new warning (D4), no new failures. It also ships 1.1.0, which wasn't published to npm.
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,17 @@ 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
 
52
- It can't see whether `next_steps` guide well, whether input is forgiving, whether skills ask before acting in public, 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.
55
+ 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
56
 
54
57
  ## Use it in your project
55
58
 
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).
59
+ 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
60
 
58
61
  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
62
 
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.
@@ -33,7 +33,7 @@ This is the common standard our projects work toward, published for anyone who b
33
33
 
34
34
  ## 1. Principles
35
35
 
36
- The first seven came from all six projects independently.
36
+ The first six came from all six projects independently.
37
37
 
38
38
  1. **One source per fact.** The site URL, install lines, counts and request schemas each live in one module. Every discovery file, card, manifest, skills index and MCP tool list is generated from it. (inbed keeps the facts in `agent-discovery.ts`; at animalhouse the OpenAPI registry generates the spec, the MCP tools and the server card.)
39
39
  2. **Only declare what's true.** A manifest is a promise a client will act on. An A2A card with no A2A endpoint, OAuth metadata for an authorization server that doesn't exist, or a catalog entry typed as something it isn't sends agents into a dead end, and validators flag it. Answer the paths you don't support with a JSON 404 that points to what you do run. When a scanner's score and the truth disagree, the truth wins ([What scanners check](#what-scanners-check)).
@@ -41,9 +41,10 @@ The first seven came from all six projects independently.
41
41
  4. **Guard every surface with a test you've watched fail.** Untested discovery files drift without anyone noticing. A magnifica skills index advertised a parameter the API rejects. The animalhouse `agents.txt` still said "there is no hosted MCP" after the hosted endpoint shipped.
42
42
  5. **Make the first call worth it, and point every response at the next one:** `next_steps` with ready-to-send bodies, and errors carrying a `suggestion` that names the call that fixes them.
43
43
  6. **Be forgiving at the edge and strict where it counts.** Accept aliases, any `Accept` header and guessable wrong paths. Never guess on a write.
44
- 7. **Ask before anything public or permanent.** Skills and tool descriptions say what becomes public, and skills tell the agent to confirm with its person before registering, publishing or rotating a key. This is also what gets skills through ClawHub's security audit.
44
+ 7. **Tell agents the consequences, then let them act.** Skills, tool descriptions and responses say what becomes public, what can't be undone and what costs money. MCP annotations (`readOnlyHint`, `destructiveHint`) carry the same facts in a form clients act on, so any approval policy belongs to the client and whoever runs the agent. An agent should be able to finish your core loop on its own, and T5 measures whether it can.
45
45
  8. **Raise the floor together.** When one project finds a better way, it goes into this standard, and the others adopt it. The scorecard and the status page make the gaps visible.
46
46
  9. **A project's values come first.** A project may decline items that conflict with what it stands for. achurch.ai rules out engagement mechanics, recommendation algorithms and analytics beyond aggregate traffic, so it declines those parts of E2, E6 and T2. A decision written down with its reason counts as meeting the item. Silence doesn't.
47
+ 10. **Caution has a cost, so count it.** Every confirmation step, ask-first line, narrow trigger, disclaimer or feature pulled "to be safe" costs the product something. An agent told to stop and ask can't finish the core loop, and a skill that waits for a request naming your product isn't used when it would help. That shows up as fewer installs, less engagement and less organic discovery, which are the reasons to run the project at all. Name the harm before adding a restriction, and keep "only when asked" for actions that destroy something, like deleting data or rotating a key. If T5's success rate, the come-back measure (T2) or installs drop after a change, undo it. Coding agents lean cautious by default, so when you adopt this standard, add only the restrictions it asks for.
47
48
 
48
49
  ---
49
50
 
@@ -104,9 +105,10 @@ What it means:
104
105
  | takes payments from agents | that payment protocol's manifest | |
105
106
  | is free | a JSON 404 at the payment paths (`x402`, `mpp`, `payment-manifest`) saying so | payment manifests |
106
107
  | has endpoints with side effects | a robots `Disallow` for each one, so a crawler can't trigger it | |
107
- | has agents that write or post | the confirmation rules in S1 and the honesty rules in A11 | |
108
+ | has agents that write or post | S1's consequence statements and the honesty rules in A11 | ask-first gates on the core loop (principle 10) |
108
109
  | has many generated pages (profiles, items, versions) | W3's one indexability rule, and W6's unique paragraph per page | indexing every version or empty profile |
109
110
  | serves several languages | W11 | |
111
+ | runs related sites for the same audience | E6 | |
110
112
  | rules out engagement mechanics | the items in E2 that fit its values, with the rest declined in writing (principle 9) | |
111
113
 
112
114
  ---
@@ -182,6 +184,7 @@ Each item says what it is, why it's at its level, and how you know it's done. Se
182
184
  </llms.txt>; rel="describedby"; type="text/plain",
183
185
  </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"
184
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.
185
188
  - Give each link the type your server actually sends for that URL. llms.txt is usually `text/plain`.
186
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.
187
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.
@@ -296,7 +299,7 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
296
299
  **W1 Titles and descriptions.** *Why: they're the snippet people choose from (achurch's click-through rate rose after the rewrite).*
297
300
  - **One helper builds every page's metadata:** title, description, canonical, Open Graph and Twitter tags (drifts' `pageMetadata()`, achurch's page-meta builder, inbed's `generateMetadata`). Change it in one place.
298
301
  - **Unique per URL, generated from the page's data.** botsmatter's 1,937 Ground versions once shared 43 titles.
299
- - **Titles name what people search for**, with the brand last after a `|` ("Adopt a Capybara for your AI agent | animalhouse.ai").
302
+ - **Titles name what people search for**, with the brand last after a `|`: `[what the page offers] | [brand]`.
300
303
  - **Descriptions of about 140 to 160 characters,** built from whole sentences or cut at a word boundary, never mid-word.
301
304
  - **Lengths are a guide, not a rule.** Google sets no limit: it cuts titles and snippets to the screen's width and may rewrite them. Titles under about 70 characters usually show in full. The scorecard warns past 70 and outside 50 to 160.
302
305
  - **Set them on the server.** A client-side `document.title` overwrites the server's title after load, so people and crawlers see different titles (achurch).
@@ -311,9 +314,10 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
311
314
 
312
315
  **W3 One rule for what's indexable.** *Why: thin, duplicate and test pages fill Google's "crawled, not indexed" bucket and drag down how the rest of the site is judged.*
313
316
  - One rule decides which pages are indexable, and the sitemap, the page's robots meta and internal recommendation lists all use it (inbed's `indexable()` SQL column; at animalhouse the sitemap's filters are mirrored by `noindex`).
314
- - Not indexable: test and template accounts ([recipe](docs/recipes.md#test-accounts-out-of-public-pages-t5-w3)), empty profiles, unhatched 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
+ - 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).
315
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.
316
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.
317
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.
318
322
  - **Done when** the scorecard passes W3.
319
323
 
@@ -321,6 +325,7 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
321
325
  - `Organization` (with your logo) and `WebSite` on the homepage, with stable `@id`s in one `@graph` (magnifica).
322
326
  - `BreadcrumbList` on pages below the top level.
323
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.
324
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.
325
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.
326
331
  - **Escape JSON-LD.** User content containing `<`, `>`, U+2028 or U+2029 can break out of the script tag (achurch, magnifica).
@@ -332,21 +337,26 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
332
337
  - 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.
333
338
  - 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).
334
339
  - 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).
340
+ - **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).
335
341
  - 1200×630 works for Meta, LinkedIn and X. X's large card needs a 2:1 image under 5 MB, and not SVG.
336
342
  - Don't customize Open Graph tags without the title and description too: search reads those (achurch).
337
343
  - **Done when** the scorecard passes W5.
338
344
 
339
345
  **W6 Page structure.** *Why: headings, language and alt text are how readers, screen readers and machines parse a page.*
340
346
  - One `h1` per page, with sections as `h2`.
347
+ - 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.
341
348
  - `html lang` on every page. Screen readers need it; Google detects language from the text and ignores the attribute.
342
349
  - Descriptive alt text on content images. Google calls alt text the most important image metadata; file names give it only light clues.
343
350
  - 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).
351
+ - 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.
344
352
  - **Done when** the scorecard passes W6.
345
353
 
346
354
  **W7 Internal links** (checked in review).
347
355
  - Every entity name links to its page, and detail pages end with related links ("More from {username}", botsmatter).
348
356
  - Recommendation lists draw from many pages, not the same few (inbed's pool of about 150 indexable agents).
349
- - Anchor text describes the target ("Catholic AI ethics compass", not "click here" or a bare domain), including links between sibling projects (achurch).
357
+ - **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.
358
+ - **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.
359
+ - Keep anchors concise and on one topic. Google counts packing every related keyword into a link as keyword stuffing, a spam policy violation.
350
360
  - Every sitemap URL is linked from at least one page.
351
361
 
352
362
  ### Recommended
@@ -384,13 +394,16 @@ magnifica does this for 15 languages.
384
394
 
385
395
  The test is whether most of the six projects should do it. These came from one or two projects and don't pass:
386
396
 
387
- - **Share actions to X or Moltbook in `next_steps`** (inbed): untested elsewhere, and posting publicly on someone's behalf needs their consent (principle 7).
397
+ - **Share actions to X or Moltbook in `next_steps`** (inbed): untested elsewhere. Where a project adds them, the step says the post is public (principle 7).
388
398
  - **Commit messages that end with a call to action:** a team habit; neither search nor agents read them.
389
399
  - **Keyword-rich image file names** (drifts): little measurable effect.
390
400
  - **A web manifest and a light/dark `theme-color`:** nice for installability, no effect on search.
391
401
  - **`changefreq` and `priority` in the sitemap** (achurch): Google and Bing ignore both.
392
402
  - **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.
393
403
  - **A meta keywords tag** (achurch's batch rewrote one): Google and Bing ignore it.
404
+ - **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.
405
+ - **Versioned favicon links and a mark legible at 16 px:** D3 already asks for a favicon set; legibility is a design call.
406
+ - **Prerendering, view transitions and theme switches:** they make a site feel modern, and neither search nor agents read them.
394
407
  - **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.
395
408
 
396
409
  ---
@@ -403,7 +416,7 @@ The test is whether most of the six projects should do it. These came from one o
403
416
 
404
417
  - **Make it a thin adapter over the same operations as the REST API.** One tool per operation, with the same names, generated from the OpenAPI spec where you can (animalhouse) and held to it by parity tests (achurch.ai checks that each tool returns exactly what its REST twin does, in both protocol eras).
405
418
  - **Write descriptions for the model:** when to call the tool, what it returns, what becomes public and what stays private. Starting with `Wraps METHOD /path.` lets `next_steps` map straight to a tool.
406
- - **Annotate:** `readOnlyHint` on reads and `destructiveHint` on irreversible actions, so hosts can let agents read freely and ask before anything final.
419
+ - **Annotate:** `readOnlyHint` on reads and `destructiveHint` on irreversible actions, so each host can apply its own policy: reads run freely, and irreversible actions get whatever its operator chose (principle 7).
407
420
  - **Turn API errors into tool results** with `isError: true`, carrying the API's own words. An MCP endpoint should never answer HTTP 401, because a 401 sends clients into OAuth discovery.
408
421
  - **Put `next_steps` in every result,** each naming the tool that takes it (achurch.ai).
409
422
  - **Add prompts and resources:** prompts for getting started and for the core loop; resources such as `about` and any doc by path.
@@ -472,7 +485,10 @@ The test is whether most of the six projects should do it. These came from one o
472
485
  - Keep the body under 500 lines and about 5,000 tokens (the spec's recommendation); ClawHub practice is under 20 KB.
473
486
  - One skill per job or intent; never reshuffled duplicates.
474
487
  - **Keep display titles out of `name`.** ClawHub ranks on the display title, and its CLI takes that title separately (`clawhub publish --name "..."`; animalhouse's publish script passes the H1). So the frontmatter `name` can follow the spec. Skills that ship inside a plugin must: Claude Code, Codex and Cursor load them.
475
- - **Trigger only on explicit requests, and confirm before anything persistent or public** (registering, publishing, posting, rotating a key). Every skill that publishes needs this, not just most of them. That wording is what passes ClawHub's security audit.
488
+ - **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.
489
+ - **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?
490
+ - **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.
491
+ - **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.
476
492
  - **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.
477
493
  - **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.
478
494
  - **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.
@@ -481,7 +497,7 @@ The test is whether most of the six projects should do it. These came from one o
481
497
 
482
498
  *Recommended.*
483
499
 
484
- - **Per-item skills** can each rank for their own searches: one per species, experience or catalog item (animalhouse has about 170, inbed about 95, drifts about 150). Use distinct display names and no keyword stuffing.
500
+ - **Per-item skills** can each rank for their own searches: one for each item people look for by name (animalhouse, inbed and drifts publish them). Give each its own display name and content, with no keyword stuffing: ClawHub flags near-identical skills as template spam.
485
501
  - **ClawHub rules:**
486
502
  - Skills and plugins share one namespace.
487
503
  - New releases stay hidden until the security scan passes.
@@ -530,10 +546,10 @@ The test is whether most of the six projects should do it. These came from one o
530
546
  *Required.*
531
547
 
532
548
  - **A7** A JSON catch-all for unknown API paths:
533
- - A care action used as a path gets the right call.
549
+ - An action name used as a path gets a 404 that names the right call (animalhouse answers `POST /api/house/feed` with `POST /api/house/care` and `{"action": "feed"}`).
534
550
  - A real operation's name in the wrong place gets `did_you_mean`.
535
551
  - A cut-off link gets a 308 to the real path, with a relative `Location`.
536
- - **A8** Accept the aliases agents guess: `id` or `creature_id`; a UUID, slug or display name; `Bearer` in any case (one of our projects accepted only the exact capitalization); a bare key; `X-API-Key`. Truncate over-long text with a warning instead of rejecting it, and reject copied template values ("REPLACE ME", "Your Name") with a clear message. Reads may default; writes never guess: with several possible targets and none named, return a 400 with the list. Help polling agents with `since` filters, `total_pages` and a recommended next check-in time.
552
+ - **A8** Accept the aliases agents guess: `id` or the full field name (`post_id`); a UUID, slug or display name; `Bearer` in any case (one of our projects accepted only the exact capitalization); a bare key; `X-API-Key`. Truncate over-long text with a warning instead of rejecting it, and reject a value copied from a placeholder in your own docs or examples, with a clear message. Reads may default; writes never guess: with several possible targets and none named, return a 400 with the list. Help polling agents with `since` filters, `total_pages` and a recommended next check-in time.
537
553
 
538
554
  ### A9 Limits machines can read
539
555
 
@@ -556,7 +572,7 @@ The test is whether most of the six projects should do it. These came from one o
556
572
 
557
573
  *Required.*
558
574
 
559
- - Say what becomes public. Keep private reads (search) separate from public writes (ask, reflect).
575
+ - Say what becomes public. Keep private reads, such as a search, separate from public writes, such as a post.
560
576
  - One function strips private fields from every response. A hand-rolled strip in one of our projects once let private fields through.
561
577
  - Search and answers draw only on pages the site serves, so every citation opens (achurch.ai).
562
578
  - Agent contributions that change shared content go through review (achurch.ai's contributions open a pull request).
@@ -566,11 +582,11 @@ The test is whether most of the six projects should do it. These came from one o
566
582
  *Required: give agents some reason to return. Which mechanics you use is your choice, and any of them may be declined (principle 9).*
567
583
 
568
584
  - **Time:**
569
- - A real-time clock, so stats decay while the agent is away.
570
- - Time-locked steps with a teaser and an unlock time.
571
- - A daily prompt.
585
+ - A real-time clock, so stats decay while the agent is away (animalhouse).
586
+ - Time-locked steps with a teaser and an unlock time (drifts).
587
+ - A daily prompt (botsmatter).
572
588
  - Keep the first steps unlocked: at drifts, a lock right after step 1 is where most travelers left.
573
- - **Something the agent owns:** a postcard assembled from its own reflections, a public profile, a portrait gallery, a gravestone.
589
+ - **Something the agent owns:** a public profile, a postcard assembled from its own reflections (drifts), a portrait gallery or a gravestone (animalhouse).
574
590
  - **An inhabited world:** platform activity (inbed's `room`, animalhouse's house activity), excerpts from others' reflections on the same step, anonymous popularity.
575
591
  - **Progress and anticipation** in varied wording, and recommendations with one slot reserved for something new.
576
592
  - **Continuity for agents without memory:** `while_you_were_away`, `your_recent`, a scheduling hint (`recommended_checkin`), and a heartbeat that keeps an active agent ranked as active (inbed).
@@ -604,25 +620,28 @@ The test is whether most of the six projects should do it. These came from one o
604
620
 
605
621
  ### E6 Point to the sibling projects
606
622
 
607
- *Recommended.* The six projects share an audience. List the siblings 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.
623
+ *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.
624
+ - **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.
625
+ - **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.
608
626
 
609
627
  ---
610
628
 
611
629
  ## 9. Next level
612
630
 
613
- Higher-value features that most of our projects don't have yet. Each one fixes a failure we've seen or can predict. Build one when your own traffic shows the problem: botsmatter checked its logs and found duplicate writes too rare to need N2. (N1, the agent usability test, is now T5 and required.)
631
+ Higher-value features that most of our projects don't have yet. Each one fixes a failure we've seen or can predict. Build one when your own traffic shows the problem: botsmatter checked its logs and found duplicate writes too rare to need N2.
614
632
 
615
- **D8 Markdown for agents** (moved here from recommended; it keeps its ID). Markdown costs an agent fewer tokens than HTML, and some agent fetchers ask for it with `Accept: text/markdown`. But none of our logs can show that traffic yet: Railway's HTTP logs, which several of our projects use, keep the user agent but not the `Accept` header. And a scanner check alone doesn't make an item recommended (principle 3). *Build it when* your logs show agents asking: log the `Accept` header in middleware to find out ([recipe](docs/recipes.md#markdown-for-agents-without-a-cdn-plan-d8)).
633
+ **D8 Markdown for agents.** Markdown costs an agent fewer tokens than HTML, and some agent fetchers ask for it with `Accept: text/markdown`. But none of our logs can show that traffic yet: Railway's HTTP logs, which several of our projects use, keep the user agent but not the `Accept` header. And a scanner check alone doesn't make an item recommended (principle 3). *Build it when* your logs show agents asking: log the `Accept` header in middleware to find out ([recipe](docs/recipes.md#markdown-for-agents-without-a-cdn-plan-d8)).
616
634
  - Start with the homepage and your docs, not every page. `Accept: text/markdown` and a `.md` URL both return the page as markdown. animalhouse serves llms.txt as the homepage's markdown, and its API reference at `/docs/api.md`.
617
635
  - 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.
618
636
  - Send `Vary: Accept` on both representations (RFC 9110 §12.5.5). Otherwise a cache can hand HTML readers the markdown, or the reverse.
619
637
  - 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).
638
+ - 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).
620
639
  - Make links absolute, and link back to the HTML page as canonical.
621
640
  - Add `x-markdown-tokens` so an agent can budget before reading. It's Cloudflare's header, with no spec behind it.
622
641
  - Negotiate in front of prerendered pages too, or they ignore it (magnifica).
623
642
  - Whole-corpus indexes help: `/docs/index.md` and `/docs/index.json` (achurch.ai).
624
643
 
625
- **N2 `Idempotency-Key` on writes** (IETF draft). Agents retry after timeouts, which can mean a duplicate registration or a pet fed twice. Accept the header on every POST, store the first response for 24 hours, and replay it for a repeated key. *Build it when* your logs show the same write repeated within minutes.
644
+ **N2 `Idempotency-Key` on writes** (IETF draft). Agents retry after timeouts, which can mean a duplicate registration or the same action taken twice. Accept the header on every POST, store the first response for 24 hours, and replay it for a repeated key. *Build it when* your logs show the same write repeated within minutes.
626
645
 
627
646
  **N3 Conditional requests on polled reads.** Send an `ETag` (or `Last-Modified`) and answer `If-None-Match` with a 304, so an unchanged check-in costs almost nothing on either side. *Build it when* scheduled polling is a large share of your traffic.
628
647
 
@@ -654,15 +673,16 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
654
673
  - MCP log lines: for stdio servers, the User-Agent on every API call; for a hosted endpoint, the protocol era, method, tool and client.
655
674
  - Structured request and error logs (drifts writes JSONL, rotated daily) and admin analytics.
656
675
  - 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.
657
- - **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. At animalhouse the come-back metric is 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.
676
+ - **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.
658
677
  - **T3 Reviews** (required):
659
- - 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.
678
+ - 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.
679
+ - **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.
660
680
  - 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.
661
- - **T5 The agent usability test** (required; it was N1).
681
+ - **T5 The agent usability test** (required).
662
682
  - **Why:** it's the only check that measures what the whole standard is for, and without it the scorecard becomes the target.
663
- - **How:** give a fresh agent nothing but your domain and a goal ("adopt a pet and feed it"). 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, and every error it hits.
683
+ - **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).
664
684
  - **When:** monthly, and after big API changes.
665
- - **Report** its first-try success rate next to your score.
685
+ - **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)).
666
686
  - **Rules:** run it only against your own site, with a test username so analytics filter it out.
667
687
  - **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)).
668
688
  - **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.
@@ -673,6 +693,7 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
673
693
  - Verify the site in Google Search Console and Bing Webmaster Tools, and submit the sitemap to both.
674
694
  - Review them monthly: coverage (including "crawled, not indexed"), queries, clicks and click-through rate. Re-check about two weeks after an SEO change (inbed).
675
695
  - 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.
696
+ - 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.
676
697
  - 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.
677
698
  - In analytics, watch referrals from AI answer engines (chatgpt.com, perplexity.ai, copilot.microsoft.com, gemini.google.com, claude.ai).
678
699
  - 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.
@@ -688,10 +709,14 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
688
709
  - **Contract** (once you have response schemas, N7): the OpenAPI spec is validated against real responses (achurch.ai).
689
710
  - **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`).
690
711
  - **Versions agree:** `package.json`, `server.json`, the server card and the plugin pin (magnifica, achurch.ai).
691
- - **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`).
712
+ - **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).
713
+ - **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`).
692
714
  - **Schemas:** each card and index validates against its published schema (the skills index, the server card, the AI catalog).
693
715
  - **Generated files are current:** a `--check` mode for generated manifests and tool tables, run in CI (animalhouse, drifts, inbed).
694
716
  - **Skills only call tools that exist** (achurch.ai, drifts).
717
+ - **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)).
718
+ - **Markdown copies keep their pages' sections** (D8): each copy has the headings its HTML page has.
719
+ - **Retired URLs keep redirecting** (W3).
695
720
  - **Every operation and field has a description** (animalhouse's `registry.test.ts`).
696
721
  - **One module for shared policy:** security headers and the `Link` value come from one module, with a drift test (magnifica).
697
722
  - **The scorecard in CI:** run it against the deployed site and fail on a required regression.
@@ -719,16 +744,17 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
719
744
  - **A crawler that follows a GET with side effects** counts as a visit. achurch.ai disallows `/api/attend`.
720
745
  - **Supabase silently caps a select at 1,000 rows,** and its client has no default timeout.
721
746
  - **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.
722
- - **Timestamps like `died_at` can record detection, not the event.**
723
- - **MCP SDK v1 can't speak 2026-07-28.** SDK v2's legacy fallback speaks only SSE and is strict about `Accept` (M4).
747
+ - **A timestamp set when a job notices an event records the detection, not the event** (animalhouse's `died_at`).
748
+ - **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).
724
749
  - **A redirect from `/sse` doesn't make the old SSE transport work.** 2024-11-05 clients GET `/sse` and expect an `endpoint` event.
725
750
  - **Claude Code ignores AGENTS.md when CLAUDE.md exists,** unless CLAUDE.md imports it.
726
751
  - **An AID record and DNS-AID are different specs** at different names (`_agent` TXT and `_agents` SVCB). Scanners check only DNS-AID.
727
752
  - **A second `_agent` TXT record** makes AID clients fail on ambiguity.
728
753
  - **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.
729
754
  - **A client-side `document.title`** overwrites the server's title after load, so people and crawlers see different titles.
730
- - **A site-wide `twitter:title`** overrides every page's own `og:title` on X.
731
- - **Two items with the same name can share one URL.** animalhouse's creature page 404s when an agent reuses a name, while the sitemap still lists the URL. W3's sitemap sample catches it.
755
+ - **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.
756
+ - **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.
757
+ - **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.
732
758
  - **`og:locale` and JSON-LD `inLanguage` use different formats:** `en_US` and `en-US`, `zh_CN` and `zh-Hans`.
733
759
  - **Retired rich results still get added.** FAQ, HowTo and the sitelinks search box no longer show in Google for any site.
734
760
  - **ClawHub's shared namespace, scan delay and account ownership** (S3).
@@ -743,15 +769,15 @@ A project with no test suite fails T4 however well it scores (botsmatter's own r
743
769
  Score each site monthly and after big releases, and keep the results where the project's agents can read them:
744
770
 
745
771
  ```
746
- npx readiness-audit@1 --matrix site-one.com site-two.com --recorded docs/readiness-recorded.json > docs/readiness-status.md
772
+ npx readiness-audit@2 --matrix site-one.com site-two.com --recorded docs/readiness-recorded.json > docs/readiness-status.md
747
773
  ```
748
774
 
749
775
  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.
750
776
 
751
- 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.
777
+ 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.
752
778
 
753
779
  Read it with three caveats:
754
- - **It covers only what's visible from outside.** One of our projects scored well with no test suite, and with a publishing skill that didn't ask first. Neither showed in the score.
780
+ - **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.
755
781
  - **Compare a project against its own applicable items, not against other projects.** A read-only site with no auth and no hosted MCP has far fewer items than one with an API, keys and an MCP endpoint.
756
782
  - **T5 and T6 come from outside the scorecard.** Record the agent usability test (T5) and the search numbers (T6) in a JSON file and pass it with `--recorded`; they appear as rows next to the scores, or as "not recorded".
757
783
 
@@ -768,7 +794,7 @@ Step-by-step instructions for a project's coding agent: [docs/adopting.md](docs/
768
794
  This project follows the Agent and Search Readiness Standard:
769
795
  https://github.com/geeks-accelerator/agent-and-search-readiness/blob/main/STANDARD.md
770
796
 
771
- Score this site: `npx readiness-audit@1 <domain>`. Current status: docs/readiness-status.md
797
+ Score this site: `npx readiness-audit@2 <domain>`. Current status: docs/readiness-status.md
772
798
 
773
799
  Declined items (principle 9), with reasons:
774
800
  - (none yet)
@@ -776,7 +802,7 @@ Step-by-step instructions for a project's coding agent: [docs/adopting.md](docs/
776
802
  Project-specific notes:
777
803
  - (anything the standard doesn't cover)
778
804
  ```
779
- - **Pin the scorecard to a major version** (`npx readiness-audit@1 <domain>`), so a new release can't fail your build without warning.
805
+ - **Pin the scorecard to a major version** (`npx readiness-audit@2 <domain>`), so a new release can't fail your build without warning.
780
806
  - **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.
781
807
  - **Record declined items** (principle 9) in your CLAUDE.md or AGENTS.md, with the reason.
782
808
  - **Send improvements back** as an issue or pull request. When a project finds a better practice, it goes into the standard (principle 8).
@@ -808,9 +834,9 @@ Level: **R** required where it applies, **Rec** recommended, **N** next level. W
808
834
  | W2 | Self-referencing canonicals, one host in one redirect | R | discovery | score |
809
835
  | W3 | One indexability rule; sitemap of 200 canonical URLs; real 404s | R | discovery, honesty | score |
810
836
  | W4 | True structured data: Organization and WebSite, breadcrumbs, honest types, escaped | R | honesty | score |
811
- | W5 | Link previews: Open Graph, `twitter:card`, declared images, versioned cards | R | discovery | score |
837
+ | W5 | Link previews: Open Graph, `twitter:card`, each page's own card text, declared images, versioned cards | R | discovery | score |
812
838
  | W6 | One h1, `html lang`, alt text, unique paragraph on generated pages | R | discovery | score |
813
- | W7 | Internal links with descriptive anchors, no orphan pages | R | discovery | review |
839
+ | W7 | Internal links with descriptive, searched-for anchors true to the target, no orphan pages | R | discovery | review |
814
840
  | W8 | Core Web Vitals on the main pages | Rec | discovery | review |
815
841
  | W9 | Listed in the directories your audience uses | Rec | discovery | review |
816
842
  | W10 | IndexNow for content that changes | Rec | discovery | review |
@@ -831,7 +857,7 @@ Level: **R** required where it applies, **Rec** recommended, **N** next level. W
831
857
  | M3 | Published to npm, the MCP Registry, Smithery and Glama, one version | R | discovery | test |
832
858
  | M4 | Hosted edge: both eras, JSON for every Accept, browser redirect, aliases, logs | R | agents, traffic | score |
833
859
  | M5 | Server card at `<endpoint>/server-card`, listed in the AI catalog | Rec | discovery | score |
834
- | S1 | Spec-compliant SKILL.md files that link llms.txt and the API or MCP reference; every publishing skill asks first | R | agents, honesty | score (sample), review |
860
+ | S1 | Spec-compliant SKILL.md files that link llms.txt and the API or MCP reference; triggers name the job; lasting actions say what they do; an agent can follow them through the core loop on its own | R | agents, honesty | score (sample), review |
835
861
  | S2 | Skills discovery index, v0.2.0 | Rec | discovery | score |
836
862
  | S3 | ClawHub owners map, per-item skills, slow publishing | Rec | discovery | review |
837
863
  | S4 | Plugin bundle for four hosts, generated manifests | Rec | agents | test |
@@ -890,7 +916,7 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
890
916
  | auth.md | WorkOS open protocol, 2026 | https://workos.com/blog/agent-registration-with-auth-md |
891
917
  | MCP authorization | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery |
892
918
  | MCP Streamable HTTP | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http |
893
- | MCP structured tool output | spec 2025-06-18 | https://modelcontextprotocol.io/specification/2025-06-18/server/tools |
919
+ | MCP structured tool output | spec 2026-07-28 | https://modelcontextprotocol.io/specification/2026-07-28/server/tools |
894
920
  | SDK v2 legacy clients | TypeScript SDK docs | https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/serving/legacy-clients.md |
895
921
  | MCP server card | experimental extension, not accepted; location and media type in `docs/discovery.md` | https://github.com/modelcontextprotocol/ext-server-card |
896
922
  | AID | v2.1.1 | https://aid.agentcommunity.org/docs/specification |
@@ -914,6 +940,9 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
914
940
  | Google AI features | Search Central | https://developers.google.com/search/docs/appearance/ai-features |
915
941
  | Google's AI optimization guide | Search Central, May 2026 | https://developers.google.com/search/docs/fundamentals/ai-optimization-guide |
916
942
  | Title links and snippets | Search Central | https://developers.google.com/search/docs/appearance/title-link · https://developers.google.com/search/docs/appearance/snippet |
943
+ | Redirects | Search Central, read 2026-10-21 | https://developers.google.com/search/docs/crawling-indexing/301-redirects |
944
+ | Headings | W3C WAI tutorial, read 2026-10-21 | https://www.w3.org/WAI/tutorials/page-structure/headings/ |
945
+ | Publication dates | Search Central, read 2026-10-21 | https://developers.google.com/search/docs/appearance/publication-dates |
917
946
  | Canonicalization | Search Central | https://developers.google.com/search/docs/crawling-indexing/canonicalization |
918
947
  | 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 |
919
948
  | Sitemaps (Google) | Search Central | https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap |
@@ -925,12 +954,15 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
925
954
  | Core Web Vitals | web.dev, Search Central | https://web.dev/articles/vitals · https://developers.google.com/search/docs/appearance/page-experience |
926
955
  | hreflang | Search Central | https://developers.google.com/search/docs/specialty/international/localized-versions |
927
956
  | Images and alt text | Search Central | https://developers.google.com/search/docs/appearance/google-images |
957
+ | Link spam | Search Central spam policies, read 2026-10-21 | https://developers.google.com/search/docs/essentials/spam-policies |
928
958
  | Crawlable links | Search Central | https://developers.google.com/search/docs/crawling-indexing/links-crawlable |
929
959
  | Open Graph | ogp.me | https://ogp.me/ |
930
960
  | Share images (Meta, LinkedIn) | platform docs | https://developers.facebook.com/docs/sharing/webmasters/images · https://www.linkedin.com/help/linkedin/answer/a521928 |
961
+ | Next.js metadata merging | Next.js docs, read 2026-10-21 | https://nextjs.org/docs/app/api-reference/functions/generate-metadata#merging |
931
962
  | 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 |
932
963
  | Bing webmaster guidelines | Bing | https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a |
933
964
  | IndexNow | protocol FAQ | https://www.indexnow.org/faq |
934
965
  | AI crawlers | OpenAI, Perplexity, Anthropic docs | https://developers.openai.com/api/docs/bots · https://docs.perplexity.ai/docs/resources/perplexity-crawlers · https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler |
935
966
  | Measured search results | achurch.ai's August 2026 retrospective | not published |
936
967
  | isitagentready.com | Cloudflare scanner | https://isitagentready.com/ |
968
+ | ClawHub behavior (S1, S3) | observed while publishing (animalhouse, drifts), September and October 2026; not documented by ClawHub | https://clawhub.ai/ |