diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dd4f49a..c83e68f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -21,11 +21,14 @@ jobs:
         with:
           go-version-file: go.mod
       - name: build
+        env:
+          VERSION: ${{ github.ref_name }}
         run: |
           ext=""
           [ "${{ matrix.goos }}" = "windows" ] && ext=".exe"
           CGO_ENABLED=0 GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} \
-            go build -trimpath -ldflags "-s -w" \
+            go build -trimpath \
+            -ldflags "-s -w -X github.com/karitham/thrift-ls/lsp.ServerVersion=${VERSION#v}" \
             -o "dist/thrift-ls-${{ matrix.goos }}-${{ matrix.goarch }}$ext" .
       - uses: actions/upload-artifact@v4
         with:
@@ -62,6 +65,10 @@ jobs:
         run: |
           npm ci
           npm run test
+          [ "$(node -p "require('./package.json').version")" = "${GITHUB_REF_NAME#v}" ] || {
+            echo "vsix version does not match tag $GITHUB_REF_NAME"
+            exit 1
+          }
           npm run package
       - uses: actions/upload-artifact@v4
         with:
diff --git a/README.md b/README.md
index b7acc76..4b9ff58 100644
--- a/README.md
+++ b/README.md
@@ -358,6 +358,24 @@ Controls logging verbosity (the server logs to `$TMPDIR/thrift-ls.log`):
 - 5: debug
 - 6: trace
 
+## Releasing
+
+A `v*` tag triggers the release workflow: it builds the six `thrift-ls`
+binaries (linux/darwin/windows × amd64/arm64), a `checksums.txt`, and the
+VS Code `.vsix`, and attaches them to the GitHub release. The workflow
+injects the tag into the binary (`--version`), and fails if the vsix version
+doesn't match the tag.
+
+Before tagging, make sure the versions agree:
+
+- `vscode/package.json` `version`
+- `flake.nix` `version` and the `ServerVersion` ldflag (the workflow enforces
+  the vsix; the flake is manual)
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
 ## Development
 
 ```bash
diff --git a/flake.nix b/flake.nix
index 1772c3b..cbbadbd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -16,12 +16,15 @@
         pkgs:
         pkgs.buildGoModule {
           pname = "thrift-ls";
-          version = "0.1";
+          # Keep in sync with the release tag: the binary reports this
+          # version and the release workflow injects the same value.
+          version = "0.1.0";
           src = nixpkgs.lib.cleanSource ./.;
           vendorHash = "sha256-zWy0x3yktLA8dtcbwzue3aB7a+SlqwWO86G3ZP8DgOQ=";
           ldflags = [
             "-s"
             "-w"
+            "-X github.com/karitham/thrift-ls/lsp.ServerVersion=0.1.0"
           ];
           meta = {
             description = "A Thrift language server and formatter";
diff --git a/lsp/consts.go b/lsp/consts.go
index 635836a..0879a39 100644
--- a/lsp/consts.go
+++ b/lsp/consts.go
@@ -1,8 +1,13 @@
 package lsp
 
 const (
-	ServerName    = "thrift-ls"
-	ServerVersion = "0.1"
-
+	ServerName       = "thrift-ls"
 	LanguageIDThrift = "thrift"
 )
+
+// ServerVersion is the version reported by --version and the initialize
+// handshake. It defaults to "dev" and is replaced at release build time
+// with the git tag:
+//
+//	go build -ldflags "-X github.com/karitham/thrift-ls/lsp.ServerVersion=0.1.0"
+var ServerVersion = "dev"