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. 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 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

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 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 versionsThe published version of each hlix package, and how to install it.

ChangelogDeveloper-tooling status and notable changes per package.

Install the CLIWhat to verify once a channel opens, and what to use until then.

API & OpenAPIHow the API contract's own version and URL prefix move.