Runbook: docs platform

This site is a static Fumadocs (Next.js) build deployed to Cloudflare Pages. There are two deployments from the same repo:

Build & deploy

pnpm install

# public
pnpm run deploy:public

# internal twin
pnpm run deploy:internal

Each deploy script builds (out/) and pushes via wrangler pages deploy. Deploys are atomic — a build that fails never replaces the live site.

Roll back

Cloudflare Pages keeps every deployment. Dashboard → the Pages project → Deployments → pick the previous one → Rollback. Or redeploy a known good commit:

git checkout <good-sha>
pnpm run deploy:public

Swap in the real OpenAPI spec

The /api reference renders from spec/openapi.yaml (currently a placeholder). To replace it with the gateway's real spec:

# from the gateway repo (FastAPI exposes its schema programmatically)
python -c "import json; from app.main import app; print(json.dumps(app.openapi()))" \
  > ../documentation/spec/openapi.json

Then point src/lib/openapi.ts at the new file, build, and review the generated pages. Never edit reference pages by hand — fix the spec instead.

Access (internal twin)

The internal project is gated by Cloudflare Access (Okta). If someone cannot reach it: Zero Trust dashboard → Access → Applications → sirius-docs-internal — check the policy includes their group, and that the Okta identity provider is healthy under Settings → Authentication.