Design: Public Docs Site — Content Parity for v1 Launch

Status: Accepted Date: 2026-05-20 UTC Owner: software-architect Parent card: #104 Refs: docs-site-scaffold-2026-05-15.md (superseded in scope), ADR-0088 ADRs: 0103

1. Context

Operator decision 2026-05-20 UTC: the public docs site must ship at v1 launch (2026-05-23 UTC) with full content parity to internal-docs. T-3 days.

The prior design (docs-site-scaffold-2026-05-15.md) delivered the technical foundation at T-8: - Builder (scripts/build-customer-docs.py) — shipped, CLOSED - CSS theme — shipped, CLOSED - CI workflow (deploy-customer-docs.yml) — shipped, CLOSED - Content stubs for Getting Started, Concepts, FAQ, Privacy+Terms — shipped

What is NOT done at T-3: - broker-setup.md — stub with draft: true and multiple TODOs - troubleshooting.md — stub with draft: true and multiple TODOs - Pricing / plan details page — not authored - Release notes section — deferred pending #99 (semver + GitHub Releases) - noindex → index, follow flip — pending launch-day runbook step

Interpretation of "full content parity": Internal-docs serves 522 pages across 30 categories. The vast majority are operator-only (ADRs, runbooks, ops triage, security scans, sprint plans, business-legal, finance). A literal mirror is not the intent — and several categories contain content that MUST NOT be public per platform invariants.

"Content parity" means: the customer-facing content domain (everything a user needs to understand, use, and get support for the product) is fully authored, not stub-only. The six content axes below define the complete customer-facing scope.

2. Invariants

All platform invariants from the prior design doc apply unchanged:

• No broker/vendor names in customer copy. Build-time lint enforces.
• No forward-looking framing. All copy is retrospective and descriptive of the platform's behavior on the user's own data. AI references are limited to retrospective description.
• Brand placeholders. data-brand-placeholder attributes mark wordmark, tagline, and pillar copy until formal brand system ships (~2026-11 UTC).
• noindex pre-launch, index, follow at launch. Flip is a single-line edit to frontend/docs/_headers per the launch-day runbook.
• Audit trail on every deploy. Per new-surface-convention.md.
• No credentials stored or accepted. Site is static HTML.
• No PII collected. No analytics, no forms, no sessions at v1.
• No internal-only content on the public site. The explicit allowlist (see Content Classification below) is the gate. Anything not on the allowlist stays in internal-docs, never in docs/customer/.

3. Content Classification

Internal-docs sections and their public status

Customer-facing content scope (public, v1)

Six content axes define the complete v1 public docs site:

Sections explicitly excluded from v1 (no customer-facing gap)

• API Reference — no public API at v1. Internal docs/API.md contains broker-name references and localhost endpoints; excluded from customer build.
• Release Notes — depends on #99 (semver + GitHub Releases). Excluded from v1 build manifest; section landing (/release-notes/) can 404 gracefully at v1, or scaffold a coming-soon stub.
• Architecture overview for integrators — planned in #131 (closed defer:post-launch). No integrators at v1; exclude.
• SDK docs — no SDK exists.
• Localization — Quebec geo-blocked at signup; fr-CA docs deferred.

4. APIs / Contracts

No change from prior design. Static HTML via Cloudflare Pages.

Build manifest allowlist (the exhaustive set of customer-facing source files):

docs/customer/index.md
docs/customer/getting-started.md
docs/customer/concepts.md
docs/customer/broker-setup.md
docs/customer/faq.md
docs/customer/privacy-terms.md
docs/customer/troubleshooting.md
docs/customer/pricing.md          ← new file, SC-D11

No other source paths enter the customer-docs build.

5. State machines / sequences

Content authoring → publish flow

sequenceDiagram
    participant FD as feature-developer
    participant PR as GitHub PR
    participant CI as GH Actions
    participant CF as Cloudflare Pages (raxx-docs)

    FD->>PR: merge docs/customer/<file>.md
    PR->>CI: push to main triggers deploy-customer-docs.yml
    CI->>CI: broker-name lint (build script)
    CI->>CI: forward-looking-phrase lint (build script)
    CI->>CF: wrangler pages deploy dist-customer-docs/
    CF-->>CI: deploy URL
    CI->>CI: health-check docs.raxx.app (expect 200)
    CI->>CI: emit audit row

v1 launch-day sequence (noindex flip)

stateDiagram-v2
    [*] --> AllContentMerged
    AllContentMerged : All 8 source files authored\nand merged to main
    AllContentMerged --> PreLaunch
    PreLaunch : X-Robots-Tag: noindex, nofollow\nSite live but not indexed
    PreLaunch --> LaunchDayFlip : 2026-05-23 UTC\nrunbook step 1
    LaunchDayFlip : Edit frontend/docs/_headers\nX-Robots-Tag: index, follow
    LaunchDayFlip --> Indexed : CI redeploys (~2 min)
    Indexed --> [*]

6. Migrations

No schema changes. Static site.

Rollback: CF Pages instant rollback via dashboard or revert-and-merge. Content-only changes have zero database migration risk.

7. Rollout plan

Target: all content merged to main by 2026-05-22 UTC (1 day buffer).

Phase 1 / Phase 2 split (honest assessment of T-3):

Three content files require authoring work before launch: - broker-setup.md — 4 unresolved product TODOs (requires product owner decision on v1 supported broker list and permission set) - troubleshooting.md — 5 unresolved product TODOs (requires product owner decision on UX details) - pricing.md — new file, not yet drafted

The broker-setup and troubleshooting TODOs are gated on product owner decisions, not just writing effort. If those decisions are made by 2026-05-20 UTC, the content can ship by 2026-05-22. If those decisions are deferred, the v1 site ships with the current "complete-but-generic" versions of those pages (no broker-specific names, no UI label specifics — just the accurate high-level flow that already exists in the stubs). This is an acceptable v1 state since Raxx does not name its broker integrations in customer copy.

8. Security considerations

• PII collected: None. No forms, no analytics, no user sessions at v1.
• Retention: N/A (static site, no data store).
• DSR (data subject request): N/A at v1. If analytics are added post-v1 (e.g. Fathom/Plausible), revisit DSR scope.
• Audit log: Every CF Pages deploy emits an audit row to the console audit endpoint per new-surface-convention.md. Retained per platform-wide policy.
• Credentials / replay risk: None. The site accepts no credentials.
• Breach notification: No user data; no breach-notification obligation for this surface.
• Secrets: CF_PAGES_DEPLOY_TOKEN in Infisical vault at /MooseQuest/CF_PAGES_DEPLOY_TOKEN, prod environment. Rotatable without redeploy.
• Kill-switch: Remove docs.raxx.app custom domain from CF Pages project in Cloudflare dashboard. Takes effect in seconds.
• Broker-name leak prevention: Build script lints all source files and all rendered HTML output before wrangler deploys. Build exits non-zero on any hit.
• Internal content leak prevention: The build script reads only docs/customer/ (explicit allowlist). Any file outside that directory is never ingested, regardless of repo structure changes.

9. Open questions (blocking operator decision)

1. Broker list for v1 — broker-setup.md has a TODO asking which brokers are supported at v1 launch. The current stub text is accurate (authorization-flow described generically) but the "supported brokers" list is empty. Decision needed: publish the page as broker-agnostic-generic (fine for v1 given no broker names appear in copy), or defer to a post-launch iteration. Recommended: publish as generic — no customer blocker.

2. Troubleshooting UI details — three TODOs reference exact UI labels from #479 (broker rejection codes surface, reconnect UX, evaluation log UI). If these UI features are not shipped at v1, the troubleshooting steps should describe the general flow without specific button labels. Decision needed: are those UI surfaces live at v1?

3. Pricing page — pricing tiers are locked (Free / Pro / Pro+ / Founders $29). A pricing page in docs reinforces trust for pre-signup users. However, the exact Pro and Pro+ prices are marked "pending BLR research" in project_pricing_tiers_locked.md. Decision needed: (a) publish a pricing page with Founders tier only and "Pro/Pro+ pricing announced at launch" language, or (b) hold the pricing page until prices are finalized.

4. Release notes section — the v1 build intentionally excludes release notes (depends on #99). Should /release-notes/ 404 silently or show a coming-soon stub page? No technical blocker — editorial preference only.

5. Search — deferred post-v1 per prior design. Still deferred; confirming no change to scope.

Sub-cards (this scope extension)

The prior design's sub-cards (SC-D1 through SC-D10) are all closed. This design adds three new sub-cards for the content-parity gap:

Plus one non-content sub-card that closes the launch loop:

SC-D14 is the final gate. It is a one-line edit to frontend/docs/_headers (already annotated) plus adding docs.raxx.app to the marketing site footer and README. It requires all content to be merged first.