Rubric: findability

Written by a person. Last read by a person on 2026-09-05, 3 days ago. Its facts were checked by the eval suite on 2026-09-07.

Enforced by check_findability, check_fragments and check_anchor_stability.

The claim

Everything a reader can see is in the served document, at an address that does not move, and every link into a section lands somewhere real.

Why this is a gate and not a preference

Documents read linearly because paper is linear, and that constraint is gone. What is not gone is what the linear document was quietly providing: a substrate you can search, cite, link into and crawl. None of that is a reading-order property. All of it is addressability, and addressability survives the loss of linearity only if it is protected deliberately.

Ctrl+F, a crawler and a screen reader all see the document before any interaction, and none of them will perform one.

What counts as an address

A heading, and a details or section carrying an explicit id. The test is whether a link to it resolves and lands, not which tag it happens to be.

That matters when a heading becomes a disclosure. Keeping the id keeps every link somebody already sent, and a check that only looked at headings would call that a break while every one of those links still worked.

Observable evidence

• Unrendered template syntax in the output.
• Content hidden by display:none or the hidden attribute, which removes it from the document rather than from view.
• Every link containing a fragment, and whether the target page has that id.
• Every heading anchor, compared against the recorded baseline.

The pass bar

No unrendered templates. No content hidden from find-in-page. Every fragment resolves. No recorded anchor disappears.

What this caught on its first run

Two things, both of which had already shipped.

Markdown headings were being rendered with no id at all, so there was nothing to deep-link to and nothing for a fragment to resolve against, and a link written in this repo's own API documentation pointed at a section anchor that did not exist — the page resolved, the fragment landed nowhere, and nothing reported it.

That second one was a known gap, recorded in the link-integrity rubric as a case that would pass. It had been recorded honestly and it was still wrong in production, which is the argument for closing gaps rather than documenting them and moving on.

Ambiguous cases

Whether a browser's find-in-page expands a collapsed region. Modern browsers do expand a closed details to reveal a match. This rubric does not assert that: it checks that the text is present in the document, which is the part under this project's control. The browser behavior is recorded as verified separately, per browser, and is not inferred from the HTML.

Content legitimately hidden. A skip link positioned offscreen is available to a screen reader and to find-in-page and is not hidden in the sense this rubric means. The check targets display:none and hidden, which remove an element from the accessibility tree as well as from view.

Anchors that should change. Renaming a section is sometimes right. The check does not forbid it; it refuses to let it happen silently. Re-record the baseline deliberately, in the same commit, and the diff shows a reviewer which citations were broken on purpose.

External links. Still unchecked, and still a real gap. Checking them makes a green build depend on the reachability of sites this project does not control.