Complete the header template across Partnership, Kernel, Deployment and Plugin

Finishes the pass: every script now documents its safeguards, and the deliberate absences
in the sourced libraries are recorded so they are not "corrected" later.

Plugin/build.sh

@@ -26,6 +26,73 @@
 #   rebuild cron when the array mounts. Scripts stay on appdata (git clone).
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Resolve version — first argument, else today's date as YYYY.MM.DD
+#   2. Verify makepkg exists (Slackware tooling — this only runs on unRAID)
+#   3. Stage Plugin/unraid/ into the install layout the package expects
+#   4. makepkg the stage into Plugin/dist/<name>-<version>-noarch-1.txz
+#   5. sha256sum the result and write the .sha256 alongside it
+#   6. Rewrite <!ENTITY version> and <!ENTITY sha256> in varaverk.plg so the .plg
+#      always points at the package just built
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Release Path, Not the Dev Path
+#   Day-to-day work uses plugin_setup.sh, which symlinks the source directory so edits are
+#   live immediately. This produces the artifact unRAID reinstalls from flash on every boot.
+#   Keeping the two separate is what allows fast iteration without shipping half-finished
+#   files into a package.
+#
+# The .plg Always Matches the Package
+#   Version and checksum are written into varaverk.plg in the same run that produces the
+#   .txz. A .plg pointing at a checksum it was not built against fails to install with a
+#   mismatch error, so the two are never updated independently.
+#
+# Date Version by Default
+#   An omitted version becomes today's date. Builds are therefore always ordered and always
+#   unique without anyone maintaining a counter.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root — Deliberate
+#   Writes only into Plugin/dist/ and rewrites varaverk.plg inside the repo. It installs
+#   nothing and touches nothing under /usr or /boot, so it needs no privilege. Requiring
+#   root would mean building release artifacts as root for no reason.
+#
+# makepkg Presence Check
+#   Aborts immediately if makepkg is missing, with a note that this runs on unRAID. The
+#   Slackware toolchain is not present on a normal dev machine and a partial build would be
+#   worse than a clear refusal.
+#
+# Checksum Written From the Real Artifact
+#   The sha256 is computed from the .txz that was just produced, never assumed or carried
+#   forward, so the .plg cannot advertise a checksum for a different build.
+#
+# Staged Build
+#   The package is assembled from a staging directory rather than from the live source
+#   tree, so an in-progress edit cannot end up inside a release artifact.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None — this is a build tool, not a runtime script. It reads no conf and calls no
+# load_config.sh.
+#
+# Inputs are positional and derived:
+#   $1                  version string (default: today, YYYY.MM.DD)
+#   Plugin/unraid/      source tree that gets packaged
+#   Plugin/varaverk.plg rewritten in place with the new version and checksum
+#
+# Output: Plugin/dist/<name>-<version>-noarch-1.txz and its .sha256
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #