docs: link the four sitemap-only orphan pages back into the site

[claude]

Fixes #12353

Docs-only. Face touched: body prose links. No frontmatter, no headings, no meta.json, no
apps/docs — the epic #12243 boundary stated in the dispatch order.

The measurement first: the card's stated method does not produce the card's number

The card's method is "fetch every sitemap URL, collect every internal href="/...", score each
page by how many other sitemap pages link to it". Reproduced against a locally rendered site,
that instrument scores all four named pages at 6 or more inbound links — not zero. Two pieces
of fumadocs chrome are in the rendered HTML of every page:

• the sidebar renders the active folder expanded, so the five kernel/contracts pages link
  each other;
• a Previous / Next footer is rendered inside the page's article element, derived from the
  page tree (fumadocs-ui@16.14.4, dist/layouts/docs/page/slots/footer.js, useFooterItems) —
  so every page in the tree has at least one inbound link from its neighbour. A grep for
  NODE_ENV across that package's dist/layouts returns no match (exit 1), so this is not a
  dev-only rendering.

Restrict the instrument to the prose the authors write — MDX bodies, fenced and inline code
stripped — and the card's number comes back exactly: on the card's base commit, four pages had
zero inbound links, and they are the four the card names (plus /docs itself, which is linked
from the homepage hero in apps/docs/app/[lang]/page.tsx, not from any MDX page).

So the finding is real and the stated method is not what found it. The accurate statement is
"these pages carry no editorial link from anywhere in the docs" — not "a reader following the
docs' own navigation can never arrive at them", which the sidebar and the Previous/Next footer
both falsify. This PR fixes the real half.

The count is 3, not 4

/docs/concepts/metadata-driven acquired an inbound prose link from
content/docs/getting-started/glossary.mdx:91 in b000ab59b (2026-08-26T01:24Z, #12385) — the
morning after the card was filed. The card's instrument was accurate when it ran; only the
count has drifted. Left as-is here, with the reasoning recorded: it is measurably no longer an
orphan.

The card's own hypothesis, checked and false

content/docs/kernel/contracts/meta.json lists all five pages, auth-service and
cache-service included; each of the other three orphans is likewise listed in its section's
meta.json. No meta.json needed an entry, and none is edited. The real gap is one level
up: the Contract Catalog table on kernel/contracts/index.mdx named all five contracts as plain
text, so the section index linked none of its own children.

Per-page calls

Page	Call	Where the link now comes from
/docs/kernel/contracts/auth-service	link-in	section index catalog + permissions/authentication, at the sentence about a service that does not implement handleRequest
/docs/kernel/contracts/cache-service	link-in	section index catalog + plugins/packages, at the sentence naming the contract the cache service sits behind
/docs/protocol/backward-compatibility	link-in	protocol/index + upgrading, where a reader crossing a major needs the rule for what a major may change
/docs/concepts/metadata-driven	leave it	already linked from getting-started/glossary since 2026-08-26

Deletion was considered for none of them: backward-compatibility carries the SemVer guarantees,
the deprecation timeline, the breaking-change table and the spec package guarantees, and an
existing redirect (/docs/guides/cheatsheets/backward-compatibility) still points at it. Per the
dispatch order, no page deletion is in this PR in any case.

The catalog rows for the three non-orphan contracts are linked in the same edit: they are the
same defect (a section index that links none of its children), and linking two of five rows would
leave the table inconsistent.

Verification

Prose-link graph over all 404 doc pages, code fences and inline code stripped:

before:  orphans = 4   /docs · kernel/contracts/auth-service · kernel/contracts/cache-service · protocol/backward-compatibility
after:   orphans = 1   /docs        (linked from the homepage hero, which is not an MDX page)
         auth-service 0 -> 2 · cache-service 0 -> 2 · backward-compatibility 0 -> 2

Rendered check of the five edited pages against a locally running docs server: each new link is
present as an href inside the article element, i.e. in the page body rather than in chrome.
Positive control kept, as the card specifies: /docs/data-modeling and /docs/ai score 195 and
195 inbound under the all-href instrument, 29 and 14 under the article-scoped one — non-zero
either way, so a zero elsewhere is a real zero.

Narrowing, declared with its measurement: the render was a dev server, not
next build && next start. What that costs is bounded and measured: the four card pages were
each measured directly under both instruments (not extrapolated), the Previous/Next footer and
the sidebar are unconditional in the library's own compiled output (the NODE_ENV grep above),
and the crawl covered 197 of 409 URLs before the dev server hit its heap limit — the four card
pages and both positive controls are inside those 197. The site-wide "zero orphans under the
all-href instrument" figure is therefore reported as partial; the per-page numbers are not.

Gates

Derived after the final commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
on the merge of origin/main, exit code read before any pipe.

Gate	Result	Exit
check:doc-anchors	GREEN	0
check:doc-authoring	GREEN	0
check:docs-single-h1	GREEN	0
check:docs-redirects	GREEN	0
check:docs-audit-scope	GREEN	0
check:corpus-claim-drift	GREEN	0
check:published-readme-links	GREEN	0
check:docs-image-tag	GREEN	0
check:role-word	GREEN	0
check-doc-frontmatter.mjs	GREEN	0
check-doc-route-spelling.mjs	GREEN	0
check-docs-section-name.mjs	GREEN	0
check-section-landing-index.mjs	GREEN	0
@objectstack/lint check:doc-formula-expressions	GREEN	0
@objectstack/lint check:doc-security-posture	GREEN	0
@objectstack/spec check:docs	GREEN	0

All sixteen were run on the final commit 1cb5a1b47 (this branch merged with origin/main), each
with its output redirected to a file and $? captured before any pipe. The last three needed
prerequisites the checkout does not carry — they first reported PREREQUISITE NOT MET (the gates'
own words: "Nothing was measured") — so @objectstack/formula and @objectstack/lint were built
and packages/spec gen:schema was run, and they were then measured green. Verdict lines, quoted
from the gates themselves:

check-doc-anchors: 287 internal #fragment link(s) across 409 source file(s) all resolve to a real heading
check-docs-single-h1: 404 page(s) under content/docs/ carry no body-level heading marker
check-section-landing-index: 8 section index block(s) enumerate their meta.json pages, in order, both directions
check-doc-security-posture: 26 ObjectSchema.create example(s) in 230 marked block(s) across 237 prose file(s) carry an os validate-clean security posture
check:docs (spec): 230 generated files in sync with packages/spec

The rest of the derived family is repo-wide surface this diff does not touch (spec liveness,
type-check, ESLint) and is left to CI, which runs the farm regardless.

skip-changeset: this PR publishes nothing — the whole diff is five content/docs MDX files.

Filed, not fixed here

• [finding] check-section-landing-index covers 8 docs sections; the three that produced the sitemap-only orphans are outside it #13778 — check-section-landing-index enforces exactly this defect class ("a section landing
  page enumerates its meta.json pages") but only over the 8 sections that carry the
  What's in this module heading. kernel/contracts, concepts and protocol are outside that
  census, which is how a catalog table naming five pages and linking none of them stayed green.
  Bringing a section into the census means adding a body heading — epic epic(docs-site): the site is technically un-indexable — fix robots/sitemap/canonical/OG first, then the keyword shape #12243's territory, not
  this PR's.
• [finding] docs(protocol): the Backward Compatibility page's pre-1.0 disclaimer still says 0.x, on a platform shipping 17.2.0 #13779 — the Backward Compatibility page ends with a pre-1.0 disclaimer ("during the 0.x
  development phase, MINOR versions may contain breaking changes") on a platform shipping 17.2.0.
  Content accuracy, not link repair.

---

Generated by Claude Code