Build the documentation

Outcome

apps/docs/build/client contains every documentation route, one compact static ZBSearch page index, 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, representative authored and generated-reference queries, installed production dependency license inventory, eager JavaScript budget, lazy search-index budget, and forbidden backend/credential string. The index is generated from each page's title, description, headings, and body content; it stays one lazy artifact while under the 2 MiB compressed split threshold. The build 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. The Pages workflow imports the same generated search route used by the application before it verifies the deployed immutable artifact.

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.