Skip to main content

​
AGENTS.md

This file provides guidance to coding agents (Claude Code, etc.) when working with code in this repository.

​
What this repo is

Mintlify-built documentation for Coinbase Developer Platform (CDP). Content lives in .mdx files; navigation, redirects, and global config live in docs.json (~300KB — search before editing). Production deploys automatically on merge to master.

​
Common commands

mint dev                              # local preview at http://localhost:3000
npx mint broken-links                 # validate links
npm run lint                          # prettier --check .
npm run format                        # prettier --write .
vale --config=.vale.ini --no-global --output=JSON ./   # prose lint (requires `brew install vale`)
npx playwright test                   # smoke + payment-API tests; auto-starts mint dev
npx playwright test tests/smoke.spec.ts   # single test file
npx playwright test --ui              # interactive runner
If mint dev errors on docs.json config, run mint update (or npm i -g mint@latest) — Mintlify ships breaking schema changes.

​
OpenAPI spec automation

Two pipelines, selected per-spec by config in scripts/openapi/openapi-specs.ts:
  1. Standard pipeline (e.g. exchange-api, prime-api): downloads YAML from url, runs autogenerate-openapi-mdx-files.ts to generate per-endpoint MDX into outputPath. Honors skipExistingFiles, tagRenames, tagOverrides, pathRenames from the spec config.
  2. Inject pipeline (cdp-api-v2, payment-apis): MDX, nav.json, errors.mdx, and the spec yaml are pre-built upstream in the coinbase/cdp-api repo and published to CloudFront (artifactsBaseUrl). fetch-openapi-spec.ts caches them to artifactsCacheDir; inject-cdp-api-artifacts.ts copies them into api-reference/v2/ or api-reference/payment-apis/ and rewrites the matching "REST API" page group in docs.json from nav.json (preserving manually-curated entries that appear before the first generated group).
Run npm run openapi:update -- <spec-id> — it picks the right pipeline. For local cdp-api builds, override the source with npm run openapi:inject-cdp-api-v2 -- --source <path> or OPENAPI_ZIP_PATH=<zip>. To add a new spec: append to openApiSpecs in scripts/openapi/openapi-specs.ts AND add the spec ID to the choices in .github/workflows/update-openapi-specs.yml.

​
SDK doc automation

scripts/sdks/run-all-sdk-updates.ts clones an SDK repo, runs its docsCommand, then process-typescript-sdk-docs.ts renames README.md → index.mdx, *.md → *.mdx, rewrites relative links, strips TypeDoc headers, and updates the sidebar at sidebarPath inside docs.json. Configure new SDKs in scripts/sdks/sdk-specs.ts. Triggered manually via update-sdk-docs.yml; update-openapi-specs.yml runs daily at 00:00 UTC.

​
Authoring conventions

From CONTRIBUTING.md (enforce when writing or reviewing docs):
  • Casing: Title Case for H1, Sentence case for all other headers.
  • UI elements: bold (**Save**).
  • Files: lowercase, hyphen-separated.
  • Voice: second person for instructions (“you”), first person plural for team actions (“we”). Avoid “simply”, “please”, exclamation marks.
  • Links: descriptive text, never “click here”. Relative paths (./foo.mdx) for in-project links; /project-name/docs/... for cross-project. End how-tos with a “What to read next” section.
  • Diátaxis types: explanation, tutorial/how-to, reference — match the doc’s purpose. Reference pages stay terse.
Vale runs on every PR. Add valid project-specific terms to vale-styles/config/vocabularies/Coinbase/accept.txt rather than rewording around them. lint-staged runs prettier --write --ignore-unknown on every changed file via the husky pre-commit hook. .prettierignore excludes all *.mdx, all yaml/json under api-reference/, and **/downloads/* — so prose changes won’t be reformatted, but TS scripts and docs.json will be.

​
Editing docs.json

docs.json drives navigation. When adding a new page MDX, you almost always also need to register it in the matching navigation group. For OpenAPI-generated REST API groups, do not hand-edit — the inject/generate scripts overwrite them on the next run; instead, change the upstream spec or the script config.

​
Testing UI changes

Playwright tests live in tests/ and auto-start npx mintlify dev (see playwright.config.ts). The webServer readiness probe hits /api-reference/v2/introduction (not /) because Mintlify answers / before compilation finishes — keep that probe URL on a real compiled page if you change it. Tests run sequentially with 1 worker; the Mintlify dev server can’t handle parallel load.

​
Production / monitoring

Merges to master deploy to https://docs.cdp.coinbase.com in ~1 minute. Datadog synthetic tests monitor production pages — update them at https://app.datadoghq.com/synthetics/details/67y-9hr-qvx if you rename or remove pages.