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

.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

@@ -482,6 +482,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`
+
 
 ---
 

content/docs/references/data/driver-common.mdx

@@ -36,6 +36,12 @@ const result = DriverSslToggleSchema.parse(data);
 
 ---
 
+## DriverSslToggle
+
+Enable TLS. Certificates go in the datasource-level `ssl` block.
+
+**Type:** `boolean`
+
 
 ---
 

content/docs/references/data/field-value.mdx

@@ -83,9 +83,17 @@ const result = AddressSchema.parse(data);
 
 ---
 
+## CalendarDateValue
+
+**Type:** `string`
+
 
 ---
 
+## ClockTimeValue
+
+**Type:** `string`
+
 
 ---
 
@@ -119,6 +127,10 @@ Type: `string`
 
 ---
 
+## FileReferenceIdValue
+
+**Type:** `string`
+
 
 ---
 
@@ -138,6 +150,10 @@ Type: `string`
 
 ---
 
+## InstantValue
+
+**Type:** `string`
+
 
 ---
 
@@ -155,6 +171,10 @@ Type: `string`
 
 ---
 
+## ReferenceIdValue
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/data/filter.mdx

@@ -99,6 +99,10 @@ Type: `[FilterArray](#filterarray)[]`
 
 ---
 
+## FilterCondition
+
+**Type:** `Record<string, any> & { $and?: [FilterCondition](#filtercondition)[]; $or?: [FilterCondition](#filtercondition)[]; $not?: [FilterCondition](#filtercondition) }`
+
 
 ---
 

content/docs/references/data/query.mdx

@@ -67,6 +67,10 @@ const result = AggregationFunction.parse(data);
 
 ---
 
+## FieldNode
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/kernel/manifest.mdx

@@ -99,6 +99,12 @@ Plugin compatibility ranges (ADR-0025 §3.2)
 
 ---
 
+## PluginIntegrity
+
+Per-file content digests of the plugin artifact (ADR-0025 §3.2)
+
+**Type:** `Record<string, string>`
+
 
 ---
 

content/docs/references/kernel/plugin-structure.mdx

@@ -43,6 +43,12 @@ Scanned domain module representing a plugin folder
 
 ---
 
+## OpsFilePath
+
+Validates a file path against OPS naming conventions
+
+**Type:** `string`
+
 
 ---
 

content/docs/references/qa/testing.mdx

@@ -91,6 +91,12 @@ Comparison operator for test assertions
 
 ---
 
+## TestContext
+
+Initial context or variables for the test
+
+**Type:** `Record<string, any>`
+
 
 ---
 

content/docs/references/shared/branded-types.mdx

@@ -38,21 +38,57 @@ const result = AppNameSchema.parse(data);
 
 ---
 
+## AppName
+
+Branded app name (system identifier)
+
+**Type:** `string`
+
 
 ---
 
+## FieldName
+
+Branded field name (snake_case, no dots)
+
+**Type:** `string`
+
 
 ---
 
+## FlowName
+
+Branded flow name (system identifier)
+
+**Type:** `string`
+
 
 ---
 
+## ObjectName
+
+Branded object name (snake_case, no dots)
+
+**Type:** `string`
+
 
 ---
 
+## RoleName
+
+Branded role name (system identifier)
+
+**Type:** `string`
+
 
 ---
 
+## ViewName
+
+Branded view name (system identifier)
+
+**Type:** `string`
+
 
 ---