ADR 0103 — Public docs content parity: what ships at v1 vs post-v1

Status: Accepted Date: 2026-05-20 UTC Decider: software-architect (ratifying operator decision 2026-05-20 UTC) Parent card: #104 Design doc: public-docs-content-parity-2026-05-20.md

Context

Operator re-scoped #104 on 2026-05-20 UTC: "full content parity" with internal-docs is required at v1 launch (2026-05-23 UTC). The prior design (docs-site-scaffold-2026-05-15.md, ADR-0088) established the technical foundation at T-8 and explicitly excluded content authoring from its scope.

The question this ADR answers: what does "content parity" mean for a public customer-facing docs site when the internal-docs contains 522 pages of operator-only content, ADRs, security triage, and business-legal artifacts that must NOT be public?

Two interpretations were considered:

A — Literal mirror: Publish all internal-docs content (or as much as possible) on the public site. 522+ pages.

B — Customer-domain parity: Author every content axis a customer needs to understand, use, and get support for the product. Six source files covering the complete customer journey. No operator content, no internal architecture detail, no vendor names.

Decision

Option B — Customer-domain parity.

The six customer-facing content axes (index, getting-started, concepts, broker-setup, FAQ, privacy-terms) plus two new additions (troubleshooting fully authored, pricing page) constitute the complete v1 customer-facing docs surface. Nothing from operator-internal categories (ADRs, runbooks, security, ops) appears on the public site.

The content domain is bounded by the explicit allowlist in scripts/build-customer-docs.py (reads docs/customer/ only). Any file outside that directory is never built into the public site regardless of what the internal-docs site contains.

Consequences

• The public site is 8 content pages at v1. This is the correct scope for a product at initial launch. Docs depth grows with the user base.
• No operator content ever reaches the public site. The allowlist model makes accidental internal-content leak structurally impossible (not just policy-dependent).
• Three content files require authoring work before launch. broker-setup.md, troubleshooting.md, and pricing.md have outstanding TODOs that need product owner decisions (supported broker list, UI label specifics, Pro/Pro+ pricing finalization). See open questions in the design doc.
• T-3 is achievable if product decisions are made by 2026-05-20 UTC. If those decisions slip to 2026-05-21 UTC, T-2 authoring is still feasible. If all three decisions are still open at 2026-05-22 UTC, broker-setup and troubleshooting ship as generic (no broker-specific or UI-label content, which is acceptable given platform invariants) and pricing ships as Founders-tier-only with "Pro/Pro+ pricing at launch" placeholder language.

Alternatives considered

Option A — Literal internal-docs mirror

Rejected because: 1. The majority of internal-docs content is operator-only (ADRs, ops runbooks, security triage, business-legal). Publishing it violates the "no operator infrastructure details in customer copy" posture. 2. ADRs reference vendor names, internal token paths, and infrastructure topology that MUST NOT appear on a public surface. 3. 522 pages of internal-docs cannot be curated and audited for customer safety in T-3. 4. The build-script broker-name lint would flag hundreds of internal-docs ADRs and runbooks immediately — the build would fail.

Option C — API reference inclusion

Also considered: adding docs/API.md / docs/API_DOCUMENTATION.md to the customer build. Rejected because: 1. Both files reference localhost:5001 endpoints and internal broker names. 2. There is no versioned public API contract at v1. 3. ADR-0088 explicitly records "no public API at v1." Post-v1 API reference should be generated from OpenAPI (see #132).