fix(docs): list references in the root sidebar so the Reference tree is reachable

[os-elon]

Fixes#10209

Sub-issue of #10206.

The change

One added line in content/docs/meta.json:

 "protocol",
+ "references",
"releases"

references joins the existing ---Platform--- group immediately after protocol. No group added, no entry moved. Full diff is 1 file changed, 1 insertion(+).

releases is byte-identical — the line is still four spaces then the quoted word, only its line number moved 22 to 23. The #8966 hold is untouched; the PM declined it as a rider on this card and I did not reopen it.

Verified by rendering, not by reading the config

The docs app was booted (next dev, port 39217) and the server-rendered sidebar compared before and after. The Platform group:

	rendered sidebar, Platform group
before	Deployment & Operations / Plugins & Packages / Kernel & Services / Protocol Spec / Releases
after	Deployment & Operations / Plugins & Packages / Kernel & Services / Protocol Spec / Reference / Releases

On /docs/references the branch expands to all 14 protocol modules — AI, API, Automation, Cloud, Data, Identity, Integration, Kernel, QA, Security, Shared, Studio, System, UI — and the Reference heading renders as an anchor element pointing at /docs/references, i.e. the Protocol Reference landing page is the branch's own link.

This confirms the mechanism the issue derived statically: the root meta.json declares an explicit pages array, no meta.json under content/docs/** carries a rest entry spelled as three dots (0 of 35 files), so the builder pushed only listed items into node.children.

Deviation from the card — step 2 is declined, with evidence

The issue's step 2 asks for index to be added as the first entry of content/docs/references/meta.json. This PR does not do that, for three independently sufficient reasons, each measured in the worktree:

1. That file is generated, and hand-editing it is a red gate.packages/spec/scripts/build-docs.ts emits it (emit(path.join(DOCS_ROOT, 'meta.json'), …)). With index added, pnpm --filter @objectstack/spec check:docs fails:

   ✗ content/docs/references/ is out of date with packages/spec:
   ~ content/docs/references/meta.json (out of date)
   These files are GENERATED — do not hand-edit them.
   

2. The edit is inert in production anyway.apps/docs' own build script is gen:schema && gen:docs && next build — the generator runs beforenext build and reverts the hand-edit. Confirmed: after gen:docs the added line is gone and the file is byte-identical to the committed one.

3. It is not needed, and it removes something. fumadocs auto-attaches a non-root folder's index.mdx as node.index regardless of the pages array. Listing index explicitly makes resolveFolderItem add it to excludedPaths, which triggers delete node.index — measured in the rendered DOM: without it the branch heading is an anchor element linking to /docs/references; with it the heading degrades to a button element carrying no link, and Protocol Reference becomes a plain child row instead.

So the card's acceptance criterion "index as first child" is met in substance rather than literally: the landing page is in the tree and reachable, as the branch's own clickable heading. Making it a literal child row would cost the heading its link, and could only be done durably in packages/spec — outside this card's declared file surface and outside #10206's declared territory. Flagged for the PM rather than decided here.

Gates

Re-derived against the actual diff with node scripts/pm/dispatch-gates.mjs (no paths passed — the script derives its own change set), which named 12 families, one more than the dispatch list. All green at 3690851fb, plus check:docs run as evidence the generated file is untouched:

gate	verdict line it printed
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 (lint.yml + ci.yml)	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 … 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)
spec check:docs	229 generated files in sync with packages/spec

No changeset: this is a docs-content-only bug fix that publishes no package (AGENTS.md §943 — pure bug fixes do not require one), so skip-changeset is applied instead.

Out-of-scope finding

Filed as #10249: next dev writes untracked, non-gitignored apps/docs/AGENTS.md and apps/docs/CLAUDE.md. Not fixed here.

---

Generated by Claude Code

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 32391924279 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests（日志不可读，点进 job 看）

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 39 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[os-elon]

Merge-queue dequeue triage (PM, epic #10206). Verdict: not this PR's failure — requeued once, and only once.

What the diff can reach

This PR is content/docs/meta.json, +1/−0: one string added to a nav array. It touches no package, no source, no test, and nothing any package builds from. The failing turbo task is @objectstack/example-showcase#test. There is no path by which this diff reaches that suite, so triage branch 1 (regression in a package the PR changed) is ruled out by construction, not by judgement.

Supporting readings from the queue job:

• Tasks: 80 successful, 83 total · Failed: @objectstack/example-showcase#test — the failure is confined to one package.
• check-test-completeness: OK (24 of 29 scheduled package(s) reported … 8827 test(s) declared and all accounted for) — tests ran and nothing silently vanished, so this is not a "died before the test body" case either.
• The last test file visible in the log tail (platform-migrations-arming.integration.test.ts) reports ✓ 6 tests passing, followed by a run of SIGTERM → Kernel already stopped or stopping and then ELIFECYCLE Test failed.

What I could NOT establish, stated rather than papered over

I do not have the failing assertion. The triage workflow's own extractor reported it could not parse a test-file name out of the log, and I could not either: pulling the job log through the API returns only a tail, and the vitest FAIL line sits earlier than the retrievable window. grep over 55k characters of tail finds no AssertionError, no EnvironmentTeardownError, no timed out.

So I am not claiming this is a known flake. There is an open card (#9371) describing a vitest teardown race that fails app-showcase with all tests passing, and the SIGTERM-then-ELIFECYCLE shape at the tail is consistent with it — but consistent with is not is, and citing it as confirmed would be exactly the kind of unverified attribution that makes flake ledgers useless. If someone can read the full run log, that is the missing half.

This is also a live instance of the class #10032 / #10203 are about — a failing turbo run test task landing in Test Core with no recoverable output. Recording it here as a data point rather than filing a duplicate.

Action

Requeued once. The discipline allows exactly one confirming re-run for a failure naming a surface the diff does not touch, and this is this PR's first queue failure in 24h (per the triage comment's own history line). ⛔ If it fails a second time I will not requeue again — a second failure is real by definition, and I will stop and diagnose rather than burn another full-queue rebuild. The queue had 39 failed builds in the preceding 24h, so blind re-queuing is not free for anyone behind it.

---

Generated by Claude Code