added context for agents

AGENTS.md

@@ -0,0 +1,21 @@
+# Repository Guidance
+
+## RMM script execution model
+
+Scripts in this repository are generally executed by a small caller script in the RMM. The caller first downloads and dot-sources `Tools.ps1` from the public repository URL:
+
+```powershell
+. $([Scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://dev.emberkom.com/emberkom/management-scripts/raw/branch/master/Tools.ps1')))
+```
+
+The caller then invokes `Run-Script`, passing the repository script's filename without the `.ps1` extension:
+
+```powershell
+Run-Script -LivePSScript Create-BatteryReport
+```
+
+For a live PowerShell script without `-Arguments`, `Run-Script` downloads the target script and dot-sources it. This keeps the core script logic in version control, and changes pushed to the repository take effect in production without updating each RMM caller.
+
+When a repository script needs RMM-provided input, define the variable in the RMM caller before calling `Run-Script`. Because the target is dot-sourced into the caller's scope, it can read that variable directly.
+
+When changing `Run-Script` or scripts invoked through it, preserve this shared-scope behavior unless the change explicitly includes migrating all affected RMM callers.

Create-BatteryReport.ps1

@@ -13,10 +13,67 @@ If ( Test-Path $HtmlReportPath ) { Remove-Item -Path $HtmlReportPath -Force }
 
 # Generate the XML report
 Write-Output "Generating XML battery report: ${XmlReportPath}"
-Try { Start-Process "powercfg.exe" -ArgumentList "/batteryreport /output ""${XmlReportPath}"" /xml" -Wait }
-Catch { Write-Error $_.Exception.Message }
+
+Try {
+    $XmlProcess = Start-Process "powercfg.exe" `
+        -ArgumentList "/batteryreport /output ""${XmlReportPath}"" /xml" `
+        -Wait `
+        -PassThru `
+        -ErrorAction Stop
+}
+Catch {
+    Write-Error $_.Exception.Message
+    Exit 1
+}
+
+# Make sure powercfg succeeded and actually produced the report
+If ( $XmlProcess.ExitCode -ne 0 ) {
+    Write-Error "powercfg failed to generate the XML battery report with exit code $($XmlProcess.ExitCode)"
+    Exit 1
+}
+
+If ( !(Test-Path -LiteralPath $XmlReportPath -PathType Leaf) ) {
+    Write-Error "The XML battery report was not created: ${XmlReportPath}"
+    Exit 1
+}
+
+# Validate the generated XML and confirm that it contains battery records
+Try {
+    [xml]$GeneratedBatteryReport = Get-Content `
+        -LiteralPath $XmlReportPath `
+        -Raw `
+        -ErrorAction Stop
+}
+Catch {
+    Write-Error "The generated battery report is not valid XML: $($_.Exception.Message)"
+    Exit 1
+}
+
+$GeneratedBatteries = @(
+    $GeneratedBatteryReport.BatteryReport.Batteries.Battery
+)
+
+If ( $GeneratedBatteries.Count -eq 0 ) {
+    Write-Error "The generated battery report contains no battery records"
+    Exit 1
+}
 
 # Convert XML report to HTML
 Write-Output "Generating HTML battery report: ${HtmlReportPath}"
-Try { Start-Process "powercfg.exe" -ArgumentList "/batteryreport /transformxml ""${XmlReportPath}"" /output ""${HtmlReportPath}""" -Wait }
-Catch { Write-Error $_.Exception.Message }
+
+Try {
+    $HtmlProcess = Start-Process "powercfg.exe" `
+        -ArgumentList "/batteryreport /transformxml ""${XmlReportPath}"" /output ""${HtmlReportPath}""" `
+        -Wait `
+        -PassThru `
+        -ErrorAction Stop
+}
+Catch {
+    Write-Error $_.Exception.Message
+    Exit 1
+}
+
+If ( $HtmlProcess.ExitCode -ne 0 -or !(Test-Path -LiteralPath $HtmlReportPath -PathType Leaf) ) {
+    Write-Error "Failed to create the HTML battery report"
+    Exit 1
+}