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.
Target time: 25 min
Import an existing codebase
Stabilize what already exists instead of treating adoption as a rewrite project.
Target time: 20 min
Validation and typing
Keep runtime validation and TypeScript behavior aligned from the same source definitions.
Target time: 20 min
Build a contract-driven form
Use FormSpec to keep data shape, fields, layout, policy, and submit behavior aligned.
Target time: 25 min
Flexible import templates
Accept partner CSV, JSON, and XML files with alternate headers and localized values while preserving a canonical import contract.
Target time: 25 min
Generate docs and clients
Publish stable docs, schemas, and client-facing artifacts from the contract layer.
Target time: 20 min
Docs pipeline
Feed generated reference material into the docs site without confusing ownership.
Target time: 20 min
Build a first module bundle
Define one bundle spec, resolve a surface plan, and render it through the React host layer.
Target time: 20 min
Host the Builder workbench
Wire a Builder workspace snapshot, common commands, runtime modes, and mobile review links into the reusable host.
Target time: 20 min
Handle Builder specs packs
Analyze a zip or folder, derive the task ledger, and keep apply blocked until Connect, tests, replay, and verifier evidence exist.
Target time: 25 min
Use Connect in a repo
Enable Connect, verify agent actions locally, and inspect the resulting review and replay artifacts.
Target time: 15 min
Adopt provider-backed knowledge
Sync Gmail and Google Drive into governed knowledge spaces with provider checkpoints, tombstones, and mutation gates.
Target time: 30 min
Author release capsules
Pair changesets with structured release capsules and generate the artifacts that changelog and upgrade flows consume.
Target time: 15 min
CI diff gating
Use deterministic checks to catch drift and risky changes before they ship.
Target time: 15 min
Working style
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.