Contributing overview

This section is for engineers working on the Baseline repository itself: the CLI, the shared runtime, and the provider emulators. If you only want to run emulators in your own project, start at Getting Started instead. CONTRIBUTING.md and AGENTS.md at the repository root are the source of truth. These pages expand on them with the commands and file paths you need day to day.

Repository layout

Baseline is a pnpm workspace driven by Turborepo. Workspace packages are declared in pnpm-workspace.yaml as packages/* and packages/@deploybaseline/*.

Path	What lives there
`packages/cli`	`@deploybaseline/cli`, the `baseline` binary and the programmatic API (`createEmulator`, `defineEmulator`, `defineConfig`). `src/registry.ts` lists every built-in provider and its port slot; `src/catalog.generated.json` holds their package data.
`packages/@deploybaseline/core`	The shared runtime: the HTTP layer (`http.ts`, built on Hono’s API), `Store`, `WebhookDispatcher` and signing helpers, auth middleware, saved state, `composeService`, and the UI design system in `ui.ts`.
`packages/@deploybaseline/testing`	Test harness for providers: `startService` and `restartService`, the webhook sink, coverage and spec gates, and dual mode helpers.
`packages/@deploybaseline/graphql`	GraphQL endpoint kit (`graphqlEndpoint`, `buildSchema`) used by Linear, Shopify, and GitHub’s GraphQL fields.
`packages/@deploybaseline/ws`	WebSocket kit (handshake, connection registry, heartbeat, resume buffer) used by Slack Socket Mode and the Discord gateway.
`packages/@deploybaseline/state-sqlite`, `state-libsql`	Optional backends for `--state sqlite:<path>` and `--state libsql://<host>`.
`packages/@deploybaseline/<provider>`	One package per emulated vendor (`stripe`, `github`, `resend`, and so on).
`skills/`	Agent skills, one `SKILL.md` per provider plus `baseline` and `custom-apis`.
`docs/`	This Mintlify site. `docs/snippets/` holds generated fragments.
`scripts/`	Repo tooling: provider scaffolding, coverage and spec generators, conformance, vendoring, release helpers.
`conformance/verified.json`	Dates of the last passing dual mode run per provider, written by CI.
`tests/contracts/`	Shared behavior contracts (`persistence.js`, `custom-api.js`) that the CLI runtimes run.

House rules

Tooling

Use pnpm for every development command. End-user instructions use npx @deploybaseline/cli or npm install, never npx baseline (that unscoped name belongs to an unrelated package).

Writing style

No emojis anywhere in the repository. Never use a double hyphen as a dash in prose, comments, or output; use an em dash or, better, rephrase. CLI flags such as --port are the only exception.

Pull requests

One concern per pull request. Mechanical changes (renames, moves) never share a pull request with behavior changes.

Documentation

A change that affects how people use Baseline updates four places: README.md, skills/*/SKILL.md, docs/ (page and navigation), and the CLI --help output in packages/cli/src/index.ts.

Emulator UI

Inspector pages, OAuth screens, checkout pages, and inboxes use the shared render functions in packages/@deploybaseline/core/src/ui.ts. No standalone HTML templates or custom style tags in provider packages.

Reference projects and licenses

Other emulators (Stunt, Fauxcord, PaperTiger, Mimic, Klavis) are references for behavior only. Never copy or port their code. Do not read Fauxcord source or any Elastic License (ELv2) file in Mimic. Vendored specs and schemas need a license check and a THIRD_PARTY_NOTICES.md entry before they land.

Dependencies

Check the latest npm version when adding a dependency (pnpm add <package> without a version, or npm view <package> version). Source for dependencies can be fetched into opensrc/ with npx opensrc <package>.

Where to go next

Local development

Toolchain, first-time setup, the daily loop, and troubleshooting.

Architecture

How a request travels from the CLI registry to a provider route.

Adding a provider

Scaffolding and the provider definition of done.

Testing and conformance

SDK tests, coverage gates, spec gates, dual mode, and what CI enforces.

Docs and API reference

Where docs live and which parts are generated.

Releasing

How a version bump becomes an npm release.

​Repository layout

​House rules

​Where to go next