docs content: `api/automation-api` and `api/package-api` publish their endpoint listing as a run-on paragraph — the source writes it unfenced

[claude]

Two reference pages publish an endpoint table as a run-on paragraph, because the source writes the listing unfenced.

api/automation-api and api/package-api both caption a listing and then write its rows as ordinary prose lines inside the module docblock:

packages/spec/src/api/automation-api.zod.ts:16-25
 * @example Endpoints
 * GET    /api/automation                         — List flows
 * GET    /api/automation/:name                   — Get flow
 * POST   /api/automation                         — Create flow
 * ...

packages/spec/src/api/package-api.zod.ts:19-27 has the identical shape.

Those rows are consecutive non-blank lines, so they are ONE markdown paragraph. apps/docs/source.config.ts loads no remark-breaks, so a soft line break renders as a space: the reader gets every row concatenated onto one line, with the column alignment the author wrote gone. Every other example on these pages is fenced and renders correctly.

Reproduce

sed -n '14,25p' content/docs/references/api/automation-api.mdx
sed -n '13,22p' content/docs/references/api/package-api.mdx

Both show the rows unfenced. Compare with content/docs/references/api/odata.mdx, whose listing under the same kind of caption IS fenced and renders as a block.

Not the renderer

renderFileDescription (packages/spec/scripts/lib/file-description.ts) is correct here — it preserves the source's own line layout deliberately, and markdown's own rules then apply. The fix is in the two sources: fence the listing, the way the neighbouring modules already do. A renderer-side rule that guessed which prose runs are really tables would be exactly the kind of shape-sniffing that file's header rejects.

Provenance

Found while doing #14455, which rewrote the @example Endpoints caption above these two listings into a bold caption. That card is scoped to the TAG LINE and deliberately does not touch what is beneath it, so these two pages still read as a caption followed by a run-on line. Filed rather than folded in.

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:spec / priority:p3 / pm:queue

Anchor read, not guessed — and this is the case where the naive anchor is wrong. The symptom is on two published docs pages, so domain:devx looks right; it is not. The card locates the fix precisely: the pages are generated from the module docblocks, and the sources are packages/spec/src/api/automation-api.zod.ts and packages/spec/src/api/package-api.zod.ts ⇒ domain:spec. Nothing under content/docs/ is hand-edited to close this.

Verified on origin/main f1d7872 (2026-09-04T23:47:57Z):

• automation-api.zod.ts:16 — @example Endpoints, followed by nine consecutive non-blank * GET … — List flows rows, unfenced. Reproduced verbatim.
• ⭐ @example Endpoints occurs in exactly two files repo-wide — automation-api.zod.ts:16 and package-api.zod.ts:19. That is the positive control the card's "both have the identical shape" claim needs, and it doubles as a completeness bound: these two are the whole population under this caption, so there is no third page waiting to be found afterwards.

Grade — p3

Cosmetic in mechanism, real in effect: the rows render as one run-on line with the author's column alignment gone, on a customer-facing reference page. But nothing is wrong — every endpoint is still listed and still correct, the reader can recover the information, and no gate is red. p3, and I would resist promoting it: the fix is cheap enough that it does not need a higher grade to get picked up.

Boundary test — Bug/tidy, no manual floor

Fencing a listing changes rendering only. No accept set, no contract, no behaviour.

⛔ The trap on this card, and it is the whole reason to read it before starting

The obvious "clever" fix is renderer-side — teach renderFileDescription to notice that a run of aligned prose lines is really a table. Do not. The card is right and its reasoning is the repo's own:

renderFileDescription (packages/spec/scripts/lib/file-description.ts) is correct here — it preserves the source's own line layout deliberately, and markdown's own rules then apply. … A renderer-side rule that guessed which prose runs are really tables would be exactly the kind of shape-sniffing that file's header rejects.

The failure is not a renderer bug and not a missing remark-breaks in apps/docs/source.config.ts either. It is two sources writing a block as prose while every neighbouring example on the same pages is fenced and renders correctly — which is what makes "fence these two listings" the whole fix and anything larger a regression risk.

⇒ Scope: fence both listings, confirm the two pages render as blocks, stop. ⛔ Do not touch the renderer, ⛔ do not add a remark plugin, ⛔ do not sweep other docblocks for "similar" prose runs — the @example Endpoints census above says there are none under this caption, and a broader sweep is a different card with a different justification.

Provenance fence — endorsed

#14455 rewrote the caption above these listings and is ruled to the tag line, deliberately not touching what sits beneath it. That is correct scoping, not an omission, and this card is the intended way for the remainder to survive. ⛔ Nobody should read this as rework on #14455.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code