moai-ref-seo

# Search Visibility Reference ## Target Agents - `manager-develop` — applies these rules while implementing pages, routes, and serialized metadata output - `/moai review` — pre-ship indexing review surface; equivalently available as a per-spawn `Agent(general-purpose)` with web-output review instructions ## Core Principle A page is indexed on what a machine can fetch and parse, not on what a person sees once everything has finished loading. Two failures dominate everything below: the same content reachable at more than one address, and a claim asserted in serialized data that nothing on the page corroborates. Every rule here is a specialization of one of those two. Figures that engines publish and then quietly revise — truncation widths, ranking weights, crawl allowances — are deliberately absent. Where a limit matters, this reference gives the decision rule and the measurement to take, so the guidance outlives the figure. ## Document Semantics The structure a parser reads before it reaches any content signal. Cheapest class of defect to introduce, and the cheapest to detect. | Rule | How to check it | Failure it prevents | |---|---|---| | Exactly one `h1` per document | Count `h1` elements in the rendered output of each page | Competing topic signals leave the subject ambiguous | | No skipped heading level | Walk the heading sequence; each descent moves by at most one level | Section nesting a parser cannot reconstruct | | Every image carries `alt` text | Each image ...