docs(generator): fix reference $ref links and opaque Object types; re-arm link CI

The 243 generated reference pages carried ~92 links to a page that never
existed (`[__schema0](./__schema0)`), 6 self-links to `(./#)`, and every
inline object rendered as an opaque `Object`. Root causes, all in
build-docs.ts:

- `formatType` turned `$ref` into `./<schemaName>`, but pages are named
  after the *zod file* — so no `$ref` link could ever resolve. Named refs
  now resolve through the schemaCategoryMap/schemaZodFileMap that
  scanCategories() already built (dead code until now) to
  `/docs/references/<category>/<file>#<schema>`, and fall back to plain
  text rather than a 404 when no page exists.
- `__schemaN` refs are Zod-hoisted inline schemas with no page at all;
  they are now expanded structurally, with a cycle guard (these schemas
  are recursive — a node contains nodes — and naive inlining blows the
  stack).
- `$ref: "#"` (self-reference) now links to the section's own anchor.
- Inline objects render their shape one level deep
  (`{ label: string; value: string; color?: string; … }`) instead of
  `Object`; const variants render their literal, so discriminated unions
  read as `'a' | 'b'` rather than `Object | Object`.
- JSDoc `{@link ../automation/sync.zod.ts}` linked to a repo path that
  404s on the site; source paths now rewrite to their docs route, and a
  bare `@see` renders as "See also:" prose instead of a stray tag.

Counts after regenerating: __schemaN links 92 → 0, (./#) 6 → 0,
zod.ts links → 0.

Re-arms the link CI, which is why this drifted: check-links.yml had its
push/pull_request triggers commented out, leaving only manual dispatch.
It now runs on PRs touching content/, scoped by paths so unrelated PRs
don't pay for it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.github/workflows/check-links.yml

@@ -2,12 +2,14 @@ name: Check Links
 
 on:
   workflow_dispatch:
-  # push:
-  #   branches:
-  #     - main
-  # pull_request:
-  #   branches:
-  #     - main
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'content/**'
+      - 'README.md'
+      - 'lychee.toml'
+      - '.github/workflows/check-links.yml'
 
 jobs:
   link-checker:

content/docs/references/ai/agent.mdx

@@ -74,22 +74,22 @@ const result = AIKnowledge.parse(data);
 | **avatar** | `string` | optional |  |
 | **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") |
 | **instructions** | `string` | ✅ | System Prompt / Prime Directives |
-| **model** | `Object` | optional |  |
-| **lifecycle** | `Object` | optional | State machine defining the agent conversation follow and constraints |
+| **model** | `{ provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature: number; maxTokens?: number; … }` | optional |  |
+| **lifecycle** | `{ id: string; description?: string; contextSchema?: Record<string, any>; initial: string; … }` | optional | State machine defining the agent conversation follow and constraints |
 | **surface** | `Enum<'ask' \| 'build'>` | ✅ | Product surface this agent binds ('ask' \| 'build') — ADR-0063 §1 |
 | **skills** | `string[]` | optional | Skill names to attach (Agent→Skill→Tool architecture) |
-| **tools** | `Object[]` | optional | Direct tool references (legacy fallback) |
-| **knowledge** | `Object` | optional | RAG access |
+| **tools** | `{ type: Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>; name: string; description?: string }[]` | optional | Direct tool references (legacy fallback) |
+| **knowledge** | `{ topics: string[]; indexes: string[] }` | optional | RAG access |
 | **active** | `boolean` | ✅ |  |
 | **access** | `string[]` | optional | Who can chat with this agent |
 | **permissions** | `string[]` | optional | Required permission-set capabilities |
 | **tenantId** | `string` | optional | Tenant/Organization ID |
 | **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ | [EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating. |
-| **planning** | `Object` | optional | Autonomous reasoning and planning configuration |
-| **memory** | `Object` | optional | Agent memory management |
-| **guardrails** | `Object` | optional | Safety guardrails for the agent |
-| **structuredOutput** | `Object` | optional | Structured output format and validation configuration |
-| **protection** | `Object` | optional | Package author protection block — lock policy for this agent. |
+| **planning** | `{ strategy: Enum<'react' \| 'plan_and_execute' \| 'reflexion' \| 'tree_of_thought'>; maxIterations: integer; allowReplan: boolean }` | optional | Autonomous reasoning and planning configuration |
+| **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory management |
+| **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent |
+| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output format and validation configuration |
+| **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. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |

content/docs/references/ai/conversation.mdx

@@ -33,7 +33,7 @@ const result = CodeContent.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'code'` | ✅ |  |
 | **text** | `string` | ✅ | Code snippet |
 | **language** | `string` | ✅ |  |
 | **metadata** | `Record<string, any>` | optional |  |
@@ -93,12 +93,12 @@ const result = CodeContent.parse(data);
 | **id** | `string` | ✅ | Unique message ID |
 | **timestamp** | `string` | ✅ | ISO 8601 timestamp |
 | **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ |  |
-| **content** | `Object \| Object \| Object \| Object[]` | ✅ | Message content (multimodal array) |
-| **functionCall** | `Object` | optional | Legacy function call |
-| **toolCalls** | `Object[]` | optional | Tool calls |
+| **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** | `Object` | optional | Token usage for this message |
+| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Token usage for this message |
 | **cost** | `number` | optional | Cost for this message in USD |
 | **pinned** | `boolean` | ✅ | Prevent removal during pruning |
 | **importance** | `number` | optional | Importance score for pruning |
@@ -116,12 +116,12 @@ const result = CodeContent.parse(data);
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique session ID |
 | **name** | `string` | optional | Session name/title |
-| **context** | `Object` | ✅ |  |
+| **context** | `{ sessionId: string; userId?: string; agentId?: string; object?: string; … }` | ✅ |  |
 | **modelId** | `string` | optional | AI model ID |
-| **tokenBudget** | `Object` | ✅ |  |
-| **messages** | `Object[]` | ✅ |  |
-| **tokens** | `Object` | optional |  |
-| **totalTokens** | `Object` | optional | Total tokens across all messages |
+| **tokenBudget** | `{ maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens: integer; … }` | ✅ |  |
+| **messages** | `{ id: string; timestamp: string; 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> }[]; … }[]` | ✅ |  |
+| **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'>` | ✅ |  |
 | **createdAt** | `string` | ✅ | ISO 8601 timestamp |
@@ -143,7 +143,7 @@ const result = CodeContent.parse(data);
 | **originalTokens** | `integer` | ✅ | Original token count |
 | **summaryTokens** | `integer` | ✅ | Summary token count |
 | **tokensSaved** | `integer` | ✅ | Tokens saved |
-| **messageRange** | `Object` | ✅ | Range of messages summarized |
+| **messageRange** | `{ startIndex: integer; endIndex: integer }` | ✅ | Range of messages summarized |
 | **generatedAt** | `string` | ✅ | ISO 8601 timestamp |
 | **modelId** | `string` | optional | Model used for summarization |
 
@@ -156,7 +156,7 @@ const result = CodeContent.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'file'` | ✅ |  |
 | **fileUrl** | `string` | ✅ | File attachment URL |
 | **mimeType** | `string` | ✅ | MIME type |
 | **fileName** | `string` | optional |  |
@@ -184,7 +184,7 @@ const result = CodeContent.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'image'` | ✅ |  |
 | **imageUrl** | `string` | ✅ | Image URL |
 | **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ |  |
 | **metadata** | `Record<string, any>` | optional |  |
@@ -206,7 +206,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'text'` | ✅ |  |
 | **text** | `string` | ✅ | Text content |
 | **metadata** | `Record<string, any>` | optional |  |
 
@@ -220,7 +220,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'image'` | ✅ |  |
 | **imageUrl** | `string` | ✅ | Image URL |
 | **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ |  |
 | **metadata** | `Record<string, any>` | optional |  |
@@ -235,7 +235,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'file'` | ✅ |  |
 | **fileUrl** | `string` | ✅ | File attachment URL |
 | **mimeType** | `string` | ✅ | MIME type |
 | **fileName** | `string` | optional |  |
@@ -251,7 +251,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'code'` | ✅ |  |
 | **text** | `string` | ✅ | Code snippet |
 | **language** | `string` | ✅ |  |
 | **metadata** | `Record<string, any>` | optional |  |
@@ -281,7 +281,7 @@ This schema accepts one of the following structures:
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **timestamp** | `string` | ✅ | Event timestamp |
-| **prunedMessages** | `Object[]` | ✅ |  |
+| **prunedMessages** | `{ messageId: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; tokens: integer; importance?: number }[]` | ✅ |  |
 | **tokensFreed** | `integer` | ✅ |  |
 | **messagesRemoved** | `integer` | ✅ |  |
 | **remainingTokens** | `integer` | ✅ |  |
@@ -309,7 +309,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `string` | ✅ |  |
+| **type** | `'text'` | ✅ |  |
 | **text** | `string` | ✅ | Text content |
 | **metadata** | `Record<string, any>` | optional |  |
 
@@ -380,7 +380,7 @@ This schema accepts one of the following structures:
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Tool call ID |
 | **type** | `Enum<'function'>` | ✅ |  |
-| **function** | `Object` | ✅ |  |
+| **function** | `{ name: string; arguments: string; result?: string }` | ✅ |  |
 
 
 ---

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

@@ -43,7 +43,7 @@ const result = FileKnowledgeSource.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'file'` | ✅ |  |
 | **prefix** | `string` | ✅ | Storage prefix |
 | **mimeTypes** | `string[]` | optional |  |
 
@@ -56,7 +56,7 @@ const result = FileKnowledgeSource.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'http'` | ✅ |  |
 | **urls** | `string[]` | ✅ |  |
 | **userAgent** | `string` | optional |  |
 
@@ -86,10 +86,10 @@ const result = FileKnowledgeSource.parse(data);
 | **description** | `string` | optional |  |
 | **adapter** | `string` | ✅ | Adapter id |
 | **adapterConfig** | `Record<string, any>` | optional |  |
-| **source** | `Object \| Object \| Object` | ✅ |  |
-| **embedding** | `Object` | optional |  |
-| **vectorStore** | `Object` | optional |  |
-| **refresh** | `Object` | optional |  |
+| **source** | `{ kind: 'object'; object: string; contentFields: string[]; metadataFields?: string[]; … } \| { kind: 'file'; prefix: string; mimeTypes?: string[] } \| { kind: 'http'; urls: string[]; userAgent?: string }` | ✅ |  |
+| **embedding** | `{ provider: Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>; model: string; dimensions: integer; endpoint?: string; … }` | optional |  |
+| **vectorStore** | `{ provider: Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>; collection: string; endpoint?: string; secretRef?: string; … }` | optional |  |
+| **refresh** | `{ onRecordChange?: boolean; cron?: string }` | optional |  |
 | **aiExposed** | `boolean` | optional |  |
 
 
@@ -107,7 +107,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'object'` | ✅ |  |
 | **object** | `string` | ✅ | Short object name to index |
 | **contentFields** | `string[]` | ✅ | Fields contributing to document content |
 | **metadataFields** | `string[]` | optional |  |
@@ -121,7 +121,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'file'` | ✅ |  |
 | **prefix** | `string` | ✅ | Storage prefix |
 | **mimeTypes** | `string[]` | optional |  |
 
@@ -133,7 +133,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'http'` | ✅ |  |
 | **urls** | `string[]` | ✅ |  |
 | **userAgent** | `string` | optional |  |
 
@@ -148,7 +148,7 @@ This schema accepts one of the following structures:
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **kind** | `string` | ✅ |  |
+| **kind** | `'object'` | ✅ |  |
 | **object** | `string` | ✅ | Short object name to index |
 | **contentFields** | `string[]` | ✅ | Fields contributing to document content |
 | **metadataFields** | `string[]` | optional |  |

content/docs/references/ai/mcp.mdx

@@ -23,7 +23,7 @@ server (so an agent can mount its tools).
 
 2. **MCPToolBinding** — how an MCP tool from a referenced server
 
-is exposed as an ObjectStack [AIToolDefinition](AIToolDefinition) (alias,
+is exposed as an ObjectStack `AIToolDefinition` (alias,
 
 visibility, approval policy).