Updating these docs

This site is the living engineering documentation. Treat it as code — same review process, same conventions.

Where pages live

apps/docs/
  content/docs/             ← MDX pages
  app/[[...slug]]/page.tsx  ← renderer
  lib/source.ts             ← Fumadocs loader
  meta.json                 ← sidebar order + group labels

Every .mdx file in content/docs/ becomes a page. The sidebar comes from meta.json — if your page isn't listed there, it won't appear in the sidebar.

Adding a page

1. Create content/docs/my-page.mdx:

   ---
   title: My page
   description: One-sentence summary used by search and meta tags
   ---
   
   Page body. Frontmatter title renders as the page heading — don't add an
   H1 inside the body.
   
   ## Section

2. Add the slug to meta.json in the position you want.

3. Run pnpm --filter @app/docs dev — the new page is available at /my-page.

Conventions

• No H1 in body. Frontmatter title renders as the page heading. Adding # at the top duplicates.
• One topic per page. If a page is over ~250 lines, consider splitting.
• Cross-link liberally. Use relative paths: [Architecture](./system-overview).
• Glossary first. Before introducing jargon, check Glossary. If missing, add it there and link from your page.
• Avoid timestamps. Don't write "as of November 2025." Pages drift; timestamps lie. Write the truth that's true forever, or anchor to git history.

Admonitions

Use Docusaurus-style directives for callouts:

:::tip
Helpful nudge.
:::

:::warn
Watch out — this can break things.
:::

:::note
Side note worth knowing.
:::

File-tree codeblocks

Render an ASCII tree as a collapsible file browser:

```files
src
├── lib/
│   └── helper.ts
└── index.ts
```

Mermaid diagrams

Use a mermaid codeblock:

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

Supported types: flowchart, sequenceDiagram, erDiagram, classDiagram, stateDiagram, gantt. Light/dark themes are automatic. Click a diagram to open a full-viewport modal with scroll-zoom + drag-pan. Full syntax reference: mermaid.js.org.

Search

Search comes from remarkStructure indexing. Headings + paragraph content are indexed. The Fumadocs search dialog hits /api/search.

LLM-ready export

Every page exports _markdown — the post-processed plain Markdown — via getText("processed"). Useful for ingestion into an AI tool or generating llms.txt.

Build + verify

pnpm --filter @app/docs build   # production build
pnpm lint                       # workspace ESLint

The pre-push hook + pnpm check cover these. CI runs the same.