feat(spec): the example type-check gate now covers content/docs, not just skills/ (#3882)

check:skill-examples compiles the TypeScript in prose against the built spec, so
an example that stops compiling fails CI instead of quietly teaching code that no
longer works. It does its job — it caught the broken defineTool example in #3876.
But it only ever walked skills/:

    skills/          9 files with ts blocks,   9 compiled
    content/docs/  124 files with ts blocks,   0 compiled

The identical break in a docs page ships. Docs examples are copied verbatim by
humans and AI exactly like skill examples — the same shape as the stale-evidence
and orphan-proof warnings fixed in #3857 / #3868: a gate covering a fraction of
the surface it appears to cover reads as coverage.

The walker is now a SOURCE_ROOTS list, and this lands the first batch: 164 docs
blocks across 63 pages, taking the gate from 32 to 196 checked examples.
content/docs/references/ is excluded — build-docs.ts regenerates it from the
schemas, so it cannot drift independently.

THE MARKER IS NOW PER-FORMAT. MDX has no HTML comments: `<!-- os:check -->` in a
.mdx does not degrade, it fails the fumadocs build outright ("Unexpected
character `!`… to create a comment in MDX, use `{/* text */}`"). Found by building
the docs site after the first attempt broke 60+ pages; nothing in the type-check
gate would have said so, because block extraction is regex-level and never parses
MDX. skills/**/*.md keeps `<!-- os:check -->`; content/docs/**/*.mdx uses
`{/* os:check */}`. Both spellings are recognised for ORPHAN detection, so a
wrong-format marker fails loudly instead of silently checking nothing.

The batch was measured, not guessed: marking all 780 docs blocks and compiling
showed which are self-contained. One subtlety — a block that "passes" inside a
780-file program can be leaning on globals declared by OTHER blocks (a file with
no import/export is a global script), so the first pass's 564 "passing" blocks
collapsed to 164 once compiled as the real, smaller set. Converged by recompiling
and dropping newly-failing blocks until green.

The remaining blocks are mostly fragments, which the opt-in design anticipates.
Whether any are genuine rot is now answerable for the first time.

Author: os-zhuang

.changeset/prose-example-gate-covers-docs.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": patch
+---
+
+feat(spec): the example type-check gate now covers `content/docs`, not just `skills/`
+
+`check:skill-examples` compiles the TypeScript in prose against the built spec, so
+an example that stops compiling fails CI instead of quietly teaching code that no
+longer works. It does its job — it caught the broken `defineTool` example when
+`tool.requiresConfirmation` was removed (#3715).
+
+But it only ever walked `skills/`:
+
+| Tree | files with `ts` blocks | compiled |
+|---|---|---|
+| `skills/` | 9 | **9** |
+| `content/docs/` (hand-written) | 124 | **0** |
+
+The identical break in a docs page would have shipped. Docs examples are copied
+verbatim by humans and AI exactly like skill examples, so a gate covering a
+fraction of the surface it appears to cover reads as coverage — the same shape as
+the stale-evidence and orphan-proof warnings fixed in #3857 / #3868.
+
+The walker is now a `SOURCE_ROOTS` list, and this lands the first batch: **164
+docs blocks across 63 pages, taking the gate from 32 to 196 checked examples**.
+`content/docs/references/` is excluded — `build-docs.ts` regenerates it from the
+schemas, so it cannot drift independently of its source.
+
+**The marker is now per-format.** MDX has no HTML comments: `<!-- os:check -->` in
+a `.mdx` fails the fumadocs build outright — *"Unexpected character `!`… to create
+a comment in MDX, use `{/* text */}`"*. Caught by building the docs site, after
+the first attempt broke 60+ pages. `skills/**/*.md` keeps `<!-- os:check -->`;
+`content/docs/**/*.mdx` uses `{/* os:check */}`. Both spellings are recognised for
+**orphan** detection, so a wrong-format marker fails loudly rather than silently
+checking nothing — the existing guard's philosophy, extended to the new failure
+mode this change introduces.
+
+The batch was measured rather than guessed: marking all 780 docs blocks and
+compiling showed which are self-contained. One subtlety worth recording — a block
+that "passes" inside a 780-file program can be leaning on globals declared by
+*other* blocks (a file with no import/export is a global script), so the set was
+converged by recompiling and dropping newly-failing blocks until green. 164 stand
+on their own.
+
+The remaining blocks are mostly fragments (a `columns: [...]` subtree), which the
+gate's opt-in design already anticipates. Whether any are genuine rot is worth a
+follow-up now that the machinery reaches them.

content/docs/ai/actions-as-tools.mdx

@@ -70,6 +70,7 @@ Add an optional `ai:` block to give the model a precise, LLM-facing description
 spec; `list_actions` surfaces `ai.description` to the model, falling back to the
 UI `label` when it is absent.
 
+{/* os:check */}
 ```typescript
 export const triageCaseAction = {
   name: 'triage_case',

content/docs/ai/agents.mdx

@@ -167,6 +167,7 @@ point at, and reach it through `@objectstack/mcp` (BYO-AI).
 
 ## Sales Assistant Agent
 
+{/* os:check */}
 ```typescript
 import { defineAgent } from '@objectstack/spec/ai';
 

content/docs/api/environment-routing.mdx

@@ -24,6 +24,7 @@ depending on request context.
 
 Enable scoped route registration in `objectstack.config.ts`:
 
+{/* os:check */}
 ```typescript
 import { defineStack } from '@objectstack/spec';
 

content/docs/api/error-handling-client.mdx

@@ -17,6 +17,7 @@ This guide covers best practices for handling ObjectStack API errors in client a
 
 Every error response from ObjectStack follows this shape:
 
+{/* os:check */}
 ```typescript
 interface ErrorResponse {
   success: false;        // Always false for error responses
@@ -56,6 +57,7 @@ Error `code` values are lowercase snake_case (`validation_error`, `permission_de
 
 Create a typed error parser to extract structured information from API responses:
 
+{/* os:check */}
 ```typescript
 import type { ErrorResponse } from '@objectstack/spec/api';
 

content/docs/api/error-handling-server.mdx

@@ -23,6 +23,7 @@ lowercase snake_case members of `StandardErrorCode` (see
 `@objectstack/spec/api`), e.g. `validation_error`, `resource_conflict`,
 `permission_denied`.
 
+{/* os:check */}
 ```typescript
 import type { ErrorResponse, StandardErrorCode } from '@objectstack/spec/api';
 
@@ -289,6 +290,7 @@ export const EnrichTaskWithAI: Hook = {
 
 Prevent cascading failures when an external service is down:
 
+{/* os:check */}
 ```typescript
 class CircuitBreaker {
   private failures = 0;

content/docs/automation/flows.mdx

@@ -9,6 +9,7 @@ A **Flow** is a visual automation that orchestrates business logic through conne
 
 ## Basic Structure
 
+{/* os:check */}
 ```typescript
 const approvalFlow = {
   name: 'order_approval',
@@ -607,6 +608,7 @@ metadata, which `objectstack validate` will point at.
 
 Flows use variables to pass data between nodes and to/from callers:
 
+{/* os:check */}
 ```typescript
 variables: [
   { name: 'input_id', type: 'text', isInput: true, isOutput: false },
@@ -781,6 +783,7 @@ is retired; model the same logic as a Flow.
 
 ### Record-change flow
 
+{/* os:check */}
 ```typescript
 import type { Flow } from '@objectstack/spec/automation';
 

content/docs/automation/index.mdx

@@ -9,6 +9,7 @@ Automation is ObjectStack's process engine: you attach business logic to the dat
 
 The smallest useful automation is a hook (from the CRM example app):
 
+{/* os:check */}
 ```typescript
 import type { Hook, HookContext } from '@objectstack/spec/data';
 

content/docs/automation/workflows.mdx

@@ -21,6 +21,7 @@ This page keeps the historical route but documents the current split.
 Use Flow when something should happen after a record event, schedule, button, or
 subflow call:
 
+{/* os:check */}
 ```typescript
 import type { Flow } from '@objectstack/spec/automation';
 
@@ -63,6 +64,7 @@ registration/runtime.
 Use `StateMachineSchema` when the core requirement is "this object can only move
 through these states by these events."
 
+{/* os:check */}
 ```typescript
 import type { StateMachineConfig } from '@objectstack/spec/automation';
 

content/docs/concepts/architecture.mdx

@@ -88,6 +88,7 @@ description — data (objects), automation (flows), access (permissions), and in
 
 ### Example: Defining a Customer Object
 
+{/* os:check */}
 ```typescript
 // src/objects/customer.object.ts
 import { ObjectSchema, Field } from '@objectstack/spec/data';
@@ -148,6 +149,7 @@ That's the job of the other layers.
 
 ### Example: Permission Rules
 
+{/* os:check */}
 ```typescript
 // src/permissions/sales_rep.permission.ts
 import { definePermissionSet } from '@objectstack/spec';
@@ -175,6 +177,7 @@ export const SalesRepPermission = definePermissionSet({
 
 ### Example: Workflow Automation
 
+{/* os:check */}
 ```typescript
 // src/flows/high_value_customer.flow.ts
 import { defineFlow } from '@objectstack/spec';
@@ -221,6 +224,7 @@ Kernel **orchestrates** these rules at runtime, independent of the data structur
 
 ### Example: List View
 
+{/* os:check */}
 ```typescript
 // src/views/customer.view.ts
 import { defineView } from '@objectstack/spec';
@@ -245,6 +249,7 @@ export const CustomerView = defineView({
 
 ### Example: Form View
 
+{/* os:check */}
 ```typescript
 // src/views/customer.view.ts
 import { defineView } from '@objectstack/spec';
@@ -300,6 +305,7 @@ User clicks "Save"
 
 ### Step 2: UI Layer Sends Request
 
+{/* os:check */}
 ```typescript
 // ObjectUI dispatches an action to Kernel
 const request = {
@@ -375,6 +381,7 @@ for (const workflow of workflows) {
 
 ### Step 7: ObjectUI Updates Display
 
+{/* os:check */}
 ```typescript
 // Kernel returns success response
 // UI optimistically updates the screen
@@ -388,6 +395,7 @@ Here's how all three protocols collaborate for a **Kanban Board** feature:
 
 ### 1. ObjectQL: Define the Data
 
+{/* os:check */}
 ```typescript
 import { ObjectSchema, Field } from '@objectstack/spec/data';
 
@@ -426,6 +434,7 @@ export const Opportunity = ObjectSchema.create({
 
 ### 2. Kernel: Define Business Rules
 
+{/* os:check */}
 ```typescript
 import { defineFlow } from '@objectstack/spec';
 
@@ -450,6 +459,7 @@ export const OpportunityWonFlow = defineFlow({
 
 ### 3. ObjectUI: Define the Kanban View
 
+{/* os:check */}
 ```typescript
 import { defineView } from '@objectstack/spec';