[finding] `@example` and `@category` tag lines render verbatim on 13 published reference pages — a tag WITH a payload needs a rewrite, not the `@module` drop

[claude]

renderFileDescription (packages/spec/scripts/lib/file-description.ts) emits a
module docblock's prose lines verbatim, so a JSDoc block tag written on a
prose line reaches the published reference page as literal tag text. Two tags do
this today, on 13 customer-facing pages:

@example — 14 lines across 10 pages

content/docs/references/api/automation-api.mdx:15:@example Endpoints
content/docs/references/api/documentation.mdx:25:@example Documentation Config
content/docs/references/api/odata.mdx:45:@example OData Query
content/docs/references/api/odata.mdx:57:@example Programmatic Use
content/docs/references/api/package-api.mdx:14:@example Endpoints
content/docs/references/api/plugin-rest-api.mdx:31:@example Serving routes from a plugin (imperative `http.server` mount)
content/docs/references/automation/time-relative-trigger.mdx:33:@example T-minus renewal reminders (fires on the day a contract is 60/30/7 days out)
content/docs/references/automation/time-relative-trigger.mdx:48:@example "Expiring soon" range (fires every day a document is within 30 days of expiry)
content/docs/references/automation/time-relative-trigger.mdx:55:@example Overdue sweep (fires for POs up to 14 days past due)
content/docs/references/shared/mapping.mdx:21:@example Basic field mapping
content/docs/references/shared/mapping.mdx:29:@example With a fallback for missing source values
content/docs/references/studio/object-designer.mdx:41:@example
content/docs/references/studio/plugin.mdx:38:@example
content/docs/references/system/worker.mdx:24:@example Basic task

@category — 4 lines across 4 pages

content/docs/references/system/incident-response.mdx:16:@category Security
content/docs/references/system/security-context.mdx:27:@category Security
content/docs/references/system/supplier-security.mdx:15:@category Security
content/docs/references/system/training.mdx:15:@category Security

Reproduce: grep -rn '^@example\|^@category' content/docs/references/

Why this is not the @module fix, and not a filter

The @module marker was removable because its entire content IS the marker — it
selects the block and says nothing a reader needs, so the renderer now drops it
at prose level.

These two are the opposite case. Both carry a payload:

• @example Basic field mapping is the caption of the fenced block directly
  beneath it. Dropping the line deletes reader prose and orphans the fence.
• @category Security is a classification a reader may well want surfaced.

So a blanket ^@\w+ line filter is the wrong instrument here — it would take
that prose off the page. The renderer already has the right shape for a tag with
content, one line away: renderProse REWRITES @see path into See also: path
rather than dropping it. The open question this issue asks is what the
corresponding rewrite should be, e.g.

• @example CAPTION becomes a bolded caption line, or a heading at the block's
  section level, above the fence — and the bare @example with no caption (two
  pages, studio/plugin and studio/object-designer) presumably becomes
  nothing at all, since it has no payload;
• @category VALUE becomes prose, or is routed into page frontmatter, or is
  dropped as machinery — that one is genuinely a judgement call about whether
  the classification is for readers or for tooling.

Both need a decision about the rendered shape before anyone writes code, which
is why they are filed rather than folded into the render fix.

Notes

• Any fix belongs in renderFileDescription, beside the existing prose-level
  marker drop, with unit pins in packages/spec/scripts/file-description.test.ts
  and a corpus assertion re-derived from packages/spec/src — the pattern the
  neighbouring cases in that file already use.
• check:docs cannot see this class: it compares the artifact against the
  source, and the artifact reproduces the tag faithfully. Assert on the rendered
  fragment, not on the emitted .mdx.

Found while fixing the @module marker leak in #13796; that card is deliberately
scoped to the one tag whose whole content is the marker, and does not address
the two above.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Triage: lands in packages/spec/scripts/lib/file-description.ts ⇒ domain:spec (the lane owns packages/spec/scripts/** and the toolchain that turns on the spec contract). Graded Bug · priority:p3.

Bug by the mechanical boundary test: nothing widens, a renderer emits raw tag text where reader prose was intended.

priority:p3 — 13 customer-facing reference pages show literal @example / @category text. Visible and embarrassing, ⛔ not harmful: no contract is wrong, nothing fails, and the surrounding prose still reads.

⛔ Not sent to the decision inbox, and the reason matters for the shape of the work

The card says both tags need a decision about the rendered shape before anyone writes code. Read against the escalation threshold, only half of that is a decision, and it is the smaller half:

• @example CAPTION is mechanical. The payload is the caption of the fence directly beneath it — the card establishes that, and it is checkable on the page. It renders as a caption; the two bare @example lines with no payload (studio/plugin, studio/object-designer) render as nothing, since a tag with no payload is the @module case the renderer already drops. ⛔ No judgement is owed here.
• @category Security is the open one — reader-facing prose, page frontmatter, or machinery to drop. Four pages, all Security.

⇒ Routed as work rather than as a decision. The spec seat picks the @category shape as part of doing it, and escalates to the inbox only if it judges the classification a product-surface call rather than a rendering one. Putting a four-line docs-rendering question in the maintainer's inbox ahead of its owner having looked would be premature.

What the card already establishes and should not be re-derived

⭐ The right instrument is one line away and named: renderProse already rewrites @see path into See also: path rather than dropping it. That is the precedent for a tag with a payload, and it is in the same file.

⛔ A blanket ^@\w+ line filter is the wrong instrument and the card is right to rule it out — it would take reader prose off the page and orphan the fences.

⚠️ check:docs is structurally blind to this class: it compares the artifact against the source, and the artifact reproduces the tag faithfully. ⇒ Assert on the rendered fragment, ⛔ not on the emitted .mdx, or the pin will pass while the page stays wrong. Unit pins go in packages/spec/scripts/file-description.test.ts with a corpus assertion re-derived from packages/spec/src, matching the neighbouring cases in that file.

⚠️ The 18 cited lines are from 2026-09-02. Re-run the card's own repro before editing (grep -rn '^@example\|^@category' content/docs/references/) — it is the acceptance instrument, so a stale baseline makes the count unprovable.

---

Generated by Claude Code