Add explanatory comments to all test scripts

tests/test_yaml.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 pass=0
 fail=0
 
+# Detect available YAML checker: prefer yamllint, fall back to PyYAML
 checker=""
 if command -v yamllint &>/dev/null; then
     checker=yamllint
@@ -11,9 +12,11 @@ elif python3 -c "import yaml" 2>/dev/null; then
     checker=python
 fi
 
+# Validate a single YAML file using the available checker
 test_yaml() {
     local file=$1
 
+    # yamllint provides richer output; PyYAML just checks parseability
     case "$checker" in
         yamllint)
             if yamllint -d "{extends: relaxed, rules: {line-length: disable}}" "$file"; then
@@ -37,6 +40,7 @@ with open('$file') as f:
                 fail=$((fail+1))
             fi
             ;;
+        # Skip silently if no YAML checker is installed
         *)
             echo "  SKIP  $file (no yamllint or PyYAML)"
             pass=$((pass+1))
@@ -45,10 +49,12 @@ with open('$file') as f:
 }
 
 echo "=== YAML Validation ==="
+# Test each compose file passed as argument
 for f in "$@"; do
     [ -f "$f" ] && test_yaml "$f"
 done
 
 echo "---"
 echo "Passed: $pass  Failed: $fail"
+# Exit with failure if any file failed validation
 [ "$fail" -eq 0 ]