semver — pick the right version number

Semantic Versioning is MAJOR.MINOR.PATCH (e.g. 2.4.1). The number is a promise to whoever depends on you. Choose the bump from the single most impactful change since the last release — one breaking change makes the whole release MAJOR, no matter how many small fixes rode along.

The decision — run top to bottom, first match wins

MAJOR (x.0.0) — you broke backwards compatibility. Someone upgrading might have to change their code or config.
- Removed or renamed a public function, flag, field, endpoint, or env var.
- Changed a default, a return shape, or behavior callers relied on.
- Tightened validation so input that used to work now fails.
MINOR (x.y.0) — you added something, backwards-compatibly. Existing users upgrade with zero changes.
- New feature, function, flag, endpoint, or optional field.
- Marked something deprecated (it still works — actual removal is the future MAJOR).
PATCH (x.y.z) — backwards-compatible fix or no-surface change.
- Bug fix that keeps the intended contract.
- Performance, docs, internal refactor, dependency bump with no visible change.

When you bump a higher slot, reset the lower ones to 0: 1.4.2 → MAJOR 2.0.0 · MINOR 1.5.0 · PATCH 1.4.3.