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 surface truncates it, then cut to what you observed. Placeholder detection belongs in the pre-ship check — scan the emitted output for the scaffold's own default strings and fail when one survives.

Structured Data

Serialized JSON-LD states what a page is. Its one hard constraint is correspondence with the visible page.

Decision	Rule
Which types to emit	Derive them from the page's actual role — an organization, a product, a piece of software, a place, an article. Emit the site-level type everywhere and the page-specific type only where it applies
Required fields	Each type has a small mandatory core. Emit that core completely rather than emitting several types partially
Addresses inside the data	Absolute, and resolving. Relative values are discarded without a warning
Several entities on one page	Emit one block holding all of them, give each a stable identifier, and cross-reference by identifier instead of nesting duplicate copies
Placement	Keep each type on the page it describes. A type repeated site-wide dilutes rather than reinforces

Mirroring rule — every claim in the serialized data needs a visible counterpart on the same page. A name, a description, a rating, or a question-and-answer pair that exists only in the markup is an assertion the reader cannot check, and it is now scored as a negative signal rather than a neutral one.

Entity Consistency

Structured data identifies an entity. Consistency is what makes that identity hold across independent sources.

Surface	Requirement
Canonical name	One spelling, one casing, one suffix — the same in the serialized data, the page copy, and the headings
Owned profile links	Restricted to accounts this entity itself administers, each confirmed to resolve rather than bounce to a sign-in wall
Contact details	Name, address, and contact number identical across the serialized data, the visible page, and any third-party listings
Omission over approximation	A field with no accurate value is left out. A partial or invented one fragments the identity it was meant to establish

Formatting differences that read as trivial to a person are distinct values to a matcher. Fix one format per field and hold it everywhere the entity appears.

Host-Derived Crawl Artifacts

robots.txt and sitemap.xml are output the site serves, not files carried between environments.

Artifact	Rule
robots.txt	Derive the absolute addresses it contains from the incoming request's host, so every environment serves a correct description of itself
sitemap.xml	Enumerate the addresses actually served. An entry for a removed page spends crawl attempts and signals staleness
Staying in sync	Adding or removing a route updates the enumeration in the same change. A hand-maintained list drifts within one iteration
Per-entry hints	Freshness and weighting hints attached to entries are advisory and widely discounted. Correctness of the address set matters far more than the hints on it

Hardcoding one environment's host into either artifact is the defect that keeps recurring, because it passes review while being correct in exactly one place.

Delivery Chokepoints

Concern	Rule
Response headers	Apply them at a single wrapping point every response passes through, error and redirect responses included. A header set only on the success path is missing exactly when a reader is most likely to be misled
Rendering mode	Treat "what does a reader receive in the first response?" as a question the project answers explicitly. Content that appears only after client-side work is content a non-executing reader may never see
Redirect chains	One hop to the canonical address. Each extra hop is another opportunity to lose the reader
Third-party origins	Connection hints for origins the page depends on belong ahead of the resources that use them. Measure the effect on this project's own pages rather than assuming one

Common Rationalizations

Rationalization	Reality
"The framework already sets sensible metadata defaults"	A default is identical on every route by construction. Uniqueness is the entire purpose of the field, so it cannot be inherited.
"Both address forms serve the same page, so it makes no difference"	Two addresses serving one resource are two resources to a crawler. Which one survives is guessed unless a declaration and a redirect settle it deliberately.
"Serialized data may say more than the page shows — it is extra context"	Data with no visible counterpart is an unverifiable claim, and it is scored as one.
"Heading structure and alt text belong to accessibility, not to indexing"	They are the parse structure a machine uses to segment and describe a page. Sharing a mechanism with accessibility is not a reason to defer them.
"The address enumeration can be updated in a follow-up change"	A list maintained apart from the routes drifts immediately and then silently. Deriving it from the routes is the only version that stays true.
"The staging host in the artifact is fine, we swap it at deploy"	A hardcoded host is right in one environment and wrong in every other, including the one that gets indexed.

Red Flags

• Two or more h1 elements on one page, or a heading sequence that skips a level
• A canonical declaration that does not match the address actually serving the page
• The same title or meta description reused across more than one route
• An image with no alt attribute, or alt text that repeats the file name
• Link text that reads as an instruction instead of naming a destination
• An in-page fragment link with no matching identifier in the rendered output
• robots.txt or sitemap.xml carrying a hardcoded host instead of one derived from the request
• Serialized JSON-LD asserting a name, description, or offer with no visible counterpart
• A relative address in a field a third party fetches — a share-preview image, a structured-data logo
• Response headers applied on the success path only, leaving redirect and error responses uncovered

Verification

• Every rendered page has exactly one h1 and a heading sequence with no skipped level — report the counts observed, not the intent
• Each route's canonical declaration was fetched and returned that same page with no redirect in between
• title and meta description were collected across all routes; no duplicates and no scaffold default strings remain
• Every image element has an alt attribute, and decorative images are marked as such on purpose
• Every in-page fragment link was resolved against the rendered output of the page carrying it
• robots.txt and sitemap.xml were fetched from the deployed host and every address in them resolves — quote the address set observed
• Serialized JSON-LD parses, its addresses are absolute, and each claim it makes has a visible counterpart quoted from the page
• Response headers were observed on a success response, on a redirect response, and on an error response