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

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

`renderFileDescription` emitted a module docblock's prose verbatim, so a
JSDoc block tag written on a prose line reached the published page as
literal tag text: 18 lines across 14 customer-facing reference pages.

The verdict is per tag, on the payload rather than the spelling:

- `@example CAPTION` (12 lines, 10 pages) captions the block directly
  beneath it, so it is REWRITTEN into that caption in bold — the shape
  `@see` beside it already had.
- a bare `@example` (2 lines) has no payload, which is the `@module`
  case exactly, so it is DROPPED before classification alongside the
  `os:check` marker it sits against.
- `@category Security` (4 lines, 4 pages) is dropped. Measured: one
  value on four pages, and no consumer anywhere in the repo — no
  typedoc, no api-extractor, no search index, no gate.

Pins assert on the rendered fragment, never on the emitted `.mdx`:
`check:docs` compares the artifact to the source and reproduced all 18
tag lines faithfully.

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

* docs(spec): regenerate reference pages for the tag-payload render fix

18 tag lines across 14 pages: 12 `@example CAPTION` become bold
captions, 2 bare `@example` and 4 `@category Security` come off.
The card's own repro (`grep -rn '^@example\|^@category'
content/docs/references/`) now returns zero, and no other page in the
230-file regeneration moved.

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

* chore(changeset): reference-page block-tag payload render

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.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';