Docs Maintenance

What is hand-written

User and developer guide pages live in Markdown under apps/docs/content.

Use short headings, plain language and examples that match the product UI. These pages are meant to be skimmed.

What is generated

The generated reference data lives at apps/docs/generated/reference.json.

It is built from:

• route JSDoc blocks in apps/api/src/routes
• Fastify route registrations
• exported backend functions and classes
• Mongoose schemas in apps/api/src/models
• shared DTOs, entities and enums in packages/types/src

Run:

pnpm docs:generate

Route comment format

Put a JSDoc block directly above each route registration:

/**
 * Create a suite and queue the first discovery crawl.
 *
 * @body CreateTestSuiteInput
 * @returns TestSuite
 * @status 201
 * @auth Optional
 */
app.post<{ Body: CreateTestSuiteInput }>('/', async (req, reply) => {
  // ...
});

The first paragraph becomes the endpoint summary. The tags fill out the API reference table.

Checking docs in CI

pnpm docs:check regenerates the reference in memory and compares it with the checked-in JSON. It also fails if a route does not have a JSDoc block.

This cannot prove that prose is still perfect, but it does catch stale generated docs and missing endpoint comments. That is the right first guardrail before adding heavier documentation review tooling.