Operate the documentation site

apps/docs is a separate Next.js documentation application. It renders the canonical Markdown and MDX files from the repository-level docs/ directory; there is no second content/docs copy. Changing a guide changes the repository contract and the rendered site together.

The docs site is not the React product SPA and is not deployed by the application OpenTofu, Railway, Dokploy, Vercel-SPA, or Cloudflare static-assets paths. It is optional buyer-owned documentation and needs an independently selected Next.js host when published.

Local development

The scaffold creates ignored apps/docs/.env with a localhost origin so the full zero-key workspace build remains deterministic.

pnpm --filter @app/docs dev

Open http://localhost:3002/docs. Search is served by the Next route handler. Markdown negotiation, llms.txt, llms-full.txt, per-page Markdown, sitemap, robots, and Open Graph image routes are part of the application.

Offline Markdown bundle

The documentation navigation includes Download Markdown. It downloads the current published documentation as one Markdown file from llms-full.txt; save that file for offline reading or give it to an agent alongside the exact product release. It contains only the published documentation, not private environment files, seller-only surfaces, evaluation evidence, or historical Phase 2 material.

Download the current Markdown bundle

Content and navigation

For every new published page:

1. add the .md or .mdx file under docs/;
2. add it to docs/meta.json at the intended sidebar position;
3. add it to the files list in apps/docs/lib/source.ts;
4. use links to other published docs pages or external HTTPS pages;
5. render and verify the route, Markdown representation, search, sitemap, and adjacent navigation.

Repository-only files such as ADRs, commercial policies, evaluation evidence, and infrastructure READMEs should be referenced as code paths unless they are deliberately added to the published source list. A filesystem-valid relative Markdown link can still be a 404 in the docs application.

Verification

pnpm --filter @app/docs lint
pnpm --filter @app/docs typecheck
pnpm --filter @app/docs test
NEXT_PUBLIC_SITE_URL=https://docs.example.com \
  pnpm --filter @app/docs build:public

The ordinary build command accepts the generated localhost origin for repository-wide local and CI verification. build:public rejects missing, HTTP, localhost, credentialed, query, fragment, or path-bearing values before Next builds.

Publication

Set NEXT_PUBLIC_SITE_URL to the exact public HTTPS origin in the deployment environment. It is inlined into canonical URLs, sitemap entries, robots, and Open Graph metadata at build time. Rebuild after changing the origin.

Use a Node-compatible Next.js deployment that can run the search route and proxy. Build with build:public, then start the produced application with:

pnpm --filter @app/docs start

No production host automation is included. The selected host must preserve Next route handlers, static assets, proxy behavior, HTTPS, immutable release identification, logs, rollback, and a smoke covering /docs, /api/search, /sitemap.xml, /robots.txt, /llms.txt, and one Open Graph image.

Do not publish the generated local .env, rely on localhost metadata, or assume the product SPA deployment also serves this application.