objectstack-ai · os-zhuang · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
diff --git a/.changeset/docs-gen-description-line-layout-and-nested-links.md b/.changeset/docs-gen-description-line-layout-and-nested-links.md
@@ -0,0 +1,58 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): docs-gen renders a module description as the markdown it was written as (#5553, #6136)
+
+Two independent defects in `scripts/lib/file-description.ts`, both from a
+transform applied at the wrong granularity. The block SELECTION rule #5059 added
+is untouched: all 185 sources that carried a module header still render one, and
+no page gained or lost an opening paragraph.
+
+**#5553 — line layout is content, not decoration.** The renderer dropped every
+blank line and joined what survived with `\n\n`, making each SOURCE LINE its own
+paragraph. Anything that legitimately wraps across lines was then cut in half by
+a paragraph boundary, and an inline code span cannot cross one, so both of its
+backticks fell out as literal text — `` `explain(principal, object, `` /
+`` operation)` `` on `security/explain`, and three more like it. The same pass
+escaped `{` and `}` everywhere including inside code, where a backslash is not
+an escape character but a character the reader sees, so pages published
+`` `\{ dialect, source \}` ``.
+
+The fix is to stop rewriting the layout: strip the ` * ` gutter and keep the
+lines as authored. Markdown's own rules then do what the issue asked for —
+consecutive lines are one paragraph, a blank line opens the next — and lists,
+headings, tables and code blocks keep working, which the literal space-join the
+issue floated would have broken on the 85 sources that write a list. Escaping and
+link resolution are now scoped to prose: fenced and indented code blocks are
+copied verbatim, and within prose a tokenizer keeps inline code spans out of
+reach.
+
+One construct is deliberately NOT reproduced as authored: an indented (4-space)
+code block is re-emitted as a fenced one. MDX dropped CommonMark's indented code
+blocks so that indentation could lay out JSX, so such a block reaches the MDX
+compiler as ordinary prose — and unescaped braces in prose are an expression.
+`data/date-macros` and `data/context-tokens` write their placeholder examples
+that way and are almost entirely braces; left indented they fail to compile
+("Could not parse expression with acorn"), and escaped instead they show `\{` in
+what is meant to be code. The target dialect has one spelling for a code block.
+
+Measured over the 185 rendered descriptions: paragraphs with unpaired backticks
+8 → 0 (`automation/flow-function`, `security/explain`, `shared/expression`,
+`system/settings-client`), and backslash-brace residue inside code 296 → 0 across
+33 pages. 32 pages get their fenced `@example` sample back as a real code block
+instead of one escaped paragraph per line, and 47 regain the indentation that
+made a nested list nested. The issue named five victim pages; `system/doc` is not
+among them because #5059 has since found its header documents `DocSchema` and
+stopped publishing it.
+
+**#6136 — a rewriter that ran over its own output.** The untitled
+`{@link <path>}` branch emits `[<path>](<route>)`, whose link TEXT is the path
+itself. The bare-source-path rewriter ran next over the whole string and matched
+that text, wrapping it a second time into a link nested in a link. Lookaround
+cannot express "not nested inside a link", so the rewriter is now applied per
+prose token with formed links excluded. `automation/etl` and
+`integration/connector` each get their "See also" back as one clickable link.
+
+169 reference pages are regenerated. No runtime, package export or protocol
+semantics change — this is the docs generator only.
diff --git a/content/docs/references/ai/conversation.mdx b/content/docs/references/ai/conversation.mdx
@@ -8,7 +8,6 @@ description: Conversation protocol schemas
 AI Conversation Memory Protocol
 
 Multi-turn AI conversations with token budget management.
-
 Enables context preservation, conversation history, and token optimization.
 
 <Callout type="info">

diff --git a/content/docs/references/ai/embedding.mdx b/content/docs/references/ai/embedding.mdx
@@ -10,25 +10,17 @@ Embedding & Vector Store Primitives
 Platform contract for configuring embedding models and vector stores.
 
 Scope (intentionally minimal):
-
 - How to reference an embedding model (provider + model name + secret).
-
 - How to reference a vector store (provider + connection).
 
 NOT in scope (these belong to application code, not the platform):
-
 - Chunking strategies (fixed/semantic/recursive/markdown).
-
 - Retrieval pipelines (rerankers, multi-stage retrieval, filters).
-
 - Document loaders / ingestion DSLs.
-
 - End-to-end RAG pipeline orchestration.
 
 These were removed in v1 because they describe one specific way to
-
 build a RAG application; the platform's job is to expose the embed +
-
 vector primitives so any RAG strategy can be built on top.
 
 <Callout type="info">

diff --git a/content/docs/references/ai/knowledge-document.mdx b/content/docs/references/ai/knowledge-document.mdx
@@ -6,15 +6,11 @@ description: Knowledge Document protocol schemas
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
 Knowledge Document / Chunk / Hit — canonical shapes shared by every
-
 `IKnowledgeAdapter` implementation.
 
 The framework does **not** prescribe chunk strategy or vector
-
 format. Adapters are free to chunk however they like; the framework
-
 only requires they round-trip these shapes when talking to the
-
 `IKnowledgeService`.
 
 See `content/docs/protocol/knowledge.mdx` for the full design.

diff --git a/content/docs/references/ai/knowledge-source.mdx b/content/docs/references/ai/knowledge-source.mdx
@@ -6,17 +6,12 @@ description: Knowledge Source protocol schemas
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
 Knowledge Source — declarative metadata describing what to index and
-
 which adapter to use.
 
 A KnowledgeSource is the metadata-level equivalent of an
-
 `IDataEngine` driver binding: it pairs a logical source description
-
 (object/file/http) with the *id* of an `IKnowledgeAdapter` plugin
-
 that will actually do the work. The adapter resolves the id at
-
 runtime via `IKnowledgeService.registerAdapter`.
 
 See `content/docs/protocol/knowledge.mdx` for the full design.

diff --git a/content/docs/references/ai/mcp.mdx b/content/docs/references/ai/mcp.mdx
@@ -8,29 +8,20 @@ description: Mcp protocol schemas
 Model Context Protocol (MCP) — Reference & Binding Primitives
 
 MCP itself is an external protocol defined by Anthropic
-
 (https://modelcontextprotocol.io). The platform does NOT re-define
-
 MCP's wire format, transport, or message shapes — that is the job
-
 of the `@modelcontextprotocol/sdk` consumed by `@objectstack/mcp`.
 
 This file defines only the two things the *platform* needs:
 
 1. **MCPServerRef** — how a project references an external MCP
-
-server (so an agent can mount its tools).
-
+   server (so an agent can mount its tools).
 2. **MCPToolBinding** — how an MCP tool from a referenced server
-
-is exposed as an ObjectStack `AIToolDefinition` (alias,
-
-visibility, approval policy).
+   is exposed as an ObjectStack `AIToolDefinition` (alias,
+   visibility, approval policy).
 
 Everything else (transport details, capability negotiation,
-
 resource/prompt shapes, streaming, sampling) is handled by the SDK
-
 at runtime and does not need a metadata representation.
 
 <Callout type="info">

diff --git a/content/docs/references/ai/model-registry.mdx b/content/docs/references/ai/model-registry.mdx
@@ -8,7 +8,6 @@ description: Model Registry protocol schemas
 AI Model Registry Protocol
 
 Centralized registry for managing AI models, prompt templates, and model versioning.
-
 Enables AI-powered ObjectStack applications to discover and use LLMs consistently.
 
 <Callout type="info">

diff --git a/content/docs/references/ai/skill.mdx b/content/docs/references/ai/skill.mdx
@@ -8,7 +8,6 @@ description: Skill protocol schemas
 Skill Trigger Condition Schema
 
 Defines programmatic conditions under which a skill becomes active.
-
 Allows context-aware activation based on object type, user role, etc.
 
 <Callout type="info">

diff --git a/content/docs/references/ai/usage.mdx b/content/docs/references/ai/usage.mdx
@@ -10,25 +10,17 @@ AI Usage Primitives
 Platform contract for measuring AI consumption.
 
 Scope (intentionally minimal):
-
 - Token usage per call.
-
 - Per-call cost (computed from a model's unit price).
-
 - Model unit pricing.
 
 NOT in scope (deferred to FinOps / product layer):
-
 - Budget definitions, enforcement, alerts.
-
 - Cost allocation / chargeback / reports.
-
 - Optimization recommendations.
 
 Rationale: the platform must record *what was used*; deciding what
-
 to do about it (block calls, send alerts, allocate to cost centers)
-
 is product policy that varies wildly between tenants.
 
 <Callout type="info">

diff --git a/content/docs/references/api/analytics.mdx b/content/docs/references/api/analytics.mdx
@@ -8,7 +8,6 @@ description: Analytics protocol schemas
 Analytics API Protocol
 
 Defines the HTTP interface for the Semantic Layer.
-
 Provides endpoints for executing analytical queries and discovering metadata.
 
 <Callout type="info">

diff --git a/content/docs/references/api/auth-endpoints.mdx b/content/docs/references/api/auth-endpoints.mdx
@@ -8,13 +8,10 @@ description: Auth Endpoints protocol schemas
 Authentication Endpoint Specification
 
 Defines the canonical HTTP endpoints for the authentication service.
-
 Based on better-auth v1.4.18 endpoint conventions.
 
 NOTE: ObjectStack's auth implementation uses better-auth library which has
-
 established endpoint conventions. This spec documents those conventions as
-
 the canonical API contract.
 
 <Callout type="info">

diff --git a/content/docs/references/api/auth.mdx b/content/docs/references/api/auth.mdx
@@ -8,7 +8,6 @@ description: Auth protocol schemas
 Authentication Service Protocol
 
 Defines the standard API contracts for Identity, Session Management,
-
 and Access Control.
 
 <Callout type="info">

diff --git a/content/docs/references/api/automation-api.mdx b/content/docs/references/api/automation-api.mdx
@@ -8,29 +8,19 @@ description: Automation Api protocol schemas
 Automation API Protocol
 
 Defines REST CRUD endpoint schemas for managing automation flows,
-
 triggering executions, and querying execution history.
 
 Base path: /api/automation
 
 @example Endpoints
-
 GET    /api/automation                         — List flows
-
 GET    /api/automation/:name                   — Get flow
-
 POST   /api/automation                         — Create flow
-
 PUT    /api/automation/:name                   — Update flow
-
 DELETE /api/automation/:name                   — Delete flow
-
 POST   /api/automation/:name/trigger           — Trigger flow execution
-
 POST   /api/automation/:name/toggle            — Enable/disable flow
-
 GET    /api/automation/:name/runs              — List execution runs
-
 GET    /api/automation/:name/runs/:runId       — Get single execution run
 
 <Callout type="info">

diff --git a/content/docs/references/api/batch.mdx b/content/docs/references/api/batch.mdx
@@ -8,17 +8,12 @@ description: Batch protocol schemas
 Batch Operations API
 
 Provides efficient bulk data operations with transaction support.
-
 Implements P0/P1 requirements for ObjectStack kernel.
 
 Features:
-
 - Batch create/update/delete operations
-
 - Atomic transaction support (all-or-none)
-
 - Partial success handling
-
 - Detailed error reporting per record
 
 Industry alignment: Salesforce Bulk API, Microsoft Dynamics Bulk Operations

diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx
@@ -6,19 +6,13 @@ description: Discovery protocol schemas
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
 Service Status Enum
-
 Describes the operational state of a service in the discovery response.
 
 - `available`   – Fully operational: service is registered AND HTTP handler is verified.
-
 - `registered`  – Route is declared in the dispatcher table but the HTTP handler has
-
-not been verified (may 501 at runtime).
-
+                  not been verified (may 501 at runtime).
 - `unavailable` – Service is not installed / not registered in the kernel.
-
 - `degraded`    – Partially working (e.g., in-memory fallback, missing persistence).
-
 - `stub`        – Placeholder handler that always returns 501 Not Implemented.
 
 <Callout type="info">

diff --git a/content/docs/references/api/dispatcher.mdx b/content/docs/references/api/dispatcher.mdx
@@ -8,25 +8,17 @@ description: Dispatcher protocol schemas
 # HttpDispatcher Protocol
 
 Defines how the ObjectStack HttpDispatcher routes incoming API requests
-
 to the correct kernel service based on URL prefix matching.
 
 The dispatcher is the central routing component that:
-
 1. Matches incoming request URLs against registered route prefixes
-
 2. Delegates to the corresponding CoreService implementation
-
 3. Returns 503 Service Unavailable when a service is not registered
-
 4. Supports dynamic route registration from plugins via contributes.routes
 
 Architecture alignment:
-
 - Kubernetes: API server aggregation layer
-
 - Eclipse: Extension registry routing
-
 - VS Code: Command palette routing
 
 <Callout type="info">

diff --git a/content/docs/references/api/documentation.mdx b/content/docs/references/api/documentation.mdx
@@ -8,55 +8,33 @@ description: Documentation protocol schemas
 API Documentation & Testing Interface Protocol
 
 Provides schemas for generating interactive API documentation and testing
-
 interfaces similar to Swagger UI, Postman, etc.
 
 Features:
-
 - OpenAPI/Swagger specification generation
-
 - Interactive API testing playground
-
 - API versioning and changelog
-
 - Code generation templates
-
 - Mock server configuration
 
 Architecture Alignment:
-
 - Swagger UI: Interactive API documentation
-
 - Postman: API testing collections
-
 - Redoc: Documentation rendering
 
 @example Documentation Config
-
 ```typescript
-
-const docConfig: ApiDocumentationConfig = \{
-
-enabled: true,
-
-title: 'ObjectStack API',
-
-version: '1.0.0',
-
-servers: [\{ url: 'https://api.example.com', description: 'Production' \}],
-
-ui: \{
-
-type: 'swagger-ui',
-
-theme: 'light',
-
-enableTryItOut: true
-
-\}
-
-\}
-
+const docConfig: ApiDocumentationConfig = {
+  enabled: true,
+  title: 'ObjectStack API',
+  version: '1.0.0',
+  servers: [{ url: 'https://api.example.com', description: 'Production' }],
+  ui: {
+    type: 'swagger-ui',
+    theme: 'light',
+    enableTryItOut: true
+  }
+}
 ```
 
 <Callout type="info">