fix(spec): qualify a union variant's nested-shape and allowed-values headings by which variant they belong to

.changeset/wild-pugs-shave.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/spec': patch
+---
+
+Reference docs: qualify a union variant's `### Nested Shape:` and `### Allowed Values:` headings by which variant they belong to.
+
+The `### Union Options` renderer calls the property-table renderer once per variant, and both halves of the `Schema.key` qualifier those headings carry are shared by every sibling variant of one schema. Two `ViewItem` variants each declaring a shape-opening `config` therefore emitted `### Nested Shape: \`ViewItem.config\`` twice — two identical anchors on one page, on the very heading whose qualifier exists to prevent that. Measured on the published tree: 12 excess occurrences, 10 distinct headings, 4 pages, all under schemas rendering `### Union Options`.
+
+The heading now names the variant with the accessor grammar the page already prints — `ViewItem[viewKind='list'].config`, or `[option 2]` where the union pins no distinct discriminant — reusing the same `variantSelector` that stamps the variant segment into a property accessor, so a page carries one variant notation rather than two. `### Allowed Values:` is covered in the same change (no page collides there today; the exposure is identical). Headings outside a union variant, and unions with a single heading-emitting arm, are byte-identical: regenerating the 214-page tree changes 39 heading lines and nothing else.
+
+This changes what the docs site publishes, hence a release-visible patch rather than a skipped changeset.

content/docs/references/api/websocket.mdx

@@ -474,7 +474,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent |
 | **subscription** | `{ subscriptionId: string; events: string[]; objects?: string[]; filters?: any; … }` | ✅ | Subscription configuration |
 
-### Nested Shape: `WebSocketMessage.subscription`
+### Nested Shape: `WebSocketMessage[type='subscribe'].subscription`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -499,7 +499,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent |
 | **request** | `{ subscriptionId: string }` | ✅ | Unsubscribe request |
 
-### Nested Shape: `WebSocketMessage.request`
+### Nested Shape: `WebSocketMessage[type='unsubscribe'].request`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -539,7 +539,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent |
 | **presence** | `{ userId: string; sessionId: string; status: Enum<'online' \| 'away' \| 'busy' \| 'offline'>; lastSeen: string; … }` | ✅ | Presence state |
 
-### Nested Shape: `WebSocketMessage.presence`
+### Nested Shape: `WebSocketMessage[type='presence'].presence`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -567,7 +567,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent |
 | **cursor** | `{ userId: string; sessionId: string; documentId: string; position?: object; … }` | ✅ | Cursor position |
 
-### Nested Shape: `WebSocketMessage.cursor`
+### Nested Shape: `WebSocketMessage[type='cursor'].cursor`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -595,7 +595,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime when message was sent |
 | **operation** | `{ operationId: string; documentId: string; userId: string; sessionId: string; … }` | ✅ | Edit operation |
 
-### Nested Shape: `WebSocketMessage.operation`
+### Nested Shape: `WebSocketMessage[type='edit'].operation`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |

content/docs/references/data/data-engine.mdx

@@ -543,7 +543,7 @@ This schema accepts one of the following structures:
 | **object** | `string` | ✅ | |
 | **query** | `{ context?: object; where?: Record<string, any> \| any; fields?: string[]; orderBy?: object[]; … }` | optional | |
 
-### Nested Shape: `DataEngineRequest.query`
+### Nested Shape: `DataEngineRequest[method='find'].query`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -577,7 +577,7 @@ This schema accepts one of the following structures:
 | **object** | `string` | ✅ | |
 | **query** | `{ context?: object; where?: Record<string, any> \| any; fields?: string[]; orderBy?: object[]; … }` | optional | |
 
-### Nested Shape: `DataEngineRequest.query`
+### Nested Shape: `DataEngineRequest[method='findOne'].query`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -626,7 +626,7 @@ This schema accepts one of the following structures:
 | **id** | `string \| number` | optional | ID for single update, or use where in options |
 | **options** | `{ context?: object; where?: Record<string, any> \| any; multi?: boolean; returning?: boolean; … }` | optional | |
 
-### Nested Shape: `DataEngineRequest.options`
+### Nested Shape: `DataEngineRequest[method='update'].options`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -650,7 +650,7 @@ This schema accepts one of the following structures:
 | **id** | `string \| number` | optional | ID for single delete, or use where in options |
 | **options** | `{ context?: object; where?: Record<string, any> \| any; multi?: boolean; filter?: Record<string, any> \| any }` | optional | |
 
-### Nested Shape: `DataEngineRequest.options`
+### Nested Shape: `DataEngineRequest[method='delete'].options`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -671,7 +671,7 @@ This schema accepts one of the following structures:
 | **object** | `string` | ✅ | |
 | **query** | `{ context?: object; where?: Record<string, any> \| any; filter?: Record<string, any> \| any }` | optional | |
 
-### Nested Shape: `DataEngineRequest.query`
+### Nested Shape: `DataEngineRequest[method='count'].query`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -691,7 +691,7 @@ This schema accepts one of the following structures:
 | **object** | `string` | ✅ | |
 | **query** | `{ context?: object; where?: Record<string, any> \| any; groupBy?: (string \| object)[]; aggregations?: object[]; … }` | ✅ | |
 
-### Nested Shape: `DataEngineRequest.query`
+### Nested Shape: `DataEngineRequest[method='aggregate'].query`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |

content/docs/references/system/collaboration.mdx

@@ -195,7 +195,7 @@ This schema accepts one of the following structures:
 | **replicaId** | `string` | ✅ | ID of replica that performed last write |
 | **vectorClock** | `{ clock: Record<string, integer> }` | optional | Optional vector clock for causality tracking |
 
-### Nested Shape: `CRDTState.vectorClock`
+### Nested Shape: `CRDTState[type='lww-register'].vectorClock`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -241,7 +241,7 @@ This schema accepts one of the following structures:
 | **type** | `'or-set'` | ✅ | |
 | **elements** | `{ value: any; timestamp: string; replicaId: string; uid: string; … }[]` | ✅ | Set elements with metadata |
 
-### Nested Shape: `CRDTState.elements[number]`
+### Nested Shape: `CRDTState[type='or-set'].elements[number]`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -268,7 +268,7 @@ This schema accepts one of the following structures:
 | **lamportClock** | `integer` | ✅ | Current Lamport clock value |
 | **vectorClock** | `{ clock: Record<string, integer> }` | ✅ | Vector clock for causality |
 
-### Nested Shape: `CRDTState.operations[number]`
+### Nested Shape: `CRDTState[type='text'].operations[number]`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -280,7 +280,7 @@ This schema accepts one of the following structures:
 | **timestamp** | `string` | ✅ | ISO 8601 datetime of operation |
 | **lamportTimestamp** | `integer` | ✅ | Lamport timestamp for ordering |
 
-### Nested Shape: `CRDTState.vectorClock`
+### Nested Shape: `CRDTState[type='text'].vectorClock`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |

content/docs/references/system/migration.mdx

@@ -465,7 +465,7 @@ Add a new field to an existing object
 | **fieldName** | `string` | ✅ | Name of the field to add |
 | **field** | `{ name?: string; label?: string; type: Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>; description?: string; … }` | ✅ | Full field definition to add |
 
-### Nested Shape: `MigrationOperation.field`
+### Nested Shape: `MigrationOperation[type='add_field'].field`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -590,7 +590,7 @@ Create a new object
 | **type** | `'create_object'` | ✅ | |
 | **object** | `{ name: string; label?: string; pluralLabel?: string; description?: string; … }` | ✅ | Full object definition to create |
 
-### Nested Shape: `MigrationOperation.object`
+### Nested Shape: `MigrationOperation[type='create_object'].object`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |

content/docs/references/system/tenant.mdx

@@ -249,7 +249,7 @@ This schema accepts one of the following structures:
 | **database** | `{ enableRLS: boolean; contextMethod: Enum<'session_variable' \| 'search_path' \| 'application_name'>; contextVariable: string; applicationValidation: boolean }` | optional | Database configuration |
 | **performance** | `{ usePartialIndexes: boolean; usePartitioning: boolean; poolSizePerTenant?: integer }` | optional | Performance settings |
 
-### Nested Shape: `TenantIsolationConfig.database`
+### Nested Shape: `TenantIsolationConfig[strategy='shared_schema'].database`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -258,7 +258,7 @@ This schema accepts one of the following structures:
 | **contextVariable** | `string` | optional (default: `"app.current_tenant"`) | Session variable name |
 | **applicationValidation** | `boolean` | optional (default: `true`) | Application-level tenant validation |
 
-### Nested Shape: `TenantIsolationConfig.performance`
+### Nested Shape: `TenantIsolationConfig[strategy='shared_schema'].performance`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -279,7 +279,7 @@ This schema accepts one of the following structures:
 | **migrations** | `{ strategy: Enum<'parallel' \| 'sequential' \| 'on_demand'>; maxConcurrent: integer; rollbackOnError: boolean }` | optional | Migration configuration |
 | **performance** | `{ poolPerSchema: boolean; schemaCacheTTL: integer }` | optional | Performance settings |
 
-### Nested Shape: `TenantIsolationConfig.schema`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_schema'].schema`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -288,15 +288,15 @@ This schema accepts one of the following structures:
 | **sharedSchema** | `string` | optional (default: `"public"`) | Schema for shared resources |
 | **autoCreateSchema** | `boolean` | optional (default: `true`) | Auto-create schema |
 
-### Nested Shape: `TenantIsolationConfig.migrations`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_schema'].migrations`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **strategy** | `Enum<'parallel' \| 'sequential' \| 'on_demand'>` | optional (default: `"parallel"`) | Migration strategy |
 | **maxConcurrent** | `integer` | optional (default: `10`) | Max concurrent migrations |
 | **rollbackOnError** | `boolean` | optional (default: `true`) | Rollback on error |
 
-### Nested Shape: `TenantIsolationConfig.performance`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_schema'].performance`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -317,7 +317,7 @@ This schema accepts one of the following structures:
 | **backup** | `{ strategy: Enum<'individual' \| 'consolidated' \| 'on_demand'>; frequencyHours: integer; retentionDays: integer }` | optional | Backup configuration |
 | **encryption** | `{ perTenantKeys: boolean; algorithm: string; keyManagement?: Enum<'aws_kms' \| 'azure_key_vault' \| 'gcp_kms' \| 'hashicorp_vault' \| 'custom'> }` | optional | Encryption configuration |
 
-### Nested Shape: `TenantIsolationConfig.database`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_db'].database`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -326,7 +326,7 @@ This schema accepts one of the following structures:
 | **separateCredentials** | `boolean` | optional (default: `true`) | Separate credentials per tenant |
 | **autoCreateDatabase** | `boolean` | optional (default: `true`) | Auto-create database |
 
-### Nested Shape: `TenantIsolationConfig.connectionPool`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_db'].connectionPool`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
@@ -335,15 +335,15 @@ This schema accepts one of the following structures:
 | **idleTimeout** | `integer` | optional (default: `300`) | Idle pool timeout |
 | **usePooler** | `boolean` | optional (default: `true`) | Use connection pooler |
 
-### Nested Shape: `TenantIsolationConfig.backup`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_db'].backup`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **strategy** | `Enum<'individual' \| 'consolidated' \| 'on_demand'>` | optional (default: `"individual"`) | Backup strategy |
 | **frequencyHours** | `integer` | optional (default: `24`) | Backup frequency |
 | **retentionDays** | `integer` | optional (default: `30`) | Backup retention days |
 
-### Nested Shape: `TenantIsolationConfig.encryption`
+### Nested Shape: `TenantIsolationConfig[strategy='isolated_db'].encryption`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |

content/docs/references/ui/app.mdx

@@ -892,7 +892,7 @@ This schema accepts one of the following structures:
 | **type** | `'action'` | ✅ | |
 | **actionDef** | `{ actionName: string; params?: Record<string, any> }` | ✅ | Action definition to execute when clicked |
 
-### Nested Shape: `NavigationItem.actionDef`
+### Nested Shape: `NavigationItem[type='action'].actionDef`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |