Document the breaking-change advisory block in the PR template

Explains the ```breaking-change block a breaking-change PR can carry —
severity, action (warn/block), expect, and before_update steps — with a
copy-paste example kept inside an HTML comment so it stays inert until an
author fills it in.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TFBuZEp142Ei2PAfWqbMXT

.github/pull_request_template.md

@@ -35,3 +35,35 @@ Fixes #
 - [ ] 🌍 **Website update** – Changes to script metadata (PocketBase/website data).
 - [ ] 🔧 **Refactoring / Code Cleanup** – Improves readability or maintainability without changing functionality.
 - [ ] 📝 **Documentation update** – Changes to `README`, `AppName.md`, `CONTRIBUTING.md`, or other docs.
+
+---
+
+## 💥 Breaking Change Advisory (only if you checked "Breaking change")
+
+If this PR changes existing behaviour in a way that may require action before an
+update, add a `breaking-change` advisory block to this PR body. The website and
+the in-container update guard read it to tell operators exactly what to expect,
+what to do first, and — with `action: block` — to stop an update until it's
+handled. Every field is optional; the advisory auto-expires 30 days after merge.
+
+Copy the block out of the comment below, fill it in, and paste it here:
+
+<!--
+```breaking-change
+severity: warning        # info | warning | critical
+action: warn             # warn (default) | block — "block" halts the update until an operator forces it
+expect: One line describing what changes and why it may need action.
+before_update:
+  - First thing to do before updating
+  - Second thing to do before updating
+```
+
+Guidance:
+- Leave this commented (or delete it) for a routine change — no block, no advisory.
+- Use `action: block` only for changes that break or lose data if the operator
+  updates without acting first (e.g. a required manual migration or backup).
+- `expect:` supersedes the auto-scraped summary; keep it to one line.
+- Steps render as a checklist on the site and in the update prompt.
+-->
+
+<!-- The advisory block is only active once it is OUTSIDE this comment. -->

.github/workflows/notify-breaking-change.yml

@@ -0,0 +1,58 @@
+name: Notify breaking change
+
+# When a PR labelled "breaking change" is merged, tell the Helper-Scripts site
+# so it can show a temporary advisory on the affected scripts. The site pulls
+# the PR itself and re-verifies it is merged + labelled, so this workflow only
+# has to hand over the PR number.
+#
+# Requires one repo secret:
+#   BREAKING_CHANGE_INGEST_SECRET  — must match the value the site runs with.
+# Site URL is taken from the existing FRONTEND_URL secret, then an optional
+# SITE_URL variable, then a hard default.
+#
+# pull_request_target (not pull_request) so the run has access to the secret
+# even for fork PRs. It is safe here: the job never checks out or runs PR code —
+# it only forwards the number after the PR has merged.
+
+on:
+  pull_request_target:
+    # closed  -> fires on the merge itself
+    # labeled -> fires if the label is added to an already-merged PR
+    types: [closed, labeled]
+
+concurrency:
+  group: notify-breaking-change-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  notify:
+    if: >-
+      github.event.pull_request.merged == true &&
+      contains(github.event.pull_request.labels.*.name, 'breaking change')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify site of breaking change
+        env:
+          INGEST_SECRET: ${{ secrets.BREAKING_CHANGE_INGEST_SECRET }}
+          SITE_URL: ${{ secrets.FRONTEND_URL || vars.SITE_URL || 'https://community-scripts.org' }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          if [ -z "${INGEST_SECRET:-}" ]; then
+            echo "::error::BREAKING_CHANGE_INGEST_SECRET secret is not set."
+            exit 1
+          fi
+          url="${SITE_URL%/}/api/breaking-changes/ingest"
+          echo "Notifying $url for PR #${PR}"
+          status="$(curl -sS -o response.json -w '%{http_code}' \
+            -X POST "$url" \
+            -H "Authorization: Bearer ${INGEST_SECRET}" \
+            -H "Content-Type: application/json" \
+            -d "{\"pr\": ${PR}}")"
+          echo "HTTP $status"
+          cat response.json || true
+          echo
+          if [ "$status" != "200" ]; then
+            echo "::error::ingest endpoint returned HTTP $status"
+            exit 1
+          fi

CHANGELOG.md

@@ -527,6 +527,8 @@ Exercise vigilance regarding copycat or coat-tailing sites that seek to exploit
 
 </details>
 
+## 2026-08-24
+
 ## 2026-08-23
 
 ### 🚀 Updated Scripts

misc/build.func

@@ -1208,10 +1208,12 @@ base_settings() {
 # - Used by default_var_settings and app defaults loading
 # - Only loads whitelisted var_* keys
 # - Optional force parameter to override existing values (for app defaults)
+# - Optional protected list preserves genuinely user-exported var_* values
 # ------------------------------------------------------------------------------
 load_vars_file() {
   local file="$1"
-  local force="${2:-no}" # If "yes", override existing variables
+  local force="${2:-no}"      # If "yes", override existing variables
+  local protected="${3:-}"    # space-separated var_* keys the user genuinely exported before this file loaded; never overwritten
   [ -f "$file" ] || return 0
   msg_info "Loading defaults from ${file}"
 
@@ -1231,6 +1233,13 @@ load_vars_file() {
     return 1
   }
 
+  # Protected check helper (genuinely user-exported vars, see $protected above)
+  _is_protected() {
+    local k="$1" p
+    for p in $protected; do [ "$k" = "$p" ] && return 0; done
+    return 1
+  }
+
   local line key val
   while IFS= read -r line || [ -n "$line" ]; do
     line="${line#"${line%%[![:space:]]*}"}"
@@ -1435,9 +1444,19 @@ load_vars_file() {
         esac
       fi
 
-      # Set variable: force mode overrides existing, otherwise only set if empty
+      # Set variable: force mode overrides existing, otherwise only set if empty.
+      # Exception: var_cpu/var_ram/var_disk are always applied here (unless the
+      # user genuinely exported them beforehand, per $protected) even though the
+      # app script already declared its own baseline for them - base_settings()
+      # reconciles the final floor against APP_DEFAULT_* afterward, so this file
+      # must be allowed to raise them instead of being silently blocked by the
+      # app's own pre-set value.
       if [[ "$force" == "yes" ]]; then
         export "${var_key}=${var_val}"
+      elif _is_protected "$var_key"; then
+        :
+      elif [[ "$var_key" == "var_cpu" || "$var_key" == "var_ram" || "$var_key" == "var_disk" ]]; then
+        export "${var_key}=${var_val}"
       else
         [[ -z "${!var_key+x}" ]] && export "${var_key}=${var_val}"
       fi
@@ -1597,7 +1616,7 @@ EOF
     msg_error "default.vars not found after ensure step"
     return 252
   }
-  load_vars_file "$dv"
+  load_vars_file "$dv" "no" "${!_HARD_ENV[*]}"
 
   # 3) Map var_verbose → VERBOSE
   if [[ -n "${var_verbose:-}" ]]; then