OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Build
Adoption guides for teams that want to keep their code.
These guides assume you are introducing ContractSpec into a real code base. Start with a narrow surface, verify the generated outputs, and expand only after the contract loop feels trustworthy.
Adopt one endpoint in Next.js
Start inside a live app with one operation, one generated surface, and one clearly bounded change.
Import an existing codebase
Stabilize what already exists instead of treating adoption as a rewrite project.
Validation and typing
Keep runtime validation and TypeScript behavior aligned from the same source definitions.
Generate docs and clients
Publish stable docs, schemas, and client-facing artifacts from the contract layer.
Docs pipeline
Feed generated reference material into the docs site without confusing ownership.
CI diff gating
Use deterministic checks to catch drift and risky changes before they ship.
- Run each guide in a branch or sandboxed workspace.
- Prefer one bounded surface at a time: one endpoint, one workflow, one integration, one unsafe module.
- Use the example and reference outputs to verify what changed, not just the narrative page.
# list example systems
contractspec examples list
# validate the examples in this workspace
contractspec examples validate --repo-root .Contract types
Choose the right contract surface for the behavior you want to make explicit.
Adopt one endpoint in Next.js
Start with one endpoint, one contract, and one generated surface in an existing Next.js app.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.