fix(spec): render a nested item shape as a table so its describe text reaches the reference page

.changeset/docs-nested-item-shape-tables.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): reference pages carry a nested item shape's `.describe()` text instead of collapsing it into a signature cell (#11601)
+
+`build-docs.ts` renders a property whose type is an inline object as a
+one-line signature — `{ label: string; icon?: string; visibleWhen?: string |
+object; value?: string; … }[]` — into a table cell that has **no description
+column**. Every `.describe()` an author wrote on a key of that shape was
+therefore unreachable from the reference page: not truncated, not marked,
+absent. `page:tabs`'s item-level `visibleWhen` carries a ~600-character
+contract note whose whole point is that its evaluation environment is **not**
+the page-component `visibleWhen` of the same name, and
+`content/docs/references/ui/component.mdx` rendered that row with an empty
+Description cell.
+
+The loss was invisible from both sides. `check:docs` compares generated output
+with committed output, so it is green forever on prose neither side contains —
+measured on the tree before this change, adding a `.describe()` to a nested
+item key produced a **zero-line** `gen:docs` diff.
+
+**The population, measured on the emitted tree.** 1293 property rows across
+566 published schemas and 13 of 14 categories open a nested shape; 1208 of them
+have at least one key carrying describe text, 7502 described keys in total,
+~473 KB of authored prose that reached no page.
+
+**What is rendered now.** A property that opens exactly one shape, and whose
+shape has at least one described key, gets a `### Nested Shape:` table directly
+under the Properties table — the same position, addressing and heading level
+the `### Allowed Values:` relocation has used since #6225, so the page gains no
+second grammar. The heading names the shape with a TypeScript indexed accessor
+(`PageTabsProps.items[number]`, `Object.fields[string]`), which is a real
+spelling rather than a sigil invented for the docs.
+
+Four bounds, each measured rather than chosen:
+
+- **One level**, matching the `SHAPE_DEPTH_LIMIT` budget a cell already spends.
+ A nested table opens no table of its own.
+- **Only where there is text to publish.** A shape whose keys carry no
+ describe text keeps its cell; a table there would restate the cell in more
+ space.
+- **A union of two or more object shapes keeps its cell.** There is no single
+ "the shape of this property" to name — the same reason `formatPropertyType`
+ refuses to relocate a vocabulary out of `Enum<…>[]`.
+- **A nested table does not relocate vocabularies.** It is a second position
+ for those keys, so it elides them the way a `{ … }` summary does. Without
+ this rule the 288-member `ApiError.code` vocabulary was re-listed under every
+ nested `error` shape — 20,260 bullet lines across the tree, `api/metadata.mdx`
+ alone +6097.
+
+Tombstoned keys are rendered in a nested table, unlike in the cell above it:
+`retiredKey()` puts the whole `[REMOVED]` migration prescription in
+`description`, and a signature has no column to carry it.
+
+The regenerated tree is **purely additive** — 143 files, +14195 / -118 lines,
+and every one of the 38177 pre-existing lines is still present byte for byte
+(the 118 are re-ordering around the inserted sections, not removal).

content/docs/references/ai/agent.mdx

@@ -71,6 +71,68 @@ const result = AIModelConfigSchema.parse(data);
 | **_packageVersion** | `string` | optional | Owning package version. |
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 
+### Nested Shape: `Agent.model`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>` | optional (default: `"openai"`) | |
+| **model** | `string` | ✅ | Model name (e.g. gpt-4, claude-3-opus) |
+| **temperature** | `number` | optional (default: `0.7`) | |
+| **maxTokens** | `number` | optional | |
+| **topP** | `number` | optional | |
+
+### Nested Shape: `Agent.lifecycle`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Unique Machine ID |
+| **description** | `string` | optional | |
+| **contextSchema** | `Record<string, any>` | optional | Zod Schema for the machine context/memory |
+| **initial** | `string` | ✅ | Initial State ID |
+| **states** | `Record<string, { type: Enum<'atomic' \| 'compound' \| 'parallel' \| 'final' \| 'history'>; entry?: (string \| object)[]; exit?: (string \| object)[]; on?: Record<string, string \| object \| object[]>; … }>` | ✅ | State Nodes |
+| **on** | `Record<string, string \| { target?: string; cond?: string \| object; actions?: (string \| object)[]; description?: string } \| { target?: string; cond?: string \| object; actions?: (string \| object)[]; description?: string }[]>` | optional | |
+
+### Nested Shape: `Agent.planning`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **maxIterations** | `integer` | optional (default: `10`) | Maximum planning loop iterations |
+
+### Nested Shape: `Agent.memory`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **longTerm** | `{ enabled: boolean; store: Enum<'vector' \| 'database' \| 'redis'>; maxEntries?: integer }` | optional | Long-term / persistent memory |
+| **reflectionInterval** | `integer` | optional | Reflect every N interactions to improve behavior |
+
+### Nested Shape: `Agent.guardrails`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **maxTokensPerInvocation** | `integer` | optional | Token budget per single invocation |
+| **maxExecutionTimeSec** | `integer` | optional | Max execution time in seconds |
+| **blockedTopics** | `string[]` | optional | Forbidden topics or action names |
+
+### Nested Shape: `Agent.structuredOutput`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **format** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | ✅ | Expected output format |
+| **schema** | `Record<string, any>` | optional | JSON Schema definition for output |
+| **strict** | `boolean` | optional (default: `false`) | Enforce exact schema compliance |
+| **retryOnValidationFailure** | `boolean` | optional (default: `true`) | Retry generation when output fails validation |
+| **maxRetries** | `integer` | optional (default: `3`) | Maximum retries on validation failure |
+| **fallbackFormat** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | optional | Fallback format if primary format fails |
+| **transformPipeline** | `Enum<'trim' \| 'parse_json' \| 'validate' \| 'coerce_types'>[]` | optional | Post-processing steps applied to output |
+
+### Nested Shape: `Agent.protection`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | ✅ | Lock policy — none \| no-overlay \| no-delete \| full. |
+| **reason** | `string` | ✅ | User-visible reason shown when the lock blocks an action. |
+| **docsUrl** | `string` | optional | Optional URL the Studio banner links to for more context. |
+
 
 ---
 

content/docs/references/ai/conversation.mdx

@@ -104,6 +104,30 @@ const result = CodeContentSchema.parse(data);
 | **embedding** | `number[]` | optional | Vector embedding for semantic search |
 | **metadata** | `Record<string, any>` | optional | |
 
+### Nested Shape: `ConversationMessage.functionCall`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **name** | `string` | ✅ | Function name |
+| **arguments** | `string` | ✅ | JSON string of function arguments |
+| **result** | `string` | optional | Function execution result |
+
+### Nested Shape: `ConversationMessage.toolCalls[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Tool call ID |
+| **type** | `Enum<'function'>` | optional (default: `"function"`) | |
+| **function** | `{ name: string; arguments: string; result?: string }` | ✅ | |
+
+### Nested Shape: `ConversationMessage.tokens`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **promptTokens** | `integer` | ✅ | Tokens consumed by the prompt |
+| **completionTokens** | `integer` | ✅ | Tokens generated in the completion |
+| **totalTokens** | `integer` | ✅ | Total tokens (prompt + completion) |
+
 
 ---
 
@@ -128,6 +152,79 @@ const result = CodeContentSchema.parse(data);
 | **expiresAt** | `string` | optional | ISO 8601 timestamp |
 | **metadata** | `Record<string, any>` | optional | |
 
+### Nested Shape: `ConversationSession.context`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **sessionId** | `string` | ✅ | Conversation session ID |
+| **userId** | `string` | optional | User identifier |
+| **agentId** | `string` | optional | AI agent identifier |
+| **object** | `string` | optional | Related object (e.g., "case", "project") |
+| **recordId** | `string` | optional | Related record ID |
+| **scope** | `Record<string, any>` | optional | Additional context scope |
+| **systemMessage** | `string` | optional | System prompt/instructions |
+| **metadata** | `Record<string, any>` | optional | |
+
+### Nested Shape: `ConversationSession.tokenBudget`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **maxTokens** | `integer` | ✅ | Maximum total tokens |
+| **maxPromptTokens** | `integer` | optional | Max tokens for prompt |
+| **maxCompletionTokens** | `integer` | optional | Max tokens for completion |
+| **reserveTokens** | `integer` | optional (default: `500`) | Reserve tokens for system messages |
+| **bufferPercentage** | `number` | optional (default: `0.1`) | Buffer percentage (0.1 = 10%) |
+| **strategy** | `Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>` | optional (default: `"sliding_window"`) | |
+| **slidingWindowSize** | `integer` | optional | Number of recent messages to keep |
+| **minImportanceScore** | `number` | optional | Minimum importance to keep |
+| **semanticThreshold** | `number` | optional | Semantic similarity threshold |
+| **enableSummarization** | `boolean` | optional (default: `false`) | Enable context summarization |
+| **summarizationThreshold** | `integer` | optional | Trigger summarization at N tokens |
+| **summaryModel** | `string` | optional | Model ID for summarization |
+| **warnThreshold** | `number` | optional (default: `0.8`) | Warn at % of budget (0.8 = 80%) |
+
+### Nested Shape: `ConversationSession.messages[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **id** | `string` | ✅ | Unique message ID |
+| **timestamp** | `string` | ✅ | ISO 8601 timestamp |
+| **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ | |
+| **content** | `({ type: 'text'; text: string; metadata?: Record<string, any> } \| { type: 'image'; imageUrl: string; detail: Enum<'low' \| 'high' \| 'auto'>; metadata?: Record<string, any> } \| { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } \| { type: 'code'; text: string; language: string; metadata?: Record<string, any> })[]` | ✅ | Message content (multimodal array) |
+| **functionCall** | `{ name: string; arguments: string; result?: string }` | optional | Legacy function call |
+| **toolCalls** | `{ id: string; type: Enum<'function'>; function: object }[]` | optional | Tool calls |
+| **toolCallId** | `string` | optional | Tool call ID this message responds to |
+| **name** | `string` | optional | Name of the function/user |
+| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Token usage for this message |
+| **cost** | `number` | optional | Cost for this message in USD |
+| **pinned** | `boolean` | optional (default: `false`) | Prevent removal during pruning |
+| **importance** | `number` | optional | Importance score for pruning |
+| **embedding** | `number[]` | optional | Vector embedding for semantic search |
+| **metadata** | `Record<string, any>` | optional | |
+
+### Nested Shape: `ConversationSession.tokens`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **promptTokens** | `integer` | optional (default: `0`) | |
+| **completionTokens** | `integer` | optional (default: `0`) | |
+| **totalTokens** | `integer` | optional (default: `0`) | |
+| **budgetLimit** | `integer` | ✅ | |
+| **budgetUsed** | `integer` | optional (default: `0`) | |
+| **budgetRemaining** | `integer` | ✅ | |
+| **budgetPercentage** | `number` | ✅ | Usage as percentage of budget |
+| **messageCount** | `integer` | optional (default: `0`) | |
+| **prunedMessageCount** | `integer` | optional (default: `0`) | |
+| **summarizedMessageCount** | `integer` | optional (default: `0`) | |
+
+### Nested Shape: `ConversationSession.totalTokens`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **promptTokens** | `integer` | ✅ | Tokens consumed by the prompt |
+| **completionTokens** | `integer` | ✅ | Tokens generated in the completion |
+| **totalTokens** | `integer` | ✅ | Total tokens (prompt + completion) |
+
 
 ---
 
@@ -381,6 +478,14 @@ This schema accepts one of the following structures:
 | **type** | `Enum<'function'>` | optional (default: `"function"`) | |
 | **function** | `{ name: string; arguments: string; result?: string }` | ✅ | |
 
+### Nested Shape: `ToolCall.function`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **name** | `string` | ✅ | Function name |
+| **arguments** | `string` | ✅ | JSON string of function arguments |
+| **result** | `string` | optional | Function execution result |
+
 
 ---
 

content/docs/references/ai/knowledge-source.mdx

@@ -87,6 +87,26 @@ const result = FileKnowledgeSourceSchema.parse(data);
 | **refresh** | `{ onRecordChange?: boolean; cron?: string }` | optional (default: `{}`) | |
 | **aiExposed** | `boolean` | optional (default: `true`) | |
 
+### Nested Shape: `KnowledgeSource.embedding`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **provider** | `Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ | |
+| **model** | `string` | ✅ | Provider-specific model identifier |
+| **dimensions** | `integer` | ✅ | Embedding vector dimensions |
+| **endpoint** | `string` | optional | Custom endpoint URL |
+| **secretRef** | `string` | optional | Reference to stored API key secret |
+
+### Nested Shape: `KnowledgeSource.vectorStore`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **provider** | `Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| …>` | ✅ | |
+| **collection** | `string` | ✅ | Collection / index / namespace name |
+| **endpoint** | `string` | optional | Connection string or endpoint URL |
+| **secretRef** | `string` | optional | Reference to stored credential secret |
+| **dimensions** | `integer` | optional | |
+
 
 ---