diff --git a/README.md b/README.md
index d5482a3..39e4a3f 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,33 @@ jobs:
 
 In this example, the GitHub Action updates an existing nullplatform build's status to 'successful' when a pull request is closed.
 
+## Releasing
+
+Releases are split into two scripts because the org-level branch protection requires changes to `main` to go through a pull request.
+
+1. **Bump and open a release PR**:
+
+   ```bash
+   ./update-version.sh <new-version>     # e.g. ./update-version.sh 1.3.0
+   ```
+
+   Bumps `package.json` and `package-lock.json`, regenerates `dist/`, creates a `release/v<x.y.z>` branch, and opens a PR titled `Version v<x.y.z>`.
+
+2. **After the PR is merged**, sync `main` and publish tags:
+
+   ```bash
+   git checkout main && git pull
+   ./tag-release.sh <new-version>        # e.g. ./tag-release.sh 1.3.0
+   ```
+
+   Creates the fixed `v<x.y.z>` tag and force-moves the major moving tag (`v1`, `v2`, ...). Tags are not under the branch ruleset, so they can be pushed directly.
+
+3. **Optional** — publish a GitHub Release for the changelog:
+
+   ```bash
+   gh release create v<x.y.z> --title "v<x.y.z>" --notes "..."
+   ```
+
 ## License
 
 This GitHub Action is licensed under the [MIT License](LICENSE).
diff --git a/tag-release.sh b/tag-release.sh
new file mode 100755
index 0000000..e4ae1fe
--- /dev/null
+++ b/tag-release.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NEW_VERSION="${1:-}"
+if [ -z "$NEW_VERSION" ]; then
+  echo "Usage: $0 <version>" >&2
+  echo "Example: $0 1.3.0" >&2
+  exit 1
+fi
+
+VERSION="v$NEW_VERSION"
+MAJOR_VERSION="v$(echo "$NEW_VERSION" | cut -d. -f1)"
+
+# Pre-flight
+if [ "$(git branch --show-current)" != "main" ]; then
+  echo "Must be on main branch" >&2
+  exit 1
+fi
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Working tree must be clean" >&2
+  exit 1
+fi
+git fetch origin --quiet
+if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]; then
+  echo "Local main must equal origin/main (run: git pull)" >&2
+  exit 1
+fi
+
+PACKAGE_VERSION=$(grep '"version"' package.json | cut -d '"' -f 4)
+if [ "$PACKAGE_VERSION" != "$NEW_VERSION" ]; then
+  echo "package.json reports version $PACKAGE_VERSION but expected $NEW_VERSION" >&2
+  echo "Did you merge the PR opened by update-version.sh and pull main?" >&2
+  exit 1
+fi
+
+# Create fixed tag, force-move major moving tag
+git tag -a "$VERSION" -m "Version $VERSION"
+git tag -f -a "$MAJOR_VERSION" -m "Version $MAJOR_VERSION"
+
+# Push
+git push origin "$VERSION"
+git push origin "$MAJOR_VERSION" --force
+
+echo ""
+echo "Tags published:"
+echo "  $VERSION       -> $(git rev-parse "$VERSION^{}")"
+echo "  $MAJOR_VERSION         -> $(git rev-parse "$MAJOR_VERSION^{}")"
+echo ""
+echo "Optional final step — create a GitHub Release:"
+echo "  gh release create $VERSION --title \"$VERSION\" --notes \"...\""
diff --git a/update-version.sh b/update-version.sh
index f44ee49..0795b11 100755
--- a/update-version.sh
+++ b/update-version.sh
@@ -1,29 +1,48 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-VERSION_NUMBER=$(grep '"version"' package.json | cut -d '"' -f 4)
-MAJOR_VERSION_NUMBER=$(echo "$VERSION_NUMBER" | cut -d '.' -f 1)
-VERSION=$(echo "v$VERSION_NUMBER")
-MAJOR_VERSION=$(echo "v$MAJOR_VERSION_NUMBER")
+NEW_VERSION="${1:-}"
+if [ -z "$NEW_VERSION" ]; then
+  echo "Usage: $0 <version>" >&2
+  echo "Example: $0 1.3.0" >&2
+  exit 1
+fi
+
+VERSION="v$NEW_VERSION"
+BRANCH="release/$VERSION"
 
-# Prepare code to upload
+# Pre-flight
+if [ "$(git branch --show-current)" != "main" ]; then
+  echo "Must be on main branch" >&2
+  exit 1
+fi
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Working tree must be clean" >&2
+  exit 1
+fi
+git fetch origin --quiet
+if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]; then
+  echo "Local main must equal origin/main (run: git pull)" >&2
+  exit 1
+fi
+
+# Bump and rebuild
+npm version "$NEW_VERSION" --no-git-tag-version
 npm run prepare
-git add .
-git commit -m "Version $VERSION"
-git push origin main
 
-# Create or update a Git tag with the version number
-git tag -f -a "$VERSION" -m "Version $VERSION"
+# Branch + commit + push
+git checkout -b "$BRANCH"
+git add package.json package-lock.json dist/
+git commit -m "Version $VERSION"
+git push -u origin "$BRANCH"
 
-# Check if the major tag already exists
-if git rev-parse "$MAJOR_VERSION" >/dev/null 2>&1; then
-  # Update the existing major tag
-  git tag -f -a "$MAJOR_VERSION" -m "Version $MAJOR_VERSION"
-else
-  # Create a new tag
-  git tag -a "$MAJOR_VERSION" -m "Version $MAJOR_VERSION"
-fi
+# Open PR
+gh pr create \
+  --title "Version $VERSION" \
+  --body "Release commit for $VERSION. Tags will be created and pushed after merge via \`tag-release.sh\`."
 
-# Push the Git tags to GitHub
-git push origin "$VERSION" --force
-git push origin "$MAJOR_VERSION" --force
+echo ""
+echo "Next steps:"
+echo "  1. Merge the PR opened above"
+echo "  2. git checkout main && git pull"
+echo "  3. ./tag-release.sh $NEW_VERSION"