/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"

# MoAI Extension: Progressive Disclosure
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

One resource, one address; everything else redirects to it.

| Decision | Rule | |---|---| | Which address is canonical | Pick one form per resource and declare it. The declared value must equal the address actually served | | Trailing-slash variants | Choose one form and redirect the other permanently. Serving both splits one resource across two addresses | | Case, query parameters, tracking suffixes | Normalize before serving. A parameter that does not change the response must not mint a second address | | Parameterized routes | Build the declared value from the resolved parameters, never from a fixed string shared across the whole route | | Retiring an address | Redirect permanently from the old form and update the declaration in the same change |

A declaration pointing at an address that redirects, errors, or serves different content is worse than no declaration at all: it actively steers the reader away from the page it appears on.

Per-Page Metadata

| Field | Rule | Recurring defect | |---|---|---| | `title` | Unique per page, composed from a page-specific part plus a stable identifier for the site | The scaffold's default survives to production on every route | | meta description | Unique per page, written for a person reading a result snippet | One description copied everywhere, or prose that describes nothing | | Indexing directive | Set a default for public pages, then narrow per page class. Authenticated areas and internal tools are excluded deliberately, not merely left unlinked | A private surface gets indexed because nothing declared otherwise | | Social preview fields | Present and absolute. A relative address in a field a third party fetches resolves against the wrong host | A share card that renders blank off-site |

Length budgets are a decision rule, not a constant: draft the text, observe where the consuming surfac