Release Checklist

Use this checklist when cutting a CLI release. Docs build stays separate from the binary, but reference tables should match the shipped CLI.

Full release mechanics (version PR, candidate artifacts, protected promotion, metadata recovery) live in RELEASING.md and PACKAGING.md.

Before the version PR

bun run ci

bun run changeset

bun run --cwd apps/docs generate
git add apps/docs/lib/generated-metadata.json

bun run --cwd apps/docs scripts/check-codegen-freshness.ts
bun run --cwd apps/docs test
bun run --cwd apps/docs build:app

After the version PR merges

Confirm staged release metadata (schema v2):

• .release/kunai-vX.Y.Z.json has status: "staged" and publishedAt: null
• Public docs latest remains the newest published release (for example 0.2.5 while 0.2.6 is staged under Upcoming, not history)

Promote with workflow_dispatch

1. Actions → Release → Run workflow with the exact version matching apps/cli/package.json and the provider_signoff_run_id for current default-route evidence.
2. Wait for the candidate job: CI, binaries, bun run release:pack → preserved kunai-npm.tgz + 8 binaries + SHA256SUMS.
3. Wait for the confirmation job (release:confirmation:check) to emit ready-for-confirmation evidence.
4. Approve the protected environment release-production.
5. publish downloads preserved artifacts (no rebuild), bun publish of the tarball, draft GitHub release, verify, then promote to public latest.
6. metadata runs set-release-status.ts … published and pushes the narrow .release JSON update.

If the metadata push fails under branch protection, recover manually with a contents-write PAT (see RELEASING.md) — do not re-publish npm solely to fix metadata.

Release artifacts

• CHANGELOG entry via changesets (version PR)
• Staged .release/kunai-v*.json / .md until promotion
• Nine GitHub assets after publish (8 binaries + SHA256SUMS)
• bun run release:notes:check when available

After release

• Verify /releases shows the new tag as published latest (staged-only versions stay under Upcoming)
• Optional local Lighthouse: bun run --cwd apps/docs lighthouse:docs

See Docs maintenance for the L0–L4 truth model.