Docs Publishing Ops

---
title: Docs Publishing Operations Runbook
description: Operating guide for publishing and maintaining public and internal docs surfaces on Vercel.
owner: ops
last_reviewed: 2026-03-03
audience: internal
status: active
---
 
# Docs Publishing Operations Runbook
 
## Purpose
 
Run and support the dual-surface docs deployment:
 
- Public: `https://docs.rgl8r.com`
- Internal: `https://docs-internal.rgl8r.com`
 
This runbook defines preflight checks, release steps, validation, and rollback.
 
## Architecture
 
Source of truth:
 
- Canonical docs: `docs/`
- Publication manifests:
  - `docs/public-manifest.yaml`
  - `docs/private-manifest.yaml`
- Frontmatter policy: `docs/docs-frontmatter.schema.json`
 
Docs app:
 
- `apps/docs` (single app, dual runtime mode via `DOCS_MODE`)
- `DOCS_MODE=public` for customer-safe docs
- `DOCS_MODE=internal` for allowlisted internal routes at `/internal/**`
 
## Release Preconditions
 
Before merge to `main`, all must pass:
 
1. `Docs Quality Gate` workflow green.
2. Public docs frontmatter valid.
3. Public link check passes.
4. Sensitive-content scan passes.
5. Public build and internal build both pass.
 
## Vercel Configuration
 
Two projects, same code root (`apps/docs`):
 
1. `rgl8r-docs-public`
   - Domain: `docs.rgl8r.com`
   - Env:
     - `DOCS_MODE=public`
     - `NEXT_PUBLIC_APP_URL` (recommended)
 
2. `rgl8r-docs-internal`
   - Domain: `docs-internal.rgl8r.com`
   - Env:
     - `DOCS_MODE=internal`
     - `DOCS_INTERNAL_CLERK_ORG_IDS`
     - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
     - `CLERK_SECRET_KEY`
     - `NEXT_PUBLIC_APP_URL` (optional)
 
## Release Procedure
 
1. Merge approved docs PR to `main`.
2. Confirm `Docs Quality Gate` passed on merge commit.
3. Confirm Vercel deployments triggered for both docs projects.
4. Validate endpoints:
   - `GET https://docs.rgl8r.com` returns `200`
   - `GET https://docs-internal.rgl8r.com` redirects/challenges when unauthenticated
   - Internal allowlisted user can access `/internal/docs`
5. Spot-check required public docs pages:
   - Public API contract
   - Integration kit
   - OpenAPI `v1.1.0`
   - Route namespace contract
   - Legal terms/privacy
 
## Incident Handling
 
### Public docs leak risk
 
Trigger examples:
 
- Sensitive-content check bypassed
- Public manifest accidentally includes internal paths
 
Actions:
 
1. Revert offending PR on `main`.
2. Confirm fresh Vercel deploy completes.
3. Verify leaked page returns `404` or no longer contains sensitive content.
4. Record incident and remediation in launch evidence.
 
### Internal auth misconfiguration
 
Trigger examples:
 
- Internal users blocked unexpectedly
- Internal docs accessible without proper org membership
 
Actions:
 
1. Validate `DOCS_INTERNAL_CLERK_ORG_IDS` values.
2. Validate Clerk keys are set and current.
3. If exposure risk exists, remove `docs-internal.rgl8r.com` custom domain until fixed.
4. Redeploy and re-verify with allowlisted + non-allowlisted users.
 
## Rollback Procedure
 
1. Revert latest docs PR affecting docs app/manifests/content.
2. Merge revert to `main`.
3. Confirm both Vercel docs projects redeploy cleanly.
4. Re-run endpoint probes and internal auth probe.
5. Update `docs/operations/p19-e-docs-launch-evidence-2026-03-03.md` with rollback record.
 
## Operator Checklist
 
- [ ] Docs Quality Gate passed on target commit
- [ ] Public domain healthy (`200`, TLS valid)
- [ ] Internal domain auth behavior validated
- [ ] Public nav and key links work
- [ ] Evidence file updated with timestamp and commit SHA