version bump

.gitea/workflows/build.yml

@@ -3,6 +3,8 @@ name: Build
 on:
   push:
     branches: [main]
+    tags:
+      - 'v*'
 
 env:
   IMAGE: ${{ vars.REGISTRY_HOST }}/${{ gitea.repository_owner }}/catalyst
@@ -35,6 +37,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
+
       - name: Log in to Gitea registry
         uses: docker/login-action@v3
         with:
@@ -47,31 +60,24 @@ jobs:
         with:
           context: .
           push: true
-          tags: |
-            ${{ env.IMAGE }}:latest
-            ${{ env.IMAGE }}:${{ gitea.sha }}
+          tags: ${{ steps.meta.outputs.tags }}
 
   release:
     runs-on: ubuntu-latest
     needs: build
+    if: startsWith(gitea.ref, 'refs/tags/v')
 
     steps:
       - name: Create release
-        env:
-          SHA: ${{ gitea.sha }}
         run: |
-          SHORT_SHA="${SHA:0:7}"
-          DATE=$(date +%Y-%m-%d)
-          TAG="v${DATE}-${SHORT_SHA}"
-
           curl -sf -X POST \
             -H "Authorization: token ${{ secrets.TOKEN }}" \
             -H "Content-Type: application/json" \
             "${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}/releases" \
             -d "{
-              \"tag_name\": \"${TAG}\",
-              \"name\": \"${TAG}\",
-              \"body\": \"Image: \`${{ env.IMAGE }}:${SHA}\`\",
+              \"tag_name\": \"${{ gitea.ref_name }}\",
+              \"name\": \"Catalyst ${{ gitea.ref_name }}\",
+              \"body\": \"### Image\n\n\`${{ env.IMAGE }}:${{ gitea.ref_name }}\`\",
               \"draft\": false,
               \"prerelease\": false
             }"

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.

package.json

@@ -1,4 +1,6 @@
 {
+  "name": "catalyst",
+  "version": "1.0.0",
   "type": "module",
   "scripts": {
     "test": "vitest run",