version bump

README.md

@@ -98,3 +98,37 @@ Deletes an instance by internal `id`. Only instances on the `development` stack
 | `hardware_acceleration` | 0 \| 1 | |
 | `createdAt` | ISO string | Set on insert |
 | `updatedAt` | ISO string | Updated on every write |
+
+---
+
+## Versioning
+
+Catalyst uses [semantic versioning](https://semver.org). The version in `package.json` is the source of truth and must match the release tag.
+
+| Change | Bump | Example |
+|---|---|---|
+| Bug fix | patch | `1.0.0` → `1.0.1` |
+| New feature, backward compatible | minor | `1.0.0` → `1.1.0` |
+| Breaking change | major | `1.0.0` → `2.0.0` |
+
+### Cutting a release
+
+**1. Bump the version in `package.json`**
+```json
+"version": "1.1.0"
+```
+
+**2. Commit, tag, and push**
+```bash
+git add package.json
+git commit -m "chore: release v1.1.0"
+git tag v1.1.0
+git push && git push --tags
+```
+
+Pushing the tag triggers the full pipeline: tests → build → release.
+
+- The image is tagged `:1.1.0`, `:1.1`, and `:latest` in the Gitea registry
+- A Gitea release is created at `v1.1.0` with the image reference in the release notes
+
+Pushes to `main` without a tag still run tests and build a `:latest` image — no release is created.