Add remarks and examples to Microsoft.Windows.System.Power API docs

microsoft.windows.system.power/batterystatus.md

@@ -34,6 +34,8 @@ The battery is charging.
 
 ## -remarks
 
+Use this enum with the [BatteryStatus](powermanager_batterystatus.md) property to determine the current battery state. A value of `NotPresent` indicates a desktop or device without a battery. The `Idle` state means the battery is neither charging nor discharging.
+
 ## -see-also
 
 [BatteryStatus property](powermanager_batterystatus.md), [BatteryStatusChanged event](powermanager_batterystatuschanged.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/effectivepowermode.md

@@ -46,6 +46,10 @@ The device is in the windows mixed reality power mode.
 
 ## -remarks
 
+The effective power mode reflects the combined result of the user's power plan selection, battery saver state, and other system policies. `GameMode` and `MixedReality` represent specialized modes for those workloads.
+
+Use this enum with the [EffectivePowerMode](powermanager_effectivepowermode.md) or [EffectivePowerMode2](powermanager_effectivepowermode2.md) property to adapt your app's behavior to the current power mode.
+
 ## -see-also
 
 [EffectivePowerMode property](powermanager_effectivepowermode.md), [EffectivePowerModeChanged event](powermanager_effectivepowermodechanged.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/microsoft_windows_system_power.md

@@ -13,6 +13,10 @@ For more information, see [Power management with the app lifecycle API](/windows
 
 ## -remarks
 
+The **Microsoft.Windows.System.Power** namespace is part of the Windows App SDK. The [PowerManager](powermanager.md) class provides static properties to query the current power state and static events to react when the state changes. The namespace also defines enums such as [BatteryStatus](batterystatus.md), [EffectivePowerMode](effectivepowermode.md), and [PowerSourceKind](powersourcekind.md) that represent the possible values for those properties.
+
+Common scenarios include deferring background work when the device is on battery, reducing visual effects in power-saver mode, and pausing activity when the user is away or the display is off.
+
 ## -see-also
 
 [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/powermanager.md

@@ -16,12 +16,47 @@ Provides static events that notify your app of changes to the devices power stat
 
 ## -remarks
 
-For more information about using this class, see [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power).
+**PowerManager** is a static class — you do not instantiate it. Read its properties to query the current power state and subscribe to its events to be notified when the state changes.
+
+Several of the properties and enums in this class correspond to Win32 [power setting GUIDs](/windows/win32/power/power-setting-guids), as noted in their individual remarks.
+
+For more information, see [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power).
 
 ## -see-also
 
 [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)
 
 ## -examples
 
-For code examples that demonstrsate how to use this class, see [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power).
+The following example checks whether the device is on battery and subscribes to power-state change events.
+
+```csharp
+using Microsoft.Windows.System.Power;
+
+// Check current power source
+if (PowerManager.PowerSourceKind == PowerSourceKind.DC)
+{
+    // Running on battery — defer non-essential work
+    int chargePercent = PowerManager.RemainingChargePercent;
+    System.Diagnostics.Debug.WriteLine($"On battery: {chargePercent}% remaining");
+}
+
+// React to battery status changes
+PowerManager.BatteryStatusChanged += (sender, args) =>
+{
+    BatteryStatus status = PowerManager.BatteryStatus;
+    if (status == BatteryStatus.Discharging)
+    {
+        // Reduce background activity
+    }
+};
+
+// React to energy saver (battery saver) changes
+PowerManager.EnergySaverStatusChanged += (sender, args) =>
+{
+    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
+    {
+        // Minimize resource usage
+    }
+};
+```

microsoft.windows.system.power/powermanager_batterystatus.md

@@ -20,6 +20,8 @@ The current status of the battery.
 
 ## -remarks
 
+Use this property to determine whether the device has a battery and whether it is currently charging, discharging, or idle. Subscribe to the [BatteryStatusChanged](powermanager_batterystatuschanged.md) event to be notified when this value changes.
+
 ## -see-also
 
 [BatteryStatusChanged event](powermanager_batterystatuschanged.md), [BatteryStatus enum](batterystatus.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/powermanager_effectivepowermode.md

@@ -19,6 +19,10 @@ The current effective power mode of the device.
 
 ## -remarks
 
+This property returns an asynchronous operation that resolves to the current [EffectivePowerMode](effectivepowermode.md). For a synchronous alternative, use [EffectivePowerMode2](powermanager_effectivepowermode2.md).
+
+The effective power mode reflects the combined result of the user's power plan selection, battery saver state, and system policies. Use this value to adjust your app's resource usage — for example, reduce animation quality or defer background processing when the mode is `BatterySaver` or `BetterBattery`.
+
 ## -see-also
 
 [EffectivePowerModeChanged event](powermanager_effectivepowermodechanged.md), [EffectivePowerMode enum](effectivepowermode.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power), [EffectivePowerMode2](./powermanager_effectivepowermode2.md)

microsoft.windows.system.power/powermanager_effectivepowermode2.md

@@ -19,6 +19,10 @@ The current effective power mode of the device.
 
 ## -remarks
 
+This property returns the current [EffectivePowerMode](effectivepowermode.md) synchronously. It returns the same value as awaiting [EffectivePowerMode](powermanager_effectivepowermode.md), but does not require an asynchronous call.
+
+Subscribe to the [EffectivePowerModeChanged](powermanager_effectivepowermodechanged.md) event to be notified when this value changes.
+
 ## -see-also
 
 [EffectivePowerModeChanged event](powermanager_effectivepowermodechanged.md), [EffectivePowerMode enum](effectivepowermode.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power), [EffectivePowerMode](./powermanager_effectivepowermode.md)

microsoft.windows.system.power/powermanager_powersupplystatus.md

@@ -20,6 +20,8 @@ The current power supply status of the device.
 
 ## -remarks
 
+Use this property to determine whether the power supply is connected and providing adequate power. Subscribe to the [PowerSupplyStatusChanged](powermanager_powersupplystatuschanged.md) event to be notified when this value changes.
+
 ## -see-also
 
 [PowerSupplyStatusChanged event](powermanager_powersupplystatuschanged.md), [PowerSupplyStatus enum](powersupplystatus.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/powermanager_remainingdischargetime.md

@@ -20,6 +20,8 @@ The remaining discharge time of the battery.
 
 ## -remarks
 
+Returns a [TimeSpan](/dotnet/api/system.timespan) representing the estimated time remaining before the battery is fully discharged. This value is meaningful only when the device is running on battery power ([PowerSourceKind](powermanager_powersourcekind.md) is `DC`). Subscribe to the [RemainingDischargeTimeChanged](powermanager_remainingdischargetimechanged.md) event to be notified when this estimate changes.
+
 ## -see-also
 
 [RemainingDischargeTimeChanged event](powermanager_remainingdischargetimechanged.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/powermanager_systemsuspendstatus.md

@@ -20,6 +20,8 @@ The current suspend status of the device.
 
 ## -remarks
 
+Use this property to detect when the system is entering or resuming from a suspend (sleep/hibernate) state. Your app can use the [SystemSuspendStatusChanged](powermanager_systemsuspendstatuschanged.md) event together with this property to save state before suspend and refresh data after resume.
+
 ## -see-also
 
 [SystemSuspendStatusChanged event](powermanager_systemsuspendstatuschanged.md), [SystemSuspendStatus enum](systemsuspendstatus.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/powersupplystatus.md

@@ -30,6 +30,8 @@ Power supply is adequate.
 
 ## -remarks
 
+Use this enum with the [PowerSupplyStatus](powermanager_powersupplystatus.md) property. `NotPresent` means no power supply is connected, `Inadequate` means a power supply is connected but not providing adequate power, and `Adequate` means the power supply is connected and providing adequate power.
+
 ## -see-also
 
 [PowerSupplyStatus property](powermanager_powersupplystatus.md), [PowerSupplyStatusChanged event](powermanager_powersupplystatuschanged.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)

microsoft.windows.system.power/systemsuspendstatus.md

@@ -34,6 +34,8 @@ The user has manually resumed the device from suspend state.
 
 ## -remarks
 
+Use this enum with the [SystemSuspendStatus](powermanager_systemsuspendstatus.md) property and the [SystemSuspendStatusChanged](powermanager_systemsuspendstatuschanged.md) event to detect when the system is entering or leaving a suspend state. `AutoResume` indicates the system resumed without user interaction, while `ManualResume` indicates the user explicitly woke the device.
+
 ## -see-also
 
 [SystemSuspendStatus property](powermanager_systemsuspendstatus.md), [SystemSuspendStatusChanged event](powermanager_systemsuspendstatuschanged.md), [Power management with the app lifecycle API](/windows/apps/windows-app-sdk/applifecycle/applifecycle-power)