Bring script headers onto the template and close safeguard gaps

Headers claimed protections the code never had, and several destructive paths had no
guard against a collapsed config value.

Tools/bulk_permissions_repair.sh

@@ -23,9 +23,32 @@
 # repairs this tool is meant for — worth remembering before pointing it at an entire share.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# For each path given on the command line:
+#
+#   1. Path guard — refuse anything shallower than two components
+#   2. Existence check — a missing path is a failure for that entry, not the run
+#   3. Report scale — file count, dir count, total size, so the operator sees the job size
+#   4. Count entries with wrong ownership (the diagnostic number in the summary)
+#   5. chown -R PERMISSIONS_OWNER across the path
+#   6. find -type d → chmod PERMISSIONS_DIR_MODE
+#   7. find -type f → chmod PERMISSIONS_FILE_MODE
+#
+# Unlike the nightly media_shares_permissions.sh, steps 5–7 are unconditional — see the
+# ctime note in PURPOSE above for why that distinction matters.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
+# Unconditional by Design, Unlike the Nightly Job
+#   media_shares_permissions.sh applies its passes conditionally to protect ctime as an
+#   age signal for arr orphan collection. This tool deliberately does not: it exists to
+#   repair paths that are known-wrong, where correctness matters more than preserving a
+#   clock. That is exactly why it is a targeted manual tool and not a scheduled one.
+#
 # Permissions Model
 #   Directories (PERMISSIONS_DIR_MODE, default 755):
 #     Owner (nobody) — rwx  enter, list, create files
@@ -53,9 +76,6 @@
 #   Each path is verified before processing — missing paths log an error and
 #   are skipped rather than silently passing.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # Silent on Success
 #   Only failures and the wrong-owner diagnostic produce visible output.
 #
@@ -137,6 +157,18 @@ for share_path in "${PARSED_ARGS[@]}"; do
     echo ""
     echo "━━━ $ICON_PERMS $(basename "$share_path") ━━━"
 
+    # chown -R below. Paths come straight from the command line, so a spacing typo
+    # ("/mnt/user /Movies" instead of "/mnt/user/Movies") would hand this a bare top-level
+    # directory — and chown -R nobody:users on / or /etc breaks the system outright.
+    # Require at least two path components; that still allows a deliberate whole-share
+    # repair like /mnt/user while refusing /, /mnt, /etc, /boot and friends.
+    _bpr_slashes="${share_path//[^\/]/}"
+    if [[ "$share_path" != /* || "${#_bpr_slashes}" -lt 2 ]]; then
+        error "$share_path — refusing: expected an absolute path at least 2 levels deep"
+        FAIL+=("$share_path")
+        continue
+    fi
+
     if [[ ! -d "$share_path" ]]; then
         error "$share_path — not found"
         FAIL+=("$share_path")