Release and Distribution

Purpose #

Explain how aidokit ships: registry, scopes, dist-tags, Changesets, provenance, and the pre-1.0 versus post-1.0 promises.

Big Picture #

Authoritative: ADR-0004 and .docs/ARCHITECTURE.md §17.

Registry: public npm only (registry.npmjs.org). No alternate registry, no GitHub Packages.
Packages: scoped @aidokit/* for libraries; unscoped aidokit for the CLI binary.
Pre-1.0 dist-tag: alpha (and optionally beta at v0.5). latest is unset until v1.0.
v1.0 dist-tag: latest. alpha continues for in-progress major work.
Versioning: Changesets, independent semver per package.
Provenance: required for every @aidokit/* package from v1.0; pre-1.0 best-effort.
Distribution: npx aidokit init is the only supported entry point through v1.0.

How It Works #

Version coordination via Changesets #

Every PR that changes published behaviour MUST include a .changeset/*.md file:

pnpm changeset

Pre-1.0 policy (from ADR-0004 §4):

Patch — internal refactor, doc fixes, bugs that don't change API or emitted output.
Minor — new features and breaking changes (pre-1.0 only).
Major — reserved; pre-v1.0 we don't version-major. v1.0.0 is the first major.

Post-1.0:

Strict semver. Breaking changes require major bumps and ship with aidokit migrate scripts.

What is published #

Per package.json's files allowlist:

{ "files": ["dist/**", "README.md", "LICENSE", "NOTICE", "CHANGELOG.md"] }

Source files, tests, configs, and the agent-artifacts/ tree are not published.

Each package carries LICENSE + NOTICE per ADR-0003.

Provenance #

From v1.0 GA:

npm publish --provenance --access public

Requires GitHub Actions OIDC (or equivalent). Users verify with:

npm audit signatures

aidokit doctor (v1.0+) MAY check provenance on installed adapter packages and warn on missing or invalid signatures.

Pre-1.0 `latest` behaviour #

npx aidokit init resolves aidokit@latest. Pre-1.0, latest is unset for the aidokit package, so npx aidokit init errors with a message pointing users to npx aidokit@alpha init. The README mirrors this guidance.

What stays out #

No container distribution. aidokit is a scaffolder, not a service.
No single-binary builds. Deferred to post-v1.0; tracked in .docs/ARCHITECTURE.md §21.
No Homebrew / snap / flatpak / scoop formulae. npx only.

Release principles #

From .docs/ROADMAP.md §Release principles:

Ship narrow, ship working — each release covers less than the previous plan suggested, but ships at production quality.
Dogfood as soon as possible — aidokit init re-bootstraps this repo from v0.1 onward.
Stability before breadth — lock contracts and CLI before adding more adapters/packs.
Honest about pre-1.0 — breaking changes allowed between minor versions.
No telemetry, no API calls, no surprises.
Migrations are first-class — every breaking change ships with aidokit migrate.

Example: a typical release flow #

# Contributor — every PR that affects published behaviour
pnpm changeset
git add .changeset/ && git commit -m "chore: changeset for ..."
# PR merged

# Maintainer / CI — at release time
pnpm changeset version      # consumes .changeset/*.md, updates package.json + CHANGELOG
pnpm install --frozen-lockfile=false
pnpm build
pnpm test
pnpm changeset publish --tag alpha     # pre-1.0
# OR
pnpm changeset publish                 # v1.0+ → 'latest'

The full CI publish workflow is sketched at ADR-0004 §Implementation notes.

Diagram #

See diagrams/release-flow.md.

Common Mistakes #

Forgetting a changeset. PRs that change published behaviour need one. CI enforces this once the changeset CI lint lands.
Bumping major pre-v1.0. The first major is 1.0.0. Pre-1.0 breaking changes go on minor.
Publishing without provenance from v1.0. That's a security requirement, not a nice-to-have.
Adding files to a published package outside the files allowlist. Source files and tests must not ship.

Checklist before tagging a release #

[ ] All pending .changeset/*.md files reviewed and merged.
[ ] pnpm test and pnpm test:conformance green across all packages.
[ ] Dogfood byte-compare clean (post-Phase 8).
[ ] CHANGELOG.md per package up to date (Changesets handles this).
[ ] License + NOTICE present in every published package.
[ ] engines.node: ">=20.0.0" in every package.json.
[ ] Provenance attested (v1.0+).
[ ] Maintainer ran npm audit signatures against the just-published tag.