fix(spec): 根参考索引 content/docs/references/index.mdx 纳入生成,不再无主烂尾 (#4759) (#5854)

* fix(spec): generate the root reference index instead of leaving it ownerless (#4759)

`content/docs/references/index.mdx` was the one file in that tree with no
owner at all: the Documentation Guardrails forbid hand-editing anything under
`content/docs/references/`, and `build-docs.ts` generated every category
folder and each category's `index.mdx` but never the root one. A table nobody
may edit and nothing regenerates can only rot, and it had, in every way such a
table can:

  - rows for files deleted a month earlier (`automation/trigger-registry.zod.ts`
    at #4499, `automation/sync.zod.ts` at #4738, plus a `workflow.zod.ts`
    `src/automation/` never had);
  - schema names that were never exports (`TriggerRegistrySchema`, `SyncSchema`,
    `ETLSchema` — the real one is `ETLPipeline`);
  - a nine-row section for the `src/hub` directory, deleted wholesale, and a
    `shared/connector-auth.zod.ts` row for a file `@objectstack/spec/shared`
    does not publish;
  - three mutually contradictory totals — 133 in the frontmatter, 169 in the
    navigation table, 19 in a Data row headed "18 schemas";
  - two of four dead "Next Steps" cards, and a doubled-paren link.

The per-module tables are rendered from the same page/schema grouping that
decides which reference pages to emit, so each class above is now structurally
impossible: no row can name a file the walk did not find, no cell can name a
schema the spec does not publish, and every count is a `reduce` over the rows
it heads rather than a second tally kept beside them. The page indexes all
1608 published schemas against the 201 files that declare them.

The old free-prose "用途" column is not reproduced. Per-file it would be 201
hand-kept sentences nothing can check — the rotten artifact rewritten in
TypeScript — so it is replaced by the schema names each page documents, which
are enumerated. The surviving prose is one line per CATEGORY (14 entries),
held to exactly the categories that have pages by `blurbCoverage`, in both
directions.

Intro, conventions and Next Steps live in reviewed generator source rather
than being preserved inside the generated zone — preserving hand-written text
there would recreate the ownerless state this fixes. Generation cannot make
their links true, so `docLinkTargets` resolves every one against the docs tree
and fails the build on a dead target.

`manageDir(DOCS_ROOT, …)` claims the two root-level files this generator owns
and only those, so removing the emit reports the page as stale instead of
silently shrinking `check:docs` back to 231 files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01559M8FVm6W6vDLABL3jvdW

* chore(spec): regenerate the root reference index after merging main

`api/discovery.zod.ts` gained `CapabilityDescriptor` on main (#5851 line),
so the index's api/discovery row and both totals moved: 1608 -> 1609.

Worth noting what this merge demonstrates. The frontmatter count and the
Total row moved TOGETHER, without anyone touching either, because both are
`reduce` over the rows they head — the disagreement this page shipped for
months (133 in the frontmatter, 169 in the nav table) has no way to recur.
And the drift was caught by `check:docs`, which could not see this file at
all before #4759.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01559M8FVm6W6vDLABL3jvdW

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

.changeset/root-reference-index-generated.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/spec': patch
+---
+
+Generate the root reference index (`content/docs/references/index.mdx`) instead of leaving it ownerless.
+
+That page sat in the AUTO-GEN zone — which the Documentation Guardrails forbid hand-editing —
+while `build-docs.ts` never wrote it, so it could only rot, and it had: rows for
+`automation/trigger-registry.zod.ts` and `automation/sync.zod.ts` (deleted at #4499 / #4738),
+schema names that were never exports (`TriggerRegistrySchema`, `SyncSchema`, `ETLSchema`), a
+nine-row section for a `src/hub` directory deleted long ago, a `shared/connector-auth.zod.ts`
+row for a file `@objectstack/spec/shared` does not publish, three mutually contradictory totals
+(133 / 169 / 19-under-a-heading-of-18), and two dead "Next Steps" cards.
+
+The per-module tables are now enumerated from the same JSON Schema output the category pages are
+built from, so a deleted `.zod.ts` cannot leave a row behind, a name the spec does not publish
+cannot appear, and every count is a sum of the rows it heads. The page now lists all 1608
+published schemas against the 201 files that declare them. `check:docs` covers it like any other
+generated file.