objectstack-ai · hotlong · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026
diff --git a/content/docs/references/ai/feedback-loop.mdx b/content/docs/references/ai/feedback-loop.mdx
@@ -12,27 +12,13 @@ description: Feedback Loop protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { FeedbackLoop, Issue, Resolution } from '@objectstack/spec/ai';
-import type { FeedbackLoop, Issue, Resolution } from '@objectstack/spec/ai';
+import { Issue } from '@objectstack/spec/ai';
+import type { Issue } from '@objectstack/spec/ai';
 
 // Validate data
-const result = FeedbackLoop.parse(data);
+const result = Issue.parse(data);
 ```
 
----
-
-## FeedbackLoop
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **issue** | `Object` | ✅ |  |
-| **analysis** | `string` | optional | AI analysis of the root cause |
-| **resolutions** | `Object[]` | optional |  |
-| **status** | `Enum<'open' \| 'analyzing' \| 'resolved' \| 'ignored'>` | ✅ |  |
-
-
 ---
 
 ## Issue
@@ -53,17 +39,3 @@ const result = FeedbackLoop.parse(data);
 
 ---
 
-## Resolution
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **issueId** | `string` | ✅ |  |
-| **reasoning** | `string` | ✅ | Explanation of why this fix is needed |
-| **confidence** | `number` | ✅ |  |
-| **fix** | `Object \| Object` | ✅ |  |
-
-
----
-
diff --git a/content/docs/references/api/contract.mdx b/content/docs/references/api/contract.mdx
@@ -154,7 +154,7 @@ const result = ApiError.parse(data);
 | **having** | `[__schema2](./__schema2)` | optional | HAVING clause for aggregation filtering |
 | **windowFunctions** | `Object[]` | optional | Window functions with OVER clause |
 | **distinct** | `boolean` | optional | SELECT DISTINCT flag |
-| **expand** | `Record<string, [__schema0](./__schema0)>` | optional | Recursive relation loading (nested queries) |
+| **expand** | `Record<string, [__schema0](./__schema0)>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3. |
 
 
 ---

diff --git a/content/docs/references/api/metadata.mdx b/content/docs/references/api/metadata.mdx
@@ -50,8 +50,8 @@ the entire platform, including Hono, Next.js, and NestJS adapters.
 ## TypeScript Usage
 
 ```typescript
-import { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
-import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse, ObjectDefinitionResponse } from '@objectstack/spec/api';
+import { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse } from '@objectstack/spec/api';
+import type { AppDefinitionResponse, ConceptListResponse, MetadataBulkResponse, MetadataBulkUnregisterRequest, MetadataDeleteResponse, MetadataDependenciesResponse, MetadataDependentsResponse, MetadataEffectiveResponse, MetadataExistsResponse, MetadataExportRequest, MetadataExportResponse, MetadataImportRequest, MetadataImportResponse, MetadataItemResponse, MetadataListResponse, MetadataNamesResponse, MetadataOverlayResponse, MetadataOverlaySaveRequest, MetadataQueryRequest, MetadataQueryResponse, MetadataRegisterRequest, MetadataTypeInfoResponse, MetadataTypesResponse, MetadataValidateRequest, MetadataValidateResponse } from '@objectstack/spec/api';
 
 // Validate data
 const result = AppDefinitionResponse.parse(data);
@@ -425,17 +425,3 @@ Metadata query with filtering, sorting, and pagination
 
 ---
 
-## ObjectDefinitionResponse
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **success** | `boolean` | ✅ | Operation success status |
-| **error** | `Object` | optional | Error details if success is false |
-| **meta** | `Object` | optional | Response metadata |
-| **data** | `Object` | ✅ | Full Object Schema |
-
-
----
-
diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx
@@ -226,7 +226,7 @@ const result = ODataConfig.parse(data);
 | **$orderby** | `string \| string[]` | optional | Sort order |
 | **$top** | `integer` | optional | Max results to return |
 | **$skip** | `integer` | optional | Results to skip |
-| **$expand** | `string \| string[]` | optional | Navigation properties to expand |
+| **$expand** | `string \| string[]` | optional | Navigation properties to expand (lookup/master_detail fields) |
 | **$count** | `boolean` | optional | Include total count |
 | **$search** | `string` | optional | Search expression |
 | **$format** | `Enum<'json' \| 'xml' \| 'atom'>` | optional | Response format |

diff --git a/content/docs/references/api/protocol.mdx b/content/docs/references/api/protocol.mdx
@@ -395,7 +395,7 @@ const result = AiChatRequest.parse(data);
 | **object** | `string` | ✅ | The object name. |
 | **id** | `string` | ✅ | The unique record identifier (primary key). |
 | **select** | `string[]` | optional | Fields to include in the response (allowlisted query param). |
-| **expand** | `string[]` | optional | Relations to eager-load (allowlisted query param). |
+| **expand** | `string[]` | optional | Lookup/master_detail field names to expand. The engine resolves these via batch $in queries, replacing foreign key IDs with full objects. |
 
 
 ---
@@ -782,7 +782,7 @@ const result = AiChatRequest.parse(data);
 | **orderBy** | `string` | optional | Alias for sort (OData compatibility). |
 | **top** | `number` | optional | Max records to return (limit). |
 | **skip** | `number` | optional | Records to skip (offset). |
-| **expand** | `string` | optional | Comma-separated list of relations to eager-load. |
+| **expand** | `string` | optional | Comma-separated list of lookup/master_detail field names to expand. Resolved to populate array and passed to the engine for batch $in expansion. |
 | **search** | `string` | optional | Full-text search query. |
 | **distinct** | `boolean` | optional | SELECT DISTINCT flag. |
 | **count** | `boolean` | optional | Include total count in response. |

diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx
@@ -115,7 +115,7 @@ const result = Address.parse(data);
 | **min** | `number` | optional | Minimum value |
 | **max** | `number` | optional | Maximum value |
 | **options** | `Object[]` | optional | Static options for select/multiselect |
-| **reference** | `string` | optional | Target Object Name |
+| **reference** | `string` | optional | Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. |
 | **referenceFilters** | `string[]` | optional | Filters applied to lookup dialogs (e.g. "active = true") |
 | **writeRequiresMasterRead** | `boolean` | optional | If true, user needs read access to master record to edit this field |
 | **deleteBehavior** | `Enum<'set_null' \| 'cascade' \| 'restrict'>` | ✅ | What happens if referenced record is deleted |

diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx
@@ -14,8 +14,8 @@ API Operations Enum
 ## TypeScript Usage
 
 ```typescript
-import { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
-import type { ApiMethod, CDCConfig, Index, Object, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
+import { ApiMethod, CDCConfig, Index, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
+import type { ApiMethod, CDCConfig, Index, ObjectCapabilities, ObjectExtension, ObjectOwnershipEnum, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
 
 // Validate data
 const result = ApiMethod.parse(data);
@@ -71,45 +71,6 @@ const result = ApiMethod.parse(data);
 | **partial** | `string` | optional | Partial index condition (SQL WHERE clause for conditional indexes) |
 
 
----
-
-## Object
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **name** | `string` | ✅ | Machine unique key (snake_case). Immutable. |
-| **label** | `string` | optional | Human readable singular label (e.g. "Account") |
-| **pluralLabel** | `string` | optional | Human readable plural label (e.g. "Accounts") |
-| **description** | `string` | optional | Developer documentation / description |
-| **icon** | `string` | optional | Icon name (Lucide/Material) for UI representation |
-| **tags** | `string[]` | optional | Categorization tags (e.g. "sales", "system", "reference") |
-| **active** | `boolean` | ✅ | Is the object active and usable |
-| **isSystem** | `boolean` | ✅ | Is system object (protected from deletion) |
-| **abstract** | `boolean` | ✅ | Is abstract base object (cannot be instantiated) |
-| **datasource** | `string` | ✅ | Target Datasource ID. "default" is the primary DB. |
-| **tableName** | `string` | optional | Physical table/collection name in the target datasource |
-| **fields** | `Record<string, Object>` | ✅ | Field definitions map. Keys must be snake_case identifiers. |
-| **indexes** | `Object[]` | optional | Database performance indexes |
-| **tenancy** | `Object` | optional | Multi-tenancy configuration for SaaS applications |
-| **softDelete** | `Object` | optional | Soft delete (trash/recycle bin) configuration |
-| **versioning** | `Object` | optional | Record versioning and history tracking configuration |
-| **partitioning** | `Object` | optional | Table partitioning configuration for performance |
-| **cdc** | `Object` | optional | Change Data Capture (CDC) configuration for real-time data streaming |
-| **validations** | `[__schema0](./__schema0)[]` | optional | Object-level validation rules |
-| **stateMachines** | `Record<string, Object>` | optional | Named state machines for parallel lifecycles (e.g., status, payment, approval) |
-| **displayNameField** | `string` | optional | Field to use as the record display name (e.g., "name", "title"). Defaults to "name" if present. |
-| **recordName** | `Object` | optional | Record name generation configuration (Salesforce pattern) |
-| **titleFormat** | `string` | optional | Title expression (e.g. "`{name}` - `{code}`"). Overrides displayNameField. |
-| **compactLayout** | `string[]` | optional | Primary fields for hover/cards/lookups |
-| **search** | `Object` | optional | Search engine configuration |
-| **enable** | `Object` | optional | Enabled system features modules |
-| **recordTypes** | `string[]` | optional | Record type names for this object |
-| **sharingModel** | `Enum<'private' \| 'read' \| 'read_write' \| 'full'>` | optional | Default sharing model |
-| **keyPrefix** | `string` | optional | Short prefix for record IDs (e.g., "001" for Account) |
-
-
 ---
 
 ## ObjectCapabilities

diff --git a/content/docs/references/data/query.mdx b/content/docs/references/data/query.mdx
@@ -162,7 +162,7 @@ Type: `string`
 | **having** | `[__schema1](./__schema1)` | optional | HAVING clause for aggregation filtering |
 | **windowFunctions** | `Object[]` | optional | Window functions with OVER clause |
 | **distinct** | `boolean` | optional | SELECT DISTINCT flag |
-| **expand** | `Record<string, [#](./#)>` | optional | Recursive relation loading (nested queries) |
+| **expand** | `Record<string, [#](./#)>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3. |
 
 
 ---

diff --git a/content/docs/references/integration/meta.json b/content/docs/references/integration/meta.json
@@ -8,6 +8,7 @@
     "misc",
     "object-storage",
     "offline",
-    "tenant"
+    "tenant",
+    "translation"
   ]
 }
diff --git a/content/docs/references/integration/misc.mdx b/content/docs/references/integration/misc.mdx
@@ -12,8 +12,8 @@ description: Misc protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration';
-import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageFormat, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration';
+import { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration';
+import type { AckMode, ApiVersionConfig, BuildConfig, CdcConfig, DatabaseConnector, DatabasePoolConfig, DatabaseTable, DeliveryGuarantee, DeploymentConfig, DlqConfig, DomainConfig, EdgeFunctionConfig, EnvironmentVariables, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, GitHubActionsWorkflow, GitHubCommitConfig, GitHubConnector, GitHubIssueTracking, GitHubProvider, GitHubPullRequestConfig, GitHubReleaseConfig, GitHubRepository, GitRepositoryConfig, MessageQueueConnector, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue, VercelConnector, VercelFramework, VercelMonitoring, VercelProject, VercelProvider, VercelTeam } from '@objectstack/spec/integration';
 
 // Validate data
 const result = AckMode.parse(data);
@@ -521,22 +521,6 @@ GitHub provider type
 | **autoDeployPreview** | `boolean` | ✅ | Auto-deploy preview branches |
 
 
----
-
-## MessageFormat
-
-Message format/serialization
-
-### Allowed Values
-
-* `json`
-* `xml`
-* `protobuf`
-* `avro`
-* `text`
-* `binary`
-
-
 ---
 
 ## MessageQueueConnector

diff --git a/content/docs/references/integration/translation.mdx b/content/docs/references/integration/translation.mdx
@@ -0,0 +1,39 @@
+---
+title: Translation
+description: Translation protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
+
+<Callout type="info">
+**Source:** `packages/spec/src/integration/translation.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { MessageFormat } from '@objectstack/spec/integration';
+import type { MessageFormat } from '@objectstack/spec/integration';
+
+// Validate data
+const result = MessageFormat.parse(data);
+```
+
+---
+
+## MessageFormat
+
+Message format/serialization
+
+### Allowed Values
+
+* `json`
+* `xml`
+* `protobuf`
+* `avro`
+* `text`
+* `binary`
+
+
+---
+