Spike: prototype fumadocs-mdx + Scalar docs pipeline on TanStack Start

[JSONbored]

Context

Both loopover-ui and metagraphed's apps/ui currently hand-author docs as individual TanStack Router route files (docs.<slug>.tsx), each a full React component with hardcoded JSX content, meta tags, and manually-maintained nav entries in docs.index.tsx. This doesn't scale: every content edit touches a component file, there's no structured content model, no generated navigation, and no search. It also means every "add a docs page" contributor issue currently asks for a whole hand-built route rather than prose.

Decided direction (2026-07-15, after research into Mintlify, Fumadocs, Docusaurus, Nextra, Starlight, Content Collections, and Scalar): fumadocs-core + fumadocs-mdx (headless — not fumadocs-ui's full component shell) as the MDX content/structure/search layer, rendered through the existing <DocsPage>/Callout/CodeBlock ui-kit primitives, plus Scalar's @scalar/api-reference (MIT, self-hosted, framework-agnostic) for the API playground instead of fumadocs-openapi.

This is a spike, not a committed integration, because of two real open risks that need proving, not assuming:

1. fumadocs-openapi's createAPIPage has documented, recent compatibility issues in TanStack/Vite environments — this is why the plan routes around it entirely via Scalar rather than trying to make it work.
2. Both apps run Vite through @lovable.dev/vite-tanstack-config, a managed preset that explicitly warns against adding plugins directly ("do NOT add them manually or the app will break with duplicate plugins"). Fumadocs' official TanStack Start guide assumes a bare TanStack Start + Vite setup — it has never been tested against this specific wrapped preset. fumadocs-mdx/vite's plugin has to go through the preset's vite: {...} passthrough; whether that works cleanly (particularly around React/JSX processing, since viteReact is already registered by the preset) is unverified.

Requirements — this is a bounded proof, not a full migration

• Add fumadocs-core + fumadocs-mdx to loopover-ui and get the Vite plugin working through @lovable.dev/vite-tanstack-config's vite: {...} passthrough, without duplicate-plugin breakage (dev server AND a real npm run build must both succeed — a dev-only proof isn't sufficient given the preset's own comments flag build-vs-dev-vs-sandbox differences).
• Define one defineDocs/content-source config and migrate exactly one existing page — docs.self-hosting-quickstart.tsx is the suggested candidate (already read and understood from the recent AMS-docs work) — into an .mdx file, rendered through fumadocs-core's page-tree/source API but using the existing <DocsPage>/Callout/CodeBlock components from the ui-kit for actual markup, not fumadocs-ui's bundled components. Confirm visual output is unchanged from the current hand-built page.
• Confirm Fumadocs' built-in Orama search indexes the migrated page and returns real results, self-hosted (no external search service).
• Confirm nav/sidebar can be generated from the content source's page tree instead of a hand-maintained array like docs.index.tsx's AUDIENCES.
• Separately, add @scalar/api-reference as a standalone page or embed pointed at the existing OpenAPI JSON output (ui:openapi), and confirm the interactive "Try it" playground actually issues a request against a real endpoint.
• Write up findings in a PR-description-length report (not a new markdown doc under docs/ — post as a PR description or issue comment, since it's a decision record, not user-facing content): what worked, what didn't, the exact working Vite config diff, whether the Lovable-preset passthrough needed anything non-obvious, and a clear go/no-go recommendation with a fallback (Content Collections was the runner-up architecture during research) if something in here turns out to be a blocker.

Deliverables

• Working fumadocs-mdx Vite integration in loopover-ui, both dev and production build green
• One real page (docs.self-hosting-quickstart.tsx's content) migrated to .mdx, rendered via existing ui-kit primitives, visually equivalent to today
• Working Orama search over the migrated content
• Working Scalar API reference page against the existing OpenAPI output
• A written findings report with a go/no-go recommendation, posted as the PR description

Test Coverage Requirements

This is UI/tooling work under apps/loopover-ui/** — outside coverage.include per this repo's convention, so Codecov's patch gate does not apply. If the spike touches anything under src/** (it shouldn't), that would inherit the normal 99%+ patch requirement.

Expected Outcome

A proven, working integration pattern (or a clear, evidenced reason it doesn't work here) that the AMS-docs migration (#6012 and its sub-issues, currently paused) and metagraphed's docs-page migration (currently paused) can both be re-scoped against, instead of guessing.

Links & Resources

• apps/loopover-ui/vite.config.ts (the managed preset to integrate through)
• apps/loopover-ui/src/routes/docs.self-hosting-quickstart.tsx (candidate page to migrate)
• apps/loopover-ui/src/routes/docs.index.tsx (nav to eventually replace)
• Fumadocs TanStack Start guide, Vite/TanStack MDX setup
• Scalar API reference
• Epic: port AMS's raw-markdown operator guides to proper website docs pages #6012 and its sub-issues docs(ams): port DEPLOYMENT.md to a website docs page (docs.ams-deployment.tsx) #6022-docs(ams): decide + possibly port BENCHMARKS.md to a website docs page #6032 (paused pending this spike)

[linear-code]

JSO-4136