Docs platform decision: 2026-10-21

Docs platform decision: 2026-10-21

Status: decision, landed by O-DOCS (this wave), pending master merge. Supersedes: the Mintlify scaffold already on main in tcpsystems/docs (branch docs/mintlify-site). Authority: the estate design canon foxcorecloud/ops docs/design/design-direction-v2-2026-10-21.md.

The decision

Astro Starlight is the documentation platform for the estate front doors. It is the only candidate that satisfies all four standing criteria. The existing Mintlify scaffold on tcpsystems/docs is deprecated; its content is preserved for porting (see the rollout order below).

The four criteria

The platform decision is made against the same criteria the in-flight W202 decision document carried. They are constraints, not preferences:

1. Self-host-first. The site must build to static assets we own and serve ourselves. A platform that requires a vendor login, a GitHub App install, or a browser handoff is out.
2. Cloudflare Workers static hosting. The output must deploy to Cloudflare Pages or an asset-only Worker on the estate’s existing Cloudflare account. No new origin server, no Node runtime.
3. Per-brand theming. One shared token system, per-brand accent skins (tcp = Ember + Wire, foxcore = Ember, xenode = inherits Ember) that drop in without layout changes.
4. Search. Static, local, no service and no API key.
5. Markdown reuse. The docs are plain Markdown that already exists in tcpsystems/ops; the platform consumes it, it does not fork it.

Comparison

Criterion	Starlight	Mintlify	VitePress	Docusaurus
Self-host	Yes — static build	No — SaaS, GitHub App + browser login	Yes	Yes
CF Workers static	Yes — dist/ uploads	No	Yes	Yes
Per-brand theming	CSS custom props + customCss	Constrained, hosted	Vue components	React components
Search	Pagefind, built-in, local	Hosted API	minisearch (Vue)	Algolia or plugin
Markdown reuse	MD/MDX content collections	MDX, locked to platform	MD (Vue-flavoured)	MD (React-flavoured)
Stack fit	framework-agnostic	n/a	Vue	React

The estate’s front-end is SvelteKit (panel) and Go (daemons). VitePress and Docusaurus drag in Vue and React respectively, and both are heavier for a plain Markdown front door than Starlight. Starlight is the only candidate that is framework-neutral, static, and ships search with no service.

Cost

All candidates are $0 licence. The difference is operating cost and lock-in:

• Starlight — astro + @astrojs/starlight (MIT), Pagefind (MIT), fonts OFL 1.1. Build runs on the estate’s existing Cloudflare free tier. No recurring licence. The site is our asset.
• Mintlify — free tier is for public repositories only; tcpsystems/docs is private, so the estate pays Mintlify’s hosted plan and DNS is delegated to Mintlify. Recurring, non-zero, and not self-hosted — rejected on criterion 1 before cost matters.
• VitePress / Docusaurus — $0, but each pulls a second front-end framework into the estate for no benefit over Starlight.

The binding number is not a licence fee; it is that Mintlify is the only candidate that fails the self-host and CF-Workers criteria outright.

What shipped with this decision

• tcpsystems/docs converted to Starlight on branch docs/starlight-platform-2026-10-21.
• src/styles/tokens.css — the shared canon tokens (Kiln neutrals, type, radius, spacing, motion, one shadow).
• src/styles/fonts.css — Archivo + three Commit Mono cuts, self-hosted, metric-matched fallback.
• src/styles/themes/{tcp,foxcore,xenode}.css — the per-brand accent skins.
• src/lib/themes.mjs — the per-brand token module; DOCS_BRAND=tcp|foxcore|xenode swaps the skin at build time with no layout change.
• Seed content ported from tcpsystems/ops: the owner decision map, the balance watch, and the capacity expansion + finder surveys.