fix(spec): render @example captions and drop @category on reference pages

.changeset/reference-page-block-tag-payload-render.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": patch
+---
+
+Reference pages no longer print `@example` and `@category` tag lines as literal text.
+
+A module docblock is JSDoc, so its header carries block tags, and the reference-docs
+renderer emitted a tag written on a prose line verbatim — 18 such lines reached 14
+customer-facing pages, as `@example Basic field mapping` above a code fence and
+`@category Security` at the foot of four `system/` pages. `#13796` removed `@module`
+from the page and left these two open, because a blanket `^@\w+` line filter would
+have taken reader prose off the page and orphaned the fences below it.
+
+The verdict is per tag, and the axis is the payload rather than the spelling:
+
+- **`@example CAPTION` is REWRITTEN** into that caption, in bold, above the block it
+  captions — the shape `@see` already had (`See also: …`). 12 lines across 10 pages.
+  Bold rather than a heading because heading renumbering has already run by then, so
+  an emitted heading would carry a level chosen blind of the page, add entries to the
+  pages' tables of contents, and put a caption in reach of `check:docs-single-h1`.
+- **A bare `@example` is DROPPED.** With no payload it is the `@module` case exactly,
+  and the fence beneath it is visibly an example without a line announcing one. 2
+  lines (`studio/plugin`, `studio/object-designer`), both sitting against the
+  `check:skill-examples` opt-in marker that was already dropped there.
+- **`@category VALUE` is DROPPED.** 4 lines, all reading `Security`, on four pages that
+  already sit under a `system/` section saying as much — and nothing in the repo reads
+  the tag: no typedoc or api-extractor (neither is used here), no search index, no
+  gate. Routing it into page frontmatter instead would publish a field with no
+  consumer. The tag stays in the source, where it is a legitimate JSDoc tag; only the
+  rendered page drops it.
+
+No schema behavior changes. The pins assert on the rendered fragment rather than on the
+emitted `.mdx`, because `check:docs` compares the artifact against the source and
+reproduced all 18 tag lines faithfully.

content/docs/references/api/automation-api.mdx

@@ -12,7 +12,7 @@ triggering executions, and querying execution history.
 
 Base path: /api/automation
 
-@example Endpoints
+**Endpoints**
 GET    /api/automation                         — List flows
 GET    /api/automation/:name                   — Get flow
 POST   /api/automation                         — Create flow

content/docs/references/api/documentation.mdx

@@ -22,7 +22,7 @@ Architecture Alignment:
 - Postman: API testing collections
 - Redoc: Documentation rendering
 
-@example Documentation Config
+**Documentation Config**
 ```typescript
 const docConfig: ApiDocumentationConfig = {
   enabled: true,

content/docs/references/api/odata.mdx

@@ -42,7 +42,7 @@ See also: https://www.odata.org/documentation/
 
 See also: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html
 
-@example OData Query
+**OData Query**
 ```
 GET /api/odata/customers?
   $select=name,email&
@@ -54,7 +54,7 @@ GET /api/odata/customers?
   $count=true
 ```
 
-@example Programmatic Use
+**Programmatic Use**
 ```typescript
 const query: ODataQuery = {
   select: ['name', 'email'],

content/docs/references/api/package-api.mdx

@@ -11,7 +11,7 @@ REST API endpoint schemas for package lifecycle management.
 
 Base path: /api/v1/packages
 
-@example Endpoints
+**Endpoints**
 POST   /api/v1/packages/install              — Install a package
 POST   /api/v1/packages/upgrade              — Upgrade a package
 POST   /api/v1/packages/resolve-dependencies — Resolve dependencies

content/docs/references/api/plugin-rest-api.mdx

@@ -28,7 +28,7 @@ Architecture Alignment:
 - Microsoft Dynamics: Web API with entity operations
 - Strapi: Auto-generated REST endpoints from schemas
 
-@example Serving routes from a plugin (imperative `http.server` mount)
+**Serving routes from a plugin (imperative `http.server` mount)**
 ```typescript
 // Routes are mounted in CODE — resolve the `http.server` service from the
 // plugin context and register handlers on `kernel:ready` (the service is

content/docs/references/automation/time-relative-trigger.mdx

@@ -30,7 +30,7 @@ automation context (so `{record.<field>}` interpolation and the start-node
 `condition` gate work exactly as they do for record-change flows). The
 descriptor is carried on the flow's start node as `config.timeRelative`.
 
-@example T-minus renewal reminders (fires on the day a contract is 60/30/7 days out)
+**T-minus renewal reminders (fires on the day a contract is 60/30/7 days out)**
 ```ts
 // flow start node
 config: {
@@ -45,14 +45,14 @@ config: {
 }
 ```
 
-@example "Expiring soon" range (fires every day a document is within 30 days of expiry)
+**"Expiring soon" range (fires every day a document is within 30 days of expiry)**
 ```ts
 config: {
   timeRelative: { object: 'hr_document', dateField: 'expires_on', withinDays: 30 },
 }
 ```
 
-@example Overdue sweep (fires for POs up to 14 days past due)
+**Overdue sweep (fires for POs up to 14 days past due)**
 ```ts
 config: {
   timeRelative: { object: 'purchase_order', dateField: 'due_date', withinDays: -14, filter: { status: 'open' } },

content/docs/references/shared/mapping.mdx

@@ -18,15 +18,15 @@ ObjectStack for data synchronization.
   this base too, until the whole external-lookup family was retired in
   #8075 — ADR-0049, zero consumers.)
 
-@example Basic field mapping
+**Basic field mapping**
 ```typescript
 const mapping: FieldMapping = {
   source: 'external_user_id',
   target: 'user_id',
 };
 ```
 
-@example With a fallback for missing source values
+**With a fallback for missing source values**
 ```typescript
 const mapping: FieldMapping = {
   source: 'user_name',

content/docs/references/studio/object-designer.mdx

@@ -38,7 +38,6 @@ The Object Designer is composed of four interconnected panels:
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-@example
 ```typescript
 import {
   ObjectDesignerConfigSchema,

content/docs/references/studio/plugin.mdx

@@ -35,7 +35,6 @@ Like VS Code extensions, Studio plugins have two layers:
 └─────────────────────────────────────────────────────────┘
 ```
 
-@example
 ```typescript
 import { StudioPluginManifestSchema } from '@objectstack/spec/studio';
 

content/docs/references/system/incident-response.mdx

@@ -13,8 +13,6 @@ and notification matrices.
 
 See also: https://www.iso.org/standard/27001
 
-@category Security
-
 <Callout type="info">
 **Source:** `packages/spec/src/system/incident-response.zod.ts`
 </Callout>

content/docs/references/system/security-context.mdx

@@ -24,8 +24,6 @@ governance context.
 
 See also: https://www.iso.org/standard/27001
 
-@category Security
-
 <Callout type="info">
 **Source:** `packages/spec/src/system/security-context.zod.ts`
 </Callout>

content/docs/references/system/supplier-security.mdx

@@ -12,8 +12,6 @@ risk assessment, security requirements, monitoring, and change control.
 
 See also: https://www.iso.org/standard/27001
 
-@category Security
-
 <Callout type="info">
 **Source:** `packages/spec/src/system/supplier-security.zod.ts`
 </Callout>

content/docs/references/system/training.mdx

@@ -12,8 +12,6 @@ course definitions, completion tracking, and organizational training plans.
 
 See also: https://www.iso.org/standard/27001
 
-@category Security
-
 <Callout type="info">
 **Source:** `packages/spec/src/system/training.zod.ts`
 </Callout>

content/docs/references/system/worker.mdx

@@ -21,7 +21,7 @@ Features:
 - Dead letter queues
 - Task monitoring and logging
 
-@example Basic task
+**Basic task**
 ```typescript
 const task: Task = {
   id: 'task-123',