Skip to main content

​
How the docs are organized

The site is Mintlify, configured by docs/docs.json. Every page is an .mdx file in docs/, and a page only appears in the sidebar once it is listed in a navigation group of docs.json.
Never edit generated files by hand. CI regenerates them and fails when the committed copy differs.

​
The four places a user-facing change goes

When a change affects how humans or agents use Baseline (new, changed, or removed commands, flags, behavior, routes, seed config, or SDK integration), update all four in the same pull request:

README.md

The repository front page, including the provider list.

skills/*/SKILL.md

The agent skill for each affected service.

docs/

The Mintlify page, plus its navigation entry in docs/docs.json.

CLI --help

The help text in packages/cli/src/index.ts.
User-facing examples use npx @deploybaseline/cli, never npx baseline.

​
Provider route lists

The API reference generator reads every `METHOD /path` written in a provider page. A bullet line in this form also gives the operation its title and description:
The title is the text before the first colon, comma, semicolon, or parenthesis. Keep it short: text longer than 48 characters, quoting code, or describing parameters (“With email and…”) gives no title, and the operation is named from its path instead. The rest of the line becomes the description. The nearest ## or ### heading above a mention becomes the operation’s tag (its group in the sidebar), unless the heading is generic, such as “Routes” or “Endpoints”. Any parameter spelling works (:id, {id}, <id>), and paths may be written relative to the API’s base (/tickets/:id under /api/v2). A relative path gives a title only when it lines up with the route (a parameter for a parameter), and one made only of parameters (/:bucket) never does, since it fits under any prefix. A registered route that the page never mentions still appears in the reference, with a title derived from its path.
A mention that matches no registered route fails pnpm api-reference --check, so a misspelled, removed, or never-built route cannot stay in the docs. Write each route out in full: `GET` and `DELETE /x` reads as DELETE /x. When a route is genuinely served by middleware rather than a registered route, add it to SERVED_BY_MIDDLEWARE in the script with the reason.

​
Generated content

​
Conformance

scripts/conformance.mjs writes CONFORMANCE.md and docs/snippets/conformance/<provider>.mdx from the coverage matrices, gate settings, vendored specs, the lockfile, and conformance/verified.json. Provider pages import their snippet:
CI runs pnpm conformance, then fails when git diff --exit-code reports any change to CONFORMANCE.md or docs/snippets/conformance. Regenerate after any change to a matrix, gate, vendored spec, or tested SDK version.

​
API reference

scripts/generate-api-reference.mjs builds packages/@deploybaseline/<provider>/api-reference.json for every provider. The CLI build ships them all, and the console serves them at /docs (see API reference). It is grounded in what the code actually serves, not in what the docs claim:
1

Routes from the plugin

The operations are the routes the plugin registers, read with pluginRoutes from @deploybaseline/testing. A route that is not registered never appears.
2

Titles and tags from the provider page

Titles and tags are parsed from the route lines in docs/<provider>.mdx (see Provider route lists).
3

Response schemas from the vendored spec

When packages/@deploybaseline/<provider>/spec/openapi.json exists, matching operations get its response schemas.
4

Status from the coverage matrix

Each operation carries x-baseline-status (supported, partial, or not_started) from src/__tests__/coverage.ts.
Every operation also carries x-baseline-route (the pattern exactly as registered) and, when the vendored spec has it, x-vendor-operation. Route patterns become OpenAPI paths: :id becomes {id}, a regex parameter keeps its pattern, and Microsoft’s alternatives (:mailbox{me|users/[^/]+}) show their first alternative. A trailing /* route under which concrete routes exist is a fallback (it answers unknown paths with the vendor’s not-found error); fallbacks are listed under x-baseline.fallbacks rather than as operations. Only the vendor schemas some operation reaches are kept. It also writes docs/snippets/providers/<provider>.mdx, the “At a glance” block on each provider page (package, port, config key, operation count, and start commands). The site has no per-provider reference pages: the endpoint reference lives in the CLI. The script reads built providers, so run make build first. Output depends only on repository content, never on the time of the run. CI runs pnpm api-reference --check, which fails when any generated file is stale or a provider page mentions a route that is not registered. Regenerate whenever you add or remove a route, change a provider page, refresh a vendored spec, or change a matrix status. pnpm api-reference stripe regenerates one provider while you work.

​
Vendored specs

Where a vendor publishes an OpenAPI document under a license we can use, a trimmed copy lives at packages/@deploybaseline/<provider>/spec/openapi.json.
  • Sources are declared in SOURCES at the top of scripts/vendor-spec.mjs with their repository, branch, file, and license. The header also records why some providers are not vendored (no license, or no usable spec).
  • The copy is pinned to an upstream commit and keeps only the operations the emulator registers, with their JSON response schemas and the component schemas they reach. Run pnpm build first: routes come from the provider’s dist.
  • Each file carries its provenance in x-baseline-source:
  • The fetch date only changes when the trimmed shapes change, so rerunning is a no-op.
  • A new source needs a license check and a THIRD_PARTY_NOTICES.md entry before it lands.
GraphQL schemas work the same way through scripts/vendor-graphql-schema.mjs, which writes src/graphql/schema.generated.ts for GitHub, Linear, and Shopify.

​
Weekly drift checks

The Spec drift workflow (.github/workflows/spec-drift.yml) runs every Monday and on demand. For each provider in vendor-spec.mjs --list it refreshes the spec, and when the shapes changed it runs the provider’s tests against the new spec and opens or updates a spec-drift/<provider> PR listing the responses that no longer match. A graphql-drift job does the same for vendored GraphQL schemas on schema-drift/<provider> branches. To resolve a drift PR, fix the emulator, or rerun node scripts/generate-spec-allow.mjs <provider> and give each new allow entry a reason. PRs opened with the workflow token do not trigger CI; close and reopen the PR to run it.

​
Previewing

Open http://localhost:3333. Run Mintlify on an LTS Node release. Links between pages use absolute paths without the extension (/configuration, /contributing/architecture), and mint broken-links catches any that do not resolve.