This handbook runs on fumadocs-ui (^15.8.5) + fumadocs-mdx (^11.10.1) + fumadocs-core (^15.8.5). It's mounted under /droidspeak/docs/* of the main dashboard — same Next process, same auth chrome, same Tailwind tokens.

Where it lives in src/

The lazy/eager files shim

fumadocs-mdx 11.x returns { files: () => [...] } (lazy); fumadocs-core 15.x expects { files: [...] } (eager). docs-source.ts resolves the lazy form at module init so the catch-all route can iterate synchronously. Drop the shim when both packages agree on a shape.

Adding a page

1. Create content/docs/<section>/<page-slug>.mdx with frontmatter:

   ---
   title: Page Title
   description: One-sentence summary used in cards and search.
   ---

2. Add the slug to the section's meta.json pages array (order in the array drives sidebar order).

3. If you're creating a new section, add the section name to the root content/docs/meta.json pages array as well.

4. Cross-link with regular markdown links — [Galaxy Map](/droidspeak/docs/components/galaxy-map). The fumadocs router resolves both .mdx and slug-only forms.

MDX components

The handbook uses fumadocs-ui's built-in components:

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';

<Callout type="warn">Don't do X.</Callout>

<Cards>
  <Card title="Install" href="/droidspeak/docs/install/k8s">Production path</Card>
</Cards>

Callout, Card/Cards, code blocks, tables, and mermaid diagrams (```mermaid) are pre-wired. Anything else you import needs adding to mdx-components.tsx.

Mermaid

```mermaid
flowchart LR
  A --> B
```

Rendered client-side. Don't put more than one or two diagrams per page — the renderer is heavy.

Search

Fumadocs ships search out of the box (Cmd-K). The index is built at build time from every MDX page's frontmatter + body.

Conventions for this handbook

• No bd-/RS-N tracker codes in copy. Tracker codes belong in beads / feature docs, not user-facing surfaces. (Internal memory rule — applies to docs too.)
• No storage-vendor names in dashboard chrome. Inside the docs section itself, vendor names (TrailBase, ReductStore, Restreamer) are fine and expected — this is the technical reference. Outside the docs, refer to "snapshot history" / "stream archive" / "data store".
• No "subtitle that explains the rationale". Frontmatter description is one sentence, neutral. Rationale lives in the body under a Why heading.
• Pages are scannable. Tables and lists over walls of prose. The reader is usually looking for one fact.

See also

• Contributor guide
• Tech Stack — the rest of the dashboard's libraries