seo-agent-readiness (M22 — Agent-readiness)

Google's Optimizing your website for generative AI features guide points to "agent-friendly website best practices" (web.dev Build agent-friendly websites): agents drive a page through its accessibility tree, so unnamed, non-semantic, or script-only controls are invisible to them. This module checks the statically checkable subset and names the rest. Alt text is M9, anchor-text quality is M10, rendering is M4 — reference them, never re-emit them.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read parsed (anchors[], forms, iframes, scripts[], landmarks) from <run_dir>/pages/<slug>.json, preferring parsed_rendered when render.used is not none; Grep pages/<slug>.html (or .rendered.html) for the offending elements as verbatim evidence. Deterministic findings already emitted by audit.mjs are listed in <run_dir>/findings.deterministic.json — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" and use the printed snapshot path.

Audits

Semantic controls — interactive behavior on div/span (onclick, role="button", tabindex + handler) instead of <button> / <a href>; count against total controls.
Named buttons — <button>, role="button", input[type=button|submit] with no text content, aria-label, aria-labelledby, title, or value.
Named links — <a href> whose accessible name is empty (icon-only, image without alt inside). Generic-vs-descriptive anchor wording stays in M10.
Labeled form controls — input/select/textarea without <label for>, a wrapping <label>, aria-label, or aria-labelledby (a placeholder alone does not count).
href="javascript:" (and href="#" carrying handlers) — navigation that only works through script.
Primary content in an iframe — the main article/product content lives inside <iframe>; agents and crawlers see only the shell.
WebMCP — navigator.modelContext in inline/linked scripts: report presence as informational. It is a W3C Community Group draft (2026-04-23) in a Chrome origin trial — never a recommendation.
Not checkable statically — cursor: pointer, target size (web.dev's > 8px² guidance), ghost overlays / off-screen click blockers. List them explicitly as not_checkable_static; Tier 1 covers them through Lighthouse's "Agentic browsing" category (M150+).