diff --git a/.github/workflows/version.yml b/.github/workflows/version.yml
new file mode 100644
index 0000000..ce5f52b
--- /dev/null
+++ b/.github/workflows/version.yml
@@ -0,0 +1,18 @@
+name: version
+
+# Versioning via the bounded-systems mint capability. Validates .release/ intents
+# (fails closed on a malformed one) and previews the next version on every PR.
+# Pinned to an immutable mint commit SHA; bump when mint tags.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  version:
+    uses: bounded-systems/mint/.github/workflows/version.yml@7bc5c9c0826aa7bcb1fc78c8286ab6cc6311630a # mint
+    with:
+      ref: 7bc5c9c0826aa7bcb1fc78c8286ab6cc6311630a
diff --git a/.release/README.md b/.release/README.md
new file mode 100644
index 0000000..fa57da5
--- /dev/null
+++ b/.release/README.md
@@ -0,0 +1,15 @@
+# Release intents
+
+This repo uses [@bounded-systems/mint](https://github.com/bounded-systems/mint) for
+versioning. Each PR with a user-facing change drops an intent file here; mint
+resolves the strongest bump and cuts the release deterministically.
+
+Format — `.release/<slug>.md`:
+
+    ---
+    bump: minor   # patch | minor | major
+    ---
+    short summary of the change (becomes the changelog line)
+
+The `version` CI job runs `mint plan`, which validates every intent and previews
+the next version.