> ## Documentation Index > Fetch the complete documentation index at: https://docs.deploybaseline.com/llms.txt > Use this file to discover all available pages before exploring further. # Docs and API reference > Where Baseline's documentation lives, what is generated from code, how vendored specs are pinned, and how to preview changes. ## 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`. | Location | Content | Edited by | | - | - | - | | `docs/*.mdx` | Guides, configuration, adapters, one page per provider (`docs/stripe.mdx`) | Hand | | `docs/contributing/*.mdx` | This section | Hand | | `docs/snippets/conformance/.mdx` | Conformance table for each provider page | `pnpm conformance` | | `docs/snippets/providers/.mdx` | "At a glance" block on each provider page, from its manifest | `pnpm api-reference` | | `packages/@deploybaseline//api-reference.json` | Per-provider OpenAPI document, served by the CLI at `/docs` | `pnpm api-reference` | > [!WARNING] > > 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: ```md theme={null} ## Emails - `POST /emails` — send single email - `GET /emails/:id` — get email ``` 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}`, ``), 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. > [!WARNING] > > 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 ```bash theme={null} make conformance # pnpm conformance ``` `scripts/conformance.mjs` writes `CONFORMANCE.md` and `docs/snippets/conformance/.mdx` from the coverage matrices, gate settings, vendored specs, the lockfile, and `conformance/verified.json`. Provider pages import their snippet: ```mdx theme={null} import Conformance from "/snippets/conformance/resend.mdx"; ``` 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 ```bash theme={null} make api-reference # node scripts/generate-api-reference.mjs ``` `scripts/generate-api-reference.mjs` builds `packages/@deploybaseline//api-reference.json` for every provider. The CLI build ships them all, and the console serves them at `/docs` (see [API reference](/api-reference.md)). 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/.mdx` (see [Provider route lists](#provider-route-lists)). **3. Response schemas from the vendored spec** When `packages/@deploybaseline//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/.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//spec/openapi.json`. ```bash theme={null} make vendor-spec P=stripe # node scripts/vendor-spec.mjs stripe node scripts/vendor-spec.mjs stripe --check # exit 1 when upstream differs node scripts/vendor-spec.mjs --list # providers with a spec source ``` * 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`: ```json theme={null} "x-baseline-source": { "url": "https://github.com/stripe/openapi/blob/e924802e.../openapi/spec3.json", "repository": "stripe/openapi", "commit": "e924802e...", "license": "MIT", "fetched": "2026-10-19" } ``` * 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/` PR listing the responses that no longer match. A `graphql-drift` job does the same for vendored GraphQL schemas on `schema-drift/` branches. To resolve a drift PR, fix the emulator, or rerun `node scripts/generate-spec-allow.mjs ` 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 ```bash theme={null} make docs # cd docs && npx mint dev --port 3333 make docs-check # npx mint validate && npx mint broken-links, inside docs/ ``` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.