Release flow

How the @capxul/* packages ship — Changesets in pre-release mode on the alpha tag, the Release workflow, and version pinning for consumers.

Packages ship from the monorepo with Changesets. The trunk branch is master, and the full runbook is canon/release-flow.md; this page is the contributor summary.

Pre-release mode on the alpha tag

The repo is in Changesets pre-release mode (.changeset/pre.json: "mode": "pre", "tag": "alpha"). Every publish lands a prerelease version on the alpha npm dist-tag — latest only moves when a stable release ships intentionally. @capxul/sdk, @capxul/sdk-react, @capxul/sdk-testing, and @capxul/mcp are a fixed group in .changeset/config.json: they version in lock-step, so their published versions always match.

The publishable set

Package	Role
`@capxul/sdk`	Core SDK
`@capxul/sdk-react`	React hooks surface
`@capxul/sdk-testing`	Testing utilities for SDK adapters and proof harnesses
`@capxul/mcp`	Runnable `capxul-mcp` MCP server CLI (`apps/mcp`)
`@capxul/sandbox`	Runnable sandbox operator CLI (`apps/sandbox`)

All other workspace packages (backend, wire, types, errors, config, observability, contracts, and the non-published apps) are "private": true and never publish — .changeset/config.json sets privatePackages.tag: false. @capxul/mcp and @capxul/sandbox are published apps: they ship a runnable CLI (a single bundled main.mjs with a bin entry) rather than a library, and every internal @capxul/* package they reach is inlined into the bundle.

Day-to-day: add a changeset

When a PR changes a publishable package's consumer-facing behavior, add a changeset before merge — CI enforces this via the changeset:required check:

vp run changeset

Pick the affected packages, the semver bump, and write a short summary. Do not bump package.json versions in feature PRs — only the changeset file lands.

The Release workflow

.github/workflows/release.yml runs on every push to master:

Version PR — when pending changesets exist, changesets/action opens a PR titled chore(release): version packages that bumps versions, updates CHANGELOG.md files, and consumes the changeset files. Review it like any other PR: versions, changelog wording, which packages ship.
Publish on merge — merging the version PR triggers the same workflow to publish to npm (auth via a granular NPM_TOKEN under the protected npm environment), create @capxul/<pkg>@x.y.z git tags, and open GitHub Releases. A final step re-aligns the alpha dist-tag on the published versions.

If the workflow is blocked, there is a break-glass local path (vp run release:local) — see the manual release runbook.

Pin exact versions

Consumers install from the alpha dist-tag and should pin exact versions:

npm i @capxul/sdk@alpha @capxul/sdk-react@alpha

The alpha train can change surface between prereleases, so treat every bump as deliberate: pin the exact 1.0.0-alpha.x version in package.json (no ^/~ range), upgrade @capxul/sdk and @capxul/sdk-react together (they version in lock-step), and check Capability status for what is live in the version you are pinning. npm versions are immutable — a bad publish is fixed by a new version, never a republish.