Smart Agent Teams

Writing docs

How this documentation site is built, how to run it, the MDX components and style rules, and which pages are generated from code.

This site lives in apps/docs. It is a Next.js app using Fumadocs, built as a static export. Most pages are MDX written by hand; the API reference and the CLI reference are generated from the code, so they cannot drift. Docs change in the same pull request as the feature they describe.

Layout

meta.json
index.mdx
STYLE.md
next.config.mjs
PathWhat it is
content/docs/**/*.mdxThe pages. The URL is the file path: content/docs/operations/database.mdx is /docs/operations/database.
content/docs/**/meta.jsonSidebar title and page order for each folder. Add a new page's slug to its folder's pages array. The root meta.json orders the sections.
app/Next.js routes: the docs pages, search, Open Graph images, llms.txt and llms-full.txt.
components/MDX component mapping (mdx.tsx), the Mermaid renderer, the API page, search.
lib/source.ts, lib/openapi.tsThe content source: MDX pages plus one generated page per API operation.
public/screenshots/Product screenshots for pages.
scripts/check-links.tsChecks every internal link in the built site.
STYLE.mdThe style guide. Read it before writing.

Run it

bun install                 # repo root
bun run dev:docs            # next dev on http://localhost:4300

The dev server reloads MDX on save. To build the static site and check links as CI does:

bun run build:docs                       # next build → apps/docs/out
bun run --cwd apps/docs check-links      # needs apps/docs/out
bun run --cwd apps/docs typecheck

Style rules

The full guide is STYLE.md. The rules that matter most:

  1. True to the code. Read the source before you write. If something is not implemented, say "not implemented yet". Never describe intent as fact.
  2. Plain, precise English. Short sentences, active voice, second person. No marketing words, no emojis, no exclamation marks.
  3. Concrete examples from the demo company: NoteFlow, prefix NF, with Ada (CEO), Linus (CTO), Grace (senior engineer), Ken (engineer), Maya (CMO), Margaret (QA lead) and Toni (content writer).
  4. Three surfaces. Where a feature exists in the web app, the CLI and the API, show all three in <Tabs items={['Web app', 'CLI', 'API']}>.
  5. Money is integer cents; a budget of 0 means no limit.
  6. Statuses use the exact API values in backticks: in_review, pending_approval.
  7. Links are absolute site paths without an extension: /docs/features/runs. Generated API operations live at /docs/api-reference/endpoints/<tag-folder>/<operation-id>, with underscores in the operation id replaced by dashes, for example /docs/api-reference/endpoints/runs/claim-run. Check libs/api-client/openapi.json for the exact operation id.
  8. No secrets. The demo login may appear only on local-development pages.
  9. Front matter on every page: a short sentence-case title and a one-sentence description that ends with a period.
  10. Headings start at ## and use sentence case.
  11. Code blocks are runnable and labelled with a language; use title="..." for file names.

Feature pages follow the template in STYLE.md: summary, how it works, fields, statuses, use it, permissions, events, limits and known gaps, related. Guides use <Steps>; references use tables. Split a page when it passes about 400 lines.

Components

These are available in every page without an import.

ComponentUse it for
<Callout type="info" title="...">Notes. Types: info, warn, error, success, idea.
<Cards> with <Card title href description />The "Related" section and navigation grids.
<Tabs items={[...]}> with <Tab value="...">Web app, CLI and API variants of the same task.
<Steps> with <Step>Ordered procedures. Start each step with a ### heading.
<Accordions> with <Accordion title="...">FAQ and troubleshooting entries.
<TypeTable type={{ field: { type, description, required, default } }} />Object fields, from company/schemas.py.
<Mermaid chart={...} />Diagrams: flowcharts, sequence, state and ER diagrams. Pass the diagram as a template literal.
<Files>, <Folder name>, <File name>File trees.
Example
<Callout type="warn" title="The company budget is not enforced">
Only agent budgets pause work.
</Callout>

<Mermaid chart={`
stateDiagram-v2
  [*] --> queued
  queued --> running: claimed
  running --> succeeded
  running --> failed
`} />

MDX treats < and { in prose as JSX. Put placeholders such as <sha> or {company_id} in backticks or code blocks. Inside a <Mermaid> template literal, avoid backticks and ${.

Screenshots: ![The inbox with two pending approvals](/screenshots/inbox.png). Write alt text that describes what the screen shows.

Generated pages

API reference

The pages under API reference are generated at build time from libs/api-client/openapi.json, the same schema the web app and CLI are typed against. Never write endpoint pages by hand.

  • Content comes from FastAPI. The summary and description are the endpoint function's docstring; fields and constraints come from the Pydantic models in company/schemas.py and api/schemas.py. To improve an endpoint page, edit the docstring or model, then regenerate the client:

    bun run --cwd libs/api-client generate

  • Only the supported API is published. lib/openapi.ts keeps /health and paths under /api/login, /api/register, /api/refresh, /api/logout, /api/me (including /api/me/api-keys), /api/password and /api/companies. Legacy routes are left out.

  • Tags are reassigned by path into folders: authentication, api-keys, companies, agents, tasks, goals, projects, runs, approvals, routines, insights, live-events, health.

CLI reference

Command reference is generated from the commander definitions in apps/cli/src by apps/cli/scripts/docs.ts:

bun run --cwd apps/cli docs          # rewrites content/docs/cli/reference.mdx
bun run --cwd apps/cli docs:check    # exits 1 if the committed page is out of date

Change a command's description or options in the CLI source, never in reference.mdx.

What CI checks

The web CI job builds the docs as part of bunx turbo run typecheck test build, then runs:

CheckFails when
bun run --cwd apps/docs check-linksAny internal link in the built site points at a missing page, or at a #fragment the target page does not have
bun run --cwd apps/cli docs:checkcli/reference.mdx does not match the CLI's commands
bun run lintBiome finds problems in apps/docs source (generated output is excluded)

A link to a page that does not exist yet fails CI. Add the page, or link to an existing one.

Docs in the same pull request

When a change affects behaviour that a page describes, update the page in the same pull request:

  • New or changed endpoint: docstring, regenerated client, and the feature page if behaviour changed.
  • New or changed CLI command: regenerated CLI reference, and the CLI or runner page.
  • New environment variable: Configuration.
  • New limit or status: Limits or Statuses.
  • New migration: Database.
  • Fixed a problem someone could hit again: an entry in Troubleshooting.

Publishing the site is a separate, manual step today.

Development setup

Install the toolchain.

Codebase tour

Where the code you are documenting lives.

API reference

The generated endpoint pages.

Command reference

The generated CLI page.

Testing

Every SAT test suite, how to run it locally, what CI runs on each pull request, and where to add tests for a change.

Glossary

Every SAT term in one alphabetical list, with a short definition and a link to the page that explains it.

On this page

LayoutRun itStyle rulesComponentsGenerated pagesAPI referenceCLI referenceWhat CI checksDocs in the same pull requestRelated