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

Author release capsules

Pair each publishable changeset with a structured release capsule so changelog, upgrade, and docs surfaces all read from the same release source of truth.

What you'll build

  • A .changeset/<slug>.md file for package/version intent.
  • A .changeset/<slug>.release.yaml companion for audiences, migrations, validation, and evidence.
  • Generated release artifacts that the website changelog and upgrade flows can consume safely.

1) Create the paired changeset files

The Markdown file states the package bumps and reader-facing change intent. The YAML file carries the structured release metadata.

.changeset/contract-dx-first-slice.release.yaml
schemaVersion: "1"
slug: contract-dx-first-slice
summary: Improve app-config, theme, and feature authoring with explicit validation and shared setup alignment.
isBreaking: false
packages:
  - name: "@contractspec/lib.contracts-spec"
    releaseType: minor
validation:
  commands:
    - "cd packages/libs/contracts-spec && bun run test && bun run typecheck"
  evidence:
    - "Package-level validation entrypoints now back setup, docs, and CLI authoring flows."

Expected output: every publishable slug has both the human-facing changeset and the structured release capsule beside it.

2) Use the release authoring commands instead of raw drift-prone edits

release-authoring
contractspec release init --summary "Improve app-config, theme, and feature authoring"

# Or revise an existing capsule with the guided flow
contractspec release edit contract-dx-first-slice

Expected output: the CLI scaffolds or revises the paired files with the current release schema instead of leaving maintainers to hand-roll YAML structure.

3) Build the generated release artifacts before consuming them

release-build
contractspec release build

Expected output: `generated/releases/manifest.json`, `generated/releases/upgrade-manifest.json`, and the related customer/maintainer guidance files are refreshed from the release capsules.

4) Enforce completeness before publishing or building the changelog

release-check
contractspec release check --strict

Expected output: missing capsules, incomplete migration guidance, or stale generated release artifacts are flagged before the website changelog or publish workflow treats the release data as canonical.

5) Sync the public docs if workflow expectations changed

  • root `README.md` and generated root `AGENTS.md` inputs when contributor or operator workflow changes
  • the nearest package `README.md` and `AGENTS.md` for any touched public package surface
  • website docs and `/llms*` summaries when the release changes how users or contributors should work
Connect guide Website changelog
OSS docsoperateStart with OSS. Adopt Studio when you want the operating layer.
Previous

CI diff gating

Use deterministic checks to block drift and risky changes before they reach production.

Next

Security and trust

Understand the trust model, artifact validation expectations, and operational boundaries.

Why ContractSpec

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

ManifestoContract-first APISpec-driven development