neutral

Phase 28 — Documentation Site (Docusaurus)

Replaces the Phase 15 Hugo-based docs site with a production-grade, Temporal-quality documentation website built on Docusaurus and styled to match Cruvero's dark-first UI design system.

Status: Planned
Depends on: Phase 15 (Hugo docs), Phase 20 (React UI design system), Phases 1–27 complete
Migrations: None
Branch: dev

---

Why Now

Phase 15's Hugo Book theme was sufficient when Cruvero documentation was small. As of 2026-02-15, the repo's documentation surface area is now large enough that discoverability, navigation quality, and reference automation directly affect contributor velocity and portfolio perception:

• Docs inventory under docs/ contains 435 Markdown/JSON files.
• Manual docs: 34 files (docs/manual/*.md).
• Operations docs: 12 files (docs/operations/*.md).
• Session notes: 140 files (docs/notes/sessions/*.md) which must remain non-public.
• Phase specs live in docs/phases/ (not docs/ root): 225 PHASE*.md files (includes sub-phases and prompt artifacts).

The Hugo site directory docs/site/ is currently absent on disk, while the Makefile and CI still reference it. Phase 28 resolves this by moving to a single supported docs pipeline (site/ Docusaurus), with build-time link validation and automated reference generation (OpenAPI, CLI, config/env).

Phase 28 is required for:

1. Portfolio showcase: the docs site is the main "product surface" most viewers will evaluate first.
2. Onboarding: a Temporal-style information architecture is needed to make 300+ pages usable.
3. Professional polish: a cohesive Cruvero theme (tokens, spacing, components) signals production-grade engineering.
4. Discoverability: full-text search, cross-links, and generated references prevent docs drift.

---

Architecture

Stack

• Docusaurus v3 (React + MDX) under repo root site/.
• Multi-instance docs to achieve Temporal-style top-level sections without a /docs prefix:
  • /getting-started
  • /develop
  • /operations
  • /api
  • /architecture
• Public pages (no sidebar) as MDX pages under site/src/pages/:
  • /glossary
  • /contributing
  • /llm-guide

Design System

Cruvero's docs theme is derived from the UI source of truth:

• cmd/ui/frontend/tailwind.config.ts
• cmd/ui/frontend/src/index.css

Required tokens:

• Dark background: #020617
• Surface: #0f172a / #1e293b
• Primary accent: #3b82f6 / #2563eb
• Status colors: success #22c55e, warning #f59e0b, danger #ef4444
• Fonts: body IBM Plex Sans, code JetBrains Mono

Content Rules (Public)

• Must migrate: docs/manual/**, docs/operations/**, docs/examples/**, phase overview specs under docs/phases/PHASE<NUM>.md.
• Must exclude: docs/notes/** (including docs/notes/sessions/**) and docs/.claude/**.
• Must not publish: prompt artifacts (docs/phases/*-PROMPT.md) and sub-phase specs (docs/phases/PHASE*<letter>.md). Link to GitHub instead.

---

Sub-Phases

Sub-Phase	Name	Prompts	Depends On
28A	Docusaurus Scaffold & Cruvero Theme	6	—
28B	Content Migration — Getting Started & Developer Guide	8	28A
28C	Content Migration — Operations, Architecture & Reference	7	28A
28D	API Reference, CLI Reference & Interactive Features	5	28B, 28C
28E	Search, SEO, Performance & CI/CD	4	28D
28F	Quality Assurance, Gap Closure & Polish	4	28A–28E

Total: 6 sub-phases, 34 prompts

Dependency Graph

28A (Scaffold & Theme)
 ├──→ 28B (Content: Getting Started + Developer Guide)  ──┐
 └──→ 28C (Content: Operations + Architecture + Reference) ──┤
                                                            ├──→ 28D (API/CLI/Interactive)
                                                            │          │
                                                            │          ▼
                                                            └──→ 28E (Search/SEO/CI)
                                                                       │
                                                                       ▼
                                                                  28F (QA & Polish)

---

Success Metrics

Metric	Target
site build	make site-build succeeds with zero warnings
Link validation	0 broken internal links (CI enforced)
Search	Cmd/Ctrl+K, indexes all public content
Coverage	100% of public source docs represented in the site
API	OpenAPI renders and includes all endpoints registered in internal/api/routes/*
CLI	CLI reference covers all cmd/*/main.go commands
Theme	Dark-first, matches UI tokens and typography