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.

AI index

Troubleshooting

Common issues and fixes when installing or generating with ContractSpec.

Command not found

  • Reinstall the CLI and ensure it is in your PATH.
  • Confirm Node.js 20+ or Bun 1.0+ is installed.

Specs not discovered

  • Run contractspec list to see discovered specs.
  • Verify your spec path conventions in .contractsrc.json.

Build or validate fails

  • Run contractspec validate to surface schema errors.
  • Check that generated files were not manually edited.

Diagnostics

troubleshooting-diagnostics
contractspec --version
contractspec list
contractspec validate src/contracts/mySpec.ts

Still blocked?

  • Confirm compatibility requirements for runtime and framework.
  • Re-run builds on a clean branch to isolate changes.
  • Use a new spec and minimal adapter to validate setup.
Start hereCompatibilityNext: Installation
OSS docsstartStart with OSS. Adopt Studio when you want the operating layer.
Previous

Developer tools

Use the CLI, editors, and helper tooling that make the OSS workflow practical day to day.

Next

Contracts and specs

Understand the spec model that drives generated surfaces, validation, policy, and safe regeneration.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development