ADR-0023: Docs site architecture (Phase 1.5)

• Status: Accepted
• Date: 2026-06-12 (amended 2026-06-13 — docs/app/ layout)
• Authors: IBEX Harness team

Context

• Marketing landing lives in a separate repo (marvel-scape) at ibexharness.com.
• Engineering documentation (~133 markdown files) lives in repo-root docs/ for ADRs, roadmap, and internal audits.
• Public product docs must ship at docs.ibexharness.com with a polished, Vercel/Linear-style design (MASTER_BRIEF).
• DNS docs CNAME is managed in Cloudflare; production docs deploy to Cloudflare Pages static export (amended 2026-06-26).

Decision

1) Public docs app location

• Add docs/app/ — Fumadocs on Next.js 15 App Router.
• Go services remain in services/; shared Go libraries stay in packages/ (unchanged). Shared TypeScript libraries for the docs site also live under packages/ (e.g. future packages/sdk-typescript/). Do not relocate Go code into docs/app/.

2) Two documentation corpora

Public pages are authored as MDX; port/adapt from engineering sources per CONTENT_SOURCES.md.

3) JavaScript toolchain

• pnpm workspaces + Turborepo at repo root.
• pnpm-workspace.yaml includes docs/app and packages/* (pnpm ignores Go-only dirs without package.json).
• Tailwind v3 (Fumadocs UI v14 requirement).

4) Hosting

• Cloudflare Pages — pure static export (output: export → docs/app/out/).
• Pages project name: ibex-harness-docs.
• Deploy only through GitHub Actions .github/workflows/docs-deploy.yml.
• Credentials in GitHub Environment production (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID); see DEPLOY_CLOUDFLARE.md.
• Separate from landing project ibexdepo — never attach docs.ibexharness.com to the landing Vercel project.
• NEXT_PUBLIC_SITE_URL=https://docs.ibexharness.com in production.
• Search: pre-built /search-index.json (Orama simple mode, ~272 KB); /api/search redirects to it in production.
• OG images: pre-generated at build into public/docs/*/opengraph-image.png.
• Redirects: public/_redirects (Pages); cache headers: public/_headers.
• Amendment (2026-06-22): Vercel → Cloudflare Workers + OpenNext (#129–#133).
• Amendment (2026-06-26): Workers + OpenNext → Cloudflare Pages static export. Recurring Error 1102 traced to Worker CPU limits on a fully static site; OpenNext Durable Object cache handlers were unnecessary for force-static pages. /api/search Orama rebuild and runtime OG generation were additional Worker CPU sinks.

5) API reference

• Phase 1.5: manual endpoint pages for implemented surfaces only.
• OpenAPI-driven pages (fumadocs-openapi) deferred until services/proxy publishes openapi.yaml (Phase 2).

6) Delivery

• Wave-based PRs (one milestone or tight pair per PR); see phase-1-5 README.

Consequences

• repo-guards must allow docs/app/ under docs/ and root Node manifest files.
• CI gains docs-build job (path-filtered) and docs-deploy workflow on main; see D.4.2 (partial).
• D.4.1 Vercel preview deploys superseded by GHA + workflow_dispatch deploy smoke tests.
• Phase 2 entry blocked until Phase 1.5 production launch (docs-first sequencing).

References

• MASTER_BRIEF.md
• DOCS_DOMAIN_HANDOFF (landing repo)
• ADR-0020 — Go packages/ boundaries unchanged