readiness-audit 2.0.0 → 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 +7 -0
- package/README.md +2 -0
- package/STANDARD.md +8 -2
- package/bin/readiness-audit.mjs +4 -1
- package/package.json +1 -1
- package/src/audit.mjs +16 -4
- package/src/helpers.mjs +38 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
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
|
+
|
|
3
10
|
## 2.0.0 (2026-10-21)
|
|
4
11
|
|
|
5
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`.
|
package/README.md
CHANGED
|
@@ -52,6 +52,8 @@ The scorecard covers what's visible from outside. It checks:
|
|
|
52
52
|
- a sample of skill files: spec names and descriptions, and links to llms.txt and the API reference;
|
|
53
53
|
- markdown negotiation, the AI catalog, the DNS AID record, the API catalog, auth.md and the skills index.
|
|
54
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
|
+
|
|
55
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.
|
|
56
58
|
|
|
57
59
|
## Use it in your project
|
package/STANDARD.md
CHANGED
|
@@ -329,7 +329,9 @@ The evidence that this work pays: achurch.ai's August batch rewrote titles and s
|
|
|
329
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.
|
|
330
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.
|
|
331
331
|
- **Escape JSON-LD.** User content containing `<`, `>`, U+2028 or U+2029 can break out of the script tag (achurch, magnifica).
|
|
332
|
-
- **
|
|
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.
|
|
333
335
|
|
|
334
336
|
**W5 Link previews.** *Why: a shared link is how many people, and some agents, first see a page.*
|
|
335
337
|
- Open Graph (`og:type`, `og:url`, `og:title`, `og:description`, `og:image`) and `twitter:card` set to `summary_large_image` on every page.
|
|
@@ -693,6 +695,7 @@ Higher-value features that most of our projects don't have yet. Each one fixes a
|
|
|
693
695
|
- Verify the site in Google Search Console and Bing Webmaster Tools, and submit the sitemap to both.
|
|
694
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).
|
|
695
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.
|
|
696
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.
|
|
697
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.
|
|
698
701
|
- In analytics, watch referrals from AI answer engines (chatgpt.com, perplexity.ai, copilot.microsoft.com, gemini.google.com, claude.ai).
|
|
@@ -833,7 +836,7 @@ Level: **R** required where it applies, **Rec** recommended, **N** next level. W
|
|
|
833
836
|
| W1 | Titles and descriptions: one helper, unique, searched-for words, 140 to 160 character descriptions | R | traffic | score |
|
|
834
837
|
| W2 | Self-referencing canonicals, one host in one redirect | R | discovery | score |
|
|
835
838
|
| W3 | One indexability rule; sitemap of 200 canonical URLs; real 404s | R | discovery, honesty | score |
|
|
836
|
-
| W4 | True structured data: Organization and WebSite, breadcrumbs, honest types, escaped | R | honesty | score |
|
|
839
|
+
| W4 | True structured data: Organization and WebSite, breadcrumbs, honest types, escaped, tested in Google's Rich Results Test | R | honesty | score, review |
|
|
837
840
|
| W5 | Link previews: Open Graph, `twitter:card`, each page's own card text, declared images, versioned cards | R | discovery | score |
|
|
838
841
|
| W6 | One h1, `html lang`, alt text, unique paragraph on generated pages | R | discovery | score |
|
|
839
842
|
| W7 | Internal links with descriptive, searched-for anchors true to the target, no orphan pages | R | discovery | review |
|
|
@@ -941,6 +944,9 @@ Status as of 2026-10-05. Several are drafts, so re-check before relying on a det
|
|
|
941
944
|
| Google's AI optimization guide | Search Central, May 2026 | https://developers.google.com/search/docs/fundamentals/ai-optimization-guide |
|
|
942
945
|
| Title links and snippets | Search Central | https://developers.google.com/search/docs/appearance/title-link · https://developers.google.com/search/docs/appearance/snippet |
|
|
943
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 |
|
|
944
950
|
| Headings | W3C WAI tutorial, read 2026-10-21 | https://www.w3.org/WAI/tutorials/page-structure/headings/ |
|
|
945
951
|
| Publication dates | Search Central, read 2026-10-21 | https://developers.google.com/search/docs/appearance/publication-dates |
|
|
946
952
|
| Canonicalization | Search Central | https://developers.google.com/search/docs/crawling-indexing/canonicalization |
|
package/bin/readiness-audit.mjs
CHANGED
|
@@ -115,7 +115,10 @@ if (flag('--matrix')) {
|
|
|
115
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')}`);
|
|
116
116
|
if (changes) console.log(`\n${formatComparison(changes, since).join('\n')}`);
|
|
117
117
|
console.log('\nNot scored, so check these yourself:');
|
|
118
|
-
for (const [id, what] of REVIEW)
|
|
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
|
+
}
|
|
119
122
|
}
|
|
120
123
|
process.exitCode = rep.results.some((r) => r.level === 'required' && r.status === 'fail') ? 1 : 0;
|
|
121
124
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "readiness-audit",
|
|
3
|
-
"version": "2.
|
|
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": {
|
package/src/audit.mjs
CHANGED
|
@@ -9,9 +9,9 @@
|
|
|
9
9
|
import { lookup, resolveTxt, Resolver } from 'node:dns/promises';
|
|
10
10
|
import { isIP } from 'node:net';
|
|
11
11
|
import { request } from './http.mjs';
|
|
12
|
-
import { SKILL_NAME, sampleSkillEntries, skillNameProblem, cdnCacheNote, repeatsSummary, hasVariantDescription, spread, samplePages, sharedCardText, API_LINK, MCP_LINK, linkRels, apiPresence, DISCOVERY_FILES, AI_BOTS, missingSections, list, norm, pathDepth, decodeText, headings, headingSkips, sitemapEntries, llmsLinks, baseMapper, formatRecorded } from './helpers.mjs';
|
|
12
|
+
import { SKILL_NAME, sampleSkillEntries, skillNameProblem, cdnCacheNote, repeatsSummary, hasVariantDescription, spread, samplePages, sharedCardText, API_LINK, MCP_LINK, linkRels, apiPresence, DISCOVERY_FILES, AI_BOTS, missingSections, richResultPages, list, norm, pathDepth, decodeText, headings, headingSkips, sitemapEntries, llmsLinks, baseMapper, formatRecorded } from './helpers.mjs';
|
|
13
13
|
|
|
14
|
-
export const VERSION = '2.
|
|
14
|
+
export const VERSION = '2.1.0';
|
|
15
15
|
export const REPO = 'https://github.com/geeks-accelerator/agent-and-search-readiness';
|
|
16
16
|
const UA = `readiness-audit/${VERSION} (+${REPO})`;
|
|
17
17
|
const AID_PROTOCOLS = ['mcp', 'a2a', 'openapi', 'grpc', 'graphql', 'websocket', 'local', 'zeroconf', 'ucp'];
|
|
@@ -22,6 +22,7 @@ const ORDER = ['D1', 'D2', 'D4', 'D6', 'D11', 'D12', 'W1', 'W2', 'W3', 'W4', 'W5
|
|
|
22
22
|
// Items the scorecard can't see from outside. Each project checks these in review and tests.
|
|
23
23
|
export const REVIEW = [
|
|
24
24
|
['D3', 'pages read well: server-rendered, unique prose on generated pages (the scorecard checks W1 to W6 on a sample)'],
|
|
25
|
+
['W4', 'Google\'s Rich Results Test on one page per kind of markup (listed below: the scorecard checks the markup parses, Google checks its required properties), after deploying a change to a template\'s markup; Search Console\'s rich result reports cover every page (T6)'],
|
|
25
26
|
['W7', 'internal links: entity names link to their pages, anchors that say what the target is (not the brand alone), no orphan pages; sibling links in context, never sitewide (E6)'],
|
|
26
27
|
['W8', 'Core Web Vitals on the main pages (Lighthouse or PageSpeed Insights)'],
|
|
27
28
|
['W9', 'listed in the directories your audience uses'],
|
|
@@ -611,11 +612,13 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
611
612
|
|
|
612
613
|
// ---- W: search, on a sample of sitemap pages ----
|
|
613
614
|
let htmlKb = null; // median HTML size of the sampled pages, reported, not scored
|
|
615
|
+
let richTest = []; // the pages to run through Google's Rich Results Test (W4, in review)
|
|
614
616
|
{
|
|
615
617
|
const urls = entries.map((e) => e.loc);
|
|
616
618
|
const sample = samplePages(urls);
|
|
617
619
|
const pick = sample.pages;
|
|
618
|
-
const
|
|
620
|
+
const templateOf = new Map(sample.templates.flatMap((t) => t.urls.map((u) => [norm(u), t.pattern])));
|
|
621
|
+
const templatePages = new Set(templateOf.keys());
|
|
619
622
|
const sampled = `${pick.length} sampled pages (${sample.static} static, ${sample.templates.length ? `${sample.templates.length} template${sample.templates.length === 1 ? '' : 's'}` : 'no templates'}${sample.skipped ? `; ${sample.skipped} static pages over the cap not read` : ''})`;
|
|
620
623
|
const attrs = (tag) => Object.fromEntries([...tag.matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)].map((m) => [m[1].toLowerCase(), m[3] ?? m[4]]));
|
|
621
624
|
const tags = (html, name) => [...html.matchAll(new RegExp(`<${name}\\b[^>]*>`, 'gi'))].map((m) => attrs(m[0]));
|
|
@@ -746,6 +749,10 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
746
749
|
const deepPages = ok200.filter((p) => templatePages.has(norm(p.url)) && pathDepth(p.url) >= 2);
|
|
747
750
|
const noCrumbs = deepPages.filter((p) => !p.types.includes('BreadcrumbList')).map((p) => short(p.url));
|
|
748
751
|
const all = new Set(ok200.flatMap((p) => p.types));
|
|
752
|
+
// One page per kind of markup: the homepage, a page of each template, then the rest.
|
|
753
|
+
const homePage = ok200.find((p) => short(p.url) === '/') ?? (home.status === 200 ? { url: `${BASE}/`, types: homeTypes } : null);
|
|
754
|
+
const isTemplate = (p) => templatePages.has(norm(p.url));
|
|
755
|
+
richTest = richResultPages([homePage, ...ok200.filter(isTemplate).map((p) => ({ ...p, template: templateOf.get(norm(p.url)) })), ...ok200.filter((p) => !isTemplate(p))].filter(Boolean));
|
|
749
756
|
const notes = [];
|
|
750
757
|
if (all.has('FAQPage') || all.has('HowTo')) notes.push(`${['FAQPage', 'HowTo'].filter((t) => all.has(t)).join(' and ')} markup earns no rich results in Google anymore (HowTo ended in 2023, FAQ in May 2026); keep it only where the page really is one`);
|
|
751
758
|
if (all.has('Person')) notes.push('Person markup found: fine on a profile the page labels as an AI agent; don\'t imply a human');
|
|
@@ -859,7 +866,7 @@ export async function audit(domain, { mcpPath = '/mcp', base = null } = {}) {
|
|
|
859
866
|
}
|
|
860
867
|
|
|
861
868
|
results.sort((a, b) => LEVELS.indexOf(a.level) - LEVELS.indexOf(b.level) || ORDER.indexOf(a.id) - ORDER.indexOf(b.id));
|
|
862
|
-
return { domain, base: baseOrigin, version: VERSION, checked_at: new Date().toISOString(), hosted_mcp: hosted, has_api: api.present, html_kb_median: htmlKb, results };
|
|
869
|
+
return { domain, base: baseOrigin, version: VERSION, checked_at: new Date().toISOString(), hosted_mcp: hosted, has_api: api.present, html_kb_median: htmlKb, rich_results_test: richTest, results };
|
|
863
870
|
}
|
|
864
871
|
|
|
865
872
|
export function score(results, level) {
|
|
@@ -900,5 +907,10 @@ export function matrix(reports, command, recorded = {}) {
|
|
|
900
907
|
out.push('');
|
|
901
908
|
}
|
|
902
909
|
out.push('## Checked in review and tests, not scored', '', ...REVIEW.map(([id, what]) => `- **${id}**: ${what}`), '');
|
|
910
|
+
const rich = reports.filter((rep) => rep.rich_results_test?.length);
|
|
911
|
+
if (rich.length) {
|
|
912
|
+
out.push('## Pages for Google\'s Rich Results Test (W4)', '', 'One page per kind of markup. Pages built from one template share it, so one tests them all.', '');
|
|
913
|
+
for (const rep of rich) out.push(`**${rep.domain}**`, '', ...rep.rich_results_test.map((p) => `- [${p.url}](${p.test}): ${p.features.join(', ')}`), '');
|
|
914
|
+
}
|
|
903
915
|
return out.join('\n');
|
|
904
916
|
}
|
package/src/helpers.mjs
CHANGED
|
@@ -68,6 +68,44 @@ export function headingSkips(hs) {
|
|
|
68
68
|
return skips;
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
+
/**
|
|
72
|
+
* schema.org types that can earn a Google rich result, by the feature Google's search gallery
|
|
73
|
+
* names (read 2026-10-21; the gallery was updated 2026-10-16). FAQ and HowTo aren't there anymore.
|
|
74
|
+
*/
|
|
75
|
+
export const GOOGLE_RICH_RESULTS = {
|
|
76
|
+
Article: ['Article', 'NewsArticle', 'BlogPosting'], Breadcrumb: ['BreadcrumbList'], 'Course list': ['Course'], Dataset: ['Dataset'],
|
|
77
|
+
'Discussion forum': ['DiscussionForumPosting'], 'Education Q&A': ['Quiz'], 'Employer aggregate rating': ['EmployerAggregateRating'],
|
|
78
|
+
Event: ['Event'], 'Image metadata': ['ImageObject'], 'Job posting': ['JobPosting'], 'Local business': ['LocalBusiness'],
|
|
79
|
+
'Math solver': ['MathSolver'], Movie: ['Movie'], Organization: ['Organization'], Product: ['Product'], 'Profile page': ['ProfilePage'],
|
|
80
|
+
'Q&A': ['QAPage'], Recipe: ['Recipe'], 'Review snippet': ['Review', 'AggregateRating'],
|
|
81
|
+
'Software app': ['SoftwareApplication', 'MobileApplication', 'WebApplication', 'VideoGame'], 'Vacation rental': ['VacationRental'], Video: ['VideoObject'],
|
|
82
|
+
};
|
|
83
|
+
const RICH_FEATURE = new Map(Object.entries(GOOGLE_RICH_RESULTS).flatMap(([feature, types]) => types.map((t) => [t, feature])));
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The pages to run through Google's Rich Results Test. Pages from one template share their markup,
|
|
87
|
+
* so one page tests them all; each template is its own code, so each one with rich-result markup is
|
|
88
|
+
* listed once. Candidates come in order (the homepage, the template pages, then the rest), each
|
|
89
|
+
* { url, types, template } with template the page's template pattern, if any; a page outside a
|
|
90
|
+
* template is kept only when it adds a feature no kept page has.
|
|
91
|
+
* Returns up to `max` { url, features, test }.
|
|
92
|
+
*/
|
|
93
|
+
export function richResultPages(pages, max = 8) {
|
|
94
|
+
const seen = new Set();
|
|
95
|
+
const listedTemplates = new Set();
|
|
96
|
+
const out = [];
|
|
97
|
+
for (const p of pages) {
|
|
98
|
+
const features = [...new Set((p.types ?? []).map((t) => RICH_FEATURE.get(t)).filter(Boolean))].sort();
|
|
99
|
+
if (!features.length || listedTemplates.has(p.template)) continue;
|
|
100
|
+
if (!p.template && !features.some((f) => !seen.has(f))) continue;
|
|
101
|
+
if (p.template) listedTemplates.add(p.template);
|
|
102
|
+
features.forEach((f) => seen.add(f));
|
|
103
|
+
out.push({ url: p.url, features, test: `https://search.google.com/test/rich-results?url=${encodeURIComponent(p.url)}` });
|
|
104
|
+
if (out.length === max) break;
|
|
105
|
+
}
|
|
106
|
+
return out;
|
|
107
|
+
}
|
|
108
|
+
|
|
71
109
|
/** A sitemap's entries, urlset or index, as { loc, lastmod } (lastmod undefined when absent). */
|
|
72
110
|
export function sitemapEntries(xml) {
|
|
73
111
|
return [...String(xml ?? '').matchAll(/<(url|sitemap)>([\s\S]*?)<\/\1>/g)].map((m) => ({
|