seo-headings-structure (M7c)

A clean, single-rooted heading tree and proper semantic landmarks make a page's outline machine-readable — the same structure that AI engines use to extract answer blocks and that search engines use to understand content scope. Schema/entity context: references/schema-tier1.md.

Audits

Working from the PageSnapshot (rendered_dom if present, else raw_html):

1. Single H1: exactly one <h1> per page. Zero H1s, or multiple H1s, are both findings.
2. No skipped levels: nesting descends one level at a time (an <h2> may be followed by <h3>, not directly by <h4>). Build the outline and flag any jump.
3. Descriptive text: each heading names its section in human terms — flag empty headings, headings used purely for visual styling, and generic placeholders ("Section 1", "Welcome").
4. Semantic landmarks: detect <main>, <article>, <section>, <nav>, <header>, <footer>; flag when headings live inside non-semantic <div> soup or when more than one <main> exists.
5. Outline ↔ landmark agreement: sectioning elements should carry their own heading; orphan landmarks and headings outside any landmark are findings.

Good heading structure feeds AI answer-block extraction: clear H2/H3 boundaries map to candidate quotable passages.

Fixes

• Heading-level restructuring — re-leveling H2-H6 to remove skips or to nest correctly (fixable: proposed). This alters the visual hierarchy, so it requires per-item accept; emit a fix_preview diff, never an auto-write.
• Add a single missing H1 — when the page has no H1, propose one sourced from the populated <title>/og:title or the obvious page-title element (fixable: proposed, per-item accept — adding a visible heading is editorial). Never fabricate H1 text from thin content; ask the user if the source is ambiguous.
• Wrap in semantic landmarks — recommending <main>/<article> adoption is advisory (structural refactor the tool does not write).