moai-ref-seo

name	moai-ref-seo
description	Search-visibility and crawlability reference for web output: canonical URL discipline, per-page title and meta description uniqueness, robots.txt and sitemap.xml as host-derived artifacts, JSON-LD structured data with entity consistency, and the document-semantics rules that decide whether a machine can read a page at all. Agent-extending skill that amplifies web-output implementation and pre-ship review with production-grade indexing and structured-data patterns. NOT for: keyboard operability, visible focus indicators, and form-control labeling (accessibility owns those; delegated to the accessibility surface); generative-engine optimization, deliberately excluded as insufficiently settled; visual polish and interface detail (see moai-ref-ui-polish); API contract design (see moai-ref-api-patterns); security headers and hardening (see moai-ref-owasp-checklist and moai-ref-secops).
when_to_use	Use when a project emits pages that a search engine or an automated reader will fetch: choosing canonical addresses, writing per-page metadata, emitting robots.txt or sitemap.xml, adding or reviewing JSON-LD, keeping entity naming consistent between the page and its serialized data, or auditing heading structure, image alt text, anchor text, and in-page fragment targets before shipping. Guidance stays at the protocol and output layer — addresses, response headers, markup, serialized data — so it applies to any stack that produces HTML.
user-invocable	false
metadata	{"version":"1.0.0","category":"domain","status":"active","updated":"2026-08-01","tags":"seo, canonical, structured-data, json-ld, sitemap, robots, metadata, crawlability, reference"}
progressive_disclosure	{"enabled":true,"level1_tokens":100,"level2_tokens":3000}

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 element has a non-empty alt attribute, or an empty one paired with an explicit decorative marker	Meaning locked inside a binary the parser cannot open
Anchor text names its destination	Read each link's text with the surrounding sentence hidden, then ask where it goes	Instruction-shaped link text carries no signal about the target
Fragment targets resolve	For each in-page fragment link, confirm a matching identifier exists in the same rendered output	Navigation that silently lands nowhere

Derive alt text from what the image depicts, never from its file name. Where an image genuinely adds nothing a reader needs, mark it decorative on purpose instead of inventing a description for it.

Identity and Canonical Address