# Versioning policy

> What a slivingdoc release contains and how it is tagged, what is stable across releases, and how this documentation is versioned and archived.

Canonical URL: https://www.slivingdoc.dev/docs/project/versioning/ · Version: 0.1 · Updated: 2026-09-21

Full site index: https://www.slivingdoc.dev/llms.txt

This page has two halves: how the tool is released, and how these docs
are versioned alongside it.

## Release tags

A release is a `v<semver>` Git tag. slivingdoc is in its `v0.1.x` line
today, and this documentation set is written against `v0.1.19`.

One tag publishes native binaries for:

- linux/amd64, linux/arm (32-bit ARMv7, including Raspberry Pi OS armhf),
  and linux/arm64
- darwin/amd64 and darwin/arm64
- windows/amd64

They ship together with a strict `SHA256SUMS` file and the license
`NOTICE`. Asset names follow `slivingdoc-v<semver>-<os>-<arch>`, with
`.exe` on Windows.

The npm package `slivingdoc` is a launcher rather than a copy of the
binary. It selects the asset for its exact version and platform, verifies
the published SHA-256, caches the verified bytes under the npm cache, and
forwards stdio to the child process. An unsupported platform fails before
any download, with an actionable error. See
[Installation](/docs/installation/).

A prerelease tag — `v1.2.3-rc1`, for example — publishes to the `next`
npm dist-tag. A stable tag publishes to `latest`.

## Publication order

The order is enforced, not conventional:

1. The tag builds every target and assembles the GitHub release.
2. `npm run check-release` fails until the GitHub release for that
   version contains every required artifact, so npm publication can never
   precede a complete GitHub release.
3. The same tag then publishes the npm launcher automatically.
4. Only after that does the MCP Registry job validate and publish the
   checked-in `server.json` card, because the Registry can verify
   ownership only once the matching npm package version is public.

Publication uses npm trusted publishing (OIDC): the repository stores no
npm token and no Registry token, and each publish carries a provenance
attestation. The Registry card's server version and the npm package
version always move together.

## What is stable across releases

The tool's architecture contract names exactly what a caller may depend
on:

- The error `code`, `reason`, and `action` tokens, and every
  `files[].reason` token, are stable. Message text can change. See
  [Errors](/docs/reference/errors/).
- The storage format is versioned in the manifest itself: a future
  incompatible or extended schema uses a different `version`, and a
  version 1 reader rejects it before touching a pack. MCP callers do not
  depend on the internal representation at all.

Beyond that, the published sources make no compatibility promise, and
neither does this page. The tool is pre-1.0.

## How these docs are versioned

A docs version is one tool minor release. Today there is exactly one,
which is why no version switcher is shown.

- **Latest lives at the plain URL.** `/docs/…` is always the newest
  version. Bookmarks and links to a page keep pointing at its current
  form.
- **Archived versions get a prefix.** When a version is cut, the old set
  moves to `/docs/v<label>/…` and stays there, frozen.
- **An archived page says so.** It carries a banner linking to the latest
  version of the same page, and declares that latest page as canonical
  for search engines when one exists.
- **Archived pages are excluded** from the site search and from the
  `/llms.txt` and `/llms-full.txt` indexes, so neither a person nor an
  agent lands on a stale page by accident. They still have a Markdown
  representation like every other page.

Changes inside one version are listed on the
[Changelog](/docs/project/changelog/).