REST API reference authoring

How we maintain the hand-written REST API section, keep it aligned with OpenAPI, and avoid autogenerated wrappers.

The public REST reference lives under content/docs/api/ in the docs app. Pages are maintained as MDX with a fixed section layout—not generated <APIPage /> wrappers.

Workflow

Export the machine-readable contract from the API app (updates apps/docs/openapi.json):
```
cd apps/api && pnpm run openapi:export
```
Regenerate baseline MDX from the spec (run from apps/docs):
```
pnpm run api:bootstrap
```
This refreshes per-operation files and meta.json. Then edit pages for clarity: examples, edge cases, links to guides, and wording.
Run pnpm lint in apps/docs—it checks OpenAPI tone rules, REST parity (every public merchant operation has a doc), required headings, and internal links.

Frontmatter (required for each operation page)

Each file must include:

Field	Example	Notes
`title`	Short human title	Mirrors OpenAPI `summary` initially
`description`	One line	Search / meta
`method`	`get`	Lowercase HTTP verb
`path`	`/accounts/{id}`	Must match OpenAPI path key exactly
`operationId`	`AccountsController_findOne`	Matches Nest `operationId`
`full`	`true`	Keeps wide API layout

Required sections (headings)

Lint enforces these headings:

## Overview, ## Authentication, ## Endpoint, ## Request, ## Responses, ## Errors, ## Example, ## OpenAPI

What we exclude

/agent/** routes are not listed in the public REST reference (parity check skips them). Document agent APIs elsewhere if needed.

Legacy URLs

Older bookmarks used flat paths like /api/AccountsController_findAll. The app redirects those to the canonical grouped path /api/accounts/AccountsController_findAll.

Scripts reference

Script	Role
`lib/scripts/pre-build.ts`	OpenAPI export + security normalize + registry; does not overwrite REST MDX
`lib/scripts/bootstrap-manual-api-reference.ts`	(Re)builds operation MDX + `meta.json` from `openapi.json`
`lib/scripts/manual-api/render-operation-mdx.ts`	Template for one operation page
`lib/scripts/manual-api/_expected-public-operations.json`	Generated list of `METHOD /path` strings (bootstrap output)