Authoring Guide

This guide is the human-readable companion to the agent instructions in .github/instructions/. Follow it for every page you add.

The one rule that matters most

Structure: app-first, audience-second

Every page lives under an app and an audience:

content/docs/<app>/<audience>/<page>.mdx

• Apps are top-level folders with meta.json containing "root": true. They render as the sidebar app switcher. Current apps: loan-portal, flexrate, marketing, ocr, plus the cross-cutting platform.
• Audiences are the second level — one of:
  • users/ — task how-tos for people using the app. Plain language, no assumed engineering knowledge.
  • product/ — how features behave: events, workflows, parity, roadmap.
  • engineering/ — architecture, runbooks, API references, deep dives.

Frontmatter

Every .mdx page starts with frontmatter:

---
title: Page Title
description: One sentence describing the page. Used in search and metadata.
icon: BookOpen        # optional — a lucide-react icon name
---

Navigation (meta.json)

Each folder may have a meta.json controlling its title, icon, and page order:

{
  "title": "Engineering",
  "icon": "Code",
  "pages": ["architecture", "tech-debt", "api"]
}

• App root folders add "root": true.
• Use "---Section---" strings inside pages to add labeled separators.
• List every page/folder you want ordered; omitted items are appended.

Components

Markdown (including GFM tables and task lists) works out of the box. For richer pages, import fumadocs components directly in MDX:

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

Use Cards on landing pages to link onward, and Callout for important notes.

Voice by audience

• Users: imperative, step-by-step, screenshot-first. Avoid jargon.
• Product: explain behavior and intent. Describe events/workflows in terms of cause and effect.
• Engineering: precise and reference-grade. Name real classes, commands, and files. Prefer durable explanations over status updates.

Adding a new app

1. Create content/docs/<app>/meta.json with "root": true, a title, and a description.
2. Add index.mdx (the app landing) with audience Cards.
3. Add users/, product/, and engineering/ subfolders, each with a meta.json and an index.mdx.
4. Register the app in the root content/docs/meta.json pages list.