From 220c30292166725ecef9c393c7d7c7043a2bf493 Mon Sep 17 00:00:00 2001
From: Richard Eckart de Castilho <richard.eckart@gmail.com>
Date: Sat, 25 Jul 2026 18:01:50 +0200
Subject: [PATCH 1/4] #6189 - Release helper script

- Initial version with a status command
---
 scripts/release.sh | 289 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 289 insertions(+)
 create mode 100755 scripts/release.sh

diff --git a/scripts/release.sh b/scripts/release.sh
new file mode 100755
index 0000000000..41928f4f99
--- /dev/null
+++ b/scripts/release.sh
@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Release helper. Every subcommand is independently invocable and safe to
+# re-run: state is derived by looking at the file system and at the GitHub
+# release, never from a state file. That way you can stop after any step,
+# continue days later, and steps you performed by hand are still recognized.
+#
+# Usage:
+#   release.sh status <version>
+#
+# See `release.sh --help`.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+REPO="inception-project/inception"
+
+# Resolve the project root from this script's location so the script works
+# regardless of the current working directory.
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+
+MACOS_TARGET="$PROJECT_ROOT/inception/inception-dist-macos/target"
+WIN_TARGET="$PROJECT_ROOT/inception/inception-dist-win/target"
+WEBAPP_TARGET="$PROJECT_ROOT/inception/inception-app-webapp/target"
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+if [ -t 1 ]; then
+  C_RESET=$'\033[0m'; C_BOLD=$'\033[1m'; C_DIM=$'\033[2m'
+  C_GREEN=$'\033[32m'; C_YELLOW=$'\033[33m'; C_RED=$'\033[31m'
+else
+  C_RESET=''; C_BOLD=''; C_DIM=''; C_GREEN=''; C_YELLOW=''; C_RED=''
+fi
+
+say() { printf '%s\n' "$*"; }
+warn() { printf '%s\n' "${C_YELLOW}WARNING:${C_RESET} $*" >&2; }
+die() { printf '%s\n' "${C_RED}ERROR:${C_RESET} $*" >&2; exit 1; }
+
+# Status markers. Deliberately ASCII-safe words rather than symbols only, so
+# the output stays readable when redirected to a file or a CI log.
+mark_ok()      { printf '  %sok%s      %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+mark_missing() { printf '  %smissing%s %s\n' "$C_YELLOW" "$C_RESET" "$*"; }
+mark_note()    { printf '  %s-%s       %s\n' "$C_DIM" "$C_RESET" "$*"; }
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || die "Required tool '$1' not found in PATH."
+}
+
+# Print the size of a file in a human readable form, or nothing if absent.
+file_size() {
+  if [ -f "$1" ]; then
+    du -h "$1" | awk '{print $1}'
+  fi
+}
+
+# The git tag used for a given version.
+tag_for() { printf 'inception-%s\n' "$1"; }
+
+# Native installers are named after the base version *without* any beta
+# suffix, e.g. the inception-41.0-beta-2 release contains
+# INCEpTION-41.0-x86_64.msi, while the JAR keeps the full version.
+base_version_for() { printf '%s\n' "${1%%-beta*}"; }
+
+# ---------------------------------------------------------------------------
+# Expected artifacts
+# ---------------------------------------------------------------------------
+
+# Emits "<label>|<local-path>|<asset-name>" for every artifact a release is
+# expected to carry. This single definition is what `status` checks and what
+# later subcommands (draft/upload) will consume, so the notion of "complete"
+# lives in exactly one place.
+expected_artifacts() {
+  local version="$1"
+  local base; base="$(base_version_for "$version")"
+
+  printf 'macOS DMG (Apple Silicon)|%s|%s\n' \
+    "$MACOS_TARGET/jpackage-aarch64/INCEpTION-$base-aarch64.dmg" \
+    "INCEpTION-$base-aarch64.dmg"
+  printf 'macOS DMG (Intel)|%s|%s\n' \
+    "$MACOS_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.dmg" \
+    "INCEpTION-$base-x86_64.dmg"
+  printf 'Windows MSI|%s|%s\n' \
+    "$WIN_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.msi" \
+    "INCEpTION-$base-x86_64.msi"
+  printf 'Executable JAR|%s|%s\n' \
+    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar" \
+    "inception-app-webapp-$version-standalone.jar"
+  printf 'JAR signature|%s|%s\n' \
+    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar.asc" \
+    "inception-app-webapp-$version-standalone.jar.asc"
+}
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+# Is the DMG notarized and stapled? `stapler validate` exits 0 for a stapled
+# DMG and non-zero otherwise -- but it also exits 0 while printing an error
+# for a missing file, so the caller must check existence first.
+dmg_is_stapled() {
+  xcrun stapler validate "$1" >/dev/null 2>&1
+}
+
+cmd_status() {
+  local version="${1:-}"
+  [ -n "$version" ] || die "Usage: release.sh status <version>   (e.g. 41.3)"
+
+  require_tool gh
+  require_tool jq
+
+  local tag; tag="$(tag_for "$version")"
+  local base; base="$(base_version_for "$version")"
+
+  say "${C_BOLD}Release status for $version${C_RESET}  (tag: $tag)"
+  if [ "$base" != "$version" ]; then
+    say "${C_DIM}Native installers use base version $base${C_RESET}"
+  fi
+  say ""
+
+  # --- Git tag -------------------------------------------------------------
+  say "${C_BOLD}Git tag${C_RESET}"
+  if git -C "$PROJECT_ROOT" rev-parse -q --verify "refs/tags/$tag" >/dev/null 2>&1; then
+    mark_ok "$tag exists locally"
+  else
+    mark_missing "$tag does not exist locally"
+  fi
+  say ""
+
+  # --- Local build artifacts ----------------------------------------------
+  say "${C_BOLD}Local artifacts${C_RESET}"
+  local label path asset size
+  while IFS='|' read -r label path asset; do
+    if [ -f "$path" ]; then
+      size="$(file_size "$path")"
+      case "$path" in
+        *.dmg)
+          if dmg_is_stapled "$path"; then
+            mark_ok "$label ($size, notarized)"
+          else
+            mark_ok "$label ($size, ${C_YELLOW}not notarized${C_RESET})"
+          fi
+          ;;
+        *) mark_ok "$label ($size)" ;;
+      esac
+    else
+      mark_missing "$label"
+      printf '            %sexpected: %s%s\n' "$C_DIM" "${path#"$PROJECT_ROOT"/}" "$C_RESET"
+    fi
+  done < <(expected_artifacts "$version")
+  say ""
+
+  # --- Docker Compose file -------------------------------------------------
+  say "${C_BOLD}Docker Compose file${C_RESET}"
+  local compose="$WEBAPP_TARGET/generated-docs/admin-guide/scripts/docker-compose.yml"
+  if [ -f "$compose" ]; then
+    if grep -q '{revnumber}' "$compose"; then
+      mark_missing "contains unsubstituted {revnumber} placeholder"
+      printf '            %s%s%s\n' "$C_DIM" "${compose#"$PROJECT_ROOT"/}" "$C_RESET"
+    else
+      mark_ok "generated ($(file_size "$compose"))"
+    fi
+  else
+    mark_missing "not generated yet"
+  fi
+  say ""
+
+  # --- GitHub release ------------------------------------------------------
+  say "${C_BOLD}GitHub release${C_RESET}"
+  local release_json
+  if release_json="$(gh release view "$tag" --repo "$REPO" \
+        --json isDraft,isPrerelease,assets,url 2>/dev/null)"; then
+    local is_draft url
+    is_draft="$(jq -r '.isDraft' <<<"$release_json")"
+    url="$(jq -r '.url' <<<"$release_json")"
+    if [ "$is_draft" = "true" ]; then
+      mark_ok "draft exists"
+    else
+      mark_ok "${C_BOLD}PUBLISHED${C_RESET}"
+    fi
+    mark_note "$url"
+
+    say ""
+    say "  ${C_BOLD}Attached assets${C_RESET}"
+    while IFS='|' read -r label path asset; do
+      if jq -e --arg n "$asset" '.assets[] | select(.name == $n)' \
+           <<<"$release_json" >/dev/null 2>&1; then
+        mark_ok "$asset"
+      else
+        mark_missing "$asset"
+      fi
+    done < <(expected_artifacts "$version")
+
+    # Anything attached that we did not expect is worth surfacing rather than
+    # silently ignoring -- it may be a leftover or a manually added file.
+    local expected_names extra
+    expected_names="$(expected_artifacts "$version" | cut -d'|' -f3)"
+    extra="$(jq -r '.assets[].name' <<<"$release_json" \
+      | grep -Fxv -f <(printf '%s\n' "$expected_names") || true)"
+    if [ -n "$extra" ]; then
+      say ""
+      say "  ${C_BOLD}Additional assets${C_RESET}"
+      while IFS= read -r name; do
+        [ -n "$name" ] && mark_note "$name"
+      done <<<"$extra"
+    fi
+  else
+    mark_missing "no release for $tag"
+  fi
+  say ""
+
+  # --- Docker image --------------------------------------------------------
+  say "${C_BOLD}Docker image${C_RESET}"
+  local image="ghcr.io/inception-project/inception:$version"
+  local token
+  token="$(curl -s "https://ghcr.io/token?scope=repository:inception-project/inception:pull&service=ghcr.io" \
+    | jq -r '.token // empty' 2>/dev/null || true)"
+  if [ -n "$token" ]; then
+    local code
+    code="$(curl -s -o /dev/null -w '%{http_code}' \
+      -H "Authorization: Bearer $token" \
+      -H 'Accept: application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json,application/vnd.docker.distribution.manifest.v2+json' \
+      "https://ghcr.io/v2/inception-project/inception/manifests/$version")"
+    if [ "$code" = "200" ]; then
+      mark_ok "$image pushed"
+    else
+      mark_missing "$image not pushed (HTTP $code)"
+    fi
+  else
+    mark_note "could not query ghcr.io (offline?)"
+  fi
+  say ""
+}
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+usage() {
+  cat <<'EOF'
+Release helper for INCEpTION.
+
+Usage:
+  release.sh status <version>    Show what is done and what is still missing
+  release.sh --help             Show this help
+
+Every subcommand is safe to re-run. State is derived from the file system and
+from the GitHub release, so steps performed by hand are recognized too.
+
+Examples:
+  release.sh status 41.2
+EOF
+}
+
+main() {
+  local cmd="${1:-}"
+  case "$cmd" in
+    status) shift; cmd_status "$@" ;;
+    -h|--help|help|'') usage ;;
+    *) die "Unknown subcommand '$cmd'. Try --help." ;;
+  esac
+}
+
+main "$@"

From 0ac18ddba631fd7883df9426779e09738f76945f Mon Sep 17 00:00:00 2001
From: Richard Eckart de Castilho <richard.eckart@gmail.com>
Date: Sat, 25 Jul 2026 18:40:50 +0200
Subject: [PATCH 2/4] #6189 - Release helper script

- Replace single-file Docker Compose placeholder check with version-aware checks for all three generated scripts (docker-compose.yml, docker-compose-mysql8.yml, kubernetes.yml)
- Verify generated scripts pin the requested version, detecting both unsubstituted placeholders and stale builds from earlier versions
- Add GitHub Pages checks for release entry in releases.yml and documentation upload
- Add explicit "Not checked by this script" section to clarify which release checklist items cannot be verified
---
 scripts/release.sh | 131 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 118 insertions(+), 13 deletions(-)

diff --git a/scripts/release.sh b/scripts/release.sh
index 41928f4f99..44ec702b10 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -34,6 +34,11 @@ set -euo pipefail
 
 REPO="inception-project/inception"
 
+# The GitHub Pages site lives in a separate repository. It carries the release
+# index (`releases.yml`) and a per-release copy of the documentation.
+PAGES_REPO="inception-project/inception-project.github.io"
+PAGES_RELEASES_YML="_data/releases.yml"
+
 # Resolve the project root from this script's location so the script works
 # regardless of the current working directory.
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
@@ -116,6 +121,28 @@ expected_artifacts() {
     "inception-app-webapp-$version-standalone.jar.asc"
 }
 
+# ---------------------------------------------------------------------------
+# Generated example scripts
+# ---------------------------------------------------------------------------
+
+# The admin guide ships downloadable example scripts that must name the version
+# being released. Emits "<file>|<image-repo>" for each: the image repository is
+# the string the version has to be pinned to, and it is *not* the same for all
+# of them -- kubernetes.yml pulls from inception-snapshots.
+#
+# Deliberately no placeholder spelling here. Asserting that the file names the
+# requested version catches an unsubstituted placeholder of any spelling as
+# well as a file left over from an earlier version's build. Grepping for one
+# literal placeholder would not: the spelling changes from {revnumber} to
+# @project.version@ with the fix for #6186.
+generated_scripts() {
+  printf 'docker-compose.yml|ghcr.io/inception-project/inception\n'
+  printf 'docker-compose-mysql8.yml|ghcr.io/inception-project/inception\n'
+  printf 'kubernetes.yml|ghcr.io/inception-project/inception-snapshots\n'
+}
+
+GENERATED_SCRIPTS_DIR="$WEBAPP_TARGET/generated-docs/admin-guide/scripts"
+
 # ---------------------------------------------------------------------------
 # status
 # ---------------------------------------------------------------------------
@@ -175,19 +202,45 @@ cmd_status() {
   done < <(expected_artifacts "$version")
   say ""
 
-  # --- Docker Compose file -------------------------------------------------
-  say "${C_BOLD}Docker Compose file${C_RESET}"
-  local compose="$WEBAPP_TARGET/generated-docs/admin-guide/scripts/docker-compose.yml"
-  if [ -f "$compose" ]; then
-    if grep -q '{revnumber}' "$compose"; then
-      mark_missing "contains unsubstituted {revnumber} placeholder"
-      printf '            %s%s%s\n' "$C_DIM" "${compose#"$PROJECT_ROOT"/}" "$C_RESET"
+  # --- Generated example scripts -------------------------------------------
+  say "${C_BOLD}Generated example scripts${C_RESET}"
+  local script_name image_repo script_path
+  while IFS='|' read -r script_name image_repo; do
+    script_path="$GENERATED_SCRIPTS_DIR/$script_name"
+    if [ ! -f "$script_path" ]; then
+      mark_missing "$script_name not generated yet"
+      continue
+    fi
+    # Find the image line for this repository and require the version to appear
+    # on it. Matching the whole line rather than just the version keeps other
+    # versions mentioned elsewhere in the file from satisfying the check.
+    #
+    # The version is not necessarily adjacent to the repository name: the
+    # compose files wrap both in shell default expansions, as in
+    #   image: "${INCEPTION_IMAGE:-<repo>}:${INCEPTION_VERSION:-<version>}"
+    # while kubernetes.yml writes "<repo>:<version>" directly. Anchoring on the
+    # repository name and then looking for the version covers both.
+    #
+    # `|| true` because a non-matching grep must not abort the script: this
+    # whole block runs under `set -e`.
+    local image_line
+    image_line="$(grep -F "$image_repo" "$script_path" | head -1 || true)"
+    if [ -z "$image_line" ]; then
+      mark_missing "$script_name has no $image_repo image line"
+      printf '            %s%s%s\n' \
+        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
+    elif grep -qF "$version" <<<"$image_line"; then
+      mark_ok "$script_name pins $version"
     else
-      mark_ok "generated ($(file_size "$compose"))"
+      mark_missing "$script_name does not pin $version"
+      # Showing the actual line distinguishes an unsubstituted placeholder from
+      # a file left over from an earlier version's build.
+      printf '            %sfound: %s%s\n' \
+        "$C_DIM" "$(sed 's/^[[:space:]]*//' <<<"$image_line")" "$C_RESET"
+      printf '            %s%s%s\n' \
+        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
     fi
-  else
-    mark_missing "not generated yet"
-  fi
+  done < <(generated_scripts)
   say ""
 
   # --- GitHub release ------------------------------------------------------
@@ -234,6 +287,54 @@ cmd_status() {
   fi
   say ""
 
+  # --- GitHub Pages --------------------------------------------------------
+  # Both checks read the Pages repository through the API, so they need no
+  # credentials beyond the `gh` login that `status` already requires.
+  say "${C_BOLD}GitHub Pages${C_RESET} ${C_DIM}($PAGES_REPO)${C_RESET}"
+  local releases_yml
+  if releases_yml="$(gh api "repos/$PAGES_REPO/contents/$PAGES_RELEASES_YML" \
+        --jq '.content' 2>/dev/null | base64 -d 2>/dev/null)" \
+     && [ -n "$releases_yml" ]; then
+    # Recent entries quote the version (- version: "41.2"), older ones do not
+    # (- version: 0.4.0), so accept either. Commented-out entries do not count:
+    # the file keeps disabled snapshot/beta blocks around permanently.
+    if grep -Eq "^-[[:space:]]+version:[[:space:]]+\"?${version//./\\.}\"?[[:space:]]*$" \
+         <<<"$releases_yml"; then
+      mark_ok "$PAGES_RELEASES_YML lists $version"
+    else
+      mark_missing "$PAGES_RELEASES_YML does not list $version"
+    fi
+  else
+    mark_note "could not read $PAGES_RELEASES_YML"
+  fi
+
+  # The per-release documentation copy. Checking for a guide inside the docs
+  # directory rather than the directory itself, so a half-finished upload does
+  # not read as done.
+  local docs_path="releases/$version/docs"
+  local docs_listing
+  if docs_listing="$(gh api "repos/$PAGES_REPO/contents/$docs_path" \
+        --jq '.[].name' 2>/dev/null)" && [ -n "$docs_listing" ]; then
+    if grep -qx 'user-guide.html' <<<"$docs_listing"; then
+      mark_ok "release documentation uploaded ($docs_path)"
+    else
+      mark_missing "$docs_path exists but has no user-guide.html"
+    fi
+  else
+    mark_missing "no release documentation at $docs_path"
+  fi
+  say ""
+
+  # --- Manual steps --------------------------------------------------------
+  # Listed explicitly and never marked ok: these cannot be verified from here,
+  # and omitting them would let a clean run read as "release complete".
+  say "${C_BOLD}Not checked by this script${C_RESET}"
+  mark_note "all issues and PRs resolved/merged"
+  mark_note "release announcement written and added to the GitHub release"
+  mark_note "stable / community / demo instances updated"
+  mark_note "announcement sent to the mailing list"
+  say ""
+
   # --- Docker image --------------------------------------------------------
   say "${C_BOLD}Docker image${C_RESET}"
   local image="ghcr.io/inception-project/inception:$version"
@@ -269,8 +370,12 @@ Usage:
   release.sh status <version>    Show what is done and what is still missing
   release.sh --help             Show this help
 
-Every subcommand is safe to re-run. State is derived from the file system and
-from the GitHub release, so steps performed by hand are recognized too.
+Every subcommand is safe to re-run. State is derived from the file system, from
+the GitHub release and from the GitHub Pages site, so steps performed by hand
+are recognized too.
+
+`status` does not cover every item of the release checklist; the steps it cannot
+verify are listed under "Not checked by this script" in its output.
 
 Examples:
   release.sh status 41.2

From 4d619c41739d8e81873fb37eea333b1b707455bc Mon Sep 17 00:00:00 2001
From: Richard Eckart de Castilho <richard.eckart@gmail.com>
Date: Sat, 25 Jul 2026 18:44:45 +0200
Subject: [PATCH 3/4] #6189 - Release helper script

- Check the release tag on the remote rather than locally, detecting when a tag was never pushed or when a local tag diverges from origin
- Handle annotated tags correctly by comparing peeled commits, avoiding false mismatches and dependency on local tag object presence
- Distinguish network failures from missing tags when querying the remote
---
 scripts/release.sh | 47 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/scripts/release.sh b/scripts/release.sh
index 44ec702b10..fb60f9b93b 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -171,11 +171,52 @@ cmd_status() {
   say ""
 
   # --- Git tag -------------------------------------------------------------
+  # The remote tag is what makes a release a release; a purely local tag means
+  # the release was never pushed. The local tag is still worth resolving,
+  # because a leftover one from an aborted `release:prepare` shadows the real
+  # one and would make every local check look at the wrong commit.
   say "${C_BOLD}Git tag${C_RESET}"
-  if git -C "$PROJECT_ROOT" rev-parse -q --verify "refs/tags/$tag" >/dev/null 2>&1; then
-    mark_ok "$tag exists locally"
+  local local_sha='' remote_sha='' remote_commit='' remote_out remote_ok=1
+  local_sha="$(git -C "$PROJECT_ROOT" rev-parse -q --verify "refs/tags/$tag^{commit}" \
+    2>/dev/null || true)"
+
+  # `git ls-remote` exits 0 both for "no such tag" (no output) and, once piped,
+  # for a failure to reach the remote -- so the two must be told apart by
+  # capturing output and status separately rather than by exit code alone.
+  #
+  # Release tags are annotated, so refs/tags/X reports the *tag object* while
+  # refs/tags/X^{} reports the commit it points at. Ask for both and prefer the
+  # peeled line: comparing the tag object against a local commit would flag a
+  # mismatch on every annotated tag. Peeling remotely also avoids depending on
+  # the tag object being present in the local object store.
+  if remote_out="$(git -C "$PROJECT_ROOT" ls-remote --tags origin \
+        "refs/tags/$tag" "refs/tags/$tag^{}" 2>/dev/null)"; then
+    remote_ok=0
+    remote_sha="$(awk -v t="refs/tags/$tag" '$2 == t {print $1}' <<<"$remote_out")"
+    remote_commit="$(awk -v p="refs/tags/$tag^{}" '$2 == p {print $1}' <<<"$remote_out")"
+    # A lightweight tag has no peeled line; there the ref itself is the commit.
+    [ -n "$remote_commit" ] || remote_commit="$remote_sha"
+  fi
+
+  if [ "$remote_ok" -ne 0 ]; then
+    mark_note "could not query origin (offline?)"
+  elif [ -n "$remote_sha" ]; then
+    mark_ok "$tag pushed to origin"
   else
-    mark_missing "$tag does not exist locally"
+    mark_missing "$tag not pushed to origin"
+  fi
+
+  if [ -n "$local_sha" ]; then
+    if [ -n "$remote_commit" ] && [ "$remote_commit" != "$local_sha" ]; then
+      mark_missing "local $tag points at a different commit than origin"
+      printf '            %slocal:  %s%s\n' "$C_DIM" "$local_sha" "$C_RESET"
+      printf '            %sorigin: %s%s\n' "$C_DIM" "$remote_commit" "$C_RESET"
+    else
+      mark_note "also present locally (${local_sha:0:9})"
+    fi
+  elif [ "$remote_ok" -eq 0 ] && [ -n "$remote_sha" ]; then
+    # Perfectly normal -- a fresh clone, or the release was cut elsewhere.
+    mark_note "not present locally (run: git fetch --tags)"
   fi
   say ""
 

From da02106fa38bd73b7b8830f08953c735a94fdde1 Mon Sep 17 00:00:00 2001
From: Richard Eckart de Castilho <richard.eckart@gmail.com>
Date: Sat, 25 Jul 2026 21:05:44 +0200
Subject: [PATCH 4/4] #6189 - Release helper script

- Split monolithic release script into dispatcher plus ten focused subcommands
- Add release-functions.shlib for shared configuration and helpers
- Add release-status.sh to report build/release checklist status
- Add release-maven.sh to run Maven release prepare and perform
- Add release-macos.sh to build and notarize DMGs from target/checkout
- Add release-docker.sh to build and push Docker image with beta/release routing
- Add release-windows.sh to dispatch CI build, fetch MSI, and verify stale checkouts
- Add release-draft.sh to create GitHub draft release with changelog and boilerplate
- Add release-upload.sh to attach artifacts to draft and handle re-runs
- Add release-all.sh to run all steps in order with resumable failure handling
- Add release-notes.md.template for externalized release notes boilerplate
- Compose file examples now included as release artifacts
---
 scripts/release-all.sh            | 119 ++++++++
 scripts/release-docker.sh         |  84 ++++++
 scripts/release-draft.sh          | 178 +++++++++++
 scripts/release-functions.shlib   | 225 ++++++++++++++
 scripts/release-macos.sh          |  67 +++++
 scripts/release-maven.sh          |  56 ++++
 scripts/release-notes.md.template |  52 ++++
 scripts/release-status.sh         | 414 ++++++++++++++++++++++++++
 scripts/release-upload.sh         | 103 +++++++
 scripts/release-windows.sh        | 129 ++++++++
 scripts/release.sh                | 476 ++++++------------------------
 11 files changed, 1510 insertions(+), 393 deletions(-)
 create mode 100755 scripts/release-all.sh
 create mode 100755 scripts/release-docker.sh
 create mode 100755 scripts/release-draft.sh
 create mode 100644 scripts/release-functions.shlib
 create mode 100755 scripts/release-macos.sh
 create mode 100755 scripts/release-maven.sh
 create mode 100644 scripts/release-notes.md.template
 create mode 100755 scripts/release-status.sh
 create mode 100755 scripts/release-upload.sh
 create mode 100755 scripts/release-windows.sh

diff --git a/scripts/release-all.sh b/scripts/release-all.sh
new file mode 100755
index 0000000000..f7e93497b6
--- /dev/null
+++ b/scripts/release-all.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Runs the release steps in order, stopping at the first failure.
+#
+# Re-runnable: every step decides for itself whether there is anything to do -
+# maven refuses on a dirty tree, macos/docker rebuild in place, windows reuses a
+# successful CI run, draft leaves an existing draft alone, upload skips assets
+# already attached. So after fixing whatever broke, run this again and it carries
+# on rather than starting over.
+#
+# The release is deliberately left as a draft: review the notes and publish in
+# the browser. The remaining manual steps are listed by `release.sh status`.
+#
+# Usage: release-all.sh [--from <step>] [--dry-run]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=release-functions.shlib
+source "$SCRIPT_DIR/release-functions.shlib"
+
+# maven first (it creates target/checkout that the rest read the version from),
+# then the builds, then windows - which waits on CI and is by far the slowest -
+# then the release itself. upload comes last so it sees every artifact.
+STEPS="maven macos windows docker draft upload"
+
+from=''
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help|help)
+      info "Usage: release-all.sh [--from <step>] [--dry-run]"
+      info "Steps: $STEPS"
+      exit 0 ;;
+    --dry-run) dry_run=1 ;;
+    --from)
+      shift; [ $# -gt 0 ] || die "--from needs a step name."
+      from="$1" ;;
+    --from=*) from="${1#*=}" ;;
+    *) die "Unexpected argument '$1'." ;;
+  esac
+  shift
+done
+
+if [ -n "$from" ]; then
+  case " $STEPS " in
+    *" $from "*) ;;
+    *) die "Unknown step '$from'. Steps: $STEPS" ;;
+  esac
+fi
+
+dry_args=()
+if [ "$dry_run" -eq 1 ]; then
+  dry_args=(--dry-run)
+  # Everything after maven reads the version from target/checkout, which only
+  # exists once release:perform has run. Without it a dry run can only show the
+  # first step, so say that instead of failing four times over.
+  if ! version_from_checkout >/dev/null 2>&1; then
+    info "${C_YELLOW}No target/checkout yet${C_RESET} - the steps after maven derive the"
+    info "version from it, so they cannot be previewed before the release has run."
+    info ""
+    info "Steps that would run, in order:"
+    for step in $STEPS; do info "  $step"; done
+    exit 0
+  fi
+fi
+
+skipping=0
+[ -n "$from" ] && skipping=1
+
+for step in $STEPS; do
+  if [ "$skipping" -eq 1 ]; then
+    if [ "$step" = "$from" ]; then
+      skipping=0
+    else
+      info "${C_DIM}--- skip $step${C_RESET}"
+      continue
+    fi
+  fi
+
+  info ""
+  info "${C_BOLD}=== $step ===${C_RESET}"
+  info ""
+
+  # Not exec'd and not backgrounded: each step's output goes straight to the
+  # terminal, and a failure stops the sequence here so the log ends at the
+  # problem rather than scrolling past it.
+  if ! "$SCRIPT_DIR/release-$step.sh" "${dry_args[@]}"; then
+    info ""
+    die "Step '$step' failed. Fix it, then resume with:
+  release.sh all --from $step"
+  fi
+done
+
+info ""
+info "${C_BOLD}=== done ===${C_RESET}"
+info ""
+if [ "$dry_run" -eq 1 ]; then
+  info "${C_DIM}dry run - nothing was executed${C_RESET}"
+  exit 0
+fi
+info "The release is still a draft. Review the notes and publish it in the browser."
+info "Outstanding work: release.sh status"
diff --git a/scripts/release-docker.sh b/scripts/release-docker.sh
new file mode 100755
index 0000000000..aa105c116e
--- /dev/null
+++ b/scripts/release-docker.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Builds and pushes the multi-arch Docker image from target/checkout.
+#
+# Usage: release-docker.sh [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help|help) info "Usage: release-docker.sh [--dry-run]"; exit 0 ;;
+    --dry-run) dry_run=1 ;;
+    *) die "Unexpected argument '$1'." ;;
+  esac
+  shift
+done
+
+# Build from target/checkout, not from the working tree: the image tag comes from
+# ${project.version}, so building here would push <version>-SNAPSHOT from the
+# development poms. The checkout is the tag release:perform checked out, which is
+# what carries the released version - so the version is not a parameter, it is
+# whatever that tree says it is.
+build_dir="$PROJECT_ROOT/target/checkout"
+[ -d "$build_dir" ] || die "\
+No target/checkout - run the Maven release first (release.sh maven).
+The Docker image is built from the checked-out release tag, not the working tree."
+version="$(version_from_checkout)" \
+  || die "target/checkout has no released version (a SNAPSHOT, or an aborted run?)."
+
+# The image name has to be passed explicitly: the dist-docker profile defaults it
+# to inception-snapshots and release-docker does not override it, so omitting it
+# would push a release to the snapshots repository. Betas belong there, final
+# releases do not - image_repo_for() encodes that.
+image_repo="$(image_repo_for "$version")"
+warn_if_checkout_published "$version"
+
+MVN_ARGS=(-pl :inception-dist-docker -Pdist-docker,release-docker clean deploy
+  "-Ddocker.image.name=$image_repo")
+
+info "  cd target/checkout && mvn ${MVN_ARGS[*]}"
+info ""
+info "Pushing ${C_BOLD}$image_repo:$version${C_RESET}"
+if is_beta_version "$version"; then
+  info "${C_DIM}beta - goes to the snapshots repository${C_RESET}"
+fi
+info ""
+
+if [ "$dry_run" -eq 1 ]; then
+  info "${C_DIM}dry run - nothing executed${C_RESET}"
+  exit 0
+fi
+
+require_tool mvn
+require_tool docker
+# Warn early rather than after the multi-arch build. Only checks that ghcr.io is
+# known to Docker at all; whether the credentials are still valid shows at push.
+grep -q '"ghcr.io"' "${DOCKER_CONFIG:-$HOME/.docker}/config.json" 2>/dev/null \
+  || info "${C_YELLOW}ghcr.io not found in the Docker config - run: docker login ghcr.io${C_RESET}"
+
+cd "$build_dir"
+mvn "${MVN_ARGS[@]}"
+
+info ""
+info "Now check: release.sh status $version"
diff --git a/scripts/release-draft.sh b/scripts/release-draft.sh
new file mode 100755
index 0000000000..f9313f75bd
--- /dev/null
+++ b/scripts/release-draft.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Creates the GitHub release as a draft, with the changelog and the usual
+# boilerplate, and attaches the built artifacts.
+#
+# A draft on purpose: review and edit it in the browser before publishing. The
+# issue-type emojis past releases carry are not reproduced - GitHub's generated
+# changelog has no way to know them - so add those while editing if wanted.
+#
+# Usage: release-draft.sh [version] [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+version=''
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help|help) info "Usage: release-draft.sh [version] [--dry-run]"; exit 0 ;;
+    --dry-run) dry_run=1 ;;
+    -*) die "Unknown option '$1'." ;;
+    *) [ -z "$version" ] || die "Unexpected argument '$1'."; version="$1" ;;
+  esac
+  shift
+done
+
+[ -n "$version" ] || version="$(version_from_checkout)" \
+  || die "No version given and none could be derived from target/checkout."
+
+tag="$(tag_for "$version")"
+
+# The release this one upgrades from, and what the changelog is diffed against.
+#
+# 'inception-[0-9]*' rather than 'inception-*': the latter also matches the old
+# inception-app-* tags, which sort above everything and would produce a changelog
+# spanning years.
+#
+# Betas are skipped for a final release: 41.0's notes say "from 40.6 to 41.0",
+# not from 41.0-beta-2, even though the beta sorts higher. For a beta itself the
+# preceding beta is the right comparison, so they are kept in that case.
+# Picks the greatest tag strictly below this version rather than simply the
+# newest one, so re-drafting an older release still compares against the right
+# predecessor instead of the latest tag in the repository.
+previous_tag() {
+  local tags
+  tags="$(git -C "$PROJECT_ROOT" tag --list 'inception-[0-9]*' --sort=-v:refname \
+    | grep -vFx "$tag")"
+  if is_beta_version "$version"; then
+    # sort -V treats 41.0 as *lower* than 41.0-beta-1, so the final release of
+    # the same base would be picked as a beta's predecessor. Drop it.
+    tags="$(grep -vFx "$(tag_for "$(base_version_for "$version")")" <<<"$tags" || true)"
+  else
+    tags="$(grep -v -- '-beta' <<<"$tags" || true)"
+  fi
+  # sort -V puts our tag among the others; whatever lands just after it is the
+  # next lower version.
+  printf '%s\n%s\n' "$tags" "$tag" | sort -Vr | grep -A1 -Fx "$tag" | tail -1
+}
+
+# A .0 release carries features; anything else is bugfixes only.
+release_kind() {
+  case "$version" in
+    *-beta*) printf 'This is a beta release.\n' ;;
+    *.0) printf 'This is a feature and bug fix release.\n' ;;
+    *) printf 'This is a bug fix release.\n' ;;
+  esac
+}
+
+java_release() {
+  sed -n 's|.*<maven.compiler.release>\([0-9]*\)</maven.compiler.release>.*|\1|p' \
+    "$PROJECT_ROOT/inception/pom.xml" | head -1
+}
+
+prev="$(previous_tag)"
+prev_version="${prev#inception-}"
+java_ver="$(java_release)"
+[ -n "$java_ver" ] || die "Could not read maven.compiler.release from inception/pom.xml."
+
+# GitHub generates the same "## What's Changed" + "Full Changelog" block that
+# past releases carry, so it is fetched rather than rebuilt from the git log.
+changelog() {
+  gh api "repos/$REPO/releases/generate-notes" \
+    -f tag_name="$tag" -f previous_tag_name="$prev" --jq '.body' 2>/dev/null \
+    || info "(changelog generation failed - fill this in manually)"
+}
+
+TEMPLATE="$SCRIPT_DIR/release-notes.md.template"
+
+# Renders the template, replacing {{NAME}} placeholders.
+#
+# Placeholders rather than a sourced heredoc: the template is prose that gets
+# edited as text, and a heredoc would evaluate any $ or backtick it happens to
+# contain. Multi-line values are substituted with awk, since sed cannot insert
+# newlines portably.
+body() {
+  [ -f "$TEMPLATE" ] || die "Template not found: $TEMPLATE"
+
+  # The changelog is many lines, and BSD awk rejects newlines in -v values, so
+  # it is passed as a file and spliced in line by line.
+  local changes_file; changes_file="$(mktemp)"
+  # shellcheck disable=SC2064
+  trap "rm -f '$changes_file'" RETURN
+  changelog >"$changes_file"
+
+  awk -v kind="$(release_kind)" -v changes_file="$changes_file" \
+      -v version="$version" -v prev="$prev_version" -v java="$java_ver" '
+    {
+      gsub(/\{\{RELEASE_KIND\}\}/, kind)
+      gsub(/\{\{PREVIOUS_VERSION\}\}/, prev)
+      gsub(/\{\{JAVA_VERSION\}\}/, java)
+      gsub(/\{\{VERSION\}\}/, version)
+      if ($0 == "{{CHANGELOG}}") {
+        while ((getline line < changes_file) > 0) print line
+        next
+      }
+      print
+    }
+  ' "$TEMPLATE"
+}
+
+# Artifacts are not attached here - that is `release.sh upload`, which can run
+# repeatedly as they appear (the Windows MSI comes last, from CI). Keeping the
+# two apart means the build steps and this one can run in any order.
+info "Draft ${C_BOLD}INCEpTION $version${C_RESET} ($tag), changelog since $prev"
+info ""
+
+if [ "$dry_run" -eq 1 ]; then
+  info "${C_DIM}dry run - the body that would be used:${C_RESET}"
+  info ""
+  body
+  exit 0
+fi
+
+require_tool gh
+require_tool jq
+git -C "$PROJECT_ROOT" rev-parse -q --verify "refs/tags/$tag" >/dev/null 2>&1 \
+  || die "Tag $tag does not exist - run the Maven release first."
+
+# An existing draft is left alone rather than treated as an error: notes may have
+# been edited by hand already, and re-running must not discard that. This is what
+# makes `release.sh all` resumable. A published release is a different matter.
+if existing="$(gh release view "$tag" --repo "$REPO" --json isDraft,url 2>/dev/null)"; then
+  if [ "$(jq -r '.isDraft' <<<"$existing")" = "true" ]; then
+    info "A draft for $tag already exists - leaving it untouched."
+    info "$(jq -r '.url' <<<"$existing")"
+    info "Attach the artifacts with: release.sh upload $version"
+    exit 0
+  fi
+  die "Release $tag is already published - not replacing it."
+fi
+
+prerelease=()
+is_beta_version "$version" && prerelease=(--prerelease)
+
+gh release create "$tag" --repo "$REPO" --draft --verify-tag \
+  --title "INCEpTION $version" --notes-file - "${prerelease[@]}" < <(body)
+
+info ""
+info "Draft created. Attach the artifacts with: release.sh upload $version"
+gh release view "$tag" --repo "$REPO" --json url --jq '.url'
diff --git a/scripts/release-functions.shlib b/scripts/release-functions.shlib
new file mode 100644
index 0000000000..d19af96764
--- /dev/null
+++ b/scripts/release-functions.shlib
@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Shared definitions for the release helper scripts.
+#
+# Sourced, not executed: `release.sh` and the per-subcommand scripts each pull
+# this in so that the notion of what a release consists of - the expected
+# artifacts, the version rules, the output helpers - exists in exactly one
+# place. Sourcing rather than duplicating is deliberate: the beta rules below
+# are easy to get subtly wrong in a second copy.
+#
+# Anything used by more than one subcommand belongs here. Anything used by
+# exactly one belongs in that subcommand's script.
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+REPO="inception-project/inception"
+
+# The GitHub Pages site lives in a separate repository. It carries the release
+# index (`releases.yml`) and a per-release copy of the documentation.
+PAGES_REPO="inception-project/inception-project.github.io"
+PAGES_RELEASES_YML="_data/releases.yml"
+
+# Resolve the project root from *this file's* location, so it is correct no
+# matter which script sourced it or what the current working directory is.
+# BASH_SOURCE[0] is this library even when sourced, which is what we want:
+# every release script lives in the same scripts/ directory.
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+
+# Release artifacts are built from target/checkout (the tag release:perform
+# checks out), because their names come from ${project.version} and the working
+# tree is still on a SNAPSHOT. Fall back to the working tree so a hand-made
+# local build is still found.
+if [ -d "$PROJECT_ROOT/target/checkout/inception" ]; then
+  BUILD_ROOT="$PROJECT_ROOT/target/checkout"
+else
+  BUILD_ROOT="$PROJECT_ROOT"
+fi
+
+MACOS_TARGET="$BUILD_ROOT/inception/inception-dist-macos/target"
+WIN_TARGET="$BUILD_ROOT/inception/inception-dist-win/target"
+WEBAPP_TARGET="$BUILD_ROOT/inception/inception-app-webapp/target"
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+if [ -t 1 ]; then
+  C_RESET=$'\033[0m'; C_BOLD=$'\033[1m'; C_DIM=$'\033[2m'
+  C_GREEN=$'\033[32m'; C_YELLOW=$'\033[33m'; C_RED=$'\033[31m'
+else
+  C_RESET=''; C_BOLD=''; C_DIM=''; C_GREEN=''; C_YELLOW=''; C_RED=''
+fi
+
+info() { printf '%s\n' "$*"; }
+warn() { printf '%s\n' "${C_YELLOW}WARNING:${C_RESET} $*" >&2; }
+die() { printf '%s\n' "${C_RED}ERROR:${C_RESET} $*" >&2; exit 1; }
+
+# Status markers. Deliberately ASCII-safe words rather than symbols only, so
+# the output stays readable when redirected to a file or a CI log.
+mark_ok()      { printf '  %sok%s      %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+mark_missing() { printf '  %smissing%s %s\n' "$C_YELLOW" "$C_RESET" "$*"; }
+mark_note()    { printf '  %s-%s       %s\n' "$C_DIM" "$C_RESET" "$*"; }
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || die "Required tool '$1' not found in PATH."
+}
+
+# Print the size of a file in a human readable form, or nothing if absent.
+file_size() {
+  if [ -f "$1" ]; then
+    du -h "$1" | awk '{print $1}'
+  fi
+}
+
+# The git tag used for a given version.
+tag_for() { printf 'inception-%s\n' "$1"; }
+
+# The project version from a pom. The first <version> inside the project's own
+# <artifactId>..<packaging> block; the one before it belongs to the parent.
+pom_version() {
+  sed -n '/<artifactId>inception<\/artifactId>/,/<packaging>/p' "$1" 2>/dev/null \
+    | sed -n 's|.*<version>\(.*\)</version>.*|\1|p' | tail -1
+}
+
+# release:perform checks the tag out into target/checkout, leaving a tree whose
+# poms carry the released version. It survives the release (release.properties
+# does not - perform deletes it on success), so it is the best guess at "the
+# version I just released" when none is given.
+RELEASE_CHECKOUT_POM="$PROJECT_ROOT/target/checkout/pom.xml"
+
+version_from_checkout() {
+  [ -f "$RELEASE_CHECKOUT_POM" ] || return 1
+  local v; v="$(pom_version "$RELEASE_CHECKOUT_POM")"
+  # A SNAPSHOT there means the checkout is stale or from an aborted run, not a
+  # released version -- better to say nothing than to report on the wrong one.
+  case "$v" in
+    ''|*-SNAPSHOT) return 1 ;;
+    *) printf '%s\n' "$v" ;;
+  esac
+}
+
+# The checkout is not cleaned up between releases, so it can be left over from an
+# earlier one - and an earlier version reads as perfectly valid, which would
+# quietly push or attach artifacts for the wrong release.
+#
+# Comparing against the working tree's version does not work: right after
+# releasing 41.2 the tree is legitimately on 41.3-SNAPSHOT, so any "tree has moved
+# on" rule fires on every correct run. What actually distinguishes a stale
+# checkout is that its version is already published on GitHub.
+#
+# A warning, not an error: re-running a step against the release just made is
+# legitimate, and only the caller knows which they meant.
+warn_if_checkout_published() {
+  local v="$1" state
+  state="$(gh release view "$(tag_for "$v")" --repo "$REPO" --json isDraft \
+    --jq '.isDraft' 2>/dev/null)" || return 0
+  [ "$state" = "false" ] || return 0
+  warn "target/checkout is for $v, which is already published."
+  warn "If you meant to release a newer version, run 'release.sh maven' first."
+}
+
+# Native installers are named after the base version *without* any beta
+# suffix, e.g. the inception-41.0-beta-2 release contains
+# INCEpTION-41.0-x86_64.msi, while the JAR keeps the full version.
+base_version_for() { printf '%s\n' "${1%%-beta*}"; }
+
+is_beta_version() { [ "$(base_version_for "$1")" != "$1" ]; }
+
+# Betas are published to the snapshots repository, not to the release one:
+# only final releases go to ghcr.io/inception-project/inception. Verified
+# against ghcr.io -- 41.0-beta-1 and 41.0-beta-2 exist under
+# inception-snapshots and are absent from inception.
+#
+# This is the third consequence of the beta distinction, after the installer
+# naming above and the image repository in kubernetes.yml, which is why it gets
+# a named function rather than an inline test at the point of use.
+image_repo_for() {
+  if is_beta_version "$1"; then
+    printf 'ghcr.io/inception-project/inception-snapshots\n'
+  else
+    printf 'ghcr.io/inception-project/inception\n'
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Expected artifacts
+# ---------------------------------------------------------------------------
+
+# Emits "<label>|<local-path>|<asset-name>" for every artifact a release is
+# expected to carry. This single definition is what `status` checks and what
+# later subcommands (draft/upload) will consume, so the notion of "complete"
+# lives in exactly one place.
+expected_artifacts() {
+  local version="$1"
+  local base; base="$(base_version_for "$version")"
+
+  printf 'macOS DMG (Apple Silicon)|%s|%s\n' \
+    "$MACOS_TARGET/jpackage-aarch64/INCEpTION-$base-aarch64.dmg" \
+    "INCEpTION-$base-aarch64.dmg"
+  printf 'macOS DMG (Intel)|%s|%s\n' \
+    "$MACOS_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.dmg" \
+    "INCEpTION-$base-x86_64.dmg"
+  printf 'Windows MSI|%s|%s\n' \
+    "$WIN_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.msi" \
+    "INCEpTION-$base-x86_64.msi"
+  printf 'Executable JAR|%s|%s\n' \
+    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar" \
+    "inception-app-webapp-$version-standalone.jar"
+  printf 'JAR signature|%s|%s\n' \
+    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar.asc" \
+    "inception-app-webapp-$version-standalone.jar.asc"
+
+  # The generated example scripts, so users can grab a compose file pinned to
+  # this release instead of copying one out of the documentation. Note releases
+  # up to 41.2 did not carry these - they are an addition, not a restoration.
+  local script_name image_repo
+  while IFS='|' read -r script_name image_repo; do
+    printf 'Example script (%s)|%s|%s\n' \
+      "$script_name" "$GENERATED_SCRIPTS_DIR/$script_name" "$script_name"
+  done < <(generated_scripts)
+}
+
+# ---------------------------------------------------------------------------
+# Generated example scripts
+# ---------------------------------------------------------------------------
+
+# The admin guide ships downloadable example scripts that must name the version
+# being released. Emits "<file>|<image-repo>" for each: the image repository is
+# the string the version has to be pinned to, and it is *not* the same for all
+# of them -- kubernetes.yml pulls from inception-snapshots.
+#
+# Deliberately no placeholder spelling here. Asserting that the file names the
+# requested version catches an unsubstituted placeholder of any spelling as
+# well as a file left over from an earlier version's build. Grepping for one
+# literal placeholder would not: the spelling changes from {revnumber} to
+# @project.version@ with the fix for #6186.
+generated_scripts() {
+  printf 'docker-compose.yml|ghcr.io/inception-project/inception\n'
+  printf 'docker-compose-mysql8.yml|ghcr.io/inception-project/inception\n'
+  printf 'kubernetes.yml|ghcr.io/inception-project/inception-snapshots\n'
+}
+
+GENERATED_SCRIPTS_DIR="$WEBAPP_TARGET/generated-docs/admin-guide/scripts"
diff --git a/scripts/release-macos.sh b/scripts/release-macos.sh
new file mode 100755
index 0000000000..ae87019aec
--- /dev/null
+++ b/scripts/release-macos.sh
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Builds and notarizes the macOS DMGs from target/checkout.
+#
+# Usage: release-macos.sh [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+# One invocation, not two: notarization binds to `verify`, which runs `package`
+# first, so building and notarizing separately would build the DMGs twice. Both
+# profiles are needed here - release-macos only adds the notarize executions and
+# does not activate dist-macos.
+#
+# mac.signing.identity and mac.notarization.keychain.profile are enforced by the
+# poms but come from the macos-signing profile in ~/.m2/settings.xml, so they are
+# deliberately not passed here.
+MVN_ARGS=(-pl :inception-dist-macos verify -Pdist-macos,release-macos)
+
+case "${1:-}" in
+  -h|--help|help) info "Usage: release-macos.sh [--dry-run]"; exit 0 ;;
+esac
+
+# Built from target/checkout, not the working tree: the DMG names come from
+# ${project.version}, so building here would produce <version>-SNAPSHOT DMGs
+# instead of release ones.
+build_dir="$PROJECT_ROOT/target/checkout"
+
+info "  cd target/checkout && mvn ${MVN_ARGS[*]}"
+info ""
+version="$(version_from_checkout 2>/dev/null || true)"
+if [ -n "$version" ]; then
+  info "Building DMGs for ${C_BOLD}$(base_version_for "$version")${C_RESET}"
+  info ""
+fi
+
+if [ "${1:-}" = "--dry-run" ]; then
+  info "${C_DIM}dry run - nothing executed${C_RESET}"
+  exit 0
+fi
+
+[ "$(uname -s)" = "Darwin" ] || die "Notarization requires macOS."
+require_tool mvn
+[ -d "$build_dir" ] || die "\
+No target/checkout - run the Maven release first (release.sh maven).
+The DMGs are built from the checked-out release tag, not the working tree."
+
+cd "$build_dir"
+mvn "${MVN_ARGS[@]}"
diff --git a/scripts/release-maven.sh b/scripts/release-maven.sh
new file mode 100755
index 0000000000..0962634938
--- /dev/null
+++ b/scripts/release-maven.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Runs the Maven release. Maven prompts for the versions as usual.
+#
+# Usage: release-maven.sh [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+MVN_ARGS=(release:prepare release:perform
+  -DpreparationGoals=clean
+  -Darguments=-DskipTests\ -DretryFailedDeploymentCount=3)
+
+case "${1:-}" in
+  -h|--help|help) info "Usage: release-maven.sh [--dry-run]"; exit 0 ;;
+esac
+
+info '  mvn release:prepare release:perform -DpreparationGoals=clean \'
+info '    -Darguments="-DskipTests -DretryFailedDeploymentCount=3"'
+info ""
+# When Maven asks for the next development version after a beta, its suggestion
+# (e.g. 41.0-beta-3-SNAPSHOT) is not what this project uses: development goes
+# back to the snapshot the beta came from, e.g. 41.0-SNAPSHOT.
+info "${C_DIM}Releasing a beta? The next development version stays on the"
+info "same snapshot, not Maven's suggested -beta-N+1-SNAPSHOT.${C_RESET}"
+info ""
+
+if [ "${1:-}" = "--dry-run" ]; then
+  info "${C_DIM}dry run - nothing executed${C_RESET}"
+  exit 0
+fi
+
+require_tool mvn
+cd "$PROJECT_ROOT"
+mvn "${MVN_ARGS[@]}"
+
+info ""
+info "Now check: release.sh status <version>"
diff --git a/scripts/release-notes.md.template b/scripts/release-notes.md.template
new file mode 100644
index 0000000000..9098fb9a30
--- /dev/null
+++ b/scripts/release-notes.md.template
@@ -0,0 +1,52 @@
+INCEpTION is an extensible web-based collaborative environment for text annotation. It integrates machine-learning-based annotation support, knowledge base management and corpus building into a single comprehensive platform.
+
+{{RELEASE_KIND}}
+
+{{CHANGELOG}}
+
+
+### Download
+
+The new version can be downloaded from our website [3] or is available as docker images from GitHub [8].
+
+
+### Important upgrade notes
+
+Please check the upgrade notes [7]. If you upgrade from an older version, check upgrade and release notes of intermediate releases as well.
+
+An in-place upgrade from INCEpTION {{PREVIOUS_VERSION}} to {{VERSION}} is possible. You can usually also perform an in-place upgrade from an older version, but you should make sure that each of the intermediate releases allow an in-place upgrade to the next higher release.
+
+Back up your data before the upgrade [4].
+
+
+### Publication
+
+An overview of INCEpTION can be found in
+
+>Klie, J.-C., Bugert, M., Boullosa, B., Eckart de Castilho, R. and Gurevych, I. (2018):
+The INCEpTION Platform: Machine-Assisted and Knowledge-Oriented Interactive Annotation.
+In Proceedings of System Demonstrations of the 27th International Conference on Computational Linguistics (COLING 2018), Santa Fe, New Mexico, USA
+
+PDF and BibTeX as well as more publications on specific features are available from our website [5].
+
+
+### License and System requirements
+
+INCEpTION is provided as open source software under the Apache License version 2.
+
+Running INCEpTION requires **Java version {{JAVA_VERSION}}** or higher.
+
+By default, INCEpTION uses an embedded database which is sufficient for testing. However, the use of a MariaDB database is recommended.
+
+INCEpTION works best with Chrome and Safari.
+
+-- The INCEpTION developer team
+
+[1] https://github.com/inception-project/inception/issues?q=milestone%3A{{VERSION}}
+[2] https://github.com/inception-project/inception/issues
+[3] https://inception-project.github.io/downloads/
+[4] https://inception-project.github.io/releases/{{VERSION}}/docs/admin-guide.html#_backup_your_data
+[5] https://inception-project.github.io/publications/
+[6] https://inception-project.github.io/releases/{{VERSION}}/docs/admin-guide.html#_running_the_behind_a_reverse_proxy_jar
+[7] https://inception-project.github.io/releases/{{VERSION}}/docs/admin-guide.html#_upgrade_notes
+[8] https://github.com/inception-project/inception/pkgs/container/inception
diff --git a/scripts/release-status.sh b/scripts/release-status.sh
new file mode 100755
index 0000000000..0cdbc5d87b
--- /dev/null
+++ b/scripts/release-status.sh
@@ -0,0 +1,414 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Reports what is done and what is still missing for a release, in one pass.
+#
+# Read-only: it queries git, the file system, the GitHub release, GitHub Pages
+# and ghcr.io, and changes nothing. State is derived from those sources rather
+# than from a state file, so a release you performed by hand - or on another
+# machine - is recognized just the same.
+#
+# Usage:
+#   release-status.sh <version>          e.g. release-status.sh 41.2
+#
+# Also reachable as `release.sh status <version>`.
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+# ---------------------------------------------------------------------------
+# Checks
+# ---------------------------------------------------------------------------
+#
+# One `report_<area>` function per section of the output. Each resolves the
+# state it needs and prints its own findings; none of them change anything.
+#
+# Where a check cannot reach its source (offline, no credentials) it says so
+# with a `-` note rather than reporting the step as missing: "could not tell"
+# and "not done" are different answers and conflating them would be misleading.
+
+# Is the DMG notarized and stapled? `stapler validate` exits 0 for a stapled
+# DMG and non-zero otherwise -- but it also exits 0 while printing an error
+# for a missing file, so the caller must check existence first.
+dmg_is_stapled() {
+  xcrun stapler validate "$1" >/dev/null 2>&1
+}
+
+# --- Git tag ---------------------------------------------------------------
+
+# Resolves the tag state into TAG_LOCAL_SHA / TAG_REMOTE_COMMIT / TAG_REMOTE_OK
+# so both the predicate and the reporter can use it without querying twice.
+#
+# `git ls-remote` exits 0 both for "no such tag" (no output) and, once piped,
+# for a failure to reach the remote -- so the two must be told apart by
+# capturing output and status separately rather than by exit code alone.
+#
+# Release tags are annotated, so refs/tags/X reports the *tag object* while
+# refs/tags/X^{} reports the commit it points at. Ask for both and prefer the
+# peeled line: comparing the tag object against a local commit would flag a
+# mismatch on every annotated tag. Peeling remotely also avoids depending on
+# the tag object being present in the local object store.
+resolve_tag_state() {
+  local tag="$1" remote_out
+  TAG_LOCAL_SHA=''; TAG_REMOTE_SHA=''; TAG_REMOTE_COMMIT=''; TAG_REMOTE_OK=1
+
+  TAG_LOCAL_SHA="$(git -C "$PROJECT_ROOT" rev-parse -q --verify \
+    "refs/tags/$tag^{commit}" 2>/dev/null || true)"
+
+  if remote_out="$(git -C "$PROJECT_ROOT" ls-remote --tags origin \
+        "refs/tags/$tag" "refs/tags/$tag^{}" 2>/dev/null)"; then
+    TAG_REMOTE_OK=0
+    TAG_REMOTE_SHA="$(awk -v t="refs/tags/$tag" '$2 == t {print $1}' <<<"$remote_out")"
+    TAG_REMOTE_COMMIT="$(awk -v p="refs/tags/$tag^{}" '$2 == p {print $1}' <<<"$remote_out")"
+    # A lightweight tag has no peeled line; there the ref itself is the commit.
+    [ -n "$TAG_REMOTE_COMMIT" ] || TAG_REMOTE_COMMIT="$TAG_REMOTE_SHA"
+  fi
+}
+
+# Done when the tag is on origin. A tag that exists locally but diverges from
+# origin is *not* "todo" -- redoing would mean moving a published tag, which
+# rewrites history others may have fetched. Report it as a conflict instead and
+# let the caller refuse.
+# True when a local tag disagrees with origin about which commit is tagged.
+tag_diverged() {
+  [ -n "$TAG_LOCAL_SHA" ] && [ -n "$TAG_REMOTE_COMMIT" ] \
+    && [ "$TAG_REMOTE_COMMIT" != "$TAG_LOCAL_SHA" ]
+}
+
+report_tag() {
+  local version="$1" tag; tag="$(tag_for "$version")"
+  info "${C_BOLD}Git tag${C_RESET}"
+
+  resolve_tag_state "$tag"
+
+  if [ "$TAG_REMOTE_OK" -ne 0 ]; then
+    mark_note "could not query origin (offline?)"
+  elif [ -n "$TAG_REMOTE_SHA" ]; then
+    mark_ok "$tag pushed to origin"
+  else
+    mark_missing "$tag not pushed to origin"
+  fi
+
+  if [ -n "$TAG_LOCAL_SHA" ]; then
+    if tag_diverged; then
+      mark_missing "local $tag points at a different commit than origin"
+      printf '            %slocal:  %s%s\n' "$C_DIM" "$TAG_LOCAL_SHA" "$C_RESET"
+      printf '            %sorigin: %s%s\n' "$C_DIM" "$TAG_REMOTE_COMMIT" "$C_RESET"
+    else
+      mark_note "also present locally (${TAG_LOCAL_SHA:0:9})"
+    fi
+  elif [ "$TAG_REMOTE_OK" -eq 0 ] && [ -n "$TAG_REMOTE_SHA" ]; then
+    # Perfectly normal -- a fresh clone, or the release was cut elsewhere.
+    mark_note "not present locally (run: git fetch --tags)"
+  fi
+  info ""
+}
+
+# --- Local build artifacts -------------------------------------------------
+
+# Done when every expected artifact exists. Notarization is reported but does
+# not decide the verdict: an un-notarized DMG is a real problem, yet rebuilding
+# is not what fixes it, so it must not make the build step look undone.
+report_artifacts() {
+  info "${C_BOLD}Local artifacts${C_RESET}"
+  local label path asset size
+  while IFS='|' read -r label path asset; do
+    if [ -f "$path" ]; then
+      size="$(file_size "$path")"
+      case "$path" in
+        *.dmg)
+          if dmg_is_stapled "$path"; then
+            mark_ok "$label ($size, notarized)"
+          else
+            mark_ok "$label ($size, ${C_YELLOW}not notarized${C_RESET})"
+          fi
+          ;;
+        *) mark_ok "$label ($size)" ;;
+      esac
+    else
+      mark_missing "$label"
+      printf '            %sexpected: %s%s\n' "$C_DIM" "${path#"$PROJECT_ROOT"/}" "$C_RESET"
+    fi
+  done < <(expected_artifacts "$1")
+  info ""
+}
+
+# --- Generated example scripts ---------------------------------------------
+
+# Done when every generated example script pins the requested version. See
+# generated_scripts() for why the image repository is per-file and why the
+# check is placeholder-agnostic.
+#
+# Emits nothing; report_scripts repeats the matching so it can show detail.
+report_scripts() {
+  local version="$1"
+  info "${C_BOLD}Generated example scripts${C_RESET}"
+  local script_name image_repo script_path image_line
+  while IFS='|' read -r script_name image_repo; do
+    script_path="$GENERATED_SCRIPTS_DIR/$script_name"
+    if [ ! -f "$script_path" ]; then
+      mark_missing "$script_name not generated yet"
+      continue
+    fi
+    # Find the image line for this repository and require the version to appear
+    # on it. Matching the whole line rather than just the version keeps other
+    # versions mentioned elsewhere in the file from satisfying the check.
+    #
+    # The version is not necessarily adjacent to the repository name: the
+    # compose files wrap both in shell default expansions, as in
+    #   image: "${INCEPTION_IMAGE:-<repo>}:${INCEPTION_VERSION:-<version>}"
+    # while kubernetes.yml writes "<repo>:<version>" directly. Anchoring on the
+    # repository name and then looking for the version covers both.
+    #
+    # `|| true` because a non-matching grep must not abort the script: this
+    # whole block runs under `set -e`.
+    image_line="$(grep -F "$image_repo" "$script_path" | head -1 || true)"
+    if [ -z "$image_line" ]; then
+      mark_missing "$script_name has no $image_repo image line"
+      printf '            %s%s%s\n' \
+        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
+    elif grep -qF "$version" <<<"$image_line"; then
+      mark_ok "$script_name pins $version"
+    else
+      mark_missing "$script_name does not pin $version"
+      # Showing the actual line distinguishes an unsubstituted placeholder from
+      # a file left over from an earlier version's build.
+      printf '            %sfound: %s%s\n' \
+        "$C_DIM" "$(sed 's/^[[:space:]]*//' <<<"$image_line")" "$C_RESET"
+      printf '            %s%s%s\n' \
+        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
+    fi
+  done < <(generated_scripts)
+  info ""
+}
+
+# --- GitHub release --------------------------------------------------------
+
+# Fetches the release once into RELEASE_JSON. `gh release view` fails both for
+# "no such release" and for auth/network trouble; the two are told apart by
+# checking whether gh can reach the API at all.
+resolve_release_state() {
+  RELEASE_JSON=''; RELEASE_OK=1
+  if RELEASE_JSON="$(gh release view "$1" --repo "$REPO" \
+        --json isDraft,isPrerelease,assets,url 2>/dev/null)"; then
+    RELEASE_OK=0
+  fi
+}
+
+# Done when the release exists *and* carries every expected asset. A release
+# with missing assets is not done: re-running should upload the rest.
+report_release() {
+  local version="$1" tag; tag="$(tag_for "$version")"
+  info "${C_BOLD}GitHub release${C_RESET}"
+  resolve_release_state "$tag"
+  if [ "$RELEASE_OK" -ne 0 ]; then
+    mark_missing "no release for $tag"
+    info ""
+    return
+  fi
+
+  local is_draft url
+  is_draft="$(jq -r '.isDraft' <<<"$RELEASE_JSON")"
+  url="$(jq -r '.url' <<<"$RELEASE_JSON")"
+  if [ "$is_draft" = "true" ]; then
+    mark_ok "draft exists"
+  else
+    mark_ok "${C_BOLD}PUBLISHED${C_RESET}"
+  fi
+  mark_note "$url"
+
+  info ""
+  info "  ${C_BOLD}Attached assets${C_RESET}"
+  local label path asset
+  while IFS='|' read -r label path asset; do
+    if jq -e --arg n "$asset" '.assets[] | select(.name == $n)' \
+         <<<"$RELEASE_JSON" >/dev/null 2>&1; then
+      mark_ok "$asset"
+    else
+      mark_missing "$asset"
+    fi
+  done < <(expected_artifacts "$version")
+
+  # Anything attached that we did not expect is worth surfacing rather than
+  # silently ignoring -- it may be a leftover or a manually added file.
+  local expected_names extra name
+  expected_names="$(expected_artifacts "$version" | cut -d'|' -f3)"
+  extra="$(jq -r '.assets[].name' <<<"$RELEASE_JSON" \
+    | grep -Fxv -f <(printf '%s\n' "$expected_names") || true)"
+  if [ -n "$extra" ]; then
+    info ""
+    info "  ${C_BOLD}Additional assets${C_RESET}"
+    while IFS= read -r name; do
+      [ -n "$name" ] && mark_note "$name"
+    done <<<"$extra"
+  fi
+  info ""
+}
+
+# --- GitHub Pages ----------------------------------------------------------
+
+# Both checks read the Pages repository through the API, so they need no
+# credentials beyond the `gh` login that `status` already requires.
+
+pages_releases_yml() {
+  gh api "repos/$PAGES_REPO/contents/$PAGES_RELEASES_YML" --jq '.content' \
+    2>/dev/null | base64 -d 2>/dev/null
+}
+
+# Recent entries quote the version (- version: "41.2"), older ones do not
+# (- version: 0.4.0), so accept either. Commented-out entries do not count:
+# the file keeps disabled snapshot/beta blocks around permanently.
+releases_yml_lists() {
+  grep -Eq "^-[[:space:]]+version:[[:space:]]+\"?${2//./\\.}\"?[[:space:]]*$" <<<"$1"
+}
+
+# The per-release documentation copy. Checking for a guide inside the docs
+# directory rather than the directory itself, so a half-finished upload does
+# not read as done.
+report_pages() {
+  local version="$1"
+  info "${C_BOLD}GitHub Pages${C_RESET} ${C_DIM}($PAGES_REPO)${C_RESET}"
+
+  local yml; yml="$(pages_releases_yml)"
+  if [ -z "$yml" ]; then
+    mark_note "could not read $PAGES_RELEASES_YML"
+  elif releases_yml_lists "$yml" "$version"; then
+    mark_ok "$PAGES_RELEASES_YML lists $version"
+  else
+    mark_missing "$PAGES_RELEASES_YML does not list $version"
+  fi
+
+  local docs_path="releases/$version/docs" docs_listing
+  if docs_listing="$(gh api "repos/$PAGES_REPO/contents/$docs_path" \
+        --jq '.[].name' 2>/dev/null)" && [ -n "$docs_listing" ]; then
+    if grep -qx 'user-guide.html' <<<"$docs_listing"; then
+      mark_ok "release documentation uploaded ($docs_path)"
+    else
+      mark_missing "$docs_path exists but has no user-guide.html"
+    fi
+  else
+    mark_missing "no release documentation at $docs_path"
+  fi
+  info ""
+}
+
+# --- Docker image ----------------------------------------------------------
+
+# Which repository to look in depends on whether this is a beta; see
+# image_repo_for(). Checking the release repository for a beta would report a
+# correctly published beta as missing.
+#
+# Returns the HTTP status of a manifest HEAD, or nothing if no anonymous token
+# could be obtained (offline).
+ghcr_manifest_status() {
+  local repo_path="$1" version="$2" token
+  token="$(curl -s "https://ghcr.io/token?scope=repository:$repo_path:pull&service=ghcr.io" \
+    | jq -r '.token // empty' 2>/dev/null || true)"
+  [ -n "$token" ] || return 1
+  curl -s -o /dev/null -w '%{http_code}' \
+    -H "Authorization: Bearer $token" \
+    -H 'Accept: application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json,application/vnd.docker.distribution.manifest.v2+json' \
+    "https://ghcr.io/v2/$repo_path/manifests/$version"
+}
+
+report_docker() {
+  local version="$1" repo_path image code
+  info "${C_BOLD}Docker image${C_RESET}"
+  repo_path="$(image_repo_for "$version")"; repo_path="${repo_path#ghcr.io/}"
+  image="ghcr.io/$repo_path:$version"
+  if is_beta_version "$version"; then
+    mark_note "beta - expected in the snapshots repository"
+  fi
+  if code="$(ghcr_manifest_status "$repo_path" "$version")"; then
+    if [ "$code" = "200" ]; then
+      mark_ok "$image pushed"
+    else
+      mark_missing "$image not pushed (HTTP $code)"
+    fi
+  else
+    mark_note "could not query ghcr.io (offline?)"
+  fi
+  info ""
+}
+
+# --- Manual steps ----------------------------------------------------------
+
+# Listed explicitly and never marked ok: these cannot be verified from here,
+# and omitting them would let a clean run read as "release complete".
+report_manual() {
+  info "${C_BOLD}Not checked by this script${C_RESET}"
+  mark_note "all issues and PRs resolved/merged"
+  mark_note "release announcement written and added to the GitHub release"
+  mark_note "stable / community / demo instances updated"
+  mark_note "announcement sent to the mailing list"
+  info ""
+}
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+cmd_status() {
+  local version="${1:-}" derived=0
+  if [ -z "$version" ]; then
+    version="$(version_from_checkout)" || die "\
+Usage: release.sh status <version>   (e.g. 41.3)
+No version given and none could be derived from target/checkout."
+    derived=1
+  fi
+
+  require_tool gh
+  require_tool jq
+
+  local tag; tag="$(tag_for "$version")"
+  local base; base="$(base_version_for "$version")"
+
+  info "${C_BOLD}Release status for $version${C_RESET}  (tag: $tag)"
+  if [ "$derived" -eq 1 ]; then
+    info "${C_DIM}version taken from target/checkout${C_RESET}"
+  fi
+  if [ "$base" != "$version" ]; then
+    info "${C_DIM}Native installers use base version $base${C_RESET}"
+  fi
+  info ""
+
+  report_tag "$version"
+  report_artifacts "$version"
+  report_scripts "$version"
+  report_release "$version"
+  report_pages "$version"
+  report_manual
+  report_docker "$version"
+}
+
+
+main() {
+  local version="${1:-}"
+  case "$version" in
+    -h|--help|help)
+      info "Usage: release-status.sh [version]   (default: from target/checkout)"
+      exit 0
+      ;;
+  esac
+  # With no argument, cmd_status tries target/checkout and fails if there is
+  # nothing to derive from -- a forgotten version must not look like success.
+  cmd_status "$version"
+}
+
+main "$@"
diff --git a/scripts/release-upload.sh b/scripts/release-upload.sh
new file mode 100755
index 0000000000..55bcc2aa9a
--- /dev/null
+++ b/scripts/release-upload.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Attaches the built artifacts to an existing GitHub release.
+#
+# Separate from `draft` so the order of the build steps does not matter: create
+# the draft whenever, and run this again as artifacts appear (the Windows MSI
+# arrives last, via CI). Uploads with --clobber, so re-running replaces rather
+# than fails.
+#
+# Usage: release-upload.sh [version] [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+version=''
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help|help) info "Usage: release-upload.sh [version] [--dry-run]"; exit 0 ;;
+    --dry-run) dry_run=1 ;;
+    -*) die "Unknown option '$1'." ;;
+    *) [ -z "$version" ] || die "Unexpected argument '$1'."; version="$1" ;;
+  esac
+  shift
+done
+
+[ -n "$version" ] || version="$(version_from_checkout)" \
+  || die "No version given and none could be derived from target/checkout."
+
+tag="$(tag_for "$version")"
+
+require_tool gh
+require_tool jq
+
+release_json="$(gh release view "$tag" --repo "$REPO" --json isDraft,assets,url 2>/dev/null)" \
+  || die "No release for $tag - create it first with: release.sh draft"
+
+# Refuse to touch a published release: its assets are what people have already
+# been pointed at. Re-attaching to a draft is safe, changing a published release
+# is not something to do implicitly.
+[ "$(jq -r '.isDraft' <<<"$release_json")" = "true" ] \
+  || die "Release $tag is already published - not modifying its assets."
+
+# Only upload what is missing or has changed size; re-uploading a 360 MB MSI that
+# is already attached wastes minutes.
+to_upload=()
+missing=0
+while IFS='|' read -r label path asset; do
+  if [ ! -f "$path" ]; then
+    info "${C_YELLOW}missing${C_RESET} $label ${C_DIM}(not built yet)${C_RESET}"
+    missing=$((missing + 1))
+    continue
+  fi
+  remote_size="$(jq -r --arg n "$asset" \
+    '.assets[] | select(.name == $n) | .size' <<<"$release_json")"
+  local_size="$(wc -c <"$path" | tr -d ' ')"
+  if [ -z "$remote_size" ]; then
+    info "${C_GREEN}upload${C_RESET}  $asset ($(file_size "$path"))"
+    to_upload+=("$path")
+  elif [ "$remote_size" != "$local_size" ]; then
+    info "${C_GREEN}replace${C_RESET} $asset ${C_DIM}($remote_size -> $local_size bytes)${C_RESET}"
+    to_upload+=("$path")
+  else
+    info "ok      $asset ${C_DIM}(already attached)${C_RESET}"
+  fi
+done < <(expected_artifacts "$version")
+
+info ""
+if [ "${#to_upload[@]}" -eq 0 ]; then
+  info "Nothing to upload.$([ "$missing" -gt 0 ] && printf ' %s artifact(s) still missing.' "$missing")"
+  exit 0
+fi
+
+if [ "$dry_run" -eq 1 ]; then
+  info "${C_DIM}dry run - would upload ${#to_upload[@]} file(s)${C_RESET}"
+  exit 0
+fi
+
+gh release upload "$tag" --repo "$REPO" --clobber "${to_upload[@]}"
+
+info ""
+if [ "$missing" -gt 0 ]; then
+  info "$missing artifact(s) still missing - run the remaining build steps."
+fi
+info "Now check: release.sh status $version"
diff --git a/scripts/release-windows.sh b/scripts/release-windows.sh
new file mode 100755
index 0000000000..6ec6cc13bf
--- /dev/null
+++ b/scripts/release-windows.sh
@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Technische Universität Darmstadt under one
+#  or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The Technische Universität Darmstadt
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Builds the Windows MSI on GitHub Actions and downloads it.
+#
+# The MSI cannot be built locally, so this dispatches the dist-win workflow on
+# the release tag, waits for it, and unpacks the artifact where the other
+# release steps expect it - so `release.sh status` and `release.sh draft` then
+# treat it like a locally built artifact.
+#
+# Re-runnable: if a successful run for the tag already exists, it downloads from
+# that instead of building again. Use --rebuild to force a new run.
+#
+# Usage: release-windows.sh [--rebuild] [--dry-run]
+
+set -euo pipefail
+
+# shellcheck source=release-functions.shlib
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/release-functions.shlib"
+
+WORKFLOW="dist-win.yml"
+ARTIFACT="inception-msi-x86_64"
+
+rebuild=0
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help|help)
+      info "Usage: release-windows.sh [--rebuild] [--dry-run]"; exit 0 ;;
+    --rebuild) rebuild=1 ;;
+    --dry-run) dry_run=1 ;;
+    *) die "Unexpected argument '$1'." ;;
+  esac
+  shift
+done
+
+# Like macos and docker, the version comes from the checkout release:perform left
+# behind rather than from an argument - there is one release in flight at a time.
+version="$(version_from_checkout)" || die "\
+No target/checkout - run the Maven release first (release.sh maven).
+The MSI is built from the release tag recorded there."
+
+tag="$(tag_for "$version")"
+# The MSI carries the base version, dropping any beta suffix.
+msi="INCEpTION-$(base_version_for "$version")-x86_64.msi"
+dest="$WIN_TARGET/jpackage-x86_64"
+
+# Latest run of the workflow for this tag, whatever its state.
+latest_run() {
+  gh run list --workflow "$WORKFLOW" --repo "$REPO" --branch "$tag" \
+    --limit 1 --json databaseId,status,conclusion 2>/dev/null
+}
+
+info "Windows MSI for ${C_BOLD}$version${C_RESET} ($tag)"
+info "  workflow: $WORKFLOW on $tag"
+info "  artifact: $ARTIFACT -> ${dest#"$PROJECT_ROOT"/}/$msi"
+info ""
+
+if [ "$dry_run" -eq 1 ]; then
+  info "${C_DIM}dry run - nothing executed${C_RESET}"
+  exit 0
+fi
+
+require_tool gh
+require_tool jq
+warn_if_checkout_published "$version"
+
+if [ -f "$dest/$msi" ] && [ "$rebuild" -eq 0 ]; then
+  info "Already present - nothing to do (use --rebuild to force a new run)."
+  exit 0
+fi
+
+run_json="$(latest_run)"
+run_id="$(jq -r '.[0].databaseId // empty' <<<"$run_json")"
+conclusion="$(jq -r '.[0].conclusion // empty' <<<"$run_json")"
+
+if [ "$rebuild" -eq 1 ] || [ -z "$run_id" ] || [ "$conclusion" = "failure" ]; then
+  git ls-remote --tags origin "refs/tags/$tag" 2>/dev/null | grep -q . \
+    || die "Tag $tag is not on origin - the workflow can only build a pushed tag."
+
+  info "Dispatching $WORKFLOW on $tag ..."
+  gh workflow run "$WORKFLOW" --repo "$REPO" --ref "$tag" -f ref="$tag"
+
+  # `gh workflow run` does not report the run id, so wait for a *new* run to
+  # appear rather than picking up the previous one for this tag.
+  prev_run_id="$run_id"
+  for _ in $(seq 1 30); do
+    sleep 2
+    run_json="$(latest_run)"
+    run_id="$(jq -r '.[0].databaseId // empty' <<<"$run_json")"
+    if [ -n "$run_id" ] && [ "$run_id" != "$prev_run_id" ]; then
+      break
+    fi
+    run_id=''
+  done
+  [ -n "$run_id" ] || die "Dispatched, but no new run appeared. Check: gh run list --workflow $WORKFLOW"
+fi
+
+info "Run: https://github.com/$REPO/actions/runs/$run_id"
+gh run watch "$run_id" --repo "$REPO" --exit-status \
+  || die "The workflow run failed. See the log above."
+
+mkdir -p "$dest"
+info ""
+info "Downloading $ARTIFACT ..."
+gh run download "$run_id" --repo "$REPO" --name "$ARTIFACT" --dir "$dest"
+
+[ -f "$dest/$msi" ] || die "\
+Downloaded, but $msi is not there. Contents:
+$(ls -1 "$dest" 2>/dev/null)"
+
+info ""
+info "$msi ($(file_size "$dest/$msi"))"
+info "Now check: release.sh status $version"
diff --git a/scripts/release.sh b/scripts/release.sh
index fb60f9b93b..91a97ac97c 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -16,419 +16,109 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Release helper. Every subcommand is independently invocable and safe to
-# re-run: state is derived by looking at the file system and at the GitHub
-# release, never from a state file. That way you can stop after any step,
-# continue days later, and steps you performed by hand are still recognized.
+# Release helper for INCEpTION - dispatcher only.
 #
-# Usage:
-#   release.sh status <version>
+# Each subcommand lives in its own script next to this one, so that any single
+# step can be read and understood on its own:
 #
-# See `release.sh --help`.
+#   status  ->  release-status.sh
+#   maven   ->  release-maven.sh
+#   macos   ->  release-macos.sh
+#   docker  ->  release-docker.sh
+#   windows ->  release-windows.sh
+#   draft   ->  release-draft.sh
+#   upload  ->  release-upload.sh
+#   all     ->  release-all.sh   (runs the above in order)
+#
+# Shared definitions live in release-functions.shlib. This file only picks a
+# script and hands over; it contains no release logic itself.
 
 set -euo pipefail
 
-# ---------------------------------------------------------------------------
-# Configuration
-# ---------------------------------------------------------------------------
-
-REPO="inception-project/inception"
-
-# The GitHub Pages site lives in a separate repository. It carries the release
-# index (`releases.yml`) and a per-release copy of the documentation.
-PAGES_REPO="inception-project/inception-project.github.io"
-PAGES_RELEASES_YML="_data/releases.yml"
-
-# Resolve the project root from this script's location so the script works
-# regardless of the current working directory.
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
-
-MACOS_TARGET="$PROJECT_ROOT/inception/inception-dist-macos/target"
-WIN_TARGET="$PROJECT_ROOT/inception/inception-dist-win/target"
-WEBAPP_TARGET="$PROJECT_ROOT/inception/inception-app-webapp/target"
-
-# ---------------------------------------------------------------------------
-# Output helpers
-# ---------------------------------------------------------------------------
-
-if [ -t 1 ]; then
-  C_RESET=$'\033[0m'; C_BOLD=$'\033[1m'; C_DIM=$'\033[2m'
-  C_GREEN=$'\033[32m'; C_YELLOW=$'\033[33m'; C_RED=$'\033[31m'
-else
-  C_RESET=''; C_BOLD=''; C_DIM=''; C_GREEN=''; C_YELLOW=''; C_RED=''
-fi
-
-say() { printf '%s\n' "$*"; }
-warn() { printf '%s\n' "${C_YELLOW}WARNING:${C_RESET} $*" >&2; }
-die() { printf '%s\n' "${C_RED}ERROR:${C_RESET} $*" >&2; exit 1; }
-
-# Status markers. Deliberately ASCII-safe words rather than symbols only, so
-# the output stays readable when redirected to a file or a CI log.
-mark_ok()      { printf '  %sok%s      %s\n' "$C_GREEN" "$C_RESET" "$*"; }
-mark_missing() { printf '  %smissing%s %s\n' "$C_YELLOW" "$C_RESET" "$*"; }
-mark_note()    { printf '  %s-%s       %s\n' "$C_DIM" "$C_RESET" "$*"; }
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-require_tool() {
-  command -v "$1" >/dev/null 2>&1 || die "Required tool '$1' not found in PATH."
-}
-
-# Print the size of a file in a human readable form, or nothing if absent.
-file_size() {
-  if [ -f "$1" ]; then
-    du -h "$1" | awk '{print $1}'
-  fi
-}
-
-# The git tag used for a given version.
-tag_for() { printf 'inception-%s\n' "$1"; }
-
-# Native installers are named after the base version *without* any beta
-# suffix, e.g. the inception-41.0-beta-2 release contains
-# INCEpTION-41.0-x86_64.msi, while the JAR keeps the full version.
-base_version_for() { printf '%s\n' "${1%%-beta*}"; }
-
-# ---------------------------------------------------------------------------
-# Expected artifacts
-# ---------------------------------------------------------------------------
-
-# Emits "<label>|<local-path>|<asset-name>" for every artifact a release is
-# expected to carry. This single definition is what `status` checks and what
-# later subcommands (draft/upload) will consume, so the notion of "complete"
-# lives in exactly one place.
-expected_artifacts() {
-  local version="$1"
-  local base; base="$(base_version_for "$version")"
-
-  printf 'macOS DMG (Apple Silicon)|%s|%s\n' \
-    "$MACOS_TARGET/jpackage-aarch64/INCEpTION-$base-aarch64.dmg" \
-    "INCEpTION-$base-aarch64.dmg"
-  printf 'macOS DMG (Intel)|%s|%s\n' \
-    "$MACOS_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.dmg" \
-    "INCEpTION-$base-x86_64.dmg"
-  printf 'Windows MSI|%s|%s\n' \
-    "$WIN_TARGET/jpackage-x86_64/INCEpTION-$base-x86_64.msi" \
-    "INCEpTION-$base-x86_64.msi"
-  printf 'Executable JAR|%s|%s\n' \
-    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar" \
-    "inception-app-webapp-$version-standalone.jar"
-  printf 'JAR signature|%s|%s\n' \
-    "$WEBAPP_TARGET/inception-app-webapp-$version-standalone.jar.asc" \
-    "inception-app-webapp-$version-standalone.jar.asc"
-}
-
-# ---------------------------------------------------------------------------
-# Generated example scripts
-# ---------------------------------------------------------------------------
-
-# The admin guide ships downloadable example scripts that must name the version
-# being released. Emits "<file>|<image-repo>" for each: the image repository is
-# the string the version has to be pinned to, and it is *not* the same for all
-# of them -- kubernetes.yml pulls from inception-snapshots.
-#
-# Deliberately no placeholder spelling here. Asserting that the file names the
-# requested version catches an unsubstituted placeholder of any spelling as
-# well as a file left over from an earlier version's build. Grepping for one
-# literal placeholder would not: the spelling changes from {revnumber} to
-# @project.version@ with the fix for #6186.
-generated_scripts() {
-  printf 'docker-compose.yml|ghcr.io/inception-project/inception\n'
-  printf 'docker-compose-mysql8.yml|ghcr.io/inception-project/inception\n'
-  printf 'kubernetes.yml|ghcr.io/inception-project/inception-snapshots\n'
-}
-
-GENERATED_SCRIPTS_DIR="$WEBAPP_TARGET/generated-docs/admin-guide/scripts"
-
-# ---------------------------------------------------------------------------
-# status
-# ---------------------------------------------------------------------------
-
-# Is the DMG notarized and stapled? `stapler validate` exits 0 for a stapled
-# DMG and non-zero otherwise -- but it also exits 0 while printing an error
-# for a missing file, so the caller must check existence first.
-dmg_is_stapled() {
-  xcrun stapler validate "$1" >/dev/null 2>&1
-}
-
-cmd_status() {
-  local version="${1:-}"
-  [ -n "$version" ] || die "Usage: release.sh status <version>   (e.g. 41.3)"
-
-  require_tool gh
-  require_tool jq
-
-  local tag; tag="$(tag_for "$version")"
-  local base; base="$(base_version_for "$version")"
-
-  say "${C_BOLD}Release status for $version${C_RESET}  (tag: $tag)"
-  if [ "$base" != "$version" ]; then
-    say "${C_DIM}Native installers use base version $base${C_RESET}"
-  fi
-  say ""
-
-  # --- Git tag -------------------------------------------------------------
-  # The remote tag is what makes a release a release; a purely local tag means
-  # the release was never pushed. The local tag is still worth resolving,
-  # because a leftover one from an aborted `release:prepare` shadows the real
-  # one and would make every local check look at the wrong commit.
-  say "${C_BOLD}Git tag${C_RESET}"
-  local local_sha='' remote_sha='' remote_commit='' remote_out remote_ok=1
-  local_sha="$(git -C "$PROJECT_ROOT" rev-parse -q --verify "refs/tags/$tag^{commit}" \
-    2>/dev/null || true)"
-
-  # `git ls-remote` exits 0 both for "no such tag" (no output) and, once piped,
-  # for a failure to reach the remote -- so the two must be told apart by
-  # capturing output and status separately rather than by exit code alone.
-  #
-  # Release tags are annotated, so refs/tags/X reports the *tag object* while
-  # refs/tags/X^{} reports the commit it points at. Ask for both and prefer the
-  # peeled line: comparing the tag object against a local commit would flag a
-  # mismatch on every annotated tag. Peeling remotely also avoids depending on
-  # the tag object being present in the local object store.
-  if remote_out="$(git -C "$PROJECT_ROOT" ls-remote --tags origin \
-        "refs/tags/$tag" "refs/tags/$tag^{}" 2>/dev/null)"; then
-    remote_ok=0
-    remote_sha="$(awk -v t="refs/tags/$tag" '$2 == t {print $1}' <<<"$remote_out")"
-    remote_commit="$(awk -v p="refs/tags/$tag^{}" '$2 == p {print $1}' <<<"$remote_out")"
-    # A lightweight tag has no peeled line; there the ref itself is the commit.
-    [ -n "$remote_commit" ] || remote_commit="$remote_sha"
-  fi
-
-  if [ "$remote_ok" -ne 0 ]; then
-    mark_note "could not query origin (offline?)"
-  elif [ -n "$remote_sha" ]; then
-    mark_ok "$tag pushed to origin"
-  else
-    mark_missing "$tag not pushed to origin"
-  fi
-
-  if [ -n "$local_sha" ]; then
-    if [ -n "$remote_commit" ] && [ "$remote_commit" != "$local_sha" ]; then
-      mark_missing "local $tag points at a different commit than origin"
-      printf '            %slocal:  %s%s\n' "$C_DIM" "$local_sha" "$C_RESET"
-      printf '            %sorigin: %s%s\n' "$C_DIM" "$remote_commit" "$C_RESET"
-    else
-      mark_note "also present locally (${local_sha:0:9})"
-    fi
-  elif [ "$remote_ok" -eq 0 ] && [ -n "$remote_sha" ]; then
-    # Perfectly normal -- a fresh clone, or the release was cut elsewhere.
-    mark_note "not present locally (run: git fetch --tags)"
-  fi
-  say ""
-
-  # --- Local build artifacts ----------------------------------------------
-  say "${C_BOLD}Local artifacts${C_RESET}"
-  local label path asset size
-  while IFS='|' read -r label path asset; do
-    if [ -f "$path" ]; then
-      size="$(file_size "$path")"
-      case "$path" in
-        *.dmg)
-          if dmg_is_stapled "$path"; then
-            mark_ok "$label ($size, notarized)"
-          else
-            mark_ok "$label ($size, ${C_YELLOW}not notarized${C_RESET})"
-          fi
-          ;;
-        *) mark_ok "$label ($size)" ;;
-      esac
-    else
-      mark_missing "$label"
-      printf '            %sexpected: %s%s\n' "$C_DIM" "${path#"$PROJECT_ROOT"/}" "$C_RESET"
-    fi
-  done < <(expected_artifacts "$version")
-  say ""
-
-  # --- Generated example scripts -------------------------------------------
-  say "${C_BOLD}Generated example scripts${C_RESET}"
-  local script_name image_repo script_path
-  while IFS='|' read -r script_name image_repo; do
-    script_path="$GENERATED_SCRIPTS_DIR/$script_name"
-    if [ ! -f "$script_path" ]; then
-      mark_missing "$script_name not generated yet"
-      continue
-    fi
-    # Find the image line for this repository and require the version to appear
-    # on it. Matching the whole line rather than just the version keeps other
-    # versions mentioned elsewhere in the file from satisfying the check.
-    #
-    # The version is not necessarily adjacent to the repository name: the
-    # compose files wrap both in shell default expansions, as in
-    #   image: "${INCEPTION_IMAGE:-<repo>}:${INCEPTION_VERSION:-<version>}"
-    # while kubernetes.yml writes "<repo>:<version>" directly. Anchoring on the
-    # repository name and then looking for the version covers both.
-    #
-    # `|| true` because a non-matching grep must not abort the script: this
-    # whole block runs under `set -e`.
-    local image_line
-    image_line="$(grep -F "$image_repo" "$script_path" | head -1 || true)"
-    if [ -z "$image_line" ]; then
-      mark_missing "$script_name has no $image_repo image line"
-      printf '            %s%s%s\n' \
-        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
-    elif grep -qF "$version" <<<"$image_line"; then
-      mark_ok "$script_name pins $version"
-    else
-      mark_missing "$script_name does not pin $version"
-      # Showing the actual line distinguishes an unsubstituted placeholder from
-      # a file left over from an earlier version's build.
-      printf '            %sfound: %s%s\n' \
-        "$C_DIM" "$(sed 's/^[[:space:]]*//' <<<"$image_line")" "$C_RESET"
-      printf '            %s%s%s\n' \
-        "$C_DIM" "${script_path#"$PROJECT_ROOT"/}" "$C_RESET"
-    fi
-  done < <(generated_scripts)
-  say ""
-
-  # --- GitHub release ------------------------------------------------------
-  say "${C_BOLD}GitHub release${C_RESET}"
-  local release_json
-  if release_json="$(gh release view "$tag" --repo "$REPO" \
-        --json isDraft,isPrerelease,assets,url 2>/dev/null)"; then
-    local is_draft url
-    is_draft="$(jq -r '.isDraft' <<<"$release_json")"
-    url="$(jq -r '.url' <<<"$release_json")"
-    if [ "$is_draft" = "true" ]; then
-      mark_ok "draft exists"
-    else
-      mark_ok "${C_BOLD}PUBLISHED${C_RESET}"
-    fi
-    mark_note "$url"
-
-    say ""
-    say "  ${C_BOLD}Attached assets${C_RESET}"
-    while IFS='|' read -r label path asset; do
-      if jq -e --arg n "$asset" '.assets[] | select(.name == $n)' \
-           <<<"$release_json" >/dev/null 2>&1; then
-        mark_ok "$asset"
-      else
-        mark_missing "$asset"
-      fi
-    done < <(expected_artifacts "$version")
-
-    # Anything attached that we did not expect is worth surfacing rather than
-    # silently ignoring -- it may be a leftover or a manually added file.
-    local expected_names extra
-    expected_names="$(expected_artifacts "$version" | cut -d'|' -f3)"
-    extra="$(jq -r '.assets[].name' <<<"$release_json" \
-      | grep -Fxv -f <(printf '%s\n' "$expected_names") || true)"
-    if [ -n "$extra" ]; then
-      say ""
-      say "  ${C_BOLD}Additional assets${C_RESET}"
-      while IFS= read -r name; do
-        [ -n "$name" ] && mark_note "$name"
-      done <<<"$extra"
-    fi
-  else
-    mark_missing "no release for $tag"
-  fi
-  say ""
-
-  # --- GitHub Pages --------------------------------------------------------
-  # Both checks read the Pages repository through the API, so they need no
-  # credentials beyond the `gh` login that `status` already requires.
-  say "${C_BOLD}GitHub Pages${C_RESET} ${C_DIM}($PAGES_REPO)${C_RESET}"
-  local releases_yml
-  if releases_yml="$(gh api "repos/$PAGES_REPO/contents/$PAGES_RELEASES_YML" \
-        --jq '.content' 2>/dev/null | base64 -d 2>/dev/null)" \
-     && [ -n "$releases_yml" ]; then
-    # Recent entries quote the version (- version: "41.2"), older ones do not
-    # (- version: 0.4.0), so accept either. Commented-out entries do not count:
-    # the file keeps disabled snapshot/beta blocks around permanently.
-    if grep -Eq "^-[[:space:]]+version:[[:space:]]+\"?${version//./\\.}\"?[[:space:]]*$" \
-         <<<"$releases_yml"; then
-      mark_ok "$PAGES_RELEASES_YML lists $version"
-    else
-      mark_missing "$PAGES_RELEASES_YML does not list $version"
-    fi
-  else
-    mark_note "could not read $PAGES_RELEASES_YML"
-  fi
-
-  # The per-release documentation copy. Checking for a guide inside the docs
-  # directory rather than the directory itself, so a half-finished upload does
-  # not read as done.
-  local docs_path="releases/$version/docs"
-  local docs_listing
-  if docs_listing="$(gh api "repos/$PAGES_REPO/contents/$docs_path" \
-        --jq '.[].name' 2>/dev/null)" && [ -n "$docs_listing" ]; then
-    if grep -qx 'user-guide.html' <<<"$docs_listing"; then
-      mark_ok "release documentation uploaded ($docs_path)"
-    else
-      mark_missing "$docs_path exists but has no user-guide.html"
-    fi
-  else
-    mark_missing "no release documentation at $docs_path"
-  fi
-  say ""
-
-  # --- Manual steps --------------------------------------------------------
-  # Listed explicitly and never marked ok: these cannot be verified from here,
-  # and omitting them would let a clean run read as "release complete".
-  say "${C_BOLD}Not checked by this script${C_RESET}"
-  mark_note "all issues and PRs resolved/merged"
-  mark_note "release announcement written and added to the GitHub release"
-  mark_note "stable / community / demo instances updated"
-  mark_note "announcement sent to the mailing list"
-  say ""
-
-  # --- Docker image --------------------------------------------------------
-  say "${C_BOLD}Docker image${C_RESET}"
-  local image="ghcr.io/inception-project/inception:$version"
-  local token
-  token="$(curl -s "https://ghcr.io/token?scope=repository:inception-project/inception:pull&service=ghcr.io" \
-    | jq -r '.token // empty' 2>/dev/null || true)"
-  if [ -n "$token" ]; then
-    local code
-    code="$(curl -s -o /dev/null -w '%{http_code}' \
-      -H "Authorization: Bearer $token" \
-      -H 'Accept: application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json,application/vnd.docker.distribution.manifest.v2+json' \
-      "https://ghcr.io/v2/inception-project/inception/manifests/$version")"
-    if [ "$code" = "200" ]; then
-      mark_ok "$image pushed"
-    else
-      mark_missing "$image not pushed (HTTP $code)"
-    fi
-  else
-    mark_note "could not query ghcr.io (offline?)"
-  fi
-  say ""
-}
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
 
 usage() {
-  cat <<'EOF'
+  cat <<'USAGE'
 Release helper for INCEpTION.
 
 Usage:
-  release.sh status <version>    Show what is done and what is still missing
-  release.sh --help             Show this help
-
-Every subcommand is safe to re-run. State is derived from the file system, from
-the GitHub release and from the GitHub Pages site, so steps performed by hand
-are recognized too.
-
-`status` does not cover every item of the release checklist; the steps it cannot
-verify are listed under "Not checked by this script" in its output.
+  release.sh status [version]     Show what is done and what is still missing
+  release.sh maven                Run the Maven release (prepare + perform)
+  release.sh macos                Build and notarize the macOS DMGs
+  release.sh docker               Build and push the Docker image
+  release.sh windows              Build the Windows MSI on CI and fetch it
+  release.sh draft [version]      Create the GitHub release as a draft
+  release.sh upload [version]     Attach the built artifacts to the draft
+  release.sh all                  Run all of the above, in order
+  release.sh --help              Show this help
+
+Subcommands are separate scripts in the same directory and can also be called
+directly:
+
+  release-status.sh [version]
+  release-maven.sh [--dry-run]
+  release-macos.sh [--dry-run]
+  release-docker.sh [--dry-run]
+  release-windows.sh [--rebuild] [--dry-run]
+  release-draft.sh [version] [--dry-run]
+  release-upload.sh [version] [--dry-run]
+  release-all.sh [--from <step>] [--dry-run]
+
+`macos`, `docker` and `windows` take the version from target/checkout - the tag
+release:perform checks out - because artifact names come from the pom version and
+the working tree is still on a SNAPSHOT. Run them after `maven`, in the same
+working copy. `status` and `draft` read that version too when none is given.
+
+`status` is read-only; the checklist items it cannot verify are listed under
+"Not checked by this script" in its output.
+
+`maven` runs release:prepare and release:perform; Maven prompts for the
+versions as usual.
+
+`docker` derives the image name from the version: betas go to
+inception-snapshots, final releases to inception.
+
+`windows` dispatches the dist-win workflow on the release tag (the MSI cannot be
+built locally), waits for it and unpacks the artifact where the other steps
+expect it. It reuses an existing successful run unless --rebuild is given, so
+re-running it is cheap. Requires the tag to be pushed.
+
+`draft` creates the release as a draft with GitHub's generated changelog and the
+usual boilerplate. It does not attach artifacts; issue-type emojis are not added.
+
+`upload` attaches the artifacts to the draft and can be re-run as they appear -
+the Windows MSI arrives last, from CI. It skips what is already attached at the
+same size, and refuses to modify a release that has been published. Because the
+two are separate, `draft` and the build steps can run in any order.
+
+`all` runs maven, macos, windows, docker, draft and upload in that order and
+stops at the first failure. Every step is re-runnable, so fix whatever broke and
+run it again - or skip ahead with --from <step>. It leaves the release as a
+draft for you to review and publish.
 
 Examples:
   release.sh status 41.2
-EOF
+  release.sh all --dry-run
+  release.sh all --from docker
+USAGE
 }
 
 main() {
   local cmd="${1:-}"
   case "$cmd" in
-    status) shift; cmd_status "$@" ;;
+    status) shift; exec "$SCRIPT_DIR/release-status.sh" "$@" ;;
+    maven)  shift; exec "$SCRIPT_DIR/release-maven.sh" "$@" ;;
+    macos)  shift; exec "$SCRIPT_DIR/release-macos.sh" "$@" ;;
+    docker) shift; exec "$SCRIPT_DIR/release-docker.sh" "$@" ;;
+    windows) shift; exec "$SCRIPT_DIR/release-windows.sh" "$@" ;;
+    draft)  shift; exec "$SCRIPT_DIR/release-draft.sh" "$@" ;;
+    upload) shift; exec "$SCRIPT_DIR/release-upload.sh" "$@" ;;
+    all)    shift; exec "$SCRIPT_DIR/release-all.sh" "$@" ;;
     -h|--help|help|'') usage ;;
-    *) die "Unknown subcommand '$cmd'. Try --help." ;;
+    *)
+      printf 'ERROR: Unknown subcommand %s. Try --help.\n' "'$cmd'" >&2
+      exit 1
+      ;;
   esac
 }