Build the documentation

Generate reference truth, prerender every route, and validate the static GitHub Pages artifact.

Outcome

apps/docs/build/client contains every documentation route, static ZBSearch data, canonical URLs, sitemap, robots policy, LLM text files, source and third-party notices, and no application-runtime dependency.

Prerequisites

Bootstrap the root workspace. Use Node 24.18.0; scripts rely on its native erasable TypeScript support. Set DOCS_BASE_PATH only when testing a project-site prefix. The custom production domain uses /.

Steps

Regenerate machine-owned pages after their canonical source changes:

pnpm --filter @lumen/docs generate:reference

Build and validate the custom-domain artifact:

DOCS_BASE_PATH=/ pnpm --filter @lumen/docs build

For a subpath staging artifact, use one URL-safe prefix such as /lumen-preview; the same value controls Vite assets, React Router basename, search, canonical URLs, sitemap, robots, and LLM links.

Verify

The build checks every expected route, source link/anchor, built link/anchor, canonical URL, generated file, search JSON, installed production dependency license inventory, eager JavaScript budget, lazy search-index budget, and forbidden backend/credential string. It fails on an unreviewed license, reference drift, and placeholder copy. The inventory deliberately covers the installed production dependency closure; it does not claim to reconstruct browser-bundle composition.

The root pnpm check command serves both the root and /lumen-preview artifacts without hidden rewrites, then drives deep links, keyboard focus, accessibility, static search, narrow/dark/reduced and forced-color viewports, 404 behavior, console/network cleanliness, and performance budgets in a real browser.

Recover

If generated reference drifts, regenerate and review the canonical contract change. If a route or anchor fails, fix the source link; do not add a static-host redirect that hides missing content. If a license has no declared identity, stop the build and review the dependency. If the JavaScript budget fails, inspect eager imports before changing the budget.

Next task

Prepare a release.