# Versions & releases

**A release identity is the version number that describes one surface, and hlix keeps six of them separate.** A web or backend release must not accidentally publish an npm package, and a package release must not promote production.

For the current version of each package, see [Current versions](/releases/availability/). This page is the scheme behind those numbers.

## Version identities

| Surface | Scheme | Example shape | Meaning |
| --- | --- | --- | --- |
| Platform | date-based CalVer | `platform-vYYYY.MM.DD` | one reviewed production cut |
| CLI | semantic versioning | `cli-v1.2.3` | public command/output package |
| TypeScript SDK | semantic versioning | `sdk-v1.2.3` | public library package |
| MCP server | semantic versioning | `mcp-v1.2.3` | public stdio tool server and Registry entry |
| API contract | semantic versioning | `1.0.0` | compatibility of published request/response shapes |
| API URL | major prefix | `/v1/api` | coexistence boundary for breaking API generations |

These numbers move independently. An internal platform deployment may not change the API or packages. An SDK patch may improve packaging without changing the API contract.

## Package changes

User-visible CLI, SDK, and MCP changes carry a Changeset:

- patch: backwards-compatible fix or polish;
- minor: new command, method, or optional capability;
- major: breaking flag, JSON contract, signature, or behavior.

The package changelog is generated from reviewed Changeset summaries. The tag must match the package name and exact manifest version.

## Publication gates

A package is not called available merely because source code or a workflow exists. The release path verifies:

1. a real non-private package version and license;
2. typecheck, build, and package tests;
3. exact tarball contents, including README and license;
4. CLI execution from the built artifact;
5. npm trusted publishing with short-lived OIDC identity;
6. registry version lookup;
7. clean-project installation and runtime smoke test;
8. a matching GitHub release and checksums;
9. for MCP, an exact active MCP Registry record naming the same npm package and version;
10. a reconciled release ledger before the docs or application advertise the package.

The MCP path is recoverable across partial releases. If npm already contains the exact packed artifact, a rerun verifies its integrity and continues with Registry, GitHub release, and ledger reconciliation. It refuses an existing npm version whose integrity differs, an inconsistent Registry record, or a release asset with different bytes.

The npm access token is not part of this flow.
**Availability is evidence-based:** Publication is evidence-based: a version reaches the release ledger — and therefore these docs — only after it is live in the registry and installs cleanly into a fresh project.

The platform repository is private. npm trusted publishing still provides short-lived OIDC authentication, but npm does not issue public provenance attestations for packages published from private repositories. Hlix does not claim an attestation until package source is released from a public mirror.

## Homebrew

Homebrew is a distribution layer over a verified CLI artifact, not a second build with unrelated contents. A formula should pin a released archive and SHA-256, then pass `hlix --version` and `hlix --help` in a clean environment.

The tap is announced only after its repository, formula, checksum, and install test exist. See [Install the CLI](/getting-started/install/) for current availability.

## Platform releases

Platform release notes use the `platform-v…` namespace. Publishing a reviewed platform release promotes the backend/web release path. Package tags are excluded from that production trigger.

## Verify what you have

```bash
hlix --version
npm view @hlix/cli version
npm view @hlix/sdk version
npm view @hlix/mcp version
```

An npm `E404` means that channel is not yet available; it is not evidence that the source install failed. [Current versions](/releases/availability/) is the page that says which channels are open.

For released builds, compare the installed version to the corresponding GitHub release and package changelog.

## If the versions disagree

- **`hlix --version` differs from `npm view @hlix/cli version`** — you are running a source build or an older global install, not the registry's latest. Both are valid; know which one you are testing.
- **A tag exists but the package does not** — a tag is not a release. Publication runs the ten gates above; only the reconciled ledger marks a package available.
- **A package version does not match its GitHub release checksum** — do not use it. Gate 8 refuses that combination, so its presence means the artifact changed after publication.
- **A platform release changed nothing in a package** — expected. The numbers move independently by design.
- **A Homebrew formula is missing for a released CLI** — the tap is announced separately, after its repository, formula, checksum, and install test exist.

## Next steps

[Current versions](/releases/availability/)
  [Changelog](/releases/changelog/)
  [Install the CLI](/getting-started/install/)
  [API & OpenAPI](/api/openapi/)