` found or no headings at all **Why it matters:** AI agents use headings to build a content outline and determine topic hierarchy. A clear h1→h2→h3 structure helps AI systems extract and summarize your content accurately. ### Fix Workflow 1. **Audit current headings:** ```bash curl -s https://example.com | grep -oE ']*>.*?' | head -30 ``` 2. **Fix the hierarchy** — ensure exactly one `

` and sequential levels: ```html

Page Title — One Per Page

Main Section

Subsection

Another Section

Subsection

Detail

``` 3. **Common fixes:** - Multiple `

` tags → keep one, demote others to `

` - `

` → `

` skip → add intermediate `

` - Empty headings → add meaningful text or remove the tag - Logo in `

` → move logo out, use text `

` for page title 4. Verify — re-check that heading levels are sequential. See [references/gotchas.md](references/gotchas.md) for common heading hierarchy pitfalls (component-level `

`, level resets). References: - [MDN Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements) - [W3C Using h1-h6 to identify headings](https://www.w3.org/WAI/WCAG22/Techniques/html/H42) --- ## Checkpoint 3.3: Semantic HTML Elements (20 pts) What the scanner checks: Presence of 5 semantic landmark elements: `
`, `
`, `
`, `
` or `
`, `
`. 4 points each. Scoring: - 20 pts (pass) — All 5 elements present - 12–16 pts (partial) — 3–4 elements present - 0–8 pts (fail) — Fewer than 3 elements Why it matters: AI agents navigate pages using the accessibility tree, not visual layout. Semantic elements like `
`, `
`, and `
` provide structural meaning that AI systems rely on to parse content. ### Fix Workflow 1. Check which elements are present: ```bash curl -s https://example.com | grep -oE '<(header|nav|main|article|section|footer)[\s>]' | sort -u ``` 2. Implement the full semantic structure: ```html

Home About Contact

Page Title

Introduction

Content here...

Details

More content...

Privacy Policy Terms of Service

© 2026 Example Inc.

``` 3. Replace `
` wrappers with semantic equivalents: - `
` → `
` - `
` → `
` - `
` → `
` - `
` → `
` - `
` → `
` See [references/semantic-html-guide.md](references/semantic-html-guide.md) for the complete element reference and `
` vs `
` guidance. References: - [MDN Semantics in HTML](https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantics_in_html) - [W3C HTML5 Document Sections](https://www.w3.org/TR/html52/sections.html) --- ## Checkpoint 3.4: ARIA Landmarks (10 pts) What the scanner checks: - Implicit landmarks from semantic elements (`
` → main, `
` → navigation, `
` → banner, `
` → contentinfo, `
` → complementary) - Explicit ARIA roles (`role="navigation"`, `role="main"`, etc.) - Additive ARIA attributes: `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-live`, `aria-expanded`, `aria-current`, `aria-hidden` Scoring: - 10 pts — 3+ landmark regions AND at least 1 additive ARIA attribute - 7 pts — 3+ landmark regions, no additive ARIA - 5 pts — 1+ landmark AND 1+ additive ARIA attribute - 3 pts — Any landmark or ARIA attribute present - 0 pts — No landmarks or ARIA attributes found Why it matters: ARIA landmarks help AI agents identify page regions (navigation, main content, footer). This is the same API used by screen readers and is increasingly used by AI browsing agents. ### Fix Workflow 1. Use semantic HTML first — these provide implicit landmarks without extra attributes: ```html

``` 2. Add ARIA attributes for disambiguation and state: ```html
Home About

Privacy

``` 3. Do NOT add redundant roles to semantic elements: ```html

``` 4. Verify — check for 3+ landmark types plus at least one `aria-` attribute. References: - [W3C Landmarks Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/) - [MDN ARIA Roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) --- ## Checkpoint 3.5: Image Alt Text (15 pts) What the scanner checks: All `` tags have non-empty `alt` attributes. Score = (images with alt / total images) 15. No images on page = full score. Why it matters: AI agents cannot see images. Alt text is the only way for AI systems to understand image content, context, and relevance to the surrounding text. ### Fix Workflow 1. Find images missing alt text: ```bash curl -s https://example.com | grep -oE ']>' | grep -v 'alt=' ``` 2. Add appropriate alt text: ```html Email us ``` 3. Alt text guidelines: - Be specific and concise (under 125 characters) - Describe the content and function, not appearance - Don't start with "Image of..." or "Picture of..." - For charts/graphs, describe the key data point or trend - For decorative images, use `alt=""` (empty, not missing) References: - [WCAG Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) - [MDN img alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt) --- ## Checkpoint 3.6: Language Attribute (5 pts) What the scanner checks: `` tag has a `lang` attribute with a valid BCP 47 language code. Scoring: - 5 pts — Valid BCP 47 code (e.g., `en`, `nl`, `en-US`) - 2 pts — `lang` attribute present but invalid value - 0 pts — No `lang` attribute Why it matters: The `lang` attribute tells AI agents what language your content is in, enabling correct text processing, translation, and language-specific understanding. ### Fix Workflow 1. Check current state: ```bash curl -s https://example.com | grep -oE ']lang="[^"]"' ``` 2. Add or fix the lang attribute: ```html ``` 3. For multilingual content, use `lang` on specific elements: ```html
This is English text.

Ceci est en français.
``` References: - [MDN lang attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) - [W3C Declaring language in HTML](https://www.w3.org/International/questions/qa-html-language-declarations) --- ## Checkpoint 3.7: Descriptive Link Texts (10 pts) What the scanner checks: Samples up to 50 links. Flags generic text: "click here", "read more", "learn more", "here", "link", "more", "details", "info", "more details". Score = (descriptive links / total sampled) 10. Why it matters: AI agents use link text to understand navigation and discover related content. Generic text like "click here" provides no context about where the link leads. ### Fix Workflow 1. Find generic links: ```bash curl -s https://example.com | grep -oiE ']>([^<])<\/a>' | grep -iE '>(click here|read more|learn more|here|link|more|details|info|more details)<' ``` 2. Replace with descriptive text: ```html Click here Read more Learn more To sign up, click here. View pricing plans Read our AI trends analysis Explore the documentation Create your free account. ``` 3. Patterns for common cases: - Blog posts: "Read [article title]" instead of "Read more" - CTAs: describe the action — "Start free trial", "Download the report" - Navigation: use the destination name — "About us", "API documentation" - Lists: "[Item name] details" instead of "Details" 4. For "Read more" in card layouts, make the entire card clickable or use `aria-label`: ```html Read AI trends analysis Read more ``` References: - [WCAG Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) - [MDN Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) --- ## Checkpoint 3.8: Question-Based Headings (10 pts) What the scanner checks: H2 headings that use question format — ending with `?` or starting with a question word (how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall). Scoring: - 10 pts — 2+ question-format H2 headings, or (3 or fewer total H2s and at least 30% are questions) - 5 pts — At least 1 question-format H2 - 0 pts — H2 headings exist but none are questions - Skip (0/0) — No H2 headings present Why it matters: 78.4% of ChatGPT citations come from pages with question-based H2 headings. Question headings match how users query AI systems, making your content more likely to be selected as a source for AI-generated answers. ### Fix Workflow 1. Audit current H2 headings: ```bash curl -s https://example.com | grep -oE ']>.?

' ``` 2. **Rewrite H2 headings as questions:** ```html

AI Agent Readiness

Content Discovery by AI Systems

What Is AI Agent Readiness?

How Do AI Systems Discover Your Content?

Why Does Structured Data Matter for AI?

``` 3. **Recognized question starters:** how, what, why, when, where, which, who, can, does, do, is, are, will, should, would, could, shall — or any heading ending with `?`. 4. **Not all headings need to be questions** — aim for 2+ question H2s on pages with 4+ H2s, or 30%+ on pages with 3 or fewer. 5. **Pair with FAQPage schema** (checkpoint 2.7) for maximum AI citation potential — match H2 questions with JSON-LD Question/Answer pairs. 6. **Verify:** ```bash curl -s https://example.com | grep -oE ']*>.*?

`s with `

`, `

`, sequential heading levels (no h1→h3 skip), non-empty heading text. Scoring: - 20 pts — Single `

`, no level skips, all headings have text - 15 pts — Good hierarchy but some headings have empty text - 10 pts — Single `

` present but levels are skipped - 5 pts — Multiple `

` tags - 0 pts — No `

` and sequential levels: ```html

Page Title — One Per Page

Main Section

Subsection

Subsection

Another Section

Subsection

Detail

` tags → keep one, demote others to `

` - `

` → `

` skip → add intermediate `

` - Empty headings → add meaningful text or remove the tag - Logo in `

` → move logo out, use text `

` for page title 4. Verify — re-check that heading levels are sequential. See [references/gotchas.md](references/gotchas.md) for common heading hierarchy pitfalls (component-level `

AI Agent Readiness

Content Discovery by AI Systems

What Is AI Agent Readiness?

How Do AI Systems Discover Your Content?

Why Does Structured Data Matter for AI?

`, sequential heading levels (no h1→h3 skip), non-empty heading text. **Scoring:** - 20 pts — Single `

`, no level skips, all headings have text - 15 pts — Good hierarchy but some headings have empty text - 10 pts — Single `

` present but levels are skipped - 5 pts — Multiple `

` tags - 0 pts — No `

` and sequential levels: ```html

Page Title — One Per Page

Main Section

Subsection

Subsection

Another Section

Subsection

Detail

` tags → keep one, demote others to `

` - `

` → `

` skip → add intermediate `

` - Empty headings → add meaningful text or remove the tag - Logo in `

` → move logo out, use text `

` for page title 4. **Verify** — re-check that heading levels are sequential. See [references/gotchas.md](references/gotchas.md) for common heading hierarchy pitfalls (component-level `

AI Agent Readiness

Content Discovery by AI Systems

What Is AI Agent Readiness?

How Do AI Systems Discover Your Content?

Why Does Structured Data Matter for AI?

`, sequential heading levels (no h1→h3 skip), non-empty heading text. Scoring: - 20 pts — Single `

` for page title 4. Verify — re-check that heading levels are sequential. See [references/gotchas.md](references/gotchas.md) for common heading hierarchy pitfalls (component-level `