fix(#4570): spell reference-doc import examples from the 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 — on the assumption that both names exist. Nothing
verified it, and `check:docs` structurally could not: it diffs the generator's
output against the committed docs, so a name the generator invents stays "in
sync" with itself forever.

Compiling the committed `import type` lines against `packages/spec/src` gives
150 `has no exported member` errors, and every `.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 public entry point:

  - value import: `<Name>Schema` when the entry exports it, else `<Name>` (a
    merged `export const Foo = z.enum(…)` + `export type Foo` is reported as
    `type` by kindOf, so presence — not kind — is the sound signal there);
  - type import: `<Name>` only when the entry exports it with a type-bearing
    kind, which kindOf's TypeAlias-before-Variable ordering makes decidable;
  - the example parses with the resolved 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 #4539's scenario
(deleting a zero-consumer type alias while its schema keeps its reference page)
now turns `check:docs` red instead of silently publishing a dead import. The
baseline is regenerated only by an explicit `--update-import-baseline`, never by
a `gen:` script, for the same reason the dual-source baseline is (#4446).

225 reference pages regenerate with corrected imports. The 154 accepted gaps
are 150 schemas with no exported type alias (#4593) and 4 whose names are
mangled by a first-occurrence `replace('Schema','')` in build-schemas.ts (#4592).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5

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);
 ```
 
 ---