Release guide

Maintainer HQ treats the local release gate as authoritative. CI calls the same underlying scripts and adds parallelism, caching, summaries, and failure artifacts.

Before versioning

Add user-visible changes under a category in the Unreleased section of CHANGELOG.md. From a clean main checkout, install exact dependencies and the browser runtime, then run:

npm ci
npx playwright install chromium
npm run check:release

The gate validates source and syntax, enforces coverage thresholds, runs browser flows, audits dependencies, scans publication content, dry-runs the package manifest, creates the tarball and checksum, and installs that tarball under a clean temporary home for an onboarding probe. The dependency audit retries only recognized transient registry failures within a fixed attempt limit; vulnerability findings and unrecognized failures still stop immediately.

Cut a version

Use the guarded version command instead of editing version fields or tags manually:

npm run release:version -- patch

major, minor, patch, and an exact x.y.z version are accepted. The command refuses a non-main branch, a dirty tree, an existing tag, a non-advancing version, or empty release notes. It runs the full release gate before editing, synchronizes package.json, package-lock.json, src/constants.mjs, and CHANGELOG.md, reruns unit and integration tests against the new version, rechecks publication state, commits only the version files, and creates an annotated vX.Y.Z tag. It does not push.

Publish through GitHub

Push the release commit only when branch CI should run. Wait for all required jobs to pass, then push the annotated tag. Tag CI verifies the tag against the package, source constant, changelog, and checked-out commit; reruns the release gate; builds the tarball and SHA256SUMS; and creates the GitHub release from the exact changelog section.

The tag workflow is the normal deployment path. It provisions its own Chromium runtime before repeating the full release gate. If a remote release must be recovered manually, use the same npm run verify:release-tag, npm run check:release, npm run package, and npm run release:notes -- vX.Y.Z commands before invoking GitHub CLI. Never upload a workspace document, provider projection, environment file, browser trace containing private state, or ad hoc artifact outside dist/.

Verify a release

Download the tarball and checksum from the GitHub release, verify SHA-256, install into a temporary prefix, and run maintctl --version, maintctl init, and maintctl doctor. The automated clean-install probe performs the same product checks on every release candidate.