docs(nav): the whole Reference tree is missing from the sidebar — root meta.json lists 16 sections and `references` is not one of them

[os-elon]

Part of #10206

The defect

Root content/docs/meta.json declares an explicit pages array of 16 entries. references is not one of them, and no meta.json anywhere in content/docs/** uses the "..." rest entry.

Verified against the real page-tree builder in fumadocs-core@16.14.4 (the pinned version in apps/docs/package.json), dist/loader-*.js ← src/source/page-tree/builder.ts:

if (metadata.pages) {
 const outputArray = [];
 for (const item of metadata.pages) resolveFolderItem(folderPath, item, outputArray, excludedPaths);
 for (const item of outputArray) {
 if (item !== rest && item !== restReversed) { node.children.push(item); continue; }
 ... // only a "..." entry pulls in the unlisted remainder
 }
} else for (const item of buildPaths(files, ...)) ... // no `pages` key ⇒ everything

So the 199 pages under content/docs/references/** (1589 schemas, per references/index.mdx) render at their URLs but never appear in the sidebar tree. They are reachable only from two inline links — content/docs/index.mdx ("Schema Reference") and getting-started/quick-reference.mdx — and a reader who follows one gets no sidebar branch to browse from.

This is the single exception in the tree; every other section lists its own pages in full:

references: UNLISTED -> index
--- root ---
unlisted dirs: ['references']
unlisted files: []

content/docs/references/meta.json additionally omits its own index from its pages, so even once the folder is listed its landing page would not appear as a child.

Why it is a Bug and not a Feature

Nothing about the accepted set changes. content/docs/index.mdx already advertises the section ("Schema Reference — generated Zod schema reference for every metadata type") and references/index.mdx presents itself as a browsable index with a per-module Quick Navigation table. The nav config fails to deliver what the docs declare — declared ≠ delivered, restored, not widened.

File surface

• content/docs/meta.json
• content/docs/references/meta.json

Nothing else. This card does not add or edit a single .mdx body.

What to do

1. Add references to the root pages array inside the existing ---Platform--- group, immediately after protocol. PM ruling — do not invent a new group and do not move any existing entry; see the rider section below for why.
2. Add index as the first entry of content/docs/references/meta.json's pages.
3. Verify the sidebar actually renders the branch, do not infer it from the config diff. pnpm --filter docs dev (or the repo's documented docs-dev command) and confirm: the Reference branch is present under Platform, expands to the 14 protocol modules, and the Protocol Reference index page is its first child. If the docs app cannot be booted in your worktree, say so in the report and state exactly what you checked instead — an unverified nav change is the whole failure mode of this card.

⛔ On-hold rider — #8966

#8966 (pm:on-hold) carries, in its most recent hold-transition comment (2026-08-16 06:22Z):

Remaining restart conditions: ① any card touching root content/docs/meta.json (devx seat: keep it in the pre-dispatch must-check list — that card takes this as a declared rider or declines on-card); ② a maintainer statement on releases-section placement.

This card fires condition ①. Both release checks pass (the condition is from the latest transition comment; no merged PR has landed on #8966 since it). PM decision: declined as a rider — the hold stands. Whether releases belongs in Platform or Build is a taxonomy call the triage seat already graded as maintainer-only, and today's authorization is about metadata-type docs coverage, not release-note shelving.

Therefore: ⛔ do not move, reorder, or re-group releases, and do not touch any other existing entry. Your diff to the root meta.json must be exactly one added line. If you believe references cannot be placed without moving something, stop and report — do not decide it.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

pnpm check:release-notes matches this card specifically through content/docs/meta.json, plus the content/docs family: check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff and run what it names; the full farm is CI's job.

Acceptance

• The Reference branch appears in the docs sidebar under Platform, with its index as first child, evidenced by a rendered check rather than by reading the JSON.
• Root meta.json diff is a single added entry; releases is byte-identical.
• Named gates green.

[os-elon]

Claim: PM loop round 1 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10209-references-sidebar
Worktree: objectstack-issue-10209
Domain: domain:devx
File surface: content/docs/meta.json, content/docs/references/meta.json (stop on breach; explain in the report)
Container & model: S mechanical, mode:subagent, model: opus — no path-derived mandate (node scripts/pm/dispatch-gates.mjs --tier content/docs/meta.json content/docs/references/meta.json → "the surface hits none of the 1 declared glob(s)"), so the tier is this seat's call. Raised above the sonnet floor for one reason: the card carries the #8966 on-hold rider and a placement constraint, and the failure mode is a plausible-looking nav edit that quietly re-shelves a section.
Clause-②: no
Serial constraints cleared: root content/docs/meta.json — #8966 is pm:on-hold and unassigned (not in flight; rider declined on-card, see #8966 (comment)). content/docs/references/meta.json — no in-flight claim. Sibling epic cards #10210 / #10211 dispatched in this same batch touch content/docs/ui/** and content/docs/automation/** respectively; file surfaces are disjoint from this one, and no pin on this card asserts their behaviour.

---

Generated by Claude Code

[os-elon]

{
 "issue": 10209,
 "status": "done",
 "branch": "claude/issue-10209-references-sidebar",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10253",
 "premise_still_valid": true,
 "summary": "The card's own premise held and is now fixed: root content/docs/meta.json declared an explicit pages array with no rest entry anywhere in the tree (0 of 35 meta.json files), so the whole references branch was absent from the rendered sidebar. Adding one line ('references' after 'protocol' inside the existing ---Platform--- group) restores it; final diff is 1 file changed, 1 insertion, and 'releases' is byte-identical (still four spaces then the quoted word, line 22 to 23). DEVIATION, declared: the card's step 2 (add 'index' to content/docs/references/meta.json) was NOT done, and PM mechanism assumption 2 is FALSIFIED. That file is generated by packages/spec/scripts/build-docs.ts, which emits it wholesale; the omission of 'index' is deliberate in the generator (rootFiles filter is f.endsWith('.mdx') && !f.startsWith('index')). Three independent disqualifiers, each measured: (a) with 'index' hand-added, check:docs goes red naming that exact file; (b) apps/docs' own build script runs gen:docs before next build, so the hand-edit is reverted before the site is ever rendered - inert in production; (c) it is unnecessary and lossy, because fumadocs auto-attaches a non-root folder's index.mdx as node.index regardless of the pages array, and listing it explicitly triggers delete node.index. Acceptance criterion 'index as first child' is therefore met in substance, not literally: the landing page IS in the tree, as the branch's own clickable heading. The #8966 hold was not touched or reopened; no existing entry moved and no group was added.",
 "tests": "All evidence at commit 3690851fb (final HEAD; gate union re-derived and run AFTER the commit). GATE DERIVATION: `node scripts/pm/dispatch-gates.mjs` with NO path arguments - it derived its own change set (1 path, merge base 502dc6fe7, three-dot semantics) and did NOT refuse for shallow checkout. It named 12 families, one MORE than the dispatch list: `node scripts/check-cross-package-test-inputs.mjs` [ci.yml], which I ran. GATES, each cited by the verdict line the gate itself printed, exit codes captured by redirect-then-$? (never through a pipe): check:release-notes 'check-release-notes: OK - every released major has a curated, navigable release page.' | check:doc-anchors '252 internal #fragment link(s) across 399 source file(s) all resolve to a real heading' | check:docs-audit-scope 'docs-accuracy-audit scope is in sync with content/docs/' + 'release-owned pages are in scope and read-only: 9 page(s)' | check:docs-redirects '48 assertions over a temp fixture (real loadTable + checkTable path)' | check:published-readme-links '152 outbound link(s) across 60 published markdown file(s)' | check:role-word 'OK self-test' | check:cross-package-test-inputs (both lint.yml and ci.yml spellings) 'OK: 12 package(s) read outside themselves, all declared' | spec check:empty-state 'all classified (1 closed, 2 open, 4 output, 9 scope)' | spec check:liveness 'every governed-type property at the walk's one-level granularity is classified' | spec check:strictness-ledger 'strictness ledger: 61 file(s) across 5 triaged director(ies)' | spec check:variant-docs 'variant/doc gate: 18 discriminated union(s) - 8 governed, 10 exempt' | spec check:docs (extra, run as proof the generated file is untouched) '229 generated files in sync with packages/spec'. All 13 EXIT=0. RENDER VERIFICATION (the card's whole point - observed, not inferred): booted the real docs app with next dev on port 39217, fetched the server-rendered HTML and read the sidebar text content. BEFORE: Platform group = Deployment & Operations / Plugins & Packages / Kernel & Services / Protocol Spec / Releases - no Reference branch, confirming PM assumption 1 by rendering. AFTER the one-line edit: Platform group = ... / Protocol Spec / Reference / Releases, Reference sitting exactly between protocol and releases. On /docs/references (HTTP 200) the branch expands to all 14 modules: AI, API, Automation, Cloud, Data, Identity, Integration, Kernel, QA, Security, Shared, Studio, System, UI Protocol. The Reference heading is an anchor element with href /docs/references. ABLATION for assumption 2, both legs, each confirmed on disk before reading any result: leg 1 added 'index' to references/meta.json - mutation confirmed by grep -c on the injected text (1) and by head of the file, NOT by the editor's exit code - then re-rendered: heading degraded from anchor element to a button element with no link, and 'Protocol Reference' appeared as a plain child row; check:docs went red naming content/docs/references/meta.json. Leg 2 (restore) ran gen:docs, confirmed absent by grep -c (0) and byte-diff against the pre-experiment file (identical), git status clean. Direction observed matched the static prediction read from the packed fumadocs-core@16.14.4 builder (loader-cKlyDdAK.js lines 489-521: the else-if-not-root branch auto-attaches index as node.index; resolveFolderItem adds a listed page to excludedPaths, which then triggers delete node.index). No sleeping or CI polling; report delivered at draft-PR time. Teardown: dev server killed by exact PID (25483/25453/25451, port 39217 confirmed closed), never by process name; worktree removed without --force; sibling worktrees 10210/10211 untouched.",
 "open_questions": [
 {
 "question": "Acceptance asked for the Protocol Reference index as the branch's literal FIRST CHILD ROW. As shipped it is the branch's own clickable heading instead (fumadocs node.index). Getting the literal child row is possible but only durably in the generator, outside this card's file surface and outside #10206's declared territory - and it costs the heading its link. Leave as shipped, or file a follow-up?",
 "options": [
 "A - leave as shipped: the landing page is in the tree and reachable, the heading links to /docs/references, zero further churn, and content/docs/references/meta.json stays a pure generator projection",
 "B - file a domain:spec follow-up to change build-docs.ts so it emits 'index' first in the references pages array, making it a literal child row - but this DELETES node.index, so the Reference heading stops being a link",
 "C - file a follow-up only if a maintainer wants the row for consistency with how other sections present their landing pages"
 ],
 "recommendation": "A. B is a strict regression on the four axes: it trades a working heading link for a duplicate row, serves no measured reader need, and spends a packages/spec change on cosmetics during a startup-scope-discipline phase. The rendered result already satisfies the acceptance intent - the branch is browsable and its index is reachable. Worth a PM sentence confirming the substance reading, not a card."
 }
 ],
 "out_of_scope_findings": [
 "filed as #10249: `next dev` writes untracked, non-gitignored apps/docs/AGENTS.md and apps/docs/CLAUDE.md - repo-significant agent-instruction filenames that a `git add -A` can sweep into any PR, and whose Next-authored text argues for committing them. Unassigned, no label, left for triage."
 ]
}

---

Generated by Claude Code