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

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.4.0-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.4.0
+- 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,52 @@
+---
+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="Integrity policy" href="/integrity">
+    The short version of what providers agree to.
+  </Card>
+  <Card title="Provider Agreement" href="/provider-agreement">
+    The full terms for listing a model on the arena.
+  </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/integrity-decisions.mdx

@@ -0,0 +1,96 @@
+---
+title: Integrity decisions
+description: The public record of models suspended from TTS Arena for vote manipulation — what happened, the provider's response, and the outcome in each case.
+---
+
+TTS Arena ranks text-to-speech models through blind A/B voting: voters hear two clips and pick the better one, and the leaderboard is computed from those votes. Manipulated votes break that evaluation.
+
+This page is the public record of models suspended for vote manipulation. In every case below, the matter was put to the provider before a decision was made, and the outcome was the same: the manipulated votes were excluded, the leaderboard was recomputed from clean votes, and the model was suspended.
+
+Decisions are made under the [Provider Agreement](/provider-agreement). Providers may not vote on their own model, through staff or anyone acting for them (s4.1), or use any side channel, including the sound of their own model, to work out which clip is theirs (s4.2). Intent is not the test, and decisions are final (s9). A suspended model stays on the board, unranked, at the bottom, with the reason and date shown; the label has no expiry, and the model cannot be retracted, withdrawn, renamed, or resubmitted under another name (s8.3).
+
+## Suspended models
+
+| Model                        | Provider      | Suspended  | Accounts             | Votes excluded |
+| ---------------------------- | ------------- | ---------- | -------------------- | -------------- |
+| SwanTale (listed as "Venus") | SwanTale team | 2026-10-31 | 3                    | 170            |
+| Audio8-TTS-Realistic-0.6B    | Edge0         | 2026-10-30 | 11                   | 670            |
+| U2-TTS                       | Unisound      | 2026-09-05 | 5                    | 703            |
+| Vocu V3.0                    | Vocu          | 2026-07-03 | Provider-linked ring | ~4,900         |
+
+## Cases
+
+### SwanTale (stealth codename "Venus") — suspended 2026-10-31
+
+**Provider:** SwanTale team
+
+SwanTale was listed under the stealth codename "Venus" and is now displayed under its real name.
+
+- Between 2026-10-27 and 2026-10-28, three accounts cast 170 votes. The account names were the submitting group's own research project names, and the accounts were active in sequence with no overlap.
+- The three accounts saw Venus in 33 battles and picked Venus in all 33. Other voters picked Venus about 60% of the time.
+- The provider's first response: the accounts belonged to two different students and were not team-controlled.
+- After the evidence was shared, the provider's second response confirmed that a team member had organised the voting, that two colleagues had voted through the group's shared project accounts, and that a VPN/proxy had been used. The provider accepted the suspension.
+
+From the provider's response:
+
+> "I sincerely apologize for encouraging and coordinating votes in support of Venus."
+
+> "I acknowledge that we also deliberately took turns to make the coordinated activity less conspicuous. This was inappropriate, and I deeply regret it."
+
+**Outcome.** The 170 votes were excluded, SwanTale's rating was recomputed from 1722 to approximately 1508, and the model was suspended.
+
+### Audio8-TTS-Realistic-0.6B — suspended 2026-10-30
+
+**Provider:** Edge0
+
+- Audio8-TTS-Realistic-0.6B was listed on 2026-10-23. Starting on listing day, eleven accounts — Edge0 staff and company-linked accounts — cast 670 votes.
+- These accounts saw Audio8 in 149 battles and picked it 121 times (81%). Other voters picked Audio8 57% of the time.
+- The provider confirmed the accounts and the activity, describing an office group session of roughly an hour in which colleagues were invited to listen after Audio8 wins and so became familiar with its voices. Per the provider, the activity stopped once the rating rose sharply, and the team had been unaware of the affiliated-voting ban.
+- The voting records show activity from 02:08 to 11:50 UTC on 2026-10-23 — roughly ten hours — and one of the accounts voted again on 2026-10-26 and 2026-10-27.
+- Recognising the model's own voice and picking it is un-blinding under s4.2; under s9, intent is not the test.
+
+From the provider's response:
+
+> "The account connections and voting activity you described are real: I participated myself"
+
+**Outcome.** The provider agreed to the exclusion of the votes and asked for the suspension and label to be lifted; the request was declined. The 670 votes were excluded, the rating was recomputed from approximately 1690 to approximately 1590, and the model's clean battle count fell from 182 to 47. The model was suspended.
+
+### U2-TTS — suspended 2026-09-05
+
+**Provider:** Unisound
+
+- Between 2026-08-21 and 2026-09-04, five accounts cast 703 votes. Per the provider, two of the accounts were company test accounts and one was an employee's personal account.
+- The five accounts voted almost only when U2-TTS appeared in a battle and abandoned most other battles. Voters generally vote at the same rate whether or not a given model appears.
+- The accounts covered 295 of the model's 452 battles. On 2026-08-31 — the day U2-TTS passed 300 votes, the threshold at which the Preliminary label is removed — they covered 265 of 321.
+- Outside voters picked U2-TTS in 54% of battles (85 of 157); the employee account picked it in 93% (38 of 41). The model's listed win rate was 63%.
+- On a call, the provider said the voters had recognised U2-TTS by its voice and picked it when outputs sounded similar, and that the vote count had been watched with the goal of passing 300 votes to drop the Preliminary label. The provider said it had been unaware that this counted as manipulation.
+
+The provider, describing the voting pattern:
+
+> "we didn't want to spend too much time listening and waiting for the voting buttons to appear just to cast votes, when we did not hear our system sound (i.e, there is no our model in A/B test), because that would have significantly increased our time cost and slowed down our overall evaluation process."
+
+The provider asked, in order, for: the votes to be excluded and the model relisted; the model to be retracted and re-evaluated from scratch; the listing to be renamed; the model to be removed from the public board. All four requests were declined — under s8.3 a suspended model cannot be retracted, renamed, or resubmitted, and under s9 decisions are final.
+
+**Outcome.** The 703 votes were excluded, the board was recomputed, and the model was suspended. After this case, an explicit rule was added: provider staff may not vote on their own model.
+
+### Vocu V3.0 — suspended 2026-07-03
+
+**Provider:** Vocu
+
+- A ring of provider-linked accounts cast roughly 4,900 votes. The volume and regularity of the voting indicated automation, not listening.
+- When Vocu appeared in a battle, the ring's four main accounts picked it 99% of the time. Among 202 other voters, Vocu won 33% of the time.
+- The provider first denied owning a linked account. When shown that the account was registered to an email address belonging to the provider, the provider confirmed it and apologised.
+
+The provider's first reply:
+
+> "I actually don't even own that account..."
+
+And after being shown the registration:
+
+> "Yes, this is my email address. I apologize for my earlier moment of rashness in trying to justify our wrongdoing — it was deeply shameful of me."
+
+**Outcome.** The roughly 4,900 votes were excluded, the board was recomputed, and the model was suspended.
+
+## Reporting
+
+To report suspected vote manipulation or any other breach of the [Provider Agreement](/provider-agreement), use [Discord](https://discord.gg/HB8fMR6GTr) or [email](mailto:me@mrfake.name). All reports are reviewed.

apps/docs/content/docs/integrity.mdx

@@ -0,0 +1,36 @@
+---
+title: Integrity policy
+description: The short version of what providers agree to. The full terms are in the Provider Agreement.
+---
+
+TTS Arena only works if the votes are real. Every provider accepts this policy
+by submitting a model. The full terms are in the
+[Provider Agreement](/provider-agreement); this page is the part that matters
+most, kept short so there is no excuse for not reading it.
+
+## Rules
+
+1. **Nobody on your side votes on your model.** Not staff, contractors, agencies,
+   or anyone you ask. Not from personal accounts, not from "test accounts".
+2. **You don't un-blind the arena.** No matching endpoint logs to arena
+   sessions, no audio tells, no side channel that reveals which side is yours.
+3. **No bought, botted, or coordinated votes.**
+4. **The arena is for ranking, not internal evaluation.** Want to hear your
+   model next to others? Type a custom prompt - those votes never move the board.
+5. **We know who you are**, even for codenamed entries, and you answer honestly
+   when we ask.
+
+## If it's broken
+
+- The votes are excluded and the board is recomputed.
+- The model is **suspended**: it stays on the leaderboard, at the bottom, with a
+  label saying why and when. The label doesn't expire. Suspended models can't be
+  retracted, renamed, or withdrawn.
+- We may publish what happened, including what the provider told us.
+
+Nothing is deleted, so the record can be checked. Past cases are listed in
+[Integrity decisions](/integrity-decisions). Decisions are made by the
+TTS Arena team and are final.
+
+Questions: [Discord](https://discord.gg/HB8fMR6GTr) or
+[email](mailto:me@mrfake.name).

apps/docs/content/docs/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Docs",
+  "pages": [
+    "index",
+    "voting",
+    "ranking",
+    "submit-a-model",
+    "integrity",
+    "integrity-decisions",
+    "provider-agreement",
+    "privacy",
+    "api",
+    "development"
+  ]
+}

apps/docs/content/docs/privacy.mdx

@@ -0,0 +1,83 @@
+---
+title: Privacy
+description: What TTS Arena collects, why, and what we do with it.
+---
+
+TTS Arena is a volunteer-run, open-source research project. We collect what we
+need to keep the votes honest and to build a useful benchmark, and not much
+else. This page says what that is in plain terms.
+
+## What we collect
+
+**When you sign in** with Hugging Face, we receive your Hugging Face user ID,
+username, avatar, account creation date, and the email address on the account.
+The account age is used for the 30-day voting requirement. The email is stored
+so we can contact you about your account (for example, if it's been
+quarantined) and is not used for anything else.
+
+**When you use the arena**, we record:
+
+- the prompts you submit and the audio each model produced for them;
+- your votes, and how long you listened before voting;
+- your IP address, browser user-agent, and a device fingerprint, on sign-in and
+  with each vote;
+- session events - battles started, whether they were voted on or abandoned,
+  generation timings and errors.
+
+A **captcha** may run once per browser. It stores a short-lived token and
+nothing about you.
+
+## Why
+
+Almost all of this exists for one reason: a blind preference benchmark is only
+worth something if the votes are real. IP, fingerprint, timing, and session
+data are what let us spot automated voting, coordinated rings, and accounts
+that can somehow recognise a model they shouldn't be able to. The
+[voting](/voting) page describes how that system works.
+
+The prompts and audio are the benchmark itself. They're what we and others can
+use to study how people judge synthetic speech.
+
+## What we publish
+
+- The leaderboard: per-model ratings, uncertainty, win rates, and vote counts.
+  Never per-voter data.
+- Aggregate statistics and, from time to time, anonymised datasets of prompts,
+  audio, and preferences. These contain no account identifiers, IP addresses,
+  fingerprints, or email addresses.
+- Accounts of integrity findings against model providers. These name the model
+  and the provider, and can quote what the provider told us. They can describe
+  the behaviour of accounts involved. See the
+  [Provider Agreement](/provider-agreement).
+
+## What we don't do
+
+- We don't sell data, run ads, or share personal data with model providers.
+  Providers see their model's ratings, not who voted.
+- We don't send your identity to the model endpoints. They receive the prompt
+  text, nothing else.
+- We don't track you across other sites.
+
+## Retention
+
+We keep vote, session, and anti-abuse records indefinitely, because a decision
+about the leaderboard has to remain checkable after the fact. Cached audio is
+kept as long as it's useful to the benchmark.
+
+If you want your account data removed, contact us. We'll delete your profile
+information (username, email, avatar). Vote records may be retained in
+anonymised form so the leaderboard's history remains consistent.
+
+## Where it lives
+
+The app runs on Hugging Face Spaces; the database runs on a server we operate.
+Hugging Face handles the sign-in and has its own
+[privacy policy](https://huggingface.co/privacy). TTS Arena is not affiliated
+with Hugging Face.
+
+## Contact
+
+Questions or deletion requests: [Discord](https://discord.gg/HB8fMR6GTr) or
+[email](mailto:me@mrfake.name).
+
+_Last updated 5 September 2026._

apps/docs/content/docs/provider-agreement.mdx

@@ -0,0 +1,218 @@
+---
+title: Provider Agreement
+description: The terms under which a model is listed and evaluated on TTS Arena.
+---
+
+_Effective 5 September 2026._
+
+This agreement is between the **TTS Arena** project ("TTS Arena", "we", "us")
+and any person or organisation that submits a text-to-speech model for
+evaluation (the "Provider", "you"). By submitting a model, or by leaving a model
+listed after this agreement is posted, you accept it on behalf of yourself and
+the organisation you represent.
+
+It is written in plain English on purpose. Where it says "must", it means it.
+
+## 1. Who we are
+
+TTS Arena is an independent, open-source community project maintained by
+volunteers. **It is not affiliated with, operated by, sponsored by, or endorsed
+by Hugging Face, Inc.**, or by any model provider. The arena is hosted on
+Hugging Face Spaces and uses Hugging Face accounts for sign-in, in the same way
+any third-party project may; that does not make it a Hugging Face product, and
+nothing in the arena's rankings, labels, or communications is a statement by
+Hugging Face. The source is public under the Apache 2.0 licence.
+
+## 2. Submitting a model
+
+1. **Accurate information.** Everything you tell us about the model - its name,
+   provider, whether it is publicly available, which model is actually behind
+   the endpoint - must be true, and you must tell us when it changes.
+2. **Identity.** You must tell us who you are: the organisation, and a contact
+   who can speak for it. This applies to codenamed entries too (see section 5).
+3. **Authority.** The person submitting confirms they are authorised to bind the
+   Provider to this agreement.
+4. **One model, one entry.** We evaluate one version of a model at a time. A new
+   version is a new submission, and we may decline to run two entries from the
+   same provider that are substantially the same model.
+5. **Our discretion.** We may accept, decline, delay, or remove any submission,
+   for any reason, including capacity, cost, and the integrity of the board.
+
+## 3. The endpoint
+
+1. **It serves the model you said it does**, and the same model that users of
+   your product get. No arena-specific tuning, no better model for arena
+   traffic, no silent swaps. If you change what is behind the endpoint, tell us
+   first; we will decide whether the entry continues or restarts.
+2. **Prompt handling.** The endpoint must synthesise what it is given. It must
+   not detect arena prompts, treat arena traffic differently from ordinary
+   traffic, or cache and replay outputs for known prompts. If it refuses a
+   prompt (for example on safety grounds), it must return an error, not degraded
+   audio.
+3. **Voices.** You supply a fixed pool of voices for us to rotate through. We do
+   not do zero-shot cloning in the arena.
+4. **Availability.** The endpoint should be reliably available. We may time out,
+   retire, or remove a model whose endpoint is failing, slow enough to distort
+   the listening test, or rate-limiting the arena below what evaluation needs.
+5. **Cost.** You bear the cost of serving your own endpoint, and you must not
+   charge the arena for it. We may cap the volume of requests we send.
+6. **Keys.** We keep your API credentials confidential, use them only for the
+   arena, and delete them when the model is retired. You may rotate them at any
+   time by telling us.
+
+## 4. Integrity
+
+The [integrity policy](/integrity) is part of this agreement. In full:
+
+1. **No voting on your own model** by anyone on your side: employees,
+   contractors, interns, agencies, investors, family, communities you run, or
+   anyone acting at your request or with your encouragement. This includes
+   personal accounts and any "test" or shared accounts. You must not create,
+   lend, or control voter accounts.
+2. **No un-blinding.** You must not use your endpoint's request logs,
+   timestamps, telemetry, watermarks, audio artefacts, prompt matching, or any
+   other side channel to work out which side of a battle is yours, whether or
+   not you then vote. The arena is a blind test; defeating the blind for
+   yourself defeats the test.
+3. **No purchased, incentivised, automated, or coordinated votes.** No paying
+   or rewarding people for votes, no bots or scripts, no vote drives, no asking
+   a community to "go vote for us".
+4. **No selective participation.** You must not use the arena as an internal
+   evaluation harness - for example, generating battles and abandoning the ones
+   your model isn't in. Compare models with your own tooling, or with custom
+   prompts here, which do not affect the ratings.
+5. **No harvesting.** You must not scrape the arena, or use it to collect other
+   providers' audio, prompts, or outputs for training, benchmarking, or
+   reverse-engineering.
+6. **Disclosure.** If you become aware that anyone connected to you has done any
+   of the above, you must tell us promptly.
+7. **Cooperation.** If we contact you about activity that looks like a breach,
+   you must respond honestly and within a reasonable time. Silence, or answers
+   that later prove false, are themselves a breach.
+
+## 5. Codenamed (anonymous) entries
+
+1. You may run an unreleased model under a codename. It is anonymous **to
+   voters**, not to us: we must know the provider and the model.
+2. Anonymity is bounded by time or vote count, set when the entry is accepted,
+   and ends regardless of how the model performs. You may withdraw before then;
+   you may not reveal only because it won, or keep an entry codenamed
+   indefinitely.
+3. A model that is already publicly available runs under its real name.
+4. We keep your identity confidential until the reveal **as a courtesy, not a
+   guarantee**. If this agreement is breached we may disclose the provider as
+   part of the outcome. We may also disclose it if required by law.
+
+## 6. Data, audio, and publication
+
+1. **Generated audio.** Audio your endpoint produces for the arena may be
+   stored, played to voters, cached, and published, including as part of
+   research datasets and in illustrations of results. You grant TTS Arena a
+   perpetual, worldwide, royalty-free licence to do so, and you confirm you have
+   the rights needed to grant it.
+2. **Votes and sessions.** Vote records, session data, and anti-abuse signals
+   belong to the arena. We may publish aggregate results and anonymised data.
+   Providers do not receive raw voter data.
+3. **Correspondence.** Communications between you and the arena about a listing,
+   an integrity review, or a decision may be quoted or published, in whole or
+   in part, as part of our account of that matter.
+4. **Outcomes.** We may publish the outcome of any integrity review, including
+   the model name, the provider name, what the data showed, and what the
+   provider told us. By submitting, you consent to that publication.
+5. **Nothing is deleted.** Votes, sessions, and correspondence are retained so
+   that any decision can be checked afterwards.
+
+## 7. Using arena results
+
+1. You may cite your model's ranking, rating, or win rate, provided you state
+   the date and link to the leaderboard. Rankings move; a claim must be true
+   when it is made and must not be presented as permanent.
+2. You must not alter, crop, or restyle leaderboard screenshots in a way that
+   changes their meaning, omit the Preliminary or Suspended labels, or present
+   results of custom prompts, side-by-side listening, or your own testing as
+   arena results.
+3. You must not describe TTS Arena results as an official ranking by Hugging
+   Face or anyone else, or imply that TTS Arena endorses your model.
+4. You may use the TTS Arena name to refer to the arena factually. You may not
+   use it, or the arena's marks, in a way that suggests partnership or
+   endorsement.
+
+## 8. Labels, withdrawal, and removal
+
+1. **Preliminary** marks a model with fewer votes than we need to settle its
+   rating. It is ranked normally.
+2. **Retired** marks a model whose provider has stopped serving it. You may
+   retire a model at any time by telling us. It stays on the board with the
+   rating it earned.
+3. **Suspended** marks a model removed from evaluation for a breach of this
+   agreement. It stays on the leaderboard, at the bottom, unranked, with the
+   reason and date. The label has no expiry. A suspended model **cannot be
+   retracted, withdrawn, renamed, or re-submitted under another name**, and
+   retiring it does not remove the label.
+4. We may remove or retire a model for technical reasons (a failing endpoint, a
+   discontinued API) without that being a finding against the provider, and we
+   will say so.
+
+## 9. Consequences of breach
+
+If we find that this agreement has been breached:
+
+1. affected votes are excluded and the leaderboard is recomputed from the clean
+   set;
+2. the model is suspended as described in section 8;
+3. we may publish an account of what happened as described in section 6;
+4. we may decline future submissions from the same provider, or accept them on
+   conditions;
+5. we may inform other evaluation platforms of the outcome.
+
+Whether the breach was intended is not the test. Conduct that moves the board
+is a breach whether or not that was the purpose.
+
+Findings are made by the TTS Arena team on the evidence available to us. We
+will contact the provider before a decision where we reasonably can, and we
+will consider what the provider says. Decisions are final.
+
+## 10. Disclaimers
+
+1. The arena, its ratings, and its API are provided **"as is"**, without
+   warranty of any kind. Ratings are statistical estimates from crowd
+   preferences; they are not a measure of fitness for any purpose.
+2. We do not guarantee that a model will be listed, evaluated to any number of
+   votes, evaluated within any time, or kept on the board.
+3. We do not guarantee uptime, and we may change the arena's methodology,
+   thresholds, design, or rules at any time. Material changes to this agreement
+   will be posted here with a new effective date; keeping a model listed after
+   that is acceptance.
+
+## 11. Liability and indemnity
+
+1. To the fullest extent permitted by law, TTS Arena and its maintainers are
+   not liable to you for any indirect, incidental, consequential, or special
+   damages, or for lost profits, revenue, or business, arising from the arena,
+   a listing, a rating, a label, or a published outcome. Where liability cannot
+   be excluded, it is limited to US $100.
+2. You will indemnify TTS Arena and its maintainers against claims arising from
+   your endpoint, your audio, your use of arena results, or your breach of this
+   agreement.
+
+## 12. General
+
+1. **Governing law.** This agreement is governed by the laws of the State of
+   California, USA, without regard to conflict-of-law rules. Disputes will be
+   brought in the state or federal courts located in California, and you
+   consent to their jurisdiction. Before bringing any claim, you agree to raise
+   the matter with us in writing and allow thirty days for an informal
+   resolution.
+2. **Relationship.** Nothing here creates a partnership, agency, employment, or
+   joint venture. Listing a model is not an endorsement of the provider by the
+   arena, or of the arena by the provider.
+3. **Assignment.** You may not transfer this agreement without our written
+   consent. We may assign it to a successor maintainer of the project.
+4. **Severability.** If any part is unenforceable, the rest stands.
+5. **Entire agreement.** This page, the [integrity policy](/integrity), and the
+   [Provider API](/api) documentation are the whole agreement between you and
+   TTS Arena about a listing. Anything said in Discord, email, or on a call
+   does not change it unless we confirm the change in writing.
+6. **Contact.** The TTS Arena team can be reached on
+   [Discord](https://discord.gg/HB8fMR6GTr) or by
+   [email](mailto:me@mrfake.name).

apps/docs/content/docs/ranking.mdx

@@ -0,0 +1,65 @@
+---
+title: Ranking
+description: How votes become a leaderboard.
+---
+
+Each counting vote is one head-to-head result: model A beat model B on a
+controlled prompt from the Random pool. 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.
+
+## Other labels
+
+- **Retired** - the provider no longer serves the model, so it's out of rotation.
+  Its rating is preserved from past votes.
+- **Suspended** - the model was pulled for breaking the
+  [integrity policy](/integrity). It sits at the bottom of the board, unranked,
+  with the reason and date. Its votes and history are kept, the label doesn't
+  expire, and a suspended model can't be retracted or renamed.
+
+## 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 on first-use Random prompts count. Typed custom prompts,
+  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,50 @@
+---
+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)).
+
+Submitting a model means accepting the [Provider Agreement](/provider-agreement).
+The [integrity policy](/integrity) is the short version - read that first at a
+minimum.
+
+## 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.
+- **A model that's yours.** Built or fine-tuned by you, or one you hold the
+  rights to serve under your own name. We don't list wrappers, resellers, or
+  rebrands of another provider's model - if the audio is coming from someone
+  else's API, that provider is who belongs on the board.
+
+## Anonymous pre-release
+
+You can run under a codename before your model is public - a way to get honest,
+blind feedback ahead of launch. Three rules keep this fair:
+
+- **Anonymous to voters, not to us.** To run under a codename you tell the TTS
+  Arena team who you are. We keep that confidential until the reveal - unless
+  the [integrity policy](/integrity) is broken, in which case we may disclose
+  the provider as part of the outcome.
+- 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,60 @@
+---
+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. The identities are revealed. If the line came unchanged from **Random**, the
+   public ratings update.
+
+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**.
+- **Don't vote on a model you're connected to.** If you work for, contract for,
+  or are otherwise affiliated with a provider, don't vote in battles that
+  include their model. That applies to personal accounts too. Providers agree
+  to this in the [integrity policy](/integrity); it binds their people as well.
+- Only clean votes on first-use **Random** prompts move the public leaderboard.
+  Typed custom prompts are still useful for side-by-side listening, but they do
+  not affect ratings.
+
+## 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 **captcha** appears once per browser, and again if risk rises.
+- A background sweep looks for coordinated rings - accounts sharing an IP or
+  device that pile onto one model, whether they signed in together or merely
+  voted together - and retroactively excludes their votes.
+- The sweep also runs a **statistical test for recognition**. For every voter
+  and every model, it compares how often that voter picks the model against how
+  often everyone else does, counting only the battles the model actually
+  appeared in. Liking a model puts you a few points above the crowd. Picking it
+  almost every time it appears, when the crowd is split, is not a preference -
+  it means you can tell which one it is, and a blind test where you can't be
+  blind isn't a vote. The comparison excludes the voter's own votes from the
+  baseline, so nobody can define the norm they are measured against.
+
+Whenever votes are excluded, the leaderboard is recomputed from the clean set,
+so a rating never keeps the lift it was given.
+
+<Callout>
+  None of this affects honest voting - it's invisible unless your activity looks
+  automated or coordinated. What we collect to do it, and why, is on the
+  [privacy](/privacy) page.
+</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.4.3",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^7.0.2"
+  }
+}

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"]
+}