fix(spec): render the reference section for a non-object root schema (#7658) (#7808)

`build-docs.ts` picked the node it was documenting by enumerating shapes —
`properties`, `enum`, `anyOf`, `oneOf` — and answered "none of those" with
`return ''`. A JSON Schema root is routinely none of those:
`z.string().describe(…)` compiles to a bare scalar, `z.record(…)` to an object
with `additionalProperties` and no `properties`, `z.array(…)` to an array,
`z.intersection(…)` to an `allOf`. Each lost its whole `## Name` section —
heading included, and with it the `.describe()` prose written to be read — while
the page's `## TypeScript Usage` block, spelled from the export surface rather
than from this function, went on naming the export.

Measured on today's tree: 45 published schemas were in that state, 33 carrying a
description. The card counted 22 (`~23`), having scanned only the bare-scalar
spelling. Regenerating adds 244 lines across 27 pages and removes none, so the
1533 sections that already rendered are byte-identical. Emitted files 230 → 230:
an empty section never removed a page, so no category's `pages.length` moves and
the #7303 `meta.json` guard is untouched.

The renderer moves to `scripts/lib/schema-section.ts` so it can be pinned
directly — the extraction `lib/format-type.ts` got at #4912, for the same reason.
Its output here was the empty string, which is precisely what grepping emitted
`.mdx` cannot see, and why `check:docs` stayed green over this for months.

Reverse-verified: restoring the old fallback turns 7 of the 13 new cases red and
leaves the other 6 green.


Claude-Session: https://claude.ai/code/session_01RpBD5DrXb9gsPKkRHL8FHG

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

Author: os-help

.changeset/reference-docs-opaque-root-schemas.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): reference pages no longer drop the whole section for a non-object root schema (#7658)
+
+`build-docs.ts` decided which node of a published document it was documenting by
+enumerating shapes — `properties`, `enum`, `anyOf`, `oneOf` — and answered "none
+of those" with `return ''`. A JSON Schema root is routinely none of those:
+`z.string().describe(…)` compiles to a bare scalar, `z.record(…)` to an object
+with `additionalProperties` and no `properties`, `z.array(…)` to an array,
+`z.intersection(…)` to an `allOf`. Every one of them lost its ENTIRE `## Name`
+section — heading included, and with it the `.describe()` prose an author wrote
+to be read — while the page's `## TypeScript Usage` block, which is spelled from
+the export surface rather than from this function, went on naming the export. The
+page read as if it had forgotten to finish rendering an entry it had just
+imported.
+
+**Measured on today's tree: 45 published schemas were in that state, 33 of them
+carrying a description.** The filed issue counted 22 (`~23`), having scanned only
+the bare-scalar spelling; record maps, one array root and one `allOf` are the
+same defect through the same line. Regenerating restores all 45 sections — 244
+added lines, **zero removed**, so none of the 1533 sections that already rendered
+moves. Emitted file count is unchanged at 230: a section rendering as the empty
+string never removed a page, so no category's `pages.length` changes and the
+`meta.json` emit guard added in #7303 is untouched.
+
+Nothing was failing, which is why this stood for months: `check:docs` compares
+generated output to committed output, so a section that never existed stays green
+forever, and there is no grep for what is missing.
+
+The renderer moved to `scripts/lib/schema-section.ts` to be pinned directly —
+the same extraction, for the same reason, that `lib/format-type.ts` got at #4912.
+Its output was the empty string, the one thing grepping emitted `.mdx` cannot
+see.
+
+Sections for these shapes now carry the schema's description plus a single
+`**Type:**` line, rendered by the same `formatType` that every property row on
+the page uses, so a schema's own section and a property typed with it cannot
+disagree. Constraints (`pattern`, `minLength`, `minimum`) are deliberately not
+spelled: this renderer prints none in any position, and `json-schema/` stays the
+authority on them.

content/docs/references/api/contract.mdx

@@ -483,6 +483,12 @@ const result = ApiErrorSchema.parse(data);
 
 ---
 
+## RecordData
+
+Key-value map of record data
+
+**Type:** `Record<string, any>`
+
 
 ---
 

content/docs/references/api/websocket.mdx

@@ -178,6 +178,12 @@ const result = AckMessageSchema.parse(data);
 
 ---
 
+## EventPattern
+
+Event pattern (supports wildcards like "record.*" or "*.created")
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/cloud/environment-artifact.mdx

@@ -34,6 +34,12 @@ const result = Sha256DigestSchema.parse(data);
 
 ---
 
+## Sha256Digest
+
+SHA-256 digest (64 hex chars)
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/cloud/environment.mdx

@@ -107,6 +107,12 @@ Credential lifecycle status
 
 ---
 
+## EnvironmentDriver
+
+Data-plane driver key (e.g. `turso`, `libsql`, `sqlite`, `postgres`)
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/cloud/package.mdx

@@ -91,9 +91,21 @@ Register a new package in the Control Plane
 
 ---
 
+## PackageCategory
+
+Package category for marketplace discovery (e.g. "crm", "hr", "finance", "devtools")
+
+**Type:** `string`
+
 
 ---
 
+## PackageLocale
+
+BCP-47 locale tag
+
+**Type:** `string`
+
 
 ---
 
@@ -128,6 +140,12 @@ Per-locale overrides for a package listing
 
 ---
 
+## PackageTranslations
+
+Locale-keyed overrides; missing keys fall back to base columns
+
+**Type:** `Record<string, { displayName?: string; description?: string; readme?: string; tagline?: string; … }>`
+
 
 ---
 

content/docs/references/cloud/tenant.mdx

@@ -158,6 +158,12 @@ const result = PackageInstallationSchema.parse(data);
 
 ---
 
+## TenantPlan
+
+Opaque plan/tier identifier. The vocabulary is control-plane config owned by the cloud distribution, not protocol — this schema accepts any string and does not enumerate valid values. Convention: an empty or unrecognized value is treated as the free tier by cloud-side readers (not enforced by this schema).
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/data/context-tokens.mdx

@@ -92,9 +92,17 @@ const result = ContextTokenSchema.parse(data);
 
 ---
 
+## ContextToken
+
+**Type:** `string`
+
 
 ---
 
+## ContextTokenPlaceholder
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/data/datasource.mdx

@@ -68,6 +68,12 @@ const result = DatasourceSchema.parse(data);
 
 ---
 
+## DriverType
+
+Underlying driver identifier
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/data/date-macros.mdx

@@ -92,9 +92,17 @@ const result = DateMacroPlaceholderSchema.parse(data);
 
 ---
 
+## DateMacroPlaceholder
+
+**Type:** `string`
+
 
 ---
 
+## DateMacroToken
+
+**Type:** `string`
+
 
 ---