Sorbet docs

Internal technical documentation for Sorbet. Pages are written from the code in sorbet-api, sorbet-app, and sorbet-dashboard. sorbet-deploy is covered only under operations.

Verify every edit against source. Do not copy stale markdown from those repos.

There is no site build. Read the files in this tree, or browse them on GitHub.

How to navigate

Section	What it covers
architecture/	System diagram, request lifecycle, environments
api/	NestJS API: auth, domains, data model, integrations
web/	Consumer web app (apps/web)
mobile/	Expo iOS/Android app (apps/mobile)
shared-packages/	@sorbet/core, @sorbet/api, @sorbet/types
dashboard/	Internal admin dashboard
operations/	Local setup, CI, deploy, secrets

Start with architecture/overview.md if you are new.

How pages are maintained

• AGENTS.md is the writing contract (voice, frontmatter, what not to dump).

• docs-map.yaml maps source-repo path globs to the pages that describe them.

• Each page has YAML frontmatter: title, repos, sources, last_verified.

The sync job

.github/workflows/docs-sync.yml runs nightly and pulls from the source repos; nothing is pushed from them. Each run:

1. Clones sorbet-api, sorbet-app, and sorbet-dashboard at current main.

2. Diffs each one from the SHA recorded in .docs-sync-state.json, dropping paths that cannot change documented behaviour (tests, stories, lockfiles, markdown, assets).

3. Runs Cursor CLI against .github/docs-sync-prompt.md, restricted by .cursor/cli.json to editing pages only — no git, no gh, no writes to the checkouts.

4. If pages changed, commits to the rolling docs/auto branch and opens or updates one pull request. If nothing changed, the run ends without a PR.

State advances only when a docs change actually lands, so a failed or skipped night is picked up by the next run rather than silently dropped.

A baseline in .docs-sync-state.json asserts "the pages were verified against this commit". The job will not invent one: if a repo is missing a baseline, or its recorded SHA has been rewritten away, that repo is reported and skipped rather than auto-seeded. Adding a repo to the sync therefore means writing its current SHA into that file yourself, once you have checked the relevant pages against it.

Review these PRs like any other change: check the cited source files. The agent can be wrong, and a page that reads plausibly can still be inaccurate.

Run it by hand from the Actions tab. workflow_dispatch takes a repo subset, a model slug, and a dry_run flag that runs the agent without opening a PR.

Editing

1. Read AGENTS.md.

2. Change the page and bump last_verified.

3. If you add a page, add a row to docs-map.yaml and a link from the nearest overview.