> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# 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

```shell theme={null}
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`): MDX, `nav.json`, `errors.mdx`, and the spec yaml are pre-built upstream in the [`coinbase/cdp-api`](https://github.com/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/` 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.