[finding] `build-docs.ts:624` bakes "REST/GraphQL contracts" into the generated references index

[claude]

Found while implementing #10710 and filed per that card's triage, which named this as
generator territory and asked for it as a separate domain:spec follow-up rather than a
widening of the docs PR. Confirmed: generator, and the cause is one line.

The sites

content/docs/references/index.mdx:23 and :66 both read:

REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery.

The cause

Not the page. packages/spec/scripts/build-docs.ts:624 holds it in the CATEGORY_BLURBS
map:

api: 'REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery.',

and the root index is emitted from it at build-docs.ts:891
(emit(path.join(DOCS_ROOT, 'index.mdx'), rootIndex)). The script's own header is explicit
that editing the page is not an option:

// This script regenerates ALL files under content/docs/references/{category}/.
// DO NOT place hand-written content in content/docs/references/ — it WILL be

So a fix on the page is reverted by the next gen:docs, and check:docs would flag the
drift. The edit belongs at build-docs.ts:624 — dropping /GraphQL so the blurb reads
"REST contracts, endpoints, routing, realtime, batch, discovery." — followed by
pnpm --filter @objectstack/spec gen:docs to regenerate.

Why it is wrong

packages/spec/src/api/ — the very directory this blurb summarises — contains zero
graphql files (measured). The API-protocol category it labels has 28 schemas and none of
them is a GraphQL contract. /graphql was removed from the dispatcher
(packages/runtime/src/http-dispatcher.ts:2026) and graphql was deleted as a
CoreServiceName in v17 (packages/spec/src/system/core-services.zod.ts:132).

Low reader-harm on its own — it is a category blurb, not an endpoint contract — but it is
the last GraphQL claim in the docs tree that no page-level edit can reach, and it will
outlive every hand-written fix until the generator changes.

Back-links: #10710, #10583, #10616, #10563

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage first-touch: promoted to queue, type Task, spec lane (packages/spec/scripts/build-docs.ts is spec-lane tooling). Scope: drop /GraphQL from the CATEGORY_BLURBS.api entry at build-docs.ts:624, then pnpm --filter @objectstack/spec gen:docs to regenerate — ⛔ never hand-edit content/docs/references/** (the script's own header). Sibling card #10833 (llms.txt GraphQL row) is the same defect family in the same lane — the spec seat may fold the pair into one dispatch under the family rules (both already graded, shared theme, near-disjoint files) or run them serially; landing note: the regen PR goes through the os-regen-merge.sh four-step at merge time. No accept/reject change ⇒ no clause-②. Size/model suggestion: S, sonnet.

---

Generated by Claude Code