{"version":"0.2.0","checked":"2026-11-02","count":113,"layers":[{"id":"perception","name":"Perception","summary":"How agents see the page: semantic HTML, accessibility tree, server vs rendered","weight":3,"chapters":"2,3"},{"id":"crawl","name":"Crawler access","summary":"robots.txt groups per AI crawler, content signals, sitemaps, bot challenges","weight":2,"chapters":"4"},{"id":"structured","name":"Structured data","summary":"JSON-LD validity against schema.org and parity with visible content","weight":2,"chapters":"5"},{"id":"content","name":"Agent-readable content","summary":"Markdown negotiation, llms.txt, Link headers, feeds","weight":2,"chapters":"6"},{"id":"api","name":"APIs","summary":"api-catalog, OpenAPI quality, problem+json, rate-limit headers","weight":1.5,"chapters":"7,10,13"},{"id":"mcp","name":"MCP","summary":"Server card, live initialize/tools/list probe, schemas, Origin validation","weight":1,"chapters":"8,10,11"},{"id":"webmcp","name":"WebMCP","summary":"Declarative and imperative tools found in a real browser","weight":1,"chapters":"9,10"},{"id":"discovery","name":"Discovery","summary":"ARD, Agent Skills, A2A, DNS-AID, well-known hygiene","weight":1,"chapters":"11"},{"id":"commerce","name":"Commerce","summary":"UCP, ACP, x402, MPP, AP2, product data (scored only on shops)","weight":1,"chapters":"12"},{"id":"identity","name":"Identity & auth","summary":"OAuth AS/PRM metadata, PKCE, CIMD, auth.md, Web Bot Auth","weight":1,"chapters":"14,15"},{"id":"security","name":"Security","summary":"Hidden prompt injection, tool annotations, HTTPS, headers","weight":2,"chapters":"16"},{"id":"privacy","name":"Privacy & consent","summary":"Policy links, consent overlays, GPC, human confirmation","weight":1,"chapters":"17"},{"id":"performance","name":"Performance & stability","summary":"CLS, TTFB, compression, redirects, page weight","weight":1,"chapters":"3,19"}],"checks":[{"id":"perception.html-lang","layer":"perception","title":"<html lang> declares the page language","severity":1,"standard":{"key":"html","name":"HTML Living Standard","body":"WHATWG","version":"Living Standard","date":"continuous","status":"Living Standard","maturity":"standard","url":"https://html.spec.whatwg.org/"},"chapter":3,"test":"Parse server HTML; pass if html[lang] is a valid BCP 47 tag","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"The lang attribute tells agents and screen readers which language the page is in, so they read, translate and quote it correctly (book chapter 3).","fix":{"snippet":"<html lang=\"en\">","prompt":"Set the lang attribute on the <html> element of every page template to the page's BCP 47 language tag (for example \"en\", \"nb-NO\"), and lang on any inline passage in another language."},"implemented":true},{"id":"perception.title","layer":"perception","title":"Page has a descriptive <title>","severity":2,"standard":{"key":"html","name":"HTML Living Standard","body":"WHATWG","version":"Living Standard","date":"continuous","status":"Living Standard","maturity":"standard","url":"https://html.spec.whatwg.org/"},"chapter":3,"test":"Parse server HTML; fail if missing/empty, warn if generic (Home, Untitled) or > 70 chars","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"The <title> is the first thing an agent reads and the label it uses when it cites or links your page. A missing or generic title makes every page look the same (book chapter 3).","fix":{"snippet":"<title>Fjellro cabin: 2 bedrooms, sauna, sleeps 6 | Nordlys Cabins</title>","prompt":"Give every page a unique, descriptive <title> in the server HTML: what the page is first, then the site name, under about 70 characters."},"implemented":true},{"id":"perception.landmarks","layer":"perception","title":"Landmarks: one <main>, plus header/nav/footer","severity":2,"standard":{"key":"aria","name":"WAI-ARIA","body":"W3C","version":"1.2","date":"2023-06-06","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/wai-aria-1.2/"},"chapter":3,"test":"Parse server HTML; count main/role=main (exactly 1), nav, header, footer","iia":null,"lh":null,"roles":["dev","design"],"requires":"http","applies":"always","heuristic":false,"why":"Landmarks (one <main>, plus header, nav and footer) let an agent jump straight to the content and skip the chrome, the same way screen-reader users do (book chapter 3).","fix":{"snippet":"<header>...</header>\n<nav aria-label=\"Main\">...</nav>\n<main>...page content...</main>\n<footer>...</footer>","prompt":"Wrap each page's primary content in exactly one <main> element, and use <header>, <nav> and <footer> (or the matching ARIA roles) for the site chrome in the shared layout template."},"implemented":true},{"id":"perception.headings","layer":"perception","title":"Heading outline: one <h1>, no skipped levels","severity":2,"standard":{"key":"html","name":"HTML Living Standard","body":"WHATWG","version":"Living Standard","date":"continuous","status":"Living Standard","maturity":"standard","url":"https://html.spec.whatwg.org/"},"chapter":3,"test":"Parse server HTML; list h1-h6 in order, fail if no h1, warn if >1 h1 or level jumps","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"Headings are the outline an agent uses to find the part of the page it needs. One <h1> naming the page and levels without gaps make that outline reliable (book chapter 3).","fix":{"snippet":"<h1>Fjellro cabin</h1>\n  <h2>Rooms</h2>\n  <h2>Prices</h2>\n    <h3>High season</h3>","prompt":"Fix the heading outline in the page templates: exactly one <h1> that names the page, then <h2> for sections and <h3> inside them, without skipping levels. Style with CSS, not by picking heading levels for size."},"implemented":true},{"id":"perception.form-labels","layer":"perception","title":"Every form control has an accessible name","severity":3,"standard":{"key":"wcag","name":"WCAG","body":"W3C","version":"2.2","date":"2023-10-05","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/WCAG22/"},"chapter":3,"test":"Static: input/select/textarea (not hidden/submit) need <label for>, wrapping label, aria-label(ledby) or title","iia":null,"lh":null,"roles":["dev","design","qa"],"requires":"http","applies":"always","heuristic":false,"why":"An agent fills a form by matching field names to what it knows. A field without a label (only a placeholder, or nothing) is a guess, and the guess books the wrong date (book chapter 3).","fix":{"snippet":"<label for=\"checkin\">Check-in date</label>\n<input id=\"checkin\" name=\"checkin\" type=\"date\" required>","prompt":"Give every input, select and textarea an accessible name: a <label for> matching its id (preferred), a wrapping <label>, or aria-label/aria-labelledby. Do not rely on placeholder text alone."},"implemented":true},{"id":"perception.control-names","layer":"perception","title":"Buttons and links have accessible names","severity":3,"standard":{"key":"wcag","name":"WCAG","body":"W3C","version":"2.2","date":"2023-10-05","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/WCAG22/"},"chapter":3,"test":"Static: button, a[href], [role=button] need text, aria-label, aria-labelledby, img alt or title","iia":null,"lh":null,"roles":["dev","design","qa"],"requires":"http","applies":"always","heuristic":false,"why":"Agents act on buttons and links by name. An icon-only button with no label is invisible to them: they cannot tell \"Book\" from \"Delete\" (book chapter 3).","fix":{"snippet":"<button type=\"button\" aria-label=\"Add to favourites\"><svg aria-hidden=\"true\">...</svg></button>","prompt":"Give every button and link visible text or, for icon-only controls, an aria-label (or an <img alt>/<svg><title>) that says what it does. Check the shared components (icon buttons, social links, close buttons) first."},"implemented":true},{"id":"perception.click-divs","layer":"perception","title":"No click-only <div>/<span> controls","severity":3,"standard":{"key":"aria","name":"WAI-ARIA","body":"W3C","version":"1.2","date":"2023-06-06","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/wai-aria-1.2/"},"chapter":3,"test":"Static: div/span with onclick or [data-action]-like handlers and no role/tabindex; browser run adds cursor:pointer elements without role","iia":null,"lh":null,"roles":["dev","design"],"requires":"http","applies":"always","heuristic":false,"why":"A <div> or <span> with a click handler looks like a button to a person but not to an agent: it has no role, no keyboard access and does not show up in the accessibility tree as something to press (book chapter 3).","fix":{"snippet":"<!-- instead of <div onclick=\"book()\">Book</div> -->\n<button type=\"button\" onclick=\"book()\">Book</button>","prompt":"Replace clickable <div>/<span> elements with real <button> or <a href> elements (or, if that is impossible, add role=\"button\", tabindex=\"0\" and Enter/Space key handlers). Search the templates for onclick, @click, v-on:click, (click) and ng-click on non-interactive elements."},"implemented":true},{"id":"perception.img-alt","layer":"perception","title":"Images have alt text","severity":1,"standard":{"key":"wcag","name":"WCAG","body":"W3C","version":"2.2","date":"2023-10-05","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/WCAG22/"},"chapter":3,"test":"Static: img without alt attribute (alt=\"\" allowed for decoration)","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"Alt text is how an agent knows what an image shows: the cabin photo, the floor plan, the price table saved as a picture. alt=\"\" is right for decoration; a missing alt is a gap (book chapter 3).","fix":{"snippet":"<img src=\"/img/fjellro-sauna.jpg\" alt=\"Wood-fired sauna on the Fjellro cabin terrace\">\n<img src=\"/img/divider.svg\" alt=\"\">","prompt":"Add an alt attribute to every <img>: a short description of what the image shows for content images, alt=\"\" for purely decorative ones. Fix it in the image component so new images cannot ship without alt."},"implemented":true},{"id":"perception.native-forms","layer":"perception","title":"Key forms are real <form>s with a submit button and action","severity":2,"standard":{"key":"html","name":"HTML Living Standard","body":"WHATWG","version":"Living Standard","date":"continuous","status":"Living Standard","maturity":"standard","url":"https://html.spec.whatwg.org/"},"chapter":2,"test":"Static: forms have method/action or submit button; inputs outside forms counted; warn on JS-only forms","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"A real <form> with an action and a submit button works for any agent, even without JavaScript, and is what WebMCP declarative tools build on. Inputs wired up only by script are invisible to most agents (book chapter 2).","fix":{"snippet":"<form action=\"/search\" method=\"get\">\n  <label for=\"q\">Search cabins</label>\n  <input id=\"q\" name=\"q\" type=\"search\">\n  <button type=\"submit\">Search</button>\n</form>","prompt":"Make the key flows (search, booking, contact, sign-up) real <form> elements with an action and method that work without JavaScript, named inputs, and a submit button; progressively enhance with script afterwards."},"implemented":true},{"id":"perception.server-html","layer":"perception","title":"Server HTML carries the content (not an empty JS shell)","severity":3,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":3,"test":"Static: visible text length of server HTML; fail under 200 chars with a large script bundle; browser run compares with rendered text","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":true,"why":"Many agents and crawlers read the HTML your server sends and never run JavaScript. If the content only appears after scripts run, those agents see an empty shell (book chapter 3).","fix":{"snippet":"<!-- server-render the content; hydrate afterwards -->\n<main id=\"app\"><h1>Fjellro cabin</h1><p>Sleeps 6, sauna, from NOK 2,400 a night.</p></main>\n<script type=\"module\" src=\"/app.js\"></script>","prompt":"Render the page content on the server (SSR, static generation or prerendering in the framework in use) so the initial HTML response contains the headings, text, prices and links; keep client-side JavaScript for interactivity only. Verify with curl that the main text is in the raw HTML."},"implemented":true},{"id":"perception.rendered-parity","layer":"perception","title":"Rendered page and server HTML say the same thing","severity":2,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":3,"test":"Browser: share of rendered visible text present in server HTML (token overlap); warn < 70%, fail < 30%","iia":null,"lh":null,"roles":["dev","arch","qa"],"requires":"browser","applies":"always","heuristic":true,"why":"Many agents and crawlers read only the server HTML. If the rendered page says much more than the HTML the server sends, those agents miss it (book chapter 3).","fix":{"snippet":"<!-- Render the content on the server; hydrate on the client -->\n<main>\n  <h1>Fjellro cabin</h1>\n  <p>Sleeps 4, sauna, from NOK 1,850 per night.</p>\n</main>","prompt":"Make the server HTML of this page carry the same main content the browser shows: render headings, text, prices and links on the server (SSR or static generation) and let client JavaScript only enhance it. Verify with curl that the key sentences are in the raw HTML."},"implemented":true},{"id":"perception.axe-agent-rules","layer":"perception","title":"The 33 agent-relevant axe rules pass","severity":3,"standard":{"key":"lh-a11y","name":"Lighthouse agent-accessibility-tree (33 axe rules)","body":"Google Chrome","version":"Lighthouse 13.6.0","date":"2026-10-27","status":"Tool audit (rules from axe-core / WCAG)","maturity":"standard","url":"https://github.com/GoogleChrome/lighthouse"},"chapter":3,"test":"Browser: axe-core runOnly the 33 TARGET_RULES from Lighthouse 13.6.0; fail on any violation (Lighthouse is binary)","iia":null,"lh":"agent-accessibility-tree","roles":["dev","design","qa"],"requires":"browser","applies":"always","heuristic":false,"why":"Agents read the page through the accessibility tree. Lighthouse's agent-accessibility-tree audit runs 33 axe rules (names, labels, valid ARIA) and fails on any violation (book chapter 3).","fix":{"snippet":"<button aria-label=\"Close dialog\">×</button>\n<label for=\"email\">Email</label> <input id=\"email\" name=\"email\" type=\"email\" autocomplete=\"email\">\n<a href=\"/cabins/fjellro\">Fjellro cabin details</a>","prompt":"Fix every violation of these axe-core rules on this page: give buttons and links an accessible name (text or aria-label), label every form field, use only valid ARIA roles and attributes, and keep aria-hidden content out of the tab order. Verify with axe-core runOnly on the 33 Lighthouse agent rules, or Lighthouse Agentic Browsing agent-accessibility-tree."},"implemented":true},{"id":"perception.a11y-tree","layer":"perception","title":"Interactive elements appear in the accessibility tree with names and roles","severity":3,"standard":{"key":"aria","name":"WAI-ARIA","body":"W3C","version":"1.2","date":"2023-06-06","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/wai-aria-1.2/"},"chapter":3,"test":"Browser: accessibility snapshot; share of interactive nodes with a name; list unnamed","iia":null,"lh":null,"roles":["dev","design","qa"],"requires":"browser","applies":"always","heuristic":true,"why":"An agent can only act on a control it can find by role and name. An unnamed button in the accessibility tree is a button an agent has to guess about (book chapter 3).","fix":{"snippet":"<button type=\"button\" aria-label=\"Next photo\"><svg aria-hidden=\"true\">…</svg></button>","prompt":"Give every interactive element on this page an accessible name: visible text, aria-label or aria-labelledby for icon buttons and links, and <label> for form fields. Verify in Chrome DevTools > Accessibility pane or with a Playwright ariaSnapshot that no button, link or textbox is unnamed."},"implemented":true},{"id":"perception.focusable-controls","layer":"perception","title":"Custom controls are keyboard-focusable","severity":1,"standard":{"key":"wcag","name":"WCAG","body":"W3C","version":"2.2","date":"2023-10-05","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/WCAG22/"},"chapter":3,"test":"Browser: elements with click listeners / role=button that are not focusable (tabIndex < 0)","iia":null,"lh":null,"roles":["dev","design"],"requires":"browser","applies":"always","heuristic":false,"why":"Custom controls built from divs with click handlers cannot be reached from the keyboard, and agents that drive the page by focus and key presses cannot use them (book chapter 3).","fix":{"snippet":"<!-- Before: <div class=\"btn\" onclick=\"book()\">Book</div> -->\n<button type=\"button\" class=\"btn\" onclick=\"book()\">Book</button>","prompt":"Replace click-only <div>/<span> controls on this page with native <button> or <a href> elements. Where that is impossible, add role=\"button\", tabindex=\"0\" and a keydown handler for Enter and Space. Verify by tabbing through the page: every control receives focus."},"implemented":true},{"id":"crawl.robots-txt","layer":"crawl","title":"robots.txt is published","severity":3,"standard":{"key":"rfc9309","name":"Robots Exclusion Protocol","body":"IETF","version":"RFC 9309","date":"2022-09","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9309"},"chapter":4,"test":"GET /robots.txt: 200, text/plain, at least one User-agent line (isitagentready rule)","iia":"robotsTxt","lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"robots.txt is the first file every crawler and most agents read. Without it, nothing tells AI crawlers what they may do, and both graders start from it (book chapter 4).","fix":{"snippet":"User-agent: *\nAllow: /\nDisallow: /account/\n\nSitemap: https://example.com/sitemap.xml","prompt":"Create /robots.txt at the site root, served as text/plain with HTTP 200. Start with a User-agent: * group, allow public pages, disallow private paths such as /account/, and add an absolute Sitemap: line."},"implemented":true},{"id":"crawl.robots-syntax","layer":"crawl","title":"robots.txt parses cleanly","severity":2,"standard":{"key":"rfc9309","name":"Robots Exclusion Protocol","body":"IETF","version":"RFC 9309","date":"2022-09","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9309"},"chapter":4,"test":"Parse per RFC 9309: unknown lines, rules before any User-agent, size > 500 KiB (parser limit), HTML served as robots","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"Crawlers parse robots.txt strictly (RFC 9309). A rule before any User-agent line, a typo in a field name or a file over the 500 KiB parsing limit silently changes what each bot is allowed to do (book chapter 4).","fix":{"snippet":"# Every rule belongs to a group that starts with User-agent\nUser-agent: GPTBot\nDisallow: /\n\nUser-agent: *\nAllow: /","prompt":"Clean up /robots.txt so it parses per RFC 9309: every Allow/Disallow line must follow a User-agent line in the same group, use only \"Field: value\" lines, fix misspelled field names, and keep the file under 500 KiB. Re-test with a robots.txt validator."},"implemented":true},{"id":"crawl.ai-bot-rules","layer":"crawl","title":"robots.txt has rules for AI crawlers","severity":2,"standard":{"key":"rfc9309","name":"Robots Exclusion Protocol","body":"IETF","version":"RFC 9309","date":"2022-09","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9309"},"chapter":4,"test":"Named AI tokens or a wildcard group (isitagentready rule); lists which tokens are named","iia":"robotsTxtAiRules","lh":null,"roles":["content","pm"],"requires":"http","applies":"always","heuristic":false,"why":"Naming AI crawlers in robots.txt is how you state a deliberate policy: search and user fetchers decide whether you show up in AI answers, training crawlers decide whether your text trains models (book chapter 4).","fix":{"snippet":"# AI search and user fetchers: welcome\nUser-agent: OAI-SearchBot\nUser-agent: Claude-SearchBot\nUser-agent: PerplexityBot\nUser-agent: ChatGPT-User\nUser-agent: Claude-User\nAllow: /\n\n# Training crawlers: your choice\nUser-agent: GPTBot\nUser-agent: ClaudeBot\nUser-agent: Google-Extended\nUser-agent: CCBot\nDisallow: /","prompt":"Add explicit User-agent groups to /robots.txt for the AI crawlers: search bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot), user fetchers (ChatGPT-User, Claude-User, Perplexity-User) and training bots (GPTBot, ClaudeBot, Google-Extended, CCBot, Applebot-Extended). Allow or disallow each group to match the site's policy, then verify each token with an RFC 9309 robots tester."},"implemented":true},{"id":"crawl.ai-crawler-matrix","layer":"crawl","title":"AI crawler policy per bot (training / search / user)","severity":2,"standard":{"key":"rfc9309","name":"Robots Exclusion Protocol","body":"IETF","version":"RFC 9309","date":"2022-09","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9309"},"chapter":4,"test":"Evaluate the homepage path for 17 documented AI tokens with RFC 9309 group matching; warn when search or user fetchers are blocked while training is allowed, or all AI is blocked by accident","iia":null,"lh":null,"roles":["content","pm","arch"],"requires":"http","applies":"always","heuristic":true,"why":"AI bots come in three kinds: training crawlers, search indexers that put you in AI answers, and user fetchers acting for a person right now. A policy that blocks search and user fetchers while letting training through is usually the opposite of what a site wants (book chapter 4).","fix":{"snippet":"User-agent: OAI-SearchBot\nUser-agent: Claude-SearchBot\nUser-agent: PerplexityBot\nUser-agent: Amzn-SearchBot\nUser-agent: ChatGPT-User\nUser-agent: Claude-User\nUser-agent: Perplexity-User\nAllow: /\n\nUser-agent: GPTBot\nUser-agent: ClaudeBot\nUser-agent: Google-Extended\nUser-agent: Applebot-Extended\nUser-agent: CCBot\nDisallow: /","prompt":"Review /robots.txt per AI crawler purpose. Make sure AI search bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot, Amzn-SearchBot, MistralAI-Index) and user fetchers (ChatGPT-User, Claude-User, Perplexity-User, Amzn-User, MistralAI-User) can fetch public pages, and decide separately for training crawlers (GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot, MistralAI-Training, Meta-ExternalAgent). Put each purpose in its own group."},"implemented":true},{"id":"crawl.content-signal","layer":"crawl","title":"Content-Signal preferences are declared","severity":2,"standard":{"key":"contentsignals","name":"Content Signals Policy","body":"Cloudflare","version":"first version (draft-romm-aipref-contentsignals)","date":"2025-09-24","status":"Vendor proposal","maturity":"proposal","url":"https://contentsignals.org/"},"chapter":4,"test":"robots.txt Content-Signal line with ai-train, search or ai-input (isitagentready rule)","iia":"contentSignals","lh":null,"roles":["content","pm"],"requires":"http","applies":"always","heuristic":false,"why":"Content Signals state in robots.txt what crawled content may be used for: search, AI input (answers) or AI training. isitagentready requires the line for Level 2; it is a vendor proposal, not a standard (book chapter 4).","fix":{"snippet":"User-agent: *\nContent-Signal: search=yes, ai-input=yes, ai-train=no\nAllow: /","prompt":"Add a Content-Signal line inside the User-agent: * group of /robots.txt, for example \"Content-Signal: search=yes, ai-input=yes, ai-train=no\", choosing yes/no for each of search, ai-input and ai-train to match the site's policy."},"implemented":true},{"id":"crawl.content-signal-valid","layer":"crawl","title":"Content-Signal values are well-formed","severity":1,"standard":{"key":"contentsignals","name":"Content Signals Policy","body":"Cloudflare","version":"first version (draft-romm-aipref-contentsignals)","date":"2025-09-24","status":"Vendor proposal","maturity":"proposal","url":"https://contentsignals.org/"},"chapter":4,"test":"Keys in {search, ai-input, ai-train}, values yes/no, inside a User-agent group","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"A Content-Signal line only counts if crawlers can read it: the keys are search, ai-input and ai-train, the values yes or no, and the line sits inside a User-agent group (book chapter 4).","fix":{"snippet":"User-agent: *\nContent-Signal: search=yes, ai-input=yes, ai-train=no","prompt":"Fix the Content-Signal lines in /robots.txt: place each one inside a User-agent group, use only the keys search, ai-input and ai-train, and only the values yes or no, separated by commas."},"implemented":true},{"id":"crawl.aipref-usage","layer":"crawl","title":"AI preferences (Content-Usage, IETF aipref) if present are valid","severity":1,"standard":{"key":"aipref","name":"AI Preferences vocabulary + attachment","body":"IETF aipref WG","version":"draft-ietf-aipref-vocab-08 / attach-05","date":"2026-09-14","status":"IETF WG draft","maturity":"draft","url":"https://datatracker.ietf.org/wg/aipref/about/"},"chapter":4,"test":"robots.txt Content-Usage lines and Content-Usage response header parsed against the vocab draft; informational when absent","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"The IETF AI Preferences drafts define Content-Usage (train-ai, ai-use, search, each y or n) as a robots.txt rule and an HTTP header. They are working-group drafts still in flux, so absence is fine; a malformed line just gets ignored (book chapter 4).","fix":{"snippet":"User-agent: *\nAllow: /\nContent-Usage: train-ai=n, search=y\nContent-Usage: /blog/ train-ai=y","prompt":"If the site wants to state IETF aipref preferences, add Content-Usage rules inside a robots.txt User-agent group (optionally path-scoped, \"Content-Usage: /path/ train-ai=n\") and/or a Content-Usage response header, using only the vocabulary keys train-ai, ai-use and search with values y or n (draft-ietf-aipref-vocab-08, draft-ietf-aipref-attach-05)."},"implemented":true},{"id":"crawl.robots-meta","layer":"crawl","title":"Homepage is not noindex/none for everyone","severity":3,"standard":{"key":"xrobots","name":"X-Robots-Tag / meta robots","body":"Google Search (de-facto)","version":"documentation","date":"continuous","status":"De-facto convention","maturity":"standard","url":"https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag"},"chapter":4,"test":"Homepage X-Robots-Tag header and <meta name=robots>: fail on noindex/none for all agents","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"A noindex in the X-Robots-Tag header or the robots meta tag tells every crawler, AI search included, to keep the page out. It is often left over from staging (book chapter 4).","fix":{"snippet":"<!-- remove noindex from public pages -->\n<meta name=\"robots\" content=\"index, follow\">","prompt":"Remove \"noindex\" and \"none\" from the X-Robots-Tag response header and the <meta name=\"robots\"> tag on public pages. Keep noindex only on private or transactional pages, then re-check the headers with curl -I."},"implemented":true},{"id":"crawl.bot-challenge","layer":"crawl","title":"Agents get the page, not a challenge","severity":3,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":15,"test":"GET homepage with this checker's identifying UA vs a browser UA: warn/fail when the bot gets 403/429/challenge HTML and the browser gets 200","iia":null,"lh":null,"roles":["arch","security"],"requires":"http","applies":"always","heuristic":true,"why":"Bot protection that challenges every non-browser client also stops the AI agents and assistants you want. Verified-bot and Web Bot Auth allow-lists let good agents through while still blocking scrapers (book chapter 15).","fix":{"snippet":"# Allow verified bots / signed agents in your WAF or bot manager, e.g.\n# - allow requests with a valid Web Bot Auth Signature-Agent\n# - allow verified AI crawlers (OAI-SearchBot, Claude-SearchBot, ...) on public pages\n# - keep challenges on login, checkout and APIs that need them","prompt":"Find the bot-protection rule (WAF, CDN bot management or anti-bot script) that challenges or blocks this site's public pages for non-browser user agents. Exempt public, read-only pages for identified agents and verified bots (Web Bot Auth signatures or the vendors' verified-bot lists), keep challenges on sensitive paths, then verify with curl -A \"AgentReadyCheck\" that the homepage returns 200 HTML."},"implemented":true},{"id":"crawl.sitemap","layer":"crawl","title":"A sitemap is published","severity":2,"standard":{"key":"sitemaps","name":"Sitemaps protocol","body":"sitemaps.org","version":"0.9","date":"long-standing","status":"Convention backed by the major search engines","maturity":"standard","url":"https://www.sitemaps.org/protocol.html"},"chapter":6,"test":"/sitemap.xml returns XML, or a Sitemap line in robots.txt (isitagentready rule)","iia":"sitemap","lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"A sitemap lists the pages you want found, with dates. Crawlers and agents use it to discover content without guessing links, and isitagentready counts it for Level 1 (book chapter 6).","fix":{"snippet":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n  <url><loc>https://example.com/</loc><lastmod>2026-11-02</lastmod></url>\n</urlset>","prompt":"Generate /sitemap.xml (sitemaps.org protocol) listing every public canonical URL with an honest <lastmod>, serve it as application/xml, regenerate it on publish, and add \"Sitemap: https://<host>/sitemap.xml\" to /robots.txt."},"implemented":true},{"id":"crawl.sitemap-valid","layer":"crawl","title":"Sitemap is valid XML with <loc> URLs on this site","severity":2,"standard":{"key":"sitemaps","name":"Sitemaps protocol","body":"sitemaps.org","version":"0.9","date":"long-standing","status":"Convention backed by the major search engines","maturity":"standard","url":"https://www.sitemaps.org/protocol.html"},"chapter":6,"test":"Parse urlset/sitemapindex; count URLs; all on the same site; under 50,000 URLs / 50 MB","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"A sitemap that is not valid XML, lists another site or exceeds the protocol limits is ignored by crawlers (book chapter 6).","fix":{"snippet":"<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n  <url><loc>https://example.com/cabins/</loc></url>\n</urlset>","prompt":"Make the sitemap valid per sitemaps.org: a <urlset> (or <sitemapindex>) root with the sitemap namespace, one absolute <loc> per entry on this site's host, at most 50,000 URLs and 50 MB per file (split into a sitemap index if larger), XML-escaped URLs."},"implemented":true},{"id":"crawl.sitemap-lastmod","layer":"crawl","title":"Sitemap carries honest lastmod dates","severity":1,"standard":{"key":"sitemaps","name":"Sitemaps protocol","body":"sitemaps.org","version":"0.9","date":"long-standing","status":"Convention backed by the major search engines","maturity":"standard","url":"https://www.sitemaps.org/protocol.html"},"chapter":6,"test":"Share of URLs with W3C-datetime lastmod; warn if all identical or in the future","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"Honest <lastmod> dates let crawlers and agents refetch only what changed. Dates that are all identical or in the future get ignored (book chapter 6).","fix":{"snippet":"<url><loc>https://example.com/cabins/fjellro</loc><lastmod>2026-10-28</lastmod></url>","prompt":"Emit <lastmod> for every sitemap URL from the content's real last-modified time (not the build time), in W3C Datetime format (YYYY-MM-DD or full timestamp with zone), and never in the future."},"implemented":true},{"id":"crawl.sitemap-in-robots","layer":"crawl","title":"robots.txt names the sitemap","severity":1,"standard":{"key":"rfc9309","name":"Robots Exclusion Protocol","body":"IETF","version":"RFC 9309","date":"2022-09","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9309"},"chapter":6,"test":"Sitemap: line(s) present and absolute","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"A Sitemap: line in robots.txt is how crawlers find the sitemap without guessing its path. It must be an absolute URL (book chapter 6).","fix":{"snippet":"Sitemap: https://example.com/sitemap.xml","prompt":"Add an absolute \"Sitemap: https://<host>/sitemap.xml\" line to /robots.txt (outside or after the groups; it applies to all crawlers)."},"implemented":true},{"id":"crawl.tdmrep","layer":"crawl","title":"TDM reservation (TDMRep) if used is valid","severity":1,"standard":{"key":"tdmrep","name":"TDM Reservation Protocol","body":"W3C CG","version":"Final CG Report","date":"2024-05-10","status":"W3C CG report","maturity":"draft","url":"https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/"},"chapter":4,"test":"/.well-known/tdmrep.json and tdm-reservation header/meta; informational","iia":null,"lh":null,"roles":["content","pm"],"requires":"http","applies":"always","heuristic":false,"why":"TDMRep (a W3C Community Group report) is one machine-readable way to make the EU text-and-data-mining opt-out. It is optional; if published it must be well-formed or it says nothing (book chapter 4).","fix":{"snippet":"[\n  { \"location\": \"/\", \"tdm-reservation\": 1, \"tdm-policy\": \"https://example.com/tdm-policy.json\" }\n]","prompt":"Only if the site wants a TDM reservation: publish /.well-known/tdmrep.json as application/json, an array of objects with \"location\" (a path pattern), \"tdm-reservation\" (0 or 1) and optionally \"tdm-policy\" (an absolute URL). Check with legal first; it covers all text and data mining, not only AI training."},"implemented":true},{"id":"crawl.rsl","layer":"crawl","title":"RSL licence pointer if used resolves","severity":1,"standard":{"key":"rsl","name":"RSL (Really Simple Licensing)","body":"RSL Collective","version":"1.0","date":"2025-12-10","status":"Published specification","maturity":"draft","url":"https://rslstandard.org/"},"chapter":4,"test":"robots.txt License: line / <link rel=license type=application/rsl+xml>; fetch and check XML; informational","iia":null,"lh":null,"roles":["content","pm"],"requires":"http","applies":"always","heuristic":false,"why":"RSL (Really Simple Licensing 1.0) lets a site point crawlers to machine-readable licence terms from robots.txt or a <link>. Optional; if used, the pointer must resolve to an RSL document (book chapter 4).","fix":{"snippet":"# robots.txt\nLicense: https://example.com/license.xml\n\n<!-- or in HTML -->\n<link rel=\"license\" type=\"application/rsl+xml\" href=\"/license.xml\">","prompt":"Only if the site licenses content to AI systems: publish an RSL 1.0 document (root <rsl xmlns=\"https://rslstandard.org/rsl\">) at a stable URL, served as application/rsl+xml or XML, and point to it with a \"License:\" line in robots.txt and/or <link rel=\"license\" type=\"application/rsl+xml\">."},"implemented":true},{"id":"structured.jsonld-present","layer":"structured","title":"Page has JSON-LD structured data","severity":2,"standard":{"key":"jsonld","name":"JSON-LD","body":"W3C","version":"1.1","date":"2020-07","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/json-ld11/"},"chapter":5,"test":"Static: script[type=\"application/ld+json\"] blocks on the homepage (and the sampled page)","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"JSON-LD gives agents the facts of the page (what it is, prices, dates, who runs it) as data instead of prose to guess from (book chapter 5).","fix":{"snippet":"<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"LodgingBusiness\",\n  \"name\": \"Fjellro cabin\",\n  \"url\": \"https://example.com/cabins/fjellro\"\n}\n</script>","prompt":"Add a <script type=\"application/ld+json\"> block to the page's server HTML describing its main entity with schema.org (for example Organization and WebSite on the homepage, Product/Offer on product pages), generated from the same data that renders the visible page."},"implemented":true},{"id":"structured.jsonld-syntax","layer":"structured","title":"JSON-LD blocks parse as JSON","severity":3,"standard":{"key":"jsonld","name":"JSON-LD","body":"W3C","version":"1.1","date":"2020-07","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/json-ld11/"},"chapter":5,"test":"JSON.parse each block; report position of errors","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"One stray comma makes the whole JSON-LD block unreadable; agents and search engines then drop all of it silently (book chapter 5).","fix":{"snippet":"// generate JSON-LD with JSON.stringify, never by string concatenation\nconst ld = JSON.stringify(data).replace(/</g, \"\\\\u003c\");\nhtml += `<script type=\"application/ld+json\">${ld}</script>`;","prompt":"Generate every JSON-LD block with a JSON serializer (JSON.stringify or the framework's equivalent) instead of templates or string concatenation, escape \"<\" as \\u003c, and add a unit test that JSON.parse succeeds on each block."},"implemented":true},{"id":"structured.jsonld-context","layer":"structured","title":"JSON-LD uses the schema.org context","severity":1,"standard":{"key":"jsonld","name":"JSON-LD","body":"W3C","version":"1.1","date":"2020-07","status":"W3C Recommendation","maturity":"standard","url":"https://www.w3.org/TR/json-ld11/"},"chapter":5,"test":"@context is https://schema.org (or http) in each top-level node or @graph","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Without \"@context\": \"https://schema.org\" the types and properties mean nothing to a JSON-LD processor; \"Product\" is just a string (book chapter 5).","fix":{"snippet":"{ \"@context\": \"https://schema.org\", \"@type\": \"Organization\", \"name\": \"Nordlys Cabins\" }","prompt":"Set \"@context\": \"https://schema.org\" on the top-level object of every JSON-LD block (or once on the object that holds \"@graph\")."},"implemented":true},{"id":"structured.schema-types","layer":"structured","title":"@type values exist in schema.org","severity":2,"standard":{"key":"schemaorg","name":"schema.org","body":"schema.org community","version":"current release","date":"continuous","status":"Community vocabulary","maturity":"standard","url":"https://schema.org/"},"chapter":5,"test":"Every @type checked against the bundled schema.org type list (release noted in the report)","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"A misspelled or invented @type (\"Cabin\", \"Hotell\") is ignored by every consumer; the data is there but says nothing (book chapter 5).","fix":{"snippet":"\"@type\": \"LodgingBusiness\"   // not \"Cabin\"; see https://schema.org/LodgingBusiness","prompt":"Replace every JSON-LD @type that is not a schema.org class with the closest real one (look it up on schema.org; for example LodgingBusiness, Product, Event), keeping the exact capitalisation."},"implemented":true},{"id":"structured.schema-properties","layer":"structured","title":"Properties exist in schema.org","severity":1,"standard":{"key":"schemaorg","name":"schema.org","body":"schema.org community","version":"current release","date":"continuous","status":"Community vocabulary","maturity":"standard","url":"https://schema.org/"},"chapter":5,"test":"Every property name checked against the bundled schema.org property list","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"Properties that schema.org does not define (\"pricePerNight\", \"image_url\") are dropped by consumers, so the fact they carry never reaches an agent (book chapter 5).","fix":{"snippet":"\"offers\": { \"@type\": \"Offer\", \"price\": \"2400\", \"priceCurrency\": \"NOK\" }   // not \"pricePerNight\"","prompt":"Rename every JSON-LD property that schema.org does not define to the matching schema.org property (check the type's page on schema.org), or move site-specific data out of the schema.org block."},"implemented":true},{"id":"structured.key-properties","layer":"structured","title":"Key properties are filled for the main types","severity":2,"standard":{"key":"schemaorg","name":"schema.org","body":"schema.org community","version":"current release","date":"continuous","status":"Community vocabulary","maturity":"standard","url":"https://schema.org/"},"chapter":5,"test":"Organization/WebSite/Product/Offer/LodgingBusiness/Event/Article/FAQPage: required-for-meaning fields (name, url, offers.price+priceCurrency, startDate...)","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"An Offer without a price, an Event without a date or a business without an address is structured data that cannot answer the question an agent came with (book chapter 5).","fix":{"snippet":"{\n  \"@type\": \"Offer\",\n  \"price\": \"2400\",\n  \"priceCurrency\": \"NOK\",\n  \"availability\": \"https://schema.org/InStock\"\n}","prompt":"Fill the meaning-carrying fields of each main JSON-LD node: name and url for Organization/WebSite; name and offers for Product; price and priceCurrency for Offer; name, address and url for LodgingBusiness; name, startDate and location for Event; headline, datePublished and author for Article. Use the same values the page shows."},"implemented":true},{"id":"structured.visible-parity","layer":"structured","title":"Structured data matches visible content","severity":3,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":5,"test":"name, headline, price and description values found in visible server text (normalised); warn below 80%, fail below 50%","iia":null,"lh":null,"roles":["content","qa"],"requires":"http","applies":"always","heuristic":true,"why":"Structured data that disagrees with the page (an old price, a different name) misleads agents and is against search engines' guidelines. The JSON-LD should say what the page says (book chapter 5).","fix":{"snippet":"// render the JSON-LD and the visible HTML from the same object\nconst cabin = await db.cabin(slug);\nhtml(`<h1>${cabin.name}</h1><p>${cabin.price} NOK</p>`);\njsonld({ \"@type\": \"Product\", name: cabin.name, offers: { price: cabin.price, priceCurrency: \"NOK\" } });","prompt":"Generate the JSON-LD and the visible HTML from the same data object so names, headlines, descriptions and prices cannot drift. Remove JSON-LD values that the page does not show."},"implemented":true},{"id":"structured.identity","layer":"structured","title":"Homepage identifies the organisation (Organization/WebSite)","severity":1,"standard":{"key":"schemaorg","name":"schema.org","body":"schema.org community","version":"current release","date":"continuous","status":"Community vocabulary","maturity":"standard","url":"https://schema.org/"},"chapter":5,"test":"Organization or WebSite node with name and url; sameAs and logo noted","iia":null,"lh":null,"roles":["content","pm"],"requires":"http","applies":"always","heuristic":false,"why":"An Organization (or WebSite) node with name, url, logo and sameAs links tells agents who runs the site and ties it to its other profiles, so they can trust and cite it (book chapter 5).","fix":{"snippet":"{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Organization\",\n  \"name\": \"Nordlys Cabins\",\n  \"url\": \"https://example.com/\",\n  \"logo\": \"https://example.com/logo.png\",\n  \"sameAs\": [\"https://www.linkedin.com/company/example\"]\n}","prompt":"Add an Organization (or the more specific LocalBusiness subtype) and a WebSite JSON-LD node to the homepage with name, url, logo and sameAs links to the official profiles."},"implemented":true},{"id":"structured.canonical","layer":"structured","title":"Canonical URL is declared and consistent","severity":1,"standard":{"key":"html","name":"HTML Living Standard","body":"WHATWG","version":"Living Standard","date":"continuous","status":"Living Standard","maturity":"standard","url":"https://html.spec.whatwg.org/"},"chapter":5,"test":"link rel=canonical present, absolute, same site; matches final URL or redirects there","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"The canonical URL tells agents which address is the real one, so they cite and deduplicate one URL instead of five tracking variants (book chapter 5).","fix":{"snippet":"<link rel=\"canonical\" href=\"https://example.com/cabins/fjellro\">","prompt":"Add <link rel=\"canonical\" href=\"...\"> with the absolute, preferred URL of each page (same host and scheme the site redirects to) to the page head template."},"implemented":true},{"id":"structured.meta-description","layer":"structured","title":"Meta description and Open Graph basics","severity":1,"standard":{"key":"ogp","name":"Open Graph protocol","body":"Meta (ogp.me)","version":"—","date":"long-standing","status":"De-facto convention","maturity":"convention","url":"https://ogp.me/"},"chapter":5,"test":"meta description, og:title, og:description present","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"The meta description and Open Graph title/description are the summary agents and link previews show. Without them they write their own, usually from the cookie banner (book chapter 5).","fix":{"snippet":"<meta name=\"description\" content=\"Two-bedroom cabin with sauna, sleeps 6, two hours from Oslo.\">\n<meta property=\"og:title\" content=\"Fjellro cabin | Nordlys Cabins\">\n<meta property=\"og:description\" content=\"Two-bedroom cabin with sauna, sleeps 6.\">","prompt":"Add a page-specific <meta name=\"description\">, <meta property=\"og:title\"> and <meta property=\"og:description\"> to every page head, generated from the page's own content."},"implemented":true},{"id":"content.markdown-negotiation","layer":"content","title":"Markdown via Accept: text/markdown","severity":3,"standard":{"key":"mdagents","name":"Markdown for Agents (Accept: text/markdown)","body":"Cloudflare","version":"documentation","date":"2026","status":"Vendor convention on RFC 9110 negotiation","maturity":"proposal","url":"https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/"},"chapter":6,"test":"GET homepage with Accept: text/markdown; pass on Content-Type text/markdown (isitagentready rule)","iia":"markdownNegotiation","lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"Markdown is the cheapest way for an agent to read a page: no navigation, scripts or markup, often 80% fewer tokens. Content negotiation serves it from the same URL, and isitagentready needs it for Level 3 (book chapter 6).","fix":{"snippet":"// Express-style middleware\napp.get(\"*\", (req, res, next) => {\n  res.vary(\"Accept\");\n  if (req.accepts([\"text/html\", \"text/markdown\"]) === \"text/markdown\") {\n    return res.type(\"text/markdown; charset=utf-8\").send(toMarkdown(req.path));\n  }\n  next();\n});","prompt":"Add content negotiation for Markdown: when a request's Accept header prefers text/markdown, return a Markdown version of the same page with Content-Type: text/markdown; charset=utf-8 and Vary: Accept; browsers keep getting HTML. Verify with curl -H \"Accept: text/markdown\"."},"implemented":true},{"id":"content.markdown-vary","layer":"content","title":"Negotiated responses send Vary: Accept","severity":2,"standard":{"key":"rfc9110","name":"HTTP Semantics (content negotiation, Vary)","body":"IETF","version":"RFC 9110","date":"2022-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9110"},"chapter":6,"test":"Both the HTML and Markdown responses carry Vary including Accept, so caches do not mix them","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"When one URL serves HTML and Markdown, caches must know the answer depends on Accept. Without Vary: Accept a CDN can hand Markdown to a browser or HTML to an agent (book chapter 6).","fix":{"snippet":"Vary: Accept","prompt":"Add \"Vary: Accept\" to both the HTML and the Markdown responses of every negotiated URL (merge with any existing Vary values such as Accept-Encoding), then check both with curl -I."},"implemented":true},{"id":"content.markdown-quality","layer":"content","title":"The Markdown is real Markdown with the page content","severity":2,"standard":{"key":"rfc7763","name":"text/markdown media type","body":"IETF","version":"RFC 7763","date":"2016-03","status":"RFC (Informational)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc7763"},"chapter":6,"test":"Markdown body is not HTML, has a heading, shares >= 50% of key terms with the HTML text","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":true,"why":"Negotiated \"Markdown\" that is really HTML, or a stub without the page content, gives agents less than the HTML did (book chapter 6).","fix":{"snippet":"# Fjellro cabin\n\nTwo-bedroom cabin with a wood-fired sauna. Sleeps 6.\n\n## Prices\n\n- High season: NOK 2,400 per night","prompt":"Make the Markdown representation a faithful conversion of the page's main content (not its navigation): start with an H1, keep headings, lists, links, prices and dates, and do not wrap HTML in it. Compare it with the HTML page in a test."},"implemented":true},{"id":"content.markdown-alternate","layer":"content","title":"Pages link their Markdown twin","severity":1,"standard":{"key":"llmstxt","name":"llms.txt","body":"Individual (Jeremy Howard)","version":"v2","date":"2026-08-10","status":"Proposal","maturity":"proposal","url":"https://llmstxt.org/"},"chapter":6,"test":"<link rel=alternate type=text/markdown> or Link header; fetch it, expect text/markdown or text/plain","iia":null,"lh":null,"roles":["dev","content"],"requires":"http","applies":"always","heuristic":false,"why":"A <link rel=\"alternate\" type=\"text/markdown\"> (or Link header) points agents to the page's Markdown twin, for those that do not send Accept: text/markdown (book chapter 6).","fix":{"snippet":"<link rel=\"alternate\" type=\"text/markdown\" href=\"/cabins/fjellro.md\">\n# or as a header\nLink: </cabins/fjellro.md>; rel=\"alternate\"; type=\"text/markdown\"","prompt":"Publish a Markdown twin for each page (for example <path>.md) and advertise it with <link rel=\"alternate\" type=\"text/markdown\" href=\"...\"> in the head and/or a Link response header; serve it as text/markdown."},"implemented":true},{"id":"content.llms-txt","layer":"content","title":"llms.txt is published","severity":2,"standard":{"key":"llmstxt","name":"llms.txt","body":"Individual (Jeremy Howard)","version":"v2","date":"2026-08-10","status":"Proposal","maturity":"proposal","url":"https://llmstxt.org/"},"chapter":6,"test":"GET /llms.txt: 200 text, not HTML","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"always","heuristic":false,"why":"llms.txt is a short Markdown map of the site for language models: what it is and where the important pages are. It is a proposal, not a standard, and cheap to publish (book chapter 6).","fix":{"snippet":"# Nordlys Cabins\n\n> Six holiday cabins in Norway you can book directly. Prices in NOK.\n\n## Cabins\n\n- [Fjellro](https://example.com/cabins/fjellro.md): Hemsedal, sleeps 6\n\n## Optional\n\n- [Sitemap](https://example.com/sitemap.xml)","prompt":"Publish /llms.txt as text/markdown (or text/plain): one H1 with the site name, a one-line blockquote summary, then H2 sections listing the key pages as \"- [name](absolute URL): one-line note\". Generate it from the same data as the sitemap."},"implemented":true},{"id":"content.llms-txt-format","layer":"content","title":"llms.txt follows the format (H1, summary, link lists)","severity":2,"standard":{"key":"llmstxt","name":"llms.txt","body":"Individual (Jeremy Howard)","version":"v2","date":"2026-08-10","status":"Proposal","maturity":"proposal","url":"https://llmstxt.org/"},"chapter":6,"test":"Lighthouse llms-txt rules: H1, Markdown link, >= 50 chars; plus blockquote summary and H2 sections","iia":null,"lh":"llms-txt","roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"Lighthouse's llms-txt audit fails a file without an H1, without a Markdown link or under 50 characters; the llms.txt proposal also expects a blockquote summary and H2 sections of links (book chapter 6).","fix":{"snippet":"# Site name\n\n> One-sentence summary of the site.\n\n## Docs\n\n- [Getting started](https://example.com/start.md): first steps","prompt":"Restructure /llms.txt: exactly one \"# \" H1 first, a \"> \" summary line, then \"## \" sections each listing links as \"- [name](URL): note\". Keep it over 50 characters and make every link absolute."},"implemented":true},{"id":"content.llms-txt-links","layer":"content","title":"llms.txt links resolve","severity":2,"standard":{"key":"llmstxt","name":"llms.txt","body":"Individual (Jeremy Howard)","version":"v2","date":"2026-08-10","status":"Proposal","maturity":"proposal","url":"https://llmstxt.org/"},"chapter":6,"test":"HEAD/GET up to 15 linked URLs (robots-respecting); warn on any 4xx/5xx, fail if most fail","iia":null,"lh":null,"roles":["content","qa"],"requires":"http","applies":"always","heuristic":false,"why":"llms.txt is only useful if its links work. A model that follows a dead link from it learns nothing, or learns your 404 page (book chapter 6).","fix":{"snippet":"// in CI: fail the build when an llms.txt link breaks\nfor (const url of links) { const r = await fetch(url, { method: \"HEAD\" }); if (!r.ok) throw new Error(url); }","prompt":"Generate /llms.txt from the live route list so it only links pages that exist, use absolute URLs, and add a CI step that requests every link in llms.txt and fails on any 4xx/5xx."},"implemented":true},{"id":"content.llms-full","layer":"content","title":"llms-full.txt (optional)","severity":1,"standard":{"key":"llmsfull","name":"llms-full.txt","body":"Community","version":"—","date":"—","status":"Convention (not in llms.txt v2)","maturity":"convention","url":"https://llmstxt.org/"},"chapter":6,"test":"GET /llms-full.txt; informational, size reported","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"llms-full.txt bundles the full text of the important pages into one file, so an agent can load your docs in one request. It is an optional convention (book chapter 6).","fix":{"snippet":"# Nordlys Cabins (full)\n\n## Fjellro cabin\n\nTwo-bedroom cabin with a wood-fired sauna...","prompt":"Optionally publish /llms-full.txt: the Markdown of every page listed in llms.txt concatenated under its H2, served as text/markdown or text/plain; keep it under a few MB."},"implemented":true},{"id":"content.link-headers","layer":"content","title":"Link headers point agents to resources","severity":2,"standard":{"key":"rfc8288","name":"Web Linking","body":"IETF","version":"RFC 8288","date":"2017-10","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc8288"},"chapter":6,"test":"Homepage Link header with agent-useful rels (service-desc, describedby, api-catalog, alternate markdown, sitemap, ...) (isitagentready rule)","iia":"linkHeaders","lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"Link response headers let an agent find your API catalog, docs, sitemap or Markdown twin from a single HEAD request, before parsing any HTML. isitagentready counts them for Level 1 (book chapter 6).","fix":{"snippet":"Link: </.well-known/api-catalog>; rel=\"api-catalog\", </sitemap.xml>; rel=\"sitemap\", </index.md>; rel=\"alternate\"; type=\"text/markdown\", </llms.txt>; rel=\"describedby\"","prompt":"Add a Link response header to the homepage (and ideally every page) pointing agents to the useful resources the site has: rel=\"api-catalog\" for /.well-known/api-catalog, rel=\"service-desc\" for the OpenAPI file, rel=\"sitemap\", rel=\"alternate\" type=\"text/markdown\" for the Markdown twin, rel=\"describedby\" for llms.txt."},"implemented":true},{"id":"content.feeds","layer":"content","title":"Feeds are discoverable (RSS/Atom/JSON Feed)","severity":1,"standard":{"key":"feeds","name":"RSS 2.0 / Atom (RFC 4287) / JSON Feed","body":"RSS board / IETF","version":"RFC 4287","date":"2005-12","status":"RFC + conventions","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc4287"},"chapter":6,"test":"link rel=alternate with feed types; fetch first and validate root element","iia":null,"lh":null,"roles":["content"],"requires":"http","applies":"always","heuristic":false,"why":"RSS, Atom or JSON Feed tell agents what is new without crawling the whole site. Worth having when the site publishes articles or updates (book chapter 6).","fix":{"snippet":"<link rel=\"alternate\" type=\"application/atom+xml\" title=\"Guides\" href=\"/guide/feed.xml\">","prompt":"If the site publishes articles or updates, publish an Atom or RSS feed (or JSON Feed) of the latest items with absolute links and dates, and advertise it with <link rel=\"alternate\" type=\"application/atom+xml\" href=\"...\"> in the page head."},"implemented":true},{"id":"content.caching","layer":"content","title":"Responses support conditional requests","severity":1,"standard":{"key":"rfc9110","name":"HTTP Semantics (content negotiation, Vary)","body":"IETF","version":"RFC 9110","date":"2022-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9110"},"chapter":6,"test":"Homepage has ETag or Last-Modified; a conditional request returns 304","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"ETag or Last-Modified plus 304 answers let agents and crawlers re-check a page for the cost of a header, so they can come back often without loading your server (book chapter 6).","fix":{"snippet":"ETag: \"v42-fjellro\"\nLast-Modified: Mon, 02 Nov 2026 10:00:00 GMT\nCache-Control: public, max-age=300\n# and answer If-None-Match / If-Modified-Since with 304 Not Modified","prompt":"Make page responses cacheable for revalidation: send a strong ETag (content hash) or Last-Modified header, honour If-None-Match / If-Modified-Since with 304 Not Modified, and set a sensible Cache-Control. Verify with curl -I -H 'If-None-Match: \"<etag>\"'."},"implemented":true},{"id":"api.catalog","layer":"api","title":"API catalog at /.well-known/api-catalog","severity":2,"standard":{"key":"rfc9727","name":"api-catalog","body":"IETF","version":"RFC 9727","date":"2025-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9727"},"chapter":7,"test":"GET /.well-known/api-catalog: linkset+json with linkset array (isitagentready rule)","iia":"apiCatalog","lh":null,"roles":["arch","dev"],"requires":"http","applies":"api","heuristic":false,"why":"An API catalog at /.well-known/api-catalog is the one fixed place an agent can look to find every API a site offers, with links to their descriptions. isitagentready counts it toward Level 4 (book chapter 7).","fix":{"snippet":"{\n  \"linkset\": [\n    {\n      \"anchor\": \"https://example.com/api/v1\",\n      \"service-desc\": [{ \"href\": \"https://example.com/openapi.json\", \"type\": \"application/openapi+json\" }],\n      \"service-doc\": [{ \"href\": \"https://example.com/docs/api\", \"type\": \"text/html\" }],\n      \"status\": [{ \"href\": \"https://example.com/api/v1/health\", \"type\": \"application/json\" }]\n    }\n  ]\n}","prompt":"Serve /.well-known/api-catalog (RFC 9727) as application/linkset+json with a \"linkset\" array. Add one entry per API with an \"anchor\" (the API base URL) and service-desc (OpenAPI URL), service-doc and status links. Verify with: curl -i https://<site>/.well-known/api-catalog"},"implemented":true},{"id":"api.catalog-valid","layer":"api","title":"API catalog entries are complete","severity":2,"standard":{"key":"rfc9727","name":"api-catalog","body":"IETF","version":"RFC 9727","date":"2025-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9727"},"chapter":7,"test":"Content-Type application/linkset+json; each entry has anchor and service-desc/service-doc; links resolve","iia":null,"lh":null,"roles":["arch","dev"],"requires":"http","applies":"api","heuristic":false,"why":"A catalog only helps when every entry says which API it is (anchor) and where its description lives (service-desc or service-doc), and those links work (book chapter 7).","fix":{"snippet":"Content-Type: application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"\n\n{ \"linkset\": [ { \"anchor\": \"https://example.com/api/v1\", \"service-desc\": [{ \"href\": \"https://example.com/openapi.json\" }] } ] }","prompt":"Make every entry in /.well-known/api-catalog have an \"anchor\" and at least one service-desc or service-doc link whose href answers HTTP 200. Serve it with Content-Type application/linkset+json and the RFC 9727 profile parameter."},"implemented":true},{"id":"api.openapi","layer":"api","title":"OpenAPI description is discoverable","severity":2,"standard":{"key":"openapi","name":"OpenAPI Specification","body":"OpenAPI Initiative","version":"3.2.1","date":"2026-09-10","status":"Dated spec","maturity":"standard","url":"https://spec.openapis.org/oas/latest.html"},"chapter":7,"test":"Find via api-catalog service-desc, Link header, or /openapi.json, /openapi.yaml, /.well-known/openapi.json","iia":null,"lh":null,"roles":["arch","dev"],"requires":"http","applies":"api","heuristic":false,"why":"An OpenAPI description tells an agent every operation, parameter and response of your API, so it can call it without guessing or scraping (book chapter 7).","fix":{"snippet":"Link: </openapi.json>; rel=\"service-desc\"; type=\"application/openapi+json\"","prompt":"Publish the API's OpenAPI 3.1 document at /openapi.json, link it from /.well-known/api-catalog as service-desc, and add a Link header rel=\"service-desc\" on the homepage."},"implemented":true},{"id":"api.openapi-valid","layer":"api","title":"OpenAPI document is valid","severity":2,"standard":{"key":"openapi","name":"OpenAPI Specification","body":"OpenAPI Initiative","version":"3.2.1","date":"2026-09-10","status":"Dated spec","maturity":"standard","url":"https://spec.openapis.org/oas/latest.html"},"chapter":7,"test":"Parse JSON/YAML; openapi 3.x, info.title/version, paths; refs resolve locally","iia":null,"lh":null,"roles":["dev","qa"],"requires":"http","applies":"api","heuristic":false,"why":"Agents and SDK generators stop at the first structural error. A valid OpenAPI 3.x document with resolving $refs is the difference between a callable API and a broken one (book chapter 7).","fix":{"snippet":"{\n  \"openapi\": \"3.1.1\",\n  \"info\": { \"title\": \"Example API\", \"version\": \"1.0.0\" },\n  \"servers\": [{ \"url\": \"https://example.com/api/v1\" }],\n  \"paths\": { \"/items\": { \"get\": { \"operationId\": \"listItems\", \"responses\": { \"200\": { \"description\": \"OK\" } } } } }\n}","prompt":"Fix the OpenAPI document so it declares \"openapi\": \"3.1.x\", has info.title and info.version, a paths object with operations, and every local $ref resolves. Validate it with an OpenAPI linter (for example Redocly CLI: npx @redocly/cli lint openapi.json)."},"implemented":true},{"id":"api.openapi-agent-quality","layer":"api","title":"Operations are described for agents","severity":2,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":10,"test":"Share of operations with operationId, summary/description, described parameters and response schemas","iia":null,"lh":null,"roles":["dev","pm"],"requires":"http","applies":"api","heuristic":true,"why":"An agent picks an operation by its id and description and fills parameters from their descriptions. Unnamed, undescribed operations are guesswork (book chapter 10).","fix":{"snippet":"\"get\": {\n  \"operationId\": \"searchItems\",\n  \"summary\": \"Search items by keyword and date\",\n  \"parameters\": [{ \"name\": \"q\", \"in\": \"query\", \"description\": \"Free-text search, e.g. \\\"sauna\\\"\", \"schema\": { \"type\": \"string\" } }],\n  \"responses\": { \"200\": { \"description\": \"Matching items\", \"content\": { \"application/json\": { \"schema\": { \"$ref\": \"#/components/schemas/ItemList\" } } } } }\n}","prompt":"For every operation in the OpenAPI document add a unique camelCase operationId, a one-line summary saying what it does and when to use it, a description on every parameter (with an example), and a JSON schema for each 2xx response."},"implemented":true},{"id":"api.problem-json","layer":"api","title":"Errors use problem+json (RFC 9457)","severity":1,"standard":{"key":"rfc9457","name":"Problem Details for HTTP APIs","body":"IETF","version":"RFC 9457","date":"2023-08","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9457"},"chapter":7,"test":"Request an unknown path under the API base; expect application/problem+json with type/title/status","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"api","heuristic":false,"why":"When a call fails, an agent needs a machine-readable reason to recover. RFC 9457 problem details give it a type, title and status instead of an HTML error page (book chapter 7).","fix":{"snippet":"HTTP/1.1 404 Not Found\nContent-Type: application/problem+json\n\n{ \"type\": \"https://example.com/problems/not-found\", \"title\": \"No item with that id\", \"status\": 404, \"detail\": \"Item 42 does not exist.\" }","prompt":"Make every API error (4xx and 5xx, including unknown routes) answer with Content-Type application/problem+json and a JSON body with type, title, status and detail (RFC 9457). Verify with: curl -i https://<site>/api/does-not-exist"},"implemented":true},{"id":"api.ratelimit","layer":"api","title":"Rate limits are announced in headers","severity":1,"standard":{"key":"ratelimit","name":"RateLimit header fields","body":"IETF httpapi WG","version":"draft-11","date":"2026-05","status":"IETF WG draft","maturity":"draft","url":"https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/"},"chapter":7,"test":"API responses carry RateLimit/RateLimit-Policy (draft-11) or Retry-After on 429","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"api","heuristic":false,"why":"Agents run in loops. Announcing the quota in RateLimit headers lets them slow down before they hit 429 instead of being blocked (book chapter 7). The header fields are an IETF draft.","fix":{"snippet":"RateLimit-Policy: \"default\";q=100;w=60\nRateLimit: \"default\";r=99;t=60","prompt":"Add the IETF RateLimit-Policy and RateLimit response headers (draft-ietf-httpapi-ratelimit-headers-11) to every API response, and answer 429 with Retry-After and an application/problem+json body when the quota is used up."},"implemented":true},{"id":"api.deprecation","layer":"api","title":"Deprecation/Sunset headers are well-formed (if used)","severity":1,"standard":{"key":"rfc9745","name":"Deprecation header (+ Sunset RFC 8594)","body":"IETF","version":"RFC 9745","date":"2025-03","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9745"},"chapter":20,"test":"Deprecation (RFC 9745 structured date) and Sunset (HTTP-date) on API responses; informational","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"api","heuristic":false,"why":"APIs change. Deprecation (RFC 9745) and Sunset (RFC 8594) headers warn an agent in-band, before a call it depends on stops working (book chapter 20).","fix":{"snippet":"Deprecation: @1798761600\nSunset: Sat, 01 Jan 2028 00:00:00 GMT\nLink: <https://example.com/docs/migrate-v2>; rel=\"deprecation\"","prompt":"On deprecated API endpoints add a Deprecation header in RFC 9745 form (@ followed by Unix seconds), a Sunset header with an HTTP-date, and a Link rel=\"deprecation\" to the migration guide. Mark the operations \"deprecated\": true in OpenAPI."},"implemented":true},{"id":"api.actionable-interface","layer":"api","title":"Key actions have a machine interface","severity":2,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":13,"test":"If the site has forms or commerce signals: at least one of API catalog/OpenAPI, MCP endpoint or WebMCP tools","iia":null,"lh":null,"roles":["pm","arch"],"requires":"http","applies":"always","heuristic":false,"why":"If people can search, book or buy on your site, agents need a way to do the same without clicking through forms: an API, an MCP server or WebMCP tools (book chapter 13).","fix":{"snippet":"<form action=\"/search\" toolname=\"search_items\" tooldescription=\"Search the catalogue by keyword\">\n  <input name=\"q\" toolparamdescription=\"Search words\">\n</form>","prompt":"Give the site's main actions a machine interface. Cheapest: add WebMCP attributes (toolname, tooldescription) to the existing forms. Fuller: publish an OpenAPI-described API and list it in /.well-known/api-catalog, or an MCP server with a server card."},"implemented":true},{"id":"mcp.server-card","layer":"mcp","title":"MCP server card is published","severity":2,"standard":{"key":"mcpcard","name":"MCP Server Cards","body":"MCP project","version":"SEP-2127 (earlier SEP-1649)","date":"2026","status":"Contested (SEP page \"Final\", extension repo \"Experimental\")","maturity":"proposal","url":"https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127"},"chapter":11,"test":"/.well-known/mcp/server-card.json, /.well-known/mcp/server-cards.json or /.well-known/mcp.json with a name (isitagentready rule)","iia":"mcpServerCard","lh":null,"roles":["arch","dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"A server card describes an MCP server (name, endpoint, what it offers) before an agent connects, so clients and registries can find it. isitagentready counts it toward Level 4 (book chapter 11).","fix":{"snippet":"{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json\",\n  \"name\": \"com.example/shop\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Search the catalogue and place orders.\",\n  \"remotes\": [{ \"type\": \"streamable-http\", \"url\": \"https://example.com/mcp\" }]\n}","prompt":"Serve an MCP server card as JSON at /.well-known/mcp/server-card.json (the path scanners read today) and at <mcp-endpoint>/server-card (the SEP-2127 location), with name, version, description and a remotes entry pointing at the MCP endpoint."},"implemented":true},{"id":"mcp.server-card-valid","layer":"mcp","title":"Server card is complete and points to a live endpoint","severity":2,"standard":{"key":"mcpcard","name":"MCP Server Cards","body":"MCP project","version":"SEP-2127 (earlier SEP-1649)","date":"2026","status":"Contested (SEP page \"Final\", extension repo \"Experimental\")","maturity":"proposal","url":"https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127"},"chapter":11,"test":"serverInfo name+version, transport/remotes URL that answers, SEP-2127 location (/mcp/server-card) also checked","iia":null,"lh":null,"roles":["arch","dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"A card is only useful when it names the server and version and points at an endpoint that actually answers (book chapter 11).","fix":{"snippet":"\"remotes\": [{ \"type\": \"streamable-http\", \"url\": \"https://example.com/mcp\", \"supportedProtocolVersions\": [\"2025-11-25\", \"2026-07-28\"] }]","prompt":"Complete the MCP server card: add name, version, description and remotes[0].url pointing at the live MCP endpoint, and also serve the card at <endpoint>/server-card (SEP-2127). Verify the endpoint answers an initialize POST."},"implemented":true},{"id":"mcp.endpoint","layer":"mcp","title":"MCP endpoint answers initialize","severity":3,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":8,"test":"POST initialize (protocolVersion 2026-07-28) to the endpoint from the card/ARD or /mcp; pass on a JSON-RPC result or a spec 401 challenge","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"The MCP endpoint is where agents actually connect. It must answer server/discover (MCP 2026-07-28) or the 2025-era initialize handshake with a JSON-RPC result, or a proper 401 challenge when it needs OAuth (book chapter 8).","fix":{"snippet":"POST /mcp\nContent-Type: application/json\nAccept: application/json, text/event-stream\nMCP-Protocol-Version: 2026-07-28\nMcp-Method: server/discover\n\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\"io.modelcontextprotocol/clientCapabilities\":{},\"io.modelcontextprotocol/clientInfo\":{\"name\":\"test\",\"version\":\"1\"}}}}","prompt":"Make the MCP endpoint answer a Streamable HTTP server/discover POST (MCP 2026-07-28; keep serving the 2025 initialize handshake for older clients) with a JSON-RPC result (or, when it needs OAuth, HTTP 401 with WWW-Authenticate: Bearer resource_metadata=\"<PRM URL>\"). Test with the MCP Inspector: npx @modelcontextprotocol/inspector."},"implemented":true},{"id":"mcp.protocol-version","layer":"mcp","title":"Server speaks a current MCP protocol version","severity":1,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":8,"test":"protocolVersion from initialize; warn on versions before 2025-06-18","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"Older MCP protocol versions lack structured output, elicitation and the current authorization rules; clients negotiate down and lose features (book chapter 8).","fix":{"snippet":"\"protocolVersion\": \"2026-07-28\"","prompt":"Upgrade the MCP server SDK so the server supports the stateless 2026-07-28 revision (server/discover) and still serves 2025-11-25 clients, then re-test with the MCP Inspector."},"implemented":true},{"id":"mcp.tools-list","layer":"mcp","title":"tools/list returns tools (public endpoints)","severity":2,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":8,"test":"tools/list on public endpoints; count and names; skipped when auth is required","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"tools/list is what an agent sees of your server: if it is empty or broken, nothing is callable (book chapter 8).","fix":{"snippet":"{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"search_items\",\"description\":\"Search the catalogue\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"q\":{\"type\":\"string\",\"description\":\"Search words\"}}}}]}}","prompt":"Register the site's main actions as MCP tools so tools/list returns them, each with a name, description and an inputSchema of type object."},"implemented":true},{"id":"mcp.tool-schemas","layer":"mcp","title":"Tool inputSchemas are valid JSON Schema objects with descriptions","severity":2,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":10,"test":"Each tool: name pattern, description length, inputSchema type object, properties described, required subset","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"Agents fill tool arguments from the inputSchema and choose tools by description. A missing or malformed schema means wrong calls (book chapter 10).","fix":{"snippet":"\"inputSchema\": {\n  \"type\": \"object\",\n  \"properties\": { \"check_in\": { \"type\": \"string\", \"format\": \"date\", \"description\": \"Arrival date, YYYY-MM-DD\" } },\n  \"required\": [\"check_in\"]\n}","prompt":"For every MCP tool: use a name of letters, digits, _ - . only; write a description of at least one sentence saying when to use it; give an inputSchema with \"type\": \"object\", a description on every property, and a required list that only names existing properties."},"implemented":true},{"id":"mcp.origin-validation","layer":"mcp","title":"Endpoint rejects foreign Origin headers","severity":2,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":16,"test":"POST initialize with Origin: https://evil.example; spec says servers MUST validate Origin (DNS rebinding); pass on 403/400","iia":null,"lh":null,"roles":["security","dev"],"requires":"http","applies":"mcp","heuristic":false,"why":"The MCP Streamable HTTP transport says servers MUST validate the Origin header, so a web page cannot use the visitor's browser to talk to the server (DNS rebinding). Public servers often accept any origin on purpose (book chapter 16).","fix":{"snippet":"if (req.headers.origin && !ALLOWED_ORIGINS.has(req.headers.origin)) return new Response(null, { status: 403 });","prompt":"In the MCP endpoint handler, reject requests whose Origin header is present and not on an allowlist with HTTP 403, and never answer Access-Control-Allow-Origin with a reflected origin together with Access-Control-Allow-Credentials: true."},"implemented":true},{"id":"webmcp.tools","layer":"webmcp","title":"Page exposes WebMCP tools","severity":2,"standard":{"key":"webmcp","name":"WebMCP","body":"W3C Web Machine Learning CG","version":"Draft 2026-11-02","date":"2026-11-02","status":"W3C CG draft, Chrome origin trial","maturity":"draft","url":"https://webmachinelearning.github.io/webmcp/"},"chapter":9,"test":"Browser with WebMCPTesting: document.modelContext.getTools(); static fallback finds registerTool calls and <form toolname> (isitagentready rule)","iia":"webMcp","lh":"webmcp-registered-tools","roles":["dev","pm"],"requires":"http","applies":"forms","heuristic":false,"why":"WebMCP lets a site hand in-browser agents named tools with schemas instead of making them click through the page. Both isitagentready and Lighthouse look for them (book chapter 9).","fix":{"snippet":"<form action=\"/search\" toolname=\"search_products\"\n      tooldescription=\"Search the catalogue by keyword. Returns matching products with prices.\">\n  <label>Keyword <input name=\"q\" toolparamdescription=\"Words to search for\"></label>\n  <button>Search</button>\n</form>\n<script>\n  if ('modelContext' in document) document.modelContext.registerTool({\n    name: 'get_product', description: 'Get one product by its id, with price and stock.',\n    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'Product id from search_products' } }, required: ['id'] },\n    annotations: { readOnlyHint: true },\n    async execute({ id }) { return JSON.stringify(await (await fetch(`/api/products/${id}`)).json()); },\n  });\n</script>","prompt":"Expose the site's key actions as WebMCP tools. Add toolname, tooldescription and toolparamdescription attributes to existing forms (search, contact, booking), and register tools that no single form covers with document.modelContext.registerTool() behind a feature check ('modelContext' in document). Verify in Chrome with chrome://flags WebMCP testing enabled: document.modelContext.getTools() lists them."},"implemented":true},{"id":"webmcp.form-coverage","layer":"webmcp","title":"Forms declare toolname and tooldescription","severity":2,"standard":{"key":"lh-webmcp","name":"Lighthouse WebMCP audits","body":"Google Chrome","version":"Lighthouse 13.6.0","date":"2026-10-27","status":"Tool audit over a W3C CG draft","maturity":"draft","url":"https://github.com/GoogleChrome/lighthouse"},"chapter":9,"test":"Every <form> has both attributes (Lighthouse webmcp-form-coverage)","iia":null,"lh":"webmcp-form-coverage","roles":["dev","design"],"requires":"http","applies":"forms","heuristic":false,"why":"A form that already does a job is the cheapest tool you will ever write: two attributes turn it into a WebMCP tool, with the schema built from its fields. Lighthouse lists the forms that lack them (book chapter 9).","fix":{"snippet":"<form action=\"/contact\" method=\"post\" toolname=\"contact_us\"\n      tooldescription=\"Send a message to the team. Use for questions about orders or bookings.\">","prompt":"For every public form except login and password forms, add toolname (snake_case verb_noun) and tooldescription (what it does, when to use it, what happens on submit) to the <form> element, and toolparamdescription to fields whose label is not self-explanatory. Re-run Lighthouse Agentic Browsing: webmcp-form-coverage should pass."},"implemented":true},{"id":"webmcp.schema-validity","layer":"webmcp","title":"Declarative tool attributes and field names are valid","severity":2,"standard":{"key":"lh-webmcp","name":"Lighthouse WebMCP audits","body":"Google Chrome","version":"Lighthouse 13.6.0","date":"2026-10-27","status":"Tool audit over a W3C CG draft","maturity":"draft","url":"https://github.com/GoogleChrome/lighthouse"},"chapter":9,"test":"toolname pattern, descriptions, named fields with toolparamdescription; Lighthouse 0/0.5/1 scoring","iia":null,"lh":"webmcp-schema-validity","roles":["dev"],"requires":"http","applies":"forms","heuristic":false,"why":"Chrome builds a declarative tool's schema from the form. A missing toolname, a required field without a name or an undescribed optional field gives agents a broken or vague tool. Lighthouse scores this 0, 0.5 or 1 (book chapter 9).","fix":{"snippet":"<form toolname=\"find_booking\" tooldescription=\"Look up a booking by its reference and email.\">\n  <label for=\"ref\">Booking reference</label>\n  <input id=\"ref\" name=\"ref\" required toolparamdescription=\"Reference like NC-1234\">\n  <input name=\"email\" type=\"email\" required>\n</form>","prompt":"In every form that has toolname or tooldescription: make sure toolname is set (snake_case, letters, digits and underscores), every required field has a name attribute, and every optional field has a <label> or toolparamdescription. Re-run Lighthouse Agentic Browsing: webmcp-schema-validity should score 1."},"implemented":true},{"id":"webmcp.tool-schemas","layer":"webmcp","title":"Imperative tools have valid input schemas","severity":2,"standard":{"key":"webmcp","name":"WebMCP","body":"W3C Web Machine Learning CG","version":"Draft 2026-11-02","date":"2026-11-02","status":"W3C CG draft, Chrome origin trial","maturity":"draft","url":"https://webmachinelearning.github.io/webmcp/"},"chapter":9,"test":"Each registered tool: inputSchema is a JSON Schema object, required subset of properties, outputSchema valid if given","iia":null,"lh":null,"roles":["dev"],"requires":"browser","applies":"always","heuristic":false,"why":"An imperative tool's inputSchema is the only parameter documentation an agent gets. It must be an object schema whose required names exist in properties (book chapter 9).","fix":{"snippet":"inputSchema: {\n  type: 'object',\n  properties: {\n    checkIn: { type: 'string', format: 'date', description: 'Arrival date, YYYY-MM-DD' },\n    guests: { type: 'integer', minimum: 1, description: 'Number of guests' },\n  },\n  required: ['checkIn', 'guests'],\n}","prompt":"For every tool passed to document.modelContext.registerTool(): give it an inputSchema with type \"object\", a properties map where each property has a type and a description, and a required array that only names properties that exist. If outputSchema is set, make it an object schema too. Verify with document.modelContext.getTools() in Chrome with WebMCP testing enabled."},"implemented":true},{"id":"webmcp.tool-count","layer":"webmcp","title":"Tool count stays manageable (<= 40)","severity":1,"standard":{"key":"lh-webmcp","name":"Lighthouse WebMCP audits","body":"Google Chrome","version":"Lighthouse 13.6.0","date":"2026-10-27","status":"Tool audit over a W3C CG draft","maturity":"draft","url":"https://github.com/GoogleChrome/lighthouse"},"chapter":10,"test":"Count of registered tools; warn above 40 (Lighthouse threshold)","iia":null,"lh":null,"roles":["dev","pm"],"requires":"browser","applies":"always","heuristic":false,"why":"Agents choose worse from long tool lists, and every tool costs context. Lighthouse warns above 40 tools on one page (book chapter 10).","fix":{"snippet":"// Register only the tools that fit this page; unregister on navigation\nconst controller = new AbortController();\ndocument.modelContext.registerTool(tool, { signal: controller.signal });","prompt":"Reduce the number of WebMCP tools registered on this page to the actions that make sense here (40 at most, ideally under 20): merge near-duplicates, register page-specific tools only on their pages, and unregister with an AbortController when they stop applying."},"implemented":true},{"id":"webmcp.descriptions","layer":"webmcp","title":"Tool descriptions tell an agent when to use them","severity":1,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":10,"test":"Description length 20-500 chars, starts with a verb, names inputs; duplicates flagged","iia":null,"lh":null,"roles":["dev","pm"],"requires":"http","applies":"forms","heuristic":true,"why":"The description is how an agent decides whether to call a tool: it should say what the tool does, when to use it and what comes back. Vague or duplicate descriptions make agents pick the wrong tool (book chapter 10).","fix":{"snippet":"description: 'Check if one cabin is free for a stay and get the exact total price. Call this before create_booking. available=false means the dates are taken.'","prompt":"Rewrite each WebMCP tool description (tooldescription attribute or registerTool description) to start with a verb, say what the tool does, when to use it and what it returns, in 20 to 500 characters, and make every description distinct."},"implemented":true},{"id":"webmcp.annotations","layer":"webmcp","title":"Tools carry readOnlyHint / untrustedContentHint annotations","severity":1,"standard":{"key":"webmcp","name":"WebMCP","body":"W3C Web Machine Learning CG","version":"Draft 2026-11-02","date":"2026-11-02","status":"W3C CG draft, Chrome origin trial","maturity":"draft","url":"https://webmachinelearning.github.io/webmcp/"},"chapter":10,"test":"Read-only-looking tools (get/search/list/check) marked readOnlyHint; write tools not","iia":null,"lh":null,"roles":["dev","security"],"requires":"browser","applies":"always","heuristic":false,"why":"readOnlyHint tells the browser and the agent whether a call changes anything, so hosts can skip or require a confirmation. A write tool marked read-only removes that safety net (book chapter 10).","fix":{"snippet":"annotations: { readOnlyHint: true, untrustedContentHint: true } // for get_/search_ tools that return user content\nannotations: { readOnlyHint: false }                            // for book_/create_/cancel_ tools","prompt":"For every registerTool() call, set annotations.readOnlyHint: true on tools that only read (get, search, list, check), leave it false on tools that change state (book, create, cancel, send), and set untrustedContentHint: true on tools that return third-party or user-written content."},"implemented":true},{"id":"webmcp.origin-trial","layer":"webmcp","title":"WebMCP origin-trial token (for Chrome) if WebMCP is used","severity":1,"standard":{"key":"webmcp","name":"WebMCP","body":"W3C Web Machine Learning CG","version":"Draft 2026-11-02","date":"2026-11-02","status":"W3C CG draft, Chrome origin trial","maturity":"draft","url":"https://webmachinelearning.github.io/webmcp/"},"chapter":9,"test":"meta http-equiv=origin-trial or Origin-Trial header; informational","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Until WebMCP ships by default, ordinary Chrome users only get a site's tools when the site carries a valid WebMCP origin-trial token for its own origin (book chapter 9).","fix":{"snippet":"<meta http-equiv=\"origin-trial\" content=\"YOUR_WEBMCP_TOKEN\">\n<!-- or the HTTP header -->\nOrigin-Trial: YOUR_WEBMCP_TOKEN","prompt":"Register the site origin for the WebMCP origin trial in the Chrome Origin Trials console, then serve the token on every page that registers tools, as an Origin-Trial response header or a <meta http-equiv=\"origin-trial\"> tag in <head>. Renew it before it expires."},"implemented":true},{"id":"discovery.ard","layer":"discovery","title":"ARD manifest is discoverable","severity":2,"standard":{"key":"ard","name":"Agentic Resource Discovery (ARD)","body":"Authors from Google and others","version":"v0.91","date":"2026-08-26","status":"Proposal","maturity":"proposal","url":"https://agenticresourcediscovery.org/"},"chapter":11,"test":"Agentmap robots line, link rel=ard, Link header, /.well-known/ard.json, legacy /.well-known/ai-catalog.json (isitagentready + Lighthouse order)","iia":"ard","lh":"ard-schema","roles":["arch","dev"],"requires":"http","applies":"always","heuristic":false,"why":"An ARD manifest lists everything an agent can use on your site (MCP servers, skills, APIs) in one file, found through robots.txt, a link or a well-known path. Lighthouse 13.6 audits it (book chapter 11). ARD is a proposal (v0.91).","fix":{"snippet":"Agentmap: https://example.com/.well-known/ard.json\n\nLink: </.well-known/ard.json>; rel=\"ard\"","prompt":"Publish an ARD manifest at /.well-known/ard.json with a specVersion and an entries array (identifier urn:air:<domain>:<namespace>:<name>, displayName, IANA media type in \"type\", and exactly one of url or data), then point to it with an Agentmap: line in robots.txt and a Link header rel=\"ard\" on the homepage."},"implemented":true},{"id":"discovery.ard-valid","layer":"discovery","title":"ARD manifest is valid","severity":2,"standard":{"key":"ard","name":"Agentic Resource Discovery (ARD)","body":"Authors from Google and others","version":"v0.91","date":"2026-08-26","status":"Proposal","maturity":"proposal","url":"https://agenticresourcediscovery.org/"},"chapter":11,"test":"specVersion, entries with urn:air identifier, displayName, IANA media type, exactly one of url/data; host object noted (only Cloudflare's fix text asks for it); warns on legacy location","iia":null,"lh":null,"roles":["arch","dev"],"requires":"http","applies":"always","heuristic":false,"why":"Agents and Lighthouse read every ARD entry; a wrong identifier, a missing media type or both url and data make an entry unusable (book chapter 11).","fix":{"snippet":"{\n  \"specVersion\": \"1.0\",\n  \"entries\": [{\n    \"identifier\": \"urn:air:example.com:mcp:shop\",\n    \"displayName\": \"Example shop\",\n    \"type\": \"application/mcp-server-card+json\",\n    \"url\": \"https://example.com/mcp/server-card\"\n  }]\n}","prompt":"Fix every entry in the ARD manifest: identifier urn:air:<your-domain>:<namespace>:<name>, a displayName, an IANA media type in \"type\", exactly one of url or data. Serve it at /.well-known/ard.json (not the legacy ai-catalog.json)."},"implemented":true},{"id":"discovery.agent-skills","layer":"discovery","title":"Agent Skills index is published","severity":2,"standard":{"key":"skills","name":"Agent Skills Discovery","body":"Vendor proposal (Cloudflare)","version":"v0.2.0","date":"2026","status":"Vendor proposal","maturity":"proposal","url":"https://github.com/cloudflare/agent-skills-discovery-rfc"},"chapter":11,"test":"/.well-known/agent-skills/index.json (or legacy /.well-known/skills/index.json) with a skills array (isitagentready rule)","iia":"agentSkills","lh":null,"roles":["arch","dev"],"requires":"http","applies":"always","heuristic":false,"why":"An Agent Skills index lets agents download ready-made instructions for working with your site. isitagentready counts it toward Level 4 (book chapter 11).","fix":{"snippet":"{\n  \"$schema\": \"https://schemas.agentskills.io/discovery/0.2.0/schema.json\",\n  \"skills\": [{ \"name\": \"place-an-order\", \"type\": \"skill-md\", \"description\": \"Order from Example shop\", \"url\": \"/.well-known/agent-skills/place-an-order/SKILL.md\", \"digest\": \"sha256:<hex>\" }]\n}","prompt":"Publish /.well-known/agent-skills/index.json (Agent Skills Discovery v0.2.0) with $schema and a skills array; each entry has name, type, description, url and a sha256 digest of the skill file. Serve each SKILL.md at its url."},"implemented":true},{"id":"discovery.agent-skills-valid","layer":"discovery","title":"Skill entries are complete and digests match","severity":2,"standard":{"key":"skills","name":"Agent Skills Discovery","body":"Vendor proposal (Cloudflare)","version":"v0.2.0","date":"2026","status":"Vendor proposal","maturity":"proposal","url":"https://github.com/cloudflare/agent-skills-discovery-rfc"},"chapter":11,"test":"$schema, name/type/description/url/digest per entry; fetch each skill (max 10) and compare sha256 digest","iia":null,"lh":null,"roles":["dev","security"],"requires":"http","applies":"always","heuristic":false,"why":"The digest lets an agent verify it got the skill the site published, not a tampered copy; missing fields or stale digests make the index untrustworthy (book chapter 11).","fix":{"snippet":"digest = \"sha256:\" + sha256(file bytes as served).hex()\n# shell: printf \"sha256:%s\" \"$(curl -s https://example.com/.well-known/agent-skills/x/SKILL.md | sha256sum | cut -d\" \" -f1)\"","prompt":"Give every entry in /.well-known/agent-skills/index.json a name (lowercase, digits, hyphens), type, description, url and digest; regenerate each digest as sha256 of the exact bytes served at the url (build step, not by hand) and add \"$schema\"."},"implemented":true},{"id":"discovery.a2a-card","layer":"discovery","title":"A2A Agent Card (opt-in)","severity":1,"standard":{"key":"a2a","name":"A2A (Agent2Agent) Agent Card","body":"Agentic AI Foundation","version":"1.0.1","date":"2026-05-26","status":"Dated spec","maturity":"standard","url":"https://a2a-protocol.org/latest/specification/"},"chapter":11,"test":"/.well-known/agent-card.json with name, version, supportedInterfaces (isitagentready rule, opt-in)","iia":"a2aAgentCard","lh":null,"roles":["arch"],"requires":"http","applies":"optin","heuristic":false,"why":"An A2A Agent Card describes an agent your site runs, so other agents can delegate tasks to it. Only relevant if you operate an agent; isitagentready makes it opt-in (book chapter 11).","fix":{"snippet":"{ \"name\": \"Example concierge\", \"version\": \"1.0.0\", \"description\": \"Answers questions about orders\", \"supportedInterfaces\": [{ \"url\": \"https://example.com/a2a\", \"protocolBinding\": \"JSONRPC\" }], \"skills\": [] }","prompt":"If the site operates an A2A agent, serve /.well-known/agent-card.json (A2A 1.0) with name, version, description, supportedInterfaces and skills."},"implemented":true},{"id":"discovery.dns-aid","layer":"discovery","title":"DNS-AID records under _agents","severity":1,"standard":{"key":"dnsaid","name":"DNS for AI Discovery (DNS-AID)","body":"IETF (individual)","version":"draft-mozleywilliams-dnsop-dnsaid-02","date":"2026-05-27","status":"Individual draft","maturity":"proposal","url":"https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/"},"chapter":11,"test":"DNS-over-HTTPS SVCB/HTTPS lookup of _index._agents.<host> and _mcp/_a2a, DNSSEC AD flag (isitagentready rule)","iia":"dnsAid","lh":null,"roles":["arch"],"requires":"dns","applies":"always","heuristic":false,"why":"DNS-AID publishes agent endpoints in DNS (SVCB records under _agents), signed with DNSSEC, so agents can find them before any HTTP request. It is an early IETF draft (book chapter 11).","fix":{"snippet":"_index._agents.example.com. 3600 IN SVCB 1 agents.example.com. alpn=\"h2\" port=443","prompt":"Publish ServiceMode SVCB records such as _index._agents.<domain> (or _mcp._agents / _a2a._agents) pointing at your agent endpoints, and sign the zone with DNSSEC. Verify with: curl -s -H \"accept: application/dns-json\" \"https://cloudflare-dns.com/dns-query?name=_index._agents.<domain>&type=SVCB\""},"implemented":true},{"id":"discovery.poppy","layer":"discovery","title":"Personal Agent Protocol manifest (informational)","severity":1,"standard":{"key":"poppy","name":"Personal Agent Protocol (poppy.json)","body":"Single proposal","version":"Draft 0.1","date":"2026","status":"Proposal","maturity":"proposal","url":"https://personalagentprotocol.org/docs/spec"},"chapter":11,"test":"/.well-known/poppy.json organisation/domain/interfaces (isitagentready rule, informational)","iia":"personalAgentProtocol","lh":null,"roles":["arch"],"requires":"http","applies":"optin","heuristic":false,"why":"The Personal Agent Protocol (draft 0.1) lets a site declare which personal agents may act for its users. It is a single early proposal; isitagentready shows it as informational (book chapter 11).","fix":{"snippet":"{ \"organization\": \"Example\", \"domain\": \"example.com\", \"interfaces\": { \"web\": {} } }","prompt":"Only if you adopt the Personal Agent Protocol: serve /.well-known/poppy.json with organization, domain and interfaces (web: {} for website-only); when you declare auth, make the RFC 8414 issuer match and list the domain in poppy_domains."},"implemented":true},{"id":"discovery.soft-404","layer":"discovery","title":"Unknown paths return 404 (no soft-404s)","severity":2,"standard":{"key":"rfc8615","name":"Well-Known URIs","body":"IETF","version":"RFC 8615","date":"2019-05","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc8615"},"chapter":11,"test":"GET a random /.well-known path and a random page; a 200 HTML answer makes every probe ambiguous and agents waste requests","iia":null,"lh":null,"roles":["dev","qa"],"requires":"http","applies":"always","heuristic":false,"why":"Agents probe well-known paths to find capabilities. If unknown paths answer 200 with an HTML page, every probe looks like a hit, agents waste requests and some will parse your homepage as a manifest. RFC 8615 reserves /.well-known/ for real resources (book chapter 11).","fix":{"snippet":"# nginx\nlocation /.well-known/ { try_files $uri =404; }\nerror_page 404 /404.html;","prompt":"Make unknown paths, especially under /.well-known/, answer HTTP 404 (not 200 with the app shell or a redirect to the homepage). For single-page apps, restrict the HTML fallback to real routes."},"implemented":true},{"id":"discovery.wellknown-types","layer":"discovery","title":"Well-known JSON files are served as JSON","severity":1,"standard":{"key":"rfc8615","name":"Well-Known URIs","body":"IETF","version":"RFC 8615","date":"2019-05","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc8615"},"chapter":11,"test":"Every found well-known JSON resource has a JSON media type and parses","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Agents decide how to parse a file from its Content-Type. A well-known JSON file served as text/html or text/plain may be skipped or misread (book chapter 11).","fix":{"snippet":"# Cloudflare _headers / Netlify\n/.well-known/*.json\n  Content-Type: application/json\n/.well-known/api-catalog\n  Content-Type: application/linkset+json","prompt":"Serve every JSON file under /.well-known/ with a JSON media type (application/json, or the specific +json type such as application/linkset+json for the API catalog) and make sure each one parses as JSON."},"implemented":true},{"id":"commerce.detected","layer":"commerce","title":"Commerce signals detected","severity":1,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":12,"test":"Product/Offer JSON-LD, cart/checkout links, platform markers (Shopify, WooCommerce...); decides whether commerce checks score","iia":null,"lh":null,"roles":["pm"],"requires":"http","applies":"always","heuristic":false,"why":"Commerce protocols (UCP, ACP, x402, MPP, AP2) and product data only matter for sites that sell or book. This check decides whether the commerce checks are scored (book chapter 12).","fix":{"snippet":"{ \"@context\": \"https://schema.org\", \"@type\": \"Product\", \"name\": \"...\", \"offers\": { \"@type\": \"Offer\", \"price\": \"49.00\", \"priceCurrency\": \"EUR\", \"availability\": \"https://schema.org/InStock\" } }","prompt":"If the site sells or books anything, mark products and offers up with schema.org Product/Offer JSON-LD so agents (and this checker) recognise it as a shop."},"implemented":true},{"id":"commerce.product-data","layer":"commerce","title":"Products/offers have price, currency and availability","severity":2,"standard":{"key":"schemaorg","name":"schema.org","body":"schema.org community","version":"current release","date":"continuous","status":"Community vocabulary","maturity":"standard","url":"https://schema.org/"},"chapter":12,"test":"Product/Offer JSON-LD: offers.price, priceCurrency, availability; checked against visible price","iia":null,"lh":null,"roles":["content","dev"],"requires":"http","applies":"commerce","heuristic":false,"why":"Shopping agents compare offers from structured data. Without price, currency and availability in Product/Offer JSON-LD, or with a price that differs from the page, they skip you or quote the wrong price (book chapter 12).","fix":{"snippet":"<script type=\"application/ld+json\">\n{ \"@context\": \"https://schema.org\", \"@type\": \"Product\", \"name\": \"Fjellro cabin\",\n  \"offers\": { \"@type\": \"Offer\", \"price\": \"1290\", \"priceCurrency\": \"NOK\", \"availability\": \"https://schema.org/InStock\" } }\n</script>","prompt":"Add schema.org Product (or the right subtype) JSON-LD to product pages with offers.price (a number as a string, no currency sign), offers.priceCurrency (ISO 4217), and offers.availability (a schema.org ItemAvailability URL); render it from the same data as the visible price so they never differ."},"implemented":true},{"id":"commerce.ucp","layer":"commerce","title":"UCP business profile","severity":2,"standard":{"key":"ucp","name":"Universal Commerce Protocol","body":"Google, Shopify and partners","version":"dated releases","date":"2026","status":"Dated spec (Lodging: draft)","maturity":"standard","url":"https://ucp.dev/specification/overview/"},"chapter":12,"test":"/.well-known/ucp with protocol_version (or ucp.version) and services (isitagentready rule)","iia":"ucp","lh":null,"roles":["arch","pm"],"requires":"http","applies":"commerce","heuristic":false,"why":"A UCP business profile tells shopping agents which commerce services and capabilities (checkout, booking, orders) your site supports (book chapter 12). UCP is a dated spec; some capabilities are drafts.","fix":{"snippet":"{ \"ucp\": { \"version\": \"2026-08-25\", \"services\": { \"dev.ucp.shopping\": [{ \"version\": \"2026-08-25\", \"transport\": \"rest\", \"endpoint\": \"https://example.com/ucp/v1\" }] }, \"capabilities\": { \"dev.ucp.shopping.checkout\": [{ \"version\": \"2026-08-25\" }] } } }","prompt":"Serve /.well-known/ucp as JSON with the UCP protocol version, the services you implement (each with transport and an https endpoint) and the capabilities you support, following ucp.dev."},"implemented":true},{"id":"commerce.ucp-valid","layer":"commerce","title":"UCP profile lists capabilities and reachable endpoints","severity":1,"standard":{"key":"ucp","name":"Universal Commerce Protocol","body":"Google, Shopify and partners","version":"dated releases","date":"2026","status":"Dated spec (Lodging: draft)","maturity":"standard","url":"https://ucp.dev/specification/overview/"},"chapter":12,"test":"capabilities array, services with transport endpoints, endpoints on https","iia":null,"lh":null,"roles":["arch","dev"],"requires":"http","applies":"commerce","heuristic":false,"why":"Agents act on the endpoints and capabilities a UCP profile names; a profile without capabilities or with non-https endpoints cannot be used (book chapter 12).","fix":{"snippet":"\"services\": { \"dev.ucp.shopping\": [{ \"version\": \"2026-08-25\", \"transport\": \"rest\", \"endpoint\": \"https://example.com/ucp/v1\", \"schema\": \"https://ucp.dev/services/shopping/rest.openapi.json\" }] }","prompt":"In /.well-known/ucp give every service binding a transport and an https endpoint, and list the capabilities you implement with their versions."},"implemented":true},{"id":"commerce.acp","layer":"commerce","title":"ACP discovery document","severity":1,"standard":{"key":"acp","name":"Agentic Commerce Protocol","body":"OpenAI and Stripe","version":"2026-04-17","date":"2026-04-17","status":"Beta (discovery path is the scanner's convention)","maturity":"proposal","url":"https://agenticcommerce.dev"},"chapter":12,"test":"/.well-known/acp.json with protocol.name/version, api_base_url, transports, capabilities.services (isitagentready rule)","iia":"acp","lh":null,"roles":["arch"],"requires":"http","applies":"commerce","heuristic":false,"why":"The ACP discovery document tells agents where your Agentic Commerce Protocol checkout lives. The ACP repository says merchant discovery is not yet defined, so this path is the scanner's convention (book chapter 12).","fix":{"snippet":"{ \"protocol\": { \"name\": \"acp\", \"version\": \"2026-09-30\" }, \"api_base_url\": \"https://example.com/acp\", \"transports\": [\"rest\"], \"capabilities\": { \"services\": [\"checkout\"] } }","prompt":"If you implement the Agentic Commerce Protocol, serve /.well-known/acp.json with protocol.name, protocol.version, api_base_url, transports and capabilities.services."},"implemented":true},{"id":"commerce.x402","layer":"commerce","title":"x402 payment-required responses","severity":1,"standard":{"key":"x402","name":"x402","body":"x402 Foundation","version":"V2","date":"2026","status":"Dated spec","maturity":"draft","url":"https://x402.org"},"chapter":12,"test":"Paid API routes (from OpenAPI/catalog) answer 402 with x402 payment requirements (isitagentready rule)","iia":"x402","lh":null,"roles":["arch","dev"],"requires":"http","applies":"commerce","heuristic":false,"why":"x402 lets an agent pay for an API call in-band: the route answers 402 with machine-readable payment requirements. Only relevant for paid APIs (book chapter 12).","fix":{"snippet":"HTTP/1.1 402 Payment Required\nPAYMENT-REQUIRED: <base64 of {\"x402Version\":2,\"accepts\":[{\"scheme\":\"exact\",\"network\":\"...\",\"amount\":\"10000\",\"payTo\":\"...\"}]}>","prompt":"For paid API routes, add x402 middleware so an unpaid request answers HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON with x402Version and accepts) as the x402 V2 spec describes."},"implemented":true},{"id":"commerce.mpp","layer":"commerce","title":"MPP payment info in OpenAPI","severity":1,"standard":{"key":"mpp","name":"Machine Payments Protocol","body":"Stripe and Tempo","version":"launched 2026-03-18","date":"2026-03-18","status":"Vendor-led open protocol","maturity":"proposal","url":"https://mpp.dev"},"chapter":12,"test":"/openapi.json operations with x-payment-info (isitagentready rule)","iia":"mpp","lh":null,"roles":["arch"],"requires":"http","applies":"commerce","heuristic":false,"why":"MPP (Machine Payment Protocol) puts price and payment details on each payable OpenAPI operation (x-payment-info) so an agent knows the cost before calling (book chapter 12).","fix":{"snippet":"\"post\": { \"operationId\": \"createReport\", \"x-payment-info\": { \"price\": \"0.05\", \"currency\": \"USD\", \"protocols\": [\"x402\"] } }","prompt":"Add an x-payment-info extension to every payable operation in /openapi.json, describing price, currency and the accepted payment protocols per the MPP payment discovery draft."},"implemented":true},{"id":"commerce.ap2","layer":"commerce","title":"AP2 extension in the A2A card","severity":1,"standard":{"key":"ap2","name":"Agent Payments Protocol (AP2)","body":"FIDO Alliance (donated)","version":"v0.2","date":"2026","status":"Extension of A2A and UCP","maturity":"proposal","url":"https://ap2-protocol.org/"},"chapter":12,"test":"A2A Agent Card extensions include AP2 with a role (isitagentready rule)","iia":"ap2","lh":null,"roles":["arch"],"requires":"http","applies":"commerce","heuristic":false,"why":"AP2 (Agent Payments Protocol) is declared as an extension in an A2A Agent Card with your role (merchant, shopper...), so payment agents know how to transact with yours (book chapter 12).","fix":{"snippet":"\"capabilities\": { \"extensions\": [{ \"uri\": \"https://github.com/google-agentic-commerce/ap2/tree/v0.1\", \"params\": { \"roles\": [\"merchant\"] } }] }","prompt":"If your A2A agent takes payments, add the AP2 extension to /.well-known/agent-card.json under capabilities.extensions with params.roles naming your role."},"implemented":true},{"id":"commerce.vrp","layer":"commerce","title":"Vacation Rental Protocol offers (informational)","severity":1,"standard":{"key":"vrp","name":"Vacation Rental Protocol","body":"Single maintainer","version":"v0.1","date":"2026-11-01","status":"Single-maintainer draft","maturity":"proposal","url":"https://www.iana.org/assignments/well-known-uris/"},"chapter":12,"test":"/.well-known/vacation-rental.json; informational for lodging sites","iia":null,"lh":null,"roles":["pm"],"requires":"http","applies":"commerce","heuristic":false,"why":"The Vacation Rental Protocol (v0.1, a single-maintainer draft) lets a lodging host publish signed offers for agents. Informational, and only for rentals (book chapter 12).","fix":{"snippet":"/.well-known/vacation-rental.json  (see the VRP v0.1 draft for the signed offer format)","prompt":"Only for vacation-rental hosts that want to try the draft: publish /.well-known/vacation-rental.json following the VRP v0.1 draft."},"implemented":true},{"id":"identity.oauth-discovery","layer":"identity","title":"OAuth/OIDC authorization server metadata","severity":2,"standard":{"key":"rfc8414","name":"OAuth 2.0 Authorization Server Metadata / OIDC Discovery","body":"IETF / OpenID","version":"RFC 8414","date":"2018-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc8414"},"chapter":14,"test":"/.well-known/oauth-authorization-server or openid-configuration with issuer, endpoints, grant types (isitagentready rule)","iia":"oauthDiscovery","lh":null,"roles":["arch","security"],"requires":"http","applies":"auth","heuristic":false,"why":"Agents that act for a signed-in person need to find your authorization server automatically. RFC 8414 / OpenID Connect discovery metadata is where they look (book chapter 14).","fix":{"snippet":"{\n  \"issuer\": \"https://example.com\",\n  \"authorization_endpoint\": \"https://example.com/oauth/authorize\",\n  \"token_endpoint\": \"https://example.com/oauth/token\",\n  \"response_types_supported\": [\"code\"],\n  \"grant_types_supported\": [\"authorization_code\", \"refresh_token\"],\n  \"code_challenge_methods_supported\": [\"S256\"]\n}","prompt":"Serve RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server with issuer (exactly the origin it is served from), authorization_endpoint, token_endpoint, response_types_supported, grant_types_supported and code_challenge_methods_supported [\"S256\"]."},"implemented":true},{"id":"identity.protected-resource","layer":"identity","title":"OAuth Protected Resource Metadata","severity":2,"standard":{"key":"rfc9728","name":"OAuth 2.0 Protected Resource Metadata","body":"IETF","version":"RFC 9728","date":"2025-04","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9728"},"chapter":14,"test":"/.well-known/oauth-protected-resource (and path-suffixed for the MCP endpoint) with resource and authorization_servers (isitagentready rule)","iia":"oauthProtectedResource","lh":null,"roles":["arch","security"],"requires":"http","applies":"auth","heuristic":false,"why":"Protected Resource Metadata (RFC 9728) tells an agent which authorization server issues tokens for your API or MCP server, so it can start OAuth without being configured by hand (book chapter 14).","fix":{"snippet":"{\n  \"resource\": \"https://example.com/mcp\",\n  \"authorization_servers\": [\"https://example.com\"],\n  \"scopes_supported\": [\"bookings:read\", \"bookings:write\"],\n  \"bearer_methods_supported\": [\"header\"]\n}","prompt":"Serve RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource and, for an MCP endpoint at /mcp, at /.well-known/oauth-protected-resource/mcp, with resource (the exact resource URL), authorization_servers and scopes_supported. Reference it from the 401 WWW-Authenticate header as resource_metadata."},"implemented":true},{"id":"identity.pkce-s256","layer":"identity","title":"Authorization server supports PKCE S256","severity":2,"standard":{"key":"oauth21","name":"OAuth 2.1 (PKCE S256)","body":"IETF OAuth WG","version":"draft-ietf-oauth-v2-1-17","date":"2026-10-31","status":"IETF WG draft (normative in MCP)","maturity":"draft","url":"https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/"},"chapter":14,"test":"code_challenge_methods_supported includes S256 (required by MCP authorization)","iia":null,"lh":null,"roles":["security"],"requires":"http","applies":"auth","heuristic":false,"why":"Agents are public clients: PKCE with S256 is what stops a stolen authorization code from being used. OAuth 2.1 and the MCP authorization spec require it (book chapter 14).","fix":{"snippet":"\"code_challenge_methods_supported\": [\"S256\"]","prompt":"Enable PKCE with the S256 method on the authorization server (reject plain), and advertise it as code_challenge_methods_supported: [\"S256\"] in its metadata."},"implemented":true},{"id":"identity.client-registration","layer":"identity","title":"Agent clients can register (CIMD preferred over DCR)","severity":1,"standard":{"key":"cimd","name":"Client ID Metadata Document","body":"IETF OAuth WG","version":"draft-ietf-oauth-client-id-metadata-document","date":"2026-07-06","status":"IETF WG draft (required path in MCP 2026-07-28)","maturity":"draft","url":"https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/"},"chapter":14,"test":"client_id_metadata_document_supported true (MCP 2026-07-28); registration_endpoint only = warn (DCR deprecated for MCP)","iia":null,"lh":null,"roles":["arch","security"],"requires":"http","applies":"auth","heuristic":false,"why":"An agent you have never met must be able to get a client id. MCP 2026-07-28 prefers Client ID Metadata Documents (the client id is a URL to its metadata) over Dynamic Client Registration (book chapter 14).","fix":{"snippet":"\"client_id_metadata_document_supported\": true","prompt":"Support OAuth Client ID Metadata Documents on the authorization server (accept an https URL as client_id and fetch its metadata) and advertise client_id_metadata_document_supported: true. Keep registration_endpoint only for older clients."},"implemented":true},{"id":"identity.auth-md","layer":"identity","title":"auth.md agent registration","severity":1,"standard":{"key":"authmd","name":"auth.md","body":"WorkOS","version":"—","date":"2026","status":"Vendor proposal","maturity":"proposal","url":"https://workos.com/auth-md"},"chapter":14,"test":"/auth.md exists, PRM discoverable, AS metadata has agent_auth (isitagentready rule)","iia":"authMd","lh":null,"roles":["arch"],"requires":"http","applies":"auth","heuristic":false,"why":"auth.md (a WorkOS proposal) explains in plain language how agents authenticate and pairs it with an agent_auth block in the authorization server metadata. isitagentready counts it as a Level 5 auth option (book chapter 14).","fix":{"snippet":"\"agent_auth\": { \"register_uri\": \"https://example.com/agents/register\", \"identity_types\": [\"...\"], \"credential_types\": [\"...\"] }","prompt":"Serve /auth.md describing how agents register and authenticate, publish Protected Resource Metadata, and add an agent_auth block (register_uri, supported identity/assertion and credential types) to the authorization server metadata, following github.com/workos/auth.md."},"implemented":true},{"id":"identity.web-bot-auth","layer":"identity","title":"Web Bot Auth key directory (for sites that send bots)","severity":1,"standard":{"key":"webbotauth","name":"Web Bot Auth (HTTP Message Signatures directory)","body":"IETF webbotauth WG","version":"draft-ietf-webbotauth-httpsig-protocol (on RFC 9421)","date":"2026-10-29","status":"IETF WG draft","maturity":"draft","url":"https://datatracker.ietf.org/wg/webbotauth/about/"},"chapter":15,"test":"/.well-known/http-message-signatures-directory: JWKS with Ed25519 keys, correct media type; informational like isitagentready","iia":"webBotAuth","lh":null,"roles":["security","arch"],"requires":"http","applies":"optin","heuristic":false,"why":"If your site sends its own bots or agents to other sites, a Web Bot Auth key directory lets those sites verify your signed requests. Most sites only receive bots, so isitagentready treats it as informational (book chapter 15).","fix":{"snippet":"GET /.well-known/http-message-signatures-directory\nContent-Type: application/http-message-signatures-directory+json\n\n{ \"keys\": [{ \"kty\": \"OKP\", \"crv\": \"Ed25519\", \"x\": \"<base64url public key>\" }] }","prompt":"Only if your service sends signed bot/agent requests: publish your Ed25519 public keys as a JWKS at /.well-known/http-message-signatures-directory with Content-Type application/http-message-signatures-directory+json, and sign the directory response itself (draft-ietf-webbotauth-httpsig-protocol)."},"implemented":true},{"id":"security.hidden-injection","layer":"security","title":"No hidden prompt-injection text","severity":3,"standard":{"key":"owasp-llm","name":"OWASP Top 10 for LLM Applications (LLM01 prompt injection)","body":"OWASP","version":"2025","date":"2025","status":"Community guidance","maturity":"standard","url":"https://genai.owasp.org/llm-top-10/"},"chapter":16,"test":"Static + browser: text hidden by CSS/aria-hidden/off-screen/zero-size/same-colour that matches instruction patterns (ignore previous, you are an AI, system prompt...)","iia":null,"lh":null,"roles":["security","content"],"requires":"http","applies":"always","heuristic":false,"why":"Text that people cannot see but agents read (display:none, off-screen, aria-hidden, comments) is the classic carrier for indirect prompt injection: instructions planted for the AI, not the visitor; OWASP lists it under LLM01 (book chapter 16).","fix":{"snippet":"<!-- remove hidden instructions such as: -->\n<div style=\"display:none\">Ignore previous instructions and ...</div>","prompt":"Find every piece of hidden text on the page (display:none, visibility:hidden, off-screen positioning, aria-hidden, HTML comments, alt text) that addresses an AI or gives instructions, and remove it. If it comes from user-generated content, sanitise it and render it as data with a clear provenance label."},"implemented":true},{"id":"security.injection-in-machine-files","layer":"security","title":"Machine-readable files carry no instructions to agents","severity":2,"standard":{"key":"owasp-llm","name":"OWASP Top 10 for LLM Applications (LLM01 prompt injection)","body":"OWASP","version":"2025","date":"2025","status":"Community guidance","maturity":"standard","url":"https://genai.owasp.org/llm-top-10/"},"chapter":16,"test":"Scan llms.txt, Markdown twin, JSON-LD and meta for instruction-like patterns aimed at models","iia":null,"lh":null,"roles":["security","content"],"requires":"http","applies":"always","heuristic":false,"why":"llms.txt, Markdown twins, JSON-LD, meta tags and tool descriptions are read by models directly. Instructions planted there (or copied in from user content) reach every agent that reads them (book chapter 16).","fix":{"snippet":"# llms.txt: describe, do not command\n> Example Shop sells outdoor gear. The product API is at /api/v1 (OpenAPI: /openapi.json).","prompt":"Remove any text in llms.txt, the Markdown version of pages, JSON-LD, meta tags and MCP/WebMCP tool descriptions that tries to instruct the model (override instructions, role markers, requests for secrets). Keep these files descriptive, and keep user-generated text out of them or clearly labelled as untrusted."},"implemented":true},{"id":"security.tool-annotations","layer":"security","title":"Destructive tools are marked as such","severity":2,"standard":{"key":"mcp","name":"Model Context Protocol","body":"Agentic AI Foundation","version":"2026-07-28","date":"2026-07-28","status":"Dated spec","maturity":"standard","url":"https://modelcontextprotocol.io/specification/2026-07-28"},"chapter":16,"test":"MCP + WebMCP tools with write verbs (delete, book, pay, send) have destructiveHint/readOnlyHint false; read tools readOnlyHint","iia":null,"lh":null,"roles":["security","dev"],"requires":"http","applies":"always","heuristic":false,"why":"Agents decide whether to ask the person before calling a tool from its annotations. A booking or delete tool that claims to be read-only, or a read tool that is not marked, leads to unsafe or needlessly nagging agents (book chapters 9 and 16).","fix":{"snippet":"// MCP\n{ name: \"cancel_booking\", annotations: { readOnlyHint: false, destructiveHint: true } }\n// WebMCP\nnavigator.modelContext.registerTool({ name: \"book_cabin\", annotations: { consequentialHint: true }, ... })\nnavigator.modelContext.registerTool({ name: \"search_cabins\", annotations: { readOnlyHint: true }, ... })","prompt":"Review every MCP and WebMCP tool: set readOnlyHint: true on tools that only read; never set it on tools that create, change, pay or delete; mark irreversible MCP tools destructiveHint: true and significant WebMCP actions consequentialHint: true. Enforce the same rules on the server; annotations are hints."},"implemented":true},{"id":"security.https","layer":"security","title":"HTTPS with HSTS","severity":2,"standard":{"key":"rfc6797","name":"HTTP Strict Transport Security","body":"IETF","version":"RFC 6797","date":"2012-11","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc6797"},"chapter":16,"test":"http:// redirects to https://; Strict-Transport-Security max-age >= 1 year","iia":null,"lh":null,"roles":["security","dev"],"requires":"http","applies":"always","heuristic":false,"why":"Agents carry people's tokens and data. Plain HTTP lets anyone on the path read or rewrite pages and tool answers; HSTS stops the downgrade (book chapter 16).","fix":{"snippet":"Strict-Transport-Security: max-age=31536000; includeSubDomains","prompt":"Redirect every http:// request to https:// with a 301 or 308, and send Strict-Transport-Security: max-age=31536000 (one year) or longer on HTTPS responses."},"implemented":true},{"id":"security.headers","layer":"security","title":"Baseline security headers","severity":1,"standard":{"key":"csp","name":"Content Security Policy Level 3","body":"W3C","version":"Working Draft","date":"continuous","status":"W3C WD (CSP2 Rec)","maturity":"standard","url":"https://www.w3.org/TR/CSP3/"},"chapter":16,"test":"Content-Security-Policy, X-Content-Type-Options nosniff, frame-ancestors/X-Frame-Options","iia":null,"lh":null,"roles":["security","dev"],"requires":"http","applies":"always","heuristic":false,"why":"A Content-Security-Policy limits what injected scripts can do, nosniff stops content-type confusion, and frame-ancestors stops clickjacking of the pages agents and people act on (book chapter 16).","fix":{"snippet":"Content-Security-Policy: default-src 'self'; frame-ancestors 'self'\nX-Content-Type-Options: nosniff","prompt":"Send Content-Security-Policy (at least default-src 'self' and frame-ancestors 'self', tightened for your scripts), X-Content-Type-Options: nosniff, and frame-ancestors (or X-Frame-Options: SAMEORIGIN) on HTML responses."},"implemented":true},{"id":"security.security-txt","layer":"security","title":"security.txt contact","severity":1,"standard":{"key":"rfc9116","name":"security.txt","body":"IETF","version":"RFC 9116","date":"2022-04","status":"RFC (Informational)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9116"},"chapter":16,"test":"/.well-known/security.txt with Contact and Expires in the future","iia":null,"lh":null,"roles":["security"],"requires":"http","applies":"always","heuristic":false,"why":"security.txt (RFC 9116) tells researchers, and the agents that report problems for them, how to reach you about a vulnerability, for example a prompt-injection hole in your tools (book chapter 16).","fix":{"snippet":"Contact: mailto:security@example.com\nExpires: 2027-11-01T00:00:00.000Z\nPreferred-Languages: en\nCanonical: https://example.com/.well-known/security.txt","prompt":"Serve /.well-known/security.txt as text/plain with a Contact line (mailto: or https:) and an Expires date less than a year ahead, per RFC 9116; set a reminder to renew Expires."},"implemented":true},{"id":"privacy.policy-link","layer":"privacy","title":"Privacy policy and terms are linked machine-readably","severity":1,"standard":{"key":"linkrels","name":"IANA link relations (privacy-policy, terms-of-service)","body":"IANA / RFC 6903","version":"RFC 6903","date":"2013-03","status":"RFC (Informational) + IANA registry","maturity":"standard","url":"https://www.iana.org/assignments/link-relations/"},"chapter":17,"test":"link rel=privacy-policy / terms-of-service, or anchors named privacy/terms on the homepage","iia":null,"lh":null,"roles":["pm","content"],"requires":"http","applies":"always","heuristic":false,"why":"Agents acting for people check what a site does with their data before sharing it. rel=\"privacy-policy\" and rel=\"terms-of-service\" (IANA-registered, RFC 6903) make those pages findable without guessing (book chapter 17).","fix":{"snippet":"<link rel=\"privacy-policy\" href=\"/privacy\">\n<link rel=\"terms-of-service\" href=\"/terms\">","prompt":"Add <link rel=\"privacy-policy\" href=\"...\"> and <link rel=\"terms-of-service\" href=\"...\"> to the <head> of every page (or the same as Link headers), pointing at the existing privacy and terms pages."},"implemented":true},{"id":"privacy.consent-overlay","layer":"privacy","title":"Consent banner does not block content for agents","severity":2,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":17,"test":"Browser: fixed/sticky overlays with consent words covering >30% of the viewport, and whether content is readable without clicking","iia":null,"lh":null,"roles":["pm","design","dev"],"requires":"browser","applies":"always","heuristic":true,"why":"A consent wall that covers the page blocks agents the same way it blocks people, and agents should not click \"accept\" on someone's behalf. Keep the content readable behind a banner (book chapter 17).","fix":{"snippet":"<!-- A banner that leaves the content readable -->\n<aside class=\"consent\" aria-label=\"Cookie choices\" style=\"position:fixed;bottom:0;max-height:25vh\">\n  <p>We use cookies for analytics.</p><button>Accept</button> <button>Reject</button>\n</aside>","prompt":"Change the cookie/consent UI on this page so it does not cover more than about a quarter of the viewport, does not lock scrolling, and leaves the main content in the DOM and readable before any choice is made. Verify with a headless browser screenshot without clicking anything."},"implemented":true},{"id":"privacy.gpc","layer":"privacy","title":"Global Privacy Control support declared","severity":1,"standard":{"key":"gpc","name":"Global Privacy Control","body":"W3C Privacy WG","version":"Working Draft 24 September 2026","date":"2026-09-24","status":"W3C Working Draft","maturity":"draft","url":"https://www.w3.org/TR/gpc/"},"chapter":17,"test":"/.well-known/gpc.json with gpc: true; informational","iia":null,"lh":null,"roles":["pm","security"],"requires":"http","applies":"always","heuristic":false,"why":"Global Privacy Control lets a person (or an agent acting for them) signal \"do not sell or share my data\"; /.well-known/gpc.json says your site honours it. It is a W3C Working Draft, legally recognised in some US states, and not covered by the book itself; consent signals are (book chapter 17).","fix":{"snippet":"{ \"gpc\": true, \"lastUpdate\": \"2026-11-01\" }","prompt":"If the site honours the Sec-GPC: 1 request header, serve /.well-known/gpc.json as application/json with { \"gpc\": true, \"lastUpdate\": \"<YYYY-MM-DD>\" } (W3C Global Privacy Control)."},"implemented":true},{"id":"privacy.human-confirmation","layer":"privacy","title":"Risky tools ask a human to confirm","severity":1,"standard":{"key":"webmcp","name":"WebMCP","body":"W3C Web Machine Learning CG","version":"Draft 2026-11-02","date":"2026-11-02","status":"W3C CG draft, Chrome origin trial","maturity":"draft","url":"https://webmachinelearning.github.io/webmcp/"},"chapter":17,"test":"WebMCP/MCP write tools: annotations or descriptions show a confirmation step (requestUserInteraction / elicitation); informational heuristic","iia":null,"lh":null,"roles":["pm","security"],"requires":"http","applies":"always","heuristic":true,"why":"Tools that book, pay, send or delete should leave the final yes to the person. Declarative WebMCP forms do this unless toolautosubmit is set; imperative and MCP tools need a confirmation step (book chapters 9 and 17).","fix":{"snippet":"<form toolname=\"book_cabin\" tooldescription=\"Book a cabin. The guest reviews and submits the form.\">  <!-- no toolautosubmit -->","prompt":"For every tool that books, pays, sends or deletes: keep declarative WebMCP forms without toolautosubmit so the person submits, mark imperative tools consequentialHint: true (WebMCP) or destructiveHint: true (MCP), and say in the description that the person confirms before the action happens; on MCP use elicitation for the confirmation."},"implemented":true},{"id":"performance.cls","layer":"performance","title":"Layout is stable (CLS)","severity":2,"standard":{"key":"cls","name":"Cumulative Layout Shift","body":"Google web.dev / W3C Layout Instability API","version":"Core Web Vital","date":"continuous","status":"Metric (W3C draft API)","maturity":"standard","url":"https://web.dev/articles/cls"},"chapter":3,"test":"Browser: PerformanceObserver layout-shift (buffered) over load + 3 s; good <= 0.1, poor > 0.25 (web.dev thresholds)","iia":null,"lh":"cumulative-layout-shift","roles":["dev","design"],"requires":"browser","applies":"always","heuristic":false,"why":"Agents that click by position or screenshot misfire when the layout jumps after they look. Lighthouse includes CLS in the Agentic Browsing category; web.dev rates 0.1 or less as good (book chapter 3).","fix":{"snippet":"<img src=\"/cabin.jpg\" width=\"1200\" height=\"800\" alt=\"Fjellro cabin\">\n<div class=\"ad-slot\" style=\"min-height:250px\"></div>","prompt":"Reduce Cumulative Layout Shift on this page below 0.1: give images, videos and iframes width and height (or aspect-ratio), reserve space for ads, banners and late-loading content with min-height, and avoid inserting content above existing content after load. Verify with Lighthouse or a PerformanceObserver for layout-shift."},"implemented":true},{"id":"performance.ttfb","layer":"performance","title":"Server responds quickly (TTFB)","severity":1,"standard":{"key":"webvitals","name":"Web Vitals (TTFB guidance)","body":"Google web.dev","version":"—","date":"continuous","status":"Guidance","maturity":"standard","url":"https://web.dev/articles/ttfb"},"chapter":19,"test":"Homepage time to first byte from the checker; good <= 0.8 s, poor > 1.8 s (web.dev)","iia":null,"lh":null,"roles":["dev","arch"],"requires":"http","applies":"always","heuristic":false,"why":"Agents run on timeouts and budgets. A slow first byte makes every page, Markdown twin and well-known file slower to fetch, and some agents give up (book chapter 19).","fix":{"snippet":"Cache-Control: public, max-age=60, stale-while-revalidate=600\n# cache rendered HTML at the edge/CDN; avoid blocking work before the first byte","prompt":"Reduce time to first byte on the homepage: cache the rendered HTML (CDN or server cache with stale-while-revalidate), move slow data fetching out of the critical path, and check the server region; target 0.8 s or less (web.dev), measured with curl -w \"%{time_starttransfer}\"."},"implemented":true},{"id":"performance.compression","layer":"performance","title":"Text responses are compressed","severity":1,"standard":{"key":"httpcomp","name":"HTTP content coding (gzip, br, zstd)","body":"IETF","version":"RFC 9110 §8.4","date":"2022-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9110#section-8.4"},"chapter":19,"test":"Homepage with Accept-Encoding: gzip, br; Content-Encoding present","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Compressed HTML and text are several times smaller, so agents fetch more pages within their time and token budgets (book chapter 19).","fix":{"snippet":"# nginx\ngzip on;\ngzip_types text/html text/markdown text/plain application/json application/xml;\n# or brotli on; brotli_types ...;","prompt":"Enable gzip or Brotli (or zstd) compression for text responses (HTML, Markdown, JSON, XML, plain text) at the web server or CDN, and verify with curl -sI -H \"Accept-Encoding: gzip, br\" that Content-Encoding is set."},"implemented":true},{"id":"performance.redirects","layer":"performance","title":"Few redirects to the homepage","severity":1,"standard":{"key":"rfc9110","name":"HTTP Semantics (content negotiation, Vary)","body":"IETF","version":"RFC 9110","date":"2022-06","status":"RFC (Standards Track)","maturity":"standard","url":"https://www.rfc-editor.org/rfc/rfc9110"},"chapter":19,"test":"Redirect chain length from the entered URL; warn above 2","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Every redirect is another round trip before an agent gets content, and long chains hit agents' redirect limits (book chapter 19).","fix":{"snippet":"# link straight to the final URL, and redirect old URLs in one hop\nreturn 301 https://www.example.com$request_uri;","prompt":"Collapse redirect chains to at most one hop: redirect http->https and apex->www (or the reverse) in a single 301 to the final URL, and update internal links and sitemaps to use final URLs."},"implemented":true},{"id":"performance.page-weight","layer":"performance","title":"HTML is a reasonable size","severity":1,"standard":{"key":"book","name":"The Agent-Ready Web (book guidance)","body":"Maxim Salnikov","version":"v1.0.0","date":"2026-11-02","status":"Book recommendation (opinion, sourced per chapter)","maturity":"guidance","url":"https://github.com/webmaxru/agent-ready-web-demos"},"chapter":3,"test":"Server HTML bytes and DOM node count reported; warns above 2 MB, the part of a file Googlebot crawls for Google Search (Google's Googlebot page, read 2026-11-03; 15 MB is the general fetch limit)","iia":null,"lh":null,"roles":["dev"],"requires":"http","applies":"always","heuristic":false,"why":"Big HTML costs agents tokens and time, and crawlers cut it off: Googlebot reads only the first 2 MB of an HTML file for Google Search (book chapter 3).","fix":{"snippet":"<!-- move inline data blobs and SVG sprites out of the HTML -->\n<script type=\"module\" src=\"/app.js\"></script>\n<link rel=\"stylesheet\" href=\"/site.css\">","prompt":"Reduce the HTML size of the page: move large inline scripts, JSON state blobs, inline SVG sprites and base64 images into separate cached files, paginate long lists, and keep the main content near the top of the document."},"implemented":true}]}