docs.raxx.app — v1 Public Organization Plan

Status: Planning Date: 2026-05-28 UTC Owner: operator / ux-polisher Parent issue: #2680 Parent epic: #2678 Scaffold design: docs/architecture/docs-site-scaffold-2026-05-15.md ADR: docs/architecture/adr/0088-docs-site-tooling-choice.md

1. Scope

This document is a layout and index deliverable — it does not write new content. It organizes what exists in docs/customer/ for v1 public consumption and identifies content that needs operator review before launch-day (FLAG_SC_D14 noindex flip).

2. Existing content inventory

All files live in docs/customer/. These feed the static build via scripts/build-customer-docs.py and ship at docs.raxx.app.

3. Proposed top-level navigation

Two-click rule: a first-time visitor must reach Getting Started, Core concepts, or Troubleshooting within two clicks from the landing page.

docs.raxx.app/
├── /                        ← index.md  ("Raxx Documentation" landing)
│
├── Getting started          ← getting-started.md
│
├── Setup
│   └── Broker setup         ← broker-setup.md
│
├── Platform concepts        ← concepts.md
│
├── FAQ                      ← faq.md
│
├── Troubleshooting          ← troubleshooting.md
│
├── Account management
│   └── Account merging      ← account-merging.md  (gated by FLAG_ACCOUNT_MERGE; refs #3252)
│
├── Pricing                  ← pricing.md  [needs operator review — TBD markers]
│
└── Legal                    ← privacy-terms.md  (links to raxx.app/privacy + raxx.app/terms)

Rationale for "Setup" grouping: broker-setup.md is a single page today. If strategy-setup.md ships post-v1, it slots under Setup without changing the top nav.

4. Navigation items that need operator review

These items exist in the content but have unresolved TBD markers or data-brand-placeholder copy that needs a content decision before launch.

5. Link audit — pages to check

These links appear in index.md and must resolve to HTTP 200 before the noindex flip (SC-D14).

6. CE visual palette — what to apply

Per feedback_all_surfaces_confidence_engine and the ux-polisher card scope:

• Replace any Bootstrap-default blue (#007bff) with var(--raxx-moss) or var(--raxx-ink)
• Replace gray backgrounds with var(--raxx-bg) (dark) or var(--raxx-bg-surface)
• Apply var(--raxx-font-sans) body type, var(--raxx-font-mono) for code blocks
• Single h1 per page — verified by link checker gate in CI
• No skipped heading levels (h2 → h4)
• Moss-pill live/status indicator if a "Platform status" link is added to the nav

The ux-polisher pass applies palette changes; it does not rewrite content.

7. Pages that do NOT exist at v1 (excluded from build manifest)

Per docs/architecture/docs-site-scaffold-2026-05-15.md §3 "Non-goals":

• API reference — no public API at v1; excluded from build
• Release notes — depends on #99 (semver + GitHub Releases); deferred post-v1
• Search — client-side search deferred post-v1
• Localization (fr-CA) — Quebec geo-blocked at signup; deferred until Canadian customers are accepted
• Video embeds — Phase 2+ content work

8. Ordering decision for ux-polisher

1. Run the link checker against the current build output — identify any broken internal links or unreachable pages.
2. Apply CE palette to all 8 pages (nav chrome + body chrome — leave content text alone).
3. Update index.md nav links to reflect the "Setup" grouping if sub-pages expand.
4. Flag pricing.md TBD markers to operator for a content decision; do not remove the page from the nav unilaterally.
5. Post the change log comment on issue #2680 listing every file touched.
6. File operator-decision items (pricing content, any dead external links) as needs:operator-decision labels rather than blocking the PR.

9. Operator-review items (summary)