Merge origin/main (take main's regenerated reference docs; regenerate next)

Author: claude

.changeset/eighty-donkeys-repeat.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/spec": patch
+---
+
+Reference docs: import examples are now spelled from the package's real export surface
+
+`build-docs.ts` derived each page's "TypeScript Usage" block from the JSON Schema file
+name — the value import verbatim, the `import type` line with a `Schema` suffix stripped —
+and nothing verified either name existed. `check:docs` could not catch it: it diffs the
+generator's output against the committed docs, so a name the generator invents stays "in
+sync" with itself forever. 150 of the committed `import type` names did not compile, and
+the `.parse()` example called a type rather than the schema const.
+
+Both lines are now resolved against `api-surface.json`, the committed record of every
+`name (kind)` per entry point: only names the entry really exports are emitted, and the
+example parses with the actual schema const. A name that resolves to nothing is dropped
+from the page and recorded in the new `docs-import-surface.baseline.json` — a shrink-only
+ratchet, so removing a type alias while its schema keeps a reference page now turns
+`check:docs` red instead of silently publishing a dead import.

content/docs/references/ai/agent.mdx

@@ -14,11 +14,11 @@ AI Model Configuration
 ## TypeScript Usage
 
 ```typescript
-import { AIModelConfig, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';
-import type { AIModelConfig, Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';
+import { AIModelConfigSchema, AgentSchema, StructuredOutputConfigSchema, StructuredOutputFormatSchema, TransformPipelineStepSchema } from '@objectstack/spec/ai';
+import type { Agent, StructuredOutputConfig, StructuredOutputFormat, TransformPipelineStep } from '@objectstack/spec/ai';
 
 // Validate data
-const result = AIModelConfig.parse(data);
+const result = AIModelConfigSchema.parse(data);
 ```
 
 ---

content/docs/references/ai/conversation.mdx

@@ -18,11 +18,11 @@ Enables context preservation, conversation history, and token optimization.
 ## TypeScript Usage
 
 ```typescript
-import { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
-import type { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
+import { CodeContentSchema, ConversationAnalyticsSchema, ConversationContextSchema, ConversationMessageSchema, ConversationSessionSchema, ConversationSummarySchema, FileContentSchema, FunctionCallSchema, ImageContentSchema, MessageContentSchema, MessageContentTypeSchema, MessagePruningEventSchema, MessageRoleSchema, TextContentSchema, TokenBudgetConfigSchema, TokenBudgetStrategySchema, TokenUsageStatsSchema, ToolCallSchema } from '@objectstack/spec/ai';
+import type { ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FunctionCall, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
 
 // Validate data
-const result = CodeContent.parse(data);
+const result = CodeContentSchema.parse(data);
 ```
 
 ---

content/docs/references/ai/embedding.mdx

@@ -38,11 +38,11 @@ vector primitives so any RAG strategy can be built on top.
 ## TypeScript Usage
 
 ```typescript
-import { EmbeddingModel, VectorStore, VectorStoreProvider } from '@objectstack/spec/ai';
+import { EmbeddingModelSchema, VectorStoreSchema, VectorStoreProviderSchema } from '@objectstack/spec/ai';
 import type { EmbeddingModel, VectorStore, VectorStoreProvider } from '@objectstack/spec/ai';
 
 // Validate data
-const result = EmbeddingModel.parse(data);
+const result = EmbeddingModelSchema.parse(data);
 ```
 
 ---

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

@@ -26,11 +26,11 @@ See `content/docs/protocol/knowledge.mdx` for the full design.
 ## TypeScript Usage
 
 ```typescript
-import { KnowledgeChunk, KnowledgeDocument, KnowledgeHit } from '@objectstack/spec/ai';
+import { KnowledgeChunkSchema, KnowledgeDocumentSchema, KnowledgeHitSchema } from '@objectstack/spec/ai';
 import type { KnowledgeChunk, KnowledgeDocument, KnowledgeHit } from '@objectstack/spec/ai';
 
 // Validate data
-const result = KnowledgeChunk.parse(data);
+const result = KnowledgeChunkSchema.parse(data);
 ```
 
 ---

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

@@ -28,11 +28,11 @@ See `content/docs/protocol/knowledge.mdx` for the full design.
 ## TypeScript Usage
 
 ```typescript
-import { FileKnowledgeSource, HttpKnowledgeSource, KnowledgeRefreshPolicy, KnowledgeSource, KnowledgeSourceKind, ObjectKnowledgeSource } from '@objectstack/spec/ai';
+import { FileKnowledgeSourceSchema, HttpKnowledgeSourceSchema, KnowledgeRefreshPolicySchema, KnowledgeSourceSchema, KnowledgeSourceKindSchema, ObjectKnowledgeSourceSchema } from '@objectstack/spec/ai';
 import type { FileKnowledgeSource, HttpKnowledgeSource, KnowledgeRefreshPolicy, KnowledgeSource, KnowledgeSourceKind, ObjectKnowledgeSource } from '@objectstack/spec/ai';
 
 // Validate data
-const result = FileKnowledgeSource.parse(data);
+const result = FileKnowledgeSourceSchema.parse(data);
 ```
 
 ---

content/docs/references/ai/mcp.mdx

@@ -40,11 +40,11 @@ at runtime and does not need a metadata representation.
 ## TypeScript Usage
 
 ```typescript
-import { MCPApprovalPolicy, MCPServerRef, MCPToolBinding, MCPTransport } from '@objectstack/spec/ai';
+import { MCPApprovalPolicySchema, MCPServerRefSchema, MCPToolBindingSchema, MCPTransportSchema } from '@objectstack/spec/ai';
 import type { MCPApprovalPolicy, MCPServerRef, MCPToolBinding, MCPTransport } from '@objectstack/spec/ai';
 
 // Validate data
-const result = MCPApprovalPolicy.parse(data);
+const result = MCPApprovalPolicySchema.parse(data);
 ```
 
 ---

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

@@ -18,11 +18,11 @@ Enables AI-powered ObjectStack applications to discover and use LLMs consistentl
 ## TypeScript Usage
 
 ```typescript
-import { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai';
+import { ModelCapabilitySchema, ModelConfigSchema, ModelLimitsSchema, ModelPricingSchema, ModelProviderSchema, ModelRegistrySchema, ModelRegistryEntrySchema, ModelSelectionCriteriaSchema, PromptTemplateSchema, PromptVariableSchema } from '@objectstack/spec/ai';
 import type { ModelCapability, ModelConfig, ModelLimits, ModelPricing, ModelProvider, ModelRegistry, ModelRegistryEntry, ModelSelectionCriteria, PromptTemplate, PromptVariable } from '@objectstack/spec/ai';
 
 // Validate data
-const result = ModelCapability.parse(data);
+const result = ModelCapabilitySchema.parse(data);
 ```
 
 ---

content/docs/references/ai/skill.mdx

@@ -18,11 +18,11 @@ Allows context-aware activation based on object type, user role, etc.
 ## TypeScript Usage
 
 ```typescript
-import { Skill, SkillTriggerCondition } from '@objectstack/spec/ai';
+import { SkillSchema, SkillTriggerConditionSchema } from '@objectstack/spec/ai';
 import type { Skill, SkillTriggerCondition } from '@objectstack/spec/ai';
 
 // Validate data
-const result = Skill.parse(data);
+const result = SkillSchema.parse(data);
 ```
 
 ---

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

@@ -34,11 +34,11 @@ batch-draft. This is the safety valve for low-specificity input.
 ## TypeScript Usage
 
 ```typescript
-import { BlueprintApp, BlueprintCondition, BlueprintDashboard, BlueprintField, BlueprintNavItem, BlueprintObject, BlueprintSeed, BlueprintSummaryOperations, BlueprintView, BlueprintWidgetCondition, SolutionBlueprint, SolutionBlueprintStrict } from '@objectstack/spec/ai';
+import { BlueprintAppSchema, BlueprintConditionSchema, BlueprintDashboardSchema, BlueprintFieldSchema, BlueprintNavItemSchema, BlueprintObjectSchema, BlueprintSeedSchema, BlueprintSummaryOperationsSchema, BlueprintViewSchema, BlueprintWidgetConditionSchema, SolutionBlueprintSchema, SolutionBlueprintStrictSchema } from '@objectstack/spec/ai';
 import type { BlueprintApp, BlueprintCondition, BlueprintDashboard, BlueprintField, BlueprintNavItem, BlueprintObject, BlueprintSeed, BlueprintSummaryOperations, BlueprintView, BlueprintWidgetCondition, SolutionBlueprint, SolutionBlueprintStrict } from '@objectstack/spec/ai';
 
 // Validate data
-const result = BlueprintApp.parse(data);
+const result = BlueprintAppSchema.parse(data);
 ```
 
 ---