diff --git a/roles/network/templates/netwarn/netwarn b/roles/network/templates/netwarn/netwarn
index fc4c8f4bb..8c5d95b05 100755
--- a/roles/network/templates/netwarn/netwarn
+++ b/roles/network/templates/netwarn/netwarn
@@ -1,5 +1,15 @@
 #!/bin/bash
 
+# CONFUSING BUT FYI: Commands below run *strictly sequentially* when this
+# script (/usr/local/sbin/netwarn) is invoked by autostart during OS boot.
+# This allows return codes to be meaningful, at each successive step.
+# (As of July 2022, this is tested to work well with Ubuntu Mate and RasPiOS
+# on Raspberry Pi 4!)
+#
+# IN CONTRAST: return codes below are NOT MEANINGFUL when this script is
+# invoked from a regularly graphical desktop session -- so make sure to test
+# during an actual OS boot-up, with autostart!
+
 if [ -f /etc/iiab/install-flags/iiab-network-complete ]; then
     exit
 fi