fix(spec-docs): one shared def renders one optionality face on every reference page

content/docs/references/ai/agent.mdx

@@ -48,7 +48,7 @@ const result = AIModelConfigSchema.parse(data);
 | **avatar** | `string` | optional |  |
 | **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") |
 | **instructions** | `string` | ✅ | System Prompt / Prime Directives |
-| **model** | `{ provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature: number; maxTokens?: number; … }` | optional |  |
+| **model** | `{ provider?: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature?: number; maxTokens?: number; … }` | optional |  |
 | **lifecycle** | `never` | optional | [REMOVED] `agent.lifecycle` was removed in @objectstack/spec 17.7.0 (ADR-0049 enforce-or-remove) — no runtime ever read it: no agent moved through a declared state and no transition was ever refused. Delete the key. A phase of a conversation is a skill with its own `instructions` and `tools`, selected by its `triggerConditions` (ADR-0064); multi-step process orchestration is a Flow (ADR-0019); a record's status transitions are a `state_machine` validation rule on the object (ADR-0020). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
 | **surface** | `Enum<'ask' \| 'build'>` | optional (default: `"ask"`) | Product surface this agent binds ('ask' \| 'build') — ADR-0063 §1 |
 | **skills** | `string[]` | optional | Skill names to attach (Agent→Skill→Tool architecture) |
@@ -57,10 +57,10 @@ const result = AIModelConfigSchema.parse(data);
 | **active** | `boolean` | optional (default: `true`) |  |
 | **access** | `string[]` | optional | Who can chat with this agent |
 | **permissions** | `string[]` | optional | Required permission-set capabilities |
-| **planning** | `{ maxIterations: integer }` | optional | Autonomous reasoning and planning configuration |
+| **planning** | `{ maxIterations?: integer }` | optional | Autonomous reasoning and planning configuration |
 | **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory (long-term notes recalled before each conversation and written by periodic reflection), enforced by the cloud AI runtime; the open framework edition does not run agents. |
 | **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent (token budget, time limit, blocked topics), enforced per user turn by the cloud AI runtime; the open framework edition does not run agents. |
-| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output contract for the agent's final answer (JSON format, schema, retries, fallback format, transform steps), enforced on every final answer by the cloud AI runtime; the open framework edition does not run agents. |
+| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema'>; schema?: Record<string, any>; strict?: boolean; retryOnValidationFailure?: boolean; … }` | optional | Structured output contract for the agent's final answer (JSON format, schema, retries, fallback format, transform steps), enforced on every final answer by the cloud AI runtime; the open framework edition does not run agents. |
 | **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | optional | Package author protection block — lock policy for this agent. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
@@ -90,7 +90,7 @@ const result = AIModelConfigSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **longTerm** | `{ enabled: boolean; maxEntries?: integer }` | optional | Long-term memory: distilled notes kept per user and agent and recalled before each conversation |
+| **longTerm** | `{ enabled?: boolean; maxEntries?: integer }` | optional | Long-term memory: distilled notes kept per user and agent and recalled before each conversation |
 | **reflectionInterval** | `integer` | optional | Reflect every N delivered interactions: each reflection writes one distilled note to long-term memory. Required when longTerm.enabled is true, and refused without it |
 
 ### Nested Shape: `Agent.guardrails`

content/docs/references/ai/conversation.mdx

@@ -94,9 +94,9 @@ const result = CodeContentSchema.parse(data);
 | **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) |
+| **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 |
+| **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 |
@@ -179,9 +179,9 @@ const result = CodeContentSchema.parse(data);
 | **name** | `string` | optional | Session name/title |
 | **context** | `{ sessionId: string; userId?: string; agentId?: string; object?: string; … }` | ✅ |  |
 | **modelId** | `string` | optional | AI model ID |
-| **tokenBudget** | `{ maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens: integer; … }` | ✅ |  |
+| **tokenBudget** | `{ maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens?: integer; … }` | ✅ |  |
 | **messages** | `{ id: string; timestamp: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; content: (object \| … +3 more)[]; … }[]` | optional (default: `[]`) |  |
-| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer; budgetLimit: integer; … }` | optional |  |
+| **tokens** | `{ promptTokens?: integer; completionTokens?: integer; totalTokens?: integer; budgetLimit: integer; … }` | optional |  |
 | **totalTokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Total tokens across all messages |
 | **totalCost** | `number` | optional | Total cost for this session in USD |
 | **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | optional (default: `"active"`) |  |
@@ -228,9 +228,9 @@ const result = CodeContentSchema.parse(data);
 | **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) |
+| **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 |
+| **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 |

content/docs/references/ai/model-registry.mdx

@@ -54,9 +54,9 @@ const result = ModelCapabilitySchema.parse(data);
 | **name** | `string` | ✅ | Model display name |
 | **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") |
 | **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ |  |
-| **capabilities** | `{ textGeneration: boolean; textEmbedding: boolean; imageGeneration: boolean; imageUnderstanding: boolean; … }` | ✅ |  |
+| **capabilities** | `{ textGeneration?: boolean; textEmbedding?: boolean; imageGeneration?: boolean; imageUnderstanding?: boolean; … }` | ✅ |  |
 | **limits** | `{ maxTokens: integer; contextWindow: integer; maxOutputTokens?: integer; rateLimit?: object }` | ✅ |  |
-| **pricing** | `{ currency: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional |  |
+| **pricing** | `{ currency?: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional |  |
 | **endpoint** | `string` | optional | Custom API endpoint |
 | **apiKey** | `string` | optional | API key (Warning: Prefer secretRef) |
 | **secretRef** | `string` | optional | Reference to stored secret (e.g. system:openai_api_key) |
@@ -202,7 +202,7 @@ const result = ModelCapabilitySchema.parse(data);
 | **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | optional (default: `"active"`) |  |
 | **priority** | `integer` | optional (default: `0`) | Priority for model selection |
 | **fallbackModels** | `string[]` | optional | Fallback model IDs |
-| **healthCheck** | `{ enabled: boolean; intervalSeconds: integer; lastChecked?: string; status: Enum<'healthy' \| 'unhealthy' \| 'unknown'> }` | optional |  |
+| **healthCheck** | `{ enabled?: boolean; intervalSeconds?: integer; lastChecked?: string; status?: Enum<'healthy' \| 'unhealthy' \| 'unknown'> }` | optional |  |
 
 ### Nested Shape: `ModelRegistryEntry.model`
 
@@ -212,9 +212,9 @@ const result = ModelCapabilitySchema.parse(data);
 | **name** | `string` | ✅ | Model display name |
 | **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") |
 | **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ |  |
-| **capabilities** | `{ textGeneration: boolean; textEmbedding: boolean; imageGeneration: boolean; imageUnderstanding: boolean; … }` | ✅ |  |
+| **capabilities** | `{ textGeneration?: boolean; textEmbedding?: boolean; imageGeneration?: boolean; imageUnderstanding?: boolean; … }` | ✅ |  |
 | **limits** | `{ maxTokens: integer; contextWindow: integer; maxOutputTokens?: integer; rateLimit?: object }` | ✅ |  |
-| **pricing** | `{ currency: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional |  |
+| **pricing** | `{ currency?: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional |  |
 | **endpoint** | `string` | optional | Custom API endpoint |
 | **apiKey** | `string` | optional | API key (Warning: Prefer secretRef) |
 | **secretRef** | `string` | optional | Reference to stored secret (e.g. system:openai_api_key) |

content/docs/references/ai/solution-blueprint.mdx

@@ -45,7 +45,7 @@ const result = BlueprintAppSchema.parse(data);
 | **name** | `string` | ✅ | App machine name (snake_case) |
 | **label** | `string` | optional | App display label |
 | **icon** | `string` | optional | Lucide icon for the App Launcher |
-| **nav** | `{ type: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string; … }[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard |
+| **nav** | `{ type?: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string; … }[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard |
 
 ### Nested Shape: `BlueprintApp.nav[number]`
 
@@ -298,7 +298,7 @@ const result = BlueprintAppSchema.parse(data);
 | **assumptions** | `string[]` | optional (default: `[]`) | Design assumptions made from the underspecified goal |
 | **questions** | `string[]` | optional | At most 1-2 structure-deciding questions to confirm before building |
 | **objects** | `{ name: string; label?: string; description?: string; fields: object[]; … }[]` | ✅ | Objects (tables) to create |
-| **views** | `{ object: string; name: string; label?: string; type: Enum<'list' \| 'form' \| 'kanban' \| 'calendar' \| 'gallery' \| 'gantt'>; … }[]` | optional | Views to create |
+| **views** | `{ object: string; name: string; label?: string; type?: Enum<'list' \| 'form' \| 'kanban' \| 'calendar' \| 'gallery' \| 'gantt'>; … }[]` | optional | Views to create |
 | **dashboards** | `{ name: string; label?: string; widgets?: object[] }[]` | optional | Dashboards to create |
 | **app** | `{ name: string; label?: string; icon?: string; nav?: object[] }` | optional | The navigation shell (app) that surfaces the created objects/dashboards to end users |
 | **seedData** | `{ object: string; records: Record<string, any>[] }[]` | optional | Suggested seed data (reported, not auto-applied in Phase C) |
@@ -340,7 +340,7 @@ const result = BlueprintAppSchema.parse(data);
 | **name** | `string` | ✅ | App machine name (snake_case) |
 | **label** | `string` | optional | App display label |
 | **icon** | `string` | optional | Lucide icon for the App Launcher |
-| **nav** | `{ type: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string; … }[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard |
+| **nav** | `{ type?: Enum<'object' \| 'dashboard'>; target: string; label?: string; icon?: string; … }[]` | optional | Navigation entries; omit to auto-surface every created object and dashboard |
 
 ### Nested Shape: `SolutionBlueprint.seedData[number]`
 

content/docs/references/api/auth-endpoints.mdx

@@ -156,8 +156,8 @@ This schema accepts one of the following structures:
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **emailPassword** | `{ enabled: boolean; disableSignUp?: boolean; requireEmailVerification?: boolean }` | ✅ | Email/password authentication config |
-| **socialProviders** | `{ id: string; name: string; enabled: boolean; type: Enum<'social' \| 'oidc'> }[]` | ✅ | Available social/OAuth providers |
-| **features** | `{ twoFactor: boolean; organization: boolean; ssoEnforced?: boolean; phoneNumber?: boolean; … }` | ✅ | Enabled authentication features |
+| **socialProviders** | `{ id: string; name: string; enabled: boolean; type?: Enum<'social' \| 'oidc'> }[]` | ✅ | Available social/OAuth providers |
+| **features** | `{ twoFactor?: boolean; organization?: boolean; ssoEnforced?: boolean; phoneNumber?: boolean; … }` | ✅ | Enabled authentication features |
 
 ### Nested Shape: `GetAuthConfigResponse.emailPassword`
 

content/docs/references/api/auth.mdx

@@ -150,7 +150,7 @@ const result = AuthProvider.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **session** | `{ id: string; expiresAt: string; token?: string; ipAddress?: string; … }` | ✅ | Active Session Info |
-| **user** | `{ id: string; email: string; emailVerified: boolean; name: string; … }` | ✅ | Current User Details |
+| **user** | `{ id: string; email: string; emailVerified?: boolean; name: string; … }` | ✅ | Current User Details |
 | **token** | `string` | optional | Bearer token if not using cookies |
 
 
@@ -187,7 +187,7 @@ const result = AuthProvider.parse(data);
 | **success** | `boolean` | ✅ | Operation success status |
 | **error** | `{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }` | optional | Error details if success is false |
 | **meta** | `{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }` | optional | Response metadata |
-| **data** | `{ id: string; email: string; emailVerified: boolean; name: string; … }` | ✅ |  |
+| **data** | `{ id: string; email: string; emailVerified?: boolean; name: string; … }` | ✅ |  |
 
 ### Nested Shape: `UserProfileResponse.error`