diff --git a/Makefile b/Makefile
index 6c1131e0..7847b244 100644
--- a/Makefile
+++ b/Makefile
@@ -23,6 +23,11 @@ else
   BRANCH ?= main
 endif
 
+# FETCH_REF is the ref content is fetched from. It defaults to BRANCH (which is
+# pinned to RELEASE_TAG when set); override it with a staging branch, RC tag, or
+# SHA to generate docs before the final tag exists.
+FETCH_REF ?= $(BRANCH)
+
 # Non-empty when RELEASE_TAG carries a prerelease suffix (-rc.N / -beta.N /
 # -alpha.N). Used to skip trunk pin regeneration on prereleases — update_versions.sh
 # only accepts final vX.Y.Z tags, and the trunk should track the latest final release.
@@ -84,19 +89,19 @@ SERVICES_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/operations/services
         init-version init-next release-next download-openapi download-openapi-all serve show-target
 
 update-apps:
-	./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
+	./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
 
 update-vms:
-	./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
+	./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
 
 update-networking:
-	./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
+	./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
 
 update-k8s:
-	./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
+	./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
 
 update-services:
-	./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" --pkgdir extra
+	./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)" --pkgdir extra
 
 update-oss-health:
 	python3 hack/update_oss_health.py
@@ -139,6 +144,7 @@ show-target:
 	@echo "RELEASE_TAG=$(RELEASE_TAG)"
 	@echo "DOC_VERSION=$(DOC_VERSION)"
 	@echo "BRANCH=$(BRANCH)"
+	@echo "FETCH_REF=$(FETCH_REF)"
 
 # Update the target directory in place. Routing rules above determine whether
 # this writes into next/ or an existing released version directory.
@@ -162,7 +168,7 @@ update-all:
 update-versions:
 ifeq ($(DOC_VERSION),next)
 ifeq ($(_is_prerelease),)
-	./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(BRANCH)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
+	./hack/update_versions.sh --dest data/versions/next.yaml --branch "$(FETCH_REF)" $(if $(RELEASE_TAG),--cozystack-tag "$(RELEASE_TAG)")
 else
 	@echo "update-versions: prerelease $(RELEASE_TAG) — skipping trunk pin refresh (pins track the latest final release)."
 endif
diff --git a/hack/update_apps.sh b/hack/update_apps.sh
index 3f00cf3d..f74a995b 100755
--- a/hack/update_apps.sh
+++ b/hack/update_apps.sh
@@ -83,6 +83,10 @@ SOURCE_REPO="cozystack/cozystack"
 RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/packages/${PKG_DIR}"
 
 
+# The per-app temp file is removed on every explicit exit path below; the trap
+# covers aborts between mktemp and those paths (set -e on touch/cp/heredoc).
+trap 'rm -f "${tmp:-}"' EXIT
+
 for app in "${APPS[@]}"; do
   if [[ "$INDEX_MODE" == "true" ]]; then
     src_file="${DEST_DIR%/}/${app}/_include/_index.md"
@@ -97,6 +101,24 @@ for app in "${APPS[@]}"; do
     fi
   fi
 
+  readme_url="${RAW_BASE_URL}/${app}/README.md"
+  echo "Processing $app..."
+
+  tmp=$(mktemp)
+  if ! curl -fsSL --compressed --retry 3 "$readme_url" \
+    | sed '1s/\xEF\xBB\xBF//' \
+    | awk 'NR==1 && /^#{1,2} / { next } { print }' > "$tmp"; then
+    rm -f "$tmp"
+    echo "Error: failed to fetch README for $app from $readme_url" >&2
+    exit 1
+  fi
+
+  if [[ ! -s "$tmp" ]]; then
+    rm -f "$tmp"
+    echo "Error: fetched empty README for $app from $readme_url" >&2
+    exit 1
+  fi
+
   # Ensure template exists (touch if missing)
   [[ -f "$src_file" ]] || touch "$src_file"
 
@@ -114,15 +136,8 @@ source: https://github.com/${SOURCE_REPO}/blob/${SOURCE_REF}/packages/${PKG_DIR}
 
 EOF
 
-  readme_url="${RAW_BASE_URL}/${app}/README.md"
-  echo "Processing $app..."
-
-  if curl -fsSL --compressed "$readme_url" \
-    | sed '1s/\xEF\xBB\xBF//' \
-    | awk 'NR==1 && /^#{1,2} / { next } { print }' >> "$dest_file"; then
-    echo "✓ Appended README for $app -> $dest_file"
-  else
-    echo "⚠️  Failed to fetch README for $app" >&2
-  fi
+  cat "$tmp" >> "$dest_file"
+  rm -f "$tmp"
+  echo "✓ Appended README for $app -> $dest_file"
 
-done
\ No newline at end of file
+done