diff --git a/README.md b/README.md
index 9532abe..9cade9f 100644
--- a/README.md
+++ b/README.md
@@ -23,19 +23,19 @@ jobs:
     runs-on: docker
     steps:
       - uses: actions/checkout@v4
-      - uses: http://192.168.1.230:3000/nholtware/workflows/node-checks@main
-      - uses: http://192.168.1.230:3000/nholtware/workflows/lint-checks@main
+      - uses: http://192.168.1.230:3000/nholtware/workflows/node-checks@v1
+      - uses: http://192.168.1.230:3000/nholtware/workflows/lint-checks@v1
   deploy:
     needs: checks
     runs-on: host
     steps:
       - uses: actions/checkout@v4
-      - uses: http://192.168.1.230:3000/nholtware/workflows/build-push@main
+      - uses: http://192.168.1.230:3000/nholtware/workflows/build-push@v1
         with:
           app-name: my-app
           registry-user: ${{ secrets.REGISTRY_USER }}
           registry-token: ${{ secrets.REGISTRY_TOKEN }}
-      - uses: http://192.168.1.230:3000/nholtware/workflows/gitops-bump@main
+      - uses: http://192.168.1.230:3000/nholtware/workflows/gitops-bump@v1
         with:
           app-name: my-app
           gitops-token: ${{ secrets.GITOPS_TOKEN }}
@@ -53,3 +53,13 @@ Secrets are user-level Actions secrets on the repo owner: `REGISTRY_USER`,
 `REGISTRY_TOKEN` (write:package), `GITOPS_TOKEN` (write on the gitops repo).
 For a non-Node app, drop the `checks` job (or swap in your own) — `deploy`
 is language-agnostic.
+
+## Versioning
+
+Consumers pin a **moving major tag**: `uses: .../workflows/<action>@v1`.
+Never reference `@main` (one bad push would break every repo at once).
+
+- Compatible change (fix, new optional input): merge to `main`, then move the tag:
+  `git tag -f v1 && git push -f origin v1`.
+- Breaking change (renamed/required input, changed behaviour): tag `v2`, migrate
+  consumers repo by repo, keep `v1` where it was.