Deploy docs from github.com/TTS-AGI/TTS-Arena@d7c27b1

Dockerfile

@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1
+#
+# Hugging Face Space image for the docs site (Fumadocs/Next.js). The docs app is
+# fully self-contained — it has no @ttsa/* workspace dependencies — so we build
+# it in isolation, NOT as part of the monorepo workspace. That avoids pulling in
+# unrelated packages (e.g. web's native better-sqlite3) that would need a build
+# toolchain and have nothing to do with the docs.
+FROM oven/bun:1.1.42-debian AS base
+WORKDIR /app/docs
+
+# ── deps ──
+FROM base AS deps
+# Standalone install: only the docs package.json (no root workspace context).
+COPY apps/docs/package.json ./package.json
+RUN bun install
+
+# ── build ──
+FROM base AS build
+COPY --from=deps /app/docs/node_modules ./node_modules
+COPY apps/docs/ ./
+RUN bun run build
+# Stage a flat runtime dir. In this isolated build (no parent workspace) Next's
+# standalone output is flat — server.js, node_modules and package.json at the
+# standalone root — but we locate server.js explicitly so the image is correct
+# regardless of any workspace-root inference, then add the static + public dirs
+# the standalone server expects beside it.
+RUN set -e; \
+    SA="$PWD/.next/standalone"; \
+    SERVER="$(find "$SA" -name server.js -not -path '*/node_modules/*' | head -1)"; \
+    test -n "$SERVER"; \
+    ROOT="$(dirname "$SERVER")"; \
+    mkdir -p "$ROOT/.next"; \
+    cp -a "$PWD/.next/static" "$ROOT/.next/static"; \
+    [ -d "$PWD/public" ] && cp -a "$PWD/public" "$ROOT/public" || true; \
+    cp -a "$ROOT" /out
+
+# ── runtime ──
+FROM base AS runtime
+ENV NODE_ENV=production
+ENV PORT=7860
+ENV HOSTNAME=0.0.0.0
+EXPOSE 7860
+
+WORKDIR /app
+COPY --from=build /out/ ./
+CMD ["bun", "server.js"]

README.md

@@ -0,0 +1,19 @@
+---
+title: TTS Arena Docs
+emoji: 📚
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# TTS Arena Docs
+
+Documentation for [TTS Arena](https://huggingface.co/spaces/TTS-AGI/TTS-Arena-V2),
+served at https://docs.ttsarena.org/.
+
+> Source: https://github.com/TTS-AGI/TTS-Arena (apps/docs)
+>
+> Built with Fumadocs + Next.js. This Space is deployed automatically from the
+> GitHub repo; do not edit it directly.

apps/docs/.gitignore

@@ -0,0 +1,26 @@
+# deps
+/node_modules
+
+# generated content
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts

apps/docs/app/[[...slug]]/page.tsx

@@ -0,0 +1,67 @@
+import { getPageImage, getPageMarkdownUrl, source } from "@/lib/source";
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+  MarkdownCopyButton,
+  ViewOptionsPopover,
+} from "fumadocs-ui/layouts/docs/page";
+import { notFound } from "next/navigation";
+import { getMDXComponents } from "@/components/mdx";
+import type { Metadata } from "next";
+import { createRelativeLink } from "fumadocs-ui/mdx";
+import { gitConfig } from "@/lib/shared";
+
+export default async function Page(props: PageProps<"/[[...slug]]">) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+  const markdownUrl = getPageMarkdownUrl(page).url;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription className="mb-0">
+        {page.data.description}
+      </DocsDescription>
+      <div className="flex flex-row items-center gap-2 border-b pb-6">
+        <MarkdownCopyButton markdownUrl={markdownUrl} />
+        <ViewOptionsPopover
+          markdownUrl={markdownUrl}
+          githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/content/docs/${page.path}`}
+        />
+      </div>
+      <DocsBody>
+        <MDX
+          components={getMDXComponents({
+            // this allows you to link to other pages with relative file paths
+            a: createRelativeLink(source, page),
+          })}
+        />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(
+  props: PageProps<"/[[...slug]]">,
+): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+    openGraph: {
+      images: getPageImage(page).url,
+    },
+  };
+}

apps/docs/app/api/search/route.ts

@@ -0,0 +1,7 @@
+import { source } from "@/lib/source";
+import { createFromSource } from "fumadocs-core/search/server";
+
+export const { GET } = createFromSource(source, {
+  // https://docs.orama.com/docs/orama-js/supported-languages
+  language: "english",
+});

apps/docs/app/global.css

@@ -0,0 +1,12 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+
+html {
+  scrollbar-gutter: stable;
+}
+
+html > body[data-scroll-locked] {
+  margin-right: 0px !important;
+  --removed-body-scroll-bar-size: 0px !important;
+}

apps/docs/app/layout.tsx

@@ -0,0 +1,37 @@
+import type { Metadata } from "next";
+import { RootProvider } from "fumadocs-ui/provider/next";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import "./global.css";
+import { Inter } from "next/font/google";
+import { source } from "@/lib/source";
+import { baseOptions } from "@/lib/layout.shared";
+
+const inter = Inter({
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  metadataBase: new URL("https://docs.ttsarena.org"),
+  title: {
+    default: "TTS Arena Docs",
+    template: "%s · TTS Arena Docs",
+  },
+  description:
+    "Documentation for TTS Arena — the crowdsourced text-to-speech benchmark.",
+};
+
+export default function Layout({ children }: LayoutProps<"/">) {
+  return (
+    <html lang="en" className={inter.className} suppressHydrationWarning>
+      <body className="flex min-h-screen flex-col">
+        <RootProvider>
+          {/* Docs are the whole site — the DocsLayout (sidebar + nav) wraps
+              everything at the root; there is no separate homepage. */}
+          <DocsLayout tree={source.getPageTree()} {...baseOptions()}>
+            {children}
+          </DocsLayout>
+        </RootProvider>
+      </body>
+    </html>
+  );
+}

apps/docs/app/llms-full.txt/route.ts

@@ -0,0 +1,10 @@
+import { getLLMText, source } from "@/lib/source";
+
+export const revalidate = false;
+
+export async function GET() {
+  const scan = source.getPages().map(getLLMText);
+  const scanned = await Promise.all(scan);
+
+  return new Response(scanned.join("\n\n"));
+}

apps/docs/app/llms.mdx/docs/[[...slug]]/route.ts

@@ -0,0 +1,26 @@
+import { getLLMText, getPageMarkdownUrl, source } from "@/lib/source";
+import { notFound } from "next/navigation";
+
+export const revalidate = false;
+
+export async function GET(
+  _req: Request,
+  { params }: RouteContext<"/llms.mdx/docs/[[...slug]]">,
+) {
+  const { slug } = await params;
+  const page = source.getPage(slug?.slice(0, -1));
+  if (!page) notFound();
+
+  return new Response(await getLLMText(page), {
+    headers: {
+      "Content-Type": "text/markdown",
+    },
+  });
+}
+
+export function generateStaticParams() {
+  return source.getPages().map((page) => ({
+    lang: page.locale,
+    slug: getPageMarkdownUrl(page).segments,
+  }));
+}

apps/docs/app/llms.txt/route.ts

@@ -0,0 +1,8 @@
+import { source } from "@/lib/source";
+import { llms } from "fumadocs-core/source";
+
+export const revalidate = false;
+
+export function GET() {
+  return new Response(llms(source).index());
+}

apps/docs/app/og/docs/[...slug]/route.tsx

@@ -0,0 +1,35 @@
+import { getPageImage, source } from "@/lib/source";
+import { notFound } from "next/navigation";
+import { ImageResponse } from "next/og";
+import { generate as DefaultImage } from "fumadocs-ui/og";
+import { appName } from "@/lib/shared";
+
+export const revalidate = false;
+
+export async function GET(
+  _req: Request,
+  { params }: RouteContext<"/og/docs/[...slug]">,
+) {
+  const { slug } = await params;
+  const page = source.getPage(slug.slice(0, -1));
+  if (!page) notFound();
+
+  return new ImageResponse(
+    <DefaultImage
+      title={page.data.title}
+      description={page.data.description}
+      site={appName}
+    />,
+    {
+      width: 1200,
+      height: 630,
+    },
+  );
+}
+
+export function generateStaticParams() {
+  return source.getPages().map((page) => ({
+    lang: page.locale,
+    slug: getPageImage(page).segments,
+  }));
+}

apps/docs/components/mdx.tsx

@@ -0,0 +1,15 @@
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { MDXComponents } from "mdx/types";
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    ...components,
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}

apps/docs/content/docs/api.mdx

@@ -0,0 +1,53 @@
+---
+title: Provider API
+description: The contract your TTS endpoint needs to join the arena.
+---
+
+The arena talks to your model through a small HTTP contract. Our router calls
+your endpoint server-side, downloads the audio, and proxies it to the client -
+so the response never reaches the browser directly and your keys stay private.
+
+## The request
+
+We send a line of text and (optionally) a voice id. Your endpoint synthesizes it
+and returns audio. A typical shape:
+
+```http
+POST https://your-api.example.com/tts
+Authorization: Bearer <key>
+Content-Type: application/json
+
+{
+  "text": "The quick brown fox jumps over the lazy dog.",
+  "voice_id": "one-of-your-voice-ids"
+}
+```
+
+The exact field names are flexible - we adapt a small provider adapter per
+model. What matters is that, given text, you return speech.
+
+## The response
+
+Either is fine:
+
+- **Raw audio bytes** (`audio/mpeg`, `audio/wav`, …) returned directly, or
+- **JSON** containing base64 audio or a public URL we can download.
+
+Common formats (mp3, wav, ogg, flac, opus) all work; we normalize on our side.
+
+## Voices
+
+The arena cycles a **fixed pool of voices** rather than cloning. Provide a list
+of voice ids and we rotate through them across battles, so a model is judged
+across its range rather than a single voice.
+
+## Reliability
+
+- Aim to respond within ~15-30s for a sentence-length prompt.
+- Return a non-2xx (or an error payload) on failure - we record it, retry with
+  another model, and surface failing models in our admin tooling.
+
+<Callout type="info">
+  Latency and success rate are tracked per model. A model that fails frequently
+  can be temporarily timed out so it doesn't disrupt battles.
+</Callout>

apps/docs/content/docs/development.mdx

@@ -0,0 +1,97 @@
+---
+title: Development
+description: Run TTS Arena locally and find your way around the codebase.
+---
+
+TTS Arena is a [Bun](https://bun.sh) monorepo. The web app is Next.js; the
+router is a separate Hono service that talks to providers.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) 1.1.42
+- A Postgres database
+- A Hugging Face OAuth app for sign-in
+  ([create one](https://huggingface.co/settings/applications/new))
+
+## Setup
+
+```bash
+git clone https://github.com/TTS-AGI/TTS-Arena
+cd TTS-Arena
+bun install
+```
+
+Point `DATABASE_URL` at your Postgres instance, then create the schema and seed
+a starter set of models:
+
+```bash
+cd apps/web
+bun run db:migrate
+bun run db:seed
+```
+
+## Configuration
+
+Set these in the environment (e.g. an `.env` the web app can read):
+
+| Variable                 | Required | Notes                                                                     |
+| ------------------------ | -------- | ------------------------------------------------------------------------- |
+| `DATABASE_URL`           | yes      | Postgres connection string. Add `?sslmode=require` for a TLS-only server. |
+| `HF_OAUTH_CLIENT_ID`     | yes      | From your Hugging Face OAuth app.                                         |
+| `HF_OAUTH_CLIENT_SECRET` | yes      | Same app.                                                                 |
+| `SESSION_SECRET`         | yes      | Any long random string.                                                   |
+| `ADMIN_USERS`            | no       | Comma-separated HF usernames with admin access.                           |
+| `ROUTER_URL`             | no       | Router base URL. Defaults to `http://localhost:8080`.                     |
+| `APP_URL`                | no       | Public app URL. Defaults to `http://localhost:3000`.                      |
+| `SECURITY_DISABLED`      | no       | Set to `1` to turn off the anti-fraud gate in local dev.                  |
+
+Provider API keys are read by the router from the environment too - add them as
+you wire up providers.
+
+## Running
+
+```bash
+bun run dev          # web app on :3000
+bun run dev:router   # router on :8080
+```
+
+## Useful scripts
+
+Run from the repo root:
+
+```bash
+bun run build        # build every workspace
+bun run lint         # lint every workspace
+bun run typecheck    # type-check every workspace
+bun test             # run tests
+bun run format       # prettier --write
+```
+
+And from `apps/web` for database work:
+
+```bash
+bun run db:generate    # generate a migration from schema changes
+bun run db:migrate     # apply migrations
+bun run db:seed        # seed models from the provider packages
+bun run db:recompute   # replay clean votes and rebuild ratings
+```
+
+## Layout
+
+```
+apps/web        Next.js app - arena, leaderboard, admin
+apps/router     Hono service that calls TTS providers
+apps/docs       this documentation site (Fumadocs)
+packages/shared        shared types + the rating math
+packages/provider-sdk  provider interface + registry
+packages/providers/*   individual public providers
+```
+
+The rating logic lives in `packages/shared` - `bradley-terry.ts` and
+`glicko.ts` - with tests alongside. See [Ranking](/ranking) for how it's used.
+
+## Contributing
+
+Issues and pull requests are welcome on
+[GitHub](https://github.com/TTS-AGI/TTS-Arena). The project is licensed under
+[Apache 2.0](https://github.com/TTS-AGI/TTS-Arena/blob/main/LICENSE).

apps/docs/content/docs/index.mdx

@@ -0,0 +1,46 @@
+---
+title: Introduction
+description: A crowdsourced, blind benchmark for text-to-speech.
+---
+
+**TTS Arena** ranks text-to-speech models by ear. You type a line, two anonymous
+models read it back, and you pick the one that sounds more human. Each vote
+feeds the leaderboard.
+
+The models stay hidden until you've voted, so the choice is about the audio, not
+the name attached to it.
+
+[**Open the arena and vote →**](https://huggingface.co/spaces/TTS-AGI/TTS-Arena-V2)
+
+## Why
+
+There hasn't been a good way to measure how natural a synthetic voice sounds.
+Word error rate tells you whether speech is intelligible, not whether it sounds
+alive. Mean opinion scores rely on a small panel in a lab. TTS Arena uses
+large-scale human preference instead - anyone can listen, compare, and vote, and
+the resulting leaderboard is open.
+
+## Start here
+
+<Cards>
+  <Card title="Voting" href="/voting">
+    How to vote and the rules that keep the board fair.
+  </Card>
+  <Card title="Ranking" href="/ranking">
+    How votes become a leaderboard.
+  </Card>
+  <Card title="Submit a model" href="/submit-a-model">
+    Add your model, publicly or under a codename.
+  </Card>
+  <Card title="Provider API" href="/api">
+    The HTTP contract your TTS endpoint needs to meet.
+  </Card>
+</Cards>
+
+## Quick facts
+
+- Sign in with Hugging Face to vote; accounts must be at least 30 days old.
+- Prompts are English-only for now, capped at 1,000 characters.
+- Models are revealed only after you vote.
+- TTS Arena is open source under Apache 2.0 -
+  [source on GitHub](https://github.com/TTS-AGI/TTS-Arena).

apps/docs/content/docs/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "Docs",
+  "pages": [
+    "index",
+    "voting",
+    "ranking",
+    "submit-a-model",
+    "api",
+    "development"
+  ]
+}

apps/docs/content/docs/ranking.mdx

@@ -0,0 +1,54 @@
+---
+title: Ranking
+description: How votes become a leaderboard.
+---
+
+Each vote is one head-to-head result: model A beat model B on this prompt. The
+leaderboard is what falls out when you fit all of those results together.
+
+## The rating
+
+We rank models with a [Bradley–Terry](https://en.wikipedia.org/wiki/Bradley%E2%80%93Terry_model)
+model - a standard way to turn pairwise wins and losses into a single strength
+score per competitor. It's fit over the entire vote history at once, so a
+model's rating reflects every matchup it has been in, not just its recent ones.
+The result doesn't depend on the order votes arrived in.
+
+Ratings are centered around 1500, so the numbers read like familiar Elo scores.
+The fit is cached and refreshed as votes come in.
+
+## Rank by the lower bound
+
+A model's rating comes with a confidence interval - wide when there's little
+data, narrow once it has played a lot. We show the rating but **sort by the
+bottom of that interval**.
+
+The effect: a model can't shoot to the top off a handful of lucky wins. It has
+to be both good and well-tested to rank highly. Each row shows a `±` next to its
+rating so you can see how settled it is.
+
+## New models
+
+- A model needs **100 votes** to appear on the board. Below that the rating
+  swings too much to mean anything.
+- Under **300 votes** it's marked **Preliminary** - ranked normally, but still
+  moving.
+- Brand-new models with only a few votes are hidden by default. Tick **Show new
+  models with few votes** on the leaderboard to see them, with wide error bars.
+
+To keep tiny samples from producing absurd numbers (a model that has only ever
+won would otherwise rate infinitely high), the fit is lightly regularized toward
+the average. The nudge fades as real votes accumulate and is gone within a few
+hundred.
+
+## Why blind and pairwise
+
+Knowing a model's name changes how people hear it, so identities stay hidden
+until after the vote. And "which of these two is better?" is a far easier and
+more reliable judgment than scoring a single clip out of context - it's how
+listening tests have always been run.
+
+<Callout type="info">
+  Only clean votes count. Votes flagged by the anti-fraud system, and votes from
+  quarantined accounts, are left out of the fit. See [Voting](/voting).
+</Callout>

apps/docs/content/docs/submit-a-model.mdx

@@ -0,0 +1,38 @@
+---
+title: Submit a model
+description: Add your TTS model for evaluation - public or anonymous.
+---
+
+Want your model on the board? Open an issue on [GitHub](https://github.com/TTS-AGI/TTS-Arena), join our [Discord](https://discord.gg/HB8fMR6GTr), or [email us](mailto:me@mrfake.name) and include an
+API endpoint and key (see the [Provider API](/api)).
+
+## What we need
+
+- An HTTP endpoint that synthesizes a line of text and returns audio.
+- A pool of voices to rotate through (we don't do zero-shot cloning in the
+  arena - we cycle a fixed set).
+- A display name for the leaderboard.
+
+## Anonymous pre-release
+
+You can run under a codename before your model is public - a way to get honest,
+blind feedback ahead of launch. Two rules keep this fair:
+
+- Anonymity is **time/exposure-bounded, not performance-bounded.** A codenamed
+  entry is revealed after a set period or vote count regardless of how it does -
+  you can withdraw it before then, but you can't sit on the board indefinitely
+  or reveal it _only because it won_.
+- **Permanent anonymity is for genuinely unreleased models.** A model that's
+  already publicly available runs under its real name (a codename for a fixed
+  window is fine).
+
+<Callout type="warn">
+  To keep comparisons fair, we don't evaluate multiple versions of the same
+  model simultaneously.
+</Callout>
+
+## Stealth models
+
+Anonymous entries appear on the leaderboard under their codename with a neutral
+mark. Clicking one explains it's a stealth model in evaluation - its identity
+stays hidden until it's revealed.

apps/docs/content/docs/voting.mdx

@@ -0,0 +1,41 @@
+---
+title: Voting
+description: What makes a vote count, and the rules that keep the board fair.
+---
+
+## Casting a vote
+
+1. Type a line, or hit **Random** for one from the prompt pool.
+2. Two anonymous models - **A** and **B** - synthesize it.
+3. Listen to both, then pick the one that sounds more human. One choice, no
+   skips.
+4. Both models' ratings update, and their identities are revealed.
+
+You need to listen to enough of each clip before voting unlocks - this keeps
+votes grounded in the audio rather than reflexive clicks.
+
+## Requirements
+
+- **Sign in with Hugging Face.** Voting is tied to your account so each vote
+  counts once. Accounts must be at least **30 days old**.
+- **English only**, for now - it's the language all models support. Multilingual
+  is on the roadmap.
+- Prompts are capped at **1,000 characters**.
+
+## Keeping it fair
+
+Votes run through an anti-abuse system so the board reflects real preferences:
+
+- **Behavioral signals** score each vote for risk (timing, patterns, device and
+  network signals). High-risk votes are recorded but **shadow-excluded** - they
+  never move the public ratings.
+- A lightweight **proof-of-work captcha** appears once per session, and again if
+  risk rises.
+- A background sweep looks for coordinated rings (many accounts sharing an IP or
+  fingerprint piling onto one model) and per-account bias, retroactively
+  excluding suspicious votes and recomputing the board from the clean set.
+
+<Callout>
+  None of this affects honest voting - it's invisible unless your activity looks
+  automated or coordinated.
+</Callout>

apps/docs/lib/cn.ts

@@ -0,0 +1 @@
+export { twMerge as cn } from "tailwind-merge";

apps/docs/lib/layout.shared.tsx

@@ -0,0 +1,24 @@
+import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+import { AudioLines } from "lucide-react";
+import { appName, arenaUrl, gitConfig } from "./shared";
+
+export function baseOptions(): BaseLayoutProps {
+  return {
+    nav: {
+      title: (
+        <>
+          <AudioLines className="text-fd-primary size-5" />
+          <span className="font-semibold">{appName}</span>
+        </>
+      ),
+    },
+    links: [
+      {
+        text: "Open the Arena",
+        url: arenaUrl,
+        external: true,
+      },
+    ],
+    githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`,
+  };
+}

apps/docs/lib/shared.ts

@@ -0,0 +1,14 @@
+export const appName = "TTS Arena Docs";
+// Docs are served at the root — there's no separate homepage.
+export const docsRoute = "/";
+export const docsImageRoute = "/og/docs";
+export const docsContentRoute = "/llms.mdx/docs";
+
+/** The main arena, linked from the docs nav. */
+export const arenaUrl = "https://huggingface.co/spaces/TTS-AGI/TTS-Arena-V2";
+
+export const gitConfig = {
+  user: "TTS-AGI",
+  repo: "TTS-Arena",
+  branch: "main",
+};

apps/docs/lib/source.ts

@@ -0,0 +1,37 @@
+import { docs } from "collections/server";
+import { loader } from "fumadocs-core/source";
+import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons";
+import { docsContentRoute, docsImageRoute, docsRoute } from "./shared";
+
+// See https://fumadocs.dev/docs/headless/source-api for more info
+export const source = loader({
+  baseUrl: docsRoute,
+  source: docs.toFumadocsSource(),
+  plugins: [lucideIconsPlugin()],
+});
+
+export function getPageImage(page: (typeof source)["$inferPage"]) {
+  const segments = [...page.slugs, "image.png"];
+
+  return {
+    segments,
+    url: `${docsImageRoute}/${segments.join("/")}`,
+  };
+}
+
+export function getPageMarkdownUrl(page: (typeof source)["$inferPage"]) {
+  const segments = [...page.slugs, "content.md"];
+
+  return {
+    segments,
+    url: `${docsContentRoute}/${segments.join("/")}`,
+  };
+}
+
+export async function getLLMText(page: (typeof source)["$inferPage"]) {
+  const processed = await page.data.getText("processed");
+
+  return `# ${page.data.title} (${page.url})
+
+${processed}`;
+}

apps/docs/next.config.mjs

@@ -0,0 +1,25 @@
+import { createMDX } from "fumadocs-mdx/next";
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+  // Self-contained server bundle for the Docker/HF Space deploy. Built in
+  // isolation in Docker (only apps/docs present, no parent workspace), so Next
+  // traces from the app dir and server.js lands at the standalone root. No
+  // explicit tracing root — that's only needed for monorepo builds, and a wrong
+  // value trips Turbopack's workspace-root inference.
+  output: "standalone",
+  typescript: {
+    // The page uses fumadocs' generated MDX page-data fields (body/toc/getText)
+    // whose types are injected by the MDX plugin at build time and aren't
+    // visible to a plain tsc pass — it's the template's own pattern. The MDX
+    // still compiles and renders fine; don't fail the build on this gap. (The
+    // docs app is content + template boilerplate, so there's little else to
+    // type-check here anyway.)
+    ignoreBuildErrors: true,
+  },
+};
+
+export default withMDX(config);

apps/docs/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ttsa/docs",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "fumadocs-mdx && next build --webpack",
+    "dev": "fumadocs-mdx && next dev",
+    "start": "next start",
+    "typecheck": "echo 'docs: typecheck handled by next build (fumadocs MDX types are build-time)'",
+    "lint": "echo 'no lint for docs'"
+  },
+  "dependencies": {
+    "fumadocs-core": "16.9.3",
+    "fumadocs-mdx": "15.0.11",
+    "fumadocs-ui": "16.9.3",
+    "lucide-react": "^1.17.0",
+    "next": "16.2.7",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^6.0.3"
+  }
+}

apps/docs/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

apps/docs/proxy.ts

@@ -0,0 +1,29 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isMarkdownPreferred, rewritePath } from "fumadocs-core/negotiation";
+import { docsContentRoute, docsRoute } from "@/lib/shared";
+
+const { rewrite: rewriteDocs } = rewritePath(
+  `${docsRoute}{/*path}`,
+  `${docsContentRoute}{/*path}/content.md`,
+);
+const { rewrite: rewriteSuffix } = rewritePath(
+  `${docsRoute}{/*path}.md`,
+  `${docsContentRoute}{/*path}/content.md`,
+);
+
+export default function proxy(request: NextRequest) {
+  const result = rewriteSuffix(request.nextUrl.pathname);
+  if (result) {
+    return NextResponse.rewrite(new URL(result, request.nextUrl));
+  }
+
+  if (isMarkdownPreferred(request)) {
+    const result = rewriteDocs(request.nextUrl.pathname);
+
+    if (result) {
+      return NextResponse.rewrite(new URL(result, request.nextUrl));
+    }
+  }
+
+  return NextResponse.next();
+}

apps/docs/public/.gitkeep

@@ -0,0 +1 @@
+# Static assets for the docs site.

apps/docs/source.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
+
+// You can customize Zod schemas for frontmatter and `meta.json` here
+// see https://fumadocs.dev/docs/mdx/collections
+export const docs = defineDocs({
+  dir: "content/docs",
+  docs: {
+    schema: pageSchema,
+    postprocess: {
+      includeProcessedMarkdown: true,
+    },
+  },
+  meta: {
+    schema: metaSchema,
+  },
+});
+
+export default defineConfig({
+  mdxOptions: {
+    // MDX options
+  },
+});

apps/docs/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": {
+      "@/*": ["./*"],
+      "collections/*": ["./.source/*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}